MacApp's Menu ManagementMacApp supplies many facilities to help your application display menus and respond to menu commands. You can read more about these topics in
Chapter 1, "MacApp Overview," and in Chapter 12, "Working With Menus." This section provides detailed information on MacApp's menu management, command-numbering system, and optimized menu setup.
Components of MacApp Menu ManagementThe components of MacApp's menu management work together to supply two important features:
MacApp doesn't have a single menu manager object but rather a number of related global objects and global routines for working with menus. The following objects are created and initialized in the global routine
- a command-numbering system that is independent of the placement of menus and menu items
- a framework for optimizing menu setup
InitUMenuMgr, which is called from
MacApp also supplies global routines to modify the appearance of menu items, including setting the text or style of a menu command, checking or unchecking a menu command, setting an icon for a menu command, and so on. Some of these routines are supplied by the
- This table stores entries consisting of a menu command number and its associated menu ID and menu item number. For example, the entry for the New menu command from the File menu has the command number
cNew, the menu ID number
mFile, and the item number 1.
- This object manages the installation of menu bars.
- This object stores a list of menu IDs and their associated resource IDs, sorted by resource ID. For example, for the File menu MacApp uses
mFileas both the menu ID and the resource ID.
- This table stores menu resource handles for the menus managed by MacApp.
TMenuBarManagerclass, which is described in Chapter 12, "Working With Menus."
MacApp's Command-Numbering SystemMacApp's command-numbering mechanism associates command numbers with menu items. When a user chooses a menu command, MacApp passes the command number for that item to your application. You create a command object to perform a specified action based on the command number.
You assign a unique command number of type
CommandNumberto each menu command. Negative numbers and positive numbers up to 999 are reserved by MacApp. To associate a command number with a menu item, you define a menu resource of the
'CMNU'resource type. The
'CMNU'type is similar to the
'MENU'type, but for each menu item it contains an additional field that specifies a command number. The following line from MacApp's default File menu
'CMNU'resource associates the
cNewcommand number with the New menu command:
"New",noIcon, "N",noMark, plain, cNew;The fields in this line specify the following menu information:
MacApp's menu management provides a number of global routines for working with command numbers in your application:
- "New" is the name of the menu item.
- No icon is drawn on the menu for this item.
- Command-N is a keyboard equivalent for choosing this menu item.
- The menu item does not have an initial checkmark.
- The menu item text style is plain text.
- The command number associated with the New menu command is defined by the constant cNew.
You can read about these and other menu routines in the MacApp Class and Method Reference.
- Tells you if the menu item with the specified command number is currently enabled.
- Returns the command number for the specified menu ID and item number.
- Returns the menu ID and item number for the specified command number.
- Returns the text of the menu item for the specified command number.
CommandFromMenuItemroutines work regardless of whether the command is actually installed in the menu bar. This allows MacApp to use a special
'CMNU'resource (see "The Buzzwords 'CMNU' Resource," beginning on page 305) to specify words or phrases to be displayed in the Undo menu item for an operation that isn't specified by a menu command.
Creating Menu Numbers on the FlySometimes the items to be displayed on a menu cannot be determined until runtime. For example, many applications use a menu to display the names of the open windows or the available fonts, which cannot be known until the program is running. Since you cannot assign a command number for the items ahead of time, MacApp generates a command number using this formula:
CommandNumber = -(256 * menu + item)These command numbers are always negative. For an example of how a Font menu uses these command numbers, see the DemoText sample application.
Optimized Menu SetupAn application must maintain the proper state for its menus and menu items. Depending on the active window, a menu may need to be enabled or disabled, or it may need to have items added or removed. A menu item may need to be checked or unchecked, enabled or disabled.
MacApp automatically performs menu setup by calling the
DoSetupMenusmethod for objects in the target chain whenever your application's menus may have changed. Each object enables the menu commands it handles. It can also check or uncheck menu items and set the text for its commands.
Applications that don't use MacApp perform menu setup through Toolbox calls such as
CheckItem. Each of these routines in turn calls
CalcMenuSize, because the width or height of the menu may have changed. Repeatedly recalculating the height and width of menus is inefficient at best. MacApp's menu management optimizes menu setup by performing all setup at one time and making just one call to
CalcMenuSizeat the end of the setup process.