-
Notifications
You must be signed in to change notification settings - Fork 678
/
Hotkeys.htm
309 lines (291 loc) · 29 KB
/
Hotkeys.htm
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
<!DOCTYPE HTML>
<html lang="en">
<head>
<title>Hotkeys - Definition & Usage | AutoHotkey</title>
<meta name="description" content="Learn details about hotkeys in general, modifier symbols, context-sensitive hotkeys, custom combinations, mouse wheel hotkeys, function hotkeys, etc." />
<meta name="keywords" content="hotkey,hotkeys,hot key,hot keys,shortcut,shortcuts,shortcut key,shortcut keys,keyboard shortcut,keyboard shortcuts,button,buttons,click,press">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="static/theme.css" rel="stylesheet" type="text/css" />
<script src="static/content.js" type="text/javascript"></script>
</head>
<body>
<h1>Hotkeys <span class="headnote">(Mouse, Controller and Keyboard Shortcuts)</span></h1>
<h2 id="toc">Table of Contents</h2>
<ul>
<li><a href="#Intro">Introduction and Simple Examples</a></li>
<li><a href="#Symbols">Hotkey Modifier Symbols</a></li>
<li><a href="#Context">Context-sensitive Hotkeys</a></li>
<li><a href="#combo">Custom Combinations</a></li>
<li><a href="#Features">Other Features</a></li>
<li><a href="#Wheel">Mouse Wheel Hotkeys</a></li>
<li><a href="#Remarks">Hotkey Tips and Remarks</a></li>
<li><a href="#alttab">Alt-Tab Hotkeys</a></li>
<li><a href="#Function">Function Hotkeys</a> <span class="ver">[v1.1.20+]</span></li>
</ul>
<h2 id="Intro">Introduction and Simple Examples</h2>
<p>Hotkeys are sometimes referred to as shortcut keys because of their ability to easily trigger an action (such as launching a program or <a href="misc/Macros.htm">keyboard macro</a>). In the following example, the hotkey <kbd>Win</kbd>+<kbd>N</kbd> is configured to launch Notepad. The pound sign [#] stands for <kbd>Win</kbd>, which is known as a <em>modifier key</em>:</p>
<pre>#n::
Run Notepad
return</pre>
<p>In the final line above, <code><a href="lib/Return.htm">return</a></code> 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 <code>return</code> is implicit:</p>
<pre>#n::Run Notepad</pre>
<p>To use more than one modifier with a hotkey, list them consecutively (the order does not matter). The following example uses <code>^!s</code> to indicate <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>S</kbd>:</p>
<pre>^!s::
<a href="lib/Send.htm">Send</a> Sincerely,{enter}John Smith <em>; This line sends keystrokes to the active (foremost) window.</em>
return</pre>
<h2 id="Symbols">Hotkey Modifier Symbols</h2>
<p>You can use the following modifier symbols to define hotkeys:</p>
<table class="info">
<tr>
<th class="center" style="width:30px">Symbol</th>
<th abbr="Descr">Description</th>
</tr>
<tr>
<td class="center bold">#</td>
<td>
<p><kbd>Win</kbd> (Windows logo key).</p>
<p id="win-l"><span class="ver">[v1.0.48.01+]</span>: For Windows Vista and later, hotkeys that include <kbd>Win</kbd> (e.g. #a) will wait for <kbd>Win</kbd> to be released before sending any text containing an <kbd>L</kbd> keystroke. This prevents usages of <a href="lib/Send.htm">Send</a> within such a hotkey from locking the PC. This behavior applies to all sending modes except <a href="lib/Send.htm#SendPlayDetail">SendPlay</a> (which doesn't need it) and <a href="lib/Send.htm#blind">blind mode</a>. <span class="ver">[v1.1.29+]:</span> <a href="lib/Send.htm#SendText">Text mode</a> is also excluded.</p>
<p class="note"><strong>Note:</strong> Pressing a hotkey which includes <kbd>Win</kbd> may result in extra simulated keystrokes (<kbd>Ctrl</kbd> by default). See <a href="lib/_MenuMaskKey.htm">#MenuMaskKey</a>.</p>
</td>
</tr>
<tr>
<td class="center bold">!</td>
<td>
<p><kbd>Alt</kbd></p>
<p class="note"><strong>Note:</strong> Pressing a hotkey which includes <kbd>Alt</kbd> may result in extra simulated keystrokes (<kbd>Ctrl</kbd> by default). See <a href="lib/_MenuMaskKey.htm">#MenuMaskKey</a>.</p>
</td>
</tr>
<tr>
<td class="center bold">^</td>
<td><kbd>Ctrl</kbd></td>
</tr>
<tr>
<td class="center bold">+</td>
<td><kbd>Shift</kbd></td>
</tr>
<tr>
<td class="center bold">&</td>
<td>An ampersand may be used between any two keys or mouse buttons to combine them into a custom hotkey. See <a href="#combo">below</a> for details.</td>
</tr>
<tr id="LeftRight">
<td class="center bold"><</td>
<td>Use the left key of the pair. e.g. <!a is the same as !a except that only the left <kbd>Alt</kbd> will trigger it.</td>
</tr>
<tr>
<td class="center bold">></td>
<td>Use the right key of the pair.</td>
</tr>
<tr id="AltGr">
<td class="center bold"><^>!</td>
<td><p><kbd>AltGr</kbd> (<a href="https://en.wikipedia.org/wiki/AltGr_key">alternate graph, or alternate graphic</a>). If your keyboard layout has <kbd>AltGr</kbd> instead of a right <kbd>Alt</kbd> key, this series of symbols can usually be used to stand for <kbd>AltGr</kbd>. For example:</p>
<pre><^>!m::MsgBox You pressed AltGr+m.
<^<!m::MsgBox You pressed LeftControl+LeftAlt+m.</pre>
<p>Alternatively, to make <kbd>AltGr</kbd> itself into a hotkey, use the following hotkey (without any hotkeys like the above present):</p>
<pre>LControl & RAlt::MsgBox You pressed AltGr itself.</pre></td>
</tr>
<tr id="wildcard">
<td class="center bold">*</td>
<td><p>Wildcard: Fire the hotkey even if extra modifiers are being held down. This is often used in conjunction with <a href="misc/Remap.htm">remapping</a> keys or buttons. For example:</p>
<pre>*#c::Run Calc.exe <em>; Win+C, Shift+Win+C, Ctrl+Win+C, etc. will all trigger this hotkey.</em>
*ScrollLock::Run Notepad <em>; Pressing ScrollLock will trigger this hotkey even when modifier key(s) are down.</em></pre>
<p>Wildcard hotkeys always use the keyboard hook, as do any hotkeys eclipsed by a wildcard hotkey. For example, the presence of <code>*a::</code> would cause <code>^a::</code> to always use the hook.</p></td>
</tr>
<tr id="Tilde">
<td class="center bold">~</td>
<td><p>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:</p>
<pre>~RButton::MsgBox You clicked the right mouse button.
~RButton & C::MsgBox You pressed C while holding down the right mouse button.</pre>
<p>Unlike the other prefix symbols, the tilde prefix is allowed to be present on some of a hotkey's <a href="lib/_IfWinActive.htm#variant">variants</a> but absent on others. However, if a tilde is applied to the <a href="#prefix">prefix key</a> of any custom combination which has not been turned off or suspended, it affects the behavior of that prefix key for <em>all</em> combinations.</p>
<p>Special hotkeys that are substitutes for <a href="#alttab">alt-tab</a> always ignore the tilde prefix.</p>
<p><span class="ver">[v1.1.14+]:</span> If the tilde prefix is applied to a custom modifier key (<a href="#prefix">prefix key</a>) 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 <em>~RButton</em> hotkey above is fired as soon as the button is pressed. Prior to <span class="ver">[v1.1.14]</span> (or without the tilde prefix), it was fired when the button was released, but only if the <em>RButton & C</em> combination was not activated.</p>
<p>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 <kbd>Menu</kbd> will show the tooltip and will not trigger a context menu:</p>
<pre>AppsKey::ToolTip Press < or > to cycle through windows.
AppsKey Up::ToolTip
~AppsKey & <::Send !+{Esc}
~AppsKey & >::Send !{Esc}</pre>
<p>If at least one variant of a keyboard hotkey has the tilde modifier, that hotkey always uses the keyboard hook.</p>
</td>
</tr>
<tr id="prefixdollar">
<td class="center bold">$</td>
<td>
<p>This is usually only necessary if the script uses the <a href="lib/Send.htm">Send</a> command to send the keys that comprise the hotkey itself, which might otherwise cause it to trigger itself. The $ prefix forces the <a href="lib/_InstallKeybdHook.htm">keyboard hook</a> to be used to implement this hotkey, which as a side-effect prevents the <a href="lib/Send.htm">Send</a> command from triggering it. The $ prefix is equivalent to having specified <code><a href="lib/_UseHook.htm">#UseHook</a></code> somewhere above the definition of this hotkey.</p>
<p>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 <a href="#Tilde">tilde (~)</a> or <a href="#wildcard">wildcard (*)</a> modifiers, key-up hotkeys and custom combinations. To determine whether a particular hotkey uses the keyboard hook, use <a href="lib/ListHotkeys.htm">ListHotkeys</a>.</p>
<p><span class="ver">[v1.1.06+]:</span> <a href="lib/_InputLevel.htm">#InputLevel</a> and <a href="lib/SendLevel.htm">SendLevel</a> provide additional control over which hotkeys and hotstrings are triggered by the Send command.</p>
</td>
</tr>
<tr id="keyup">
<td class="center">UP</td>
<td><p>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 <a href="misc/Remap.htm">remaps</a> the left <kbd>Win</kbd> to become the left <kbd>Ctrl</kbd>:</p>
<pre>*LWin::Send {LControl down}
*LWin Up::Send {LControl up}
</pre>
<p>"Up" can also be used with normal hotkeys as in this example: <code>^!r Up::MsgBox You pressed and released Ctrl+Alt+R</code>. It also works with <a href="#combo">combination hotkeys</a> (e.g. <code>F1 & e Up::</code>)</p>
<p>Limitations: 1) "Up" does not work with <a href="KeyList.htm#Controller">controller buttons</a>; 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 <a href="#Tilde">tilde prefix</a> (e.g. <code>~LControl up::</code>)</p>
<p>"Up" hotkeys and their key-down counterparts (if any) always use the keyboard hook.</p>
<p>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:</p>
<pre>LControl & F1::return <em>; Make left-control a prefix by using it in front of "&" at least once.</em>
LControl::MsgBox You released LControl without having used it to modify any other key.</pre></td>
</tr>
</table>
<p class="note"><strong>Note</strong>: See the <a href="KeyList.htm">Key List</a> for a complete list of keyboard keys and mouse/controller buttons.</p>
<p>Multiple hotkeys can be stacked vertically to have them perform the same action. For example:</p>
<pre>^Numpad0::
^Numpad1::
MsgBox Pressing either Control+Numpad0 or Control+Numpad1 will display this message.
return</pre>
<p>A key or key-combination can be disabled for the entire system by having it do nothing. The following example disables the right-side <kbd>Win</kbd>:</p>
<pre>RWin::return</pre>
<h2 id="Context">Context-sensitive Hotkeys</h2>
<p>The directives <a href="lib/_IfWinActive.htm">#IfWinActive/Exist</a> and <a href="lib/_If.htm">#If</a> can be used to make a hotkey perform a different action (or none at all) depending on a specific condition. For example:</p>
<pre>#IfWinActive 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.
#IfWinActive
#c::MsgBox You pressed Win-C while any window except Notepad is active.
#If MouseIsOver("ahk_class Shell_TrayWnd") <em>; For MouseIsOver, see <a href="lib/_If.htm#ExVolume">#If example 1</a>.</em>
WheelUp::Send {Volume_Up} <em>; Wheel over taskbar: increase/decrease volume.</em>
WheelDown::Send {Volume_Down} <em>;</em>
</pre>
<h2 id="combo">Custom Combinations</h2>
<p>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.</p>
<p>A custom combination of two keys (including mouse but not controller 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:</p>
<ul>
<li>The prefix key loses its native function, unless it is a standard modifier key or toggleable key such as <kbd>CapsLock</kbd>.</li>
<li>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. <span class="ver">[v1.1.14+]:</span> If there is both a key-down hotkey and a <a href="#keyup">key-up</a> hotkey, both hotkeys are fired at once. The fire-on-release effect is disabled if the <a href="#Tilde">tilde prefix</a> is applied to the prefix key in at least one active custom combination or the suffix hotkey itself.</li>
</ul>
<p class="note"><strong>Note:</strong> For combinations with standard modifier keys, it is usually better to use the standard syntax. For example, use <code><+s::</code> rather than <code>LShift & s::</code>.</p>
<p>In the below example, you would hold down Numpad0 then press the second key to trigger the hotkey:</p>
<pre id="prefix">Numpad0 & Numpad1::MsgBox You pressed Numpad1 while holding down Numpad0.
Numpad0 & Numpad2::Run Notepad</pre>
<p><strong>The prefix key loses its native function:</strong> In the above example, Numpad0 becomes a <em>prefix key</em>; 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:</p>
<pre>Numpad0::WinMaximize A <em>; Maximize the active/foreground window.</em>
Numpad0::Send {Numpad0} <em>; Make the <i>release</i> of Numpad0 produce a Numpad0 keystroke. See comment below.</em></pre>
<p><strong>Fire on release:</strong> The presence of one of the above custom combination hotkeys causes the <em>release</em> of Numpad0 to perform the indicated action, but only if you did not press any other keys while Numpad0 was being held down. <span class="ver">[v1.1.14+]</span>: This behaviour can be avoided by applying the <a href="#Tilde">tilde prefix</a> to either hotkey.</p>
<p id="combo_mods"><strong>Modifiers:</strong> Unlike a normal hotkey, custom combinations act as though they have the <a href="#wildcard">wildcard (*)</a> modifier by default. For example, <code>1 & 2::</code> will activate even if <kbd>Ctrl</kbd> or <kbd>Alt</kbd> is held down when <kbd>1</kbd> and <kbd>2</kbd> are pressed, whereas <code>^1::</code> would be activated only by <kbd>Ctrl</kbd>+<kbd>1</kbd> and not <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>1</kbd>.</p>
<p>Combinations of three or more keys are not supported. Combinations which your keyboard hardware supports can usually be detected by using <a href="lib/_If.htm">#If</a> and <a href="lib/GetKeyState.htm#function">GetKeyState()</a>, but the results may be inconsistent. For example:</p>
<pre><em>; Press AppsKey and Alt in any order, then slash (/).</em>
#if GetKeyState("AppsKey", "P")
Alt & /::MsgBox Hotkey activated.
<em>; If the keys are swapped, Alt must be pressed first (use one at a time):</em>
#if GetKeyState("Alt", "P")
AppsKey & /::MsgBox Hotkey activated.
<em>; [ & ] & \::</em>
#if GetKeyState("[") && GetKeyState("]")
\::MsgBox</pre>
<p><strong>Keyboard hook:</strong> Custom combinations involving keyboard keys always use the keyboard hook, as do any hotkeys which use the prefix key as a suffix. For example, <code>a & b::</code> causes <code>^a::</code> to always use the hook.</p>
<h2 id="Features">Other Features</h2>
<p><strong>NumLock, CapsLock, and ScrollLock:</strong> These keys may be forced to be "AlwaysOn" or "AlwaysOff". For example: <code><a href="lib/SetNumScrollCapsLockState.htm">SetNumLockState</a> AlwaysOn</code>.</p>
<p><strong>Overriding Explorer's hotkeys:</strong> Windows' built-in hotkeys such as <kbd>Win</kbd>+<kbd>E</kbd> (#e) and <kbd>Win</kbd>+<kbd>R</kbd> (#r) can be individually overridden simply by assigning them to an action in the script. See the <a href="misc/Override.htm">override page</a> for details.</p>
<p><strong>Substitutes for Alt-Tab:</strong> Hotkeys can provide an alternate means of alt-tabbing. For example, the following two hotkeys allow you to alt-tab with your right hand:</p>
<pre>RControl & RShift::AltTab <em>; Hold down right-control then press right-shift repeatedly to move forward.</em>
RControl & Enter::ShiftAltTab <em>; Without even having to release right-control, press Enter to reverse direction.</em></pre>
<p>For more details, see <a href="#alttab">Alt-Tab</a>.</p>
<h2 id="Wheel">Mouse Wheel Hotkeys</h2>
<p>Hotkeys that fire upon turning the mouse wheel are supported via the key names WheelDown and WheelUp. Here are some examples of mouse wheel hotkeys:</p>
<pre>MButton & WheelDown::MsgBox You turned the mouse wheel down while holding down the middle button.
^!WheelUp::MsgBox You rotated the wheel up while holding down Control+Alt.</pre>
<p id="HWheel"><span class="ver">[v1.0.48+]</span>: WheelLeft and WheelRight are also supported, but have no effect on operating systems older than Windows Vista. Some mice have a single wheel which can be scrolled up and down or tilted left and right. Generally in those cases, WheelLeft or WheelRight signals are sent repeatedly while the wheel is held to one side, to simulate continuous scrolling. This typically causes the hotkeys to execute repeatedly.</p>
<p><span class="ver">[v1.0.43.03+]</span>: The built-in variable <strong>A_EventInfo</strong> contains the amount by which the wheel was turned, which is typically 1. However, A_EventInfo can be greater or less than 1 under the following circumstances:</p>
<ul>
<li>If the mouse hardware reports distances of less than one notch, A_EventInfo may contain 0;</li>
<li>If the wheel is being turned quickly (depending on type of mouse), A_EventInfo may be greater than 1. A hotkey like the following can help analyze your mouse: <code>~WheelDown::ToolTip %A_EventInfo%</code>.</li>
</ul>
<p>Some of the most useful hotkeys for the mouse wheel involve alternate modes of scrolling a window's text. For example, the following pair of hotkeys scrolls horizontally instead of vertically when you turn the wheel while holding down the left <kbd>Ctrl</kbd>:</p>
<pre>~LControl & WheelUp:: <em>; Scroll left.</em>
ControlGetFocus, fcontrol, A
Loop 2 <em>; <-- Increase this value to scroll faster.</em>
SendMessage, 0x0114, 0, 0, %fcontrol%, A <em>; 0x0114 is WM_HSCROLL and the 0 after it is SB_LINELEFT.</em>
return
~LControl & WheelDown:: <em>; Scroll right.</em>
ControlGetFocus, fcontrol, A
Loop 2 <em>; <-- Increase this value to scroll faster.</em>
SendMessage, 0x0114, 1, 0, %fcontrol%, A <em>; 0x0114 is WM_HSCROLL and the 1 after it is SB_LINERIGHT.</em>
return</pre>
<p>Finally, since mouse wheel hotkeys generate only down-events (never up-events), they cannot be used as <a href="#keyup">key-up hotkeys</a>.</p>
<h2 id="Remarks">Hotkey Tips and Remarks</h2>
<p>Each numpad key can be made to launch two different hotkey subroutines depending on the state of <kbd>NumLock</kbd>. Alternatively, a numpad key can be made to launch the same subroutine regardless of the state. For example:</p>
<pre>NumpadEnd::
Numpad1::
MsgBox, This hotkey is launched regardless of whether NumLock is on.
return</pre>
<p>If the <a href="#Tilde">tilde (~) symbol</a> is used with a <a href="#prefix">prefix key</a> even once, it changes the behavior of that prefix key for all combinations. For example, in both of the below hotkeys, the active window will receive all right-clicks even though only one of the definitions contains a tilde:</p>
<pre>~RButton & LButton::MsgBox You pressed the left mouse button while holding down the right.
RButton & WheelUp::MsgBox You turned the mouse wheel up while holding down the right button.</pre>
<p>The <a href="lib/Suspend.htm">Suspend</a> command can temporarily disable all hotkeys except for ones you make exempt. For greater selectivity, use <a href="lib/_IfWinActive.htm">#IfWinActive/Exist</a>.</p>
<p>By means of the <a href="lib/Hotkey.htm">Hotkey</a> command, hotkeys can be created dynamically while the script is running. The Hotkey command can also modify, disable, or enable the script's existing hotkeys individually.</p>
<p>Controller hotkeys do not currently support modifier prefixes such as ^ (Ctrl) and # (Win). However, you can use <a href="lib/GetKeyState.htm#function">GetKeyState</a> to mimic this effect as shown in the following example:</p>
<pre>Joy2::
if not GetKeyState("Control") <em>; Neither the left nor right Control key is down.</em>
return <em>; i.e. Do nothing.</em>
MsgBox You pressed the first controller's second button while holding down the Control key.
return</pre>
<p>There may be times when a hotkey should wait for its own modifier keys to be released before continuing. Consider the following example:</p>
<pre>^!s::Send {Delete}</pre>
<p>Pressing <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>S</kbd> would cause the system to behave as though you pressed <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Del</kbd> (due to the system's aggressive detection of this hotkey). To work around this, use <a href="lib/KeyWait.htm">KeyWait</a> to wait for the keys to be released; for example:</p>
<pre>^!s::
KeyWait Control
KeyWait Alt
Send {Delete}
return</pre>
<p>If a hotkey label like <code>#z::</code> produces an error like "Invalid Hotkey", your system's keyboard layout/language might not have the specified character ("Z" in this case). Try using a different character that you know exists in your keyboard layout.</p>
<p>A hotkey label can be used as the target of a <a href="lib/Gosub.htm">Gosub</a> or <a href="lib/Goto.htm">Goto</a>. For example: <code>Gosub ^!s</code>. See <a href="misc/Labels.htm#hotkeys-and-hotstrings">Labels</a> for related details.</p>
<p>One common use for hotkeys is to start and stop a repeating action, such as a series of keystrokes or mouse clicks. For an example of this, see <a href="FAQ.htm#repeat">this FAQ topic</a>.</p>
<p>Finally, each script is <a href="misc/Threads.htm">quasi multi-threaded</a>, which allows a new hotkey to be launched even when a previous hotkey subroutine is still running. For example, new hotkeys can be launched even while a <a href="lib/MsgBox.htm">message box</a> is being displayed by the current hotkey.</p>
<h2 id="alttab"><span id="AltTabDetail"></span>Alt-Tab Hotkeys</h2>
<p>Alt-Tab hotkeys simplify the mapping of new key combinations to the system's Alt-Tab hotkeys, which are used to invoke a menu for switching tasks (activating windows).</p>
<p>Each Alt-Tab hotkey must be either a single key or a combination of two keys, which is typically achieved via the ampersand symbol (&). In the following example, you would hold down the right <kbd>Alt</kbd> and press <kbd>J</kbd> or <kbd>K</kbd> to navigate the alt-tab menu:</p>
<pre>RAlt & j::AltTab
RAlt & k::ShiftAltTab</pre>
<p><em>AltTab</em> and <em>ShiftAltTab</em> are two of the special commands that are only recognized when used on the same line as a hotkey. Here is the complete list:</p>
<p><strong>AltTab</strong>: If the alt-tab menu is visible, move forward in it. Otherwise, display the menu (only if the hotkey is a combination of two keys; otherwise, it does nothing).</p>
<p><strong>ShiftAltTab</strong>: Same as above except move backward in the menu.</p>
<p><strong>AltTabMenu</strong>: Show or hide the alt-tab menu.</p>
<p><strong>AltTabAndMenu</strong>: If the alt-tab menu is visible, move forward in it. Otherwise, display the menu.</p>
<p><strong>AltTabMenuDismiss</strong>: Close the Alt-tab menu.</p>
<p>To illustrate the above, the mouse wheel can be made into an entire substitute for Alt-tab. With the following hotkeys in effect, clicking the middle button displays the menu and turning the wheel navigates through it:</p>
<pre>MButton::AltTabMenu
WheelDown::AltTab
WheelUp::ShiftAltTab</pre>
<p>To cancel the Alt-Tab menu without activating the selected window, press or send <kbd>Esc</kbd>. In the following example, you would hold the left <kbd>Ctrl</kbd> and press <kbd>CapsLock</kbd> to display the menu and advance forward in it. Then you would release the left <kbd>Ctrl</kbd> to activate the selected window, or press the mouse wheel to cancel. Define the <a href="#AltTabWindow">AltTabWindow</a> window group as shown below before running this example.</p>
<pre>LCtrl & CapsLock::AltTab
#IfWinExist ahk_group AltTabWindow <em>; Indicates that the alt-tab menu is present on the screen.</em>
*MButton::Send {Blind}{Escape} <em>; The * prefix allows it to fire whether or not Alt is held down.</em>
#If</pre>
<p>If the script sent <code>{Alt Down}</code> (such as to invoke the Alt-Tab menu), it might also be necessary to send <code>{Alt Up}</code> as shown in the example further below.</p>
<h3 id="AltTabRemarks">General Remarks</h3>
<p>Currently, all special Alt-tab actions must be assigned directly to a hotkey as in the examples above (i.e. they cannot be used as though they were commands). They are <span class="red">not affected by <a href="lib/_IfWinActive.htm">#IfWin</a> or <a href="lib/_If.htm">#If</a></span>.</p>
<p>An alt-tab action may take effect on key-down and/or key-up regardless of whether the <code>up</code> keyword is used, and cannot be combined with another action on the same key. For example, using both <code>F1::AltTabMenu</code> and <code>F1 up::OtherAction()</code> is unsupported.</p>
<p id="AltTabWindow">Custom alt-tab actions can also be created via hotkeys. As the identity of the alt-tab menu differs between OS versions, it may be helpful to use a window group as shown below. For the examples above and below which use <code>ahk_group AltTabWindow</code>, this window group is expected to be defined in the <a href="Scripts.htm#auto">auto-execute section</a>. Alternatively, <code>ahk_group AltTabWindow</code> can be replaced with the appropriate <code>ahk_class</code> for your system.</p>
<pre>GroupAdd AltTabWindow, ahk_class MultitaskingViewFrame <em>; Windows 10</em>
GroupAdd AltTabWindow, ahk_class TaskSwitcherWnd <em>; Windows Vista, 7, 8.1</em>
GroupAdd AltTabWindow, ahk_class #32771 <em>; Older, or with classic alt-tab enabled</em></pre>
<p>In the following example, you would press <kbd>F1</kbd> to display the menu and advance forward in it. Then you would press <kbd>F2</kbd> to activate the selected window, or press <kbd>Esc</kbd> to cancel:</p>
<pre>*F1::Send {Alt down}{tab} <em>; Asterisk is required in this case.</em>
!F2::Send {Alt up} <em>; Release the Alt key, which activates the selected window.</em>
#IfWinExist ahk_group AltTabWindow
~*Esc::Send {Alt up} <em>; When the menu is cancelled, release the Alt key automatically.
;*Esc::Send {Esc}{Alt up} ; Without tilde (~), Escape would need to be sent.</em>
#If</pre>
<h2 id="Function">Function Hotkeys <span class="ver">[v1.1.20+]</span></h2>
<p>One or more hotkeys can be assigned a <a href="Functions.htm">function</a> by simply defining it immediately after the hotkey label as in this example:</p>
<pre><em>; Ctrl+Shift+O to open containing folder in Explorer.
; Ctrl+Shift+E to open folder with current file selected.
; Supports SciTE and Notepad++.</em>
^+o::
^+e::
editor_open_folder() {
WinGetTitle, path, A
if RegExMatch(path, "\*?\K(.*)\\[^\\]+(?= [-*] )", path)
if (FileExist(path) && A_ThisHotkey = "^+e")
Run explorer.exe /select`,"%path%"
else
Run explorer.exe "%path1%"
}</pre>
<p id="function-details"><span class="ver">[v1.1.28+]:</span> Hotstrings can also be defined this way. Multiple hotkeys or hotstrings can be stacked together to call the same function.</p>
<p>There must only be whitespace, comments or directives between the hotkey/hotstring labels or label and the function. Hotkey/hotstring labels defined this way are not visible to <a href="lib/IsLabel.htm">IsLabel()</a>, <a href="lib/Gosub.htm">Gosub</a> or other commands; however, the <a href="Scripts.htm#auto">auto-execute section</a> ends at the first hotkey/hotstring even if it is assigned a function.</p>
<p>The main benefit of using a function is that local variables can be used, which avoids conflicts when two or more hotkeys use the same variable names for different purposes. It also encourages self-documenting hotkeys, like in the code above where the function name describes the hotkey.</p>
<p>The <a href="lib/Hotkey.htm">Hotkey</a> command can also be used to assign a function or function object to a hotkey.</p>
</body>
</html>