InsertMenuW function (winuser.h)
Inserts a new menu item into a menu, moving other items down the menu.
Syntax
BOOL InsertMenuW(
[in] HMENU hMenu,
[in] UINT uPosition,
[in] UINT uFlags,
[in] UINT_PTR uIDNewItem,
[in, optional] LPCWSTR lpNewItem
);
Parameters
[in] hMenu
Type: HMENU
A handle to the menu to be changed.
[in] uPosition
Type: UINT
The menu item before which the new menu item is to be inserted, as determined by the uFlags parameter.
[in] uFlags
Type: UINT
Controls the interpretation of the uPosition parameter and the content, appearance, and behavior of the new menu item. This parameter must include one of the following required values.
The parameter must also include at least one of the following values.
Value | Meaning |
---|---|
|
Uses a bitmap as the menu item. The lpNewItem parameter contains a handle to the bitmap. |
|
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. |
|
Disables the menu item so that it cannot be selected, but does not gray it. |
|
Enables the menu item so that it can be selected and restores it from its grayed state. |
|
Disables the menu item and grays it so it cannot be selected. |
|
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. |
|
Places the item on a new line (for menu bars) or in a new column (for a drop-down menu, submenu, or shortcut menu) without separating columns. |
|
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. |
|
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. |
|
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. |
|
Specifies that the menu item is a text string; the lpNewItem parameter is a pointer to the string. |
|
Does not place a check mark next to the menu item (default). If the application supplies check-mark bitmaps (see the SetMenuItemBitmaps function), 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 has the MF_POPUP flag set, 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 MF_BITMAP, MF_OWNERDRAW, or MF_STRING flag, as follows.
Value | Meaning |
---|---|
|
Contains a bitmap handle. |
|
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 item is created or its appearance is updated. |
|
Contains a pointer to a null-terminated string (the default). |
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.
The following groups of flags cannot be used together:
- MF_BYCOMMAND and MF_BYPOSITION
- MF_DISABLED, MF_ENABLED, and MF_GRAYED
- MF_BITMAP, MF_STRING, MF_OWNERDRAW, and MF_SEPARATOR
- MF_MENUBARBREAK and MF_MENUBREAK
- MF_CHECKED and MF_UNCHECKED
Note
The winuser.h header defines InsertMenu as an alias that 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 is 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
Other Resources
Reference