CMenu::InsertMenu

Artigo
06/10/2015

Insere um novo item de menu na posição especificada por nPosition e move outros itens abaixo 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 de que o novo item de menu deve ser inserido. O parâmetro de nFlags pode ser usado para interpretar das seguintes maneiras: nPosition

nFlags	Interpretação de nPosition
MF_BYCOMMAND	Especifica que o parâmetro fornece a identificação do comando de menu item existente. Esta é a opção se nem nem MF_BYCOMMANDMF_BYPOSITION são definidos.
MF_BYPOSITION	Especifica que o parâmetro retorna a posição do item de menu existente. O primeiro item está na posição 0. Se nPosition é – 1, o novo item de menu está acrescentada ao final do menu.

nFlags
Especifica como nPosition é interpretado e especifica informações sobre o estado do novo item de menu quando é adicionada ao menu. Para obter uma lista dos sinalizadores que podem ser definidos, consulte a função de membro de AppendMenu . Para especificar mais de um valor, use o operador OR bit a bit para combiná-las com o sinalizador de MF_BYCOMMAND ou de MF_BYPOSITION .
nIDNewItem
Especifica a identificação de comando do novo item de menu ou, se nFlags é definido como MF_POPUP, a alça de menu (HMENUde menus pop-up.) O parâmetro de nIDNewItem é ignorado (não necessariamente) se nFlags é definido como MF_SEPARATOR.

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

nFlags	Interpretação de lpszNewItem
MF_OWNERDRAW	Contém um valor de 32 bits do aplicativo fornecido que o aplicativo possa usar para manter os dados adicionais associados com o item de menu. Este valor de 32 bits está disponível para o aplicativo no itemData membro de estrutura fornecida pelas mensagens de WM_MEASUREITEM e de WM_DRAWITEM . Essas mensagens são enviadas quando o item de menu inicialmente é exibido ou alterado.
MF_STRING	Contém um ponteiro para uma longa cadeia de caracteres NULL- finalizada. Esta é a interpretação padrão.
MF_SEPARATOR	O parâmetro de lpszNewItem é ignorado (não necessariamente).

pBmp
Os pontos a CBitmap objeto que será usado como o item de menu.

Valor de retorno

Diferente de zero se a função é com êxito; se não 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 (se a janela é exibida), o aplicativo deve chamar CWnd::DrawMenuBar.

Quando nIDNewItem especifica um menu pop-up, ela se torna parte do menu em que é inserido. Se o menu é destruído, o menu será destruído também inserido. Um menu inserido deve ser desanexado de um objeto de CMenu para evitar o conflito.

Se a janela filho ativa de (MDI) de interface de documentos múltiplos são maximizadas e insere um aplicativo de um menu pop-up no menu do aplicativo MDI essa função chamando e especificando o sinalizador de MF_BYPOSITION , menu é inserido um extrema esquerda da posição do que o esperado. Isso acontece porque o menu de controle da janela filho MDI ativa é inserido na primeira posição da barra de menus da janela do quadro MDI. Para posicionar corretamente o menu, o aplicativo deve adicionar 1 para valor da posição que seria usado caso contrário. Um aplicativo pode usar a mensagem de WM_MDIGETACTIVE para determinar se a janela filho ativa no momento estiver 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;
}