- Introduction—Types of Menus
- Pull-Down Menus
- Hierarchical Menus
- Pop-Up Menus
- Menu Objects, Menu IDs and Item Numbers, Command IDs, and Menu Lists
- Creating Your Application's Menus
- Providing Help Balloons (Mac OS 8/9)
- Changing Menu Item Appearance
- Adding Items to a Menu
- Associating Data with Menu Items
- Handling Menu Choices
- Hiding and Showing the Menu Bar
- Accessing Menus from Alerts and Dialogs
- Main Menu Manager Constants, Data Types, and Functions
- Demonstration Program Menus1 Listing
- Demonstration Program Menus1 Comments
- Demonstration Program Menus2 Listing
- Demonstration Program Menus2 Comments
This chapter is from the book
This chapter is from the book
This chapter is from the book
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;
Carbon Note
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:
|
Function |
Description |
|
GetMenuID |
Gets the menu ID of the specified menu. |
|
SetMenuID |
Sets the menu ID of the specified menu. |
|
GetMenuWidth |
Gets the horizontal dimensions, in pixels, of the specified menu. |
|
SetMenuWidth |
Sets the horizontal dimensions, in pixels, of the specified menu. |
|
GetMenuHeight |
Gets the vertical dimensions, in pixels, of the specified menu. |
|
SetMenuHeight |
Sets the vertical dimensions, in pixels, of the specified menu. |
|
GetMenuTitle |
Gets the title of the specified menu. |
|
SetMenuTitle SetMenuTitleWithCFString |
Sets the title of the specified menu. |
|
GetMenuDefinition |
Gets a pointer to a custom menu definition function that has already been associated with the menu. (There is no way to get a pointer to the system menu definition function.) |
|
SetMenuDefinition |
Sends a dispose message to the current menu definition and an init message to the new definition. |
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.