Menus.h
Functions
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.
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
Abstract: Returns the retain count of this menu.
ItemCount GetMenuRetainCount(MenuRef inMenu);
Parameters
Name | Description |
inMenu | The menu whose retain count to increment. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
Abstract: Determines if a menu is valid.
Boolean IsValidMenu(MenuRef inMenu);
Parameters
Name | Description |
inMenu | The menu to check for validity.
|
Result: Indicates whether the menu is valid.
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. |
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. |
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. |
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. |
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. |
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. |
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
Name | Description |
inMenu | The menu containing the item.
|
inItem | The item whose indent to set.
|
inIndent | The new indent level of the item. |
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. |
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. |
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. |
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. |
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. |
Structs
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. |
struct MDEFHiliteItemData {
MenuItemIndex previousItem;
MenuItemIndex newItem;
};
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.
struct MenuTrackingData {
MenuRef menu;
MenuItemIndex itemSelected;
MenuItemIndex itemUnderMouse;
Rect itemRect;
SInt32 virtualMenuTop;
SInt32 virtualMenuBottom;
};
© 2000 Apple Computer, Inc. (Last Updated 7/21/2000)