AppendMenuA function (winuser.h)

Appends a new item to the end of the specified menu bar, drop-down menu, submenu, or shortcut menu. You can use this function to specify the content, appearance, and behavior of the menu item.

Syntax

BOOL AppendMenuA(
  [in]           HMENU    hMenu,
  [in]           UINT     uFlags,
  [in]           UINT_PTR uIDNewItem,
  [in, optional] LPCSTR   lpNewItem
);

Parameters

[in] hMenu

Type: HMENU

A handle to the menu bar, drop-down menu, submenu, or shortcut menu to be changed.

[in] uFlags

Type: UINT

Controls the appearance and behavior of the new menu item. This parameter can be a combination of the following values.

Value Meaning
MF_BITMAP
0x00000004L
Uses a bitmap as the menu item. The lpNewItem parameter contains a handle to the bitmap.
MF_CHECKED
0x00000008L
Places a check mark next to the menu item. If the application provides check-mark bitmaps (see SetMenuItemBitmaps, this flag displays the check-mark bitmap next to the menu item.
MF_DISABLED
0x00000002L
Disables the menu item so that it cannot be selected, but the flag does not gray it.
MF_ENABLED
0x00000000L
Enables the menu item so that it can be selected, and restores it from its grayed state.
MF_GRAYED
0x00000001L
Disables the menu item and grays it so that it cannot be selected.
MF_MENUBARBREAK
0x00000020L
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
0x00000040L
Places the item on a new line (for a menu bar) or in a new column (for a drop-down menu, submenu, or shortcut menu) without separating columns.
MF_OWNERDRAW
0x00000100L
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
0x00000010L
Specifies that the menu item opens a drop-down menu or submenu. The uIDNewItem parameter specifies a handle to 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
0x00000800L
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
0x00000000L
Specifies that the menu item is a text string; the lpNewItem parameter is a pointer to the string.
MF_UNCHECKED
0x00000000L
Does not place a check mark next to the item (default). If the application supplies check-mark bitmaps (see SetMenuItemBitmaps), this flag displays the clear bitmap next to the menu item.

[in] uIDNewItem

Type: UINT_PTR

The identifier of the new menu item or, if the uFlags parameter is set to MF_POPUP, a handle to the drop-down menu or submenu.

[in, optional] lpNewItem

Type: LPCTSTR

The content of the new menu item. The interpretation of lpNewItem depends on whether the uFlags parameter includes the following values.

Value Meaning
MF_BITMAP
0x00000004L
Contains a bitmap handle.
MF_OWNERDRAW
0x00000100L
Contains an application-supplied value that can be 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 message sent when the menu is created or its appearance is updated.
MF_STRING
0x00000000L
Contains a pointer to a null-terminated string.

Return value

Type: BOOL

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.

Remarks

The application must call the DrawMenuBar function whenever a menu changes, whether the menu is in a displayed window.

To get keyboard accelerators to work with bitmap or owner-drawn menu items, the owner of the menu must process the WM_MENUCHAR message. For more information, see Owner-Drawn Menus and the WM_MENUCHAR Message.

The following groups of flags cannot be used together:

  • MF_BITMAP, MF_STRING, and MF_OWNERDRAW
  • MF_CHECKED and MF_UNCHECKED
  • MF_DISABLED, MF_ENABLED, and MF_GRAYED
  • MF_MENUBARBREAK and MF_MENUBREAK

Examples

For an example, see Adding Lines and Graphs to a Menu.

Note

The winuser.h header defines AppendMenu as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header winuser.h (include Windows.h)
Library User32.lib
DLL User32.dll
API set ext-ms-win-ntuser-menu-l1-1-0 (introduced in Windows 8)

See also

Conceptual

CreateMenu

DeleteMenu

DestroyMenu

DrawMenuBar

InsertMenu

InsertMenuItem

Menus

ModifyMenu

Reference

RemoveMenu

SetMenuItemBitmaps