InsertMenu
La función InsertMenu inserta un nuevo ítem de menú dentro de un menú, moviendo los otros ítems hacia abajo en el menú.
La función InsertMenu ha sido sustituida por la función InsertMenuItem. De todos modos, se puede seguir usando InsertMenu, si no se necesitan las características extendidas de InsertMenuItem.
Sintaxis
BOOL InsertMenu(
HMENU hMenu, // manipulador de menú
UINT uPosition, // ítem de menú al que el nuevo ítem precederá
UINT uFlags, // flags del ítem de menú
UINT uIDNewItem, // identificador de ítem de menú o manipulador de menú pop-up
LPCTSTR lpNewItem // contenido del ítem de menú
);
Parámetros:
hMenu: identifica el menú a modificar.
uPosition: indica el ítem de menú delante del cual se insertará el nuevo, tal como se determine por el parámetro uFlags.
uFlags: especifica las banderas para controlar la interpretación del parámetro yPosition y el contenido, apariencia y el comportamiento del ítem de menú. Este parámetro puede ser una combinación de uno de los valores requeridos siguientes y por lo menos uno de los valores listados en la sección de observaciones.
| Valor | Descripción |
|---|---|
| MF_BYCOMMAND | Indica que el parámetro uPosition toma el identificador del ítem de menú. La bandera MF_BYCOMMAND es el valor por defecto si no se indica ni MF_BYCOMMAND ni MF_BYPOSITION. |
| MF_BYPOSITION | Indica que el parámetro uPosition toma la posición relativa, basada en cero del nuevo ítem de menú. Si uPosition es 0xFFFFFFFF, el nuevo ítem se añadirá al final del menú. |
uIDNewItem: especifica o bien el identificador del nuevo ítem de menú o si el parámetro uFlags incluye MF_POPUP, el manipulador de un menú pop-up.
lpNewItem: especifica el contenido del nuevo ítem de menú. La interpretación de lpNewItem depende de si el parámetro uFlags incluye las banderas MF_BITMAP, MF_OWNERDRAW o MF_STRING, como se especifica a continuación:
| Valor | Descripción |
|---|---|
| MF_BITMAP | Contiene un manipulador de mapa de bits. |
| MF_OWNERDRAW | Contiene un valor de 32 bits suministrado por la aplicación que puede ser usado para mantener datos adicionales relacionados con el ítem de menú. El valor esta en el miembro itemData de la estructura apuntada por el parámetro lparam del mensaje WM_MEASUREITEM o WM_DRAWITEM enviado cuando el menú es creado o su apariencia es actualizada. |
| MF_STRING | Contiene un puntero a una cadena de caracteres terminada con cero. |
Valor de retorno
Si la función tiene éxito, el valor de retorno es TRUE.
Si falla, el valor de retorno es FALSE. Para conseguir más información, se puede llamar a GetLastError.
Observaciones
La aplicación debe llamar a la función DrawMenuBar cada vez que el menú cambie, tanto si el menú pertenece a una ventana que se está mostrando como si no.
Las siguientes banderas pueden ser usadas en el parámetro uFlags:
| Valor | Descripción |
|---|---|
| MF_BITMAP | Usa un mapa de bitsp como ítem. El parámetro lpNewItem contiene el manipulador del mapa de bits. |
| MF_CHECKED | Pone una marca de comprobación junto al ítem. Si la aplicación proporciona los mapas de bits de las marcas de comprobación (SetMenuItemBitmaps), esta bandera muestra la marca junto al ítem de menú. |
| MF_DISABLED | Inhibe el ítem de menú de modo que no puede ser seleccionado, pero esta bandera no oscurece el ítem. |
| MF_ENABLED | Habilita en ítem de menú de modo que pueda ser seleccionado y restaura su apariencia si su estado estaba oscurecido. |
| MF_GRAYED | Inhibe el ítem y lo oscurece de modo que no puede ser seleccionado. |
| MF_MENUBARBREAK | Funciona igual que el flag MF_MENUBREAK excepto para menús emergentes, donde la nueva columna es separada de la anterior por una línea vertical. |
| MF_MENUBREAK | Coloca el ítem en una línea nueva (para barras de menú) o en una columna nueva (para menús emergentes) sin columnas separadoras. |
| MF_OWNERDRAW | Especifica que el ítem es dibujado por la ventana propietaria, (owner-drawn). Antes de que el menú sea mostrado por primera vez, la ventana que posee el menú recibirá un mensaje WM_MEASUREITEM para recuperar la anchura y altura del ítem de menú. El mensaje WM_DRAWITEM es enviado al procedimiento de ventana de la ventana propietaria cada vez que la apariencia del ítem deba ser actualizada. |
| MF_POPUP | Indica que el ítem abre un menú emergente o submenú. El parámetro uIDNewItem especifica el manipulador del menú emergente o submenú. La bandera se usa para añadir un ítem pop-up a una barra de menú o a un menú emergente. |
| MF_SEPARATOR | Dibuja una línea horizontal de división. Esta bandera se usa sólo en menús emergentes. La línea no puede ser oscurecida, inhibida o resaltada. Los parámetros lpNewItem y uIDNewItem se ignoran. |
| MF_STRING | Especifica que el ítem es una cadena de texto; el parámetro lpNewItem apunta a una cadena. |
| MF_UNCHECKED | No pone la marca de comprobación junto al ítem (valor por defecto). Si la aplicación suministra mapas de bits para las marcas de comprobación (ver SetMenuItemBitmaps), esta bandera muestra el mapa de bits de no comprobación junto al ítem. |
La lista siguiente muestra grupos de banderas que no pueden ser usados 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