InsertMenu
The InsertMenu
function inserts a new menu item into a menu, moving other items down the menu.
The InsertMenu
function has been superseded by the InsertMenuItem function. You can still
use InsertMenu, however, if you do not need any of the extended features
of InsertMenuItem.
BOOL InsertMenu(
|
HMENU hMenu, |
// handle of menu |
|
UINT uPosition, |
// menu item that
new menu item precedes |
|
UINT uFlags, |
// menu item flags |
|
UINT uIDNewItem, |
// menu item
identifier or handle of drop-down menu or submenu |
|
LPCTSTR lpNewItem |
// menu item
content |
|
); |
|
Parameters
hMenu
Identifies
the menu to be changed.
uPosition
Specifies the
menu item before which the new menu item is to be inserted, as determined by
the uFlags parameter.
uFlags
Specifies
flags that control the interpretation of the uPosition parameter and the
content, appearance, and behavior of the new menu item. This parameter must be
a combination of one of the following required values and at least one of the
values listed in the following Remarks section.
|
Value |
Description |
|
MF_BYCOMMAND |
Indicates
that the uPosition parameter gives the identifier of the menu item.
The MF_BYCOMMAND flag is the default if neither the MF_BYCOMMAND nor
MF_BYPOSITION flag is specified. |
|
MF_BYPOSITION |
Indicates
that the uPosition parameter gives the zero-based relative position of
the new menu item. If uPosition is 0xFFFFFFFF, the new menu item is
appended to the end of the menu. |
uIDNewItem
Specifies
either the identifier of the new menu item or, if the uFlags parameter
has the MF_POPUP flag set, the handle of the drop-down menu or submenu.
lpNewItem
Specifies 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 |
Description |
|
MF_BITMAP |
Contains a
bitmap handle. |
|
MF_OWNERDRAW |
Contains a
32-bit value supplied by the application 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. |
|
MF_STRING |
Contains a
pointer to a null-terminated string (the default). |
Return Values
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 or
not the menu is in a displayed window.
The following
list describes the flags that can be set in the uFlags parameter:
|
Value |
Description |
|
MF_BITMAP |
Uses a
bitmap as the menu item. The lpNewItem parameter contains the handle
of the bitmap. |
|
MF_CHECKED |
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 |
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 and grays it so it cannot be selected. |
|
MF_MENUBARBREAK |
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 |
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. |
|
MF_OWNERDRAW |
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 |
Specifies
that the menu item opens a drop-down menu or submenu. The uIDNewItem
parameter specifies the handle of 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 |
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 |
Specifies
that the menu item is a text string; the lpNewItem parameter points to
the string. |
|
MF_UNCHECKED |
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 unchecked bitmap next to the menu item. |
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
See Also