CMenu::InsertMenu

Artículo
06/10/2015

Inserta un nuevo elemento de menú en la posición especificada por nPosition y mueve otros elementos desde 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 de que el nuevo elemento de menú se va a insertar. El parámetro de nFlags se puede utilizar para interpretar nPosition de las maneras siguientes:

nFlags	Interpretación de nPosition
MF_BYCOMMAND	Especifica que el parámetro proporciona el identificador del elemento de menú existente. Éste 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 es nPosition – 1, el nuevo elemento de menú se anexa al final del menú.

nFlags
Especifica cómo se interpreta nPosition y especifica la información sobre el estado del nuevo elemento de menú cuando se agrega al menú. Para obtener una lista de los marcadores que se pueden establecer, vea la función miembro de AppendMenu trabajar. Para especificar más de un valor, utilice el operador OR bit a bit para combinarlos con el marcador de MF_BYCOMMAND o de MF_BYPOSITION .
nIDNewItem
Especifica el identificador de comando del nuevo elemento de menú o, si nFlags se establece en MF_POPUP, el identificador de menú (HMENU) del elemento emergente. Se omite el parámetro de nIDNewItem (no necesario) si nFlags se establece en MF_SEPARATOR.

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

nFlags	Interpretación de lpszNewItem
MF_OWNERDRAW	Contiene un valor de 32 bits aplicación-proporcionado que la aplicación pueda utilizar para mantener los datos adicionales asociados con el elemento de menú. Este valor de 32 bits está disponible para la aplicación en el miembro de itemData de la estructura proporcionada por los mensajes de WM_MEASUREITEM y de WM_DRAWITEM . Se envían estos mensajes cuando el elemento de menú se muestra o se modifica inicialmente.
MF_STRING	Contiene un puntero largo en una cadena terminada en null. ésta es la interpretación predeterminada.
MF_SEPARATOR	Se omite el parámetro de lpszNewItem (no necesario).

pBmp
Señala a un objeto de CBitmap que se utilizará como el elemento de menú.

Valor devuelto

Distinto de cero si la función es correcta; si no 0.

Comentarios

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

Siempre que se cambie un menú que residen en una ventana (si la ventana se muestra), la aplicación debe llamar a CWnd::DrawMenuBar.

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

Si se maximiza la ventana (MDI) secundaria activa de la interfaz de múltiples documentos y una aplicación inserta un menú emergente en el menú de la aplicación MDI llamando a esta función y especificando la marca de MF_BYPOSITION , el menú se inserta un izquierdo más alejada colocar de lo esperado. Esto ocurre porque el menú de Control de la ventana MDI secundaria de activo se inserta en la primera posición de la barra de menús de MDI de la ventana de marco. Para colocar el menú correctamente, la aplicación debe agregar 1 al valor de la posición que normalmente se de otra manera. Una aplicación puede utilizar el mensaje de WM_MDIGETACTIVE para determinar si actualmente se maximiza la ventana secundaria activa.

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;
}