TweetFollow Us on Twitter

Using Navigation Services

Volume Number: 14 (1998)
Issue Number: 8
Column Tag: Emerging Technologies

Using Navigation Services

by Keith Mortensen
Edited by the MacTech Magazine Editorial Staff

Every Macintosh programmer knows you can't write an application without going through the experience of using the StandardFile package. One discovers almost immediately the limitations and constraints of StandardFile, and begins to realize the standard dialogs don't support the features most developers need. Thus, adding your own features by customizing them is the only alternative.

If you have had to customize any of the StandardFile dialogs, can you remember your first dialog hook function? Have you wondered what "pseudo items" meant? Do you remember "copying" the System file's 'DLOG' and 'DITL' resources (ID -6042) to make your very own open dialog? How about the feelings of uncertainty when "changing" these resources? Have you resorted to writing a filter callback procedure just because the SFTypeList holds no more than 4 file types?

Over the years your applications have changed, but those StandardFile dialogs haven't. I'm glad to say those days are over. In this article we will introduce the tools of Apple's successor to the StandardFile package -- Navigation Services.

Figure 1. The Open Dialog.

Meet Navigation Services, a new set of tools for document management. It hosts a suite of "utility dialogs" for opening and saving documents, choosing volumes, choosing and creating folders. More additional standard alerts are also provided to free you from having to design your own.

Navigation Services provides a set of navigation tools for the user, including:

  • Shortcuts - for quick access to mounted volumes and other desktop items.
  • Favorites - for easy navigation to frequently used items.
  • Recent - to provide a history of the users work.
  • Browser List - a hierarchical Finder-like view of the file system.

Figure 2. Shortcuts, Favorites and Recent menus.

There are several areas where Navigation Services provides "memory assistance" to improve the user experience. Each time you open a document, it will remember: your last location, what you last opened, where the dialog box was displayed on your screen, the dimensions of the dialog box, and the browser's sort key and sort order. It also remembers the selection for every folder or container you visit. More importantly, this persistence is on a per-application and per-dialog basis. Thus, an Open dialog's position and size for a word processor application may be different than of a spreadsheet application.

Navigation Services even gives you automatic built-in translation of your documents. If SimpleText were to use Navigation Services, it would be capable of opening any document that can be translated into text, picture, or movie formats. Lastly, it also gives you the capabilities to add your own interface to these utility dialogs through a well-defined system in tune with the over-all user interface.

A Navigation Services "Savvy" Application

We will be going through the process of making your application Navigation Services "savvy" by studying some simple code examples. They are designed to make the transition quick and painless. You needn't worry about how your application is built. The interface can be accessed using 68K, CFM-68K and PowerPC code. This gives you the flexibility to adapt and remain compatible to a wider variety of systems. By calling NavServicesAvailable, you can determine if Navigation Services is installed and ready to run.


The first call I recommend using is NavGetFile, a fully featured "get" dialog of Navigation Services. Here you will find most of the features you need. The following example shows how to use NavGetFile for opening multiple documents.

OSErr OpenDocument( )
   OSErr                theErr = noErr;
   NavReplyRecord       theReply;
   NavDialogOptions     dialogOptions;   
   long                 count;
   NavTypeListHandle    openTypeList = NULL;
   NavEventUPP          eventProc =
                           NewNavEventProc( myEventProc );
   NavObjectFilterUPP   filterProc =
                              NewNavObjectFilterProc( myFilterProc );
   // default behavior for browser and dialog:
   theErr = NavGetDefaultDialogOptions( &dialogOptions );

   // setup our NavTypeList for filtering:
   openTypeList = (NavTypeListHandle)GetResource('open', 128);

   theErr = NavGetFile(    NULL, &theReply, &dialogOptions, 
                                 eventProc, NULL, filterProc,
                                 openTypeList, NULL );
   if ( theReply.validRecord && theErr == noErr )
      FSSpec           finalFSSpec;   
      AEDesc           resultDesc;
      AEKeyword        keyWord;
      if ( theErr == noErr )
         // we are ready to open the document(s), grab
         // information about each file for opening:
         if ((theErr = AECountItems( &(theReply.selection), 
                              &count )) == noErr)
            for (long index=1;index<=count;index++)
               if ((theErr = AEGetNthDesc( &(theReply.selection), 
                     index,typeFSS,&keyWord,&resultDesc)) == noErr)
                  BlockMoveData( *resultDesc.dataHandle, 
                               &finalFSSpec, sizeof(FSSpec) ); 
                  if ((theErr = DoOpenFile(&finalFSSpec))== noErr)
                  theErr = AEDisposeDesc( &resultDesc );
      theErr = NavDisposeReply( &theReply );

   DisposeRoutineDescriptor( filterProc );
   DisposeRoutineDescriptor( eventProc );   
   if (openTypeList != NULL)
      ReleaseResource( (Handle)openTypeList );
   return theErr;

Opening Documents with AppleEvents

Navigation Services returns in the selection field of the NavReplyRecord an AEDescList or AppleEvent Descriptor List. It contains one or more items to be opened. To open the documents, one nifty technique is to send to your application an 'odoc' AppleEvent with the items found in this list. This method saves you from having to deal with AppleEvent Descriptors. Use your AppleEvent handler to perform the open, as if you received the AppleEvent from the Finder.

theErr = SendOpenAE(theReply.selection);

static OSStatus SendOpenAE(AEDescList list)
   OSStatus        err;
   AEAddressDesc   theAddress;
   AppleEvent      dummyReply, theEvent;
   theAddress.descriptorType   = typeNull;
   theAddress.dataHandle   = NULL;

   do {
      ProcessSerialNumber psn;
      err = GetCurrentProcess(&psn);
      if ( err != noErr) break;
      err = AECreateDesc(typeProcessSerialNumber, &psn, 
                   sizeof(ProcessSerialNumber), &theAddress);
      if ( err != noErr) break;
      dummyReply.descriptorType   = typeNull;
      dummyReply.dataHandle   = NULL;

      err = AECreateAppleEvent(kCoreEventClass, 
                   kAEOpenDocuments, &theAddress,
                   kAutoGenerateReturnID, kAnyTransactionID,
      if ( err != noErr) break;
      err = AEPutParamDesc(&theEvent, keyDirectObject, &list);
      if ( err != noErr) break;
      err = AESend(&theEvent, &dummyReply, kAEWaitReply, 
                   kAENormalPriority, kAEDefaultTimeout,
                   NULL, NULL);
      if ( err != noErr) break;         
   } while (false);
   return err;


Programming the save dialog is similar to using NavGetFile with two additions: you provide a "suggested" saved file name and file format. Once you are done with NavPutFile, call NavCompleteSave to perform translation of the saved document in case the user chose a different save format than your own. It is important you call NavCompleteSave, as this call will provide more "save" features in future versions. The next example shows how to use NavPutFile. No object filtering is necessary and the Favorites and Recent menus will show only containers.

Figure 3. The Save Dialog.

OSErr SaveDocument(WindowPtr theDocument)
   OSErr              theErr = noErr;
   NavReplyRecord     theReply;
   NavDialogOptions   dialogOptions;
   OSType             fileTypeToSave = 'TEXT';
   OSType             creatorType = 'xAPP';
   NavEventUPP        eventProc = NewNavEventProc(myEventProc);
   // default behavior for browser and dialog:
   theErr = NavGetDefaultDialogOptions( &dialogOptions );

   GetWTitle( theDocument, dialogOptions.savedFileName );

   theErr = NavPutFile( NULL, &theReply, &dialogOptions, 
                  eventProc, fileTypeToSave, creatorType, NULL );

   if (theReply.validRecord && theErr == noErr)
      FSSpec         finalFSSpec;   
      AEDesc         resultDesc;   
      AEKeyword      keyWord;

      // retrieve the returned selection:
      if (( theErr = AEGetNthDesc( &(theReply.selection), 1, 
                     typeFSS, &keyWord, &resultDesc )) == noErr )
         BlockMoveData( *resultDesc.dataHandle, &finalFSSpec, 
                      sizeof(FSSpec) );
         if (theReply.replacing)
            theErr = FSpDelete( &finalFSSpec );   
         if ( theErr == noErr )
            if (( theErr = FSpCreate( &finalFSSpec, creatorType, 
                     fileTypeToSave, smSystemScript )) == noErr )
               if (( theErr = WriteNewFile(&finalFSSpec))==noErr)
                  theErr = NavCompleteSave( &theReply, 
         AEDisposeDesc( &resultDesc );
      theErr = NavDisposeReply( &theReply );
   DisposeRoutineDescriptor( eventProc );
   return theErr;

Dialog and Browser Options

A wide variety of features and options to change the look and behavior of the interface are available by setting up a NavDialogOptions structure:

struct NavDialogOptions {
   UInt16    version;
   NavDialogOptionFlags    dialogOptionFlags; // dialog/browser options
   Point       location;          // the dialog's screen coordinates
   Str255    clientName;          // your program's name
   Str255    windowTitle;         // a complete window title
   Str255    actionButtonLabel;   // the action button's text
   Str255    cancelButtonLabel;   // the cancel button's text
   Str255    savedFileName;       // for NavPutFile, the default file name
   Str255    message;             // the banner or prompt message string
   UInt32    preferenceKey;   // unique value used to map to set of preferences
   Handle    popupExtension;      // client's added popupMenu items
typedef struct NavDialogOptions NavDialogOptions;

enum {
   kNavDefaultNavDlogOptions   = 0x000000E4,   
                                // the default features
   kNavNoTypePopup = 0x00000001,
                                // turn off using the type popup menu
   kNavDontAutoTranslate   = 0x00000002,    
                                // do not automatically translate documents
   kNavDontAddTranslateItems   = 0x00000004,    
                                // add translated types to type popup menu
   kNavAllFilesInPopup   = 0x00000010,    
                                // add "All Documents" to type popup
   kNavAllowStationery = 0x00000020,
                                // add Stationery menu option to type popup
   kNavAllowPreviews = 0x00000040,    
                                // use the Previews option for documents
   kNavAllowMultipleFiles = 0x00000080,    
                                // browser selects and returns multiple objects
   kNavAllowInvisibleFiles = 0x00000100,    
                                // browser showss invisible objects
   kNavDontResolveAliases = 0x00000200,    
                                // don't resolve aliases, return the alise file
   kNavSelectDefaultLocation = 0x00000400,   
                                // select the default location
   kNavSelectAllReadableItem = 0x00000800
                                // select "All Readable Documents"

typedef UInt32 NavDialogOptionFlags;

You can easily setup this structure to use the default settings by calling NavGetDefaultDialogOptions. It is better to call this routine anyway since it initializes the structure automatically for you. Then you can turn on or off particular features by adding or subtracting option flags.

Filtering Objects

Navigation Services does "object filtering" to determine what objects to display in the Recent Documents list, Favorites list, and the browser list. Your application has two ways of filtering objects. One method is to use a filter callback procedure. A simpler way is to use a NavTypeList structure. This data structure is identical to the 'open' resource format defined by the Translation Manager. It contains the clients creator, and a list of OSTypes which represent the file types your application can open.

By using a filter callback procedure and/or NavTypeList structure, clients can filter out unwanted file objects from the interface. You can directly filter any object, including files, folders, volumes, aliases, etc. You can use both the NavTypeList and filter callback procedure if you wish. Both are designed to work together. For example, if the NavTypeList contains TEXT and PICT types, only TEXT and PICT files will be passed into your filter callback procedure.

pascal Boolean myFilterProc(    AEDesc* theItem, void* info, 
                                NavCallBackUserData callBackUD, 
                                NavFilterModes filterMode)
   OSErr       theErr = noErr;
   Boolean    display = true;
   NavFileOrFolderInfo* theInfo = (NavFileOrFolderInfo*)info;
   if ( theItem->descriptorType == typeFSS )
      if ( !theInfo->isFolder )
         if (   theInfo->
            display = false;
   return display;

Handling Events

An event callback routine is used by your application to respond to events. Events can be Mac OS or Navigation Services events. By providing an event callback routine, you can keep your application's windows updated, handle idle events as well as communicate and interact with Navigation Services. For example, to respond to operating system events check for the kNavCBEvent message. This is one of a set of useful event messages defined in the API. Each message yields different data used for a particular event. The following shows the NavCBRec structure used in handling events:

struct NavCBRec {
   UInt16       version;
   NavContext context;          // used to refer to Navigation Services
   WindowPtr    window;         // the Navigation dialog
   Rect          customRect;    // coordinate rectangle of customization area
   Rect          previewRect;   // coordinate rectangle of the preview area
   NavEventDataInfo    eventData; // event info to examine/interpret events
   char          reserved[226];

pascal void myEventProc(    NavEventCallbackMessage 
                                  NavCBRecPtr callBackParms, 
                                  NavCallBackUserData callBackUD )
   WindowPtr pWindow = (WindowPtr)callBackParms->
   myApp* curApp = (myApp*)callBackUD;      // context to ourselves
   switch ( callBackSelector )
      case kNavCBEvent:
         switch ( callBackParms->eventData.event->what )
         case updateEvt:

Customizing the Dialogs

Throughout the years, StandardFile has been heavily customized in almost every piece of software. As a result, the user experience is often inconsistent and confusing. Up until now, most of us have learned the behaviors of StandardFile, and we all have become used to them. As a result, Apple gets stuck with the difficulties of trying to advance the human interface without breaking current applications.

Navigation Services provides a number of calls and options which address needs in the past that required customization of the StandardFile dialogs. By using the features of this API, you will not have to customize the dialogs in a manner that will cause incompatibilities with future versions of Navigation Services. The need to change the Navigation Services dialogs, however, is greatly reduced.

The example in Figure 4 is how Sampler, an example application included with the Navigation Services SDK, customizes NavGetFile. It adds a "Commands" popup menu control. Sampler is responsible for allocating any controls and responding to mouseDown and keyDown events.

Figure 4. An example of dialog customization.

Dialog Space Negotiations

If you need to add your own interface you will need to negotiate a customization space by responding to this kNavCBCustomize event. The callBackParms->customRect field describes the custom area in local coordinates anchored to the lower left of the dialog's type popup or its browser. If you want to customize the dialog, you must complete the dimensions of the rectangular area by responding to kNavCBCustomize in your event callback procedure. Complete the dimensions in callBackParms->customRect for your custom area.

The following example is in response to kNavCBCustomize and shows you how to tell Navigation Services the space you need. Agreeing upon the customized space is like a round of negotiations between you and Navigation Services, coming up with an amount of space both of you can agree upon. Once you are satisfied with the given size, exit your event callback procedure with the same custom area. This will tell Navigation Services that an agreement has been made. The minimum guaranteed space is 402 pixels wide by 40 pixels high. The next example shows you how to complete the area for customization:

// here are the desired dimensions for our custom area:
short neededWidth =
            callBackParms->customRect.left + kCustomWidth;
short neededHeight =
            callBackParms-> + kCustomHeight;
// check to see if this is the first round of negotiations:
if (( callBackParms->customRect.right == 0) && 
         (callBackParms->customRect.bottom == 0 ))
   // it is, so tell NavServices what dimensions we want:
   callBackParms->customRect.right = neededWidth;
   callBackParms->customRect.bottom = neededHeight;
   // we are in the middle of negotiating:
   if ( globals->gLastTryWidth !=
            callBackParms->customRect.right )
      if ( callBackParms->customRect.right < neededWidth )   
         // is the given width too small for us?
         callBackParms->customRect.right = neededWidth;

   // is the given height too small for us?
   if ( globals->gLastTryHeight != 
         callBackParms->customRect.bottom )
      if ( callBackParms->customRect.bottom < neededHeight )
         callBackParms->customRect.bottom = neededHeight;
// remember our last size so the next time we can re-negotiate:
globals->gLastTryWidth = callBackParms->customRect.right;
globals->gLastTryHeight = callBackParms->customRect.bottom;

Sending "Nav" Commands

If you supply an event callback routine, you can in turn "call back" to Navigation Services to control the dialog and its browser. You can do this by calling NavCustomControl. NavCustomControl accepts a "context" or reference to Navigation Services which is provided by the NavCBRec, when the client's event routine is called. Its selector field determines the type of control call being made, and a generic pointer is used to convey parameter data. Using a set of custom control messages you can control the dialog and browser in various ways. Below are some examples of how to use NavCustomControl:

Str255 fileName;
theErr = NavCustomControl(callBackParms>context,

Str255 newFolderName = "\puntitled folder";
theErr = NavCustomControl(callBackParms->context,

theErr = NavCustomControl(callBackParms->context,

The following is a list of commands or NavCustomControlMessages you can send to Navigation Services. These commands can be used in your event or preview callback procedures, where appropriate. The arrows illustrate how data is passed to and from NavCustomControl.

enum {
   kNavCtlShowDesktop   = 0,     // show desktop, parms = nil
   kNavCtlSortBy = 1,            // sort key field, parms->NavSortKeyField
   kNavCtlSortOrder = 2,         // sort order,parms->NavSortOrder
   kNavCtlScrollHome    = 3,     // scroll list home, parms = nil
   kNavCtlScrollEnd = 4,         // scroll list end, parms = nil
   kNavCtlPageUp = 5,            // page list up, parms = nil
   kNavCtlPageDown = 6,          // page list down, parms = nil
   kNavCtlGetLocation = 7,       // get current location, parms<-AEDesc
   kNavCtlSetLocation = 8,       // set current location, parms->AEDesc
   kNavCtlGetSelection   = 9,    // get current selection, parms<-AEDescList
   kNavCtlSetSelection   = 10,   // set current selection, parms->AEDescList
   kNavCtlShowSelection   = 11,  // make selection visible, parms = nil
   kNavCtlOpenSelection   = 12,  // open view of selection, parms = nil
   kNavCtlEjectVolume = 13,      // eject volume, parms->vRefNum
   kNavCtlNewFolder = 14,        // create a new folder, parms->StringPtr
   kNavCtlCancel = 15,           // cancel dialog, parms = nil
   kNavCtlAccept = 16,           // accept dialog default, parms = nil
   kNavCtlIsPreviewShowing   = 17, // get preview status, parms<-Boolean
   kNavCtlAddControl   = 18,     // add one control, parms->ControlHandle
   kNavCtlAddControlList   = 19, // add control list, parms->Handle (DITL)
   kNavCtlGetFirstControlID = 20, // get 1st control ID, parms<-UInt16
   kNavCtlSelectCustomType   = 21,
                  // select custom menu item. parms->NavMenuItemSpec
   kNavCtlSelectAllType = 22,
                  // select an "All" menu item, parms->SInt16
   kNavCtlGetEditFileName = 23,
                  // get save dialog's file name, parms<-StringPtr
   kNavCtlSetEditFileName = 24
                  // set save dialog's file name, parms->StringPtr
typedef SInt32 NavCustomControlMessage;

Adding Your Controls

After the kNavCBCustomize message has been processed, your own interface elements can be added to any dialog after you receive the kNavCBStart message. The easiest way to set this up is to create a 'DITL' resource (in local coordinates relative to the customization area). Use the next example for this purpose:

gDitlList = GetResource ( 'DITL', 3000 );
theErr = NavCustomControl ( callBackParms->context, 

Then, when the dialog is being closed, respond to the kNavCBTerminate event message by disposing of this resource. Of course, a 'DITL' resource is not the only method. You can call NewControl and then send the ControlHandle to Navigation Services by using the next example. Likewise with a ControlHandle, be sure to dispose of it after receiving the kNavCBTerminate event message.

gCustomControl = NewControl( callBackParms->window, 
                 &itemRect, "\pcheckbox", false, 
                 1, 0, 1, checkBoxProc, NULL );
theErr = NavCustomControl( callBackParms->context, 

Handling Your Controls

To work with your controls, use your event callback procedure to respond to mouseDown events. You can use the Dialog Manager to find out which one of your controls was clicked but you must use a designated offset to map the Dialog Manager's control ID to your custom controls. The next example shows how to respond to a mouseDown event:

void HandleCustomMouseDown( NavCBRecPtr callBackParms )
   OSErr           theErr = noErr;
   ControlHandle   whichControl;            
   Point           curMousePt;   
   short           theItem = 0;   
   UInt16          firstItem = 0;
   short           realItem = 0;
   SInt16          partResult = 0;
   GetMouse( &curMousePt );

   // find the control's item number:
   theItem = FindDialogItem( callBackParms->window, 
   // find the control itself:
   whichControl = FindControlUnderMouse(curMousePt, 
                              callBackParms->window, &partResult );
   if ( whichControl != NULL && partResult != 0 )
      // get the item number of the control 
      theErr = NavCustomControl( callBackParms->context,       
                              kNavCtlGetFirstControlID, &firstItem );   
      // map it to our DITL constants:
      realItem = theItem - firstItem + 1;   
      // finally handle your control:
      switch ( realItem )

Drawing Previews

Navigation Services gives you built in preview support for common preview types by using QuickTime's Preview components. These components are also used by the Image Compression Manager. If, however, you introduce new special file types to preview different types of data, you may want override the appearance of how file previews are displayed. To implement your own previews, set the kAllowPreviews flag in the browserOptions field of NavDialogOptions record. Then provide a preview callback routine to draw the preview. Your preview callback procedure gets called whenever an object is selected from the browser. I chose to do a simple preview example in Figure 5 by drawing the file name and include an extra "Preview Info" button.

Figure 5. A Customized Preview.

Use the callBackParms->eventData->param field that contains an AppleEvent Descriptor of the file to preview. To use my preview info button, I respond to the kNavCBAdjustPreview event in my event callback procedure. This event determines if the preview area has been turned on or off (the user clicked Show/Hide Preview button), or if the preview areas has been resized. To check if preview is on or off, I use the next example:

Boolean previewShowing;
theErr = NavCustomControl( callBackParms->context, 
                 kNavCtlIsPreviewShowing, &previewShowing );

To determine the preview area that was resized, I reference the callBackParms->previewRect field. This will require that I move my preview info button as a result of the resizing. The minimum preview area is 145 pixels wide by 118 pixels high.

Some file selections may require that I remove my preview info button. Using the callBackParms->eventData>param field, I can add or remove my button based, depending on if the selection is a file or a folder. Each time a different file object is clicked, I may want to have a preview with different sets of controls for each file type. So every time the preview callback procedure is called, I must decide to create and remove my individual controls accordingly.

In order to respond to my controls I have to call TrackControl in my event callback procedure. This is similar to the way you interact with your own controls in the customization area. Finally, you needn't worry about errors. Navigation Services will output any possible file system error on a given file to the upper left corner of the preview area.

pascal Boolean myPreviewProc( NavCBRecPtr callBackParms, 
                             NavCallBackUserData callBackUD )
   OSErr         theErr = noErr;
   Boolean       previewShowing = false;
   AEDesc        resultDesc;
   FSSpec        previewFileSpec;
   Boolean       result = false;
   myGlobalsPtr  globals = (myGlobalsPtr)callBackUD;
   // find out of the preview area is showing:
   theErr = NavCustomControl( callBackParms->context, 
                 kNavCtlIsPreviewShowing, &previewShowing);
if ( theErr == noErr && previewShowing )   
      // make sure we have the right descriptor type:
      if ((theErr = AECoerceDesc(
                      typeFSS, &resultDesc )) == noErr)
         FInfo info;   
         // get the FSSpec from the descriptor:
         BlockMoveData( *resultDesc.dataHandle,
                      &previewFileSpec, sizeof( FSSpec ) );   
         if ((theErr = FSpGetFInfo(
                      &previewFileSpec, &info )) == noErr)
            // the finder info was successfully retrieved, so we have a file to preview:
            short      saveTxFont;
            short      saveTxSize;   
            GrafPtr    savePort;
            Rect       previewInfoButtonRect;
            // setup and create our Preview Info button:
            SetRect( &previewInfoButtonRect,
                        callBackParms->previewRect.bottom-10 );
            if ( globals->gPreviewInfoButton == NULL )
               // the control does not exist, so create one:
               globals->gPreviewInfoButton = 
               NewControl( callBackParms->window, &previewInfoButtonRect,
                          "\pPreview Info", false, 1, 0, 1,
                          pushButProc, NULL);
            saveTxFont = callBackParms->window->txFont;
            saveTxSize = callBackParms->window->txSize;
            GetPort( &savePort );
            SetPort( callBackParms->window );
            // draw our preview information:
            TextSize( 10 );
            TextFont( applFont );
            MoveTo(    callBackParms->previewRect.left + 8,
                        callBackParms-> + 15 );
            DrawString( );
            SetPort( savePort );
            TextFont( saveTxFont );
            TextSize( saveTxSize );
            // show our Preview Info button:
            if (globals->gPreviewInfoButton != NULL )
               ShowControl( globals->gPreviewInfoButton );
               Draw1Control( globals->gPreviewInfoButton );
            // return true since we handled drawing the preview:
            result = true;
 // failed trying to get the file to preview, so remove our Preview Info button
 // since we don't plan to draw the preview:
            if ( globals->gPreviewInfoButton != NULL )
               DisposeControl( globals->gPreviewInfoButton );
               globals->gPreviewInfoButton = NULL;
   return result;

Extending the Type Popup Menu

If you would like to add your own menu items to the type popup menu found in the Open and Save dialog boxes, use NavMenuItemSpec to describe each menu item you want to add. This lets you add specific document types to be opened, or different ways of saving a file (i.e. HTML format, Text with line breaks, etc.). The menu items can be added to the menu by adding a Handle to one or more NavMenuItemSpecs to the popupExtension field in the NavDialogOptions record.

To handle your custom popup menu items, respond to the kNavCBPopupMenuSelect event when Navigation Services calls your event callback procedure. It is up to you to interpret the menu item data and respond accordingly. Extending the popup menu also requires a filter callback procedure if you are to re-filter the browser after the menu selection is made.


As you can see, Navigation Services is a powerful and easy to use component in the Mac OS. At last you have a modern interface to navigate and organize your file system. Your experience with this technology will be rewarding from the start. It is easy to get started and once you have a basic familiarity with the API, you can then tackle the more advanced features. You will soon discover that writing a Navigation Services "savvy" application will be well worth the time and investment.


  • "Programming with Navigation Services", (Apple Computer, 1998).
  • Inside Macintosh, Volume 1, The Standard File Package, (Addison-Wesley Publishing, 1985).
  • Inside Macintosh: Files, Standard File Package, (Addison-Wesley Publishing, 1992).
  • Inside Macintosh: QuickTime Components, (Addison-Wesley Publishing, 1993).


Thanks to Sean Findley, Yan Arrouye, and Otto Schlosser.

Mac OS, Macintosh, QuickTime are registered trademarks of Apple Computer, Inc. PowerPC is a trademark of International Business Machines Corporation, used under license therefrom. Screenshots of NavGetFile and NavPutFile, © 1997-98, Apple Computer, Inc. All Rights Reserved.

Keith Mortensen ( is a software engineer for Apple Computer working on various human interface products for the Mac OS, currently contributing to Navigation Services. When Keith is off work, he's busy programming, working on his Suburban, and spends his spare time four wheeling and enjoying the outdoors at the Russian River and Tuolumne County areas of California.


Community Search:
MacTech Search:

Software Updates via MacUpdate

Is there cross-platform play in slither....
So you've sunken plenty of hours into crawling around in on your iPhone or iPad. You've got your stories of tragedy and triumph, the times you coiled four snakes at one time balanced out by the others when you had a length of more than... | Read more »
Rodeo Stampede guide to running a better...
In Rodeo Stampede, honing your skills so you can jump from animal to animal and outrun the herd as long as possible is only half the fun. Once you've tamed a few animals, you can bring them home with you. [Read more] | Read more »
VoxSyn (Music)
VoxSyn 1.0 Device: iOS Universal Category: Music Price: $6.99, Version: 1.0 (iTunes) Description: VoxSyn turns your voice into the most flexible vocal sound generator ever. Instantly following even subtle modulations of pitch and... | Read more »
Catch Battleplans on Google Play from Ju...
Real-time strategy title Battleplans is due for release on Google Play on June 30th, following its release for iOS systems last month. With its simple interface and pretty graphics, the crowd-pleaser brings a formerly overlooked genre out for the... | Read more »
iDoyle: The interactive Adventures of Sh...
iDoyle: The interactive Adventures of Sherlock Holmes - A Scandal in Bohemia 1.0 Device: iOS Universal Category: Books Price: $1.99, Version: 1.0 (iTunes) Description: Special Release Price $1.99 (Normally $3.99) | Read more »
Five popular free apps to help you slim...
Thanks to retail and advertising, we're used to thinking one season ahead. Here we are just a week into the summer and we're conditioned to start thinking about the fall. [Read more] | Read more »
How to ride longer and tame more animals...
It's hard to accurately describe Rodeo Stampede to people who haven't seen it yet. It's like if someone took Crossy Roadand Disco Zoo and put them in a blender, yet with a unique game mechanic that's still simple and fun for anyone. [Read more] | Read more »
Teeny Titans - A Teen Titans Go! Figure...
Teeny Titans - A Teen Titans Go! Figure Battling Game 1.0.0 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.0 (iTunes) Description: Teeny Titans, GO! Join Robin for a figure battling RPG of epic proportions! TEENY... | Read more »
NinjAwesome: Tips and tricks to be a mor...
Sorry about that headline, but I'm going to go ahead and assume that GameResort would not have named its game NinjAwesome without expecting some of that. It is, in fact, pretty awesome the way it combines an endless runner and old school arcade... | Read more »
Into Mirror (Games)
Into Mirror 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: "Is all that we see or seem, but a dream within a dream?"- Edgar Allan Poe New game by Lemon Jam Studio, the team behind Pursuit... | Read more »

Price Scanner via

15-inch Retina MacBook Pros on sale for $200-...
B&H Photo has 15″ Retina MacBook Pros on sale for up to $210 off MSRP. Shipping is free, and B&H charges NY tax only: - 15″ 2.2GHz Retina MacBook Pro: $1799.99 $200 off MSRP - 15″ 2.5GHz... Read more
Mac minis on sale for up to $100 off MSRP
B&H Photo has Mac minis on sale for up to $100 off MSRP including free shipping plus NY sales tax only: - 1.4GHz Mac mini: $449 $50 off MSRP - 2.6GHz Mac mini: $649 $50 off MSRP - 2.8GHz Mac mini... Read more
Clearance 2015 13-inch MacBook Airs available...
B&H Photo has clearance 2015 13″ MacBook Airs available for $300 off original MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 1.6GHz/4GB/128GB MacBook Air (MJVE2LL/A): $799.... Read more
Apple refurbished Mac minis available for up...
Apple has Certified Refurbished Mac minis available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: - 1.4GHz Mac mini: $419 $80 off MSRP - 2.6GHz Mac... Read more
ABBYY TextGrabber: 1,000,000 Installs in 5 Da...
ABBYY, an international OCR technologies provider, has announced that their image-to-text application TextGrabber, got installed 1,000,000 times in just five days while being featured by the App... Read more
New SkinIt Waterproof Case For iPhone 6
With its impact and waterproof design, the Skinit Waterproof case provides security and protection to guarantee your phone will get you through even the most demanding outdoor conditions. The impact-... Read more
iMacs on sale for up to $150 off MSRP
B&H Photo has 21″ and 27″ iMacs on sale for up to $150 off MSRP including free shipping plus NY sales tax only: - 27″ 3.3GHz iMac 5K: $2181.11 $118 off MSRP - 27″ 3.2GHz/1TB Fusion iMac 5K: $1949... Read more
12-inch 1.1GHz Retina MacBooks on sale for $5...
B&H Photo has 2016 12″ 1.1GHz/256GB Retina MacBooks on sale for up to $50 off MSRP. Shipping is free, and B&H charges NY tax only: - 12″ 1.1GHz Space Gray Retina MacBook: $1249 $50 off MSRP... Read more
WWDC Announcements Revisited Still Underwhelm...
I was disappointed that no new MacBook hardware was announced at this year’s all-software World Wide Developer’s Conference. Not even a hint about what’s in the development pipeline. Of course, we... Read more
Twelve South Compass 2 iPad Stand Now Availab...
Twelve South has updated its most popular iPad stand, Compass 2, with the introduction of two new colors — Gold and Rose Gold. These new color options n perfectly complement the new Rose Gold iPad... Read more

Jobs Board

*Apple* iPhone 6s and New Products Tester Ne...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
Music Marketing Lead, iTunes & *Apple*...
…Music Marketing Lead is responsible for developing robust marketing campaigns and programs for Apple Music and iTunes across the whole of Apple ecosystem. This Read more
*Apple* Valley Medical Clinic is Hiring - AP...
Apple Valley Medical Clinic is Hiring! Apple Valley Medical Clinic is an independently owned practice operating a Family Medicine Clinic, a 24/7 Urgent Care, Read more
*Apple* New Products Testers Needed - Apple...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
*Apple* Solutions Consultant - APPLE (United...
Job Summary As an Apple Solutions Consultant, you'll be the link between our future customers and our products. You'll showcase your entrepreneurial spirit as you Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.