Standard File Functions

QuickTime provides standard file functions that your application can use to display a file’s preview during the Open dialog box. These functions allow your application to support previews automatically.

The Movie Toolbox provides two standard file functions that allow you to display file previews in an Open dialog box using standard file reply structures: SFGetFilePreview and SFPGetFilePreview. The SFGetFilePreview function corresponds to the existing SFGetFile function; the SFPGetFilePreview function corresponds to the existing SFPGetFile function.

The SFGetFilePreview function uses the dialog box shown in Figure 8-1. The SFPGetFilePreview function can also use this dialog box, if you do not supply your own.

You use these new functions in place of the existing standard file functions to indicate whether or not you want to allow the user to display previews during the Open dialog box. The user displays a file’s preview by selecting a file in the dialog box and clicking Show Preview. When the user does so, the functions display the preview for the file, as shown in Figure 8-2.

The preview area of the dialog box is displayed whenever previewing is enabled.

Customizing Your Interface

If your application requires it, you can customize the user interface for identifying files. The SFGetFilePreview function does not allow you to use a custom dialog box by creating your own dialog template resource. However, the SFPGetFilePreview function does let you access a custom dialog box of any resource type with the dlgID parameter.

Figure 8-3 shows the standard dialog box used by SFPGetFilePreview and SFGetFilePreview. Your dialog box and dialog filter function must support at least these dialog items.

Items to the left of item 13 are visible only when previewing. If you want to define items that are visible only during a file preview, place them to the left of item 13 in your custom dialog box.

If your application defines a custom dialog box, be sure to include the following items in your dialog box definition:

enum

{

/* dialog items to include in dialog box definition for use

   with SFPGetFilePreview function

*/

    sfpItemPreviewAreaUser              = 11,       /* user preview area */

    sfpItemPreviewStaticText            = 12,       /* static text preview */

    sfpItemPreviewDividerUser           = 13,       /* user divider preview */

    sfpItemCreatePreviewButton          = 14,       /* create preview button */

    sfpItemShowPreviewButton            = 15        /* show preview button */

};

Previewing Files Using Standard File Reply Structures

The Movie Toolbox provides two standard file functions, standardGetFilePreview and CustomGetFilePreview, that allow you to display file previews in an Open dialog box using standard file reply structures (of type StandardFileReply). The StandardGetFilePreview function corresponds to the existing StandardGetFile function; the CustomGetFilePreview function corresponds to the existing CustomGetFile function. Both of these new functions take the same parameters as their existing counterparts.

The StandardGetFilePreview function uses the dialog box shown in Figure 8-4. The CustomGetFilePreview function can also use this dialog box, if you do not supply your own.

You use these new functions in place of the existing standard file functions whenever you want to allow the user to display previews during the Open dialog box. The user causes a file’s preview to be displayed by selecting a file in the dialog box and clicking Show Preview. When the user does so, the functions display the preview for the file, as shown in Figure 8-5.

The preview portion of the dialog box is displayed only when the dialog box is showing a file’s preview.

The SFGetFilePreview, SFPGetFilePreview, StandardGetFilePreview, and CustomGetFilePreview functions allow the user to automatically convert files to movies if your application requests movies. If there is a file that can be converted into a movie file using a movie import component, then the file is shown in the Standard File dialog box in addition to any movies. When the user selects the file, the Open button changes to a Convert button. Figure 8-6 provides an example of this dialog box.

Choosing Convert displays a dialog box that allows the user to choose where the converted file should be saved. Figure 8-7 shows this dialog box.

When conversion is complete, the converted file is returned to the calling application as the movie that the user chose. If you want to disable automatic file conversion in your application, you must write a file filter function and pass it to the file preview display function you are using. Your file filter function must call the File Manager’s FSpGetFileInfo function on each file that is passed to it to determine its actual file type. If the File System parameter block pointer passed to your file filter function indicates that the file type is 'MooV', and the actual type returned by FSpGetFileInfo is not 'MooV', then the file filter function will convert this file. If you do not wish a file to be displayed as a candidate for conversion, your file filter function should return a value of true when it is called for that file.

A file filter function filters the files that are displayed to the user in a dialog box. You specify this function in the fileFilter parameter of the SFGetFilePreview, StandardGetFilePreview, and CustomGetFilePreview routines. If this parameter is not nil, SFGetFilePreview calls the function for each file to determine whether to display the file to the user. The SFGetFilePreview function supplies you with the information it receives from the File Manager’s GetFileInfo routine.

Functions for Creating File Previews

The Movie Toolbox provides two functions that allow you to create file previews. File previews contain information that gives the user an idea of a file’s contents without opening the file. Typically, a file’s preview is a small PICT image (called a thumbnail ), but previews may also contain other types of information that is appropriate to the type of file being considered. For example, a text file’s preview might tell the user when the file was created and what it discusses.

You can use the MakeFilePreview function to create a preview for a file. The AddFilePreview function allows you to add a preview that you have created to a file.