Classe `CMenu`

Artigo
07/05/2024

Um encapsulamento do Windows HMENU.

Sintaxe

class CMenu : public CObject

Membros

Construtores públicos

Nome	Descrição
`CMenu::CMenu`	Constrói um objeto `CMenu`.

Métodos públicos

Nome	Descrição
`CMenu::AppendMenu`	Acrescenta um novo item ao final deste menu.
`CMenu::Attach`	Anexa um identificador de menu do Windows a um objeto `CMenu`.
`CMenu::CheckMenuItem`	Coloca uma marca de seleção próxima ou remove uma marca de seleção de um item de menu no menu de item pop-up.
`CMenu::CheckMenuRadioItem`	Coloca um botão de opção próximo a um item de menu e remove o botão de opção de todos os outros itens de menu no grupo.
`CMenu::CreateMenu`	Cria um menu vazio e o anexa a um objeto `CMenu`.
`CMenu::CreatePopupMenu`	Cria um menu de item pop-up vazio e o anexa a um objeto `CMenu`.
`CMenu::DeleteMenu`	Exclui um item especificado do menu. Se o item de menu tiver um menu de item pop-up associado, destruirá o identificador para o menu de item pop-up e liberará a memória usada por ele.
`CMenu::DeleteTempMap`	Exclui todos os objetos temporários `CMenu` criados pela função membro `FromHandle`.
`CMenu::DestroyMenu`	Destrói o menu anexado a um objeto `CMenu` e libera toda memória ocupada pelo menu.
`CMenu::Detach`	Desanexa um identificador de menu do Windows de um objeto `CMenu` e retorna o identificador.
`CMenu::DrawItem`	Chamado pela estrutura quando um aspecto visual de um menu desenhado pelo proprietário é alterado.
`CMenu::EnableMenuItem`	Habilita, desabilita ou esmaece (acinzenta) um item de menu.
`CMenu::FromHandle`	Retorna um ponteiro para um objeto `CMenu`, dado um identificador de menu do Windows.
`CMenu::GetDefaultItem`	Determina o item de menu padrão no menu especificado.
`CMenu::GetMenuContextHelpId`	Recupera a ID de contexto de ajuda associada ao menu.
`CMenu::GetMenuInfo`	Recupera informações em um menu específico.
`CMenu::GetMenuItemCount`	Determina o número de itens em um menu de item pop-up ou de nível superior.
`CMenu::GetMenuItemID`	Obtém o identificador de item de menu para um item de menu localizado na posição especificada.
`CMenu::GetMenuItemInfo`	Recupera informações sobre um item de menu.
`CMenu::GetMenuState`	Retorna o status do item de menu especificado ou o número de itens em um menu de item pop-up.
`CMenu::GetMenuString`	Recupera o rótulo do item de menu especificado.
`CMenu::GetSafeHmenu`	Retorna o `m_hMenu` encapsulado por este objeto `CMenu`.
`CMenu::GetSubMenu`	Recupera um ponteiro para um menu de item pop-up.
`CMenu::InsertMenu`	Insere um novo item de menu na posição especificada, movendo outros itens para baixo no menu.
`CMenu::InsertMenuItem`	Insere um novo item de menu na posição especificada em um menu.
`CMenu::LoadMenu`	Carrega um recurso de menu do arquivo executável e o anexa a um objeto `CMenu`.
`CMenu::LoadMenuIndirect`	Carrega um menu de um modelo de menu na memória e o anexa a um objeto `CMenu`.
`CMenu::MeasureItem`	Chamado pela estrutura para determinar dimensões de menu quando um menu desenhado pelo proprietário é criado.
`CMenu::ModifyMenu`	Altera um item de menu existente na posição especificada.
`CMenu::RemoveMenu`	Exclui um item de menu com um menu de item pop-up associado do menu especificado.
`CMenu::SetDefaultItem`	Define o item de menu padrão para o menu especificado.
`CMenu::SetMenuContextHelpId`	Define a ID de contexto de ajuda que será associada ao menu.
`CMenu::SetMenuInfo`	Define informações em um menu específico.
`CMenu::SetMenuItemBitmaps`	Associa os bitmaps de marca de seleção especificados a um item de menu.
`CMenu::SetMenuItemInfo`	Altera informações sobre um item de menu.
`CMenu::TrackPopupMenu`	Exibe um menu pop-up flutuante no local especificado e rastreia a seleção de itens no menu de item pop-up.
`CMenu::TrackPopupMenuEx`	Exibe um menu pop-up flutuante no local especificado e rastreia a seleção de itens no menu de item pop-up.

Operadores públicos

Nome	Descrição
`CMenu::operator HMENU`	Recupera o identificador do objeto de menu.
`CMenu::operator !=`	Determina se dois objetos de menu não são iguais.
`CMenu::operator ==`	Determina se dois objetos de menu são iguais.

Membros de Dados Públicos

Nome	Descrição
`CMenu::m_hMenu`	Especifica o identificador no menu do Windows anexado ao objeto `CMenu`.

Comentários

Ele fornece funções membro para criar, acompanhar, atualizar e destruir um menu.

Criar um objeto CMenu no registro de ativação como um local e, em seguida, chamar as funções membro de CMenu para manipular o novo menu conforme necessário. Em seguida, chame CWnd::SetMenu para definir o menu como uma janela, seguido imediatamente por uma chamada para a função membro CMenu do objeto Detach. A função membro CWnd::SetMenu define o menu da janela como o novo menu, faz com que a janela seja redesenhada para refletir a alteração do menu e também passa a propriedade do menu para a janela. A chamada para Detach desanexa HMENU do objeto CMenu, assim quando a variável CMenu local passa fora do escopo, o destruidor de objeto CMenu não tenta destruir um menu que ele não possui mais. O menu é destruído automaticamente quando a janela é destruída.

Você pode usar a função membro LoadMenuIndirect para criar um menu a partir de um modelo na memória, mas um menu criado a partir de um recurso por uma chamada para LoadMenu é mantido com mais facilidade e o recurso de menu pode ser criado e modificado pelo editor de menus.

Hierarquia de herança

CObject

CMenu

Requisitos

Cabeçalho: afxwin.h

`CMenu::AppendMenu`

Acrescenta um novo item ao final de um menu.

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 informações sobre o estado do novo item de menu quando ele é adicionado ao menu. Ele consiste em um ou mais dos valores listados na seção Comentários.

nIDNewItem
Especifica a ID de comando do novo item de menu ou, se nFlags for definido como MF_POPUP, o identificador de menu (HMENU) de um menu de item pop-up. O parâmetro nIDNewItem será ignorado (não necessário) se nFlags for definido como MF_SEPARATOR.

lpszNewItem
Especifica o conteúdo do novo item de menu. O parâmetro nFlags é usado para interpretar lpszNewItem da seguinte maneira:

`nFlags`	Interpretação de `lpszNewItem`
`MF_OWNERDRAW`	Contém um valor de 32 bits fornecido pelo aplicativo que o aplicativo pode usar para manter dados adicionais associados ao item de menu. Esse valor de 32 bits está disponível para o aplicativo quando ele processa mensagens `WM_MEASUREITEM` e `WM_DRAWITEM`. O valor é armazenado no membro `itemData` da estrutura fornecida com essas mensagens.
`MF_STRING`	Contém um ponteiro para uma cadeia de caracteres terminada em nulo. Essa é a interpretação padrão.
`MF_SEPARATOR`	O parâmetro `lpszNewItem` será ignorado (não necessário).

pBmp
Aponta para um objeto CBitmap que será usado como o item de menu.

Valor de retorno

Diferente de zero se a função for bem-sucedida; caso contrário, 0.

Comentários

O aplicativo pode especificar o estado do item de menu definindo valores em nFlags. Quando nIDNewItem especifica um menu de item pop-up, ele se torna parte do menu ao qual ele é acrescentado. Se esse menu for destruído, o menu acrescentado também será destruído. Um menu acrescentado deve ser desanexado de um objeto CMenu para evitar conflitos. Observe que MF_STRING e MF_OWNERDRAW não são válidos para a versão bitmap de AppendMenu.

A lista a seguir descreve os sinalizadores que podem ser definidos em nFlags:

MF_CHECKED Atua como um alternância para MF_UNCHECKED colocar a marca de seleção padrão próxima ao item. Quando o aplicativo fornece bitmaps de marca de seleção (consulte a função membro SetMenuItemBitmaps), o bitmap "marca de seleção ativada" é exibido.
MF_UNCHECKED Atua como um alternância para MF_CHECKED remover uma marca de seleção próxima ao item. Quando o aplicativo fornece bitmaps de marca de seleção (consulte a função membro SetMenuItemBitmaps), o bitmap "marca de seleção desativada" é exibido.
MF_DISABLED Desabilita o item de menu para que ele não possa ser selecionado, mas não o esmaece.
MF_ENABLED Habilita o item de menu para que ele possa ser selecionado e o restaura de seu estado esmaecido.
MF_GRAYED Desabilita o item de menu para que ele não possa ser selecionado e o esmaece.
MF_MENUBARBREAK Coloca o item em uma nova linha em menus estáticos ou em uma nova coluna em menus de item pop-up. A nova coluna de menu de item pop-up será separada da coluna antiga por uma linha divisória vertical.
MF_MENUBREAK Coloca o item em uma nova linha em menus estáticos ou em uma nova coluna em menus de item pop-up. Nenhuma linha divisória é colocada entre as colunas.
MF_OWNERDRAW Especifica que o item é um item de desenho de proprietário. Quando o menu é exibido pela primeira vez, a janela que possui o menu recebe uma mensagem WM_MEASUREITEM, que recupera a altura e a largura do item de menu. A mensagem WM_DRAWITEM é aquela enviada sempre que o proprietário deve atualizar a aparência visual do item de menu. Essa opção não é válida para um item de menu de nível superior.
MF_POPUP Especifica que o item de menu tem um menu de item pop-up associado a ele. O parâmetro da ID especifica um identificador para um menu de item pop-up que deve ser associado ao item. Isso é usado para adicionar um menu de item pop-up de nível superior ou um menu de item pop-up hierárquico a um item de menu de item pop-up.
MF_SEPARATOR Desenha uma linha divisória horizontal. Pode ser usada somente em um menu de item pop-up. Essa linha não pode ser esmaecida, desabilitada ou realçada. Outros parâmetros são ignorados.
MF_STRING Especifica que o item de menu é uma cadeia de caracteres.

Cada um dos seguintes grupos lista sinalizadores mutuamente exclusivos e que não podem ser usados em conjunto:

MF_DISABLED, MF_ENABLED e MF_GRAYED
MF_STRING, MF_OWNERDRAW, MF_SEPARATOR e a versão do bitmap
MF_MENUBARBREAK e MF_MENUBREAK
MF_CHECKED e MF_UNCHECKED

Sempre que um menu que reside em uma janela é alterado (exibindo ou não a janela), o aplicativo deve chamar CWnd::DrawMenuBar.

Exemplo

Confira o exemplo de CMenu::CreateMenu.

`CMenu::Attach`

Anexa um menu existente do Windows a um objeto CMenu.

BOOL Attach(HMENU hMenu);

Parâmetros

hMenu
Especifica um identificador para um menu do Windows.

Valor de retorno

Diferente de zero se a operação foi bem-sucedida; caso contrário, 0.

Comentários

Essa função não deve ser chamada se um menu já estiver anexado ao objeto CMenu. O identificador de menu é armazenado no membro de dados m_hMenu.

Se o menu que você deseja manipular já estiver associado a uma janela, você pode usar a função CWnd::GetMenu para obter um identificador no menu.

Exemplo

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`

Adiciona ou remove marcas de seleção de itens de menu no menu de item pop-up.

UINT CheckMenuItem(
    UINT nIDCheckItem,
    UINT nCheck);

Parâmetros

nIDCheckItem
Especifica o item de menu a ser selecionado, conforme determinado por nCheck.

nCheck
Especifica como selecionar o item de menu e como determinar a posição do item no menu. O parâmetro nCheck pode ser uma combinação de MF_CHECKED ou MF_UNCHECKED com sinalizadores MF_BYPOSITION ou MF_BYCOMMAND. Esses sinalizadores podem ser combinados usando o operador bit a bit OR. Eles têm os seguintes significados:

MF_BYCOMMAND Especifica que o parâmetro fornece a ID de comando do item de menu existente. Esse é o padrão.
MF_BYPOSITION Especifica que o parâmetro fornece a posição do item de menu existente. O primeiro item está na posição 0.
MF_CHECKED Atua como um alternância para MF_UNCHECKED colocar a marca de seleção padrão próxima ao item.
MF_UNCHECKED Atua como um alternância para MF_CHECKED remover uma marca de seleção próxima ao item.

Valor de retorno

O estado anterior do item: MF_CHECKED, MF_UNCHECKED, ou 0xFFFFFFFF caso o item de menu não exista.

Comentários

O parâmetro nIDCheckItem especifica o item a ser modificado.

O parâmetro nIDCheckItem pode identificar um item de menu de item pop-up, bem como um item de menu. Nenhuma etapa especial é necessária para verificar um item de menu de item pop-up. Itens de menu de nível superior não podem ser selecionados. Um item de menu de item pop-up deve ser selecionado por posição, pois ele não tem um identificador de item de menu associado a ele.

Exemplo

Confira o exemplo de CMenu::GetMenuState.

`CMenu::CheckMenuRadioItem`

Seleciona um item de menu especificado e o torna um item de opção.

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

Parâmetros

nIDFirst
Especifica (como uma ID ou deslocamento, dependendo do valor de nFlags) o primeiro item de menu no grupo de botões de opção.

nIDLast
Especifica (como uma ID ou deslocamento, dependendo do valor de nFlags) o último item de menu no grupo de botões de opção.

nIDItem
Especifica (como uma ID ou deslocamento, dependendo do valor de nFlags) o item no grupo que será selecionado com um botão de opção.

nFlags
Especifica a interpretação de nIDFirst, nIDLast e nIDItem da seguinte maneira:

nFlags	Interpretação
`MF_BYCOMMAND`	Especifica que o parâmetro fornece a ID de comando do item de menu existente. Esse é o padrão caso `MF_BYCOMMAND` nem `MF_BYPOSITION` seja definido.
`MF_BYPOSITION`	Especifica que o parâmetro fornece a posição do item de menu existente. O primeiro item está na posição 0.

Valor de retorno

Diferente de zero se tiver êxito. Caso contrário, 0

Comentários

Ao mesmo tempo, a função desmarca todos os outros itens de menu no grupo associado e limpa o sinalizador de tipo de item de opção para esses itens. O item selecionado é exibido usando um bitmap de botão de opção (ou marcador) em vez de um bitmap de marca de seleção.

Exemplo

Confira o exemplo de ON_COMMAND_RANGE.

`CMenu::CMenu`

Cria um menu vazio e o anexa a um objeto CMenu.

CMenu();

Comentários

O menu não é criado até que você chame uma das funções membro de criação ou carregamento de CMenu:

CreateMenu
CreatePopupMenu
LoadMenu
LoadMenuIndirect
Attach

`CMenu::CreateMenu`

Cria um menu e o anexa ao objeto CMenu.

BOOL CreateMenu();

Valor de retorno

Diferente de zero se o menu foi criado com êxito. Caso contrário, 0.

Comentários

O menu inicialmente está vazio. Itens de menu podem ser adicionados usando a função membro AppendMenu ou InsertMenu.

Se o menu estiver atribuído a uma janela, ele será destruído automaticamente quando a janela é destruída.

Antes de sair, um aplicativo deve liberar recursos do sistema associados a um menu se o menu não estiver atribuído a uma janela. Um aplicativo libera um menu chamando a função membro DestroyMenu.

Exemplo

// 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`

Cria um menu de item pop-up e o anexa ao objeto CMenu.

BOOL CreatePopupMenu();

Valor de retorno

Diferente de zero se o menu de item pop-up foi criado com êxito. Caso contrário, 0.

Comentários

O menu inicialmente está vazio. Itens de menu podem ser adicionados usando a função membro AppendMenu ou InsertMenu. O aplicativo pode adicionar o menu de item pop-up a um menu ou menu de item pop-up existente. A função membro TrackPopupMenu pode ser usada para exibir esse menu como um menu de item pop-up flutuante e para acompanhar seleções no menu de item pop-up.

Se o menu estiver atribuído a uma janela, ele será destruído automaticamente quando a janela é destruída. Se o menu for adicionado a um menu existente, ele será destruído automaticamente quando esse menu for destruído.

Antes de sair, um aplicativo deve liberar recursos do sistema associados a um menu de item pop-up se o menu não estiver atribuído a uma janela. Um aplicativo libera um menu chamando a função membro DestroyMenu.

Exemplo

Confira o exemplo de CMenu::CreateMenu.

`CMenu::DeleteMenu`

Exclui um item do menu.

BOOL DeleteMenu(
    UINT nPosition,
    UINT nFlags);

Parâmetros

nPosition
Especifica o item de menu que será excluído, conforme determinado por nFlags.

nFlags
É usado para interpretar nPosition da seguinte maneira:

`nFlags`	Interpretação de `nPosition`
`MF_BYCOMMAND`	Especifica que o parâmetro fornece a ID de comando do item de menu existente. Esse é o padrão caso `MF_BYCOMMAND` nem `MF_BYPOSITION` seja definido.
`MF_BYPOSITION`	Especifica que o parâmetro fornece a posição do item de menu existente. O primeiro item está na posição 0.

Valor de retorno

Diferente de zero se a função for bem-sucedida; caso contrário, 0.

Comentários

Se o item de menu tiver um menu de item pop-up associado, DeleteMenu destruirá o identificador do menu de item pop-up e liberará a memória usada pelo menu de item pop-up.

Sempre que um menu que reside em uma janela é alterado (exibindo ou não a janela), o aplicativo pode chamar CWnd::DrawMenuBar.

Exemplo

Confira o exemplo de CWnd::GetMenu.

`CMenu::DeleteTempMap`

Chamado automaticamente pelo manipulador de tempo ocioso CWinApp, exclui todos os objetos CMenu temporários criados pela função membro FromHandle.

static void PASCAL DeleteTempMap();

Comentários

DeleteTempMap desanexa o objeto de menu do Windows anexado a um objeto CMenu temporário antes de excluir o objeto CMenu.

Exemplo

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

`CMenu::DestroyMenu`

Destrói o menu e todos os recursos do Windows que foram usados.

BOOL DestroyMenu();

Valor de retorno

Diferente de zero se o menu for destruído, Caso contrário, 0.

Comentários

O menu é desanexado do objeto CMenu antes de ser destruído. A função DestroyMenu do Windows é chamada automaticamente no destruidor CMenu.

Exemplo

Confira o exemplo de CMenu::CreateMenu.

`CMenu::Detach`

Desanexa um menu do Windows de um objeto CMenu e retorna o identificador.

HMENU Detach();

Valor de retorno

O identificador, de tipo HMENU para um menu do Windows, se bem-sucedido. Caso contrário NULL.

Comentários

O membro de dados m_hMenu está definido como NULL.

Exemplo

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`

Chamado pela estrutura quando um aspecto visual de um menu desenhado pelo proprietário é alterado.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parâmetros

lpDrawItemStruct
Um ponteiro para uma estrutura DRAWITEMSTRUCT que contém informações sobre o tipo de desenho necessário.

Comentários

O membro itemAction da estrutura DRAWITEMSTRUCT define a ação de desenho a ser executada. Substitua essa função de membro para implementar o desenho para um objeto CMenu desenhado pelo proprietário. O aplicativo deverá restaurar todos os objetos GDI (Graphics Device Interface) selecionados para o contexto de exibição fornecido em lpDrawItemStruct antes do encerramento dessa função membro.

Confira CWnd::OnDrawItem para uma descrição da estrutura DRAWITEMSTRUCT.

Exemplo

O código a seguir é da amostra CTRLTEST do 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, desabilita ou esmaece um item de menu.

UINT EnableMenuItem(
    UINT nIDEnableItem,
    UINT nEnable);

Parâmetros

nIDEnableItem
Especifica o item de menu a ser habilitado, conforme determinado por nEnable. Esse parâmetro pode especificar itens de menu pop-up, bem como itens de menu padrão.

nEnable
Especifica a ação a ser tomada. Pode ser uma combinação de MF_DISABLED, MF_ENABLED ou MF_GRAYED com MF_BYCOMMAND ou MF_BYPOSITION. Esses valores podem ser combinados usando o operador OR bit a bit C++ (|). Esses valores têm estes significados:

MF_BYCOMMAND Especifica que o parâmetro fornece a ID de comando do item de menu existente. Esse é o padrão.
MF_BYPOSITION Especifica que o parâmetro fornece a posição do item de menu existente. O primeiro item está na posição 0.
MF_DISABLED Desabilita o item de menu para que ele não possa ser selecionado, mas não o esmaece.
MF_ENABLED Habilita o item de menu para que ele possa ser selecionado e o restaura de seu estado esmaecido.
MF_GRAYED Desabilita o item de menu para que ele não possa ser selecionado e o esmaece.

Valor de retorno

Estado anterior (MF_DISABLED, MF_ENABLED ou MF_GRAYED) ou -1, se não for válido.

Comentários

As funções membro CreateMenu, InsertMenu, ModifyMenu e LoadMenuIndirect também podem definir o estado (habilitado, desabilitado ou esmaecido) de um item de menu.

Usar o valor MF_BYPOSITION requer um aplicativo para usar o CMenu correto. Se o CMenu da barra de menus for usado, um item de menu de nível superior (um item na barra de menus) será afetado. Para definir o estado de um item em um menu de item pop-up ou item pop-up aninhado por posição, um aplicativo deve especificar o CMenu do menu de item pop-up.

Quando um aplicativo especifica o sinalizador MF_BYCOMMAND, o Windows marca todos os itens de menu de item pop-up subordinados ao CMenu; portanto, é o bastante usar o CMenu da barra de menus, a menos que existam itens de menu duplicados.

Exemplo

// 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`

Retorna um ponteiro para um objeto CMenu, dado um identificador do Windows para um menu.

static CMenu* PASCAL FromHandle(HMENU hMenu);

Parâmetros

hMenu
Um identificador do Windows para um menu.

Valor de retorno

Um ponteiro para um CMenu que pode ser temporário ou permanente.

Comentários

Se um objeto CMenu não estiver anexado ao objeto de menu do Windows, um objeto CMenu temporário será criado e anexado.

Esse objeto CMenu temporário é válido somente até a próxima vez que o aplicativo tiver tempo ocioso em seu loop de eventos, momento em que todos os objetos temporários são excluídos.

Exemplo

Confira o exemplo de CMenu::CreateMenu.

`CMenu::GetDefaultItem`

Determina o item de menu padrão no menu especificado.

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

Parâmetros

gmdiFlags
Valor que especifica como a função procura itens de menu. Esse parâmetro pode ser nenhum, um ou uma combinação dos seguintes valores:

Valor	Significado
`GMDI_GOINTOPOPUPS`	Especifica que, se o item padrão for aquele que abre um submenu, a função servirá para pesquisar no submenu correspondente recursivamente. Se o submenu não tiver nenhum item padrão, o valor retornado identificará o item que abre o submenu. Por padrão, a função retorna o primeiro item padrão no menu especificado, independentemente de ser um item que abre um submenu.
`GMDI_USEDISABLED`	Especifica que a função deve retornar um item padrão, mesmo que esteja desabilitada. Por padrão, a função ignora itens desabilitados ou esmaecidos.

fByPos
Valor que especifica se deve ser recuperado o identificador do item de menu ou sua posição. Se esse parâmetro for FALSE, o identificador será retornado. Caso contrário, a posição será retornada.

Valor de retorno

Se a função for bem-sucedida, o valor retornado será o identificador ou a posição do item de menu. Se a função falhar, o valor retornado será - 1.

Comentários

Essa função membro implementa o comportamento da função do Win32 GetMenuDefaultItem, conforme descrito no SDK do Windows.

Exemplo

Confira o exemplo de CMenu::InsertMenu.

`CMenu::GetMenuContextHelpId`

Recupera a ID de ajuda de contexto associada ao CMenu.

DWORD GetMenuContextHelpId() const;

Valor de retorno

A ID de ajuda de contexto atualmente associada ao CMenu se ele tiver uma. Caso contrário, zero.

Exemplo

Confira o exemplo de CMenu::InsertMenu.

`CMenu::GetMenuInfo`

Recupera informações para um menu.

BOOL GetMenuInfo(LPMENUINFO lpcmi) const;

Parâmetros

lpcmi
Um ponteiro para uma estrutura MENUINFO que contém informações para o menu.

Valor de retorno

Se a função for bem-sucedida, o valor retornado será diferente de zero. Caso contrário, o valor retornado será zero.

Comentários

Chamar essa função para recuperar informações sobre o menu.

`CMenu::GetMenuItemCount`

Determina o número de itens em um menu de item pop-up ou de nível superior.

UINT GetMenuItemCount() const;

Valor de retorno

O número de itens no menu se a função for bem-sucedida. Caso contrário, -1.

Exemplo

Confira o exemplo de CWnd::GetMenu.

`CMenu::GetMenuItemID`

Obtém o identificador de item de menu para um item de menu localizado na posição definida por nPos.

UINT GetMenuItemID(int nPos) const;

Parâmetros

nPos
Especifica a posição (baseada em zero) do item de menu cuja ID está sendo recuperada.

Valor de retorno

A ID do item especificado em um menu de item pop-up se a função for bem-sucedida. Se o item especificado for um menu de item pop-up (em vez de um item no menu de item pop-up), o valor retornado será -1. Se nPos corresponder a um item de menu SEPARATOR, o valor retornado será 0.

Exemplo

Confira o exemplo de CMenu::InsertMenu.

`CMenu::GetMenuItemInfo`

Recupera informações sobre um item de menu.

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

Parâmetros

uItem
Identificador ou posição do item de menu sobre o qual obter informações. O significado desse parâmetro depende do valor de ByPos.

lpMenuItemInfo
Um ponteiro para um MENUITEMINFO, conforme descrito no SDK do Windows, que contém informações sobre o menu.

fByPos
Valor que especifica o significado de nIDItem. Por padrão, ByPos é FALSE, o que indica que uItem é um identificador de item de menu. Se ByPos não for definido como FALSE, ele indicará uma posição de item de menu.

Valor de retorno

Se a função for bem-sucedida, o valor retornado será diferente de zero. Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, use a função do Win32 GetLastError, conforme descrito no SDK do Windows.

Comentários

Essa função membro implementa o comportamento da função do Win32 GetMenuItemInfo, conforme descrito no SDK do Windows. Observe que, na implementação de GetMenuItemInfo do MFC, você não usa um identificador para um menu.

Exemplo

// 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`

Retorna o status do item de menu especificado ou o número de itens em um menu de item pop-up.

UINT GetMenuState(
    UINT nID,
    UINT nFlags) const;

Parâmetros

nID
Especifica a ID do item de menu, conforme determinado por nFlags.

nFlags
Especifica a natureza de nID. Pode ser um dos seguintes valores:

MF_BYCOMMAND Especifica que o parâmetro fornece a ID de comando do item de menu existente. Esse é o padrão.
MF_BYPOSITION Especifica que o parâmetro fornece a posição do item de menu existente. O primeiro item está na posição 0.

Valor de retorno

O valor 0xFFFFFFFF, se o item especificado não existir. Se nId identificar um menu de item pop-up, o byte de ordem superior conterá o número de itens no menu de item pop-up e o byte de ordem inferior conterá os sinalizadores de menu associados ao menu de item pop-up. Caso contrário, o valor retornado é uma máscara (Booliano OR) dos valores da lista a seguir (essa máscara descreve o status do item de menu que nId identifica):

MF_CHECKED Atua como um alternância para MF_UNCHECKED colocar a marca de seleção padrão próxima ao item. Quando o aplicativo fornece bitmaps de marca de seleção (consulte a função membro SetMenuItemBitmaps), o bitmap "marca de seleção ativada" é exibido.
MF_DISABLED Desabilita o item de menu para que ele não possa ser selecionado, mas não o esmaece.
MF_ENABLED Habilita o item de menu para que ele possa ser selecionado e o restaura de seu estado esmaecido. Observe que o valor dessa constante é 0. Um aplicativo não deve testar contra 0 para falha ao usar esse valor.
MF_GRAYED Desabilita o item de menu para que ele não possa ser selecionado e o esmaece.
MF_MENUBARBREAK Coloca o item em uma nova linha em menus estáticos ou em uma nova coluna em menus de item pop-up. A nova coluna de menu de item pop-up será separada da coluna antiga por uma linha divisória vertical.
MF_MENUBREAK Coloca o item em uma nova linha em menus estáticos ou em uma nova coluna em menus de item pop-up. Nenhuma linha divisória é colocada entre as colunas.
MF_SEPARATOR Desenha uma linha divisória horizontal. Pode ser usada somente em um menu de item pop-up. Essa linha não pode ser esmaecida, desabilitada ou realçada. Outros parâmetros são ignorados.
MF_UNCHECKED Atua como um alternância para MF_CHECKED remover uma marca de seleção próxima ao item. Quando o aplicativo fornece bitmaps de marca de seleção (consulte a função membro SetMenuItemBitmaps), o bitmap "marca de seleção desativada" é exibido. Observe que o valor dessa constante é 0. Um aplicativo não deve testar contra 0 para falha ao usar esse valor.

Exemplo

// 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 o rótulo do item de menu especificado para o buffer 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 o identificador inteiro do item de menu ou o deslocamento do item de menu no menu, dependendo do valor de nFlags.

lpString
Aponta para o buffer que deve receber o rótulo.

rString
Uma referência a um objeto CString que deve receber a cadeia de caracteres de menu copiada.

nMaxCount
Especifica o comprimento máximo (em caracteres) do rótulo que será copiado. Se o rótulo for maior que o máximo especificado em nMaxCount, os caracteres extras serão truncados.

nFlags
Especifica a interpretação do parâmetro nIDItem. Pode ser um dos seguintes valores:

`nFlags`	Interpretação de `nIDItem`
`MF_BYCOMMAND`	Especifica que o parâmetro fornece a ID de comando do item de menu existente. Esse é o padrão caso `MF_BYCOMMAND` nem `MF_BYPOSITION` seja definido.
`MF_BYPOSITION`	Especifica que o parâmetro fornece a posição do item de menu existente. O primeiro item está na posição 0.

Valor de retorno

Especifica o número real de caracteres copiados para o buffer, sem incluir o terminador nulo.

Comentários

O parâmetro nMaxCount deve ser um maior que o número de caracteres no rótulo para acomodar o caractere nulo que termina uma cadeia de caracteres.

Exemplo

Confira o exemplo de CMenu::InsertMenu.

`CMenu::GetSafeHmenu`

Retorna o HMENU encapsulamento por este CMenu objeto ou um NULL CMenu ponteiro.

HMENU GetSafeHmenu() const;

Exemplo

Confira o exemplo de CMenu::LoadMenu.

`CMenu::GetSubMenu`

Recupera o objeto CMenu de um menu de item pop-up.

CMenu* GetSubMenu(int nPos) const;

Parâmetros

nPos
Especifica a posição do menu de item pop-up contido no menu. Os valores de posição começam em 0 para o primeiro item de menu. O identificador do menu de item pop-up não pode ser usado nessa função.

Valor de retorno

Um ponteiro para um objeto CMenu cujo membro m_hMenu contém um identificador para o menu de item pop-up, caso exista um menu de item pop-up na posição determinada. Caso contrário NULL. Se um objeto CMenu não existir, será criado um temporário. O ponteiro CMenu retornado não deve ser armazenado.

Exemplo

Confira o exemplo de CMenu::TrackPopupMenu.

`CMenu::InsertMenu`

Insere um novo item de menu na posição especificada por nPosition e move outros itens ao longo do menu.

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 o item de menu antes do qual o novo item de menu deve ser inserido. O parâmetro nFlags pode ser usado para interpretar nPosition das seguintes maneiras:

`nFlags`	Interpretação de `nPosition`
`MF_BYCOMMAND`	Especifica que o parâmetro fornece a ID de comando do item de menu existente. Esse é o padrão caso `MF_BYCOMMAND` nem `MF_BYPOSITION` seja definido.
`MF_BYPOSITION`	Especifica que o parâmetro fornece a posição do item de menu existente. O primeiro item está na posição 0. Se `nPosition` for -1, o novo item de menu será acrescentado ao final do menu.

nFlags
Especifica como nPosition é interpretado e as informações sobre o estado do novo item de menu quando ele é adicionado ao menu. Para obter uma lista dos sinalizadores que podem ser definidos, consulte a função membro AppendMenu. Para especificar mais de um valor, use o operador bit a bit OR para combiná-los com o sinalizador MF_BYCOMMAND ou MF_BYPOSITION.

nIDNewItem
Especifica a ID de comando do novo item de menu ou, se nFlags for definido como MF_POPUP, o identificador de menu (HMENU) do menu de item pop-up. O parâmetro nIDNewItem será ignorado (não necessário) se nFlags for definido como MF_SEPARATOR.

lpszNewItem
Especifica o conteúdo do novo item de menu. lpszNewItem pode ser usado para interpretar nFlags das seguintes maneiras:

`nFlags`	Interpretação de `lpszNewItem`
`MF_OWNERDRAW`	Contém um valor de 32 bits fornecido pelo aplicativo que o aplicativo pode usar para manter dados adicionais associados ao item de menu. Esse valor de 32 bits está disponível para o aplicativo no membro `itemData` da estrutura fornecida pelas mensagens `WM_MEASUREITEM` e `WM_DRAWITEM`. Essas mensagens são enviadas quando o item de menu é exibido inicialmente ou alterado.
`MF_STRING`	Contém um ponteiro longo para uma cadeia de caracteres terminada em nulo. Essa é a interpretação padrão.
`MF_SEPARATOR`	O parâmetro `lpszNewItem` será ignorado (não necessário).

pBmp
Aponta para um objeto CBitmap que será usado como o item de menu.

Valor de retorno

Diferente de zero se a função for bem-sucedida; caso contrário, 0.

Comentários

O aplicativo pode especificar o estado do item de menu definindo valores em nFlags.

Sempre que um menu que reside em uma janela é alterado (exibindo ou não a janela), o aplicativo deve chamar CWnd::DrawMenuBar.

Quando nIDNewItem especifica um menu de item pop-up, ele se torna parte do menu no qual ele é inserido. Se esse menu for destruído, o menu inserido também será destruído. Um menu inserido deve ser desanexado de um objeto CMenu para evitar conflitos.

Se a janela filho da MDI (interface de vários documentos) ativa for maximizada e um aplicativo inserir um menu de item pop-up no menu do aplicativo da MDI chamando essa função e especificando o sinalizador MF_BYPOSITION, o menu será inserido uma posição mais à esquerda do que o esperado. Isso acontece porque o menu Controle da janela filho da MDI ativa é inserido na primeira posição da barra de menus da janela de quadro da MDI. Para posicionar o menu corretamente, o aplicativo deve adicionar 1 ao valor de posição que seria usado, caso contrário. Um aplicativo pode usar a mensagem WM_MDIGETACTIVE para determinar se a janela filho ativa no momento está maximizada.

Exemplo

// 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`

Insere um novo item de menu na posição especificada em um menu.

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

Parâmetros

uItem
Confira a descrição de uItem no InsertMenuItem do SDK do Windows.

lpMenuItemInfo
Confira a descrição de lpmii no InsertMenuItem do SDK do Windows.

fByPos
Confira a descrição de fByPosition no InsertMenuItem do SDK do Windows.

Comentários

Essa função encapsula InsertMenuItem, descrita no SDK do Windows.

`CMenu::LoadMenu`

Carrega um recurso de menu do arquivo executável do aplicativo e o anexa ao objeto CMenu.

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

Parâmetros

lpszResourceName
Aponta para uma cadeia de caracteres terminada em nulo que contém o nome do recurso de menu que será carregado.

nIDResource
Especifica a ID do menu do recurso de menu que será carregado.

Valor de retorno

Diferente de zero se o recurso de menu foi carregado com êxito. Caso contrário, 0.

Comentários

Exemplo

// 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`

Carrega um recurso de um modelo de menu na memória e o anexa ao objeto CMenu.

BOOL LoadMenuIndirect(const void* lpMenuTemplate);

Parâmetros

lpMenuTemplate
Aponta para um modelo de menu (que é uma estrutura MENUITEMTEMPLATEHEADER única e uma coleção de uma ou mais estruturas MENUITEMTEMPLATE). Para obter mais informações sobre essas duas estruturas, consulte o SDK do Windows.

Valor de retorno

Diferente de zero se o recurso de menu foi carregado com êxito. Caso contrário, 0.

Comentários

Um modelo de menu é um cabeçalho seguido por uma coleção de uma ou mais estruturas MENUITEMTEMPLATE, cada uma delas pode conter um ou mais itens de menu e menus de item pop-up.

O número da versão deve ser 0.

Os sinalizadores mtOption devem incluir MF_END para o último item em uma lista de item pop-up e para o último item na lista principal. Consulte a função de membro AppendMenu para obter outros sinalizadores. O membro mtId deve ser omitido da estrutura MENUITEMTEMPLATE quando MF_POPUP for especificado em mtOption.

O espaço alocado para a estrutura MENUITEMTEMPLATE deve ser grande o suficiente para mtString conter o nome do item de menu como uma cadeia de caracteres terminada em nulo.

Exemplo

// 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 o identificador HMENU no menu do Windows anexado ao objeto CMenu.

HMENU m_hMenu;

Exemplo

Confira o exemplo de CMenu::LoadMenu.

`CMenu::MeasureItem`

Chamado pela estrutura quando um menu com um estilo de desenho do proprietário é criado.

virtual void MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct);

Parâmetros

lpMeasureItemStruct
Um ponteiro para uma estrutura MEASUREITEMSTRUCT.

Comentários

Por padrão, essa função membro não faz nada. Substitua essa função de membro e preencha a estrutura MEASUREITEMSTRUCT para informar o Windows sobre as dimensões do menu.

Confira CWnd::OnMeasureItem para uma descrição da estrutura MEASUREITEMSTRUCT.

Exemplo

O código a seguir é da amostra CTRLTEST do 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`

Altera um item de menu existente na posição 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 o item de menu que será alterado. O parâmetro nFlags pode ser usado para interpretar nPosition das seguintes maneiras:

`nFlags`	Interpretação de `nPosition`
`MF_BYCOMMAND`	Especifica que o parâmetro fornece a ID de comando do item de menu existente. Esse é o padrão caso `MF_BYCOMMAND` nem `MF_BYPOSITION` seja definido.
`MF_BYPOSITION`	Especifica que o parâmetro fornece a posição do item de menu existente. O primeiro item está na posição 0.

nFlags
Especifica como nPosition é interpretado e fornece informações sobre as alterações a serem feitas no item de menu. Para obter uma lista de sinalizadores que podem ser definidos, consulte a função membro AppendMenu.

nIDNewItem
Especifica a ID de comando do item de menu modificado ou, se nFlags for definido como MF_POPUP, o identificador de menu (HMENU) de um menu de item pop-up. O parâmetro nIDNewItem será ignorado (não necessário) se nFlags for definido como MF_SEPARATOR.

lpszNewItem
Especifica o conteúdo do novo item de menu. O parâmetro nFlags pode ser usado para interpretar lpszNewItem das seguintes maneiras:

`nFlags`	Interpretação de `lpszNewItem`
`MF_OWNERDRAW`	Contém um valor de 32 bits fornecido pelo aplicativo que o aplicativo pode usar para manter dados adicionais associados ao item de menu. Esse valor de 32 bits está disponível para o aplicativo quando ele processa `MF_MEASUREITEM` e `MF_DRAWITEM`.
`MF_STRING`	Contém um ponteiro longo para uma cadeia de caracteres terminada em nulo ou para uma `CString`.
`MF_SEPARATOR`	O parâmetro `lpszNewItem` será ignorado (não necessário).

pBmp
Aponta para um objeto CBitmap que será usado como o item de menu.

Valor de retorno

Diferente de zero se a função for bem-sucedida; caso contrário, 0.

Comentários

O aplicativo especifica o estado novo do item de menu definindo valores em nFlags. Se essa função substituir um menu de item pop-up associado ao item de menu, ela destruirá o menu de item pop-up antigo e liberará a memória usada por ele.

Sempre que um menu que reside em uma janela é alterado (exibindo ou não a janela), o aplicativo deve chamar CWnd::DrawMenuBar. Para alterar os atributos dos itens de menu existentes, é muito mais rápido usar as funções membro CheckMenuItem e EnableMenuItem.

Exemplo

Confira o exemplo de CMenu::InsertMenu.

`CMenu::operator HMENU`

Use esse operador para recuperar o identificador do objeto CMenu.

operator HMENU() const;

Valor de retorno

Se tiver êxito, o identificador do objeto CMenu; caso contrário, NULL.

Comentários

Você pode usar o identificador para chamar as APIs do Windows diretamente.

`CMenu::operator !=`

Determina se dois menus são logicamente diferentes.

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

Parâmetros

menu
Um objeto CMenu para comparação.

Comentários

Testa se um objeto de menu à esquerda é diferente do objeto de menu à direita.

`CMenu::operator ==`

Determina se dois menus são logicamente iguais.

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

Parâmetros

menu
Um objeto CMenu para comparação.

Comentários

Testa se um objeto de menu à esquerda é igual (em termos de valor HMENU) a um objeto de menu à direita.

`CMenu::RemoveMenu`

Exclui um item de menu com um menu de item pop-up associado do menu.

BOOL RemoveMenu(
    UINT nPosition,
    UINT nFlags);

Parâmetros

nPosition
Especifica o item de menu que será removido. O parâmetro nFlags pode ser usado para interpretar nPosition das seguintes maneiras:

`nFlags`	Interpretação de `nPosition`
`MF_BYCOMMAND`	Especifica que o parâmetro fornece a ID de comando do item de menu existente. Esse é o padrão caso `MF_BYCOMMAND` nem `MF_BYPOSITION` seja definido.
`MF_BYPOSITION`	Especifica que o parâmetro fornece a posição do item de menu existente. O primeiro item está na posição 0.

nFlags
Especifica como nPosition é interpretado.

Valor de retorno

Diferente de zero se a função for bem-sucedida; caso contrário, 0.

Comentários

Ele não destrói o identificador de um menu de item pop-up, portanto, o menu pode ser reutilizado. Antes de chamar essa função, o aplicativo pode chamar a função membro GetSubMenu para recuperar o objeto de item pop-up CMenu para reutilização.

Sempre que um menu que reside em uma janela é alterado (exibindo ou não a janela), o aplicativo pode chamar CWnd::DrawMenuBar.

Exemplo

Confira o exemplo de CMenu::InsertMenu.

`CMenu::SetDefaultItem`

Define o item de menu padrão para o menu especificado.

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

Parâmetros

uItem
Identificador ou posição do novo item de menu padrão ou - 1 para nenhum item padrão. O significado desse parâmetro depende do valor de fByPos.

fByPos
Valor que especifica o significado de uItem. Se esse parâmetro for FALSE, uItem será um identificador de item de menu. Caso contrário, é uma posição de item de menu.

Valor de retorno

Comentários

Essa função membro implementa o comportamento da função do Win32 SetMenuDefaultItem, conforme descrito no SDK do Windows.

Exemplo

Confira o exemplo de CMenu::InsertMenu.

`CMenu::SetMenuContextHelpId`

Associa uma ID de ajuda de contexto ao CMenu.

BOOL SetMenuContextHelpId(DWORD dwContextHelpId);

Parâmetros

dwContextHelpId
ID de ajuda de contexto a ser associada ao CMenu.

Valor de retorno

Diferente de zero se tiver êxito. Caso contrário, 0

Comentários

Todos os itens no menu compartilham esse identificador — não é possível anexar um identificador de contexto de ajuda aos itens de menu individuais.

Exemplo

Confira o exemplo de CMenu::InsertMenu.

`CMenu::SetMenuInfo`

Define informações para um menu.

BOOL SetMenuInfo(LPCMENUINFO lpcmi);

Parâmetros

lpcmi
Um ponteiro para uma estrutura MENUINFO que contém informações para o menu.

Valor de retorno

Se a função for bem-sucedida, o valor retornado será diferente de zero. Caso contrário, o valor retornado será zero.

Comentários

Chamar essa função para definir informações específicas sobre o menu.

`CMenu::SetMenuItemBitmaps`

Associa os bitmaps especificados a um item de menu.

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

Parâmetros

nPosition
Especifica o item de menu que será alterado. O parâmetro nFlags pode ser usado para interpretar nPosition das seguintes maneiras:

`nFlags`	Interpretação de nPosition
`MF_BYCOMMAND`	Especifica que o parâmetro fornece a ID de comando do item de menu existente. Esse é o padrão caso `MF_BYCOMMAND` nem `MF_BYPOSITION` seja definido.
`MF_BYPOSITION`	Especifica que o parâmetro fornece a posição do item de menu existente. O primeiro item está na posição 0.

nFlags
Especifica como nPosition é interpretado.

pBmpUnchecked
Especifica o bitmap a ser usado em itens de menu que não estão selecionados.

pBmpChecked
Especifica o bitmap a ser usado em itens de menu que estão selecionados.

Valor de retorno

Diferente de zero se a função for bem-sucedida; caso contrário, 0.

Comentários

Se o item de menu estiver selecionado ou desmarcado, o Windows exibirá o bitmap apropriado próximo ao item de menu.

Se for pBmpUnchecked ou pBmpChecked será NULL, o Windows não exibirá nada ao próximo ao item de menu do atributo correspondente. Se os dois parâmetros forem NULL, o Windows usará a marca de seleção padrão quando o item for selecionado e removerá a marca de seleção quando o item estiver desmarcado.

Quando o menu é destruído, esses bitmaps não são destruídos; o aplicativo deve destruí-los.

A função GetMenuCheckMarkDimensions do Windows recupera as dimensões da marca de seleção padrão usada para itens de menu. O aplicativo usa esses valores para determinar o tamanho apropriado para os bitmaps fornecidos com essa função. Obtenha o tamanho, crie seus bitmaps e, em seguida, defina-os.

Exemplo

// 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`

Altera informações sobre um item de menu.

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

Parâmetros

uItem
Confira a descrição de uItem no SetMenuItemInfo do SDK do Windows.

lpMenuItemInfo
Confira a descrição de lpmii no SetMenuItemInfo do SDK do Windows.

fByPos
Confira a descrição de fByPosition no SetMenuItemInfo do SDK do Windows.

Comentários

Essa função encapsula SetMenuItemInfo, descrita no SDK do Windows.

`CMenu::TrackPopupMenu`

Exibe um menu pop-up flutuante no local especificado e rastreia a seleção de itens no menu de item pop-up.

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

Parâmetros

nFlags
Especifica sinalizadores de posição de tela e de posição do mouse. Confira TrackPopupMenu para obter uma lista dos sinalizadores disponíveis.

x
Especifica a posição horizontal nas coordenadas da tela do menu de item pop-up. Dependendo do valor do parâmetro nFlags, o menu pode ser alinhado à esquerda, alinhado à direita ou centralizado em relação a essa posição.

y
Especifica a posição vertical nas coordenadas de tela da parte superior do menu na tela.

pWnd
Identifica a janela à qual o menu de item pop-up pertence. Esse parâmetro não pode ser NULL, mesmo se o sinalizador TPM_NONOTIFY for especificado. Essa janela recebe todas as mensagens WM_COMMAND do menu. No Windows versões 3.1 e posteriores, a janela não recebe mensagens WM_COMMAND até que retorne TrackPopupMenu. No Windows 3.0, a janela recebe mensagens WM_COMMAND antes de retornar TrackPopupMenu.

lpRect
Ignorado.

Valor de retorno

Esse método retorna o resultado da chamada TrackPopupMenu no SDK do Windows.

Comentários

Um menu de item pop-up flutuante pode aparecer em qualquer lugar na tela.

Exemplo

// 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`

Exibe um menu pop-up flutuante no local especificado e rastreia a seleção de itens no menu de item pop-up.

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

Parâmetros

fuFlags
Especifica várias funções para o menu estendido. Para obter uma listagem de todos os valores e seus significados, consulte TrackPopupMenuEx.

x
Especifica a posição horizontal nas coordenadas da tela do menu de item pop-up.

y
Especifica a posição vertical nas coordenadas de tela da parte superior do menu na tela.

pWnd
Um ponteiro para a janela que possui o menu de item pop-up e recebe as mensagens do menu criado. Essa janela pode ser uma janela do aplicativo atual, mas não pode ser NULL. Se você especificar TPM_NONOTIFY no parâmetro fuFlags, a função não enviará nenhuma mensagem para pWnd. A função deve retornar para a janela apontada por pWnd para receber a mensagem WM_COMMAND.

lptpm
Ponteiro para uma estrutura TPMPARAMS que especifica uma área da tela que o menu não deve sobrepor. Esse parâmetro pode ser NULL.

Valor de retorno

Se você especificar TPM_RETURNCMD no parâmetro fuFlags, o valor retornado será o identificador de item de menu do item selecionado pelo usuário. Se o usuário cancelar o menu sem fazer uma seleção ou se ocorrer um erro, o valor retornado será 0.

Se você não especificar TPM_RETURNCMD no parâmetro fuFlags, o valor retornado será diferente de zero se a função for bem-sucedida e 0 se falhar. Para obter outras informações sobre o erro, chame GetLastError.

Comentários

Um menu de item pop-up flutuante pode aparecer em qualquer lugar na tela. Para obter mais informações sobre como lidar com erros ao criar o menu de item pop-up, consulte TrackPopupMenuEx.

Confira também

Exemplo de MFC CTRLTEST
Exemplo de MFC DYNAMENU
Classe CObject
Gráfico da hierarquia

Partilhar via

Classe CMenu

Sintaxe

Membros

Construtores públicos

Métodos públicos

Operadores públicos

Membros de Dados Públicos

Comentários

Hierarquia de herança

Requisitos

CMenu::AppendMenu

Parâmetros

Valor de retorno

Comentários

Exemplo

CMenu::Attach

Parâmetros

Valor de retorno

Comentários

Exemplo

CMenu::CheckMenuItem

Parâmetros

Valor de retorno

Comentários

Exemplo

CMenu::CheckMenuRadioItem

Parâmetros

Valor de retorno

Comentários

Exemplo

CMenu::CMenu

Comentários

CMenu::CreateMenu

Valor de retorno

Comentários

Exemplo

CMenu::CreatePopupMenu

Valor de retorno

Comentários

Exemplo

CMenu::DeleteMenu

Parâmetros

Valor de retorno

Comentários

Exemplo

CMenu::DeleteTempMap

Comentários

Exemplo

CMenu::DestroyMenu

Valor de retorno

Comentários

Exemplo

CMenu::Detach

Valor de retorno

Comentários

Exemplo

CMenu::DrawItem

Parâmetros

Comentários

Exemplo

CMenu::EnableMenuItem

Parâmetros

Valor de retorno

Comentários

Exemplo

CMenu::FromHandle

Parâmetros

Valor de retorno

Comentários

Exemplo

CMenu::GetDefaultItem

Parâmetros

Valor de retorno

Comentários

Exemplo

CMenu::GetMenuContextHelpId

Valor de retorno

Exemplo

CMenu::GetMenuInfo

Classe `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`