Menus.h

Functions

AcquireRootMenu

Abstract: Get the menu whose contents are displayed in the menubar.

MenuRef AcquireRootMenu(void);

The refcount of the root menu is incremented by this API. The caller should release a refcount with ReleaseMenu when itÕs done with the menu.

AppendMenuItemTextWithCFString

Abstract: Appends a new menu item with text from a CFString.

OSStatus AppendMenuItemTextWithCFString(MenuRef menu,
 CFStringRef inString,
 MenuItemAttributes inAttributes,
 MenuCommand inCommandID,
 MenuItemIndex * outNewItem) /* can be NULL */;

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

Parameters

Name Description

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.

Name	Description
`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.

ChangeMenuAttributes

Abstract: Changes the attributes of a menu.

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

Parameters

Name Description

menu The menu.

setTheseAttributes The attributes to add to the menu.

clearTheseAttributes The attributes to remove from the menu.

Name	Description
`menu`	The menu.
`setTheseAttributes`	The attributes to add to the menu.
`clearTheseAttributes`	The attributes to remove from the menu.

ChangeMenuItemAttributes

Abstract: Changes the attributes of a menu item.

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

Parameters

Name Description

menu The menu.

item The menu item.

setTheseAttributes The attributes to add to the menu item.

clearTheseAttributes The attributes to remove from the menu item.

Name	Description
`menu`	The menu.
`item`	The menu item.
`setTheseAttributes`	The attributes to add to the menu item.
`clearTheseAttributes`	The attributes to remove from the menu item.

ChangeMenuItemPropertyAttributes

Abstract: Changes the attributes of a menu item property.

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

Parameters

Name Description

menu The menu.

item 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.

Name	Description
`menu`	The menu.
`item`	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.

CopyMenuItemTextAsCFString

Abstract: Returns a CFString containing the text of a menu item.

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

Parameters

Name Description

inMenu The menu containing the item.

inItem The item whose text to return.

outString On exit, a CFString containing the item's text. This string must be released by the caller.

Name	Description
`inMenu`	The menu containing the item.
`inItem`	The item whose text to return.
`outString`	On exit, a CFString containing the item's text. This string must be released by the caller.

CopyMenuItems

Abstract: Copies menu items from one menu to another.

OSStatus CopyMenuItems(MenuRef sourceMenu,
 MenuItemIndex firstItem,
 ItemCount numItems,
 MenuRef destMenu,
 MenuItemIndex insertAfter);

Parameters

Name Description

sourceMenu The menu from which to copy items.

firstItem The first item to copy.

numItems The number of items to copy.

destMenu The menu to which to copy items.

insertAfter The menu item in the destination menu after which to insert the copied items.

Name	Description
`sourceMenu`	The menu from which to copy items.
`firstItem`	The first item to copy.
`numItems`	The number of items to copy.
`destMenu`	The menu to which to copy items.
`insertAfter`	The menu item in the destination menu after which to insert the copied items.

CopyMenuTitleAsCFString

Abstract: Returns a CFString containing the title of a menu.

OSStatus CopyMenuTitleAsCFString(MenuRef inMenu,
 CFStringRef * outString);

Parameters

Name Description

inMenu The menu whose title to return.

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

Name	Description
`inMenu`	The menu whose title to return.
`outString`	On exit, a CFString containing the menu's title. This string must be released by the caller.

CountMenuItemsWithCommandID

Abstract: Counts the menu items with a specified command ID.

ItemCount CountMenuItemsWithCommandID(MenuRef menu,
 MenuCommand commandID);

In CarbonLib 1.0.x, this API will always return zero or one; it stops after finding the first menu item with the specified command ID. In CarbonLib 1.1 and Mac OS X 1.0, it will count all menu items with the specified command ID.

Parameters

Name Description

menu The menu in which to begin searching for items with the specified command ID. Pass NULL to hegin searching with the root menu. The search will descend into all submenus of this menu.

commandID The command ID for which to search.

Name	Description
`menu`	The menu in which to begin searching for items with the specified command ID. Pass NULL to hegin searching with the root menu. The search will descend into all submenus of this menu.
`commandID`	The command ID for which to search.

CreateCustomMenu

Abstract: Creates a new, untitled, empty menu using a custom menu definition function.

OSStatus CreateCustomMenu(const MenuDefSpec * inDefSpec,
 MenuID inMenuID,
 MenuAttributes inMenuAttributes,
 MenuRef * outMenuRef);

Similar to CreateNewMenu, but also allows you to specify a custom menu definition function.

Parameters

Name Description

inDefSpec Specifies a custom menu definition function. defSpec->defType must be kMenuDefProcPtr.

inMenuID The menu ID to use for the new menu.

inMenuAttributes The menu attributes to use for the new menu.

outMenuRef On exit, contains the new menu.

Name	Description
`inDefSpec`	Specifies a custom menu definition function. defSpec->defType must be kMenuDefProcPtr.
`inMenuID`	The menu ID to use for the new menu.
`inMenuAttributes`	The menu attributes to use for the new menu.
`outMenuRef`	On exit, contains the new menu.

CreateNewMenu

Abstract: Creates a new, untitled, empty menu.

OSStatus CreateNewMenu(MenuID inMenuID,
 MenuAttributes inMenuAttributes,
 MenuRef * outMenuRef);

CreateNewMenu is preferred over NewMenu because it allows you to specify the menu's attributes and it does not require you to specify a Str255-based menu title. To set the menu title, you can use either SetMenuTitle or SetMenuTitleWithCFString.

Parameters

Name Description

inMenuID The menu ID to use for the new menu.

inMenuAttributes The menu attributes to use for the new menu.

outMenuRef On exit, contains the new menu.

Name	Description
`inMenuID`	The menu ID to use for the new menu.
`inMenuAttributes`	The menu attributes to use for the new menu.
`outMenuRef`	On exit, contains the new menu.

DeleteMenuItems

Abstract: Deletes multiple menu items.

OSStatus DeleteMenuItems(MenuRef menu,
 MenuItemIndex firstItem,
 ItemCount numItems);

This API is more efficient than calling DeleteMenuItem multiple times.

Parameters

Name Description

menu The menu from which to delete items.

firstItem The first item to delete.

numItems The number of items to delete.

Name	Description
`menu`	The menu from which to delete items.
`firstItem`	The first item to delete.
`numItems`	The number of items to delete.

DisableAllMenuItems

Abstract: Disables all items in a menu.

void DisableAllMenuItems(MenuRef theMenu);

This API is equivalent to pre-Carbon code that masked the enableFlags field of the MenuInfo with 0x01. It disables all items (including items past item 31) but does not affect the state of the menu title.

Parameters

Name Description

theMenu The menu whose items to disable.

Name	Description
`theMenu`	The menu whose items to disable.

DisableMenuCommand

Abstract: Disables the menu item with a specified command ID.

void DisableMenuCommand(MenuRef theMenu,
 MenuCommand commandID);

Parameters

Name Description

theMenu The menu in which to begin searching for the item. Pass NULL to begin searching with the root menu. The search will descend into all submenus of this menu.

commandID The command ID of the menu item to be disabled. If more than one item has this command ID, only the first will be disabled.

Name	Description
`theMenu`	The menu in which to begin searching for the item. Pass NULL to begin searching with the root menu. The search will descend into all submenus of this menu.
`commandID`	The command ID of the menu item to be disabled. If more than one item has this command ID, only the first will be disabled.

DisposeMenuBar

Abstract: Releases a menubar handle.

OSStatus DisposeMenuBar(MenuBarHandle mbar);

This API should be used in Carbon applications when releasing a handle returned from GetMenuBar or GetNewMBar. You should not use DisposeHandle to release such a handle. This is necessary in Carbon so that the refcounts of the menus in the menubar handle can be decremented when the handle is released.

Parameters

Name Description

mbar The menubar handle to release.

Name	Description
`mbar`	The menubar handle to release.

DuplicateMenu

Abstract: Creates a new menu that is a copy of another menu.

OSStatus DuplicateMenu(MenuRef inSourceMenu,
 MenuRef * outMenu);

Unlike CloneMenu, DuplicateMenu creates an entirely new menu that is an exact copy of the original menu. The MDEF for the new menu will receive an init message after the menu has been fully created.

Parameters

Name Description

inSourceMenu The menu to duplicate.

outMenu On exit, a copy of the source menu.

Name	Description
`inSourceMenu`	The menu to duplicate.
`outMenu`	On exit, a copy of the source menu.

DuplicateMenuBar

Abstract: Duplicates a menubar handle.

OSStatus DuplicateMenuBar(MenuBarHandle mbar,
 MenuBarHandle * outBar);

This API should be used in Carbon applications when duplicating a handle returned from GetMenuBar or GetNewMBar. You should not use Memory Manager APIs (HandToHand, NewHandle, etc) to duplicate such a handle. This is necessary in Carbon so that the refcounts of the menus in the menubar handle can be incremented when the handle is duplicated.

Parameters

Name Description

mbar The menubar handle to duplicate.

outBar On exit, contains the new menubar handle.

Name	Description
`mbar`	The menubar handle to duplicate.
`outBar`	On exit, contains the new menubar handle.

EnableAllMenuItems

Abstract: Enables all items in a menu.

void EnableAllMenuItems(MenuRef theMenu);

This API is equivalent to pre-Carbon code that or'd the enableFlags field of the MenuInfo with 0xFFFFFFFE. It enables all items (including items past item 31) but does not affect the state of the menu title.

Parameters

Name Description

theMenu The menu whose items to enable.

Name	Description
`theMenu`	The menu whose items to enable.

EnableMenuCommand

Abstract: Enables the menu item with a specified command ID.

void EnableMenuCommand(MenuRef theMenu,
 MenuCommand commandID);

Parameters

Name Description

theMenu The menu in which to begin searching for the item. Pass NULL to begin searching with the root menu. The search will descend into all submenus of this menu.

commandID The command ID of the menu item to be enabled. If more than one item has this command ID, only the first will be enabled.

Name	Description
`theMenu`	The menu in which to begin searching for the item. Pass NULL to begin searching with the root menu. The search will descend into all submenus of this menu.
`commandID`	The command ID of the menu item to be enabled. If more than one item has this command ID, only the first will be enabled.

GetIndMenuItemWithCommandID

Abstract: Finds a menu item with a specified command ID.

OSStatus GetIndMenuItemWithCommandID(MenuRef menu,
 MenuCommand commandID,
 UInt32 itemIndex,
 MenuRef * outMenu,
 MenuItemIndex * outIndex);

This API searches the specified menu and its submenus for the n'th menu item with the specified command ID. In CarbonLib 1.0.x, only the first menu item will be returned. In CarbonLib 1.1 and Mac OS X 1.0, this API will iterate over all menu items with the specified command ID.

Parameters

Name Description

menu The menu in which to begin searching for items with the specified command ID. Pass NULL to hegin searching with the root menu. The search will descend into all submenus of this menu.

commandID The command ID for which to search.

itemIndex The 1-based index of the menu item to retrieve. In CarbonLib 1.0.x, this parameter must be 1. In CarbonLib 1.1 and Mac OS X 1.0, this parameter may vary from 1 to the number of menu items with the specified command ID.

outMenu On exit, the menu containing the menu item with the specified command ID.

outIndex On exit, the item index of the menu item with the specified command ID.

Name	Description
`menu`	The menu in which to begin searching for items with the specified command ID. Pass NULL to hegin searching with the root menu. The search will descend into all submenus of this menu.
`commandID`	The command ID for which to search.
`itemIndex`	The 1-based index of the menu item to retrieve. In CarbonLib 1.0.x, this parameter must be 1. In CarbonLib 1.1 and Mac OS X 1.0, this parameter may vary from 1 to the number of menu items with the specified command ID.
`outMenu`	On exit, the menu containing the menu item with the specified command ID.
`outIndex`	On exit, the item index of the menu item with the specified command ID.

GetMenuAttributes

Abstract: Gets the attributes of a menu.

OSStatus GetMenuAttributes(MenuRef menu,
 MenuAttributes * outAttributes);

Parameters

Name Description

menu The menu.

outAttributes On exit, contains the attributes of the menu.

Name	Description
`menu`	The menu.
`outAttributes`	On exit, contains the attributes of the menu.

GetMenuCommandMark

Abstract: Locates the menu item with a specified command ID and returns its mark character.

OSStatus GetMenuCommandMark(MenuRef theMenu,
 MenuCommand commandID,
 UniChar * outMark);

Parameters

Name Description

theMenu The menu in which to begin searching for the item. Pass NULL to begin searching with the root menu. The search will descend into all submenus of this menu.

commandID The command ID of the menu item to be examined. If more than one item has this command ID, only the first will be examined.

outMark On exit, the menu item's mark character.

Name	Description
`theMenu`	The menu in which to begin searching for the item. Pass NULL to begin searching with the root menu. The search will descend into all submenus of this menu.
`commandID`	The command ID of the menu item to be examined. If more than one item has this command ID, only the first will be examined.
`outMark`	On exit, the menu item's mark character.

GetMenuItemAttributes

Abstract: Gets the attributes of a menu item.

OSStatus GetMenuItemAttributes(MenuRef menu,
 MenuItemIndex item,
 MenuItemAttributes * outAttributes);

Parameters

Name Description

menu The menu.

item The menu item.

outAttributes On exit, contains the attributes of the menu item.

Name	Description
`menu`	The menu.
`item`	The menu item.
`outAttributes`	On exit, contains the attributes of the menu item.

GetMenuItemHierarchicalMenu

Abstract: Returns the submenu attached to a menu item.

OSStatus GetMenuItemHierarchicalMenu(MenuRef inMenu,
 MenuItemIndex inItem,
 MenuRef * outHierMenu);

GetMenuItemHierarchicalMenu will return the submenu attached to a menu item regardless of how the submenu was specified. If the submenu was specified by menu ID (using SetItemCmd or SetMenuItemHierarchicalID), GetMenuItemHierarchicalMenu will return the currently installed menu with that ID, if any. The only case where GetMenuItemHierarchicalMenu will fail to return the item's submenu is when the submenu is specified by menu ID, but the submenu is not currently inserted in the menu bar.

Parameters

Name Description

inMenu The parent menu.

inItem The parent item.

outHierMenu On exit, the item's submenu, or NULL if it does not have one.

Name	Description
`inMenu`	The parent menu.
`inItem`	The parent item.
`outHierMenu`	On exit, the item's submenu, or NULL if it does not have one.

GetMenuItemIndent

Abstract: Gets the indent level of a menu item.

OSStatus GetMenuItemIndent(MenuRef inMenu,
 MenuItemIndex inItem,
 UInt32 * outIndent);

The indent level of an item is an amount of extra space added to the left of the item's icon or checkmark. The level is simply a number, starting at zero, which the Menu Manager multiplies by a constant to get the indent in pixels. The default indent level is zero.

Parameters

Name Description

inMenu The menu containing the item.

inItem The item whose indent to retrieve.

outIndent On exit, the indent level of the item.

Name	Description
`inMenu`	The menu containing the item.
`inItem`	The item whose indent to retrieve.
`outIndent`	On exit, the indent level of the item.

GetMenuItemPropertyAttributes

Abstract: Gets the attributes of a menu item property.

OSStatus GetMenuItemPropertyAttributes(MenuRef menu,
 MenuItemIndex item,
 OSType propertyCreator,
 OSType propertyTag,
 UInt32 * attributes);

Parameters

Name Description

menu The menu.

item The menu item.

propertyCreator The creator code of the property.

propertyTag The property tag.

attributes On exit, contains the attributes of the property.

Name	Description
`menu`	The menu.
`item`	The menu item.
`propertyCreator`	The creator code of the property.
`propertyTag`	The property tag.
`attributes`	On exit, contains the attributes of the property.

GetMenuRetainCount

Abstract: Returns the retain count of this menu.

ItemCount GetMenuRetainCount(MenuRef inMenu);

Parameters

Name Description

inMenu The menu whose retain count to increment.

Name	Description
`inMenu`	The menu whose retain count to increment.

GetMenuTitleIcon

Abstract: Retrieves the icon, if any, being used as the title of a menu.

OSStatus GetMenuTitleIcon(MenuRef inMenu,
 UInt32 * outType, /* can be NULL */
 void ** outIcon) /* can be NULL */;

This API does not increment a refcount on the returned icon. The caller should not release the icon.

Parameters

Name Description

inMenu The menu whose icon title to retrieve.

outType On exit, contains the type of icon being used as the title of the menu. Contains kMenuNoIcon if the menu does not have an icon title.

outIcon On exit, contains the IconSuiteRef or IconRef being used as the title of the menu, or NULL if the menu does not have an icon title. May be NULL.

Name	Description
`inMenu`	The menu whose icon title to retrieve.
`outType`	On exit, contains the type of icon being used as the title of the menu. Contains kMenuNoIcon if the menu does not have an icon title.
`outIcon`	On exit, contains the IconSuiteRef or IconRef being used as the title of the menu, or NULL if the menu does not have an icon title. May be NULL.

GetMenuTrackingData

Abstract: Gets information about the menu currently selected by the user.

OSStatus GetMenuTrackingData(MenuRef theMenu,
 MenuTrackingData * outData);

This API replaces direct access to the low-memory globals TopMenuItem, AtMenuBottom, MenuDisable, and mbSaveLoc. It is only valid to call this API while menu tracking is occurring. This API will most commonly be used by custom MDEFs.

Parameters

Name Description

theMenu The menu about which to get tracking information. May be NULL to get information about the menu that the user is currently selecting. If the menu is not currently open, menuNotFoundErr is returned.

outData On exit, contains tracking data about the menu. On CarbonLib, the itemRect field is not supported and is always set to an empty rect.

Name	Description
`theMenu`	The menu about which to get tracking information. May be NULL to get information about the menu that the user is currently selecting. If the menu is not currently open, menuNotFoundErr is returned.
`outData`	On exit, contains tracking data about the menu. On CarbonLib, the itemRect field is not supported and is always set to an empty rect.

GetMenuType

Abstract: Gets the display type (pulldown, hierarchical, or popup) of a menu.

OSStatus GetMenuType(MenuRef theMenu,
 UInt16 * outType);

This API may only be called when the menu is displayed. If the menu is not currently open, an error is returned. The display type of a menu may vary from one menu tracking session to another; for example, the same menu might be displayed as a pulldown menu and as a popup menu.

Parameters

Name Description

theMenu The menu whose type to get.

outType On exit, the type of the menu. The returned value will be one of the ThemeMenuType constants: kThemeMenuTypePullDown, PopUp, or Hierarchical. The kThemeMenuTypeInactive bit will never be set.

Name	Description
`theMenu`	The menu whose type to get.
`outType`	On exit, the type of the menu. The returned value will be one of the ThemeMenuType constants: kThemeMenuTypePullDown, PopUp, or Hierarchical. The kThemeMenuTypeInactive bit will never be set.

InsertMenuItemTextWithCFString

Abstract: Inserts a new menu item with text from a CFString.

OSStatus InsertMenuItemTextWithCFString(MenuRef menu,
 CFStringRef inString,
 MenuItemIndex inAfterItem,
 MenuItemAttributes inAttributes,
 MenuCommand inCommandID);

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

Parameters

Name Description

menu The menu in which to insert the new item.

inString The text of the new item.

inAfterItem The item after which to insert the new item.

inAttributes The attributes of the new item.

inCommandID The command ID of the new item.

Name	Description
`menu`	The menu in which to insert the new item.
`inString`	The text of the new item.
`inAfterItem`	The item after which to insert the new item.
`inAttributes`	The attributes of the new item.
`inCommandID`	The command ID of the new item.

InvalidateMenuItems

Abstract: Invalidates a group of menu items so that they will be redrawn when UpdateInvalidMenuItems is next called.

OSStatus InvalidateMenuItems(MenuRef menu,
 MenuItemIndex firstItem,
 ItemCount numItems);

Menu items are automatically invalidated when their contents are changed using Menu Manager APIs while the menu is open. However, you might need to use this API if you have a custom MDEF that draws using state not contained in the menu.

Parameters

Name Description

menu The menu whose items to invalidate.

firstItem The first item to invalidate.

numItems The number of items to invalidate.

Name	Description
`menu`	The menu whose items to invalidate.
`firstItem`	The first item to invalidate.
`numItems`	The number of items to invalidate.

InvalidateMenuSize

Abstract: Invalidates the menu size so that it will be recalculated when next displayed.

OSStatus InvalidateMenuSize(MenuRef inMenu);

The pre-Carbon technique for invalidating the menu size was to set the width and height to -1. Although this technique still works, for best compatibility it's preferable to use the InvalidateMenuSize API so that the Menu Manager has explicit notification that the menu is invalid.

Parameters

Name Description

inMenu The menu whose size to invalidate.

Name	Description
`inMenu`	The menu whose size to invalidate.

IsMenuBarInvalid

Abstract: Determines if the menubar is invalid and should be redrawn.

Boolean IsMenuBarInvalid(MenuRef rootMenu);

Parameters

Name Description

rootMenu The root menu for the menubar to be examined. Pass NULL to check the state of the current menubar.

Name	Description
`rootMenu`	The root menu for the menubar to be examined. Pass NULL to check the state of the current menubar.

IsMenuCommandEnabled

Abstract: Determines if the menu item with a specified command ID is enabled.

Boolean IsMenuCommandEnabled(MenuRef menu,
 MenuCommand commandID);

Parameters

Name Description

theMenu The menu in which to begin searching for the item. Pass NULL to begin searching with the root menu. The search will descend into all submenus of this menu.

commandID The command ID of the menu item to examine. If more than one item has this command ID, only the first will be examined.

Name	Description
`theMenu`	The menu in which to begin searching for the item. Pass NULL to begin searching with the root menu. The search will descend into all submenus of this menu.
`commandID`	The command ID of the menu item to examine. If more than one item has this command ID, only the first will be examined.

IsMenuItemInvalid

Abstract: Determines if a menu item is invalid and should be redrawn.

Boolean IsMenuItemInvalid(MenuRef menu,
 MenuItemIndex item);

Parameters

Name Description

menu The menu whose item to examine.

item The item to examine.

Name	Description
`menu`	The menu whose item to examine.
`item`	The item to examine.

IsMenuKeyEvent

Abstract: Determines if an event corresponds to a menu command key.

Boolean IsMenuKeyEvent(MenuRef startMenu,
 EventRef event,
 MenuEventOptions options,
 MenuRef * outMenu, /* can be NULL */
 MenuItemIndex * outMenuItem) /* can be NULL */;

By default, IsMenuKeyEvent searches the menus in the current menu bar and hilites the menu title of the menu containing the selected item.

Parameters

Name Description

startMenu IsMenuKeyEvent searches for matching menu items in this menu and all of its submenus. May be NULL to search the current menu bar contents.

event The event to match against. Non-keyboard events are ignored.

options Options controlling how to search. Pass kNilOptions for the default behavior.

outMenu On exit, the menu containing the matching item. May be NULL.

outMenuItem On exit, the menu item that matched. May be NULL.

Name	Description
`startMenu`	IsMenuKeyEvent searches for matching menu items in this menu and all of its submenus. May be NULL to search the current menu bar contents.
`event`	The event to match against. Non-keyboard events are ignored.
`options`	Options controlling how to search. Pass kNilOptions for the default behavior.
`outMenu`	On exit, the menu containing the matching item. May be NULL.
`outMenuItem`	On exit, the menu item that matched. May be NULL.

IsMenuSizeInvalid

Abstract: Determines if a menu's size is invalid and should be recalculated.

Boolean IsMenuSizeInvalid(MenuRef inMenu);

The pre-Carbon technique for determining if a menu's size is invalid was to check if the width or height was -1. This technique is not always reliable on Carbon due to implementation changes in the Menu Manager. You should now use IsMenuSizeInvalid instead.

Parameters

Name Description

inMenu The menu whose size to examine.

Name	Description
`inMenu`	The menu whose size to examine.

IsValidMenu

Abstract: Determines if a menu is valid.

Boolean IsValidMenu(MenuRef inMenu);

Parameters

Name Description

inMenu The menu to check for validity.

Name	Description
`inMenu`	The menu to check for validity.

Result: Indicates whether the menu is valid.

MenuHasEnabledItems

Abstract: Determines if any items in a menu are enabled.

Boolean MenuHasEnabledItems(MenuRef theMenu);

This API is equivalent to pre-Carbon code that compared the enableFlags field of the MenuInfo with 0. It checks the enable state of all items to see if any are enabled, but ignores the state of the menu title. It will return true even if the menu title is disabled.

Parameters

Name Description

theMenu The menu whose items to examine.

Name	Description
`theMenu`	The menu whose items to examine.

RegisterMenuDefinition

Abstract: Registers a binding between a resource ID and a menu definition function.

OSStatus RegisterMenuDefinition(SInt16 inResID,
 MenuDefSpecPtr inDefSpec);

In the Mac OS 8.x Menu Manager, a 'MENU' resource can contain an embedded MDEF procID that is used by the Menu Manager as the resource ID of an 'MDEF' resource to measure and draw the menu. The 'MDEF' resource is loaded by the Menu Manager when you load the menu with GetMenu. Since MDEFs can no longer be packaged as code resources on Carbon, the procID can no longer refer directly to an MDEF resource. However, using RegisterMenuDefinition you can instead specify a UniversalProcPtr pointing to code in your application code fragment.

Parameters

Name Description

inResID An MDEF proc ID, as used in a 'MENU' resource.

inDefSpec Specifies the MenuDefUPP that should be used for menus with the given MDEF proc ID.

Name	Description
`inResID`	An MDEF proc ID, as used in a 'MENU' resource.
`inDefSpec`	Specifies the MenuDefUPP that should be used for menus with the given MDEF proc ID.

ReleaseMenu

Abstract: Decrements the retain count of a menu.

OSStatus ReleaseMenu(MenuRef inMenu);

If called on a menu that was not created by CarbonLib, it will not affect the menu's retain count.

Parameters

Name Description

inMenu The menu whose retain count to decrement. If the retain count falls to zero, the menu is destroyed.

Name	Description
`inMenu`	The menu whose retain count to decrement. If the retain count falls to zero, the menu is destroyed.

RetainMenu

Abstract: Increments the retain count of a menu.

OSStatus RetainMenu(MenuRef inMenu);

RetainMenu does not create a new menu. It simply adds one to the retain count. If called on a menu that was not created by CarbonLib, it will not affect the menu's retain count.

Parameters

Name Description

inMenu The menu whose retain count to increment.

Name	Description
`inMenu`	The menu whose retain count to increment.

SetMenuCommandMark

Abstract: Locates the menu item with a specified command ID and sets its mark character.

OSStatus SetMenuCommandMark(MenuRef theMenu,
 MenuCommand commandID,
 UniChar mark);

Parameters

Name Description

theMenu The menu in which to begin searching for the item. Pass NULL to begin searching with the root menu. The search will descend into all submenus of this menu.

commandID The command ID of the menu item to be modified. If more than one item has this command ID, only the first will be modified.

mark The new mark character. This is a Unicode character. On Mac OS 8.x, the low byte of this character will be used as the mark character. On Mac OS X, the entire UniChar will be used and drawn.

Name	Description
`theMenu`	The menu in which to begin searching for the item. Pass NULL to begin searching with the root menu. The search will descend into all submenus of this menu.
`commandID`	The command ID of the menu item to be modified. If more than one item has this command ID, only the first will be modified.
`mark`	The new mark character. This is a Unicode character. On Mac OS 8.x, the low byte of this character will be used as the mark character. On Mac OS X, the entire UniChar will be used and drawn.

SetMenuItemHierarchicalMenu

Abstract: Attaches a submenu to a menu item.

OSStatus SetMenuItemHierarchicalMenu(MenuRef inMenu,
 MenuItemIndex inItem,
 MenuRef inHierMenu);

Using SetMenuItemHierarchicalMenu, it is possible to directly specify the submenu for a menu item without specifying its menu ID. It is not necessary to insert the submenu into the hierarchical portion of the menubar, and it is not necessary for the submenu to have a unique menu ID; it is recommended that you use 0 as the menu ID for the submenu, and identify selections from the menu by command ID.

Parameters

Name Description

inMenu The parent menu.

inItem The parent item.

inHierMenu The submenu.

Name	Description
`inMenu`	The parent menu.
`inItem`	The parent item.
`inHierMenu`	The submenu.

SetMenuItemIndent

Abstract: Sets the indent level of a menu item.

OSStatus SetMenuItemIndent(MenuRef inMenu,
 MenuItemIndex inItem,
 UInt32 inIndent);

Parameters

Name Description

inMenu The menu containing the item.

inItem The item whose indent to set.

inIndent The new indent level of the item.

Name	Description
`inMenu`	The menu containing the item.
`inItem`	The item whose indent to set.
`inIndent`	The new indent level of the item.

SetMenuItemTextWithCFString

Abstract: Sets the text of a menu item to the text contained in a CFString.

OSStatus SetMenuItemTextWithCFString(MenuRef inMenu,
 MenuItemIndex inItem,
 CFStringRef inString);

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

Parameters

Name Description

inMenu The menu containing the item.

inItem The item whose text to return.

inString The string containing the new menu item text.

Name	Description
`inMenu`	The menu containing the item.
`inItem`	The item whose text to return.
`inString`	The string containing the new menu item text.

SetMenuTitleIcon

Abstract: Sets the title of a menu to be an icon.

OSStatus SetMenuTitleIcon(MenuRef inMenu,
 UInt32 inType,
 void * inIcon);

The Menu Manager takes ownership of the supplied icon after this call. When a menu with an title icon is disposed, the Menu Manager will dispose the icon also; the Menu Manager will also dispose of the current title icon when a new text or icon title is supplied for a menu. If an IconRef is specified, the Menu Manager will increment its refcount, so you may freely release your reference to the IconRef without invalidating the Menu Manager's copy. The menubar will be invalidated by this call, and redrawn at the next opportunity.

Parameters

Name Description

inMenu The menu whose title to set.

inType The type of icon being used to specify the icon title; use kMenuNoIcon to remove the icon from the menu title. The supported types are kMenuIconSuiteType and kMenuIconRefType.

inIcon The icon; must be NULL if inType is kMenuNoIcon. The supported icon formats are IconSuiteRef and IconRef.

Name	Description
`inMenu`	The menu whose title to set.
`inType`	The type of icon being used to specify the icon title; use kMenuNoIcon to remove the icon from the menu title. The supported types are kMenuIconSuiteType and kMenuIconRefType.
`inIcon`	The icon; must be NULL if inType is kMenuNoIcon. The supported icon formats are IconSuiteRef and IconRef.

SetMenuTitleWithCFString

Abstract: Sets the title of a menu to the text contained in a CFString.

OSStatus SetMenuTitleWithCFString(MenuRef inMenu,
 CFStringRef inString);

The Menu Manager will make its own copy of the CFString before returning from SetMenuTitleWithCFString. Modifying the string after calling SetMenuTitleWithCFString will have no effect on the menu's actual title. The caller may release the string after calling SetMenuTitleWithCFString.

Parameters

Name Description

inMenu The menu whose title to set.

inString The string containing the new menu title text.

Name	Description
`inMenu`	The menu whose title to set.
`inString`	The string containing the new menu title text.

SetRootMenu

Abstract: Sets the menu whose contents are displayed in the menubar.

OSStatus SetRootMenu(MenuRef inMenu);

The refcount of the root menu is incremented by this API. The caller may release the menu after calling SetRootMenu.

Parameters

Name Description

inMenu The new root menu.

Name	Description
`inMenu`	The new root menu.

UpdateInvalidMenuItems

Abstract: Redraws the invalid items of an open menu.

OSStatus UpdateInvalidMenuItems(MenuRef menu);

It is not necessary to use UpdateInvalidMenuItems if you are using Carbon's built-in support for dynamic items based on modifier key state. However, if you are modifying items dynamically using your own implementation, you should call UpdateInvalidMenuItems after completing your modifications for a single menu. It will redraw any items that have been marked as invalid, and clear the invalid flag for those items.

Parameters

Name Description

menu The menu to update.

Name	Description
`menu`	The menu to update.

Structs

MDEFDrawItemsData

struct  MDEFDrawItemsData  {
  MenuItemIndex  firstItem;
  MenuItemIndex  lastItem;
  MenuTrackingData  *  trackingData;
  void  *  context;
};

Fields

Name Description

firstItem The first item to draw.

lastItem The last item to draw.

trackingData Information about the menu's tracking state. The virtualMenuTop and virtualMenuBottom fields in this structure will be the most useful in handling the DrawItems message.

context A drawing context that may be passed to one of the Appearance Manager APIs that takes a context.

MDEFHiliteItemData

struct  MDEFHiliteItemData  {
  MenuItemIndex  previousItem;
  MenuItemIndex  newItem;
};

MenuItemDataRec

struct  MenuItemDataRec  {
  MenuItemDataFlags  whichData;
  StringPtr  text;
  UniChar  mark;
  UniChar  cmdKey;
  UInt32  cmdKeyGlyph;
  UInt32  cmdKeyModifiers;
  Style  style;
  Boolean  enabled;
  Boolean  iconEnabled;
  UInt8  filler1;
  SInt32  iconID;
  UInt32  iconType;
  Handle  iconHandle;
  MenuCommand  cmdID;
  TextEncoding  encoding;
  MenuID  submenuID;
  MenuRef  submenuHandle;
  SInt32  fontID;
  UInt32  refcon;
  OptionBits  attr;
  CFStringRef  cfText;
  Collection  properties;
  UInt32  indent;
};

When using this structure with Copy/SetMenuItemData, the caller must first set the whichData field to a combination of MenuItemDataFlags indicating which specific data should be retrieved or set. Some fields also require initialization before calling CopyMenuItemData; see the individual MenuItemDataFlags documentation for details.

MenuTrackingData

struct  MenuTrackingData  {
  MenuRef  menu;
  MenuItemIndex  itemSelected;
  MenuItemIndex  itemUnderMouse;
  Rect  itemRect;
  SInt32  virtualMenuTop;
  SInt32  virtualMenuBottom;
};

Name	Description
`firstItem`	The first item to draw.
`lastItem`	The last item to draw.
`trackingData`	Information about the menu's tracking state. The virtualMenuTop and virtualMenuBottom fields in this structure will be the most useful in handling the DrawItems message.
`context`	A drawing context that may be passed to one of the Appearance Manager APIs that takes a context.