/* File: Navigation.h Contains: Navigation Services Interfaces Version: QuickTime 7.3 Copyright: (c) 2007 (c) 1996-2001 by Apple Computer, Inc., all rights reserved Bugs?: For bug reports, consult the following page on the World Wide Web: http://developer.apple.com/bugreporter/ */ #ifndef __NAVIGATION__ #define __NAVIGATION__ #ifndef __MACTYPES__ #include #endif #ifndef __MACERRORS__ #include #endif #ifndef __CODEFRAGMENTS__ #include #endif #ifndef __TRANSLATION__ #include #endif #ifndef __MACWINDOWS__ #include #endif #if PRAGMA_ONCE #pragma once #endif #ifdef __cplusplus extern "C" { #endif #if PRAGMA_IMPORT #pragma import on #endif #if PRAGMA_STRUCT_ALIGN #pragma options align=mac68k #elif PRAGMA_STRUCT_PACKPUSH #pragma pack(push, 2) #elif PRAGMA_STRUCT_PACK #pragma pack(2) #endif typedef UInt32 NavAskSaveChangesAction; enum { /* input action codes for NavAskSaveChanges() */ kNavSaveChangesClosingDocument = 1, kNavSaveChangesQuittingApplication = 2, kNavSaveChangesOther = 0 }; typedef UInt32 NavAskSaveChangesResult; enum { /* result codes for NavAskSaveChanges() */ kNavAskSaveChangesSave = 1, kNavAskSaveChangesCancel = 2, kNavAskSaveChangesDontSave = 3 }; typedef UInt32 NavAskDiscardChangesResult; enum { /* result codes for NavAskDiscardChanges() */ kNavAskDiscardChanges = 1, kNavAskDiscardChangesCancel = 2 }; typedef SInt16 NavFilterModes; enum { /* which elements are being filtered for objects: */ kNavFilteringBrowserList = 0, kNavFilteringFavorites = 1, kNavFilteringRecents = 2, kNavFilteringShortCutVolumes = 3, kNavFilteringLocationPopup = 4 /* for v1.1 or greater */ }; enum { kNavFileOrFolderVersion = 1 }; struct NavFileOrFolderInfo { UInt16 version; Boolean isFolder; Boolean visible; UInt32 creationDate; UInt32 modificationDate; union { struct { Boolean locked; /* file is locked */ Boolean resourceOpen; /* resource fork is opened */ Boolean dataOpen; /* data fork is opened */ Boolean reserved1; UInt32 dataSize; /* size of the data fork */ UInt32 resourceSize; /* size of the resource fork */ FInfo finderInfo; /* more file info: */ FXInfo finderXInfo; } fileInfo; struct { Boolean shareable; Boolean sharePoint; Boolean mounted; Boolean readable; Boolean writeable; Boolean reserved2; UInt32 numberOfFiles; DInfo finderDInfo; DXInfo finderDXInfo; OSType folderType; /* package type, For struct version >= 1 */ OSType folderCreator; /* package creator, For struct version >= 1 */ char reserved3[206]; } folderInfo; } fileAndFolder; }; typedef struct NavFileOrFolderInfo NavFileOrFolderInfo; union NavEventDataInfo { EventRecord * event; /* for event processing */ void * param; /* points to event specific data */ }; typedef union NavEventDataInfo NavEventDataInfo; struct NavEventData { NavEventDataInfo eventDataParms; /* the event data */ SInt16 itemHit; /* the dialog item number, for v1.1 or greater */ }; typedef struct NavEventData NavEventData; /* * NavDialogRef * * Summary: * Opaque Navigation Services dialog identifier * * Discussion: * A NavDialogRef is an opaque reference to an instance of a * Navigation Services dialog. A new NavDialogRef is returned from * any of the NavCreate*Dialog functions and is later disposed with * the NavDialogDispose function. NavDialogRef is the new name for * the NavContext type, and thus when a client's event proc is * called, the value of the NavCBRec.context field is the same as * the NavDialogRef returned from the corresponding * NavCreate*Dialog. A NavDialogRef is distinct from, and is not * interchangable with, a Dialog Manager DialogRef. */ typedef struct __NavDialog* NavDialogRef; #if CALL_NOT_IN_CARBON /* NavContext is the old name for NavDialogRef */ typedef NavDialogRef NavContext; #endif /* CALL_NOT_IN_CARBON */ /* * NavUserAction * * Summary: * Indicates an action taken by the user * * Discussion: * When the user clicks a button at the bottom of a Nav Services * dialog (or makes an equivalent mouse or key gesture), a * kNavCBUserAction event is sent to the client's event proc * indicating which action was taken. Often, the action also * dismisses the dialog. User action events are only generated when * using dialogs created from a NavCreate*Dialog function. In the * special case of a modeless GetFile dialog (supported only on Mac * OS X), the user can option-click on the open button to keep the * dialog from being dismissed, but the kNavCBUserAction event is * sent so the client can get the reply record and open the selected * files. */ typedef UInt32 NavUserAction; enum { /* * No action taken. The dialog is still running or was terminated * programmatically. */ kNavUserActionNone = 0, /* * The user cancelled the dialog. */ kNavUserActionCancel = 1, /* * The user clicked the Open button in the GetFile dialog. */ kNavUserActionOpen = 2, /* * The user clicked the Save button in the PutFile dialog. */ kNavUserActionSaveAs = 3, /* * The user clicked the Choose button in the ChooseFile, * ChooseFolder, ChooseVolume or ChooseObject dialogs. */ kNavUserActionChoose = 4, /* * The user clicked the New Folder button in the New Folder dialog. */ kNavUserActionNewFolder = 5, /* * The user clicked the Save button in an AskSaveChanges dialog. */ kNavUserActionSaveChanges = 6, /* * The user clicked the Don't Save button in an AskSaveChanges dialog. */ kNavUserActionDontSaveChanges = 7, /* * The user clicked the Discard button in the AskDiscardChanges * dialog. */ kNavUserActionDiscardChanges = 8, /* * The user clicked the Review Unsaved button in the * AskReviewDocuments dialog (used only on Mac OS X). */ kNavUserActionReviewDocuments = 9, /* * The user clicked the Discard Changes button in the * AskReviewDocuments dialog (used only on Mac OS X). */ kNavUserActionDiscardDocuments = 10 }; enum { kNavCBRecVersion = 1 }; /* * NavCBRec * * Summary: * A structure passed to event and preview callbacks * * Discussion: * The NavCBRec structure is passed to the client's event proc or * custom preview proc. It provides information that is specific to * each event type. New for Carbon: the userAction field. */ struct NavCBRec { /* * The version of the struct (currently 1) */ UInt16 version; /* * The NavDialogRef this callback with which this call is associated */ NavDialogRef context; /* * The dialog's window */ WindowRef window; /* * The custom control area rectangle (window coordinates) */ Rect customRect; /* * The custom preview area rectangle (window coordinates) */ Rect previewRect; /* * The event-specific data, including the EventRecord, if any */ NavEventData eventData; /* * The action taken by the user that generated a kNavCBUserAction * event (Carbon dialogs only) */ NavUserAction userAction; /* * Reserved for future use */ char reserved[218]; }; typedef struct NavCBRec NavCBRec; typedef NavCBRec * NavCBRecPtr; /* * NavEventCallbackMessage * * Summary: * Identifies the message type being sent to the client's event proc */ typedef SInt32 NavEventCallbackMessage; enum { /* * An OS event has occurred. A pointer to the EventRecord is in the * eventData.eventDataParms.event field of the NavCBRec. */ kNavCBEvent = 0, /* * Negotiate for custom control space. Client can set change the * customRect field in the NavCBRec to create space for a custom * area. Nav Services will continue to send the kNavCBCustomize * message until the client leaves the customRect field unchanged. */ kNavCBCustomize = 1, /* * This message is sent after custom area negotiation, just before * the dialog is made visible. Add your custom controls when you * receive this message. */ kNavCBStart = 2, /* * This is the last message sent, after the dialog has been hidden. */ kNavCBTerminate = 3, /* * Sent when the dialog has been resized. Check the customRect and or * previewRect values to see if any relayout is needed. Nav Services * automatically moves controls in the custom area. */ kNavCBAdjustRect = 4, /* * The target folder of the dialog has changed. The * NavCBRec.eventData.eventDataParms.param field is an AEDesc* * containing an descriptor of the new location (ususally an FSSpec * or an FSRef). */ kNavCBNewLocation = 5, /* * The target folder has changed to the user's desktop folder. */ kNavCBShowDesktop = 6, /* * The user has selected or deselected a file or folder. The * NavCBRec.eventData.eventDataParms.param field is an AEDescList* * identifying the currently selected items. */ kNavCBSelectEntry = 7, /* * The value of the Show/Format popup menu has changed. The * NavCBRec.eventData.eventDataParms.param is a NavMenuItemSpec* * identifying the menu item selected. If the dialog was created * using the Carbon-only NavCreate*Dialog APIs, then the menuType * field of the NavMenuItemSpec is set to the index into the client's * CFArray of popupExtension strings (see NavDialogCreationOptions). */ kNavCBPopupMenuSelect = 8, /* * Sent when the user has accepted (Open, Save, etc.). */ kNavCBAccept = 9, /* * Sent when the user has cancelled the dialog. */ kNavCBCancel = 10, /* * The custom preview area state has changed. The * NavCBRec.eventData.eventDataParms.param is a Boolean* set to true * if the preview area is visible or false if it is not. */ kNavCBAdjustPreview = 11, /* * The user has taken one of the actions described in the * NavUserAction definition. The action may or may not dismiss the * dialog. The NavCBRec.userAction field indicates which action was * taken (Carbon dialogs only). */ kNavCBUserAction = 12, /* * The user has opened a folder or chosen a file. The client can * block navigation or dismissal by setting the appropriate action * state with the kNavCtlSetActionState NavCustomControl selector. */ kNavCBOpenSelection = (long)0x80000000 }; typedef void * NavCallBackUserData; /* for events and customization: */ typedef CALLBACK_API( void , NavEventProcPtr )(NavEventCallbackMessage callBackSelector, NavCBRecPtr callBackParms, void *callBackUD); /* for preview support: */ typedef CALLBACK_API( Boolean , NavPreviewProcPtr )(NavCBRecPtr callBackParms, void *callBackUD); /* filtering callback information: */ typedef CALLBACK_API( Boolean , NavObjectFilterProcPtr )(AEDesc *theItem, void *info, void *callBackUD, NavFilterModes filterMode); typedef STACK_UPP_TYPE(NavEventProcPtr) NavEventUPP; typedef STACK_UPP_TYPE(NavPreviewProcPtr) NavPreviewUPP; typedef STACK_UPP_TYPE(NavObjectFilterProcPtr) NavObjectFilterUPP; /* * NewNavEventUPP() * * Availability: * Non-Carbon CFM: available as macro/inline * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API_C( NavEventUPP ) NewNavEventUPP(NavEventProcPtr userRoutine); #if !OPAQUE_UPP_TYPES enum { uppNavEventProcInfo = 0x00000FC0 }; /* pascal no_return_value Func(4_bytes, 4_bytes, 4_bytes) */ #ifdef __cplusplus inline DEFINE_API_C(NavEventUPP) NewNavEventUPP(NavEventProcPtr userRoutine) { return (NavEventUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppNavEventProcInfo, GetCurrentArchitecture()); } #else #define NewNavEventUPP(userRoutine) (NavEventUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppNavEventProcInfo, GetCurrentArchitecture()) #endif #endif /* * NewNavPreviewUPP() * * Availability: * Non-Carbon CFM: available as macro/inline * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API_C( NavPreviewUPP ) NewNavPreviewUPP(NavPreviewProcPtr userRoutine); #if !OPAQUE_UPP_TYPES enum { uppNavPreviewProcInfo = 0x000003D0 }; /* pascal 1_byte Func(4_bytes, 4_bytes) */ #ifdef __cplusplus inline DEFINE_API_C(NavPreviewUPP) NewNavPreviewUPP(NavPreviewProcPtr userRoutine) { return (NavPreviewUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppNavPreviewProcInfo, GetCurrentArchitecture()); } #else #define NewNavPreviewUPP(userRoutine) (NavPreviewUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppNavPreviewProcInfo, GetCurrentArchitecture()) #endif #endif /* * NewNavObjectFilterUPP() * * Availability: * Non-Carbon CFM: available as macro/inline * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API_C( NavObjectFilterUPP ) NewNavObjectFilterUPP(NavObjectFilterProcPtr userRoutine); #if !OPAQUE_UPP_TYPES enum { uppNavObjectFilterProcInfo = 0x00002FD0 }; /* pascal 1_byte Func(4_bytes, 4_bytes, 4_bytes, 2_bytes) */ #ifdef __cplusplus inline DEFINE_API_C(NavObjectFilterUPP) NewNavObjectFilterUPP(NavObjectFilterProcPtr userRoutine) { return (NavObjectFilterUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppNavObjectFilterProcInfo, GetCurrentArchitecture()); } #else #define NewNavObjectFilterUPP(userRoutine) (NavObjectFilterUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppNavObjectFilterProcInfo, GetCurrentArchitecture()) #endif #endif /* * DisposeNavEventUPP() * * Availability: * Non-Carbon CFM: available as macro/inline * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API_C( void ) DisposeNavEventUPP(NavEventUPP userUPP); #if !OPAQUE_UPP_TYPES #ifdef __cplusplus inline DEFINE_API_C(void) DisposeNavEventUPP(NavEventUPP userUPP) { DisposeRoutineDescriptor((UniversalProcPtr)userUPP); } #else #define DisposeNavEventUPP(userUPP) DisposeRoutineDescriptor(userUPP) #endif #endif /* * DisposeNavPreviewUPP() * * Availability: * Non-Carbon CFM: available as macro/inline * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API_C( void ) DisposeNavPreviewUPP(NavPreviewUPP userUPP); #if !OPAQUE_UPP_TYPES #ifdef __cplusplus inline DEFINE_API_C(void) DisposeNavPreviewUPP(NavPreviewUPP userUPP) { DisposeRoutineDescriptor((UniversalProcPtr)userUPP); } #else #define DisposeNavPreviewUPP(userUPP) DisposeRoutineDescriptor(userUPP) #endif #endif /* * DisposeNavObjectFilterUPP() * * Availability: * Non-Carbon CFM: available as macro/inline * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API_C( void ) DisposeNavObjectFilterUPP(NavObjectFilterUPP userUPP); #if !OPAQUE_UPP_TYPES #ifdef __cplusplus inline DEFINE_API_C(void) DisposeNavObjectFilterUPP(NavObjectFilterUPP userUPP) { DisposeRoutineDescriptor((UniversalProcPtr)userUPP); } #else #define DisposeNavObjectFilterUPP(userUPP) DisposeRoutineDescriptor(userUPP) #endif #endif /* * InvokeNavEventUPP() * * Availability: * Non-Carbon CFM: available as macro/inline * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API_C( void ) InvokeNavEventUPP( NavEventCallbackMessage callBackSelector, NavCBRecPtr callBackParms, void * callBackUD, NavEventUPP userUPP); #if !OPAQUE_UPP_TYPES #ifdef __cplusplus inline DEFINE_API_C(void) InvokeNavEventUPP(NavEventCallbackMessage callBackSelector, NavCBRecPtr callBackParms, void * callBackUD, NavEventUPP userUPP) { CALL_THREE_PARAMETER_UPP(userUPP, uppNavEventProcInfo, callBackSelector, callBackParms, callBackUD); } #else #define InvokeNavEventUPP(callBackSelector, callBackParms, callBackUD, userUPP) CALL_THREE_PARAMETER_UPP((userUPP), uppNavEventProcInfo, (callBackSelector), (callBackParms), (callBackUD)) #endif #endif /* * InvokeNavPreviewUPP() * * Availability: * Non-Carbon CFM: available as macro/inline * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API_C( Boolean ) InvokeNavPreviewUPP( NavCBRecPtr callBackParms, void * callBackUD, NavPreviewUPP userUPP); #if !OPAQUE_UPP_TYPES #ifdef __cplusplus inline DEFINE_API_C(Boolean) InvokeNavPreviewUPP(NavCBRecPtr callBackParms, void * callBackUD, NavPreviewUPP userUPP) { return (Boolean)CALL_TWO_PARAMETER_UPP(userUPP, uppNavPreviewProcInfo, callBackParms, callBackUD); } #else #define InvokeNavPreviewUPP(callBackParms, callBackUD, userUPP) (Boolean)CALL_TWO_PARAMETER_UPP((userUPP), uppNavPreviewProcInfo, (callBackParms), (callBackUD)) #endif #endif /* * InvokeNavObjectFilterUPP() * * Availability: * Non-Carbon CFM: available as macro/inline * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API_C( Boolean ) InvokeNavObjectFilterUPP( AEDesc * theItem, void * info, void * callBackUD, NavFilterModes filterMode, NavObjectFilterUPP userUPP); #if !OPAQUE_UPP_TYPES #ifdef __cplusplus inline DEFINE_API_C(Boolean) InvokeNavObjectFilterUPP(AEDesc * theItem, void * info, void * callBackUD, NavFilterModes filterMode, NavObjectFilterUPP userUPP) { return (Boolean)CALL_FOUR_PARAMETER_UPP(userUPP, uppNavObjectFilterProcInfo, theItem, info, callBackUD, filterMode); } #else #define InvokeNavObjectFilterUPP(theItem, info, callBackUD, filterMode, userUPP) (Boolean)CALL_FOUR_PARAMETER_UPP((userUPP), uppNavObjectFilterProcInfo, (theItem), (info), (callBackUD), (filterMode)) #endif #endif #if CALL_NOT_IN_CARBON || OLDROUTINENAMES /* support for pre-Carbon UPP routines: New...Proc and Call...Proc */ #define NewNavEventProc(userRoutine) NewNavEventUPP(userRoutine) #define NewNavPreviewProc(userRoutine) NewNavPreviewUPP(userRoutine) #define NewNavObjectFilterProc(userRoutine) NewNavObjectFilterUPP(userRoutine) #define CallNavEventProc(userRoutine, callBackSelector, callBackParms, callBackUD) InvokeNavEventUPP(callBackSelector, callBackParms, callBackUD, userRoutine) #define CallNavPreviewProc(userRoutine, callBackParms, callBackUD) InvokeNavPreviewUPP(callBackParms, callBackUD, userRoutine) #define CallNavObjectFilterProc(userRoutine, theItem, info, callBackUD, filterMode) InvokeNavObjectFilterUPP(theItem, info, callBackUD, filterMode, userRoutine) #endif /* CALL_NOT_IN_CARBON */ typedef SInt32 NavCustomControlMessage; 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, /* query preview status, parms<-Boolean */ kNavCtlAddControl = 18, /* add one control to dialog, parms->ControlHandle */ kNavCtlAddControlList = 19, /* add control list to dialog, parms->Handle (DITL rsrc) */ kNavCtlGetFirstControlID = 20, /* get 1st control ID, parms<-UInt16 */ kNavCtlSelectCustomType = 21, /* select a custom menu item parms->NavMenuItemSpec* */ kNavCtlSelectAllType = 22, /* select an "All" menu item parms->SInt16 */ kNavCtlGetEditFileName = 23, /* get save dlog's file name parms<-StringPtr */ kNavCtlSetEditFileName = 24, /* set save dlog's file name parms->StringPtr */ kNavCtlSelectEditFileName = 25, /* select save dlog file name parms->ControlEditTextSelectionRec*, v1.1 or greater */ kNavCtlBrowserSelectAll = 26, /* re-scan the browser list parms = nil, v2.0 or greater */ kNavCtlGotoParent = 27, /* navigate to parent parms = nil, v2.0 or greater */ kNavCtlSetActionState = 28, /* restrict navigation parms->NavActionState (flags), v2.0 or greater */ kNavCtlBrowserRedraw = 29, /* rescan browser list parms = nil, v2.0 or greater */ kNavCtlTerminate = 30 /* terminate/dismiss dialog parms = nil, v2.0 or greater */ }; typedef UInt32 NavActionState; enum { kNavNormalState = 0x00000000, /* normal/default state */ kNavDontOpenState = 0x00000001, /* disallow opening files/folders */ kNavDontSaveState = 0x00000002, /* disallow saving files */ kNavDontChooseState = 0x00000004, /* disallow choosing objects */ kNavDontNewFolderState = 0x00000010 /* disallow creating new folders */ }; typedef UInt16 NavPopupMenuItem; enum { kNavAllKnownFiles = 0, kNavAllReadableFiles = 1, kNavAllFiles = 2 }; typedef UInt16 NavSortKeyField; enum { kNavSortNameField = 0, kNavSortDateField = 1 }; typedef UInt16 NavSortOrder; enum { kNavSortAscending = 0, kNavSortDescending = 1 }; typedef UInt32 NavDialogOptionFlags; enum { 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 preview to show */ 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 the dialog select "All Readable Documents" on open */ kNavSupportPackages = 0x00001000, /* recognize file system packages, v2.0 or greater */ kNavAllowOpenPackages = 0x00002000, /* allow opening of packages, v2.0 or greater */ kNavDontAddRecents = 0x00004000, /* don't add chosen objects to the recents list, v2.0 or greater */ kNavDontUseCustomFrame = 0x00008000, /* don't draw the custom area bevel frame, v2.0 or greater */ kNavDontConfirmReplacement = 0x00010000, /* don't show the "Replace File?" alert on save conflict, v3.0 or greater */ kNavPreserveSaveFileExtension = 0x00020000 /* extension in default file name is preserved and initially hidden, v3.1 or greater */ }; typedef UInt32 NavTranslationOptions; enum { kNavTranslateInPlace = 0, /* translate in place, replacing translation source file (default for Save) */ kNavTranslateCopy = 1 /* translate to a copy of the source file (default for Open) */ }; enum { kNavMenuItemSpecVersion = 0 }; struct NavMenuItemSpec { UInt16 version; OSType menuCreator; OSType menuType; Str255 menuItemName; char reserved[245]; }; typedef struct NavMenuItemSpec NavMenuItemSpec; typedef NavMenuItemSpec * NavMenuItemSpecArrayPtr; typedef NavMenuItemSpecArrayPtr * NavMenuItemSpecArrayHandle; typedef NavMenuItemSpecArrayPtr NavMenuItemSpecPtr; typedef NavMenuItemSpecArrayHandle NavMenuItemSpecHandle; enum { kNavGenericSignature = FOUR_CHAR_CODE('****') }; struct NavTypeList { OSType componentSignature; short reserved; short osTypeCount; OSType osType[1]; }; typedef struct NavTypeList NavTypeList; typedef NavTypeList * NavTypeListPtr; typedef NavTypeListPtr * NavTypeListHandle; enum { kNavDialogOptionsVersion = 0 }; struct NavDialogOptions { UInt16 version; NavDialogOptionFlags dialogOptionFlags; /* option flags for affecting the dialog's behavior */ Point location; /* top-left location of the dialog, or {-1,-1} for default position */ Str255 clientName; Str255 windowTitle; Str255 actionButtonLabel; /* label of the default button (or null string for default) */ Str255 cancelButtonLabel; /* label of the cancel button (or null string for default) */ Str255 savedFileName; /* default name for text box in NavPutFile (or null string for default) */ Str255 message; /* custom message prompt (or null string for default) */ UInt32 preferenceKey; /* a key for to managing preferences for using multiple utility dialogs */ NavMenuItemSpecArrayHandle popupExtension; /* extended popup menu items, an array of NavMenuItemSpecs */ char reserved[494]; }; typedef struct NavDialogOptions NavDialogOptions; enum { kNavReplyRecordVersion = 2 }; /* * NavReplyRecord * * Summary: * A structure describing the results of a Nav Services dialog * * Discussion: * A reply record is the result of a Nav Services file dialog. Using * the older API, which is always modal, the client passes the * address of a reply record when invoking the dialog. In the Carbon * API, dialogs may also be window modal or modeless, so the client * requests the reply record by calling NavDialogGetReply when a * kNavCBUserAction event is received. Either way, a reply record * should be disposed of using NavDisposeReply. */ struct NavReplyRecord { /* * The version of the structure. The first public version of the * structure was version 0. Fields added after version 0, starting * with the saveFileName field, are noted below. */ UInt16 version; /* * True if the reply contains a non-null selection */ Boolean validRecord; /* * True if this reply is from a PutFile dialog and the file to be * saved already exists and needs to be replaced. The user has * already been warned unless the kNavDontConfirmReplacement option * flag is used. */ Boolean replacing; /* * True if this reply is from a PutFile dialog and the user wants to * save the file as stationery. */ Boolean isStationery; /* * True if translation was performed on the file(s) to be opened or * if transtlation will be needed on the file to be saved. */ Boolean translationNeeded; /* * For GetFile or Choose dialogs, a list of items chosen by the user. * For the older NavPutFile dialog, a list containing one item: an * FSSpec of the file to be saved. ** IMPORTANT NOTE *** For the new * Carbon-only PutFile dialog created with NavCreatePutFileDialog, * the selection is a list containing one item: the DIRECTORY where * the file is to be saved. The file name is obtained from the * saveFileName field. When using the original modal API, each * descriptor will contain an FSSpec (typeFSS). When using the new * Carbon-only dialogs created via the NavCreate*Dialog functions, * each descriptor could contain either an FSSpec (typeFSS, used on * Mac OS 8 or 9) or an FSRef (typeFSRef, used on Mac OS X). This * divergence is caused by the need to use FSRef (for Unicode/HFS+ * support) on Mac OS X, while being unable to provide FSRefs on Mac * OS 8.6. */ AEDescList selection; /* * For NavPutFile: the script system associated with the name of the * file to be saved. */ ScriptCode keyScript; /* * A handle to an array of type FileTranslationSpec. Each array entry * corresponds to an item in the selection and describes the * translation that was performed (GetFile) or needs to be performed * (PutFile) on that item. */ FileTranslationSpecArrayHandle fileTranslation; /* * Reserved for private use. */ UInt32 reserved1; /* * Carbon PutFile dialog only: the name of the file to be saved. This * field contains the true file name to saved, even if the extension * will be hidden from the user. This field was added in structure * version 1. */ CFStringRef saveFileName; /* * The extension on the name of the saved file should be hidden. Once * the file has been saved, the client should call NavCompleteSave. * NavCompleteSave will take care of hiding the extension on the * file. However, the client needs to know that the extension is * hidden so that it can display the document name correctly in the * UI, such as in window titles and menus. This field is only used if * the client has r equested extension preservation using the * kNavPreserveSaveFileExtension dialog option flag. This field was * added in structure version 2. */ Boolean saveFileExtensionHidden; /* * Reserved for future use. */ UInt8 reserved2; /* * Reserved for future use. */ char reserved[225]; }; typedef struct NavReplyRecord NavReplyRecord; /* * NavLoad() * * Availability: * Non-Carbon CFM: in NavigationLib 1.0 and later * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: not available */ EXTERN_API( OSErr ) NavLoad(void); /* * NavUnload() * * Availability: * Non-Carbon CFM: in NavigationLib 1.0 and later * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: not available */ EXTERN_API( OSErr ) NavUnload(void); /* * NavLibraryVersion() * * Availability: * Non-Carbon CFM: in NavigationLib 1.0 and later * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API( UInt32 ) NavLibraryVersion(void); /* * NavGetDefaultDialogOptions() * * Availability: * Non-Carbon CFM: in NavigationLib 1.0 and later * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API( OSErr ) NavGetDefaultDialogOptions(NavDialogOptions * dialogOptions); /* * NavGetFile() * * Availability: * Non-Carbon CFM: in NavigationLib 1.0 and later * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API( OSErr ) NavGetFile( AEDesc * defaultLocation, /* can be NULL */ NavReplyRecord * reply, NavDialogOptions * dialogOptions, /* can be NULL */ NavEventUPP eventProc, /* can be NULL */ NavPreviewUPP previewProc, /* can be NULL */ NavObjectFilterUPP filterProc, /* can be NULL */ NavTypeListHandle typeList, /* can be NULL */ void * callBackUD); /* can be NULL */ /* * NavPutFile() * * Availability: * Non-Carbon CFM: in NavigationLib 1.0 and later * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API( OSErr ) NavPutFile( AEDesc * defaultLocation, /* can be NULL */ NavReplyRecord * reply, NavDialogOptions * dialogOptions, /* can be NULL */ NavEventUPP eventProc, /* can be NULL */ OSType fileType, OSType fileCreator, void * callBackUD); /* can be NULL */ /* * NavAskSaveChanges() * * Availability: * Non-Carbon CFM: in NavigationLib 1.0 and later * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API( OSErr ) NavAskSaveChanges( NavDialogOptions * dialogOptions, NavAskSaveChangesAction action, NavAskSaveChangesResult * reply, NavEventUPP eventProc, /* can be NULL */ void * callBackUD); /* can be NULL */ /* * NavCustomAskSaveChanges() * * Availability: * Non-Carbon CFM: in NavigationLib 1.0 and later * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API( OSErr ) NavCustomAskSaveChanges( NavDialogOptions * dialogOptions, NavAskSaveChangesResult * reply, NavEventUPP eventProc, /* can be NULL */ void * callBackUD); /* can be NULL */ /* * NavAskDiscardChanges() * * Availability: * Non-Carbon CFM: in NavigationLib 1.0 and later * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API( OSErr ) NavAskDiscardChanges( NavDialogOptions * dialogOptions, NavAskDiscardChangesResult * reply, NavEventUPP eventProc, /* can be NULL */ void * callBackUD); /* can be NULL */ /* * NavChooseFile() * * Availability: * Non-Carbon CFM: in NavigationLib 1.0 and later * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API( OSErr ) NavChooseFile( AEDesc * defaultLocation, /* can be NULL */ NavReplyRecord * reply, NavDialogOptions * dialogOptions, /* can be NULL */ NavEventUPP eventProc, /* can be NULL */ NavPreviewUPP previewProc, /* can be NULL */ NavObjectFilterUPP filterProc, /* can be NULL */ NavTypeListHandle typeList, /* can be NULL */ void * callBackUD); /* can be NULL */ /* * NavChooseFolder() * * Availability: * Non-Carbon CFM: in NavigationLib 1.0 and later * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API( OSErr ) NavChooseFolder( AEDesc * defaultLocation, /* can be NULL */ NavReplyRecord * reply, NavDialogOptions * dialogOptions, /* can be NULL */ NavEventUPP eventProc, /* can be NULL */ NavObjectFilterUPP filterProc, /* can be NULL */ void * callBackUD); /* can be NULL */ /* * NavChooseVolume() * * Availability: * Non-Carbon CFM: in NavigationLib 1.0 and later * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API( OSErr ) NavChooseVolume( AEDesc * defaultSelection, /* can be NULL */ NavReplyRecord * reply, NavDialogOptions * dialogOptions, /* can be NULL */ NavEventUPP eventProc, /* can be NULL */ NavObjectFilterUPP filterProc, /* can be NULL */ void * callBackUD); /* can be NULL */ /* * NavChooseObject() * * Availability: * Non-Carbon CFM: in NavigationLib 1.0 and later * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API( OSErr ) NavChooseObject( AEDesc * defaultLocation, /* can be NULL */ NavReplyRecord * reply, NavDialogOptions * dialogOptions, /* can be NULL */ NavEventUPP eventProc, /* can be NULL */ NavObjectFilterUPP filterProc, /* can be NULL */ void * callBackUD); /* can be NULL */ /* * NavNewFolder() * * Availability: * Non-Carbon CFM: in NavigationLib 1.0 and later * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API( OSErr ) NavNewFolder( AEDesc * defaultLocation, /* can be NULL */ NavReplyRecord * reply, NavDialogOptions * dialogOptions, /* can be NULL */ NavEventUPP eventProc, /* can be NULL */ void * callBackUD); /* can be NULL */ /* * NavTranslateFile() * * Availability: * Non-Carbon CFM: in NavigationLib 1.0 and later * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API( OSErr ) NavTranslateFile( NavReplyRecord * reply, NavTranslationOptions howToTranslate); /* * NavCompleteSave() * * Availability: * Non-Carbon CFM: in NavigationLib 1.0 and later * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API( OSErr ) NavCompleteSave( NavReplyRecord * reply, NavTranslationOptions howToTranslate); /* * NavCustomControl() * * Availability: * Non-Carbon CFM: in NavigationLib 1.0 and later * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API( OSErr ) NavCustomControl( NavDialogRef dialog, NavCustomControlMessage selector, void * parms); /* * NavCreatePreview() * * Availability: * Non-Carbon CFM: in NavigationLib 2.0 and later * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API( OSErr ) NavCreatePreview( AEDesc * theObject, OSType previewDataType, const void * previewData, Size previewDataSize); /* * NavDisposeReply() * * Availability: * Non-Carbon CFM: in NavigationLib 1.0 and later * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API( OSErr ) NavDisposeReply(NavReplyRecord * reply); /* * NavServicesCanRun() * * Availability: * Non-Carbon CFM: in NavigationLib 1.0 and later * CarbonLib: in CarbonLib 1.0 and later * Mac OS X: not available */ EXTERN_API( Boolean ) NavServicesCanRun(void); #if TARGET_RT_MAC_CFM #ifdef __cplusplus inline pascal Boolean NavServicesAvailable() { return ((NavLibraryVersion != (void*)kUnresolvedCFragSymbolAddress) && NavServicesCanRun()); } #else #define NavServicesAvailable() ((NavLibraryVersion != (void*)kUnresolvedCFragSymbolAddress) && NavServicesCanRun()) #endif #elif TARGET_RT_MAC_MACHO /* Navigation is always available on OS X */ #ifdef __cplusplus inline pascal Boolean NavServicesAvailable() { return true; } #else #define NavServicesAvailable() (true) #endif #else /* NavServicesAvailable() is implemented in Navigation.o for classic 68K clients*/ #if CALL_NOT_IN_CARBON /* * NavServicesAvailable() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: not available */ EXTERN_API( Boolean ) NavServicesAvailable(void); #endif /* CALL_NOT_IN_CARBON */ #endif /* */ #if PRAGMA_STRUCT_ALIGN #pragma options align=reset #elif PRAGMA_STRUCT_PACKPUSH #pragma pack(pop) #elif PRAGMA_STRUCT_PACK #pragma pack() #endif #ifdef PRAGMA_IMPORT_OFF #pragma import off #elif PRAGMA_IMPORT #pragma import reset #endif #ifdef __cplusplus } #endif #endif /* __NAVIGATION__ */