MF_BYCOMMAND and MF_BYPOSITION| BOOL InsertMenu(hmenu, uItem, fuFlags, idNewItem, lpszNewItem) | |||||
| HMENU hmenu; | /* handle of menu | */ | |||
| UINT uItem; | /* menu item that new menu item is to precede | */ | |||
| UINT fuFlags; | /* menu-item flags | */ | |||
| UINT idNewItem; | /* menu-item identifier or pop-up menu handle | */ | |||
| LPCTSTR lpszNewItem; | /* menu-item content | */ | |||
The InsertMenu function inserts a new menu item into a menu, moving other items down the menu. An application can specify the content, appearance, and behavior of the menu item by setting values in the fuFlags parameter.
hmenu
Identifies the menu to be changed.
uItem
Specifies the menu item before which the new menu item is to be inserted, as determined by the fuFlags parameter.
fuFlags
Specifies flags that control the interpretation of the uItem parameter and the content, appearance, and behavior of the new menu item. This parameter can be a combination of one of the following values and the values listed in the Comments section.
| Value | Meaning |
| MF_BYCOMMAND | ||
| The uItem parameter specifies the identifier of the menu item. | ||
| MF_BYPOSITION | ||
| The uItem parameter specifies the zero-based relative position of the menu item. If uItem 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 the fuFlags parameter is set to MF_POPUP, the handle of the pop-up menu.
lpszNewItem
Specifies the content of the new menu item. The interpretation of this parameter depends on whether the fuFlags parameter includes the MF_STRING, MF_BITMAP, or MF_OWNERDRAW flag.
| Value | Menu-item content |
| MF_STRING | ||
| Contains a pointer to a null-terminated string (default). | ||
| MF_BITMAP | ||
| Contains a bitmap handle. | ||
| MF_OWNERDRAW | ||
| Contains an application-supplied 32-bit value that the application can use to maintain additional data associated with the menu item. An application can find this value in the itemData member of the structure pointed to by the lParam parameter of the WM_MEASUREITEM and WM_DRAWITEM messages that are sent when the menu item is created or when its appearance must be updated. | ||
The return value is TRUE if the function is successful or FALSE if an error occurs. To obtain extended error information, use the GetLastError function.
The InsertMenu function may be used as either a wide-character function (where text arguments must use Unicode) or an ANSI function (where text arguments must use characters from the Windows 3.x character set).
Whenever a menu changes (whether or not the menu is in a window that is displayed), the application should call the DrawMenuBar function.
The following list shows groups of flags that cannot 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 lpszNewItem parameter contains the handle of the bitmap. |
| MF_BYCOMMAND | Indicates that the uItem parameter specifies the identifier of the menu item (default). |
| MF_BYPOSITION | Indicates that the uItem parameter specifies the zero-based relative position of the new menu item. |
| MF_CHECKED | Places a check mark next to the item. If the application has provided check mark bitmaps (see the SetMenuItemBitmaps function), setting this flag displays the checked bitmap next to the menu item. |
| MF_DISABLED | Disables the menu item so that it cannot be selected, but does not gray 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 that, in pop-up menus, inserts a vertical line to separate the new column from the old column. |
| MF_MENUBREAK | Places the item on a new line (for an item in a menu-bar). For an item in a pop-up menu, places the item in a new column, with no dividing line between the columns. |
| MF_OWNERDRAW | Specifies that the item is an owner-draw item. The window that owns the menu receives a WM_MEASUREITEM message before the menu is displayed for the first time to retrieve the width and height of the menu item. The WM_DRAWITEM message is then sent to the window procedure of the owner window whenever the appearance of the menu item must be updated. |
| MF_POPUP | Specifies that the menu item is a pop-up item; that is, selecting it invokes a pop-up menu. The idNewItem parameter specifies the handle of the pop-up menu. This flag is used for adding a pop-up item to a menu bar or to a pop-up menu. |
| MF_SEPARATOR | Draws a horizontal dividing line. This flag can be used only in a pop-up menu. The dividing line cannot be grayed, disabled, or highlighted. The lpszNewItem and idNewItem parameters are ignored. |
| MF_STRING | Specifies that the menu item is a string; the lpszNewItem parameter points to the string. |
| MF_UNCHECKED | Does not place a checkmark next to the item (default). If the application has supplied check mark bitmaps (see the SetMenuItemBitmaps function), setting this flag displays the unchecked bitmap next to the menu item. |
AppendMenu, DeleteMenu, DrawMenuBar, ModifyMenu, RemoveMenu, SetMenuItemBitmaps