Inside Macintosh: Macintosh Toolbox Essentials /: Chapter 3 - Menu Manager

Summary of the Menu Manager

Pascal Summary

Constants

CONST
      noMark         = 0;  {menu item doesn't have a marking character}

      {values for the message parameter to the menu definition procedure}
      mDrawMsg       = 0;  {draw the menu items of a menu}
      mChooseMsg     = 1;  {highlight or unhighlight a menu item as }
                           { appropriate if the cursor is in a menu item}
      mSizeMsg       = 2;  {calculate the dimensions of a menu}
      mPopUpMsg      = 3;  {calculate the open pop-up box rectangle}
   
      textMenuProc   = 0;  {resource ID of standard menu definition }
                           { procedure}
      hMenuCmd       = 27; {constant ($1B) specified as keyboard equivalent }
                           { to indicate a menu item has a submenu}
      hierMenu       = -1; {constant used with InsertMenu routine to insert }
                           { a submenu or pop-up menu into the submenu }
                           { portion of the current menu list}
      mctAllItems    = -98;{search for all items with the given ID}
      mctLastIDIndic = -99;{last menu color table entry has this value }
                           { in the ID field of the entry}

Data Types

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;

      MenuPtr     = ^MenuInfo;   {pointer to a menu record}
      MenuHandle  = ^MenuPtr;    {handle to a menu record}
      MCEntry =                  {menu color entry record}
      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 record}

      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}

Menu Manager Routines

Initializing the Menu Manager

PROCEDURE InitMenus;
PROCEDURE InitProcMenu(resID: Integer);

Creating Menus

FUNCTION NewMenu (menuID: Integer; menuTitle: Str255)
: MenuHandle;
FUNCTION GetMenu (resourceID: Integer): MenuHandle;

Adding Menus to and Removing Menus From the Current Menu List

PROCEDURE InsertMenu (theMenu: MenuHandle; beforeID: Integer);
PROCEDURE DeleteMenu (menuID: Integer);
PROCEDURE ClearMenuBar;

Getting a Menu Bar Description From an 'MBAR' Resource

FUNCTION GetNewMBar (menuBarID: Integer): Handle;

Getting and Setting the Menu Bar

FUNCTION GetMenuBar: Handle;
PROCEDURE SetMenuBar (menuList: Handle);
FUNCTION GetMBarHeight: Integer;

Drawing the Menu Bar

PROCEDURE DrawMenuBar;
PROCEDURE InvalMenuBar;

Responding to the User's Choice of a Menu Command

FUNCTION MenuSelect(startPt: Point): LongInt;
FUNCTION MenuKey(ch: Char): LongInt;
FUNCTION MenuChoice: LongInt;
PROCEDURE HiliteMenu (menuID: Integer);
FUNCTION PopUpMenuSelect (menu: MenuHandle;
Top: Integer; Left: Integer; 
PopUpItem: Integer): LongInt;
PROCEDURE SystemMenu (menuResult: LongInt);
FUNCTION SystemEdit (editCmd: Integer): Boolean;

Getting a Handle to a Menu Record

{some routines have two spellings, see Table 3-8 for the alternate spelling}
FUNCTION GetMenuHandle (menuID: Integer): MenuHandle;
FUNCTION HMGetHelpMenuHandle
   (VAR mh: MenuHandle): OSErr;

Adding and Deleting Menu Items

{some routines have two spellings, see Table 3-8 for the alternate spelling}
PROCEDURE AppendMenu(menu: MenuHandle; data: Str255);
PROCEDURE InsertMenuItem(theMenu: MenuHandle; itemString: Str255; 
afterItem: Integer);
PROCEDURE DeleteMenuItem(theMenu: MenuHandle; item: Integer);
PROCEDURE AppendResMenu(theMenu: MenuHandle; theType: ResType);
PROCEDURE InsertResMenu(theMenu: MenuHandle; theType: ResType;
                        afterItem: Integer);

Getting and Setting the Appearance of Menu Items

{some routines have two spellings, see Table 3-8 for the alternate spelling}
PROCEDURE EnableItem (theMenu: MenuHandle; item: Integer);
PROCEDURE DisableItem (theMenu: MenuHandle; item: Integer);
PROCEDURE GetMenuItemText (theMenu: MenuHandle; item: Integer;
                     VAR itemString: Str255);
PROCEDURE SetMenuItemText (theMenu: MenuHandle; item: Integer;
                  itemString: Str255);
PROCEDURE GetItemStyle (theMenu: MenuHandle; item: Integer;
                        VAR chStyle: Style);
PROCEDURE SetItemStyle (theMenu: MenuHandle; item: Integer;
                        chStyle: Style);
PROCEDURE GetItemMark (theMenu: MenuHandle; item: Integer;
                        VAR markChar: Char);
PROCEDURE SetItemMark (theMenu: MenuHandle; item: Integer;
                        markChar: Char);
PROCEDURE CheckItem (theMenu: MenuHandle; item: Integer;
                     checked: Boolean);
PROCEDURE GetItemIcon (theMenu: MenuHandle; item: Integer;
                        VAR iconIndex: Byte);
PROCEDURE SetItemIcon (theMenu: MenuHandle; item: Integer;
                        iconIndex: Byte);
PROCEDURE GetItemCmd(theMenu: MenuHandle; item: Integer;
VAR cmdChar: CHAR);
PROCEDURE SetItemCmd(theMenu: MenuHandle; item: Integer;
cmdChar: CHAR);

Disposing of Menus

PROCEDURE DisposeMenu (theMenu: MenuHandle);

Counting the Items in a Menu

FUNCTION CountMItems (theMenu: MenuHandle): Integer;

Highlighting the Menu Bar

PROCEDURE FlashMenuBar (menuID: Integer);
PROCEDURE SetMenuFlash (count: Integer);

Recalculating Menu Dimensions

PROCEDURE CalcMenuSize (theMenu: MenuHandle);

Managing Entries in the Menu Color Information Table

{some routines have two spellings, see Table 3-8 for the alternate spelling}
FUNCTION GetMCInfo: MCTableHandle;
PROCEDURE SetMCInfo(menuCTbl: MCTableHandle);
PROCEDURE DisposeMCInfo (menuCTbl: MCTableHandle);
FUNCTION GetMCEntry (menuID: Integer; menuItem: Integer)
: MCEntryPtr;
PROCEDURE SetMCEntries (numEntries: Integer; 
                        menuCEntries: MCTablePtr);
PROCEDURE DeleteMCEntries (menuID: Integer; menuItem: Integer);

Application-Defined Routine

PROCEDURE MyMenuDef (message: Integer; theMenu: MenuHandle;
                     VAR menuRect: Rect; hitPt: Point; 
                     VAR whichItem: Integer);

C Summary

Constants

enum {
      #define noMark '\0'  /*menu item doesn't have a marking character*/

      /*values for the message parameter to the menu definition procedure*/
      mDrawMsg       = 0,  /*draw the menu items of a menu*/
      mChooseMsg     = 1,  /*highlight or unhighlight a menu item as */
                           /* appropriate if the cursor is in a menu item*/
      mSizeMsg       = 2,  /*calculate the dimensions of a menu*/
      mPopUpMsg      = 3,  /*calculate the open pop-up box rectangle*/
   
      textMenuProc   = 0,  /*resource ID of standard menu definition */
                           /* procedure*/
      hMenuCmd       = 27, /*constant ($1B) specified as keyboard */
                           /* equivalent to indicate an item has a submenu*/
      hierMenu       = -1, /*constant used with InsertMenu to insert */
                           /* a submenu or pop-up menu into the submenu */
                           /* portion of the current menu list*/
      mctAllItems    = -98,/*search for all items with the given ID*/
      mctLastIDIndic = -99 /*last menu color table entry has this value */
                           /* in the ID field of the entry*/
   };

Data Types

struct MenuInfo {          /*menu record*/
         short       menuID;        /*number that identifies the menu*/
         short       menuWidth;     /*width (in pixels) of the menu*/
         short       menuHeight;    /*height (in pixels) of the menu*/
         Handle      menuProc;      /*menu definition procedure*/
         long        enableFlags;   /*indicates whether menu and */
                                    /* menu items are enabled*/
         Str255      menuData;      /*title of menu*/
         /*itemDefinitions*/        /*variable-length data that */
                                    /* defines the menu items*/
      };

typedef struct MenuInfo MenuInfo;         /*pointer to a menu record*/
typedef MenuInfo *MenuPtr, **MenuHandle;  /*handle to a menu record*/
struct MCEntry {           /*menu color entry record*/
         short       mctID;         /*menu ID or 0 for menu bar*/
         short       mctItem;       /*menu item number or 0 for */
                                    /* menu title*/
         RGBColor    mctRGB1;       /*usage depends on mctID and */
                                    /* mctItem*/
         RGBColor    mctRGB2;       /*usage depends on mctID and */
                                    /* mctItem*/
         RGBColor    mctRGB3;       /*usage depends on mctID and */
                                    /* mctItem*/
         RGBColor    mctRGB4;       /*usage depends on mctID and */
                                    /* mctItem*/
         short       mctReserved;   /*reserved*/
      };

typedef struct MCEntry MCEntry;
typedef MCEntry *MCEntryPtr;        /*pointer to a menu color entry record*/
                                    /*menu color table*/
typedef MCEntry MCTable[1], *MCTablePtr, **MCTableHandle;

Menu Manager Routines

Initializing the Menu Manager

pascal void InitMenus(void);
pascal void InitProcMenu(short resID);

Creating Menus

pascal MenuHandle NewMenu (short menuID, const Str255 menuTitle);
pascal MenuHandle GetMenu (short resourceID);

Adding Menus to and Removing Menus From the Current Menu List

pascal void InsertMenu(MenuHandle theMenu, short beforeID);
pascal void DeleteMenu(short menuID);
pascal void ClearMenuBar(void);

Getting a Menu Bar Description From an 'MBAR' Resource

pascal Handle GetNewMBar (short menuBarID);

Getting and Setting the Menu Bar

pascal Handle GetMenuBar(void);
pascal void SetMenuBar(Handle menuList);
#define GetMBarHeight() (* (short*) 0x0BAA)

Drawing the Menu Bar

pascal void DrawMenuBar(void);
pascal void InvalMenuBar(void);

Responding to the User's Choice of a Menu Command

pascal long MenuSelect(Point startPt);
pascal long MenuKey(short ch);
pascal long MenuChoice(void);
pascal void HiliteMenu(short menuID);
pascal long PopUpMenuSelect(MenuHandle menu, short top, short left,
short popUpItem);
pascal void SystemMenu(long menuResult);
pascal Boolean SystemEdit(short editCmd);

Getting a Handle to a Menu Record

{some routines have two spellings, see Table 3-8 for the alternate spelling}
pascal MenuHandle GetMenuHandle 
(short menuID);
pascal OSErr HMGetHelpMenuHandle 
(MenuHandle *mh);

Adding and Deleting Menu Items

{some routines have two spellings, see Table 3-8 for the alternate spelling}
pascal void AppendMenu(MenuHandle menu, ConstStr255Param data);
pascal void InsertMenuItem(MenuHandle theMenu, 
ConstStr255Param itemString,
short afterItem);
pascal void DeleteMenuItem(MenuHandle theMenu, short item);
pascal void AppendResMenu(MenuHandle theMenu, ResType theType);
pascal void InsertResMenu(MenuHandle theMenu, ResType theType,
short afterItem);

Getting and Setting the Appearance of Menu Items

{some routines have two spellings, see Table 3-8 for the alternate spelling}
pascal void EnableItem(MenuHandle theMenu, short item);
pascal void DisableItem(MenuHandle theMenu, short item);
pascal void GetMenuItemText(MenuHandle theMenu, short item,
Str255 itemString);
pascal void SetMenuItemText(MenuHandle theMenu, short item, 
ConstStr255Param itemString);
pascal void GetItemStyle(MenuHandle theMenu, short item, 
Style *chStyle);
pascal void SetItemStyle(MenuHandle theMenu, short item, short chStyle);
pascal void GetItemMark(MenuHandle theMenu, short item, 
short *markChar);
pascal void SetItemMark(MenuHandle theMenu, short item, 
short markChar);
pascal void CheckItem (MenuHandle theMenu, short item, 
Boolean checked);
pascal void GetItemIcon(MenuHandle theMenu, short item, 
short *iconIndex);
pascal void SetItemIcon(MenuHandle theMenu, short item, 
short iconIndex);
pascal void GetItemCmd(MenuHandle theMenu, short item, short 
*cmdChar);
pascal void SetItemCmd(MenuHandle theMenu, short item, short cmdChar);

Disposing of Menus

pascal void DisposeMenu(MenuHandle theMenu);

Counting the Items in a Menu

pascal short CountMItems(MenuHandle theMenu);

Highlighting the Menu Bar

pascal void FlashMenuBar(short menuID);
pascal void SetMenuFlash(short count);

Recalculating Menu Dimensions

pascal void CalcMenuSize(MenuHandle theMenu);

Managing Entries in the Menu Color Information Table

{some routines have two spellings, see Table 3-8 for the alternate spelling}
pascal MCTableHandle GetMCInfo(void);
pascal void SetMCInfo(MCTableHandle menuCTbl);
pascal void DisposeMCInfo(MCTableHandle menuCTbl);
pascal MCEntryPtr GetMCEntry(short menuID, short menuItem);
pascal void SetMCEntries(short numEntries, MCTablePtr menuCEntries);
pascal void DeleteMCEntries(short menuID, short menuItem);

Application-Defined Routine

pascal void MyMenuDef (short message, MenuHandle theMenu,
                     Rect *menuRect, Point hitPt, 
short *whichItem);

Assembly-Language Summary

Data Structures

The Menu Information Data Structure
0 `menuID` word number that identifies the menu
2 `menuWidth` word width (in pixels) of the menu
4 `menuHeight` word height (in pixels) of the menu
6 `menuDefHandle` long menu definition procedure
10 `menuEnable` long enable flags
14 `menuData` 256 bytes menu title followed by menu item information

Global Variables
AtMenuBottom The pixel value at the bottom of the scrollable menu.
`MBarEnable` Contains 0 if all menus in the current menu bar belong to an application; contains a nonzero value if all menus belong to a desk accessory.
MBarHeight Contains current height of the menu bar, in pixels.
MBarHook Address of routine that `MenuSelect` calls repeatedly while the mouse button
is down.
MenuCInfo Contains a handle to application's menu color information table.
MenuDisable Contains the menu ID and item number of the last item chosen, regardless of whether the item was disabled or enabled.
MenuFlash Contains the current count (number of times) a menu item blinks when chosen by the user.
MenuHook Address of routine that `MenuSelect` calls after a menu title is highlighted and the menu rectangle is calculated but before the menu is drawn.
TheMenu Contains the menu ID of the highlighted menu in the menu bar.
TopMenuItem The pixel value at the top of the scrollable menu.

Result Codes
noErr 0 No error
paramErr -50 Error in parameter list
memFullErr -108 Not enough room in heap zone
resNotFound -192 Unable to read resource
hmHelpManagerNotInited -855 Help menu not set up

0	`menuID`	word	number that identifies the menu
2	`menuWidth`	word	width (in pixels) of the menu
4	`menuHeight`	word	height (in pixels) of the menu
6	`menuDefHandle`	long	menu definition procedure
10	`menuEnable`	long	enable flags
14	`menuData`	256 bytes	menu title followed by menu item information

AtMenuBottom	The pixel value at the bottom of the scrollable menu.
`MBarEnable`	Contains 0 if all menus in the current menu bar belong to an application; contains a nonzero value if all menus belong to a desk accessory.
MBarHeight	Contains current height of the menu bar, in pixels.
MBarHook	Address of routine that `MenuSelect` calls repeatedly while the mouse button is down.
MenuCInfo	Contains a handle to application's menu color information table.
MenuDisable	Contains the menu ID and item number of the last item chosen, regardless of whether the item was disabled or enabled.
MenuFlash	Contains the current count (number of times) a menu item blinks when chosen by the user.
MenuHook	Address of routine that `MenuSelect` calls after a menu title is highlighted and the menu rectangle is calculated but before the menu is drawn.
TheMenu	Contains the menu ID of the highlighted menu in the menu bar.
TopMenuItem	The pixel value at the top of the scrollable menu.

noErr	0	No error
paramErr	-50	Error in parameter list
memFullErr	-108	Not enough room in heap zone
resNotFound	-192	Unable to read resource
hmHelpManagerNotInited	-855	Help menu not set up

Summary of the Menu Manager

Pascal Summary

Constants

Data Types

Menu Manager Routines

Initializing the Menu Manager

Creating Menus

Adding Menus to and Removing Menus From the Current Menu List

Getting a Menu Bar Description From an 'MBAR' Resource

Getting and Setting the Menu Bar

Drawing the Menu Bar

Responding to the User's Choice of a Menu Command

Getting a Handle to a Menu Record

Adding and Deleting Menu Items

Getting and Setting the Appearance of Menu Items

Disposing of Menus

Counting the Items in a Menu

Highlighting the Menu Bar

Recalculating Menu Dimensions

Managing Entries in the Menu Color Information Table

Application-Defined Routine

C Summary

Constants

Data Types

Menu Manager Routines

Initializing the Menu Manager

Creating Menus

Adding Menus to and Removing Menus From the Current Menu List

Getting a Menu Bar Description From an 'MBAR' Resource

Getting and Setting the Menu Bar

Drawing the Menu Bar

Responding to the User's Choice of a Menu Command

Getting a Handle to a Menu Record

Adding and Deleting Menu Items

Getting and Setting the Appearance of Menu Items

Disposing of Menus

Counting the Items in a Menu

Highlighting the Menu Bar

Recalculating Menu Dimensions

Managing Entries in the Menu Color Information Table

Application-Defined Routine

Assembly-Language Summary

Data Structures

Result Codes noErr0No error paramErr-50Error in parameter list memFullErr-108Not enough room in heap zone resNotFound-192Unable to read resource hmHelpManagerNotInited-855Help menu not set up

Result Codes
noErr 0 No error
paramErr -50 Error in parameter list
memFullErr -108 Not enough room in heap zone
resNotFound -192 Unable to read resource
hmHelpManagerNotInited -855 Help menu not set up