Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 3 - Menu Manager / Menu Manager Reference

Data Structures

The Menu Color Information Table Record

Your application's menu color information table defines the standard color for the menu bar, titles of menus, text and characteristics of menu items, and background color of a displayed menu. If you do not add any entries to this table, the Menu Manager draws your menus using the default colors, black on white. You can add colors to your menus by adding entries to your application's menu color information table by using Menu Manager routines or by defining these entries in an 'mctb' resource. Note that the menu color information table uses a format that is different from the standard color table format.

The Menu Manager maintains information about an application's menu color information table as an array of menu color entry records.

TYPE  MCTable = ARRAY[0..0] OF MCEntry;         {menu color table}
      MCTablePtr = ^MCTable;      {pointer to a menu color table}
      MCTableHandle = ^MCTablePtr;{handle to a menu color table}

A menu color entry is defined by the MCEntry data type.

TYPE  MCEntry =                  {menu color entry}
      RECORD
         mctID:      Integer;    {menu ID or 0 for menu bar}
         mctItem:    Integer;    {menu item number or 0 for }
                                 { menu title}
         mctRGB1:    RGBColor;   {usage depends on mctID and }
                                 { mctItem}
         mctRGB2:    RGBColor;   {usage depends on mctID and }
                                 { mctItem}
         mctRGB3:    RGBColor;   {usage depends on mctID and }
                                 { mctItem}
         mctRGB4:    RGBColor;   {usage depends on mctID and }
                                 { mctItem}
         mctreserved:Integer;    {reserved}
      END;

      MCEntryPtr = ^MCEntry;     {pointer to a menu color entry}

The first two fields of a menu color entry record, mctID and mctItem, define whether the entry is a menu bar entry, a menu title entry, or a menu item entry. The following four fields specify color information for whatever type of entry the mctID and mctItem fields describe. The value of the mctID field in the last entry in a menu color information table is -99, and the rest of the fields of the last entry are reserved. The Menu Manager automatically creates the last entry in a menu color information table; your application should not use the value -99 as the menu ID of a menu if you wish to add a menu color entry for it.

The Menu Manager creates your application's menu color information table the first
time your application calls InitMenus or InitProcMenu. It creates the menu color information table as initially empty except for the last entry, which indicates the end
of the table.

Table 3-7 shows how the Menu Manager interprets the mctID and mctItem fields for each type of menu color entry in a menu color information table.

Table 3-7 Table 3-7 Color information for menu entries

	ID	Item	RGB1	RGB2	RGB3	RGB4
Menu bar	0	0	Default menu title color	Default back- ground color of menus	Default item color	Default bar color
Menu title	N<>0	0	Menu title color	Bar color	Default item color	Backgroundcolor of menu
Menu item	N<>0	M<>0	Mark color	Item text color	Keyboard equivalent color	Backgroundcolor of menu
Last entry	-99	Reserved	Reserved	Reserved	Reserved	Reserved

A menu bar entry is defined by a menu color entry record that contains 0 in both the mctID and mctItem fields. You can define only one menu bar entry in a menu color information table. If you don't provide a menu bar entry for your application's menu color information table, the Menu Manager uses the standard menu bar colors (black text on a white background), and it uses the standard colors for the other menu elements. You can provide a menu bar entry to specify default colors for the menu title, the background of a displayed menu, the items in a menu, and the menu bar. The color information fields for a menu bar entry are interpreted as follows:

• mctRGB1 specifies the default color for menu titles. If a menu doesn't have a menu title entry, the Menu Manager uses the value in this field as the color of the menu title.
• mctRGB2 specifies the default color for the background of a displayed menu. If a menu doesn't have a menu title entry, the Menu Manager uses the value in this field as the color of the menu's background when it is displayed.
• mctRGB3 specifies the default color for the items in a displayed menu. If a menu item doesn't have a menu item entry or a default color defined in a menu title entry, the Menu Manager uses the value in this field as the color of the menu item.
• mctRGB4 specifies the default color for the menu bar. If a menu doesn't have a menu bar entry (and doesn't have any menu title entries), the Menu Manager uses the standard colors for the menu bar.

A menu title entry is defined by a menu color entry record that contains a menu ID in the mctID field and 0 in the mctItem field. You can define only one menu title entry for each menu. If you don't provide a menu title entry for a menu in your application's menu color information table, the Menu Manager uses the colors defined by the menu bar entry. If a menu bar entry doesn't exist, the Menu Manager uses the standard colors




(black on white). You can provide a menu title entry to specify a color for the title and background of a specific menu and a default color for its items. The color information fields for a menu title entry are interpreted as follows:

• mctRGB1 specifies the color for the menu title of the specified menu. If a menu doesn't have a menu title entry, the Menu Manager uses the default value defined
  in the menu bar entry.
• mctRGB2 specifies the default color for the menu bar. If a menu color information table doesn't have a menu bar entry, the Menu Manager uses the value in this field as the color of the menu bar. If a menu bar entry already exists, the Menu Manager replaces the value in the mctRGB2 field of the menu title entry with the value defined in the mctRGB4 field of the menu bar entry.
• mctRGB3 specifies the default color for the items in the menu. If a menu item doesn't have a menu item entry or a default color defined in a menu bar entry, the Menu Manager uses the value in this field as the color of the menu item.
• mctRGB4 specifies the color for the background of the menu.

A menu item entry is defined by a menu color entry record that contains a menu ID in the mctID field and an item number in the mctItem field. You can define only one menu item entry for each menu item. If you don't provide a menu item entry for an item in your application's menu color information table, the Menu Manager uses the colors defined by the menu title entry (or by the menu bar entry if the menu containing the item doesn't have a menu title entry). If neither a menu title entry nor a menu bar entry exists, the Menu Manager draws the mark, text, and keyboard equivalent in black. You can provide a menu item entry to specify a color for the mark, text, and keyboard equivalent of a specific menu item. The color information fields for a menu item entry are interpreted as follows:

• mctRGB1 specifies the color for the mark of the menu item. If a menu item doesn't have a menu item entry, the Menu Manager uses the default value defined in the menu title entry or the menu bar entry.
• mctRGB2 specifies the color for the text of the menu item. If a menu item doesn't have a menu item entry, the Menu Manager uses the default value defined in the menu title entry or the menu bar entry. The Menu Manager also draws a black-and-white icon of a menu item using the same color as defined by the mctRGB2 field. (Use a 'cicn' resource to provide a menu item with a color icon.)
• mctRGB3 specifies the color for the keyboard equivalent of the menu item. If a menu item doesn't have a menu item entry, the Menu Manager uses the default value defined in the menu title entry or the menu bar entry.
• mctRGB4 specifies the color for the background of the menu. If the menu color information table doesn't have a menu title entry for the menu this item is in, or doesn't have a menu bar entry, the Menu Manager uses the value in this field as the background color of the menu. If a menu title entry already exists, the Menu Manager replaces the value in the mctRGB4 field of the menu item entry with the value defined in the mctRGB4 field of the menu title entry (or with the mctRGB2 field of the menu bar entry).

You can use the GetMCInfo function to get a copy of your application's menu color information table and the SetMCEntries procedure to set entries of your application's menu color information table, or you can provide 'mctb' resources that define the color entries for your menus.

The GetMenu, GetNewMBar, and ClearMenuBar routines can also modify the entries in the menu color information table. The GetMenu function looks for an 'mctb' resource with a resource ID equal to the value in the menuID parameter. If it finds one, it adds the entries to the application's menu color information table.

The GetNewMBar function builds a new menu color information table when it creates the new menu list. If you want to save the current menu color information table, call GetMCInfo before calling GetNewMBar.

The ClearMenuBar procedure reinitializes both the current menu list and the menu color information table.