Retired Document
Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
Navigation Services for Carbon
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. Navigation Services is provided as a Carbon-compliant replacement for and enhancement to the Standard File Package, which was introduced with the original Macintosh System. Navigation Services is available on Mac OS 8.6 and later, including Mac OS X.
The enhanced functionality of Navigation Services is easy to adopt. Functions are simple and flexible; they are designed to help you avoid writing custom code. Navigation Services also provides automatic support for the Appearance Manager’s extended suite of dialogs, alerts, and user controls to ensure a more consistent and comprehensible user interface across applications.
File Browsing: Then and Now
Prior to Navigation Services, Mac OS file browsing was often confusing to users as a result of the differences between Standard File Package dialogs and the Finder’s file interface. Also, users were faced with navigation much larger volumes than those which existed when the Standard File Package was developed. These large data spaces require extended functionality, so Navigation Services provides tools for you to implement a greatly enhanced user experience in the area of document management.
One enhancement is the ability for users to select and open multiple files simultaneously. There are buttons that let users easily select local or remote storage volumes, choose recently opened files and folders, or build their own list of favorite items. You can take advantage of translation services offered by the Translation Manager to give users more ways to open and save files. Navigation Services also lets you opt for deferred translation, which gives your application the ability to save interim changes in a file’s native format and avoid the time-consuming task of translation until the user closes the document.
Navigation Services for Carbon
Navigation Services 3.0, introduced with CarbonLib 1.1, 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. Figure 1-1
shows a flowchart that descries one way to use this model to provide file-opening services.

This approach involves five-steps:
Create a dialog with the features you need. In the example shown in
Figure 1-1
, you call theNavGetDefaultDialogCreationOptions
function to set up default options and theNavCreateGetFileDialog
function to create the Open File dialog.Display the dialog by calling the
NavDialogRun
function.Respond when Navigation Services supplies an event message constant in the callback record. In
Figure 1-1
, this is thekNavCBUserAction
constant. If you implement custom features, you may need to call theNavCutsomControl
function at this time.After the dialog closes, process the dialog session information from the reply record you obtain by calling the
NavDialogGetReply
function. For example, if you obtain thekNavUserActionOpen
constant from the reply record, your application opens the appropriate files.Dispose of the dialog reference and the reply record when you have finished using them, by calling the function
NavDialogDispose
and the functionNavDisploseReply
, respectively.
See Also
Navigation Services Reference in Carbon User Experience Documentation provides a complete reference for the Navigation Services application programming interface.
Technical Q&A QA1315, “Why Isn't My Edit Text Box in My Navigation Dialog's Custom Area Working on 10.3?”
Technical Q&A QA1152, “Using Navigation Services to Filter QuickTime Files.”
Copyright © 2000, 2003 Apple Computer, Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2003-12-10