The ModifyMenu function changes an existing menu item. This function is used to specify the content, appearance, and behavior of the menu item.
The ModifyMenu function has been superseded by the SetMenuItemInfo function. You can still use ModifyMenu, however, if you do not need any of the extended features of SetMenuItemInfo.
BOOL ModifyMenu(
HMENU hMnu, |
// handle of menu |
UINT uPosition, |
// menu item to modify |
UINT uFlags, |
// menu item flags |
UINT uIDNewItem, |
// menu item identifier or handle of drop-down menu or submenu |
LPCTSTR lpNewItem |
// menu item content |
); |
Value |
Meaning |
MF_BYCOMMAND |
Indicates that the uPosition parameter gives the identifier of the menu item. The MF_BYCOMMAND flag is the default if neither the MF_BYCOMMAND nor MF_BYPOSITION flag is specified. |
MF_BYPOSITION |
Indicates that the uPosition parameter gives the zero-based relative position of the menu item. |
Value |
Meaning |
MF_BITMAP |
Contains a bitmap handle. |
MF_OWNERDRAW |
Contains a 32-bit value supplied by an application that is used to maintain additional data related to the menu item. The value is in the itemData member of the structure pointed to by the lparam parameter of the WM_MEASUREITEM or WM_DRAWITEM messages sent when the menu item is created or its appearance is updated. |
MF_STRING |
Contains a pointer to a null-terminated string (the default). |
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
If ModifyMenu replaces a menu item that opens a drop-down menu or submenu, the function destroys the old drop-down menu or submenu and frees the memory used by it.
The application must call the DrawMenuBar function whenever a menu changes, whether or not the menu is in a displayed window. To change the attributes of existing menu items, it is much faster to use the CheckMenuItem and EnableMenuItem functions.
The following list describes the flags that may be set in the uFlags parameter:
Value |
Meaning |
MF_BITMAP |
Uses a bitmap as the menu item. The lpNewItem parameter contains the handle of the bitmap. |
MF_BYCOMMAND |
Indicates that the uPosition parameter specifies the identifier of the menu item (the default). |
MF_BYPOSITION |
Indicates that the uPosition parameter specifies the zero-based relative position of the new menu item. |
MF_CHECKED |
Places a check mark next to the item. If your application provides check mark bitmaps (see the SetMenuItemBitmaps function), this flag displays a checked bitmap next to the menu item. |
MF_DISABLED |
Disables the menu item so that it cannot be selected, but this flag 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 and grays it so that it cannot be selected. |
MF_MENUBARBREAK |
Functions the same as the MF_MENUBREAK flag for a menu bar. For a drop-down menu, submenu, or shortcut menu, the new column is separated from the old column by a vertical line. |
MF_MENUBREAK |
Places the item on a new line (for menu bars) or in a new column (for a drop-down menu, submenu, or shortcut menu) without separating columns. |
MF_OWNERDRAW |
Specifies that the item is an owner-drawn item. Before the menu is displayed for the first time, the window that owns the menu receives a WM_MEASUREITEM message 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 opens a drop-down menu or submenu. The uIDNewItem parameter specifies the handle of the drop-down menu or submenu. This flag is used to add a menu name to a menu bar or a menu item that opens a submenu to a drop-down menu, submenu, or shortcut menu. |
MF_SEPARATOR |
Draws a horizontal dividing line. This flag is used only in a drop-down menu, submenu, or shortcut menu. The line cannot be grayed, disabled, or highlighted. The lpNewItem and uIDNewItem parameters are ignored. |
MF_STRING |
Specifies that the menu item is a text string; the lpNewItem parameter points to the string. |
MF_UNCHECKED |
Does not place a check mark next to the item (the default). If your application supplies check mark bitmaps (see the SetMenuItemBitmaps function), this flag displays an unchecked bitmap next to the menu item. |
The following groups of flags cannot be used together:
AppendMenu, CheckMenuItem, DrawMenuBar, EnableMenuItem, SetMenuItemBitmaps, SetMenuItemInfo, WM_DRAWITEM, WM_MEASUREITEM