Win32 API Functions

Microsoft Documentation

MSDN > Documentation > Windows > API Reference > Win32 > Functions > User > TrackPopupMenu

TrackPopupMenu Function

The TrackPopupMenu function displays a shortcut menu at the specified location and enables the user to select an item from the menu.

Syntax

BOOL TrackPopupMenu(
      [in]           HMENU hMenu,
      [in]           UINT  uFlags,
      [in]           int   x,
      [in]           int   y,
      [in]           int   nReserved,
      [in]    const  HWND  hWnd,
      [in, out, optional]  RECT  *prcExclude
    );

Parameters

Parameter Description
hMenu Handle to the menu to be displayed. This handle can be obtained by calling the CreatePopupMenu function.
uFlags Flags that control the display of the menu. This parameter can be a combination of the following values:
  • TPM_CENTERALIGN: Centers the menu horizontally relative to the current cursor position.
  • TPM_LEFTALIGN: Aligns the left side of the menu with the current cursor position.
  • TPM_RIGHTALIGN: Aligns the right side of the menu with the current cursor position.
  • TPM_TOPALIGN: Aligns the top of the menu with the current cursor position.
  • TPM_VCENTERALIGN: Centers the menu vertically relative to the current cursor position.
  • TPM_BOTTOMALIGN: Aligns the bottom of the menu with the current cursor position.
  • TPM_VERPOSANIMATION: Animates the menu vertically using a slide-in effect from top to bottom.
  • TPM_WORKAREA: Use the screen coordinates of the work area.
x The horizontal screen coordinate for the display of the menu.
y The vertical screen coordinate for the display of the menu.
nReserved Reserved; must be zero.
hWnd Handle to the window that owns the shortcut menu. This parameter is required for TPM_RETURNCMD.
prcExclude Pointer to a RECT structure that specifies the screen region that the menu should not overlap. This parameter is used only if TPM_EXCLUDESIZE is specified in uFlags.

Return Value

If the function succeeds, it returns the identifier of the menu item selected by the user. If the function fails (e.g., because the menu is invalid or the user cancels the menu without selecting an item), it returns zero.

Remarks

The TrackPopupMenu function is a convenience function that simplifies the process of tracking shortcut menus.

When tracking a menu, the system sends the WM_COMMAND or WM_SYSCOMMAND message to the owner window when the user selects an item.

When passing a menu handle obtained from CreatePopupMenu, you should call DestroyMenu to free the menu's resources after the menu is no longer needed.
Ensure that the hWnd parameter is valid and points to a visible window if you intend to receive menu command notifications.

Example Usage

// Assuming hWnd is a valid window handle and hMenu is a valid HMENU
            // Display the menu at the current mouse cursor position
            POINT pt;
            GetCursorPos(&pt);

            UINT uFlags = TPM_LEFTALIGN | TPM_TOPALIGN | TPM_VERPOSANIMATION | TPM_WORKAREA;

            int commandId = TrackPopupMenu(hMenu, uFlags, pt.x, pt.y, 0, hWnd, NULL);

            if (commandId == 0) {
                // Menu tracking failed or user canceled
            } else {
                // Process the commandId
                // For example:
                // switch(commandId) {
                //     case IDM_OPTION1: ... break;
                //     case IDM_OPTION2: ... break;
                // }
            }

See Also