Legacy Document

Inside Macintosh: Files /

Chapter 3 - Standard File Package / Standard File Package Reference

Standard File Package Routines / Opening Files

CustomGetFile

Call the CustomGetFile procedure when your application requires more control over the Open dialog box than is possible using StandardGetFile.

PROCEDURE CustomGetFile (fileFilter: FileFilterYDProcPtr;
                           numTypes: Integer; 
                           typeList: SFTypeList; 
                           VAR reply: StandardFileReply; 
                           dlgID: Integer;
                           where: Point; 
                           dlgHook: DlgHookYDProcPtr; 
                           filterProc: ModalFilterYDProcPtr;
                           activeList: Ptr; 
                           activateProc: ActivateYDProcPtr;
                           yourDataPtr: UNIV Ptr);

fileFilter

A pointer to an optional file filter function, provided by your application, through which CustomGetFile passes files of the specified types.

numTypes

The number of file types to be displayed. If you specify a numTypes value of -1, the first filtering passes files of all types.

typeList

A list of file types to be displayed.

reply

The reply record, which CustomGetFile fills in before returning.

dlgID

The resource ID of a customized dialog template. To use the standard template, set this parameter to 0.

where

The upper-left corner of the dialog box in global coordinates. If you specify the point (-1,-1), CustomGetFile automatically centers the dialog box on the screen.

dlgHook

A pointer to your dialog hook function, which handles item selections received from the Dialog Manager. Specify a value of NIL if you have not added any items to the dialog box and want the standard items handled in the standard ways. See "Writing a Dialog Hook Function" on page 3-21 for a description of the dialog hook function.

filterProc

A pointer to your modal-dialog filter function, which determines how ModalDialog filters events when called by CustomGetFile. Specify a value of NIL if you are not supplying your own function. See "Writing a Modal-Dialog Filter Function" on page 3-28 for a description of the modal-dialog filter function.

activeList

A pointer to a list of all dialog items that can be activated--that is, made the target of keyboard input. The list is stored as an array of 16-bit integers. The first integer is the number of items in the list. The remaining integers are the item numbers of all possible keyboard targets, in the order that they are activated by the Tab key. If you supply an activeList parameter of NIL, CustomGetFile directs all keyboard input to the displayed list.

activateProc

A pointer to your activation procedure, which controls the highlighting of dialog items that are defined by your application and that can receive keyboard input. See "Writing an Activation Procedure" on page 3-30 for a description of the activation procedure.

yourDataPtr

A pointer to optional data supplied by your application. When CustomGetFile calls any of your callback routines, it pushes this parameter on the stack, making the data available to your callback routines. If you are not supplying any data of your own, specify a
value of NIL.

DESCRIPTION

The CustomGetFile procedure is an alternative to StandardGetFile when you want to use a customized dialog box or handle the default Open dialog box in a customized way. CustomGetFile presents a dialog box through which the user specifies the name and location of a file to be opened. While the dialog box is active, CustomGetFile gets and handles events until the user completes the interaction, either by selecting a file to open or by canceling the operation. CustomGetFile returns the user's input in a record of type StandardFileReply.

The first four parameters are similar to the same parameters in StandardGetFile.
The fileFilter, numTypes, and typeList parameters determine which files
appear in the list of choices. If you specify a value of -1 in the numTypes parameter, CustomGetFile displays or passes to your file filter function all files and folders (not just the files) at the current level of the display hierarchy. If you provide a filter function, CustomGetFile passes it both the pointer to the catalog entry for each file to be processed and also a pointer to the optional data passed by your application in its call
to CustomGetFile.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for CustomGetFile are

Trap macro	Selector
_Pack3	$0008

SPECIAL CONSIDERATIONS

The CustomGetFile procedure is not available in all versions of system software.
Use the Gestalt function to determine whether CustomGetFile is available before calling it.

Because CustomGetFile may move memory, you should not call it at interrupt time.