All Databases Inside Mac - Basic Toolbox

InsMenuItem

Insert an item into a menu

#include <Menus.h> Menu Manager

void InsMenuItem(theMenu, itemText, afterItem );

MenuHandle theMenu ; handle of menu in which to insert an item

Str255 itemText ; address of length-prefixed text; metachars OK

short afterItem ; 0=before first; else=where to put the item

InsMenuItem lets you place a new item into a menu at any place in the

menu. It is useful in manipulating menus that change, such as a list of open

windows. It also defines whether an item is a submenu.

theMenu is the handle of a menu obtained via NewMenu or GetMenu. It

leads to a variable-length MenuInfo structure.

itemText is the address of a length-prefixed, Pascal-style string containing

the text of the item to insert. The string may be blank, but must not

be empty. Multiple items are separated by semi-colons (;). The

following lists special meta characters that may be embedded in

itemText :

Char Dec Hex Description

; 59 0x3B Item separator

Return 13 0x0D Item separator

^ 94 0x5E Next character specifies an icon (its

resource ID is char ASCII value + 208 )

! 33 0x21 Next char is "mark"; e.g., \030 = " ...OR...

when cmd-key is 0x1B, this is a submenu ID

< 60 0x3C Next char specifies style (B,I,U,O, or S)

/ 47 0x2f Next char is a command-key equivalent ...OR...

when next char is 0x1B, this is a submenu title

( 40 0x28 This item is disabled (dimmed)

- 45 0x2d (When first char) "item" is a dotted line

Normally used with ("; e.g. "\p(-

afterItem specifies where the new item should be inserted it is one of:

0 The new item goes before all other items

valid item ID The new item goes after the item designated by afterItem

high number If afterItem is higher than any current item ID, the new item

is appended to the end of the menu.

Returns: none

Notes: InsMenuItem and DelMenuItem are available for systems having the

128K or later versions of the ROMs.

Note that when an item is inserted into a menu, the item IDs of other menu

items (those having IDs higher than afterItem ) are increased by 1. For

instance in the following sequence, the item labeled "Item 3" gets

re numbered and its item ID becomes 4.

AppendMenu( theMenu, "\pItem 1;Item 2;Item 3" );

InsMenuItem( theMenu, "\pAnew Item", 2 );

As with AppendMenu, it is OK to insert multiple items, separated by

semicolons (;). However, the items are inserted in the reverse of the order

they are listed in itemText.

To insert a submenu item, use a command key of 0x1b and a menu-ID item

mark. The following creates a submenu and inserts it into a menu:

subMenuHandle = NewMenu( 7, "Options" ); /* menu ID is 7 */

AppendMenu( subMenuHandle, "\pOption1; Option2; Option 3" );

InsertMenu( subMenu, hierMenu ); /* i.e., beforeID is -1 */

/* add to File menu; use cmd-key = 0x1B and item mark = 7 */

AppendMenu( fileMenuHandle, "\pOptions /\033!\007" );

Or, you may find it easier to call SetItemCmd and SetItemMark to

install the submenu.