Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 3 - Menu Manager / Menu Manager Reference

Menu Manager Routines / Adding and Deleting Menu Items

InsertMenuItem

Use the InsertMenuItem procedure to insert one or more items to a menu previously created using NewMenu, GetMenu, or GetNewMBar.

The InsertMenuItem procedure is also available as the InsMenuItem procedure.

PROCEDURE InsertMenuItem (theMenu: MenuHandle; itemString: Str255; 
                           afterItem: Integer); 

theMenu

A handle to the menu record of 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 resource, so that your menu items can be more easily localized. You can specify the contents of the itemString parameter using metacharacters; the InsertMenuItem procedure accepts the same metacharacters as the AppendMenu procedure. However, if you specify multiple items, the InsertMenuItem procedure 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.

DESCRIPTION

The InsertMenuItem procedure inserts any defined menu items to the specified menu. The menu items are inserted according to the location specified by the afterItem parameter. You specify the text of any menu items and their characteristics in the itemString parameter. You can embed metacharacters in the string you specify to define various characteristics of a menu item. The metacharacters aren't displayed in
the menu.

Here are the metacharacters you can specify in the itemString parameter:

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 $1C, this number is interpreted as a script code.
!	When followed by a character, defines the mark for the item. If the keyboard equivalent field contains $1B, this value is interpreted as the menu ID of a submenu of this menu item.

Metacharacter	Description
<	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 $1B, specifies that this menu item has a submenu. To specify that the menu item has a script code, small icon, or reduced icon, use the SetItemCmd procedure to set the keyboard equivalent field to $1C, $1D, or $1E, 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 InsertMenuItem, specifying at least one character as the item's text, and then use the SetMenuItemText procedure to set the item's text to the desired string.

Note

If you add menu items using the InsertMenuItem procedure, 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 itemString 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 InsertMenuItem procedure 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 procedure 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.

SEE ALSO

See "Adding Items to a Menu" beginning on page 3-64 for examples.