TrackPopupMenu function (winuser.h)
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.
Syntax
BOOL TrackPopupMenu(
[in] HMENU hMenu,
[in] UINT uFlags,
[in] int x,
[in] int y,
[in] int nReserved,
[in] HWND hWnd,
[in, optional] const RECT *prcRect
);
Parameters
[in] hMenu
Type: HMENU
A 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 a handle to a submenu associated with an existing menu item.
[in] uFlags
Type: UINT
Use zero of more of these flags to specify function options.
Use one of the following flags to specify how the function positions the shortcut menu horizontally.
Use one of the following flags to specify how the function positions the shortcut menu vertically.
Use the following flags to control discovery of the user selection without having to set up a parent window for the menu.
Use one of the following flags to specify which mouse button the shortcut menu tracks.
| Value | Meaning |
|---|---|
|
The user can select menu items with only the left mouse button. |
|
The user can select menu items with both the left and right mouse buttons. |
Use any reasonable combination of the following flags to modify the animation of a menu. For example, by selecting a horizontal and a vertical flag, you can achieve diagonal animation.
For any animation to occur, the SystemParametersInfo function must set SPI_SETMENUANIMATION. Also, all the TPM_*ANIMATION flags, except TPM_NOANIMATION, are ignored if menu fade animation is on. For more information, see the SPI_GETMENUFADE flag in SystemParametersInfo.
Use the TPM_RECURSE flag to display a menu when another menu is already displayed. This is intended to support context menus within a menu.
For right-to-left text layout, use TPM_LAYOUTRTL. By default, the text layout is left-to-right.
[in] x
Type: int
The horizontal location of the shortcut menu, in screen coordinates.
[in] y
Type: int
The vertical location of the shortcut menu, in screen coordinates.
[in] nReserved
Type: int
Reserved; must be zero.
[in] hWnd
Type: HWND
A 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.
[in, optional] prcRect
Type: const RECT*
Ignored.
Return value
Type: BOOL
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, 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
Call GetSystemMetrics with SM_MENUDROPALIGNMENT to determine the correct horizontal alignment flag (TPM_LEFTALIGN or TPM_RIGHTALIGN) and/or horizontal animation direction flag (TPM_HORPOSANIMATION or TPM_HORNEGANIMATION) to pass to TrackPopupMenu or TrackPopupMenuEx. This is essential for creating an optimal user experience, especially when developing Microsoft Tablet PC applications.
To specify an area of the screen that the menu should not overlap, use the TrackPopupMenuEx function
To display a context menu for a notification icon, the current window must be the foreground window before the application calls TrackPopupMenu or TrackPopupMenuEx. Otherwise, the menu will not disappear when the user clicks outside of the menu or the window that created the menu (if it is visible). If the current window is a child window, you must set the (top-level) parent window as the foreground window.
However, when the current window is the foreground window, the second time this menu is displayed, it appears and then immediately disappears. To correct this, you must force a task switch to the application that called TrackPopupMenu. This is done by posting a benign message to the window or thread, as shown in the following code sample:
SetForegroundWindow(hDlg);
// Display the menu
TrackPopupMenu( hSubMenu,
TPM_RIGHTBUTTON,
pt.x,
pt.y,
0,
hDlg,
NULL);
PostMessage(hDlg, WM_NULL, 0, 0);
Examples
For an example, see Displaying a Shortcut Menu.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | winuser.h (include Windows.h) |
| Library | User32.lib |
| DLL | User32.dll |
| API set | ext-ms-win-ntuser-menu-l1-1-0 (introduced in Windows 8) |
See also
Conceptual
Reference