Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Macintosh Toolbox Essentials /: Chapter 3 - Menu Manager / Using the Menu Manager

Adding Items to a Menu
Usually you define a menu and all its items in a 'MENU' resource. Occasionally you might need to add items to a menu after you've created it. After creating a menu (using NewMenu, GetMenu, or GetNewMBar), you can add items to it using the AppendMenu, InsertMenuItem, AppendResMenu, or InsertResMenu procedure.
You can use AppendResMenu or InsertResMenu to add items that consist of resource names to a menu. For example, you can use the AppendResMenu procedure to add fonts to your application's Font menu or to add all of the desktop items from the Apple Menu Items folder to your application's Apple menu. These are common instances when you'll need to add items not already defined in a 'MENU' resource to a menu. See "Adding Fonts to a Menu" on page 3-71 and "Adding Items to the Apple Menu" on page 3-70 for information on adding names of resources to menus.
If you add items to your application's Help menu, you'll need to use AppendMenu or InsertMenuItem to add the additional items. This section discusses how to add items using the AppendMenu and InsertMenuItem procedures, and "Adding Items to the Help Menu" on page 3-69 shows a specific example of adding items to the Help menu.
If you need to add items other than the names of resources to a previously created menu, you can use the AppendMenu or InsertMenuItem procedure. You can use AppendMenu to add items to the end of a menu; note that you can add items to only the end of the menu when using AppendMenu. Use InsertMenuItem to add items after any given item in a menu. When you add items to a menu using AppendMenu or InsertMenuItem, you can specify the same characteristics for menu items that are available to you when defining 'MENU' resources.
You specify a handle to the menu record of the menu to which you want to add the item or items, and you specify a string describing the items to add as parameters to the AppendMenu or InsertMenuItem procedure. The string you pass to these procedures should consist of the text and any characteristics of the menu items. You can specify a hyphen as the menu item text to create a divider line. You can also use various metacharacters in the text string to separate menu items and to specify certain characteristics of the menu items. The metacharacters aren't displayed in the menu.
Here is a list of the metacharacters you can use in the text string that you specify to the AppendMenu or InsertMenuItem procedure:
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.
< 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 to define the characteristics of a menu item. Note that 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 or InsertMenuItem, specifying at least one character as the item's text. Then use the SetMenuItemText procedure to set the item's text to the desired string.)

Note
If you add menu items using the AppendMenu or InsertMenuItem procedure, you should define the text and any marks or keyboard equivalents in resources for easier localization.
Listing 3-13 shows a string list ('STR#') resource that stores the text of the menu items used in the next examples.
Listing 3-13 Rez input for text of menu items
resource 'STR#' (300, "Text for appended menu items") {
   {
   /*[1]*/
   "Just Text";
   /*[2]*/
   "Pick a Color...";
   /*[3]*/
   "(^2!=Everything<B/E";
   }
);
Here's code that uses the AppendMenu procedure to append a menu item with no specific characteristics other than its text to the menu identified by the menu handle in the myMenu variable. The text for the menu item is "Just Text" as stored in the 'STR#' resource with resource ID 300.
VAR
   myMenu:     MenuHandle;
   itemString: Str255;
   myMenu := GetMenuHandle(mLibrary);
   GetIndString(itemString, 300, 1);
   AppendMenu(myMenu, itemString);
To insert an item after a given menu item, use the InsertMenuItem procedure. For example, this code inserts the menu item Pick a Color after the menu item with the item number specified by the iRed constant. The text for the new menu item consists of the string "Pick a Color..." as stored in the 'STR#' resource with resource ID 300.
VAR
   myMenu:     MenuHandle;
   itemString: Str255;
   myMenu := GetMenuHandle(mColors);
   GetIndString(itemString, 300, 2);
   InsertMenuItem(myMenu, itemString, iRed);
If you do not explicitly specify a value for an item characteristic in the text string that you pass to AppendMenu or InsertMenuItem, the procedure assigns the default value for that characteristic. The Menu Manager defines the default item characteristics as no icon, no marking character, no keyboard equivalent, and plain text style. AppendMenu and InsertMenuItem enable the added menu items unless you specify otherwise.
This code appends a menu item with the text "Everything" to the menu identified by the menu handle in the myMenu variable. The text and other characteristics of this menu item are stored in the 'STR#' resource shown in Listing 3-13. It also specifies that this menu item is disabled, has an icon with resource ID 258 (2 + 256), and has the "=" character as a marking character; the style of the text is Bold; and the menu item has a keyboard equivalent of Command-E.
VAR
   myMenu:     MenuHandle;
   itemString: Str255;

   myMenu := GetMenuHandle(mLibrary);
   GetIndString(itemString, 300, 3);
   AppendMenu(myMenu, itemString);
This code appends multiple items to the Edit menu using AppendMenu:
VAR
   myMenu:     MenuHandle;

   myMenu := GetMenuHandle(mEdit);
   AppendMenu(myMenu, 'Undo/Z;-;Cut/X;Copy/C;Paste/V'); 
The InsertMenuItem procedure differs from AppendMenu in how it handles the given text string when the text string specifies multiple items. The InsertMenuItem procedure inserts the items in the reverse of their order in the text string. For example, this code inserts menu items into the Edit menu using InsertMenuItem and is equivalent to the previous example:
VAR
   myMenu:     MenuHandle;

   myMenu := GetMenuHandle(mEdit);
   InsertMenuItem(myMenu, 'Paste/V';Copy/C;Cut/X;-;Undo/Z',0);
Once you've added a menu item to a menu, you can change any of its characteristics using Menu Manager routines, as described in "Changing the Appearance of Items in a Menu" on page 3-59.

Adding Items to the Help Menu
You add items to the Help menu by using the HMGetHelpMenuHandle function and either the AppendMenu or InsertMenuItem procedure.
The HMGetHelpMenuHandle function returns a copy of the handle to the menu record of your application's Help menu. Do not use the GetMenuHandle function to get a handle to the Help menu, because GetMenuHandle returns a handle to the global Help menu, not the Help menu that is specific to your application. Once you have a handle to the Help menu that is specific to your application, you can add items to it using the AppendMenu procedure or other Menu Manager routines. For example, Listing 3-14 adds the menu item displayed in Figure 3-19 on page 3-35.
Listing 3-14 Adding an item to the Help menu
PROCEDURE MyAddHelpItem;
VAR
   myMenu:     MenuHandle;
   myErr:      OSErr;
   itemString: Str255;
BEGIN
   myErr := HMGetHelpMenuHandle(myMenu);
   IF myErr = noErr THEN
      IF myMenu <> NIL THEN
      BEGIN
         {get the string (with index kSurfHelp) from the 'STR#' }
         { resource with resource ID kMyStrings}
         GetIndString(itemString, kMyStrings, kSurfHelp);
         AppendMenu(myMenu, itemString);
      END;
END;
When you add items to the Help menu, the Help Manager automatically adds a divider between the end of the standard Help menu items and your items.
Be sure to use an 'hmnu' resource and specify the kHMHelpMenuID constant as the resource ID to provide help balloons for items you've added to the Help menu. (The Help Manager automatically creates the help balloons for the Help menu title and the standard Help menu items.) See the chapter "Help Manager" in Inside Macintosh: More Macintosh Toolbox for specific information on the 'hmnu' resource.
The Help Manager automatically processes the event when a user chooses any of the standard menu items in the Help menu. The Help Manager automatically enables and disables help when the user chooses Show Balloons or Hide Balloons from the Help menu. The setting of Balloon Help is global and affects all applications. See "Handling the Help Menu" on page 3-83 for information on responding to the user when the user chooses one of your appended items.

Adding Items to the Apple Menu
To insert the items contained in the Apple Menu Items folder into your application's Apple menu, use the AppendResMenu or InsertResMenu procedure and specify 'DRVR' as the resource type. Doing so causes this procedure to automatically add all items in the Apple Menu Items folder to the specified menu.
The user can place any desktop object in the Apple Menu Items folder. When the user places an item in this folder, the system software automatically adds it to the list of items in the Apple menu of all open applications.
After inserting the Apple menu into your application's menu bar (by using GetNewMBar or GetMenu and InsertMenu), your application can add items to it. Listing 3-15 shows code that uses GetMenuHandle to get a handle to the application's Apple menu. The code then uses the AppendResMenu procedure, specifying that AppendResMenu should add all desktop items in the Apple Menu Items folder to the application's Apple menu.
Listing 3-15 Adding menu items to the Apple menu
VAR
   myMenu:           MenuHandle;

   myMenu := GetMenuHandle(mApple);
   IF myMenu <> NIL THEN
      AppendResMenu(myMenu, 'DRVR');{add desktop items in the }
                                    { Apple Menu Items folder }
                                    { to the Apple menu}
Listing 3-16 on page 3-72 shows a complete sample that sets up an application's menu bar, adds items to the Apple menu, adds items to the Font menu, and then updates the appearance of the menu bar.

Adding Fonts to a Menu
If your application provides a Font menu, you typically include the description of the menu in a 'MENU' resource, include a description of your menu bar in an 'MBAR' resource, and use GetNewMBar to create your menu bar and all menus in the menu bar. Once you've created the menu, you can use AppendResMenu to add the names of all font resources in the Fonts folder of the System Folder (or in system software versions earlier than 7.1, in the System file) as menu items in your application's Font menu. (You can also use InsertResMenu to insert the fonts into your menu.)
Listing 3-16 on the next page shows how to add names of font resources in the Fonts folder to an application's Font menu. The AppendResMenu procedure adds all resources of the specified type to a given menu. If you specify the resource type 'FONT' or 'FOND', the Menu Manager adds all resources of type 'FOND' and 'FONT' to the menu. ('NFNT' and 'sfnt' resources are specified through 'FOND' resources.)
The AppendResMenu and InsertResMenu procedures perform special processing for any font resources they find that have font numbers greater than $4000. The Menu Manager automatically sets the keyboard equivalent field of the menu item to $1C and stores the script code in the icon field of the menu item for any such 'FOND' resource. The Menu Manager displays a font name in its corresponding script if the script system for that font is installed.
Listing 3-16 Adding font names to a menu
PROCEDURE MyMakeAllMenus; 
VAR
   menu:                MenuHandle;
   menuBar:             Handle;
 BEGIN
                        {read menus in & create new menu list}
   menuBar := GetNewMBar(rMenuBar);    
   IF menuBar = NIL THEN
      EXIT(MyMakeAllMenus);
   SetMenuBar(menuBar); {insert menus into the current menu list}
   DisposHandle(menuBar);
   myMenu := GetMenuHandle(mApple);
   IF myMenu <> NIL THEN                  {add desktop items in }
      AppendResMenu(myMenu, 'DRVR');      { Apple Menu Items }
                                          { folder to Apple menu}
   myMenu := GetMenuHandle(mFont);
   IF myMenu <> NIL THEN               
      AppendResMenu(myMenu, 'FONT');      {add font names to the }
         { Font menu--this adds all bitmapped and TrueType fonts }
         { in the Fonts folder to the Font menu}
   MyAddHelpItem;       {add app-specific item to Help menu}
   MyAdjustMenus;       {adjust menu items}
   DrawMenuBar;         {draw the menu bar}
 END; 
Your application should indicate the current font to the user by placing the appropriate mark next to the text of the menu item that lists the font name. ("Changing the Mark of Menu Items" on page 3-63 explains how to add marks to and remove marks from menu items; Figure 3-13 on page 3-32 and Figure 3-14 on page 3-32 show examples of typical Font menus.)
If your application allows the user to change the font style or font size of text, you should provide separate Size and Style menus. See "Handling a Size Menu" beginning on page 3-84 for information on providing a Size menu in your application.

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.
<	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.