All Databases Inside Mac - Basic Toolbox

PopUpMenuSelect

Pop up a menu and initiate user selection of a menu item

#include <Menus.h> Menu Manager

long PopUpMenuSelect(theMenu, top,left, popUpItem );

MenuHandle theMenu ; handle of menu containing item to modify

short top ; vertical position ( global coordinates)

short left ; horizontal position (global coordinates)

short popUpItem ; ID of item to align with top

returns HiWord is menu ID or 0; LoWord is item number

PopUpMenuSelect displays a popup menu at the specified coordinates and

interacts with the user until the mouse button is released. It returns the IDs

of the menu and item selected.

theMenu is a handle leading to a variable-length MenuInfo structure. It is a

value obtained via NewMenu or GetMenu. It identifies the menu

containing the item to modify.

top and...

left are global coordinates which identify where to display the menu. It

is typically the topleft corner of a "popup box" (a rectangle with a

one-pixel drop shadow) that surrounds the point of a recent

mouseDown, as obtained via GetNextEvent.

Note that the menu will be aligned with popUpItem so it may extend

above, as well as below, the "popup box".

popUpItem identifies which item in theMenu to display at top and left. You will

normally use the item ID of the "current selection" (popup menus

typically display a list from which the user may choose; the idea is

that the current selection is displayed in the popup box and gets

overwritten with that same text when the menu is displayed).

A value of 1 specifies aligning the top menu item with top and left.

Returns: a 32-bit long that indicates the selected menu and item. It is made

up of two values as follows:

High Word menu ID of selection (0 means none)

Low Word item number of selection

Notes: PopUpMenuSelect is used to display menus that have been inserted into

the hierarchical portion of the menu list; i.e., they have been set into the

menu list via InsMenuItem or AppendMenu, using a beforeID of

hierMenu (-1).

Most often, popup menus are inserted into the menu directly before calling

PopUpMenuSelect and deleted immediately afterwards:

/* -- mouseDown event in myPopUpBox --- */

InvertRect( myPopUpTitleRect ); /* Hilight your popup title area */

InsertMenu( myPopUpMenuHandle, hierMenu );

mresult = PopUpMenuSelect( myPopUpMenuHandle,

myPopUpRect.top, myPopUpRect.left,

lastItemSelected );

DeleteMenu( myPopUpMenuID );

InvertRect( myPopUpTitleRect ); /* UnHilight your popup title area */

if ( HiWord(mresult ) != 0 ) { /*... some item was selected ...*/ }

The return value is formatted the same as that of MenuSelect and

MenuKey, thus a typical operation just checks the hi word for non-zero

and passes the result to a common "command handler" routine that figures

out what to do.

Since this does not hilite any title in the menu bar, there is no need to call

HiliteMenu(0) after the call; however, doing so won't cause a problem.

If items in a popup menu have command-key equivalents, your application

should provide some visual feed back (such as inverting the popup title

box) when the command key is detected via MenuKey.

About DAs: By convention, menus with negative IDs are owned by DAs.

When one is selected, the return value is sent to the DA and you get a

"cancel" value (the high word is 0).