MF_BYCOMMAND and MF_BYPOSITION BOOL InsertMenu(hMenu,nPosition,wFlags,wIDNewItem,lpNewItem)
This function inserts a new menu item at the position specified by the nPosition parameter, moving other items down the menu. The application can specify the state of the menu item by setting values in the wFlags parameter.
| Parameter | Type/Description |
| hMenu | HMENU Identifies the menu to be changed. | ||
| nPosition | WORD Specifies the menu item before which the new menu item is to be inserted. The interpretation of the nPosition parameter depends upon the setting of the wFlags parameter. | ||
| If wFlags is: | nPosition: | ||
| MF_BYPOSITION | Specifies the position of the existing menu item. The first item in the menu is at position zero. | ||
| If nPosition is –1, the new menu item is appended to the end of the menu. | |||
| MF_BYCOMMAND | Specifies the command ID of the existing menu item. | ||
| wFlags | WORD Specifies how the nPosition parameter is interpreted and information about the state of the new menu item when it is added to the menu. It consists of one or more values listed in the following “Comments” section. | ||
| wIDNewItem | WORD Specifies either the command ID of the new menu item or, if wFlags is set to MF_POPUP, the menu handle of the pop-up menu. | ||
| lpNewItem | LPSTR Specifies the content of the new menu item. If wFlags is set to MF_STRING (the default), then lpNewItem is a long pointer to a null-terminated character string. If wFlags is set to MF_BITMAP instead, then lpNewItem contains a bitmap handle (HBITMAP) in its low-order word. If wFlags is set to MF_OWNERDRAW, lpNewItem specifies an application-supplied 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 field of the data structure pointed to by the lParam parameter of the following messages: | ||
| WM_MEASUREITEM WM_DRAWITEM | |||
| These messages are sent when the menu item is initially displayed, or is changed. | |||
The return value specifies the outcome of the function. It is TRUE if the function is successful. Otherwise, it is FALSE.
Whenever a menu changes (whether or not the menu resides in a window that is displayed), the application should call DrawMenuBar.
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 which may be set in the wFlags 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 nPosition parameter gives the menu-item control ID number (default). | |
| MF_BYPOSITION | Specifies that the nPosition parameter gives the position of the menu item to be changed rather than an ID number. | |
| MF_CHECKED | Places a checkmark next to the menu item. If the application has supplied checkmark bitmaps (see the SetMenuItemBitmaps function), setting this flag displays the “checkmark on” 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 for pop-up menus, separates the new column from the old column with 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-draw 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 wIDNewItem parameter specifies a handle to 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 wIDNewItem 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 checkmark next to the item (default). If the application has supplied checkmark bitmaps (see SetMenuItemBitmaps), setting this flag displays the “checkmark off” bitmap next to the menu item. |