NavPutFile

NavPutFile
Header:	Navigation.h		Carbon status:	Supported

Displays a Save dialog box.

OSErr NavPutFile (
    AEDesc *defaultLocation, 
    NavReplyRecord *reply, 
    NavDialogOptions *dialogOptions, 
    NavEventUPP eventProc, 
    OSType fileType, 
    OSType fileCreator, 
    void *callBackUD
);

Parameter descriptions

defaultLocation: A pointer to an Apple event descriptor structure (AEDesc). Before calling NavPutFile, 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 displays the last location visited during a call to the NavPutFile 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 NavPutFile call.
dialogOptions: A pointer to a structure of type NavDialogOptions. Before calling NavPutFile, you can 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 Save dialog box is not movable or resizable. For more information, see “Handling Events”.
fileType: A four-character code. Pass the file type code for the document to be saved.
fileCreator: A four-character code. Pass the file creator code for the document to be saved. Under Navigation Services 2.0 or later, you may pass the kNavGenericSignature constant if you want to override the types of files appearing in the Format popup.
callBackUD: A pointer to a value set by your application. When the NavPutFile function calls your event-handling function, the callBackUD value is passed back to your application.

function result: A result code. Note: If you specify the kNavDontResolveAliases constant as a dialog box option, as described in “Dialog Option Configuration Constants”, before calling the NavPutFile function, Navigation Services returns a paramErr (-50).

DISCUSSION

After your application calls the NavPutFile function to display a Save dialog box and the user selects a location, enters a filename, and clicks OK, NavPutFile closes the dialog box and returns references to the file to be saved 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 save the file and call the function NavCompleteSave.

If you specify the Format pop-up menu in a dialog box displayed by the NavPutFile function, your application must provide adequate kind strings to describe the file types available. If the user uses the Format menu to save a file to a format other than the file’s native format, Navigation Services translates the file automatically. If you wish to turn off automatic translation, set to false the value of the translationNeeded field of the NavReplyRecord structure you pass in the reply parameter. If you turn off automatic translation, your application is responsible for any required translation.

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

For more information on translation, see “Translating Files on Save”.

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.