A menu bar is a horizontal bar typically displayed immediately below a window's title bar. It contains a list of drop-down menus, which can contain menu items, separators, and nested submenus. Individual menu items can be enabled or disabled, checked or unchecked, and may appear grayed to indicate that they are unavailable.
Menus can be created programmatically or designed using a resource editor provided by many integrated development environments (IDEs). The CreateMenu(), AppendMenu(), and InsertMenuItem() functions are among the Windows API functions used to create and modify menus at run time.
Creating a Menu
To create an empty menu at run time, use the CreateMenu() API function. The prototype is:
HMENU CreateMenu();
If the function succeeds, the return value is a handle to the newly created menu. If the function fails, the return value is NULL.
Adding a Menu Item
To add an item to a top-level menu, drop-down menu, submenu, or context menu, use the AppendMenu() API function. The prototype is:
BOOL AppendMenu(HMENU hMenu, UINT uFlags, UINT_PTR uIDNewItem, LPCSTR lpNewItem);
where
hMenu – A handle to the menu to be changed.
uFlags – Controls the appearance and behaviour of the new menu item.
uIDNewItem – The identifier of the new menu item or, when MF_POPUP is specified, a handle to the drop-down menu or submenu.
lpNewItem – The content of the menu item. Depending on the flags specified, this can identify a string, bitmap, or owner-drawn menu item.
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.
For further detailed reading, see the Microsoft documentation for AppendMenu().
Dynamically Modifying Menus
Modify a Menu
The ModifyMenu() function changes an existing menu item. The prototype is:
BOOL ModifyMenu(HMENU hMenu, UINT uPosition, UINT uFlags, UINT_PTR uIDNewItem, LPCTSTR lpNewItem);
where
hMenu – A handle to the menu to be changed.
uPosition – Specifies the menu item to be changed, as determined by the uFlags parameter.
uFlags – Specifies flags that control the interpretation of uPosition and the content, appearance, and behaviour of the menu item.
uIDNewItem – Specifies either the identifier of the modified menu item or, when MF_POPUP is specified, the handle to a drop-down menu or submenu.
lpNewItem – A pointer to the content of the modified menu item.
Returns nonzero if the function succeeds; otherwise, it returns zero.
For further detailed reading, see the Microsoft documentation for ModifyMenu().
Insert a Menu Item
To insert a new menu item at a specified position in a menu, use the InsertMenuItem() API function. The prototype is:
BOOL InsertMenuItem(HMENU hmenu, UINT item, BOOL fByPosition, LPCMENUITEMINFOA lpmi);
where
hMenu – A handle to the menu where the new menu item will be inserted.
uItem – The identifier or position of the menu item before which the new item will be inserted.
fByPosition – Specifies how uItem is interpreted. If this parameter is FALSE, uItem is a menu item identifier. If it is TRUE, uItem is a menu item position.
lpmii – A pointer to a MENUITEMINFO structure containing information about the new menu item.
Returns nonzero if the function succeeds; otherwise, it returns zero.
For further detailed reading, see the Microsoft documentation for InsertMenuItem().
Deleting a Menu Item
To delete a menu item and any submenu associated with it, use the DeleteMenu() function. The prototype is:
BOOL DeleteMenu(HMENU hMenu, UINT uPosition, UINT uFlags);
where
hMenu – A handle to the menu to be changed.
uPosition – Specifies the menu item that is to be deleted.
uFlags – Specifies how the uPosition parameter is interpreted.
Returns nonzero if the function succeeds; otherwise, it returns zero.
Useful Menu-Related Messages
WM_COMMAND – Sent when the user selects a menu item. The low-order word of wParam contains the identifier of the selected menu item.
WM_INITMENU – Sent just before a menu is displayed, allowing an application to modify the menu before the user makes a selection. Windows sends this message each time a menu is activated, whether by using the mouse or keyboard. The wParam parameter contains a handle to the menu being initialised.
WM_MENUSELECT – Sent to a menu's owner window whenever the user selects or highlights a menu item. The low-order word of wParam contains the identifier of the selected menu item or the index of the selected submenu, while the high-order word contains menu flags describing the selected item. The lParam parameter contains a handle to the menu that contains the selected item.
WM_INITMENUPOPUP – Sent when a drop-down menu or submenu is about to be displayed. This message allows an application to initialise or modify the contents of the menu before it is shown.
The Popup or Context Menu
A popup menu, also known as a context menu, is typically displayed when the user right-clicks a window or control. The term context menu reflects the fact that the commands it contains are relevant to the object or area that was clicked.
The TrackPopupMenu() function displays a popup menu at a specified screen position and tracks the user's selection. A popup menu can be loaded from a menu resource or created dynamically using the CreatePopupMenu() function.
The prototype for TrackPopupMenu() is:
BOOL TrackPopupMenu(HMENU hMenu, UINT uFlags, int x, int y, int nReserved, HWND hWnd, const RECT *prcRect);
where
hMenu – A handle to the popup menu.
uFlags – Specifies how the popup menu is positioned and how it behaves.
x – Specifies the horizontal position, in screen coordinates, of the popup menu.
y – Specifies the vertical position, in screen coordinates, of the popup menu.
nReserved – Reserved and must be zero.
hWnd – A handle to the window that owns the popup menu.
prcRect – Reserved and must be NULL.
Common positioning flags include:
- TPM_LEFTALIGN – Positions the left side of the popup menu at the specified x-coordinate.
- TPM_CENTERALIGN – Centres the popup menu horizontally around the specified x-coordinate.
- TPM_RIGHTALIGN – Positions the right side of the popup menu at the specified x-coordinate.
- TPM_TOPALIGN – Positions the top of the popup menu at the specified y-coordinate.
- TPM_VCENTERALIGN – Centres the popup menu vertically around the specified y-coordinate.
- TPM_BOTTOMALIGN – Positions the bottom of the popup menu at the specified y-coordinate.
The function returns nonzero if the menu is displayed successfully; otherwise, it returns zero.
Example
The example below creates a window with a top-level menu, a drop-down menu, and two selectable menu items. The same commands are also made available through a right-click context menu. Selecting either menu option produces a message beep.
