Función InsertMenuW (winuser.h)

Artículo
08/27/2023

Inserta un nuevo elemento de menú en un menú y mueve otros elementos hacia abajo en el menú.

Nota La función InsertMenu se ha reemplazado por la función InsertMenuItem . Sin embargo, puede usar InsertMenu si no necesita ninguna de las características extendidas de InsertMenuItem.

Sintaxis

BOOL InsertMenuW(
  [in]           HMENU    hMenu,
  [in]           UINT     uPosition,
  [in]           UINT     uFlags,
  [in]           UINT_PTR uIDNewItem,
  [in, optional] LPCWSTR  lpNewItem
);

Parámetros

[in] hMenu

Tipo: HMENU

Identificador del menú que se va a cambiar.

[in] uPosition

Tipo: UINT

Elemento de menú antes del cual se va a insertar el nuevo elemento de menú, determinado por el parámetro uFlags .

[in] uFlags

Tipo: UINT

Controla la interpretación del parámetro uPosition y el contenido, la apariencia y el comportamiento del nuevo elemento de menú. Este parámetro debe incluir uno de los siguientes valores obligatorios.

Value	Significado
MF_BYCOMMAND 0x00000000L	Indica que el parámetro uPosition proporciona el identificador del elemento de menú. La marca MF_BYCOMMAND es el valor predeterminado si no se especifica la marca MF_BYCOMMAND ni MF_BYPOSITION .
MF_BYPOSITION 0x00000400L	Indica que el parámetro uPosition proporciona la posición relativa de base cero del nuevo elemento de menú. Si uPosition es -1, el nuevo elemento de menú se anexa al final del menú.

El parámetro también debe incluir al menos uno de los valores siguientes.

Value	Significado
MF_BITMAP 0x00000004L	Usa un mapa de bits como elemento de menú. El parámetro lpNewItem contiene un identificador para el mapa de bits.
MF_CHECKED 0x00000008L	Coloca una marca de verificación junto al elemento de menú. Si la aplicación proporciona mapas de bits de marca de verificación (vea SetMenuItemBitmaps), esta marca muestra el mapa de bits de marca de verificación junto al elemento de menú.
MF_DISABLED 0x00000002L	Deshabilita el elemento de menú para que no se pueda seleccionar, pero no lo gris.
MF_ENABLED 0x00000000L	Habilita el elemento de menú para que se pueda seleccionar y restaurar a partir de su estado atenuado.
MF_GRAYED 0x00000001L	Deshabilita el elemento de menú y lo grisiza para que no se pueda seleccionar.
MF_MENUBARBREAK 0x00000020L	Funciona igual que la marca MF_MENUBREAK para una barra de menús. Para un menú desplegable, submenú o menú contextual, la nueva columna se separa de la columna antigua mediante una línea vertical.
MF_MENUBREAK 0x00000040L	Coloca el elemento en una nueva línea (para barras de menús) o en una nueva columna (para un menú desplegable, submenú o menú contextual) sin separar las columnas.
MF_OWNERDRAW 0x00000100L	Especifica que el elemento es un elemento dibujado por el propietario. Antes de que el menú se muestre por primera vez, la ventana propietaria del menú recibe un mensaje de WM_MEASUREITEM para recuperar el ancho y el alto del elemento de menú. A continuación, el mensaje de WM_DRAWITEM se envía al procedimiento de ventana de la ventana del propietario cada vez que se debe actualizar la apariencia del elemento de menú.
MF_POPUP 0x00000010L	Especifica que el elemento de menú abre un menú desplegable o submenú. El parámetro uIDNewItem especifica un identificador para el menú desplegable o submenú. Esta marca se usa para agregar un nombre de menú a una barra de menús o un elemento de menú que abre un submenú en un menú desplegable, submenú o menú contextual.
MF_SEPARATOR 0x00000800L	Dibuja una línea divisoria horizontal. Esta marca solo se usa en un menú desplegable, submenú o menú contextual. La línea no puede estar atenuada, deshabilitada o resaltada. Se omiten los parámetros lpNewItem y uIDNewItem .
MF_STRING 0x00000000L	Especifica que el elemento de menú es una cadena de texto; El parámetro lpNewItem es un puntero a la cadena.
MF_UNCHECKED 0x00000000L	No coloca una marca de verificación junto al elemento de menú (valor predeterminado). Si la aplicación proporciona mapas de bits de marca de verificación (vea la función SetMenuItemBitmaps ), esta marca muestra el mapa de bits sin borrar junto al elemento de menú.

[in] uIDNewItem

Tipo: UINT_PTR

Identificador del nuevo elemento de menú o, si el parámetro uFlags tiene establecido la marca MF_POPUP , un identificador en el menú desplegable o submenú.

[in, optional] lpNewItem

Tipo: LPCTSTR

Contenido del nuevo elemento de menú. La interpretación de lpNewItem depende de si el parámetro uFlags incluye la marca MF_BITMAP, MF_OWNERDRAW o MF_STRING , como se indica a continuación.

Value	Significado
MF_BITMAP 0x00000004L	Contiene un identificador de mapa de bits.
MF_OWNERDRAW 0x00000100L	Contiene un valor proporcionado por la aplicación que se puede usar para mantener datos adicionales relacionados con el elemento de menú. El valor está en el miembro itemData de la estructura a la que apunta el parámetro lParam del WM_MEASUREITEM o WM_DRAWITEM mensaje enviado cuando se crea el elemento de menú o se actualiza su apariencia.
MF_STRING 0x00000000L	Contiene un puntero a una cadena terminada en null (valor predeterminado).

Valor devuelto

Tipo: BOOL

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

La aplicación debe llamar a la función DrawMenuBar siempre que cambie un menú, si el menú está en una ventana mostrada.

Los siguientes grupos de marcas no se pueden usar juntos:

MF_BYCOMMAND y MF_BYPOSITION
MF_DISABLED, MF_ENABLED y MF_GRAYED
MF_BITMAP, MF_STRING, MF_OWNERDRAW y MF_SEPARATOR
MF_MENUBARBREAK y MF_MENUBREAK
MF_CHECKED y MF_UNCHECKED

Nota

El encabezado winuser.h define InsertMenu como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

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)