Menu

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 MenuName parameter can be Tray or the name of any custom menu. A custom menu is automatically created the first time its name is used with the Add sub-command. For example: Menu, MyMenu, Add, Item1. Once created, a custom menu can be displayed with the Show sub-command. It can also be attached as a submenu to one or more other menus via the Add sub-command.

The SubCommand, Value1, Value2, Value3 and Value4 parameters are dependent on each other their usage is described below.

Sub-commands

Add

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.

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.

[v1.1.20+]: If it is not the name of an existing label, LabelOrSubmenu can be the name of a function, or a single variable reference containing a function object. For example, %FuncObj% or % FuncObj. See example #5 for a fully functional demonstration. Other expressions which return objects are currently unsupported. The function can optionally define parameters as shown below:

To have MenuItemName become a submenu -- which is a menu item that opens a new menu when selected -- specify for LabelOrSubmenu a colon followed by the MenuName of an existing custom menu. For example:

If not omitted, Options must be a space- or tab-delimited list of one or more of the following options:

Option	Description
Pn	Replace n with the menu item's thread priority, e.g. `P1`. If this option is omitted when adding a menu item, the priority will be 0, which is the standard default. If omitted when updating a menu item, the item's priority will not be changed. Use a decimal (not hexadecimal) number as the priority.
+Radio	[v1.1.23+]: If the item is checked, a bullet point is used instead of a check mark.
+Right	[v1.1.23+]: The item is right-justified within the menu bar. This only applies to menu bars, not popup menus or submenus.
+Break	[v1.1.23+]: The item begins a new column in a popup menu.
+BarBreak	[v1.1.23+]: As above, but with a dividing line between columns.

The plus sign (+) is optional and can be replaced with minus (-) to remove the option, as in -Radio. Options are not case sensitive.

To change an existing item's options without affecting its label or submenu, simply omit the LabelOrSubmenu parameter.

Insert [v1.1.23+]

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

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 each of its submenus to be destroyed, to be recreated later as needed. Other menus which contain those submenus may also be affected. This can be avoided by deleting the items of the menu with DeleteAll before deleting the menu itself.

DeleteAll

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

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

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

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).

NoStandard

Removes all standard (non-custom) menu items from the menu (if they are present).

Icon

Setting the tray icon

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.

The last parameter: Specify 1 for the last parameter to freeze the icon, or 0 to unfreeze it (or leave it blank to keep the frozen/unfrozen state unchanged). When the icon has been frozen, Pause and Suspend will not change it. Note: To freeze or unfreeze the current icon, use 1 or 0 as in the following example: Menu, Tray, Icon,,, 1.

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).

Slight distortion may occur when loading tray icons from file types other than .ICO. This is especially true for 16x16 icons. To prevent this, store the desired tray icon inside a .ICO file.

There are some icons built into the operating system's DLLs and CPLs that might be useful. For example: Menu, Tray, Icon, Shell32.dll, 174.

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).

[v1.1.23+]: An icon handle can be used instead of a filename. For example, Menu Tray, Icon, HICON:*%handle%. The asterisk is required as the icon must be "loaded" twice: once for the small icon and again for the large icon.

[v1.1.27+]: Non-icon image files and bitmap handles are supported for Filename. For example, Menu Tray, Icon, HBITMAP:*%handle%.

Setting the menu item's icon [AHK_L 17+]

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.

[v1.1.23+]: A bitmap or icon handle can be used instead of a filename. For example, HBITMAP:%handle%.

NoIcon

Removing the tray icon

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+]

MenuItemName is the name or position of a menu item (see MenuItemName for details).

Tip

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).

Show

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

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

Specify 1 for ClickCount to allow a single-click to activate the tray menu's default menu item. Specify 2 for ClickCount to return to the default behavior (double-click). For example: Menu, Tray, Click, 1.

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.

NoMainWindow

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.

UseErrorLevel

Skips any warning dialogs and thread terminations whenever the Menu command generates an error.

If this option is never used in the script, it defaults to OFF. The OFF setting displays a dialog and terminates the current thread whenever the Menu command generates an error. Specify Menu, Tray, UseErrorLevel to prevent the dialog and thread termination; instead, ErrorLevel will be set to 1 if there was a problem or 0 otherwise. To turn this option back off, specify OFF (or in [v1.1.30+], 0) for the next parameter. This setting is global, meaning it affects all menus, not just MenuName.

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:

When the Win32 menu is destroyed, the Win32 menu of each submenu and parent menu may also be destroyed.

When a menu which contains the standard items has its Win32 menu recreated, the standard items are placed at the top.

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

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.

New menu items are always added at the bottom of the menu. For the tray menu: To put your menu items on top of the standard menu items (after adding your own menu items) run Menu, Tray, NoStandard followed by Menu, Tray, Standard.

The standard menu items such as "Pause Script" and "Suspend Hotkeys" cannot be individually operated upon by any menu sub-command.

If a menu ever becomes completely empty -- such as by using Menu, MyMenu, DeleteAll -- it cannot be shown. If the tray menu becomes empty, right-clicking and double-clicking the tray icon will have no effect (in such cases it is usually better to use #NoTrayIcon).

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.

To keep a non-hotkey, non-GUI script running -- such as one that contains only custom menus or menu items -- use #Persistent.

Examples

Adds a new menu item to the bottom of the tray icon menu.

#Persistent  ; Keep the script running until the user exits it.
Menu, Tray, Add  ; Creates a separator line.
Menu, Tray, Add, Item1, MenuHandler  ; Creates a new menu item.
return

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

Creates a popup menu that is displayed when the user presses a hotkey.

; Create the popup menu by adding some items to it.
Menu, MyMenu, Add, Item1, MenuHandler
Menu, MyMenu, Add, Item2, MenuHandler
Menu, MyMenu, Add  ; Add a separator line.

; Create another menu destined to become a submenu of the above menu.
Menu, Submenu1, Add, Item1, MenuHandler
Menu, Submenu1, Add, Item2, MenuHandler

; Create a submenu in the first menu (a right-arrow indicator). When the user selects it, the second menu is displayed.
Menu, MyMenu, Add, My Submenu, :Submenu1

Menu, MyMenu, Add  ; Add a separator line below the submenu.
Menu, MyMenu, Add, Item3, MenuHandler  ; Add another menu item beneath the submenu.
return  ; End of script's auto-execute section.

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

#z::Menu, MyMenu, Show  ; i.e. press the Win-Z hotkey to show the menu.

Demonstrates some of the various menu sub-commands.

#Persistent
#SingleInstance
Menu, Tray, Add ; separator
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 ; Also enables the next test since it can't undo the disabling of itself.
Menu, Tray, Add, TestDelete ; Similar to above.
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 != false)
{
    Menu, Tray, NoStandard
    Standard := false
}
else
{
    Menu, Tray, Standard
    Standard := true
}
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

Demonstrates how to add icons to menu items.

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 ; Use the 2nd icon group from the file
Menu, FileMenu, Icon, Suspend Icon, %A_AhkPath%, -206 ; Use icon with resource identifier 206
Menu, FileMenu, Icon, Pause Icon, %A_AhkPath%, -207 ; Use icon with resource identifier 207
Menu, MyMenuBar, Add, &File, :FileMenu
Gui, Menu, MyMenuBar
Gui, Add, Button, gExit, Exit This Example
Gui, Show
return

MenuHandler:
return

Exit:
ExitApp

Demonstrates the usage of BoundFunc objects to pass additional parameters when using a function instead of a subroutine.

; Bind parameters to the function and return BoundFunc objects:
BoundGivePar := Func("GivePar").Bind("First", "Test one")
BoundGivePar2 := Func("GivePar").Bind("Second", "Test two")

; Create the menu and show it:
Menu MyMenu, Add, Give parameters, % BoundGivePar
Menu MyMenu, Add, Give parameters2, % BoundGivePar2
Menu MyMenu, Show

; Definition of custom function GivePar:
GivePar(a, b, ItemName, ItemPos, MenuName)
{
    MsgBox % "a:`t`t" a "`n"
           . "b:`t`t" b "`n"
           . "ItemName:`t" ItemName "`n"
           . "ItemPos:`t`t" ItemPos "`n"
           . "MenuName:`t" MenuName
}

Table of Contents

Sub-commands

Add

Insert [v1.1.23+]

Delete

DeleteAll

Rename

Check

Uncheck

ToggleCheck

Enable

Disable

ToggleEnable

Default

NoDefault

Standard

NoStandard

Icon

Setting the tray icon

Setting the menu item's icon [AHK_L 17+]

NoIcon

Removing the tray icon

Removing the menu item's icon [AHK_L 17+]

Tip

Show

Color

Click

MainWindow

NoMainWindow

UseErrorLevel

The MenuItemName Parameter

Win32 Menus

Remarks

Examples

Menu

Table of Contents

Sub-commands

Add

Insert [v1.1.23+]

Delete

DeleteAll

Rename

Check

Uncheck

ToggleCheck

Enable

Disable

ToggleEnable

Default

NoDefault

Standard

NoStandard

Icon

Setting the tray icon

Setting the menu item's icon [AHK_L 17+]

NoIcon

Removing the tray icon

Removing the menu item's icon [AHK_L 17+]

Tip

Show

Color

Click

MainWindow

NoMainWindow

UseErrorLevel

The MenuItemName Parameter

Win32 Menus

Remarks

Related

Examples