Inside Macintosh: QuickTime /

Chapter 2 - Movie Toolbox / Movie Toolbox Reference

Functions for Displaying File Previews /

SFPGetFilePreview

The SFPGetFilePreview function allows you to display file previews in an Open dialog box using a standard file reply structure. This function differs from SFGetFilePreview in that you can provide a custom dialog box with any resource type and you can specify a modal-dialog filter function that allows you to gain greater control over the user interface.

pascal void SFPGetFilePreview (Point where, 
                               ConstStr255Param prompt,
                               FileFilterProcPtr fileFilter,
                               short numTypes, 
                               SFTypeList typeList,
                               DlgHookProcPtr dlgHook, 
                               SFReply *reply, short dlgID,
                               ModalFilterProcPtr filterProc);

where

Specifies the location of the upper-left corner of the dialog box in global coordinates. If you set this point to (-1, -1), the Movie Toolbox centers the dialog box on the main screen. If you set this point to (-2, -2), the Movie Toolbox centers the dialog box on the screen that has the best display characteristics.

prompt

This parameter is ignored; it is included for historical reasons only.

fileFilter

Points to a function that filters the files that are displayed to the user in the dialog box. This is an optional function provided by your application; if you do not want to supply a filter function, set this parameter to nil. The SFGetFilePreview function uses this parameter along with the numTypes and typeList parameters to determine which files appear in the dialog box.

If this parameter is not nil, SFPGetFilePreview calls the function for each file to determine whether to display the file to the user. The SFPGetFilePreview function supplies you with the information it receives from the File Manager's GetFileInfo routine (see Inside Macintosh: Files for more information). Your function returns a Boolean value indicating whether to display the file. Set the Boolean value to false to cause the file to be displayed. See "File Filter Functions," which begins on page 2-338, for details on file filter functions.

Your function must provide the following interface:

            pascal Boolean MyFileFilter (ParmBlkPtr parmBlock);

numTypes

Specifies the number of file types in the array specified by the typeList parameter. Specify a number between 1 and 4. Set this parameter to -1 to display all files.

typeList

Specifies an array of file types to be displayed to the user. The SFGetFilePreview function only displays files whose type matches an entry in this array (unless you set the numTypes parameter to -1; in this case, the function displays all files to the user). The SFTypeList data type is defined as follows:

            typedef OSType SFTypeList[4];

dlgHook

Points to a custom dialog box function. You can use this parameter to support a custom dialog box function you have supplied by specifying a dialog template resource in your resource file (the dialog template's resource type must be set to 'DLOG'; you must also supply an item list in a 'DITL' resource). You specify the dialog template's resource ID with the dlgID parameter. If you are not supplying a custom dialog function in this manner, set this parameter to nil.

Your custom dialog box function must present the following interface:

            pascal short MyDlgHook (short item, 
                                    DialogPtr theDialog, 
                                    Ptr myDataPtr);

See "Custom Dialog Functions" on page 2-339 for more information on using custom dialog functions with the SFPGetFilePreview function.

reply

Contains a pointer to a standard file reply structure that is to receive information about the user's selection. See Inside Macintosh: Files for more information about reply structures.

dlgID

Specifies the resource ID of your custom dialog template. You can use this parameter to specify a custom dialog template resource that has a resource type that differs from the standard value. Set this parameter to 0 to use the standard template.

filterProc

Points to your modal-dialog filter function. This function gives you greater control over the interface presented to the user. Your modal-dialog filter function must present the following interface:

            pascal Boolean MyModalFilter (DialogPtr theDialog,
                                          EventRecord* theEvent,
                                          short itemHit, 
                                          Ptr myDataPtr);

See "Modal-Dialog Filter Functions" beginning on page 2-340 for details.

DESCRIPTION

The SFPGetFilePreview function presents an Open dialog box to the user and allows the user to view file previews during the dialog. This function corresponds to the File Manager's SFPGetFile routine. The SFPGetFilePreview function takes the same parameters as its existing counterpart with the addition of a where parameter that allows you to specify the location of the dialog box. See Inside Macintosh: Files for a complete description of the SFPGetFile routine and for more information about the parameters to this function.

The SFPGetFilePreview function automatically converts files to movies if your application requests movies. If a file could be converted into a movie file using a movie import component, then the file is shown in the Standard File dialog box. See Figure 2-38 on page 2-59 for the dialog box with an automatic file-to-movie conversion option and Figure 2-39 on page 2-59 for the dialog box for saving a movie converted from a file.

Note

The SFPGetFilePreview function does not appear in the MPW interface file Movies.h; rather, it's listed in ImageCompression.h.