ModifyMenuA 函数 (winuser.h)

  • 项目

更改现有菜单项。 此函数用于指定菜单项的内容、外观和行为。

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

语法

BOOL ModifyMenuA(
  [in]           HMENU    hMnu,
  [in]           UINT     uPosition,
  [in]           UINT     uFlags,
  [in]           UINT_PTR uIDNewItem,
  [in, optional] LPCSTR   lpNewItem
);

参数

[in] hMnu

类型： HMENU

要更改的菜单的句柄。

[in] uPosition

类型： UINT

要更改的菜单项，由 uFlags 参数确定。

[in] uFlags

类型： UINT

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

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

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

值 含义
MF_BITMAP
0x00000004L
 使用位图作为菜单项。 lpNewItem 参数包含位图的句柄。
MF_CHECKED
0x00000008L
 Places项旁边的检查标记。 如果应用程序提供检查标记位图 (看到 SetMenuItemBitmaps 函数) ，则此标志会在菜单项旁边显示所选位图。
MF_DISABLED
0x00000002L
 禁用菜单项，使其无法被选中，但此标志不会灰显。
MF_ENABLED
0x00000000L
 启用菜单项，以便可以选择菜单项，并从其灰色状态还原它。
MF_GRAYED
0x00000001L
 禁用菜单项并将其灰显，以便无法选择它。
MF_MENUBARBREAK
0x00000020L
 功能与菜单栏的 MF_MENUBREAK 标志相同。 对于下拉菜单、子菜单或快捷菜单，新列与旧列之间将用一条竖线分隔。
MF_MENUBREAK
0x00000040L
 Places菜单栏的新行 (上的项) ，或者在下拉菜单、子菜单或快捷菜单的新列 (中) 不分隔列。
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

已更改的菜单项的内容。 此参数的解释取决于 uFlags 参数是包含 MF_BITMAP、 MF_OWNERDRAW还是 MF_STRING 标志。

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

返回值

类型： BOOL

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

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

注解

如果 ModifyMenu 替换打开下拉菜单或子菜单的菜单项，该函数将销毁旧的下拉菜单或子菜单并释放它使用的内存。

为了使键盘快捷方式能够处理位图或所有者绘制的菜单项，菜单所有者必须处理 WM_MENUCHAR 消息。 有关详细信息 ，请参阅所有者绘制的菜单和WM_MENUCHAR消息 。

无论菜单是否在显示的窗口中，只要菜单发生更改，应用程序都必须调用 DrawMenuBar 函数。 若要更改现有菜单项的属性，使用 CheckMenuItem 和 EnableMenuItem 函数要快得多。

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

  • 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

示例

有关示例，请参阅 设置 Menu-Item 文本字符串的字体。

注意

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

要求

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

另请参阅

AppendMenu

CheckMenuItem

概念性

DrawMenuBar

EnableMenuItem

菜单

引用

SetMenuItemBitmaps

SetMenuItemInfo