SFGetFilePreview(IM:Q)

Chapter 2 - Movie Toolbox / Movie Toolbox Reference

Functions for Displaying File Previews /

SFGetFilePreview
The SFGetFilePreview function allows you to display file previews in an Open dialog box using a standard file reply structure. This is the preferred function for displaying a file preview and it works with either System 7 or System 6.
pascal void SFGetFilePreview (Point where, 
                              ConstStr255Param prompt,
                              FileFilterProcPtr fileFilter,
                              short numTypes, SFTypeList typeList,
                              DlgHookProcPtr dlgHook, 
                              SFReply *reply);
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, 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 (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.

Your function must provide the following interface:
            pascal Boolean MyFileFilter (ParmBlkPtr parmBlock);
See "File Filter Functions" on page 2-338 for details.
numTypes
Specifies the number of file types in the array specified by the typeList parameter (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
Specifies a pointer to a custom dialog function. You can use this parameter to support a custom dialog box function you have supplied. If you are not supplying a custom dialog box function, set this parameter to nil. Your custom dialog function must present the following interface:
            pascal short MyDlgHook (short item, 
                                    DialogPtr theDialog, 
                                    Ptr myDataPtr);
For more information about using custom dialog box functions with the SFGetFilePreview function, see "Custom Dialog Functions" on page 2-339.
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.

DESCRIPTION
The SFGetFilePreview 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 SFGetFile routine. See Inside Macintosh: Files for a complete description of the SFGetFile routine.
The SFGetFilePreview 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.
The SFGetFilePreview 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 SFGetFilePreview function does not appear in the MPW interface file Movies.h; rather, it's listed in ImageCompression.h.