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