Getting What You Want from StandardGetFilePreview

Dispatch 10

QuickTime provides a facility for allowing the user to choose a movie file using a standard dialog. This capability is provided through StandardGetFilePreview and CustomGetFilePreview. On both Mac OS and Windows these functions use standard system dialogs to accomplish their task.

Getting Movies and other Dynamic Media

When QuickTime was first introduced it could only open a single kind of media file, a QuickTime movie. This made it very easy to use, as shown below.

StandardFileReply reply;
OSType fileType = kQTFileTypeMovie;
   
StandardGetFilePreview(nil, 1, &fileType, &reply);

Successive revisions of QuickTime added support for more and more file types. Rather than require developers to update their applications to support these new file types, such as AIFF and WAVE, StandardGetFilePreview was changed. When an application requests movie files, QuickTime assumes that the application would actually accept any file which can be opened using the standard QuickTime APIs (OpenMovieFile, NewMovieFromFile, etc.). When StandardGetFilePreview returns a file that isn't a movie file but that should be considered to be a movie file, such as an AIFF or WAVE file, it sets the file type field (sfType) to kQTFileTypeMovie. Of course, if an application wishes to know the actual file type of the returned file, it can use FSpGetFInfo.

Some applications may be able to open some of the file types that QuickTime can also open. For example, Adobe Premiere 4.2 can open AIFF files without help from QuickTime, but cannot open AU (muLaw) files. It might call StandardGetFilePreview as follows:

StandardFileReply reply;
OSType fileTypes[ ] = {kQTFileTypeMovie, kQTFileTypeAIFF};
   
StandardGetFilePreview(nil, 2, fileTypes, &reply);

In this case, if the user selects an AIFF file, the sfType field in the StandardFileReply will be set to kFileTypeAIFF, since the application has indicated that it can handle the file format directly, there is no need for QuickTime to help. If the user had selected an AU file in this case, then it would require help from QuickTime to open it, so the sfType field in the StandardFileReply would be set to kQTFileTypeMuLaw.

When an application requests movie files to be shown in StandardGetFilePreview, it isn't actually true that every kind of file that be opened by QuickTime is displayed. During the development of QuickTime, there were two kinds of files that QuickTime could open that were so common on Macintosh systems, that it was decided not to always display them. These two file types were Text and Pictures. If your application would like these two file types to be displayed to users when the StandardGetFilePreview dialog is presented, a second file type must be passed. Apple's MoviePlayer does this in its "Import..." dialog.

StandardFileReply reply;
OSType fileTypes[ ] = {kQTFileTypeMovie,
                      kQTFileTypeMovie | 0x80000000};
   
StandardGetFilePreview(nil, 2, fileTypes, &reply);

Getting Images

In addition to supporting dynamic media files like QuickTime movies, QuickTime also supports a wide range of image file types. StandardGetFilePreview makes it just as easy to select an image file as it does to select a movie file. If an application calls StandardGetFilePreview and requests QuickTime Image files to be displayed in the list, QuickTime displays all image file types that can be opened using QuickTime's Graphics Importers.

StandardFileReply reply;
OSType fileType = kQTFileTypeQuickTimeImage;
   
StandardGetFilePreview(nil, 1, &fileType, &reply);

As with movie files, if a file is selected which isn't listed in the file type list, its file type will be listed as kQTFileTypeQuickTimeImage in the sfType field in the StandardFileReply. So, if a JPEG file was selected, the file type returned would be kQTFileTypeQuickTimeImage. As in the previous case, the actual file type can be determined with FSpGetFInfo.

Getting Movies and Images

Some applications may open both QuickTime movies and images from the same dialog. Because any file image file that is supported by QuickTime can be opened as a QuickTime movie, if an application specifies both kQTFileTypeMovie and kQTFileTypeQuickTimeImage when calling StandardGetFilePreview, the sfType field in the StandardFileReply will always indicate kQTFileTypeMovie. For many applications, this is not a problem. These applications will treat the still images as QuickTime movies. However, some applications may wish to present users with a different interface for working with still images and dynamic media. Therefore, after the file is returned from StandardGetFilePreview it is necessary to determine if the file is an image file or a dynamic media file. QuickTime provides functions that make it easy to do this. To determine if a file can be displayed using QuickTime's Graphics Importers, and is therefore a still image, use GetGraphicsImporterForFile as shown below.

GraphicsImportComponent gi;
   
GetGraphicsImporterForFile(&reply.sfFile, &gi);
if (gi != nil) {
 // this file is a still image
 CloseComponent(gi);
}

To determine if a file can be opened by QuickTime as a movie, use GetMovieImporterForDataRef as shown below.

AliasHandle alias;
MovieImportComponent mi;
   
NewAliasMinimal(&reply.sfFile, &alias);
GetMovieImporterForDataRef(rAliasType, (Handle)alias,
    kGetMovieImporterDontConsiderGraphicsImporters, &mi);
DisposeHandle((Handle)alias);
if (mi != nil) {
  // this file can be opened as a movie
}

Note that because we passed kGetMovieImporterDontConsiderGraphicsImporters to GetMovieImporterForDataRef we will not consider any still image file formats that could be opened as QuickTime movies. If we want GetMovieImporterForDataRef to check for still image formats that could be opened as QuickTime movies, we would pass zero for the flags to GetMovieImporterForDataRef.

For applications which support Drag and Drop of files, the functions GetMovieImporterForDataRef and GetGraphicsImporterForFile are also convenient. These functions allow your application to easily determine if QuickTime can be used to work with the file that is being dropped by the user.

Getting More than Four Types

One common point of confusion with StandardGetFilePreview is the typeList and numTypes parameters. The cause of this confusion is the prototype for StandardGetFilePreview, which is shown below.

typedef OSType SFTypeList[4];
typedef const OSType *ConstSFTypeListPtr;
   
EXTERN_API(void) StandardGetFilePreview(FileFilterUPP fileFilter,
    short numTypes, ConstSFTypeListPtr typeList,
    StandardFileReply *reply);

Because an SFTypeList is defined as an array of four elements, most developers have assumed that if they want to include more than four file types in the file selection dialog, that it is necessary to provide a file filter. Fortunately, this is not the case. StandardGetFilePreview doesn't limit the number of file types that the "typeList" parameter points to. To have more files appear, simply define a larger array as a local variable. The following example shows how to have different six file types appear.

StandardFileReply reply;
OSType fileTypes[] = {kQTFileTypeMovie, kQTFileTypeAIFF,
                      kQTFileTypeWave, kQTFileTypeAVI,
                      kQTFileTypeTargaImage, kQTFileTypeGIF };
   
StandardGetFilePreview(nil, 6, fileTypes, &reply);

See Also

Inside Macintosh: QuickTime - Image Compression Manager chapter

QuickTime 3 Reference - Image Compression Manager

Change History

4/20/98 - jph - First published