List of keys (keyboard, mouse and joystick)

Tray Icon

By default, each script adds its own icon to the taskbar notification area (commonly known as the tray).

The tray icon usually looks like this (but the color or letter changes when the script is paused or suspended):

Right-click the tray icon to show the tray menu, which has the following options by default:

• Open — Open the script’s .
• Help — Open the AutoHotkey offline help file.
• Window Spy — Displays various information about a window.
• Reload This Script — See Reload.
• Edit This Script — See Edit.
• Suspend Hotkeys — Suspend or unsuspend hotkeys.
• Pause Script — Pause or unpause the script.
• Exit — Exit the script.

By default, double-clicking the tray icon shows the script’s .

The Menu command can be used to customise the tray icon and menu.

The #NoTrayIcon directive can be used to hide the tray icon.

Other Features

NumLock, CapsLock, and ScrollLock: These keys may be forced to be «AlwaysOn» or «AlwaysOff». For example: .

Overriding Explorer’s hotkeys: Windows’ built-in hotkeys such as Win+E (#e) and Win+R (#r) can be individually overridden simply by assigning them to an action in the script. See the override page for details.

Substitutes for Alt-Tab: Hotkeys can provide an alternate means of alt-tabbing. For example, the following two hotkeys allow you to alt-tab with your right hand:

RControl & RShift::AltTab  ; Hold down right-control then press right-shift repeatedly to move forward.
RControl & Enter::ShiftAltTab  ; Without even having to release right-control, press Enter to reverse direction.

For more details, see .

Parameters

When a function is defined, its parameters are listed in parentheses next to its name (there must be no spaces between its name and the open-parenthesis). If a function does not accept any parameters, leave the parentheses empty; for example: .

ByRef Parameters: From the function’s point of view, parameters are essentially the same as unless they are defined as ByRef as in this example:

Swap(ByRef Left, ByRef Right)
{
    temp := Left
    Left := Right
    Right := temp
}

In the example above, the use of ByRef causes each parameter to become an alias for the variable passed in from the caller. In other words, the parameter and the caller’s variable both refer to the same contents in memory. This allows the Swap function to alter the caller’s variables by moving Left’s contents into Right and vice versa.

By contrast, if ByRef were not used in the example above, Left and Right would be copies of the caller’s variables and thus the Swap function would have no external effect.

Since return can send back only one value to a function’s caller, ByRef can be used to send back extra results. This is achieved by having the caller pass in a variable (usually empty) in which the function stores a value.

When passing large strings to a function, ByRef enhances performance and conserves memory by avoiding the need to make a copy of the string. Similarly, using ByRef to send a long string back to the caller usually performs better than something like .

: If something other than a modifiable variable is passed to a ByRef parameter, the function behaves as though the keyword «ByRef» is absent. For example, stores the value of A_Index in i, but the value assigned to Left is discarded once the Swap function returns.

: The function can be used to determine whether the caller supplied a variable for a given ByRef parameter.

Known limitations:

• Fields of objects are not considered variables for the purposes of ByRef. For example, if is passed to a ByRef parameter, it will behave as though ByRef was omitted.
• It is not possible to pass Clipboard, , or to a function’s ByRef parameter, even when #NoEnv is absent from the script.
• Although a function may call itself recursively, if it passes one of its own or non-ByRef parameters to itself ByRef, the new layer’s ByRef parameter will refer to its own local variable of that name rather than the previous layer’s. However, this issue does not occur when a function passes to itself a , , or ByRef parameter.
• If a parameter in a function-call resolves to a variable (e.g. or or ), other parameters to its left or right can alter that variable before it is passed to the function. For example, would unexpectedly pass 1 and 0 when Var is initially 0, even when the function’s first parameter is not ByRef. Since this behavior is counterintuitive, it might change in a future release.
• ByRef is not directly supported in functions called by COM clients, or when calling COM methods. Instead, the script receives or must pass a containing the VarType and address of the value.

General Remarks

Characters vs. keys: By default, characters are sent by first translating them to keystrokes. If this translation is not possible (that is, if the current keyboard layout does not contain a key or key combination which produces that character), the character is sent by one of following fallback methods:

• SendEvent and SendInput use SendInput() with the . : ANSI builds of AutoHotkey convert the character to Unicode before sending it. Prior to v1.1.27, ANSI builds used the Alt+nnnnn method.
• SendPlay uses the method, which produces Unicode only if supported by the target application.
• ControlSend posts a WM_CHAR message.

Note: Characters sent using any of the above methods usually do not trigger keyboard shortcuts or hotkeys.

: For characters in the range a-z or A-Z (plain ASCII letters), each character which does not exist in the current keyboard layout may be sent either as a character or as the corresponding virtual keycode (vk41-vk5A):

• If a naked letter is sent (that is, without modifiers or braces), or if mode is in effect, it is sent as a character. For example, sends the expected text, even though pressing the R key (vk52) produces some other character (such as К on the Russian layout). can be omitted in this case, unless a modifier key was put into effect by a prior Send.
• If one or more modifier keys have been put into effect by the Send command, or if the letter is wrapped in braces, it is sent as a keycode (modified with Shift if the letter is upper-case). This allows the script to easily activate standard keyboard shortcuts. For example, and activate the standard Ctrl+C shortcut and is equivalent to .

If the letter exists in the current keyboard layout, it is always sent as whichever keycode the layout associates with that letter (unless the is used, in which case the character is sent by other means). In other words, the section above is only relevant for non-Latin based layouts such as Russian.

Modifier State: When Send is required to change the state of the Win or Alt modifier keys (such as if the user was holding one of those keys), it may inject additional keystrokes (Ctrl by default) to prevent the Start menu or window menu from appearing. For details, see #MenuMaskKey.

BlockInput Compared to SendInput/SendPlay: Although the BlockInput command can be used to prevent any keystrokes physically typed by the user from disrupting the flow of simulated keystrokes, it is often better to use or so that keystrokes and mouse clicks become uninterruptible. This is because unlike BlockInput, SendInput/Play does not discard what the user types during the send; instead, such keystrokes are buffered and sent afterward.

When sending a large number of keystrokes, a can be used to improve readability and maintainability.

Since the operating system does not allow simulation of the Ctrl+Alt+Delete combination, doing something like will have no effect.

Send may have no effect on Windows Vista or later if the active window is running with administrative privileges and the script is not. This is due to a security mechanism called User Interface Privilege Isolation.

Send variants

Send: By default, Send is synonymous with SendEvent; but it can be made a synonym for SendInput or SendPlay via SendMode.

SendRaw: Similar to Send, except that all characters in Keys are interpreted and sent literally. See for details.

SendInput and SendPlay : SendInput and SendPlay use the same syntax as Send but are generally faster and more reliable. In addition, they buffer any physical keyboard or mouse activity during the send, which prevents the user’s keystrokes from being interspersed with those being sent. SendMode can be used to make Send synonymous with SendInput or SendPlay. For more details about each mode, see and below.

SendEvent : SendEvent sends keystrokes using the same method as the pre-1.0.43 Send command. The rate at which keystrokes are sent is determined by SetKeyDelay.

Introduction and Simple Examples

Hotkeys are sometimes referred to as shortcut keys because of their ability to easily trigger an action (such as launching a program or keyboard macro). In the following example, the hotkey Win+N is configured to launch Notepad. The pound sign stands for the Win key, which is known as a modifier:

#n::
Run Notepad
return

In the final line above, serves to finish the hotkey. However, if a hotkey needs to execute only a single line, that line can be listed to the right of the double-colon. In other words, the is implicit:

#n::Run Notepad

To use more than one modifier with a hotkey, list them consecutively (the order does not matter). The following example uses to indicate Control+Alt+S:

^!s::
Send Sincerely,{enter}John Smith  ; This line sends keystrokes to the active (foremost) window.
return

Custom Combinations

You can define a custom combination of two keys (except joystick buttons) by using » & » between them. In the below example, you would hold down Numpad0 then press the second key to trigger the hotkey:

Numpad0 & Numpad1::MsgBox You pressed Numpad1 while holding down Numpad0.
Numpad0 & Numpad2::Run Notepad

The prefix key loses its native function: In the above example, Numpad0 becomes a prefix key; but this also causes Numpad0 to lose its original/native function when it is pressed by itself. To avoid this, a script may configure Numpad0 to perform a new action such as one of the following:

Numpad0::WinMaximize A   ; Maximize the active/foreground window.
Numpad0::Send {Numpad0}  ; Make the release of Numpad0 produce a Numpad0 keystroke. See comment below.

Fire on release: The presence of one of the above custom combination hotkeys causes the release of Numpad0 to perform the indicated action, but only if you did not press any other keys while Numpad0 was being held down. : This behaviour can be avoided by applying the to either hotkey.

Modifiers: Unlike a normal hotkey, custom combinations act as though they have the modifier by default. For example, will activate even if Ctrl or Alt is held down when 1 and 2 are pressed, whereas would be activated only by Ctrl+1 and not Ctrl+Alt+1.

For standard modifier keys, normal hotkeys typically work as well or better than «custom» combinations. For example, is recommended over .

Combinations of three or more keys are not supported. Combinations which your keyboard hardware supports can usually be detected by using #If and GetKeyState(), but the results may be inconsistent. For example:

; Press AppsKey and Alt in any order, then slash (/).
#if GetKeyState("AppsKey", "P")
Alt & /::MsgBox Hotkey activated.

; If the keys are swapped, Alt must be pressed first (use one at a time):
#if GetKeyState("Alt", "P")
AppsKey & /::MsgBox Hotkey activated.

;  & \::
#if GetKeyState("")
\::MsgBox

Keyboard hook: Custom combinations involving keyboard keys always use the keyboard hook, as do any hotkeys which use the prefix key as a suffix. For example, causes to always use the hook.

Language Syntax

When are quotation marks used with commands and their parameters?

Double quotes («) have special meaning only within . In all other places, they are treated literally as if they were normal characters. However, when a script launches a program or document, the operating system usually requires quotes around any command-line parameter that contains spaces, such as in this example: .

When exactly are variable names enclosed in percent signs?

Variable names are always enclosed in percent signs except in cases illustrated in bold below:

1) In parameters that are input or output variables:
2) On the left side of an assignment:
3) On the left side of traditional (non-expression) if-statements:
4) Everywhere in . For example:

If (Var1 <> Var2)
    Var1 := Var2 + 100

For further explanation of how percent signs are used, see and . Percent signs can also have other meanings:

• The causes a command parameter to be interpreted as an expression.
• percent signs () and percent signs in have no special meaning (they are interpreted as literal percent signs).

When should percent signs and commas be escaped?

Literal percent signs must be escaped by preceding them with an accent/backtick. For example: Literal commas must also be escaped () except when used in MsgBox or the last parameter of any command (in which case the accent is permitted but not necessary).

When commas or percent signs are enclosed in quotes within an , the accent is permitted but not necessary. For example: .

Special modes

The following modes affect the interpretation of the characters in Keys or the behavior of key-sending commands such as Send, SendInput, SendPlay, SendEvent and ControlSend. These modes must be specified as in Keys, where x is either Raw, Text, or Blind. For example, .

Raw mode

The Raw mode can be either enabled with , SendRaw or ControlSendRaw, which causes all subsequent characters, including the special characters , to be interpreted literally rather than translating to Enter, to Control+C, etc. For example, both and send instead of a Tab keystroke.

The Raw mode does not affect the interpretation of escape sequences, and . For example, sends the string . When using ControlSend, it is also necessary to escape literal commas ().

Text mode

The Text mode can be enabled with , which is similar to the Raw mode, except that no attempt is made to translate characters (other than , , and ) to keycodes; instead, the is used for all of the remaining characters. For SendEvent, SendInput and ControlSend, this improves reliability because the characters are much less dependent on correct modifier state. This mode can be combined with the Blind mode to avoid releasing any modifier keys: . However, some applications require that the modifier keys be released.

, and are all translated to a single Enter keystroke, unlike the default behavior and Raw mode, which translate to two Enter keystrokes. is translated to Tab and to Backspace, but all other characters are sent without translation.

: Like the Blind mode, the Text mode ignores SetStoreCapsLockMode (that is, the state of CapsLock is not changed) and does not . This is because the Text mode typically does not depend on the state of CapsLock and cannot trigger the system Win+L hotkey. However, this only applies when Keys begins with or .

Blind mode

The Blind mode can be enabled with , which gives the script more control by disabling a number of things that are normally done automatically to make things work as expected. must be the first item in the string to enable the Blind mode. It has the following effects:

• The Blind mode avoids releasing Alt/Control/Shift/Win if they started out in the down position. For example, the hotkey would send ABC rather than abc because the user is holding down Shift.
• Modifier keys are restored differently to allow a Send to turn off a hotkey’s modifiers even if the user is still physically holding them down. For example, automatically pushes Ctrl back down if the user is still physically holding Ctrl, whereas allows Ctrl to be logically up even though it is physically down.
• SetStoreCapsLockMode is ignored; that is, the state of CapsLock is not changed.
• Menu masking is disabled. That is, Send omits the extra keystrokes that would otherwise be sent in order to prevent: 1) Start Menu appearance during Win keystrokes (LWin/RWin); 2) menu bar activation during Alt keystrokes. However, the Blind mode does not prevent masking performed by the keyboard hook following activation of a hook hotkey.
• Send does not wait for the Win key to be released even if the text contains an L keystroke. This would normally be done to prevent Send from triggering the system «lock workstation» hotkey (Win+L). See for details.

The Blind mode is used internally when remapping a key. For example, the remapping would produce: 1) «b» when you type «a»; 2) uppercase «B» when you type uppercase «A»; and 3) Control+B when you type Control+A.

is not supported by SendRaw or ControlSendRaw; use instead.

The Blind mode is not completely supported by , especially when dealing with the modifier keys (Control, Alt, Shift, and Win).

SendInput [v1.0.43+]

SendInput is generally the preferred method to send keystrokes and mouse clicks because of its superior speed and reliability. Under most conditions, SendInput is nearly instantaneous, even when sending long strings. Since SendInput is so fast, it is also more reliable because there is less opportunity for some other window to pop up unexpectedly and intercept the keystrokes. Reliability is further improved by the fact that anything the user types during a SendInput is postponed until afterward.

Unlike the other sending modes, the operating system limits SendInput to about 5000 characters (this may vary depending on the operating system’s version and performance settings). Characters and events beyond this limit are not sent.

Note: SendInput ignores SetKeyDelay because the operating system does not support a delay in this mode. However, when SendInput reverts to under the conditions described below, it uses (unless SendEvent’s KeyDelay is , in which case is used). When SendInput reverts to , it uses SendPlay’s KeyDelay.

If a script other than the one executing SendInput has a low-level keyboard hook installed, SendInput automatically reverts to (or if is in effect). This is done because the presence of an external hook disables all of SendInput’s advantages, making it inferior to both SendPlay and SendEvent. However, since SendInput is unable to detect a low-level hook in programs other than , it will not revert in these cases, making it less reliable than SendPlay/Event.

When SendInput sends mouse clicks by means such as , and is in effect (the default), every click will be relative to the window that was active at the start of the send. Therefore, if SendInput intentionally activates another window (by means such as alt-tab), the coordinates of subsequent clicks within the same command will be wrong because they will still be relative to the old window rather than the new one.

Run a Script

With AutoHotkey installed, there are several ways to run a script:

• Double-click a script file (or shortcut to a script file) in Explorer.
• Call AutoHotkey.exe on the command line and pass the script’s filename as a .
• After creating , launch AutoHotkey via the shortcut in the Start menu to run it.
• If AutoHotkey is pinned to the taskbar or Start menu on Windows 7 or later, recent or pinned scripts can be launched via the program’s Jump List.

Most scripts have an effect only while they are running. Use the or the ExitApp command to exit a script. Scripts are also forced to exit when Windows shuts down. To configure a script to start automatically after the user logs in, the easiest way is to place a shortcut to the script file in the folder.

Scripts can also be ; that is, combined together with an AutoHotkey binary file to form a self-contained executable (.exe) file.

Repeating or Holding Down a Key

To repeat a keystroke: Enclose in braces the name of the key followed by the number of times to repeat it. For example:

Send {DEL 4}  ; Presses the Delete key 4 times.
Send {S 30}   ; Sends 30 uppercase S characters.
Send +{TAB 4}  ; Presses Shift-Tab 4 times.

To hold down or release a key: Enclose in braces the name of the key followed by the word Down or Up. For example:

Send {b down}{b up}
Send {TAB down}{TAB up}
Send {Up down}  ; Press down the up-arrow key.
Sleep 1000  ; Keep it down for one second.
Send {Up up}  ; Release the up-arrow key.

When a key is held down via the method above, it does not begin auto-repeating like it would if you were physically holding it down (this is because auto-repeat is a driver/hardware feature). However, a Loop can be used to simulate auto-repeat. The following example sends 20 tab keystrokes:

Loop 20
{
    Send {Tab down}  ; Auto-repeat consists of consecutive down-events (with no up-events).
    Sleep 30  ; The number of milliseconds between keystrokes (or use SetKeyDelay).
}
Send {Tab up}  ; Release the key.

By default, Send will not automatically release a modifier key (Control/Shift/Alt/Win) if that modifier key was «pressed down» by sending it. For example, may behave similar to if the user is physically holding Ctrl, but followed by will produce a Control+A keystroke. DownTemp and DownR can be used to override this behavior. DownTemp and DownR have the same effect as Down except for the modifier keys (Control/Shift/Alt/Win).

DownTemp tells subsequent sends that the key is not permanently down, and may be released whenever a keystroke calls for it. For example, followed later by would produce a normal A keystroke, not a Control+A keystroke. Any use of Send may potentially release the modifier permanently, so DownTemp is not ideal for remapping modifier keys.

: DownR (where «R» stands for remapping, which is its main use) tells subsequent sends that if the key is automatically released, it should be pressed down again when send is finished. For example, followed later by would produce a normal A keystroke, not a Control+A keystroke, but will leave the Control key in the pressed state for use with keyboard shortcuts. In other words, DownR has an effect similar to physically pressing the key.

If a character does not correspond to a virtual key on the current keyboard layout, it cannot be «pressed» or «released». For example, has no effect on most layouts, and is equivalent to .

Hotkeys, Hotstrings, and Remapping

How do I put my hotkeys and hotstrings into effect automatically every time I start my PC?

There are several ways to make a script (or any program) launch automatically every time you start your PC. The easiest is to place a shortcut to the script in the Startup folder:

1. Find the script file, select it, and press Control+C.
2. Press Win+R to open the Run dialog, then enter and click OK or Enter. This will open the Startup folder for the current user. To instead open the folder for all users, enter (however, in that case you must be an administrator to proceed).
3. Right click inside the window, and click «Paste Shortcut». The shortcut to the script should now be in the Startup folder.

I’m having trouble getting my mouse buttons working as hotkeys. Any advice?

The left and right mouse buttons should be assignable normally (for example, is the Win+LeftButton hotkey). Similarly, the middle button and the turning of the mouse wheel should be assignable normally except on mice whose drivers directly control those buttons.

The fourth button (XButton1) and the fifth button (XButton2) might be assignable if your mouse driver allows their clicks to be seen by the system. If they cannot be seen — or if your mouse has more than five buttons that you want to use — you can try configuring the software that came with the mouse (sometimes accessible in the Control Panel or Start Menu) to send a keystroke whenever you press one of these buttons. Such a keystroke can then be defined as a hotkey in a script. For example, if you configure the fourth button to send Control+F1, you can then indirectly configure that button as a hotkey by using in a script.

If you have a five-button mouse whose fourth and fifth buttons cannot be seen, you can try changing your mouse driver to the default driver included with the OS. This assumes there is such a driver for your particular mouse and that you can live without the features provided by your mouse’s custom software.

How can Tab and Space be defined as hotkeys?

Use the names of the keys (Tab and Space) rather than their characters. For example, is Win+Space and is Control+Alt+Tab.

How do I detect the double press of a key or button?

Use as follows:

~Ctrl::
    if (A_ThisHotkey = A_PriorHotkey && A_TimeSincePriorHotkey < 200)
        MsgBox double-press
return

How can a hotkey or hotstring be made exclusive to certain program(s)? In other words, I want a certain key to act as it normally does except when a specific window is active.

The preferred method is #IfWinActive. For example:

#IfWinActive, ahk_class Notepad
^a::MsgBox You pressed Control-A while Notepad is active.

How can a prefix key be made to perform its native function rather than doing nothing?

Consider the following example, which makes Numpad0 into a prefix key:

Numpad0 & Numpad1::MsgBox, You pressed Numpad1 while holding down Numpad0.

Now, to make Numpad0 send a real Numpad0 keystroke whenever it wasn’t used to launch a hotkey such as the above, add the following hotkey:

 $Numpad0::Send, {Numpad0}

The $ prefix is needed to prevent a warning dialog about an infinite loop (since the hotkey «sends itself»). In addition, the above action occurs at the time the key is released.

My keypad has a special 000 key. Is it possible to turn it into a hotkey?

Yes. This makes the 000 key into an equals key. You can change the action by replacing the line with line(s) of your choice.

Variadic Functions [AHK_L 60+]

When defining a function, write an asterisk after the final parameter to mark the function as variadic, allowing it to receive a variable number of parameters:

Join(sep, params*) {
    for index,param in params
        str .= param . sep
    return SubStr(str, 1, -StrLen(sep))
}
MsgBox % Join("`n", "one", "two", "three")

When a variadic function is called, surplus parameters can be accessed via an object which is stored in the function’s final parameter. The first surplus parameter is at , the second at and so on. As with any standard object, can be used to determine the highest numeric index (in this case the number of parameters). However, if there are no parameters, MaxIndex returns an empty string.

Notes:

• The «variadic» parameter can only appear at the end of the formal parameter list.
• RegEx callouts cannot be variadic; the «variadic» parameter is tolerated but left blank.
• Callbacks pass surplus parameters rather than via an array.

Variadic Function Calls

While variadic functions can accept a variable number of parameters, an array of parameters can be passed to any function by applying the same syntax to a function-call:

substrings := 
MsgBox % Join("`n", substrings*)

Notes:

• Numbering of parameters within the source array begins at 1.
• Optional parameters may be entirely omitted from the array.
• The array of parameters may contain named items when calling a user-defined function; in any other case, named items are not supported.
• The target function may also be variadic, in which case named items are copied even if they have no corresponding formal parameter.
• This syntax can also be used when calling methods or retrieving properties of objects; for example, . : It can also be used for setting properties.

Known limitations:

• Only the right-most parameter can be expanded this way. For example, is supported but is not.
• There must not be any non-whitespace characters between the asterisk () and the symbol which ends the parameter list.