NavCustomControlMessage

Header: Navigation.h

enum NavCustomControlMessage {
    kNavCtlShowDesktop = ,
    kNavCtlSortBy = 1,
    kNavCtlSortOrder = 2,
    kNavCtlScrollHome = 3,
    kNavCtlScrollEnd = 4,
    kNavCtlPageUp = 5,
    kNavCtlPageDown = 6,
    kNavCtlGetLocation = 7,
    kNavCtlSetLocation = 8,
    kNavCtlGetSelection = 9,
    kNavCtlSetSelection = 10,
    kNavCtlShowSelection = 11,
    kNavCtlOpenSelection = 12,
    kNavCtlEjectVolume = 13,
    kNavCtlNewFolder = 14,
    kNavCtlCancel = 15,
    kNavCtlAccept = 16,
    kNavCtlIsPreviewShowing = 17,
    kNavCtlAddControl = 18,
    kNavCtlAddControlList = 19,
    kNavCtlGetFirstControlID = 20,
    kNavCtlSelectCustomType = 21,
    kNavCtlSelectAllType = 22,
    kNavCtlGetEditFileName = 23,
    kNavCtlSetEditFileName = 24,
    kNavCtlSelectEditFileName = 25,
    kNavCtlBrowserSelectAll = 26,
    kNavCtlGotoParent = 27,
    kNavCtlSetActionState = 28,
    kNavCtlBrowserRedraw = 29,
    kNavCtlTerminate = 30
};

Constant descriptions

kNavCtlShowDesktop

Tells Navigation Services to change the browser list location to the desktop.

kNavCtlSortBy

Alerts Navigation Services that your application is setting a sort key in the browser list. In addition to the kNavCtlSortBy constant, your application passes one of the NavSortKeyField constants in the parms parameter of the function NavCustomControl. For a description of the NavSortKeyField constants, see “File Sorting Constants”.

kNavCtlSortOrder

Alerts Navigation Services that your application is setting sort order, either ascending or descending, in the browser list. In addition to passing the kNavCtlSortOrder constant, your application must pass one of the NavSortOrder constants in the parms parameter of the NavCustomControl function. For a description of the NavSortOrder constants, see “Sort Order Constants”.

kNavCtlScrollHome

Tells Navigation Services to scroll the browser to the top of the file list.

kNavCtlScrollEnd

Tells Navigation Services to scroll the browser to the bottom of the file list.

kNavCtlPageUp

Tells Navigation Services to scroll the browser up one page length as a result of the user clicking the scroll bar above the scroll box.

kNavCtlPageDown

Tells Navigation Services to scroll the browser down one page length as a result of the user clicking the scroll bar below the scroll box.

kNavCtlGetLocation

Tells Navigation Services to return the current location. Navigation Services reports the current location by setting a pointer to an AEDesc structure in the param field of the structure of type NavCBRec that you specified in your event-handling function. For more information on parsing AEDesc structures, see “Obtaining Object Descriptions”.

kNavCtlSetLocation

Tells Navigation Services that your application wishes to set the location being viewed in the browser list. In addition to specifying the kNavCtlSetLocation constant, your application passes a pointer to an AEDesc structure describing the new location in the parms parameter of the NavCustomControl function.

kNavCtlGetSelection

Tells Navigation Services to return the selected item or items in the browser. When you specify this constant, Navigation Services returns a pointer to an AEDesc structure describing the selected item(s) in the param field of the structure of type NavCBRec that you specified in your event-handling function. For more information on parsing AEDescList structures, see “Obtaining Object Descriptions”. If the user deselects the current selection, the AEDescList returned by Navigation Services contains an empty reference. You can account for this case by using the function AECountItems and checking for a zero count.

kNavCtlSetSelection

Tells Navigation Services to change the browser list selection. In addition to specifying the kNavCtlSetSelection constant, your application must pass a pointer to an AEDescList structure describing the selection in the parms parameter of the NavCustomControl function. If you want to deselect the current selection without making a new selection, pass NULL for the pointer.Note: If you specify this constant, Navigation Services notifies your event-handling function by setting the kNavCBSelectEntry constant twice: once when the previous selection is deselected, and once when the new selection is made.

kNavCtlShowSelection

Tells Navigation Services to make the current selection visible in the browser list if the selection has been scrolled out of sight by the user.

kNavCtlOpenSelection

Tells Navigation Services to open the current selection.

kNavCtlEjectVolume

Tells Navigation Services to eject a volume. In addition to specifying this constant, you pass a pointer to the volume reference number (vRefNum) of the volume to be ejected in the parms parameter of the NavCustomControl function.

kNavCtlNewFolder

Tells Navigation Services to create a new folder in the current browser location. In addition to specifying the kNavCtlNewFolder constant, your application passes a string representing the name of the new folder in the parms parameter of the NavCustomControl function.

kNavCtlCancel

Tells Navigation Services to dismiss the Open or Save dialog box as if the user had pressed the Cancel button.

kNavCtlAccept

Tells Navigation Services to close the Open or Save dialog box as if the user had pressed the Open or Save button. Navigation Services does not act on this constant if there is no current selection.

kNavCtlIsPreviewShowing

Asks Navigation Services if the preview area is currently available. If you specify this constant, Navigation Services sets a pointer to a Boolean value in the param field of the structure of type NavCBRec that you specified in your event-handling function. This value is true if the preview area is available, false otherwise.

kNavCtlAddControl

Tells Navigation Services to add one application-defined control to Open or Save dialog boxes. In addition to sending this message, your application passes a control handle in the parms parameter of the NavCustomControl function. Design the control in local coordinates.

Note: To avoid any unnecessary flickering or redrawing, ensure the control is initially invisible before specifying this constant. You may set the control to visible after Navigation Services supplies the kNavCBStart constant, described in “Event Message Constants”, in the param field of the structure of type NavCBRec. If the user resizes the dialog box, your application must move the control because it is not maintained by Navigation Services. If you use the kNavCtlAddControlList constant (described next) and you supply a 'DITL' resource, you avoid the need to move the control yourself.

kNavCtlAddControlList

Tells Navigation Services to add a list of application-defined dialog box items to Open or Save dialog boxes. In addition to specifying this constant, your application passes a handle to a dialog box item list or 'DITL' resource in the parms parameter of the NavCustomControl function. Design the 'DITL' resource in local coordinates. Navigation Services adds the custom items relative to the upper left corner of the customization area. If the user resizes the dialog box, your custom items are moved automatically.

kNavCtlGetFirstControlID

Asks Navigation Services to help you identify the first custom control in the dialog box, in order to determine which custom control item was selected by the user. Navigation Services returns a pointer to a 16-bit integer that indicates the item number of the first custom control in the param field of the structure of type NavCBRec that you specified in your event-handling function. In your event-handling function, use the Dialog Manager function FindDialogItem to find out which item was selected. The FindDialogItem function returns 0 for the first item, 1 for the second and so on. To get the proper item number, add 1 to the FindDialogItem function result. The Open or Save dialog box’s standard controls precede yours, so use the formula (itemHit - yourFirstItem + 1) to determine which of your items was selected. Your application should not depend on any hardcoded value for the number of items, since this value is likely to change in the future.

Be sure to test the result from FindDialogItem to ensure that it describes a control that you defined. Your application must not respond to any controls that do not belong to it.

kNavCtlSelectCustomType

Tells Navigation Services to set one of your custom menu items in the Show pop-up menu or the Format pop-up menu as the default selection. This is useful if you want to override the default pop-up menu selection. In addition to specifying this constant, pass a pointer to a structure of type NavMenuItemSpec in the parms parameter of the NavCustomControl function. This structure describes the item you wish to have selected. For more information on providing custom menu items, see “Customizing Type Pop-up Menus”.

kNavCtlSelectAllType

Tells Navigation Services to override the default menu item in the Type pop-up menu. By specifying one of the NavPopupMenuItem constants, described in “Menu Item Selection Constants”, in the parms parameter of the NavCustomControl function, you can set the default item to All Documents, All Readable Documents or All Documents.

kNavCtlGetEditFileName

Tells Navigation Services to return the name of the file to be saved by the function NavPutFile. This would be useful if you wanted to automatically add an extension to the filename, for example. When you send this message, the parms parameter of the NavCustomControl function returns a StringPtr to a Pascal string containing the filename.

kNavCtlSetEditFileName

Tells Navigation Services that your application wishes to set the name of the file to be saved by the function NavPutFile. Your application normally specifies the KNavCtlSetEditFileName constant after modifying the filename obtained by specifying the kNavCtlGetEditFileName constant. In addition to specifying the kNavCtlSetEditFileName constant, your application passes a StringPtr to a Pascal string containing the filename in the parms parameter of the NavCustomControl function.

kNavCtlSelectEditFileName

(Navigation Services 1.1 or later) Tells Navigation Services to display the name of the file to be saved by the function NavPutFile with some or all of the filename string highlighted for selection. In addition to specifying the kNavCtlSelectEditFileName constant, your application passes a Control Manager structure of type ControlEditTextSelectionRec in the parms parameter of the NavCustomControl function in order to specify which part of the filename string to highlight. For more information on the ControlEditTextSelectionRec structure, see Mac OS 8 Control Manager Reference.

kNavCtlBrowserSelectAll

(Navigation Services 2.0 or later.) Tells Navigation Services to select all files in the browser list.

kNavCtlGotoParent

(Navigation Services 2.0 or later.) Tells Navigation Services to navigate to the parent folder or volume of the current selection.

kNavCtlSetActionState

(Navigation Services 2.0 or later.) Prevents Navigation Services from handling certain user actions, such as opening or saving files. This is useful if you want to prevent the dismissal of a dialog box until certain conditions are met, for example. Specify which actions to prevent by passing one or more of the constants defined by the NavActionState enumeration, described in “Action State Constants”. For more information, see “Handling Events”.

kNavCtlBrowserRedraw

(Navigation Services 2.0 or later.) Tells Navigation Services to refresh the browser list.

kNavCtlTerminate

(Navigation Services 2.0 or later.) Tells Navigation Services to dismiss the current dialog box. This constant is similar to kNavCtlCancel, except that using kNavCtlTerminate does not return an error code.