Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Navigation Services Reference

Framework
Carbon/Carbon.h
Declared in
Navigation.h

Overview

Navigation Services is an application programming interface that allows your application to provide a user interface for navigating, opening, and saving Mac OS file objects.

This reference describes the application programming interface for Navigation Services, as introduced with CarbonLib 1.1. Navigation Services establishes a new model for creating, displaying, and processing dialogs. This new functionality gives you the ability to create truly modeless dialogs and provides support for Unicode and Mac OS X sheets.

Navigation Services replaces the Standard File Package, which is not supported in Carbon.

Functions by Task

Creating Dialogs

Choosing Files, Folders and Volumes

Saving Files

Customizing Dialogs

Running And Disposing of Dialogs

Obtaining Dialog Information

Translating Files

Identifying Navigation Services Availability

Working With Universal Procedure Pointers

Deprecated Functions

Unsupported Functions

Functions

DisposeNavEventUPP

Disposes of a UPP to an application-defined event–handling function.

void DisposeNavEventUPP (
   NavEventUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Discussion

For more information on event–handling functions, see NavEventProcPtr.

Availability
Declared In
Navigation.h

DisposeNavObjectFilterUPP

Disposes of a UPP to an application-defined filter function.

void DisposeNavObjectFilterUPP (
   NavObjectFilterUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Discussion

For more information on filter functions, see NavObjectFilterProcPtr.

Availability
Declared In
Navigation.h

DisposeNavPreviewUPP

Disposes of a UPP to an application-defined preview function.

void DisposeNavPreviewUPP (
   NavPreviewUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Discussion

For more information on preview functions, see NavPreviewProcPtr.

Availability
Declared In
Navigation.h

InvokeNavEventUPP

Calls your application-defined event–handling function.

void InvokeNavEventUPP (
   NavEventCallbackMessage callBackSelector,
   NavCBRecPtr callBackParms,
   void *callBackUD,
   NavEventUPP userUPP
);

Discussion

You should not need to use the function InvokeNavEventUPP, as the system calls your event–handling function for you.

Availability
Declared In
Navigation.h

InvokeNavObjectFilterUPP

Calls your application-defined filter function.

Boolean InvokeNavObjectFilterUPP (
   AEDesc *theItem,
   void *info,
   void *callBackUD,
   NavFilterModes filterMode,
   NavObjectFilterUPP userUPP
);

Discussion

You should not need to use the function InvokeNavObjectFilterUPP, as the system calls your filter function for you.

Availability
Declared In
Navigation.h

InvokeNavPreviewUPP

Calls your application-defined preview function.

Boolean InvokeNavPreviewUPP (
   NavCBRecPtr callBackParms,
   void *callBackUD,
   NavPreviewUPP userUPP
);

Discussion

You should not need to use the function InvokeNavPreviewUPP, as the system calls your preview function for you.

Availability
Declared In
Navigation.h

NavCompleteSave

Completes a save operation and performs any needed translation on the file.

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

Parameters
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 NavCompleteSave call.

howToTranslate

A pointer to a structure of type NavTranslationOptions. Pass one of two values to specify how to perform any needed translation. For a description of the constants you can use to represent these values, see “Translation Options.” Translating in-place causes the source file to be replaced by the translation. Translating to a copy results in a file name followed by the string “(converted)” to avoid unwanted replacement. If you call the NavCompleteSave function in response to a Save a Copy command, you should pass the kNavTranslateInPlace constant in this parameter.

Return Value

A result code. See “Navigation Services Result Codes.” Since this function performs any needed translation, it may return a translation error.

Discussion

You should always call NavCompleteSave to complete any file saving operation performed with the NavCreatePutFileDialog function. NavCompleteSave performs any needed translation, so you do not have to use the function NavTranslateFile when saving. 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 of the NavPutFile function. If you turn off automatic translation, your application is responsible for any required translation.

Availability
Declared In
Navigation.h

NavCreateAskDiscardChangesDialog

Creates a dialog that asks the user whether to discard changes.

OSStatus NavCreateAskDiscardChangesDialog (
   const NavDialogCreationOptions *inOptions,
   NavEventUPP inEventProc,
   void *inClientData,
   NavDialogRef *outDialog
);

Parameters
inOptions

A pointer to a structure specifying options that control the appearance and behavior of the dialog. You must supply a string in the saveFileName field of this structure; otherwise the function returns paramErr.

inEventProc

A Universal Procedure Pointer (UPP) to your application’s event-handling function. You are strongly advised to create and register an event-handling function, as described in NavEventProcPtr. You must have an event-handling function in order to create modeless or window-modal (sheet) dialogs. Specify NULL in this parameter if you do not implement an event-handling function.

inClientData

A pointer to an application-defined value that is passed back to all callback functions. You can use this value to provide context information, for example. You may pass NULL in this parameter.

outDialog

On successful creation of a Discard Changes dialog, A pointer to a Navigation Services dialog reference that you can pass to the NavDialogRun function

Return Value

A result code.

Discussion

This function creates a dialog that gives the user the option of discarding unsaved changes to a file or cancelling the operation. This dialog is most commonly used when the user wants to revert to the last saved version of a document.

Once you have successfully created the Discard Changes dialog, you display it by calling the NavDialogRun function. After the user interacts with the dialog, you can obtain information about the dialog session by calling the NavDialogGetReply function. When you are finished with the dialog, dispose of it by calling the NavDialogDispose function.

This function replaces the NavAskDiscardChanges function and adds support for Unicode and new window modalities.

Availability
Declared In
Navigation.h

NavCreateAskReviewDocumentsDialog

Creates a Review Changes dialog, which notifies the user of multiple unsaved documents and gives the user the option to review them.

OSStatus NavCreateAskReviewDocumentsDialog (
   const NavDialogCreationOptions *inOptions,
   ItemCount inDocumentCount,
   NavEventUPP inEventProc,
   void *inClientData,
   NavDialogRef *outDialog
);

Parameters
inOptions

A pointer to a structure specifying options that control the appearance and behavior of the dialog.

inDocumentCount

The number of documents needing review. This number appears in the text presented to the user. If the total number of unsaved documents is unknown, specify 0; Navigation Services uses a general message. You should not specify 1; this alert should be used only when more than one document needs review. For more information, see Inside Mac OS X: Aqua Human Interface Guidelines.

inEventProc

A universal procedure pointer (UPP) to an application-defined event-handling function. You are strongly advised to create and register an event-handling function, as described in NavEventProcPtr. You must have an event-handling function in order to create modeless or window-modal (sheet) dialogs. Specify NULL in this parameter if you do not implement an event-handling function.

inClientData

A pointer to an application-defined value that is passed back to all callback functions.

outDialog

Upon successful completion, a reference to the created dialog.

Return Value

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

Discussion

The Review Changes dialog tells the user how many unsaved documents there are and asks the user to choose one of the following options:

Use of this dialog is appropriate when an application is quitting and there is more than one unsaved document. It is supported only on Mac OS X; prior to Mac O X, this dialog is not part of the application quit sequence.

Upon successful creation, the dialog is not visible; to present and run the dialog, call the NavDialogRun function. After the dialog is complete, dispose of it with the NavDialogDispose function. Upon dismissal of the dialog, the user’s action is set to one of the following actions: kNavUserActionReviewDocuments, kNavUserActionDiscardDocuments, or kNavUserActionCancel. You can obtain this reply by calling the NavDialogGetReply.

Availability
Declared In
Navigation.h

NavCreateAskSaveChangesDialog

Creates a dialog that asks the user whether to save changes.

OSStatus NavCreateAskSaveChangesDialog (
   const NavDialogCreationOptions *inOptions,
   NavAskSaveChangesAction inAction,
   NavEventUPP inEventProc,
   void *inClientData,
   NavDialogRef *outDialog
);

Parameters
inOptions

A pointer to a structure specifying options that control the appearance and behavior of the dialog.

inAction

A value indicating whether the user is closing a document or quitting the application and thereby determines the message displayed to the user. To provide a customized message for the dialog, specify a non-NULL value in the message field of the structure provided in the inOptions parameter.

inEventProc

A Universal Procedure Pointer (UPP) to your application’s event-handling function. You are strongly advised to create and register an event-handling function, as described in NavEventProcPtr. You must have an event-handling function in order to create modeless or window-modal (sheet) dialogs. Specify NULL in this parameter if you do not implement an event-handling function.

inClientData

A pointer to an application-defined value that is passed back to all callback functions. You can use this value to provide context information, for example. You may pass NULL in this parameter.

outDialog

On successful creation of the Save Changes dialog, a pointer to a Navigation Services dialog reference that you can pass to the NavDialogRun function.

Return Value

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

Discussion

This function creates a Save Changes dialog, which your application should display when the user attempts to close a document or quit the application with unsaved changes. The Save Changes dialog allows the user to choose one of the following options:

Once you have successfully created the Save Changes dialog, you display it by calling the NavDialogRun function. After the user interacts with the dialog, you can obtain information about the dialog session by calling the NavDialogGetReply function. When you are finished with the dialog, dispose of it by calling the NavDialogDispose function.

If there is more than one document with unsaved changes when the user attempts to quit your application, you should display a Review Changes dialog instead. You can create a Review Changes dialog with the NavCreateAskReviewDocumentsDialog function.

This function replaces the NavAskSaveChanges function and adds support for Unicode and new window modalities.

Availability
Declared In
Navigation.h

NavCreateChooseFileDialog

Creates a Choose File dialog, which prompts the user to select a single file as the target of an operation.

OSStatus NavCreateChooseFileDialog (
   const NavDialogCreationOptions *inOptions,
   NavTypeListHandle inTypeList,
   NavEventUPP inEventProc,
   NavPreviewUPP inPreviewProc,
   NavObjectFilterUPP inFilterProc,
   void *inClientData,
   NavDialogRef *outDialog
);

Parameters
inOptions

A pointer to a structure specifying options that control the appearance and behavior of the dialog.

inTypeList

A structure specifying a creator signature and a list of file types to show in the Choose File dialog.

inEventProc

A Universal Procedure Pointer (UPP) to your application’s event-handling function. You are strongly advised to create and register an event-handling function, as described in NavEventProcPtr. You must have an event-handling function in order to create modeless or window-modal (sheet) dialogs. Specify NULL in this parameter if you do not implement an event-handling function.

inPreviewProc

A Universal Procedure Pointer (UPP) to your application’s preview function. You may specify NULL if you don’t need to register a preview function. For more information on preview functions, see NavPreviewProcPtr.

inFilterProc

A Universal Procedure Pointer (UPP) to your application’s filter function. You may specify NULL if you don’t need to register a filter function. For more information on filter functions, see NavObjectFilterProcPtr.

inClientData

A pointer to an application-defined value that is passed back to all callback functions. You can use this value to provide context information, for example. You may pass NULL in this parameter.

outDialog

On successful creation of a Choose File dialog, A pointer to a Navigation Services dialog reference that you can pass to the NavDialogRun function.

Return Value

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

Discussion

Once you have successfully created the Choose File dialog, you display it by calling the NavDialogRun function. After the user interacts with the dialog, you can obtain information about the dialog session by calling the NavDialogGetReply function. When you are finished with the dialog, you should dispose of it by calling the NavDialogDispose function.

This function replaces the NavChooseFile function and adds support for Unicode and new window modalities.

Availability
Declared In
Navigation.h

NavCreateChooseFolderDialog

Creates a Choose Folder dialog, which prompts the user to select a folder as the target of an operation.

OSStatus NavCreateChooseFolderDialog (
   const NavDialogCreationOptions *inOptions,
   NavEventUPP inEventProc,
   NavObjectFilterUPP inFilterProc,
   void *inClientData,
   NavDialogRef *outDialog
);

Parameters
inOptions

A pointer to a structure specifying options that control the appearance and behavior of the dialog.

inEventProc

A Universal Procedure Pointer (UPP) to your application’s event-handling function. You are strongly advised to create and register an event-handling function, as described in NavEventProcPtr. You must have an event-handling function in order to create modeless or window-modal (sheet) dialogs. Specify NULL in this parameter if you do not implement an event-handling function.

inFilterProc

A Universal Procedure Pointer (UPP) to your application’s filter function. You may specify NULL if you don’t need to register a filter function. For more information on filter functions, see NavObjectFilterProcPtr.

inClientData

A pointer to an application-defined value that is passed back to all callback functions. You can use this value to provide context information, for example. You may pass NULL in this parameter.

outDialog

On successful creation of a Choose Folder dialog, A pointer to a Navigation Services dialog reference that you can pass to the NavDialogRun function.

Return Value

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

Discussion

Once you have successfully created the Choose Folder dialog, you display it by calling the NavDialogRun function. After the user interacts with the dialog, you can obtain information about the dialog session by calling the NavDialogGetReply function. When you are finished with the dialog, you should dispose of it by calling the NavDialogDispose function.

This function replaces the NavChooseFolder function and adds support for Unicode and new window modalities.

Availability
Declared In
Navigation.h

NavCreateChooseObjectDialog

Creates a Choose Object dialog, which prompts the user to select a file. folder or volume.

OSStatus NavCreateChooseObjectDialog (
   const NavDialogCreationOptions *inOptions,
   NavEventUPP inEventProc,
   NavPreviewUPP inPreviewProc,
   NavObjectFilterUPP inFilterProc,
   void *inClientData,
   NavDialogRef *outDialog
);

Parameters
inOptions

A pointer to a structure specifying options that control the appearance and behavior of the dialog.

inEventProc

A Universal Procedure Pointer (UPP) to your application’s event-handling function. You are strongly advised to create and register an event-handling function, as described in NavEventProcPtr. You must have an event-handling function in order to create modeless or window-modal (sheet) dialogs. Specify NULL in this parameter if you do not implement an event-handling function.

inPreviewProc

A Universal Procedure Pointer (UPP) to your application’s preview function. You may specify NULL if you don’t need to register a preview function. For more information on preview functions, see NavPreviewProcPtr.

inFilterProc

A Universal Procedure Pointer (UPP) to your application’s filter function. You may specify NULL if you don’t need to register a filter function. For more information on filter functions, see NavObjectFilterProcPtr.

inClientData

A pointer to an application-defined value that is passed back to all callback functions. You can use this value to provide context information, for example. You may pass NULL in this parameter.

outDialog

On successful creation of a Choose Object dialog, a pointer to a Navigation Services dialog reference that you can pass to the NavDialogRun function.

Return Value

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

Discussion

Once you have successfully created the Choose Object dialog, you display it by calling the NavDialogRun function. After the user interacts with the dialog, you can obtain information about the dialog session by calling the NavDialogGetReply function. When you are finished with the dialog, you should dispose of it by calling the NavDialogDispose function.

This function replaces the NavChooseObject function and adds support for Unicode and new window modalities.

Availability
Declared In
Navigation.h

NavCreateChooseVolumeDialog

Creates a Choose Volume dialog, which prompts the user to select a volume.

OSStatus NavCreateChooseVolumeDialog (
   const NavDialogCreationOptions *inOptions,
   NavEventUPP inEventProc,
   NavObjectFilterUPP inFilterProc,
   void *inClientData,
   NavDialogRef *outDialog
);

Parameters
inOptions

A pointer to a structure specifying options that control the appearance and behavior of the dialog.

inEventProc

A Universal Procedure Pointer (UPP) to your application’s event-handling function. You are strongly advised to create and register an event-handling function, as described in NavEventProcPtr. You must have an event-handling function in order to create modeless or window-modal (sheet) dialogs. Specify NULL in this parameter if you do not implement an event-handling function.

inFilterProc

A Universal Procedure Pointer (UPP) to your application’s filter function. You may specify NULL if you don’t need to register a filter function. For more information on filter functions, see NavObjectFilterProcPtr.

inClientData

A pointer to an application-defined value that is passed back to all callback functions. You can use this value to provide context information, for example. You may pass NULL in this parameter.

outDialog

On successful creation of a Choose Volume dialog, A pointer to a Navigation Services dialog reference that you can pass to the NavDialogRun function.

Return Value

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

Discussion

Once you have successfully created the Choose Volume dialog, you display it by calling the NavDialogRun function. After the user interacts with the dialog, you can obtain information about the dialog session by calling the NavDialogGetReply function. When you are finished with the dialog, you should dispose of it by calling the NavDialogDispose function.

This function replaces the NavChooseVolume function and adds support for Unicode and new window modalities.

Availability
Declared In
Navigation.h

NavCreateGetFileDialog

Creates an Open dialog, which prompts the user to select a file or files to be opened.

OSStatus NavCreateGetFileDialog (
   const NavDialogCreationOptions *inOptions,
   NavTypeListHandle inTypeList,
   NavEventUPP inEventProc,
   NavPreviewUPP inPreviewProc,
   NavObjectFilterUPP inFilterProc,
   void *inClientData,
   NavDialogRef *outDialog
);

Parameters
inOptions

A pointer to a structure specifying options that control the appearance and behavior of the dialog.

inTypeList

A structure specifying an application signature and a list of file types to show in the Open dialog.

inEventProc

A Universal Procedure Pointer (UPP) to your application’s event-handling function. You are strongly advised to create and register an event-handling function, as described in NavEventProcPtr. You must have an event-handling function in order to create modeless or window-modal (sheet) dialogs. Specify NULL in this parameter if you do not implement an event-handling function.

inPreviewProc

A Universal Procedure Pointer (UPP) to your application’s preview function. You may specify NULL if you don’t need to register a preview function. For more information on creating a preview function, see NavPreviewProcPtr.

inFilterProc

A Universal Procedure Pointer (UPP) to your application’s filter function. You may specify NULL if you don’t need to register a filter function. For more information on creating a filter function, see NavObjectFilterProcPtr.

inClientData

A pointer to an application-defined value that is passed back to all callback functions. You can use this value to provide context information, for example. You may pass NULL in this parameter.

outDialog

On successful creation of an Open dialog instance, this value specifies a Navigation Services dialog reference that you can pass to the NavDialogRun function.

Return Value

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

Discussion

Once you have successfully created the Open dialog, you display it by calling the NavDialogRun function. After the user interacts with the dialog, you can obtain information about the dialog session by calling the NavDialogGetReply function. When you are finished with the dialog, you should dispose of it by calling the NavDialogDispose function.

This function replaces the NavGetFile function and adds support for Unicode and new window modalities.

Availability
Declared In
Navigation.h

NavCreateNewFolderDialog

Creates a New Folder dialog.

OSStatus NavCreateNewFolderDialog (
   const NavDialogCreationOptions *inOptions,
   NavEventUPP inEventProc,
   void *inClientData,
   NavDialogRef *outDialog
);

Parameters
inOptions

A pointer to a structure specifying options that control the appearance and behavior of the dialog.

inEventProc

A Universal Procedure Pointer (UPP) to your application’s event-handling function. You are strongly advised to create and register an event-handling function, as described in NavEventProcPtr. You must have an event-handling function in order to create modeless or window-modal (sheet) dialogs. Specify NULL in this parameter if you do not implement an event-handling function.

inClientData

A pointer to an application-defined value that is passed back to all callback functions. You can use this value to provide context information, for example. You may pass NULL in this parameter.

outDialog

On successful creation of a New Folder dialog, a pointer to a Navigation Services dialog reference that you can pass to the NavDialogRun function.

Return Value

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

Discussion

Once you have successfully created the New Folder dialog, you display it by calling the NavDialogRun function. After the user interacts with the dialog, you can obtain information about the dialog session by calling the NavDialogGetReply function. When you are finished with the dialog, you should dispose of it by calling the NavDialogDispose function

Use the New Folder dialog to allow the user to create a new folder. Navigation Services creates the folder as specified by the user and returns a reference to the folder in the selection field of the reply record.

This function replaces the NavNewFolder function and adds support for Unicode and new window modalities.

Availability
Declared In
Navigation.h

NavCreatePutFileDialog

Creates a Save dialog, which prompts the user for the name and location of a file to be saved.

OSStatus NavCreatePutFileDialog (
   const NavDialogCreationOptions *inOptions,
   OSType inFileType,
   OSType inFileCreator,
   NavEventUPP inEventProc,
   void *inClientData,
   NavDialogRef *outDialog
);

Parameters
inOptions

A pointer to a structure specifying options that control the appearance and behavior of the dialog.

inFileType

A four-character code specifying a file type for the file to be saved.

inFileCreator

A four-character code specifying a creator signature for the file to be saved. If you want to change or remove the top default item in the Format menu, pass kNavGenericSignature.

inEventProc

A Universal Procedure Pointer (UPP) to your application’s event-handling function. You are strongly advised to create and register an event-handling function, as described in NavEventProcPtr. You must have an event-handling function in order to create modeless or window-modal (sheet) dialogs. Specify NULL in this parameter if you do not implement an event-handling function.

inClientData

A pointer to an application-defined value that is passed back to all callback functions. You can use this value to provide context information, for example. You may pass NULL in this parameter.

outDialog

On successful creation of a Save dialog, a pointer to a Navigation Services dialog reference that you can pass to the NavDialogRun function.

Return Value

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

Discussion

Once you have successfully created the Save dialog, you display it by calling the NavDialogRun function. After the user interacts with the dialog, you can obtain information about the dialog session by calling the NavDialogGetReply function. When you are finished with the dialog, you should dispose of it by calling the NavDialogDispose function.

This function replaces the NavPutFile function and adds support for Unicode and new window modalities.

Availability
Declared In
Navigation.h

NavCustomControl

Allows your application to control various settings in Navigation Services dialogs.

OSErr NavCustomControl (
   NavDialogRef dialog,
   NavCustomControlMessage selector,
   void *parms
);

Parameters
dialog

A Navigation Services dialog reference. You can obtain this value from the context field of the structure of type NavCBRec specified in the callBackParms parameter of your event-handling function.

selector

A value of type NavCustomControlMessage. Pass one or more of the constants representing the possible values used to control various aspects of the active dialog. For a description of these constants, see “Custom Control Settings.”

parms

A pointer to a configuration value. Some of the control setting constants passed in the selector parameter require that you provide an additional configuration value. For a description of which constants require configuration values, see “Custom Control Settings.”

Return Value

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

Discussion

If you provide an event-handling function and an event occurs in a Navigation Services dialog, Navigation Services calls your event-handling function and specifies one of the constants described in “Event Messages” in the param field of a NavCBRec structure. Navigation Services specifies this structure in the callBackParms parameter of your event-handling function. When Navigation Services supplies the kNavCBStart constant in the param field, your application can call the NavCustomControl function and pass one of the constants described in “Custom Control Settings” to control various aspects of the active Navigation Services dialog. For example, your application can tell Navigation Services to sort the browser list by date by calling the NavCustomControl function and passing the kNavCtlSortBy constant in the selector parameter and a pointer to the kNavSortDateField configuration constant in the parms parameter. (Some of the NavCustomControlMessage constants do not require a corresponding configuration constant.)

Note that your application can call the NavCustomControl function from within its event-handling function or its preview-drawing function.

Special Considerations

Navigation Services does not accept calls to the NavCustomControl function until an appropriate dialog box is fully initialized and displayed. Always check for the kNavCBStart constant, described in “Event Messages,” in the param field of the NavCBRec structure before calling the NavCustomControl function.

Availability
Declared In
Navigation.h

NavDialogDispose

Disposes of a dialog reference.

void NavDialogDispose (
   NavDialogRef inDialog
);

Parameters
inDialog

A Navigation Services dialog reference previously obtained by your application.

Discussion

Use this function to dispose of a dialog reference when you are completely finished with its associated dialog. You may call NavDialogDispose from within your application-defined event-handling function.

Availability
Declared In
Navigation.h

NavDialogGetReply

Reports the results of a dialog session (unless cancelled or programmatically terminated).

OSStatus NavDialogGetReply (
   NavDialogRef inDialog,
   NavReplyRecord *outReply
);

Parameters
inDialog

A reference to a previously created dialog.

outReply

A pointer to a reply record you allocate to be filled out by Navigation Services.

Return Value

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

Discussion

Call this function when you obtain a value other than kNavUserActionCancel or kNavUserActionNone from the NavDialogGetUserAction function. Upon completion of the NavDialogGetReply function, Navigation Services fills out the specified reply record with information about the dialog session. When you are finished with the reply record, remember to dispose of it by calling the NavDisposeReply function.

Availability
Declared In
Navigation.h

NavDialogGetSaveFileExtensionHidden

Gets the current state of extension hiding in a Save dialog.

Boolean NavDialogGetSaveFileExtensionHidden (
   NavDialogRef inPutFileDialog
);

Parameters
inPutFileDialog

A reference to the Save dialog. You can create a Save dialog using the NavCreatePutFileDialog function.

Return Value

True if the extension is hidden; false if the extension is visible or if there is no extension.

Discussion

This function can be called at any time to determine if a Save dialog is hiding the file extension—if any—of the file to be saved.

Availability
Declared In
Navigation.h

NavDialogGetSaveFileName

Obtains the current value of the filename text field in a Save dialog.

CFStringRef NavDialogGetSaveFileName (
   NavDialogRef inPutFileDialog
);

Parameters
inPutFileDialog

A reference to a previously created dialog.

Return Value

A reference to the string containing the save filename. You should retain this string reference if you need the information after the dialog is dismissed. On Mac OS X, the full filename is returned, including any extension that may be hidden from the user. See the CFString documentation for a description of the CFStringRef data type.

Discussion

This function provides a Unicode-based replacement for using the kNavGetEditFileName selector with the NavCustomControl function.

Special Considerations

Note that you cannot use NavDialogGetSaveFileName with a Save dialog created using the NavPutFile function. You should instead create your Save dialog using the NavCreatePutFileDialog function.

Availability
Declared In
Navigation.h

NavDialogGetUserAction

Reports the user action taken to dismiss a dialog.

NavUserAction NavDialogGetUserAction (
   NavDialogRef inDialog
);

Parameters
inDialog

A reference to a previously created dialog.

Return Value

One of the constants defined by the NavUserAction enumeration. This value indicates the user action that dismissed the dialog. See “User Actions” for a description of the values that may be returned here.

Discussion

If the dialog has not been dismissed or if the dialog was terminated by using the kNavCtlTerminate selector with the NavCustomControl function, the NavDialogGetUserAction function returns the kNavUserActionNone constant. When you obtain a value other than kNavUserActionCancel or kNavUserActionNone after returning from a file-handling dialog, Navigation Services fills out a reply record that you can obtain with the NavDialogGetReply function.

Availability
Declared In
Navigation.h

NavDialogGetWindow

Obtains a window reference for a dialog.

WindowRef NavDialogGetWindow (
   NavDialogRef inDialog
);

Parameters
inDialog

A reference to a previously created dialog.

Return Value

A window reference for the specified dialog. Note that a valid dialog reference may not have a window associated with it until the NavDialogRun function is called. If no window is associated with the specified dialog, the NavDialogGetWindow function returns NULL.

Availability
Declared In
Navigation.h

NavDialogRun

Displays a previously created dialog.

OSStatus NavDialogRun (
   NavDialogRef inDialog
);

Parameters
inDialog

A reference to a previously created Navigation Services dialog.

Return Value

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

Discussion

You must create a dialog before displaying it. To create a dialog, call one of the NavCreate...Dialog functions described in “Choosing Files, Folders and Volumes” and “Saving Files.” If you specify an application-modal or system-modal dialog, the NavDialogRun function returns after the dialog is dismissed. If you specify a window-modal dialog (sheet) or a modeless dialog, the NavDialogRun function returns immediately; in order to know when the dialog has been dismissed, you must supply an event-handling function and watch for the kNavCBUserAction event.

After the user interacts with the dialog, you can obtain information about the dialog session by calling the NavDialogGetReply function.

Version Notes

On Mac OS 9 and earlier, all Navigation Services dialogs are modal, even if a window-modal or modeless dialog is requested. However, the kNavCBUserAction event is still sent to your event-handling function. It is possible to use a single programming model on both Mac OS 9 and on Mac OS X, provided you assume that the NavDialogRun function returns immediately after displaying the dialog.

Availability
Declared In
Navigation.h

NavDialogSetFilterTypeIdentifiers

Sets UTI filtering criteria for “get file” and “choose file” dialogs. 

OSStatus NavDialogSetFilterTypeIdentifiers (
   NavDialogRef inGetFileDialog,
   CFArrayRef inTypeIdentifiers
);

Parameters
inGetFileDialog

A Navigation Services dialog reference obtained from calling NavCreateChooseFileDialog or NavCreateGetFileDialog.

inTypeIdentifiers

A Core Foundation array of uniform type identifiers. This array specifies the file types that you want your dialog to enable. If you pass an empty array, all files are filtered (and will appear dimmed in the dialog). If you pass NULL, all files are enabled.

The file types you specify here also appear in the popup menu (displayed using the localized name associated with the UTI), allowing the user to filter by a specific file type. The “All readable documents” selection displays all the types specified in the UTI array.

Return Value

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

Discussion

For simple filtering by file type, you should use this function instead of writing a custom filter callback function. However, you can also use this call in conjunction with a filter callback; your custom filter callback is called after NavDialogSetFilterTypeIdentifiers performs the initial filtering.

This function supersedes the list of OSType values you can pass in the inTypeList parameter in dialog creation functions.

You can call this function at any time, even while the dialog is displayed. For example, say your dialog contained a custom menu item to filter by a specific type. When the user selects your menu item, you could call NavDialogSetFilterTypeIdentifiers with the UTI corresponding to that type, and the dialog will automatically update with the new filtering criteria.

For more information about uniform type identifiers, see Uniform Type Identifiers Overview

Availability
Declared In
Navigation.h

NavDialogSetSaveFileExtensionHidden

Sets the current state of extension hiding in a Save dialog.

OSStatus NavDialogSetSaveFileExtensionHidden (
   NavDialogRef inPutFileDialog,
   Boolean inHidden
);

Parameters
inPutFileDialog

A reference to the Save dialog. You can create a Save dialog using the NavCreatePutFileDialog function.

inHidden

A Boolean value indicating whether the file extension should be hidden. Pass true to hide the file extension; false to make any extension visible.

Return Value

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

Discussion

This function can be called at any time to hide or show the extension of the file to be saved in a Save dialog. If the current filename has no extension, hiding the extension has no effect.

Availability
Declared In
Navigation.h

NavDialogSetSaveFileName

Specifies the current value of the filename text field in a Save dialog.

OSStatus NavDialogSetSaveFileName (
   NavDialogRef inPutFileDialog,
   CFStringRef inFileName
);

Parameters
inPutFileDialog

A reference to a previously created dialog.

inFileName

The filename to specify.

Return Value

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

Discussion

This function may be called at any time to set the current filename for a save operation. You may use it to set an initial filename before calling NavDialogRun, or to change the filename dynamically while a dialog is running.

This function provides a Unicode-based replacement for using the kNavSetEditFileName selector with the NavCustomControl function.

Special Considerations

Note that you cannot use NavDialogSetSaveFileName with a Save dialog created using the NavPutFile function. You should instead create your Save dialog using the NavCreatePutFileDialog function.

Availability
Declared In
Navigation.h

NavDisposeReply

Releases the memory allocated for a NavReplyRecord structure after your application has finished using the structure.

OSErr NavDisposeReply (
   NavReplyRecord *reply
);

Parameters
reply

A pointer to a structure of type NavReplyRecord that your application has created.

Return Value

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

Discussion

If your application calls a Navigation Services function that uses a structure of type NavReplyRecord, you must use the NavDisposeReply function afterward to release the memory allotted for the NavReplyRecord structure.

Availability
Declared In
Navigation.h

NavGetDefaultDialogCreationOptions

Determines the default attributes or behavior for dialogs. 

OSStatus NavGetDefaultDialogCreationOptions (
   NavDialogCreationOptions *outOptions
);

Parameters
outOptions

A pointer to a NavDialogCreationOptions structure that you provide. On return, Navigation Services fills out the structure with default dialog configuration values.

Return Value

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

Discussion

This function gives you a simple way to initialize a NavDialogCreationOptions structure and set default options before creating a Navigation Services dialog. After you create the NavDialogCreationOptions structure, you can change the configuration options before you call one of the dialog creation functions.

Availability
Declared In
Navigation.h

NavLoad

Pre-loads the Navigation Services shared library.

Unsupported

OSErr NavLoad (
   void
);

Return Value

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

Discussion

Use this function to pre-load the Navigation Services library. Pre-loading increases the memory used by your application, but it provides the best performance when using Navigation Services functions. If you don’t use the NavLoad function, the Navigation Services shared library may not be loaded until your application calls one of the Navigation Services functions. If you use the NavLoad function, you must call the function NavUnload if you want to release reserved memory prior to quitting.

Availability
Declared In
Navigation.h

NavServicesAvailable

Reports whether the Navigation Services library is available on the user’s system.

pascal Boolean NavServicesAvailable

Return Value

A Boolean value. This function returns true if Navigation Services is available, false if not.

Discussion

Use this function before attempting to use Navigation Services on Mac OS 8 and Mac OS 9. It is not necessary to call this function on Mac OS X, as Navigation Services is always available.

Special Considerations

There is a known problem with Navigation Services 1.0 that occurs if you call NavServicesAvailable more than once without the Appearance Manager being installed. Make sure that you check for the presence of the Appearance Manager before calling NavServicesAvailable.

Version Notes

Available in Navigation Services 1.0 and later.

Availability
Declared In
Navigation.h

NavServicesCanRun

Unsupported

Boolean NavServicesCanRun (
   void
);

Availability
Declared In
Navigation.h

NavUnload

Unloads the Navigation Services shared library.

Unsupported

OSErr NavUnload (
   void
);

Return Value

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

Discussion

This function allows your application to unload the Navigation Services library and release the memory reserved for it. If you use the function NavLoad to load the Navigation Services library, you must call the NavUnload function if you want to release reserved memory prior to quitting.

Availability
Declared In
Navigation.h

NewNavEventUPP

Creates a new universal procedure pointer to your application-defined event–handling function.

NavEventUPP NewNavEventUPP (
   NavEventProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your event–handling function.

Return Value

On return, a universal procedure pointer (UPP) to the event–handling function. See the description of the NavEventUPP data type.

Availability
Declared In
Navigation.h

NewNavObjectFilterUPP

Creates a new universal procedure pointer to your application-defined filter function.

NavObjectFilterUPP NewNavObjectFilterUPP (
   NavObjectFilterProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your filter function.

Return Value

On return, a universal procedure pointer (UPP) to the filter function. See the description of the NavObjectFilterUPP data type.

Availability
Declared In
Navigation.h

NewNavPreviewUPP

Creates a new universal procedure pointer to your application-defined preview function.

NavPreviewUPP NewNavPreviewUPP (
   NavPreviewProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your preview function.

Return Value

On return, a universal procedure pointer (UPP) to the preview function. See the description of the NavPreviewUPP data type.

Availability
Declared In
Navigation.h

Callbacks

NavEventProcPtr

A pointer to an event-handling function that handles events such as window updating and resizing.

typedef void (*NavEventProcPtr) (
   NavEventCallbackMessage callBackSelector,
   NavCBRecPtr callBackParms,
   void * callBackUD);

If you name your function MyNavEventProc, you would declare it like this:

void MyNavEventProc (
   NavEventCallbackMessage callBackSelector,
   NavCBRecPtr callBackParms,
   void * callBackUD);

Parameters
callBackSelector

One of the values specified by the NavEventCallbackMessage data type. These values indicate which type of event your function must respond to. For a description of the constants that represent these values, see “Event Messages.”

callBackParms

A pointer to a NavCBRec structure. Your application uses the data supplied in this structure to process the event.

callBackUD

A pointer to a value set by your application when it calls a Navigation Services dialog creation function. When Navigation Services calls your event-handling function, the callBackUD value is passed back to your application in this parameter.

Discussion

Register your event-handling function by passing a Universal Procedure Pointer (UPP) in the eventProc parameter of a Navigation Services dialog creation function. You obtain this UPP by calling the function NewNavEventUPP and passing a pointer to your event-handling function. If you determine that an event is appropriate for your event-handling function, you can call other functions to handle custom control drawing.

When events involve controls, your event-handling function must respond to events only for your application-defined c