InsertMenuW 函数 (winuser.h)

项目
08/27/2023

将新的菜单项插入到菜单中，将其他项向下移动菜单。

注意InsertMenu 函数已被 InsertMenuItem 函数取代。但是，如果不需要 InsertMenuItem 的任何扩展功能，仍然可以使用 InsertMenuIteu。

语法

BOOL InsertMenuW(
  [in]           HMENU    hMenu,
  [in]           UINT     uPosition,
  [in]           UINT     uFlags,
  [in]           UINT_PTR uIDNewItem,
  [in, optional] LPCWSTR  lpNewItem
);

参数

[in] hMenu

类型： HMENU

要更改的菜单的句柄。

[in] uPosition

类型： UINT

要在其前面插入新菜单项的菜单项，由 uFlags 参数确定。

[in] uFlags

类型： UINT

控制 uPosition 参数的解释以及新菜单项的内容、外观和行为。此参数必须包含以下必需值之一。

值	含义
MF_BYCOMMAND 0x00000000L	指示 uPosition 参数提供菜单项的标识符。如果未指定 MF_BYCOMMAND 标志和 MF_BYPOSITION 标志，则 MF_BYCOMMAND 标志为默认值。
MF_BYPOSITION 0x00000400L	指示 uPosition 参数提供新菜单项的从零开始的相对位置。如果 uPosition 为 -1，则新菜单项将追加到菜单的末尾。

参数还必须至少包含以下值之一。

值	含义
MF_BITMAP 0x00000004L	使用位图作为菜单项。 lpNewItem 参数包含位图的句柄。
MF_CHECKED 0x00000008L	在菜单项旁边放置一个检查标记。如果应用程序提供检查标记位图 (请参阅 SetMenuItemBitmaps) ，则此标志在菜单项旁边显示检查标记位图。
MF_DISABLED 0x00000002L	禁用菜单项，使其无法被选中，但不将其灰显。
MF_ENABLED 0x00000000L	启用菜单项，以便可以选择菜单项，并将其从灰显状态还原。
MF_GRAYED 0x00000001L	禁用菜单项并将其灰显，使其无法选中。
MF_MENUBARBREAK 0x00000020L	功能与菜单栏的 MF_MENUBREAK 标志相同。对于下拉菜单、子菜单或快捷菜单，新列与旧列之间将用一条竖线分隔。
MF_MENUBREAK 0x00000040L	将项放置在菜单栏的新行 () ，或放置在下拉菜单、子菜单或快捷菜单) 的新列 (中，而不分隔列。
MF_OWNERDRAW 0x00000100L	指定该项是所有者绘制的项。在首次显示菜单之前，拥有菜单的窗口会收到 WM_MEASUREITEM 消息，用于检索菜单项的宽度和高度。然后，每当必须更新菜单项的外观时， WM_DRAWITEM消息就会发送到所有者窗口的窗口过程。
MF_POPUP 0x00000010L	指定菜单项打开下拉菜单或子菜单。 uIDNewItem 参数指定下拉菜单或子菜单的句柄。此标志用于向菜单栏或菜单项添加菜单名称，以便向下拉菜单、子菜单或快捷菜单打开子菜单。
MF_SEPARATOR 0x00000800L	绘制一条水平分割线。此标志仅在下拉菜单、子菜单或快捷菜单中使用。行不能灰显、禁用或突出显示。忽略 lpNewItem 和 uIDNewItem 参数。
MF_STRING 0x00000000L	指定菜单项为文本字符串; lpNewItem 参数是指向字符串的指针。
MF_UNCHECKED 0x00000000L	不要在菜单项旁边放置检查标记 (默认) 。如果应用程序提供检查标记位图 (看到 SetMenuItemBitmaps 函数) ，则此标志在菜单项旁边显示清除位图。

[in] uIDNewItem

类型： UINT_PTR

新菜单项的标识符;如果 uFlags 参数设置了 MF_POPUP 标志，则为下拉菜单或子菜单的句柄。

[in, optional] lpNewItem

类型： LPCTSTR

新菜单项的内容。 lpNewItem 的解释取决于 uFlags 参数是包含MF_BITMAP、MF_OWNERDRAW还是MF_STRING标志，如下所示。

值	含义
MF_BITMAP 0x00000004L	包含位图句柄。
MF_OWNERDRAW 0x00000100L	包含应用程序提供的值，该值可用于维护与菜单项相关的其他数据。该值位于结构的 itemData 成员中，该成员由创建菜单项或更新其外观时发送的WM_MEASUREITEM或WM_DRAWITEM消息的 lParam 参数指向。
MF_STRING 0x00000000L	包含指向以 null 结尾的字符串 (默认) 的指针。

返回值

类型： BOOL

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

注解

无论菜单是否在显示的窗口中，只要菜单发生更改，应用程序都必须调用 DrawMenuBar 函数。

以下标志组不能一起使用：

MF_BYCOMMAND 和 MF_BYPOSITION
MF_DISABLED、 MF_ENABLED和 MF_GRAYED
MF_BITMAP、 MF_STRING、 MF_OWNERDRAW和 MF_SEPARATOR
MF_MENUBARBREAK 和 MF_MENUBREAK
MF_CHECKED 和 MF_UNCHECKED

注意

winuser.h 标头将 InsertMenu 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求


最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	winuser.h (包括 Windows.h)
Library	User32.lib
DLL	User32.dll
API 集	windows 8) 中引入的 ext-ms-win-ntuser-menu-l1-1-0 (