winuser.h


ModifyMenu

La función ModifyMenu modifica un ítem de menú existente. Esta función se usa para especificar el contenido, apariencia y comportamiento del ítem de menú.

La función ModifyMenu ha sido sustituida por SetMenuItemInfo. De todos modos, se puede seguir usando si no se necesitan las características extendidas de SetMenuItemInfo.

Sintaxis

BOOL ModifyMenu(
    HMENU hMnu,        // manipulador de menú
    UINT uPosition,    // ítem de menú a modificar
    UINT uFlags,       // banderas de ítem de menú
    UINT uIDNewItem,   // identificador de ítem de menú o
                       // manipulador de menú desplegable o submenú
    LPCTSTR lpNewItem  // contenido de ítem de menú 
   );

Parámetros

hMnu: identifica el menú a modificar.

uPosition: especifica el ítem de menú a modificar, tal como lo determine el parámetro uFlags.

uFlags: especifica las banderas que controlan la interpretación del parámetro uPosition y el contenido, apariencia y comportamiento del ítem de menú. Este parámetro debe ser una combinación de uno de los siguientes valores requeridos y al menos uno de los valores listados en la sección de observaciones.

Valor Significado
MF_BYCOMMAND indica que el parámetro uPosition proporciona el identificador del ítem de menú. La bandera MF_BYCOMMAND es el valor por defecto si no se especifica ni MF_BYCOMMAND ni MF_BYPOSITION.
MF_BYPOSITION Indica que el parámetro uPosition proporciona la posición relativa, empezando en cero, del ítem de menú.

uIDNewItem: especifica bien el identificador del ítem de menú modificado o, si el parámetro uFlags tiene la bandera MF_POPUP activa, el manipulador del menú desplegable o submenú.

lpNewItem: apunta al contenido del ítem de menú modificado. La interpretación de este parámetro depende de si el parámetro uFlags incluye las banderas MF_BITMAP, MF_OWNERDRAW o MF_STRING.

Valor Significado
MF_BITMAP Contiene un manipulador de mapa de bits.
MF_OWNERDRAW Contiene un valor de 32 bits suministrado por una aplicación que se usa para mantener datos adicionales relacionados con el ítem de menú. El valor está en el miembro itemData de la estructura apuntada por el parámetro lparam de los mensajes WM_MEASUREITEM o WM_DRAWITEM, enviados cuando el ítem de menú es creado o su apariencia se actualiza.
MF_STRING Contiene un puntero a una cadena terminada en nulo (valor por defecto).

Valor de retorno

Si la función tiene éxito, el valor de retorno es distinto de cero.

Si la función falla, el valor de retorno es cero. Para obtener información adicional sobre el error, llamar a GetLastError.

Observaciones

Si ModifyMenu reemplaza un ítem de menú que abre un menú desplegable o un submenú, la función destruye el menú desplegable o submenú antiguo y libera la memoria usada por él.

La aplicación debe llamar a la función DrawMenuBar cada vez que el menú cambie, tanto si el menú está en una ventana del display como si no. Para cambiar los atributos de ítems de menú existentes, es mucho más rápido usar las funciones CheckMenuItem y EnableMenuItem.

La lista siguiente describe las banderas que pueden ser usadas en el parámetro uFlags:

Valor Descripción
MF_BITMAP Usa un mapa de bits como ítem. El parámetro lpNewItem contiene el manipulador del mapa de bits.
MF_BYCOMMAND Indica que el parámetro uPosition especifica el identificador del ítem de menú (valor por defecto).
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 (ver 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 el í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.