Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 3 - Menu Manager / Menu Manager Reference

Application-Defined Routine / The Menu Definition Procedure

MyMenuDef

You can provide your own menu definition procedure if you need special features in a menu other than those provided by the standard menu definition procedure. This section describes how to define your own menu definition procedure, defines the parameters passed to your procedure by the Menu Manager, and describes the general actions your procedure should perform.

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

message

A number that identifies the operation that the menu definition proce- dure should perform. The message parameter can contain any one of these values:

	CONST
      mDrawMsg       = 0; {draw the menu}
      mChooseMsg     = 1; {tell which item was chosen }
                          { and highlight it}
      mSizeMsg       = 2; {calculate menu dimensions}
      mPopUpMsg      = 3; {calculate rectangle of }
                          { the pop-up box}

Your menu definition procedure should not respond to any value other than the four constants listed above.

theMenu

A handle to the menu record of the menu that the operation should affect.

menuRect

The rectangle (in global coordinates) in which the menu is located; the Menu Manager provides this information to the menu definition procedure only when the value in the message parameter is the mDrawMsg or mChooseMsg constant.

When the value in the message parameter is the mPopUpMsg constant, the menu definition procedure should calculate and then return the dimensions of the pop-up box in this parameter. When the value in the message parameter is the mSizeMsg constant, the menu definition procedure should calculate the horizontal and vertical dimensions of the menu rectangle and store these values in the menuWidth and menuHeight fields of the menu record.

hitPt

A mouse location (in global coordinates). The Menu Manager provides information in this parameter to the menu definition procedure when the value in the message parameter is the mChooseMsg or mPopUpMsg constant. When the menu definition procedure receives the mChooseMsg constant in the message parameter, it should determine whether the mouse location specified in the hitPt parameter is in an enabled menu item and highlight or unhighlight the item specified in the whichItem parameter appropriately. When the menu definition procedure receives the mPopUpMsg constant in the message parameter, the hitPt parameter contains the top-left coordinates of the closed pop-up box, which your procedure can use to calculate the rectangle of the open pop-up box.

whichItem

The item number of the last item chosen from this menu (or 0 if an item hasn't been chosen). The Menu Manager provides information in this parameter to the menu definition procedure when the value in the message parameter is the mChooseMsg constant. When the menu definition procedure receives the mChooseMsg constant in the
message parameter, it should determine whether the mouse location specified in the hitPt parameter is in an enabled menu item. If so, the menu definition procedure should unhighlight the item specified by
the whichItem parameter, highlight the new item, and return the new item number in whichItem. If the mouse location isn't in an enabled menu item, the menu definition procedure should unhighlight the
item specified by the whichItem parameter and return 0 in the
whichItem parameter.

DESCRIPTION

The Menu Manager calls your menu definition procedure whenever it needs your definition procedure to perform a certain action on a specific menu. The action
your menu definition procedure should perform depends on the value of the
message parameter.

If you provide your own menu definition procedure, store it in a resource of type 'MDEF' and include its resource ID in the description of each menu that uses your own definition procedure. If you create a menu using GetMenu (or GetNewMBar), the Menu Manager reads the menu definition procedure into memory and stores a handle to it in the menuProc field of the menu's menu record.

If you create a menu using NewMenu, the Menu Manager stores a handle to the standard menu definition procedure in the menuProc field of the menu's menu record. In this case you must replace the value in the menuProc field with a handle to your own procedure and then call the CalcMenuSize procedure. If your menu definition procedure is in a resource file, you can get its handle by using the Resource Manager to read it from the resource file into memory. However, note that you should usually store your menus in resources (rather than using NewMenu) to make your application easier to localize. See the "Resource Manager" chapter in Inside Macintosh: More Macintosh Toolbox for information on the Resource Manager.

The menu definition procedure is responsible for drawing the contents of the menu and its menu items, determining whether the cursor is in a displayed menu, highlighting and unhighlighting menu items, and calculating a menu's dimensions.

When the Menu Manager requests your menu definition procedure to perform an action on a menu, it provides your procedure with a handle to its menu record. This allows your procedure to access the data in the menu record and to use any data in the variable data portion of the menu record to appropriately handle the menu items.

When the Menu Manager creates a menu as a result of an application calling GetMenu or GetNewMBar, it fills out the menuID, menuProc, enableFlags, menuTitle, and itemDefinitions fields of the menu record according to its resource definition. If the menu is managed by your menu definition procedure, the Menu Manager calls your procedure (specifying mSizeMsg) to calculate and fill in the menuHeight and menuWidth fields of the menu record. The menu items are described by a variable length field (itemDefinitions) in the menu record. Your menu definition procedure can define and use this variable-length data in any manner it chooses.

For pop-up menus that are not implemented as controls, the Menu Manager uses the menu definition procedure to support pop-up menus. If your menu definition procedure supports pop-up menus, it should respond appropriately to the mPopUpMsg constant.

The Menu Manager specifies the mPopUpMsg constant in the message parameter and calls your menu definition procedure whenever it needs to calculate the rectangle bounded by the pop-up box for a pop-up menu that is managed by your menu definition procedure. The parameter theMenu contains a handle to the menu record
of the pop-up menu, the hitPt parameter contains the top-left coordinates of the pop- up box, and whichItem contains the previously chosen item. Your menu definition procedure should calculate the rectangle in which the pop-up menu is to appear
and return this rectangle in the menuRect parameter. If the menu is so large that it scrolls, return the actual top of the menu in the whichItem parameter. For pop-up menus, your menu definition procedure also must place the pop-up menu's scrolling information in the global variables TopMenuItem and AtMenuBottom. Place in TopMenuItem the pixel value of the top of the scrollable menu, and place in AtMenuBottom the pixel value of the bottom of the scrollable menu.

Note

Your menu definition procedure should not assume that the A5
register is properly set up, so your procedure can't refer to any of
the QuickDraw global variables.

SEE ALSO

For additional information on how your menu definition procedure should respond when it receives the mDrawMsg, mChooseMsg, or mSizeMsg constant in the message parameter, see "Writing Your Own Menu Definition Procedure" beginning on page 3-87.