Inside Macintosh: Programmer's Guide to MacApp / Part 1 - MacApp Theory and Architecture

Chapter 5 - Events and Commands

MacApp's Menu Management

MacApp 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 Management

The components of MacApp's menu management work together to supply two important features:

• a command-numbering system that is independent of the placement of menus and menu items
• a framework for optimizing menu setup

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 InitUMenuMgr, which is called from DoInitUMacApp:

gCmdTable

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.

gMenuBarManager

This object manages the installation of menu bars.

gMenuIDList

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 mFile as both the menu ID and the resource ID.

gMenuTable

This table stores menu resource handles for the menus managed by MacApp.

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 TMenuBarManager class, which is described in Chapter 12, "Working With Menus."

MacApp's Command-Numbering System

MacApp'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 CommandNumber to 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 cNew command number with the New menu command:

"New",noIcon, "N",noMark, plain, cNew;

The fields in this line specify the following menu information:

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

MacApp's menu management provides a number of global routines for working with command numbers in your application:

CommandEnabled

Tells you if the menu item with the specified command number is currently enabled.

CommandFromMenuItem

Returns the command number for the specified menu ID and item number.

CommandToMenuItem

Returns the menu ID and item number for the specified command number.

CommandToName

Returns the text of the menu item for the specified command number.

You can read about these and other menu routines in the MacApp Class and Method Reference.

Note

The CommandToMenuItem and CommandFromMenuItem routines 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 Fly

Sometimes 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 Setup

An 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 DoSetupMenus method 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 SetItem, SetItemStyle, and 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 CalcMenuSize at the end of the setup process.