Menu

AutoHotKey

Menu

创建, 删除, 修改和显示菜单和菜单项. 改变托盘图标和它的提示. 控制是否可以打开已编译脚本的主窗口.

Menu, MenuName, Cmd [, P3, P4, P5]

参数

MenuName

它可以为 TRAY 或任何自定义菜单的名称. 首次和 Add 命令一起使用自定义菜单的名称时会自动创建此菜单. 例如:Menu, MyMenu, Add, Item1.

创建后, 可以用 Show 命令显示自定义菜单. 通过 Add 命令还可以把它作为子菜单附加到一个或更多的其他菜单上.

Cmd, P3, P4, P5

这 4 个参数彼此依赖. 请参阅下表了解允许的组合.

MenuItemName

菜单项的名称或位置. 一些适用于此参数的规则同样适用于所有使用此参数的子命令:

要为菜单项名称的某个字母加下划线, 在这个字母前加一个 & 号. 当菜单显示出来时, 此项可以通过按键盘上对应的按键来选中. 要显示原义的 & 号像这样指定连续的两个 & 号: Save && Exit .

当引用到一个已存在的菜单或菜单项时, 其名称不区分大小写但 & 号不能少, 例如: &Open .

[v1.1.23+]: 要通过在菜单中的位置确定一个菜单项, 写下该菜单项的位置并尾随一个 & 号. 例如, 1& 表示第一个菜单项.

添加或改变菜单项

Add [, MenuItemName, Label-or-Submenu, Options]: 此命令有多种用途, 包括添加菜单项, 使用新的子菜单或标签更新菜单项或把普通菜单转换成子菜单 (或相反). 如果 MenuItemName 还不存在, 则把它添加到菜单. 否则, 将使用新指定的 Label-or-Submenu 更新 MenuItemName.

要添加菜单分隔线, 请省略所有三个参数.

当用户选择菜单项时, 标签子程序作为新 线程 运行 (类似于 Gosub热键子程序). 如果省略 Label-or-Submenu, 那么将使用 MenuItemName 同时作为标签和菜单项的名称.

[v1.1.20+]: 如果不存在这个名称的标签, 那么 Label-or-Submenu 可以是一个函数对象的名称, 或是引用某个 函数对象的变量. 例如 , %funcobj%% funcobj. 目前暂不支持其他表达式返回对象. 另外还可以定义函数可选参数, 例如:

FunctionName(ItemName, ItemPos, MenuName)

要让 MenuItemName 变成子菜单 (在选择时打开新菜单的菜单项), 请在 Label-or-Submenu 中指定冒号后面跟着现有自定义菜单的 MenuName. 例如:

Menu, MySubmenu, add, Item1
Menu, tray, add, This Menu Item Is A Submenu, :MySubmenu

如果不省略, 选项 必须是包含一个或多个下列选项并以空格或制表符分隔的列表:

Pn n 代表菜单项的 进程优先级, 如 P1. 如果在添加菜单项时省略此选项, 其优先级将会是默认的 0 . 如果在更新菜单项时省略此选项, 其优先级不变. 用十进制数字 (非十六进制) 表示优先级.
+Radio [v1.1.23+]: 选中菜单项时显示的是一个空心圆而不是打勾标志.
+Right [v1.1.23+]: 让菜单栏中的菜单项右对齐. 此选项仅适用于 菜单栏 而不是弹出式菜单或子菜单.
+Break [v1.1.23+]: 让弹出式菜单中的菜单项以新的一列开始.
+BarBreak [v1.1.23+]: 作用同上, 不过该选项会在列之间加分隔线.

选项中的加号 (+) 是可选的也可以用减号 (-) 代替用以移除某个选项, 就像 -Radio . 选项不区分大小写.

为了不影响菜单项的标签或子菜单, 在改变一个已存在的菜单项的选项时直接忽略 Label-or-Submenu 参数即可.

Insert [, ItemToInsertBefore, NewItemName, Label-or-Submenu, Options] [v1.1.23+]: 在指定的菜单项前插入一个新的菜单项. 其用法同上面的 Add , 多出来的 ItemToInsertBefore 参数代表一个已存在的菜单项名称或介于1和 当前菜单项数目+1 之间的位置序号(位置&). 也可以用忽略 ItemToInsertBefore (连写两个逗号)的方式追加菜单项. 与 Add 不同, InsertNewItemName 和已有菜单项同名的情况下仍可以创建新的菜单项.

Delete [, MenuItemName]: 从菜单中删除 MenuItemName . 标准菜单项例如 Exit (请参阅下面) 不能被单独删除. 如果删除了 默认 菜单项, 则效果与使用 NoDefault 选项类似. 如果省略了 MenuItemName, 则会删除整个 MenuName 以及在其他菜单中名称为 MenuName 的任何子菜单项. 删除一个菜单也会导致当前 Win32 菜单 的父菜单和子菜单被销毁, 之后在需要时才能被重新创建.

DeleteAll: 从菜单中删除所有自定义菜单项, 当不包含 标准 菜单项 (请参阅下面) 时则让菜单留空. 与使用 Delete 命令 (请参阅上面) 完全删除菜单不同, 此时仍然存在一个空菜单, 因此其他任何包含此菜单项作为子菜单的菜单仍保留这些子菜单. 但当前 Win32 菜单 的父菜单和子菜单会被销毁, 之后在需要时才能被重新创建.

Rename, MenuItemName [, NewName]: 改变 MenuItemNameNewName (如果 NewName 为空, 则 MenuItemName 会变为分隔线). 菜单项的当前目标标签或子菜单不会改变. [v1.1.23+]: 可通过指定分隔线的 位置& 和一个非空的 NewName 的方式将分隔线转换成正常的菜单项, 随后使用 Add 命令为其指定一个标签或子菜单.

Check, MenuItemName:在MenuItemName前添加复选标记(如果还没有).

Uncheck, MenuItemName:从MenuItemName中移除复选标记(如果有).

ToggleCheck, MenuItemName: 如果没有复选标记则进行添加; 否则移除它.

Enable, MenuItemName: 允许用户再次选择之前禁用 (灰色) 的 MenuItemName.

Disable, MenuItemName:把 MenuItemName 变成灰色以指示用户无法选择它.

ToggleEnable, MenuItemName: 禁用之前启用的 MenuItemName; 否则启用它.

Default [, MenuItemName]: 改变菜单的默认项为 MenuItemName 并加粗其字体 (当前在 TRAY 以外的菜单中设置默认项只是改变外观而没有其他作用). 当用户双击托盘图标时, 会运行其默认菜单项. 如果没有默认项, 则双击没有效果. 如果省略了 MenuItemName, 则效果等同于使用了下面的 NoDefault.

NoDefault: 对于托盘菜单: 让菜单恢复其默认菜单项, 对于未编译脚本为 OPEN 而对于 已编译脚本 则没有 (除非 MainWindow 选项有效). 如果因为之前使用了下面的 NoStandard 命令使得 OPEN 菜单项不存在, 那么将没有默认菜单项, 因此双击托盘图标没有效果. 对于 TRAY 以外的其他菜单: 任何现有的默认项恢复为非加粗字体.

Standard:在菜单底部插入标准菜单项(如果还不存在). 此命令可用于托盘菜单或其他任何菜单.

NoStandard:从托盘菜单移除所有标准(非自定义)的菜单项(如果存在).

Icon, MenuItemName, FileName [, IconNumber, IconWidth]: 设置 MenuItemName 的图标. FileName 可以为图标文件或 AutoHotkey 支持的格式的任何图像. 要使用文件中的图标组而不是首个图标, 请在 IconNumber 指定它的编号 (如果省略, 则它默认为 1). 如果 IconNumber 为负数, 则假定其绝对值表示可执行文件中图标的资源 ID. 在 IconWidth 中指定期望的图标宽度. 如果 IconNumber 表示的图标组包含多种大小的图标, 则使用最接近的匹配并将图标缩放到指定的大小. 请参阅示例部分的用法示例.

当前在 Windows Vista 和更高版本中如果需要被设置的图标保留透明度时, 则必须指定 "真实的大小". 例如:

Menu, MenuName, Icon, MenuItemName, Filename.png,, 0

已知限制: 在 Windows XP 和更早版本中, Gui 菜单栏中的图标无法放置到正确的位置.

[v1.1.23+]: bitmap (位图) 或 icon (图标) handle 句柄 可替代文件名. 例如, HBITMAP:%handle%.

NoIcon, MenuItemName:移除 MenuItemName 的图标(如果有).

改变托盘图标或工具提示 (MenuName 必须为 TRAY)

Icon [, FileName, IconNumber, 1]: 改变脚本的图标为 FileName 中的某个图标. 支持下列的文件类型: ICO, CUR, ANI, EXE, DLL, CPL, SCR 以及包含图标资源的其他类型. 要使用文件中的图标组而不是首个图标, 请在 IconNumber 指定它的编号 (如果省略, 则它默认为 1). 例如, 2 将加载第二个图标组中的默认图标. 如果 IconNumber 为负数, 则假定其绝对值表示可执行文件中图标的资源 ID. 在 FileName 指定星号(*)来恢复脚本到其默认图标.

最后一个参数: 在最后一个参数指定 1 来冻结图标, 而 0 则解冻它 (或留空来保持冻结/解冻状态不变). 当图标已经冻结时, PauseSuspend 不会改变它. 注:要冻结或解冻当前的图标, 请使用 1 或 0, 例如:Menu, Tray, Icon,,, 1.

改变托盘图标同时也改变由 InputBox, Progress 和后续创建的 GUI 窗口显示的图标. 也会影响 已编译脚本, 即使它在编译时指定了自定义的图标. 注:如果之前使用如 #NoTrayIcon 的方法隐藏了托盘图标, 则改变图标不会让它显示出来;要让它显示, 请使用 Menu, Tray, Icon(不带参数).

从 .ICO 外的其他类型文件中加载托盘图标时可能产生轻微的变形. 尤其是对于 16x16 的图标. 要避免此问题, 请把要使用的托盘图标保存到 .ICO 文件.

操作系统的 DLL 和 CPL 文件包含的一些图标可能会有用. 例如:Menu, Tray, Icon, Shell32.dll, 174.

内置变量 A_IconNumberA_IconFile 分别包含了当前图标的编号和名称 (带完整路径) (如果为默认图标则两者都为空).

[v1.1.23+]: bitmap (位图) 或 icon (图标) handle 句柄 可替代文件名. 例如, HBITMAP:%handle%.

Icon (不带参数):如果还没有托盘图标则进行创建. 如果在脚本中使用了 #NoTrayIcon, 则此命令会覆盖它.

NoIcon: 如果存在托盘图标则移除它. 如果在脚本的最顶部使用此命令, 则当脚本运行时托盘图标可能出现短暂的时间. 要避免这种情况, 请使用 #NoTrayIcon. 如果托盘图标当前是隐藏的, 则内置变量 A_IconHidden 的值为 1, 否则为 0.

Tip [, Text]: 改变托盘图标的工具提示, 这是在鼠标悬停在托盘图标上时显示的. 要创建多行的工具提示, 请在两行之间使用换行符 (`n), 例如 Line1`nLine2. 仅显示Text中的前127个字符, 并且如果Text中存在tab字符, 则首个此字符后的内容被截除. 如果省略 Text, 则把工具提示恢复为默认文本. 内置变量 A_IconTip 包含了当前工具提示的默认文本 (如果文本是默认的, 则为空).

杂项命令

Show [, X, Y]: 显示 MenuName, 允许用户使用方向键, 菜单快捷键 (下划线字母) 或鼠标选择菜单项. 可以显示包括托盘菜单在内的任何菜单, 但 GUI 菜单栏例外. 如果同时省略 X 和 Y, 则菜单显示在鼠标光标的当前位置. 如果仅省略其中一个, 则用鼠标光标的位置代替省略的这个. X 和 Y 相对于活动窗口. 预先指定 "CoordMode, Menu" 可以让它们相对于整个屏幕.

Color, ColorValue [, Single]: 改变菜单的背景颜色为 ColorValue, 它是 16 种 HTML 基础颜色之一或 6 位的 RGB 颜色值 (请参阅 颜色图标). 将 ColorValue 留空 (或指定单词 Default) 来恢复菜单的默认颜色. 如果后一个参数不是单词 Single, 则任何附加到此菜单的子菜单都会改变颜色.

Click, ClickCount: 在 ClickCount 中指定 1 来允许单击激活托盘菜单的默认菜单项. 在 ClickCount 中指定 2 来恢复到默认行为 (双击). 例如:Menu, Tray, Click, 1.

MainWindow: 此命令仅影响 已编译脚本. 它允许用户通过托盘图标打开脚本主窗口, 否则这是不行的. 它同时也启用了主窗口的 View 菜单项 (例如 "Lines most recently executed"), 这样就允许查看脚本的源代码和其他信息. MenuName 必须为 TRAY.

NoMainWindow (默认): 此命令仅影响 已编译脚本. 它恢复脚本的默认行为, 即阻止打开主窗口. 即使此选项有效, 脚本运行中遇到下列命令时仍然会显示主窗口: ListLines, ListVars, ListHotkeysKeyHistory. MenuName 必须为 TRAY.

UseErrorLevel [, off]: 如果脚本中从未使用过此选项, 则它默认为 OFF. 每当 Menu 命令遇到错误时, OFF 设置会显示一个对话框并终止 当前线程. 指定 Menu, Tray, UseErrorLevel 来阻止显示对话框和终止线程;作为替代, 如果遇到问题则 ErrorLevel 被设置为 1 否则为 0. 要让此选项转回 off, 请在后一个参数中指定 OFF. 此设置是全局的, 这意味着它影响所有的菜单, 而不只是 MenuName.

Win32 菜单

当菜单项被添加到菜单中或被修改时, 每个菜单项的名称和其他属性会被 Menu 命令记录下来, 但实际上 Win32 菜单 并不会被马上创建. 这种情况发生在菜单或父菜单被附加到一个 GUI 或者首次被显示或者菜单在最近一次显示后被"销毁". 下列任意一种情形都会导致 Win32 菜单被销毁, 其父菜单和子菜单也会随之销毁:

  • 删除菜单.
  • 用标签或不同的菜单替换某个菜单项的子菜单.
  • Menu, MenuName, DeleteAll.
  • Menu, MenuName, NoStandard (如果标准菜单项存在的话).

任何通过 Win32 API 调用直接对菜单进行的修改仅适用与菜单的当前 "实例" , 在菜单被销毁后丢失.

在首次添加到菜单中时每个菜单项都会被分配到一个 ID. 脚本不能依靠某个菜单项来接收其特定 ID, 但可以像 MenuGetHandle 示例 中那样使用 GetMenuItemID 获取该 ID. 此 ID 不可以用在 Menu 命令中, 却可以用于多种 Win32 函数.

备注

菜单和菜单项的名称长度最多可达 260 个字符.

分割线可通过 Menu, MenuName, Add 来增加 (也就是忽略其他所有参数). 要单独删除分割线, 确定他们在菜单中的位置 (依赖 v1.1.23+). 例如, 使用 Menu, MenuName, Delete, 3& 如果分隔符之前有两个项目. 还可以 Menu, MenuName, DeleteAll 然后重新添加自定义菜单项.

新的菜单项总是添加到菜单的底部. 对于托盘菜单:要把您的菜单项放到标准菜单项的上面, (在添加完自定义菜单项后)执行 Menu, tray, NoStandard 后面接着执行 Menu, tray, Standard.

不能使用任何菜单子命令单独操作标准菜单项, 例如 "Pause Script" 和 "Suspend Hotkeys".

如果一个菜单项已变得完全空了(例如使用 Menu, MyMenu, DeleteAll), 则无法把它显示出来. 如果托盘菜单变成空的, 则右击和双击托盘菜单将没有效果 (此时通常使用 #NoTrayIcon 更好).

如果一个菜单项的子程序已经运行而用户再次选择相同的菜单项, 则会创建一个新 线程 运行相同的子程序, 并中断之前的线程. 要缓冲这样的事件到以后执行, 请在子程序的首行使用 Critical (不过, 这样也将缓冲/延迟其他线程, 例如按下的热键).

每当通过菜单项运行子程序时, 它会使用设置 (例如 SendMode) 的默认值开始. 这些默认值可以在 自动执行段 改变.

内置变量 A_ThisMenuItemA_ThisMenuItemPos 分别包含了最近用户选择的自定义菜单项的名称和位置(如果没有则为空). 同样地, A_ThisMenu 是选择的 A_ThisMenuItem 的菜单名称. 这些变量可用于在创建的菜单内容不总是相同的时候. 在这种情况下, 通常最好把所有这样的菜单项指向相同的标签, 并在此标签中引用上面的变量来决定执行什么动作.

要让非热键且非 GUI 的脚本持续运行 (例如仅包含自定义菜单或菜单项的脚本), 请使用 #Persistent.

相关

GUI, 线程, Thread, Critical, #NoTrayIcon, Gosub, Return, SetTimer, #Persistent

示例

; 示例 #1: 这是个可运行脚本, 它添加一个新菜单项到托盘图标菜单的底部.

#Persistent  ; 让脚本持续运行, 直到用户退出.
Menu, tray, add  ; 创建分隔线.
Menu, tray, add, Item1, MenuHandler  ; 创建新菜单项.
return

MenuHandler:
MsgBox You selected %A_ThisMenuItem% from menu %A_ThisMenu%.
return

 

; 示例 #2: 这是个可运行脚本, 它创建了一个在用户按下 Win-Z 热键时显示的弹出菜单.

; 添加一些菜单项来创建弹出菜单.
Menu, MyMenu, Add, Item1, MenuHandler
Menu, MyMenu, Add, Item2, MenuHandler
Menu, MyMenu, Add  ; 添加分隔线.

; 添加子菜单到上面的菜单中.
Menu, Submenu1, Add, Item1, MenuHandler
Menu, Submenu1, Add, Item2, MenuHandler

; 创建第一个菜单的子菜单 (右箭头指示符). 当用户选择它时会显示第二个菜单.
Menu, MyMenu, Add, My Submenu, :Submenu1

Menu, MyMenu, Add  ; 在子菜单下添加分隔线.
Menu, MyMenu, Add, Item3, MenuHandler  ; 在子菜单下添加另一个菜单项.
return  ; 脚本的自动运行段结束.

MenuHandler:
MsgBox You selected %A_ThisMenuItem% from the menu %A_ThisMenu%.
return

#z::Menu, MyMenu, Show  ; 即按下 Win-Z 热键来显示菜单.

 

; 示例 #3: 这是个可运行脚本, 它演示了一些菜单命令.

#Persistent
#SingleInstance
menu, tray, add ; 分隔符
menu, tray, add, TestToggle&Check
menu, tray, add, TestToggleEnable
menu, tray, add, TestDefault
menu, tray, add, TestStandard
menu, tray, add, TestDelete
menu, tray, add, TestDeleteAll
menu, tray, add, TestRename
menu, tray, add, Test
return

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

TestToggle&Check:
menu, tray, ToggleCheck, TestToggle&Check
menu, tray, Enable, TestToggleEnable ; 同时启用了下一行的测试, 因为它不能撤销自己的禁用状态.
menu, tray, add, TestDelete ; 类似于上面.
return

TestToggleEnable:
menu, tray, ToggleEnable, TestToggleEnable
return

TestDefault:
if default = TestDefault
{
    menu, tray, NoDefault
    default =
}
else
{
    menu, tray, Default, TestDefault
    default = TestDefault
}
return

TestStandard:
if standard <> n
{
    menu, tray, NoStandard
    standard = n
}
else
{
    menu, tray, Standard
    standard = y
}
return

TestDelete:
menu, tray, delete, TestDelete
return

TestDeleteAll:
menu, tray, DeleteAll
return

TestRename:
if NewName <> renamed
{
    OldName = TestRename
    NewName = renamed
}
else
{
    OldName = renamed
    NewName = TestRename
}
menu, tray, rename, %OldName%, %NewName%
return

Test:
MsgBox, You selected "%A_ThisMenuItem%" in menu "%A_ThisMenu%".
return
; 示例 #4: 这是个添加图标到其菜单项的可运行脚本.
Menu, FileMenu, Add, Script Icon, MenuHandler
Menu, FileMenu, Add, Suspend Icon, MenuHandler
Menu, FileMenu, Add, Pause Icon, MenuHandler
Menu, FileMenu, Icon, Script Icon, %A_AhkPath%, 2 ;使用文件中的第二个图标组
Menu, FileMenu, Icon, Suspend Icon, %A_AhkPath%, -206 ;使用资源标识符 206 表示的图标
Menu, FileMenu, Icon, Pause Icon, %A_AhkPath%, -207 ;使用资源表示符 207 表示的图标
Menu, MyMenuBar, Add, &File, :FileMenu
Gui, Menu, MyMenuBar
Gui, Add, Button, gExit, Exit This Example
Gui, Show
MenuHandler:
Return

Exit:
ExitApp