MF_BYCOMMAND and MF_BYPOSITION BOOL ModifyMenu(hMenu,nPosition,wFlags,wIDNewItem,lpNewItem)
This function changes an existing menu item at the position specified by the nPosition parameter. The application specifies the new state of the menu item by setting values in the wFlags parameter. If this function replaces a pop-up menu associated with the menu item, it destroys the old pop-up menu and frees the memory used by the pop-up menu.
| Parameter | Type/Description |
| hMenu | HMENU Identifies the menu to be changed. | ||
| nPosition | WORD Specifies the menu item to be changed. 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. | ||
| MF_BYCOMMAND | Specifies the command ID of the existing menu item. | ||
| wFlags | WORD Specifies how the nPosition parameter is interpreted and information about the changes to be made to the menu item. It consists of one or more values listed in the following “Comments” section. | ||
| wIDNewItem | WORD Specifies either the command ID of the modified 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 changed 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 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. In order to change the attributes of existing menu items, it is much faster to use the CheckMenuItem and EnableMenuItem functions.
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 menu 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. This is the default if neither MF_BYCOMMAND nor MF_POSITION is set. | |
| 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 SetMenuItemBitmaps), 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, this flag places the item in a new column, with no dividing line between the columns. | |
| MF_OWNERDRAW | Specifies that the menu 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 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 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 menu item. Use this 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 only use this flag in a pop-up menu. This line cannot be grayed, disabled, or highlighted. The lpNewItem and wIDNewItem parameters are ignored. | |
| MF_STRING | Specifies that the menu item is a character string; the lpNewItem parameter points to the string for the menu item. | |
| MF_UNCHECKED | Does not place a checkmark next to the menu item. No checkmark is the default if neither MF_CHECKED nor MF_UNCHECKED is set. If the application has supplied checkmark bitmaps (see SetMenuItemBitmaps), setting this flag displays the “checkmark off” bitmap next to the menu item. |