- 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
Creating Your Application's Menus
'MBAR', 'MENU', and 'xmnu' Resources
As stated in Chapter 1, you can provide a textual, formal description of resources in a file and then use a resource compiler such as Rez to compile the description into a resource, or you can create resource descriptions using a resource editor such as Resorcerer. This book assumes the use of Resorcerer.
When creating resources using Resorcerer, it is advisable that you refer to a diagram and description of the structure of the resource and relate that to the various items in the Resorcerer editing windows. Accordingly, the following describes the structure of those resources associated with the creation of menus.
Structure of a Compiled 'MBAR' Resource
Fig 5 shows the structure of a compiled 'MBAR' resource. The number of menu resource IDs should match the number of menus declared in the first two bytes.
){kind=link}
Figure 3.5 Structure of a compliled MBAR resource.
Structure of a Compiled 'MENU' Resource
Fig 6 shows the structure of a compiled 'MENU' resource (and its variable length data) and how it "feeds" the menu object.
){kind=link}
Figure 3.6 Structue of a compiled menu ("menu") resource and its variable length data.
The following describes the main fields of the 'MENU' resource:
|
Field |
Description |
|
MENU ID |
The menu's unique identification number. Note that the number assigned to the menu ID and the resource ID do not have to be identical, though it is advisable that these numbers be the same. A menu ID from 1 to 235 indicates a menu (or submenu) of an application. Apple reserves the menu ID of 0. |
|
PLACEHOLDER FOR MENU WIDTH PLACEHOLDER FOR MENU HEIGHT |
After reading in the resource data, the Menu Manager requests the menu's MDEF to calculate the width and height of the menu and store these values in the menu object. |
|
RESOURCE ID OF MENU DEFINITION FUNCTION |
If the integer 63 appears here, the standard MDEF will be used. The MDEF is read in after the menu's resource data is read in. The Menu Manager stores a handle to the MDEF in the menu object. |
|
INITIAL ENABLED STATE OF THE MENU AND MENU ITEMS |
A value whose bits indicate if the corresponding menu item is enabled or disabled, with bit 0 indicating whether the menu as a whole is enabled or disabled. |
|
VARIABLE LENGTH DATA THAT DEFINES THE MENU ITEMS |
The Menu Manager stores the variable length data for each menu item at the end of the menu object (see Fig 6). |
The following describes the main fields of the variable length data for each menu item. Note that various alternatives apply to the icon number, keyboard equivalent, and marking character fields. For example, a menu item can have a keyboard equivalent or a submenu, but not both.
|
Field |
Description |
|
ICON NUMBER, SCRIPTCODE, OR 0 |
ICON NUMBER A number from 1 to 255 (or from 1 to 254 for small or reduced icons). If the menu item specifies an icon, you must provide a 'cicn' (color icon) or 'ICON' resource with a resource ID equal to the icon number plus 256. If you want an 'ICON' resource to be reduced to the size of a small icon ('SICN'), or if you want the size of a 'cicn' resource reduced by half, assign the value 0x1D to the keyboard equivalent field. If you want a 'SICN' resource, assign the value 0x1E. The Menu Manager looks first for a 'cicn' resource with the calculated resource ID. In the Carbon era, color icons are much to be preferred. SCRIPTCODE (Not used when the 'MENU' resource is extended with an 'xmnu' resource) Specify the script code here if you want the item's text to be drawn in a script other than the system script, and also provide 0x1C in the keyboard equivalent field. When the 'MENU' resource is extended by an 'xmnu' resource, the script code should be set in the text encoding field of the 'xmnu' resource. 0 Specifies that the menu item does not contain an icon and uses the system script. |
|
KEYBOARD EQUIVALENT, 0X1B, 0X1C, |
KEYBOARD EQUIVALENT 0X1D, OX1E, OR 0 Specified as a one-byte character and, actually, a Command-key equivalent only. The Command-key equivalent can be extended with modifier key (Shift, Option, Control) constants in the modifier keys field of the extended menu ('xmnu' ) resource (see below). 0x1B Specifies that the menu item has a submenu. (The menu ID of the submenu should be assigned to the marking character field (see below).) 0x1C (Not used when the 'MENU' resource is extended with an 'xmnu' resource) Specifies that the item uses a script other than the system script. (The script code should be assigned to the icon number field (see above).) When the 'MENU' resource is extended by an 'xmnu' resource, the script code should be set in the text encoding field of the 'xmnu' resource. 0x1D For menu items containing icons, causes 'ICON' resources to be reduced to the size of a small icon, or 'cicn' resources to be reduced by half. 0x1E Specifies that you want the Menu Manager to use a small icon ('SICN') resource for the item's icon. (The small icon's resource ID should be assigned to the icon number field (see above).) 0 Specifies that the menu item has neither a keyboard equivalent nor a submenu and uses the system script. |
|
MARKING CHARACTER, MENU ID OF |
MARKING CHARACTER SUBMENU, OR 0 Special characters, such as the checkmark and diamond characters are available to indicate the marks associated with a menu item. MENU ID OF SUBMENU Submenus of an application must have menu IDs from 1 to 235. Submenus of a driver must have menu IDs from 236 to 255. 0 Specifies that the item has neither a mark nor a submenu. |
|
FONT STYLE OF THE MENU ITEM |
Specifies whether the font style of the menu item should be plain, or any combination of bold, italic, outline, and shadow. |
NOTE
As the user traverses menu items, if an item has a submenu, the MenuSelect function looks in the submenu portion of the menu list for the submenu. It then searches for a menu with a defined menu ID that matches the menu ID specified by the hierarchical menu item. If it finds a match, it attaches the submenu to the menu item.
Structure of a Compiled 'xmnu' Resource
The 'xmnu' resource provides for the additional features, for example, support for extended modifier keys, command IDs, and so on. Fig 7 shows the structure of a compiled 'xmnu' resource and an individual menu item entry in that resource.
){kind=link}
The following describes the fields of a compiled 'xmnu' resource:
|
Field |
Description |
|
VERSION NUMBER |
Version of the resource. |
|
NUMBER OF ENTRIES |
Number of entries (extended menu item structures) in the resource. |
|
FIRST EXTENDED MENU ENTRY |
A number of extended menu item structures (see fig 7) |
|
.... LAST EXTENDED MENU ENTRY |
|
Figure 3.7 Structure of a compiled extended menu ("xmnu") resource and an extended menu item entry.
Each entry in a 'xmnu' resource corresponds to a menu item. The following describes the main fields of an extended menu item entry.
|
Field |
Description |
|
TYPE |
Specifies whether there is extended information for the item. 1 indicates that there is extended information for the item, causing the rest of the entry to be read in. 0 indicates that there is no information for the item, causing the Menu Manager to skip the rest of the entry. |
|
COMMAND ID |
A unique value used to identify the menu item (as opposed to referring to the item using the menu ID and item number). This value may be ascertained via a call to GetMenuItemCommandID. A command ID may be assigned to a menu item programmatically via a call to SetMenuItemCommandID. |
|
MODIFIER KEYS |
Specifies the modifier keys used in a keyboard equivalent to select a menu item. The current modifier keys may be ascertained via a call to GetMenuItemModifiers. Modifier keys may be assigned to a menu item programmatically via a call to SetMenuItemModifiers. |
|
ICON TYPE PLACEHOLDER |
(Reserved. Set to 0.) |
|
ICON HANDLE PLACEHOLDER |
(Reserved. Set to 0.) |
|
TEXT ENCODING |
Specifies the text encoding for the menu item text. This field of the 'xmnu' resource should be used instead of setting the keyboard equivalent field in the 'MENU' resource to 0x1C and the icon number field to the script code. If you want to use the system script, assign -1. If you want to use the current script, assign -2. The current text encoding may be ascertained via a call to GetMenuItemTextEncoding. Text encoding may be assigned to a menu item programmatically via a call to SetMenuItemTextEncoding. |
|
REFERENCE CONSTANT |
Any value an application wants to store. The current value may be ascertained via a call to GetMenuItemRefCon. Reference constants may be assigned to a menu item programmatically via a call to SetMenuItemRefCon. |
|
REFERENCE CONSTANT |
Any additional value an application wants to store. The getter and setter functions relating to this second reference constant are not available in Carbon. If you wish to associate data with a menu item you should use the functions which are available for that purpose (see "Associating Data With Menu Items"). |
|
MENU ID OF SUBMENU |
A value between 1 and 235, identifying the submenu. The current submenu ID may be acertained via a call to GetMenuItemHierarchicalID. The menu ID of a submenu may be assigned to a menu item programmatically via a call to SetMenuItemHierarchicalID. This, in effect, attaches a submenu to the menu item. |
|
FONT ID |
The ID of the font family. If this value is 0, then the large system font ID (Mac OS 8/9) or system font (Mac OS X) is used. The current font ID may be acertained via a call to GetMenuItemFontID. The font ID of a menu item may be set programmatically via a call to SetMenuItemFontID. |
|
KEYBOARD GLYPH |
A symbol representing a menu item's modifier key. The current keyboard glyph may be ascertained via a call to GetMenuItemGlyph. If the value in this field is zero, the keyboard glyph uses the keyboard font. (A glyph is a visual representation of a character.) You can override the character code to be displayed with a substitute glyph by assigning a non-zero value to this field. The keyboard glyph of a menu item may be set programmatically via a call to SetMenuItemKeyGlyph. |
The information in an 'xmnu' resource is set for specified menu items; it is not necessary to create an extended menu entry for all menu items in a menu.
It is not necessary to provide 'xmnu' resources if your application's menus do not require the additional features provided by this resource.
Creating 'MBAR', 'MENU', and 'xmnu' Resources Using Resorcerer
As previously stated, when creating resources using Resorcerer, it is advisable that you refer to a diagram and description of the structure of the resource and relate that to the various items in the Resorcerer editing windows. The following assumes that approach.
Creating 'MBAR' Resources
Fig 8 shows an 'MBAR' resource containing seven menus being created with Resorcerer. The first three entries would be, respectively, the Apple, File, and Edit menus.
){kind=link}
Figure 3.8 Creating an 'MBAR' resource using resorcerer
Creating 'MENU' Resources
Fig 9 shows an imaginary View menu with the Full Screen menu item being edited. This menu item has been assigned a keyboard equivalent (more specifically, a Command-key equivalent); accordingly, the Key Equiv: radio button has been clicked and the character F has been entered as the Command-key equivalent. The menu item has also been assigned a marking character (a checkmark).
){kind=link}
Figure 3.9 Editing a 'MENU' resource using resorcerer
Fig 10 shows the same View menu with the Floating Palettes menu item being edited. This item has a submenu; accordingly, the Sub-menu ID radio button has been clicked and the resource ID of the submenu's 'MENU' resource has been entered. The item also has an icon provided by a 'CICN' or 'cicn' resource with a resource ID of 257.
){kind=link}
Figure 3.10 Further editing of a 'MENU' resource using resorcerer.
Creating 'MENU' Resources for Submenus
Fig 11 shows the Line and Fill submenu item in the submenu attached to the Floating Palettes menu item being edited. This item has a marking character (a checkmark), an icon provided by an 'ICON' or 'cicn' resource with resource ID 258, and a Command-key equivalent.
){kind=link}
Figure 3.11 Editing a 'MENU' resource for a submenu using resourcerer.
Creating 'xmnu' Resources
Fig 12 shows an 'xmnu' resource being created using Resorcerer. This 'xmnu' resource extends the 'MENU' resource with resource ID 133 (the View menu, above). Menu item 4 has been assigned a command ID, and the Command-key equivalent assigned to this item in the 'MENU' resource (Command-F) has been extended to the keyboard equivalent Command-Shift-F by specifying the Shift key as an extended modifier.
){kind=link}
Figure 3.12 Creating an 'xmnu' resource using resorcerer.
Creating the Menu Bar and Pull-Down Menus
The function GetNewMBar, which itself calls GetMenu, should be used to read in the 'MBAR' resource and its associated 'MENU' resources. After reading in a 'MENU' resource, GetMenu looks for an 'xmnu' resource with the same resource ID and reads it in if found. GetNewMBar creates a menu object for each menu and inserts each menu into the menu list.
SetMenuBar should then be used to set the current menu list as the menu list created by your application. A call to DrawMenuBar completes the process by drawing the menu bar, displaying all the menu titles in the current menu list.
Deleting the Quit Command
As previously stated, your application must include a Quit command in the File menu when your application is run on Mac OS 8/9 but not when it is run on Mac OS X. Accordingly, you must conditionalize your code so as to ensure that the Quit command and its preceding divider are deleted when your application is run on Mac OS X. The methodology recommended by Apple is as follows:
SInt32 response;
MenuRef menuRef;
Gestalt(gestaltMenuMgrAttr,&response);
if(response & gestaltMenuMgrAquaLayoutMask)
{
menuRef = GetMenuRef(mFile);
if(menuRef != NULL)
{
DeleteMenuItem(menuRef,iQuit);
DeleteMenuItem(menuRef,iQuit - 1);
}
}
Creating a Hierarchical Menu
GetNewMBar does not read in the resource descriptions of submenus but simply records the menu ID of any submenu in the menu object. Submenu descriptions are read in with GetMenu and the submenu is inserted in the current menu list using InsertMenu, with the constant hierMenu passed as the second parameter to that call.
NOTE
As the user traverses menu items, if an item has a submenu, the MenuSelect function looks in the submenu portion of the menu list for the submenu. It then searches for a menu with a defined menu ID that matches the menu ID specified by the hierarchical menu item. If it finds a match, it attaches the submenu to the menu item.
Carbon Note
In Carbon, calling GetMenu twice on the same resource ID will create two independent, unique menus. (In Classic, the second call to GetMenu returns the same MenuHandle as the first call.) Thus, to prevent memory leaks in Carbon, GetMenu should not be called a second time on the same resource ID without an intervening call to DisposeMenu.
Adding Menus to the Menu List
A menu may be added to the current menu list using one of the following procedures:
Read the relevant 'MENU' resource in with GetMenu, add it to the current menu list with InsertMenu, and update the menu bar with DrawMenuBar.
Use NewMenu to create a new empty menu, use AppendMenu, InsertMenuItem, InsertResMenu, or AppendResMenu to fill the menu with menu items, add the menu to the current menu list using InsertMenu, and update the menu bar using DrawMenuBar.
Note that GetMenuRef may be used to obtain a reference to the menu object of any menu in the current menu list.