NavGetFile

NavGetFile
Header:	Navigation.h		Carbon status:	Supported

Displays a dialog box that prompts the user to select a file or files to be opened.

OSErr NavGetFile (
    AEDesc *defaultLocation, 
    NavReplyRecord *reply, 
    NavDialogOptions *dialogOptions, 
    NavEventUPP eventProc, 
    NavPreviewUPP previewProc, 
    NavObjectFilterUPP filterProc, 
    NavTypeListHandle typeList, 
    void *callBackUD
);

Parameter descriptions

defaultLocation: A pointer to an Apple event descriptor structure (AEDesc). Before calling NavGetFile, you can set up a structure of AEDesc type 'typeFSS' to specify a default location to be viewed. If you pass NULL in this parameter, Navigation Services defaults to the last location visited during a call to the NavGetFile function. If the file system specification in the AEDesc structure does not describe a directory or volume, Navigation Services uses the desktop as the default location.
reply: A pointer to a structure of type NavReplyRecord. Upon return, Navigation Services uses this structure to provide data to your application about the results of your NavGetFile call.
dialogOptions: A pointer to a structure of type NavDialogOptions. Before calling NavGetFile, set up this structure to specify dialog box settings. If you pass NULL in this parameter, Navigation Services uses the defaults for all options. See “Dialog Option Configuration Constants” for a description of the default settings.
eventProc: A Universal Procedure Pointer (UPP) of type NavEventProcPtr that points to your application-defined event-handling function. You obtain this UPP by calling the macro NewNavEventProc. Implementing an event-handling function allows your application to update windows after the user moves or resizes the dialog box. If you pass NULL in this parameter, the Open dialog box is not movable or resizable. For more information, see “Handling Events”.
previewProc: A Universal Procedure Pointer (UPP) of type NavPreviewProcPtr that points to your application-defined preview function. Obtain this UPP by calling the macro NewNavPreviewProc. A preview function allows your application to draw previews or to override Navigation Services previews. For more information, see “Drawing Custom Previews”).
filterProc: A Universal Procedure Pointer (UPP) of type NavObjectFilterProcPtr that points to your application-defined filter function. Obtain this UPP by calling the macro NewNavObjectFilterProc. An application-defined filter function determines if a volume, directory, or file should be displayed in the browser list or pop-up menus. For more information, see “Filtering File Objects”.
typeList: A handle to a structure of type NavTypeList. Before calling, set up this structure to declare file types that your application can open. For more information, see “Providing File Format Options”.
callBackUD: A pointer to a value set by your application. When the NavGetFile function calls your event-handling function, the callBackUD value is passed back to your application.

function result: A result code.

DISCUSSION

After your application calls the NavGetFile function to display an Open dialog box and the user selects one or more files and clicks the Open button, NavGetFile closes the dialog box and returns references to the files to be opened in the NavReplyRecord structure. Your application should check the validRecord field of the NavReplyRecord structure; if this field is set to true, your application should open the files specified in the selection field of the NavReplyRecord structure.

Always dispose of the NavReplyRecord structure after completing the file opening operation by calling the function NavDisposeReply. If you fail to use the NavDisposeReply function, memory used for the NavReplyRecord structure remains allocated and unavailable.

If you use the Show pop-up menu in an Open dialog box, your application must provide adequate kind strings to describe its native file types. For more information on describing native file types, see “Providing File Opening Options”.

For a sample code listing, see “A Sample File-Opening Function”.

SPECIAL CONSIDERATIONS

Always dispose of the NavReplyRecord structure after completing the file opening operation by calling the function NavDisposeReply. Failure to use the NavDisposeReply function causes memory used for the NavReplyRecord structure to remain allocated.

If you use the Show pop-up menu in an Open dialog box, your application must provide adequate kind strings to describe its native file types. For more information, see “Providing File Format Options”. For more information on kind strings, see Inside Macintosh: More Macintosh Toolbox.

VERSION NOTES

Available in Navigation Services 1.0 and later.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.