MACINTOSH C CARBON: A Hobbyist's Guide To Programming the Macintosh in C
Version 1.0
� 2001 K. J. Bricknell

CHAPTER 3

MENUS

Introduction - Types of Menus

A menu is a user interface element that allows the user to view, or choose from, a list of choices and commands provided by your application. There are basically three types of menus:

• Pull-Down Menus. A pull-down menu comprises a menu title, displayed in the menu bar, and one or more menu items.

• Submenus. A submenu is a menu that is attached to another menu. A menu to which a submenu is attached is referred to as a hierarchical menu.

• Pop-Up Menus. A pop-up menu is a menu that does not appear in the menu bar but rather appears on another part of the screen.

Pull-Down Menus

Menu Definition Functions and Menu Bar Definition Functions

The Menu Manager uses the following to display, and to perform basic operations on, menus and the menu bar:

• Menu Definition Function. When you define a menu, you must specify the required menu definition function (MDEF). The Menu Manager uses that MDEF to draw the menu items in a menu, determine which item the user chose, etc. An MDEF thus determines the look and behaviour of menus.

• Menu Bar Definition Function. The Menu Manager uses the menu bar definition function (MBDF) to draw and clear the menu bar, determine whether the cursor is currently within the menu bar or any currently displayed menu, highlight menu titles, etc. A menu bar definition function thus determines the look and behaviour of the menu bar.

Standard Menu and Menu Bar Definition Functions

The system software provides a standard MDEF and a standard MBDF. The standard MDEF is the 'MDEF' resource with a resource ID of 63. The standard MBDF is the 'MBDF' resource with a resource ID of 63.

Ordinarily, your application will specify the standard definition functions; however, as with most other elements of the Macintosh user interface, the option is available to write your own custom definition function if you need to provide features not available in the standard definition functions.

The Menu Bar and Menus

The Menu Bar

The menu bar extends across the top of the screen and is high enough to display menu titles in the height of the large system font (Mac OS 8/9) or system font (Mac OS X).

Generally, the menu bar should always be visible. If you want to hide the menu bar for some reason, you should provide a method (for example, a keyboard equivalent) to allow the user to make the menu bar reappear.

The 'MBAR' Resource

Each application has its own menu bar, which is defined by an 'MBAR' resource. This resource lists the order and resource ID of each menu appearing in your menu bar. Your application's 'MBAR' resource should be defined such that the the Mac OS 8/9 Apple menu or Mac OS X Application menu (see below) is the first menu in the menu bar, with the File menu being the next. . For Mac OS 8/9, the Help menu and the Mac OS 8/9 Application menu (see below) do not need to be defined in the 'MBAR' resource, since the Menu Manager automatically adds them to the menu bar when the application calls GetNewMBar provided that your menu bar includes the Apple menu.

Menus

All Macintosh applications should ordinarily provide, as a minimum, the Mac OS 8/9 Apple menu (for Mac OS 8/9) or Mac OS X Application menu (for Mac OS X), a File menu, and a Window menu (see Chapter 16). If your application is not document-oriented, the File menu may be renamed to something more appropriate.

Your application can disable any menu, which causes the Menu Manager to dim that menu's title and all associated menu items. The menu items can also be disabled individually. Your application should specify whether menu items are enabled or disabled when it first defines and creates a menu and can enable or disable items at any time thereafter.

The 'MENU' Resource

For each menu, you define the menu title and the individual characteristics of its menu items in a 'MENU' resource.

The 'xmnu' Resource

For each menu, you may also define an 'xmnu' (extended menu) resource. The 'xmnu' resource is, in effect, an extension of the 'MENU' resource required to provide for additional menu features. . Note that you do not need to provide this resource if you do not require these additional features. An 'xmnu' resource must have the same ID as the 'MENU' resource it extends.

Menu Items

A menu item can contain text or a divider. On Mac OS 8/9 the divider is a line extending the full width of the menu. On Mac OS X it is simply an empty space, like a menu item with no text. Each menu item, other than a divider, can have a number of characteristics as follows:

• An icon, small icon, reduced icon, colour icon, or an icon from an icon family3 to the left of the menu item's text.

  The various icon types are described at Chapter 13.

• A checkmark or other marking character indicating the status of the menu item or the mode it controls.

• The symbols for the item's keyboard equivalent. (An item that has a keyboard equivalent cannot have a submenu, a small icon or a reduced icon.)

• A triangular indicator to the right of a menu item's text to indicate that the item has a submenu. (An item that has a submenu cannot have a keyboard equivalent, a marking character, a small icon or a reduced icon.)

• A font style (bold, italic, etc.) for the menu item's text.

• The text of the menu item.

• The ellipsis character (...) as the last character in the text of the menu item, indicating that, before executing the command, the application will display a dialog box requesting more information from the user. (The ellipsis character should not be used in menu items that display informational dialogs or a confirmational alert.)

• A dimmed appearance when the application disables the item. (When the menu title is dimmed, all menu items in that menu are also dimmed.)

Groups of Menu Items

Where appropriate, menu items should be grouped, with each group separated by a divider. For example, a menu can contain commands that perform actions and commands that set attributes. The action commands that are logically related should be grouped, as should attribute commands that are interdependent. The attribute commands that are mutually exclusive, and those that form accumulating attributes (for example, Bold, Italic and Underline), should also be grouped.

Keyboard Equivalents for Menu Commands

The Menu Manager provides support for keyboard equivalents. Your application can detect a keyboard equivalent by examining the modifiers field of the event structure, first determining whether the Command key was pressed at the time of the event. If a keyboard equivalent is detected, your application typically calls MenuEvent, which maps the keyboard equivalent character contained in the specified event structure to its corresponding menu and menu item and returns the menu ID and the chosen menu item.

A keyboard equivalent is any combination of the Command key, optionally one or more modifier keys (Shift, Option, Control), and another key. A Command-key equivalent such as Command-C is thus, by definition, also a keyboard equivalent.

Reserved Command-Key Equivalents

Apple reserves the following Command-key equivalents, which should be used in the File and Edit menus of your application:

Other common keyboard equivalents are:

The Mac OS 8/9 Apple Menu and Mac OS X Application Menu

On Mac OS 8/9, the Mac OS 8/9 Apple Menu is the first menu in your application. On Mac OS X, the Mac OS X Application Menu (see Fig 1) is the first menu.

Typically, applications provide an About command as the first menu item in the Apple (Mac OS 8/9) and Mac OS X Application menus. On Mac OS 8/9, the remaining items are controlled by the contents of the Apple Menu Items folder in the System folder. On Mac OS X, the remaining items are the default items automatically included in the system-created Application menu. Application menu items are general to the application, that is, they are items that are not specific to a document or other window.

To create your application's Mac OS 8/9 Apple menu fo Mac OS 8/9, you simply define the Apple menu title and the characteristics of your application's About command in a 'MENU' resource. When your application is run on Mac OS 8/9, the contents of the Apple Menu Items folder are automatically added to the Apple menu.

The Apple menu 'MENU' resource will also cause the About command to be inserted in the Application menu when the application is run on Mac OS X.

When the user chooses the About command on Mac OS 8/9, your application should display a dialog or an alert containing your application's name, version number, copyright information, any other information as required. On Mac OS X, your application should display a modeless dialog containing the application's version and copyright information, as prescribed in Aqua Human Interface Guidelines.

The File Menu

The standard File menu contains commands related to the document management plus, on Mac OS 8/9, the Quit command. (On Mac OS X, the Quit command is located in the Application menu (see Fig 1).) The standard commands (see Fig 2) should be supported by your application. Any other commands added to the menu should pertain to the management of documents. The actions your application should take when File menu commands are chosen are detailed at Chapter 15 and Chapter 18.

The Edit Menu

The standard Edit menu (see Fig 2) provides commands related to the editing of a document's contents, to copying data between different applications using the Clipboard, and, on Mac OS 8/9, to showing and hiding the Clipboard. For Mac OS 8/9 only, the standard Edit menu also standardises the location of the Preferences... item, which, when chosen, should invoke a dialog that enables the user to set application-specific preferences. (On Mac OS X, the Preferences... command is located in the Mac OS X Application menu.)

The implementation of Preferences commands is demonstrated at the demonstration program at Chapter 19.

All Macintosh applications which support text entry, including text entry in edit text items in dialog boxes, should include the standard editing commands (Undo, Cut, Copy, Paste and Clear). An additional word or phrase should be added to Undo to clarify exactly what action your application will reverse.

Other commands may be added if they are related to editing or changing the contents of your application's documents.

The Mac OS 8/9 System-Managed Menus

On Mac OS 8/9, two menus, namely the Mac OS 8/9 Application menu and the Help menu, are added automatically by the Menu Manager and are often referred to as the system-managed menus.

The Mac OS 8/9 Application Menu

When the user chooses an item from the Mac OS 8/9 Application menu, the Menu Manager handles the event as appropriate. For example, if the user chooses another application, your application is sent to the background and receives a suspend event.

The Help Menu

Applications written for Mac OS 8/9 using the Classic API have the option of programmatically appending an item (or items) to the end of the Help menu, and of programmatically detecting the user's choice of that item, so as to give the user access to help texts provided by the application. For Mac OS 8/9, this option is not available in the Carbon API.

Carbon applications may use Apple Help, which was introduced with Mac OS 8.6, to provide application help. Apple Help documentation and tools are included in an Apple Help Software Development Kit (SDK), which is available at http:/developer.apple.com/sdk. Amongst other things, the documentation describes how to create an Apple Guide file which, when located in the same folder as your application, will cause the system to install a help menu item (or items) in your application's Help menu. The menu at the left at Fig 3 show the Help menu as it normally appears. The menus at the right at Fig 3 show the Help menu as it appears when the Apple Guide file is present.

Mac OS Help Menus

For Mac OS X, your application must itself create the Help menu (using the function HMGetHelpMenu), insert the required item, or items, in that menu, and respond to the user choosing items in the menu.

Font Menus

If your application has a Font menu, you should list in that menu the names of all currently available fonts (that is, all those residing in the Fonts folder in the System folder). Fonts may be added to the Font menu using AppendResMenu or InsertResMenu. However, a better alternative is to use the relatively new Menu Manager function CreateStandardFontMenu to build either a hierarchical or non-hierarchical Font menu. (A hierarchical Font menu is one in which the styles available in each font family (regular, bold, italic, etc.) appear in a submenu attached to the menu item containing the font family name.)

To indicate which font is currently in use, your application should add a checkmark to the left of the font's name in the Font menu. If the current selection contains more than one font, a dash should be placed next to the name of each font the selection contains. When the user starts entering text at the insertion point, your application should display text in the current font.

To indicate which font is currently in use in a hierachical Font menu, your application should place a checkmark next to the font in the submenu and a dash next to the menu item to which the submenu is attached.

Font Attributes

Separate menus should be used to accommodate lists of font attributes such as styles and sizes.

WYSIWYG Font Menus

The function SetMenuItemFontID allows you to easily set up a Font menu with each item being drawn in the actual font.

Hierarchical Menus

A hierarchical menu is a menu which has a submenu attached to it. You should use a submenu only when you have more menus than fit in the menu bar. There should only ever be one hierarchical level, that is, there should be only one level of submenus. A menu item that is the title of a submenu should clearly represent the choices the submenu contains.

Hierarchical menus work best for providing a submenu of attributes.

Pop-Up Menus

Pop-up menus work well when your application needs to present several choices to the user and it is acceptable to hide these choices until the menu is opened. (Other methods of displaying choices are checkboxes and radio buttons.) Pop-up menus should not be used for multiple choice lists or as a way to provide more commands. They should contain attributes rather than actions; accordingly, Command-key equivalents should not be used in pop-up menus.

The standard pop-up menu is actually implemented as a control, specifically, the pop-up menu button control. Its appearance (see Fig 4) and behaviour is thus determined by a pop-up menu button control definition function.

Because pop-up menus are implemented as controls, they are addressed at Chapter 7. Further information in this chapter will be limited to the provision of the 'MENU' resource required by the pop-up menu button control.

Menu Objects, Menu IDs and Item Numbers, Command IDs, and Menu Lists

The Menu Object

The Menu Manager maintains information about individual menus in opaque data structures known as menu objects. The data type MenuHandle is defined as a pointer to a menu object:

     typedef struct OpaqueMenuHandle* MenuHandle;

Note that the data type MenuHandle is equivalent to the newer data type MenuRef:

     typedef MenuHandle MenuRef;

A major change introduced in Carbon is that some commonly used data structures are now opaque, meaning that their internal structure is hidden to applications. Directly referencing fields within these structures is no longer possible, and special new accessor functions must be used instead. As an example, the Classic API equivalent of the menu object is the MenuInfo structure, which is defined as follows: struct MenuInfo { MenuID menuID; short menuWidth; short menuHeight; Handle menuProc; long enableFlags; Str255 menuData; }; typedef struct MenuInfo MenuInfo; typedef MenuInfo *MenuPtr; typedef MenuPtr *MenuHandle; In the Classic API, your application can determine the menu width by directly accessing the menuWidth field like this: MenuHandle menuHdl; SInt16 width; menuHdl = GetMenuHandle(mFile); // Get handle to MenuInfo structure. width = (**menuHdl).menuWidth; In Carbon, you must use the accessor function GetMenuWidth to obtain the menu width from a menu object: MenuRef menuRef; SInt16 width; menuRef = GetMenuRef(mFile); // Get reference to menu object. width = GetMenuWidth(menuRef);

The following accessor functions are provided to access the information in menu objects:

You typically specify most of the information in a menu object in a 'MENU' resource. When you create a menu, the Menu Manager creates a menu object for the menu and returns a reference to that object. The Menu Manager automatically updates the menu object when you make any changes to the menu programmatically.

Menu IDs and Item Numbers

To refer to a menu, you usually use either the menu's ID or the reference to the menu's menu object. Accordingly, you must assign a menu ID to each menu in your application as follows:

• Pull-down menus must use a menu ID greater than 0.

• Submenus of an application may use a menu ID in the range 1 to 32767.

To refer to a menu item, you use the item's item number. Item numbers in a menu start at 1.

Command IDs

The command ID, a unique value that you set to identify a menu item, is an alternative way of referring to a specific menu item in an application's menus.

The Menu List

The menu list, a structure private to the Menu Manager, contains references to the menu objects of one or more menus (although a menu list can, in fact, be empty). The end of a menu list contains references to the menu objects of submenus and pop-up menus, if any, the phrase "submenu portion of the menu list" referring to this portion of the list.

At application launch, the Menu Manager creates the menu list. The menu list is initially empty but changes as your application adds menus to it or removes menus from it programmatically.

Creating Your Application's Menus

'MBAR', 'MENU', and 'xmnu' Resources

As stated at 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.

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.

The following describes the main fields of the 'MENU' resource:

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 The icon number is 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' (colour 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 (see below). 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, colour 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 (see below). A script system consists of keyboard resources (which provide for text input in any language from any keyboard) international resources (which contain information specific to a particular language, such as its date and time formats, sorting order, and word-break rules), and fonts (that is, sets of glyphs, which are visual representations of characters). A script code is a numeric value indicating a particular Mac OS script system. Constants (e.g., smRoman, smJapanese) are defined for each of the script codes recognized by the Mac OS. The constant for the script code for the system script system is smSystemScript. 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, 0X1D, OX1E, OR 0	KEYBOARD EQUIVALENT 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 SUBMENU, OR 0	MARKING CHARACTER Special characters, such as the checkmark and diamond charcaters, 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.

Structure of a Compiled 'xmnu' Resource

The 'xmnu' resource provides for the additional features, for example, support for extended modifier keys, command IDs, etc. Fig 7 shows the structure of a compiled 'xmnu' resource and an individual menu item entry in that resource.

The following describes the fields of a compiled 'xmnu' resource:

Each entry in a 'xmnu' resource corresponds to a menu item. The following describes the main fields of an extended menu item entry.

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.

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

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.

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.

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.

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

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.

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.

Providing Help Balloons (Mac OS 8/9)

'hmmu' Resources

For Mac OS 8/9, you should define Help balloons for each of your application's menu items and each menu title. Help balloons for menus are defined in 'hmmu' resources. The resource ID of an 'hmnu' resource should be the same as the resource ID of the 'MENU' resource to which it pertains.

Creating 'hmnu' Resources

Fig 13 shows an 'hmnu' (help menu) resource being created using Resorcerer.

Specifying the Format of Help Messages.

The example at Fig 13 specifies the format of the help messages as (Pascal) text strings stored within the 'hmnu' resource itself. Clicking on the pop-up button adjacent to Message record type opens a pop-up menu that facilitates the choice of other formats (and also provides an option that enables you to instruct the Help Manager to skip the item). The items in the pop-up menu and their meanings are as follows:

Text for Help Balloons

The text of your help balloons for menus should answer at least one of the following questions:

• What is this? For example, when the user moves the cursor over the title of the File menu in the title bar, the beginning of the balloon text should be "File menu".

• What does this do? For example, when the user moves the cursor over the Find item in a File menu, the balloon text should be "Finds and selects items with the characteristics you specify" or similar.

Changing Menu Item Appearance

Menu Manager functions may be used to change the appearance of items in a menu, for example, the font style, text or other characteristics.

Enabling and Disabling Menu Items

Specific menu items or entire menus may be disabled and enabled using DisableMenuItem and EnableMenuItem, which both take a reference to the menu object that identifies the desired menu and either the item number of the menu to be enabled/disabled or a value of 0 to indicate that the entire menu is to be enabled/disabled. Alternatively, if your application uses command IDs to identify menu items, you should use the functions EnableMenuCommand and DisableMenuCommand to enable and disable items.

When an entire menu is disabled or enabled, DrawMenuBar should be called to update the appearance of the menu bar. If you do not need to update the menu bar immediately, you can use InvalMenuBar instead of DrawMenuBar, causing the Event Manager to redraw the menu bar the next time it scans for update events. This will reduce the menu bar flicker which will occur if DrawMenuBar is called more than once in rapid succession.

If you disable an entire menu, the Menu Manager dims that menu's title at the next call to DrawMenuBar and dims all menu items when it displays the menu. If you enable an entire menu, the Menu Manager enables only the menu title and any items that you did not previously disable individually.

Enabling the Preferences... Item in the Application Menu

The Preferences... item in the Mac OS X Application menu is disabled by default. If your application needs to allow the user to invoke a Preferences dialog box by choosing this item, it must explicitly enable the item. The following shows how to enable the Preferences... item:

     EnableMenuCommand(NULL,kHICommandPreferences);

Other Appearance Changes

The following lists other functions related to changing the appearance of menu items.

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:

As an example of the use of metacharacters, assume that the following two strings are stored in a string list ('STR#') resource:

     Pick a Colour...
     (^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.

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 Colour..." 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(mColours);
     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.

Associating Data With Menu Items

The following functions may be used by your application to associate data with menu items:

Note that these functions require a command ID to be passed in their second parameter. Accordingly, they may only be used when your application uses command IDs to refer to the relevant menu items.

Handling Menu Choices

Determining the Menu ID and Menu Item - MenuSelect and MenuEvent

The first action your application should take when the user presses the mouse button while the cursor is in the menu bar is menu adjustment (that is, enabling or disabling menu items and adding or removing marks as required). Your application should then call MenuSelect. MenuSelect tracks the mouse, displays menus, highlights menu titles, displays and highlights enabled menu items, handles all user activity until the user releases the mouse button, and returns a long integer as its function result. The long integer contains the menu ID in the high word and the item number in the low word.

If some of your menu items have keyboard equivalents, your application should detect such key-down events. If an examination of the modifiers field of the event structure reveals that the Command key was down, your application should first adjust its menus and then call MenuEvent. MenuEvent scans the current menu list for a menu item that has a matching keyboard equivalent. Like MenuSelect, MenuEvent returns a long integer containing the menu ID and the item number.

If the user did not actually choose a menu command with the mouse, or if the user pressed a keyboard combination that did not map to a keyboard equivalent, MenuSelect and MenuEvent return 0 in the high word, the value in the low word being undefined.

Further Handling - Command IDs Not Used

The long integer returned by MenuSelect and MenuEvent should be passed as a parameter to a function that switches according to the menu ID in the high word and passes the low word to other functions that respond appropriately to that menu command.

Further Handling - Command IDs Used

Mac OS 8 introduced an alternative method of identifying, for the purposes of further handling, the menu item chosen by the user. This method assumes that you have previously assigned a unique value to your individual menu items via the command ID field of the 'xmnu' resource (or, programmatically, via calls to SetMenuItemCommandID).

Using this method, the menu ID and item number should be extracted from the long integer returned by MenuSelect and MenuEvent in the usual way. The menu ID should then be used in a call to GetMenuRef to get the reference to the menu's menu object. This reference and the menu item should then be used in a call to GetMenuItemCommandID, which returns the unique value that you previously assigned to the item (that is, the item's command ID). Your application should then switch according to that command ID, calling the other functions that respond appropriately to that menu command.

Unhighlighting the Menu Title

Recall that one of the actions of MenuSelect and MenuEvent is to highlight the menu title. Ordinarily, your application should not unhighlight the menu title (using HiliteMenu) until it performs the action associated with the menu command chosen by the user. However, if, in response to a menu command, your application displays a modal dialog box containing an edit text item, you should unhighlight the menu title immediately so that the user can access the Edit menu.

Adjusting Menus

Menu adjustment should be on the basis of the type of window that is currently the frontmost window, for example, a text window, a modeless dialog box, etc. Accordingly, the menu adjustment function should first determine which window is the front window. The following are examples of menu adjustment functions:

     void  doAdjustMenus(void)
     {
       WindowRef  windowRef;
       SInt16     windowType;

       windowRef = FrontWindow();
       windowType = doGetWindowType(windowRef);

       switch windowType 
       {
         case kMyDocWindow:
           doAdjustFileMenuForDocWindow();
           doAdjustEditMenuForDocWindow();
           // Adjust others.
           break;

         case kMyModelessDialogWindow:
           doAdjustMenusForModelessDialogs();
           break;

         case kNil:
          doAdjustMenusNoWindows();
           break;
       };

       DrawMenuBar;
     }

     void doAdjustFileMenuForDocWindow(void)
     {
       MenuRef  menuHdl;

       menuHdl = GetMenuRef(mFile);

       EnableMenuItem (menuHdl,iNew);
       EnableMenuItem (menuHdl,iOpen);
       DisableMenuItem(menuHdl,iClose);
       DisableMenuItem(menuHdl,iSave);
       DisableMenuItem(menuHdl,iSaveAs);
       DisableMenuItem(menuHdl,iPageSetup);
       DisableMenuItem(menuHdl,iPrint);
       EnableMenuItem (menuHdl,iQuit);
     }

Handling Mac OS 8/9 Apple Menu Choices

When the user chooses an item in the Mac OS 8/9 Apple menu, MenuSelect returns the menu ID of your application's Apple menu in the high word and the item number in the low word.

If your application provides an About command as the first menu item in the Apple menu, and the user chooses this item, you should display the About dialog/alert. Other choices from the Mac OS 8/9 Apple menu are handled automatically by the system.

Handling Mac OS X Application Menu Choices

About Command

When the user chooses the About command in the Mac OS X Application menu, MenuSelect returns the menu ID of your application's Application menu in the high word and 1 in the low word. Thus the code that handles the user's choice of the Apple menu's About item on Mac OS 8/9 will also handle the user's choice of the Application menu's About item on Mac OS X.

Quit Command

When the user chooses the Quit command from the Mac OS X Application menu, a high-level event (more specifically, an Apple event) known as a Quit Application event is sent to your application. Your application must support the Quit Application event in order to respond to the user choosing the Quit command. (See Chapter 10.)

Preferences... Command

An Apple Event, known as the Show Preferences event, is sent to your application when the user chooses the Preferences... command from the Mac OS X Application menu. Your application must support the Show Preferences event in order to respond to the user choosing the Preferences... command. (See the demonstration program at Chapter 19.)

Handling a Size Menu

Preamble

On Mac OS 8/9, font sizes in Size menus should be outlined to indicate which sizes are directly provided by the current font. For bitmapped fonts, you should outline only those sizes that exist in the Fonts folder. For TrueType fonts, all sizes supported by that font should be outlined. The current font size should be indicated with a checkmark. If the current selection contains more than one font size, a dash should be placed next to each font size in the selection.

Size menus should, in addition to displaying available font sizes, provide an Other command to enable the user to specify a size not currently listed in the menu. When the user chooses the Other command, the current font size should be displayed in a dialog box that allows the user to enter the desired font size. If the user chooses a size not already in the menu, a checkmark should be added to the Other menu item and the chosen size should be added in parenthesis to the text of the Other command.

Handling the Menu Choice

The following is an example function that handles a user's choice of an item in a Size menu:

  void  doHandleSizeCommand(SInt16 menuItem)
  {
    SInt16   numItems;
    Boolean  addItem;
    SInt32   sizeChosen;

    numItems = CountMenuItems(GetMenuRef(mSize));
    if(menuItem == numItems)          // If user chose Other, display dialog box. If the
    {                                 // user-specified size is not in the menu, add a
      doDisplayOtherBox(sizeChosen);  // checkmark to the Other command and add the new
    }                                 // font size to the text of the Other command.
    else                              // Return sizeChosen.
    {                                 // User chose a size.  Remove marks
      doRemoveMarksFromSizeMenu();    // from item/s showing previous size.
      CheckMenuItem(GetMenuRef(mSize),menuItem,true);  // Add mark to chosen item.
      sizeChosen = doItemToSize(menuItem);             // Convert item number to font size.
    }
    doResizeSelection(sizeChosen);  // Update document state or user selection.
  }

Hiding and Showing the Menu Bar

HideMenuBar and ShowMenuBar may be used to make the menu bar invisible and unselectable and visible and selectable. On Mac OS X, these functions also hide and show the Dock.

Accessing Menus From Alert and Dialog Boxes

When alert boxes and dialog boxes are displayed, the Dialog Manager and the Menu Manager interact to provide varying degrees of access to menus in your menu bar. In some circumstances, you can rely on the system software to disable the appropriate menus and menu items. In other circumstances, you application must contribute to, or control, the matter of menu access.

The subject of menu access when alert boxes, movable alert boxes, modal dialog boxes, moveable modal dialog boxes, and modeless dialog boxes are displayed is somewhat involved, and is addressed in detail at Chapter 8.

Main Menu Manager Constants, Data Types, and Functions

Constants

For markChar Parameter of SetItemMark Calls

noMark       = 0
commandMark  = 17
checkMark    = 18
diamondMark  = 19
appleMark    = 20

For beforeID Parameter of InsertMenu to Insert a Submenu Into the Submenu Portion of the Menu List

hierMenu  = -1

For options Parameter of CreateStandardFontMenu Calls

KHierarchicalFontMenuOption = 0x00000001

Modifier Key Masks for GetMenuItemModifiers and SetMenuItemModifiers Calls

kMenuCommandModifiers  = 0  // If no bit is set, only the Command key is used.
kMenuShiftModifier     = (1 << 0)  // If this bit (0) is set, the Shift key is used.
kMenuOptionModifier    = (1 << 1)  // If this bit (1) is set, the Option key is used.
kMenuControlModifier   = (1 << 2)  // If this bit (2) is set, the Control key is used.
kMenuNoCommandModifier = (1 << 3)  // If this bit (3) is set, the Command key is not used.

Menu Icon Handle Constants for GetMenuItemIconHandle and SetMenuItemIconHandle Calls

kMenuNoIcon          = 0  // No icon.
kMenuIconType        = 1  // 'ICON' handle.
kMenuShrinkIconType  = 2  // 32-by-32 'ICON' handle shrunk (at display time) to 16-by-16.
kMenuSmallIconType   = 3  // 'SICN' handle.
kMenuColorIconType   = 4  // 'cicn' handle.
kMenuIconSuiteType   = 5  // Icon suite handle.

Menu Attributes

kMenuAttrExcludesMarkColumn = (1 << 0)
kMenuAttrAutoDisable        = (1 << 2)

Data Types

typedef struct OpaqueMenuHandle* MenuHandle;
typedef MenuHandle  MenuRef;
typedef SInt16      MenuID;
typedef UInt16      MenuItemIndex;
typedef UInt32      MenuCommand;
typedef Handle      MenuBarHandle;
typedef UInt32      MenuAttributes;

Functions

Creating and Disposing Of Menus

MenuHandle  NewMenu(short menuID, ConstStr255Param menuTitle);
MenuHandle  GetMenu(short resourceID);
void        DisposeMenu(MenuRef theMenu);

Creating a Help Menu (Mac OS X)

OSStatus    HMGetHelpMenu(MenuRef *outHelpMenu,MenuItemIndex *outFirstCustomItemIndex);

Adding Menus to and Removing Menus From the Current Menu List

void  InsertMenu(MenuHandle theMenu,short beforeID);
void  DeleteMenu(short menuID);
void  ClearMenuBar(void);

Getting a MenuBar Description From an 'MBAR' resource

Handle  GetNewMBar(short menuBarID);

Getting, Setting and Disposing of the Menu Bar

Handle   GetMenuBar(void);
void     SetMenuBar(Handle menuList);
OSStatus DisposeMenuBar (MenuBarHandle mbar);
short    GetMBarHeight(void);

Drawing the Menu Bar

void  DrawMenuBar(void);
void  InvalMenuBar(void);

Controlling Menu Bar Visibility

void    HideMenuBar(void);
void    ShowMenuBar(void);
Boolean IsMenuBarVisible(void);

Modifying the Menu Width

Boolean   GetMenuExcludesMarkColumn(MenuHandle menu);
OSStatus  SetMenuExcludesMarkColumn(MenuHandle menu,Boolean excludesMark);

Responding to User Choice of a Menu Command

Uint32 MenuEvent (EventRecord *inEvent);
long   MenuSelect(Point startPt);
long   MenuChoice(void);
void   HiliteMenu(short menuID);
long   PopUpMenuSelect(MenuHandle menu,short top,short left,short popUpItem);

Getting a Reference to a Menu Object

MenuHandle GetMenuRef(short menuID);

Adding and Deleting Menu Items

void     AppendMenu(MenuHandle menu,ConstStr255Param data);
void     InsertMenuItem(MenuHandle theMenu,ConstStr255Param itemString,short afterItem);
OSStatus AppendMenuItemText(MenuHandle menu,ConstStr255Param inString);
OSStatus AppendMenuItemTextWithCFStringMenuRef inMenu,CFStringRef inString,
         MenuItemAttributes inAttributes,MenuCommand inCommandID,MenuItemIndex *outNewItem);
OSStatus InsertMenuItemText(MenuHandle menu,ConstStr255Param inString,UInt16 afterItem);
OSStatus InsertMenuItemTextWithCFString(MenuRef menu,CFStringRef inString,
         MenuItemIndex inAfterItem,MenuItemAttributes inAttributes,MenuCommand inCommandID);
void     DeleteMenuItem(MenuHandle theMenu,short item);
void     AppendResMenu(MenuHandle theMenu,ResType theType);
void     InsertResMenu(MenuHandle theMenu,ResType theType,short afterItem);

Enabling and Disabling Menus, Menu Items, and Menu Item Icons

void     EnableMenuItem(MenuHandle theMenu,MenuItemIndex item);
void     DisableMenuItem(MenuHandle theMenu,MenuItemIndex item);
Boolean  IsMenuItemEnabled(MenuHandle menu,MenuItemIndex item);
void     DisableAllMenuItems(MenuRef theMenu);
void     EnableAllMenuItems(MenuRef theMenu);
Boolean  MenuHasEnabledItems(MenuRef theMenu);
void     EnableMenuCommand(MenuRef theMenu,MenuCommand commandID);
void     DisableMenuCommand(MenuRef theMenu,MenuCommand commandID);
Boolean  IsMenuCommandEnabled(MenuRef menu,MenuCommand commandID);
void     EnableMenuItemIcon(MenuHandle theMenu,MenuItemIndex item);
void     DisableMenuItemIcon(MenuHandle theMenu,MenuItemIndex item);
Boolean  IsMenuItemIconEnabled(MenuHandle menu,MenuItemIndex item);

Getting and Setting Menu Item Command IDs

OSErr    GetMenuItemCommandID(MenuRef inMenu,SInt16 inItem,UInt32* outCommandID);
OSErr    SetMenuItemCommandID(MenuRef inMenu,SInt16 inItem,UInt32 inCommandID);

Menu Object Accessor Functions

MenuID    GetMenuID(MenuRef menu);
void      SetMenuID(MenuRef menu,MenuID menuID);
SInt16    GetMenuWidth(MenuRef menu);
void      SetMenuWidth(MenuRef menu,SInt16 width);
SInt16    GetMenuHeight(MenuRef menu);
void      SetMenuHeight(MenuRef menu,SInt16 height);
StringPtr GetMenuTitle(MenuRef menu,Str255 title);
OSStatus  SetMenuTitle(MenuRef menu,ConstStr255Param title);
OSStatus  SetMenuTitleWithCFString(MenuRef menu,CFStringRef inString);
OSStatus  GetMenuDefinition(MenuRef menu,MenuDefSpecPtr outDefSpec);
OSStatus  SetMenuDefinition (MenuRef menu,const MenuDefSpec *defSpec);

Manipulating and Accessing Menu Item Characteristics

void     GetMenuItemText(MenuHandle menu,short item,Str255 itemString); 
void     SetMenuItemText(MenuHandle theMenu, short item, ConstStr255Param itemString);
OSStatus SetMenuItemTextWithCFString(MenuRef menu,MenuItemIndex item,
         CFStringRef inString);
void     GetItemStyle(MenuHandle theMenu,short item,Style *chStyle); 
void     SetItemStyle(MenuHandle theMenu,short item,short chStyle);
void     GetItemMark(MenuHandle theMenu,short item,short *markChar);
void     SetItemMark(MenuHandle theMenu,short item,short markChar);
void     CheckMenuItem(MenuHandle theMenu,short item,Boolean checked);
OSStatus GetMenuFont(MenuHandle menu,SInt16 *outFontID,UInt16 *outFontSize);
OSStatus SetMenuFont(MenuHandle menu,SInt16 inFontID,UInt16 inFontSize);
void     GetItemIcon(MenuHandle theMenu,short item,short *iconIndex);
void     SetItemIcon(MenuHandle theMenu,short item,short iconIndex);
void     GetItemCmd(MenuHandle theMenu,short item,short *cmdChar);
void     SetItemCmd(MenuHandle theMenu,short item,short cmdChar);
OSErr    GetMenuItemFontID(MenuHandle inMenu,SInt16 inItem,SInt16* outFontID);
OSErr    SetMenuItemFontID(MenuHandle inMenu,SInt16 inItem,SInt16 inFontID);
OSErr    GetMenuItemHierarchicalID(MenuHandle inMenu,SInt16 inItem,SInt16 *outHierID);
OSErr    SetMenuItemHierarchicalID(MenuHandle inMenu,SInt16 inItem,SInt16 inHierID);
OSErr    GetMenuItemIconHandle(MenuHandle inMenu,SInt16 inItem,MenuIconType outIconType,
         Handle* outIconHandle);
OSErr    SetMenuItemIconHandle(MenuHandle inMenu,SInt16 inItem,MenuIconType inIconType,
         Handle inIconHandle);
OSErr    GetMenuItemKeyGlyph(MenuHandle inMenu,SInt16 inItem,SInt16 *outGlyph);
OSErr    SetMenuItemKeyGlyph(MenuHandle inMenu,SInt16 inItem,SInt16 inGlyph);
OSErr    GetMenuItemModifiers(MenuHandle inMenu,SInt16 inItem,SInt16* outModifiers);
OSErr    SetMenuItemModifiers(MenuHandle inMenu,SInt16 inItem,SInt16 inModifiers);
OSErr    GetMenuItemRefCon(MenuHandle inMenu,SInt16 inItem,SInt32* outRefCon);
OSErr    SetMenuItemRefCon(MenuHandle inMenu,SInt16 inItem,SInt32 inRefCon);
OSErr    GetMenuItemTextEncoding(MenuHandle inMenu,SInt16 inItem,TextEncoding* outScriptID);
OSErr    SetMenuItemTextEncoding(MenuHandle inMenu,SInt16 inItem,TextEncoding inScriptID);

Getting a Menu Reference and Menu ID from a Command ID

OSStatus   GetIndMenuItemWithCommandID(MenuRef menu,MenuCommand commandID,UInt32 itemIndex,
           MenuRef *outMenu,MenuItemIndex *outIndex);

Associating Data With Menu Items

OSStatus  SetMenuCommandProperty(MenuRef menu,MenuCommand commandID,OSType propertyCreator,
          OSType propertyTag,ByteCount propertySize,const void *propertyData);
OSStatus  GetMenuCommandPropertySize(MenuRef menu,MenuCommand commandID,
          OSType propertyCreator,OSType propertyTag,ByteCount *size);
OSStatus  GetMenuCommandProperty(MenuRef menu,MenuCommand commandID,OSType propertyCreator,
          OSType propertyTag,ByteCount bufferSize,ByteCount *actualSize,
          void *propertyBuffer);
OSStatus  RemoveMenuCommandProperty(MenuRef menu,MenuCommand commandID,
          OSType propertyCreator,OSType propertyTag);

Counting Items in a Menu

short  CountMenuItems(MenuHandle theMenu);
ItemCount  CountMenuItemsWithCommandID(MenuRef menu,MenuCommand commandID);

Building and Updating Font Menus and Obtaining Font Family and Style

OSStatus CreateStandardFontMenu(MenuRef menu,MenuItemIndex afterItem,
         MenuID firstHierMenuID,OptionBits options,ItemCount *outHierMenuCount);
OSStatus UpdateStandardFontMenu(MenuRef menu,ItemCount *outHierMenuCount);
OSStatus GetFontFamilyFromMenuSelection(MenuRef menu,MenuItemIndex item,
         FMFontFamily *outFontFamily,FMFontStyle *outStyle);

Recalculating Menu Dimensions

void   CalcMenuSize(MenuHandle theMenu);

Highlighting the Menu Bar

void   FlashMenuBar(short menuID);