Microsoft Windows CE 3.0  

InsertMenu

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This function inserts a new menu item into a menu, moving other items down the menu.

BOOL
InsertMenu(
HMENU
hMenu
,
UINT
uPosition
,
UINT
uFlags
,
UINT
uIDNewItem
,
LPCTSTR
lpNewItem
);

Parameters

hMenu
[in] Handle to the menu to be changed.
uPosition
[in] Specifies the menu item before which the new menu item is to be inserted, as determined by the uFlagsparameter.
uFlags
[in] Specifies flags that control the interpretation of the uPositionparameter 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 uPositionparameter 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 uPositionparameter gives the zero-based relative position of the new menu item. If uPositionis 0xFFFFFFFF, the new menu item is appended to the end of the menu.
uIDNewItem
[in] Specifies either the identifier of the new menu item or, if the uFlagsparameter has the MF_POPUP flag set, the handle to the drop-down menu or submenu.
lpNewItem
[in] Long pointer to the content of the new menu item. The interpretation of lpNewItemdepends on whether the uFlagsparameter includes the MF_OWNERDRAW or MF_STRING flag, as follows:
Value Description
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 itemDatamember of the structure pointed to by the lparamparameter of the WM_MEASUREITEMor WM_DRAWITEMmessage 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

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The application must call the DrawMenuBarfunction 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 uFlagsparameter:

MF_CHECKED
Places a check mark next to the menu item.
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.

Windows CE versions 1.0 and 1.01 do not support this flag.

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.

Windows CE versions 1.0 and 1.01 do not support this flag.

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 uIDNewItemparameter specifies the 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.

Windows CE versions 1.0 and 1.01 do not support this flag.

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 lpNewItemand uIDNewItemparameters are ignored.
MF_STRING
Specifies that the menu item is a text string; the lpNewItemparameter points to the string.
MF_UNCHECKED
Does not place a check mark next to the menu item (default).

The following groups of flags cannot be used together:

  • MF_BYCOMMAND and MF_BYPOSITION
  • MF_ENABLED and MF_GRAYED
  • MF_STRING, MF_OWNERDRAW, and MF_SEPARATOR
  • MF_MENUBARBREAK and MF_MENUBREAK
  • MF_CHECKED and MF_UNCHECKED

    Menu items cannot be disabled without being grayed. To disable a menu item, use the MF_GRAYED flag.

    Windows CE versions 1.0 and 1.01 do not support cascading menus. If you are using Windows CE version 1.0 or 1.01, you cannot insert an MF_POPUP menu into another pop-up menu. If using Windows CE versions 2.0 or later, you can.

    Requirements

    Runs on Versions Defined in Include Link to
    Windows CE OS 1.0 and later Winuser.h   Menu.lib
    Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

    See Also

    AppendMenu, CreateMenu, DeleteMenu, GetLastError, RemoveMenu, WM_DRAWITEM, WM_MEASUREITEM