InsertMenu

3.0

  BOOL InsertMenu(hmenu, idItem, fuFlags, idNewItem, lpNewItem)    
  HMENU hmenu; /* handle of menu, */  
  UINT idItem; /* menu item that new menu item is to precede */
  UINT fuFlags; /* menu flags, */  
  UINT idNewItem; /* item identifier or pop-up menu handle */
  LPCSTR lpNewItem; /* item content, */  

The InsertMenu function inserts a new menu item into a menu, moving other items down the menu. The function also sets the state of the menu item.

Parameters

hmenu

Identifies the menu to be changed.

idItem

Specifies the menu item before which the new menu item is to be inserted, as determined by the fuFlags parameter.

fuFlags

Specifies how the idItem parameter is interpreted and information about the state of the new menu item when it is added to the menu. This parameter consists of a combination of one of the following values and the values listed in the Comments section.

Value Meaning

MF_BYCOMMAND The idItem parameter specifies the menu-item identifier.
MF_BYPOSITION The idItem parameter specifies the zero-based position of the menu item. If idItem is –1, the new menu item is appended to the end of the menu.

idNewItem

Specifies either the identifier of the new menu item or, if fuFlags is set to MF_POPUP, the menu handle of the pop-up menu.

lpNewItem

Specifies the contents of the new menu item. If fuFlags is set to MF_STRING (the default value), this parameter points to a null-terminated string. If fuFlags is set to MF_BITMAP instead, lpNewItem contains a bitmap handle in its low-order word. If fuFlags is set to MF_OWNERDRAW, lpNewItem specifies an application-defined 32-bit value, which 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 pointed to by the lParam parameter of the WM_MEASUREITEM and WM_DRAWITEM messages. These messages are sent when the menu item is initially displayed or is changed.

Return Value

The return value is nonzero if the function is successful. Otherwise, it is zero.

Comments

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 occurs because the System menu of the active MDI child window is inserted into the first position of the MDI frame window's menu bar. To avoid this behavior, 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.

Whenever a menu changes (whether or not the menu is in a window that is displayed), the application should call the DrawMenuBar function.

Each of the following groups lists flags that should not be used together:

MF_BYCOMMAND and MF_BYPOSITION

MF_DISABLED, MF_ENABLED, and MF_GRAYED

MF_BITMAP, MF_STRING, MF_OWNERDRAW, and MF_SEPARATOR

MF_MENUBARBREAK and MF_MENUBREAK

MF_CHECKED and MF_UNCHECKED

The following list describes the flags that may be set in the fuFlags parameter:

Value Meaning

MF_BITMAP Uses a bitmap as the item. The low-order word of the lpNewItem parameter contains the handle of the bitmap.
MF_BYCOMMAND Specifies that the idItem parameter gives the menu-item identifier (default).
MF_BYPOSITION Specifies that the idItem parameter gives the position of the menu item rather than the menu-item identifier.
MF_CHECKED Places a check mark next to (selects) the menu item. If the application has supplied check-mark bitmaps (see the SetMenuItemBitmaps function), setting this flag displays the check-mark bitmap next to the menu item.
MF_DISABLED Disables the menu item so that it cannot be selected, but does not gray (dim) it.
MF_ENABLED Enables the menu item so that it can be selected, and restores it from its grayed state.
MF_GRAYED Disables the menu item so that it cannot be selected, and grays it.
MF_MENUBARBREAK Same as MF_MENUBREAK except, for pop-up menus, separates the new column from the old column by using a vertical line.
MF_MENUBREAK Places the menu item on a new line for static menu-bar items. For pop-up menus, places the menu item in a new column, with no dividing line between the columns.
MF_OWNERDRAW Specifies that the item is an owner-drawn item. The window that owns the menu receives a WM_MEASUREITEM message (when the menu is displayed for the first time) to retrieve the height and width of the menu item. The WM_DRAWITEM message is then sent to the owner whenever the owner must update the visual appearance of the menu item. This option is not valid for a top-level menu item.
MF_POPUP Specifies that the menu item has a pop-up menu associated with it. The idNewItem parameter specifies a handle of a pop-up menu to be associated with the item. Use the MF_OWNERDRAW flag to add either a top-level pop-up menu or a hierarchical pop-up menu to a pop-up menu item.
MF_SEPARATOR Draws a horizontal dividing line. You can use this flag in a pop-up menu. This line cannot be grayed, disabled, or highlighted. Windows ignores the lpNewItem and idNewItem parameters.
MF_STRING Specifies that the menu item is a character string; the lpNewItem parameter points to the string for the item.
MF_UNCHECKED Does not place a check mark next to the item (default value). If the application has supplied check-mark bitmaps (see SetMenuItemBitmaps), setting this flag displays the check-mark-off bitmap next to the menu item.

See Also

AppendMenu, CreateMenu, DrawMenuBar, RemoveMenu, SetMenuItemBitmaps