ModifyMenu

  BOOL ModifyMenu(hmenu, uItem, fuFlags, idNewItem, lpszNewItem)    
  HMENU hmenu; /* handle of menu */
  UINT uItem; /* menu item to modify */
  UINT fuFlags; /* menu-item flags */
  UINT idNewItem; /* menu-item identifier or pop-up menu handle */
  LPCTSTR lpszNewItem; /* menu-item content */

The ModifyMenu function changes an existing menu item. An application can use this function to specify the content, appearance, and behavior of the menu item.

Parameters

hmenu

Identifies the menu to be changed.

uItem

Specifies the menu item to be changed, 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 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.

idNewItem

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

lpszNewItem

Specifies the content of the changed 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.

Return Value

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.

Comments

The ModifyMenu 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).

If the ModifyMenu function replaces a menu item that invokes a pop-up menu, the function destroys the old pop-up menu and frees the memory used by the pop-up menu.

Whenever a menu changes (whether or not the menu resides in a window that is displayed), the application should call the DrawMenuBar function. To change the attributes of existing menu items, it is much faster to use the CheckMenuItem and EnableMenuItem functions.

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 check mark 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.

See Also

AppendMenu, CheckMenuItem, DrawMenuBar, EnableMenuItem, SetMenuItemBitmaps