TrackPopupMenu

The TrackPopupMenu function displays a shortcut menu at the specified location and tracks the selection of items on the menu. The shortcut menu can appear anywhere on the screen.

BOOL TrackPopupMenu(
  HMENU hMenu,         // handle to shortcut menu
  UINT uFlags,         // screen-position and mouse-button flags
  int x,               // horizontal position, in screen coordinates
  int y,               // vertical position, in screen coordinates
  int nReserved,       // reserved, must be zero
  HWND hWnd,           // handle to owner window
  CONST RECT *prcRect  // ignored
);
 

Parameters

hMenu

Handle to the shortcut menu to be displayed. The handle can be obtained by calling CreatePopupMenu to create a new shortcut menu, or by calling GetSubMenu to retrieve the handle to a submenu associated with an existing menu item.

uFlags

A set of bit flags that specify function options.

Use one of the following bit flag constants to specify how the function positions the shortcut menu horizontally.

Value	Meaning
TPM_CENTERALIGN	If this flag is set, the function centers the shortcut menu horizontally relative to the coordinate specified by the x parameter.
TPM_LEFTALIGN	If this flag is set, the function positions the shortcut menu so that its left side is aligned with the coordinate specified by the x parameter.
TPM_RIGHTALIGN	Positions the shortcut menu so that its right side is aligned with the coordinate specified by the x parameter.

Use one of the following bit flag constants to specify how the function positions the shortcut menu vertically.

Value	Meaning
TPM_BOTTOMALIGN	If this flag is set, the function positions the shortcut menu so that its bottom side is aligned with the coordinate specified by the y parameter.
TPM_TOPALIGN	If this flag is set, the function positions the shortcut menu so that its top side is aligned with the coordinate specified by the y parameter.
TPM_VCENTERALIGN	If this flag is set, the function centers the shortcut menu vertically relative to the coordinate specified by the y parameter.

Use the following bit flag constants to determine the user selection without having to set up a parent window for the menu.

Value	Meaning
TPM_NONOTIFY	If this flag is set, the function does not send notification messages when the user clicks on a menu item.
TPM_RETURNCMD	If this flag is set, the function returns the menu item identifier of the user's selection in the return value.

Use one of the following bit flag constants to specify which mouse button the shortcut menu tracks.

Value	Meaning
TPM_LEFTBUTTON	If this flag is set, the user can select menu items with only the left mouse button.
TPM_RIGHTBUTTON	If this flag is set, the user can select menu items with both the left and right mouse buttons.

x

Specifies the horizontal location of the shortcut menu, in screen coordinates.

y

Specifies the vertical location of the shortcut menu, in screen coordinates.

nReserved

Reserved; must be zero.

hWnd

Handle to the window that owns the shortcut menu. This window receives all messages from the menu. The window does not receive a WM_COMMAND message from the menu until the function returns.

If you specify TPM_NONOTIFY in the uFlags parameter, the function does not send messages to the window identified by hWnd. However, you must still pass a window handle in hWnd. It can be any window handle from your application.

prcRect

Ignored.

Return Values

If you specify TPM_RETURNCMD in the uFlags parameter, the return value is the menu-item identifier of the item that the user selected. If the user cancels the menu without making a selection, or if an error occurs, then the return value is zero.

If you do not specify TPM_RETURNCMD in the uFlags parameter, the return value is nonzero if the function succeeds and zero if it fails. To get extended error information, call GetLastError.

Remarks

Windows CE: Windows CE does not support the following flags for the uFlags parameter:

TPM_NONOTIFY

TPM_LEFTBUTTON

TPM_RIGHTBUTTON

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Requires version 1.0 or later.
  Header: Declared in winuser.h.
  Import Library: Use user32.lib.

See Also

Menus Overview, Menu Functions, CreatePopupMenu, GetSubMenu, RECT, WM_COMMAND