- Introduction—Types of Menus
- Pull-Down Menus
- Hierarchical Menus
- Pop-Up Menus
- Menu Objects, Menu IDs and Item Numbers, Command IDs, and Menu Lists
- Creating Your Application's Menus
- Providing Help Balloons (Mac OS 8/9)
- Changing Menu Item Appearance
- Adding Items to a Menu
- Associating Data with Menu Items
- Handling Menu Choices
- Hiding and Showing the Menu Bar
- Accessing Menus from Alerts and Dialogs
- Main Menu Manager Constants, Data Types, and Functions
- Demonstration Program Menus1 Listing
- Demonstration Program Menus1 Comments
- Demonstration Program Menus2 Listing
- Demonstration Program Menus2 Comments
This chapter is from the book
This chapter is from the book
This chapter is from the book
Adding Items to a Menu
Adding Items Other Than the Names of Resources
AppendMenu, InsertMenuItem, AppendMenuItemText, AppendMenuItemTextWithCFString, InsertMenuItemText and InsertMenuItemTextWithCFString are used to add items other than the names of resources (such as font resources) to a previously created menu. They require:
A reference to the menu object of the menu involved.
A string describing the items to add.
Strings with Metacharacters
AppendMenu and InsertMenuItem allow you to specify the same characteristics for menu items as are available when defining a 'MENU' resource. The string consists of the text of the menu item and any required characteristics. You can specify a hyphen as the menu item text to create a divider. You can also use various metacharacters in the text string to separate menu items and to specify the required characteristics. The following metacharacters may be used:
|
MetaCharacter |
Description |
|
; or Return |
Separates menu items. |
|
^ |
When followed by an icon number, defines the icon for the item. |
|
! |
When followed by a character, defines the mark for the item. |
|
|
If the keyboard equivalent field contains 0x1B, this value is interpreted as the menu ID of a submenu of this menu item.1 |
|
< |
When followed by one or more of the characters B, I, U, O, and S, defines the character style of the item to, respectively, bold, italic, underline, outline or shadow. |
|
/ |
When followed by a character, defines the Command-key equivalent for the item.2 When followed by 0x1B, specifies that this menu item has a submenu.1 (Note: To specify that a menu item has a script code, reduced icon or small icon, use SetItemCmd to set the keyboard equivalent field to, respectively, 0x1C, 0x1D or 0x1E.3 ) |
|
( |
Defines the menu item as disabled. |
As an example of the use of metacharacters, assume that the following two strings are stored in a string list ('STR#') resource:
Pick a Color... (^2!=Everything<B/E
The second string in this resource uses metacharacters to specify that the menu item is to be disabled, that it has an icon with a resource ID 258 (2+256), that it has the "=" character as a marking character, that the text style is bold, and that the item has a Command-key equivalent of Command-E.
NOTE
The Menu Manager adds 256 to the number you specify, and uses the result as the icon's resource ID.
Examples
The following code uses AppendMenu to append a menu item with no specific characteristics other than its text to the menu identified by the menu reference. The text for the menu item is "Pick a Color..." as stored in the preceding 'STR#' resource.
MenuRef menuRef; Str255 itemString; ... menuRef = GetMenuRef(mLibrary); GetIndString(itemString,300,1); AppendMenu(menuRef,itemString);
To insert an item after a given menu item, use InsertMenuItem. The following code inserts the menu item "Everything" after the menu item with the item number specified in the iRed constant:
MenuRef menuRef; Str255 ItemString; ... menuRef = GetMenuRef(mColors); GetIndString(itemString,300,2); InsertMenuItem(menuRef,itemString,iRed);
The following code appends multiple items to the Edit menu using AppendMenu:
MenuRef menuRef; ... menuRef = GetMenuRef(mEdit); AppendMenu(menuRef,"\pUndo/Z;-;Cut/X;Copy/C;Paste/V");
InsertMenuItem differs from AppendMenu in the way it handles the given text string when that string contains multiple items, inserting them in reverse order. This code is equivalent to the last line of the preceding code:
InsertMenuItem(menuRef,"\pPaste/V;Copy/C;Cut/X-;-;Undo/Z",0);
The following code adds a divider to the Edit menu:
AppendMenu(menuRef,"\p(-");
Strings Without Metacharacters
AppendMenuItemText, AppendMenuItemTextWithCFString, InsertMenuItemText and InsertMenuItemTextWithCFString append and insert the specified string without evaluating the string for metacharacters. These functions may be used if you have a need to present non-alphanumeric characters in a menu item.
Adding Items Comprising Resource Names to a Menu
AppendResMenu or InsertResMenu may be used to add items that consist of resource names to a menu. For example, you can use AppendResMenu to add the names of all resident fonts as menu items in your application's Font menu.