Although introduced with Mac OS 8.5, Navigation Services may be used with Mac OS 7.5.5 or later provided Appearance Manager 1.0.1 or later is present. QuickTime is also required if previews of graphic documents are to be created and viewed. Macintosh Easy Open is required for document translation and the correct display of file types. On 680x0 systems, Navigation Services requires the CFM-68K Runtime Enabler.

The dialog and alert boxes created by Navigation Services are all Appearance-compliant. Provided that your application provides an event-handling callback function, the primary dialog boxes are resizable and movable and the alert boxes are movable.

As is the case with the Standard File Package dialogs, the primary Navigation Services dialog boxes may be customised.

Navigation Services Dialog and Alert Boxes

• Open.

• Save.

• Choose a folder.

• Choose a volume.

• Choose a file.

• Choose a file object.

• Create a new folder.

• Save changes.

• Discard changes.

The menus associated with the standard user interface elements known as the Shortcut, Favourites, and Recent bevel buttons are shown in more detail at Fig 2.

Moving and Resizing Navigation Services Dialog Boxes

Folders and volumes cannot be multiple-selected.

The Show Pop-up Menu

Native File Types Section

The remaining items in the native file types section will default to <Application Name> Document unless you provide kind strings to describe the file types included in your NavTypeList structure. You can do this by including a kind resource (a resource of type 'kind') in your application's resource fork. Fig 4 shows the structure of a compiled 'kind' resource and such a resource being created using Resorcerer.

The kind strings from your application's 'kind' resource also appear in the Kind column in Finder window list views.

The NavDialogOptions and NavTypeList Structures

     struct NavTypeList 
     {
       OSType componentSignature; // Your application signature.
       short  reserved;
       short  osTypeCount;        // How many file types will be defined.
       OSType osType[1];          // A list of file types your application can open.
     };

The NavDialogOptions Structure

     struct NavDialogOptions 
     {
       UInt16               version;
       NavDialogOptionFlags dialogOptionFlags;
       Point                location;
       Str255               clientName;
       Str255               windowTitle;
       Str255               actionButtonLabel;
       Str255               cancelButtonLabel;
       Str255               savedFileName;
       Str255               message;
       UInt32               preferenceKey;
       Handle               popupExtension;
     };

dialogOptionsFlags	One of the following constants of type NavDialogOptionFlags: Constant Description kNavDefaultNavDlogOptions Use default options. The defaults are as follows: No custom control titles. No banner or prompt message. Automatic resolution of aliases. Support for file previews. No invisible file objects are displayed. Support for stationery. kNavNoTypePopup Don't show file type pop-up. kNavDontAutoTranslate Don't auto-translate on Open. kNavDontAddTranslateItems Don't add translation choices. kNavAllFilesInPopup Add "All Files" menu item. kNavAllowStationery Allow stationery files. kNavAllowPreviews Allow previews. kNavAllowMultipleFiles Allow multiple selection. kNavAllowInvisibleFiles Show invisible objects. kNavDontResolveAliases Don't resolve aliases. kNavSelectDefaultLocation Make default location the browser selection. kNavSelectAllReadableItem Make All Readable Items default selection.
location	The upper-left location of the dialog box, in global coordinates. If the dialogOptionFlags field is NULL or the coordinate value is (-1,-1), then the dialog box appears in the same location as when last closed. The size and location of the dialog box is persistent, but defaults to opening in the middle of the main screen if any portion is not visible when opened at the persistent location and size.
clientName	A string that identifies your application in the dialog box window title.
windowTitle	A string that you can provide to override the default window title.
actionButtonLabel	An alternative button title for the dialog box's action push button. If you do not specify a label, the push button will use the default label (Open or Save, for example.)
cancelButtonLabel	An alternative button title for the Cancel push button in dialog boxes.
savedFileName	The default file name for a saved file.
message	The string for the banner, or prompt, below the browser list. This message can provide more descriptive instructions for the user. If you don't provide a message string, the browser list will expand to fill that area.
preferenceKey	An application-defined value that identifies which set of dialog box preferences Navigation Services should use. If your application maintains multiple sets of preferences for a particular type of dialog box, you can determine which set is active by specifying the appropriate value in the preferenceKey field. For example, an application may allow one set of preferences when it calls the function NavGetFile to open text files and a different set of preferences when opening movie files. If you do not wish to provide a preference key, specify zero for the preferenceKey value.
popupExtension	A handle to one or more structures of type NavMenuItemSpec used to add extra menu items to the Show pop-up menu in an Open dialog box or the Format pop-up menu in Save dialog boxes. Using NavMenuItemSpec structures allows your application to add additional document types to be opened or saved, or different ways of saving a file (with or without line breaks, for example).

The function NavGetDefaultDialogOptions may be called to initialise a structure of type NavDialogOptions with the default dialog box options.

The NavReplyRecord Structure

     struct NavReplyRecord 
     {
       UInt16              version;
       Boolean             validRecord;
       Boolean             replacing;
       Boolean             isStationery;
       Boolean             translationNeeded;
       AEDescList          selection;
       ScriptCode          keyScript;
       FileTranslationSpec **fileTranslation;
     };

validRecord	true if the user closes a dialog box by pressing Return or Enter, or by pressing the default button in an Open or Save dialog box. If this field is false, all other fields are unused and do not contain valid data.
replacing	true if the user chooses to save a file by replacing an existing file (thereby necessitating the removal or renaming of the existing file).
isStationery	A Boolean value informing your application that the file about to be saved should be saved as a stationery document.
translationNeeded	A Boolean value indicating that translation was or will be needed for files selected in Open and Save dialog boxes.
selection	An Apple event descriptor list (AEDescList) created from FSSpec references to items selected through the dialog box. Navigation Services creates this list, which is automatically disposed of when your application calls the function NavDisposeReply (see below). You can determine the number of items in the list by calling the Apple Event Manager function AECountItems. (Some dialog boxes may return one or more items; a Save dialog box will always return one.) Each selected item is described in an AEDesc structure by the descriptor type typeFSS. You can coerce this descriptor into an FSSpec structure to perform operations such as opening the file.
keyScript	The keyboard script system used for the filename.
fileTranslation	A handle to a FileTranslationSpec structure. This structure contains a corresponding translation array for each file reference returned in the selection field. When opening files, Navigation Services will perform the translation automatically unless you set the kNavDontAutoTranslate flag in the dialogOptionFlags field of the NavDialogOptions structure. When Navigation Services performs an automatic translation, the FileTranslationSpec structure is strictly for the Translation Manager's use. If you turn off automatic translation, your application may use the FileTranslationSpec structure for its own translation scheme. If the user chooses a translation for a saved file, the FileTranslationSpec structure contains a single translation reference for the saved file and the translationNeeded field of the NavReplyRecord structure is set to true. The handle to the FileTranslationSpec structure is locked, so you can safely use dereferenced pointers.

When your application has finished using this structure, it should dispose of it by calling the function NavDisposeReply.

Saving Files

You should always call the function NavCompleteSave to complete any save operation. Amongst other things, NavCompleteSave performs any needed translation.

Translating Files on Save

If the user selects an output file type that is different from the native type, Navigation Services prepares a translation specification and supplies a handle to it in the fileTranslation field of a NavReplyRecord structure. If you choose to provide your own translation, Navigation Services informs you that translation is required by setting the translationNeeded field of the NavReplyRecord structure to true.

If you wish to turn off automatic translation, set the value of the translationNeeded field of the NavReplyRecord structure to false before calling the NavCompleteSave function.

By default, the NavPutFile function saves translations as a copy of the original file. Your application can direct Navigation Services to replace the original with the translation by passing the kNavTranslateInPlace constant in the howToTranslate parameter of the NavCompleteSave function.

Choosing A Folder

Several Navigation Services functions return Apple event descriptors for file objects. When Navigation Services passes your application an AEDesc structure of type typeFSS describing a file, the name field will contain the file's name and the parID field will contain the directory ID of the file's parent directory. However, when Navigation Services passes your application an AEDesc structure of type typeFSS describing a directory, the name field is empty and the parID field contains the directory ID of that directory.

This means, incidentally, that you can use the name field to determine whether an object is a file or a folder.

Choosing Volumes, Files, File Objects, and Creating a New Folder

The function NavChooseFile displays a dialog box that prompts the user to choose a file. This file can be a preferences file, dictionary, or other specialised file.

The function NavChooseObject displays a dialog box that prompts the user to choose a file object. This function is useful when you need the user to select an object which might be one of several different types.

The function NavNewFolder displays a dialog box that prompts the user to create a new folder.

As with the Choose Folder dialog box, these dialog boxes will display a string assigned to the message field of the NavDialogOptions structure immediately below the browser list.

Save Changes and Discard Changes Alert Boxes

One of the following constants is passed in the action parameter of the NavAskSaveChanges function:

     kNavSaveChangesClosingDocument = 1
     kNavSaveChangesQuittingApplication  = 2
     kNavSaveChangesOther                = 0

     kNavAskSaveChangesSave = 1
     kNavAskSaveChangesCancel    = 2
     kNavAskSaveChangesDontSave  = 3

Save Changes alert boxes are movable only if your application provides an application-defined event-handling callback function to handle update events.

Discard Changes Alert Box

After the user closes the alert box, Navigation Services tells your application which button the user clicked by returning one of the following constants:

     kNavAskDiscardChanges       = 1
     kNavAskDiscardChangesCancel = 2

The following is an example of an event-handling function:

     pascal void  myEventFunction(NavEventCallbackMessage callBackSelector,
                             NavCBRecPtr callBackParms,void *callBackUD)
     {
       WindowPtr window;

       WindowPtr = (WindowPtr) callBackParms->eventData.event->message;

       switch (callBackSelector)
       {
         case kNavCBEvent:
           switch (callBackParms->eventData.event->what)
           {
             case updateEvt:
               doUpdate(window,(EventRecord *) callBackParms->eventData.event);
               break;
           }
           break;
       }

You can use both an NavTypeList structure and a filter function if you wish, but be aware that your filter function is directly affected by the NavTypeList structure. For example, if the NavTypeList structure contains only TEXT and PICT types, only TEXT and PICT files will be passed into your filter function.

You pass a universal procedure pointer to your filter function in the filterProc parameter of functions such as NavGetFile. Your filter function should return true if an object is to be displayed. The following is an example of a simple filter function:

     pascal Boolean  myFilterFunction(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->fileAndFolder.fileInfo.finderInfo.fdType != 'TEXT')
             display = false;

       return display;
     }

     pascal Boolean  myPreviewProc(NavCBRecPtr callBackParms,
                                   NavCallBackUserData callBackUD);

Your application can use the function NavCustomControl to determine if the preview area is visible and, if so, what its dimensions are.

Adding Controls to a Navigation Services Dialog Box

• Provide an event-handling function to communicate with Navigation Services.

• Within the event-handling function, respond to the kNavCBCustomize event message constant, which your application can obtain from the param field of the NavCBRec structure. (See Application-Defined Event Handling, above.) The customRect field of the NavCBRec structure defines a rectangle in the local coordinates of the window. The top-left coordinates of this rectangle define the anchor point for the customisation rectangle, which is the area Navigation Services provides for your application to add custom dialog items. Your application responds by passing the values which will complete the dimensions of your required customisation rectangle. Navigation Services inspects the customRect field to determine if the requested dimensions can be accommodtated in the screen space available. If not, the rectangle will be set to the largest size that can be accommodated and your application will be sent another kNavCBCustomize constant. Your application can continue to negotiate by examining the customRect field and requesting a different size until Navigation Services provides an acceptable rectangle value. The minimum dimensions for the customisation area are 400 pixels wide by 40 pixels high.

  The customRect field contains an empty rectangle if customisation is not allowed (i.e. dialog boxes other than Open or Save). In this case, your application can simply ignore the call.

• With the customisation rectangle established, check for the kNavCBStart event message constant in the param field of the NavCBRec structure. kNavCBStart indicates that Navigation Services is opening the dialog box. After you obtain this constant, you can add your interface elements to the customisation rectangle. You can do this by providing a 'DITL' resource (in local coordinates, relative to the anchor point of the customisation rectangle) and passing the kNavCtlAddControlList constant in the selector parameter of the function NavCustomControl. The following shows one way to do this:

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

  The advantage of using a 'DITL' resource is that the Dialog Manager will handle all control movement and tracking.

• When Navigation Services supplies the kNavCBTerminate event message constant in the param field of the NavCBRec structure (after the user closes the dialog box), dispose of the control or resource.

Main Navigation Services Constants, Data Types, and Functions

kNavDefaultNavDlogOptions = 0x000000E4  Use defaults for all the options
kNavNoTypePopup           = 0x00000001  Don't show file type/extension popup on 
                                        Open/Save
kNavDontAutoTranslate     = 0x00000002  Don't automatically translate on Open
kNavDontAddTranslateItems = 0x00000004  Don't add translation choices on Open/Save
kNavAllFilesInPopup       = 0x00000010  "All Files" menu item in the type popup on 
                                        Open
kNavAllowStationery       = 0x00000020  Allow saving of stationery files
kNavAllowPreviews         = 0x00000040  Allow to show previews
kNavAllowMultipleFiles    = 0x00000080  Allow multiple items to be selected
kNavAllowInvisibleFiles   = 0x00000100  Allow invisible items to be shown
kNavDontResolveAliases    = 0x00000200  Don't resolve aliases
kNavSelectDefaultLocation = 0x00000400  Make the default location the browser selection
kNavSelectAllReadableItem = 0x00000800  Make dialog select "All Readable Documents" on 
                                        Open
kNavSupportPackages       = 0x00001000  Recognize file system packages
kNavAllowOpenPackages     = 0x00002000  Allow opening of packages
kNavDontAddRecents        = 0x00004000  Don't add chosen objects to the recents list 
kNavDontUseCustomFrame    = 0x00008000  Don't add the bevelled custom frame 

kNavSaveChangesClosingDocument      = 1
kNavSaveChangesQuittingApplication  = 2
kNavSaveChangesOther                = 0

kNavAskSaveChangesSave      = 1
kNavAskSaveChangesCancel    = 2
kNavAskSaveChangesDontSave  = 3

kNavAskDiscardChanges        = 1
kNavAskDiscardChangesCancel  = 2

kNavCBEvent           = 0  // An event has occurred (update, idle events, etc.)
kNavCBCustomize       = 1  // Protocol for negotiating customization space
kNavCBStart           = 2  // The navigation dialog is starting up
kNavCBTerminate       = 3  // The navigation dialog is closing down
kNavCBAdjustRect      = 4  // The navigation dialog is being resized
kNavCBNewLocation     = 5  // User has chosen a new location in the browser
kNavCBShowDesktop     = 6  // User has navigated to the desktop
kNavCBSelectEntry     = 7  // User has made a selection in the browser
kNavCBPopupMenuSelect = 8  // Signifies that a popup menu selection was made
kNavCBAccept          = 9  // User has accepted the navigation dialog
kNavCBCancel          = 10 // User has cancelled the navigation dialog
kNavCBAdjustPreview   = 11 // Preview button clicked or preview was resized
kNavCBOpenSelection   = (long) 0x80000000  // User has opened or chosen an object

kNavFilteringBrowserList      = 0
kNavFilteringFavorites        = 1
kNavFilteringRecents          = 2
kNavFilteringShortCutVolumes  = 3

struct NavDialogOptions 
{
  UInt16                version;
  NavDialogOptionFlags  dialogOptionFlags;
  Point                 location;
  Str255                clientName;
  Str255                windowTitle;
  Str255                actionButtonLabel;
  Str255                cancelButtonLabel;
  Str255                savedFileName;
  Str255                message;
  UInt32                preferenceKey;
  Handle                popupExtension;
  char                  reserved[494];
};
typedef struct NavDialogOptions NavDialogOptions;

struct NavReplyRecord 
{
  UInt16              version;
  Boolean             validRecord;
  Boolean             replacing;
  Boolean             isStationery
  Boolean             translationNeeded;
  AEDescList          selection;
  ScriptCode          keyScript;
  FileTranslationSpec **fileTranslation;
  UInt32              reserved1;
  char                reserved[231];
};
typedef struct NavReplyRecord NavReplyRecord;

struct NavTypeList 
{
  OSType  componentSignature;
  short   reserved;
  short   osTypeCount;
  OSType  osType[1];
};
typedef struct NavTypeList NavTypeList;
typedef NavTypeList *NavTypeListPtr;
typedef NavTypeListPtr *NavTypeListHandle;

OSErr  NavLoad(void);
OSErr  NavUnload(void);
OSErr  NavGetDefaultDialogOptions(NavDialogOptions *dialogOptions);
OSErr  NavDisposeReply(NavReplyRecord *reply);

OSErr  NavGetFile(AEDesc *defaultLocation,NavReplyRecord *reply,
       NavDialogOptions *dialogOptions,NavEventUPP eventProc,
       NavPreviewUPP previewProc,NavObjectFilterUPP filterProc,
       NavTypeListHandle typeList,NavCallBackUserData callBackUD);
OSErr  NavChooseFile(AEDesc *defaultLocation,NavReplyRecord *reply,
       NavDialogOptions *dialogOptions,NavEventUPP eventProc,
       NavPreviewUPP previewProc,NavObjectFilterUPP filterProc,
       NavTypeListHandle typeList,NavCallBackUserData callBackUD);
OSErr  NavChooseVolume(AEDesc *defaultSelection,NavReplyRecord *reply,
       NavDialogOptions *dialogOptions,NavEventUPP eventProc,
       NavObjectFilterUPP filterProc,NavCallBackUserData callBackUD);
OSErr  NavChooseFolder(AEDesc *defaultLocation,NavReplyRecord *reply,
       NavDialogOptions *dialogOptions,NavEventUPP eventProc,
       NavObjectFilterUPP filterProc,NavCallBackUserData callBackUD);
OSErr  NavChooseObject(AEDesc *defaultLocation,NavReplyRecord *reply,
       NavDialogOptions *dialogOptions,NavEventUPP eventProc,
       NavObjectFilterUPP filterProc,NavCallBackUserData callBackUD);
OSErr  NavNewFolder(AEDesc *defaultLocation,NavReplyRecord *reply,
       NavDialogOptions *dialogOptions,NavEventUPP eventProc,
       NavCallBackUserData callBackUD);
OSErr  NavCreatePreview(AEDesc *theObject,OSType previewDataType,
       const void *previewData,Size previewDataSize);

OSErr  NavPutFile(AEDesc *defaultLocation,NavReplyRecord *reply,
       NavDialogOptions *dialogOptions,NavEventUPP eventProc,OSType fileType,
       OSType fileCreator, NavCallBackUserData callBackUD);
OSErr  NavAskSaveChanges(NavDialogOptions *dialogOptions,
       NavAskSaveChangesAction  action,NavAskSaveChangesResult *reply,
       NavEventUPP eventProc,NavCallBackUserData callBackUD);
OSErr  NavCustomAskSaveChanges(NavDialogOptions *dialogOptions,
       NavAskSaveChangesResult *reply,NavEventUPP eventProc,
       NavCallBackUserData callBackUD);
OSErr  NavAskDiscardChanges(NavDialogOptions *dialogOptions,
       NavAskDiscardChangesResult *reply,NavEventUPP eventProc,
       NavCallBackUserData callBackUD);
OSErr  NavCompleteSave(NavReplyRecord *reply,NavTranslationOptions howToTranslate);