-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathProgram.htm
351 lines (324 loc) · 34.4 KB
/
Program.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
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
<!DOCTYPE HTML>
<html lang="en">
<head>
<title>Using the Program | AutoHotkey v2</title>
<meta name="description" content="Learn details about creating, editing and running a script, the tray icon, the main window, command line usage, portability and installer options." />
<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>Using the Program</h1>
<p>AutoHotkey doesn't do anything on its own; it needs a script to tell it what to do. A script is simply a plain text file with the <code>.ahk</code> filename extension containing instructions for the program, like a configuration file, but much more powerful. A script can do as little as performing a single action and then exiting, but most scripts define a number of <a href="Hotkeys.htm">hotkeys</a>, with each hotkey followed by one or more actions to take when the hotkey is pressed.</p>
<pre>#z::Run "https://www.autohotkey.com" <em>; Win+Z</em>
^!n:: <em>; Ctrl+Alt+N</em>
{
if WinExist("Untitled - Notepad")
WinActivate
else
Run "Notepad"
}</pre>
<p><strong>Tip:</strong> If your browser supports it, you can download any code block (such as the one above) as a script file by clicking the button which appears in the top-right of the code block when you hover your mouse over it.</p>
<h2 id="toc">Table of Contents</h2>
<ul>
<li><a href="#create">Create a Script</a></li>
<li><a href="#edit">Edit a Script</a></li>
<li><a href="#run">Run a Script</a></li>
<li><a href="#tray-icon">Tray Icon</a></li>
<li><a href="#main-window">Main Window</a></li>
<li><a href="#embedded-scripts">Embedded Scripts</a></li>
<li><a href="#cmd">Command Line Usage</a></li>
<li><a href="#portability">Portability of AutoHotkey.exe</a></li>
<li><a href="#launcher">Launcher</a></li>
<li><a href="#dash">Dash</a></li>
<li><a href="#newscript">New Script</a></li>
<li><a href="#install">Installation</a>
<ul>
<li><a href="#Installer_uiAccess">Run with UI Access</a></li>
</ul></li>
</ul>
<h2 id="create">Create a Script</h2>
<p>There are a few common ways to create a script file:</p>
<ul>
<li>In Notepad (or a <a href="misc/Editors.htm">text editor</a> of your choice), save a file with the <code>.ahk</code> filename extension. On some systems you may need to enclose the name in quotes to ensure the editor does not add another extension (such as .txt).
<p class="note">Be sure to save the file as UTF-8 with BOM if it will contain non-ASCII characters. For details, see the <a href="FAQ.htm#nonascii">FAQ</a>.</p></li>
<li>In Explorer, right-click in empty space in the folder where you want to save the script, then select <strong>New</strong> and <strong>AutoHotkey Script</strong>. You can then type a name for the script (taking care not to erase the <code>.ahk</code> extension if it is visible).</li>
<li>In the <a href="#dash">Dash</a>, select <a href="#newscript">New script</a>, type a name for the script (excluding the <code>.ahk</code> extension) and click <em>Create</em> or <em>Edit</em>. The template used to create the script and the location it will be saved can be configured within this window, and set as default if desired.</li>
</ul>
<p class="note">See <a href="Language.htm">Scripting Language</a> for details about how to write a script.</p>
<h2 id="edit">Edit a Script</h2>
<p>To open a script for editing, right-click on the script file and select <strong>Edit Script</strong>. If the script is already running, you can use the <a href="lib/Edit.htm">Edit</a> function or right-click the script's <a href="#tray-icon">tray icon</a> and select <strong>Edit Script</strong>. If you haven't selected a default editor yet, you should be prompted to select one. Otherwise, you can change your default editor via <em>Editor settings</em> in the <a href="#dash">Dash</a>. Of course, you can always open a text editor first and then open the script as you would any other text file.</p>
<p>After editing a script, you must run or <a href="lib/Reload.htm">reload</a> the script for the changes to take effect. A running script can usually be reloaded via its <a href="#tray-icon">tray menu</a>.</p>
<h2 id="run">Run a Script</h2>
<p>With AutoHotkey installed, there are several ways to run a script:</p>
<ul>
<li>Double-click a script file (or shortcut to a script file) in Explorer.</li>
<li>Call AutoHotkey.exe on the command line and pass the script's filename as a <a href="Scripts.htm#cmd">command-line parameter</a>.</li>
<li>After creating <a href="Scripts.htm#defaultfile">the default script</a>, launch AutoHotkey via the shortcut in the Start menu to run it.</li>
<li>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.</li>
</ul>
<p>Most scripts have an effect only while they are running. Use the <a href="#tray-icon">tray menu</a> or the <a href="lib/ExitApp.htm">ExitApp</a> function 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 <a href="Variables.htm#Startup">Startup</a> folder.</p>
<p>Scripts can also be <a href="Scripts.htm#ahk2exe">compiled</a>; that is, combined together with an AutoHotkey binary file to form a self-contained executable (.exe) file.</p>
<h2 id="tray-icon">Tray Icon</h2>
<p>By default, each script adds its own icon to the taskbar notification area (commonly known as the tray).</p>
<p>The tray icon usually looks like this (but the color or letter changes when the script is <a href="lib/Pause.htm">paused</a> or <a href="lib/Suspend.htm">suspended</a>): <img src="static/ahk16.png" alt="H"></p>
<p>Right-click the tray icon to show the tray menu, which has the following options by default:</p>
<ul>
<li>Open - Open the script's <a href="#main-window">main window</a>.</li>
<li>Help - Open the AutoHotkey offline help file.</li>
<li>Window Spy - Displays various information about a window.</li>
<li>Reload Script - See <a href="lib/Reload.htm">Reload</a>.</li>
<li>Edit Script - See <a href="lib/Edit.htm">Edit</a>.</li>
<li>Suspend Hotkeys - <a href="lib/Suspend.htm">Suspend</a> or unsuspend hotkeys.</li>
<li>Pause Script - <a href="lib/Pause.htm">Pause</a> or unpause the script.</li>
<li>Exit - Exit the script.</li>
</ul>
<p>By default, double-clicking the tray icon shows the script's <a href="#main-window">main window</a>.</p>
<p>The behavior and appearance of the tray icon and menu can be customized:</p>
<ul>
<li><a href="Variables.htm#TrayMenu">A_TrayMenu</a> returns a <a href="lib/Menu.htm">Menu object</a> which can be used to customise the tray menu.</li>
<li><a href="Variables.htm#IconHidden">A_IconHidden</a> or the <a href="lib/_NoTrayIcon.htm">#NoTrayIcon</a> directive can be used to hide (or show) the tray icon.</li>
<li><a href="Variables.htm#IconTip">A_IconTip</a> can be assigned new tooltip text for the tray icon.</li>
<li><a href="lib/TraySetIcon.htm">TraySetIcon</a> can be used to change the icon.</li>
</ul>
<h2 id="main-window">Main Window</h2>
<p>The script's main window is usually hidden, but can be shown via the <a href="#tray-icon">tray icon</a> or one of the functions listed below to gain access to information useful for debugging the script. Items under the <strong>View</strong> menu control what the main window displays:</p>
<ul>
<li>Lines most recently executed - See <a href="lib/ListLines.htm">ListLines</a>.</li>
<li>Variables and their contents - See <a href="lib/ListVars.htm">ListVars</a>.</li>
<li>Hotkeys and their methods - See <a href="lib/ListHotkeys.htm">ListHotkeys</a>.</li>
<li>Key history and script info - See <a href="lib/KeyHistory.htm">KeyHistory</a>.</li>
</ul>
<p><strong>Known issue:</strong> Keyboard shortcuts for menu items do not work while the script is displaying a <a href="lib/MsgBox.htm">message box</a> or other dialog.</p>
<p>The built-in variable <a href="Variables.htm#ScriptHwnd">A_ScriptHwnd</a> contains the unique ID (HWND) of the script's main window.</p>
<p>Closing this window with <a href="lib/WinClose.htm">WinClose</a> (even from another script) causes the script to exit, but most other methods just hide the window and leave the script running.</p>
<p>Minimizing the main window causes it to automatically be hidden. This is done to prevent any owned windows (such as GUI windows or certain dialog windows) from automatically being minimized, but also has the effect of hiding the main window's taskbar button. To instead allow the main window to be minimized normally, override the default handling with <a href="lib/OnMessage.htm">OnMessage</a>. For example:</p>
<pre>; This prevents the main window from hiding on minimize:
OnMessage 0x0112, PreventAutoMinimize <em>; WM_SYSCOMMAND = 0x0112</em>
OnMessage 0x0005, PreventAutoMinimize <em>; WM_SIZE = 0x0005
; This prevents owned GUI windows (but not dialogs) from automatically minimizing:</em>
OnMessage 0x0018, PreventAutoMinimize
Persistent
PreventAutoMinimize(wParam, lParam, uMsg, hwnd) {
if (uMsg = 0x0112 && wParam = 0xF020 && hwnd = A_ScriptHwnd) { <em>; SC_MINIMIZE = 0xF020</em>
WinMinimize
return 0 <em>; Prevent main window from hiding.</em>
}
if (uMsg = 0x0005 && wParam = 1 && hwnd = A_ScriptHwnd) <em>; SIZE_MINIMIZED = 1</em>
return 0 <em>; Prevent main window from hiding.</em>
if (uMsg = 0x0018 && lParam = 1) <em>; SW_PARENTCLOSING = 1</em>
return 0 <em>; Prevent owned window from minimizing.</em>
}</pre>
<h3 id="title">Main Window Title</h3>
<p>The title of the script's main window is used by the <a href="lib/_SingleInstance.htm">#SingleInstance</a> and <a href="lib/Reload.htm">Reload</a> mechanisms to identify other instances of the same script. <a href="lib/WinSetTitle.htm">Changing the title</a> prevents the script from being identified as such. The default title depends on how the script was loaded:</p>
<table class="info">
<tr><th>Loaded From</th><th>Title Expression</th><th>Example</th></tr>
<tr><td>.ahk file</td><td><code>A_ScriptFullPath " - AutoHotkey v" A_AhkVersion</code></td><td>E:\My Script.ahk - AutoHotkey v1.1.33.09</td></tr>
<tr><td>Main resource (compiled script)</td><td><code>A_ScriptFullPath</code></td><td>E:\My Script.exe</td></tr>
<tr><td>Any other resource</td><td><code>A_ScriptFullPath " - " A_LineFile</code></td><td>E:\My AutoHotkey.exe - *BUILTIN-TOOL.AHK</td></tr>
</table>
<p>The following code illustrates how the default title could be determined by the script itself (but the actual title can be retrieved with <a href="lib/WinGetTitle.htm">WinGetTitle</a>):</p>
<pre>
title := A_ScriptFullPath
if !A_IsCompiled
title .= " - AutoHotkey v" A_AhkVersion
<em>; For the correct result, this must be evaluated by the resource being executed,
; not an #include (unless the #include was merged into the script by Ahk2Exe):</em>
else if SubStr(A_LineFile, 1, 1) = "*" && A_LineFile != "*#1"
title .= " - " A_LineFile
</pre>
<h2 id="embedded-scripts">Embedded Scripts</h2>
<p>Scripts may be embedded into a standard AutoHotkey .exe file by adding them as Win32 (RCDATA) resources using the <a href="Scripts.htm#ahk2exe">Ahk2Exe compiler</a>. To add additional scripts, see the <a href="misc/Ahk2ExeDirectives.htm#AddResource">AddResource</a> compiler directive.</p>
<p>An embedded script can be specified on the command line or with <a href="lib/_Include.htm">#Include</a> by writing an asterisk (*) followed by the resource name. For an integer ID, the resource name must be a hash sign (#) followed by a decimal number.</p>
<p>The program may automatically load script code from the following resources, if present in the file:</p>
<table class="info">
<tr><th>ID</th><th>Spec</th><th>Usage</th></tr>
<tr>
<td>1</td><td>*#1</td>
<td>This is the means by which a <a href="Scripts.htm#ahk2exe">compiled script</a> is created from an .exe file. This script is executed automatically and most command line switches are passed to the script instead of being interpreted by the program. External scripts and alternative embedded scripts can be executed by using the <a href="Scripts.htm#SlashScript">/script</a> switch.</td>
</tr>
<tr>
<td>2</td><td>*#2</td>
<td>If present, this script is automatically "included" before any script that the program loads, and before any file specified with <a href="Scripts.htm#SlashInclude">/include</a>.</td>
</tr>
</table>
<p>When the source of the main script is an embedded resource, the program acts in "compiled script" mode, with the exception that <a href="Variables.htm#AhkPath">A_AhkPath</a> always contains the path of the current executable file (the same as <a href="Variables.htm#ScriptFullPath">A_ScriptFullPath</a>). For resources other than *#1, the resource specifier is included in <a href="#title">the main window's title</a> to support <a href="lib/_SingleInstance.htm">#SingleInstance</a> and <a href="lib/Reload.htm">Reload</a>.</p>
<p>When referenced from code that came from an embedded resource, <a href="Variables.htm#LineFile">A_LineFile</a> contains an asterisk (*) followed by the resource name.</p>
<h2 id="cmd">Command Line Usage</h2>
<p>See <a href="Scripts.htm#cmd">Passing Command Line Parameters to a Script</a> for command line usage, including a list of command line switches which affect the program's behavior.</p>
<h2 id="portability">Portability of AutoHotkey.exe</h2>
<p>The file AutoHotkey.exe is all that is needed to launch any .ahk script.</p>
<p>Renaming AutoHotkey.exe also changes which script it runs <a href="Scripts.htm#defaultfile">by default</a>, which can be an alternative to compiling a script for use on a computer without AutoHotkey installed. For instance, <i>MyScript</i>.exe automatically runs <i>MyScript</i>.ahk if a filename is not supplied, but is also capable of running other scripts.</p>
<h2 id="launcher">Launcher</h2>
<p>The launcher enables the use of v1 and v2 scripts on one system, with a single filename extension, without necessarily giving preference to one version or requiring different methods of launching scripts. It does this by checking the script for clues about which version it requires, and then locating an appropriate exe to run the script.</p>
<p>If the script contains the <a href="lib/_Requires.htm">#Requires</a> directive, the launcher looks for an exe that satisfies the requirement. Otherwise, the launcher optionally checks syntax. That is, it checks for patterns that are valid only in one of the two major versions. Some of the common patterns it may find include:</p>
<ul>
<li>v1: <code>MsgBox, with comma</code>, <code>MsgBox % "no end percent"</code> and <code>Legacy = assignment</code>.</li>
<li>v1: Multi-line hotkeys without braces or a function definition.</li>
<li>Common directives such as #NoEnv and #If (v1) or <a href="lib/_HotIf.htm">#HotIf</a> (v2).</li>
<li>v2: Unambiguous use of <a href="Scripts.htm#continuation-expr">continuation by enclosure</a> or <a href="Scripts.htm#continuation-line">end-of-line continuation operators</a>.</li>
<li>v2: Unambiguous use of <code>'single quotes'</code> or <a href="Variables.htm#fat-arrow">fat arrow <code>=></code></a> in an expression.</li>
</ul>
<p>Detection is conservative; if a case is ambiguous, it should generally be ignored.</p>
<p>In any case where detection fails, by default a menu is shown for the user to select a version. This default can be changed to instead launch either v1 or v2.</p>
<p><strong>Known limitations:</strong></p>
<ul>
<li>Only the main file is checked.</li>
<li>Since it is legal to include a line like <code>/****/</code> in v1, but <code>*/</code> at line-end only closes comments in v2, the presence of such a line may cause a large portion of the script to be ignored (by both the launcher and the v1 interpreter).</li>
<li>Only syntax is checked, not semantics. For instance, <code>xyz,</code> is invalid in v2, so is assumed to be a valid v1 command. <code>xyz 1</code> could be a function statement in v2, but is assumed to also be a valid v1 command, and is therefore ignored.</li>
<li>Since the patterns being detected are effectively syntax errors in one version, a script with actual syntax errors or incorrectly mixed syntax might be misidentified.</li>
</ul>
<p class="note"><strong>Note:</strong> Declaring the required version with <a href="lib/_Requires.htm">#Requires</a> at the top of the main file eliminates any ambiguity.</p>
<h3 id="launcher-config">Launch Settings</h3>
<p>The launcher can be enabled, disabled or configured via the Launch Settings GUI, which can be accessed via the <a href="#dash">dash</a>.</p>
<p><em>Run all scripts with a specific interpreter</em> disables the launcher and allows the user to select which exe to use to run all scripts, the traditional way. Be aware that selecting a v1 exe will make it difficult to run any of the support scripts, except via the "AutoHotkey" shortcut in the Start menu.</p>
<p><em>Auto-detect version when launching script</em> enables the launcher. Additional settings control how the launcher selects which interpreter to use.</p>
<h3 id="launcher-criteria">Criteria</h3>
<p>When multiple interpreters with the same version number are found, the launcher can rank them according to a predetermined or user-defined set of criteria. The criteria can be expressed as a comma-delimited list of substrings, where each substring may be prefixed with "!" to negate a match. A score is calculated based on which substrings matched, with the left-most substring having highest priority.</p>
<p>Substrings are matched in the file's description, with the exception of "UIA", which matches if the filename contains "_UIA".</p>
<p>For example, <code>_H, 64, !ANSI</code> would prefer AutoHotkey_H if available, 64-bit if compatible with the system, and finally Unicode over ANSI.</p>
<p>Although the Launcher Settings GUI presents drop-down lists with options such as "Unicode 32-bit", a list of substrings can be manually entered.</p>
<p>Additional (higher-priority) criteria can be specified on the command line with the <a href="#SlashRunWith">/RunWith</a> launcher switch.</p>
<p>Criteria can be specified within the script by using the <a href="lib/_Requires.htm">#Requires</a> directive, either as a requirement (if supported by the target AutoHotkey version), or appended to the directive as a comment beginning with "prefer" and ending with a full stop or line ending. For example:</p>
<pre>#Requires AutoHotkey v1.1.35 <em>; prefer 64-bit, Unicode. More comments.</em></pre>
<h3 id="launcher-run">Run *Launch</h3>
<p>The installer registers a hidden shell verb named "launch", which executes the launcher with the <a href="#SlashLaunch">/Launch</a> switch. It can be utilized by following this example:</p>
<pre>pid := RunWait('*Launch "' PathOfScript '"')</pre>
<p>By contrast with the default action for .ahk files:</p>
<ul>
<li>/Launch causes the process ID (PID) of the newly launched script to be returned as the launcher's exit code, whereas it would normally return the launched script's exit code. Run's <em>OutputVarPID</em> parameter returns the PID of the launcher.</li>
<li>/Launch causes the launcher to exit immediately after launching the script. If /Launch is not used, the launcher generally has to assume that its parent process might be doing something like <code>RunWait(PathOfScript)</code>, which wouldn't work as expected if the launcher exited before the launched script.</li>
</ul>
<h3 id="launcher-cmd">Command-line Usage</h3>
<p>The launcher can be explicitly executed at the command line for cases where .ahk files are not set to use the launcher by default, or for finer control over its behaviour. If the launcher is compiled, its usage is essentially the same as AutoHotkey.exe except for the additional launcher switches. Otherwise, the format for command line use is as follows:</p>
<pre>AutoHotkeyUX.exe launcher.ahk [<i>Switches</i>] [<i>Script Filename</i>] [<i>Script Parameters</i>]</pre>
<p>Typically full paths and quote marks would be used for the path to AutoHotkeyUX.exe and launcher.ahk, which can be found in the UX subdirectory of the AutoHotkey installation. An appropriate version of AutoHotkey32.exe or AutoHotkey64.exe can be used instead of AutoHotkeyUX.exe (which is just a copy).</p>
<p><em>Switches</em> can be a mixture of any of the <a href="Scripts.htm#cmd">standard switches</a> and the following launcher-only switches:</p>
<table class="info">
<tr><th>Switch</th><th>Meaning</th></tr>
<tr id="SlashLaunch">
<td>/Launch</td>
<td>Causes the launcher to exit immediately after launching the script, instead of waiting in the background for it to terminate. The launcher's exit code is the process ID (PID) of the new script process.</td>
</tr>
<tr id="SlashRunWith">
<td>/RunWith <em>criteria</em></td>
<td>Specifies additional <a href="#launcher-criteria">criteria</a> for determining which executable to use to launch the script. For example, <code>/RunWith UIA</code>.</td>
</tr>
<tr id="SlashWhich">
<td>/Which</td>
<td>
<p>Causes the launcher to identify which interpreter it would use and return it instead of running the script.</p>
<p>The launcher's exit code is the major version number (1 or 2) if identified by #Requires or syntax (if syntax detection is enabled), otherwise 0.</p>
<p>Stdout receives the following UTF-8 strings, each terminated with <code>`n</code>:</p>
<ul>
<li>The version number. If #Requires was detected, this is whatever number it specified, excluding "v". Otherwise, it is an integer the same as the exit code, unless the version wasn't detected, in which case this is 0 to indicate that the user would have been prompted, or 1 or 2 to indicate the user's preferred version as configured in the Launch Settings.</li>
<li>The path of the interpreter EXE that would be used, if one was found. This is blank if the user would have been prompted or no compatible interpreters were found.</li>
<li>Any additional command-line switches that the launcher would insert, such as <code>/CP65001</code>.</li>
</ul>
<p>Additional lines may be returned in future.</p>
</td>
</tr>
</table>
<h2 id="dash">Dash</h2>
<p>The dash provides access to support scripts and documentation. It can be opened via the "AutoHotkey" shortcut in the Start menu after installation, or by directly running UX\ui-dash.ahk from the installation directory. Currently it is little more than a menu containing the following items, but it might be expanded to provide controls for active scripts, or other convenient functions.</p>
<ul>
<li>New script: Create a new script from a template.</li>
<li>Compile: Opens Ahk2Exe, or offers to automatically download and install it.</li>
<li>Help files (F1): Shows a menu containing help files and online documentation for v1 and v2, and any other CHM files found in the installation directory.</li>
<li>Window spy</li>
<li>Launch settings: Configure the launcher.</li>
<li>Editor settings: Set the default editor for .ahk files.</li>
</ul>
<p>Note that although the Start menu shortcut launches the dash, if it is pinned to the taskbar (or to the Start menu in Windows 7 or 10), the jump list will include any recent scripts launched with the <em>open</em>, <em>runas</em> or <em>UIAccess</em> shell verbs (which are normally accessed via the Explorer context menu or by double-clicking a file). Scripts can be pinned for easy access.</p>
<h2 id="newscript">New Script</h2>
<p>The New Script GUI can be accessed via the dash or by right-clicking within a folder in Explorer and selecting New → AutoHotkey Script. It can be used to create a new script file from a preinstalled or user-defined template, and optionally open it for editing.</p>
<p>Right-clicking on a template in the list gives the following options:</p>
<ul>
<li>Edit template: Open the template in the default editor. If it is a preinstalled template, an editable copy is created instead of opening the original.</li>
<li>Hide template: Adds the template name to a list of templates that will not be shown in the GUI. To unhide a template, delete the corresponding registry value from <code>HKCU\Software\AutoHotkey\New\HideTemplate</code>.</li>
<li>Set as default: Sets the template to be selected by default.</li>
</ul>
<p>By default, the GUI closes after creating a file unless the Ctrl key is held down.</p>
<p>Additional settings can be accessed via the settings button at the bottom-left of the GUI:</p>
<ul>
<li>Default to Create: Pressing Enter will activate the Create button, which creates the script and selects it in Explorer.</li>
<li>Default to Edit: Pressing Enter will activate the Edit button, which creates the script and opens it in the default script editor.</li>
<li>Stay open: If enabled, the window will not close automatically after creating a script.</li>
<li>Set folder as default: Sets the current folder as the default location to save scripts. The default location is used if the New Script window is opened directly or via the Dash; it is not used when New Script is invoked via the Explorer context menu.</li>
<li>Open templates folder: Opens the folder where user-defined <a href="#templates">templates</a> can be stored.</li>
</ul>
<h3 id="templates">Templates</h3>
<p>Template files are drawn from UX\Templates (preinstalled) and <em>%A_MyDocuments%</em>\AutoHotkey\Templates (user), with a user-defined template overriding any preinstalled template which has the same name. If a file exists at <em>%A_WinDir%</em>\ShellNew\Template.ahk, it is shown as "Legacy" and can be overridden by a user-defined template of that name.</p>
<p>Each template may contain an INI section as follows:</p>
<pre>/*
[NewScriptTemplate]
Description = Descriptive text
Execute = true|false|1|0
*/</pre>
<p>If the INI section starts with <code>/*</code> and ends with <code>*/</code> as shown above, it is not included in the created file.</p>
<p><strong>Description</strong> is optional. It is shown in the GUI, in addition to the file's name.</p>
<p><strong>Execute</strong> is optional. If set to true, the template script is executed with <code>A_Args[1]</code> containing the path of the file to be created and <code>A_Args[2]</code> containing either "Create" or "Edit", depending on which button the user clicked. The template script is expected to create the file and open it for editing if applicable. If the template script needs to <code>#include</code> other files, they can be placed in a subdirectory to avoid having them shown in the template list.</p>
<h2 id="install">Installation</h2>
<p>This installer and related scripts are designed to permit multiple versions of AutoHotkey to coexist. The installer provides very few options, as most things can be configured after installation. Only the following choices must be made during installation:</p>
<ul>
<li>Where to install.</li>
<li>Whether to install for all users or the current user.</li>
</ul>
<p>By default the installer will install to "%A_ProgramFiles%\AutoHotkey" for all users. This is recommended, as the UI Access option requires the program to be installed under Program Files. If the installer is not already running as admin, it will attempt to elevate when the Install button is clicked, as indicated by the shield icon on the button.</p>
<p>Current user installation does not require admin rights, as long as the user has write access to the chosen directory. The default directory for a current user installation is "%LocalAppData%\Programs\AutoHotkey".</p>
<h3 id="install_v1">Installing with v1</h3>
<p>There are two methods of installing v1 and v2 together:</p>
<ol>
<li>Install v1 first, and then v2. In that case, the v1 files are left in the root of the installation directory, to avoid breaking any external tools or shortcuts that rely on their current path.</li>
<li>Install v1 as an additional version. Running a v1.1.34.03 or later installer gives this option. Alternatively, use the <code>/install</code> switch described below. Each version installs into its own subdirectory.</li>
</ol>
<p>Running a v1.1.34.02 or older installer (or a custom install with v1.1.34.03 or newer) will overwrite some of the values set in the registry by the v2 installer, such as the version number, uninstaller entry and parts of the file type registration. It will also register the v1 uninstaller, which is not capable of correctly uninstalling both versions. To re-register v2, re-run any v2 installer or run UX\install.ahk using AutoHotkey32.exe or AutoHotkey64.exe.</p>
<h3 id="installdef">Default Version</h3>
<p>Unlike a v1 installation, a default version is not selected during installation. Defaults are instead handled more dynamically by the launcher, and can be configured per-user.</p>
<h3 id="installcmd">Command Line Usage</h3>
<p>To directly install to the <em>DESTINATION</em> directory, use <code>/installto</code> or <code>/to</code> (the two switches are interchangeable) as shown below, from within the source directory. Use either a downloaded setup.exe or files extracted from a downloaded zip or other source.</p>
<pre>AutoHotkey_setup.exe /installto "%DESTINATION%"</pre>
<pre>AutoHotkey32.exe UX\install.ahk /to "%DESTINATION%"</pre>
<p>To install an additional version from <em>SOURCE</em> (which should be a directory containing AutoHotkey*.exe files), execute the following from within the current installation directory (adjusting the path of AutoHotkey32.exe as needed):</p>
<pre>AutoHotkey32.exe UX\install.ahk /install "%SOURCE%"</pre>
<p>The full command string for the above is registered as <em>InstallCommand</em> under <code>HKLM\Software\AutoHotkey</code> or <code>HKCU\Software\AutoHotkey</code>, with <code class="no-highlight">%1</code> as the substitute for the source directory. Using this registry value may be more future-proof.</p>
<p>To re-register the current installation:</p>
<pre>AutoHotkey32.exe UX\install.ahk</pre>
<p>To uninstall:</p>
<pre>AutoHotkey32.exe UX\install.ahk /uninstall</pre>
<p>Alternatively, read the <em>QuietUninstallString</em> value from one of the following registry keys, and execute it:</p>
<pre>HKLM\Microsoft\Windows\CurrentVersion\Uninstall\AutoHotkey
HKCU\Microsoft\Windows\CurrentVersion\Uninstall\AutoHotkey</pre>
<p>Use the <code>/silent</code> switch to suppress warning or confirmation dialogs and prevent the <a href="#dash">Dash</a> from being shown when installation is complete. The following actions may be taken automatically, without warning:</p>
<ul>
<li>Terminate scripts to allow AutoHotkey*.exe to be overwritten.</li>
<li>Overwrite files that were not previously registered by the installer, or that were modified since registration.</li>
</ul>
<h3 id="Installer_IsHostApp">Taskbar Buttons</h3>
<p>The v2 installer does not provide an option to separate taskbar buttons. This was previously achieved by registering each AutoHotkey executable as a <a href="https://learn.microsoft.com/windows/win32/shell/app-registration">host app (IsHostApp)</a>, but this approach has limitations, and becomes less manageable when multiple versions can be installed. Instead, each script should set the <a href="https://learn.microsoft.com/windows/win32/shell/appids">AppUserModelID</a> of its process or windows to control grouping.</p>
<h3 id="Installer_uiAccess">Run with UI Access</h3>
<p>When installing under Program Files, the installer creates an additional set of AutoHotkey exe files that can be used to work around some <a href="FAQ.htm#uac">common UAC-related issues</a>. These files are given the "_UIA.exe" suffix. When one of these UIA.exe files is used by an administrator to run a script, the script is able to interact with windows of programs that run as admin, without the script itself running as admin.</p>
<p>The installer does the following:</p>
<ul>
<li>Copies each AutoHotkey*.exe to AutoHotkey*_UIA.exe.</li>
<li>Sets the <a href="https://learn.microsoft.com/windows/win32/winauto/uiauto-securityoverview">uiAccess attribute</a> in each UIA.exe file's embedded manifest.</li>
<li>Creates a self-signed digital certificate named "AutoHotkey" and signs each UIA.exe file.</li>
<li>Registers the <em>UIAccess</em> shell verb, which appears in Explorer's context menu as "Run with UI access". By default this executes the <a href="#launcher">launcher</a>, which tries to select an appropriate UIA.exe file to run the script.</li>
</ul>
<p>The <a href="#launcher">launcher</a> can also be configured to run v1 scripts, v2 scripts or both with UI Access by default, but this option has no effect if a UIA.exe file does not exist for the selected version and build.</p>
<p>Scripts which need to run other scripts with UI access can simply <a href="lib/Run.htm">Run</a> the appropriate UIA.exe file with the normal <a href="#cmd">command line parameters</a>. Alternatively, if the <em>UIAccess</em> shell verb is registered, it can be used via Run. For example: <code>Run '*UIAccess "Script.ahk"'</code></p>
<p><strong>Known limitations</strong>:</p>
<ul>
<li>UIA is only effective if the file is in a trusted location; i.e. a Program Files sub-directory.</li>
<li>UIA.exe files created on one computer cannot run on other computers without first installing the digital certificate which was used to sign them.</li>
<li>UIA.exe files cannot be started via CreateProcess due to security restrictions. ShellExecute can be used instead. <a href="lib/Run.htm">Run</a> tries both.</li>
<li>UIA.exe files cannot be modified, as it would invalidate the file's digital signature.</li>
<li>Because UIA programs run at a different "integrity level" than other programs, they can only access objects registered by other UIA programs. For example, <code><a href="lib/ComObjActive.htm">ComObjActive</a>("Word.Application")</code> will fail because Word is not marked for UI Access.</li>
<li>The script's own windows can't be automated by non-UIA programs/scripts for security reasons.</li>
<li>Running a non-UIA script which uses a mouse hook (even as simple as <code>InstallMouseHook</code>) may prevent all mouse hotkeys from working when the mouse is pointing at a window owned by a UIA script, even hotkeys implemented by the UIA script itself. A workaround is to ensure UIA scripts are loaded last.</li>
<li>UIA prevents the Gui <a href="lib/Gui.htm#Parent">+Parent</a> option from working on an existing window if the new parent is always-on-top and the child window is not.</li>
</ul>
<p>For more details, see <a href="https://www.autohotkey.com/board/topic/70449-enable-interaction-with-administrative-programs/">Enable interaction with administrative programs</a> on the archive forum.</p>
</body>
</html>