Table of Contents Introduction and Simple Examples Hotkey Modifier Symbols Context-sensitive Hotkeys Custom Combinations Other Features Mouse Wheel Hotkeys Hotkey Tips and Remarks Alt-Tab Hotkeys Named Function Hotkeys 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 Win, which is known as a modifier key:
n::
{ Run "notepad" }
In the above, the braces serve to define a function body for the hotkey. The opening brace may also be specified on the same line as the double-colon to support the OTB (One True Brace) style. 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 braces are implicit:
n::Run "notepad"
When a hotkey is triggered, the name of the hotkey is passed as its first parameter named ThisHotkey (which excludes the trailing colons). For example:
n::MsgBox ThisHotkey ; Reports #n
With few exceptions, this is similar to the built-in variable A_ThisHotkey. The parameter name can be changed by using a named function.
To use more than one modifier with a hotkey, list them consecutively (the order does not matter). The following example uses ^!s to indicate Ctrl+Alt+S:
^!s:: { Send "Sincerely,{enter}John Smith" ; This line sends keystrokes to the active (foremost) window. }
Hotkey Modifier Symbols You can use the following modifier symbols to define hotkeys:
| Symbol | Description |
|---|---|
| # | Win (Windows logo key). Hotkeys that include Win (e.g. #a) will wait for Win to be released before sending any text containing an L keystroke. This prevents usages of Send within such a hotkey from locking the PC. This behavior applies to all sending modes except SendPlay (which doesn't need it), blind mode and text mode. Note: Pressing a hotkey which includes Win may result in extra simulated keystrokes (Ctrl by default). See A_MenuMaskKey. |
| ! | Alt Note: Pressing a hotkey which includes Alt may result in extra simulated keystrokes (Ctrl by default). See A_MenuMaskKey. |
| ^ | Ctrl |
| + | Shift |
| & | An ampersand may be used between any two keys or mouse buttons to combine them into a custom hotkey. See below for details. |
| < | Use the left key of the pair. e.g. <!a is the same as !a except that only the left Alt will trigger it. |
| > | Use the right key of the pair. |
| <^>! | AltGr (alternate graph, or alternate graphic). If your keyboard layout has AltGr instead of a right Alt key, this series of symbols can usually be used to stand for AltGr. For example: <^>!m::MsgBox "You pressed AltGr+m." <^<!m::MsgBox "You pressed LeftControl+LeftAlt+m." Alternatively, to make AltGr itself into a hotkey, use the following hotkey (without any hotkeys like the above present): LControl & RAlt::MsgBox "You pressed AltGr itself." |
| * | Wildcard: Fire the hotkey even if extra modifiers are being held down. This is often used in conjunction with remapping keys or buttons. For example: *#c::Run "calc.exe" ; Win+C, Shift+Win+C, Ctrl+Win+C, etc. will all trigger this hotkey. *ScrollLock::Run "notepad" ; Pressing ScrollLock will trigger this hotkey even when modifier key(s) are down. Wildcard hotkeys always use the keyboard hook, as do any hotkeys eclipsed by a wildcard hotkey. For example, the presence of *a:: would cause ^a:: to always use the hook. |
| ~ | When the hotkey fires, its key's native function will not be blocked (hidden from the system). In both of the below examples, the user's click of the mouse button will be sent to the active window: ~RButton::MsgBox "You clicked the right mouse button." ~RButton & C::MsgBox "You pressed C while holding down the right mouse button." Unlike the other prefix symbols, the tilde prefix is allowed to be present on some of a hotkey's variants but absent on others. However, if a tilde is applied to the prefix key of any custom combination which has not been turned off or suspended, it affects the behavior of that prefix key for all combinations. Special hotkeys that are substitutes for alt-tab always ignore the tilde prefix. If the tilde prefix is applied to a custom modifier key (prefix key) which is also used as its own hotkey, that hotkey will fire when the key is pressed instead of being delayed until the key is released. For example, the ~RButton hotkey above is fired as soon as the button is pressed. If the tilde prefix is applied only to the custom combination and not the non-combination hotkey, the key's native function will still be blocked. For example, in the script below, holding Menu will show the tooltip and will not trigger a context menu: AppsKey::ToolTip "Press < or > to cycle through windows." AppsKey Up::ToolTip ~AppsKey & <::Send "!+{Esc}" ~AppsKey & >::Send "!{Esc}" If at least one variant of a keyboard hotkey has the tilde modifier, that hotkey always uses the keyboard hook. |
| $ | This is usually only necessary if the script uses the Send function to send the keys that comprise the hotkey itself, which might otherwise cause it to trigger itself. The $ prefix forces the keyboard hook to be used to implement this hotkey, which as a side-effect prevents the Send function from triggering it. The $ prefix is equivalent to having specified #UseHook somewhere above the definition of this hotkey. The $ prefix has no effect for mouse hotkeys, since they always use the mouse hook. It also has no effect for hotkeys which already require the keyboard hook, including any keyboard hotkeys with the tilde (~) or wildcard (*) modifiers, key-up hotkeys and custom combinations. To determine whether a particular hotkey uses the keyboard hook, use ListHotkeys. #InputLevel and SendLevel provide additional control over which hotkeys and hotstrings are triggered by the Send function. |
| UP | The word UP may follow the name of a hotkey to cause the hotkey to fire upon release of the key rather than when the key is pressed down. The following example remaps the left Win to become the left Ctrl: *LWin::Send "{LControl down}" *LWin Up::Send "{LControl up}" "Up" can also be used with normal hotkeys as in this example: ^!r Up::MsgBox "You pressed and released Ctrl+Alt+R". It also works with combination hotkeys (e.g. F1 & e Up::) Limitations: 1) "Up" does not work with joystick buttons; and 2) An "Up" hotkey without a normal/down counterpart hotkey will completely take over that key to prevent it from getting stuck down. One way to prevent this is to add a tilde prefix (e.g. ~LControl up::) "Up" hotkeys and their key-down counterparts (if any) always use the keyboard hook. On a related note, a technique similar to the above is to make a hotkey into a prefix key. The advantage is that although the hotkey will fire upon release, it will do so only if you did not press any other key while it was held down. For example: LControl & F1::return ; Make left-control a prefix by using it in front of "&" at least once. LControl::MsgBox "You released LControl without having used it to modify any other key." |
Note: See the Key List for a complete list of keyboard keys and mouse/joystick buttons.
Multiple hotkeys can be stacked vertically to have them perform the same action. For example:
^Numpad0:: ^Numpad1:: { MsgBox "Pressing either Ctrl+Numpad0 or Ctrl+Numpad1 will display this." }
A key or key-combination can be disabled for the entire system by having it do nothing. The following example disables the right-side Win:
RWin::return Context-sensitive Hotkeys The #HotIf directive can be used to make a hotkey perform a different action (or none at all) depending on a specific condition. For example:
HotIf WinActive("ahk_class Notepad")
^a::MsgBox "You pressed Ctrl-A while Notepad is active. Pressing Ctrl-A in any other window will pass the Ctrl-A keystroke to that window."
c::MsgBox "You pressed Win-C while Notepad is active."
HotIf
c::MsgBox "You pressed Win-C while any window except Notepad is active."
HotIf MouseIsOver("ahk_class Shell_TrayWnd") ; For MouseIsOver, see #HotIf example 1.
WheelUp::Send "{Volume_Up}" ; Wheel over taskbar: increase/decrease volume. WheelDown::Send "{Volume_Down}" ;
Custom Combinations Normally shortcut key combinations consist of optional prefix/modifier keys (Ctrl, Alt, Shift and LWin/RWin) and a single suffix key. The standard modifier keys are designed to be used in this manner, so normally have no immediate effect when pressed down.
A custom combination of two keys (including mouse but not joystick buttons) can be defined by using " & " between them. Because they are intended for use with prefix keys that are not normally used as such, custom combinations have the following special behavior:
The prefix key loses its native function, unless it is a standard modifier key or toggleable key such as CapsLock. If the prefix key is also used as a suffix in another hotkey, by default that hotkey is fired upon release, and is not fired at all if it was used to activate a custom combination. If there is both a key-down hotkey and a key-up hotkey, both hotkeys are fired at once. The fire-on-release effect is disabled if the tilde prefix is applied to the prefix key in at least one active custom combination or the suffix hotkey itself. Note: For combinations with standard modifier keys, it is usually better to use the standard syntax. For example, use
