Clase `CMenu`

Artículo
06/16/2023

Una encapsulación de HMENUde Windows.

Sintaxis

class CMenu : public CObject

Miembros

Constructores públicos

Nombre	Descripción
`CMenu::CMenu`	Construye un objeto `CMenu`.

Métodos públicos

Nombre	Descripción
`CMenu::AppendMenu`	Anexa un nuevo elemento al final de este menú.
`CMenu::Attach`	Adjunta un manipulador de Windows a un objeto `CMenu`.
`CMenu::CheckMenuItem`	Coloca una marca de verificación al lado a o quita una marca de verificación de un elemento de menú en el menú emergente.
`CMenu::CheckMenuRadioItem`	Coloca un botón de radio junto a un elemento de menú y quita el botón de radio de todos los demás elementos de menú en el grupo.
`CMenu::CreateMenu`	Crea un menú vacío y lo adjunta a un objeto `CMenu`.
`CMenu::CreatePopupMenu`	Crea un menú emergente vacío y lo adjunta a un objeto `CMenu`.
`CMenu::DeleteMenu`	Elimina un elemento especificado del menú. Si el elemento de menú tiene un menú emergente asociado, destruye el manipulador en el menú emergente y libera la memoria usada por él.
`CMenu::DeleteTempMap`	Elimina los objetos temporales `CMenu` creados por la función miembro `FromHandle`.
`CMenu::DestroyMenu`	Destruye el menú adjunto a un objeto `CMenu` y libera cualquier memoria que ocupe el menú.
`CMenu::Detach`	Desasocia un manipulador de Windows de un objeto `CMenu` y devuelve el manipulador.
`CMenu::DrawItem`	La llama el marco cuando cambia un aspecto visual de un menú dibujado por el propietario.
`CMenu::EnableMenuItem`	Habilita, deshabilita o atenúa (en color gris) un elemento de menú.
`CMenu::FromHandle`	Devuelve un puntero a un objeto `CMenu` cuando se proporciona un manipulador de Windows.
`CMenu::GetDefaultItem`	Determina el elemento de menú predeterminado en el menú especificado.
`CMenu::GetMenuContextHelpId`	Recupera el id. de contexto de ayuda asociado al menú.
`CMenu::GetMenuInfo`	Recupera información en un menú específico.
`CMenu::GetMenuItemCount`	Determina el número de elementos de un menú emergente o de nivel superior.
`CMenu::GetMenuItemID`	Obtiene el identificador de elemento de menú ubicado en la posición especificada.
`CMenu::GetMenuItemInfo`	Recupera información sobre un elemento de menú.
`CMenu::GetMenuState`	Devuelve el estado del elemento de menú especificado o el número de elementos de un menú emergente.
`CMenu::GetMenuString`	Recupera la etiqueta del elemento de menú especificado.
`CMenu::GetSafeHmenu`	Devuelve el `m_hMenu` contenido por este objeto `CMenu`.
`CMenu::GetSubMenu`	Recupera un puntero a un menú emergente.
`CMenu::InsertMenu`	Inserta un nuevo elemento de menú en la posición especificada, al mover otros elementos hacia abajo del menú.
`CMenu::InsertMenuItem`	Inserta un nuevo elemento de menú en la posición especificada de un menú.
`CMenu::LoadMenu`	Carga un recurso de menú desde el archivo ejecutable y lo adjunta a un objeto `CMenu`.
`CMenu::LoadMenuIndirect`	Carga un menú de una plantilla de menú en memoria y lo adjunta a un objeto `CMenu`.
`CMenu::MeasureItem`	La llama el marco para determinar las dimensiones de menú cuando se crea un menú dibujado por el propietario.
`CMenu::ModifyMenu`	Cambia un elemento de menú existente en la posición especificada.
`CMenu::RemoveMenu`	Elimina un elemento de menú con un menú emergente asociado del menú especificado.
`CMenu::SetDefaultItem`	Establece el elemento de menú predeterminado para el menú especificado.
`CMenu::SetMenuContextHelpId`	Recupera el id. de contexto de ayuda asociado con el menú.
`CMenu::SetMenuInfo`	Recupera información en un menú específico.
`CMenu::SetMenuItemBitmaps`	Asocia los mapas de bits de marca de verificación especificados con un elemento de menú.
`CMenu::SetMenuItemInfo`	Cambia información sobre un elemento de menú.
`CMenu::TrackPopupMenu`	Muestra un menú emergente flotante en la ubicación especificada y supervisa la selección de elementos en el menú emergente.
`CMenu::TrackPopupMenuEx`	Muestra un menú emergente flotante en la ubicación especificada y supervisa la selección de elementos en el menú emergente.

Operadores públicos

Nombre	Descripción
`CMenu::operator HMENU`	Recupera el manipulador del objeto de menú.
`CMenu::operator !=`	Determina si dos objetos de menú no son iguales.
`CMenu::operator ==`	Determina si dos objetos de menú son iguales.

Miembros de datos públicos

Nombre	Descripción
`CMenu::m_hMenu`	Especifica el manipulador del menú de Windows adjunto al objeto `CMenu`.

Comentarios

Proporciona funciones miembro para crear, supervisar, actualizar y destruir un menú.

Cree un objeto CMenu en el marco de pila como local y, a continuación, llame a las funciones miembro de CMenu para manipular el nuevo menú según sea necesario. A continuación, llame CWnd::SetMenu a para establecer el menú en una ventana, seguido inmediatamente de una llamada a la función miembro Detach del objeto CMenu. La función miembro CWnd::SetMenu establece el menú de la ventana en el nuevo menú, ocasiona que la ventana se vuelva a dibujar para reflejar el cambio de menú y también pasa la propiedad del menú a la ventana. La llamada a Detach desasocia el HMENUdel objeto CMenu para que cuando la variable local CMenu pase fuera del ámbito, el destructor de objeto CMenu no intente destruir un menú que ya no posee. El propio menú se destruye automáticamente cuando se destruye la ventana.

Puede usar la función miembro LoadMenuIndirect para crear un menú a partir de una plantilla en la memoria, pero un menú creado a partir de un recurso mediante una llamada a LoadMenu se mantiene más fácilmente y el propio recurso de menú se puede crear y modificar mediante el editor de menús.

Jerarquía de herencia

CObject

CMenu

Requisitos

Encabezado: afxwin.h

`CMenu::AppendMenu`

Anexa un nuevo elemento al final de este menú.

BOOL AppendMenu(
    UINT nFlags,
    UINT_PTR nIDNewItem = 0,
    LPCTSTR lpszNewItem = NULL);

BOOL AppendMenu(
    UINT nFlags,
    UINT_PTR nIDNewItem,
    const CBitmap* pBmp);

Parámetros

nFlags
Especifica información sobre el estado del elemento de menú nuevo cuando se agrega al menú. Consta de uno o más de los valores enumerados en la sección Comentarios.

nIDNewItem
Especifica el id. de comando del nuevo elemento de menú o, si nFlags está establecido en MF_POPUP, el manipulador de menú (HMENU) de un menú emergente. El parámetro nIDNewItem se omite (no es necesario) si nFlags se establece en MF_SEPARATOR.

lpszNewItem
Especifica el contenido del nuevo elemento de menú. El parámetro nFlags se usa para interpretar lpszNewItem de la siguiente manera:

`nFlags`	Interpretación de `lpszNewItem`
`MF_OWNERDRAW`	Contiene un valor de 32 bits proporcionado por la aplicación que la aplicación puede usar para mantener datos adicionales asociados al elemento de menú. Este valor de 32 bits está disponible para la aplicación cuando procesa mensajes de `WM_MEASUREITEM` y `WM_DRAWITEM`. El valor se almacena en el miembro `itemData` de la estructura proporcionada con esos mensajes.
`MF_STRING`	Puntero a una cadena terminada en null. Esta es la interpretación predeterminada.
`MF_SEPARATOR`	El parámetro `lpszNewItem` se omite (no es necesario).

pBmp
Apunta a un objeto CBitmap que se usará como elemento de menú.

Valor devuelto

Es distinto de cero si la función se realiza correctamente; de lo contrario, es 0.

Comentarios

La aplicación puede especificar el estado del elemento de menú al establecer valores en nFlags. Cuando nIDNewItem especifica un menú emergente, se convierte en parte del menú al que se anexa. Si ese menú se destruye, también se destruirá el menú anexado. Se debe desasociar un menú anexado de un objeto CMenu para evitar conflictos. Tenga en cuenta que MF_STRING y MF_OWNERDRAW no son válidos para la versión de mapa de bits de AppendMenu.

La lista siguiente describe las marcas que se pueden establecer en nFlags:

MF_CHECKED Actúa como un botón de alternancia con MF_UNCHECKED para colocar la marca de verificación predeterminada junto al elemento. Cuando la aplicación proporciona mapas de bits de marca de verificación (consulte la función miembro SetMenuItemBitmaps), se muestra el mapa de bits "marca de verificación".
MF_UNCHECKED Actúa como un botón de alternancia con MF_CHECKED para quitar una marca de verificación junto al elemento. Cuando la aplicación proporciona mapas de bits de marca de verificación (consulte la función miembro SetMenuItemBitmaps), se muestra el mapa de bits "marca de verificación".
MF_DISABLED Deshabilita el elemento de menú para que no se pueda seleccionar, pero no lo atenúa.
MF_ENABLED Habilita el elemento de menú para que se pueda seleccionar y restaurar a partir de su estado atenuado.
MF_GRAYED Deshabilita el elemento de menú para que no se pueda seleccionar y lo atenúa.
MF_MENUBARBREAK Coloca el elemento en una nueva línea en menús estáticos o en una nueva columna en menús emergentes. La nueva columna de menú emergente se separará de la columna anterior mediante una línea divisoria vertical.
MF_MENUBREAK Coloca el elemento en una nueva línea en menús estáticos o en una nueva columna en menús emergentes. No se coloca ninguna línea divisoria entre las columnas.
MF_OWNERDRAW Especifica que el elemento es un elemento dibujado por el propietario. Cuando el menú se muestra por primera vez, la ventana propietaria del menú recibe un mensaje de WM_MEASUREITEM, que recupera la altura y la anchura del elemento de menú. El mensaje de WM_DRAWITEM es el que se envía cada vez que el propietario debe actualizar la apariencia visual del elemento de menú. Esta opción no es válida para un elemento de menú de nivel superior.
MF_POPUP Especifica que el elemento de menú tiene asociado un menú emergente. El id. de parámetro especifica un manipulador para un menú emergente que se va a asociar al elemento. Se usa para agregar un menú emergente de nivel superior o un menú emergente jerárquico con un elemento de menú emergente.
MF_SEPARATOR Dibuja una línea divisoria horizontal. Solo se puede usar en un menú emergente. Esta línea no se puede atenuar, deshabilitar ni resaltar. Otros parámetros se ignoran.
MF_STRING Especifica que el elemento de menú es una cadena de caracteres.

Cada uno de los grupos siguientes enumera las marcas que son mutuamente excluyentes y no se pueden usar juntas:

MF_DISABLED, MF_ENABLED y MF_GRAYED
MF_STRING, MF_OWNERDRAW, MF_SEPARATOR y la versión del mapa de bits
MF_MENUBARBREAK y MF_MENUBREAK
MF_CHECKED y MF_UNCHECKED

Cada vez que se cambia un menú que reside en una ventana (ya sea que se muestre o no la ventana), la aplicación debe llamar a CWnd::DrawMenuBar.

Ejemplo

Vea el ejemplo de CMenu::CreateMenu.

`CMenu::Attach`

Asocia un menú de Windows existente a un objeto CMenu.

BOOL Attach(HMENU hMenu);

Parámetros

hMenu
Especifica un manipulador para una ventana de Windows.

Valor devuelto

Distinto de cero si la operación es correcta; de lo contrario, 0.

Comentarios

No se debe llamar a esta función si ya hay un menú adjunto al objeto CMenu. El manipulador de menú se almacena en el miembro de datos m_hMenu.

Si el menú que desea manipular ya está asociado a una ventana, puede usar la función CWnd::GetMenu para obtener un manipulador en el menú.

Ejemplo

CMenu mnu;
HMENU hmnu = AfxGetMainWnd()->GetMenu()->GetSafeHmenu();
mnu.Attach(hmnu);

// Now you can manipulate the window's menu as a CMenu
// object...

mnu.Detach();

`CMenu::CheckMenuItem`

Agrega o quita marcas de verificación de los elementos de menú del menú emergente.

UINT CheckMenuItem(
    UINT nIDCheckItem,
    UINT nCheck);

Parámetros

nIDCheckItem
Especifica el elemento de menú que se comprobará, según lo determinado por nCheck.

nCheck
Especifica cómo comprobar el elemento de menú y cómo determinar la posición del elemento en el menú. El parámetro nCheck puede ser una combinación de MF_CHECKED o MF_UNCHECKED con marcas MF_BYPOSITION o MF_BYCOMMAND. Estos marcadores se pueden combinar utilizando el operador OR bit a bit. Tienen los significados siguientes:

MF_BYCOMMAND Especifica que el parámetro proporciona el id. de comando del elemento de menú existente. Este es el valor predeterminado.
MF_BYPOSITION Especifica que el parámetro proporciona la posición del elemento de menú existente. El primer elemento está en la posición 0.
MF_CHECKED Actúa como un botón de alternancia con MF_UNCHECKED para colocar la marca de verificación predeterminada junto al elemento.
MF_UNCHECKED Actúa como un botón de alternancia con MF_CHECKED para quitar una marca de verificación junto al elemento.

Valor devuelto

El estado anterior del elemento: MF_CHECKED o MF_UNCHECKED, o 0xFFFFFFFF si el elemento de menú no existía.

Comentarios

El parámetro nIDCheckItem especifica el elemento que se va a modificar.

El parámetro nIDCheckItem puede identificar un elemento de menú emergente, así como un elemento de menú. No es necesario realizar ningún paso especial para comprobar un elemento de menú emergente. No se pueden comprobar los elementos de menú de nivel superior. Un elemento de menú emergente debe comprobarse por posición, ya que no tiene un identificador de elemento de menú asociado.

Ejemplo

Vea el ejemplo de CMenu::GetMenuState.

`CMenu::CheckMenuRadioItem`

Comprueba un elemento de menú especificado y lo convierte en un elemento de radio.

BOOL CheckMenuRadioItem(
    UINT nIDFirst,
    UINT nIDLast,
    UINT nIDItem,
    UINT nFlags);

Parámetros

nIDFirst
Especifica (como un id. o un desplazamiento, según el valor de nFlags) el primer elemento de menú del grupo de botones de radio.

nIDLast
Especifica (como un id. o un desplazamiento, según el valor de nFlags) el último elemento de menú del grupo de botones de radio.

nIDItem
Especifica (como id. o desplazamiento, según el valor de nFlags) el elemento del grupo que se comprobará con un botón de radio.

nFlags
Especifica la interpretación de nIDFirst, nIDLast y nIDItem de la siguiente manera:

nFlags	Interpretación
`MF_BYCOMMAND`	Especifica que el parámetro proporciona el id. de comando del elemento de menú existente. Este es el valor predeterminado si no se establece `MF_BYCOMMAND` ni `MF_BYPOSITION`.
`MF_BYPOSITION`	Especifica que el parámetro proporciona la posición del elemento de menú existente. El primer elemento está en la posición 0.

Valor devuelto

Si es correcto, su valor es distinto de cero. En caso contrario, es 0

Comentarios

Al mismo tiempo, la función desmarca todos los demás elementos de menú del grupo asociado y borra la marca de tipo de elemento de radio para esos elementos. El elemento activado se muestra mediante un mapa de bits de botón de radio (o viñeta) en lugar de un mapa de bits de marca de verificación.

Ejemplo

Vea el ejemplo de ON_COMMAND_RANGE.

`CMenu::CMenu`

Crea un menú vacío y lo adjunta a un objeto CMenu.

CMenu();

Comentarios

El menú no se crea hasta que se llama a una de las funciones miembro de creación o carga de CMenu:

CreateMenu
CreatePopupMenu
LoadMenu
LoadMenuIndirect
Attach

`CMenu::CreateMenu`

Crea un menú y lo adjunta al objeto CMenu.

BOOL CreateMenu();

Valor devuelto

Distinto de cero si el menú se creó correctamente; en caso contrario, 0.

Comentarios

El menú está inicialmente vacío. Los elementos de menú se pueden agregar mediante la función miembro AppendMenu o InsertMenu.

Si el menú se asigna a una ventana, se destruye automáticamente cuando se destruye la ventana.

Antes de salir, una aplicación debe liberar recursos del sistema asociados con un menú si el menú no está asignado a una ventana. Una aplicación libera un menú al llamar a la función miembro DestroyMenu.

Ejemplo

// The code fragment below shows how to create a new menu for the
// application window using CreateMenu() and CreatePopupMenu().
// Then, the created menu will replace the current menu of the
// application. The old menu will be destroyed with DestroyMenu().
// NOTE: The code fragment below is done in a CFrameWnd-derived class.

// Create a new menu for the application window.
VERIFY(m_NewMenu.CreateMenu());

// Create a "File" popup menu and insert this popup menu to the
// new menu of the application window. The "File" menu has only
// one menu item, i.e. "Exit".
VERIFY(m_FileMenu.CreatePopupMenu());
m_FileMenu.AppendMenu(MF_STRING, ID_APP_EXIT, _T("E&xit"));
m_NewMenu.AppendMenu(MF_POPUP, (UINT_PTR)m_FileMenu.m_hMenu, _T("&File"));

// Remove and destroy old menu
SetMenu(NULL);
CMenu *old_menu = CMenu::FromHandle(m_hMenuDefault);
old_menu->DestroyMenu();

// Add new menu.
SetMenu(&m_NewMenu);

// Assign default menu
m_hMenuDefault = m_NewMenu.m_hMenu;

`CMenu::CreatePopupMenu`

Crea un menú emergente y lo adjunta al objeto CMenu.

BOOL CreatePopupMenu();

Valor devuelto

Distinto de cero si el menú emergente se creó correctamente; de lo contrario, 0.

Comentarios

El menú está inicialmente vacío. Los elementos de menú se pueden agregar mediante la función miembro AppendMenu o InsertMenu. La aplicación puede agregar el menú emergente a un menú existente o a un menú emergente. La función miembro TrackPopupMenu se puede usar para mostrar este menú como un menú emergente flotante y para seguir las selecciones en el menú emergente.

Si el menú se asigna a una ventana, se destruye automáticamente cuando se destruye la ventana. Si el menú se agrega a un menú existente, se destruye automáticamente cuando se destruye ese menú.

Antes de salir, una aplicación debe liberar recursos del sistema asociados con un menú emergente si el menú no está asignado a una ventana. Una aplicación libera un menú al llamar a la función miembro DestroyMenu.

Ejemplo

Vea el ejemplo de CMenu::CreateMenu.

`CMenu::DeleteMenu`

Elimina un elemento del menú.

BOOL DeleteMenu(
    UINT nPosition,
    UINT nFlags);

Parámetros

nPosition
Especifica el elemento de menú que se va a eliminar, según se determina mediante nFlags.

nFlags
Se usa para interpretar nPosition de la siguiente manera:

`nFlags`	Interpretación de `nPosition`
`MF_BYCOMMAND`	Especifica que el parámetro proporciona el id. de comando del elemento de menú existente. Este es el valor predeterminado si no se establece `MF_BYCOMMAND` ni `MF_BYPOSITION`.
`MF_BYPOSITION`	Especifica que el parámetro proporciona la posición del elemento de menú existente. El primer elemento está en la posición 0.

Valor devuelto

Es distinto de cero si la función se realiza correctamente; de lo contrario, es 0.

Comentarios

Si el elemento de menú tiene un menú emergente asociado, DeleteMenu destruye el manipulador para el menú emergente y libera la memoria usada por el menú emergente.

Cada vez que se cambia un menú que reside en una ventana (ya sea que se muestre o no la ventana), la aplicación debe llamar a CWnd::DrawMenuBar.

Ejemplo

Vea el ejemplo de CWnd::GetMenu.

`CMenu::DeleteTempMap`

El controlador de tiempo de inactividad CWinApp la llama automáticamente y elimina cualquier objeto temporal CMenu creado por la función miembro FromHandle.

static void PASCAL DeleteTempMap();

Comentarios

DeleteTempMap desasocia el objeto de menú de Windows que estaba asociado con un objeto CMenu temporal antes de que se elimine el objeto CMenu.

Ejemplo

// DeleteTempMap() is a static member and does not need
// an instantiated CMenu object.
CMenu::DeleteTempMap();

`CMenu::DestroyMenu`

Destruye el menú y los recursos de Windows que se usaron.

BOOL DestroyMenu();

Valor devuelto

Distinto de cero si se destruye el menú; de lo contrario, 0.

Comentarios

El menú se desasocia del objeto CMenu antes de que se destruya. Se llama automáticamente a la función de Windows DestroyMenu en el destructor CMenu.

Ejemplo

Vea el ejemplo de CMenu::CreateMenu.

`CMenu::Detach`

Desasocia un menú de Windows de un objeto CMenu y devuelve el manipulador.

HMENU Detach();

Valor devuelto

El manipulador, de tipo HMENU, en un menú de Windows, si se ejecuta correctamente; de lo contrario NULL.

Comentarios

El miembro de datos m_hMenu se establece en NULL.

Ejemplo

CMenu mnu;
HMENU hmnu = AfxGetMainWnd()->GetMenu()->GetSafeHmenu();
mnu.Attach(hmnu);

// Now you can manipulate the window's menu as a CMenu
// object...

mnu.Detach();

`CMenu::DrawItem`

La llama el marco cuando cambia un aspecto visual de un menú dibujado por el propietario.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parámetros

lpDrawItemStruct
Un puntero a una estructura DRAWITEMSTRUCT que contiene información sobre el tipo de dibujo necesario.

Comentarios

El miembro itemAction de la estructura DRAWITEMSTRUCT define la acción de dibujo que se realizará. Invalida esta función miembro para implementar el dibujo de un objeto CMenu dibujado por el propietario. La aplicación debe restaurar todos los objetos de la interfaz de dispositivo gráfico (GDI) seleccionados para el contexto de visualización que se proporciona en lpDrawItemStruct antes de que finalice esta función miembro.

Consulte CWnd::OnDrawItem para obtener una descripción de la estructura DRAWITEMSTRUCT.

Ejemplo

El código siguiente procede de la muestra de CTRLTEST de MFC:

// Override DrawItem() to implement drawing for an owner-draw CMenu object.
// CColorMenu is a CMenu-derived class.
void CColorMenu::DrawItem(LPDRAWITEMSTRUCT lpDIS)
{
   CDC *pDC = CDC::FromHandle(lpDIS->hDC);
   COLORREF cr = (COLORREF)lpDIS->itemData; // RGB in item data

   if (lpDIS->itemAction & ODA_DRAWENTIRE)
   {
      // Paint the color item in the color requested
      CBrush br(cr);
      pDC->FillRect(&lpDIS->rcItem, &br);
   }

   if ((lpDIS->itemState & ODS_SELECTED) &&
       (lpDIS->itemAction & (ODA_SELECT | ODA_DRAWENTIRE)))
   {
      // item has been selected - hilite frame
      COLORREF crHilite = RGB(255 - GetRValue(cr),
                              255 - GetGValue(cr), 255 - GetBValue(cr));
      CBrush br(crHilite);
      pDC->FrameRect(&lpDIS->rcItem, &br);
   }

   if (!(lpDIS->itemState & ODS_SELECTED) &&
       (lpDIS->itemAction & ODA_SELECT))
   {
      // Item has been de-selected -- remove frame
      CBrush br(cr);
      pDC->FrameRect(&lpDIS->rcItem, &br);
   }
}

`CMenu::EnableMenuItem`

Habilita, deshabilita o atenúa un elemento de menú.

UINT EnableMenuItem(
    UINT nIDEnableItem,
    UINT nEnable);

Parámetros

nIDEnableItem
Especifica el elemento de menú que se habilitará, según lo determinado por nEnable. Este parámetro puede especificar elementos de menú emergente, así como elementos de menú estándar.

nEnable
Especifica la acción que se va a realizar. Puede ser una combinación de MF_DISABLED, MF_ENABLED o MF_GRAYED, con MF_BYCOMMAND o MF_BYPOSITION. Estos valores se pueden combinar mediante el operador OR bit a bit (|). Estos valores tienen los significados siguientes:

MF_BYCOMMAND Especifica que el parámetro proporciona el id. de comando del elemento de menú existente. Este es el valor predeterminado.
MF_BYPOSITION Especifica que el parámetro proporciona la posición del elemento de menú existente. El primer elemento está en la posición 0.
MF_DISABLED Deshabilita el elemento de menú para que no se pueda seleccionar, pero no lo atenúa.
MF_ENABLED Habilita el elemento de menú para que se pueda seleccionar y restaurar a partir de su estado atenuado.
MF_GRAYED Deshabilita el elemento de menú para que no se pueda seleccionar y lo atenúa.

Valor devuelto

Estado anterior (MF_DISABLED, MF_ENABLED o MF_GRAYED), o -1 si no es válido.

Comentarios

Las funciones miembro CreateMenu, InsertMenu, ModifyMenu y LoadMenuIndirect también pueden establecer el estado (habilitado, deshabilitado o atenuado) de un elemento de menú.

El uso del valor MF_BYPOSITION requiere que una aplicación use el CMenu correcto. Si se usa el elemento CMenu de la barra de menús, se ve afectado un elemento de menú de nivel superior (un elemento de la barra de menús). Para establecer el estado de un elemento en un menú emergente o en un menú emergente anidado por posición, una aplicación debe especificar el CMenu del menú emergente.

Cuando una aplicación especifica la marca MF_BYCOMMAND, Windows comprueba todos los elementos de menú emergente que están subordinados a CMenu; por lo tanto, a menos que haya elementos de menú duplicados, el uso del CMenu de la barra de menús es suficiente.

Ejemplo

// The code fragment below shows how to disable (and gray out) the
// File\New menu item.
// NOTE: m_bAutoMenuEnable is set to FALSE in the constructor of
// CMainFrame so no ON_UPDATE_COMMAND_UI or ON_COMMAND handlers are
// needed, and CMenu::EnableMenuItem() will work as expected.

CMenu *mmenu = GetMenu();
CMenu *submenu = mmenu->GetSubMenu(0);
submenu->EnableMenuItem(ID_FILE_NEW, MF_BYCOMMAND | MF_DISABLED | MF_GRAYED);

`CMenu::FromHandle`

Devuelve un puntero que apunta a un objeto CMenu si se proporciona el manipulador de Windows para un menú.

static CMenu* PASCAL FromHandle(HMENU hMenu);

Parámetros

hMenu
Un manipulador de Windows para un menú.

Valor devuelto

Un puntero a CMenu que podría ser temporal o permanente.

Comentarios

Si todavía no se ha asociado un objeto CMenu con el objeto del menú de Windows, se creará y asociará un objeto CMenu temporal.

Este objeto CMenu temporal solo es válido hasta la próxima vez que haya tiempo de inactividad en el bucle de eventos de la aplicación. En ese momento, se eliminarán todos los objetos temporales.

Ejemplo

Vea el ejemplo de CMenu::CreateMenu.

`CMenu::GetDefaultItem`

Determina el elemento de menú predeterminado en el menú especificado.

UINT GetDefaultItem(
    UINT gmdiFlags,
    BOOL fByPos = FALSE);

Parámetros

gmdiFlags
Valor que especifica cómo busca la función elementos de menú. Este parámetro puede ser ninguno, uno o una combinación de los siguientes valores:

Valor Significado

GMDI_GOINTOPOPUPS Especifica que, si el elemento predeterminado es uno que abre un submenú, la función es buscar en el submenú correspondiente de forma recursiva. Si el submenú no tiene ningún elemento predeterminado, el valor devuelto identifica el elemento que abre el submenú.

De forma predeterminada, la función devuelve el primer elemento predeterminado del menú especificado, independientemente de si es un elemento que abre un submenú.

GMDI_USEDISABLED Especifica que la función es devolver un elemento predeterminado, incluso si está deshabilitado.

De forma predeterminada, la función omite los elementos deshabilitados o atenuados.

Valor	Significado
`GMDI_GOINTOPOPUPS`	Especifica que, si el elemento predeterminado es uno que abre un submenú, la función es buscar en el submenú correspondiente de forma recursiva. Si el submenú no tiene ningún elemento predeterminado, el valor devuelto identifica el elemento que abre el submenú. De forma predeterminada, la función devuelve el primer elemento predeterminado del menú especificado, independientemente de si es un elemento que abre un submenú.
`GMDI_USEDISABLED`	Especifica que la función es devolver un elemento predeterminado, incluso si está deshabilitado. De forma predeterminada, la función omite los elementos deshabilitados o atenuados.

fByPos
Valor que especifica si se va a recuperar el identificador del elemento de menú o su posición. Si este parámetro es FALSE, se devuelve el identificador . De lo contrario, se devuelve la posición.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es el identificador o la posición del elemento de menú. Si la función produce un error, el valor devuelto es - 1.

Comentarios

En esta función miembro, se implementa el comportamiento de la función GetMenuDefaultItem de Win32, tal y como se describe en Windows SDK.

Ejemplo

Vea el ejemplo de CMenu::InsertMenu.

`CMenu::GetMenuContextHelpId`

Recupera el id. de ayuda de contexto asociado con CMenu.

DWORD GetMenuContextHelpId() const;

Valor devuelto

El id. de ayuda de contexto asociado actualmente con CMenu si tiene uno; de lo contrario, cero.

Ejemplo

Vea el ejemplo de CMenu::InsertMenu.

`CMenu::GetMenuInfo`

Recupera información de un menú.

BOOL GetMenuInfo(LPMENUINFO lpcmi) const;

Parámetros

lpcmi
Un puntero a una estructura MENUINFO que contiene información para el menú.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es distinto de cero; de lo contrario, el valor devuelto es cero.

Comentarios

Llame a esta función para recuperar información sobre el menú.

`CMenu::GetMenuItemCount`

Determina el número de elementos de un menú emergente o de nivel superior.

UINT GetMenuItemCount() const;

Valor devuelto

El número de elementos del menú si la función es correcta; en caso contrario, -1.

Ejemplo

Vea el ejemplo de CWnd::GetMenu.

`CMenu::GetMenuItemID`

Obtiene el identificador del elemento de menú ubicado en la posición especificada por nPos.

UINT GetMenuItemID(int nPos) const;

Parámetros

nPos
Especifica la posición (basada en cero) del elemento de menú cuyo id. se está recuperando.

Valor devuelto

Id. del elemento especificado en un menú emergente si la función se ejecuta correctamente. Si el elemento especificado es un menú emergente (en lugar de un elemento dentro del menú emergente), el valor devuelto es -1. Si nPos corresponde a un elemento de menú SEPARATOR, el valor devuelto es 0.

Ejemplo

Vea el ejemplo de CMenu::InsertMenu.

`CMenu::GetMenuItemInfo`

Recupera información sobre un elemento de menú.

BOOL GetMenuItemInfo(
    UINT uItem,
    LPMENUITEMINFO lpMenuItemInfo,
    BOOL fByPos = FALSE);

Parámetros

uItem
Identificador o posición del elemento de menú sobre el que obtendrá información. El significado de este parámetro depende del valor de ByPos.

lpMenuItemInfo
Un puntero a MENUITEMINFO, como se describe en Windows SDK, que contiene información sobre el menú.

fByPos
Valor que especifica el significado de nIDItem. De forma predeterminada, ByPos es FALSE, lo cual indica que uItem es un identificador de elemento de menú. Si ByPos no se establece en FALSE, indica una posición de elemento de menú.

Valor devuelto

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 un error extendida, use la función GetLastError de Win32, como se describe en Windows SDK.

Comentarios

Esta función miembro se implementa el comportamiento de la función GetMenuItemInfo de Win32, tal y como se describe en Windows SDK. Tenga en cuenta que en la implementación de MFC de GetMenuItemInfo, no se usa un manipulador para un menú.

Ejemplo

// CMainFrame::OnToggleTestMenuInfo() is a menu command handler for 
// "Toggle Info" menu item (whose resource id is ID_MENU_TOGGLEINFO). It 
// toggles the checked or unchecked state of the "Toggle Info" menu item.
// CMainFrame is a CFrameWnd-derived class.
void CMainFrame::OnToggleTestMenuItemInfo()
{
   // Get the popup menu which contains the "Toggle Info" menu item.
   CMenu* mmenu = GetMenu();
   CMenu* submenu = mmenu->GetSubMenu(4);

   // Check the state of the "Toggle Info" menu item. Check the menu item
   // if it is currently unchecked. Otherwise, uncheck the menu item
   // if it is not currently checked.
   MENUITEMINFO info;
   info.cbSize = sizeof (MENUITEMINFO); // must fill up this field
   info.fMask = MIIM_STATE;             // get the state of the menu item
   VERIFY(submenu->GetMenuItemInfo(ID_MENU_TOGGLEINFO, &info));

   if (info.fState & MF_CHECKED)
      submenu->CheckMenuItem(ID_MENU_TOGGLEINFO, MF_UNCHECKED | MF_BYCOMMAND);
   else
      submenu->CheckMenuItem(ID_MENU_TOGGLEINFO, MF_CHECKED | MF_BYCOMMAND);
}

`CMenu::GetMenuState`

Devuelve el estado del elemento de menú especificado o el número de elementos de un menú emergente.

UINT GetMenuState(
    UINT nID,
    UINT nFlags) const;

Parámetros

nID
Especifica el id. del elemento de menú, determinado por nFlags.

nFlags
Especifica la naturaleza de nID. Puede ser uno de los siguientes valores:

MF_BYCOMMAND Especifica que el parámetro proporciona el id. de comando del elemento de menú existente. Este es el valor predeterminado.
MF_BYPOSITION Especifica que el parámetro proporciona la posición del elemento de menú existente. El primer elemento está en la posición 0.

Valor devuelto

El valor 0xFFFFFFFF si el elemento especificado no existe. Si nId identifica un menú emergente, el byte de orden superior contiene el número de elementos del menú emergente y el byte de orden inferior contiene las marcas de menú asociadas con el menú emergente. De lo contrario, el valor devuelto es una máscara (OR booleano) de los valores de la lista siguiente (esta máscara describe el estado del elemento de menú que nId identifica):

MF_CHECKED Actúa como un botón de alternancia con MF_UNCHECKED para colocar la marca de verificación predeterminada junto al elemento. Cuando la aplicación proporciona mapas de bits de marca de verificación (consulte la función miembro SetMenuItemBitmaps), se muestra el mapa de bits "marca de verificación".
MF_DISABLED Deshabilita el elemento de menú para que no se pueda seleccionar, pero no lo atenúa.
MF_ENABLED Habilita el elemento de menú para que se pueda seleccionar y restaurar a partir de su estado atenuado. Tenga en cuenta que el valor de esta constante es 0; una aplicación no debe arrojar 0 en una prueba al usar este valor.
MF_GRAYED Deshabilita el elemento de menú para que no se pueda seleccionar y lo atenúa.
MF_MENUBARBREAK Coloca el elemento en una nueva línea en menús estáticos o en una nueva columna en menús emergentes. La nueva columna de menú emergente se separará de la columna anterior mediante una línea divisoria vertical.
MF_MENUBREAK Coloca el elemento en una nueva línea en menús estáticos o en una nueva columna en menús emergentes. No se coloca ninguna línea divisoria entre las columnas.
MF_SEPARATOR Dibuja una línea divisoria horizontal. Solo se puede usar en un menú emergente. Esta línea no se puede atenuar, deshabilitar ni resaltar. Otros parámetros se ignoran.
MF_UNCHECKED Actúa como un botón de alternancia con MF_CHECKED para quitar una marca de verificación junto al elemento. Cuando la aplicación proporciona mapas de bits de marca de verificación (consulte la función miembro SetMenuItemBitmaps), se muestra el mapa de bits "marca de verificación". Tenga en cuenta que el valor de esta constante es 0; una aplicación no debe arrojar 0 en una prueba al usar este valor.

Ejemplo

// CMainFrame::OnToggleTestMenuState() is a menu command handler for
// "Toggle State" menu item (whose resource id is ID_MENU_TOGGLESTATE).
// It toggles the checked or unchecked state of the "Toggle State" menu item.
// CMainFrame is a CFrameWnd-derived class.
void CMainFrame::OnToggleTestMenuState()
{
   // Get the popup menu which contains the "Toggle State" menu item.
   CMenu *mmenu = GetMenu();
   CMenu *submenu = mmenu->GetSubMenu(4);

   // Check the state of the "Toggle State" menu item. Check the menu item
   // if it is currently unchecked. Otherwise, uncheck the menu item
   // if it is not currently checked.
   UINT state = submenu->GetMenuState(ID_MENU_TOGGLESTATE, MF_BYCOMMAND);
   ASSERT(state != 0xFFFFFFFF);

   if (state & MF_CHECKED)
      submenu->CheckMenuItem(ID_MENU_TOGGLESTATE, MF_UNCHECKED | MF_BYCOMMAND);
   else
      submenu->CheckMenuItem(ID_MENU_TOGGLESTATE, MF_CHECKED | MF_BYCOMMAND);
}

`CMenu::GetMenuString`

Copia la etiqueta del elemento de menú especificado en el búfer especificado.

int GetMenuString(
    UINT nIDItem,
    LPTSTR lpString,
    int nMaxCount,
    UINT nFlags) const;

int GetMenuString(
    UINT nIDItem,
    CString& rString,
    UINT nFlags) const;

Parámetros

nIDItem
Especifica el identificador entero del elemento de menú o el desplazamiento del elemento de menú en el menú, en función del valor de nFlags.

lpString
Apunta a un búfer que recibirá la etiqueta.

rString
Una referencia a un objeto CString que recibirá la cadena de menú copiada.

nMaxCount
Especifica la longitud máxima (en caracteres) de la etiqueta que se copiará. Si la etiqueta es mayor que el máximo especificado en nMaxCount, se truncan los caracteres adicionales.

nFlags
Especifica la interpretación del parámetro nIDItem. Puede ser uno de los siguientes valores:

`nFlags`	Interpretación de `nIDItem`
`MF_BYCOMMAND`	Especifica que el parámetro proporciona el id. de comando del elemento de menú existente. Este es el valor predeterminado si no se establece `MF_BYCOMMAND` ni `MF_BYPOSITION`.
`MF_BYPOSITION`	Especifica que el parámetro proporciona la posición del elemento de menú existente. El primer elemento está en la posición 0.

Valor devuelto

Especifica el número real de caracteres copiados en el búfer, sin incluir el terminador null.

Comentarios

El parámetro nMaxCount debe ser uno mayor que el número de caracteres en la etiqueta para dar cabida al carácter null que finaliza una cadena.

Ejemplo

Vea el ejemplo de CMenu::InsertMenu.

`CMenu::GetSafeHmenu`

Devuelve el HMENU contenedor de este CMenu objeto o un NULL CMenu puntero.

HMENU GetSafeHmenu() const;

Ejemplo

Vea el ejemplo de CMenu::LoadMenu.

`CMenu::GetSubMenu`

Recupera el objeto CMenu de un menú emergente.

CMenu* GetSubMenu(int nPos) const;

Parámetros

nPos
Especifica la posición del menú emergente contenido en el menú. Los valores de posición comienzan en 0 para el primer elemento de menú. El identificador del menú emergente no se puede usar en esta función.

Valor devuelto

Un puntero a un objeto CMenu cuyo miembro m_hMenu contiene un manipulador para el menú emergente si existe un menú emergente en la posición especificada; de lo contrario NULL. Si no existe un objeto CMenu, se crea entonces uno temporal. El puntero CMenu devuelto no debe almacenarse.

Ejemplo

Vea el ejemplo de CMenu::TrackPopupMenu.

`CMenu::InsertMenu`

Inserta un nuevo elemento de menú en la posición especificada por nPosition y mueve otros elementos hacia abajo en el menú.

BOOL InsertMenu(
    UINT nPosition,
    UINT nFlags,
    UINT_PTR nIDNewItem = 0,
    LPCTSTR lpszNewItem = NULL);

BOOL InsertMenu(
    UINT nPosition,
    UINT nFlags,
    UINT_PTR nIDNewItem,
    const CBitmap* pBmp);

Parámetros

nPosition
Especifica el elemento de menú antes del cual se va a insertar el nuevo elemento de menú. El parámetro nFlags se usa para interpretar nPosition de la siguiente manera:

`nFlags`	Interpretación de `nPosition`
`MF_BYCOMMAND`	Especifica que el parámetro proporciona el id. de comando del elemento de menú existente. Este es el valor predeterminado si no se establece `MF_BYCOMMAND` ni `MF_BYPOSITION`.
`MF_BYPOSITION`	Especifica que el parámetro proporciona la posición del elemento de menú existente. El primer elemento está en la posición 0. Si `nPosition` es -1, el nuevo elemento de menú se anexa al final del menú.

nFlags
Especifica cómo se interpreta nPosition y especifica información sobre el estado del elemento de menú nuevo cuando se agrega al menú. Para obtener una lista de las marcas que se pueden establecer, consulte la función miembro AppendMenu. Para especificar más de un valor, use el operador OR bit a bit para combinarlos con la marca MF_BYCOMMAND o MF_BYPOSITION.

nIDNewItem
Especifica el id. de comando del nuevo elemento de menú o, si nFlags está establecido en MF_POPUP, el manipulador de menú (HMENU) del menú emergente. El parámetro nIDNewItem se omite (no es necesario) si nFlags se establece en MF_SEPARATOR.

lpszNewItem
Especifica el contenido del nuevo elemento de menú. nFlags se puede usar para interpretar lpszNewItem de las siguientes maneras:

`nFlags`	Interpretación de `lpszNewItem`
`MF_OWNERDRAW`	Contiene un valor de 32 bits proporcionado por la aplicación que la aplicación puede usar para mantener datos adicionales asociados al elemento de menú. Este valor de 32 bits está disponible para la aplicación en el miembro `itemData` de la estructura proporcionada por los mensajes de `WM_MEASUREITEM` y `WM_DRAWITEM`. Estos mensajes se envían cuando se cambia o se muestra inicialmente el elemento de menú.
`MF_STRING`	Contiene un puntero largo a una cadena finalizada en null. Esta es la interpretación predeterminada.
`MF_SEPARATOR`	El parámetro `lpszNewItem` se omite (no es necesario).

pBmp
Apunta a un objeto CBitmap que se usará como elemento de menú.

Valor devuelto

Es distinto de cero si la función se realiza correctamente; de lo contrario, es 0.

Comentarios

La aplicación puede especificar el estado del elemento de menú al establecer valores en nFlags.

Cada vez que se cambia un menú que reside en una ventana (ya sea que se muestre o no la ventana), la aplicación debe llamar a CWnd::DrawMenuBar.

Cuando nIDNewItem especifica un menú emergente, se convierte en parte del menú al que se inserta. Si ese menú se destruye, también se destruirá el menú insertado. Se debe desasociar un menú insertado de un objeto CMenu para evitar conflictos.

Si se maximiza la ventana secundaria de la interfaz de varios documentos (MDI) activa y una aplicación inserta un menú emergente en el menú de la aplicación de MDI al llamar a esta función y especificar la marca MF_BYPOSITION, el menú se inserta una posición más lejos de lo esperado. Esto sucede porque el menú Control de la ventana secundaria de la MDI activa se inserta en la primera posición de la barra de menús de la ventana del marco de MDI. Para colocar el menú correctamente, la aplicación debe agregar 1 al valor de posición que, de lo contrario, se usaría. Una aplicación puede usar el mensaje WM_MDIGETACTIVE para determinar si la ventana secundaria actualmente activa está maximizada.

Ejemplo

// CMainFrame::OnChangeFileMenu() is a menu command handler for
// CMainFrame class, which in turn is a CFrameWnd-derived class.
// It modifies the File menu by inserting, removing and renaming
// some menu items. Other operations include associating a context
// help id and setting default menu item to the File menu.
// CMainFrame is a CFrameWnd-derived class.
void CMainFrame::OnChangeFileMenu()
{
   // Get the menu from the application window.
   CMenu *mmenu = GetMenu();

   // Look for "File" menu.
   int pos = FindMenuItem(mmenu, _T("&File"));
   if (pos == -1)
      return;

   // Remove "New" menu item from the File menu.
   CMenu *submenu = mmenu->GetSubMenu(pos);
   pos = FindMenuItem(submenu, _T("&New\tCtrl+N"));
   if (pos > -1)
      submenu->RemoveMenu(pos, MF_BYPOSITION);

   // Look for "Open" menu item from the File menu. Insert a new
   // menu item called "Close" right after the "Open" menu item.
   // ID_CLOSEFILE is the command id for the "Close" menu item.
   pos = FindMenuItem(submenu, _T("&Open...\tCtrl+O"));
   if (pos > -1)
      submenu->InsertMenu(pos + 1, MF_BYPOSITION, ID_CLOSEFILE, _T("&Close"));

   // Rename menu item "Exit" to "Exit Application".
   pos = FindMenuItem(submenu, _T("E&xit"));
   if (pos > -1)
   {
      UINT id = submenu->GetMenuItemID(pos);
      submenu->ModifyMenu(id, MF_BYCOMMAND, id, _T("E&xit Application"));
   }

   // Associate a context help ID with File menu, if one is not found.
   // ID_FILE_CONTEXT_HELPID is the context help ID for the File menu
   // that is defined in resource file.
   if (submenu->GetMenuContextHelpId() == 0)
      submenu->SetMenuContextHelpId(ID_FILE_CONTEXT_HELPID);

   // Set "Open" menu item as the default menu item for the File menu,
   // if one is not found. So, when a user double-clicks the File
   // menu, the system sends a command message to the menu's owner
   // window and closes the menu as if the File\Open command item had
   // been chosen.
   if (submenu->GetDefaultItem(GMDI_GOINTOPOPUPS, TRUE) == -1)
   {
      pos = FindMenuItem(submenu, _T("&Open...\tCtrl+O"));
      submenu->SetDefaultItem(pos, TRUE);
   }
}

// FindMenuItem() will find a menu item string from the specified
// popup menu and returns its position (0-based) in the specified
// popup menu. It returns -1 if no such menu item string is found.
int FindMenuItem(CMenu *Menu, LPCTSTR MenuString)
{
   ASSERT(Menu);
   ASSERT(::IsMenu(Menu->GetSafeHmenu()));

   int count = Menu->GetMenuItemCount();
   for (int i = 0; i < count; i++)
   {
      CString str;
      if (Menu->GetMenuString(i, str, MF_BYPOSITION) &&
          str.Compare(MenuString) == 0)
         return i;
   }

   return -1;
}

`CMenu::InsertMenuItem`

Inserta un nuevo elemento de menú en la posición especificada de un menú.

BOOL InsertMenuItem(
    UINT uItem,
    LPMENUITEMINFO lpMenuItemInfo,
    BOOL fByPos = FALSE);

Parámetros

uItem
Consulte la descripción de uItem en InsertMenuItem en Windows SDK.

lpMenuItemInfo
Consulte la descripción de lpmii en InsertMenuItem en Windows SDK.

fByPos
Consulte la descripción de fByPosition en InsertMenuItem en Windows SDK.

Comentarios

Esta función encapsula InsertMenuItem, que se describe en Windows SDK.

`CMenu::LoadMenu`

Carga un recurso de menú desde el archivo ejecutable de la aplicación y lo adjunta al objeto CMenu.

BOOL LoadMenu(LPCTSTR lpszResourceName);
BOOL LoadMenu(UINT nIDResource);

Parámetros

lpszResourceName
Apunta a una cadena finalizada en null que contiene el nombre del recurso de menú que se cargará.

nIDResource
Especifica el id. de menú del recurso de menú que se cargará.

Valor devuelto

Distinto de cero si el recurso de menú se cargó correctamente; de lo contrario, 0.

Comentarios

Ejemplo

// CMainFrame::OnReplaceMenu() is a menu command handler for CMainFrame
// class, which in turn is a CFrameWnd-derived class. It loads a new
// menu resource and replaces the SDI application window's menu bar with
// this new menu. CMainFrame is a CFrameWnd-derived class.
void CMainFrame::OnReplaceMenu()
{
   // Load the new menu.
   m_ShortMenu.LoadMenu(IDR_SHORT_MENU);
   ASSERT(m_ShortMenu);

   // Remove and destroy the old menu
   SetMenu(NULL);
   ::DestroyMenu(m_hMenuDefault);

   // Add the new menu
   SetMenu(&m_ShortMenu);

   // Assign default menu
   m_hMenuDefault = m_ShortMenu.GetSafeHmenu(); // or m_ShortMenu.m_hMenu;
}

`CMenu::LoadMenuIndirect`

Carga un menú de una plantilla de menú en memoria y lo adjunta a un objeto CMenu.

BOOL LoadMenuIndirect(const void* lpMenuTemplate);

Parámetros

lpMenuTemplate
Apunta a una plantilla de menú (que es una única estructura MENUITEMTEMPLATEHEADER y una colección de una o varias estructuras MENUITEMTEMPLATE). Para más información sobre estas dos estructuras, consulte Windows SDK.

Valor devuelto

Distinto de cero si el recurso de menú se cargó correctamente; de lo contrario, 0.

Comentarios

Una plantilla de menú es un encabezado seguido por una colección de una o varias estructuras MENUITEMTEMPLATE, cada una de las cuales puede contener uno o varios elementos de menú y menús emergentes.

El número de versión debería ser 0.

Las marcas mtOption deben incluir MF_END para el último elemento de una lista emergente y para el último elemento de la lista principal. Consulte la función miembro AppendMenu para ver otras marcas. El miembro mtId debe omitirse de la estructura MENUITEMTEMPLATE cuando MF_POPUP se especifica en mtOption.

El espacio asignado para la estructura MENUITEMTEMPLATE debe ser lo suficientemente grande para que mtString contenga el nombre del elemento de menú como una cadena finalizada en null.

Ejemplo

// CMainFrame::OnLoadMenuIndirect() is a menu command handler for
// CMainFrame class, which in turn is a CFrameWnd-derived class. It
// shows how to use LoadMenuIndirect() to load a resource from a
// menu template in memory.
void CMainFrame::OnLoadMenuIndirect()
{
   // For simplicity, allocate 500 bytes from stack. May use
   // GlobalAlloc() to allocate memory bytes from heap.
   BYTE milist[500];
   memset(milist, 0, 500);
   int bytes_left = sizeof(milist);

   // Fill up the MENUITEMTEMPLATEHEADER structure.
   MENUITEMTEMPLATEHEADER *mheader = (MENUITEMTEMPLATEHEADER*)milist;
   mheader->versionNumber = 0;
   mheader->offset = 0;

   int bytes_used = sizeof(MENUITEMTEMPLATEHEADER);
   bytes_left -= bytes_used;

   // Add the following menu items to menu bar:
   // File     Edit
   //   Exit     Copy
   //            Paste
   bytes_used += AddMenuItem(milist + bytes_used, bytes_left, L"&File", 0,
                             TRUE, FALSE);
   bytes_left -= bytes_used;
   bytes_used += AddMenuItem(milist + bytes_used, bytes_left, L"E&xit",
                             ID_APP_EXIT, FALSE, TRUE);
   bytes_left -= bytes_used;
   bytes_used += AddMenuItem(milist + bytes_used, bytes_left, L"&Edit", 0,
                             TRUE, TRUE);
   bytes_left -= bytes_used;
   bytes_used += AddMenuItem(milist + bytes_used, bytes_left, L"&Copy",
                             ID_EDIT_COPY, FALSE, FALSE);
   bytes_left -= bytes_used;
   bytes_used += AddMenuItem(milist + bytes_used, bytes_left, L"&Paste",
                             ID_EDIT_PASTE, FALSE, TRUE);
   bytes_left -= bytes_used;

   // Load resource from a menu template in memory.
   ASSERT(m_IndiMenu.LoadMenuIndirect(milist));

   // Remove and destroy old menu
   SetMenu(NULL);
   ::DestroyMenu(m_hMenuDefault);

   // Add new menu.
   SetMenu(&m_IndiMenu);

   // Assign default menu
   m_hMenuDefault = m_IndiMenu.m_hMenu;
}

// This is a helper function for adding a menu item (either a popup
// or command item) to the specified menu template.
//
//    MenuTemplate  - pointer to a menu template
//    TemplateBytes - space remaining in MenuTemplate
//    MenuString    - string for the menu item to be added
//    MenuID        - id for the command item. Its value is ignored if
//                    IsPopup is TRUE.
//    IsPopup       - TRUE for popup menu (or submenu); FALSE for command
//                    item
//    LastItem      - TRUE if MenuString is the last item for the popup;
//                    FALSE otherwise.
UINT AddMenuItem(LPVOID MenuTemplate, int TemplateBytes, WCHAR *MenuString,
                 WORD MenuID, BOOL IsPopup, BOOL LastItem)
{
   MENUITEMTEMPLATE *mitem = (MENUITEMTEMPLATE*)MenuTemplate;

   UINT bytes_used = 0;
   if (IsPopup) // for popup menu
   {
      if (LastItem)
         mitem->mtOption = MF_POPUP | MF_END;
      else
         mitem->mtOption = MF_POPUP;
      bytes_used += sizeof(mitem->mtOption);

      mitem = (MENUITEMTEMPLATE*)((BYTE*)MenuTemplate + bytes_used);
      // a popup doesn't have mtID!!!

      TemplateBytes -= bytes_used;
      wcscpy_s((WCHAR*)mitem, TemplateBytes / sizeof(WCHAR), MenuString);
      bytes_used += (UINT)(sizeof(WCHAR) * (wcslen(MenuString) + 1)); // include '\0'
   }
   else // for command item
   {
      mitem->mtOption = LastItem ? MF_END : 0;
      mitem->mtID = MenuID;
      TemplateBytes -= bytes_used;
      wcscpy_s(mitem->mtString, TemplateBytes / sizeof(WCHAR), MenuString);
      bytes_used += (UINT)(sizeof(mitem->mtOption) + sizeof(mitem->mtID) +
                           sizeof(WCHAR) * (wcslen(MenuString) + 1)); // include '\0'
   }

   return bytes_used;
}

`CMenu::m_hMenu`

Especifica el manipulador HMENU del menú de Windows adjunto al objeto CMenu.

HMENU m_hMenu;

Ejemplo

Vea el ejemplo de CMenu::LoadMenu.

`CMenu::MeasureItem`

La llama el marco cuando se crea un menú con un estilo dibujado por el propietario.

virtual void MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct);

Parámetros

lpMeasureItemStruct
Un puntero a una estructura MEASUREITEMSTRUCT.

Comentarios

De manera predeterminada, esta función miembro no hace nada. Invalide esta función miembro y rellene la estructura MEASUREITEMSTRUCT para informar a Windows de las dimensiones del menú.

Consulte CWnd::OnMeasureItem para obtener una descripción de la estructura MEASUREITEMSTRUCT.

Ejemplo

El código siguiente procede de la muestra de CTRLTEST de MFC:

// Override MeasureItem() to return the size of the menu item.
// CColorMenu is a CMenu-derived class.

#define COLOR_BOX_WIDTH 20
#define COLOR_BOX_HEIGHT 20

void CColorMenu::MeasureItem(LPMEASUREITEMSTRUCT lpMIS)
{
   // all items are of fixed size
   lpMIS->itemWidth = COLOR_BOX_WIDTH;
   lpMIS->itemHeight = COLOR_BOX_HEIGHT;
}

`CMenu::ModifyMenu`

Cambia un elemento de menú existente en la posición especificada por nPosition.

BOOL ModifyMenu(
    UINT nPosition,
    UINT nFlags,
    UINT_PTR nIDNewItem = 0,
    LPCTSTR lpszNewItem = NULL);

BOOL ModifyMenu(
    UINT nPosition,
    UINT nFlags,
    UINT_PTR nIDNewItem,
    const CBitmap* pBmp);

Parámetros

nPosition
Especifica el elemento de menú que se cambiará. El parámetro nFlags se usa para interpretar nPosition de la siguiente manera:

`nFlags`	Interpretación de `nPosition`
`MF_BYCOMMAND`	Especifica que el parámetro proporciona el id. de comando del elemento de menú existente. Este es el valor predeterminado si no se establece `MF_BYCOMMAND` ni `MF_BYPOSITION`.
`MF_BYPOSITION`	Especifica que el parámetro proporciona la posición del elemento de menú existente. El primer elemento está en la posición 0.

nFlags
Especifica cómo nPosition se interpreta y proporciona información sobre los cambios que se realizarán en el elemento de menú. Para obtener una lista de las marcas que se pueden establecer, consulte la función miembro AppendMenu.

nIDNewItem
Especifica el id. de comando del elemento de menú modificado o, si nFlags está establecido en MF_POPUP, el manipulador de menú (HMENU) de un menú emergente. El parámetro nIDNewItem se omite (no es necesario) si nFlags se establece en MF_SEPARATOR.

lpszNewItem
Especifica el contenido del nuevo elemento de menú. El parámetro nFlags se usa para interpretar lpszNewItem de la siguiente manera:

`nFlags`	Interpretación de `lpszNewItem`
`MF_OWNERDRAW`	Contiene un valor de 32 bits proporcionado por la aplicación que la aplicación puede usar para mantener datos adicionales asociados al elemento de menú. Este valor de 32 bits está disponible para la aplicación cuando procesa `MF_MEASUREITEM` y `MF_DRAWITEM`.
`MF_STRING`	Contiene un puntero largo a una cadena finalizada en null o a `CString`.
`MF_SEPARATOR`	El parámetro `lpszNewItem` se omite (no es necesario).

pBmp
Apunta a un objeto CBitmap que se usará como elemento de menú.

Valor devuelto

Es distinto de cero si la función se realiza correctamente; de lo contrario, es 0.

Comentarios

La aplicación especifica el nuevo estado del elemento de menú al establecer valores en nFlags. Si esta función reemplaza un menú emergente asociado al elemento de menú, destruye el menú emergente anterior y libera la memoria usada por el menú emergente.

Cada vez que se cambia un menú que reside en una ventana (ya sea que se muestre o no la ventana), la aplicación debe llamar a CWnd::DrawMenuBar. Para cambiar los atributos de los elementos de menú existentes, es mucho más rápido usar las funciones miembro CheckMenuItem y EnableMenuItem.

Ejemplo

Vea el ejemplo de CMenu::InsertMenu.

`CMenu::operator HMENU`

Use este operador para recuperar el manipulador del objeto CMenu.

operator HMENU() const;

Valor devuelto

Si se ejecuta correctamente, el manipulador del objeto CMenu; de lo contrario, NULL.

Comentarios

Puede usar el manipulador para llamar directamente a las API de Windows.

`CMenu::operator !=`

Determina si dos menús no son lógicamente iguales.

BOOL operator!=(const CMenu& menu) const;

Parámetros

menu
Un objeto CMenu para la comparación.

Comentarios

Prueba si un objeto de menú del lado izquierdo no es igual al objeto del menú del lado derecho.

`CMenu::operator ==`

Determina si dos menús no son lógicamente iguales.

BOOL operator==(const CMenu& menu) const;

Parámetros

menu
Un objeto CMenu para la comparación.

Comentarios

Comprueba si un objeto de menú del lado izquierdo es igual (en términos del valor de HMENU) a un objeto de menú del lado derecho.

`CMenu::RemoveMenu`

Elimina un elemento de menú con un menú emergente asociado del menú.

BOOL RemoveMenu(
    UINT nPosition,
    UINT nFlags);

Parámetros

nPosition
Especifica el elemento de menú que se quitará. El parámetro nFlags se usa para interpretar nPosition de la siguiente manera:

`nFlags`	Interpretación de `nPosition`
`MF_BYCOMMAND`	Especifica que el parámetro proporciona el id. de comando del elemento de menú existente. Este es el valor predeterminado si no se establece `MF_BYCOMMAND` ni `MF_BYPOSITION`.
`MF_BYPOSITION`	Especifica que el parámetro proporciona la posición del elemento de menú existente. El primer elemento está en la posición 0.

nFlags
Especifica cómo se interpreta nPosition.

Valor devuelto

Es distinto de cero si la función se realiza correctamente; de lo contrario, es 0.

Comentarios

No destruye el manipulador de un menú emergente, por lo que se puede reutilizar el menú. Antes de llamar a esta función, la aplicación puede llamar a la función miembro GetSubMenu para recuperar el objeto emergente CMenu y reutilizarlo.

Cada vez que se cambia un menú que reside en una ventana (ya sea que se muestre o no la ventana), la aplicación debe llamar a CWnd::DrawMenuBar.

Ejemplo

Vea el ejemplo de CMenu::InsertMenu.

`CMenu::SetDefaultItem`

Establece el elemento de menú predeterminado para el menú especificado.

BOOL SetDefaultItem(
    UINT uItem,
    BOOL fByPos = FALSE);

Parámetros

uItem
Identificador o posición del nuevo elemento de menú predeterminado o - 1 para ningún elemento predeterminado. El significado de este parámetro depende del valor de fByPos.

fByPos
Valor que especifica el significado de uItem. Si este parámetro es FALSE, uItem es un identificador de elemento de menú. De lo contrario, es una posición de elemento de menú.

Valor devuelto

Comentarios

En esta función miembro, se implementa el comportamiento de la función SetMenuDefaultItem de Win32, tal y como se describe en Windows SDK.

Ejemplo

Vea el ejemplo de CMenu::InsertMenu.

`CMenu::SetMenuContextHelpId`

Asocia un id. de ayuda de contexto a CMenu.

BOOL SetMenuContextHelpId(DWORD dwContextHelpId);

Parámetros

dwContextHelpId
Id. de ayuda de contexto que se asociará a CMenu.

Valor devuelto

Si es correcto, su valor es distinto de cero. En caso contrario, es 0

Comentarios

Todos los elementos del menú comparten este identificador: no es posible adjuntar un identificador contextual de ayuda a los elementos de menú individuales.

Ejemplo

Vea el ejemplo de CMenu::InsertMenu.

`CMenu::SetMenuInfo`

Establece la información de un menú.

BOOL SetMenuInfo(LPCMENUINFO lpcmi);

Parámetros

lpcmi
Un puntero a una estructura MENUINFO que contiene información para el menú.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es distinto de cero; de lo contrario, el valor devuelto es cero.

Comentarios

Llame a esta función para establecer información específica sobre el menú.

`CMenu::SetMenuItemBitmaps`

Asocia los mapas de bits especificados con un elemento de menú.

BOOL SetMenuItemBitmaps(
    UINT nPosition,
    UINT nFlags,
    const CBitmap* pBmpUnchecked,
    const CBitmap* pBmpChecked);

Parámetros

nPosition
Especifica el elemento de menú que se cambiará. El parámetro nFlags se usa para interpretar nPosition de la siguiente manera:

`nFlags`	Interpretación de nPosition
`MF_BYCOMMAND`	Especifica que el parámetro proporciona el id. de comando del elemento de menú existente. Este es el valor predeterminado si no se establece `MF_BYCOMMAND` ni `MF_BYPOSITION`.
`MF_BYPOSITION`	Especifica que el parámetro proporciona la posición del elemento de menú existente. El primer elemento está en la posición 0.

nFlags
Especifica cómo se interpreta nPosition.

pBmpUnchecked
Especifica el mapa de bits que se usará para los elementos de menú que no están activados.

pBmpChecked
Especifica el mapa de bits que se usará para los elementos de menú que están activados.

Valor devuelto

Es distinto de cero si la función se realiza correctamente; de lo contrario, es 0.

Comentarios

Tanto si el elemento de menú está activado como desactivado, Windows muestra el mapa de bits adecuado junto al elemento de menú.

Si pBmpUnchecked o pBmpChecked es NULL, Windows no muestra nada junto al elemento de menú del atributo correspondiente. Si ambos parámetros son NULL, Windows usa la marca de verificación predeterminada cuando se activa el elemento y quita la marca de verificación cuando el elemento se desactiva.

Cuando se destruye el menú, estos mapas de bits no se destruyen; la aplicación debe destruirlas.

La función de Windows GetMenuCheckMarkDimensions recupera las dimensiones de la marca de verificación predeterminada usada para los elementos de menú. La aplicación usa estos valores para determinar el tamaño adecuado de los mapas de bits proporcionados con esta función. Obtenga el tamaño, cree los mapas de bits y, a continuación, establézcalos.

Ejemplo

// The code fragment below is from CMainFrame::OnCreate and shows
// how to associate bitmaps with the "Bitmap" menu item.
// Whether the "Bitmap" menu item is checked or unchecked, Windows
// displays the appropriate bitmap next to the menu item. Both
// IDB_CHECKBITMAP and IDB_UNCHECKBITMAP bitmaps are loaded
// in OnCreate() and destroyed in the destructor of CMainFrame class.
// CMainFrame is a CFrameWnd-derived class.

// Load bitmaps from resource. Both m_CheckBitmap and m_UnCheckBitmap
// are member variables of CMainFrame class of type CBitmap.
ASSERT(m_CheckBitmap.LoadBitmap(IDB_CHECKBITMAP));
ASSERT(m_UnCheckBitmap.LoadBitmap(IDB_UNCHECKBITMAP));

// Associate bitmaps with the "Bitmap" menu item.
CMenu *mmenu = GetMenu();
CMenu *submenu = mmenu->GetSubMenu(4);
ASSERT(submenu->SetMenuItemBitmaps(ID_MENU_BITMAP, MF_BYCOMMAND,
                                   &m_CheckBitmap, &m_UnCheckBitmap));

// This code fragment is taken from CMainFrame::~CMainFrame

// Destroy the bitmap objects if they are loaded successfully
// in OnCreate().
if (m_CheckBitmap.m_hObject)
   m_CheckBitmap.DeleteObject();

if (m_UnCheckBitmap.m_hObject)
   m_UnCheckBitmap.DeleteObject();

`CMenu::SetMenuItemInfo`

Cambia información sobre un elemento de menú.

BOOL SetMenuItemInfo(
    UINT uItem,
    LPMENUITEMINFO lpMenuItemInfo,
    BOOL fByPos = FALSE);

Parámetros

uItem
Consulte la descripción de uItem en SetMenuItemInfo en Windows SDK.

lpMenuItemInfo
Consulte la descripción de lpmii en SetMenuItemInfo en Windows SDK.

fByPos
Consulte la descripción de fByPosition en SetMenuItemInfo en Windows SDK.

Comentarios

Esta función encapsula SetMenuItemInfo, que se describe en Windows SDK.

`CMenu::TrackPopupMenu`

Muestra un menú emergente flotante en la ubicación especificada y supervisa la selección de elementos en el menú emergente.

BOOL TrackPopupMenu(
    UINT nFlags,
    int x,
    int y,
    CWnd* pWnd,
    LPCRECT lpRect = 0);

Parámetros

nFlags
Especifica las marcas de posición de pantalla y posición del mouse. Consulte TrackPopupMenu para obtener una lista de marcas disponibles.

x
Especifica la posición horizontal en coordenadas de la pantalla del menú emergente. Según el valor del parámetro nFlags, el menú puede estar alineado a la izquierda, alineado a la derecha o centrado en relación con esta posición.

y
Especifica la posición vertical en coordenadas de la pantalla de la parte superior del menú en pantalla.

pWnd
Identifica la ventana que posee el menú emergente. Este parámetro no puede ser NULL, incluso si se especifica la marca TPM_NONOTIFY. Esta ventana recibe todos los mensajes WM_COMMAND del menú. En las versiones 3.1 y posteriores de Windows, la ventana no recibe mensajes de WM_COMMAND hasta que se devuelve TrackPopupMenu. En Windows 3.0, la ventana recibe mensajes de WM_COMMAND antes de que se devuelva TrackPopupMenu.

lpRect
ignorado.

Valor devuelto

Este método devuelve el resultado de llamar a TrackPopupMenu en Windows SDK.

Comentarios

Un menú emergente flotante puede aparecer en cualquier parte de la pantalla.

Ejemplo

// The code fragment shows how to get the File menu from the
// application window and displays it as a floating popup menu
// when the right mouse button is clicked in view.
// CMdiView is a CView-derived class.
void CMdiView::OnRButtonDown(UINT nFlags, CPoint point)
{
   CView::OnRButtonDown(nFlags, point);

   CMenu *menu_bar = AfxGetMainWnd()->GetMenu();
   CMenu *file_menu = menu_bar->GetSubMenu(0);
   ASSERT(file_menu);

   ClientToScreen(&point);
   file_menu->TrackPopupMenu(TPM_LEFTALIGN | TPM_RIGHTBUTTON, point.x,
                             point.y, this);
}

`CMenu::TrackPopupMenuEx`

Muestra un menú emergente flotante en la ubicación especificada y supervisa la selección de elementos en el menú emergente.

BOOL TrackPopupMenuEx(
    UINT fuFlags,
    int x,
    int y,
    CWnd* pWnd,
    LPTPMPARAMS lptpm);

Parámetros

fuFlags
Especifica varias funciones del menú extendido. Para obtener una lista de todos los valores y su significado, consulte TrackPopupMenuEx.

x
Especifica la posición horizontal en coordenadas de la pantalla del menú emergente.

y
Especifica la posición vertical en coordenadas de la pantalla de la parte superior del menú en pantalla.

pWnd
Un puntero a la ventana que posee el menú emergente y recibe los mensajes del menú creado. Esta ventana puede ser cualquier ventana de la aplicación actual, pero no puede ser NULL. Si especifica TPM_NONOTIFY en el parámetro fuFlags, la función no envía ningún mensaje a pWnd. La función debe devolver para que la ventana apuntada a pWnd reciba el mensaje de WM_COMMAND.

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

Valor devuelto

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

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 0 si se produce un error. Para obtener información de errores extendida, realice una llamada a GetLastError.

Comentarios

Un menú emergente flotante puede aparecer en cualquier parte de la pantalla. Para obtener más información sobre el control de errores al crear el menú emergente, consulte TrackPopupMenuEx.

Consulte también

Ejemplo de MFCCTRLTEST
Ejemplo de MFCDYNAMENU
CObject (clase)
Gráfico de jerarquías

Compartir a través de

Clase CMenu

Sintaxis

Miembros

Constructores públicos

Métodos públicos

Operadores públicos

Miembros de datos públicos

Comentarios

Jerarquía de herencia

Requisitos

CMenu::AppendMenu

Parámetros

Valor devuelto

Comentarios

Ejemplo

CMenu::Attach

Parámetros

Valor devuelto

Comentarios

Ejemplo

CMenu::CheckMenuItem

Parámetros

Valor devuelto

Comentarios

Ejemplo

CMenu::CheckMenuRadioItem

Parámetros

Valor devuelto

Comentarios

Ejemplo

CMenu::CMenu

Comentarios

CMenu::CreateMenu

Valor devuelto

Comentarios

Ejemplo

CMenu::CreatePopupMenu

Valor devuelto

Comentarios

Ejemplo

CMenu::DeleteMenu

Parámetros

Valor devuelto

Comentarios

Ejemplo

CMenu::DeleteTempMap

Comentarios

Ejemplo

CMenu::DestroyMenu

Valor devuelto

Comentarios

Ejemplo

CMenu::Detach

Valor devuelto

Comentarios

Ejemplo

CMenu::DrawItem

Parámetros

Comentarios

Ejemplo

CMenu::EnableMenuItem

Parámetros

Valor devuelto

Comentarios

Ejemplo

CMenu::FromHandle

Parámetros

Valor devuelto

Comentarios

Ejemplo

CMenu::GetDefaultItem

Parámetros

Valor devuelto

Comentarios

Ejemplo

CMenu::GetMenuContextHelpId

Valor devuelto

Ejemplo

CMenu::GetMenuInfo

Clase `CMenu`

`CMenu::AppendMenu`

`CMenu::Attach`

`CMenu::CheckMenuItem`

`CMenu::CheckMenuRadioItem`

`CMenu::CMenu`

`CMenu::CreateMenu`

`CMenu::CreatePopupMenu`

`CMenu::DeleteMenu`

`CMenu::DeleteTempMap`

`CMenu::DestroyMenu`

`CMenu::Detach`

`CMenu::DrawItem`

`CMenu::EnableMenuItem`

`CMenu::FromHandle`

`CMenu::GetDefaultItem`

`CMenu::GetMenuContextHelpId`

`CMenu::GetMenuInfo`

`CMenu::GetMenuItemCount`

`CMenu::GetMenuItemID`

`CMenu::GetMenuItemInfo`

`CMenu::GetMenuState`

`CMenu::GetMenuString`

`CMenu::GetSafeHmenu`

`CMenu::GetSubMenu`

`CMenu::InsertMenu`

`CMenu::InsertMenuItem`

`CMenu::LoadMenu`

`CMenu::LoadMenuIndirect`

`CMenu::m_hMenu`

`CMenu::MeasureItem`

`CMenu::ModifyMenu`

`CMenu::operator HMENU`

`CMenu::operator !=`

`CMenu::operator ==`

`CMenu::RemoveMenu`