Función TrackPopupMenu (winuser.h)

Artículo
08/28/2023

Muestra un menú contextual en la ubicación especificada y realiza un seguimiento de la selección de elementos en el menú. El menú contextual puede aparecer en cualquier parte de la pantalla.

Sintaxis

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
);

Parámetros

[in] hMenu

Tipo: HMENU

Identificador del menú contextual que se va a mostrar. El identificador se puede obtener llamando a CreatePopupMenu para crear un nuevo menú contextual o llamando a GetSubMenu para recuperar un identificador a un submenú asociado a un elemento de menú existente.

[in] uFlags

Tipo: UINT

Use cero de más de estas marcas para especificar las opciones de función.

Use una de las siguientes marcas para especificar cómo la función coloca horizontalmente el menú contextual.

Value	Significado
TPM_CENTERALIGN 0x0004L	Centra el menú contextual horizontalmente en relación con la coordenada especificada por el parámetro x .
TPM_LEFTALIGN 0x0000L	Coloca el menú contextual para que su lado izquierdo esté alineado con la coordenada especificada por el parámetro x .
TPM_RIGHTALIGN 0x0008L	Coloca el menú contextual para que su lado derecho esté alineado con la coordenada especificada por el parámetro x .

Use una de las siguientes marcas para especificar cómo la función coloca verticalmente el menú contextual.

Value	Significado
TPM_BOTTOMALIGN 0x0020L	Coloca el menú contextual para que su lado inferior esté alineado con la coordenada especificada por el parámetro y .
TPM_TOPALIGN 0x0000L	Coloca el menú contextual para que su lado superior esté alineado con la coordenada especificada por el parámetro y .
TPM_VCENTERALIGN 0x0010L	Centra verticalmente el menú contextual en relación con la coordenada especificada por el parámetro y .

Use las marcas siguientes para controlar la detección de la selección de usuario sin tener que configurar una ventana primaria para el menú.

Value	Significado
TPM_NONOTIFY 0x0080L	La función no envía mensajes de notificación cuando el usuario hace clic en un elemento de menú.
TPM_RETURNCMD 0x0100L	La función devuelve el identificador de elemento de menú de la selección del usuario en el valor devuelto.

Use una de las marcas siguientes para especificar qué botón del mouse realiza el seguimiento del menú contextual.

Value	Significado
TPM_LEFTBUTTON 0x0000L	El usuario puede seleccionar elementos de menú con solo el botón izquierdo del mouse.
TPM_RIGHTBUTTON 0x0002L	El usuario puede seleccionar elementos de menú con los botones izquierdo y derecho del mouse.

Use cualquier combinación razonable de las marcas siguientes para modificar la animación de un menú. Por ejemplo, si selecciona una marca horizontal y vertical, puede lograr una animación diagonal.

Value	Significado
TPM_HORNEGANIMATION 0x0800L	Anima el menú de derecha a izquierda.
TPM_HORPOSANIMATION 0x0400L	Anima el menú de izquierda a derecha.
TPM_NOANIMATION 0x4000L	Muestra el menú sin animación.
TPM_VERNEGANIMATION 0x2000L	Anima el menú de abajo a arriba.
TPM_VERPOSANIMATION 0x1000L	Anima el menú de arriba abajo.

Para que se produzca cualquier animación, la función SystemParametersInfo debe establecer SPI_SETMENUANIMATION. Además, todas las marcas TPM_*ANIMATION, excepto TPM_NOANIMATION, se omiten si la animación de atenuación del menú está activada. Para obtener más información, vea la marca SPI_GETMENUFADE en SystemParametersInfo.

Use la marca TPM_RECURSE para mostrar un menú cuando ya se muestre otro menú. Esto está pensado para admitir menús contextuales dentro de un menú.

Para el diseño de texto de derecha a izquierda, use TPM_LAYOUTRTL. De forma predeterminada, el diseño de texto es de izquierda a derecha.

[in] x

Tipo: int

Ubicación horizontal del menú contextual, en coordenadas de pantalla.

[in] y

Tipo: int

Ubicación vertical del menú contextual, en coordenadas de pantalla.

[in] nReserved

Tipo: int

Reservados; debe ser cero.

[in] hWnd

Tipo: HWND

Identificador de la ventana que posee el menú contextual. Esta ventana recibe todos los mensajes del menú. La ventana no recibe un mensaje de WM_COMMAND desde el menú hasta que la función devuelve. Si especifica TPM_NONOTIFY en el parámetro uFlags , la función no envía mensajes a la ventana identificada por hWnd. Sin embargo, todavía debe pasar un identificador de ventana en hWnd. Puede ser cualquier identificador de ventana de la aplicación.

[in, optional] prcRect

Tipo: const RECT*

ignorado.

Valor devuelto

Tipo: BOOL

Si especifica TPM_RETURNCMD en el parámetro uFlags , el valor devuelto es el identificador de elemento de menú del elemento seleccionado por el usuario. Si el usuario cancela el menú sin realizar una selección, o si se produce un error, el valor devuelto es cero.

Si no especifica TPM_RETURNCMD en el parámetro uFlags , el valor devuelto es distinto de cero si la función se ejecuta correctamente y cero si se produce un error. Para obtener información de error extendida, llame a GetLastError.

Comentarios

Llame a GetSystemMetrics con SM_MENUDROPALIGNMENT para determinar la marca de alineación horizontal correcta (TPM_LEFTALIGN o TPM_RIGHTALIGN) o la marca de dirección de animación horizontal (TPM_HORPOSANIMATION o TPM_HORNEGANIMATION) para pasar a TrackPopupMenu o TrackPopupMenuEx. Esto es esencial para crear una experiencia de usuario óptima, especialmente al desarrollar aplicaciones de PC de Microsoft Tablet.

Para especificar un área de la pantalla que el menú no debe superponerse, use la función TrackPopupMenuEx .

Para mostrar un menú contextual para un icono de notificación, la ventana actual debe ser la ventana en primer plano antes de que la aplicación llame a TrackPopupMenu o TrackPopupMenuEx. De lo contrario, el menú no desaparecerá cuando el usuario haga clic fuera del menú o la ventana que creó el menú (si está visible). Si la ventana actual es una ventana secundaria, debe establecer la ventana primaria (de nivel superior) como la ventana de primer plano.

Sin embargo, cuando la ventana actual es la ventana de primer plano, se muestra la segunda vez que se muestra este menú, aparece y, a continuación, desaparece inmediatamente. Para corregir esto, debe forzar un modificador de tarea a la aplicación que llamó TrackPopupMenu. Esto se hace publicando un mensaje benigno en la ventana o el subproceso, como se muestra en el ejemplo de código siguiente:


   SetForegroundWindow(hDlg);

   // Display the menu
   TrackPopupMenu(   hSubMenu,
                     TPM_RIGHTBUTTON,
                     pt.x,
                     pt.y,
                     0,
                     hDlg,
                     NULL);

   PostMessage(hDlg, WM_NULL, 0, 0);

Ejemplos

Para obtener un ejemplo, vea Mostrar un menú contextual.

Requisitos


Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winuser.h (incluir Windows.h)
Library	User32.lib
Archivo DLL	User32.dll
Conjunto de API	ext-ms-win-ntuser-menu-l1-1-0 (introducido en Windows 8)