AppendMenu

Version 3.0

Syntax

BOOL AppendMenu(hMenu,wFlags,wIDNewItem,lpNewItem)

This function appends a new item to the end of a 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.  
wFlags WORD Specifies 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. The interpretation of the lpNewItem parameter depends upon the setting of the wFlags parameter.  
  If wFlags is lpNewItem
  MF_STRING Contains a long pointer to a null-terminated character string.
  MF_BITMAP Contains a bitmap handle HBITMAP in its low-order word.
  MF_OWNERDRAW Contains 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 WM_MEASUREITEM and WM_DRAWITEM messages sent when the menu item is initially displayed or is changed.

Return Value

The return value specifies the outcome of the function. It is TRUE if the function is successful. Otherwise, it is FALSE.

Comments

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 are mutually exclusive and should not be used together:

MF_BYCOMMAND and MF_BYPOSITION

MF_DISABLED, MF_ENABLED, and MF_GRAYED

MF_BITMAP, MF_STRING, and MF_OWNERDRAW

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_CHECKED Places a checkmark next to the 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 item on a new line for static menu-bar items. For pop-up menus, 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 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 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. This is used for adding either a top-level pop-up menu or adding a hierarchical pop-up menu to a pop-up menu item.  
MF_SEPARATOR Draws a horizontal dividing line. Can only be used 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 item (default). If the application has supplied checkmark bitmaps (see SetMenuItemBitmaps), setting this flag displays the “checkmark off” bitmap next to the menu item.