< Previous PageNext Page >

Hide TOC

Deprecated Navigation Services Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.5

NavAskDiscardChanges

Displays an alert box that asks the user whether to discard changes to a particular document. (Deprecated in Mac OS X v10.5.)

Not recommended

OSErr NavAskDiscardChanges (
   NavDialogOptions *dialogOptions,
   NavAskDiscardChangesResult *reply,
   NavEventUPP eventProc,
   void *callBackUD
);

Parameters

dialogOptions: A pointer to a structure of type NavDialogOptions. Before calling NavAskDiscardChanges, set up this structure to specify dialog box settings. In this case, the savedFileName field is the only one you must supply with a value.
reply: A pointer to a structure of type NavAskDiscardChanges. On return, the value describes the user’s response to the Discard Changes alert box. For a description of the constants used to represent possible responses, see “Discard Changes Actions.”
eventProc: A Universal Procedure Pointer (UPP) to your application-defined event-handling function. You obtain this UPP by calling the function NewNavEventUPP. 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 Discard Changes alert box is not movable. For more information on event-handling functions, see NavEventProcPtr.
callBackUD: A pointer to a value set by your application. When the NavAskDiscardChanges function calls your event-handling function, the callBackUD value is passed back to your application.

Return Value

A result code. See “Navigation Services Result Codes.”

Discussion

If your application provides a Revert to Saved command, you can use the NavAskDiscardChanges function to display a confirmation alert box when a user selects Revert to Saved for a document with unsaved changes. Navigation Services uses the string you supply in the savedFileName field of the NavDialogOptions structure you passed in the dialogOptions parameter to display the alert message, “Discard changes to [savedFilename]?”.

Availability

Available in CarbonLib 1.0 and later when Navigation Services 1.0 or later is present.
Available in Mac OS X 10.0 and later.
Deprecated in Mac OS X v10.5.

Carbon Porting Notes

Apple recommends you use the function NavCreateAskDiscardChangesDialog in order to take advantage of Mac OS X features like Unicode, long filenames and enhanced modality.

Declared In

Navigation.h

NavAskSaveChanges

Displays a Save Changes alert box. (Deprecated in Mac OS X v10.5.)

Not recommended

OSErr NavAskSaveChanges (
   NavDialogOptions *dialogOptions,
   NavAskSaveChangesAction action,
   NavAskSaveChangesResult *reply,
   NavEventUPP eventProc,
   void *callBackUD
);

Parameters

dialogOptions: A pointer to a structure of type NavDialogOptions. Before calling NavAskSaveChanges, set up this structure to specify dialog box settings. When calling NavAskSaveChanges, the clientName and savedFileName fields are the only two fields you must supply with values.
action: A value of type NavAskSaveChangesAction. Pass a constant describing the user action that prompted the Save Changes alert box. For a description of the constants, see “Save Changes Requests.”
reply: A pointer to a value of type NavAskSaveChangesResult. On return, the value describes the user’s response to the Save Changes alert box. For a description of the constants used to represent possible responses, see “Save Changes Actions.”
eventProc: A Universal Procedure Pointer (UPP) to your application-defined event-handling function. You obtain this UPP by calling the function NewNavEventUPP. 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 Changes alert box is not movable. For more information on event-handling functions, see NavEventProcPtr.
callBackUD: A pointer to a value set by your application. When the NavAskSaveChanges function calls your event-handling function, the callBackUD value is passed back to your application.

Return Value

A result code. See “Navigation Services Result Codes.”

Discussion

This function is useful when your application needs to display an alert when the user attempts to close a document or an application with unsaved changes.

Availability

Available in CarbonLib 1.0 and later when Navigation Services 1.0 or later is present.
Available in Mac OS X 10.0 and later.
Deprecated in Mac OS X v10.5.

Carbon Porting Notes

Apple recommends you use the function NavCreateAskSaveChangesDialog in order to take advantage of Mac OS X features like Unicode, long filenames and enhanced modality.

Declared In

Navigation.h

NavChooseFile

Creates a simple dialog box that prompts the user to select a file. (Deprecated in Mac OS X v10.5.)

Not recommended

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

Parameters

defaultLocation: A pointer to an Apple event descriptor structure (AEDesc). Before calling NavChooseFile, 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 NavChooseFile 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 NavChooseFile call.
dialogOptions: A pointer to a structure of type NavDialogOptions. Before calling NavChooseFile, 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 Configuration Options” for a description of the default settings.
eventProc: A Universal Procedure Pointer (UPP) to your application-defined event-handling function. You obtain this UPP by calling the function NewNavEventUPP. 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 Choose a File dialog box is not movable or resizable. For more information on event-handling functions, see NavEventProcPtr.
previewProc: A Universal Procedure Pointer (UPP) to your application-defined preview function. Obtain this UPP by calling the function NewNavPreviewUPP. A preview function allows your application to draw previews or to override Navigation Services previews. For more information on preview functions, see NavPreviewProcPtr.
filterProc: A Universal Procedure Pointer (UPP) to your application-defined filter function. Obtain this UPP by calling the function NewNavObjectFilterUPP. 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 on filter functions, see NavObjectFilterProcPtr.
typeList: A handle to a structure of type NavTypeList. Before calling NavChooseFile, you can set up this structure to declare file types that your application can open.
callBackUD: A pointer to a value set by your application. When the NavChooseFile function calls your event-handling function, the callBackUD value is passed back to your application.

Return Value

A result code. See “Navigation Services Result Codes.”

Discussion

This function allows the user to choose a single file, such as a preferences file, for an action other than opening. The NavChooseFile function is similar to NavGetFile, but is limited to selecting a single file.

The dialog box displayed by the NavChooseFile function does not display a Show menu. If you wish to control the files displayed by the browser list or the pop-up menus, you must specify a list of file types in the typeList parameter or specify a filter function in the filterProc parameter. If you specify a list of file types in the typeList parameter, the NavChooseFile function ignores the signature field of the NavTypeList structure. This means that all files of the types specified in the list of file types will be displayed, regardless of their application signature.

Availability

Available in CarbonLib 1.0 and later when Navigation Services 1.0 or later is present.
Available in Mac OS X 10.0 and later.
Deprecated in Mac OS X v10.5.

Carbon Porting Notes

Apple recommends you use the function NavCreateChooseFileDialog in order to take advantage of Mac OS X features like Unicode, long filenames and enhanced modality.

Declared In

Navigation.h

NavChooseFolder

Displays a dialog box that prompts the user to choose a folder or volume. (Deprecated in Mac OS X v10.5.)

Not recommended

OSErr NavChooseFolder (
   AEDesc *defaultLocation,
   NavReplyRecord *reply,
   NavDialogOptions *dialogOptions,
   NavEventUPP eventProc,
   NavObjectFilterUPP filterProc,
   void *callBackUD
);

Parameters

defaultLocation: A pointer to an Apple event descriptor structure (AEDesc). Before calling NavChooseFolder, 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 NavChooseFolder 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 NavChooseFolder call.
dialogOptions: A pointer to a structure of type NavDialogOptions. Before calling NavChooseFolder, 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 Configuration Options” for a description of the default settings.
eventProc: A Universal Procedure Pointer (UPP) to your application-defined event-handling function. You obtain this UPP by calling the function NewNavEventUPP. 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 dialog box is not movable or resizable. For more information on event-handling functions, see NavEventProcPtr.
filterProc: A Universal Procedure Pointer (UPP) to your application-defined filter function. Obtain this UPP by calling the function NewNavObjectFilterUPP. 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 on filter functions, see NavObjectFilterProcPtr.
callBackUD: A pointer to a value set by your application. When the NavChooseFolder function calls your event-handling function, the callBackUD value is passed back to your application.

Return Value

A result code. See “Navigation Services Result Codes.”

Discussion

This function provides a way for your application to prompt the user to select a folder or volume. This might be useful if you need to install application files, for example.

Availability

Available in CarbonLib 1.0 and later when Navigation Services 1.0 or later is present.
Available in Mac OS X 10.0 and later.
Deprecated in Mac OS X v10.5.

Carbon Porting Notes

Apple recommends you use the function NavCreateChooseFolderDialog in order to take advantage of Mac OS X features like Unicode, long filenames and enhanced modality.

Declared In

Navigation.h

NavChooseObject

Displays a dialog box that prompts the user to choose a file, folder, or volume. (Deprecated in Mac OS X v10.5.)

Not recommended

OSErr NavChooseObject (
   AEDesc *defaultLocation,
   NavReplyRecord *reply,
   NavDialogOptions *dialogOptions,
   NavEventUPP eventProc,
   NavObjectFilterUPP filterProc,
   void *callBackUD
);

Parameters

defaultLocation: A pointer to an Apple event descriptor structure (AEDesc). Before calling NavChooseObject, 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 NavChooseObject 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 NavChooseObject call.
dialogOptions: A pointer to a structure of type NavDialogOptions. Before calling NavChooseObject, set up this structure to specify dialog box settings. If you do not provide this structure, Navigation Services uses the defaults for all options. See “Dialog Configuration Options” for a description of the default settings.
eventProc: A Universal Procedure Pointer (UPP) to your application-defined event-handling function. You obtain this UPP by calling the function NewNavEventUPP. 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 dialog box is not movable or resizable. For more information on event-handling functions, see NavEventProcPtr.
filterProc: A Universal Procedure Pointer (UPP) to your application-defined filter function. Obtain this UPP by calling the function NewNavObjectFilterUPP. 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 on filter functions, see NavObjectFilterProcPtr.
callBackUD: A pointer to a value set by your application. When the NavChooseObject function calls your event-handling function, the callBackUD value is passed back to your application.

Return Value

A result code. See “Navigation Services Result Codes.”

Discussion

This function is useful when you need to display a dialog box that prompts the user to choose a file object that might be a file, folder, or volume. If you want the user to choose a specific type of file object, you should use the function designed for that type of object; to select a file, for example, use the function NavChooseFile.

Availability

Available in CarbonLib 1.0 and later when Navigation Services 1.0 or later is present.
Available in Mac OS X 10.0 and later.
Deprecated in Mac OS X v10.5.

Carbon Porting Notes

Apple recommends you use the function NavCreateChooseObjectDialog in order to take advantage of Mac OS X features like Unicode, long filenames and enhanced modality.

Declared In

Navigation.h

NavChooseVolume

Displays a dialog box that prompts the user to choose a volume. (Deprecated in Mac OS X v10.5.)

Not recommended

OSErr NavChooseVolume (
   AEDesc *defaultSelection,
   NavReplyRecord *reply,
   NavDialogOptions *dialogOptions,
   NavEventUPP eventProc,
   NavObjectFilterUPP filterProc,
   void *callBackUD
);

Parameters

defaultSelection: A pointer to an Apple event descriptor structure (AEDesc). Before calling NavChooseVolume, 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 NavChooseVolume 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 NavChooseVolume call.
dialogOptions: A pointer to a structure of type NavDialogOptions. Before calling, 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 Configuration Options” for a description of the default settings.
eventProc: A Universal Procedure Pointer (UPP) to your application-defined event-handling function. You obtain this UPP by calling the function NewNavEventUPP. 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 Choose a Volume dialog box is not movable or resizable. For more information on event-handling functions, see NavEventProcPtr.
filterProc: A Universal Procedure Pointer (UPP) to your application-defined filter function. Obtain this UPP by calling the function NewNavObjectFilterUPP. 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 on filter functions, see NavObjectFilterProcPtr.
callBackUD: A pointer to a value set by your application. When the NavChooseVolume function calls your event-handling function, the callBackUD value is passed back to your application.

Return Value

A result code. See “Navigation Services Result Codes.”

Discussion

This function provides a way for your application to prompt the user to select a volume. This might be useful for a disk repair utility, for example.

Availability

Available in CarbonLib 1.0 and later when Navigation Services 1.0 or later is present.
Available in Mac OS X 10.0 and later.
Deprecated in Mac OS X v10.5.

Carbon Porting Notes

Apple recommends you use the function NavCreateChooseVolumeDialog in order to take advantage of Mac OS X features like Unicode, long filenames and enhanced modality.

Declared In

Navigation.h

NavCreatePreview

Creates a document preview in a specified file. (Deprecated in Mac OS X v10.5.)

OSErr NavCreatePreview (
   AEDesc *theObject,
   OSType previewDataType,
   const void *previewData,
   Size previewDataSize
);

Parameters

theObject: A pointer to an Apple Event Descriptor (AEDesc) structure specifying the file in which to create the preview.
previewDataType: A four character code specifying the type of preview data to create. If you pass NULL in this parameter, Navigation Services creates a preview of type 'PICT'.
previewData: A pointer to a buffer holding preview data. If you pass NULL in this parameter, Navigation Services provides its own data.
previewDataSize: A value specifying the size, in bytes, of the preview data you are providing. If you pass NULL in this parameter, Navigation Services provides its own data.

Return Value

A result code. See “Navigation Services Result Codes.”

Discussion

This function creates a preview of the specified file and stores the data in an appropriate resource. If you call this function without passing in preview data, as in the following snippet, Navigation Services obtains and creates the preview automatically:

NavCreatePreview(theObject,0,NULL,0)

If the specified file is image-based ('PICT', 'JPEG', etc.), Navigation Services creates a thumbnail custom icon for the file. Navigation Services does not create a custom icon if you pass in your own preview data.

Availability

Available in CarbonLib 1.0 and later when Navigation Services 2.0 or later is present.
Available in Mac OS X 10.0 and later.
Deprecated in Mac OS X v10.5.
Not available to 64-bit applications.

Declared In

Navigation.h

NavCustomAskSaveChanges

Displays a Save Changes alert box with a custom alert message. (Deprecated in Mac OS X v10.5.)

Not recommended

OSErr NavCustomAskSaveChanges (
   NavDialogOptions *dialogOptions,
   NavAskSaveChangesResult *reply,
   NavEventUPP eventProc,
   void *callBackUD
);

Parameters

dialogOptions: A pointer to a structure of type NavDialogOptions. Before calling NavCustomAskSaveChanges, set up this structure to specify dialog box settings. When calling NavCustomAskSaveChanges, the message field is the only field you must supply with a value.
reply: A pointer to a value of type NavAskSaveChangesResult. On return, the value describes the user’s response to the Save Changes alert box. For a description of the constants used to represent possible responses, see “Save Changes Actions.”
eventProc: A Universal Procedure Pointer (UPP) to your application-defined event-handling function. You obtain this UPP by calling the function NewNavEventUPP. 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 Changes alert box is not movable. For more information on event-handling functions, see NavEventProcPtr.
callBackUD: A pointer to a value set by your application. When the NavCustomAskSaveChanges function calls your event-handling function, the callBackUD value is passed back to your application.

Return Value

A result code. See “Navigation Services Result Codes.”

Discussion

This function is similar to the function NavAskSaveChanges, except that you provide a custom alert message. This function is useful when you need to post a Save Changes alert box at times other than quitting or closing a file. Your application can display this alert box if a specified time interval has passed since the user last saved changes, for example.

Availability

Available in CarbonLib 1.0 and later when Navigation Services 1.0 or later is present.
Available in Mac OS X 10.0 and later.
Deprecated in Mac OS X v10.5.

Carbon Porting Notes

Apple recommends you use the function NavCreateAskSaveChangesDialog in order to take advantage of Mac OS X features like Unicode, long filenames and enhanced modality. In order to provide a customized alert message, pass a non-null message string in the NavDialogCreationOptions structure passed to NavCreateAskSaveChangesDialog.

Declared In

Navigation.h

NavGetDefaultDialogOptions

Determines the default attributes or behavior for dialog boxes. (Deprecated in Mac OS X v10.5.)

Not recommended

OSErr NavGetDefaultDialogOptions (
   NavDialogOptions *dialogOptions
);

Parameters

dialogOptions: A pointer to a structure of type NavDialogOptions. On return, Navigation Services fills out the structure with default option values that your application can change as needed.

Return Value

A result code. See “Navigation Services Result Codes.”

Discussion

This function gives you a simple way to initialize a structure of type NavDialogOptions and set the default dialog box options before calling one of the dialog box display functions. After you create the NavDialogOptions structure, you can supply it with the NavDialogOptions constants, described in “Dialog Configuration Options,” to change the configuration options.

Availability

Available in CarbonLib 1.0 and later when Navigation Services 1.0 or later is present.
Available in Mac OS X 10.0 and later.
Deprecated in Mac OS X v10.5.

Carbon Porting Notes

Apple recommends that you adopt the dialog creation functions (NavCreate...Dialog); you pass these functions a NavDialogCreationOptions structure rather than a NavDialogOptions structure.

Related Sample Code

QTMetaData

Declared In

Navigation.h

NavGetFile

Displays a dialog box that prompts the user to select a file or files to be opened. (Deprecated in Mac OS X v10.5.)

Not recommended

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

Parameters

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 Configuration Options” for a description of the default settings.
eventProc: A Universal Procedure Pointer (UPP) to your application-defined event-handling function. You obtain this UPP by calling the function NewNavEventUPP. 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 on event-handling functions, see NavEventProcPtr.
previewProc: A Universal Procedure Pointer (UPP) to your application-defined preview function. Obtain this UPP by calling the function NewNavPreviewUPP. A preview function allows your application to draw previews or to override Navigation Services previews. For more information on preview functions, see NavPreviewProcPtr.
filterProc: A Universal Procedure Pointer (UPP) to your application-defined filter function. Obtain this UPP by calling the function NewNavObjectFilterUPP. 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 on filter functions, see NavObjectFilterProcPtr.
typeList: A handle to a structure of type NavTypeList. Before calling, set up this structure to declare file types that your application can open.
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.

Return Value

A result code. See “Navigation Services Result Codes.”

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 kind strings, see Inside Macintosh: More Macintosh Toolbox.

Availability

Available in CarbonLib 1.0 and later when Navigation Services 1.0 or later is present.
Available in Mac OS X 10.0 and later.
Deprecated in Mac OS X v10.5.

Carbon Porting Notes

Apple recommends you use the function NavCreateGetFileDialog in order to take advantage of Mac OS X features like Unicode, long filenames and enhanced modality.

Related Sample Code

QTMetaData

Declared In

Navigation.h

NavLibraryVersion

Reports the currently installed version of the Navigation Services shared library. (Deprecated in Mac OS X v10.5.)

UInt32 NavLibraryVersion (
   void
);

Return Value

An unsigned 32-bit integer. This value represents the version number (in binary-coded decimal) of Navigation Services installed on the user’s system.

Discussion

If you want to use features that are present only in a specific version of Navigation Services, use the NavLibraryVersion function to determine which version of Navigation Services is installed.

Availability

Available in CarbonLib 1.0 and later when Navigation Services 1.0 or later is present.
Available in Mac OS X 10.0 and later.
Deprecated in Mac OS X v10.5.

Declared In

Navigation.h

NavNewFolder

Displays a dialog box that prompts the user to create a new folder. (Deprecated in Mac OS X v10.5.)

Not recommended

OSErr NavNewFolder (
   AEDesc *defaultLocation,
   NavReplyRecord *reply,
   NavDialogOptions *dialogOptions,
   NavEventUPP eventProc,
   void *callBackUD
);

Parameters

defaultLocation: A pointer to an Apple event descriptor structure (AEDesc). Before calling NavNewFolder, 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 NavNewFolder 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 the NavNewFolder function call.
dialogOptions: A pointer to a structure of type NavDialogOptions. Before calling NavNewFolder, 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 Configuration Options” for a description of the default settings.
eventProc: A Universal Procedure Pointer (UPP) to your application-defined event-handling function. You obtain this UPP by calling the function NewNavEventUPP. 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 dialog box is not movable or resizable. For more information on event-handling functions, see NavEventProcPtr.
callBackUD: A pointer to a value set by your application. When the NavNewFolder function calls your event-handling function, the callBackUD value is passed back to your application.

Return Value

A result code. See “Navigation Services Result Codes.”

Discussion

This function provides a way for your application to prompt the user to create a new folder. This might be useful for creating a project folder, for example.

Availability

Available in CarbonLib 1.0 and later when Navigation Services 1.0 or later is present.
Available in Mac OS X 10.0 and later.
Deprecated in Mac OS X v10.5.

Carbon Porting Notes

Apple recommends you use the function NavCreateNewFolderDialog in order to take advantage of Mac OS X features like Unicode, long filenames and enhanced modality.

Declared In

Navigation.h

NavPutFile

Displays a Save dialog box. (Deprecated in Mac OS X v10.5.)

Not recommended

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

Parameters

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 Configuration Options” for a description of the default settings.
eventProc: A Universal Procedure Pointer (UPP) to your application-defined event-handling function. You obtain this UPP by calling the function NewNavEventUPP. 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 on event-handling functions, see NavEventProcPtr.
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 “Generic File Signature Constant” 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.

Return Value

A result code. See “Navigation Services Result Codes.” Note: If you specify the kNavDontResolveAliases constant as a dialog box option, as described in “Dialog Configuration Options,” 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.

Availability

Available in CarbonLib 1.0 and later when Navigation Services 1.0 or later is present.
Available in Mac OS X 10.0 and later.
Deprecated in Mac OS X v10.5.

Carbon Porting Notes

Apple recommends you use the function NavCreatePutFileDialog in order to take advantage of Mac OS X features like Unicode, long filenames and enhanced modality.

Related Sample Code

QTMetaData

Declared In

Navigation.h

NavTranslateFile

Provides a means for files opened through Navigation Services to be read from different file formats. (Deprecated in Mac OS X v10.5.)

OSErr NavTranslateFile (
   const NavReplyRecord *reply,
   NavTranslationOptions howToTranslate
);

Parameters

reply: A pointer to a structure of type NavReplyRecord. Upon return, Navigation Services uses this structure to provide translation information about the selected files.
howToTranslate: A value of type NavTranslationOptions. Pass one of these constants to tell Navigation Services how to perform the translation: either in-place or by making a copy of the file. For a description of the constants, see “Translation Options.”

Return Value

A result code. See “Navigation Services Result Codes.”

Discussion

Under automatic file translation, Navigation Services calls the NavTranslateFile function as necessary before returning from a file-opening function.

Your application can perform its own translation using the NavReplyRecord structure you specified in the translateInfo parameter. The NavReplyRecord structure contains a list of descriptors for the file or files to be opened and a corresponding list of translation specification records that can be passed to the Translation Manager. To determine if your application has to translate a file, your application can examine the NavReplyRecord structure to see if Navigation Services set the translationNeeded field to true. (The translationNeeded field of the NavReplyRecord structure is also set to true after returning from a NavGetFile call during which automatic translation was performed.) If you want to turn off automatic file translation, set the constant kNavDontAutoTranslate in the dialogOptionFlags field of the structure of type NavDialogOptions that you pass in the dialogOptions parameter of the file-opening function.

If your application uses the NavTranslateFile function after opening a file without automatic translation, Navigation Services checks to see if the source location can accept a new file. If the source location is not available (as occurs when the volume is locked or there is insufficient space), Navigation Services prompts the user to select a location in which to save the translated file. The same prompt may occur when automatic translation is enabled in an Open dialog box.

Availability

Available in CarbonLib 1.0 and later when Navigation Services 1.0 or later is present.
Available in Mac OS X 10.0 and later.
Deprecated in Mac OS X v10.5.

Declared In

Navigation.h

< Previous PageNext Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.