Creates, deletes, modifies and displays menus and menu items. Changes the tray icon and its tooltip. Controls whether the main window of a compiled script can be opened.
The SubCommand, Value1, Value2, Value3 and Value4 parameters are dependent on each other their usage is described below.
Table of Contents
Sub-commands
For SubCommand, specify one of the following:
Adds a menu item, updates one with a new submenu or label, or converts one from a normal item into a submenu (or vice versa).
This is a multipurpose sub-command. MenuItemName is the name or position of a menu item (see MenuItemName for details). If MenuItemName does not yet exist, it will be added to the menu. Otherwise, MenuItemName is updated with the newly specified LabelOrSubmenu.
To add a menu separator line, omit all three parameters.
The label subroutine is run as a new thread when the user selects the menu item (similar to Gosub and hotkey subroutines). If LabelOrSubmenu is omitted, MenuItemName will be used as both the label and the menu item’s name.
If not omitted, Options must be a space- or tab-delimited list of one or more of the following options:
To change an existing item’s options without affecting its label or submenu, simply omit the LabelOrSubmenu parameter.
Insert [v1.1.23+]
Inserts a new item before the specified menu item.
Usage is identical to the Add sub-command (above), except that MenuItemName is always the name or position of an existing menu item (see MenuItemName for details) and ItemToInsert is the name of a new menu item to insert before MenuItemName. Menu items can also be appended by omitting MenuItemName (by writing two consecutive commas). Unlike the Add sub-command, the Insert sub-command creates a new menu item even if MenuItemName matches the name of an existing menu item.
Delete
Deletes the specified menu item from the menu.
MenuItemName is the name or position of a menu item (see MenuItemName for details). Standard menu items such as «Exit» (see below) cannot be individually deleted. If the default menu item is deleted, the effect will be similar to having used the NoDefault sub-command. If MenuItemName is omitted, the entire MenuName menu will be deleted as will any menu items in other menus that use MenuName as a submenu. Deleting a menu also causes the current Win32 menu of its parent and submenus to be destroyed, to be recreated later as needed.
DeleteAll
Deletes all custom menu items from the menu.
Any existing standard menu items (see below) remain unaffected. Unlike a menu entirely deleted by the Delete sub-command (see above), an empty menu still exists and thus any other menus that use it as a submenu will retain those submenus.
Rename
Renames the specified menu item to NewName.
If NewName is blank, the specified menu item will be converted into a separator line. MenuItemName is the name or position of a menu item (see MenuItemName for details). The menu item’s current target label or submenu is unchanged. [v1.1.23+]: A separator line can be converted to a normal menu item by specifying the position& of the separator and a non-blank NewName, and then using the Add sub-command to give the menu item a label or submenu.
Check
Adds a visible checkmark in the menu next to the specified menu item (if there isn’t one already).
MenuItemName is the name or position of a menu item (see MenuItemName for details).
Uncheck
Removes the checkmark (if there is one) from the specified menu item.
MenuItemName is the name or position of a menu item (see MenuItemName for details).
ToggleCheck
Adds a checkmark to the specified menu item if there wasn’t one; otherwise, removes it.
MenuItemName is the name or position of a menu item (see MenuItemName for details).
Enable
Allows the user to once again select the specified menu item if was previously disabled (grayed).
MenuItemName is the name or position of a menu item (see MenuItemName for details).
Disable
Changes the specified menu item to a gray color to indicate that the user cannot select it.
MenuItemName is the name or position of a menu item (see MenuItemName for details).
ToggleEnable
Disables the specified menu item if it was previously enabled; otherwise, enables it.
MenuItemName is the name or position of a menu item (see MenuItemName for details).
Default
Changes the menu’s default item to be the specified menu item and makes its font bold.
Setting a default item in menus other than TRAY is currently purely cosmetic. MenuItemName is the name or position of a menu item (see MenuItemName for details). When the user double-clicks the tray icon, its default menu item is launched. If there is no default, double-clicking has no effect. If MenuItemName is omitted, the effect is the same as having used the NoDefault sub-command below.
NoDefault
Reverses setting a user-defined default menu item.
For the tray menu: Changes the menu back to having its standard default menu item, which is OPEN for non-compiled scripts and none for compiled scripts (except when the MainWindow sub-command is in effect). If the OPEN menu item does not exist due to a previous use of the NoStandard sub-command below, there will be no default and thus double-clicking the tray icon will have no effect. For menus other than TRAY: Any existing default item is returned to a non-bold font.
Standard
Inserts the standard menu items at the bottom of the menu (if they are not already present).
This sub-command can be used with the tray menu or any other menu.
NoStandard
Removes all standard (non-custom) menu items from the menu (if they are present).
This sub-command can be used with the tray menu or any other menu.
Affects the tray icon or [in AHK_L 17+] the menu item’s icon depending on syntax usage below.
Setting the tray icon
Changes the script’s tray icon to one of the ones from FileName.
The following types of files are supported: ICO, CUR, ANI, EXE, DLL, CPL, SCR, and other types that contain icon resources. To use an icon group other than the first one in the file, specify its number for IconNumber (if omitted, it defaults to 1). For example, 2 would load the default icon from the second icon group. If IconNumber is negative, its absolute value is assumed to be the resource ID of an icon within an executable file. Specify an asterisk (*) for FileName to restore the script to its default icon.
Changing the tray icon also changes the icon displayed by InputBox, Progress, and subsequently-created GUI windows. Compiled scripts are also affected even if a custom icon was specified at the time of compiling.
Note: Changing the icon will not unhide the tray icon if it was previously hidden by means such as #NoTrayIcon; to do that, use Menu, Tray, Icon (with no parameters).
The built-in variables A_IconNumber and A_IconFile contain the number and name (with full path) of the current icon (both are blank if the icon is the default).
Setting the menu item’s icon [AHK_L 17+]
Sets a icon for the specified menu item.
MenuItemName is the name or position of a menu item (see MenuItemName for details). FileName can either be an icon file or any image in a format supported by AutoHotkey. To use an icon group other than the first one in the file, specify its number for IconNumber (if omitted, it defaults to 1). If IconNumber is negative, its absolute value is assumed to be the resource ID of an icon within an executable file. Specify the desired width of the icon in IconWidth. If the icon group indicated by IconNumber contains multiple icon sizes, the closest match is used and the icon is scaled to the specified size. See example #4 for usage examples.
Currently it is necessary to specify «actual size» when setting the icon to preserve transparency on Windows Vista and later. For example:
Known limitation: Icons on Gui menu bars are positioned incorrectly on Windows XP and older.
NoIcon
Affects the tray icon or [in AHK_L 17+] the menu item’s icon depending on syntax usage below.
Removing the tray icon
Removes the tray icon if it exists.
If this sub-command is used at the very top of the script, the tray icon might be briefly visible when the script is launched. To prevent that, use #NoTrayIcon instead. The built-in variable A_IconHidden contains 1 if the tray icon is currently hidden or 0 otherwise.
Removing the menu item’s icon [AHK_L 17+]
Removes the icon from the specified menu item, if any.
MenuItemName is the name or position of a menu item (see MenuItemName for details).
Changes the tray icon’s tooltip.
The tray icon’s tooltip is displayed when the mouse hovers over it. To create a multi-line tooltip, use the linefeed character (`n) in between each line, e.g. Line1`nLine2. Only the first 127 characters of Text are displayed, and Text is truncated at the first tab character, if present. If Text is omitted, the tooltip is restored to its default text. The built-in variable A_IconTip contains the current text of the tooltip (blank if the text is at its default).
The user can select an item with arrow keys, menu shortcuts (underlined letters), or the mouse. Any menu can be shown, including the tray menu but with the exception of GUI menu bars. If both X and Y are omitted, the menu is displayed at the current position of the mouse cursor. If only one of them is omitted, the mouse cursor’s position will be used for it. X and Y are relative to the active window. Specify «CoordMode, Menu» beforehand to make them relative to the entire screen.
Color
Changes the background color of the menu to ColorValue.
ColorValue is one of the 16 primary HTML color names or a 6-digit RGB color value (see color chart). Leave ColorValue blank (or specify the word Default) to restore the menu to its default color. If the word Single is not present as the next parameter, any submenus attached to this menu will also be changed in color.
Click
Sets the number of clicks to activate the tray menu’s default menu item.
MainWindow
Allows the main window of a script to be opened via the tray icon, which is impossible by default for compiled or embedded scripts.
This sub-command restores the «Open» option to the tray menu, unless the NoStandard sub-command was used. It also enables the items in the main window’s View menu such as «Lines most recently executed», which allows viewing of the script’s source code and other info.
This mode is the default for scripts which are neither compiled nor embedded.
NoMainWindow
Prevents the main window from being opened via the tray icon.
This sub-command removes the standard «Open» option from the tray menu. It also disables the items in the main window’s View menu such as «Lines most recently executed». However, the following commands are still able to show the main window and activate the corresponding View options when they are encountered in the script at runtime: ListLines, ListVars, ListHotkeys, and KeyHistory.
This sub-command does not prevent the main window from being shown by WinShow or inspected by ControlGetText or similar methods, but it does prevent the script’s source code and other info from being exposed via the main window, except when one of the commands listed above is called by the script.
This mode is the default for scripts which are compiled or embedded.
[v1.1.34+]: This sub-command can be used even in a non-compiled script.
UseErrorLevel
Skips any warning dialogs and thread terminations whenever the Menu command generates an error.
The MenuItemName Parameter
The name or position of a menu item. Some common rules apply to this parameter across all sub-commands which use it:
Win32 Menus
As items are added to a menu or modified, the name and other properties of each item are recorded by the Menu command, but the actual Win32 menu is not constructed immediately. This occurs when the menu or its parent menu is attached to a GUI or shown, either for the first time or if the menu has been «destroyed» since it was last shown. Any of the following can cause this Win32 menu to be destroyed, along with any parent menus and submenus:
Any modifications which are made to the menu directly by Win32 API calls only apply to the current «instance» of the menu, and are lost when the menu is destroyed.
Each menu item is assigned an ID when it is first added to the menu. Scripts cannot rely on an item receiving a particular ID, but can retrieve the ID of an item by using GetMenuItemID as shown in the MenuGetHandle example. This ID cannot be used with the Menu command, but can be used with various Win32 functions.
Remarks
A menu usually looks like this:
The names of menus and menu items can be up to 260 characters long.
Separator lines can be added to the menu by using Menu, MenuName, Add (i.e. omit all other parameters). [v1.1.23+] : To delete separator lines individually, identify them by their position in the menu. For example, use Menu, MenuName, Delete, 3& if there are two items preceding the separator. Alternatively, use Menu, MenuName, DeleteAll and then re-add your custom menu items.
The standard menu items such as «Pause Script» and «Suspend Hotkeys» cannot be individually operated upon by any menu sub-command.
If a menu item’s subroutine is already running and the user selects the same menu item again, a new thread will be created to run that same subroutine, interrupting the previous thread. To instead buffer such events until later, use Critical as the subroutine’s first line (however, this will also buffer/defer other threads such as the press of a hotkey).
Whenever a subroutine is launched via a menu item, it starts off fresh with the default values for settings such as SendMode. These defaults can be changed in the auto-execute section.
The built-in variables A_ThisMenuItem and A_ThisMenuItemPos contain the name and position of the custom menu item most recently selected by the user (blank if none). Similarly, A_ThisMenu is the name of the menu from which A_ThisMenuItem was selected. These variables are useful when building a menu whose contents are not always the same. In such a case, it is usually best to point all such menu items to the same label and have that label refer to the above variables to determine what action to take.
Related
Examples
Adds a new menu item to the bottom of the tray icon menu.
Создаёт, удаляет, модифицирует и показывает меню. Изменяет значок скрипта в области уведомлений (трее) и всплывающую подсказку этого значка. Для компилированных скриптов определяет, может ли быть открыто главное окно скрипта.
Параметры
Добавление или изменение пунктов меню
Add [, MenuItemName, Label-or-Submenu, Pn] Это многоцелевая команда, которая может добавить пункт меню, обновить сопоставленные ему метку или подменю или преобразовать нормальный пункт меню в подменю (и наоборот). Если пункт, чьё имя задано в параметре MenuItemName, ещё не существует, он будет добавлен. Иначе будут обновлены его метка или подменю.
Чтобы добавить не пункт, а линию-разделитель, опустите все 3 параметра в квадратных скобках.
Подпрограмма, на которую указывает метка, запускается как новый поток, когда пользователь выбирает соответствующий пункт в меню (так же, как это происходит по команде Gosub или нажатию горячей клавиши). Если параметр Label-or-Submenu опущен, значение MenuItemName будет использовано одновременно как имя пункта меню и как имя метки.
Чтобы превратить MenuItemName в подменю, т.е. в пункт, который, будучи выбранным, открывает новое меню, задайте параметр Label-or-Submenu как двоеточие со следующим сразу за ним именем уже существующего пользовательского меню. Например:
Параметр Pn позволяет задать приоритет запускаемого данным пунктом потока. Например, P1. Если при добавлении пункта этот параметр опущен, приоритет будет 0, что является стандартным значением по умолчанию. Если этот параметр опущен при изменении пункта, существующий приоритет не будет изменён. Если у пункта нужно изменить только приоритет, опустите параметр Label-or-Submenu. При задании значения приоритета используйте десятичные числа.
Delete [, MenuItemName] Удаляет пункт из меню. Стандартные пункты, такие как Exit (см. ниже), не могут удаляться по отдельности. Если удаляется пункт по умолчанию, эффект будет тот же, что и при использовании опции NoDefault. Если параметр MenuItemName опущен, всё меню, указанное в MenuName, будет удалено, так же как и все пункты в других меню, которые используют это меню как подменю.
DeleteAll Удаляет из меню все пункты, добавленные пользователем, оставляя меню пустым, если только оно не содержит стандартных пунктов (см. ниже). В отличие от меню, полностью удаляемого командой Delete, пустое меню продолжает существовать, так что все другие меню, использующие его как своё подменю, сохранят соответствующий пункт.
Rename, MenuItemName [, NewName] Переименовывает пункт меню. Новое имя задаётся в параметре NewName. Если этот параметр пустой, пункт будет преобразован в линию-разделитель. Новое имя не должно совпадать с каким-то из уже существующих имён пользовательских пунктов. Связанные с пунктом метка или подменю не изменяются.
Check, MenuItemName Ставит отметку рядом с именем пункта (если она уже не стоит).
Uncheck, MenuItemName Убирает отметку, если она есть.
ToggleCheck, MenuItemName Ставит отметку, если её нет. Убирает, если есть.
Enable, MenuItemName Разблокирует пункт меню, если он был ранее блокирован.
Disable, MenuItemName Блокирует пункт меню (делает его серым).
ToggleEnable, MenuItemName Разблокирует пункт, если он блокирован. Блокирует, если он действующий.
Default [, MenuItemName] Задаёт пункт по умолчанию и выделяет его имя в меню жирным шрифтом (применение этой команды ко всем меню, кроме того, что в области уведомлений, в настоящее время даёт лишь косметический эффект). Когда пользователь делает двойной щелчок по значку скрипта в трее, задействуется пункт меню по умолчанию. Если параметр MenuItemName опущен, команда действует так же, как команда NoDefault ниже.
NoDefault Для меню в области уведомлений означает возвращение к стандартному пункту по умолчанию. Если скрипт не компилированный, то это пункт Open, если компилированный, то пункта по умолчанию нет (за исключением случая, когда была выбрана опция MainWindow). Если пункт Open в меню отсутствует из-за того, что ранее была использована команда NoStandard (см. ниже), умолчательный пункт будет отсутствовать, так что двойной щелчок по значку в трее не будет производить никакого эффекта. Для меню не в области уведомлений жирный шрифт в имени пункта по умолчанию будет заменён на обычный.
Standard Добавляет стандартные пункты в нижнюю часть меню (если их ещё нет). Эта команда применима к любому меню.
NoStandard Удаляет стандартные (не пользовательские) пункты из меню в области уведомлений (если таковые присутствуют).
Изменение значка в области уведомлений или его подсказки (MenuName должно быть Tray)
Icon [, FileName, IconNumber, 1] Заменяет значок скрипта на один из тех, что имеются в файле, указанном в параметре FileName. Поддерживаются файлы с расширениями ICO, CUR, ANI, EXE, DLL, CPL, SCR и другие, в которых содержатся значки. Чтобы использовать группу значков иную, чем первая, укажите её номер в параметре IconNumber (если опущен, считается равным 1). Например, значение 2 загрузит значок по умолчанию из второй группы. Укажите звёздочку (*) как значение FileName, чтобы вернуть скрипт к его значку по умолчанию.
Последний параметр может принимать значения 1 или 0, которые означают «замораживание» и «размораживание» значка. Замороженный значок не будет изменять свой вид при выполнении команд Pause и Suspend. Чтобы заморозить текущий значок, используйте команду Menu, Tray, Icon. 1 (или 0, чтобы разморозить).
Изменение значка в трее влияет также на значок, используемый InputBox, Progress и создаваемыми впоследствии окнами GUI. Это также затрагивает компилированные скрипты, даже если при компиляции им был присвоен собственный значок. Примечание: изменение значка не показывает значок, если он был до этого спрятан, например, директивой #NoTrayIcon; чтобы сделать это, используйте команду Menu, Tray, Icon (без параметров).
При отображении значков из файлов иного формата, чем ICO, возможны небольшие искажения, особенно для значков 16×16. Чтобы избежать этого, храните значки в ICO-файлах.
Значки можно найти в системных файлах с расширениями DLL и CPL. Например:
Встроенные переменные A_IconNumber и A_IconFile содержат номер и полный путь используемого значка (обе они пусты, если используется значок по умолчанию).
Icon (без параметров) Создаёт значок в трее, если он отсутствует. Отменяет действие директивы #NoTrayIcon, если она присутствует в скрипте.
Разное
Show [, X, Y] Показывает меню, позволяя пользователю выбрать пункт с помощью клавиш-стрелок, акселераторов (подчёркнутые буквы) или мышью. Показано может быть любое меню, за исключением строки меню GUI. Если обе координаты (X и Y) опущены, меню показывается в месте, где курсор мыши. Если опущена одна из них, её значение берётся из координат курсора мыши. Координаты считаются относительно активного окна. Используйте предварительно команду CoordMode, Menu, чтобы перейти к экранным координатам.
Color, ColorValue [, Single] Заменяет цвет фона меню на заданный в параметре ColorValue. Возможные значения включают 16 имён цветов, используемые в HTML, а также 6-значные числа в формате RGB (красный-зелёный-синий, см. примеры в статье SplashImage). Чтобы вернуть меню его цвет по умолчанию, оставьте этот параметр пустым (или задайте его словом Default). Если слово Single не присутствует в качестве последнего параметра, все подменю также изменят цвет фона.
Click, ClickCount Если ClickCount задать как 1, это позволит пункту по умолчанию срабатывать от одиночного щелчка по значку в трее. Чтобы вернуться к двойному щелчку, задайте 2. Например:
MainWindow Эта команда действует только на компилированные скрипты, позволяя главному окну скрипта открываться через значок в трее, что иначе невозможно. Она также включает пункты в меню View главного окна, такие как «Lines most recently executed» (последние выполненные строки), позволяя пользователю просматривать исходный код скрипта и другую информацию. MenuName должно иметь значение TRAY.
NoMainWindow (по умолчанию) Действует на компилированные скрипты. Запрещает открытие главного окна. Но даже если выбрана эта опция, следующие команды всё-таки способны показывать главное окно во время выполнения скрипта: ListLines, ListVars, ListHotkeys и KeyHistory. MenuName должно иметь значение TRAY.
UseErrorLevel [, off] Если эта опция в скрипте не используется, она имеет значение по умолчанию OFF. В этом случае при ошибке в ходе выполнения команды меню будет показано диалоговое окно и выполнение текущего потока будет прекращено. Если же использовать такую команду: Menu, Tray, UseErrorLevel, то в случае ошибки диалоговое окно показано не будет и поток не будет остановлен; вместо этого значение переменной ErrorLevel будет равно 1. Чтобы вернуться к настройке по умолчанию, используйте команду с параметром OFF. Эта установка имеет глобальное действие и затрагивает все меню, а не только указанное в параметре MenuName.
Примечания
Чтобы подчеркнуть одну из букв в имени пункта, поставьте перед ней амперсанд (&). Когда меню показано, такой пункт может быть выбран нажатием соответствующей буквы на клавиатуре. Чтобы показать амперсанд как обычный текстовый символ, используйте его дважды. Например: Save && Exit.
Имена меню и пунктов могут содержать до 260 символов.
При ссылках на существующие меню или пункты, регистр можно не учитывать, но амперсанды должны быть указаны. Например, &Open.
Новые пункты всегда добавляются снизу. Для меню в трее: чтобы поместить ваши (уже добавленные) пункты выше стандартных, используйте команду Menu, tray, NoStandard, а затем Menu, tray, Standard.
На стандартные пункты меню, такие как «Pause Script» и «Suspend Hotkeys», нельзя воздействовать индивидуально через какие-либо подкоманды команды Menu.
Когда меню пустое, как, например, после использования команды Menu, MyMenu, DeleteAll, оно не может быть показано. Если пустым становится меню в трее, щелчки мыши по значку не производят никакого эффекта (в таких случаях обычно лучше использовать директиву #NoTrayIcon).
Если связанная с пунктом подпрограмма уже выполняется, а пользователь опять выбирает этот пункт, подпрограмма будет снова запущена, как новый поток, прерывающий (приостанавливающий) выполнение предыдущего. Чтобы вместо этого повторный выбор пункта буферизовался (был отсрочен), используйте команду Critical в качестве первой строки подпрограммы (однако это приведёт к тому, что буферизоваться будут и другие события, такие как нажатие горячей клавиши).
Запускаемая через меню подпрограмма стартует со значениями по умолчанию для настроек, таких, как SendMode. Эти умолчания могут быть изменены в секции автовыполнения (верхняя часть скрипта).
Встроенные переменные A_ThisMenuItem и A_ThisMenuItemPos содержат имя и позицию последнего использованного пункта пользовательского меню. A_ThisMenu содержит имя этого меню. Эти переменные полезны для меню, чьи пункты могут меняться. В этом случае обычно лучше всего привязать все такие пункты к одной и той же подпрограмме, которая определяла бы по вышеупомянутым переменным, какой пункт её вызвал, и совершала соответствующие действия.
Чтобы скрипт, содержащий только меню, оставался постоянно в памяти, используйте директиву #Persistent.
