Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Menu Manager Reference

Framework
Carbon/Carbon.h
Declared in
Menus.h

Overview

You can use the Menu Manager to create and manage the menus in your application. Menus allow the user to view or choose from a list of choices and commands that your application provides. All Mac OS applications should provide these standard menus: the Application menu, the File menu, and the Edit menu.

Carbon supports the Menu Manager, with the following changes:

Functions by Task

Function descriptions are grouped by the tasks for which you use the functions. For an alphabetical list of functions, go to the API index at the end of the document.

Creating and Disposing of Menus

Manipulating the Root Menu

Manipulating the Menu Bar

Adding and Removing Menus

Manipulating and Accessing Menu Characteristics

Drawing Menus and Menu Items

Adding and Deleting Menu Items

Associating Data With Menu Items

Enabling Menus and Menu Items

Manipulating Menu Item Text

Manipulating and Accessing Menu Item Characteristics

Responding to Menu Events and User Selections

Handling Contextual Menu Plugins

Obsolete Functions

Functions

AcquireRootMenu

Get the menu whose contents are displayed in the menubar.

MenuRef AcquireRootMenu (
   void
);

Return Value

The current root menu. See page for a description of the MenuRef data type. If no root menu currently exists, the Menu Manager creates one and returns its menu reference.

Discussion

This function increments the reference count of the root menu. The caller should call ReleaseMenu when done with the menu.

Availability
Declared In
Menus.h

AppendMenuItemTextWithCFString

Appends a new menu item with text from a CFString.

OSStatus AppendMenuItemTextWithCFString (
   MenuRef inMenu,
   CFStringRef inString,
   MenuItemAttributes inAttributes,
   MenuCommand inCommandID,
   MenuItemIndex *outNewItem
);

Parameters
menu

The menu to which to append the new item.

inString

The text of the new item.

inAttributes

The attributes of the new item.

inCommandID

The command ID of the new item.

outNewItem

On exit, the index of the new item. May be NULL if the caller does not need this information.

Return Value

A result code. See “Menu Manager Result Codes.”

Discussion

The Menu Manager will make its own copy of the CFString before returning from this function. Modifying the string after calling AppendMenuItemTextWithCFString will have no effect on the menu item's actual text. The caller may release the string after the call.

Availability
Declared In
Menus.h

CalcMenuSize

Recalculates the horizontal and vertical dimensions of a menu.

void CalcMenuSize (
   MenuRef theMenu
);

Parameters
theMenu

The menu whose dimensions need recalculating.

Discussion

The CalcMenuSize function uses the menu definition function of the specified menu to calculate the dimensions of the menu. In most cases, your application does not need to use the CalcMenuSize function.

Availability
Declared In
Menus.h

CancelMenuTracking

Cancels menu tracking.

OSStatus CancelMenuTracking (
   MenuRef inRootMenu,
   Boolean inImmediate,
   UInt32 inDismissalReason
);

Parameters
inRootMenu

The root menu of the tracking session to dismiss. For menu bar tracking, pass the result from AcquireRootMenu; for popup menu tracking, pass the menu that was passed to PopUpMenuSelect.

inImmediate

Pass true if you want the open menus to disappear immediately, false if you want them to fade out.

inDismissalReason

Why the menu is being dismissed. This value is passed in the kEventMenuEndTracking event. You can pass the constants in “Menu Dismissal Constants.” If you pass zero here, the kEventMenuEndTracking event contains kMenuDismissedByCancelMenuTracking.

Return Value

A result code. See “Menu Manager Result Codes.”

Availability
Declared In
Menus.h

ChangeMenuAttributes

Changes the attributes of a menu.

OSStatus ChangeMenuAttributes (
   MenuRef menu,
   MenuAttributes setTheseAttributes,
   MenuAttributes clearTheseAttributes
);

Parameters
menu

The menu whose attributes you want to change.

setTheseAttributes

The attributes to add to the menu. See “Menu Attribute Constants” for a list of possible values.

clearTheseAttributes

The attributes to remove from the menu. See “Menu Attribute Constants” for a list of possible values.

Return Value

A result code. See “Menu Manager Result Codes.”

Availability
Declared In
Menus.h

ChangeMenuItemAttributes

Changes the attributes of a menu item.

OSStatus ChangeMenuItemAttributes (
   MenuRef menu,
   MenuItemIndex item,
   MenuItemAttributes setTheseAttributes,
   MenuItemAttributes clearTheseAttributes
);

Parameters
menu

The menu.

item

The index of the menu item.

setTheseAttributes

The attributes to add to the menu item. See “Menu Item Attribute Constants” for a list of possible values.

clearTheseAttributes

The attributes to remove from the menu item.

Return Value

A result code. See “Menu Manager Result Codes.”

Availability
Declared In
Menus.h

ChangeMenuItemPropertyAttributes

Changes the attributes of a menu item property.

OSStatus ChangeMenuItemPropertyAttributes (
   MenuRef menu,
   MenuItemIndex item,
   OSType propertyCreator,
   OSType propertyTag,
   OptionBits attributesToSet,
   OptionBits attributesToClear
);

Parameters
menu

The menu containing the menu item whose properties you want ot change.

item

The index of the menu item.

propertyCreator

The creator code of the property.

propertyTag

The property tag.

attributesToSet

The attributes to add to the menu item property.

attributesToClear

The attributes to remove from the menu item property.

Return Value

A result code. See “Menu Manager Result Codes.”

Discussion

Currently you can only specify the kMenuPropertyPersistent attribute (See “Menu Item Property Attribute Constant”), which currently has no effect on Mac OS X. Therefore, SetMenuItemPropertyAttributes is not useful at this time.

Availability
Declared In
Menus.h

CheckMenuItem

Adds or removes a check mark from a menu item.

void CheckMenuItem (
   MenuRef theMenu,
   short item,
   Boolean checked
);

Parameters
theMenu

The menu containing the menu item to check or uncheck.

item

The menu index of the item to check or uncheck.

checked

Pass true to add a check, false to remove it.

Discussion

You can also add or remove a check mark using the SetItemMark function.

Availability
Declared In
Menus.h

ClearMenuBar

Deletes all menus from the current menu list.

void ClearMenuBar (
   void
);

Discussion

The ClearMenuBar function deletes all menus from the current menu list. ClearMenuBar decrements the reference count of each menu in the menu list; if the reference count reaches zero, the memory associated with the menu is released. To explicitly release the memory occupied by a menu, use DisposeMenu.

Availability
Declared In
Menus.h

CMPluginExamineContext

An application-defined callback function that examines the context in a contextual menu CFPlugin.

OSStatus CMPluginExamineContext (
   void *thisInstance,
   const AEDesc *inContext,
   AEDescList *outCommandPairs
);

Parameters
thisInstance

The instance of this plugin.

inContext

The Apple event descriptor describing the selection that invoked the contextual menu.

outCommandPairs

On return, outCommandPairs points to an array of Apple event descriptors, each of which contains information about a menu item to display in the contextual menu.

Return Value

A result code. See “Menu Manager Result Codes.”

Discussion

Your contextual menu plugin must implement this function to determine what menu items to display given the user selection. The Apple event descriptor for each menu item contains the information to display in the item (such as text) and a command ID.

Availability
Declared In
Menus.h

CMPluginHandleSelection

An application-defined callback function that handles menu item selection in a contextual menu CFPlugin.

OSStatus CMPluginHandleSelection (
   void *thisInstance,
   AEDesc *inContext,
   SInt32 inCommandID
);

Parameters
thisInstance

The instance of this plugin.

inContext

The Apple event descriptor describing the selection that invoked the contextual menu.

inCommandID

The command ID associated with the user’s menu item selection.

Return Value

A result code. See “Menu Manager Result Codes.”

Discussion

Your contextual menu plugin must implement this function to handle a user’s selection of an item in the contextual menu. The command ID indicates which of the choices you gave in CMPluginExamineContext the user selected, so you can use that and the user selection stored in the inContext parameter to execute the conxtexual menu selection appropriately.

Availability
Declared In
Menus.h

CMPluginPostMenuCleanup

An application-defined callback function that handles any post-selection cleanup in a contextual menu CFPlugin.

void CMPluginPostMenuCleanup (
   void *thisInstance
);

Parameters
thisInstance

The instance of this plugin.

Discussion

Your contextual menu plugin must implement this function to handle any necessary cleanup required after displaying the contextual menu. If no cleanup is needed, you can simply return from this function.

Availability
Declared In
Menus.h

ContextualMenuSelect

Displays a contextual menu.

OSStatus ContextualMenuSelect (
   MenuRef inMenu,
   Point inGlobalLocation,
   Boolean inReserved,
   UInt32 inHelpType,
   ConstStr255Param inHelpItemString,
   const AEDesc *inSelection,
   UInt32 *outUserSelectionType,
   MenuID *outMenuID,
   MenuItemIndex *outMenuItem
);

Parameters
inMenu

The menu containing application commands to display. The caller creates this menu based on the current context, the mouse location, and the current selection (if it was the target of the mouse). If you pass NULL, only system commands are displayed.

inGlobalLocation

The location (in global coordinates) of the mouse near which the menu is to be displayed.

inReserved

Reserved for future use. Pass false for this parameter.

inHelpType

An identifier specifying the type of help provided by the application; see “Contextual Menu Help Type Constants.”

inHelpItemString

The string containing the text to be displayed for the help menu item. This string is unused unless you also pass the constant kCMOtherHelp in the inHelpType parameter.

inSelection

A pointer to an object specifier for the current selection. This allows the system to examine the selection and add special system commands accordingly. Passing a value of NULL indicates that no selection should be examined, and most likely, no special system actions will be included.

outUserSelectionType

A pointer to an unsigned 32-bit value. On return, the value indicates what the user selected from the contextual menu; see “Contextual Menu Selection Type Constants” for a list of possible values.

outMenuID

A pointer to a signed 16-bit value. On return, if outUserSelectionType is set to kCMMenuItemSelected, the value is set to the menu ID of the chosen item.

outMenuItem

A pointer to an unsigned 16-bit value. On return, if outUserSelectionType is set to kCMMenuItemSelected, the value is set to the index of the menu item chosen.

Return Value

A result code. See “Menu Manager Result Codes.” Returns userCanceledErr and sets outUserSelectionType to kCMNothingSelected if the user selects an item that requires no additional actions on your part.

Discussion

If your application uses the standard window handler, you may want to install handlers for the kEventWindowContextualMenuSelect or kEventControlContextualMenuClick events and call ContextualMenuSelect from within your handler. The standard window handler automatically detects contextual menu clicks and sends the kEventWindowContextualMenuSelect and kEventControlContextualMenuClick events.

If the IsShowContextualMenuEvent function returns true or you receive the appropriate contextual menu Carbon event, you should call the ContextualMenuSelect function after generating your own menu and preparing an Apple Event descriptor ( AEDesc) that describes the item for which your application is displaying a contextual menu. This descriptor may contain an object specifier or raw data and will be passed to all contextual menu plug-ins.

The system will add other items before displaying the contextual menu, and it will remove those items before returning, leaving the menu in its original state.

After all the system commands are added, the contextual menu is displayed and tracked. If the user selects one of the system items, it is handled by the system and the call returns as though the user didn’t select anything from the menu. If the user selects any other item (or no item at all), the Menu Manager passes back appropriate values in the parameters outUserSelectionType, outMenuID, and outMenuItem.

Your application should provide visual feedback indicating the item that was clicked upon. For example, a click on an icon should highlight the icon, while a click on editable text should not eliminate the current selection.

If the outUserSelectionType parameter contains kCMMenuItemSelected, you should look at the outMenuID and outMenuItem parameters to determine what menu item the user chose and handle it appropriately. If the outUserSelectionType parameter contains kCMShowHelpSelected, you should open the proper help sequence.

Availability
Declared In
Menus.h

CopyMenuItemData

Obtains multiple menu item attributes at once. 

OSStatus CopyMenuItemData (
   MenuRef inMenu,
   MenuItemID inItem,
   Boolean inIsCommandID,
   MenuItemDataPtr ioData
);

Parameters
menu

The menu whose attributes you want to get. Note that if you pass true for the inIsCommandID parameter, you can pass NULL here, in which case the Menu Manager searches the root menu for the first menu that matches the specified command ID.

item

The menu item index or the command ID of the menu item.

isCommandID

A Boolean value indicating whether the value passed for the inItem parameter is a command ID or a menu item index. Pass true to indicate a command ID, false to indicate that it is a menu item index. If you pass true, the Menu Manager returns the data for the first menu item that matches the specified command ID.

outData

A pointer to a MenuItemDataRec structure. Before calling, you should set the whichData field to indicate what data you want to obtain. (Individual fields may also require initialization before calling.) On return, the structure contains the data you requested. For more details on the types of data you can obtain, see “Menu Item Data Flags.”

Return Value

A result code. See “Menu Manager Result Codes.”

Discussion

You can use this function to obtain multiple menu item attributes simultaneously, which is often more efficient than making several different calls. For example, a menu definition function could use CopyMenuItemData to obtain all the individual attributes necessary for drawing a menu all at once.

This function returns copies of the data in the menu, so you should release any data in the MenuItemDataRec structure that was allocated dynamically (such as the CFString item text).

Availability
Declared In
Menus.h

CopyMenuItems

Copies menu items from one menu to another.

OSStatus CopyMenuItems (
   MenuRef inSourceMenu,
   MenuItemIndex inFirstItem,
   ItemCount inNumItems,
   MenuRef inDestMenu,
   MenuItemIndex inInsertAfter
);

Parameters
inSourceMenu

The menu from which to copy items.

inFirstItem

The first item to copy.

inNumItems

The number of items to copy.

inDestMenu

The menu to which to copy items.

inInsertAfter

The menu item in the destination menu after which to insert the copied items. Pass zero to insert items at the beginning of the menu. Note that you cannot specify an index value greater than the number of items in the destination menu.

Return Value

A result code. See “Menu Manager Result Codes.”

Availability
Declared In
Menus.h

CopyMenuItemTextAsCFString

Returns a CFString containing the text of a menu item.

OSStatus CopyMenuItemTextAsCFString (
   MenuRef inMenu,
   MenuItemIndex inItem,
   CFStringRef *outString
);

Parameters
menu

The menu containing the item.

item

The item whose text you want to copy.

outString

On exit, a CFString containing the item's text. The caller must release this string when it is no longer needed.

Return Value

A result code. See “Menu Manager Result Codes.”

Availability
Declared In
Menus.h

CopyMenuTitleAsCFString

Returns a CFString containing the title of a menu.

OSStatus CopyMenuTitleAsCFString (
   MenuRef inMenu,
   CFStringRef *outString
);

Parameters
inMenu

The menu whose title you want to obtain.

outString

On exit, a CFString containing the menu's title. This string must be released by the caller.

Return Value

A result code. See “Menu Manager Result Codes.”

Availability
Declared In
Menus.h

CountMenuItems

Obtains the number of menu items in a menu

UInt16 CountMenuItems (
   MenuRef theMenu
);

Parameters
theMenu

The menu whose items you want to count.

Return Value

The number of menu items in the menu.

Availability
Declared In
Menus.h