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

PopUpMenuSelect

To display a pop-up menu without using the standard pop-up control definition function, use the PopUpMenuSelect function to display the pop-up menu anywhere
on the screen. If your application uses the standard pop-up control definition function, your application does not need to use PopUpMenuSelect.

FUNCTION PopUpMenuSelect (menu: MenuHandle;
                           Top: Integer; Left: Integer; 
                           PopUpItem: Integer)
                           : LongInt;

menu

A handle to the menu record of the menu. The NewMenu, GetMenu, and GetMenuHandle functions return a handle to a specified menu's menu record.

Top

The top coordinate of the pop-up box when it is closed. This value should be in global coordinates.

Left

The left coordinate of the pop-up box when it is closed. This value should be in global coordinates.

PopUpItem

The item number of the current item minus 1. This value should correspond to the user's previous choice from this menu. If the user has not previously made a choice, this value should be set to the default value.

DESCRIPTION

The PopUpMenuSelect function uses the location specified by the Top and Left parameters to determine where to display the specified item of the pop-up menu. The PopUpMenuSelect function displays the pop-up menu so that the menu item specified in the PopUpItem parameter appears highlighted at the specified location. Figure 3-24 on page 3-34 shows the pop-up title and pop-up box of a pop-up menu.

The PopUpMenuSelect function highlights and unhighlights menu items and handles all user interaction until the user releases the mouse button. The PopUpMenuSelect function returns the menu ID of the chosen menu in the high-order word of its function result and the chosen menu item in the low-order word.

Your application is responsible for highlighting the pop-up title, setting the mark of the current menu item appropriately, and drawing the text and downward-pointing indicator in the pop-up box before calling PopUpMenuSelect. Your application should also make sure the pop-up menu is in the submenu portion of the current menu list before calling PopUpMenuSelect. (You can use the InsertMenu procedure and specify -1 in the beforeID parameter to insert the pop-up menu into the current menu list.) After calling PopUpMenuSelect, your application can delete the pop-up menu from the current menu list or leave it in the current menu list.

Your application is also responsible for storing the current value of the menu item, drawing the text and downward-pointing indicator in the pop-up box, and unhighlighting the pop-up title after calling PopUpMenuSelect. If you use the standard pop-up control definition function, these actions are performed for you by the pop-up control and your application does not need to call PopUpMenuSelect.

When implementing pop-up menus, you should follow the guidelines for pop-up menus described in Macintosh Human Interface Guidelines. For example, you should define the pop-up box of your pop-up menu as a rectangle that is the same height as a menu item, with a one-pixel drop shadow, and should make the pop-up box wide enough to show the currently selected item and a downward-pointing indicator.