Version 2.3 © 2000 K. J. Bricknell
MENUSA link to the associated demonstration program listings is at the bottom of this page
IntroductionTypes of MenusA menu is a user interface element which 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 MenusMenu Definition Functions and Menu Bar Definition FunctionsThe Menu Manager uses the following to display, and to perform basic operations on, menus and the menu bar:
Standard Theme-Compliant Menu and Menu Bar Definition FunctionsThe system software provides a standard theme-compliant MDEF and a standard theme-compliant menu bar definition function, which are stored as code resources in the System file. The standard MDEF is the 'MDEF' resource with a resource ID of 63. The standard menu bar definition function is the 'MBDF' resource with a resource ID of 63.
When you define your menus and menu bar, you specify the definition functions that the Menu Manager should use when managing them. Ordinarily, you will use the standard 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. Given the new features added by the latest standard definition functions, however, it is all but impossible to conceive of circumstances that would require the writing of a custom definition function.
The Menu Bar and MenusThe Menu BarThe menu bar extends across the top of the screen. As defined by the standard menu bar definition function, the menu bar is white and high enough to display menu titles in the height of the system font (Chicago 12 point or Charcoal 12 point for Roman Scripts) plus a single pixel bottom border.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 for a menu command) 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 menu's 'MBAR' resource should be defined such that the Apple menu is the first menu in the menu bar, with the File and Edit menus being the next two. The Help and Application menus 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. MenusAll Macintosh applications should provide, as a minimum, the standard menus. The standard menus are the Apple menu, the File menu and the Edit menu.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 was introduced with Mac OS 8 and the Appearance Manager and is, in effect, the 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 ItemsA menu item can contain text or a dividing line (that is, a divider). A divider is always dimmed. Each menu item, other than dividers, can have a number of characteristics as follows:
Groups of Menu ItemsWhere appropriate, menu items should be grouped, with each group separated by a divider. For example, a menu can contain commands which perform actions and commands which set attributes. The action commands which are logically related should be grouped, as should attribute commands which are interdependent. The attribute commands which are mutually exclusive, and those which form accumulating attributes (for example, Bold, Italic and Underline), should also be grouped.Keyboard Equivalents for Menu CommandsThe Menu Manager provides support for keyboard equivalents. You 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 so, 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.
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:
Menus Added Automatically By the Menu ManagerThe menus added automatically by the Menu Manager (the Help and Application menus) are sometimes referred to as the system-managed menus. The Application menu has an icon as a title. The Help menu is displayed only if space is available; however, the application menu is invariably displayed, overlapping the main part of a long menu if this becomes necessary.
Your application does not need to take any action if the user chooses an item from the Application menu. However, if the user chooses an item added by your application to the Help menu, your application is responsible for taking the appropriate action. The Apple MenuThe Apple menu should be defined as the first in your application. Typically, applications provide an About command as the first menu item, followed by a divider. The remaining items are, of course, controlled by the contents of the Apple Menu Items folder in the System folder.To create your application's Apple menu, firstly define the Apple menu title, the characteristics of your application's About command and the divider following it in a 'MENU' resource. Then insert the contents of the Apple Menu Items folder into your application's Apple menu by calling AppendResMenu, with 'DRVR' specified as the resource type in the parameter theType. When the user chooses the About command, your application should display a dialog box or an alert box containing your application's name, version number, copyright information, any other information as required, and an OK button. When the user chooses an item other than the About command, your application should call the OpenDeskAcc function, which schedules the chosen item for execution and then returns to your application. At the next call to WaitNextEvent, your application receives a suspend event and the chosen item becomes the foreground process. The File MenuThe standard File menu (see Fig 1) contains commands related to the management of documents, plus the Quit command. The standard commands should be supported by your application. Any other commands added to the standard section of 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 - Printing and Chapter 16 - Files.The Edit MenuThe standard Edit menu (see Fig 2) provides commands which allow the user to edit the contents of their documents and to copy data between different applications using the Clipboard.
All Macintosh applications should include the standard editing commands (Undo, Cut, Copy, Paste and Clear) so as to support those operations in dialog boxes. 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 Help MenuYou can add items to the end of the Help menu to give the user access to any online help that your application provides in addition to help balloons. Items are added to the Help menu using HMGetHelpMenuHandle and AppendMenu. When adding items, include the name of your application in the command so as to indicate to the user just which application the help relates to.You should, however, not add an item to the Help menu in this way if you are providing online help using Apple Help (see below). Help BalloonsIn the Help menu, the effect of selecting Show Balloons and Hide Balloons is global and affects all applications. The Help Manager provides balloons for the Apple, Help and Application menu titles, for items in the Application menu, and for the standard items in the Help menu. Your application should provide the content of help balloons for all other menu items and menus in your application.Apple Help and the Help MenuApplications may use Apple Help, which was introduced with Mac OS 8.6, to provide online 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 the Help menu. The menu at the left at Fig 2 is the Help menu as it normally appears. The menu at the right at Fig 2 shows the Help menu as it appears when the Apple Guide file is present.
The Application MenuWhen the user chooses an item from the Application menu, the Menu Manager handles the event as appropriate. For example, if the user chooses another application, the Menu Manager sends your application a suspend event.Font MenusIf 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 are added to the Font menu using AppendResMenu or InsertResMenu, which add items to the specified menu in alphabetical order.Your application should indicate which font is in use by adding a checkmark to the left of the 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. Font AttributesSeparate menus should be used to accommodate lists of font attributes such as styles and sizes. Since the system software supports both bitmapped and TrueType fonts, your application should not provide an upper limit for font sizes.WYSIWYG Font MenusMac OS 8 and the Appearance Manager introduced the new function SetMenuItemFontID, which enables you to easily set up a Font menu with each item being drawn in the actual font.Hierarchical MenusA hierarchical menu is a menu which has a submenu attached to it. Hierarchical menus should be used to provide the user with additional choices in the nature of attributes. They should not be used to provide additional commands. There should only ever be one hierarchical level, that is, there should be only one level of submenus.Pop-Up MenusPop-up menus are used to present the user with a list of choices in a dialog box or window. 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 3) 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 - Introduction to Controls. Further information in this chapter will be limited to the provision of the 'MENU' resource required by the pop-up menu button control. Menu Structures, Menu IDs and Item Numbers, Command IDs, and Menu ListsThe Menu StructureThe Menu Manager maintains information about menus in menu structures, a data structure of type MenuInfo:
struct MenuInfo { short menuID; // Menu ID of the menu. short menuWidth; // Horizontal dimensions of the menu in pixels. short menuHeight; // Vertical dimensions of the menu in pixels. Handle menuProc; // Handle to the menu definition procedure. long enableFlags; // Enabled/disabled flags. Str255 menuData; // Menu title }; typedef struct MenuInfo MenuInfo; typedef MenuInfo *MenuPtr; typedef MenuPtr *MenuHandle;You typically specify most of this information in a 'MENU' resource. When you create a menu, the Menu Manager creates a menu structure for the menu and returns a handle to that structure. The Menu Manager automatically updates the menu structure when you make any changes to the menu programmatically. Menu IDs and Item NumbersTo refer to a menu, you usually use either the menu's ID or the handle to the menu's menu structure. Accordingly, you must assign a menu ID to each menu in your application as follows:
Command IDsMac OS 8 and the Appearance Manager introduced the command ID, which is an alternative way of referring to a specific menu item in an application's menus.The Menu ListThe menu list, a structure private to the Menu Manager, contains handles to the menu structures of one or more menus (although a menu list can, in fact, be empty). The end of a menu list contains handles to the menu structures of submenus and pop-up menus, if any, the phrase "submenu portion of the menu list" referring to this portion of the list.When your application initialises the Menu Manager, 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' ResourcesAs stated at Chapter 1 - System Software, Memory, And Resources, 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. Macintosh C 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' ResourceFig 4 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' ResourceFig 5 shows the structure of a compiled 'MENU' resource (and its variable length data) and how it "feeds" the menu structure.
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.
Structure of a Compiled 'xmnu' ResourceThe 'xmnu' resource provides for the additional features introduced with Mac OS 8 and the Appearance Manager, for example, support for extended modifier keys, command IDs, etc. Fig 6 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 introduced with Mac OS 8 and the Appearance Manager. Creating 'MBAR', 'MENU', and 'xmnu' Resources Using ResorcererAs 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' ResourcesFig 7 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' ResourcesFig 8 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 9 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 SubmenusFig 10 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' ResourcesFig 11 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 MenusThe 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 an 'xmnu' resource with the same resource ID and reads it in if found. GetNewMBar creates a menu structure 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. Creating an Hierarchical MenuGetNewMBar does not read in the resource descriptions of submenus but simply records the menu ID of any submenu in the menu structure. 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.
Adding Menus to the Menu ListA menu may be added to the current menu list using one of the following procedures:
Providing Help Balloons'hmmu' ResourcesYou 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. In the case of the 'hmnu' resource for your Help menu item, the resource ID should be -16490.Creating 'hmnu' ResourcesFig 12 shows an 'hmnu' (help menu) resource being created using Resorcerer.
Specifying the Format of Help Messages. The example at Fig 12 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 which facilitates the choice of other formats (and also provides an option which 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:
Changing the Appearance of Items in a MenuMenu Manager functions may be used to change the appearance of items in a menu, for example, the font style, text or other characteristics. Most of the functions which get or set menu characteristics require three parameters:
Enabling and Disabling Menu ItemsSpecific menu items or entire menus are disabled and enabled using:
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. Other Appearance ChangesThe following lists other functions related to changing the appearance of menu items. Those appearing on a light blue background were introduced with Mac OS 8 and the Appearance Manager. . Those appearing on a dark blue background were introduced with Mac OS 8.5.
Adding Items to a MenuAdding Items Other Than the Names of ResourcesAppendMenu, InsertMenuItem, AppendMenuItemText, and InsertMenuItemText (the latter two were introduced with Mac OS 8.5) are used to add items other than the names of resources (such as font resources) to a previously created menu. They require:
Strings With MetacharactersAppendMenu 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 line. 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/EThe 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.
ExamplesThe following code uses AppendMenu to append a menu item with no specific characteristics other than its text to the menu identified by the menu handle. The text for the menu item is "Pick a Colour..." as stored in the preceding 'STR#' resource.
MenuHandle myMenu; Str255 itemString; ... myMenu = GetMenuHandle(mLibrary); GetIndString(itemString,300,1); AppendMenu(myMenu,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:
MenuHandle myMenu; Str255 ItemString; ... myMenu = GetMenuHandle(mColours); GetIndString(itemString,300,2); InsertMenuItem(myMenu,itemString,iRed);The following code appends multiple items to the Edit menu using AppendMenu:
MenuHandle myMenu; ... myMenu = GetMenuHandle(mEdit); AppendMenu(myMenu,"\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(myMenu,"\pPaste/V;Copy/C;Cut/X-;-;Undo/Z",0);The following code adds a divider to the Edit menu:
AppendMenu(myMenu,"\p(-"); Strings Without MetacharactersThe two functions introduced with Mac OS 8.5 (AppendMenuItemText, and InsertMenuItemText) append and insert the specified string without evaluating the string for metacharacters. These two 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 MenuAppendResMenu 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 font resources in the Fonts folder as menu items in your application's Font menu. Similarly, AppendResMenu can be used to add all of the items from the Apple Menu Items folder to your application's Apple menu (with 'DRVR' specified as the resource type in the call). These are common instances of when you will need to add items not already defined in a 'MENU' resource. Adding Items to the Help MenuItems are added to your application's Help menu using AppendMenu or InsertMenuItem.Handling Menu ChoicesDetermining the Menu ID and Menu Item - MenuSelect and MenuEventWhen the user presses the mouse button while the cursor is in the menu bar, your application should first adjust its menus (that is, enable or disable menu items and add or remove marks as required) and 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 which 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 UsedThe long integer returned by MenuSelect and MenuEvent should be passed as a parameter to an application-defined function which switches according to the menu ID in the high word and passes the low word to other application-defined functions which respond appropriately to that menu command.Further Handling - Command IDs UsedMac OS 8 and the Appearance Manager 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 GetMenuHandle to get the handle to the menu's menu structure. This handle 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 application-defined functions which respond appropriately to that menu command. Unhighlighting the Menu TitleRecall 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 editable text item, you should unhighlight the menu title immediately so that the user can access the Edit menu.Adjusting MenusMenu 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 application-defined menu adjustment function should first determine which window is the front window. The following are examples of menu adjustment functions:
void doAdjustMenus(void) { WindowPtr windowPtr; SInt16 windowType; windowPtr = FrontWindow(); windowType = doGetWindowType(windowPtr); switch windowType { case kMyDocWindow: doAdjustFileMenuForDocWindow(); doAdjustEditMenuForDocWindow(); // Adjust others. break; case kMyModelessDialogWindow: doAdjustMenusForModelessDialogs(); break; case kNil: doAdjustMenusNoWindows(); break; }; DrawMenuBar; } void doAdjustFileMenuForDocWindow(void) { MenuHandle menuHdl; menuHdl = GetMenuHandle(mFile); EnableItem (menuHdl,iNew); EnableItem (menuHdl,iOpen); DisableItem(menuHdl,iClose); DisableItem(menuHdl,iSave); DisableItem(menuHdl,iSaveAs); DisableItem(menuHdl,iPageSetup); DisableItem(menuHdl,iPrint); EnableItem (menuHdl,iQuit); } Handling Apple Menu ChoicesWhen the user chooses an item in the 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 box. Otherwise, your application should use the GetMenuItemText function to get the menu item text and then call the OpenDeskAcc function, passing the text of the chosen menu item as a parameter. The OpenDeskAcc function prepares to open the desktop object chosen by the user. For example, if the user chose a document created by the SimpleText application, OpenDeskAcc schedules SimpleText for execution (or prepares to open it if it was not already open) and returns to your application. On your application's next call to WaitNextEvent, your application receives a suspend event and the Process Manager makes SimpleText the foreground process, instructing it to open the chosen document. Handling Help Menu ChoicesBoth the MenuSelect and MenuEvent functions return the kHMHelpMenuID constant (-16490) in the high word if the user chooses an appended item from the Help menu. The item number of the appended item is returned in the low word. When the kHMHelpMenuID constant is detected, an application-defined function should be called to respond to the user's choice of a Help menu command. That function must accommodate the fact that Apple reserves the right to change the number of standard items in the Help menu.Handling a Size MenuPreambleFont 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 which 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 ChoiceThe following is an example application-defined function which handles a user's choice of an item in the Size menu:
void doHandleSizeCommand(SInt16 menuItem) { SInt16 numItems; Boolean addItem; SInt32 sizeChosen; numItems = CountMenuItems(GetMenuHandle(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 } // new font size to the text of the Other command. else // Return sizeChosen. { // User chose a size. Remove marks from doRemoveMarksFromSizeMenu(); // item/s showing previous size. Add mark CheckMenuItem(GetMenuHandle(mSize),menuItem,true); // 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 BarMac OS 8.5 introduced the functions HideMenuBar and ShowMenuBar, which may be used to make the menu bar invisible and unselectable and visible and selectable.Accessing Menus From Alert and Dialog BoxesWhen 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 - Dialogs and Alerts.
Main Menu Manager Constants, Data Types, and FunctionsIn the following:
ConstantsFor markChar Parameter of SetItemMark CallsnoMark = 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 ListhierMenu = -1 Modifier Key Masks for GetMenuItemModifiers and SetMenuItemModifiers CallskMenuCommandModifiers = 0 // If no bit is set, only the Command key is used. kMenuShiftModifier = (1 << 0) // If this bit is set, Shift key is used. kMenuOptionModifier = (1 << 1) // If this bit is set, Option key is used. kMenuControlModifier = (1 << 2) // If this bit is set, Control key is used. kMenuNoCommandModifier = (1 << 3) // If this bit is set, Command key is not used. Menu Icon Handle Constants for GetMenuItemIconHandle and SetMenuItemIconHandle CallskMenuNoIcon = 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. Data TypesMenu Structurestruct MenuInfo { short menuID; // Number that identifies the menu. short menuWidth; // Width (in pixels) of menu. short menuHeight; // Height (in pixels) of menu. Handle menuProc; // Menu definition procedure. long enableFlags; // Indicates whether menu and menu items are enabled. Str255 menuData; // Title of menu. }; typedef struct MenuInfo MenuInfo; typedef MenuInfo *MenuPtr; typedef MenuPtr *MenuHandle; FunctionsInitialising the Menu Managervoid InitMenus(); Creating MenusMenuHandle NewMenu(short menuID, ConstStr255Param menuTitle); MenuHandle GetMenu(short resourceID); Adding Menus to and Removing Menus From the Current Menu Listvoid InsertMenu(MenuHandle theMenu,short beforeID); void DeleteMenu(short menuID); void ClearMenuBar(void); Getting a MenuBar Description From an 'MBAR' resourceHandle GetNewMBar(short menuBarID); Getting and Setting the Menu BarHandle GetMenuBar(void); void SetMenuBar(Handle menuList); short GetMBarHeight(void); Drawing the Menu Barvoid DrawMenuBar(void); void InvalMenuBar(void); Controlling Menu Bar Visibilityvoid HideMenuBar(void); void ShowMenuBar(void); Boolean IsMenuBarVisible(void); Modifying the Menu WidthBoolean GetMenuExcludesMarkColumn(MenuHandle menu); OSStatus SetMenuExcludesMarkColumn(MenuHandle menu,Boolean excludesMark); Responding to User Choice of a Menu Commandlong MenuKey(short ch); 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 Handle to a Menu StructureMenuHandle GetMenuHandle(short menuID); OSErr HMGetHelpMenuHandle(MenuHandle *mh); Adding and Deleting Menu Itemsvoid AppendMenu(MenuHandle menu,ConstStr255Param data); void InsertMenuItem(MenuHandle theMenu,ConstStr255Param itemString,short afterItem); OSStatus AppendMenuItemText(MenuHandle menu,ConstStr255Param inString); OSStatus InsertMenuItemText(MenuHandle menu,ConstStr255Param inString,UInt16 afterItem); void DeleteMenuItem(MenuHandle theMenu,short item); void AppendResMenu(MenuHandle theMenu,ResType theType); void InsertResMenu(MenuHandle theMenu,ResType theType,short afterItem); Manipulating and Accessing Menu Item Characteristicsvoid EnableItem(MenuHandle theMenu,short item); void DisableItem(MenuHandle theMenu,short item); void EnableMenuItem(MenuHandle theMenu,UInt16 item); void DisableMenuItem(MenuHandle theMenu,UInt16 item); Boolean IsMenuItemEnabled(MenuHandle menu,UInt16 item); void EnableMenuItemIcon(MenuHandle theMenu,UInt16 item); void DisableMenuItemIcon(MenuHandle theMenu,UInt16 item); Boolean IsMenuItemIconEnabled(MenuHandle menu,UInt16 item); void GetMenuItemText(MenuHandle menu,short item,Str255 itemString); void SetMenuItemText(MenuHandle theMenu, short item, ConstStr255Param itemString); 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 SetMenuItemCommandID(MenuHandle inMenu,SInt16 inItem,UInt32 inCommandID); OSErr GetMenuItemCommandID(MenuHandle inMenu,SInt16 inItem,UInt32* outCommandID); OSErr SetMenuItemFontID(MenuHandle inMenu,SInt16 inItem,SInt16 inFontID); OSErr GetMenuItemFontID(MenuHandle inMenu,SInt16 inItem,SInt16* outFontID); OSErr SetMenuItemHierarchicalID(MenuHandle inMenu,SInt16 inItem,SInt16 inHierID); OSErr GetMenuItemHierarchicalID(MenuHandle inMenu,SInt16 inItem,SInt16 *outHierID); OSErr SetMenuItemIconHandle(MenuHandle inMenu,SInt16 inItem,MenuIconType inIconType, Handle inIconHandle); OSErr GetMenuItemIconHandle(MenuHandle inMenu,SInt16 inItem,MenuIconType outIconType, Handle* outIconHandle); OSErr SetMenuItemKeyGlyph(MenuHandle inMenu,SInt16 inItem,SInt16 inGlyph); OSErr GetMenuItemKeyGlyph(MenuHandle inMenu,SInt16 inItem,SInt16 *outGlyph); OSErr SetMenuItemModifiers(MenuHandle inMenu,SInt16 inItem,SInt16 inModifiers); OSErr GetMenuItemModifiers(MenuHandle inMenu,SInt16 inItem,SInt16* outModifiers); OSErr SetMenuItemRefCon(MenuHandle inMenu,SInt16 inItem,SInt32 inRefCon); OSErr GetMenuItemRefCon(MenuHandle inMenu,SInt16 inItem,SInt32* outRefCon); OSErr SetMenuItemRefCon2(MenuHandle inMenu,SInt16 inItem,SInt32 inRefCon); OSErr GetMenuItemRefCon2(MenuHandle inMenu,SInt16 inItem,SInt32* outRefCon); OSErr SetMenuItemTextEncoding(MenuHandle inMenu,SInt16 inItem,TextEncoding inScriptID); OSErr GetMenuItemTextEncoding(MenuHandle inMenu,SInt16 inItem,TextEncoding* outScriptID); Disposing of Menusvoid DisposeMenu(MenuHandle theMenu); Counting Items in a Menushort CountMenuItems(MenuHandle theMenu); Highlighting the Menu Barvoid FlashMenuBar(short menuID); void SetMenuFlash(short count); Recalculating Menu Dimensionsvoid CalcMenuSize(MenuHandle theMenu);
|
- SPREAD THE WORD:
- Slashdot
- Digg
- Del.icio.us
- Newsvine