As an alternative to calling NavDialogGetUserAction, you can extract the user action from the userAction field of the NavCBRec structure.
After determining the user action, your event handling function should take the appropriate action. For example, if the Open button was clicked, your event handling function should proceed to open the file, or files, selected by the user in the Open dialog.
Note that you should always call the function NavCompleteSave to complete any save operation. Amongst other things, NavCompleteSave performs any needed translation.
kNavCBTerminate Message Received
When the kNavCBTerminate message is received, your event handler should call NavDialogDispose to dispose of the dialog reference.
Event Handling in Primary Alerts
Your event handling function for the primary alerts should be declared in the same way as that for the event handling function for the primary dialogs.
When the kNavCBUserAction message is received, your application should call NavDialogGetUserAction to determine the user action, and then take the appropriate action. The user action constants relevant to the primary alerts are as follows:
Constant |
Value |
Description |
---|---|---|
kUserActionCancel | 1 | The user clicked the Cancel button. |
kUserActionSaveChanges | 6 | he user clicked the Save button in a Save Changes alert. |
kUserActionDontSaveChanges | 7 | The user clicked the Don't Save button in a Save Changes alert. |
kUserActionDiscardChanges | 8 | The user clicked the OK button in a Discard Changes alert. |
When the appropriate action has been taken, your event handler should call NavDialogDispose to dispose of the dialog reference.
Other Application-Defined (Callback) Functions
Application-Defined Object Filtering
If your application needs simple, straightforward object filtering, and as previously described, you simply pass a pointer to a structure of type NavTypeList to the relevant Navigation Services function (NavCreateGetFileDialog or NavCreateChooseFileDialog). If you desire more specific filtering, you can provide an application-defined filter function. Filter functions give you more control over what can and cannot be displayed. You can pass a universal procedure pointer to your filter function in calls to the functions NavCreateGetFileDialog, NavCreateChooseFileDialog, NavCreateChooseFolderDialog, NavCreateChooseVolumeDialog, and NavCreateChooseObjectDialog.
You can use both a NavTypeList structure and a filter function for the Open and Choose a File dialogs 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.
Your filter function should return true if an object is to be displayed. The following is an example of a filter function that allows only text files to be displayed:
Boolean myNavFilterFunction(AEDesc *theItem, void *info,void *callBackUD, NavFilterModes filterMode) { OSErr theErr = noErr; Boolean display = true; NavFileOrFolderInfo *theInfo; theInfo = (NavFileOrFolderInfo *) info; if(theItem->descriptorType == typeFSS) if(!theInfo->isFolder) if(theInfo->fileAndFolder.fileInfo.finderInfo.fdType != 'TEXT') display = false; return display; }
Application-Defined (Callback) Previews
To override how previews are drawn and handled, you can create a preview function and pass a universal procedure pointer to it in the inpreviewProc parameter of the Navigation Services functions NavCreateGetFileDialog, NavCreateChooseFileDialog and NavCreateChooseObjectDialog:
Boolean myPreviewProc(NavCBRecPtr callBackParms,void *callBackUD); | |
callBackParms | A pointer to a NavCBRec structure that contains event data needed for your function to draw the preview. |
callBackUD | A value set by your application. |
Return: true if your preview function successfully draws the file preview. If your preview function returns false, Navigation Services will display the preview if the file contains a valid 'pnot' resource. |
Main File Manager Constants, Data Types and Functions
Constants
Read/Write Permission
fsCurPerm = 0 fsRdPerm = 1 fsWrPerm = 2 fsRdWrPerm = 3 fsRdWrShPerm = 4
File Mark Positioning Modes
fsAtMark = 0 fsFromStart = 1 fsFromLEOF = 2 fsFromMark = 3 rdVerify = 64
Data Types
File System Specification Structure
struct FSSpec { short vRefNum; // Volume reference number. long parID; // Directory ID of parent directory. Str63 name; // Filename or directory name. }; typedef struct FSSpec FSSpec; typedef FSSpec *FSSpecPtr, **FSSpecHandle;
File System Reference
struct FSRef { UInt8 hidden[80]; }
File Information Structure
struct FInfo { OSType fdType; // File type. OSType fdCreator; // File's creator. unsigned short fdFlags; // Finder flags (fHasBundle, fInvisible, etc). Point fdLocation; // Position of top-left corner of file's icon. short fdFldr; // Folder containing file. }; typedef struct FInfo FInfo;
Functions
Reading, Writing and Closing Files
OSErr FSClose(short refNum); OSErr FSRead(short refNum,long *count,void *buffPtr); OSErr FSWrite(short refNum,long *count,const void *buffPtr);
Manipulating the File Mark
OSErr GetFPos(short refNum,long *filePos); OSErr SetFPos(short refNum,short posMode,long posOff);
Manipulating the End-Of-File
OSErr GetEOF(short refNum,long *logEOF); OSErr SetEOF(short refNum,long logEOF);
Opening and CreatingFiles
OSErr FSpOpenDF(const FSSpec *spec,SInt8 permission,short *refNum); OSErr FSpOpenRF(const FSSpec *spec,SInt8 permission,short *refNum); OSErr FSpCreate(const FSSpec *spec,OSType creator,OSType fileType,ScriptCode scriptTag); OSErr FSCreateFileUnicode(const FSRef *parentRef,UniCharCount nameLength,const UniChar *name, FSCatalogInfoBitmap whichInfo,const FSCatalogInfo *catalogInfo,FSRef *newRef, FSSpec *newSpec);
Deleting Files and Directories
OSErr FSpDelete(const FSSpec *spec); OSErr FSDeleteObject(const FSRef *ref);
Exchanging Data in Two Files
OSErr FSpExchangeFiles(const FSSpec *source,const FSSpec *dest); OSErr FSExchangeObjects(const FSRef *ref,const FSRef *destRef);
Creating File System Specifications and File System References
OSErr FSMakeFSSpec(short vRefNum,long dirID,ConstStr255Param fileName,FSSpec *spec); OSErr FSpMakeFSRef(const FSSpec *source,FSRef *newRef); OSErr FSMakeFSRefUnicode(const FSRef *parentRef,UniCharCount nameLength,const UniChar *name, TextEncoding textEncodingHint,FSRef *newRef)
Obtaining Volume Information
OSErr GetVInfo(short drvNum,StringPtr volName,short *vRefNum,long *freeBytes); OSErr GetVRefNum(short fileRefNum,short *vRefNum);
Getting and Setting Finder Information
OSErr FSpGetFInfo(FSSpec *spec,FInfo *fndrInfo); OSErr FSpSetFInfo(const FSSpec *spec,const FInfo *fndrInfo);
Relevant Resource Manager Functions
Creating and Opening Resource Files
void FSpCreateResFile(const FSSpec *spec,OSType creator,OSType fileType, ScriptCode scriptTag); short FSpOpenResFile(const FSSpec *spec,SignedByte permission);
Relevant Finder Interface Functions
Find a Specified Folder
OSErr FindFolder(short vRefNum,OSType folderType,Boolean createFolder, short *foundVRefNum,long *foundDirID)
Main Navigation Services Constants, Data Types, and Functions
Constants
Navigation Services Dialog Option Flags
kNavDefaultNavDlogOptions = 0x000000E4 kNavNoTypePopup = 0x00000001 kNavDontAutoTranslate = 0x00000002 kNavDontAddTranslateItems = 0x00000004 kNavAllFilesInPopup = 0x00000010 kNavAllowStationery = 0x00000020 kNavAllowPreviews = 0x00000040 kNavAllowMultipleFiles = 0x00000080 kNavAllowInvisibleFiles = 0x00000100 kNavDontResolveAliases = 0x00000200 kNavSelectDefaultLocation = 0x00000400 kNavSelectAllReadableItem = 0x00000800 kNavSupportPackages = 0x00001000 kNavAllowOpenPackages = 0x00002000 kNavDontAddRecents = 0x00004000 kNavDontUseCustomFrame = 0x00008000 kNavDontConfirmReplacement = 0x00010000
Event Messages
kNavCBEvent = 0 kNavCBCustomize = 1 kNavCBStart = 2 kNavCBTerminate = 3 kNavCBAdjustRect = 4 kNavCBNewLocation = 5 kNavCBShowDesktop = 6 kNavCBSelectEntry = 7 kNavCBPopupMenuSelect = 8 kNavCBAccept = 9 kNavCBCancel = 10 kNavCBAdjustPreview = 11 kNavCBUserAction = 12 kNavCBOpenSelection = (long) 0x80000000
User Action
kNavUserActionNone = 0 kNavUserActionCancel = 1 kNavUserActionOpen = 2 kNavUserActionSaveAs = 3 kNavUserActionChoose = 4 kNavUserActionNewFolder = 5 kNavUserActionSaveChanges = 6 kNavUserActionDontSaveChanges = 7 kNavUserActionDiscardChanges = 8
Save Changes Action
kNavSaveChangesClosingDocument = 1 kNavSaveChangesQuittingApplication = 2
Data Types
typedef struct __NavDialog *NavDialogRef; typedef UInt32 NavDialogOptionFlags; typedef SInt32 NavEventCallbackMessage; typedef void *NavCallBackUserData; typedef UInt32 NavUserAction; typedef UInt32 NavAskSaveChangesAction;
NavDialogCreationOptions
struct NavDialogCreationOptions { UInt16 version; NavDialogOptionFlags optionFlags; Point location; CFStringRef clientName; CFStringRef windowTitle; CFStringRef actionButtonLabel; CFStringRef cancelButtonLabel; CFStringRef saveFileName; CFStringRef message; UInt32 preferenceKey; CFArrayRef popupExtension; WindowModality modality; WindowRef parentWindow; char reserved[16]; }; typedef struct NavDialogCreationOptions NavDialogCreationOptions;
NavTypeList
struct NavTypeList { OSType componentSignature; short reserved; short osTypeCount; OSType osType[1]; }; typedef struct NavTypeList NavTypeList; typedef NavTypeList *NavTypeListPtr; typedef NavTypeListPtr *NavTypeListHandle;
NavCBRec
struct NavCBRec { UInt16 version; NavDialogRef context; WindowRef window; Rect customRect; Rect previewRect; NavEventData eventData; NavUserAction userAction; char reserved[218]; }; typedef struct NavCBRec NavCBRec; typedef NavCBRec *NavCBRecPtr;
NavReplyRecord
struct NavReplyRecord { UInt16 version; Boolean validRecord; Boolean replacing; Boolean isStationery; Boolean translationNeeded; AEDescList selection; ScriptCode keyScript; FileTranslationSpecArrayHandle fileTranslation; UInt32 reserved1; CFStringRef saveFileName; char reserved[227]; }; typedef struct NavReplyRecord NavReplyRecord;
Functions
Initialising the NavDialogCreationOptions Structure
OSStatus NavGetDefaultDialogCreationOptions(NavDialogCreationOptions *outOptions);
Creating and Disposing Of Navigation Services Dialogs
OSStatus NavCreateGetFileDialog(const NavDialogCreationOptions *inOptions, NavTypeListHandle inTypeList,NavEventUPP inEventProc,NavPreviewUPP inPreviewProc, NavObjectFilterUPP inFilterProc,void *inClientData,NavDialogRef *outDialog); OSStatus NavCreatePutFileDialog(const NavDialogCreationOptions *inOptions, OSType inFileType,OSType inFileCreator,NavEventUPP inEventProc, void *inClientData,NavDialogRef *outDialog); OSStatus NavCreateAskSaveChangesDialog(const NavDialogCreationOptions *inOptions, NavAskSaveChangesAction inAction,NavEventUPP inEventProc,void *inClientData, NavDialogRef *outDialog); OSStatus NavCreateAskDiscardChangesDialog(const NavDialogCreationOptions *inOptions, NavEventUPP inEventProc,void *inClientData,NavDialogRef *outDialog); OSStatus NavCreateChooseFileDialog(const NavDialogCreationOptions *inOptions, NavTypeListHandle inTypeList,NavEventUPP inEventProc,NavPreviewUPP inPreviewProc, NavObjectFilterUPP inFilterProc,void *inClientData,NavDialogRef *outDialog); OSStatus NavCreateChooseVolumeDialog(const NavDialogCreationOptions *inOptions, NavEventUPP inEventProc,NavObjectFilterUPP inFilterProc,void *inClientData, NavDialogRef *outDialog); OSStatus NavCreateChooseObjectDialog(const NavDialogCreationOptions *inOptions, NavEventUPP inEventProc,NavPreviewUPP inPreviewProc, NavObjectFilterUPP inFilterProc,void *inClientData,NavDialogRef *outDialog); void NavDialogDispose(NavDialogRef inDialog);
Displaying and Running a Navigation Services Dialog
OSStatus NavDialogRun(NavDialogRef inDialog);
Filling In and Disposing Of NavReplyRecord Structures
OSStatus NavDialogGetReply(NavDialogRef inDialog,NavReplyRecord *outReply); OSErr NavDisposeReply(NavReplyRecord *reply);
Getting the User Action
NavUserAction NavDialogGetUserAction(NavDialogRef inDialog);
Getting and Setting the Save File Name
CFStringRef NavDialogGetSaveFileName(NavDialogRef inPutFileDialog); OSStatus NavDialogSetSaveFileName(NavDialogRef inPutFileDialog,CFStringRef inFileName); Getting the Window In Which a Navigation Services Dialog Appears WindowRef NavDialogGetWindow(NavDialogRef inDialog);
Completing a Save Operation
OSErr NavCompleteSave(NavReplyRecord *reply,NavTranslationOptions howToTranslate);
Creating New Folders
OSStatus NavCreateNewFolderDialog(const NavDialogCreationOptions *inOptions, NavEventUPP inEventProc,void *inClientData,NavDialogRef *outDialog);
Creating Previews
OSErr NavCreatePreview(AEDesc *theObject,OSType previewDataType, const void *previewData,Size previewDataSize);
Creating and Disposing of Universal Procedure Pointers
NavEventUPP NewNavEventUPP(NavEventProcPtr userRoutine); NavPreviewUPP NewNavPreviewUPP(NavPreviewProcPtr userRoutine); NavObjectFilterUPP NewNavObjectFilterUPP(NavObjectFilterProcPtr userRoutine); void DisposeNavEventUPP(NavEventUPP userUPP); void DisposeNavPreviewUPP(NavPreviewUPP userUPP); void DisposeNavObjectFilterUPP(NavObjectFilterUPP userUPP);
Application-Defined (Callback) Functions - Event Handling, Previews, and Filters
void myNavEventFunction(NavEventCallbackMessage callBackSelector, NavCBRecPtr callBackParms,void *callBackUD); Boolean myNavPreviewFunction(NavCBRecPtr callBackParms,void *callBackUD); Boolean myNavObjectFilterFunction(AEDesc *theItem,void *info,void *callBackUD, NavFilterModes filterMode);
- SPREAD THE WORD:
- Slashdot
- Digg
- Del.icio.us
- Newsvine