ADC Home > Reference Library > Reference > Carbon > User Experience > Menu Manager Reference >

< Previous PageNext Page > Hide TOC

Deprecated Menu Manager Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.5

AppendMenu

Appends one or more items to a menu previously created. (Deprecated in Mac OS X v10.5.)

Not recommended

void AppendMenu (
   MenuRef menu,
   ConstStr255Param data
);

Parameters
menu

The menu to which you wish to append the menu item or items.

data

A Pascal string that defines the characteristics of the new menu item or items. Note that in most cases you should store the text of a menu item in a resource, so that your menu items can be more easily localized. The AppendMenu function appends the menu items in the order in which they are listed in the data parameter.

Discussion

Note that unless you are supporting legacy code, you should use the AppendMenuItemTextWithCFString function instead.

The AppendMenu function appends any defined menu items to a previously-created menu. The menu items are added to the end of the menu. You specify the text of any menu items and their characteristics in the data parameter. You can embed metacharacters in the string to define various characteristics of a menu item.

Table A-1 lists the metacharacters that you can specify in the data parameter:

Table A-1  Metacharacters available to pass in AppendMenu

Metacharacter

Description

; or Return

Separates menu items.

^

When followed by an icon number, defines the icon for the item. If the keyboard equivalent field contains 0x1C, this number is interpreted as a text encoding.

!

When followed by a character, defines the mark for the item. If the keyboard equivalent field contains 0x1B or the equivalent constant hMenuCmd, this value is interpreted as the menu ID of a submenu of this menu item.

<

When followed by one or more of the characters B, I, U, O, and S, defines the character style of the item to Bold, Italic, Underline, Outline, or Shadow, respectively.

/

When followed by a character, defines the keyboard equivalent for the item. When followed by 0x1B or the equivalent constant hMenuCmd, specifies that this menu item has a submenu. To specify that the menu item has a text encoding, small icon, or reduced icon, use the SetItemCmd function to set the keyboard equivalent field to 0x1C, 0x1D, or 0x1E, respectively.

(

Defines the menu item as disabled.

You can specify any, all, or none of these metacharacters in the text string. The metacharacters that you specify aren’t displayed in the menu item. (To use any of these metacharacters in the text of a menu item, first use AppendMenu, specifying at least one character as the item’s text, and then use the function SetMenuItemText to set the item’s text to the desired string.)

If you add menu items using the AppendMenu function, you should define the text and any marks or keyboard equivalents in resources for easier localization.

You can specify the first character that defines the text of a menu item as a hyphen to create a divider line. The string in the data parameter can be blank (containing one or more spaces), but it should not be an empty string.

If you do not define a specific characteristic of a menu item, the AppendMenu function assigns the default characteristic to the menu item. If you do not define any characteristic other than the text for a menu item, the AppendMenu function inserts the menu item so that it appears in the menu as an enabled item, without an icon or a mark, in the plain character style, and without a keyboard equivalent.

You can use AppendMenu to append items to a menu regardless of whether the menu is in the current menu list.

Availability
Related Sample Code
Declared In
Menus.h

AppendMenuItemText

Appends a menu item to a menu. (Deprecated in Mac OS X v10.5.)

Not recommended

OSStatus AppendMenuItemText (
   MenuRef menu,
   ConstStr255Param inString
);

Parameters
menu

The menu to which the item is to be appended.

inString

A Pascal string containing the text of the menu item to append. You can pass a string containing any characters, and these characters will be presented verbatim in the menu item.

Return Value

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

Discussion

Note that unless you are supporting legacy code, you should use the AppendMenuItemTextWithCFString function instead.

The AppendMenuItemText function appends the menu item containing the specified string to a menu, without evaluating the string for metacharacters, as the pre–Mac OS 8.5 Menu Manager function AppendMenu does. You may wish to use AppendMenuItemText if you need to present non-alphanumeric characters in a menu item.

The appended menu item appears at the end of the menu as an enabled item. If you wish to place the menu item elsewhere than at the end of the menu you should use the function InsertMenuItemText.

Availability
Declared In
Menus.h

AppendResMenu

Searches all resource files open to your application for a given resource type and appends the names of any resources it finds to a specified menu. (Deprecated in Mac OS X v10.5.)

Not recommended

void AppendResMenu (
   MenuRef theMenu,
   ResType theType
);

Parameters
theMenu

The menu to which to append the names of any resources of a given type that AppendResMenu finds.

theType

A four-character code that identifies the resource type for which to search.

Discussion

Unless you must support legacy code, you should not use functions like AppendResMenu ,which assumes that menu items to append are stored in resources.

If you want to insert fonts into a menu, you should call CreateStandardFontMenu instead.

The AppendResMenu function searches all resource files open to your application for resources of the type defined by the parameter theType. It appends the names of any resources it finds of the given type to the end of the specified menu. AppendResMenu appends the names of found resources in alphabetical order; it does not alphabetize items already in the menu. The AppendResMenu function does not add resources with names that begin with a period (.) or a percent sign (%) to the menu.

AppendResMenu assigns default characteristics to each menu item. Each appended menu item appears in the menu as an enabled item, without an icon or a mark, in the plain character style, and without a keyboard equivalent.

Note that for applications using CarbonLib, you no longer need to call AppendResMenu add resources of type ' DRVR ' to your Apple menu; CarbonLib does this for you automatically.

If you specify that AppendResMenu append resources of type ' FONT ' or ' FOND ', the Menu Manager performs special processing for any resources it finds that have font numbers greater than 0x4000. If the script system associated with the font name is installed in the system, AppendResMenu stores information in the itemDefinitions array (in the itemIcon and itemCmd fields for that item) in the menu structure. This allows the Menu Manager to display the font name in the correct script.

Special Considerations

The AppendResMenu function calls the Resource Manager function SetResLoad (specifying true in the load parameter) before returning. The AppendResMenu function reads the resource data of the resources it finds into memory. If your application does not want the Resource Manager to read resource data into memory when your application calls other functions that read resources, you need to call SetResLoad and specify false in the load parameter after AppendResMenu returns.

Availability
Related Sample Code
Declared In
Menus.h

DeleteMCEntries

Deletes a menu item entry, a menu title entry, the menu bar entry, or all menu item entries of a specific menu from your application’s menu color information table. (Deprecated in Mac OS X v10.5.)

Not recommended

void DeleteMCEntries (
   MenuID menuID,
   short menuItem
);

Parameters
menuID

The menu ID that the DeleteMCEntries function should use to determine which entry to delete from the menu color information table. Specify 0 in the menuID parameter (and the menuItem parameter) to delete the menu bar entry. Specify the menu ID of a menu in the current menu list in the menuID parameter and 0 in the menuItem parameter to delete a specific menu title entry. Specify the menu ID of a menu in the current menu list in the menuID parameter and an item number in the menuItem parameter to delete a specific menu item entry.

menuItem

The menu item that the DeleteMCEntries function should use to determine which entry to delete from the menu color information table. If you specify 0 in this parameter, DeleteMCEntries deletes either the menu bar entry or menu title entry, depending on the value of the menuID parameter. If you specify the item number of a menu item in this parameter and the menu ID of a menu in the current menu list in the menuID parameter, DeleteMCEntries deletes a specific menu item entry. You can also delete all menu item entries for a specific menu from your application’s menu color information table by specifying the constant mctAllItems.

Discussion

If the DeleteMCEntries function does not find the specified entry in your application’s menu color information table, it does not delete the entry. Your application should not delete the last entry in your application’s menu color information table.

If any of the deleted entries changes the menu bar color or a menu title color, your application should call DrawMenuBar to update the menu bar.

Carbon Porting Notes

DeleteMCEntries does nothing, because the Appearance Manager doesn’t use color tables.

Availability
Declared In
Menus.h

DisposeMCInfo

Disposes of a menu color information table. (Deprecated in Mac OS X v10.5.)

Not recommended

void DisposeMCInfo (
   MCTableHandle menuCTbl
);

Parameters
menuCTbl

The handle to the menu color information table you want to remove.

Discussion

The DisposeMCInfo function disposes of the menu color information table referred to by the menuCTbl parameter.

Carbon Porting Notes

DisposeMCInfo does nothing, because Appearance Manager doesn’t use color tables.

Availability
Declared In
Menus.h

DisposeMenuDefUPP

Disposes of universal procedure pointer to a custom menu definition. (Deprecated in Mac OS X v10.5.)

Not recommended

void DisposeMenuDefUPP (
   MenuDefUPP userUPP
);

Parameters
userUPP
Carbon Porting Notes

Apple discourages you from writing and using your own menu definition functions and encourages you to use the system-supplied menu definition function instead. New features that have previously been missing are now available in the system-supplied menu definition function. Since Appearance Manager 1.0 (in Mac OS 8.0), for example, the system-supplied menu definition function has supported extended menu item command key modifiers and glyphs. And in Carbon, the system-supplied menu definition function supports dynamic items, which allow the contents of a menu item to be redrawn while the menu is displayed in response to the user pressing a modifier key on the keyboard.

Availability
Declared In
Menus.h

EraseMenuBackground

Erases the menu background to prepare for additional drawing. (Deprecated in Mac OS X v10.5.)

OSStatus EraseMenuBackground (
   MenuRef inMenu,
   const Rect *inEraseRect,
   CGContextRef inContext
);

Parameters
inMenu

The menu whose background you want to erase.

inEraseRect

The bounds of the area to erase, in the local coordinates of the current port.

inContext

The Core Graphics context to erase. If set to NULL, this function creates a new context based on the current port.

Return Value

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

Discussion

Typically you use this function only if you are implementing message-based custom menu definition functions. HIView-based custom menus and normal application code do not need to call EraseMenuBackground.

Before calling the Appearance Manager function DrawThemeMenuBackground, you must erase the current menu background. Themes such as Aqua draw the menu background using an alpha channel, so if the old background is not erased, portions of the old image will show through the menu background.

Availability
Declared In
Menus.h

GetItemIcon

Returns a menu item’s icon or text encoding. (Deprecated in Mac OS X v10.5.)

void GetItemIcon (
   MenuRef theMenu,
   MenuItemIndex item,
   short *iconIndex
);

Parameters
theMenu

The menu containing the item.

item

The menu index of the item.

iconIndex

On output, an integer representing the menu item’s icon or text encoding. For menu items that do not specify 0x1C in the keyboard equivalent field, a value from 1 through 255 if the menu item has an icon associated with it and is 0 otherwise representing the item’s icon number.

Discussion

In most cases, you should use GetMenuItemTextEncoding rather than GetItemIcon to get the menu item’s text encoding.

The GetItemIcon function returns the icon number or text encoding of the specified menu item through the iconIndex parameter (or 0 if the item doesn’t have an icon or a text encoding). If the menu item’s keyboard equivalent field contains 0x1C, the returned number represents the text encoding of the menu item. Otherwise, the returned number represents the item’s icon number.

In the iconIndex parameter, you can add 256 to the icon number to generate the resource ID of the ' cicn ', ' ICON ', or ' SICN ' resource that describes the icon of the menu item. For example, if the GetItemIcon function returns 5 as the icon number, then the icon of the menu item is described by an icon resource with resource ID 261.

For menu items that contain 0x1C in the keyboard equivalent field, the GetItemIcon function returns the text encoding of the menu item. The Menu Manager displays the menu item using this text encoding if the corresponding script system is installed.

Availability
Declared In
Menus.h

GetMCEntry

Gets information about an entry in an application’s menu color information table. (Deprecated in Mac OS X v10.5.)

Not recommended

MCEntryPtr GetMCEntry (
   MenuID menuID,
   short menuItem
);

Parameters
menuID

The menu ID that the GetMCEntry function should use to return information about the menu color information table. Specify 0 in the menuID parameter (and the menuItem parameter) to get the menu bar entry. Specify the menu ID of a menu in the current menu list in the menuID parameter and 0 in the menuItem parameter to get a specific menu title entry. Specify the menu ID of a menu in the current menu list in the menuID parameter and an item number in the menuItem parameter to get a specific menu item entry.

menuItem

The menu item that the GetMCEntry function should use to return information about the menu color information table. If you specify 0 in this parameter, GetMCEntry returns either the menu bar entry or the menu title entry, depending on the value of the menuID parameter. If you specify the item number of a menu item in this parameter and the menu ID of a menu in the current menu list in the menuID parameter, GetMCEntry returns a specific menu item entry.

Return Value

A menu bar entry, a menu title entry, or a menu item entry according to the values specified in the menuID and menuItem parameters. If the GetMCEntry function finds the specified entry in your application’s menu color information table, it returns a pointer to a structure of data type MCEntry. If the specified entry is not found, GetMCEntry returns null. The menu color information table is relocatable, so the pointer returned by the GetMCEntry function may not be valid across functions that may move or purge memory. Your application should make a copy of the menu color entry structure if necessary. See page for a description of the MCEntry data structure.

Carbon Porting Notes

GetMCEntry does nothing, because Appearance Manager doesn’t use color tables.

Availability
Declared In
Menus.h

GetMCInfo

Returns a handle to a copy of your application’s menu color information table. (Deprecated in Mac OS X v10.5.)

Not recommended

MCTableHandle GetMCInfo (
   void
);

Return Value

A handle to a copy of your application’s menu color information table. If the copy fails, GetMCInfo returns null.

Carbon Porting Notes

The Menu Manager ignores color tables in Mac OS X, so there is no reason to call GetMCInfo.

Availability
Declared In
Menus.h

GetMenuItemHierarchicalID

Obtains the menu ID of a specified submenu. (Deprecated in Mac OS X v10.5.)

OSErr GetMenuItemHierarchicalID (
   MenuRef inMenu,
   MenuItemIndex inItem,
   MenuID *outHierID
);

Parameters
inMenu

The menu that contains the menu item for which you wish to get the submenu’s menu ID.

inItem

The menu index of the item.

outHierID

Pass a pointer to a signed 16-bit integer value. On return, the value is set to the menu ID of the submenu.

Return Value

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

Availability
Declared In
Menus.h

GetMenuItemText

Obtains the text of a menu item. (Deprecated in Mac OS X v10.5.)

Not recommended

void GetMenuItemText (
   MenuRef theMenu,
   MenuItemIndex item,
   Str255 itemString
);

Parameters
theMenu

The menu containing the item.

item

The menu index of the item.

itemString

On output, the menu item’s text string.

Discussion

Unless you need to support legacy code, you should use the CopyMenuItemTextAsCFString instead.

Availability
Related Sample Code
Declared In
Menus.h

GetMenuItemTextEncoding

Obtains the text encoding used for a menu item’s text. (Deprecated in Mac OS X v10.5.)

OSErr GetMenuItemTextEncoding (
   MenuRef inMenu,
   MenuItemIndex inItem,
   TextEncoding *outScriptID
);

Parameters
inMenu

The menu containing the menu item whose text encoding you wish to obtain.

inItem

The menu index of the item.

outScriptID

A pointer to a TextEncoding value. On return, the value is set to the script code of the text encoding used in the menu item’s text.

Return Value

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

Discussion

If a menu item has a command code of 0x1C when GetMenuItemTextEncoding is called, GetMenuItemTextEncoding gets the value in the icon field of the menu item.

See also the function SetMenuItemTextEncoding.

Availability
Declared In
Menus.h

GetMenuRetainCount

Returns the retain count of this menu. (Deprecated in Mac OS X v10.5.)

ItemCount GetMenuRetainCount (
   MenuRef inMenu
);

Parameters
inMenu

The menu whose retain count you want to obtain.

Return Value

The retain count for the menu.

Version Notes

In Mac OS X v10.2 and later, all menus are Core Foundation CFTypes, so you can also call CFGetRetainCount instead of GetMenuRetainCount.

Availability
Declared In
Menus.h

GetMenuTitle

Obtains the title of the menu (Deprecated in Mac OS X v10.5.)

Not recommended

StringPtr GetMenuTitle (
   MenuRef menu,
   Str255 title
);

Parameters
menu
title

The menu title, as a Str255 string.

Return Value

A pointer to the menu title.

Discussion

Unless you need to support legacy code, you should use the CopyMenuTitleAsCFString function instead.

Availability
Declared In
Menus.h

InitContextualMenus

Adds a program to the system registry of contextual menu clients. (Deprecated in Mac OS X v10.5.)

Not recommended

OSStatus InitContextualMenus (
   void
);

Return Value

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

Discussion

Your program should call the InitContextualMenus function early in your startup code to register your application as a contextual menu client. If you do not register your program, some system-level functions may respond as though your program does not use contextual menus. Not registering your program may also cause ProcessIsContextualMenuClient to return an incorrect value.

Carbon Porting Notes

You do not need to call this function before using contextual menus in Mac OS X.

Availability
Declared In
Menus.h

InsertFontResMenu

Inserts menu items from a font resource. (Deprecated in Mac OS X v10.5.)

Not recommended

void InsertFontResMenu (
   MenuRef theMenu,
   MenuItemIndex afterItem,
   short scriptFilter
);

Parameters
theMenu

The menu to add the fonts to.

afterItem

The menu item after which you want to add the fonts.

scriptFilter

The script filter you want to use.

Discussion

Unless you need to do script filtering, you should use CreateStandardFontMenuinstead.

Availability
Declared In
Menus.h

InsertIntlResMenu

Inserts menu items from an internationalized resource. (Deprecated in Mac OS X v10.5.)

Not recommended

void InsertIntlResMenu (
   MenuRef theMenu,
   ResType theType,
   MenuItemIndex afterItem,
   short scriptFilter
);

Parameters
theMenu

The menu to add the menu items to.

theType

The resource to retrieve the menu items from.

afterItem

The menu item after which you want to add the new items.

scriptFilter

The script filter you want to use.

Availability
Declared In
Menus.h

InsertMenuItem

Inserts one or more items into a menu previously created. (Deprecated in Mac OS X v10.5.)

Not recommended

void InsertMenuItem (
   MenuRef theMenu,
   ConstStr255Param itemString,
   short afterItem
);

Parameters
theMenu

The menu to which you wish to add the menu item or items.

itemString

A string that defines the characteristics of the new menu items. Note that in most cases you should store the text of a menu item in a nib file or resource, so that your menu items can be more easily localized. You can specify the contents of the itemString parameter using metacharacters; the function InsertMenuItem accepts the same metacharacters as the AppendMenu function. However, if you specify multiple items, the InsertMenuItem function inserts the items in the reverse of their order in the itemString parameter.

afterItem

The item number of the menu item after which the new menu items are to be added. Specify 0 in the afterItem parameter to insert the new items before the first menu item; specify the item number of a current menu item to insert the new menu items after it; specify a number greater than or equal to the last item in the menu to append the new items to the end of the menu.

Discussion

Note that unless you are supporting legacy code, you should use the InsertMenuItemTextWithCFString function instead.

If you do not define a specific characteristic of a menu item, the InsertMenuItem function assigns the default characteristic to the menu item. If you do not define any characteristic other than the text for a menu item, the InsertMenuItem function inserts the menu item so that it appears in the menu as an enabled item, without an icon or a mark, in the plain character style, and without a keyboard equivalent.

You can use InsertMenuItem to insert items into a menu regardless of whether the menu is in the current menu list.

Availability
Declared In
Menus.h

InsertMenuItemText

Inserts a menu item into a menu. (Deprecated in Mac OS X v10.5.)

Not recommended

OSStatus InsertMenuItemText (
   MenuRef menu,
   ConstStr255Param inString,
   MenuItemIndex afterItem
);

Parameters
menu

The menu into which the item is to be inserted.

inString

A Pascal string containing the text of the menu item to insert. You can pass a string containing any characters, and these characters will be presented verbatim in the menu item.

afterItem

The item number of the menu item after which the new menu item is to be inserted. Specify 0 to insert the new menu item at the top of the menu, before the first menu item. Specify a value greater than or equal to the last menu item to append the new item to the end of the menu.

Return Value

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

Discussion

Note that unless you are supporting legacy code, you should use the InsertMenuItemTextWithCFString function instead.

The InsertMenuItemText function inserts an enabled menu item containing the specified string into a menu, without evaluating the string for metacharacters, as the pre–Mac OS 8.5 Menu Manager function InsertMenuItem does. You may wish to use InsertMenuItemText if you have a need to present non-alphanumeric characters in a menu item.

See also the AppendMenuItemText function.

Availability
Declared In
Menus.h

InsertResMenu

Searches all resource files open to your application for a given resource type and inserts the names of any resources it finds in the specified menu. (Deprecated in Mac OS X v10.5.)

Not recommended

void InsertResMenu (
   MenuRef theMenu,
   ResType theType,
   MenuItemIndex afterItem
);

Parameters
theMenu

The menu to which to add the names of any resources of a given type that InsertResMenu finds.

theType

A four-character code that identifies the resource type for which to search.

afterItem

A number that indicates where in the menu to insert the names of any resources of the given type that InsertResMenu finds. Specify 0 in the afterItem parameter to insert the items before the first menu item; specify the item number of a menu item already in the menu to insert the items after the specified item number. If you specify a number greater than or equal to the last item in the menu, the items are inserted at the end of the menu.

Discussion

Unless you must support legacy code, you should not use functions like InsertResMenu that rely on searching the resource chain. Prior to Carbon, you used InsertResMenu primarily to create an Apple menu (by passing 'DRVR' for the resource type or to create a font menu (by passing 'FONT'). In Carbon, the Apple menu is created for you automatically, and you should call CreateStandardFontMenu to create a font menu.

The InsertResMenu function searches all resource files open to your application for resources of the type defined by the parameter theType. The specified menu must have been previously created using NewMenu , GetMenu , or GetNewMBar. InsertResMenu adds the names of found resources after the specified menu item in alphabetical order; it does not alphabetize items already in the menu.

The InsertResMenu function does not add resources with names that begin with a period (.) or a percent sign (%) to the menu.

The InsertResMenu function assigns default characteristics to each menu item. Each appended menu item appears in the menu as an enabled item, without an icon or a mark, in the plain character style, and without a keyboard equivalent.

If you specify that InsertResMenu add resources of type ' DRVR ' to your Apple menu, InsertResMenu adds the name (and icon) of each item in the Apple Menu Items folder to the menu.

If you specify that InsertResMenu add resources of type ' FONT ' or ' FOND ', the Menu Manager performs special processing for any resources it finds that have font numbers greater than 0x4000. If the script associated with the font name is currently active, InsertResMenu stores information in the itemDefinitions array (in the itemIcon and itemCmd fields for that item) in the menu structure that allows the Menu Manager to display the font name in the correct script.

Special Considerations

The InsertResMenu function calls the Resource Manager function SetResLoad (specifying true in the load parameter) before returning. The InsertResMenu function reads the resource data of the resources it finds into memory. If your application does not want the Resource Manager to read resource data into memory when your application calls other functions that read resources, you need to call the Resource Manager function SetResLoad and specify false in the load parameter after InsertResMenu returns.

Availability
Declared In
Menus.h

InvokeMenuDefUPP

Calls your custom menu definition through a universal procedure pointer. (Deprecated in Mac OS X v10.5.)

Not recommended

void InvokeMenuDefUPP (
   short message,
   MenuRef theMenu,
   Rect *menuRect,
   Point hitPt,
   short *whichItem,
   MenuDefUPP userUPP
);

Parameters
message
theMenu
menuRect
hitPt
whichItem
userUPP
Carbon Porting Notes

Apple discourages you from writing and using your own menu definition functions and encourages you to use the system-supplied menu definition function instead. New features that have previously been missing are now available in the system-supplied menu definition function. Since Appearance Manager 1.0 (in Mac OS 8.0), for example, the system-supplied menu definition function has supported extended menu item command key modifiers and glyphs. And in Carbon, the system-supplied menu definition function supports dynamic items, which allow the contents of a menu item to be redrawn while the menu is displayed in response to the user pressing a modifier key on the keyboard.

Availability
Declared In
Menus.h

MenuKey

Maps a character key with the command key to determine the keyboard equivalent of a menu item in a menu in the current menu list. (Deprecated in Mac OS X v10.5.)

Not recommended

SInt32 MenuKey (
   CharParameter ch
);

Parameters
ch

The 1-byte character that represents the key pressed by the user in combination with the Command key.

Return Value

A value containing the menu ID and menu item that corresponds to the given character.If the given character does not map to an enabled menu item in the current menu list, MenuKey returns 0 in its high-order word and the low-order word is undefined.

Discussion

Note that unless your application uses the WaitNextEvent event model, you should use the Carbon event–based IsMenuKeyEvent instead. Even when using the WaitNextEvent model, you should probably use MenuEvent, as that function supports the Shift, Option, and Control modifier keys in addition to the Command key

The MenuKey function determines whether the key combination maps to a current menu item when the user presses another key while holding down the Command key.

MenuKey does not distinguish between uppercase and lowercase letters. This allows a user to invoke a keyboard equivalent command, such as the Copy command, by pressing the Command key and “c” or “C”. For consistency between applications, you should define the keyboard equivalents of your commands so that they appear in uppercase in your menus.

You should not define menu items with identical keyboard equivalents. The MenuKey function scans the menus from right to left and the items from top to bottom. If you have defined more than one menu item with identical keyboard equivalents, MenuKey returns the first one it finds.

If the given character maps to an enabled menu item in the current menu list, MenuKey highlights the menu title of the chosen menu, returns the menu ID in the high-order word of its function result, and returns the chosen menu item in the low-order word of its function result. After performing the chosen task, your application should unhighlight the menu title using the HiliteMenu function.

The MenuKey function first searches the regular portion of the current menu list for a menu item with a keyboard equivalent matching the given key. If it doesn’t find one there, it searches the submenu portion of the current menu list. If the given key maps to a menu item in a submenu, MenuKey highlights the menu title in the menu bar that the user would normally pull down to begin traversing to the submenu. Your application should perform the desired command and then unhighlight the menu title.

You shouldn’t assign a Command–Shift–number key sequence to a menu item as its keyboard equivalent Command–Shift–number key sequences are reserved for use as ' FKEY ' resources. Command–Shift–number key sequences are not returned to your application, but instead are processed by the Event Manager. The Event Manager invokes the ' FKEY ' resource with a resource ID that corresponds to the number that activates it.

Apple reserves the Command-key codes 0x1B through 0x20 to indicate meanings other than keyboard equivalents. MenuKey ignores these character codes and returns a function result of 0 if you specify any of these values in the ch parameter. Your application should not use these character codes for its own use

Carbon Porting Notes

Carbon does not support desk accessories, so MenuKey cannot be used in OS X to pass keyboard equivalents to desk accessories.

Availability
Related Sample Code
Declared In
Menus.h

NewMenu

Creates an empty menu with a specified title and menu ID. (Deprecated in Mac OS X v10.5.)

Not recommended

MenuRef NewMenu (
   MenuID menuID,
   ConstStr255Param menuTitle
);

Parameters
menuID

The ID for the menu. The menu ID is a number that identifies the menu. Menu IDs in Carbon can be any value, but Apple recommends that the ID be either zero or positive. A menu ID of zero is a valid ID. IDs of submenus should similarly be zero or a positive value.

menuTitle

The title of the new menu. Note that in most cases you should store the titles of menus in resources, so that your menu titles can be more easily localized.

Return Value

A menu reference. If the NewMenu function is unable to create the menu structure, it returns NULL. See the description of the MenuRef data type.

Discussion

Unless you must support legacy code, you should not use functions like NewMenu. If you need to create menus programmatically, you can call CreateNewMenu; otherwise you should define menus in Interface Builder, store them as nib files, and then call the Interface Builder Services function CreateMenuFromNib to create them.

The NewMenu function creates a menu with the specified title, assigns it the specified menu ID, and returns a handle to the menu structure. It sets up the menu structure to use the standard menu definition function (and it reads the standard menu definition function into memory if it isn’t already there). NewMenu does not insert the newly created menu into the current menu list.

After creating a menu with NewMenu, use AppendMenu , InsertMenuItem , AppendResMenu , or InsertResMenu to add menu items to the menu. To add a menu created by NewMenu to the current menu list, use InsertMenu. In Carbon, you do not need to call DrawMenuBar to update the menu bar, as the Menu Manager automatically invalidates andredraws the menu bar.

Menus in a resource must not be purgeable nor should the resource lock bit be set. Do not define a “circular” hierarchical menu—that is, a hierarchical menu in which a submenu has a submenu whose submenu is a hierarchical menu higher in the chain.

Special Considerations

To release the memory associated with a menu that you created using NewMenu, first call DeleteMenu to remove the menu from the current menu list and to remove any entries for this menu in your application’s menu color information table then call DisposeMenu to dispose of the menu structure. Note that in Carbon, the Menu Manager automatically invalidates and redraws the menu bar after disposing of a menu.

Version Notes

Note that if you are running on Mac OS 8.1 and earlier, the menu ID of a submenu must be within the range 0 to 255.

Availability
Related Sample Code
Declared In
Menus.h

NewMenuDefUPP

Creates a new univeral procedure pointer to your custom menu definition. (Deprecated in Mac OS X v10.5.)

Not recommended

MenuDefUPP NewMenuDefUPP (
   MenuDefProcPtr userRoutine
);

Parameters
userRoutine
Return Value

See the description of the MenuDefUPP data type.

Carbon Porting Notes

Apple discourages you from writing and using your own menu definition functions and encourages you to use the system-supplied menu definition function instead. New features that have previously been missing are now available in the system-supplied menu definition function. Since Appearance Manager 1.0 (in Mac OS 8.0), for example, the system-supplied menu definition function has supported extended menu item command key modifiers and glyphs. And in Carbon, the system-supplied menu definition function supports dynamic items, which allow the contents of a menu item to be redrawn while the menu is displayed in response to the user pressing a modifier key on the keyboard.

Availability
Declared In
Menus.h

ProcessIsContextualMenuClient

Determines whether a given program is a contextual menu client. (Deprecated in Mac OS X v10.5.)

Not recommended

Boolean ProcessIsContextualMenuClient (
   ProcessSerialNumber *inPSN
);

Parameters
inPSN

A pointer to the ID of the process containing the program.

Return Value

true if the program in the process uses contextual menus; otherwise, false.

Discussion

In Mac OS X, you do not need to call InitContextualMenus to register your application, so this function call is unnecessary.

The ProcessIsContextualMenuClient function checks the system registry of contextual menu clients and returns true if the program in the given process supports contextual menus. However, the program must have been registered as a client using InitContextualMenus.

See also “Contextual Menu Gestalt Selector Constants.”

Version Notes

This function is available with Appearance Manager 1.0 and later.

Availability
Declared In
Menus.h

ReleaseMenu

Decrements the retain count of a menu. (Deprecated in Mac OS X v10.5.)

OSStatus ReleaseMenu (
   MenuRef inMenu
);

Parameters
inMenu

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

Return Value

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

Discussion

The reference that you pass in the theMenu parameter is not valid after DisposeMenu returns. This function is identical to DisposeMenu.

Version Notes

In Mac OS X v10.2 and later, all menus are Core Foundation CFTypes, so you can optionally call CFRelease instead of ReleaseMenu.

Availability
Related Sample Code
Declared In
Menus.h

RetainMenu

Increments the reference count of a menu. (Deprecated in Mac OS X v10.5.)

OSStatus RetainMenu (
   MenuRef inMenu
);

Parameters
inMenu

The menu whose reference count you want to increment.

Return Value

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

Discussion

RetainMenu does not create a new menu. It simply adds one to the reference count.

Version Notes

In Mac OS X v10.2 and later, all menus are Core Foundation CFTypes, so you can optionally call CFRetain instead of RetainMenu.

Availability
Declared In
Menus.h

ScrollMenuImage

Scrolls a portion of the menu image. (Deprecated in Mac OS X v10.5.)

OSStatus ScrollMenuImage (
   MenuRef inMenu,
   const Rect *inScrollRect,
   int inHScroll,
   int inVScroll,
   CGContextRef inContext
);

Parameters
inMenu

The menu to scroll.

inScrollRect

The bounds of the area to scroll.

inHScroll

The distance to scroll horizontally, in pixels.

inVScroll

The distance to scroll vertically, in pixels.

inContext

The Core Graphics context to scroll. If you pass NULL, the function creates a context based on the current port.

Return Value

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

Discussion

Scrolling menus on Mac OS X using ScrollRect or other QuickDraw functions destroys the alpha channel data, so you should use ScrollMenuImage instead.

Availability
Declared In
Menus.h

SetItemIcon

Sets a menu item’s icon or text encoding. (Deprecated in Mac OS X v10.5.)

void SetItemIcon (
   MenuRef theMenu,
   MenuItemIndex item,
   short iconIndex
);

Parameters
theMenu

The menu containing the item.

item

The menu index of the item.

iconIndex

An integer representing the icon number or text encoding for the specified menu item. If the menu item’s keyboard equivalent field does not contain 0x1C, the SetItemIcon function sets the icon number of the item’s icon to the number defined in this parameter. The icon number you specify should be a value from 1 through 255 (or from 1 through 254 if the item has a small or reduced icon) or 0 if the item does not have an icon.

The Menu Manager adds 256 to the icon number to generate the resource ID of the 'cicn' or 'ICON' resource that describes the icon of the menu item. For example, if you specify 5 as the value of the iconIndex parameter, when the Menu Manager needs to draw the item, it looks for an icon resource with resource ID 261.

If the menu item’s keyboard equivalent field contains 0x1C, the SetItemIcon function sets the text encoding of the menu item to the number defined in the iconIndex parameter. The Menu Manager displays the menu item using the specified text encoding if the corresponding script system is installed.

You can specify 0 in the iconIndex parameter to indicate that the item uses the current system script and does not have an icon number.

Discussion

In most cases, you should use SetMenuItemTextEncoding rather than SetItemIcon to set the menu item’s text encoding.

The SetItemIcon function sets the icon number (for resource-based icons) or text encoding of the specified menu item to the value in the iconIndex parameter. To use handle-based icons, call SetMenuItemIconHandle. Usually you display menu items in the current system script; however, if needed, you can use the SetItemIcon function to set the text encoding of a menu item. For an item’s text encoding to be set, the keyboard equivalent field of the item must contain 0x1C. If the keyboard equivalent field contains any other value, the SetItemIcon function interprets the specified number as the item’s icon number.

Availability
Declared In
Menus.h

SetMCEntries

Sets entries in an application’s menu color information table. (Deprecated in Mac OS X v10.5.)

Not recommended

void SetMCEntries (
   short numEntries,
   MCTablePtr menuCEntries
);

Parameters
numEntries

The number of entries contained in the array of menu color entry structures.

menuCEntries

A pointer to an array of menu color entry structures. Specify the number of structures in the array in the numEntries parameter.

Discussion

The SetMCEntries function sets any specified menu bar entry, menu title entry, or menu item entry according to the values specified in the menu color entry structures. If an entry already exists for a specified menu color entry, the SetMCEntries function updates the entry in your application’s menu color information table with the new values. If the entry doesn’t exist, it is added to your application’s menu color information table.

If any of the added entries specify a new menu bar color or new menu title colors, your application should call DrawMenuBar to update the menu bar with the new colors.

Special Considerations

The SetMCEntries function may move or purge memory. Your application should make sure that the array specified by the menuCEntries parameter is nonrelocatable before calling SetMCEntries.

Carbon Porting Notes

SetMCEntries does nothing, because Appearance Manager doesn’t use color tables.

Availability
Declared In
Menus.h

SetMCInfo

Makes a copy of your application’s menu color information table. (Deprecated in Mac OS X v10.5.)

Not recommended

void SetMCInfo (
   MCTableHandle menuCTbl
);

Parameters
menuCTbl

A handle to a copy of your application’s menu color information table.

Discussion

The SetMCInfo function copies the table specified by the menuCTbl parameter to your application’s menu color information table. If successful, the SetMCInfo function is responsible for disposing of your application’s current menu color information table, so your application does not need to explicitly dispose of the current table.

Your application should call the Memory Manager function MemError to determine whether the SetMCInfo function successfully copied the table. If the SetMCInfo function cannot successfully copy the table, it does not dispose of the current menu color information table and the MemError function returns a nonzero result code. If the SetMCInfo function is able to successfully copy the table, it disposes of the current menu color information table and the MemError function returns the noErr result code.

If the menu color information table specifies a new menu bar color or new menu title colors, your application should call DrawMenuBar after calling SetMCInfo.

Note that GetNewMBar does not save your application’s current menu color information table. If your application changes menu bars, you can save and restore your application’s current menu color information table by calling GetMCInfo before GetNewMBar and calling SetMCInfo afterward.

Carbon Porting Notes

SetMCInfo does nothing, because Appearance Manager doesn’t use color tables.

Availability
Declared In
Menus.h

SetMenuFlashCount

Specifies whether a menu should fade slowly or immediately disappear when closing. (Deprecated in Mac OS X v10.5.)

Modified

void SetMenuFlashCount (
   short count
);

Parameters
count

See the Discussion.

Discussion

Unlike the classic Mac OS version, SetMenuFlashCount no longer lets you set the flash count for a menu. In Mac OS X, the flash count is always 1, and it not user adjustable.

Passing zero for the count parameter causes menus to disappear immediately when closing; passing any nonzero parameter causes the menus to fade out when closing (the default).

Availability
Declared In
Menus.h

SetMenuItemHierarchicalID

Attaches a submenu to a menu item. (Deprecated in Mac OS X v10.5.)

OSErr SetMenuItemHierarchicalID (
   MenuRef inMenu,
   MenuItemIndex inItem,
   MenuID inHierID
);

Parameters
inMenu

The menu that contains the menu item to which you wish to attach a submenu.

inItem

The menu index of the item.

inHierID

An integer representing the menu ID of the submenu you wish to attach. This menu should be inserted into the menu list by calling InsertMenu with the kInsertHierarchicalMenu constant.

Return Value

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

Discussion

The SetMenuItemHierarchicalID function should be called instead of setting the keyboard equivalent to 0x1B. You should call SetMenuItemHierarchicalID instead of SetItemMark to set the menu ID of a menu item’s submenu. However, you can still use SetItemMark to set the mark of a menu item.

Availability
Declared In
Menus.h

SetMenuItemText

Sets menu item text to a specified string. (Deprecated in Mac OS X v10.5.)

Not recommended

void SetMenuItemText (
   MenuRef theMenu,
   MenuItemIndex item,
   ConstStr255Param itemString
);

Parameters
theMenu

The menu containing the item.

item

The menu index of the item.

itemString

The menu item’s text string. This parameter must not be NULL or an empty (zero-length) string. Do not use meta–font characters in this parameter.

Your menu item text string must be limited to 250 bytes. 251 or more bytes will cause the Menu Manager to crash.

Discussion

The SetMenuItemText function does not recognize any metacharacters used by AppendMenu and InsertMenuItem.

If you set the text of a menu item using the SetMenuItemText function, you should store the text in a string resource so that your application can be more easily localized.

Carbon Porting Notes

n Carbon, you should use the SetMenuItemTextWithCFString function instead.

Availability
Declared In
Menus.h

SetMenuItemTextEncoding

Sets the text encoding for a menu item’s text. (Deprecated in Mac OS X v10.5.)

OSErr SetMenuItemTextEncoding (
   MenuRef inMenu,
   MenuItemIndex inItem,
   TextEncoding inScriptID
);

Parameters
inMenu

The menu containing the menu item whose text encoding you wish to set.

inItem

The menu index of the item.

inScriptID

The script code that corresponds to the text encoding you wish to set.

Return Value

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

Discussion

If a menu item has a command code of 0x1C when SetMenuItemTextEncoding is called, the values in the menu item’s command key and icon ID fields are cleared and replaced with the value in the inScriptID parameter of SetMenuItemTextEncoding.

See also the function GetMenuItemTextEncoding.

Availability
Declared In
Menus.h

SetMenuTitle

Sets the title of a menu. (Deprecated in Mac OS X v10.5.)

Not Recommended

OSStatus SetMenuTitle (
   MenuRef menu,
   ConstStr255Param title
);

Parameters
menu

The menu whose title you want to set.

title

A string containing the menu title to set.

Return Value

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

Discussion

Unless you need to support legacy code, you should use the SetMenuTitleWithCFString function instead.

Availability
Declared In
Menus.h

< Previous PageNext Page > Hide TOC

© 1992, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-09-15)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.