AppendMenu

3.0

  BOOL AppendMenu(hmenu, fuFlags, idNewItem, lpNewItem)    
  HMENU hmenu; /* handle of menu, */  
  UINT fuFlags; /* menu-item flags, */  
  UINT idNewItem; /* menu-item identifier, */  
  LPCSTR lpNewItem; /* specifies menu-item content */

The AppendMenu 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 fuFlags parameter.

Parameters

hmenu

Identifies the menu to be changed.

fuFlags

Specifies information about the state of the new menu item when it is added to the menu. This parameter consists of one or more of the values listed in the following Comments section.

idNewItem

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

lpNewItem

Specifies the content of the new menu item. The interpretation of the lpNewItem parameter depends on the value of the fuFlags parameter.

Value Menu-item content

MF_STRING Contains a long pointer to a null-terminated string.
MF_BITMAP Contains a bitmap handle in its low-order word.
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 changed or initially displayed.

Return Value

The return value is nonzero if the function is successful. Otherwise, it is zero.

Comments

Whenever a menu changes (whether or not the menu is in a window that is displayed), the application should call the DrawMenuBar function.

Each of the following groups lists flags that are mutually exclusive and cannot be used together:

MF_DISABLED, MF_ENABLED, and MF_GRAYED

MF_BITMAP, MF_STRING, and MF_OWNERDRAW

MF_MENUBARBREAK and MF_MENUBREAK

MF_CHECKED and MF_UNCHECKED

Following are the flags that can be set in the fuFlags 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 check mark next to the item. If the application has supplied check mark bitmaps (see the SetMenuItemBitmaps function), setting this flag displays the “check mark 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-drawn 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 window 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 idNewItem 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 be used only in a pop-up menu. This line cannot be grayed, disabled, or highlighted. The lpNewItem and idNewItem 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 check mark next to the item (default). If the application has supplied check mark bitmaps (see SetMenuItemBitmaps), setting this flag displays the “check mark off” bitmap next to the menu item.

Example

The following example uses the AppendMenu function to append three items to a floating pop-up menu:

POINT ptCurrent;
HMENU hmenu;

ptCurrent = MAKEPOINT(lParam);
hmenu = CreatePopupMenu();
AppendMenu(hmenu, MF_ENABLED, IDM_ELLIPSE, "Ellipse");
AppendMenu(hmenu, MF_ENABLED, IDM_SQUARE, "Square");
AppendMenu(hmenu, MF_ENABLED, IDM_TRIANGLE, "Triangle");
ClientToScreen(hwnd, &ptCurrent);
TrackPopupMenu(hmenu, TPM_LEFTALIGN, ptCurrent.x,
    ptCurrent.y, 0, hwnd, NULL);

See Also

CreateMenu, DeleteMenu, DrawMenuBar, InsertMenu, RemoveMenu, SetMenuItemBitmaps