CMenu::InsertMenu
Inserts a new menu item at the position specified by nPosition and moves other items down the 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
);
Parameters
nPosition
Specifies the menu item before which the new menu item is to be inserted. The nFlags parameter can be used to interpret nPosition in the following ways:nFlags
Interpretation of nPosition
MF_BYCOMMAND
Specifies that the parameter gives the command ID of the existing menu item. This is the default if neither MF_BYCOMMAND nor MF_BYPOSITION is set.
MF_BYPOSITION
Specifies that the parameter gives the position of the existing menu item. The first item is at position 0. If nPosition is –1, the new menu item is appended to the end of the menu.
nFlags
Specifies how nPosition is interpreted and specifies information about the state of the new menu item when it is added to the menu. For a list of the flags that may be set, see the AppendMenu member function. To specify more than one value, use the bitwise OR operator to combine them with the MF_BYCOMMAND or MF_BYPOSITION flag.nIDNewItem
Specifies either the command ID of the new menu item or, if nFlags is set to MF_POPUP, the menu handle (HMENU) of the pop-up menu. The nIDNewItem parameter is ignored (not needed) if nFlags is set to MF_SEPARATOR.lpszNewItem
Specifies the content of the new menu item. nFlags can be used to interpret lpszNewItem in the following ways:nFlags
Interpretation of lpszNewItem
MF_OWNERDRAW
Contains an application-supplied 32-bit value that the application can use to maintain additional data associated with the menu item. This 32-bit value is available to the application in the itemData member of the structure supplied by the WM_MEASUREITEM and WM_DRAWITEM messages. These messages are sent when the menu item is initially displayed or is changed.
MF_STRING
Contains a long pointer to a null-terminated string. This is the default interpretation.
MF_SEPARATOR
The lpszNewItem parameter is ignored (not needed).
pBmp
Points to a CBitmap object that will be used as the menu item.
Return Value
Nonzero if the function is successful; otherwise 0.
Remarks
The application can specify the state of the menu item by setting values in nFlags.
Whenever a menu that resides in a window is changed (whether or not the window is displayed), the application should call CWnd::DrawMenuBar.
When nIDNewItem specifies a pop-up menu, it becomes part of the menu in which it is inserted. If that menu is destroyed, the inserted menu will also be destroyed. An inserted menu should be detached from a CMenu object to avoid conflict.
If the active multiple document interface (MDI) child window is maximized and an application inserts a pop-up menu into the MDI application's menu by calling this function and specifying the MF_BYPOSITION flag, the menu is inserted one position farther left than expected. This happens because the Control menu of the active MDI child window is inserted into the first position of the MDI frame window's menu bar. To position the menu properly, the application must add 1 to the position value that would otherwise be used. An application can use the WM_MDIGETACTIVE message to determine whether the currently active child window is maximized.
Example
// 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;
}
Requirements
Header: afxwin.h