Función TrackPopupMenuEx (winuser.h)

Artículo
03/04/2024

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

Sintaxis

BOOL TrackPopupMenuEx(
  [in]           HMENU       hMenu,
  [in]           UINT        uFlags,
  [in]           int         x,
  [in]           int         y,
  [in]           HWND        hwnd,
  [in, optional] LPTPMPARAMS lptpm
);

Parámetros

[in] hMenu

Tipo: HMENU

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

[in] uFlags

Tipo: UINT

Especifica las opciones de función.

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

Valor	Significado
TPM_CENTERALIGN 0x0004L	Centra horizontalmente el menú contextual con respecto a la coordenada especificada por el parámetro x .
TPM_LEFTALIGN 0x0000L	Coloca el menú contextual para que su lado izquierdo se alinee con la coordenada especificada por el parámetro x .
TPM_RIGHTALIGN 0x0008L	Coloca el menú contextual para que su lado derecho se alinee con la coordenada especificada por el parámetro x .

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

Valor	Significado
TPM_BOTTOMALIGN 0x0020L	Coloca el menú contextual para que su lado inferior se alinee con la coordenada especificada por el parámetro y .
TPM_TOPALIGN 0x0000L	Coloca el menú contextual para que su lado superior se alinee con la coordenada especificada por el parámetro y .
TPM_VCENTERALIGN 0x0010L	Centra verticalmente el menú contextual con respecto a 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ú.

Valor	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.

Valor	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.

Utilice 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 la animación diagonal.

Valor	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 a 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ú.

Use una de las marcas siguientes para especificar si se va a dar cabida a la alineación horizontal o vertical.

Valor	Significado
TPM_HORIZONTAL 0x0000L	Si el menú no se puede mostrar en la ubicación especificada sin superponer el rectángulo excluido, el sistema intenta acomodar la alineación horizontal solicitada antes de la alineación vertical solicitada.
TPM_VERTICAL 0x0040L	Si el menú no se puede mostrar en la ubicación especificada sin superponer el rectángulo excluido, el sistema intenta acomodar la alineación vertical solicitada antes de la alineación horizontal solicitada.

El rectángulo excluido es una parte de la pantalla que el menú no debe superponerse; se especifica mediante el parámetro lptpm .

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] 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 se devuelve la función. Si especifica TPM_NONOTIFY en el parámetro fuFlags , la función no envía mensajes a la ventana identificada por hwnd. Sin embargo, debe pasar un identificador de ventana en hwnd. Puede ser cualquier identificador de ventana de la aplicación.

[in, optional] lptpm

Tipo: LPTPMPARAMS

Puntero a una estructura TPMPARAMS que especifica un área de la pantalla que el menú no debe superponerse. Este parámetro puede ser NULL.

Valor devuelto

Tipo: BOOL

Si especifica TPM_RETURNCMD en el parámetro fuFlags , 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 fuFlags , el valor devuelto es distinto de cero si la función se realiza 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 Tableta de Microsoft.

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.

Requisitos

Requisito	Value
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 (incluya Windows.h)
Library	User32.lib
Archivo DLL	User32.dll
Conjunto de API	ext-ms-win-ntuser-menu-l1-1-1 (introducido en Windows 8.1)