Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 3 - Menu Manager / Menu Manager Reference

Menu Manager Routines / Responding to the User's Choice of a Menu Command

MenuSelect

Use the MenuSelect function to allow the user to choose a menu item from the menus in your application's menu bar.

FUNCTION MenuSelect (startPt: Point): LongInt;

startPt

The point (in global coordinates) representing the location of the cursor at the time the mouse button was pressed.

DESCRIPTION

When the user presses the mouse button while the cursor is in the menu bar, your application receives a mouse-down event. To handle mouse-down events in the menu bar, pass the location of the cursor at the time of the mouse-down event as the startPt parameter to MenuSelect. The MenuSelect function displays and removes menus as the user moves the cursor over menu titles in the menu bar, and it handles all user interaction until the user releases the mouse button.

As the user drags the cursor through the menu bar, the MenuSelect function highlights the title of the menu the cursor is currently over and displays all items in that menu. If the user moves the cursor so that it is over a different menu, the MenuSelect function removes the previous menu and unhighlights its menu title.

The MenuSelect function highlights and unhighlights menu items as the user drags the cursor over the items in a menu. The MenuSelect function highlights a menu item if the item is enabled and the cursor is currently over it; it removes such highlighting when the user moves the cursor to another menu item. The MenuSelect function does not highlight disabled menu items.

If the user chooses an enabled menu item (including any item from a submenu), the MenuSelect function returns a value as its function result that indicates which menu and menu item the user chose. The high-order word of the function result contains the menu ID of the menu, and the low-order word contains the item number of the menu item chosen by the user. The MenuSelect function leaves the menu title highlighted; after performing the chosen task your application should unhighlight the menu title using the HiliteMenu procedure.

If the user chooses an item from a submenu, MenuSelect returns the menu ID of the submenu in the high-order word and the item chosen by the user in the low-order word of its function result. The MenuSelect function also highlights the title of the menu in the menu bar that the user originally displayed in order to begin traversing to the submenu. After performing the chosen task, your application should unhighlight the menu title.

If the user releases the mouse button while the cursor is over a disabled item, in the menu bar, or outside of any menu, the MenuSelect function returns 0 in the high-order word of its function result and the low-order word is undefined. If it is necessary for your application to find the item number of the disabled item, your application can call MenuChoice to return the menu ID and menu item.

If the user chooses an enabled item in a menu that a desk accessory has inserted into your application's menu list, MenuSelect uses the SystemMenu procedure to process this occurrence and returns 0 to your application in the high-order word.

SPECIAL CONSIDERATIONS

When the MenuSelect function pulls down a menu, it stores the bits behind the menu as a relocatable object in the application heap of your application.

ASSEMBLY-LANGUAGE INFORMATION

The InitMenus and InitProcMenu procedures initialize the MenuHook and MBarHook global variables to 0. If you choose, you can store the addresses of routines that MenuSelect calls in these global variables. The MenuHook global variable contains the address (if any) of a routine that MenuSelect calls repeatedly while the mouse button is down. MenuSelect does not pass any parameters to this routine.

The MBarHook global variable contains the address (if any) of a routine that MenuSelect calls after a menu title is highlighted and the menu rectangle is calculated but before the menu is drawn. The menu rectangle is the rectangle (in global coordinates) in which the menu will be drawn. MenuSelect passes a pointer to the menu rectangle on the stack. If you provide the address of a routine in the MBarHook global variable, it should normally return 0 in the D0 register, indicating that MenuSelect should continue; returning 1 causes MenuSelect to cancel its operation and return immediately to the application.

The MenuSelect function uses the global variable MBarEnable to determine if all menus in the current menu bar belong to a desk accessory or an application. If the MBarEnable global variable is nonzero, then all menus in the current menu bar belong to a desk accessory. If the MBarEnable global variable is 0, then all menus in the current menu bar belong to an application. If you're writing a desk accessory, you may need to set the MBarEnable global variable to a nonzero value; if you're writing an application, you should not change the value of the MBarEnable global variable.

The global variable TheMenu contains the ID of the currently highlighted menu in the menu bar. If the user chooses an item from a submenu, TheMenu contains the menu ID of the submenu, not the menu to which the submenu is attached.

SEE ALSO

For information on adjusting your application's menus before calling MenuSelect, see "Adjusting the Menus of an Application" beginning on page 3-73.

See the description of the HiliteMenu procedure on page 3-121 for details on how to unhighlight a menu. For information on how to determine if the user chose a disabled item, see the description of the MenuChoice function on page 3-120.