Inside Macintosh: QuickTime /

Chapter 2 - Movie Toolbox / Movie Toolbox Reference

Functions for Displaying File Previews /

CustomGetFilePreview

The CustomGetFilePreview function presents an Open dialog box to the user and allows the user to view file previews. This function differs from StandardGetFilePreview in that you can provide a custom dialog template and functions to support your template.

Note

The CustomGetFilePreview function is available only in System 7.

pascal void CustomGetFilePreview (FileFilterYDProcPtr fileFilter, 
                                  short numTypes, SFTypeList 
                                  typeList, StandardFileReply
                                  *reply, short dlgID, 
                                 Point where, 
                                 DlgHookYDProcPtr dlgHook,
                                 ModalFilterYDProcPtr filterProc,
                                 short *activeList, 
                                 ActivateYDProcPtr activateProc, 
                                 void *yourDataPtr); 

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 CustomGetFilePreview 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, CustomGetFilePreview calls the function for each file to determine whether to display the file to the user. The CustomGetFilePreview function supplies you with information identifying the file (see Inside Macintosh: Files for more information about the format of this parameter data). 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);

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 CustomGetFilePreview 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];

reply

Contains a pointer to a 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.

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.

dlgHook

Points to a custom dialog 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. You specify the dialog template's resource ID with the dlgID parameter. If you are not supplying a custom dialog function, set this parameter to nil. For more information about using custom dialog functions with the CustomGetFile routine, see Inside Macintosh: Files. For details on the parameters of the custom dialog box function, see "Custom Dialog Functions" on page 2-339.

Your dialog hook function must present the following interface:

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

filterProc

Points to your modal-dialog filter function. This function gives you greater control over the interface presented to the user. See Inside Macintosh: Files for more information about using modal-dialog filter functions with CustomGetFile.

Your modal-dialog filter function must present the following interface.

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

For details on the application-defined modal-dialog filter, see "Modal-Dialog Filter Functions" beginning on page 2-340.

activeList

Contains a pointer to a list of all items in the dialog box that can be activated--that is, made the target of keyboard input. The list is stored as an array of integers. The first integer must contain the number of items in the array (not including this count value). The remaining array entries must contain item numbers that specify valid targets of keyboard input, in the order in which the items are to be activated. Set this parameter to nil to direct all keyboard input to the displayed list of filenames.

activateProc

Points to your activation function, which controls the highlighting of any items whose shape is known only by your application. See Inside Macintosh: Files for more information about standard file activation functions.

Your function must present the following interface:

            pascal void MyActivateProc (DialogPtr theDialog, 
                                        short itemNo, 
                                        Boolean activating, 
                                        Ptr myDataPtr);

yourDataPtr

Contains a pointer to optional data that is supplied by your application to your callback functions. When the CustomGetFilePreview function calls any of your callback functions, it places this data on the stack, making it available to your functions. Set this parameter to nil if you are not supplying any optional data.

DESCRIPTION

The CustomGetFilePreview function is available only if the value of the Gestalt selector gestaltStandardFileAttr is true. (See Inside Macintosh: Overview for more information about this selector.) This function corresponds to the File Manager's CustomGetFile routine. The CustomGetFilePreview 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 CustomGetFile routine and for more information about the parameters to this function.

The CustomGetFilePreview 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 CustomGetFilePreview function does not appear in the MPW interface file Movies.h; rather, it's listed in ImageCompression.h.