TrackPopupMenu

3.0

  BOOL TrackPopupMenu(hmenu, fuFlags, x, y, nReserved, hwnd, lprc)    
  HMENU hmenu; /* handle of menu, */  
  UINT fuFlags; /* screen-position and mouse-button flags */
  int x; /* horizontal screen position, */  
  int y; /* vertical screen position, */  
  int nReserved; /* reserved */
  HWND hwnd; /* handle of owner window */
  const RECT FAR* lprc; /* address of structure with rectangle */

The TrackPopupMenu function displays the given floating pop-up menu at the specified location and tracks the selection of items on the pop-up menu. A floating pop-up menu can appear anywhere on the screen.

Parameters

hmenu

Identifies the pop-up menu to be displayed. The application retrieves this handle by calling the CreatePopupMenu function to create a new pop-up menu or by calling the GetSubMenu function to retrieve the handle of a pop-up menu associated with an existing menu item.

fuFlags

Specifies the screen-position and mouse-button flags. The screen-position flag can be one of the following:

Value Meaning

TPM_CENTERALIGN Centers the pop-up menu horizontally relative to the coordinate specified by the x parameter.
TPM_LEFTALIGN Positions the pop-up menu so that its left side is aligned with the coordinate specified by the x parameter.
TPM_RIGHTALIGN Positions the pop-up menu so that its right side is aligned with the coordinate specified by the x parameter.

The mouse-button flag can be one of the following:

Value Meaning

TPM_LEFTBUTTON Causes the pop-up menu to track the left mouse button.
TPM_RIGHTBUTTON Causes the pop-up menu to track the right mouse button instead of the left.

x

Specifies the horizontal position, in screen coordinates, of the pop-up menu. Depending on the value of the fuFlags parameter, the menu can be left-aligned, right-aligned, or centered relative to this position.

y

Specifies the vertical position, in screen coordinates, of the top of the menu on the screen.

nReserved

Reserved; must be zero.

hwnd

Identifies the window that owns the pop-up menu. This window receives all WM_COMMAND messages from the menu. The window will not receive WM_COMMAND messages until TrackPopupMenu returns.

lprc

Points to a RECT structure that contains the screen coordinates of a rectangle in which the user can click without dismissing the pop-up menu. If this parameter is NULL, the pop-up menu is dismissed if the user clicks outside the pop-up menu. The RECT structure has the following form:

typedef struct tagRECT {    /* rc */
   int left;
   int top;
   int right;
   int bottom;
} RECT;

For a full description of this structure, see the Microsoft Windows Programmer's Reference, Volume 3.

Return Value

The return value is nonzero if the function is successful. Otherwise, it is zero.

Example

The following example creates and tracks a pop-up menu when the user clicks the left mouse button:

POINT ptCurrent;
HMENU hmenu;

ptCurrent = MAKEPOINT(lParam);
hmenu = CreatePopupMenu();
AppendMenu(hmenu, MF_ENABLED, IDM_ELLIPSE, "Ellipse");
AppendMenu(hmenu, MF_ENABLED, IDM_SQUARE, "Square");
AppendMenu(hmenu, MF_ENABLED, IDM_TRIANGLE, "Triangle");
ClientToScreen(hwnd, &ptCurrent);
TrackPopupMenu(hmenu, TPM_LEFTALIGN, ptCurrent.x,
    ptCurrent.y, 0, hwnd, NULL);

See Also

CreatePopupMenu, GetSubMenu