CMenu::InsertMenu

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

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

Return Value

Nonzero if the function is successful; otherwise 0.

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.

Remarks

Inserts a new menu item at the position specified by nPosition and moves other items down the menu. 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.

CMenu Overview | Class Members | Hierarchy Chart