Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 3 - Menu Manager / Menu Manager Reference

Data Structures

The Menu Record

A menu record contains information about a single menu. Your application should never manipulate or access the fields of a menu record; instead your application should use Menu Manager routines to create and manage the menus in your application. To refer to a menu, use a handle to the menu's menu record.

The MenuInfo data type defines the menu record. The MenuHandle data type is a handle to a menu record.

TYPE  MenuPtr     = ^MenuInfo;   {pointer to a menu record}
      MenuHandle  = ^MenuPtr;    {handle to a menu record} 

Here is the structure of a menu record:

TYPE  MenuInfo =                 {menu record}
      RECORD
         menuID:     Integer;    {number that identifies the menu}
         menuWidth:  Integer;    {width (in pixels) of the menu}
         menuHeight: Integer;    {height (in pixels) of the menu}
         menuProc:   Handle;     {menu definition procedure}
         enableFlags: LongInt;   {indicates whether menu and }
                                 { menu items are enabled}
         menuData:   Str255;     {title of menu}
         {itemDefinitions}       {variable-length data that }
                                 { defines the menu items}
      END;

Field Description

menuID

A number that identifies the menu. Each menu in your application must have a unique menu ID. Your application specifies the menu ID when you create the menu. Thereafter you can use the menu ID and the GetMenuHandle function to get a handle to the menu's menu record.

When you define hierarchical menus, you must use a number from 1 through 235 for the menu ID of a submenu of an application; use a number from 236 through 255 for the submenu of a desk accessory.

menuWidth

The horizontal dimensions of the menu, in pixels.

menuHeight

The vertical dimensions of the menu, in pixels.

menuProc

A handle to the menu definition procedure of the menu. The Menu Manager uses this menu definition procedure to draw the menu.

enableFlags

A value that represents the enabled state of the menu title and
the first 31 items in the menu. All menu items greater than 31
are enabled by default and can be disabled only by disabling the entire menu.

menuData

A string that defines the title of the menu. Although the menuData field is defined by the data type Str255 in the MenuInfo data structure, the Menu Manager allocates only the storage necessary for the title: the number of characters in the title of the string plus 1.

itemDefinitions

Variable-length data that defines the characteristics of each menu item in the menu. If the menu uses the standard menu definition procedure, this data can be conceptually defined in this manner:

itemData: ARRAY[1..X] OF
itemString: String; {text of menu item}
itemIcon: Byte; {icon number minus 256}

itemCmd: Char; {keyboard equivalent or }
{ value ($1B) indicating }
{ item has a submenu, or }
{ ($1C) if item has }
{ a script code, or }
{ ($1D) if item's 'ICON' }
{ should be reduced, or }
{ ($1E) if item has an }
{ 'SICN' icon}
itemMark: Char; {marking character or }
{ menu ID of submenu}
itemStyle: Style; {style of menu text}
endMarker: Byte; {contains 0 if no }
{ more menu items}

The menu definition procedure maintains the information about the menu items. You typically define your menu items in 'MENU' resources, and the Menu Manager stores information describing your items in the menu's menu record.

Your application should not directly change the values of any fields in a menu record. Use Menu Manager routines to change the characteristics of menu items or to make other changes to a menu.