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

NameDescription
menuThe menu to which to append the new item.
inStringThe text of the new item.
inAttributesThe attributes of the new item.
inCommandIDThe command ID of the new item.
outNewItemOn 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

NameDescription
menuThe menu.
setTheseAttributesThe attributes to add to the menu.
clearTheseAttributesThe 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

NameDescription
menuThe menu.
itemThe menu item.
setTheseAttributesThe attributes to add to the menu item.
clearTheseAttributesThe 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

NameDescription
menuThe menu.
itemThe menu item.
propertyCreatorThe creator code of the property.
propertyTagThe property tag.
attributesToSetThe attributes to add to the menu item property.
attributesToClearThe 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

NameDescription
inMenuThe menu containing the item.
inItemThe item whose text to return.
outStringOn 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

NameDescription
sourceMenuThe menu from which to copy items.
firstItemThe first item to copy.
numItemsThe number of items to copy.
destMenuThe menu to which to copy items.
insertAfterThe 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

NameDescription
inMenuThe menu whose title to return.

outStringOn 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

NameDescription
menuThe 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.
commandIDThe 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

NameDescription
inDefSpecSpecifies a custom menu definition function. defSpec->defType must be kMenuDefProcPtr.

inMenuIDThe menu ID to use for the new menu.

inMenuAttributesThe menu attributes to use for the new menu.

outMenuRefOn 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

NameDescription
inMenuIDThe menu ID to use for the new menu.

inMenuAttributesThe menu attributes to use for the new menu.

outMenuRefOn 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

NameDescription
menuThe menu from which to delete items.
firstItemThe first item to delete.
numItemsThe 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

NameDescription
theMenuThe menu whose items to disable.

DisableMenuCommand

Abstract: Disables the menu item with a specified command ID.
void DisableMenuCommand(MenuRef theMenu,
 MenuCommand commandID);

Parameters

NameDescription
theMenuThe 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.
commandIDThe 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

NameDescription
mbarThe 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

NameDescription
inSourceMenuThe menu to duplicate.

outMenuOn 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

NameDescription
mbarThe menubar handle to duplicate.
outBarOn 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

NameDescription
theMenuThe menu whose items to enable.

EnableMenuCommand

Abstract: Enables the menu item with a specified command ID.
void EnableMenuCommand(MenuRef theMenu,
 MenuCommand commandID);

Parameters

NameDescription
theMenuThe 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.
commandIDThe 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

NameDescription
menuThe 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.
commandIDThe command ID for which to search.
itemIndexThe 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.
outMenuOn exit, the menu containing the menu item with the specified command ID.
outIndexOn 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

NameDescription
menuThe menu.
outAttributesOn 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

NameDescription
theMenuThe 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.
commandIDThe command ID of the menu item to be examined. If more than one item has this command ID, only the first will be examined.
outMarkOn 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

NameDescription
menuThe menu.
itemThe menu item.
outAttributesOn 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

NameDescription
inMenuThe parent menu.
inItemThe parent item.
outHierMenuOn 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

NameDescription
inMenuThe menu containing the item.

inItemThe item whose indent to retrieve.

outIndentOn 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

NameDescription
menuThe menu.
itemThe menu item.
propertyCreatorThe creator code of the property.
propertyTagThe property tag.
attributesOn exit, contains the attributes of the property.

GetMenuRetainCount

Abstract: Returns the retain count of this menu.

ItemCount GetMenuRetainCount(MenuRef inMenu);

Parameters

NameDescription
inMenuThe 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

NameDescription
inMenuThe menu whose icon title to retrieve.

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

outIconOn 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

NameDescription
theMenuThe 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.
outDataOn 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

NameDescription
theMenuThe menu whose type to get.
outTypeOn 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

NameDescription
menuThe menu in which to insert the new item.
inStringThe text of the new item.
inAfterItemThe item after which to insert the new item.
inAttributesThe attributes of the new item.
inCommandIDThe 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

NameDescription
menuThe menu whose items to invalidate.
firstItemThe first item to invalidate.
numItemsThe 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

NameDescription
inMenuThe menu whose size to invalidate.

IsMenuBarInvalid

Abstract: Determines if the menubar is invalid and should be redrawn.
Boolean IsMenuBarInvalid(MenuRef rootMenu);

Parameters

NameDescription
rootMenuThe 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

NameDescription
theMenuThe 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.
commandIDThe 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

NameDescription
menuThe menu whose item to examine.
itemThe 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

NameDescription
startMenuIsMenuKeyEvent searches for matching menu items in this menu and all of its submenus. May be NULL to search the current menu bar contents.
eventThe event to match against. Non-keyboard events are ignored.
optionsOptions controlling how to search. Pass kNilOptions for the default behavior.
outMenuOn exit, the menu containing the matching item. May be NULL.
outMenuItemOn 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

NameDescription
inMenuThe menu whose size to examine.

IsValidMenu

Abstract: Determines if a menu is valid.

Boolean IsValidMenu(MenuRef inMenu);

Parameters

NameDescription
inMenuThe 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

NameDescription
theMenuThe 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

NameDescription
inResIDAn MDEF proc ID, as used in a 'MENU' resource.

inDefSpecSpecifies 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

NameDescription
inMenuThe 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

NameDescription
inMenuThe 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

NameDescription
theMenuThe 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.
commandIDThe command ID of the menu item to be modified. If more than one item has this command ID, only the first will be modified.
markThe 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

NameDescription
inMenuThe parent menu.
inItemThe parent item.
inHierMenuThe submenu.

SetMenuItemIndent

Abstract: Sets the indent level of a menu item.

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

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

NameDescription
inMenuThe menu containing the item.

inItemThe item whose indent to set.

inIndentThe 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

NameDescription
inMenuThe menu containing the item.
inItemThe item whose text to return.
inStringThe 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

NameDescription
inMenuThe menu whose title to set.

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

inIconThe 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

NameDescription
inMenuThe menu whose title to set.

inStringThe 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

NameDescription
inMenuThe 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

NameDescription
menuThe menu to update.

Structs

MDEFDrawItemsData

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

Fields

NameDescription
firstItemThe first item to draw.
lastItemThe last item to draw.
trackingDataInformation about the menu's tracking state. The virtualMenuTop and virtualMenuBottom fields in this structure will be the most useful in handling the DrawItems message.
contextA 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;
};


© 2000 Apple Computer, Inc. — (Last Updated 7/21/2000)