AutoHotKey Documentation

Version 1.0.45.01
www.autohotkey.com
2003-2006 Chris Mallett, portions AutoIt Team


iii
Table Of Contents
Version 1.0.45.01.......................................1
Introduction...............................................1
More about Hotkeys.................................................... 1
Other Features........................................................... 1
Acknowledgements..................................................... 2
Tutorial and Overview................................3
Tutorial Contents........................................................ 3
Creating a script......................................................... 3
Launching a program or document ............................... 3
Sending keystrokes and mouse clicks............................ 4
Activating and manipulating windows............................ 5
Getting input from the user with MsgBox, InputBox, etc. . 5
Using variables and the clipboard ................................. 6
Repeating a series of actions over and over ................... 7
Manipulating files and folders....................................... 8
Overview of other features .......................................... 9
Frequently Asked Questions (FAQ) ..........11
Language Syntax.......................................................11
Common Tasks .........................................................12
Hotkeys, Hotstrings, and Remapping ...........................15
Hotkeys (Mouse, Joystick and Keyboard
Shortcuts)................................................17
Table of Contents ......................................................17
Introduction and Simple Examples...............................17
Context-sensitive Hotkeys [v1.0.41+]..........................19
Custom Combinations and Other Features [Windows
NT/2000/XP or later] .................................................19
Mouse Wheel Hotkeys [Windows NT/2000/XP or later] ...20
Hotkey Tips and Remarks ...........................................20
Alt-Tab Hotkeys ........................................................21
Hotstrings and Auto-replace ....................23
Introduction and Simple Examples...............................23
Ending Characters .....................................................23
Options ....................................................................23
Long Replacements....................................................25
Context-sensitive Hotstrings .......................................25
AutoCorrect ..............................................................25
Remarks...................................................................26
Hotstring Helper ........................................................27
Remapping Keys and Buttons...................29
Introduction..............................................................29
Remapping the Keyboard and Mouse [v1.0.40+] ...........29
Remarks...................................................................30
Moving the Mouse Cursor via the Keyboard...................32
Remapping via the Registry's "Scancode Map" ..............32
Remapping Method for Windows 95/98/Me ...................33
Related Topics...........................................................33
List of Keys, Mouse Buttons, and Joystick
Controls ...................................................35
Mouse (mouse hotkeys require Windows NT/2000/XP or
later) ....................................................................... 35
Keyboard ................................................................. 35
Joystick.................................................................... 37
Hand-held Remote Controls........................................ 37
Special Keys ............................................................. 37
Scripts......................................................39
Table of Contents ...................................................... 39
Introduction ............................................................. 39
The Top of the Script (the Auto-execute Section) .......... 39
Escape Sequences..................................................... 40
Comments in Scripts ................................................. 40
Splitting a Long Line into a Series of Shorter Ones ........ 40
Convert a Script to an EXE (ahk2exe) .......................... 43
Passing Command Line Parameters to a Script.............. 44
Debugging a Script.................................................... 45
Portability of AutoHotkey.exe...................................... 45
Installer Options ....................................................... 45
Script Showcase........................................................ 45
Variables and Expressions........................47
Table of Contents ...................................................... 47
Introduction to Variables............................................ 47
Expressions .............................................................. 48
Operators in Expressions............................................ 50
Expression Operators (in descending precedence order)50
Built-in Variables....................................................... 52
Table of Contents ................................................... 52
Special Characters.................................................. 52
Script Properties .................................................... 53
Date and Time ....................................................... 53
Script Settings ....................................................... 54
User Idle Time ....................................................... 55
GUI Windows and Menu Bars ................................... 55
Hotkeys, Hotstrings, and Custom Menu Items............ 56
Operating System and User Info .............................. 57
Misc...................................................................... 58
Loop..................................................................... 59
Environment Variables vs. "Normal" Variables............... 59
Variable Capacity and Memory.................................... 60
Functions .................................................61
Table of Contents ...................................................... 61
Introduction and Simple Example................................ 61
Parameters............................................................... 61
Optional Parameters [v1.0.35+] ................................. 62
Local Variables and Global Variables ............................ 62
Using #Include to Share Functions Among Multiple Scripts64
Short-circuit Boolean Evaluation.................................. 64
Using Subroutines Within a Function............................ 64
Printed Documentation
iv
Return, Exit, and General Remarks ..............................65
Style and Naming Conventions....................................65
Built-in Functions ......................................................66
Frequently-used Functions.......................................66
Miscellaneous Functions ..........................................67
General Math .........................................................67
Trigonometry.........................................................68
Other Functions......................................................68
Notes for AutoIt v2 Users.........................69
Benefits....................................................................69
Running AutoIt v2 (.aut) Scripts..................................69
Converting Scripts from .aut to .ahk ............................69
Enhanced Syntax.......................................................70
Other differences between AutoIt v2 and AutoHotkey ....71
New Language and Command Style.............................72
Enhanced Commands.................................................73
New Commands and Features .....................................74
Command List ..........................................77
AutoHotkey Script Showcase....................87
Changes & New Features .........................91
1.0.45.01 - November 7, 2006....................................91
1.0.45 - November 4, 2006 ........................................91
1.0.44.14 - October 2, 2006 .......................................91
1.0.44.13 - September 20, 2006 .................................92
1.0.44.12 - September 13, 2006 .................................92
1.0.44.11 - September 9, 2006...................................92
1.0.44.10 - August 27, 2006.......................................92
1.0.44.09 - August 9, 2006 ........................................92
1.0.44.08 - July 25, 2006...........................................93
1.0.44.07 - June 17, 2006..........................................93
1.0.44.06 - June 8, 2006............................................93
1.0.44.05 - June 7, 2006............................................93
1.0.44.04 - May 31, 2006...........................................93
1.0.44.03 - May 29, 2006...........................................93
1.0.44.02 - May 20, 2006...........................................94
1.0.44.01 - May 15, 2006...........................................94
1.0.44 - May 14, 2006 ...............................................94
1.0.43.11 - May 1, 2006 ............................................94
1.0.43.10 - April 28, 2006..........................................94
1.0.43.09 - April 25, 2006..........................................95
1.0.43.08 - April 17, 2006..........................................95
1.0.43.07 - April 12, 2006..........................................95
1.0.43.06 - April 9, 2006............................................95
1.0.43.05 - April 7, 2006............................................96
1.0.43.04 - April 4, 2006............................................96
1.0.43.03 - April 3, 2006............................................96
1.0.43.02 - March 30, 2006........................................96
1.0.43.01 - March 29, 2006........................................96
1.0.43 - March 25, 2006 ............................................96
1.0.42.07 - March 9, 2006..........................................97
1.0.42.06 - March 7, 2006..........................................97
1.0.42.05 - March 6, 2006..........................................97
1.0.42.04 - March 6, 2006..........................................97
1.0.42.03 - February 20, 2006.................................... 97
1.0.42.02 - February 17, 2006.................................... 98
1.0.42.01 - February 15, 2006.................................... 98
1.0.42 - February 10, 2006 ........................................ 98
1.0.41.02 - February 1, 2006 ..................................... 99
1.0.41.01 - January 31, 2006 ..................................... 99
1.0.41 - January 19, 2006.......................................... 99
1.0.40.12 - January 11, 2006 ..................................... 99
1.0.40.11 - December 12, 2005.................................. 99
1.0.40.10 - December 1, 2005.................................... 99
1.0.40.09 - November 21, 2005.................................. 99
1.0.40.08 - November 16, 2005.................................. 99
1.0.40.07 - November 16, 2005.................................. 99
1.0.40.06 - November 10, 2005.................................. 99
1.0.40.05 - November 4, 2005.................................. 100
1.0.40.04 - November 2, 2005.................................. 100
1.0.40.03 - October 26, 2005 ................................... 100
1.0.40.02 - October 24, 2005 ................................... 100
1.0.40.01 - October 21, 2005 ................................... 100
1.0.40 - October 11, 2005........................................ 100
1.0.39 - October 3, 2005 ......................................... 101
1.0.38.06 - September 27, 2005............................... 101
1.0.38.05 - September 23, 2005............................... 101
1.0.38.04 - September 21, 2005............................... 101
1.0.38.03 - September 12, 2005............................... 101
1.0.38.02 - September 8, 2005................................. 102
1.0.38.01 - September 5, 2005................................. 102
1.0.38 - September 3, 2005 ..................................... 102
Environment Management .....................103
ClipWait ................................................................. 103
EnvGet [v1.0.43.08+] ............................................. 104
EnvSet................................................................... 104
EnvUpdate ............................................................. 105
File, Directory, and Disk Management ....107
Drive ..................................................................... 107
DriveGet ................................................................ 108
DriveSpaceFree....................................................... 110
FileAppend ............................................................. 111
FileCopy................................................................. 113
FileCopyDir............................................................. 114
FileCreateDir .......................................................... 115
FileCreateShortcut................................................... 116
FileDelete............................................................... 117
FileGetAttrib ........................................................... 118
FileGetShortcut ....................................................... 119
FileGetSize ............................................................. 120
FileGetTime ............................................................ 121
FileGetVersion ........................................................ 121
FileInstall ............................................................... 122
FileMove ................................................................ 123
FileMoveDir ............................................................ 125
FileReadLine ........................................................... 126
FileRead................................................................. 127
FileRecycle ............................................................. 128
Table Of Contents
v
FileRecycleEmpty..................................................... 128
FileRemoveDir......................................................... 129
FileSelectFile........................................................... 129
FileSelectFolder ....................................................... 133
FileSetAttrib............................................................ 134
FileSetTime............................................................. 136
IfExist / IfNotExist ................................................... 137
IniDelete ................................................................ 138
IniRead .................................................................. 139
IniWrite.................................................................. 139
Loop (files & folders)................................................ 140
Loop (read file contents) .......................................... 144
SetWorkingDir......................................................... 148
SplitPath ................................................................ 149
Flow of Control.......................................151
#Include / #IncludeAgain......................................... 151
{...} (block) ........................................................... 152
Break..................................................................... 153
Continue ................................................................ 154
Else ....................................................................... 154
Exit........................................................................ 156
ExitApp .................................................................. 156
Gosub.................................................................... 157
Goto ...................................................................... 158
If/IfEqual/IfNotEqual/IfLess/IfLessOrEqual/IfGreater/IfGre
aterOrEqual ............................................................ 158
if (expression)......................................................... 160
Loop (normal)......................................................... 161
Loop (files & folders)................................................ 163
Loop (parse a string) ............................................... 167
Loop (read file contents) .......................................... 170
Loop (registry) ........................................................ 173
OnExit.................................................................... 177
Pause..................................................................... 179
Return ................................................................... 180
SetBatchLines ......................................................... 181
SetTimer ................................................................ 181
Sleep ..................................................................... 185
Suspend................................................................. 185
Functions ...............................................187
Functions ............................................................... 187
Table of Contents ................................................. 187
Introduction and Simple Example ........................... 187
Parameters.......................................................... 188
Optional Parameters [v1.0.35+]............................. 188
Local Variables and Global Variables ....................... 188
Using #Include to Share Functions Among Multiple
Scripts ................................................................ 190
Short-circuit Boolean Evaluation............................. 190
Using Subroutines Within a Function....................... 191
Return, Exit, and General Remarks ......................... 191
Style and Naming Conventions............................... 192
Built-in Functions ................................................. 192
OnMessage() [v1.0.38+].......................................... 194
RegExMatch() [v1.0.45+] ........................................ 200
RegExReplace() [v1.0.45+] ...................................... 204
VarSetCapacity()..................................................... 206
GUI, MsgBox, InputBox & Other Dialogs 209
FileSelectFile .......................................................... 209
FileSelectFolder....................................................... 212
GUI ....................................................................... 214
Table of Contents ................................................. 214
Add, ControlType [, Options, Text] ......................... 214
Show [, Options, Title].......................................... 215
Submit [, NoHide] ................................................ 215
Cancel ................................................................ 216
Destroy............................................................... 216
Font [, Options, FontName] ................................... 216
Color [, WindowColor, ControlColor] ....................... 217
Margin [, X, Y] ..................................................... 217
+/-Option1 +/-Option2 ... ..................................... 217
Menu [, MenuName] ............................................. 219
Hide / Minimize / Maximize / Restore...................... 220
Flash [, Off]......................................................... 220
Default ............................................................... 221
Positioning and Layout via SmartGUI Creator........... 221
Positioning and Sizing of Controls........................... 221
Options for Assigning Actions and Variables to Controls222
Controls: Common Styles and Other Options ........... 223
Controls: Uncommon Styles and Options................. 224
Window Events .................................................... 224
Creating Multiple GUI Windows .............................. 226
GUI Events, Threads, and Subroutines.................... 226
Keyboard Navigation ............................................ 227
Window Appearance ............................................. 227
General Remarks ................................................. 227
Related ............................................................... 227
Examples ............................................................ 228
GUI Control Types................................................... 236
Table of Contents ................................................. 236
Text ................................................................... 236
Edit .................................................................... 237
UpDown [v1.0.35+] ............................................. 238
Picture (or Pic)..................................................... 239
Button ................................................................ 240
Checkbox ............................................................ 241
Radio.................................................................. 241
DropDownList (or DDL) ......................................... 241
ComboBox........................................................... 242
ListBox ............................................................... 242
ListView and TreeView .......................................... 243
Hotkey................................................................ 243
DateTime [v1.0.35+]............................................ 244
MonthCal [v1.0.35+] ............................................ 245
Slider.................................................................. 247
Progress ............................................................. 248
GroupBox............................................................ 249
Tab .................................................................... 249
Printed Documentation
vi
StatusBar [v1.0.44+]............................................ 250
Related Pages ...................................................... 251
GuiControl .............................................................. 251
GuiControlGet ......................................................... 255
ListView [v1.0.36+]................................................. 257
Table of Contents ................................................. 257
Introduction and Simple Example ........................... 257
Gui, Add, ListView, Options,
ColumnTitle1|ColumnTitle2|... ............................... 257
Options and Styles for "Gui, Add, ListView, Options" . 258
View Modes ......................................................... 259
Built-in Functions for ListViews............................... 260
Row Functions...................................................... 260
Column Functions................................................. 261
Getting Data Out of a ListView ............................... 262
G-Label Notifications (Primary) .............................. 264
G-Label Notifications (Secondary)........................... 264
ImageList (the means by which icons are added to a
ListView) ............................................................. 265
ListView Remarks ................................................. 266
Related ............................................................... 267
Examples ............................................................ 267
TreeView [v1.0.44+] ............................................... 273
Table of Contents ................................................. 273
Introduction and Simple Example ........................... 273
Options and Styles for "Gui, Add, TreeView, Options" 273
Built-in Functions for TreeViews ............................. 274
Add, Modify, and Delete Items ............................... 275
Getting Data Out of a TreeView.............................. 276
G-Label Notifications (Primary) .............................. 277
G-Label Notifications (Secondary)........................... 277
Remarks.............................................................. 278
Related ............................................................... 278
Example.............................................................. 278
IfMsgBox................................................................ 281
InputBox ................................................................ 282
MsgBox .................................................................. 283
Progress / SplashImage ........................................... 286
Window Size, Position, and Behavior....................... 287
Layout of Objects in the Window ............................ 288
Font Size and Weight ............................................ 288
Object Colors ....................................................... 288
Remarks.............................................................. 289
Related ............................................................... 289
Examples ............................................................ 290
Progress / SplashImage ........................................... 290
Window Size, Position, and Behavior....................... 292
Layout of Objects in the Window ............................ 292
Font Size and Weight ............................................ 293
Object Colors ....................................................... 293
Remarks.............................................................. 294
Related ............................................................... 294
Examples ............................................................ 294
SplashTextOn / SplashTextOff................................... 295
ToolTip................................................................... 296
TrayTip .................................................................. 297
Keyboard Control ...................................301
Hotkeys and Hotstrings............................................ 301
Hotkeys (Mouse, Joystick and Keyboard Shortcuts) .. 301
#HotkeyInterval .................................................. 306
#HotkeyModifierTimeout ....................................... 307
#Hotstring .......................................................... 308
#IfWinActive / #IfWinExist [v1.0.41/42+] .............. 309
#MaxHotkeysPerInterval ....................................... 311
#MaxThreads ...................................................... 312
#MaxThreadsBuffer .............................................. 312
#MaxThreadsPerHotkey ........................................ 313
#UseHook ........................................................... 314
Hotkey................................................................ 314
ListHotkeys ......................................................... 319
Pause ................................................................. 319
Reload ................................................................ 320
Suspend.............................................................. 321
#InstallKeybdHook.................................................. 321
#InstallMouseHook.................................................. 322
#KeyHistory ........................................................... 323
BlockInput.............................................................. 323
ControlSend / ControlSendRaw................................. 325
GetKeyState........................................................... 327
List of Keys, Mouse Buttons, and Joystick Controls ...... 330
Mouse (mouse hotkeys require Windows NT/2000/XP or
later) .................................................................. 330
Keyboard ............................................................ 330
Joystick............................................................... 332
Hand-held Remote Controls................................... 332
Special Keys ........................................................ 332
KeyHistory ............................................................. 333
KeyWait ................................................................. 334
Input ..................................................................... 336
Send / SendRaw / SendInput / SendPlay / SendEvent:
Send Keys & Clicks.................................................. 340
General Remarks ................................................. 348
SendInput [v1.0.43+] .......................................... 349
SendPlay [v1.0.43+] ............................................ 349
Related ............................................................... 350
Examples ............................................................ 350
SendMode [v1.0.43+].............................................. 350
SetKeyDelay........................................................... 351
SetCapsLockState/SetNumLockState/SetScrollLockState353
SetStoreCapslockMode............................................. 353
Math Commands.....................................355
EnvAdd.................................................................. 355
EnvDiv................................................................... 356
EnvMult ................................................................. 356
EnvSub.................................................................. 357
if (expression) ........................................................ 358
If/IfEqual/IfNotEqual/IfLess/IfLessOrEqual/IfGreater/IfGre
aterOrEqual ............................................................ 359
If var [not] between LowerBound and UpperBound...... 361
Table Of Contents
vii
If var is [not] type................................................... 362
Random................................................................. 363
SetFormat .............................................................. 365
Transform .............................................................. 367
Var := expression.................................................... 370
Misc. Commands ....................................371
#NoTrayIcon .......................................................... 371
#SingleInstance...................................................... 371
AutoTrim................................................................ 372
BlockInput.............................................................. 373
ClipWait ................................................................. 375
CoordMode ............................................................. 376
Critical [v1.0.38.04+] .............................................. 376
DllCall() ................................................................. 377
Edit ....................................................................... 388
ImageSearch .......................................................... 388
ListLines................................................................. 391
ListVars.................................................................. 391
Menu ..................................................................... 392
Add or Change Items in a Menu ............................. 392
Change the Tray Icon or ToolTip (MenuName must be
TRAY) ................................................................. 393
Misc.................................................................... 394
Remarks.............................................................. 394
Related ............................................................... 395
Examples ............................................................ 395
OutputDebug .......................................................... 398
PixelGetColor .......................................................... 399
PixelSearch............................................................. 400
Reload ................................................................... 401
SetBatchLines ......................................................... 402
SetEnv (Var = Value)............................................... 403
SetTimer ................................................................ 403
SysGet ................................................................... 407
Commonly Used ...................................................... 407
Not Commonly Used ................................................ 409
Thread ................................................................... 411
Transform .............................................................. 413
UrlDownloadToFile................................................... 415
VarSetCapacity() ..................................................... 416
Mouse Control ........................................419
Click [v1.0.43+]...................................................... 419
ControlClick ............................................................ 420
MouseClick ............................................................. 422
MouseClickDrag....................................................... 425
MouseGetPos .......................................................... 426
MouseMove............................................................. 428
SetDefaultMouseSpeed............................................. 429
SetMouseDelay ....................................................... 429
Process Management .............................431
Exit........................................................................ 431
ExitApp .................................................................. 431
OnExit.................................................................... 432
Process .................................................................. 433
Run / RunWait ........................................................ 438
RunAs.................................................................... 440
Shutdown............................................................... 441
Sleep..................................................................... 442
Registry Management ............................445
Loop (registry)........................................................ 445
RegDelete .............................................................. 448
RegRead ................................................................ 449
RegWrite................................................................ 450
Sound Commands...................................453
SoundBeep............................................................. 453
SoundGet............................................................... 453
SoundGetWaveVolume............................................. 455
SoundPlay.............................................................. 455
SoundSet ............................................................... 456
SoundSetWaveVolume............................................. 460
String Management ................................463
FormatTime............................................................ 463
If/IfEqual/IfNotEqual/IfLess/IfLessOrEqual/IfGreater/IfGre
aterOrEqual ............................................................ 467
IfInString / IfNotInString ......................................... 468
If var [not] in value1,value2,... If var [not] contains
value1,value2,... ..................................................... 469
If var is [not] type................................................... 471
Loop (parse a string) ............................................... 472
RegExMatch() [v1.0.45+] ........................................ 474
RegExReplace() [v1.0.45+] ...................................... 478
SetEnv (Var = Value) .............................................. 480
SetFormat .............................................................. 481
Sort....................................................................... 483
StringCaseSense..................................................... 485
StringGetPos .......................................................... 485
StringLeft / StringRight ............................................ 487
StringLen ............................................................... 488
StringLower / StringUpper........................................ 488
StringMid ............................................................... 489
StringReplace ......................................................... 490
StringSplit.............................................................. 491
StringTrimLeft / StringTrimRight ............................... 493
Window Management.............................495
Controls ................................................................. 495
Control ............................................................... 495
ControlClick......................................................... 496
ControlFocus ....................................................... 499
ControlGet .......................................................... 500
ControlGetFocus................................................... 503
ControlGetPos...................................................... 504
ControlGetText .................................................... 505
ControlMove ........................................................ 506
ControlSend / ControlSendRaw.............................. 508
ControlSetText..................................................... 509
Menu.................................................................. 510
Printed Documentation
viii
PostMessage / SendMessage.................................. 517
SetControlDelay ................................................... 520
WinMenuSelectItem.............................................. 520
Window Groups....................................................... 521
GroupActivate ...................................................... 521
GroupAdd............................................................ 522
GroupClose.......................................................... 524
GroupDeactivate .................................................. 524
#WinActivateForce .................................................. 525
DetectHiddenText .................................................... 525
DetectHiddenWindows.............................................. 526
IfWinActive / IfWinNotActive..................................... 527
IfWinExist / IfWinNotExist ........................................ 528
SetTitleMatchMode .................................................. 529
SetWinDelay........................................................... 531
StatusBarGetText .................................................... 531
StatusBarWait......................................................... 532
WinActivate ............................................................ 534
WinActivateBottom.................................................. 535
WinClose ................................................................ 536
WinGet................................................................... 537
WinGetActiveStats................................................... 540
WinGetActiveTitle .................................................... 541
WinGetClass ........................................................... 541
WinGetPos.............................................................. 542
WinGetText ............................................................ 543
WinGetTitle............................................................. 544
WinHide ................................................................. 545
WinKill ................................................................... 546
WinMaximize........................................................... 547
WinMinimize ........................................................... 548
WinMinimizeAll / WinMinimizeAllUndo......................... 549
WinMove ................................................................ 549
WinRestore............................................................. 550
WinSet ................................................................... 551
WinSetTitle............................................................. 555
WinShow................................................................ 556
WinWait ................................................................. 557
WinWaitActive / WinWaitNotActive............................. 558
WinWaitClose.......................................................... 559
#Directives ............................................561
#AllowSameLineComments ...................................... 561
#ClipboardTimeout .................................................. 561
#CommentFlag ....................................................... 561
#ErrorStdOut.......................................................... 562
#EscapeChar (and explanation of escape sequences)... 563
#HotkeyInterval ...................................................... 564
#HotkeyModifierTimeout .......................................... 565
#Hotstring.............................................................. 565
#IfWinActive / #IfWinExist [v1.0.41/42+].................. 566
#Include / #IncludeAgain......................................... 569
#InstallKeybdHook .................................................. 570
#InstallMouseHook.................................................. 571
#KeyHistory ........................................................... 572
#MaxHotkeysPerInterval .......................................... 572
#MaxMem.............................................................. 573
#MaxThreads ......................................................... 573
#MaxThreadsBuffer ................................................. 574
#MaxThreadsPerHotkey ........................................... 575
#NoEnv [v1.0.43.08+] ............................................ 575
#NoTrayIcon .......................................................... 576
#Persistent ............................................................ 576
#SingleInstance...................................................... 577
#UseHook .............................................................. 577
#WinActivateForce .................................................. 578
Index .....................................................581

1
Introduction
AutoHotkey is a free, open-source utility for Windows. With it, you can:
Automate almost anything by sending keystrokes and mouse clicks. You can write macros by
hand or use the macro recorder.
Create hotkeys for keyboard, joystick, and mouse. Virtually any key, button, or combination
can become a hotkey.
Expand abbreviations as you type them. For example, typing "btw" can automatically produce
"by the way".
Create custom data entry forms, user interfaces, and menu bars. See GUI for details.
Remap keys and buttons on your keyboard, joystick, and mouse.
Respond to signals from hand-held remote controls via the WinLIRC client script.
Run existing AutoIt v2 scripts and enhance them with new capabilities.
Convert any script into an EXE file that can be run on computers that don't have AutoHotkey
installed.
Getting started might be easier than you think. Check out the quick-start tutorial.
More about Hotkeys
AutoHotkey unleashes the full potential of your keyboard, joystick, and mouse. For example, in
addition to the typical Control, Alt, and Shift modifiers, you can use the Windows key and the Capslock
key as modifiers. In fact, you can make any key or mouse button act as a modifier. For these and
other capabilities, see Advanced Hotkeys.
Other Features
Change the volume, mute, and other settings of any soundcard.
Make any window transparent, always-on-top, or alter its shape.
Use a joystick or keyboard as a mouse.
Monitor your system. For example, close unwanted windows the moment they appear.
Retrieve and change the clipboard's contents, including file names copied from an Explorer
window.
Disable or override Windows' own shortcut keys such as Win+E and Win+R.
Alleviate RSI with substitutes for Alt-Tab (using keys, mouse wheel, or buttons).
Customize the tray icon menu with your own icon, tooltip, menu items, and submenus.
Display dialog boxes, tooltips, balloon tips, and popup menus to interact with the user.
Perform scripted actions in response to system shutdown or logoff.
Detect how long the user has been idle. For example, run CPU intensive tasks only when the
user is away.
Automate game actions by detecting images and pixel colors (this is intended for legitimate
uses such as the alleviation of RSI).
Read, write, and parse text files more easily than in other languages.
Perform operation(s) upon a set of files that match a wildcard pattern.
Work with the registry and INI files.

License: GNU General Public License
Features Not Available on Windows 95/98/Me: Hotstrings, mouse button hotkeys, and certain
advanced hotkey features.
Printed Documentation
2
Acknowledgements
A special thanks to Jonathan Bennett, whose generosity in releasing AutoIt v2 as free software in
1999 served as an inspiration and time-saver for myself and many others worldwide. In addition,
many of AutoHotkey's enhancements to the AutoIt v2 command set, as well as the Window Spy and
the script compiler, were adapted directly from the AutoIt v3 source code. So thanks to Jon and the
other AutoIt authors for those as well.

Finally, AutoHotkey would not be what it is today without these other individuals.

3
Tutorial and Overview
This brief introduction will help you start scripting your own macros and hotkeys right away.
Tutorial Contents
Creating a script
Launching a program or document
Sending keystrokes and mouse clicks
Activating and manipulating windows
Getting input from the user with MsgBox, InputBox, etc.
Using variables and the clipboard
Repeating a series of actions over and over
Manipulating files and folders
Overview of other features
Creating a script
Each script is a plain text file containing commands to be executed by the program (AutoHotkey.exe).
A script may also contain hotkeys and hotstrings, or even consist entirely of them. However, in the
absence of hotkeys and hotstrings, a script will perform its commands sequentially from top to bottom
the moment it is launched.
To create a new script:
Open Windows Explorer and navigate to a folder of your choice.
Pull down the File menu and choose New >> AutoHotkey Script (or Text Document).
Type a name for the file, ensuring that it ends in .ahk. For example: Test.ahk
Right-click the file and choose Edit Script.
On a new blank line, type the following:
#space::Run www.google.com
The symbol # stands for the Windows key, so #space means holding down the Windows key then
pressing the spacebar to activate a hotkey. The :: means that the subsequent command should be
executed whenever this hotkey is pressed, in this case to go to the Google web site. To try out this
script, continue as follows:
Save and close the file.
In Windows Explorer, double-click the script to launch it. A new tray icon appears.
Hold down the Windows key and press the spacebar. A web page opens in the default browser.
To exit or edit the script, right click its tray icon.
Note: Multiple scripts can be running simultaneously, each with its own tray icon. Furthermore, each
script can have multiple hotkeys and hotstrings.
Launching a program or document
The Run command is used to launch a program, document, URL, or shortcut. Here are some common
examples:
Run Notepad
Run C:\My Documents\Address List.doc
Run C:\My Documents\My Shortcut.lnk
Run www.yahoo.com
Run mailto:[email protected]
Printed Documentation
4
A hotkey can be assigned to any of the above examples by including a hotkey label. In the first
example below, the assigned hotkey is Win+N, while in the second it is Control+Alt+C:
#n::Run Notepad
^!c::Run calc.exe
The above examples are known as single-line hotkeys because each consists of only one command. To
have more than one command executed by a hotkey, put the first line beneath the hotkey definition
and make the last line a return. For example:
#n::
Run http://www.google.com
Run Notepad.exe
return
If the program or document to be run is not integrated with the system, specify its full path to get it
to launch:
Run %A_ProgramFiles%\Winamp\Winamp.exe
In the above example, %A_ProgramFiles% is a built-in variable. By using it rather than something like
C:\Program Files, the script is made more portable, meaning that it would be more likely to run on
other computers. Note: The names of commands and variables are not case sensitive. For example,
"Run" is the same as "run", and "A_ProgramFiles" is the same as "a_programfiles".
To have the script wait for the program or document to close before continuing, use RunWait instead
of Run. In the following example, the MsgBox command will not execute until after the user closes
Notepad:
RunWait Notepad
MsgBox The user has finished (Notepad has been closed).
To learn more about launching programs -- such as passing parameters, specifying the working
directory, and discovering a program's exit code -- click here.
Sending keystrokes and mouse clicks
Keystrokes are sent to the active (foremost) window by using the Send command. In the following
example, Win+S becomes a hotkey to type a signature (ensure that a window such as an editor or
draft e-mail message is active before pressing Win+S):
#s::
Send Sincerely,{Enter}John Smith
return
In the above example, all characters are sent literally except {Enter}, which simulates a press of the
Enter key. The next example illustrates some of the other commonly used special characters:
Send ^c!{tab}pasted:^v
The line above sends a Control+C followed by an Alt+Tab followed by the string "pasted:" followed by
a Control+V. See the Send command for a complete list of special characters and keys.
Finally, keystrokes can also be sent in response to abbreviations you type, which are known as
hotstrings. For example, whenever you type Btw followed by a space or comma, the following line will
replace it with "By the way":
::btw::by the way

Mouse Clicks: To send a mouse click to a window it is first necessary to determine the X and Y
AutoHotkey Tutorial: Macro and Hotkey Creation
5
coordinates where the click should occur. This can be done with either AutoScriptWriter or Window
Spy, which are included with AutoHotkey. The following steps apply to the Window Spy method:
Launch Window Spy from the program's tray-icon menu or the Start Menu.
Activate the window of interest either by clicking its title bar, alt-tabbing, or other means (Window
Spy will stay "always on top" by design).
Move the mouse cursor to the desired position in the target window and write down the mouse
coordinates displayed by Window Spy (or press Shift-Alt-Tab to activate Window Spy so that the
"frozen" coordinates can be copied and pasted).
1. Apply the coordinates discovered above to the Click command. The following example clicks
the left mouse button:
Click 112, 223
To move the mouse without clicking, use MouseMove. To drag the mouse, use MouseClickDrag.
Activating and manipulating windows
To activate a window (make it foremost), use WinActivate. To detect whether a window exists, use
IfWinExist or WinWait. The following example illustrates these commands:
IfWinExist Untitled - Notepad
{
WinActivate
}
else
{
Run Notepad
WinWait Untitled - Notepad
WinActivate
}
The above example first searches for any existing window whose title starts with "Untitled - Notepad"
(case sensitive). If such a window is found, it is activated. Otherwise, Notepad is launched and the
script waits for the Untitled window to appear, at which time it is activated. The above example also
utilizes the last found window to avoid the need to specify the window's title to the right of each
WinActivate.
Some of the other commonly used window commands are:
IfWinActive: Checks if the specified window is currently active.
WinWaitActive: Waits for the specified window to become active (typically used after sending a
window-activating keystroke such as pressing Control-F for "Find").
WinClose: Closes the specified window.
WinMove: Moves and/or resizes the specified window.
WinMinimize, WinMaximize, WinRestore: Minimizes, maximizes, or restores the specified
window, respectively.
Getting input from the user with MsgBox, InputBox, etc.
The following example displays a dialog with two buttons (YES and NO):
MsgBox, 4, , Would you like to continue?
IfMsgBox, No
return
Printed Documentation
6
; Otherwise, the user picked yes.
MsgBox You pressed YES.
Use the InputBox command to prompt the user to type a string. Use FileSelectFile or FileSelectFolder
to have the user select a file or folder. For more advanced tasks, use the Gui command to create
custom data entry forms and user interfaces.
Tip: You may have noticed from the other examples that the first comma of any command may be
omitted. For example:
MsgBox This is ok.
MsgBox, This is ok too (it has an explicit comma).
Using variables and the clipboard
A variable is an area of memory in which the script stores text. Although all variables store their
contents as character strings, a variable containing only digits (with an optional decimal point) is
automatically converted to a number when a math operation or comparison requires it. Conversely,
the result of a math operation is converted back to a string when it needs to be stored in a variable.
With the exception of local variables in functions, all variables are global; that is, their contents may
be read or altered by any part of the script. In addition, variables are not declared; they come into
existence simply by using them (and each variable starts off empty/blank).
To assign a string to a variable, follow these examples:
MyVar1 = 123
MyVar2 = my string
To compare the contents of a variable to a number or string, follow these examples:
if MyVar2 = my string
{
MsgBox MyVar2 contains the string "my string".
}
if MyVar1 >= 100
{
MsgBox MyVar1 contains %MyVar1%, which is a number greater than or equal to 100.
}
In the MsgBox line above, notice that the second occurrence of MyVar1 is enclosed in percent signs.
This displays the contents of MyVar1 at that position. The same technique can be used to copy the
contents of one variable to another. For example:
MyVarConcatenated = %MyVar1% %MyVar2%
The line above stores the string "123 my string" (without the quotes) in the variable
MyVarConcatenated.
To compare the contents of a variable with that of another, consider this example:
if (ItemCount > ItemLimit)
{
MsgBox The value in ItemCount, which is %ItemCount%, is greater than %ItemLimit%.
}
Notice that the first line of the example above contains parentheses. The parentheses signify that the
if-statement contains an expression. Without them, that line would be considered a "non-expression
AutoHotkey Tutorial: Macro and Hotkey Creation
7
if-statement", and thus it would need percent signs around ItemLimit. Such if-statements are limited
to a single comparison operator; that is, they cannot contain math operators or conjunctions such as
"AND" and "OR".

Math: To perform a math operation, use the colon-equal operator (:=) to assign the result of an
expression to a variable as in the example below:
NetPrice := Price * (1 - Discount/100)
See expressions for a complete list of math operators.

Clipboard: The variable named Clipboard is special because it contains the current text on the
Windows clipboard. Even so, it can be used as though it were a normal variable. For example, the
following line would display the current contents of the clipboard:
MsgBox %clipboard%
To alter the clipboard, consider the following example, which replaces the current contents of the
clipboard with new text:
clipboard = A line of text.`r`nA second line of text.`r`n
In the above, `r and `n (accent followed by the letter "r" or "n") are used to indicate two special
characters: carriage return and linefeed. These two characters start a new line of text as though the
user had pressed Enter.
To append text to the clipboard (or any other variable), follow this example:
clipboard = %clipboard% And here is the text to append.
See the clipboard and variables sections for more details.
Repeating a series of actions over and over
To perform something more than once consecutively, a loop is the answer. The following loop shows a
MsgBox three times:
Loop 3
{
MsgBox This window will be displayed three times.
}
You could also specify a variable after the word Loop, which is useful in situations where the number
of iterations is determined somewhere inside the script:
Loop %RunCount%
{
Run C:\Check Server Status.exe
Sleep 60000 ; Wait 60 seconds.
}
In the above, the loop is performed the specified number of times unless RunCount contains 0, in
which case the loop is skipped entirely.
A loop may also terminate itself when one or more conditions change. The following example clicks the
left mouse button repeatedly while the user is holding down the F1 key:
$F1:: ; Make the F1 key into a hotkey (the $ symbol facilitates the "P" mode of GetKeyState
below).
Loop ; Since no number is specified with it, this is an infinite loop unless "break" or "return" is
encountered inside.
Printed Documentation
8
{
if not GetKeyState("F1", "P") ; If this statement is true, the user has physically released
the F1 key.
break ; Break out of the loop.
; Otherwise (since the above didn't "break"), keep clicking the mouse.
Click ; Click the left mouse button at the cursor's current position.
}
return
The example above is functionally identical to what is sometimes called a "while...do" loop. The phrase
"while...do" refers to the fact that this loop does something repeatedly while certain condition(s)
remain true. In this case, the loop continues clicking the left mouse button while the F1 key is being
held down. When the user releases F1, the loop detects this and stops itself via the break command.
Break causes execution to jump to the line after the loop's closing brace.
The examples shown above are general-purpose loops. For more specialized needs, consider one of
the following loops:
File-reading/writing loop: Retrieves the lines in a text file, one at a time. This can be used to
transform a file into a different format on a line-by-line basis. It can also be used to search for lines
matching your criteria.
Files and folders loop: Retrieves the specified files or folders, one at a time. This allows an operation
to be performed upon each file or folder that meets your criteria.
Parsing loop: Retrieves substrings from a string, one at a time. This allows a string such as
"Red,Green,Blue" to be easily broken down into its three component fields.
Registry loop: Retrieves the contents of the specified registry subkey, one item at a time.
Manipulating files and folders
To add text to the end of a file (or create a new file), use FileAppend as shown in the following
example. Note that it uses `n (linefeed) to start a new line of text afterward:
FileAppend, A line of text to append.`n, C:\My Documents\My Text File.txt
To overwrite an existing file, use FileDelete prior to FileAppend. For example:
FileDelete, C:\My Documents\My Text File.txt
Some of the other commonly used file and folder commands are:
FileRead: Read the entire contents of a file into a variable.
File-reading Loop: Retrieve the lines in a text file, one by one.
IfExist: Determine whether a file or folder exists.
FileSelectFile and FileSelectFolder: Display a dialog for the user to pick a file or folder.
FileDelete/FileRecycle: Delete/recycle one or more files. Use FileRemoveDir to delete an entire
folder.
FileCopy/FileMove: Copy/move one or more files. Use FileCopyDir/FileMoveDir to copy/move
an entire folder.
File Loop: Retrieve the files and folders contained in a folder, one at a time.
FileSetAttrib and FileSetTime: Change the attributes or timestamp of one or more files.
IniRead, IniWrite, and IniDelete: Create, access, and maintain standard-format INI files.
RegRead, RegWrite, RegDelete, and Registry Loop: Work with the Windows registry.
AutoHotkey Tutorial: Macro and Hotkey Creation
9
Overview of other features
See the command list for an overview of every command.


11
Frequently Asked Questions (FAQ)
Language Syntax
When are quotation marks used with commands and their parameters?
When exactly are variable names enclosed in percent signs?
When should percent signs and commas be escaped?
Common Tasks
Why do some lines in my script never execute?
Why is the Run command unable to launch my game or program?
How can the output of a command line operation be retrieved?
How can a script close, pause, or suspend other script(s)?
How can a repeating action be stopped without exiting the script?
How can performance be improved for games or at other times when the CPU is under heavy
load?
How can context sensitive help for AutoHotkey commands be used in any editor?
How can a script detect when a web page is finished loading?
How can dates and times be compared or manipulated?
Why don't Hotstrings, Send, and MouseClick work in certain games?
How can Winamp be controlled even when it isn't active?
How can MsgBox's button names be changed?
Hotkeys, Hotstrings, and Remapping
How do I put my hotkeys and hotstrings into effect automatically every time I start my PC?
I'm having trouble getting my mouse buttons working as hotkeys. Any advice?
How can tab and space be defined as hotkeys?
How can keys or mouse buttons be remapped so that they become different keys?
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.
How can a prefix key be made to perform its native function rather than doing nothing?
How can the built-in Windows shortcut keys, such as Win+U (Utility Manager) and Win+R
(Run), be changed or disabled?
My keypad has a special 000 key. Is it possible to turn it into a hotkey?
Language Syntax
When are quotation marks used with commands and their parameters?
Double quotes (") have special meaning only within expressions. 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: Run, Notepad.exe "C:\My Documents\Address List.txt"
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: StringLen, OutputVar, InputVar
2) On the left side of an assignment: Var = 123abc
3) On the left side of traditional (non-expression) if-statements: If Var1 < %Var2%
Printed Documentation
12
4) Everywhere in expressions. For example:
If (Var1 <> Var2)
Var1 := Var2 + 100
When should percent signs and commas be escaped?
Literal percent signs must be escaped by preceding them with an accent/backtick. For example:
MsgBox The current percentage is 25`%. 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 expression, the accent is permitted
but not necessary. For example: Var := "15%"
Common Tasks
Why do some lines in my script never execute?
Any lines you want to execute immediately when the script starts should appear at the top of the
script, prior to the first hotkey, hotstring, or Return. For details, see auto-execute section.
Also, a hotkey that executes more than one line must list its first line beneath the hotkey, not on the
same line. For example:
#space:: ; Win+Spacebar
Run Notepad
WinWaitActive Untitled - Notepad
WinMaximize
return
Why is the Run command unable to launch my game or program?
Some programs need to be started in their own directories (when in doubt, it is usually best to do so).
For example:
Run, %A_ProgramFiles%\Some Application\App.exe, %A_ProgramFiles%\Some Application
How can the output of a command line operation be retrieved?
Testing shows that due to file caching, a temporary file can be very fast for relatively small outputs. In
fact, if the file is deleted immediately after use, it often does not actually get written to disk. For
example:
RunWait %comspec% /c dir > C:\My Temp File.txt
FileRead, VarToContainContents, C:\My Temp File.txt
FileDelete, C:\My Temp File.txt
To avoid using a temporary file (especially if the output is large), consider using CmdRet.
Alternatively, there is a small freeware utility cb.zip (4 KB) that captures up to 512 KB of output from
a command or program. The text is captured to the clipboard, which a script can access via the
clipboard variable. For example:
RunWait %comspec% /c dir | cb.exe
MsgBox %clipboard%
How can a script close, pause, or suspend other script(s)?
First, here is an example that closes another script:
DetectHiddenWindows On ; Allows a script's hidden main window to be detected.
AutoHotkey FAQ
13
SetTitleMatchMode 2 ; Avoids the need to specify the full path of the file below.
WinClose Script's File Name.ahk - AutoHotkey ; Update this to reflect the script's name (case
sensitive).
To suspend or pause another script, replace the last line above with one of these:
PostMessage, 0x111, 65305,,, Script's File Name.ahk - AutoHotkey ; Suspend.
PostMessage, 0x111, 65306,,, Script's File Name.ahk - AutoHotkey ; Pause.
How can a repeating action be stopped without exiting the script?
To pause or resume the entire script at the press of a key, assign a hotkey to the Pause command as
in this example:
^!p::Pause ; Press Ctrl+Alt+P to pause. Press it again to resume.
To stop an action that is repeating inside a Loop, consider the following working example, which is a
hotkey that both starts and stops its own repeating action. In other words, pressing the hotkey once
will start the Loop. Pressing the same hotkey again will stop it.
#MaxThreadsPerHotkey 3
#z:: ; Win+Z hotkey (change this hotkey to suit your preferences).
#MaxThreadsPerHotkey 1
if KeepWinZRunning ; This means an underlying thread is already running the loop below.
{
KeepWinZRunning := false ; Signal that thread's loop to stop.
return ; End this thread so that the one underneath will resume and see the change made
by the line above.
}
; Otherwise:
KeepWinZRunning := true
Loop
{
; The next four lines are the action you want to repeat (update them to suit your
preferences):
ToolTip, Press Win-Z again to stop this from flashing.
Sleep 1000
ToolTip
Sleep 1000
; But leave the rest below unchanged.
if not KeepWinZRunning ; The user signaled the loop to stop by pressing Win-Z again.
break ; Break out of this loop.
}
KeepWinZRunning := false ; Reset in preparation for the next press of this hotkey.
return
How can performance be improved for games or at other times when the CPU is
under heavy load?
Printed Documentation
14
If a script's Hotkeys, Clicks, or Sends are noticeably slower than normal while the CPU is under heavy
load, raising the script's process-priority may help. To do this, include the following line near the top
of the script:
Process, Priority, , High
How can context sensitive help for AutoHotkey commands be used in any editor?
Rajat created this script.
How can a script detect when a web page is finished loading?
The technique in the following example will work with MS Internet Explorer for most pages. A similar
technique might work in other browsers:
Run, www.yahoo.com
MouseMove, 0, 0 ; Prevents the status bar from showing a mouse-hover link instead of
"Done".
WinWait, Yahoo! - Microsoft Internet Explorer
WinActivate
StatusBarWait, Done, 30
if ErrorLevel
MsgBox The wait timed out or the window was closed.
else
MsgBox The page is done loading.
How can dates and times be compared or manipulated?
The EnvAdd command can add or subtract a quantity of days, hours, minutes, or seconds to a time-
string that is in the YYYYMMDDHH24MISS format. The following example subtracts 7 days from the
specified time:
EnvAdd, VarContainingTimestamp, -7, days
To determine the amount of time between two dates or times, see EnvSub, which gives an example.
Also, the built-in variable A_Now contains the current local time. Finally, there are several built-in
date/time variables, as well as the FormatTime command to create a custom date/time string.
Why do Hotstrings, Send, and Click have no effect in certain games?
Some games use DirectInput exclusively. As a side-effect, they might ignore all simulated keystrokes
and mouse clicks. To work around this, try one of the following (or a combination):
Use SendPlay via: 1) the SendPlay command; 2) using SendMode Play; and/or 3) the
hotstring option SP.
Increase SetKeyDelay. For example:
SetKeyDelay, 0, 50
SetKeyDelay, 0, 50, Play
Try ControlSend, which might work in cases where the other Send modes fail.
How can Winamp be controlled even when it isn't active?
See Automating Winamp.
How can MsgBox's button names be changed?
Here is an example.
AutoHotkey FAQ
15
Hotkeys, Hotstrings, and Remapping
How do I put my hotkeys and hotstrings into effect automatically every time I
start my PC?
There is a folder in the Start Menu called Startup. If you put a shortcut to your script in that folder,
the script will launch automatically every time you start your PC. To create a shortcut:
Select the script file in Explorer and press Control-C (but if your script is named "AutoHotkey.ini",
select AutoHotkey.exe instead).
Right-click the Start button and choose "Explore All Users".
Navigate to the Startup folder inside the Programs folder.
1. From the menu bar, choose Edit > 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?
Note that mouse hotkeys are not currently possible on Windows 95/98/Me. On other operating
systems, the left and right mouse buttons should be assignable normally (for example, "#LButton::" 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 -- 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 ^F1:: 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, #Space is
Win+Space and ^!Tab is Control+Alt+Tab.
How can keys or mouse buttons be remapped so that they become different keys?
This is described on the remapping page.
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.
Windows 95/98/Me: Although the above method works, pressing Control-A in a window other than
Notepad will do nothing at all (not even its native function). To work around this, use:
$^a::Send ^a ; This hotkey must be listed first on Windows 9x. The $ prefix allows it to
"send itself".
#IfWinActive, ahk_class Notepad
^a::MsgBox You pressed Control-A while Notepad is active.
Printed Documentation
16
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.
How can the built-in Windows shortcut keys, such as Win+U (Utility Manager) and
Win+R (Run), be changed or disabled?
Here are some examples.
My keypad has a special 000 key. Is it possible to turn it into a hotkey?
You can, but only if you're running Windows NT, 2000, XP, or beyond. This example script makes the
000 key into an equals key. You can change the action by replacing the "Send, =" line with line(s) of
your choice.

17
Hotkeys (Mouse, Joystick and Keyboard Shortcuts)
Table of Contents
Introduction and Simple Examples
Table of Hotkey Prefix Symbols (Modifiers)
Context-sensitive Hotkeys
Custom Combinations and Other Features
Mouse Wheel Hotkeys
Hotkey Tips and Remarks
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 Windows key, which is known as a
modifier:
#n::
Run Notepad
return
In the final line above, "return" 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 return 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::
Send Sincerely,{enter}John Smith ; This line sends keystrokes to the active (foremost)
window.
return
You can use the following modifier symbols to define hotkeys:
Symbol Description
# Win (Windows logo key)
! Alt
^ Control
+ Shift
&
An ampersand may be used between any two keys or mouse buttons to combine
them into a custom hotkey. See below for details. Such hotkeys are ignored (not
activated) on Windows 95/98/Me.
<
Use the left key of the pair. e.g. <!a is the same as !a except that only the left Alt
key will trigger it. This symbol is ignored on Windows 95/98/ME.
> Use the right key of the pair. This symbol is ignored on Windows 95/98/ME.
<^>!
AltGr (alternate graving). If your keyboard layout has an AltGr key instead of a
right-Alt key, this series of symbols can usually be used to stand for AltGr (requires
Windows NT/2k/XP or later). For example:
Printed Documentation
18
<^>!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 modifer key(s) are down.
This symbol is ignored on Windows 95/98/ME.
~
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.
Notes: 1) Unlike the other prefix symbols, the tilde prefix may be present on some
of a hotkey's variants but absent on others; 2) Special hotkeys that are substitutes
for alt-tab always ignore the tilde prefix; 3) The tilde prefix is ignored on Windows
95/98/ME
$
This is usually only necessary if the script uses the Send command to send the keys
that comprise the hotkey itself, which might otherwise cause it to trigger itself. The
exact behavior of the $ prefix varies depending on operating system:
On Windows NT4/2k/XP or later: The $ prefix forces the keyboard hook to be used
to implement this hotkey, which as a side-effect prevents the Send command from
triggering it. The $ prefix is equivalent to having specified #UseHook somewhere
above the definition of this hotkey.
On Windows 95/98/Me: The hotkey is disabled during the execution of its thread
and re-enabled afterward. As a side-effect, if #MaxThreadsPerHotkey is set higher
than 1, it will behave as though set to 1 for such hotkeys.
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 LWin to become LControl:
*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; 2) "Up" requires Windows
NT4/2000/XP or later; and 3) 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::)
On a related note, a technique similar to the above is to make a hotkey into a prefix
Hotkeys (Mouse, Joystick and Keyboard Shortcuts)
19
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.
(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 Control+Numpad0 or Control+Numpad1 will display this message.
return
A key or key-combination can be disabled for the entire system by having it do nothing. The following
example disables the right-side Windows key:
RWin::return
Context-sensitive Hotkeys [v1.0.41+]
The directives #IfWinActive/Exist can be used to make a hotkey perform a different action (or none at
all) depending on the type of window that is active or exists. For example:
#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.
Custom Combinations and Other Features [Windows NT/2000/XP or later]
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
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.
The presence of one of the above 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.
Numlock, Capslock, and Scrolllock: These keys may be forced to be "AlwaysOn" or "AlwaysOff".
For example: SetNumlockState AlwaysOn
Printed Documentation
20
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 Alt-Tab.
Mouse Wheel Hotkeys [Windows NT/2000/XP or later]
Hotkeys that fire upon turning the mouse wheel are supported via the key names WheelDown and
WheelUp. For example:
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.
In v1.0.43.03+, the built-in variable A_EventInfo contains the number of notches by which the
wheel was turned, which is always at least 1. Integers higher than 1 typically occur when the wheel is
being turned quickly (though how common this is depends on the granularity of the mouse hardware).
Example usage: ~WheelDown::ToolTip %A_EventInfo%
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 Control key:
~LControl & WheelUp:: ; Scroll left.
ControlGetFocus, fcontrol, A
Loop 2 ; <-- Increase this value to scroll faster.
SendMessage, 0x114, 0, 0, %fcontrol%, A ; 0x114 is WM_HSCROLL and the 0 after it is
SB_LINERIGHT.
return

~LControl & WheelDown:: ; Scroll right.
ControlGetFocus, fcontrol, A
Loop 2 ; <-- Increase this value to scroll faster.
SendMessage, 0x114, 1, 0, %fcontrol%, A ; 0x114 is WM_HSCROLL and the 1 after it is
SB_LINELEFT.
return
Finally, since mouse wheel hotkeys generate only down-events (never up-events), they cannot be
used as key-up hotkeys.
Hotkey Tips and Remarks
Each numpad key can be made to launch two different hotkey subroutines depending on the state of
Numlock. Alternatively, a numpad key can be made to launch the same subroutine regardless of the
Numlock state. For example:
NumpadEnd::
Hotkeys (Mouse, Joystick and Keyboard Shortcuts)
21
Numpad1::
MsgBox, This hotkey is launched regardless of whether Numlock is on.
return
If the tilde (~) operator is used with a prefix key even once, that prefix will always be sent through to
the active window. 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:
~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.
The Suspend command can temporarily disable all hotkeys except for ones you make exempt. For
greater selectivity, use #IfWinActive/Exist.
By means the Hotkey 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.
Joystick hotkeys do not currently support modifier prefixes such as ^ (Control) and # (Win). However,
you can use GetKeyState to mimic this effect as shown in the following example:
Joy2::
if not GetKeyState("Control") ; Neither the left nor right Control key is down.
return ; i.e. Do nothing.
MsgBox You pressed the first joystick's second button while holding down the Control key.
return
There may be times when a hotkey should wait for its own modifier keys to be released before
continuing. Consider the following example:
^!s::Send {Delete}
Pressing Control-Alt-S would cause the system to behave as though you pressed Control-Alt-Delete
(due to the system's aggressive detection of Ctrl-Alt-Delete). To work around this, use KeyWait to
wait for the keys to be released; for example:
^!s::
KeyWait Control
KeyWait Alt
Send {Delete}
return
A hotkey label can be used as the target of a Gosub or Goto. For example: Gosub ^!s
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 this FAQ topic.
Finally, each script is quasi multi-threaded, 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
MsgBox is being displayed by the current hotkey.
Alt-Tab Hotkeys
Each Alt-Tab hotkey must be a combination of two keys, which is typically achieved via the ampersand
symbol (&). In the following example, you would hold down the right Alt key and press J or K to
navigate the alt-tab menu:
RAlt & j::AltTab
Printed Documentation
22
RAlt & k::ShiftAltTab
AltTab and ShiftAltTab are two of the special commands that are only recognized when used on the
same line as a hotkey. Here is the complete list:
AltTab: If the menu is displayed, move forward in it. Otherwise, display the menu if the hotkey is an
"&" combination of two keys; otherwise, do nothing.
ShiftAltTab: Same as above except move backward in the menu.
AltTabAndMenu: If the menu is displayed, move forward in it. Otherwise, display the menu.
AltTabMenuDismiss: Close the Alt-tab menu.
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:
MButton::AltTabMenu
WheelDown::AltTab
WheelUp::ShiftAltTab
To cancel a hotkey-invoked Alt-tab menu without activating the selected window, use a hotkey such
as the following. It might require adjustment depending on: 1) the means by which the alt-tab menu
was originally displayed; and 2) whether the script has the keyboard hook installed.
LCtrl & CapsLock::AltTab
!MButton:: ; Middle mouse button. The ! prefix makes it fire while the Alt key is down (which
it is if the alt-tab menu is visible).
IfWinExist ahk_class #32771 ; Indicates that the alt-tab menu is present on the screen.
Send !{Escape}{Alt up}
return
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). Also, the presence of the alt-tab menu can
be detected via IfWinExist ahk_class #32771
Custom alt-tab actions can also be created via hotkeys. In the following example, you would press F1
to display the menu and advance forward in it. Then you would press F2 to activate the selected
window (or press Escape to cancel):
*F1::Send {Alt down}{tab} ; Asterisk is required in this case.
!F2::Send {Alt up} ; Release the Alt key, which activates the selected window.
~*Escape::
IfWinExist ahk_class #32771
Send {Escape}{Alt up} ; Cancel the menu without activating the selected window.
return

23
Hotstrings and Auto-replace
Note: Hotstrings require Windows NT/2000/XP or later.
Introduction and Simple Examples
Although hotstrings are mainly used to expand abbreviations as you type them (auto-replace), they
can also be used to launch any scripted action. In this respect, they are similar to hotkeys except that
they are typically composed of more than one character (that is, a string).
To define a hotstring, enclose the triggering abbreviation between pairs of colons as in this example:
::btw::by the way
In the above example, the abbreviation btw will be automatically replaced with "by the way" whenever
you type it (however, by default you must type an ending character after typing btw, such as a space,
period, or enter).
The "by the way" example above is known as an auto-replace hotstring because the typed text is
automatically erased and replaced by the string specified after the second pair of colons. By contrast,
a hotstring may also be defined to perform any custom action as in the following examples. Note that
the commands must appear beneath the hotstring:
::btw::
MsgBox You typed "btw".
return

:*:]d:: ; This hotstring replaces "]d" with the current date and time via the commands below.
FormatTime, CurrentDateTime,, M/d/yyyy h:mm tt ; It will look like 9/1/2005 3:53 PM
SendInput %CurrentDateTime%
return
Even though the two examples above are not auto-replace hotstrings, the abbreviation you type is
erased by default. This is done via automatic backspacing, which can be disabled via the b0 option.
Ending Characters
Unless the asterisk option is in effect, you must type an ending character after a hotstring's
abbreviation to trigger it. Ending characters initially consist of the following: -()[]{}':;"/\,.?!`n `t
(note that `n is Enter, `t is Tab, and there is a plain space between `n and `t). This set of characters
can be changed by editing the following example, which sets the new ending characters for all
hotstrings, not just the ones beneath it:
#Hotstring EndChars -()[]{}:;'"/\,.?!`n `t
Options
A hotstring's default behavior can be changed in two possible ways:
1. The #Hotstring directive, which affects all hotstrings physically beneath that point in the
script. The following example puts the C and R options into effect:
#Hotstring c r
2. Putting options inside a hotstring's first pair of colons. The following example puts the C and *
options into effect for a single hotstring:
:c*:j@::[email protected] ; Case sensitive and "ending character not required".
The list below describes each option. When specifying more than one option using the methods above,
spaces optionally may be included between them.

Printed Documentation
24
* (asterisk): An ending character (e.g. space, period, or enter) is not required to trigger the hotstring.
For example:
:*:j@::[email protected]
The example above would send its replacement the moment you type the @ character. When using
the #Hotstring directive, use *0 to turn this option back off.
? (question mark): The hotstring will be triggered even when it is inside another word; that is, when
the character typed immediately before it is alphanumeric. For example, if :?:al::airline is a hotstring,
typing "practical " would produce "practicairline ". Use ?0 to turn this option back off.
B0 (B followed by a zero): Automatic backspacing is not done to erase the abbreviation you type. Use
a plain B to turn backspacing back on after it was previously turned off.
C: Case sensitive: When you type an abbreviation, it must exactly match the case defined in the
script. Use C0 to turn case sensitivity back off.
C1: Do not conform to typed case. Use this option to make auto-replace hotstrings case insensitive
and prevent them from conforming to the case of the characters you actually type. Case-conforming
hotstrings (which are the default) produce their replacement text in all caps if you type the
abbreviation in all caps. If you type only the first letter in caps, the first letter of the replacement will
also be capitalized (if it is a letter). If you type the case in any other way, the replacement is sent
exactly as defined. When using the #Hotstring directive, C0 can be used to turn this option back off,
which makes hotstrings conform again.
Kn: Key-delay: This rarely-used option sets the delay between keystrokes produced by auto-
backspacing or auto-replacement. Specify the new delay for n; for example, specify k10 to have a
10ms delay and k-1 to have no delay. The exact behavior of this option depends on which sending
mode is in effect:
SI (SendInput): Key-delay is ignored because a delay is not possible in this mode. The
exception to this is when SendInput is unavailable, in which case hotstrings revert to SendPlay
mode below (which does obey key-delay).
SP (SendPlay): A delay of length zero is the default, which for SendPlay is the same as -1 (no
delay). In this mode, the delay is actually a PressDuration rather than a delay between
keystrokes.
SE (SendEvent): A delay of length zero is the default. Zero is recommended for most purposes
since it is fast but still cooperates well with other processes (due to internally doing a Sleep 0).
Specify k-1 to have no delay at all, which is useful to make auto-replacements faster if your
CPU is frequently under heavy load. When set to -1, a script's process-priority becomes an
important factor in how fast it can send keystrokes. To raise a script's priority, use Process,
Priority,, High.
O: Omit the ending character of auto-replace hotstrings when the replacement is produced. This is
useful when you want a hotstring to be kept unambiguous by still requiring an ending character, but
don't actually want the ending character to be shown on the screen. For example, if :o:ar::aristocrat
is a hotstring, typing "ar" followed by the spacebar will produce "aristocrat" with no trailing space,
which allows you to make the word plural or possessive without having to backspace. Use O0 (the
letter O followed by a zero) to turn this option back off.
Pn: The priority of the hotstring (e.g. P1). This rarely-used option has no effect on auto-replace
hotstrings.
R: Send the replacement text raw; that is, exactly as it appears rather than translating {Enter} to an
ENTER keystroke, ^c to Control-C, etc. This option is put into effect automatically for hotstrings that
have a continuation section. Use R0 to turn this option back off.
SI or SP or SE [v1.0.43+]: Sets the method by which auto-replace hotstrings send their keystrokes.
These options are mutually exclusive: only one can be in effect at a time. The following describes each
option:
SI stands for SendInput, which became the default in v1.0.43+ because of its superior speed
and reliability. Another benefit is that like SendPlay below, SendInput postpones anything you
Hotstrings and Auto-replace (similar to AutoText and AutoCorrect)
25
type during a hotstring's auto-replacement text. This prevents your keystrokes from being
interspersed with those of the replacement. When SendInput is unavailable, hotstrings
automatically use SendPlay instead.
SP stands for SendPlay, which may allow hotstrings to work in a broader variety of games.
SE stands for SendEvent, which is the default in versions older than 1.0.43.
Z: This rarely-used option resets the hotstring recognizer after each triggering of the hotstring. In
other words, the script will begin waiting for an entirely new hotstring, eliminating from consideration
anything you previously typed. This can prevent unwanted triggerings of hotstrings. To illustrate,
consider the following hotstring:
:b0*?:11::
SendInput xx
return
Since the above lacks the Z option, typing 111 (three consecutive 1's) would trigger the hotstring
twice because the middle 1 is the last character of the first triggering but also the first character of the
second triggering. By adding the letter Z in front of b0, you would have to type four 1's instead of
three to trigger the hotstring twice. Use Z0 to turn this option back off.
Long Replacements
Hotstrings that produce a large amount of replacement text can be made more readable and
maintainable by using a continuation section. For example:
::text1::
(
Any text between the top and bottom parentheses is treated literally, including commas and
percent signs.
By default, the hard carriage return (Enter) between the previous line and this one is also
preserved.
By default, the indentation (tab) to the left of this line is preserved.

See continuation section for how to change these default behaviors.
)
The presence of a continuation section also causes the hotstring to default to raw mode. The only way
to override this special default is to specify the r0 option in each hotstring that has a continuation
section (e.g. :r0:text1::).
Context-sensitive Hotstrings
In v1.0.42+, the directives #IfWinActive/Exist can be used to make selected hotstrings context
sensitive. Such hotstrings send a different replacement, perform a different action, or do nothing at all
depending on the type of window that is active or exists. For example:
#IfWinActive ahk_class Notepad
::btw::This replacement text will appear only in Notepad.
#IfWinActive
::btw::This replacement text appears in windows other than Notepad.
AutoCorrect
The following script uses hotstrings to correct about 3800 common English misspellings on-the-fly. It
also includes a Win+H hotkey to make it easy to add more misspellings:
Printed Documentation
26
Download: wikipedia_autocorrect.ahk (100 KB)
Author: Jim Biancolo and Wikipedia's Lists of Common Misspellings
Remarks
Variable references such as %MyVar% are not currently supported within the replacement text. To
work around this, don't make such hotstrings auto-replace. Instead, use the SendInput command
beneath the abbreviation, followed by a line containing only the word Return.
To send an extra space or tab after a replacement, include the space or tab at the end of the
replacement but make the last character an accent/backtick (`). For example:
:*:btw::By the way `
In v1.0.42.03+, any click of the left or right mouse button will reset the hotstring recognizer. In other
words, the script will begin waiting for an entirely new hotstring, eliminating from consideration
anything you previously typed (if this is undesirable, specify the line #Hotstring NoMouse anywhere in
the script). This "reset upon mouse click" behavior is the default because each click typically moves
the text insertion point (caret) or sets keyboard focus to a new control/field. In such cases, it is
usually desirable to: 1) fire a hotstring even if it lacks the question mark option; 2) prevent a firing
when something you type after clicking the mouse accidentally forms a valid abbreviation with what
you typed before.
The built-in variable A_EndChar contains the ending character that you typed to trigger the most
recent non-auto-replace hotstring. If no ending character was required (due to the * option), it will be
blank. A_EndChar is useful when making hotstrings that use the Send command or whose behavior
should vary depending on which ending character you typed. To send the ending character itself, use
SendRaw %A_EndChar% (SendRaw is used because characters such as !{} would not be sent
correctly by the normal Send command).
Although commas, percent signs, and single-colons within hotstring definitions do not need to be
escaped, backticks and those semicolons having a space or tab to their left require it. See escape
sequences for a complete list.
Although the Send command's special characters such as {Enter} are supported in auto-replacement
text (unless the raw option is used), the hotstring abbreviations themselves do not use this. Instead,
specify `n for the ENTER key and `t (or a literal tab) for TAB (see escape sequences for a complete
list). For example, the hotstring :*:ab`t:: would be triggered when you type "ab" followed by a tab.
Spaces and tabs are treated literally within hotstring definitions. For example, the following would
produce two different results:
::btw::by the way
::btw:: by the way
Each hotstring abbreviation can be no more than 30 characters long. The program will warn you if this
length is exceeded. By contrast, the length of hotstring's replacement text is limited to about 5000
characters when the sending mode is at its default of SendInput. That limit can be increased to 16,383
characters by switching to one of the other sending modes. Furthermore, an unlimited amount of text
can be sent by using SendPlay %MyVariable% in the body of the hotstring.
The order in which hotstrings are defined determines their precedence with respect to each other. In
other words, if more than one hotstring matches something you type, only the one listed first in the
script will take effect. Related topic: context-sensitive hotstrings.
Any backspacing you do is taken into account for the purpose of detecting hotstrings. However, the
use of arrow keys, PageUp, PageDown, Home, and End to navigate within an editor will cause the
hotstring recognition process to reset. In other words, it will begin waiting for an entirely new
hotstring.
A hotstring may be typed even when the active window is ignoring your keystrokes. In other words,
the hotstring will still fire even though the triggering abbreviation is never visible. In addition, you
may still press the backspace key to undo the most recently typed keystroke (even though you can't
see the effect).
Hotstrings and Auto-replace (similar to AutoText and AutoCorrect)
27
It is possible to Gosub or Goto a hotstring label by including its first pair of colons (including any
option symbols) in front of its name. For example: Gosub ::xyz. However, jumping to a single-line
(auto-replace) hotstring will do nothing other than execute a return.
Although hotstrings are not monitored and will not be triggered during the course of an invisible Input
command, visible Inputs are capable of triggering them.
Hotstrings can never be triggered by keystrokes produced by any AutoHotkey script. This avoids the
possibility of an infinite loop where hotstrings trigger each other over and over.
The Input command is more flexible than hotstrings for certain purposes. For example, it allows your
keystrokes to be invisible in the active window (such as a game). It also supports non-character
ending keys such as Escape.
The keyboard hook is automatically used by any script that contains hotstrings.
Hotstrings behave identically to hotkeys in the following ways:
They are affected by the Suspend command.
They obey #MaxThreads and #MaxThreadsPerHotkey (but not #MaxThreadsBuffer).
Scripts containing hotstrings are automatically persistent.
Non-auto-replace hotstrings will create a new thread when launched. In addition, they will
update the built-in hotkey variables such as A_ThisHotkey.
Known limitation: On some systems in Java applications, hotstrings might interfere with the user's
ability to type diacritical letters (via dead keys). To work around this, Suspend can be turned on
temporarily (which disables all hotstrings).
Hotstring Helper
Andreas Borutta suggested the following script, which might be useful if you are a heavy user of
hotstrings. By pressing Win+H (or another hotkey of your choice), the currently selected text can be
turned into a hotstring. For example, if you have "by the way" selected in a word processor, pressing
Win+H will prompt you for its abbreviation (e.g. btw) and then add the new hotstring to the script. It
will then reload the script to activate the hotstring.
#h:: ; Win+H hotkey
; Get the text currently selected. The clipboard is used instead of
; "ControlGet Selected" because it works in a greater variety of editors
; (namely word processors). Save the current clipboard contents to be
; restored later. Although this handles only plain text, it seems better
; than nothing:
AutoTrim Off ; Retain any leading and trailing whitespace on the clipboard.
ClipboardOld = %ClipboardAll%
Clipboard = ; Must start off blank for detection to work.
Send ^c
ClipWait 1
if ErrorLevel ; ClipWait timed out.
return
; Replace CRLF and/or LF with `n for use in a "send-raw" hotstring:
; The same is done for any other characters that might otherwise
; be a problem in raw mode:
Printed Documentation
28
StringReplace, Hotstring, Clipboard, ``, ````, All ; Do this replacement first to avoid interfering with
the others below.
StringReplace, Hotstring, Hotstring, `r`n, ``r, All ; Using `r works better than `n in MS Word, etc.
StringReplace, Hotstring, Hotstring, `n, ``r, All
StringReplace, Hotstring, Hotstring, %A_Tab%, ``t, All
StringReplace, Hotstring, Hotstring, `;, ```;, All
Clipboard = %ClipboardOld% ; Restore previous contents of clipboard.
; This will move the InputBox's caret to a more friendly position:
SetTimer, MoveCaret, 10
; Show the InputBox, providing the default hotstring:
InputBox, Hotstring, New Hotstring, Type your abreviation at the indicated insertion point. You can
also edit the replacement text if you wish.`n`nExample entry: :R:btw`::by the way,,,,,,,,
:R:`::%Hotstring%
if ErrorLevel ; The user pressed Cancel.
return
IfInString, Hotstring, :R`:::
{
MsgBox You didn't provide an abbreviation. The hotstring has not been added.
return
}
; Otherwise, add the hotstring and reload the script:
FileAppend, `n%Hotstring%, %A_ScriptFullPath% ; Put a `n at the beginning in case file lacks a
blank line at its end.
Reload
Sleep 200 ; If successful, the reload will close this instance during the Sleep, so the line below will
never be reached.
MsgBox, 4,, The hotstring just added appears to be improperly formatted. Would you like to open the
script for editing? Note that the bad hotstring is at the bottom of the script.
IfMsgBox, Yes, Edit
return

MoveCaret:
IfWinNotActive, New Hotstring
return
; Otherwise, move the InputBox's insertion point to where the user will type the abbreviation.
Send {Home}{Right 3}
SetTimer, MoveCaret, Off
return

29
Remapping Keys and Buttons
Introduction
The feature described on this page is not supported on Windows 95/98/Me or for joysticks. See the
following alternate methods for them:
Windows 9x remapping
Joystick remapping
Limitation: AutoHotkey's remapping feature described below is generally not as pure and effective as
remapping directly via the Windows registry. For the advantages and disadvantages of each approach,
see registry remapping.
Remapping the Keyboard and Mouse [v1.0.40+]
The syntax for the built-in remapping feature is OriginKey::DestinationKey. For example, a script
consisting only of the following line would make the "a" key behave like the "b" key:
a::b
The above example does not alter the "b" key itself. The "b" key would continue to send the "b"
keystroke unless you remap it to something else as shown in the following example:
a::b
b::a
The examples above use lowercase, which is recommended for most purposes because it also remaps
the corresponding uppercase letters (that is, it will send uppercase when Capslock is "on" or the Shift
key is held down). By contrast, specifying an uppercase letter on the right side forces uppercase. For
example, the following line would produce an uppercase B when you type either "a" or "A" (as long as
Capslock is off):
a::B

Mouse remapping: To remap the mouse instead of the keyboard, use the same approach. For
example:
MButton::Shift Makes the middle button behave like the Shift key.
XButton1::LButton Makes the fourth mouse button behave like the left mouse button.
RAlt::RButton Makes the right Alt key behave like the right mouse button.

Other useful remappings:
Capslock::Ctrl Makes Capslock become a Control key.
XButton2::^LButton Makes the fifth mouse button (XButton2) produce Control-LeftClick.
RAlt::AppsKey
Makes the right Alt key become the Apps key (which is the key that
opens the context menu).
RCtrl::RWin Makes the right Control key become the right Windows key.
Ctrl::Alt
Makes both Control keys behave like an Alt key. However, see alt-tab
issues.
^x::^c
Makes Control-X produce Control-C. It also makes Control-Alt-X
produce Control-Alt-C, etc.
Printed Documentation
30
RWin::Return Disables the right Windows key by having it simply return.
You can try out any of these examples by copying them into a new text file such as "Remap.ahk", then
launching the file.
See the Key List for a complete list of key and mouse button names.
Remarks
The directives #IfWinActive/Exist can be used to make selected remappings active only in the
windows you specify. For example:
#IfWinActive ahk_class Notepad
a::b ; Makes the 'a' key send a 'b' key, but only in Notepad.
#IfWinActive ; This puts subsequent remappings and hotkeys in effect for all windows.
Remapping a key or button is "complete" in the following respects:
Holding down a modifier such as Control or Shift while typing the origin key will put that modifier into
effect for the destination key. For example, b::a would produce Control-A if you press Control-B.
Capslock generally affects remapped keys in the same way as normal keys.
The destination key or button is held down for as long as you continue to hold down the origin key.
However, some games do not support remapping; in such cases, the keyboard and mouse will behave
as though not remapped.
Remapped keys will auto-repeat while being held down (except keys remapped to become mouse
buttons).
Although a remapped key can trigger normal hotkeys, it cannot trigger mouse hotkeys or hook
hotkeys (use ListHotkeys to discover which hotkeys are "hook"). For example, if the remapping a::b is
in effect, pressing Ctrl-Alt-A would trigger the ^!b hotkey only if ^!b is not a hook hotkey. If ^!b is a
hook hotkey, you can define ^!a as a hotkey if you want Ctrl-Alt-A to perform the same action as Ctrl-
Alt-B. For example:
a::b
^!a::
^!b::
ToolTip You pressed %A_ThisHotkey%.
return
If SendMode is used in the auto-execute section (top part of the script), it affects all remappings.
However, since remapping uses Send {Blind} and since the SendPlay mode does not fully support
{Blind}, some remappings might not function properly in SendPlay mode (especially Control, Shift,
Alt, and Win). To work around this, avoid SendPlay in auto-execute section when you have
remappings; then use the command SendPlay vs. Send in other places throughout the script.
Alternatively, you could translate your remappings into hotkeys (as described below) that explicitly
call SendEvent vs. Send.
When a script is launched, each remapping is translated into a pair of hotkeys. For example, a script
containing a::b actually contains the following two hotkeys instead:
*a::
SetKeyDelay -1 ; If the destination key is a mouse button, SetMouseDelay is used instead.
Send {Blind}{b DownTemp} ; DownTemp is like Down except that other Send commands in
the script won't assume "b" should stay down during their Send.
return

Remapping Keys and Buttons
31
*a up::
SetKeyDelay -1 ; See note below for why press-duration is not specified with either of these
SetKeyDelays.
Send {Blind}{b Up}
return
However, the above hotkeys vary under the following circumstances:
1. When the source key is LCtrl and the destination key is an Alt key, the line Send {Blind}{LAlt
DownTemp} is replaced by Send {Blind}{LCtrl Up}{LAlt DownTemp}. The same is true if the
source is RCtrl, except that {RCtrl up} is used.
When a keyboard key is being remapped to become a mouse button (e.g. RCtrl::RButton), the
hotkeys above use SetMouseDelay in place of SetKeyDelay. In addition, the first hotkey above is
replaced by the following, which prevents the keyboard's auto-repeat feature from generating
repeated mouse clicks:
*RCtrl::
SetMouseDelay -1
if not GetKeyState("RButton") ; i.e. the right mouse button isn't down yet.
Send {Blind}{RButton DownTemp}
return
Note that SetKeyDelay's second parameter (press duration) is omitted in the hotkeys above. This is
because press-duration does not apply to down-only or up-only events such as {b down} and {b up}.
However, it does apply to changes in the state of the Shift/Ctrl/Alt/Win keys, which affects
remappings such as a::B or a::^b. Consequently, any press-duration a script puts into effect via its
auto-execute section will apply to all such remappings.
Since remappings are translated into hotkeys as described above, the Suspend command affects
them. Similarly, the Hotkey command can disable or modify a remapping. For example, the following
two commands would disable the remapping a::b.
Hotkey, *a, off
Hotkey, *a up, off
Alt-tab issues: If you remap a key or mouse button to become an Alt key, that key will probably not
be able to alt-tab properly. A possible work-around is to add the hotkey *Tab::Send {Blind}{Tab} --
but be aware that it will likely interfere with using the real Alt key to alt-tab. Therefore, it should be
used only when you alt-tab solely by means of remapped keys and/or alt-tab hotkeys.
In addition to the keys and mouse buttons on the Key List page, the source key may also be a virtual
key (VKnn) or scan code (SCnnn) as described on the special keys page. The same is true for the
destination key except that it may optionally specify a scan code after the virtual key. For example,
sc01e::vk42sc030 is equivalent to a::b on most keyboard layouts.
To disable a key rather than remapping it, make it a hotkey that simply returns. For example,
F1::return would disable the F1 key.
The following keys are not supported by the built-in remapping method:
The mouse wheel (WheelUp and WheelDown).
Pause and Break as destination keys (since they match the names of commands).
A percent sign (%) as a destination key (use the VK/SC method instead).
"Return" as a destination key (use "Enter" instead).
Printed Documentation
32
Moving the Mouse Cursor via the Keyboard
The keyboard can be used to move the mouse cursor as demonstrated by the fully-featured Keyboard-
To-Mouse script. Since that script offers smooth cursor movement, acceleration, and other features, it
is the recommended approach if you plan to do a lot of mousing with the keyboard. By contrast, the
following example is a simpler demonstration:
*#up::MouseMove, 0, -10, 0, R ; Win+UpArrow hotkey => Move cursor upward
*#Down::MouseMove, 0, 10, 0, R ; Win+DownArrow => Move cursor downward
*#Left::MouseMove, -10, 0, 0, R ; Win+LeftArrow => Move cursor to the left
*#Right::MouseMove, 10, 0, 0, R ; Win+RightArrow => Move cursor to the right

*<#RCtrl:: ; LeftWin + RightControl => Left-click (hold down Control/Shift to Control-Click or
Shift-Click).
SendEvent {Blind}{LButton down}
KeyWait RCtrl ; Prevents keyboard auto-repeat from repeating the mouse click.
SendEvent {Blind}{LButton up}
return

*<#AppsKey:: ; LeftWin + AppsKey => Right-click
SendEvent {Blind}{RButton down}
KeyWait AppsKey ; Prevents keyboard auto-repeat from repeating the mouse click.
SendEvent {Blind}{RButton up}
return
Remapping via the Registry's " Scancode Map"
Advantages:
Registry remapping is generally more pure and effective than AutoHotkey's remapping. For
example, it works in a broader variety of games, it has no known alt-tab issues, and it is
capable of firing AutoHotkey's hook hotkeys (whereas AutoHotkey's remapping requires a
workaround).
If you choose to make the registry entries manually (explained below), absolutely no external
software is needed to remap your keyboard. Even if you use KeyTweak to make the registry
entries for you, KeyTweak does not need to stay running all the time (unlike AutoHotkey).
Disadvantages:
Registry remapping is relatively permanent: a reboot is required to undo the changes or put new ones
into effect.
Its effect is global: it cannot create remappings specific to a particular user, application, or locale.
It cannot send keystrokes that are modified by Shift, Control, Alt, or AltGr. For example, it cannot
remap a lowercase character to an uppercase one.
It is not supported on Windows 95/98/Me (AutoHotkey can do some limited Win9x
remapping).
It supports only the keyboard (AutoHotkey has mouse remapping and some limited joystick
remapping).
How to Apply Changes to the Registry: There are at least two methods to remap keys via the
registry:
Remapping Keys and Buttons
33
1. Use a program like KeyTweak (freeware) to visually remap your keys. It will change the
registry for you.
2. Remap keys manually by creating a .reg file (plain text) and loading it into the registry. This is
demonstrated at http://www.autohotkey.com/forum/post-56216.html#56216
Remapping Method for Windows 95/98/Me
The recommended method is to use Send and KeyWait. For example, the following hotkey makes the
'A' key become the left-arrow key:
a::
Send {Left down} ; Hold down the left-arrow key.
KeyWait a ; Wait for the user to release the key.
Send {Left up} ; Release the left-arrow key.
return
Related Topics
List of keys and mouse buttons
GetKeyState
Remapping a joystick

35
List of Keys, Mouse Buttons, and Joystick Controls
Mouse (mouse hotkeys require Windows NT/2000/XP or later)
LButton - the left mouse button
RButton - the right mouse button
MButton - the middle or wheel mouse button
WheelDown - this is equivalent to rotating the mouse wheel down (toward you)
WheelUp - the opposite of the above. When WheelDown/Up are used as hotkeys, A_EventInfo
contains the number of turns/notches.
Supported only in Windows 2000/XP or later:
XButton1 - a button that appears only on certain mice
XButton2 - a button that appears only on certain mice
Keyboard
Note: The names of the letter and number keys are the same as that single letter or digit.
For example: b is the "b" key and 5 is the "5" key.
Space - the spacebar
Tab
Enter (or Return)
Escape (or Esc)
Backspace (or BS)
Delete (or Del)
Insert (or Ins)
Home
End
PgUp
PgDn
Up
Down
Left
Right
ScrollLock
CapsLock
NumLock
NumpadDiv - the slash key
NumpadMult - the asterisk key
NumpadAdd - the plus key
NumpadSub - the minus key
NumpadEnter - the Enter key
The following keys are used when Numlock is OFF:
NumpadDel
NumpadIns
NumpadClear - same physical key as Numpad5 on most keyboards
NumpadUp
NumpadDown
NumpadLeft
NumpadRight
NumpadHome
NumpadEnd
NumpadPgUp
NumpadPgDn
Printed Documentation
36
The following keys are used when Numlock is ON:
Numpad0
Numpad1
Numpad2
Numpad3
Numpad4
Numpad5
Numpad6
Numpad7
Numpad8
Numpad9
NumpadDot - the decimal point (period) key
F1 through F24 - The 12 or more function keys at the top of most keyboards.
AppsKey - this is the key that invokes the right-click context menu.
LWin - the left windows key
RWin - the right windows key. Note: unlike Control/Alt/Shift, there is no generic/neutral "Win" key
because the OS does not support it.
Control (or Ctrl)
Alt
Shift
Note: For the most part, these next 6 keys are not supported by Windows 95/98/Me. Use the above
instead:
LControl (or LCtrl) - the left control key
RControl (or RCtrl) - the right control key
LShift
RShift
LAlt - the left Alt key
RAlt - Note: If your keyboard layout has AltGr instead of RAlt, you can probably use it as a hotkey
prefix via <^>! as described here. In addition, "LControl & RAlt::" would make AltGr itself into a
hotkey.
PrintScreen
CtrlBreak
Pause
Break -- Since this is synonymous with Pause, use ^CtrlBreak in hotkeys instead of ^Pause or
^Break.
Help - this probably doesn't exist on most keyboards. It's usually not the same as F1.
Sleep - note that the sleep key on some keyboards might not work with this.
The following exist only on Multimedia or Internet keyboards that have extra buttons or keys:
Browser_Back
Browser_Forward
Browser_Refresh
Browser_Stop
Browser_Search
Browser_Favorites
Browser_Home
Volume_Mute
Volume_Down
Volume_Up
Media_Next
Media_Prev
Media_Stop
Media_Play_Pause
Launch_Mail
Launch_Media
List of Keys and Mouse/Joystick Buttons for Hotkeys and Macros
37
Launch_App1
Launch_App2
SCnnn (where nnn is the scan code of a key) - Recognizes unusual keys not mentioned above. See
Special Keys for details.
VKnn (where nn is the hexadecimal virtual key code of a key) - Although this rarely-used method is
supported in all versions, only in v1.0.38.02+ does it prevent certain types of hotkeys from requiring
the keyboard hook. For example, the following hotkey does not use the keyboard hook, but as a side-
effect it is triggered by pressing either Home or NumpadHome: ^VK24::MsgBox You pressed Home or
NumpadHome while holding down Control.
Joystick
Joy1 through Joy32: The buttons of the joystick. To help determine the button numbers for your
joystick, use this test script. Note that hotkey prefix symbols such as ^ (control) and + (shift) are not
supported (though GetKeyState can be used as a substitute). Also note that the pressing of joystick
buttons always "passes through" to the active window if that window is designed to detect the
pressing of joystick buttons.
Although the following Joystick control names cannot be used as hotkeys, they can be used with
GetKeyState:
JoyX, JoyY, and JoyZ: The X (horizontal), Y (vertical), and Z (altitude/depth) axes of the joystick.
JoyR: The rudder or 4th axis of the joystick.
JoyU and JoyV: The 5th and 6th axes of the joystick.
JoyPOV: The point-of-view (hat) control.
JoyName: The name of the joystick or its driver.
JoyButtons: The number of buttons supported by the joystick (not always accurate).
JoyAxes: The number of axes supported by the joystick.
JoyInfo: Provides a string consisting of zero or more of the following letters to indicate the joystick's
capabilities: Z (has Z axis), R (has R axis), U (has U axis), V (has V axis), P (has POV control), D (the
POV control has a limited number of discrete/distinct settings), C (the POV control is continous/fine).
Example string: ZRUVPD
Multiple Joysticks: If the computer has more than one and you want to use one beyond the first,
include the joystick number in front of the control name. For example, 2joy1 is the second joystick's
first button.
Note: If you have trouble getting a script to recognize your joystick, one person reported needing to
specify a joystick number other than 1 even though only a single joystick was present. It is unclear
how this situation arises or whether it is normal, but experimenting with the joystick number in the
joystick test script can help determine if this applies to your system.
See Also:
Joystick remapping: methods of sending keystrokes and mouse clicks with a joystick.
Joystick-To-Mouse script: using a joystick as a mouse.
Hand-held Remote Controls
Respond to signals from hand-held remote controls via the WinLIRC client script.
Special Keys
If your keyboard or mouse has a key not listed above, you might still be able to make it a hotkey by
using the following steps (requires Windows XP/2000/NT or later):
1. Ensure that at least one script is running that is using the keyboard hook. You can tell if a
script has the keyboard hook by opening its main window and selecting "View->Key history"
from the menu bar.
Double-click that script's tray icon to open its main window.
Press one of the "mystery keys" on your keyboard.
Select the menu item "View->Key history"
Printed Documentation
38
Scroll down to the bottom of the page. Somewhere near the bottom are the key-down and key-up
events for your key. NOTE: Some keys do not generate events and thus will not be visible here. If this
is the case, you cannot directly make that particular key a hotkey because your keyboard driver or
hardware handles it at a level too low for AutoHotkey to access. For possible solutions, see further
below.
2. If your key is detectible, make a note of the 3-digit hexadecimal value in the second column of
the list (e.g. 159).
To define this key as a hotkey, follow this example:
SC159:: ; Replace 159 with your key's value.
MsgBox, %A_ThisHotKey% was pressed.
return
Reverse direction: To remap some other key to become a "mystery key", follow this example:
; Replace 159 with the value discovered above. Replace FF (if needed) with the
; key's virtual key, which can be discovered in the first column of the Key History screen.
#c::Send {vkFFsc159}
Alternate solutions: If your key or mouse button is not detectible by the Key History screen, one of
the following might help:
1. Reconfigure the software that came with your mouse or keyboard (sometimes accessible in the Control Panel or Start Menu) to have the "mystery key"
send some other keystroke. Such a keystroke can then be defined as a hotkey in a script. For example, if you configure a mystery key to send Control+F1,
you can then indirectly make that key as a hotkey by using ^F1:: in a script.
2. Try searching the forum or asking for help there. There may be ways to detect certain keys and buttons using techniques such as DllCall, OnMessage, and
RegisterRawInputDevices.
3. The following is a last resort and generally should be attempted only in desperation. This is because the chance of success is low and it may cause
unwanted side-effects that are difficult to undo:
Disable or remove any extra software that came with your keyboard or mouse or change its driver to a more standard one such as the one built into the
OS. This assumes there is such a driver for your particular keyboard or mouse and that you can live without the features provided by its custom driver and
software.

39
Scripts
Table of Contents
Introduction
The Top of the Script (the Auto-execute Section): This portion executes automatically when
the script starts.
Escape Sequences: When to use `% and `, to indicate a literal percent sign or comma.
Comments in Scripts: The use of semicolon and the symbols /*...*/ to add remarks to a script.
Splitting a Long Line into a Series of Shorter Ones: This can improve a script's readability and
maintainability.
Convert a Script to an EXE (ahk2exe): Convert a .ahk script into a .exe file that can run on
any PC.
Passing Command Line Parameters to a Script: The variables %1%, %2%, etc. contain the
incoming parameters.
Debugging a Script: How to find the flaws in a misbehaving script.
Portability of AutoHotkey.exe: Having a copy of AutoHotkey.exe is enough to execute any .ahk
file.
Installer Options: How to do unattended/silent installations or uninstallations.
Introduction
Each script is a plain text file containing lines to be executed by the program (AutoHotkey.exe). A
script may also contain hotkeys and hotstrings, or even consist entirely of them. However, in the
absence of hotkeys and hotstrings, a script will perform its commands sequentially from top to bottom
the moment it is launched.
The program loads the script into memory line by line, and each line may be up to 16,383 characters
long. During loading, the script is optimized and validated. Any syntax errors will be displayed, and
they must be corrected before the script can run.
The Top of the Script (the Auto-execute Section)
After the script has been loaded, it begins executing at the top line, continuing until a Return, Exit,
hotkey/hotstring label, or the physical end of the script is encountered (whichever comes first). This
top portion of the script is referred to as the auto-execute section.
A script that is not persistent and that lacks hotkeys, hotstrings, OnMessage, and GUI will terminate
after the auto-execute section has completed. Otherwise, it will stay running in an idle state,
responding to events such as hotkeys, hotstrings, GUI events, custom menu items, and timers.
Every thread launched by a hotkey, hotstring, menu item, GUI event, or timer starts off fresh with the
default values for the following attributes as set in the auto-execute section. If unset, the standard
defaults will apply (as documented on each of the following pages): DetectHiddenWindows,
DetectHiddenText, SetTitleMatchMode, SetBatchLines, SendMode, SetKeyDelay, SetMouseDelay,
SetWinDelay, SetControlDelay, SetDefaultMouseSpeed, CoordMode, SetStoreCapslockMode, AutoTrim,
SetFormat, StringCaseSense, Thread, and Critical.
If the auto-execute section takes a long time to complete (or never completes), the default values for
the above settings will be put into effect after 100 milliseconds. Thus, it's usually best to make any
desired changes to the defaults at the top of scripts that contain hotkeys, hotstrings, timers, or
custom menu items. Also note that each thread retains its own collection of the above settings.
Changes made to those settings will not affect other threads.
Printed Documentation
40
Escape Sequences
AutoHotkey's default escape character is accent/backtick (`), which is at the upper left corner of most
English keyboards. Using this character rather than backslash avoids the need for double blackslashes
in file paths.
Since commas and percent signs have special meaning in the AutoHotkey language, use `, to specify
a literal comma and `% to specify a literal percent sign. One of the exceptions to this is MsgBox,
which does not require commas to be escaped. Another exception is commas in the last parameter of
any command: they do not need to be escaped. See #EscapeChar for a complete list of escape
sequences.
Certain special characters are also produced by means of an escape sequence. The most common
ones are `t (tab), `n (linefeed), and `r (carriage return).
Tip: The first comma of any command may be omitted. For example:
MsgBox This is ok.
MsgBox, This is ok too (it has an explicit comma).
Comments in Scripts
Scripts can be commented by using a semicolon at the beginning of a line. For example:
; This entire line is a comment.
Comments may also be added to the end of a command, in which case the semicolon must have at
least one space or tab to its left. For example:
Run Notepad ; This is a comment on the same line as a command.
In addition, the /* and */ symbols can be used to comment out an entire section, but only if the
symbols appear at the beginning of a line as in this example:
/*
MsgBox, This line is commented out (disabled).
MsgBox, This one too.
*/
Since comments are ignored when a script is launched, they do not impact performance or memory
utilization.
The default comment character (semicolon) can be changed to some other character or string via
#CommentFlag.
Splitting a Long Line into a Series of Shorter Ones
Long lines can be divided up into a collection of smaller ones to improve readability and
maintainability. This does not reduce performance because split lines are merged in memory the
moment the script launches.
Method #1 [v1.0.35.03+]: A line that starts with "and", "or", ||, &&, a comma, or a period is
automatically merged with the line directly above it. In the following example, the second line is
merged with the first because it begins with a comma:
FileAppend, This is the text to append.`n ; A comment is allowed here.
, %A_ProgramFiles%\SomeApplication\LogFile.txt ; Comment.
Similarly, the following lines would get merged into a single line because the last two start with "and"
or "or":
if (Color = "Red" or Color = "Green" or Color = "Blue" ; Comment.
or Color = "Black" or Color = "Gray" or Color = "White") ; Comment.
AutoHotkey Scripts and Macros
41
and ProductIsAvailableInColor(Product, Color) ; Comment.
Although the indentation used in the examples above is optional, it might improve clarity by indicating
which lines belong to ones above them. Also, it is not necessary to include an extra space after each
of the first two lines; the program does this automatically. Finally, blank lines or comments may be
added between or at the end of any of the lines in the above examples.
Method #2: This method should be used to merge a large number of lines or when the lines are not
suitable for Method #1. Although this method is especially useful for auto-replace hotstrings, it can
also be used with any command or expression. For example:
; EXAMPLE #1:
Var =
(
Line 1 of the text.
Line 2 of the text. By default, a linefeed (`n) is present between lines.
)

; EXAMPLE #2:
FileAppend, ; The comma is required in this case.
(
A line of text.
By default, the hard carriage return (Enter) between the previous line and this one will be
written to the file as a linefeed (`n).
By default, the tab to the left of this line will also be written to the file (the same is true for
spaces).
By default, variable references such as %Var% are resolved to the variable's contents.
), C:\My File.txt
In the examples above, a series of lines is bounded at the top and bottom by a pair of parentheses.
This is known as a continuation section. Notice that the bottom line contains FileAppend's last
parameter after the closing parenthesis. This practice is optional; it is done in cases like this so that
the comma will be seen as a parameter-delimiter rather than a literal comma.
The default behavior of a continuation section can be overridden by including one or more of the
following options to the right of the section's opening parenthesis. If more than one option is present,
separate each one from the previous with a space. For example: ( LTrim Join| %
Join: Specifies how lines should be connected together. If this option is omitted, each line except the
last will be followed by a linefeed character (`n). If the word Join is specified by itself, lines are
connected directly to each other without any characters in between. Otherwise, the word Join should
be followed immediately by as many as 15 characters. For example, Join`s would insert a space after
each line except the last (`s indicates a literal space -- it is a special escape sequence recognized only
by Join). Another example is Join`r`n, which inserts CR+LF between lines. Similarly, Join| inserts a
pipe between lines. To have the final line in the section also ended by a join-string, include a blank
line immediately above the section's closing parenthesis.
LTrim: Omits spaces and tabs at the beginning of each line. This is primarily used to allow the
continuation section to be indented. In v1.0.35.06+, this option may be turned on for multiple
continuation sections by specifying #LTrim on a line by itself. #LTrim is positional: it affects all
continuation sections physically beneath it. The setting may be turned off via #LTrim Off.
RTrim0 (RTrim followed by a zero): Turns off the omission of spaces and tabs from the end of each
line.
Printed Documentation
42
% (percent sign): Treats percent signs as literal rather than as variable references. This avoids the
need to escape each percent sign to make it literal. This option is not needed in places where percent
signs are already literal, such as auto-replace hotstrings.
, (comma): Treats commas as delimiters rather than as literal commas. This rarely-used option is
necessary only for the commas between command parameters because in function calls, the type of
comma does not matter. Also, this option transforms only those commas that actually delimit
parameters. In other words, once the command's final parameter is reached (or there are no
parameters), subsequent commas are treated as literal commas regardless of this option.
` (accent): Treats each backtick character literally rather than as an escape character. Specifying this
option also prevents commas and percent signs from being explicitly and individually escaped. In
addition, it prevents the translation of any explicitly specified escape sequences such as `r and `t.
Remarks
Escape sequences such as `n (linefeed) and `t (tab) are supported inside the continuation section
except when the accent (`) option has been specified.
Comments (semicolon and /*..*/) are not supported within the interior of a continuation section
because they are seen as literal text. However, comments can be included on the bottom and top lines
of the section. For example:
FileAppend, ; Comment.
; Comments are supported here in v1.0.35.06+.
( LTrim Join ; Comment.
; This is not a comment; it is literal.
), C:\File.txt ; Comment.
As a consequence of the above, semicolons never need to be escaped within a continuation section.
A continuation section cannot produce a line whose total length is greater than 16,383 characters (if it
tries, the program will alert you the moment the script is launched). One way to work around this is to
do a series of concatenatations into a variable. For example:
Var =
(
...
)
Var = %Var%`n ; Add more text to the variable via another continuation section.
(
...
)
FileAppend, %Var%, C:\My File.txt
Since a closing parenthesis indicates the end of a continuation section, to have a line start with literal
closing parenthesis, precede it with an accent/backtick: `).
A continuation section can be immediately followed by a line containing the open-parenthesis of
another continuation section. This allows the options mentioned above to be varied during the course
of building a single line.
Known limitations: 1) The piecemeal construction of a continuation section by means of #Include is
not supported; 2) The directives #DerefChar, #Delimiter, and #EscapeChar are not obeyed by
continutation sections; only the default characters for each of these are recognized.
AutoHotkey Scripts and Macros
43
Convert a Script to an EXE (ahk2exe)
A script compiler (courtesy of Jonathan Bennett's AutoIt v3 source code) is included with the program.
AutoIt v2 scripts are not supported, so if necessary, first auto-convert your .aut file to .ahk.
Once a script is compiled, it becomes a standalone executable; that is, it can be used even on
machines where AutoHotkey is not installed (and such EXEs can be distributed or sold with no
restrictions). The compilation process compresses and encrypts all of the following: the script, any
files it includes, and any files it has incorporated via the FileInstall command.
Compiling does not improve the performance of a script. In fact, a compiled script is slightly slower to
launch because it must first be decrypted and decompressed into memory, after which it is optimized
just like a normal script.
Ahk2Exe can be used in the following ways:
1. GUI Interface: Run the "Convert .ahk to .exe" item in the Start Menu.
2. Right-click: Within an open Explorer window, you can right-click any .ahk file and select
"Compile Script" (only available if the script compiler option was chosen when AutoHotkey was
installed). This will create an EXE file of the same base filename as the script, which will
appear after a short time in the same directory. Note: The EXE file will be produced using the
same custom icon and compression level that was last used by Method #1 above and it will
not have a password.
3. Command Line: The compiler can be run from the command line with the following
parameters:
Ahk2exe.exe /in MyScript.ahk [/out MyScript.exe][/icon MyIcon.ico][/pass password]
Parameters containing spaces should be enclosed in double quotes. If the "out" file is omitted,
the EXE will have the same base filename as the script itself.
Notes:
A password should be specified if you plan to distribute your EXE and don't want anyone to be able to
view the source code of your script. Long, elaborate passwords are much more secure than short ones
(a password may be up to 64 characters long).
The commands #NoTrayIcon and "Menu, Tray, ShowMainWindow" affect the behavior of
compiled scripts.
An EXE can be decompiled to retrieve the original script by downloading Exe2Ahk (this utility
should be run from the command prompt). However, any comments originally present
(semicolon or /**/) will be lost.
Compiled scripts can be reduced in size by about 20 KB by placing this smaller version of the
AutoHotkeySC.bin file in your AutoHotkey\Compiler folder (overwriting the existing file of the
same name). Any compiled script produced in this fashion will be dependent on MSVCRT.dll.
Although this DLL is always present on Windows 2000/XP or later, older operating systems do
not necessarily have it.
Custom version info (as seen in Explorer's file-properties dialog) can be added to your compiled scripts
by using a utility such as Resource Hacker (freeware) to edit the file "AutoHotkeySC.bin". This file is
contained in the "compiler" subfolder where AutoHotkey was installed. Note: Resource Hacker will
corrupt compiled scripts, which is why only the AutoHotkeySC.bin file should be edited.
The method above can also be used to change existing icons or add new ones to all compiled scripts.
The built-in variable A_IsCompiled contains 1 if the script is running in compiled form. Otherwise, it is
blank.
If you do not wish your compiled scripts to be compressed, delete or rename the file "upx.exe" in
AutoHotkey's "Compiler" folder.
When parameters are passed to Ahk2Exe, a message indicating the success or failure of the compiling
process is written to stdout. Although the message will not appear at the command prompt, it can be
"caught" by means such as redirecting output to a file. [v1.0.43+]
Printed Documentation
44
Passing Command Line Parameters to a Script
Scripts support command line parameters. The format is:
AutoHotkey.exe [Switches] [Script Filename] [Script Parameters]
And for compiled scripts, the format is:
CompiledScript.exe [Switches] [Script Parameters]
Switches: Zero or more of the following:
/f or /force -- Launch unconditionally, skipping any warning dialogs.
/r or /restart -- Indicate that the script is being restarted (this is also used by the Reload command,
internally).
/ErrorStdOut -- Send syntax errors that prevent a script from launching to stdout rather than
displaying a dialog. See #ErrorStdOut for details.
Script Filename: This can be omitted if there are no Script Parameters. If omitted, it will run (or
prompt you to create) AutoHotkey.ini in the current working directory.
Script Parameters: The string(s) you want to pass into the script, with each separated from the next
by a space. Any parameter that contains spaces should be enclosed in quotation marks. A literal
quotation mark may be passed in by preceding it with a backslash (\"). Consequently, any trailing
slash in a quoted parameter (such as "C:\My Documents\") is treated as a literal quotation mark (that
is, the script would receive the string C:\My Documents"). To remove such quotes, use StringReplace,
1, 1, ",, All
The script sees incoming parameters as the variables %1%, %2%, and so on. In addition, %0%
contains the number of parameters passed (0 if none). The following example exits the script when
too few parameters are passed to it:
if 0 < 3 ; The left side of a non-expression if-statement is always the name of a variable.
{
MsgBox This script requires at least 3 incoming parameters but it only received %0%.
ExitApp
}
If the number of parameters passed into a script varies (perhaps due to the user dragging and
dropping a set of files onto a script), the following example can be used to extract them one by one:
Loop, %0% ; For each parameter:
{
param := %A_Index% ; Fetch the contents of the variable whose name is contained in
A_Index.
MsgBox, 4,, Parameter number %A_Index% is %param%. Continue?
IfMsgBox, No
break
}
If the parameters are file names, the following example can be used to convert them to their case-
corrected long names (as stored in the file system), including complete/absolute path:
Loop %0% ; For each parameter (or file dropped onto a script):
{
GivenPath := %A_Index% ; Fetch the contents of the variable whose name is contained in
A_Index.
Loop %GivenPath%
AutoHotkey Scripts and Macros
45
LongPath = %A_LoopFileLongPath%
MsgBox The case-corrected long path name of file`n%GivenPath%`nis:`n%LongPath%
}
Known limitation: dragging files onto a .ahk script may fail to work properly if 8-dot-3 (short) names
have been turned off in an NTFS file system. One work-around is to compile the script then drag the
files onto the resulting EXE.
Debugging a Script
Commands such as ListVars and Pause can help you debug a script. For example, the following two
lines, when temporarily inserted at carefully chosen positions, create "break points" in the script:
ListVars
Pause
When the script encounters these two lines, it will display the current contents of all variables for your
inspection. When you're ready to resume, un-pause the script via the File or Tray menu. The script will
then continue until reaching the next "break point" (if any).
It is generally best to insert these "break points" at positions where the active window does not matter
to the script, such as immediately before a WinActivate command. This allows the script to properly
resume operation when you un-pause it.
The following commands are also useful for debugging: ListLines, KeyHistory, and OutputDebug.
Portability of AutoHotkey.exe
The file AutoHotkey.exe is all that is needed to launch any .ahk script. The only exception is Windows
NT4, which requires a copy of psapi.dll (from the AutoHotkey folder) for any script that uses the
Process command.
Installer Options
To silently install AutoHotkey into the default directory (which is the same directory displayed by non-
silent mode), pass the parameter /S to the installer (/S must be capitalized). For example:
AutoHotkey104307_Install.exe /S
A directory other than the default may be specified via the /D parameter (in the absence of /S, this
changes the default directory displayed by the installer). For example:
AutoHotkey104307_Install.exe /S /D=C:\Program Files\AutoHotkey
To silently uninstall AutoHotkey, pass the parameter /S to the uninstaller. For example:
"C:\Program Files\AutoHotkey\uninst.exe" /S
Script Showcase
See this page for some useful scripts.

47
Variables and Expressions
Table of Contents
Introduction to Variables
Expressions
Operators in Expressions
Built-in Variables
Environment Variables vs. Normal Variables
Variable Capacity and Memory
Introduction to Variables
Variable types: AutoHotkey has no explicitly defined variable types; all variables are stored as
character strings. However, a variable containing only digits (with an optional decimal point) is
automatically converted to a number when a math operation or comparison requires it. Conversely,
the result of a math operation is converted back to a string when it needs to be stored in a variable.
Variable scope and declarations: With the exception of local variables in functions, all variables are
global; that is, their contents may be read or altered by any part of the script. In addition, variables
are not declared; they come into existence simply by using them (and each variable starts off
empty/blank).
Variable names: Variable names are not case sensitive (for example, CurrentDate is the same as
currentdate). Variable names may be up to 254 characters long and may consist of letters, numbers
and the following punctuation: # _ @ $ ? [ ]
Due to style conventions, it is generally better to name your variables using only letters, numbers,
and the underscore character (for example: CursorPosition, Total_Items, and entry_is_valid). This
style allows people familiar with other computer languages to understand your scripts more easily.
Also, if you use the same conventions in AutoHotkey as you use in other languages, you may find it
easier to re-read your own scripts.
Although a variable name may consist entirely of digits, this is generally used only for incoming
command line parameters. Such numeric names cannot be used in expressions because they would be
seen as numbers rather than variables.
Since the words AND, OR, and NOT are used as operators in expressions, generally they should not be
used as variable names. Using such names in an expression would prevent proper evaluation. In
addition, a line such as OR = 123 would be interpreted as a continuation line rather than an
assignment.
Storing values in variables: To store a string or number in a variable, there are two methods:
traditional and expression. The traditional method uses the equal sign operator (=) to assign
unquoted literal strings or variables enclosed in percent signs. For example:
MyNumber = 123
MyString = This is a literal string.
CopyOfVar = %Var% ; With the = operator, percent signs are required to retrieve a variable's
contents.
By contrast, the expression method uses the colon-equal operator (:=) to store numbers, quoted
strings, and other types of expressions. The following examples are functionally identical to the
previous ones:
MyNumber := 123
MyString := "This is a literal string."
Printed Documentation
48
CopyOfVar := Var ; Unlike its counterpart in the previous section, percent signs are not used
with the := operator.
The latter method is preferred by many due to its greater clarity, and because it supports an
expression syntax nearly identical to that in many other languages.
You may have guessed from the above that there are two methods to erase the contents of a variable
(that is, to make it blank):
MyVar =
MyVar := ""
The empty pair of quotes above should be used only with the := operator because if it were used with
the = operator, it would store two literal quote-characters inside the variable.
Retrieving the contents of variables: Like the two methods of storing values, there are also two
methods for retrieving them: traditional and expression. The traditional method requires that each
variable name be enclosed in percent signs to retrieve its contents. For example:
CopyOfVar = %Var%
MsgBox The value in the variable named Var is %Var%.
By contrast, the expression method omits the percent signs around variable names, but encloses
literal strings in quotes. Thus, the following are the expression equivalents of the previous examples:
CopyOfVar := Var
MsgBox % "The value in the variable named Var is " . Var . "."
In the MsgBox line above, a percent sign and a space is used to change the parameter from traditional
to expression mode. This is necessary because the traditional method is used by default by all
commands (except where otherwise documented). However, certain parameters of some commands
are documented as accepting expressions, in which case the leading percent sign is permitted but not
necessary. For example, all of the following are effectively identical because Sleep's first parameter is
expression-capable:
Sleep MillisecondsToWait
Sleep %MillisecondsToWait%
Sleep % MillisecondsToWait
Comparing variables: Please read the expressions section below for important notes about the
different kinds of comparisons, especially about when to use parentheses.
Expressions
Expressions are used to perform one or more operations upon a series of variables, literal strings,
and/or literal numbers.
Variable names in an expression are not enclosed in percent signs (except for arrays and other double
references). Consequently, literal strings must be enclosed in double quotes to distinguish them from
variables. For example:
if (CurrentSetting > 100 or FoundColor <> "Blue")
MsgBox The setting is too high or the wrong color is present.
In the example above, "Blue" appears in quotes because it is a literal string. To include an actual
quote-character inside a literal string, specify two consecutive quotes as shown twice in this example:
"She said, ""An apple a day."""
Important: An if-statement that contains an expression is differentiated from a traditional if-
statement such as If FoundColor <> Blue by making the character after the word "if" an open-
parenthesis. Although this is usually accomplished by enclosing the entire expression in parentheses,
it can also be done with something like if (x > 0) and (y > 0). In addition, the open-parenthesis may
Variables and Expressions
49
be omitted entirely if the first item after the word "if" is a function call or an operator such as "not" or
"!".
Empty strings: To specify an empty string in an expression, use an empty pair of quotes. For
example, the statement if (MyVar <> "") would be true if MyVar is not blank. However, in a
traditional-if, a pair of empty quotes is treated literally. For example, the statement if MyVar = "" is
true only if MyVar contains an actual pair of quotes. Thus, to check if a variable is blank with a
traditional-if, use = or <> with nothing on the right side as in this example: if Var =
On a related note, any invalid expression such as (x +* 3) yields an empty string.
Boolean values: When an expression is required to evaluate to true or false (such as an IF-
statement), a blank or zero result is considered false and all other results are considered true. For
example, the statement "if ItemCount" would be false only if ItemCount is blank or 0. Similarly, the
expression "if not ItemCount" would yield the opposite result.
Operators such as NOT/AND/OR/>/=/< automatically produce a true or false value: they yield 1 for
true and 0 for false. For example, in the following expression, the variable Done is assigned 1 if either
of the conditions is true:
Done := A_Index > 5 or FoundIt
As hinted above, a variable can be used to hold a false value simply by making it blank or assigning 0
to it. To take advantage of this, the shorthand statement "if Done" can be used to check whether the
variable Done is true or false.
The words true and false are built-in variables containing 1 and 0. They can be used to make a script
more readable as in these examples:
CaseSensitive := false
ContinueSearch := true
Storing the result of an expression: To assign a result to a variable, use the := operator. For
example:
NetPrice := Price * (1 - Discount/100)
Since the example above produces a floating point number (due to division), the number of decimal
places stored in NetPrice is determined by SetFormat. SetFormat can also alter other characteristics of
expression results. By contrast, AutoTrim has no effect on an expression's result.
Integers and floating point: Within an expression, literal numbers are considered to be floating
point if they contain a decimal point; otherwise, they are integers. For most operators -- such as
addition and multiplication -- if either of the inputs is a floating point number, the result will also be a
floating point number.
Within expressions and non-expressions alike, integers may be written in either hexadecimal or
decimal format. Hexadecimal numbers all start with the prefix 0x. For example, Sleep 0xFF is
equivalent to Sleep 255.
Force an expression: An expression can be used in a parameter that does not directly support it
(except an OutputVar or InputVar parameter such as those of StringLen) by preceding the expression
with a percent sign and a space or tab. This technique is often used to access arrays. For example:
FileAppend, % MyArray%i%, My File.txt
MsgBox % "The variable MyVar contains " MyVar "."
Loop % Iterations + 1
WinSet, Transparent, % X + 100
Control, Choose, % CurrentSelection - 1
Printed Documentation
50
Operators in Expressions
Operators of equal precedence such as multiply (*) and divide (/) are evaluated in left-to-right order
by default. By contrast, an operator of lower precedence such as add (+) is evaluated after a higher
one such as multiply (*). For example, 3 + 2 * 2 would be evaluated as though it were 3 + (2 * 2).
Parentheses may be used to override precedence as in this example: (3 + 2) * 2
Expression Operators (in descending precedence order)
%Var%
If a variable is enclosed in percent signs within an expression (e.g. %Var%),
whatever that variable contains is assumed to be the name or partial name of
another variable (if there is no such variable, %Var% resolves to a blank string).
This is most commonly used to reference array elements such as the following
example:
Var := MyArray%A_Index% + 100
Such a reference should not resolve to an environment variable, the clipboard, or
any reserved/read-only variable. If it does, it is treated as an empty string.
**
Power (**). Both the base and the exponent may contain a decimal point. If the
exponent is negative, the result will be formatted as a floating point number even if
the base and exponent are both integers. Since ** is of higher precedence than
unary minus, -2**2 is evaluated like -(2**2) and so yields -4. Thus, to raise a
literal negative number to a power, enclose it in parentheses such as (-2)**2.
Note: A negative base combined with a fractional exponent such as (-2)**0.5 is
not supported; it will yield an empty string. But both (-2)**2 and (-2)**2.0 are
supported.
-
!
~
& *
Unary minus (-): Although it uses the same symbol as the subtract operator,
unary minus applies to only a single item or sub-expression as shown twice in this
example: - (3 / - x). On a related note, any unary plus signs (+) within an
expression are ignored.
Logical-not (!): If the operand is blank or 0, the result of applying logical-not is 1,
which means "true". Otherwise, the result is 0 (false). For example: !x or !(y and
z).
Note: The word NOT is synonymous with ! except that ! has a higher precedence.
Bitwise-not (~): This inverts each bit of its operand. If the operand is a floating
point value, it is truncated to an integer prior to the calculation. If the operand is
between 0 and 4294967295 (0xffffffff), it will be treated as an unsigned 32-bit
value. Otherwise, it is treated as a signed 64-bit value. For example, ~0xf0f
evaluates to 0xfffff0f0 (4294963440).
Address (&) and Dereference (*) [v1.0.36.07+]: &MyVar retrieves the address
of MyVar's contents in memory. Conversely, *MyVar would assume that MyVar
contains a numeric memory address and retrieve the byte at that address as a
number between 0 and 255 (0 is always retrieved if the address is 0; but any other
invalid address must be avoided because it might crash the script). These rarely-
used operators can help with DllCall structures and the manipulation of strings that
contain binary zeros. ExtractInteger() is one example.
*
/
//
Multiply (*): The result is an integer if both inputs are integers; otherwise, it is a
floating point number.
True divide (/): Unlike EnvDiv (/=), true division yields a floating point result
even when both inputs are integers. For example, 3/2 yields 1.5 rather than 1, and
4/2 yields 2.0 rather than 2.
Floor divide (//): The double-slash operator uses high-performance integer
Variables and Expressions
51
division if the two inputs are integers. For example, 5//3 is 1 and 5//-3 is -1. If
either of the inputs is in floating point format, floating point division is performed
and the result is truncated to the nearest integer to the left. For example, 5//3.0 is
1.0 and 5.0//-3 is -2.0. Although the result of this floating point division is an
integer, it is stored in floating point format so that anything else that uses it will
see it as such. For modulo, see mod().
On a related note, the *= and /= operators are a shorthand way to multiply or
divide the value in a variable by another value. For example, Var*=2 produces the
same result as Var:=Var*2 (though the former performs better).
Division by zero yields a blank result (empty string).
+
-
Add (+) and subtract (-). Note: In expressions, any blank value (empty string)
involved in a math operation is not assumed to be zero. Instead, it is treated as an
error, which causes that part of the expression to evaluate to an empty string. For
example, if the variable X is blank, the expression X+1 yields a blank value rather
than 1.
The += and -= operators are a shorthand way to increment or decrement a
variable. For example, Var+=2 produces the same result as Var:=Var+2 (though
the former performs better). Similarly, a variable can be increased or decreased by
1 by using Var++, Var--, ++Var, or --Var.
<<
>>
Bit shift left (<<) and right (>>). Example usage: Value1 << Value2. Floating
point inputs are truncated to integers prior to the calculation. Shift left (<<) is
equivalent to multiplying Value1 by "2 to the Value2th power". Shift right (>>) is
equivalent to dividing Value1 by "2 to the Value2th power" and truncating the
remainder.
&
^
|
Bitwise-and (&), bitwise-exclusive-or (^), and bitwise-or (|). Of the three,
& has the highest precedence and | has the lowest. Floating point inputs are
truncated to integers prior to the calculation.
.
Concatenate (.). The period (dot) operator may be used to merge adjacent
strings and variables (there should be at least one space on each side of the
period). In most cases, you can also omit the period to achieve the same result
(though there should be at least one space between the items to be merged).
Example (expression method): Var := "The color is " . FoundColor
Example (traditional method): Var = The color is %FoundColor%
Sub-expressions and references such as Array%i% can also be merged with other
items. For example:
Var := "The net price is " . Price * (1 - Discount/100)
Var := "The largest among X and Y is " . Max(X, Y)
Var := "The value of array element " i " is " Array%i%
A line that begins with a period is automatically merged with the line above it. See
line continuation for details.
When text is being appended to the end of a variable, the traditional method of
concatenation (=) performs better than the expression method (:=), especially
when the strings involved are large. Here is an example of the fast method: Var =
%Var%%TextToAppend%
> <
>= <=
Greater (>), less (<), greater-or-equal (>=), and less-or-equal (<=). If
either of the inputs is not a number, both are compared alphabetically (a quoted
literal string such as "55" is always considered non-numeric in this context). The
comparison is case sensitive only if StringCaseSense has been turned on.
= ==
<> !=
Equal (=) , case-sensitive-equal (==) , and not-equal (<> or !=). The
operators != and <> are identical in function. The == operator behaves identically
Printed Documentation
52
to = except when either of the inputs is not a number, in which case == is always
case sensitive and = is always case insensitive (the method of insensitivity depends
on StringCaseSense). By contrast, <> and != obey StringCaseSense. Note: A
quoted literal string such as "55" is always considered non-numeric in this context.
NOT
Logical-NOT. Except for its lower precedence, this is the same as the ! operator.
For example, not (x = 3 or y = 3) is the same as !(x = 3 or y = 3)
AND
&&
Both of these are logical-AND. For example: x > 3 and x < 10. To enhance
performance, short-circuit evaluation is applied whenever possible. Also, a line that
begins with AND/OR/&&/|| is automatically merged with the line above it. See line
continuation for details.
OR
||
Both of these are logical-OR. For example: x <= 3 or x >= 10. To enhance
performance, short-circuit evaluation is applied whenever possible.
mod()
round()
abs()
These and other built-in math functions are described here.

Performance: The expression assignment operator (:=) is optimized so that it performs just as
quickly as the non-expression operator (=) for simple cases such as the following:
x := y ; Same performance as x = %y%
x := 5 ; Same performance as x = 5.
x := "literal string" ; Same performance as x = literal string.

Built-in Variables
The following variables are built into the program and can be referenced by any script. Most of them
are reserved, meaning that their contents cannot be directly altered by the script.
Table of Contents
Special Characters: A_Space, A_Tab
Script Properties: command line parameters, A_WorkingDir, A_ScriptDir, A_ScriptName,
(...more...)
Date and Time: A_YYYY, A_MM, A_DD, A_Hour, A_Min, A_Sec, (...more...)
Script Settings: A_IsSuspended, A_BatchLines, A_TitleMatchMode, (...more...)
User Idle Time: A_TimeIdle, A_TimeIdlePhysical
GUI Windows and Menu Bars: A_Gui, A_GuiControl, A_GuiControlEvent, A_EventInfo
Hotkeys, Hotstrings, and Custom Menu Items: A_ThisHotkey, A_EndChar, A_ThisMenuItem,
(...more...)
Operating System and User Info: A_OSVersion, A_ScreenWidth, A_ScreenHeight, (...more...)
Misc: A_Cursor, A_CaretX, A_CaretY, Clipboard, ClipboardAll, ErrorLevel
Loop: A_Index, (...more...)
Special Characters
A_Space This variable contains a single space character. See AutoTrim for details.
A_Tab This variable contains a single tab character. See AutoTrim for details.
Variables and Expressions
53
Script Properties
1, 2, 3, etc.
These variables are automatically created whenever a script is launched
with command line parameters. They can be changed and referenced just
like normal variable names (for example: %1%). The variable %0%
contains the number of parameters passed (0 if none). For details, see the
command line parameters.
A_WorkingDir
The script's current working directory, which is where files will be accessed
by default. The final backslash is not included unless it is the root directory.
Two examples: C:\ and C:\My Documents. Use SetWorkingDir to change
the working directory.
A_ScriptDir
The full path of the directory where the current script is located. For
backward compatibility with AutoIt v2, the final backslash is included only
for .aut scripts. An example for .aut scripts is C:\My Documents\
A_ScriptName The file name of the current script, without its path, e.g. MyScript.ahk.
A_ScriptFullPath
The combination of the above two variables to give the complete file
specification of the script, e.g. C:\My Documents\MyScript.ahk
A_LineNumber
The number of the currently executing line within the script (or one of its
#Include files). This line number will match the one shown by ListLines; it
can be useful for error reporting such as this example: MsgBox Could not
write to log file (line number %A_LineNumber%).
Since a compiled script has merged all its #Include files into one big script,
its line numbers may differ from when it is run as a non-compiled script.
A_LineFile
The full path and name of the file to which A_LineNumber belongs, which
will be the same as A_ScriptFullPath unless the line belongs to one of a
non-compiled script's #Include files.
A_AhkVersion
In versions prior to 1.0.22, this variable is blank. Otherwise, it contains the
version of AutoHotkey that is running the script, such as 1.0.22. In the case
of a compiled script, the version that was originally used to compile it is
reported. The formatting of the version number allows a script to check
whether A_AhkVersion is greater than some minimum version number with
> or >= as in this example: if A_AhkVersion >= 1.0.25.07
A_AhkPath
[v1.0.41+]
For non-compiled scripts: The full path and name of the EXE file that is
actually running the current script. For example: C:\Program
Files\AutoHotkey\AutoHotkey.exe
For compiled scripts: The same as the above except the AutoHotkey
directory is discovered via the registry entry
HKEY_LOCAL_MACHINE\SOFTWARE\AutoHotkey\InstallDir. If there is no
such entry, A_AhkPath is blank.
A_IsCompiled Contains 1 if the script is running as a compiled EXE and nothing if it is not.
A_ExitReason
The most recent reason the script was asked to terminate. This variable is
blank unless the script has an OnExit subroutine and that subroutine is
currently running or has been called at least once by an exit attempt. See
OnExit for details.
Date and Time
A_YYYY
Current 4-digit year (e.g. 2004). Synonymous with A_Year. Note: To retrieve a
formatted time or date appropriate for your locale and language, use
"FormatTime, OutputVar" (time and long date) or "FormatTime, OutputVar,,
LongDate" (retrieves long-format date).
Printed Documentation
54
A_MM Current 2-digit month (01-12). Synonymous with A_Mon.
A_DD Current 2-digit day of the month (01-31). Synonymous with A_MDay.
A_MMMM Current month's full name in the current user's language, e.g. July
A_MMM Current month's abbreviation in the current user's language, e.g. Jul
A_DDDD Current day of the week's full name in the current user's language, e.g. Sunday
A_DDD
Current day of the week's 3-letter abbreviation in the current user's language,
e.g. Sun
A_WDay Current 1-digit day of the week (1-7). 1 is Sunday in all locales.
A_YDay
Current day of the year (1-366). The value is not zero-padded, e.g. 9 is
retrieved, not 009. To retrieve a zero-padded value, use the following:
FormatTime, OutputVar, , YDay0
A_YWeek
Current year and week number (e.g. 200453) according to ISO 8601. To
separate the year from the week, use StringLeft, Year, A_YWeek, 4 and
StringRight, Week, A_YWeek, 2. Precise definition of A_YWeek: If the week
containing January 1st has four or more days in the new year, it is considered
week 1. Otherwise, it is the last week of the previous year, and the next week
is week 1.
A_Hour
Current 2-digit hour (00-23) in 24-hour time (for example, 17 is 5pm). To
retrieve 12-hour time as well as an AM/PM indicator, follow this example:
FormatTime, OutputVar, , h:mm:ss tt
A_Min
Current 2-digit minute (00-59).
A_Sec Current 2-digit second (00-59).
A_MSec
Current 3-digit millisecond (000-999). To remove the leading zeros, follow this
example: Milliseconds := A_MSec + 0
A_Now
The current local time in YYYYMMDDHH24MISS format. Note: Date and time
math can be performed with EnvAdd and EnvSub. Also, FormatTime can format
the date and/or time according to your locale or preferences.
A_NowUTC
The current Coordinated Universal Time (UTC) in YYYYMMDDHH24MISS format.
UTC is essentially the same as Greenwich Mean Time (GMT).
A_TickCount
The number of milliseconds since the computer was rebooted. By storing
A_TickCount in a variable, elapsed time can later be measured by subtracting
that variable from the latest A_TickCount value. For example:
StartTime := A_TickCount
Sleep, 1000
ElapsedTime := A_TickCount - StartTime
MsgBox, %ElapsedTime% milliseconds have elapsed.
If you need more precision than A_TickCount's 10ms, use
QueryPerformanceCounter().
Script Settings
A_IsSuspended Contains 1 if the script is suspended and 0 otherwise.
A_BatchLines
(synonymous with A_NumBatchLines) The current value as set by
SetBatchLines. Examples: 200 or 10ms (depending on format).
A_TitleMatchMode The current mode set by SetTitleMatchMode: 1, 2, 3, or RegEx.
A_TitleMatchModeSpeed The current match speed (fast or slow) set by SetTitleMatchMode.
Variables and Expressions
55
A_DetectHiddenWindows The current mode (On or Off) set by DetectHiddenWindows.
A_DetectHiddenText The current mode (On or Off) set by DetectHiddenText.
A_AutoTrim The current mode (On or Off) set by AutoTrim.
A_StringCaseSense The current mode (On, Off, or Locale) set by StringCaseSense.
A_FormatInteger The current integer format (H or D) set by SetFormat.
A_FormatFloat The current floating point number format set by SetFormat.
A_KeyDelay
The current delay set by SetKeyDelay (always decimal, not hex).
This delay is for the traditional SendEvent mode, not SendPlay.
A_WinDelay The current delay set by SetWinDelay (always decimal, not hex).
A_ControlDelay
The current delay set by SetControlDelay (always decimal, not
hex).
A_MouseDelay
The current delay set by SetMouseDelay (always decimal, not hex).
This delay is for the traditional SendEvent mode, not SendPlay.
A_DefaultMouseSpeed
The current speed set by SetDefaultMouseSpeed (always decimal,
not hex).
A_IconHidden
Contains 1 if the tray icon is currently hidden or 0 otherwise. The
icon can be hidden via #NoTrayIcon or the Menu command.
A_IconTip
Blank unless a custom tooltip for the tray icon has been specified
via Menu, Tray, Tip -- in which case it's the text of the tip.
A_IconFile
Blank unless a custom tray icon has been specified via Menu, tray,
icon -- in which case it's the full path and name of the icon's file.
A_IconNumber
Blank if A_IconFile is blank. Otherwise, it's the number of the icon
in A_IconFile (typically 1).
User Idle Time
A_TimeIdle
The number of milliseconds that have elapsed since the system last
received keyboard, mouse, or other input. This is useful for determining
whether the user is away. This variable will be blank unless the operating
system is Windows 2000, XP, or beyond. Physical input from the user as
well as artificial input generated by any program or script (such as the
Send or MouseMove commands) will reset this value back to zero. Since
this value tends to increase by increments of 10, do not check whether it
is equal to another value. Instead, check whether it is greater or less
than another value. For example: IfGreater, A_TimeIdle, 600000,
MsgBox, The last keyboard or mouse activity was at least 10 minutes
ago.
A_TimeIdlePhysical
Same as above but ignores artificial keystrokes and/or mouse clicks
whenever the corresponding hook (keyboard or mouse) is installed. If
neither hook is installed, this variable is equivalent to A_TimeIdle. If only
one hook is present, only that one type of artificial input will be ignored.
A_TimeIdlePhysical may be more useful than A_TimeIdle for determining
whether the user is truly present.
GUI Windows and Menu Bars
A_Gui
The GUI window number that launched the current thread. This variable
is blank unless a Gui control, menu bar item, or event such as
GuiClose/GuiEscape launched the current thread.
Printed Documentation
56
A_GuiControl
The name of the variable associated with the GUI control that launched
the current thread. If that control lacks an associated variable,
A_GuiControl instead contains the first 63 characters of the control's
text/caption (this is most often used to avoid giving each button a
variable name). A_GuiControl is blank whenever: 1) A_Gui is blank; 2)
a GUI menu bar item or event such as GuiClose/GuiEscape launched the
current thread; 3) the control lacks an associated variable and has no
caption; or 4) The control that originally launched the current thread no
longer exists (perhaps due to Gui Destroy).
A_GuiWidth
A_GuiHeight
These contain the GUI window's width and height when referenced in a
GuiSize subroutine. They apply to the window's client area, which is the
area excluding title bar, menu bar, and borders.
A_GuiX
A_GuiY
These contain the X and Y coordinates for GuiContextMenu and
GuiDropFiles events.
A_GuiControlEvent

A_GuiEvent is a
synonym for it in
v1.0.36+.
The type of event that launched the current thread. If the thread was
not launched via GUI action, this variable is blank. Otherwise, it
contains one of the following strings:
Normal: The event was triggered by a single left-click or via keystrokes
(arrow keys, TAB key, space bar, underlined shortcut key, etc.). This
value is also used for menu bar items and the special events such as
GuiClose and GuiEscape.
DoubleClick: The event was triggered by a double-click. Note: The first
click of the click-pair will still cause a Normal event to be received first.
In other words, the subroutine will be launched twice: once for the first
click and again for the second.
RightClick: Occurs only for GuiContextMenu, ListViews, and TreeViews.
Context-sensitive values: For details see GuiContextMenu,
GuiDropFiles, Slider, MonthCal, ListView, and TreeView.
A_EventInfo
[v1.0.36+]
Contains additional information about the following events:
The OnClipboardChange label
Mouse wheel hotkeys (WheelDown/Up)
GUI events, namely GuiContextMenu, GuiDropFiles, ListBox, ListView, TreeView, and StatusBar. If there
is no additional information for an event, A_EventInfo contains 0.
Note: Unlike variables such as A_ThisHotkey, each thread retains its own value for A_Gui,
A_GuiControl, A_GuiX/Y, A_GuiControlEvent, and A_EventInfo. Therefore, if a thread is interrupted by
another, upon being resumed it will still see its original/correct values in these variables.
Hotkeys, Hotstrings, and Custom Menu Items
A_ThisMenuItem
The name of the most recently selected custom menu item (blank if
none).
A_ThisMenu The name of the menu from which A_ThisMenuItem was selected.
A_ThisMenuItemPos
A number indicating the current position of A_ThisMenuItem within
A_ThisMenu. The first item in the menu is 1, the second is 2, and so
on. Menu separator lines are counted. This variable is blank if
A_ThisMenuItem is blank or no longer exists within A_ThisMenu. It
is also blank if A_ThisMenu itself no longer exists.
A_ThisHotkey
The key name of the most recently executed hotkey or hotstring
(blank if none), e.g. #z. This value will change if the current thread
is interrupted by another hotkey, so be sure to copy it into another
Variables and Expressions
57
variable immediately if you need the original value for later use in a
subroutine.
When a hotkey is first created -- either by the Hotkey command or
a double-colon label in the script -- its key name and the ordering
of its modifier symbols becomes the permanent name of that
hotkey.
A_PriorHotkey
Same as above except for the previous hotkey. It will be blank if
none.
A_TimeSinceThisHotkey
The number of milliseconds that have elapsed since A_ThisHotkey
was pressed. It will be -1 whenever A_ThisHotkey is blank.
A_TimeSincePriorHotkey
The number of milliseconds that have elapsed since A_PriorHotkey
was pressed. It will be -1 whenever A_PriorHotkey is blank.
A_EndChar
The ending character that was pressed by the user to trigger the
most recent non-auto-replace hotstring. If no ending character was
required (due to the * option), this variable will be blank.
Operating System and User Info
ComSpec
[v1.0.43.08+]
Contains the same string as the environment's ComSpec variable (e.g.
C:\Windows\system32\cmd.exe). Often used with Run/RunWait.
Note: there is no A_ prefix on this variable.
A_Temp
[v1.0.43.09+]
The full path and name of the folder designated to hold temporary
files (e.g. C:\DOCUME~1\UserName\LOCALS~1\Temp). It is retrieved
from one of the following locations (in order): 1) the environment
variables TMP, TEMP, or USERPROFILE; 2) the Windows directory. On
Windows 9x, A_WorkingDir is returned if neither TMP nor TEMP exists.
A_OSType
The type of Operating System being run. Either WIN32_WINDOWS
(i.e. Windows 95/98/ME) or WIN32_NT (i.e. Windows
NT4/2000/XP/2003/Vista).
A_OSVersion
One of the following strings: WIN_VISTA [requires v1.0.44.13+],
WIN_2003, WIN_XP, WIN_2000, WIN_NT4, WIN_95, WIN_98,
WIN_ME. For example:
if A_OSVersion in WIN_NT4,WIN_95,WIN_98,WIN_ME ; Note:
No spaces around commas.
{
MsgBox This script requires Windows 2000/XP or later.
ExitApp
}
A_Language The system's default language, which is one of these 4-digit codes.
A_ComputerName The network name of the computer.
A_UserName The logon name of the current user.
A_WinDir The windows directory. For example: C:\Windows
A_ProgramFiles
or ProgramFiles
The Program Files directory (e.g. C:\Program Files). In v1.0.43.08+,
the A_ prefix may be omitted, which helps ease the transition to
#NoEnv.
A_AppData
[v1.0.43.09+]
The full path and name of the folder containing the current user's
application-specific data.
Printed Documentation
58
A_AppDataCommon
[v1.0.43.09+]
The full path and name of the folder containing the all-users
application-specific data.
A_Desktop
The full path and name of the folder containing the current user's
desktop files.
A_DesktopCommon
The full path and name of the folder containing the all-users desktop
files.
A_StartMenu The full path and name of the current user's Start Menu folder.
A_StartMenuCommon The full path and name of the all-users Start Menu folder.
A_Programs
The full path and name of the Programs folder in the current user's
Start Menu.
A_ProgramsCommon
The full path and name of the Programs folder in the all-users Start
Menu.
A_Startup
The full path and name of the Startup folder in the current user's Start
Menu.
A_StartupCommon
The full path and name of the Startup folder in the all-users Start
Menu.
A_MyDocuments
The full path and name of the current user's "My Documents" folder.
Unlike most of the similar variables, if the folder is the root of a drive,
the final backslash is not included. For example, it would contain M:
rather than M:\
A_IsAdmin
If the current user has admin rights, this variable contains 1.
Otherwise, it contains 0. Under Windows 95/98/Me, this variable
always contains 1.
A_ScreenWidth
A_ScreenHeight
The width and height of the primary monitor, in pixels (e.g. 1024 and
768).
To discover the dimensions of other monitors in a multi-monitor
system, use SysGet.
To instead discover the width and height of the entire desktop (even if
it spans multiple monitors), use the following example (but on
Windows 95/NT, both of the below variables will be set to 0):
SysGet, VirtualWidth, 78
SysGet, VirtualHeight, 79
In addition, use SysGet to discover the work area of a monitor, which
can be smaller than the monitor's total area because the taskbar and
other registered desktop toolbars are excluded.
A_IPAddress1
through 4
The IP addresses of the first 4 network adapters in the computer.
Misc.
A_Cursor
The type of mouse cursor currently being displayed. It will be one of the
following words: AppStarting, Arrow, Cross, Help, IBeam, Icon, No, Size, SizeAll,
SizeNESW, SizeNS, SizeNWSE, SizeWE, UpArrow, Wait, Unknown. The acronyms
used with the size-type cursors are compass directions, e.g. NESW =
NorthEast+SouthWest. The hand-shaped cursors (pointing and grabbing) are
classfied as Unknown.
Known limitation (in versions prior to 1.0.42.02 or on Windows 95): If this
variable's contents are fetched repeatedly at a high frequency (i.e. every 500
ms or faster), it will probably disrupt the user's ability to double-click. There is
Variables and Expressions
59
no known workaround.
A_CaretX
A_CaretY
The current X and Y coordinates of the caret (text insertion point). The
coordinates are relative to the active window unless CoordMode is used to make
them relative to the entire screen. If there is no active window or the caret
position cannot be determined, these variables are blank.
The following script allows you to move the caret around to see its current
position displayed in an auto-update tooltip. Note that some windows (e.g.
certain versions of MS Word) report the same caret position regardless of its
actual position.
#Persistent
SetTimer, WatchCaret, 100
return
WatchCaret:
ToolTip, X%A_CaretX% Y%A_CaretY%, A_CaretX, A_CaretY - 20
return
If the contents of these variables are fetched repeatedly at a high frequency
(i.e. every 500 ms or faster), the user's ability to double-click will probably be
disrupted. There is no known workaround.
Clipboard
The contents of the OS's clipboard, which can be read or written to. See the
Clipboard section.
ClipboardAll
The entire contents of the clipboard (such as formatting and text). See
ClipboardAll.
ErrorLevel See ErrorLevel.
A_LastError
The result from the OS's GetLastError() function. For details, see DllCall() and
Run/RunWait.
Loop
A_Index
This is the number of the current loop iteration (a 64-bit integer). For
example, the first time the script executes the body of a loop, this
variable will contain the number 1. See Loop for details.
A_LoopFileName,
etc.
This and other related variables are valid only inside a file-loop.
A_LoopRegName,
etc.
This and other related variables are valid only inside a registry-loop.
A_LoopReadLine See file-reading loop.
A_LoopField See parsing loop.
Environment Variables vs. " Normal" Variables
Environment variables are maintained by the operating system. You can see a list of them at the
command prompt by typing SET then pressing Enter.
A script may create a new environment variable or change the contents of an existing one with
EnvSet. However, such additions and changes are private; they are not seen by the rest of the
system. One exception is when a script launches a program (even another script) via Run or RunWait:
such programs inherit a copy of the parent script's environment variables, including private ones.
In v1.0.43.08+, it is recommended that all new scripts retrieve environment variables such as Path
via EnvGet, OutputVar, Path. For explanation, see #NoEnv.
Printed Documentation
60
Variable Capacity and Memory
Each variable may contain up to 64 MB of text (this limit can be increased with #MaxMem).
When a variable is given a new string longer than its current contents, additional system memory is
allocated automatically.
The memory occupied by a large variable can be freed by setting it equal to nothing, e.g. var := ""
There is no limit to how many variables a script may create. The program is designed to support at
least several million variables without a significant drop in performance.
Commands, functions, and expressions that accept numeric inputs generally support 15 digits of
precision for floating point values. For integers, 64-bit signed values are supported, which range from
-9223372036854775808 (-0x8000000000000000) to 9223372036854775807 (0x7FFFFFFFFFFFFFFF).
Any integer constants outside this range are set to the nearest in-range integer. By contrast,
arithmetic operations on integers wrap around upon overflow (e.g. 0x7FFFFFFFFFFFFFFF + 1 = -
0x8000000000000000).

61
Functions
Table of Contents
Introduction and Simple Example
Parameters
Optional Parameters
Local Variables
Using #Include to Share Functions Among Multiple Scripts
Short-circuit Boolean Evaluation
Using Subroutines Within a Function
Return, Exit, and General Remarks
Built-in Functions
Introduction and Simple Example
A function is similar to a subroutine (Gosub) except that it can accept parameters (inputs) from its
caller. In addition, a function may optionally return a value to its caller. Consider the following simple
function which accepts two numbers and returns their sum:
Add(x, y)
{
return x + y ; "Return" expects an expression.
}
The above is known as a function definition because it creates a function named "Add" (not case
sensitive) and establishes that anyone who calls it must provide exactly two parameters (x and y). To
call the function, assign its result to a variable with the := operator as in this example:
Var := Add(2, 3) ; The number 5 will be stored in Var.
Also, a function may be called without storing its return value:
Add(2, 3)
But in this case, any value returned by the function is discarded; so unless the function produces
some effect other than its return value, the call would serve no purpose.
Since a function call is an expression, any variable names in its parameter list should not be enclosed
in percent signs. By contrast, literal strings should be enclosed in double quotes. For example:
if InStr(MyVar, "fox")
MsgBox The variable MyVar contains the word fox.
Finally, functions may be called in the parameters of any command (except OutputVar and InputVar
parameters such as those of StringLen). However, parameters that do not support expressions must
use the "% " prefix as in this example:
MsgBox % "The answer is: " . Add(3, 2)
The "% " prefix is also permitted in parameters that natively support expressions, but it is simply
ignored.
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 should not accept any
parameters, leave the parentheses empty; for example: GetCurrentTimestamp().
Printed Documentation
62
From the function's point of view, parameters are essentially the same as local variables 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.
Known limitation: It is not possible to pass Clipboard, built-in variables, or environment variables to a
function's ByRef parameter, even when #NoEnv is absent from the script. Passing a built-in variable to
a ByRef parameter will cause an error dialog to be displayed.
Optional Parameters [v1.0.35+]
When defining a function, one or more of its parameters can be marked as optional. This is done by
appending an equal sign followed by a default value. In the following example, the Z parameter is
marked optional:
Add(X, Y, Z = 0)
{
return X + Y + Z
}
When the caller passes three parameters to the function above, Z's default value is ignored. But when
the caller passes only two parameters, Z automatically receives the value 0.
It is not possible to have optional parameters isolated in the middle of the parameter list. In other
words, all parameters that lie to the right of the first optional parameter must also be marked
optional.
A parameter's default value must be one of the following: true, false, a literal integer, a literal floating
point number, or a literal empty string ("").
Local Variables and Global Variables
All variables referenced or created inside a function are local by default (except built-in variables such
as Clipboard, ErrorLevel, and A_TimeIdle). Each local variable's contents are visible only to lines that
lie inside the function. Consequently, a local variable may have the same name as a global variable
and both will have separate contents. Finally, all local variables start off blank each time the function
is called.
Global variables: To refer to an existing global variable inside a function (or create a new one), declare
the variable as global prior to using it. For example:
LogToFile(TextToLog)
Functions
63
{
global LogFileName ; This global variable was previously given a value somewhere outside
this function.
FileAppend, %TextToLog%`n, %LogFileName%
}
If a function needs to reference or create a large number of global variables, it can be defined to
assume that all its variables are global (except its parameters) by making its first line either the word
"global" or the declaration of a local variable. For example:
SetDefaults()
{
global ; This word can be omitted if the first line of this function will be something like
"local MyVar".
Var := 33 ; Assigns 33 to a global variable, first creating the variable if necessary.
local x, y, z ; Local variables must be declared in this mode, otherwise they would be
assumed global.
...
}
This assume-global mode can also be used by a function to create a global array, such as a loop that
assigns values to Array%A_Index%.
Static variables: A variable may be declared as static to cause its value to be remembered between
calls. For example:
LogToFile(TextToLog)
{
static LineCount
LineCount += 1 ; Maintain a tally locally (its value is remembered between calls).
global LogFileName
FileAppend, %LineCount%: %TextToLog%`n, %LogFileName%
}
Static variables are always implicitly local. In addition, the only way to detect that a static variable is
being used for the first time is to check whether it is blank.

More about locals and globals:
Multiple variables may be declared on the same line by separating them with commas as in these
examples:
global LogFileName, MaxRetries
static TotalAttempts, PrevResult
Because the words local, global, and static are processed immediately when the script launches, they
cannot be conditionally executed by means of an IF statement. In other words, any use of local,
global, or static inside an IF's or ELSE's block will take effect unconditionally. In addition, it is not
currently possible to declare a dynamic variable such as global Array%i%.
Within a function, any dynamic variable reference such as Array%i% will always resolve to a local
variable unless no variable of that name exists, in which case a global is used if it exists. If neither
exists and the usage requires the variable to be created, it will be created as a local variable unless
the assume-global mode is in effect. Note: any non-dynamic reference to a variable creates that
Printed Documentation
64
variable the moment the script launches. For example, a reference to %Array1% outside a function
creates Array1 as a global the moment the script launches. Conversely, a reference to %Array1%
inside a function immediately creates it as a local.
As a consequence of the above, a function can create a global array manually (by means such as
Array%i% := A_Index) only if it has been defined as an assume-global function.
For commands that create arrays (such as StringSplit), the resulting array will be local if the assume-
global mode is not in effect or if the array's first element has been declared as a local variable (this is
also true if one of the function's parameters is passed, even if that parameter is ByRef, because
parameters are similar to local variables). Conversely, if the first element has been declared global, a
global array will be created. The first element for StringSplit is ArrayName0. For other array-creating
commands such as WinGet List, the first element is ArrayName (i.e. without the number).
Using #Include to Share Functions Among Multiple Scripts
The #Include directive may be used (even at the top of a script) to load functions from an external
file.
Explanation: When the script's flow of execution encounters a function definition, it jumps over it
(using an instantaneous method) and resumes execution at the line after its closing brace.
Consequently, execution can never fall into a function from above, nor does the presence of one or
more functions at the very top of a script affect the auto-execute section.
Short-circuit Boolean Evaluation
When AND and OR are used within an expression, they will short-circuit to enhance performance
(regardless of whether any function calls are present). Short-circuiting operates by refusing to
evaluate parts of an expression that cannot possibly affect its final result. To illustrate the concept,
consider this example:
if (ColorName <> "" AND not FindColor(ColorName))
MsgBox %ColorName% could not be found.
In the example above, the FindColor() function will never get called if the ColorName variable is
empty. This is because the left side of the AND would be false, and thus its right side would be
incapable of making the final outcome true.
Because of this behavior, it's important to realize that any side-effects produced by a function -- such
as altering a global variable's contents -- might never occur if that function is called on the right side
of an AND or OR.
It should also be noted that short-circuit evaluation will cascade into nested ANDs and ORs. For
example, in the following expression, only the leftmost comparison will occur whenever ColorName is
blank. This is because the left side would then be enough to determine the final answer with certainty:
if (ColorName = "" OR FindColor(ColorName, Region1) OR FindColor(ColorName, Region2))
break ; Nothing to search for, or a match was found.
As shown by the examples above, any expensive (time-consuming) functions should generally be
called on the right side of an AND or OR to enhance performance. This technique can also be used to
prevent a function from being called when one of its parameters would be passed a value it considers
inappropriate, such as an empty string.
Using Subroutines Within a Function
Although a function cannot contain definitions of other functions, it can contain subroutines. As with
other subroutines, use Gosub to launch them and Return to return (in which case the Return would
belong to the Gosub and not the function).
Known limitation: Currently, the name of each subroutine (label) must be unique among those of the
entire script. The program will notify you if any duplicate labels exist.
Functions
65
If a function uses Gosub to jump to a public subroutine (one that lies outside of the function's braces),
all variables will be global and the function's own local variables will be inaccessible until the
subroutine returns.
Although the use of Goto is generally discouraged, it can be used inside a function to jump to another
position within the same function. This can help simplify complex functions that have many points of
return, all of which need to do some clean-up prior to returning.
Although a Goto whose target is outside the function is ignored, it is possible for a function to Gosub
an external/public subroutine and then do a Goto from there.
A function may contain subroutines for timers, GUI g-labels, menu items, and similar features. This is
generally done to encapsulate them in a separate file for use with #Include, which prevents them from
interfering with the script's auto-execute section. However, such subroutines should use only static
and global variables (not locals) if their function is ever called normally. This is because a subroutine
thread that interrupts a function-call thread (or vice versa) would be able to change the values of local
variables seen by the interrupted thread. Furthermore, any time a function returns to its caller, all of
its local variables are made blank to free their memory. Finally, when a function is entered by a
subroutine thread, any references to dynamic variables made by that thread are treated as globals
(including commands that create arrays).
Return, Exit, and General Remarks
If the flow of execution within a function reaches the function's closing brace prior to encountering a
Return, the function ends and returns a blank value (empty string) to its caller. A blank value is also
returned whenever the function explicitly omits Return's parameter.
When a function uses the Exit command to terminate the current thread, its caller does not receive a
return value at all. For example, the statement Var := Add(2, 3) would leave Var unchanged if Add()
exits. The same thing happens if a function causes a runtime error such as running a nonexistent file
(when UseErrorLevel is not in effect).
A function may alter the value of ErrorLevel for the purpose of returning an extra value that is easy to
remember.
To call a function with one or more blank values (empty strings), use an empty pair of quotes as in
this example: FindColor(ColorName, "")
Since the calling of a function does not start a new thread, any changes made by a function to settings
such as SendMode and SetTitleMatchMode will go into effect for its caller too.
The caller of a function may pass a nonexistent variable or array element to it, which is useful when
the function expects the corresponding parameter to be ByRef. For example, calling
GetNextLine(BlankArray%i%) would create the variable BlankArray%i% automatically as a local or
global (depending on whether the caller is inside a function and whether it has the assume-global
mode is in effect).
When used inside a function, ListVars displays a function's local variables along with their contents.
This can help debug a script.
Known limitation: Although a function may call itself recursively, if it passes one of its own local
variables or parameters to itself ByRef, the new layer's ByRef parameter will refer to its own variable
rather than the previous layer's. However, this issue does not occur when a function passes to itself a
global variable or a ByRef parameter that refers to a global or some other function's local.
Style and Naming Conventions
You might find that complex functions are more readable and maintainable if their special variables
are given a distinct prefix. For example, naming each parameter in a function's parameter list with a
leading "p" or "p_" makes their special nature easy to discern at a glance, especially when a function
has several dozen local variables competing for your attention. Similarly, the prefix "r" or "r_" could be
used for ByRef parameters, and "s" or "s_" could be used for static variables.
In v1.0.41+, the One True Brace (OTB) style may optionally be used to define functions. For example:
Printed Documentation
66
Add(x, y) {
return x + y
}
Built-in Functions
Any optional parameters at the end of a built-in function's parameter list may be completely omitted.
For example, WinExist("Untitled - Notepad") is valid because its other three parameters would be
considered to be blank.
A built-in function will be overridden if the script defines its own function of the same name. For
example, a script could have its own custom WinExist() function that is called instead of the standard
one.
External functions that reside in DLL files may be called with DllCall().
Frequently-used Functions
FileExist(FilePattern): Returns a blank value (empty string) if FilePattern does not exist (FilePattern
is assumed to be in A_WorkingDir if an absolute path isn't specified). Otherwise, it returns the
attribute string (a subset of "RASHNDOCT") of the first matching file or folder. If the file has no
attributes (rare), "X" is returned. FilePattern may be the exact name of a file or folder, or it may
contain wildcards (* or ?). Since an empty string is seen as "false", the function's return value can
always be used as a quasi-boolean value. For example, the statement if FileExist("C:\My File.txt")
would be true if the file exists and false otherwise. Similarly, the statement if InStr(FileExist("C:\My
Folder"), "D") would be true only if the file exists and is a directory. Corresponding commands: IfExist
and FileGetAttrib.
GetKeyState(KeyName [, "P" or "T"]): Unlike the GetKeyState command -- which returns D for
down and U for up -- this function returns true (1) if the key is down and false (0) if it is up. If
KeyName is invalid, an empty string is returned. See GetKeyState for other return values and usage
instructions.
InStr(Haystack, Needle [, CaseSensitive?, StartingPos]): Returns the position of the first
occurrence of the string Needle in the string Haystack. Unlike StringGetPos, position 1 is the first
character; this is because 0 is synonymous with "false", making it an intuitive "not found" indicator. If
the parameter CaseSensitive is omitted or false, the search is not case sensitive (the method of
insensitivity depends on StringCaseSense); otherwise, the case must match exactly. If StartingPos is
omitted, it defaults to 1 (the beginning of Haystack). Otherwise, specify 2 to start at Haystack's
second character, 3 to start at the third, etc. If StartingPos is beyond the length of Haystack, 0 is
returned. If StartingPos is 0, the search is conducted in reverse (right-to-left) so that the rightmost
match is found. Regardless of the value of StartingPos, the returned position is always relative to the
first character of Haystack. For example, the position of "abc" in "123abc789" is always 4. Related
items: RegExMatch(), IfInString, and StringGetPos.
RegExMatch(Haystack, NeedleRegEx [, UnquotedOutputVar = "", StartingPos = 1]): See
RegExMatch().
RegExReplace(Haystack, NeedleRegEx [, Replacement = "", OutputVarCount = "", Limit = -
1, StartingPos = 1]): See RegExReplace().
StrLen(String): Returns the length of String. If String is a variable to which ClipboardAll was
previously assigned, its total size is returned. Corresponding command: StringLen.
WinActive("WinTitle" [, "WinText", "ExcludeTitle", "ExcludeText"]): Returns the Unique ID
(HWND) of the active window if it matches the specified criteria. If it does not, the function returns 0.
Since all non-zero numbers are seen as "true", the statement if WinActive("WinTitle") is true
whenever WinTitle is active. Finally, WinTitle supports ahk_id, ahk_class, and other special strings.
See IfWinActive for details about these and other aspects of window activation.
WinExist("WinTitle" [, "WinText", "ExcludeTitle", "ExcludeText"]): Returns the Unique ID
(HWND) of the first matching window (0 if none) as a hexademinal integer. Since all non-zero
Functions
67
numbers are seen as "true", the statement if WinExist("WinTitle") is true whenever WinTitle exists.
Finally, WinTitle supports ahk_id, ahk_class, and other special strings. See IfWinExist for details about
these and other aspects of window searching.
Miscellaneous Functions
Asc(String): Returns the ASCII code (a number between 1 and 255) for the first character in String.
If String is empty, 0 is returned.
Chr(Number): Returns the single character corresponding to the ASCII code indicated by Number. If
Number is not between 1 and 255 inclusive, an empty string is returned. Common ASCII codes include
9 (tab), 10 (linefeed), 13 (carriage return), 32 (space), 48-57 (the digits 0-9), 65-90 (uppercase A-Z),
and 97-122 (lowercase a-z).
IsLabel(LabelName) [v1.0.38+]: Returns a non-zero number if LabelName exists in the script as a
subroutine, hotkey, or hotstring (do not include the trailing colon(s) in LabelName). For example, the
statement if IsLabel(VarContainingLabelName) would be true if the label exists, and false otherwise.
This is useful to avoid runtime errors when specifying a dynamic label in commands such as Gosub,
Hotkey, Menu, and Gui.
ListView and TreeView functions: See the ListView and TreeView pages for details.
OnMessage(MsgNumber [, "FunctionName"]): Monitors a message/event. See OnMessage for
details.
VarSetCapacity(UnquotedVarName [, RequestedCapacity, FillByte]): Enlarges a variable's
holding capacity or frees its memory. See VarSetCapacity for details.
General Math
Note: Math functions generally return a blank value (empty string) if any of the incoming parameters
are non-numeric.
Abs(Number): Returns the absolute value of Number. The return value is the same type as Number
(integer or floating point).
Ceil(Number): Returns Number rounded up to the nearest integer (without any .00 suffix). For
example, Ceil(1.2) is 2 and Ceil(-1.2) is -1.
Exp(N): Returns e (which is approximately 2.71828182845905) raised to the Nth power. N may be
negative and may contain a decimal point. To raise numbers other than e to a power, use the **
operator.
Floor(Number): Returns Number rounded down to the nearest integer (without any .00 suffix). For
example, Floor(1.2) is 1 and Floor(-1.2) is -2.
Log(Number): Returns the logarithm (base 10) of Number. The result is formatted as floating point.
If Number is negative, an empty string is returned.
Ln(Number): Returns the natural logarithm (base e) of Number. The result is formatted as floating
point. If Number is negative, an empty string is returned.
Mod(Dividend, Divisor): Modulo. Returns the remainder when Dividend is divided by Divisor. The
sign of the result is always the same as the sign of the first parameter. For example, both mod(5, 3)
and mod(5, -3) yield 2, but mod(-5, 3) and mod(-5, -3) yield -2. If either input is a floating point
number, the result is also a floating point number. For example, mod(5.0, 3) is 2.0 and mod(5, 3.5) is
1.5. If the second parameter is zero, the function yields a blank result (empty string).
Round(Number [, N]): If N is omitted or 0, Number is rounded to the nearest integer. If N is
positive number, Number is rounded to N decimal places. If N is negative, Number is rounded by N
digits to the left of the decimal point. For example, Round(345, -1) is 350 and Round (345, -2) is 300.
Unlike Transform Round, the result has no .000 suffix whenever N is omitted or less than 1. In
v1.0.44.01+, a value of N greater than zero displays exactly N decimal places rather than obeying
Printed Documentation
68
SetFormat. To avoid this, perform another math operation on Round()'s return value; for example:
Round(3.333, 1)+0.
Sqrt(Number): Returns the square root of Number. The result is formatted as floating point. If
Number is negative, the function yields a blank result (empty string).
Trigonometry
Sin(Number) | Cos(Number) | Tan(Number) : Returns the trigonometric sine|cosine|tangent of
Number. Number must be expressed in radians.
ASin(Number): Returns the arcsine (the number whose sine is Number) in radians. If Number is less
than -1 or greater than 1, the function yields a blank result (empty string).
ACos(Number): Returns the arccosine (the number whose cosine is Number) in radians. If Number is
less than -1 or greater than 1, the function yields a blank result (empty string).
ATan(Number): Returns the arctangent (the number whose tangent is Number) in radians.
Note: To convert a radians value to degrees, multiply it by 180/pi (approximately 57.29578). To
convert a degrees value to radians, multiply it by pi/180 (approximately 0.01745329252). The value
of pi (approximately 3.141592653589793) is 4 times the arctangent of 1.
Other Functions
Titan's Command Functions: Provides a callable function for each AutoHotkey command that has an
OutputVar. This library can be included in any script via #Include.

69
Notes for AutoIt v2 Users
Benefits
Enjoy nearly complete backward compatibility with AutoIt v2. There is no need to learn new syntax
and commands unless you want to.
Use Else with every IF-type command.
Use blocks (multi-line sections) with IFs and ELSEs (virtually eliminating the need for Goto).
Use break and continue inside loops (another way to eliminate Goto's).
Use many new commands and benefit from enhancements to old ones (see below).
Catch silly errors and typos early (at load-time) rather than later (during runtime) when you
may be less prepared to deal with them: Syntax errors are caught as part of the optimization
process.
Gain a significant boost in performance.
Running AutoIt v2 (.aut) Scripts
AutoHotkey will run most existing .aut scripts without the need to change them. Only the following
AutoIt v2 features are not supported:
Adlib section (SetTimer can be used instead)
Break (break is now used for loops instead)
HideAutoItDebug
Converting Scripts from .aut to .ahk
Although .aut scripts can be run, to take full advantage of AutoHotkey's new features (that is, if you
plan to make improvements to the script) you should convert the script to a .ahk file. This is
necessary because some commands accept new, optional parameters that if enabled for AutoIt v2
scripts, would cause some of them to behave incorrectly (see further below for details).
You can automatically convert an AutoIt v2 (.aut) script to AutoHotkey format (.ahk) . The conversion
will make the escape character an accent/backtick (`) instead of backslash (\). This is harder than it
sounds due to the precise ordering of escape sequences in each line, which is why you can't just do a
search-and-replace in a text editor. This automated way should take care of all the details:
Append a .ahk to the end of an existing .aut filename, so that it now ends in ".aut.ahk"
Run this file with AutoHotkey, which, rather than than running the file, will create a new file in the
same directory that ends in "-NEW.ahk". This is the converted version. The original version will be
unchanged.
1. If you were using #EscapeChar in the script, remove it from the converted version.
After converting a script from .aut to .ahk, the main problem areas to check for are commands that
accept additional parameters in .ahk files but not in .aut files. If you used any non-escaped commas in
the parameter that was formerly the last parameter (in AutoIt v2) but is now not the last parameter,
those commas will be interpreted as delimiters. For example:
WinActivate, title, text with literal comma, here.
The above would be a problem after conversion; The string "here." would be interpreted as the new
"exclude title" parameter.

Here is a list of commands that both accept new parameters and that might be problematic:
StringReplace
StringGetPos
FileSelectFile
FileRemoveDir
WinClose/Kill/Activate/Minimize/Maximize/Restore/Hide/Show
Printed Documentation
70
WinSetTitle/WinGetTitle

Note: Even though they accept new parameters in .ahk files, commands such as IfWinExist are not
troublesome with respect to the above because the program can tell the difference between the AutoIt
v2 and AutoHotkey methods. The WinWait family of commands should also not be a problem, nor
should the MsgBox command since it has smart handling of commas.
Enhanced Syntax
With a few exceptions, floating point numbers (e.g. 3.5) and hexadecimal notation (e.g. 0xFF) are
supported by all commands.
The keyword ELSE is supported with all IF-type commands. In addition, blocks are supported. For
example:
OLD STYLE:
IfWinExist, Notepad, , WinActivate, Notepad
NEW STYLE (use {} to create a block if theres more than one line to be executed):
IfWinExist, Untitled - Notepad
{
WinActivate ; no need to specify title again, since it will automatically use the "last found"
window.
WinMaximize ; if this line weren't here, you wouldn't need a block (braces) around this
section
}
else
Run Notepad

Nested IFs and blocks example:
if varx = 1
{
if vary = 2
if varz = 3
sleep, 1
else ; this else goes with the nearest IF
sleep, 1
}
else ; this else goes with the top IF because the block prevents it from going with "if vary =
y"
sleep, 1

Also, blocks can be used with loops. But this first example doesn't need a block because the if+else is
considered only a single statement:
Loop, 5000
IfNotExist, c:\semaphore.txt
sleep, 1000
Notes for AutoIt v2 Users
71
else
break ; terminate the loop early

Here's one that does require a block:
Loop ; Since there's no count specified, it's an infinite loop unless an Exit, Return, or Break is
encountered.
{
...
if var <= 5
continue ; skip the rest of the block and begin at the top of the block for the next
iteration.
...
if var > 25
break ; break out of the loop
}

Example of a file-loop to explore the contents of a folder (registry-loops and parsing-loops are also
supported):
Loop, %A_ProgramFiles%\*.txt, , 1 ; Recurse into subfolders.
{
MsgBox, 4, , Filename = %A_LoopFileFullPath%`n`nContinue?
IfMsgBox, No
break
}

Finally, complex expressions and function calls are supported, such as the following:
NetPrice := Price * (1 - Discount/100)

LargestOfTwo := Max(x, y)

if (CurrentSetting > 100 or FoundColor <> "Blue")
MsgBox The setting is too high or the wrong color is present.
Other differences between AutoIt v2 and AutoHotkey
AutoIt v2 (.aut) scripts are run by AutoHotkey.exe with:
backslash (\) as their escape character. But other script types (.ahk, .ini) use accent (`). Use
#EscapeChar to change these defaults.
support for same-line comments disabled (use #AllowSameLineComments to enable them).
the pound sign (#) as a comment character in the Send command. Other script types use # to
indicate the windows key. For example, #y would send Win-Y.
DetectHiddenText defaulting to OFF. Other script types default to ON because it performs
better.
Printed Documentation
72
SetBatchLines defaulting to 1, meaning that scripts run fairly slowly by default. Other script
types use 10ms.
SetWinDelay defaulting to 500. Other script types default to 100, which makes windowing
operations much faster.
extended (new) parameters disabled for the following commands. This is done for
compatibility reasons (see conversion notes above):
MsgBox
FileSelectFile
FileRemoveDir
IniRead
StringReplace
StringGetPos
WinClose
WinKill
WinActivate
WinMinimize
WinMaximize
WinRestore
WinHide
WinShow
WinSetTitle
WinGetTitle
AutoIt v2 (.aut) scripts are not supported by the script compiler (Ahk2Exe) because there's no way for
the compiled script to figure out whether to run in AutoIt v2 mode or AutoHotkey mode. So first
convert your .aut script to .ahk before compiling it (see above).
Unlike AutoIt v2, IfGreater/Less compare alphabetically whenever one of the inputs isn't purely
numeric.
IniWrite and IniDelete: For AutoIt v2 (.aut) scripts: ErrorLevel is not set by these commands. For
other script types, ErrorLevel is set to 1 if there was a problem or 0 otherwise.
InputBox: For AutoIt v2 (.aut) scripts: If the user presses the cancel button, the output variable is
made blank so that there is a way to detect that the cancel button was pressed. For AutoHotkey
scripts: The output variable is set to whatever the user entered, even if the user pressed the cancel
button. To tell the difference, ErrorLevel is set to 1 if Cancel, Alt-F4, or the X-button was pressed to
dismiss the window. Otherwise, ErrorLevel is set to 0. This allows the cancel button to specify that a
different operation should be performed on the entered text.
SplashTextOn: AutoIt v2 (.aut) scripts use splash windows that are a little less tall than those in
AutoHotkey scripts. So if you convert a .aut script to .ahk, or copy & paste code from a .aut script into
a .ahk script, you might want to reduce the height of the window by the height of its title bar
(probably around 20 pixels, but it depends on your desktop settings).
Finally, unlike AutoIt v2, AutoHotkey does not store its variables as environment variables. This is
because performance would be worse and also because the operating system limits such variables to
32 KBytes. To explicitly place a value into an environment variable, use EnvSet, not SetEnv.
New Language and Command Style
Same-line comments can be used if the file extension of the script isn't .aut (AutoIt v2). The
semicolon is used as a prefix character for these comments, just as it is for whole line comments.
However, a semicolon is not considered a comment unless there is at least one space or tab to the left
of it. If there's ever a need to have a literal semicolon with a space or tab to its left, you can escape it
by preceding it with an accent/backtick (`). In both of the following examples, a literal semicolon is
stored in the variable:
var = `;
var =;
Notes for AutoIt v2 Users
73
For convenience, the first comma can be omitted for any command. For example: Sleep 1, MsgBox
test, etc.
For some commands, you can optionally use a new style in lieu the original AutoIt v2 style. These are:
Var = value ; can be used instead of SetEnv, var, value. Value can be blank, i.e. var =
if var <> value ; you can use <> != < = > as comparison operators rather than
ifequal/notequal/greater, etc.
var += 5 ; This is equivalent to envadd, var, 5. The other operators are -=, *=, /=
But don't use the new command style on the same line as an old command:
IfEqual, x, 35, y = 55 ; The y = 55 part will not be properly recognized as the
action of the IF.
; Instead, do this:
IfEqual, x, 35, SetEnv, y, 55
; Or this:
IfEqual, x, 35
y = 55
You can also check whether a variable matches one of the items in a list:
if var [not] in item1,item2,item3 ; Exact match
if var [not] contains item1,item2,item3 ; Substring match.
... or whether a variable is between two values:
if var [not] between 5 and 10
... or whether a variable conforms to a specified data type:
if var is number
if var is not float ; not floating point
The SetTitleMatchMode command has been improved: In addition to supporting the traditional modes
of 1 & 2, the command now supports the words fast and slow (for example: SetTitleMatchMode, slow).
The default is fast, which is what AutoIt v2 uses. By contrast, the slow mode can "see" more text for
certain types of windows. The fast mode performs significantly better, which may help the speed of
scripts that that do a lot of windowing commands. The slow mode need only be used when there is no
other way to uniquely identify a given window. The version of Window Spy included with the program
indicates which text of a window is available only in the slow mode.
Enhanced Commands
For most of the window commands, such as WinActivate, passing zero parameters results in activating
the window most recently found by IfWinExist or WinWait. In addition, passing the letter A for the
window title tells the command to act upon the currently-active (foreground) window. For example:
WinClose, A
Also, most of the Window commands support new parameters for Exclude-Title and Exclude-Text. A
window that would otherwise be a match will be disqualified if its Title contains Exclude-Title or its text
contains Exclude-Text.
StringGetPos now supports a new optional last parameter. If that parameter is the letter R, the search
will be conducted from the right instead of the left, that is, the last occurrence will be found rather
than the first.
MouseClick supports a new parameter, which if the letter D, holds down the button until it is released
by the user physically clicking it or via another action in the script. If this last parameter is U, the
button will be released (even if it wasn't down before, an up-event will still be sent). In addition, you
may find the syntax of the new Click command to be easier and more flexible.
Printed Documentation
74
A_Space and A_Tab are two new built-in variables, which contain a single space and single tab
character, respectively. This avoids the need for a workaround to get a variable to contain a space.
For example:
String = String with spaces
IfInString, String, %A_SPACE%
MsgBox, A space was found.
; But to assign a naked space to a variable of your own, be sure to turn off AutoTrim so that
the
; assignment won't remove all leading and trailing spaces:
AutoTrim, off
MySpace = %A_SPACE%
ClipboardAll is a new built-in variable containing everything on the clipboard (such as pictures and
formatting). It can be used to back up one or more "saved clipboards" to memory or disk, which can
be restored at a later time. This is especially useful for allowing a script to make temporary use of the
clipboard without fear of disturbing whatever the user may have stored on it.
Run and RunWait can run shortcuts (.lnk files), documents, and URLs. For example:
Run, www.yahoo.com
RunWait, New Document.doc
In addition, they now support the following system verbs: properties, edit, print, find, explore, open,
and print. For example:
Run, properties c:\autoexec.bat ; Bring up the properties dialog for this file.
Run, edit %A_SCRIPTFULLPATH% ; Perform the associated "edit" action for this file (if it has
one).
Send and ControlSend have been enhanced so that you do not need to use the Sleep command to
allow the user time to release the modifier keys (Ctrl/Alt/Shift/Win) with hotkeys that use the Send
command. The Send command knows to change the modifiers to what they need to be for every key
that will be sent.
StringReplace can optionally replace all occurrences, via passing a last parameter "A".
StringGetPos now supports a new optional last parameter. If that parameter is the letter R, the search
will be conducted from the right instead of the left. In other words, the last occurrence will be found
rather than the first.
MsgBox supports a new optional last parameter: Timeout value (in seconds, after which the MsgBox
will close. IfMsgBox will see the value TIMEOUT in this case). For compatibility reasons, this new
parameter is only supported if the script filename doesn't end in .aut.
IniRead supports a new optional last parameter: the default value to put into the output variable if the
command fails for any reason. For compatibility reasons, this new parameter is only supported if the
script filename doesn't end in .aut.
FileSelectFile has been improved with new capabilities.
New Commands and Features
Here are some of the most noteworthy new commands and features:
GUI: Create and manage graphical user interface (GUI) windows and controls. Build your own
professional looking applications and forms without the hassle and complexity of a programming
language.
Menu: Build your own custom menu bars, tray icon menus, and popup menus.
Notes for AutoIt v2 Users
75
Hotkeys: For keyboard, joystick, and mouse.
Hotstrings: Have abbreviations expand automatically as you type them (auto-replace).
DllCall: Call functions inside DLLs, such as standard Windows API functions.
OnMessage: Specifies a function to run automatically when the script receives the specified message
(from the operating system, an external program, or some other script).
SendInput and SendPlay: These are two new methods for sending keystrokes and mouse clicks with
greater speed and reliability. In addition, SendPlay is able to send keystrokes and mouse clicks to a
broader variety of games than other modes.
Progress and SplashImage: Display progress bars and images, with optional accompanying text.
OnExit: Have a subroutine run automatically whenever the script exits. A script can also use this to
detect whether the user is logging off or the system is shutting down.
Process: Performs one of the following operations on a process: checks if it exists; changes its
priority; closes it; waits for it to close.
SoundSet: Changes various settings of a sound device (master mute, master volume, etc.)
SetTimer: Run one or more subroutines automatically at intervals of your choice.
ClipWait: Wait for the clipboard to contain text (become non-empty).
StatusBarWait: Wait for the status bar of a window to contain the specified text, or become blank.
StatusBarGetText: Retrieve text from the status bar.
WinActivateBottom: This command is similar to WinActivate but activates the oldest (bottom-most)
window rather than the newest. If there is only one window that matches, this command will perform
identically to WinActivate.
DriveSpaceFree, DriveGet, and Drive: Retrieves and changes various information about a Drive (e.g.
its free space).
AutoTrim, on/off (defaults to on): When you assign a value to a variable, this controls whether
whitespace is automatically trimmed from the left and right of the string. For this purpose, whitespace
consists of spaces and tabs, but NOT newlines/linefeeds. Thus, I believe the "on" setting yields the
same behavior as AutoIt v2 in this regard.
StringUpper and StringLower: Convert a string to uppercase or lowercase.
ControlFocus, ControlSetText, Control, ControlGet: These and other Control commands operate
directly upon the controls of a window.
SoundPlay: Play virtually any type of media file that the OS supports.
SoundGet, SoundSet, and SoundSetWaveVolume: Retrieves and changes various settings of a sound
device (master mute, master volume, wave volume, etc.)
PixelGetColor and PixelSearch: These commands are capable of detecting the colors of dots on the
screen, which can help respond to the changing state of an application or game.
GetKeyState: Find out whether a key or mouse/joystick button is down or up; find out the position of
a joystick axis; etc.
WinMenuSelectItem: Invoke menu bar items directly, even if the target window isn't active.
#AllowSameLineComments: To increase compatibility with AutoIt v2, scripts that end in .aut are
normally not permitted to have same-line comments (for example: Run, notepad ; this is a comment).
Add the line #AllowSameLineComments to the top of your script to allow them.
#SingleInstance: Specifying this anywhere in a script will prevent new instances of that script from
being launched once there is already one running. Instead, you will be prompted for whether to keep
the original (old) instance or replace it with the new instance.
Printed Documentation
76
#EscapeChar: The escape character is normally "`" but this allows you to change it to AutoIt v2's
escape character (backslash) or some other char of your choice. Note that by default, scripts that end
in .aut will use the backslash for their escape char.
Suspend (and tray menu item of the same name): This function prevents new hotkey subroutines
from launching (it will not halt any subroutines that are already running -- use Pause for that).
Pause (and tray menu item of the same name): Unlike Suspend -- which disables hotkeys entirely --
pause will freeze the currently running subroutine (if none, pause will have no effect).
File loops, registry-loops, and enhanced loops.
The concept of a Window Group is supported. Once defined, a group can be traversed via the
GroupActivate command.
Finally, there are many other new commands, which can be viewed in the alphabetical command list.

77
Command List
Click on a command name for details. Commands in large font are the most commonly used.
Command Description
{ ... }
Denotes a block. Blocks are typically used with functions, Else,
Loop, and IF-commands.
AutoTrim
Determines whether "Var1 = %Var2%" statements omit spaces
and tabs from the beginning and end of Var2.
BlockInput
Disables or enables the user's ability to interact with the
computer via keyboard and mouse.
Break Exits (terminates) a loop. Valid only inside a loop.
Click
Clicks a mouse button at the specified coordinates. It can also
hold down a mouse button, turn the mouse wheel, or move the
mouse.
ClipWait Waits until the clipboard contains data.
Continue
Skips the rest of the current loop iteration and begins a new
one. Valid only inside a loop.
Control Makes a variety of changes to a control.
ControlClick Sends a mouse button or mouse wheel event to a control.
ControlFocus Sets input focus to a given control on a window.
ControlGet Retrieves various types of information about a control.
ControlGetFocus
Retrieves which control of the target window has input focus, if
any.
ControlGetPos Retrieves the position and size of a control.
ControlGetText Retrieves text from a control.
ControlMove Moves or resizes a control.
ControlSend /
ControlSendRaw
Sends simulated keystrokes to a window or control.
ControlSetText Changes the text of a control.
CoordMode
Sets coordinate mode for various commands to be relative to
either the active window or the screen.
Critical
Prevents the current thread from being interrupted by other
threads.
DetectHiddenText
Determines whether invisible text in a window is "seen" for the
purpose of finding the window. This affects commands such as
IfWinExist and WinActivate.
DetectHiddenWindows Determines whether invisible windows are "seen" by the script.
DllCall()
Calls a function inside a DLL, such as a standard Windows API
function.
Drive
Ejects/retracts the tray in a CD or DVD drive, or sets a drive's
volume label.
DriveGet
Retrieves various types of information about the computer's
drive(s).
Printed Documentation
78
DriveSpaceFree Retrieves the free disk space of a drive, in Megabytes.
Edit Opens the current script for editing in the associated editor.
Else
Specifies the command(s) to perform if an IF-statement
evaluates to FALSE. When more than one command is present,
enclose them in a block (braces).
EnvAdd
Sets a variable to the sum of itself plus the given value (can also
add or subtract time from a date-time value). Synonymous with:
var += value
EnvDiv
Sets a variable to itself divided by the given value. Synonymous
with: var /= value
EnvGet Retrieves an environment variable.
EnvMult
Sets a variable to itself times the given value. Synonymous
with: var *= value
EnvSet Writes a value to a variable contained in the environment.
EnvSub
Sets a variable to itself minus the given value (can also compare
date-time values). Synonymous with: var -= value
EnvUpdate
Notifies the OS and all running applications that environment
variable(s) have changed.
Exit
Exits the current thread or (if the script is not persistent
contains no hotkeys) the entire script.
ExitApp Terminates the script unconditionally.
FileAppend Appends text to a file (first creating the file, if necessary).
FileCopy Copies one or more files.
FileCopyDir
Copies a folder along with all its sub-folders and files (similar to
xcopy).
FileCreateDir Creates a folder.
FileCreateShortcut Creates a shortcut (.lnk) file.
FileDelete Deletes one or more files.
FileInstall Includes the specified file inside the compiled script.
FileGetAttrib Reports whether a file or folder is read-only, hidden, etc.
FileGetShortcut
Retrieves information about a shortcut (.lnk) file, such as its
target file.
FileGetSize Retrieves the size of a file.
FileGetTime Retrieves the datetime stamp of a file or folder.
FileGetVersion Retrieves the version of a file.
FileMove Moves or renames one or more files.
FileMoveDir
Moves a folder along with all its sub-folders and files. It can also
rename a folder.
FileRead Reads a file's text into a variable.
FileReadLine
Reads the specified line from a file and stores the text in a
variable.
Alphabetical Command List for AutoHotkey
79
FileRecycle Sends a file or directory to the recycle bin, if possible.
FileRecycleEmpty Empties the recycle bin.
FileRemoveDir Deletes a folder.
FileSelectFile
Displays a standard dialog that allows the user to open or save
file(s).
FileSelectFolder
Displays a standard dialog that allows the user to select a folder.
FileSetAttrib
Changes the attributes of one or more files or folders. Wildcards
are supported.
FileSetTime
Changes the datetime stamp of one or more files or folders.
Wildcards are supported.
FormatTime
Transforms a YYYYMMDDHH24MISS timestamp into the specified
date/time format.
GetKeyState
Checks if a keyboard key or mouse/joystick button is down or
up. Also retrieves joystick status.
Gosub
Jumps to the specified label and continues execution until Return
is encountered.
Goto Jumps to the specified label and continues execution.
GroupActivate
Activates the next window in a window group that was defined
with GroupAdd.
GroupAdd
Adds a window specification to a window group, creating the
group if necessary.
GroupClose
Closes the active window if it was just activated by
GroupActivate or GroupDeactivate. It then activates the next
window in the series. It can also close all windows in a group.
GroupDeactivate
Similar to GroupActivate except activates the next window not
in the group.
GUI
Creates and manages windows and controls. Such windows can
be used as data entry forms or custom user interfaces.
GuiControl Makes a variety of changes to a control in a GUI window.
GuiControlGet
Retrieves various types of information about a control in a GUI
window.
HideAutoItWin, On|Off
[Obsolete -- the following is equivalent: Menu, tray,
NoIcon|Icon]
Hotkey
Creates, modifies, enables, or disables a hotkey while the script
is running.
if
Specifies the command(s) to perform if the comparison of a
variable to a value evalutes to TRUE. When more than one
command is present, enclose them in a block (braces).
if (expression)
Specifies the command(s) to perform if an expression evaluates
to TRUE.
If var [not] between
Checks whether a variable's contents are numerically or
alphabetically between two values (inclusive).
If var [not] in/contains
MatchList
Checks whether a variable's contents match one of the items in
a list.
Printed Documentation
80
If var is [not] type
Checks whether a variable's contents are numeric, uppercase,
etc.
IfEqual/IfNotEqual
Compares a variable to a value for equality. Synonymous with: if
var = value | if var <> value
IfExist / FileExist() Checks for the existence of a file or folder.
IfGreater/IfGreaterOrEqual
Compares a variable to a value. Synonymous with: if var >
value | if var >= value
IfInString / InStr() Checks if a variable contains the specified string.
IfLess/IfLessOrEqual
Compares a variable to a value. Synonymous with: if var <
value | if var <= value
IfMsgBox
Checks which button was pushed by the user during the most
recent MsgBox command.
IfWinActive /
IfWinNotActive
Checks if the specified window exists and is currently active
(foremost).
IfWinExist / IfWinNotExist Checks if the specified window exists.
ImageSearch Searches a region of the screen for an image.
IniDelete Deletes a value from a standard format .ini file.
IniRead Reads a value from a standard format .ini file.
IniWrite Writes a value to a standard format .ini file.
Input
Waits for the user to type a string (not supported on Windows
9x: it does nothing).
InputBox Displays an input box to ask the user to enter a string.
KeyHistory
Displays script info and a history of the most recent keystrokes
and mouse clicks.
KeyWait
Waits for a key or mouse/joystick button to be released or
pressed down.
LeftClick [Obsolete -- use Click for greater flexibility]
LeftClickDrag [Obsolete -- use MouseClickDrag for greater flexibility]
ListHotkeys
Displays the hotkeys in use by the current script, whether their
subroutines are currently running, and whether or not they use
the keyboard or mouse hook.
ListLines Displays the script lines most recently executed.
ListVars
Displays the script's variables: their names and current
contents.
Loop (normal)
Perform a series of commands repeatedly: either the specified
number of times or until break is encountered.
Loop (files & folders) Retrieves the specified files or folders, one at a time.
Loop (parse a string) Retrieves substrings (fields) from a string, one at a time.
Loop (read file contents)
Retrieves the lines in a text file, one at a time (performs better
than FileReadLine).
Loop (registry)
Retrieves the contents of the specified registry subkey, one item
at a time.
Alphabetical Command List for AutoHotkey
81
Menu
Creates, deletes, modifies and displays menus and menu items.
Changes the tray icon and its tooltip. Controls whether the main
window of a compiled script can be opened.
MouseClick
Clicks or holds down a mouse button, or turns the mouse wheel.
NOTE: The Click command is generally more flexible and easier
to use.
MouseClickDrag
Clicks and holds the specified mouse button, moves the mouse
to the destination coordinates, then releases the button.
MouseGetPos
Retrieves the current position of the mouse cursor, and
optionally which window and control it is hovering over.
MouseMove Moves the mouse cursor.
MsgBox
Displays the specified text in a small window containing one or
more buttons (such as Yes and No).
OnExit Specifies a subroutine to run automatically when the script exits.
OnMessage()
Specifies a function to run automatically when the script receives
the specified message.
OutputDebug Sends a string to the debugger (if any) for display.
Pause Pauses the script's current thread.
PixelGetColor
Retrieves the color of the pixel at the specified x,y screen
coordinates.
PixelSearch Searches a region of the screen for a pixel of the specified color.
PostMessage Places a message in the message queue of a window or control.
Process
Performs one of the following operations on a process: checks if
it exists; changes its priority; closes it; waits for it to close.
Progress Creates or updates a window containing a progress bar.
Random Generates a pseudo-random number.
RegExMatch()
Determines whether a string contains a pattern (regular
expression).
RegExReplace()
Replaces occurrences of a pattern (regular expression) inside a
string.
RegDelete Deletes a subkey or value from the registry.
RegRead Reads a value from the registry.
RegWrite Writes a value to the registry.
Reload
Replaces the currently running instance of the script with a new
one.
RepeatEndRepeat [Obsolete -- use Loop for greater flexibility]
Return
Returns from a subroutine to which execution had previously
jumped via function-call, Gosub, Hotkey activation,
GroupActivate, or other means.
RightClick [Obsolete -- use Click for greater flexibility]
RightClickDrag [Obsolete -- use MouseClickDrag for greater flexibility]
Run Runs an external program.
Printed Documentation
82
RunAs
Specifies a set of user credentials to use for all subsequent uses
of Run and RunWait. Requires Windows 2000/XP or later.
RunWait Runs an external program and waits until it finishes.
Send / SendRaw /
SendInput / SendPlay
Sends simulated keystrokes and mouse clicks to the active
window.
SendMessage
Sends a message to a window or control and waits for
acknowledgement.
SendMode
Makes Send synonymous with SendInput or SendPlay rather
than the default (SendEvent). Also makes Click and
MouseMove/Click/Drag use the specified method.
SetBatchLines Determines how fast a script will run (affects CPU utilization).
SetCapslockState
Sets the state of the Capslock key. Can also force the key to
stay on or off.
SetControlDelay
Sets the delay that will occur after each control-modifying
command.
SetDefaultMouseSpeed
Sets the mouse speed that will be used if unspecified in Click
and MouseMove/Click/Drag.
SetFormat
Sets the format of integers and floating point numbers
generated by math operations.
SetKeyDelay
Sets the delay that will occur after each keystroke sent by Send
or ControlSend.
SetMouseDelay
Sets the delay that will occur after each mouse movement or
click.
SetNumlockState
Sets the state of the Numlock key. Can also force the key to
stay on or off.
SetScrollLockState
Sets the state of the Scrolllock key. Can also force the key to
stay on or off.
SetStoreCapslockMode Whether to restore the state of CapsLock after a Send.
SetTimer
Causes a subroutine to be launched automatically and
repeatedly at a specified time interval.
SetTitleMatchMode
Sets the matching behavior of the WinTitle parameter in
commands such as WinWait.
SetWinDelay
Sets the delay that will occur after each windowing command,
such as WinActivate.
SetWorkingDir Changes the script's current working directory.
Shutdown Shuts down, restarts, or logs off the system.
Sleep Waits the specified amount of time before continuing.
Sort
Arranges a variable's contents in alphabetical, numerical, or
random order (optionally removing duplicates).
SoundBeep Emits a tone from the PC speaker.
SoundGet
Retrieves various settings from a sound device (master mute,
master volume, etc.)
SoundGetWaveVolume Retrieves the wave output volume from a sound device.
Alphabetical Command List for AutoHotkey
83
SoundPlay Plays a sound, video, or other supported file type.
SoundSet
Changes various settings of a sound device (master mute,
master volume, etc.)
SoundSetWaveVolume Changes the wave output volume for a sound device.
SplashImage
Creates or updates a window containing a JPG, GIF, or BMP
image.
SplashTextOn Creates a customizable text popup window.
SplashTextOff Closes the above window.
SplitPath
Separates a file name or URL into its name, directory, extension,
and drive.
StatusBarGetText Retrieves the text from a standard status bar control.
StatusBarWait Waits until a window's status bar contains the specified string.
StringCaseSense
Determines whether string comparisons are case sensitive
(default is "not case sensitive").
StringGetPos Retrieves the position of the specified substring within a string.
StringLeft
Retrieves a number of characters from the left-hand side of a
string.
StringLen / StrLen() Retrieves the count of how many characters are in a string.
StringLower Converts a string to lowercase.
StringMid
Retrieves one or more characters from the specified position in a
string.
StringReplace Replaces the specified substring with a new string.
StringRight
Retrieves a number of characters from the right-hand side of a
string.
StringSplit
Separates a string into an array of substrings using the specified
delimiters.
StringTrimLeft
Removes a number of characters from the left-hand side of a
string.
StringTrimRight
Removes a number of characters from the right-hand side of a
string.
StringUpper Converts a string to uppercase.
Suspend Disables or enables all or selected hotkeys.
SysGet
Retrieves screen resolution, multi-monitor info, dimensions of
system objects, and other system properties.
Thread
Sets the priority or interruptibility of threads. It can also
temporarily disable all timers.
ToolTip Creates an always-on-top window anywhere on the screen.
Transform
Performs miscellaneous math functions, bitwise operations, and
tasks such as ASCII/Unicode conversion.
TrayTip
Creates a balloon message window near the tray icon. Requires
Windows 2000/XP or later.
UrlDownloadToFile Downloads a file from the Internet.
Printed Documentation
84
Var = value Assigns the specified value to a variable.
Var := expression Evaluates an expression and stores the result in a variable.
VarSetCapacity()
Enlarges a variable's holding capacity or frees its memory.
Normally, this is necessary only for unusual circumstances such
as DllCall.
WinActivate Activates the specified window (makes it foremost).
WinActivateBottom
Same as WinActivate except that it activates the bottommost
(least recently active) matching window rather than the
topmost.
WinClose Closes the specified window.
WinGetActiveStats
Combines the functions of WinGetActiveTitle and WinGetPos into
one command.
WinGetActiveTitle Retrieves the title of the active window.
WinGetClass Retrieves the specified window's class name.
WinGet
Retrieves the specified window's unique ID, process ID, process
name, or a list of its controls. It can also retrieve a list of all
windows matching the specified criteria.
WinGetPos Retrieves the position and size of the specified window.
WinGetText Retrieves the text from the specified window.
WinGetTitle Retrieves the title of the specified window.
WinHide Hides the specified window.
WinKill Forces the specified window to close.
WinMaximize Enlarges the specified window to its maximum size.
WinMenuSelectItem
Invokes a menu item from the menu bar of the specified
window.
WinMinimize Collapses the specified window into a button on the task bar.
WinMinimizeAll Minimizes all windows.
WinMinimizeAllUndo Reverses the effect of a previous WinMinimizeAll.
WinMove Changes the position and/or size of the specified window.
WinRestore
Unminimizes or unmaximizes the specified window if it is
minimized or maximized.
WinSet
Makes a variety of changes to the specified window, such as
"always on top" and transparency.
WinSetTitle Changes the title of the specified window.
WinShow Unhides the specified window.
WinWait Waits until the specified window exists.
WinWaitActive Waits until the specified window is active.
WinWaitClose Waits until the specified window does not exist.
WinWaitNotActive Waits until the specified window is not active.
#AllowSameLineComments Only for AutoIt v2 (.aut) scripts: Allows a comment to appear on
Alphabetical Command List for AutoHotkey
85
the same line as a command.
#ClipboardTimeout
Changes how long the script keeps trying to access the clipboard
when the first attempt fails.
#CommentFlag
Changes the script's comment symbol from semicolon to some
other string.
#ErrorStdOut
Sends any syntax error that prevents a script from launching to
stdout rather than displaying a dialog.
#EscapeChar
Changes the script's escape character (for example: backslash
vs. accent).
#HotkeyInterval
Along with #MaxHotkeysPerInterval, specifies the rate of hotkey
activations beyond which a warning dialog will be displayed.
#HotkeyModifierTimeout
Affects the behavior of hotkey modifiers: CTRL, ALT, WIN, and
SHIFT.
#Hotstring Changes hotstring options or ending characters.
#IfWinActive / #IfWinExist
Creates context-sensitive hotkeys and hotstrings. Such hotkeys
perform a different action (or none at all) depending on the type
of window that is active or exists.
#Include
Causes the script to behave as though the specified file's
contents are present at this exact position.
#InstallKeybdHook Forces the unconditional installation of the keyboard hook.
#InstallMouseHook Forces the unconditional installation of the mouse hook.
#KeyHistory
Sets the maximum number of keyboard and mouse events
displayed by the KeyHistory window. You can set it to 0 to
disable key history.
#MaxHotkeysPerInterval
Along with #HotkeyInterval, specifies the rate of hotkey
activations beyond which a warning dialog will be displayed.
#MaxMem
Sets the maximum capacity of each variable to the specified
number of megabytes.
#MaxThreads Sets the maximum number of simultaneous threads.
#MaxThreadsBuffer
Causes some or all hotkeys to buffer rather than ignore
keypresses when their #MaxThreadsPerHotkey limit has been
reached.
#MaxThreadsPerHotkey Sets the maximum number of simultaneous threads per hotkey.
#NoEnv
Avoids checking empty variables to see if they are environment
variables (recommended for all new scripts).
#NoTrayIcon Disables the showing of a tray icon.
#Persistent
Keeps a script permanently running (that is, until the user closes
it or ExitApp is encountered).
#SingleInstance
Determines whether a script is allowed to run again when it is
already running.
#UseHook
Forces the use of the hook to implement all or some keyboard
hotkeys.
#WinActivateForce
Skips the gentle method of of activating a window and goes
straight to the forceful method.
Printed Documentation
86


87
AutoHotkey Script Showcase
NiftyWindows -- by Enovatic-Solutions: This script gives you easy control of all basic window
interactions such as dragging, resizing, maximizing, minimizing and closing. Its most powerful feature
is activated by dragging with the right mouse button. Visualize each window divided into a virtual 9-
cell grid with three columns and rows. The center cell is the largest one: you can grab and move a
window around by clicking and holding it with the right mouse button. The other eight cells are used
to resize a window in the same manner. NiftyWindows also offers snap-to-grid, "keep window aspect
ratio", rolling up a window to its title bar, transparency control, and other useful shortcuts.
Screen Magnifier -- by Holomind: This screen magnifier has the several advantages over the one
included with the operating system, including: Customizable refresh interval and zoom level (including
shrink/de-magnify); antialiasing to provide nicer output; and it is open-source (as a result, there are
several variations to choose from, or you can tweak the script yourself).
LiveWindows: Watch Dialog-boxes in Thumbnail -- by Holomind: This script allows you to monitor the
progress of downloads, file-copying, and other dialogs by displaying a small replica of each dialog and
its progress bar (dialogs are automatically detected, even if they're behind other windows). The
preview window stays always-on-top but uses very little screen space (it can also be resized by
dragging its edges). You can also monitor any window by dragging a selection rectangle around the
area of interest (with control-shift-drag), then press Win+W to display that section in the preview
window with real-time updates.
Mouse Gestures -- by deguix: This script watches how you move the mouse whenever the right mouse
button is being held down. If it sees you "draw" a recognized shape or symbol, it will launch a
program or perform another custom action of your choice (just like hotkeys). See the included
README file for how to define gestures.
Context Sensitive Help in Any Editor -- by Rajat: This script makes Ctrl+2 (or another hotkey of your
choice) show the help file page for the selected AutoHotkey command or keyword. If nothing is
selected, the command name will be extracted from the beginning of the current line.
Easy Window Dragging (requires XP/2k/NT): Normally, a window can only be dragged by clicking on
its title bar. This script extends that so that any point inside a window can be dragged. To activate this
mode, hold down CapsLock or the middle mouse button while clicking, then drag the window to a new
position.
Easy Window Dragging -- KDE style (requires XP/2k/NT) -- by Jonny: This script makes it much easier
to move or resize a window: 1) Hold down the ALT key and LEFT-click anywhere inside a window to
drag it to a new location; 2) Hold down ALT and RIGHT-click-drag anywhere inside a window to easily
resize it; 3) Press ALT twice, but before releasing it the second time, left-click to minimize the window
under the mouse cursor, right-click to maximize it, or middle-click to close it.
Easy Access to Favorite Folders -- by Savage: When you click the middle mouse button while certain
types of windows are active, this script displays a menu of your favorite folders. Upon selecting a
favorite, the script will instantly switch to that folder within the active window. The following window
types are supported: 1) Standard file-open or file-save dialogs; 2) Explorer windows; 3) Console
(command prompt) windows. The menu can also be optionally shown for unsupported window types,
in which case the chosen favorite will be opened as a new Explorer window.
IntelliSense -- by Rajat (requires XP/2k/NT): This script watches while you edit an AutoHotkey script.
When it sees you type a command followed by a comma or space, it displays that command's
parameter list to guide you. In addition, you can press Ctrl+F1 (or another hotkey of your choice) to
display that command's page in the help file. To dismiss the parameter list, press Escape or Enter.
Using a Joystick as a Mouse: This script converts a joystick into a three-button mouse. It allows each
button to drag just like a mouse button and it uses virtually no CPU time. Also, it will move the cursor
faster depending on how far you push the joystick from center. You can personalize various settings at
the top of the script.
Joystick Test Script: This script helps determine the button numbers and other attributes of your
joystick. It might also reveal if your joystick is in need of calibration; that is, whether the range of
Printed Documentation
88
motion of each of its axes is from 0 to 100 percent as it should be. If calibration is needed, use the
operating system's control panel or the software that came with your joystick.
On-Screen Keyboard (requires XP/2k/NT) -- by Jon: This script creates a mock keyboard at the
bottom of your screen that shows the keys you are pressing in real time. I made it to help me to learn
to touch-type (to get used to not looking at the keyboard). The size of the on-screen keyboard can be
customized at the top of the script. Also, you can double-click the tray icon to show or hide the
keyboard.
Minimize Window to Tray Menu: This script assigns a hotkey of your choice to hide any window so that
it becomes an entry at the bottom of the script's tray menu. Hidden windows can then be unhidden
individually or all at once by selecting the corresponding item on the menu. If the script exits for any
reason, all the windows that it hid will be unhidden automatically.
Changing MsgBox's Button Names: This is a working example script that uses a timer to change the
names of the buttons in a MsgBox dialog. Although the button names are changed, the IfMsgBox
command still requires that the buttons be referred to by their original names.
Numpad 000 Key: This example script makes the special 000 key that appears on certain keypads into
an equals key. You can change the action by replacing the Send, = line with line(s) of your choice.
Using Keyboard Numpad as a Mouse -- by deguix: This script makes mousing with your keyboard
almost as easy as using a real mouse (maybe even easier for some tasks). It supports up to five
mouse buttons and the turning of the mouse wheel. It also features customizable movement speed,
acceleration, and "axis inversion".
Seek -- by Phi: Navigating the Start Menu can be a hassle, especially if you have installed many
programs over time. 'Seek' lets you specify a case-insensitive key word/phrase that it will use to filter
only the matching programs and directories from the Start Menu, so that you can easily open your
target program from a handful of matched entries. This eliminates the drudgery of searching and
traversing the Start Menu.
ToolTip Mouse Menu (requires XP/2k/NT) -- by Rajat: This script displays a popup menu in response to
briefly holding down the middle mouse button. Select a menu item by left-clicking it. Cancel the menu
by left-clicking outside of it. A recent improvement is that the contents of the menu can change
depending on which type of window is active (Notepad and Word are used as examples here).
Volume On-Screen-Display (OSD) -- by Rajat: This script assigns hotkeys of your choice to raise and
lower the master and/or wave volume. Both volumes are displayed as different color bar graphs.
Window Shading (roll up a window to its title bar) -- by Rajat: This script reduces a window to its title
bar and then back to its original size by pressing a single hotkey. Any number of windows can be
reduced in this fashion (the script remembers each). If the script exits for any reason, all "rolled up"
windows will be automatically restored to their original heights.
WinLIRC Client: This script receives notifications from WinLIRC whenever you press a button on your
remote control. It can be used to automate Winamp, Windows Media Player, etc. It's easy to
configure. For example, if WinLIRC recognizes a button named "VolUp" on your remote control, create
a label named VolUp and beneath it use the command "SoundSet +5" to increase the soundcard's
volume by 5%.
1 Hour Software -- by skrommel: This is a large collection of useful scripts, professionally presented
with short descriptions and screenshots.
Titan's Scripts: This collection includes useful scripts such as:
1) XML Reader/Writer: An easy interface to XML files to retrieve and write values, like JavaScript.
2) Anchor: Keeps GUI controls attached to the right or bottom edge of a resizable GUI window.
3) Functions: A collection of wrapper functions, one for each AutoHotkey command that has an
OutputVar.
4) Weather: Displays the current weather in the tray menu or displays forecasts in a rich GUI.
Toralf's Scripts: This collection includes useful scripts such as:
1) AHK Window Info: Reveals information on windows, controls, etc.
2) Electronic Program Guide: Browses the TV programs/schedules of your region (supports several
countries).
AutoHotkey Script Showcase
89
3) Auto-Syntax-Tidy: Changes indentation and case of commands in a script to give it a consistent
format/style.
Scripts & Functions Forum: This is a searchable collection of nearly 1000 ready-to-run scripts and
functions. Built and maintained by AutoHotkey users, this archive grows and improves daily.
-- Home --

91
Changes & New Features
1.0.45.01 - November 7, 2006
Fixed FileReadLine and FileSelectFile not to crash or misbehave when other threads interrupt them
(broken by 1.0.45). [thanks toralf]
Fixed RegExMatch() so that when there's no match, named subpatterns are properly set to "" in the
output array. [thanks PhiLho]
Fixed RegExMatch()'s "J" option to properly write duplicate named subpatterns to the output array.
[thanks PhiLho]
Changed SetWorkingDir and #Include DirName to succeed even for a root directory such as C: that
lacks a backslash.
Improved DllCall() to display a warning dialog if the called function writes to a variable of zero
capacity.
1.0.45 - November 4, 2006
NOTE: Although this release has been extensively tested and is not expected to break any existing
scripts, several low-level performance enhancements were made. If you have any mission-critical
scripts, it is recommended that you retest them and/or wait a few weeks for any bugs to get fixed.
Added support for regular expressions via RegExMatch(), RegExReplace(), and SetTitleMatchMode
RegEx. [thanks Philip Hazel & PhiLho]
Improved performance and memory utilization of StringReplace.
Improved performance of the := operator for expressions and functions involving long strings.
Improved ControlClick with a new option "NA" that avoids activating the target window (this mode
also improves reliability in some cases). In addition, it's been documented that SetControlDelay -1 can
improve the reliability of ControlClick in some cases. [thanks nnesori]
Changed GUI buttons to default to "no word-wrap" when no width, height, or CR/LF characters were
specified. This may solve button display issues under some desktop themes.
Fixed "Transform HTML" for the following characters: &`n><
Fixed misinterpretation of lines starting with "if not is" such as "if not IsDone".
Fixed inability of "Gui Show" to move a window vertically downward to where its bottommost row of
pixels is now.
Fixed inability to use GroupActivate as the only line beneath an IF or ELSE.
Fixed inability of the Input command to differentiate between end-keys enclosed in braces and their
(un)shifted counterparts; e.g. '{' vs. '['. [thanks Laszlo]
1.0.44.14 - October 2, 2006
NOTE: Although this release has been extensively tested and is not expected to break any existing
scripts, several low-level performance enhancements were made. If you have any mission-critical
scripts, it is recommended that you retest them and/or wait a few weeks for any bugs to get fixed.
Fixed loop-variables like A_Index when accessed in more than one of a line's parameters. The
inaccuracy occurred only when one of those parameters called a function that returned directly from
the body of a loop. [thanks NumEric]
Changed ListVars to display ByRef parameters by their own name rather than the caller's.
Changed the Input command to do nothing on Windows 9x (not even setting ErrorLevel and
OutputVar).
Printed Documentation
92
Raised the limit on the number of GUI fonts from 100 to 200. [thanks philou]
Changed StrLen()/StringLen and internal string-handling to avoid calculating a string's length when
possible. Although this enhances performance (especially for large strings), scripts that use DllCall to
pass a string via the address operator (&) rather than as a str parameter should call
VarSetCapacity(Var, -1) to correct the internally-stored length (if it changed).
Improved performance slightly (above and beyond the StrLen improvement).
1.0.44.13 - September 20, 2006
Fixed ControlGetPos and ControlMove to work with "ahk_id %ControlHWND%". [thanks Hardeep]
Fixed #CommentFlag to affect the line beneath it the same way as other lines. [thanks PhiLho]
Changed A_OSVersion to report Windows Vista as "WIN_VISTA" rather than "".
Added options to set min/max size of GUI windows; for example: Gui +MinSize320x240
+MaxSize640x480
1.0.44.12 - September 13, 2006
Fixed timers interfering with double-clicks in FileSelectFile. [thanks DJAnonimo]
Fixed mouse hook causing a delay when pressing a GUI window's title bar buttons. [thanks Tekl]
Improved GUI windows to have CS_DBLCLKS so that OnMessage() can monitor double clicks via
WM_LBUTTONDBLCLK, WM_RBUTTONDBLCLK, and WM_MBUTTONDBLCLK. [thanks Hardeep]
Improved ListViews to support logical sorting, which treats digits as numbers rather than mere
characters. [thanks Tekl & Hacker]
1.0.44.11 - September 9, 2006
Fixed FileSelectFolder and TreeView to respond properly to mouse clicks when timers are running.
Fixed inability of OnMessage() to consistently monitor certain messages such as WM_NOTIFY. [thanks
numEric]
Fixed inability of literal/quoted strings to contain `%.
Fixed continuation sections to support #EscapeChar, #DerefChar, and #Delimiter. [thanks Laszlo]
Changed GroupBox to default to "no word-wrapping". This can be overridden via +Wrap.
Changed/improved the ** operator and "Transform Pow" to support negative bases when the
exponent isn't fractional. [thanks Laszlo]
Improved GUI responsiveness during UrlDownloadToFile (especially for slow downloads).
1.0.44.10 - August 27, 2006
Fixed OnMessage() when called from inside a monitor function for the purpose of disabling some other
monitor. [thanks Hardeep]
Changed/fixed ImageSearch's TransN option to use RGB vs. BGR as documented. [thanks Tom
Lorimor]
Changed the installer to omit the "Run" verb for .ahk files. The "Open" verb is now the default (with a
new display-name of "Run Script"). [thanks numEric]
1.0.44.09 - August 9, 2006
Fixed hook hotkeys like $^b not to fire twice when a similar, key-up hotkey exists (like "#b up" ).
[thanks Newbie]
Changes & New Features
93
Fixed one too many backspaces in asterisk hotstrings whose next-to-last character is a dead key.
[thanks Henrique]
Fixed "Gui Color" to work after the background color was previously changed to "default". [thanks
Hardeep]
Changed "if var is xdigit" to tolerate a 0x prefix. [thanks Titan]
Added command "Gui +LabelMyGui" to support custom label names (e.g. "MyGuiClose" instead of
"2GuiClose"). This also allows multiple GUI windows to share the same set of labels. [thanks Tekl]
1.0.44.08 - July 25, 2006
Fixed "Gui Show" not to unmaximize a window unless the options require it. [thanks foom]
Fixed GuiControl's +/-Left/Right for buttons, checkboxes, and radios. [thanks Hardeep]
Fixed UpDown creation to widen its buddy only when the buddy had no explicit width. [thanks Thalon]
Improved MsgBox/IfMsgBox to support Cancel/Try Again/Continue, as well as a Help button. [thanks
jballi]
1.0.44.07 - June 17, 2006
Fixed stack overflow when a registry-loop traverses deeply nested subkeys. [thanks Eggi]
Fixed Hotkey command to report ErrorLevel 0 vs. 51 upon success for joystick hotkeys. [thanks
Roland]
Changed ClipboardAll to exclude formats that cause Outlook's MS Word editor to display error dialogs.
[thanks deanhill1971]
Changed and improved UrlDownloadToFile to retrieve the file from the remote server vs. the cache.
There is a new option to override this. [thanks olfen]
Improved remapping to support destination characters that don't exist on the keyboard (such as F1::
in English). [thanks DavidT]
1.0.44.06 - June 8, 2006
Fixed remapping-to-modifier such as F1::Control (broken by 1.0.44.05). [thanks formarx]
1.0.44.05 - June 7, 2006
Fixed mouse movement being off by 1 pixel for coordinates very near 0 (broken by 1.0.43). [thanks
numEric]
Changed and improved remapping-to-modifier (such as F1::Control) to release the modifier during the
script's other uses of Send.
1.0.44.04 - May 31, 2006
Fixed double-colon warning dialog appearing upon launch of certain scripts. (broken by 1.0.44.03)
Fixed combination hotkeys like "a & b" to work even if "b & a" and "b & a up" are also present.
Fixed buddyless UpDown controls to work even if a StatusBar is present. [thanks Titan]
1.0.44.03 - May 29, 2006
Fixed FileExist() to report "X" rather than "" for files whose attributes are all undefined. [thanks Peter]
Fixed Tab controls so that the first Text control added to a new page is auto-positioned correctly even
if the previously added control was a Text control on some other page.
Printed Documentation
94
Fixed ImageSearch so that a transparent color like TransBlack is as effective in variation mode as non-
variation mode. [thanks Troz]
Fixed GetKeyState and KeyWait to accept characters that don't exist in the current keyboard layout (in
case the keyboard layout changes after launching the script).
Fixed hotkeys that don't exist in the current keyboard layout (such as ^!:: in English) to display a
warning and end the auto-execute section. [thanks Androgen Belkin]
Changed and improved ControlSend, Send, Hotstrings, Input, and AltGr handling to use the target
window's language rather than the script's. If you use only one keyboard layout on your system, this
should not affect anything. [thanks Androgen Belkin]
Improved VarSetCapacity() to interpret a capacity of -1 as "update this variable's internally-stored
length". This is useful in cases where a variable has been altered indirectly, such as by passing its
address via DllCall().
1.0.44.02 - May 20, 2006
Fixed hotkeys that use "&" and "~" together (e.g. ~a & b and ~LButton & RButton) (broken by
v1.0.44). [thanks SlimlinE & Spike]
1.0.44.01 - May 15, 2006
Fixed StatusBar's grabbing of UpDowns that are added after it. [thanks Tekl]
Changed Round() to display exactly N decimal places rather than obeying SetFormat.
1.0.44 - May 14, 2006
Fixed OnClipboardChange to work even when the script is displaying a MsgBox or other dialog.
Fixed FileCreateDir not to report ErrorLevel 1 when the specified directory ends in "\". [thanks Wesley]
Fixed hotkeys Control::, Shift::, and Alt:: to fire on release of the key rather than press-down (broken
by v1.0.41).
Fixed loading of icon #1 from nonstandard file types such as .bin.
Fixed ListView creation to obey the text color set by "Gui Font".
Changed and fixed the hotkey tilde prefix (~) so that hotkeys like ~Esc and Esc are considered
duplicates; that is, a script cannot define both ~Esc and Esc unless they are under different #IfWin
criteria (in which case ~Esc and Esc have been fixed to work properly). [thanks jballi]
Changed and improved ListViews: 1) a new option WantF2 is in effect by default, which causes an F2
keystroke to edit the current row (when not ReadOnly); 2) added LV_Modify(Row, "Vis") to scroll an
item into view; 3) drag notifications occur even without AltSubmit; 4) item-change notifications have
A_EventInfo set to the row number; 5) ErrorLevel no longer mirrors A_EventInfo in cases where it was
never documented to do so (same for GuiContextMenu).
Improved Edit controls to select all text in response to Control-A. This can be disabled via -WantCtrlA.
Added new GUI control types TreeView and StatusBar.
1.0.43.11 - May 1, 2006
Fixed %A_WorkingDir% on Windows 9x, which was sometimes blank. [thanks Points]
Improved BlockInput with a new mode that blocks only physical movement of the mouse, not
keystrokes or mouse clicks.
1.0.43.10 - April 28, 2006
Improved PixelGetColor with two alternate modes that work in a broader variety of windows and full-
screen apps. [thanks TDMedia]
Changes & New Features
95
Improved StringMid to allow "Count" to be omitted to retrieve all characters. [thanks kapege.de]
Improved FileSelectFile to support special folders such as My Computer via CLSID strings
(FileSelectFolder and Run already support them).
1.0.43.09 - April 25, 2006
Fixed SendInput not to revert to SendEvent merely because another script has a mouse hook. Only
another keyboard hook should do that. [thanks baby-luck]
Fixed LV_GetCount() to work even if the "C" in its name is lowercase.
Changed FileSelectFile to navigate/follow shortcuts (.lnk files) rather than selecting them. There is
also a new option to override this. [thanks Veovis & PhiLho]
Added "Gui +LastFoundExist" to detect the existence of a GUI window. [thanks Tekl & Evl]
Added built-in variables A_AppData, A_AppDataCommon, and A_Temp (A_Temp is the folder
designated to hold temporary files).
1.0.43.08 - April 17, 2006
Changed SendInput to use "SetKeyDelay -1, 0" when it reverts to SendEvent mode (unless
SendEvent's KeyDelay "-1,-1", in which case "-1,-1" is used).
Added directive #NoEnv, which is recommended for all new scripts because:
1. It significantly improves performance whenever empty variables are used in an expression or
command. It also improves DllCall's performance when unquoted parameter types are used
(e.g. int vs. "int").
2. It prevents script bugs caused by environment variables whose names unexpectedly match
variables used by the script.
A future version of AutoHotkey such as 1.1 might make this behavior the default (though such a
change is not expected for at least a year).
Added built-in variables ComSpec and ProgramFiles to ease the transition to #NoEnv.
Added command EnvGet, which retrieves an environment variable.
1.0.43.07 - April 12, 2006
Fixed inability of "Menu, Tray, Icon" to load icon #1 from file types cpl/scr/drv/ocx/vbx/acm/bpl
(broken by 1.0.43.03). Similarly, all icon-capable features have been improved to support these file
types. [thanks Winkie & PhiLho]
Fixed the following legacy commands to accept function-calls containing commas: EnvAdd/Sub,
LeftClick(Drag), RightClick(Drag). [thanks Titan]
1.0.43.06 - April 9, 2006
Changed ahk_id to operate directly on the specified HWND when it's a control (child). Previously, it
operated upon the topmost sub-control if that control had any sub-controls.
Improved Post/SendMessage to fully support strings put into address variables by the receiver (e.g.
PostMessage, Msg, &MyVar).
Improved support for control HWND as an alternative to control ClassNN: 1) Added a MouseGetPos
option to retrieve control HWND; 2) Added "WinGet ControlListHwnd" to retrieve a list of control
HWNDs; 3) Added "ControlGet Hwnd" to retrieve the HWND that corresponds to a control's ClassNN or
text.
Added "GuiControlGet FocusV", which gets the focused control's variable name rather than its
ClassNN.
Printed Documentation
96
1.0.43.05 - April 7, 2006
Fixed and improved support for .ICL files (icon libraries), which was broken by 1.0.43.03. [thanks
Tekl]
Changed case sensitivity in hotkey names back to pre-1.0.43.03 behavior: high ANSI letters like and
are treated as different hotkeys than their lowercase counterparts. [thanks copa017]
1.0.43.04 - April 4, 2006
Fixed crash of characters above Chr(127) in hotstring abbreviations and the locale-search-from-right
mode of InStr() and StringGetPos (broken by 1.0.43.03). [thanks PhiLho & brotherS]
1.0.43.03 - April 3, 2006
Fixed distortion of 16x16 icons loaded via ahk2exe or Menu, Tray, Icon. [thanks Tekl]
Fixed the following to ignore #MaxMem as documented: VarSetCapacity(), FileRead, ClipboardAll, and
ControlGet (ListView). [thanks Dippy46]
Changed the following to use locale case insensitivity vs. "A-Z only" insensitivity: hotkey names,
hotstring abbreviations, menu names, Input's MatchList, and Gui Tab.
Changed the expression equal operator (=) and the case-insensitive InStr() to use locale case
insensitivity when StringCaseSense is Locale or On.
Improved StringCaseSense with a new option Locale that makes string comparisons case insensitive
according to the rules of the current user's locale. For example, most English and Western European
locales treat the letters A-Z and ANSI letters like and as identical to their lowercase counterparts.
[thanks Boskoop & PhiLho]
Improved the Sort command and ListView sorting with a locale-case-insensitive option.
Improved mouse wheel hotkeys (WheelDown/Up) to report the number of wheel turns in A_EventInfo,
which allows distinguishing between fast and slow wheel movement. [thanks evl]
Improved FileRead with an option to read only the leading part of a file. [thanks Dippy46]
1.0.43.02 - March 30, 2006
Fixed raw-mode hotstrings not to send the extra string {Raw} (broken by 1.0.43). [thanks stom2006]
Changed SendMode: 1) renamed InputThenEvent to Input; 2) added InputThenPlay, which is the
same behavior as the former "Input". This was done because SendEvent is less likely to cause
compatibility problems than SendPlay.
1.0.43.01 - March 29, 2006
Fixed mouse clicking at unspecified coordinates in particular apps; e.g. Send {LButton} (broken by
1.0.43). [thanks incith]
Fixed tilde hotkeys so that if they remove a hook, their own key doesn't get stuck down (e.g. Mouse
Gestures script and ~LCtrl::Hotkey, RButton, Off). [thanks Stefan Taubenberger]
1.0.43 - March 25, 2006
NOTE: Although this release has been extensively tested and is not expected to break any existing
scripts, several changes were made to the sending of keystrokes and mouse clicks. If you have any
mission-critical scripts that rely on such features, it is recommended that they be re-tested or that you
wait two weeks for any bugs to get fixed.
Fixed AltGr hotkeys that use Send, such as <^>!m::Send ^c. Also fixed AltGr remappings such as
F1::RAlt [thanks foxer]
Fixed inability of VarSetCapacity to free the memory of a ByRef parameter. [thanks corrupt]
Changes & New Features
97
Fixed hotstring option b0 to show the ending character where you typed it rather than at the end of
the replacement.
Improved the speed and reliability of auto-replace hotstrings by defaulting them to SendInput mode.
There is also a new hotstring option to change the sending mode.
Improved the reliability of mouse clicks/drags in cases where the user is physically moving the mouse
during the event.
Added commands Click and Send {Click}, which are easier to use than MouseClick. They also
compensate if the left/right mouse buttons have been swapped via the control panel.
Added command SendMode, which makes Send synonymous with SendInput or SendPlay rather than
the default (SendEvent). It also makes Click and MouseMove/Click/Drag use the specified method.
Added two new methods for sending keystrokes and mouse clicks: SendInput and SendPlay. These are
generally faster and more reliable. Also, SendPlay allows keystrokes and hotstrings to be accepted by
a broader variety of games.
1.0.42.07 - March 9, 2006
Fixed crash of functions that recursively pass ByRef parameters. [thanks PhiLho]
1.0.42.06 - March 7, 2006
Fixed crash of A_ScriptDir (broken by 1.0.42.01).
Fixed Run/RunWait's passing of an extra space character at the end of the parameter list when
launching shortcuts. [thanks arbe]
1.0.42.05 - March 6, 2006
This is functionally identical to the previous release. The previous release's EXE and BIN were about
1% larger than they should have been due to a compiler quirk.
1.0.42.04 - March 6, 2006
Fixed ClipboardAll when used with apps such as Word and Excel (broken by previous version). [thanks
Roussi Nikolov]
Fixed ClipboardAll to prevent appearance of bookmarks in MS Word. [thanks Laszlo & 02clams]
Fixed A_TimeIdlePhysical being disrupted by simulated AltGr keystrokes. [thanks skrommel]
Fixed Send {Blind} causing sticking Win/Ctrl/Alt/Shift when the user released such a key in the middle
of a Send.
Improved the Send command not to press and release the shift key after each uppercase letter (e.g.
Send ABC).
Improved SoundSet/Get to support ComponentType "Headphones". [thanks Tobias Winkler]
1.0.42.03 - February 20, 2006
Fixed crash of WinActivate in certain rare circumstances. [thanks twhyman]
Changed hotstrings to require the mouse hook by default (see next item). This can be prevented via
#Hotstring NoMouse.
Improved hotstrings to take into account mouse clicks. This allows a hotstring to fire when the user's
click focuses a new control or moves the caret.
Improved the Random command with a means to set a new seed. [thanks Laszlo]
Improved #ClipboardTimeout to reattempt data reading when the first attempt fails. Previously, only
the opening of the clipboard was reattempted.
Printed Documentation
98
Added built-in variable A_LastError for DllCall and Run/RunWait. It contains the result from the OS's
GetLastError().
1.0.42.02 - February 17, 2006
Fixed UpDown controls to snap onto the right control when inside a Tab control that contains a
ListView. [thanks Thalon]
Improved the Hotkey command with an "Off" option (typically used to create a hotkey in an initially-
disabled state).
Improved A_Cursor not to interfere with double-clicking. [thanks Shimanov]
1.0.42.01 - February 15, 2006
Fixed the following variables to work correctly when concatenated onto other strings:
A_DetectHiddenWindows, A_DetectHiddenText, A_AutoTrim, and A_StringCaseSense. [thanks jballi]
Fixed KeyWait and GetKeyState in the subroutines of hook hotkeys (broken by 1.0.39) [thanks Laszlo
& TobStro]. For example:
~LControl::
if not GetKeyState("LControl")
ToolTip LControl is not down as expected (this bug affected some systems but not others).
return
1.0.42 - February 10, 2006
Fixed expressions such as "If not Installed" not to be misinterpreted as "If not in List". [thanks Toralf]
Fixed certain unusual situations where a hotkey would unnecessarily require the keyboard hook.
Fixed vkNNN hotkeys to be handled by the hook when that VK is also used as a prefix for other
hotkeys.
Fixed #IfWin's automatic disabling of prefix keys to work properly when Suspend is ON.
Fixed minor hotkey issues on Windows 95/98/Me: 1) The wildcard prefix (*) is ignored and such
hotkeys are put into effect rather than being disabled; 2) Non-wildcard hotkeys that are a subset of a
wildcard hotkey are put into effect rather than being disabled; 3) A left/right hotkey such as >#x is
put into effect as Win-X rather than simply "X".
Changed the Hotkey command to create a new variant (when appropriate) rather than always
updating any existing hotkey of that name. This only affects scripts that use v1.0.41's #IfWin
directive.
Changed hotkeys to recognize ^!c as being the same as !^c (different symbol order). This also affects
the Hotkey command.
Improved the Hotkey command to support UseErrorLevel and context-sensitive hotkeys (via "Hotkey
IfWinActive/Exist").
Improved #IfWinActive/Exist to support Windows 9x. In addition, the keyboard hook is now avoided
whenever possible. Finally, #IfWin now sets the Last Found Window.
Improved the following commands to support TListBox/TComboBox and possibly others: Control
(Add/Delete/Choose/ChooseString); and ControlGet (FindString/Choice/List).
Added support for hotkey and hotstring variants (duplicates). Such hotkeys perform a different action
(or none at all) depending on the type of window that is active or exists.
Changes & New Features
99
1.0.41.02 - February 1, 2006
Changed "GuiControl Move" to reduce flickering when resizing or moving controls [thanks Serenity].
However, this may cause painting artifacts for some control types under certain circumstances. If so,
please update your scripts to use GuiControl MoveDraw instead.
1.0.41.01 - January 31, 2006
Fixed AltGr hotkeys that send AltGr characters such as "<^>!a::Send \" in German. [thanks AGU]
Fixed Gui +Disable/AlwaysOnTop to work even if other options are present on the same line. [thanks
evl]
Improved syntax to support having a command on the same line as an open-brace. [thanks segfault]
1.0.41 - January 19, 2006
Fixed "Transform HTML", which was broken by v1.0.40.02. [thanks Rabiator]
Improved syntax to support One True Brace (OTB) style with IFs, ELSEs, functions, and normal loops.
Added built-in variable A_AhkPath, which contains the full path and name of AutoHotkey.exe (if
available).
Added directives #IfWinActive/Exist to make selected hotkeys and hotstrings active only in the
windows you specify.
1.0.40.12 - January 11, 2006
Fixed memory leak when GuiControl loaded some types of images into a Picture control. [thanks
beardboy]
Fixed inability of ToolTip to reappear after it was destroyed externally via Alt-F4, WinClose, etc.
1.0.40.11 - December 12, 2005
Fixed "GuiControl, %Var%" when Var is blank or contains only a window number. It now updates the
control's contents rather than doing nothing. [thanks MisterW]
Scripts in UTF-8 format can now be loaded (BOM bytes "EF BB BF" at start of file). [thanks D. J.
Rausch]
1.0.40.10 - December 1, 2005
Improved ImageSearch and the fast-mode PixelSearch to support 256-color screens (8-bit).
1.0.40.09 - November 21, 2005
Fixed hotkeys such as ^q to trigger the "*q up" hotkey upon release instead of the ^q hotkey a
second time.
1.0.40.08 - November 16, 2005
Fixed ComboBoxes to yield the proper selection when: 1) GuiControl altered the Edit field; or 2) the
user manually typed a matching item into an AltSubmit ComboBox. [thanks Tekl]
1.0.40.07 - November 16, 2005
Fixed memory leak when a script called a function recursively. [thanks Laszlo]
1.0.40.06 - November 10, 2005
Fixed crash of abs() when called with an empty string. [thanks Laszlo]
Printed Documentation
100
Fixed the number -0x8000000000000000 in expressions. [thanks Laszlo]
1.0.40.05 - November 4, 2005
Fixed Ceil(), Floor(), and "Transform Ceil/Floor" to give the correct answers for all inputs. [thanks
Litmus Red]
Fixed remapping so that "Enter" can be a destination key. [thanks jocamero]
Changed ahk_id to work on hidden child windows (controls) without the need for
DetectHiddenWindows.
Improved Post/SendMessage to accept quoted/literal strings for wParam/lParam.
1.0.40.04 - November 2, 2005
Fixed WinGetText and ControlGetText to work on apps that respond incorrectly to WM_GETTEXT (such
as AIM). [thanks Yarbuck]
Changed the program to align all data on 32-bit boundaries, which solves DllCall structure issues.
[thanks Shimanov]
1.0.40.03 - October 26, 2005
Because some other solution is necessary, the 1-pixel increase for Checkboxes and Radio Buttons in
v1.0.40.01 has been undone.
1.0.40.02 - October 24, 2005
Fixed "Transform Unicode" to be able to produce a Unicode string whose first byte is zero. [thanks
Shimanov & Laudrin]
Reduced the size of compiled scripts by 20 KB by having the compiler minimize code size in sections
that don't affect script performance.
1.0.40.01 - October 21, 2005
Fixed the title bars of script-owned windows to respond correctly to left and right down-clicks
generated by the script's own hotkeys. [thanks Shimanov]
Fixed inability of OnMessage to consistently monitor certain messages such as WM_GETMINMAXINFO.
Changed Critical to be temporarily off during MsgBox and other dialogs.
Added command "Thread NoTimers", which prevents a thread from being interrupted by timers.

CHANGES FOR GUI
Fixed GuiContextMenu's A_GuiControl to be accurate for Text and Picture controls inside a GroupBox
or Tab control.
Fixed GuiControl to properly redraw Picture controls and transparent Text controls when they are
given new contents.
Increased the width of auto-sized Checkboxes and Radio Buttons by 1 pixel to prevent wrapping on
certain desktop themes.
1.0.40 - October 11, 2005
Fixed the v1.0.39 mouse and keyboard hooks so that failure to activate them behaves correctly.
Changed the Send command for Russian and other keyboard layouts to be able to produce more
ASCII characters (such as the letters A to Z). This does not affect most Western European and English
layouts.
Changes & New Features
101
Changed hotkeys that are a subset of a wildcard hotkey to take precedence. For example, if *x and ^x
are both hotkeys, pressing ^x will now trigger ^x rather than *x.
Improved syntax so that double colons do not need to be escaped.
Improved Send and ControlSend with option {Blind}, which leaves Ctrl/Alt/Shift/Win pressed down if
they started that way.
Added a new remapping method that is more simple and powerful than the old methods. For example:
a::b ; Make the "a" key become "b".
Capslock::Ctrl ; Make Capslock become a Control key.
XButton1::LButton ; Make the fourth mouse button behave like the left mouse button.
RCtrl::RWin ; Make the right Control key become the right Windows key.
1.0.39 - October 3, 2005
The last change below may impact scripts that use the keyboard or mouse hook. If you have any
mission-critical scripts that rely on them, it is recommended that they be re-tested or that you wait
two weeks for any bugs to get fixed.
Fixed inability to have lines consisting entirely of spaces and tabs in continuation sections. [thanks
JSLover]
Fixed hotkeys such as "LButton & LCtrl" to auto-install the mouse hook. [thanks JSLover]
Added a dedicated thread to service the keyboard and mouse hooks. This eliminates mouse/keyboard
lag during long operations such as UrlDownloadToFile. It also prevents keys from getting "stuck
down". The new thread consumes only 36 KB of memory and it exists only in scripts that use the
hooks.
1.0.38.06 - September 27, 2005
Some optimizations were made to the keyboard and mouse hooks. If you have any mission-critical
scripts that rely on them, it is recommended that they be re-tested or that you wait two weeks for any
bugs to get fixed.
Fixed continuation lines that start with "AND" and "OR" to work even when the next character is in the
set "()!~*&-+". [thanks Decarlo110]
Fixed hotkeys/labels such as "(::" and "(MyLabel):" not to be misinterpreted as continuation sections.
[thanks whismerhill]
1.0.38.05 - September 23, 2005
Fixed "Menu Show" (broken in the previous version) to call the selected menu item's subroutine prior
to executing the command beneath "Menu Show". [thanks Roussi]
1.0.38.04 - September 21, 2005
Fixed hotstring reset option (Z), which could crash a script. [thanks arbe]
Improved threads to reduce the chance of an interruption occurring before even a single line can
execute. [thanks Paul Haines]
Added command Critical, which prevents the current thread from being interrupted by other threads.
It also buffers incoming events until the critical thread ends.
1.0.38.03 - September 12, 2005
Fixed key-up hotkeys so that having both a wildcard and a non-wildcard version of the same hotkey
works even when the non-wildcard down-hotkey is defined before the non-wildcard up-hotkey.
[thanks Paul Haines]
Printed Documentation
102
Improved Edit controls with the option "WantTab", which allows the tab keystroke to produce a tab
character.
1.0.38.02 - September 8, 2005
Fixed inability of "WinSet Region" to accept a negative X-coordinate.
Fixed radio buttons to start a new radio group for each new tab control or page. [thanks Toralf]
Changed VK hotkeys such as "^VK24::" to avoid the use of the keyboard hook when possible. As a
side-effect, such hotkeys are now triggered by any key that has the specified virtual key (e.g. both
Home and NumpadHome for VK24). [thanks Orion]
Improved the Hotkey command with option "On" to change a hotkey's label and enable it in one step.
[thanks Toralf]
Improved "GuiControl Disable/Enable/Hide/Show" to recognize an optional 1 or 0 suffix to simplify
scripts. [thanks Toralf]
1.0.38.01 - September 5, 2005
Fixed GuiContextMenu's A_GuiControl to be non-blank when the user right-clicks a Text, Picture, or
Tab control.
Changed OnMessage() to receive LPARAM as an unsigned vs. signed number.
1.0.38 - September 3, 2005
Fixed the Input command to properly capture keystrokes sent by a hotkey or hotstring for which the
user is physically holding down SHIFT, CTRL, ALT, or WIN. [thanks wildfire]
Changed "GuiControl, Text" to set the text of a ComboBox's Edit control rather than new choices for
its drop-list. Please update your scripts accordingly.
Improved FileMoveDir with an option to unconditionally overwrite the target folder.
Added built-in function IsLabel(), which verifies that a label exists before you Gosub it. [thanks Tekl]
Added built-in function OnMessage(), which can receive custom messages and monitor system
messages.
Added a WinLIRC client script that responds to signals from a hand-held remote control. WinLIRC is an
open-source utility that captures infrared signals from virtually any brand of remote control.

Visit http://www.autohotkey.com/changelog/ for the older changes and a list of planned features.

103
Environment Management
ClipWait
Waits until the clipboard contains data.
ClipWait [, SecondsToWait, 1]
Parameters
SecondsToWait
If omitted, the command will wait indefinitely. Otherwise, it will wait no
longer than this many seconds (can contain a decimal point or be an
expression). Specifying 0 is the same as specifying 0.5.
1
If this parameter is omitted, the command is more selective, waiting
specifically for text or files to appear ("text" includes anything that would
produce text when you paste into Notepad). If this parameter is 1 (can be
an expression), the command waits for data of any kind to appear on the
clipboard.
ErrorLevel
If the wait period expires, ErrorLevel will be set to 1. Otherwise (i.e. the clipboard contains data),
ErrorLevel is set to 0.
Remarks
It's better to use this command than a loop of your own that checks to see if this clipboard is blank.
This is because the clipboard is never opened by this command, and thus it performs better and
avoids any chance of interfering with another application that may be using the clipboard.
This command considers anything convertible to text (e.g. HTML) to be text. It also considers files,
such as those copied in an Explorer window via Control-C, to be text. Such files are automatically
converted to their filenames (with full path) whenever the clipboard variable (%clipboard%) is
referred to in the script. See Clipboard for details.
When 1 is present as the last parameter, the command will be satisified when any data appears on the
clipboard. This can be used in conjunction with ClipboardAll to save non-textual items such as
pictures.
While the command is in a waiting state, new threads can be launched via hotkey, custom menu item,
or timer.
Related
Clipboard, WinWait, KeyWait
Example
clipboard = ; Empty the clipboard
Send, ^c
ClipWait, 2
if ErrorLevel
{
MsgBox, The attempt to copy text onto the clipboard failed.
return
Printed Documentation
104
}
MsgBox, clipboard = %clipboard%
return
EnvGet [v1.0.43.08+]
Retrieves an environment variable.
EnvGet, OutputVar, EnvVarName
Parameters
OutputVar The name of the variable in which to store the string.
EnvVarName
The name of the environment variable to retrieve. For example: EnvGet,
OutputVar, Path
Remarks
If the specified environment variable is empty or does not exist, OutputVar is made blank.
The operating system limits each environment variable to 32 KB of text.
Related
EnvSet, #NoEnv, environment variables, EnvUpdate, SetEnv, Run, RunWait
Example
EnvGet, OutputVar, LogonServer
EnvSet
Writes a value to a variable contained in the environment.
EnvSet, EnvVar, Value
Parameters
EnvVar Name of the environment variable to use, e.g. "COMSPEC" or "PATH".
Value Value to set the environment variable to.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
The operating system limits each environment variable to 32 KB of text.
An environment variable created or changed with this command will be accessible only to programs
the script launches via Run or RunWait. See environment variables for more details.
This command exists separately from SetEnv because normal script variables are not stored in the
environment. This is because performance would be worse and also because the OS limits
environment variables to 32 KB.
Related
EnvGet, #NoEnv, environment variables, EnvUpdate, SetEnv, Run, RunWait
Environment Management
105
Example
EnvSet, AutGUI, Some text to put in the variable.
EnvUpdate
Notifies the OS and all running applications that environment variable(s) have changed.
EnvUpdate
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
Refreshes the OS environment. Similar effect as logging off and then on again.
For example, after making changes to the following registry key on Windows NT/2000/XP, EnvUpdate
could be used to broadcast the change:
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Session
Manager\Environment
Related
EnvSet, RegWrite
Example
EnvUpdate

107
File, Directory, and Disk Management
Drive
Ejects/retracts the tray in a CD or DVD drive, or sets a drive's volume label.
Drive, Sub-command [, Drive , Value]
The sub-command, drive, and value parameters are dependent upon each other and their usage is
described below.
Label, Drive [, NewLabel]: Changes Drive's volume label to be NewLabel (if NewLabel is omitted,
the drive will have no label). Drive is the drive letter followed by a colon and an optional backslash
(might also work on UNCs and mapped drives). For example: Drive, Label, C:, Seagate200
To retrieve the current label, follow this example: DriveGet, OutputVar, Label, C:

Lock, Drive: Prevents a drive's eject feature from working. For example: "Drive, Lock, D:". Most
drives cannot be "locked open". However, locking the drive while it is open will probably result in it
becoming locked the moment it is closed. This command has no effect on drives that do not support
locking (such as most read-only drives), nor is it likely to work on non-IDE drives on Windows
95/98/Me. If a drive is locked by a script and that script exits, the drive will stay locked until another
script or program unlocks it, or the system is restarted. If the specified drive does not exist or does
not support the locking feature, ErrorLevel is set to 1. Otherwise, it is set to 0.

Unlock, Drive: Reverses the above. On Window NT/2000/XP or later, Unlock needs to be executed
multiple times if the drive was locked multiple times (at least for some drives). For example, if "Drive,
Lock, D:" was executed three times, three executions of "Drive, Unlock, D:" might be needed to
unlock it. Because of this and the fact that there is no way to determine whether a drive is currently
locked, it is often useful to keep track of its lock-state in a variable.

Eject [, Drive, 1]: Ejects or retracts the tray of a CD or DVD drive (to eject other types of media or
devices, see the DllCall example at the bottom of this page).
if Drive is omitted, the default CD/DVD drive will be used). To eject the tray, omit the last parameter.
To retract/close the tray, specify 1 for the last parameter; for example: Drive, Eject, D:, 1
Drive Eject waits for the ejection or retraction to complete before allowing the script to continue. If the
tray is already in the correct state (open or closed), ErrorLevel is set to 0 (i.e. "no error").
Drive Eject will probably not work on a network drive or non-CD/DVD drive. If it fails in such cases or
for any other reason, ErrorLevel is set to 1.
It may be possible to detect the previous tray state by measuring the time the command takes to
complete. For example, the following hotkey toggles the tray to the opposite state (open or closed):
#c::
Drive, Eject
; If the command completed quickly, the tray was probably already ejected.
; In that case, retract it:
if A_TimeSinceThisHotkey < 1000 ; Adjust this time if needed.
Drive, Eject,, 1
return
To determine the media status of a CD or DVD drive (playing, stopped, open, etc.), see DriveGet.
Printed Documentation
108
ErrorLevel
ErrorLevel is set to 1 of there was a problem or 0 otherwise.
Remarks
The following is an alternate ejection method that also works on types of media/devices other than
CD/DVD:
; Update the first line below to match the desired drive letter (you can ignore all the other
lines below).
Driveletter = I: ; Set this to the drive letter you wish to eject.

hVolume := DllCall("CreateFile"
, Str, "\\.\" . Driveletter
, UInt, 0x80000000 | 0x40000000 ; GENERIC_READ | GENERIC_WRITE
, UInt, 0x1 | 0x2 ; FILE_SHARE_READ | FILE_SHARE_WRITE
, UInt, 0
, UInt, 0x3 ; OPEN_EXISTING
, UInt, 0, UInt, 0)
if hVolume <> -1
{
DllCall("DeviceIoControl"
, UInt, hVolume
, UInt, 0x2D4808 ; IOCTL_STORAGE_EJECT_MEDIA
, UInt, 0, UInt, 0, UInt, 0, UInt, 0
, UIntP, dwBytesReturned ; Unused.
, UInt, 0)
DllCall("CloseHandle", UInt, hVolume)
}
Related
DriveGet, DriveSpaceFree
Example
Drive, Label, D:, BackupDrive
Drive, Eject,, 1 ; Retract (close) the tray of the default CD or DVD drive.
DriveGet
Retrieves various types of information about the computer's drive(s).
DriveGet, OutputVar, Cmd [, Value]
Parameters
File, Directory, and Disk Management
109
OutputVar
The name of the variable in which to store the result of Cmd.
Cmd, Value See list below.
Cmd, Value
The Cmd and Value parameters are dependent upon each other and their usage is described below. If
a problem is encountered OutputVar is made blank and ErrorLevel is set to 1.
List [, Type] : Sets OutputVar to be a string of letters, one character for each drive letter in the
system. For example: ACDEZ. If Type is omitted, all drive types are retrieved. Otherwise, Type should
be one of the following words to retrieve only a specific type of drive: CDROM, REMOVABLE, FIXED,
NETWORK, RAMDISK, UNKNOWN.
Capacity (or Cap), Path: Retrieves the total capacity of Path (e.g. C:\) in megabytes. Use
DriveSpaceFree to determine the free space.
Filesystem (or FS), Drive : Retrieves the type of Drive's file system, where Drive is the drive letter
followed by a colon and an optional backslash, or a UNC name such \\server1\share1. OutputVar will
be set to one of the following words: FAT, FAT32, NTFS, CDFS (typically indicates a CD), UDF
(typically indicates a DVD). OutputVar will be made blank and ErrorLevel set to 1 if the drive does not
contain formatted media.
Label, Drive: Retrieves Drive's volume label, where Drive is the drive letter followed by a colon and
an optional backslash, or a UNC name such \\server1\share1. To change the label, follow this
example: Drive, Label, C:, MyLabel
Serial, Drive: Retrieves Drive's volume serial number expressed as decimal integer, where Drive is
the drive letter followed by a colon and an optional backslash, or a UNC name such \\server1\share1.
See SetFormat for how to convert it to hexadecimal.
Type, Path: Retrieves Path's drive type, which is one of the following words: Unknown, Removable,
Fixed, Network, CDROM, RAMDisk.
Status, Path: Retrieves Path's status, which is one of the following words: Unknown (might indicate
unformatted/RAW), Ready, NotReady (typical for removable drives that don't contain media), Invalid
(Path does not exist or is a network drive that is presently inaccessible, etc.)
StatusCD [, Drive]: Retrieves the media status of a CD or DVD drive, where Drive is the drive letter
followed by a colon (if Drive is omitted, the default CD/DVD drive will be used). OutputVar is made
blank if the status cannot be determined. Otherwise, it is set to one of the following strings:
not ready
The drive is not ready to be accessed, perhaps due to being engaged in a write
operation. Known limitation: "not ready" also occurs when the drive contains a
DVD rather than a CD.
open The drive contains no disc, or the tray is ejected.
playing The drive is playing a disc.
paused The previously playing audio or video is now paused.
seeking The drive is seeking.
stopped The drive contains a CD but is not currently accessing it.
This command will probably not work on a network drive or non-CD/DVD drive; if it fails in such cases
or for any other reason, OutputVar is made blank and ErrorLevel is set to 1.
If the tray was recently closed, there may be a delay before the command completes.
To eject or retract the tray, see the Drive command.
ErrorLevel
Printed Documentation
110
ErrorLevel is set to 1 of there was a problem or 0 otherwise.
Remarks
Some of the commands will accept a network share name as Path, such as \\MyServer\MyShare\
Related
Drive, DriveSpaceFree
Example
; This is a working example script.
FileSelectFolder, folder, , 3, Pick a drive to analyze:
if folder =
return
DriveGet, list, list
DriveGet, cap, capacity, %folder%
DrivespaceFree, free, %folder%
DriveGet, fs, fs, %folder%
DriveGet, label, label, %folder%
DriveGet, serial, serial, %folder%
DriveGet, type, type, %folder%
DriveGet, status, status, %folder%
MsgBox All Drives: %list%`nSelected Drive: %folder%`nDrive Type: %type%`nStatus:
%status%`nCapacity: %cap% M`nFree Space: %free% M`nFilesystem: %fs%`nVolume Label:
%label%`nSerial Number: %serial%
DriveSpaceFree
Retrieves the free disk space of a drive, in Megabytes.
DriveSpaceFree, OutputVar, Path
Parameters
OutputVar
The variable in which to store the result, which is rounded down to the nearest
whole number.
path
Path of drive to receive information from. Since NTFS supports mounted
volumes and directory junctions, different amounts of free space might be
available in different folders of the same "drive" in some cases.
Remarks
OutputVar is set to the amount of free disk space in Megabytes (rounded down to the nearest
Megabyte).
Related
Drive, DriveGet
File, Directory, and Disk Management
111
Example
DriveSpaceFree, FreeSpace, c:\
FileAppend
Appends text to a file (first creating the file, if necessary).
FileAppend [, Text, Filename]
Parameters
Text
The text to append to the file. This text may include linefeed characters (`n) to
start new lines. In addition, a single long line can be broken up into several
shorter ones by means of a continuation section.
If Text is blank, Filename will be created as an empty file (but if the file
already exists, its modification time will be updated).
If Text is %ClipboardAll% or a variable that was previously assigned the value
of ClipboardAll, Filename will be unconditionally overwritten with the entire
contents of the clipboard (i.e. FileDelete is not necessary).
Filename
The name of the file to be appended, which is assumed to be in
%A_WorkingDir% if an absolute path isn't specified.
To append in binary mode rather than text mode, prepend an asterisk to the
filename. This causes each linefeed character (`n) to be written as as a single
linefeed (LF) rather than the Windows standard of CR+LF. For example:
*C:\My Unix File.txt
If the file is not already open (due to being inside a file-reading loop), the file
is automatically opened in binary mode if Text contains any carriage return
and linefeed pairs (`r`n). In other words, the asterisk option described in the
previous paragraph is put into effect automatically. However, specifying the
asterisk when Text contains `r`n improves performance because the program
does not need to scan Text for `r`n.
Specifying an asterisk (*) for Filename causes Text to be sent to standard
output (stdout). Such text can be redirected to a file, piped to another EXE, or
captured by fancy text editors. For example, the following would be valid if
typed at a command prompt:
"%ProgramFiles%\AutoHotkey\AutoHotkey.exe" "My Script.ahk" >"Error
Log.txt"
However, text sent to stdout will not appear at the command prompt it was
launched from. This can be worked around by downloading a utility such as
PipeSplit.exe (8 KB) and using a command line such as the following:
"%ProgramFiles%\AutoHotkey\AutoHotkey.exe" "My Script.ahk" |PipeSplit.exe
nul
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
To overwrite an existing file, delete it with FileDelete prior to using FileAppend.
Printed Documentation
112
Related
FileRead, file-reading loop, FileReadLine, IniWrite, FileDelete, OutputDebug, continuation sections
Example
FileAppend, Another line.`n, C:\My Documents\Test.txt

; The following example uses a continuation section to enhance readability and maintainability:
FileAppend,
(
A line of text.
By default, the hard carriage return (Enter) between the previous line and this one will be written to
the file.
This line is indented with a tab; by default, that tab will also be written to the file.
Variable references such as %Var% are expanded by default.
), C:\My File.txt

; The following example demonstrates how to automate FTP uploading using the operating
; system's built-in FTP command. This script has been tested on Windows XP and 98se.

FTPCommandFile = %A_ScriptDir%\FTPCommands.txt
FTPLogFile = %A_ScriptDir%\FTPLog.txt
FileDelete %FTPCommandFile% ; In case previous run was terminated prematurely.

FileAppend,
(
open host.domain.com
username
password
binary
cd htdocs
put %VarContainingNameOfTargetFile%
delete SomeOtherFile.htm
rename OldFileName.htm NewFileName.htm
ls -l
quit
), %FTPCommandFile%

RunWait %comspec% /c ftp.exe -s:"%FTPCommandFile%" >"%FTPLogFile%"
File, Directory, and Disk Management
113
FileDelete %FTPCommandFile% ; Delete for security reasons.
Run %FTPLogFile% ; Display the log for review.
FileCopy
Copies one or more files.
FileCopy, SourcePattern, DestPattern [, Flag]
Parameters
SourcePattern
The name of a single file or folder, or a wildcard pattern such as
C:\Temp\*.tmp. SourcePattern is assumed to be in %A_WorkingDir% if an
absolute path isn't specified.
DestPattern
The name or pattern of the destination, which is assumed to be in
%A_WorkingDir% if an absolute path isn't specified. To perform a simple
copy -- retaining the existing file name(s) -- specify only the folder name as
shown in these functionally identical examples:
FileCopy, C:\*.txt, C:\My Folder
FileCopy, C:\*.txt, C:\My Folder\*.*
Flag
(optional) this flag determines whether to overwrite files if they already exist:
0 = (default) do not overwrite existing files
1 = overwrite existing files
This parameter can be an expression, even one that evalutes to true or false
(since true and false are stored internally as 1 and 0).
ErrorLevel
ErrorLevel is set to the number of files that could not be copied due to an error, or 0 otherwise. AutoIt
v2 (.aut) scripts set ErrorLevel to 1 if any of the files could not be copied.
In either case, if the source file is a single file (no wildcards) and it does not exist, ErrorLevel is set to
0. To detect this condition, use IfExist or FileExist() on the source file prior to copying it.
Unlike FileMove, copying a file onto itself is always counted as an error, even if the overwrite mode is
in effect.
Remarks
FileCopy copies files only. To instead copy the contents of a folder (all its files and subfolders), see the
examples section below. To copy a single folder (including its subfolders), use FileCopyDir.
The operation will continue even if error(s) are encountered.
Related
FileMove, FileCopyDir, FileMoveDir, FileDelete
Examples
FileCopy, C:\My Documents\List1.txt, D:\Main Backup\ ; Make a copy but keep the orig. file name.
FileCopy, C:\My File.txt, C:\My File New.txt ; Copy a file into the same folder by providing a new
name.
FileCopy, C:\Folder1\*.txt, D:\New Folder\*.bkp ; Copy to new location and give new extension.

Printed Documentation
114
; The following example copies all files and folders inside a folder to a different folder:
ErrorCount := CopyFilesAndFolders("C:\My Folder\*.*", "D:\Folder to receive all files & folders")
if ErrorCount <> 0
MsgBox %ErrorCount% files/folders could not be copied.

CopyFilesAndFolders(SourcePattern, DestinationFolder, DoOverwrite = false)
; Copies all files and folders matching SourcePattern into the folder named DestinationFolder and
; returns the number of files/folders that could not be copied.
{
; First copy all the files (but not the folders):
FileCopy, %SourcePattern%, %DestinationFolder%, %DoOverwrite%
ErrorCount := ErrorLevel
; Now copy all the folders:
Loop, %SourcePattern%, 2 ; 2 means "retrieve folders only".
{
FileCopyDir, %A_LoopFileFullPath%, %DestinationFolder%\%A_LoopFileName%,
%DoOverwrite%
ErrorCount += ErrorLevel
if ErrorLevel ; Report each problem folder by name.
MsgBox Could not copy %A_LoopFileFullPath% into %DestinationFolder%.
}
return ErrorCount
}
FileCopyDir
Copies a folder along with all its sub-folders and files (similar to xcopy).
FileCopyDir, Source, Dest [, Flag]
Parameters
Source
Name of the source directory (with no trailing backslash), which is assumed to
be in %A_WorkingDir% if an absolute path isn't specified. For example: C:\My
Folder
Dest
Name of the destination dir (with no trailing baskslash), which is assumed to
be in %A_WorkingDir% if an absolute path isn't specified. For example:
C:\Copy of My Folder
Flag
(optional) this flag determines whether to overwrite files if they already exist:
0 (default): Do not overwrite existing files. The operation will fail and have no
effect if Dest already exists as a file or directory.
1: Overwrite existing files. However, any files or subfolders inside Dest that do
not have a counterpart in Source will not be deleted.
This parameter can be an expression, even one that evalutes to true or false
File, Directory, and Disk Management
115
(since true and false are stored internally as 1 and 0).
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
If the destination directory structure doesn't exist it will be created if possible.
Since the operation will recursively copy a folder along with all its subfolders and files, the result of
copying a folder to a destination somewhere inside itself is undefined. To work around this, first copy
it to a destination outside itself, then use FileMoveDir to move that copy to the desired location.
FileCopyDir copies a single folder. To instead copy the contents of a folder (all its files and subfolders),
see the examples section of FileCopy.
Related
FileMoveDir, FileCopy, FileMove, FileDelete, file-loops, FileSelectFolder, SplitPath
Examples
FileCopyDir, C:\My Folder, C:\Copy of My Folder

; Example #2: A working script that prompts you to copy a folder.
FileSelectFolder, SourceFolder, , 3, Select the folder to copy
if SourceFolder =
return
; Otherwise, continue.
FileSelectFolder, TargetFolder, , 3, Select the folder IN WHICH to create the duplicate folder.
if TargetFolder =
return
; Otherwise, continue.
MsgBox, 4, , A copy of the folder "%SourceFolder%" will be put into "%TargetFolder%". Continue?
IfMsgBox, No
return
SplitPath, SourceFolder, SourceFolderName ; Extract only the folder name from its full path.
FileCopyDir, %SourceFolder%, %TargetFolder%\%SourceFolderName%
if ErrorLevel
MsgBox The folder could not be copied, perhaps because a folder of that name already exists in
"%TargetFolder%".
return
FileCreateDir
Creates a directory/folder.
FileCreateDir, DirName
Printed Documentation
116
Parameters
DirName
Name of the directory to create, which is assumed to be in %A_WorkingDir% if
an absolute path isn't specified.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
This command will also create all parent directories given in DirName if they do not already
exist.
Related
FileRemoveDir
Example
FileCreateDir, C:\Test1\My Images\Folder2
FileCreateShortcut
Creates a shortcut (.lnk) file.
FileCreateShortcut, Target, LinkFile [, WorkingDir, Args, Description, IconFile, ShortcutKey,
IconNumber, RunState]
Parameters
Target
Name of the file that the shortcut refers to, which should include an absolute
path unless the file is integrated with the system (e.g. Notepad.exe). The file
does not have to exist at the time the shortcut is created; in other words,
shortcuts to invalid targets can be created.
LinkFile
Name of the shortcut file to be created, which is assumed to be in
%A_WorkingDir% if an absolute path isn't specified. Be sure to include the
.lnk extension. If the file already exists, it will be overwritten.
WorkingDir
Directory that will become Target's current working directory when the
shortcut is launched. If blank or omitted, the shortcut will have a blank "Start
in" field and the system will provide a default working directory when the
shortcut is launched.
Args
Parameters that will be passed to Target when it is launched. Separate
parameters with spaces. If a parameter contains spaces, enclose it in double
quotes.
Description Comments that describe the shortcut (used by the OS to display a tooltip, etc.)
IconFile
The full path and name of the icon to be displayed for LinkFile. It must either
be an ico file or the very first icon of an EXE or DLL.
ShortcutKey
A single letter, number, or the name of a single key from the key list (mouse
buttons and other non-standard keys might not be supported). Do not include
modifier symbols. Currently, all shortcut keys are created as CTRL+ALT
shortcuts. For example, if the letter B is specified for this parameter, the
shortcut key will be CTRL-ALT-B.
For Windows 9x: A reboot might be required to get the shortcut key into
effect. Alternatively, you can open the properties dialog for the shortcut and
File, Directory, and Disk Management
117
recreate the shortcut key to get it into effect immediately.
IconNumber
To use an icon in IconFile other than the first, specify that number here (can
be an expression). For example, 2 is the second icon.
RunState
To have Target launched minimized or maximized, specify one of the following
digits:
1 - Normal (this is the default)
3 - Maximized
7 - Minimized
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
Target might not need to include a path if the target file resides in one of the folders listed in the
system's PATH environment variable.
The ShortcutKey of a newly created shortcut will have no effect unless the shortcut file resides on the
desktop or somewhere in the Start Menu. If the ShortcutKey you choose is already in use, your new
shortcut takes precedence.
An alternative way to create a shortcut to a URL is the following example, which creates a special URL
shortcut. Change the first two parameters to suit your preferences:
IniWrite, http://www.google.com, C:\My Shortcut.url, InternetShortcut, URL
The following may be optionally added to assign an icon to the above:
IniWrite, <IconFile>, C:\My Shortcut.url, InternetShortcut, IconFile
IniWrite, 0, C:\My Shortcut.url, InternetShortcut, IconIndex
In the above, replace 0 with the index of the icon (0 is used for the first icon) and replace <IconFile>
with a URL, EXE, DLL, or ICO file. Examples: C:\Icons.dll, C:\App.exe,
http://www.somedomain.com/ShortcutIcon.ico
The operating system will treat a .URL file created by the above as a real shortcut even though it is a
plain text file rather than a .LNK file.
Related
FileGetShortcut, FileAppend
Example
; The letter "i" in the last parameter makes the shortcut key be Ctrl-Alt-I:
FileCreateShortcut, Notepad.exe, %A_Desktop%\My Shortcut.lnk, C:\, "%A_ScriptFullPath%", My
Description, C:\My Icon.ico, i
FileDelete
Deletes one or more files.
FileDelete, FilePattern
Parameters
FilePattern
The name of a single file or a wildcard pattern such as C:\Temp\*.tmp.
FilePattern is assumed to be in %A_WorkingDir% if an absolute path isn't
Printed Documentation
118
specified.
To remove an entire folder, along with all its sub-folders and files, use
FileRemoveDir.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
To delete a read-only file, first remove the read-only attribute. For example: FileSetAttrib, -R, C:\My
File.txt
Related
FileRecycle, FileRemoveDir, FileCopy, FileMove
Example
FileDelete, C:\temp files\*.tmp
FileGetAttrib
Reports whether a file or folder is read-only, hidden, etc.
FileGetAttrib, OutputVar [, Filename]
AttributeString := FileExist(FilePattern)
Parameters
OutputVar The name of the variable in which to store the retrieved text.
Filename
The name of the target file, which is assumed to be in %A_WorkingDir% if an
absolute path isn't specified. If omitted, the current file of the innermost
enclosing File-Loop will be used instead.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
The string returned will contain a subset of the letters in the string "RASHNDOCT":

R = READONLY
A = ARCHIVE
S = SYSTEM
H = HIDDEN
N = NORMAL
D = DIRECTORY
O = OFFLINE
C = COMPRESSED
T = TEMPORARY

To check if a particular attribute is present in the retrieved string, following this example:
FileGetAttrib, Attributes, C:\My File.txt
IfInString, Attributes, H
File, Directory, and Disk Management
119
MsgBox The file is hidden.
On a related note, to retrieve a file's 8.3 short name, follow this example:
Loop, C:\My Documents\Address List.txt
ShortPathName = %A_LoopFileShortPath% ; Will yield something similar to
C:\MYDOCU~1\ADDRES~1.txt
A similar method can be used to get the long name of an 8.3 short name.
Related
FileExist(), FileSetAttrib, FileGetTime, FileSetTime, FileGetSize, FileGetVersion, File-loop
Example
FileGetAttrib, OutputVar, C:\New Folder
FileGetShortcut
Retrieves information about a shortcut (.lnk) file, such as its target file.
FileGetShortcut, LinkFile [, OutTarget, OutDir, OutArgs, OutDescription, OutIcon, OutIconNum,
OutRunState]
Parameters
LinkFile
Name of the shortcut file to be analyzed, which is assumed to be in
%A_WorkingDir% if an absolute path isn't specified. Be sure to include the
.lnk extension.
OutTarget
Name of the variable in which to store the shortcut's target (not including
any arguments it might have). For example:
C:\WINDOWS\system32\notepad.exe
OutDir
Name of the variable in which to store the shortcut's working directory. For
example: C:\My Documents. If environment variables such as %WinDir% are
present in the string, one way to resolve them is via StringReplace. For
example: StringReplace, OutDir, OutDir, `%WinDir`%, %A_WinDir%
OutArgs
Name of the variable in which to store the shortcut's parameters (blank if
none).
OutDescription
Name of the variable in which to store the shortcut's comments (blank if
none).
OutIcon
Name of the variable in which to store the filename of the shortcut's icon
(blank if none).
OutIconNum
Name of the variable in which to store the shortcut's icon number within the
icon file (blank if none). This value is most often 1, which means the first
icon.
OutRunState
Name of the variable in which to store the shortcut's initial launch state,
which is one of the following digits:
1: Normal
3: Maximized
7: Minimized
ErrorLevel
Printed Documentation
120
If there was a problem -- such as LinkFile not existing -- all the output variables are made blank and
ErrorLevel is set to 1. Otherwise, ErrorLevel is set to 0.
Remarks
Any of the output variables may be omitted if the corresponding information is not needed.
Related
FileCreateShortcut, SplitPath
Example
FileSelectFile, file,,, Pick a shortcut to analyze., Shortcuts (*.lnk)
if file =
return
FileGetShortcut, %file%, OutTarget, OutDir, OutArgs, OutDesc, OutIcon, OutIconNum, OutRunState
MsgBox
%OutTarget%`n%OutDir%`n%OutArgs%`n%OutDesc%`n%OutIcon%`n%OutIconNum%`n%OutRu
nState%
FileGetSize
Retrieves the size of a file.
FileGetSize, OutputVar [, Filename, Units]
Parameters
OutputVar
The name of the variable in which to store the retrieved size (rounded down to
the nearest whole number).
Filename
The name of the target file, which is assumed to be in %A_WorkingDir% if an
absolute path isn't specified. If omitted, the current file of the innermost
enclosing File-Loop will be used instead.
Units
If present, this parameter causes the result to be returned in units other than
bytes:
K = kilobytes
M = megabytes
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
Files over 4 gigabytes in size are supported (even if Units is bytes).
If the target file is a directory, the size will be reported as whatever the OS believes it to be (probably
zero in all cases).
To calculate the size of folder, including all its files, follow this example:
SetBatchLines, -1 ; Make the operation run at maximum speed.
FolderSize = 0
FileSelectFolder, WhichFolder ; Ask the user to pick a folder.
File, Directory, and Disk Management
121
Loop, %WhichFolder%\*.*, , 1
FolderSize += %A_LoopFileSize%
MsgBox Size of %WhichFolder% is %FolderSize% bytes.
Related
FileGetAttrib, FileSetAttrib, FileGetTime, FileSetTime, FileGetVersion, File-loop
Example
FileGetSize, size, C:\My Documents\test.doc ; Retrieve the size in bytes.
FileGetSize, size, C:\My Documents\test.doc, K ; Retrieve the size in Kbytes.
FileGetTime
Retrieves the datetime stamp of a file or folder.
FileGetTime, OutputVar [, Filename, WhichTime]
Parameters
OutputVar
The name of the variable in which to store the retrieved date-time in format
YYYYMMDDHH24MISS. The time is your own local time, not UTC/GMT.
Filename
The name of the target file or folder, which is assumed to be in
%A_WorkingDir% if an absolute path isn't specified. If omitted, the current file
of the innermost enclosing File-Loop will be used instead.
WhichTime
Which timestamp to retrieve:
M = Modification time (this is the default if the parameter is omitted)
C = Creation time
A = Last access time
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
A file's last access time might not be as precise on Win9x as it is on NT based operating systems.
See YYYYMMDDHH24MISS for an explanation of dates and times.
Related
FileSetTime, FormatTime, If var is [not] type, FileGetAttrib, FileSetAttrib, FileGetSize, FileGetVersion,
File-loop, EnvAdd, EnvSub
Example
FileGetTime, OutputVar, C:\My Documents\test.doc ; Retrieves the modification time by default.
FileGetTime, OutputVar, C:\My Documents\test.doc, C ; Retrieves the creation time.
FileGetVersion
Retrieves the version of a file.
FileGetVersion, OutputVar [, Filename]
Printed Documentation
122
Parameters
OutputVar The name of the variable in which to store the version number/string.
Filename
The name of the target file, which is assumed to be in %A_WorkingDir% if an
absolute path isn't specified. If omitted, the current file of the innermost
enclosing File-Loop will be used instead.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
Most non-executable files (and even some EXEs) won't have a version, and thus the OutputVar will be
blank in these cases.
Related
FileGetAttrib, FileSetAttrib, FileGetTime, FileSetTime, FileGetSize, File-loop
Example
FileGetVersion, version, C:\My Application.exe
FileGetVersion, version, %A_ProgramFiles%\AutoHotkey\AutoHotkey.exe
FileInstall
Includes the specified file inside the compiled script.
FileInstall, Source, Dest [, Flag]
Parameters
Source
The name of the file to be added to the compiled EXE. The file name must not
contain double quotes, variable references (e.g. %A_ProgramFiles%), or
wildcards. In addition, any special characters such as literal percent signs and
commas must be escaped (just like in the parameters of all other commands).
In versions prior to 1.0.35.11, it is best to specify the file's absolute path and
name. In later versions, the file is assumed to be in (or relative to) the script's
own directory if an absolute path isn't specified.
Dest
When Source is extracted from the EXE, this is the name of the file to be
created. It is assumed to be in %A_WorkingDir% if an absolute path isn't
specified. Unlike Source, variable references may be used.
Flag
(optional) this flag determines whether to overwrite files if they already exist:
0 = (default) do not overwrite existing files
1 = overwrite existing files
This parameter can be an expression, even one that evalutes to true or false
(since true and false are stored internally as 1 and 0).
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
File, Directory, and Disk Management
123
Remarks
This command is a directive for the Ahk2Exe compiler that allows you to add extra files to the
resulting compiled script. Later, when the compiled script is run, the files are extracted back out onto
the disk.
The file Source is added during script compilation. When the compiled script is executed and the
same "FileInstall" command is reached, the file is then extracted to Dest.
Files added to a script are compressed and also encrypted.
If this command is used in an normal (uncompiled) script, a simple file copy will be performed instead
-- this helps the testing of scripts that will eventually be compiled.
Related
FileCopy, #Include
Example
FileInstall, C:\My Documents\My File.txt, %A_ProgramFiles%\My Application\Readme.txt, 1
FileMove
Moves or renames one or more files.
FileMove, SourcePattern, DestPattern [, Flag]
Parameters
SourcePattern
The name of a single file or a wildcard pattern such as C:\Temp\*.tmp.
SourcePattern is assumed to be in %A_WorkingDir% if an absolute path isn't
specified.
DestPattern
The name or pattern of the destination, which is assumed to be in
%A_WorkingDir% if an absolute path isn't specified. To perform a simple
move -- retaining the existing file name(s) -- specify only the folder name as
shown in these functionally identical examples:
FileMove, C:\*.txt, C:\My Folder
FileMove, C:\*.txt, C:\My Folder\*.*
Flag
(optional) this flag determines whether to overwrite files if they already exist:
0 = (default) do not overwrite existing files
1 = overwrite existing files
This parameter can be an expression, even one that evalutes to true or false
(since true and false are stored internally as 1 and 0).
ErrorLevel
ErrorLevel is set to the number of files that could not be moved due to an error, or 0 otherwise.
However, if the source file is a single file (no wildcards) and it does not exist, ErrorLevel is set to 0. To
detect this condition, use IfExist or FileExist() on the source file prior to moving it.
Unlike FileCopy, moving a file onto itself is always considered successful, even if the overwrite mode is
not in effect.
Remarks
Printed Documentation
124
FileMove moves files only. To instead move the contents of a folder (all its files and subfolders), see
the examples section below. To move or rename a single folder, use FileMoveDir.
The operation will continue even if error(s) are encountered.
Although this command is capable of moving files to a different volume, the operation will take longer
than a same-volume move. This is because a same-volume move is similar to a rename, and therefore
much faster.
Related
FileCopy, FileCopyDir, FileMoveDir, FileDelete
Examples
FileMove, C:\My Documents\List1.txt, D:\Main Backup\ ; Move the file without renaming it.
FileMove, C:\File Before.txt, C:\File After.txt ; Rename a single file.
FileMove, C:\Folder1\*.txt, D:\New Folder\*.bkp ; Move and rename files to a new extension.

; The following example moves all files and folders inside a folder to a different folder:
ErrorCount := MoveFilesAndFolders("C:\My Folder\*.*", "D:\Folder to receive all files & folders")
if ErrorCount <> 0
MsgBox %ErrorCount% files/folders could not be moved.

MoveFilesAndFolders(SourcePattern, DestinationFolder, DoOverwrite = false)
; Moves all files and folders matching SourcePattern into the folder named DestinationFolder and
; returns the number of files/folders that could not be moved. This function requires v1.0.38+
; because it uses FileMoveDir's mode 2.
{
if DoOverwrite = 1
DoOverwrite = 2 ; See FileMoveDir for description of mode 2 vs. 1.
; First move all the files (but not the folders):
FileMove, %SourcePattern%, %DestinationFolder%, %DoOverwrite%
ErrorCount := ErrorLevel
; Now move all the folders:
Loop, %SourcePattern%, 2 ; 2 means "retrieve folders only".
{
FileMoveDir, %A_LoopFileFullPath%, %DestinationFolder%\%A_LoopFileName%,
%DoOverwrite%
ErrorCount += ErrorLevel
if ErrorLevel ; Report each problem folder by name.
MsgBox Could not move %A_LoopFileFullPath% into %DestinationFolder%.
}
return ErrorCount
File, Directory, and Disk Management
125
}
FileMoveDir
Moves a folder along with all its sub-folders and files. It can also rename a folder.
FileMoveDir, Source, Dest [, Flag]
Parameters
Source
Name of the source directory (with no trailing backslash), which is assumed to
be in %A_WorkingDir% if an absolute path isn't specified. For example: C:\My
Folder
Dest
Name of the destination directory (with no trailing baskslash), which is
assumed to be in %A_WorkingDir% if an absolute path isn't specified. For
example: D:\My Folder
Flag
(options) Specify one of the following single characters:
0 (default): Do not overwrite existing files. The operation will fail if Dest
already exists as a file or directory.
1: Overwrite existing files. However, any files or subfolders inside Dest that do
not have a counterpart in Source will not be deleted. Known limitation: If
Dest already exists as a folder and it is on the same volume as Source, Source
will be moved into it rather than overwriting it. To avoid this, see the next
option.
2 [v1.0.38+]: Overwrite existing files without the limitation described above.
R: Rename the directory rather than moving it. Although renaming normally
has the same effect as moving, it is helpful in cases where you want "all or
none" behavior; that is, when you don't want the operation to be only partially
successful when Source or one of its files is locked (in use). Although this
method cannot move Source onto a different volume, it can move it to any
other directory on its own volume. The operation will fail if Dest already exists
as a file or directory.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
FileMoveDir moves a single folder to a new location. To instead move the contents of a folder (all its
files and subfolders), see the examples section of FileMove.
If the source and destination are on different volumes or UNC paths, a copy/delete operation will be
performed rather than a move.
Related
FileCopyDir, FileCopy, FileMove, FileDelete, File-loops, FileSelectFolder, SplitPath
Example
FileMoveDir, C:\My Folder, D:\My Folder ; Move to a new drive.
FileMoveDir, C:\My Folder, C:\My Folder (renamed), 1
Printed Documentation
126
FileReadLine
Reads the specified line from a file and stores the text in a variable.
FileReadLine, OutputVar, Filename, LineNum
Parameters
OutputVar The name of the variable in which to store the retrieved text.
Filename
The name of the file to access, which is assumed to be in %A_WorkingDir% if
an absolute path isn't specified. Windows and Unix formats are supported; that
is, the file's lines may end in either carriage return and linefeed (`r`n) or just
linefeed (`n).
LineNum
Which line to read (1 is the first, 2 the second, and so on). This can be an
expression.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
Generally, this command should be used only for small files, or in cases where only a single line of
text is needed. To scan and process a large number of lines (one by one), use a file-reading loop for
best performance. To read an entire file into a variable, use FileRead.
Although any leading and trailing tabs and spaces present in the line will be written to OutputVar, the
linefeed character (`n) at the end of the line will not. Tabs and spaces can be trimmed from both ends
of any variable by assigning it to itself while AutoTrim is on (the default). For example: MyLine =
%MyLine%
Lines up to 65,534 characters long can be read. If the length of a line exceeds this, the remaining
characters cannot be retrieved by this command (use FileRead or a file-reading loop instead).
Related
FileRead, FileAppend, file-read loop, IniRead
Example
i = 0
Loop
{
i += 1
FileReadLine, line, C:\My Documents\ContactList.txt, %i%
if ErrorLevel
break
MsgBox, 4, , Line #%i% is "%line%". Continue?
IfMsgBox, No
return
}
MsgBox, The end of the file has been reached or there was a problem.
File, Directory, and Disk Management
127
return
FileRead
Reads a file's text into a variable.
FileRead, OutputVar, Filename
Parameters
OutputVar
The name of the variable in which to store the retrieved text. OutputVar will be
made blank if a problem occurs such as the file being "in use" or not existing
(in which case ErrorLevel is set to 1). It will also be made blank if Filename is
an empty file (in which case ErrorLevel is set to 0).
Filename
The name of the file to read, which is assumed to be in %A_WorkingDir% if an
absolute path isn't specified.
Options: Zero or more of the following strings may be also be present
immediately before the name of the file. Separate each option from the next
with a single space or tab. For example: *t *m5000 C:\Log Files\200601.txt
*c: Load a ClipboardAll file. All other options are ignored when *c is present.
*m1024 [v1.0.43.03+]: If this option is omitted, the entire file is loaded
unless the file is larger than 1 GB, in which case it is not loaded at all.
Otherwise, replace 1024 with a decimal or hexadecimal number of bytes
between 1 and 1073741824 (1 GB). If the file is larger than this, only its
leading part is loaded. Note: This might result in the last line ending in a naked
carriage return (`r) rather than `r`n.
*t: Replaces any/all occurrences of carriage return & linefeed (`r`n) with
linefeed (`n). However, this translation reduces performance and is usually not
necessary. For example, text containing `r`n is already in the right format to
be added to a Gui Edit control. Similarly, FileAppend detects the presence of
`r`n when it opens a new file; it knows to write each `r`n as-is rather than
translating it to `r`r`n. Finally, the following parsing loop will work correctly
regardless of whether each line ends in `r`n or just `n: Loop, parse,
MyFileContents, `n, `r
ErrorLevel
ErrorLevel is set to 0 if the load was successful. It is set to 1 if a problem occurred such as: 1) file
does not exist; 2) file is locked or inaccessible; 3) the system lacks sufficient memory to load the file.
Remarks
When the goal is to load all or most of a file into memory, FileRead performs much better than using a
file-reading loop.
A file greater than 1 GB in size will cause ErrorLevel to be set to 1 and OutputVar to be made blank
unless the *m option is present, in which case the leading part of the file is loaded.
FileRead does not obey #MaxMem. If there is concern about using too much memory, check the file
size beforehand with FileGetSize.
If the specified file contains any binary zeros (which never occur in proper text files), only the text
before the first binary zero will be "seen" by AutoHotkey commands and functions. However, the
entire contents are still present in OutputVar and can be accessed by advanced methods such as the
address operator (&); for example: *(&OutputVar + 1000)
FileRead can be used to quickly sort the contents of a file as in the following example:
Printed Documentation
128
FileRead, Contents, C:\Address List.txt
if not ErrorLevel ; Successfully loaded.
{
Sort, Contents
FileDelete, C:\Address List (alphabetical).txt
FileAppend, %Contents%, C:\Address List (alphabetical).txt
Contents = ; Free the memory.
}
Related
file-reading loop, FileReadLine, FileGetSize, FileAppend, IniRead, Sort, UrlDownloadToFile
Example
FileRead, OutputVar, C:\My Documents\My File.txt
FileRecycle
Sends a file or directory to the recycle bin, if possible.
FileRecycle, FilePattern
Parameters
FilePattern
The name of a single file or a wildcard pattern such as C:\Temp\*.tmp.
FilePattern is assumed to be in %A_WorkingDir% if an absolute path isn't
specified.
To recycle an entire directory, provide its name without a trailing backslash.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
None
Related
FileRecycleEmpty, FileDelete, FileCopy, FileMove
Example
FileRecycle, C:\temp files\*.tmp
FileRecycleEmpty
Empties the recycle bin.
FileRecycleEmpty [, DriveLetter]
Parameters
File, Directory, and Disk Management
129
DriveLetter
If omitted, the recycle bin for all drives is emptied. Otherwise, specify a drive
letter such as C:\
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
This commands requires that MS Internet Explorer 4 or later be installed.
Related
FileRecycle, FileDelete, FileCopy, FileMove
Example
FileRecycleEmpty, C:\
FileRemoveDir
Deletes a folder.
FileRemoveDir, DirName [, Recurse?]
Parameters
DirName
Name of the directory to delete, which is assumed to be in %A_WorkingDir% if
an absolute path isn't specified.
Recurse?
0 (default): Do not remove files and sub-directories contained in DirName. In
this case, if DirName is not empty, no action will be taken and ErrorLevel will
be set to 1.
1: Remove all files and subdirectories (like the DOS DelTree command).
This parameter can be an expression, even one that evalutes to true or false
(since true and false are stored internally as 1 and 0).
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
None
Related
FileCreateDir, FileDelete
Example
FileRemoveDir, C:\Download Temp
FileRemoveDir, C:\Download Temp, 1
FileSelectFile
Displays a standard dialog that allows the user to open or save file(s).
Printed Documentation
130
FileSelectFile, OutputVar [, Options, RootDir\Filename, Prompt, Filter]
Parameters
OutputVar
The name of the variable in which to store the filename(s) selected by the
user. This will be made blank if the user cancels the dialog (i.e. does not
wish to select a file).
Options
If omitted, it will default to zero, which is the same as having none of the
options below.
M: Multi-select. Specify the letter M to allow the user to select more than
one file via shift-click, control-click, or other means. M may optionally be
followed by a number as described below (for example, both M and M1 are
valid). To extract the individual files, see the example at the bottom of this
page.
S: Save button. Specify the letter S to cause the dialog to always contain
a Save button instead of an Open button. S may optionally be followed by
a number (or sum of numbers) as described below (for example, both S
and S24 are valid).
Even if M and S are absent, the following numbers can be used. To put
more than one of them into effect, add them up. For example, to use 8
and 16, specify the number 24.
1: File Must Exist
2: Path Must Exist
8: Prompt to Create New File
16: Prompt to OverWrite File
32 [v1.0.43.09+]: Shortcuts (.lnk files) are selected as-is rather than
being resolved to their targets. This option also prevents navigation into a
folder via a folder shortcut.
If the "Prompt to Overwrite" option is present without the "Prompt to
Create" option, the dialog will contain a Save button rather than an Open
button. This behavior is due to a quirk in Windows.
RootDir\Filename
If present, this parameter contains one or both of the following:
RootDir: The root (starting) directory, which is assumed to be a subfolder
in %A_WorkingDir% if an absolute path is not specified. If omitted or
blank, the starting directory will be a default that might depend on the OS
version (in WinNT/2k/XP and beyond, it will likely be the directory most
recently selected by the user during a prior use of FileSelectFile). In
v1.0.43.10+, a CLSID such as ::{20d04fe0-3aea-1069-a2d8-
08002b30309d} (i.e. My Computer) may also be specified, in which case
any subdirectory present after the CLSID should end in a backslash
(otherwise, the string after the last backslash will be interpreted as the
default filename, below).
Filename: The default filename to initially show in the dialog's edit field.
Only the naked filename (with no path) will be shown. To ensure that the
dialog is properly shown, ensure that no illegal characters are present
(such as /<|:").
Examples:
C:\My Pictures\Default Image Name.gif ; Both RootDir and
Filename are present.
File, Directory, and Disk Management
131
C:\My Pictures ; Only RootDir is present.
My Pictures ; Only RootDir is present, and it's relative to the
current working directory.
My File ; Only Filename is present (but if "My File" exists as a
folder, it is assumed to be RootDir).
Prompt
Text displayed in the window to instruct the user what to do. If omitted or
blank, it will default to "Select File - %A_SCRIPTNAME%" (i.e. the name of
the current script).
Filter
Indicates which types of files are shown by the dialog.
Example: Documents (*.txt)
Example: Audio (*.wav; *.mp2; *.mp3)
If omitted, the filter defaults to All Files (*.*). An option for Text
Documents (*.txt) will also be available in the dialog's "files of type"
menu.
Otherwise, the filter uses the indicated string but also provides an option
for All Files (*.*) in the dialog's "files of type" drop-down list. To include
more than one file extension in the filter, separate them with semicolons
as illustrated in the example above.
ErrorLevel
ErrorLevel is set to 1 if the user dismissed the dialog without selecting a file (such as by pressing the
Cancel button). It is also set to 1 if the system refused to show the dialog (rare). Otherwise, it is set
to 0.
Remarks
If the user didn't select anything (e.g. pressed CANCEL), OutputVar is made blank.
If multi-select is not in effect, OutputVar is set to the full path and name of the single file chosen by
the user.
If the M option (multi-select) is in effect, OutputVar is set to a list of items, each of which except the
last is followed by a linefeed (`n) character. The first item in the list is the path that contains all the
selected files (this path will end in a backslash only if it is a root folder such as C:\). The other items
are the selected filenames (without path). For example:
C:\My Documents\New Folder [this is the path in which all the files below reside]
test1.txt [these are the naked filenames: no path info]
test2.txt
... etc.
(The example at the bottom of this page demonstrates how to extract the files one by one.)
When multi-select is in effect, the sum of the lengths of the selected filenames is limited to 64 KB.
Although this is typically enough to hold several thousand files, OutputVar will be made blank if the
limit is exceeded.
A GUI window may display a modal file-selection dialog by means of Gui +OwnDialogs. A modal dialog
prevents the user from interacting with the GUI window until the dialog is dismissed.
Known limitation: A timer that launches during the display of a FileSelectFile dialog will postpone the
effect of the user's clicks inside the dialog until after the timer finishes. To work around this, avoid
using timers whose subroutines take a long time to finish, or disable all timers during the dialog:
Thread, NoTimers
FileSelectFile, OutputVar
Printed Documentation
132
Thread, NoTimers, false
Obsolete option: In v1.0.25.06+, the multi-select option "4" is obsolete. However, for compatibility
with older scripts, it still functions as it did before. Specifically, if the user selects only one file,
OutputVar will contain its full path and name followed by a linefeed (`n) character. If the user selects
more than one file, the format is the same as that of the M option described above, except that the
last item also ends in a linefeed (`n).
Related
FileSelectFolder, MsgBox, InputBox, ToolTip, GUI, CLSID List, parsing loop, SplitPath
Also, the operating system offers two standard dialogs that prompt the user to pick a font and/or
color. These dialogs can be displayed via DllCall() as demonstrated in the forum topics ChooseFont
and ChooseColor.
Examples
FileSelectFile, SelectedFile, 3, , Open a file, Text Documents (*.txt; *.doc)
if SelectedFile =
MsgBox, The user didn't select anything.
else
MsgBox, The user selected the following:`n%SelectedFile%


CLSID Example:
FileSelectFile, OutputVar,, ::{645ff040-5081-101b-9f08-00aa002f954e} ; Recycle Bin.

; Multi-Select Example:
FileSelectFile, files, M3 ; M3 = Multiselect existing files.
if files =
{
MsgBox, The user pressed cancel.
return
}
Loop, parse, files, `n
{
if a_index = 1
MsgBox, The selected files are all contained in %A_LoopField%.
else
{
MsgBox, 4, , The next file is %A_LoopField%. Continue?
IfMsgBox, No, break
}
}
File, Directory, and Disk Management
133
return
FileSelectFolder
Displays a standard dialog that allows the user to select a folder.
FileSelectFolder, OutputVar [, StartingFolder, Options, Prompt]
Parameters
OutputVar
The name of the variable in which to store the user's selected folder. This will
be made blank if the user cancels the dialog (i.e. does not wish to select a
folder). If the user selects a root directory (such as C:\), OutputVar will
contain a trailing backslash. If this is undesirable, remove it as follows:
FileSelectFolder, Folder
StringRight, LastChar, Folder, 1
if LastChar = \
StringTrimRight, Folder, Folder, 1 ; Remove the trailing backslash.
StartingFolder
If blank or omitted, the dialog's initial selection will be the user's My
Documents folder (or possibly My Computer). A CLSID folder such as
::{20d04fe0-3aea-1069-a2d8-08002b30309d} (i.e. My Computer) may be
specified start navigation at a specific special folder.
Otherwise, the most common usage of this parameter in v1.0.36.03+ is an
asterisk followed immediately by the absolute path of the drive or folder to be
initially selected. For example, *C:\ would initially select the C drive.
Similarly, *C:\My Folder would initially select that particular folder.
The asterisk indicates that the user is permitted to navigate upward (closer to
the root) from the starting folder. Without the asterisk, the user would be
forced to select a folder inside StartingFolder (or StartingFolder itself). One
benefit of omitting the asterisk is that StartingFolder is initially shown in a
tree-expanded state, which may save the user from having to click the first
plus sign.
If the asterisk is present, upward navigation may optionally be restricted to a
folder other than Desktop. This is done by preceding the asterisk with the
absolute path of the uppermost folder followed by exactly one space or tab.
In the following example, the user would not be allowed to navigate any
higher than C:\My Folder (but the initial selection would be C:\My
Folder\Projects):
C:\My Folder *C:\My Folder\Projects
Options
One of the following numbers:
0: The options below are all disabled (except on Windows 2000, where the
"make new folder" button might appear anyway).
1 (default): A button is provided that allows the user to create new folders.
However, the button will not be present on Windows 95/98/NT.
Add 2 to the above number to provide an edit field that allows the user to
type the name of a folder. For example, a value of 3 for this parameter
provides both an edit field and a "make new folder" button.
If the user types an invalid folder name in the edit field, OutputVar will be set
to the folder selected in the navigation tree rather than what the user
Printed Documentation
134
entered, at least on Windows XP.
This parameter can be an expression.
Prompt
Text displayed in the window to instruct the user what to do. If omitted or
blank, it will default to "Select Folder - %A_SCRIPTNAME%" (i.e. the name of
the current script).
ErrorLevel
ErrorLevel is set to 1 if the user dismissed the dialog without selecting a file (such as by pressing the
Cancel button). It is also set to 1 if the system refused to show the dialog (rare). Otherwise, it is set
to 0.
Remarks
A GUI window may display a modal folder-selection dialog by means of Gui +OwnDialogs. A modal
dialog prevents the user from interacting with the GUI window until the dialog is dismissed.
Known limitation: A timer that launches during the display of a FileSelectFolder dialog will postpone
the effect of the user's clicks inside the dialog until after the timer finishes. To work around this, avoid
using timers whose subroutines take a long time to finish, or disable all timers during the dialog:
Thread, NoTimers
FileSelectFolder, OutputVar,, 3
Thread, NoTimers, false
Related
FileSelectFile, MsgBox, InputBox, ToolTip, GUI, CLSID List, FileCopyDir, FileMoveDir, SplitPath
Also, the operating system offers two standard dialogs that prompt the user to pick a font and/or
color. These dialogs can be displayed via DllCall() as demonstrated in the forum topics ChooseFont
and ChooseColor.
Example
FileSelectFolder, OutputVar, , 3
if OutputVar =
MsgBox, You didn't select a folder.
else
MsgBox, You selected folder "%OutputVar%".

CLSID Example:
FileSelectFolder, OutputVar, ::{20d04fe0-3aea-1069-a2d8-08002b30309d} ; My Computer.
FileSetAttrib
Changes the attributes of one or more files or folders. Wildcards are supported.
FileSetAttrib, Attributes [, FilePattern, OperateOnFolders?, Recurse?]
Parameters
Attributes The attributes to change (see Remarks).
File, Directory, and Disk Management
135
FilePattern
The name of a single file or folder, or a wildcard pattern such as
C:\Temp\*.tmp. FilePattern is assumed to be in %A_WorkingDir% if an
absolute path isn't specified.
If omitted, the current file of the innermost enclosing File-Loop will be
used instead.
OperateOnFolders?
0 (default) Folders are not operated upon (only files).
1 All files and folders that match the wildcard pattern are operated upon.
2 Only folders are operated upon (no files).
Note: If FilePattern is a single folder rather than a wildcard pattern, it
will always be operated upon regardless of this setting.
This parameter can be an expression.
Recurse?
0 (default) Subfolders are not recursed into.
1 Subfolders are recursed into so that files and folders contained therein
are operated upon if they match FilePattern. All subfolders will be
recursed into, not just those whose names match FilePattern.
This parameter can be an expression.
ErrorLevel
ErrorLevel is set to the number of files that failed to be changed or 0 otherwise.
Remarks
The Attributes parameter consists of a collection of operators and attribute letters.
Operators:
+ Turn on the attribute
- Turn off the attribute
^ Toggle the attribute (set it to the opposite value of what it is now)

Attribute letters:
R = READONLY
A = ARCHIVE
S = SYSTEM
H = HIDDEN
N = NORMAL (this is valid only when used without any other attributes)
O = OFFLINE
T = TEMPORARY
Note: Currently, the compression state of files cannot be changed with this command.
ErrorLevel
ErrorLevel is set to the number of files that failed to be changed (if any) or 0 otherwise.
Related
FileGetAttrib, FileGetTime, FileSetTime, FileGetSize, FileGetVersion, File-loop
Printed Documentation
136
Examples
FileSetAttrib, +RH, C:\MyFiles\*.*, 1 ; +RH is identical to +R+H
FileSetAttrib, ^H, C:\MyFiles ; Toggle the folder's "hidden" attribute.
FileSetAttrib, -R+A, C:\New Text File.txt
FileSetAttrib, +A, C:\*.ini, , 1 ; Recurse through all .ini files on the C drive.
FileSetTime
Changes the datetime stamp of one or more files or folders. Wildcards are supported.
FileSetTime [, YYYYMMDDHH24MISS, FilePattern, WhichTime, OperateOnFolders?, Recurse?]
Parameters
YYYYMMDDHH24MISS
If omitted, it defaults to the current time. Otherwise, specify the time
to use for the operation (see Remarks for the format). Years prior to
1601 are not supported.
FilePattern
The name of a single file or folder, or a wildcard pattern such as
C:\Temp\*.tmp. FilePattern is assumed to be in %A_WorkingDir% if
an absolute path isn't specified.
If omitted, the current file of the innermost enclosing File-Loop will be
used instead.
WhichTime
Which timestamp to set:
M = Modification time (this is the default if the param is omitted)
C = Creation time
A = Last access time
OperateOnFolders?
0 (default) Folders are not operated upon (only files).
1 All files and folders that match the wildcard pattern are operated
upon.
2 Only folders are operated upon (no files).
Note: If FilePattern is a single folder rather than a wildcard pattern, it
will always be operated upon regardless of this setting.
This parameter can be an expression.
Recurse?
0 (default) Subfolders are not recursed into.
1 Subfolders are recursed into so that files and folders contained
therein are operated upon if they match FilePattern. All subfolders will
be recursed into, not just those whose names match FilePattern.
This parameter can be an expression.
ErrorLevel
ErrorLevel is set to the number of files that failed to be changed or 0 otherwise. If the specified
timestamp is invalid, or FilePattern resolves to a blank value, ErrorLevel is set to 1.
Remarks
Under Windows 95/98/ME, changing the timestamp of folders is not supported. Attempts to do so are
ignored.
File, Directory, and Disk Management
137
A file's last access time might not be as precise on FAT16 & FAT32 volumes as it is on NTFS volumes.
The elements of the YYYYMMDDHH24MISS format are:
YYYY The 4-digit year
MM The 2-digit month (01-12)
DD The 2-digit day of the month (01-31)
HH24 The 2-digit hour in 24-hour format (00-23). For example, 09 is 9am and 21 is 9pm.
MI The 2-digit minutes (00-59)
SS The 2-digit seconds (00-59)
If only a partial string is given for YYYYMMDDHH24MISS (e.g. 200403), any remaining element that
has been omitted will be supplied with the following default values:
MM: Month 01
DD: Day 01
HH24: Hour 00
MI: Minute 00
SS: Second 00
The built-in variable A_Now contains the current local time in the above format. Similarly, A_NowUTC
contains the current Coordinated Universal Time.
Note: Date-time values can be compared, added to, or subtracted from via EnvAdd and EnvSub. Also,
it is best to not use greater-than or less-than to compare times unless they are both the same string
length. This is because they would be compared as numbers; for example, 20040201 is always
numerically less (but chronologically greater) than 200401010533. So instead use EnvSub to find out
whether the amount of time between them is positive or negative.
Related
FileGetTime, FileGetAttrib, FileSetAttrib, FileGetSize, FileGetVersion, File-loop, EnvAdd, EnvSub
Example
; Set the modification time to the current time for all matching files:
FileSetTime, , C:\temp\*.txt

; Set the modification date (time will be midnight):
FileSetTime, 20040122, C:\My Documents\test.doc

; Set the creation date. The time will be set to 4:55pm:
FileSetTime, 200401221655, C:\My Documents\test.doc, C

; Change the mod-date of all files that match a pattern.
; Any matching folders will also be changed due to the last param:
FileSetTime, 20040122165500, C:\Temp\*.*, M, 1
IfExist / IfNotExist
Checks for the existence of a file or folder.
Printed Documentation
138
IfExist, FilePattern
IfNotExist, FilePattern
AttributeString := FileExist(FilePattern)
Parameters
FilePattern
The path, filename, or file pattern to check. FilePattern is assumed to be in
%A_WorkingDir% if an absolute path isn't specified.
Related
FileExist(), Blocks, Else, File-loops
Examples
IfExist, D:\
MsgBox, The drive exists.
IfExist, D:\Docs\*.txt
MsgBox, At least one .txt file exists.
IfNotExist, C:\Temp\FlagFile.txt
MsgBox, The target file does not exist.
IniDelete
Deletes a value from a standard format .ini file.
IniDelete, Filename, Section [, Key]
Parameters
Filename
The name of the .ini file, which is assumed to be in %A_WorkingDir% if an
absolute path isn't specified.
Section
The section name in the .ini file, which is the heading phrase that appears in
square brackets (do not include the brackets in this parameter).
Key
The key name in the .ini file. If omitted, the entire Section will be
deleted.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise. However, if the script is of type .aut
(AutoIt v2), ErrorLevel is not changed (for compatibility reasons).
Remarks
A standard ini file looks like:
[SectionName]
Key=Value
Related
IniRead, IniWrite, RegDelete
Example
IniDelete, C:\Temp\myfile.ini, section2, key
File, Directory, and Disk Management
139
IniRead
Reads a value from a standard format .ini file.
IniRead, OutputVar, Filename, Section, Key [, Default]
Parameters
OutputVar
The name of the variable in which to store the retrieved value. If the value
cannot be retrieved, the variable is set to the value indicated by the Default
parameter (described below).
Filename
The name of the .ini file, which is assumed to be in %A_WorkingDir% if an
absolute path isn't specified.
Section
The section name in the .ini file, which is the heading phrase that appears in
square brackets (do not include the brackets in this parameter).
Key The key name in the .ini file.
Default
The value to store in OutputVar if the requested key is not found. If omitted, it
defaults to the word ERROR. To store a blank value (empty string), specify
%A_Space%.
For AutoIt (.aut) scripts: For compatibility reasons, this parameter is not
supported; the string ERROR will always be stored in OutputVar if there was a
problem reading the value.
ErrorLevel
ErrorLevel is not set by this command. If there was a problem, OutputVar will be set to the Default
value as described above.
Remarks
The operating system automatically omits leading and trailing spaces/tabs from the retrieved string.
A standard ini file looks like:
[SectionName]
Key=Value
Related
IniDelete, IniWrite, RegRead, file-reading loop, FileRead
Example
IniRead, OutputVar, C:\Temp\myfile.ini, section2, key
MsgBox, The value is %OutputVar%.
IniWrite
Writes a value to a standard format .ini file.
IniWrite, Value, Filename, Section, Key
Parameters
Value
The string or number that will be written to the right of Key's equal sign (=). If
the text is long, it can be broken up into several shorter lines by means of a
Printed Documentation
140
continuation section, which might improve readability and maintainability.
Filename
The name of the .ini file, which is assumed to be in %A_WorkingDir% if an
absolute path isn't specified.
Section
The section name in the .ini file, which is the heading phrase that appears in
square brackets (do not include the brackets in this parameter).
Key The key name in the .ini file.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise. However, if the script is of type .aut
(AutoIt v2), ErrorLevel is not changed (for compatibility reasons).
Remarks
A standard ini file looks like:
[SectionName]
Key=Value
Related
IniDelete, IniRead, RegWrite
Example
IniWrite, this is a new value, C:\Temp\myfile.ini, section2, key
Loop (files & folders)
Retrieves the specified files or folders, one at a time.
Loop, FilePattern [, IncludeFolders?, Recurse?]
Parameters
FilePattern
The name of a single file or folder, or a wildcard pattern such as
C:\Temp\*.tmp. FilePattern is assumed to be in %A_WorkingDir% if an
absolute path isn't specified.
Both asterisks and question marks are supported as wildcards. A match
occurs when the pattern appears in either the file's long/normal name or its
8.3 short name.
If this parameter is a single file or folder (i.e. no wildcards) and Recurse is
set to 1, more than one match will be found if the specified file name
appears in more than one of the folders being searched.
IncludeFolders?
One of the following digits, or blank to use the default:
0 (default) Folders are not retrieved (only files).
1 All files and folders that match the wildcard pattern are retrieved.
2 Only folders are retrieved (no files).
Recurse?
One of the following digits, or blank to use the default:
0 (default) Subfolders are not recursed into.
1 Subfolders are recursed into so that files and folders contained therein are
retrieved if they match FilePattern. All subfolders will be recursed into, not
just those whose names match FilePattern.
File, Directory, and Disk Management
141
Special Variables Available Inside a File-Loop
The following variables exist within any file-loop. If an inner file-loop is enclosed by an outer file-loop,
the innermost loop's file will take precedence:
A_LoopFileName
The name of the file or folder currently retrieved (without the
path).
A_LoopFileExt
[v1.0.36.02+]
The file's extension (e.g. TXT, DOC, or EXE). The period (.) is not
included.
A_LoopFileFullPath
The full path and name of the file/folder currently retrieved.
However, if FilePattern contains a relative path rather than an
absolute path, the path here will also be relative. In addition, any
short (8.3) folder names in FilePattern will still be short (see next
item to get the long version).
A_LoopFileLongPath
This is different than A_LoopFileFullPath in the following ways: 1) It
always contains the absolute/complete path of the file even if
FilePattern contains a relative path; 2) Any short (8.3) folder
names in FilePattern itself are converted to their long names; 3)
Characters in FilePattern are converted to uppercase or lowercase
to match the case stored in the file system. This is useful for
converting file names -- such as those passed into a script as
command line parameters -- to their exact path names as shown
by Explorer.
A_LoopFileShortPath
The 8.3 short path and name of the file/folder currently retrieved.
For example: C:\MYDOCU~1\ADDRES~1.txt. However, if
FilePattern contains a relative path rather than an absolute path,
the path here will also be relative.
To retrieve the complete 8.3 path and name for a single file or
folder, specify its name for FilePattern as in this example:
Loop, C:\My Documents\Address List.txt
ShortPathName = %A_LoopFileShortPath%
NOTE: This variable will be blank if the file does not have a short
name, which can happen on systems where
NtfsDisable8dot3NameCreation has been set in the registry. It will
also be blank if FilePattern contains a relative path and the body of
the loop uses SetWorkingDir to switch away from the working
directory in effect for the loop itself.
A_LoopFileShortName
The 8.3 short name, or alternate name of the file. If the file doesn't
have one (due to the long name being shorter than 8.3 or perhaps
because short-name generation is disabled on an NTFS file
system), A_LoopFileName will be retrieved instead.
A_LoopFileDir
The full path of the directory in which A_LoopFileName resides.
However, if FilePattern contains a relative path rather than an
absolute path, the path here will also be relative. A root directory
will not contain a trailing backslash. For example: C:
A_LoopFileTimeModified The time the file was last modified. Format YYYYMMDDHH24MISS.
A_LoopFileTimeCreated The time the file was created. Format YYYYMMDDHH24MISS.
A_LoopFileTimeAccessed The time the file was last accessed. Format YYYYMMDDHH24MISS.
A_LoopFileAttrib The attributes of the file currently retrieved.
A_LoopFileSize
The size in bytes of the file currently retrieved. Files larger than 4
gigabytes are also supported.
Printed Documentation
142
A_LoopFileSizeKB
The size in Kbytes of the file currently retrieved, rounded down to
the nearest integer.
A_LoopFileSizeMB
The size in Mbytes of the file currently retrieved, rounded down to
the nearest integer.
Remarks
A file-loop is useful when you want to operate on a collection of files and/or folders, one at a time.
All matching files are retrieved, including hidden files. By contrast, OS features such as the DIR
command omit hidden files by default. To avoid processing hidden, system, and/or read-only files, use
something like the following inside the loop:
if A_LoopFileAttrib contains H,R,S ; Skip any file that is either H (Hidden), R (Read-only), or S
(System). Note: No spaces in "H,R,S".
continue ; Skip this file and move on to the next one.
To retrieve files' relative paths instead of absolute paths during a recursive search, use SetWorkingDir
to change to the base folder prior to the loop, and then omit the path from the Loop (e.g. Loop, *.*,
0, 1). That will cause A_LoopFileFullPath to contain the file's path relative to the base folder.
A file-loop can disrupt itself if it creates or renames files or folders within its own purview. For
example, if it renames files via FileMove or other means, each such file might be found twice: once as
its old name and again as its new name. To work around this, rename the files only after creating a
list of them. For example:
FileList =
Loop *.jpg
FileList = %FileList%%A_LoopFileName%`n
Loop, parse, FileList, `n
FileMove, %A_LoopField%, renamed_%A_LoopField%
Files in an NTFS file system are probably always retrieved in alphabetical order. Files in other file
systems are retrieved in no particular order. To ensure a particular ordering, use the Sort command as
shown in the Examples section below.
See Loop for information about Blocks, Break, Continue, and the A_Index variable (which exists in
every type of loop).
Related
Loop, Break, Continue, Blocks, SplitPath, FileSetAttrib, FileSetTime
Examples
; Example #1:
Loop, %A_ProgramFiles%\*.txt, , 1 ; Recurse into subfolders.
{
MsgBox, 4, , Filename = %A_LoopFileFullPath%`n`nContinue?
IfMsgBox, No
break
}

; Example #2: Calculate the size of a folder, including the files in all its subfolders:
File, Directory, and Disk Management
143
SetBatchLines, -1 ; Make the operation run at maximum speed.
FolderSizeKB = 0
FileSelectFolder, WhichFolder ; Ask the user to pick a folder.
Loop, %WhichFolder%\*.*, , 1
FolderSizeKB += %A_LoopFileSizeKB%
MsgBox Size of %WhichFolder% is %FolderSizeKB% KB.

; Example #3: Retrieve file names sorted by name (see next example to sort by date):
FileList = ; Initialize to be blank.
Loop, C:\*.*
FileList = %FileList%%A_LoopFileName%`n
Sort, FileList, R ; The R option sorts in reverse order. See Sort for other options.
Loop, parse, FileList, `n
{
if A_LoopField = ; Ignore the blank item at the end of the list.
continue
MsgBox, 4,, File number %A_Index% is %A_LoopField%. Continue?
IfMsgBox, No
break
}

; Example #4: Retrieve file names sorted by modification date:
FileList =
Loop, %A_MyDocuments%\Photos\*.*, 1
FileList = %FileList%%A_LoopFileTimeModified%`t%A_LoopFileName%`n
Sort, FileList ; Sort by date.
Loop, parse, FileList, `n
{
if A_LoopField = ; Omit the last linefeed (blank item) at the end of the list.
continue
StringSplit, FileItem, A_LoopField, %A_Tab% ; Split into two parts at the tab char.
MsgBox, 4,, The next file (modified at %FileItem1%) is:`n%FileItem2%`n`nContinue?
IfMsgBox, No
break
}

; Example #5: Copy only the source files that are newer than their counterparts
; in the destination:
Printed Documentation
144
CopyIfNewer:
; Caller has set the variables CopySourcePattern and CopyDest for us.
Loop, %CopySourcePattern%
{
copy_it = n
IfNotExist, %CopyDest%\%A_LoopFileName% ; Always copy if target file doesn't yet exist.
copy_it = y
else
{
FileGetTime, time, %CopyDest%\%A_LoopFileName%
EnvSub, time, %A_LoopFileTimeModified%, seconds ; Subtract the source file's time from the
destination's.
if time < 0 ; Source file is newer than destination file.
copy_it = y
}
if copy_it = y
{
FileCopy, %A_LoopFileFullPath%, %CopyDest%\%A_LoopFileName%, 1 ; Copy with
overwrite=yes
if ErrorLevel
MsgBox, Could not copy "%A_LoopFileFullPath%" to "%CopyDest%\%A_LoopFileName%".
}
}
Return

; Example #6: Convert filenames passed in via command-line parameters to long names,
; complete path, and correct uppercase/lowercase characters as stored in the file system.
Loop %0% ; For each file dropped onto the script (or passed as a parameter).
{
GivenPath := %A_Index% ; Retrieve the next command line parameter.
Loop %GivenPath%
LongPath = %A_LoopFileLongPath%
MsgBox The case-corrected long path name of file`n%GivenPath%`nis:`n%LongPath%
}
Loop (read file contents)
Retrieves the lines in a text file, one at a time (performs better than FileReadLine).
Loop, Read, InputFile [, OutputFile]
File, Directory, and Disk Management
145
Parameters
Read This parameter must be the word READ.
InputFile
The name of the text file whose contents will be read by the loop, which is
assumed to be in %A_WorkingDir% if an absolute path isn't specified.
Windows and Unix formats are supported; that is, the file's lines may end in
either carriage return and linefeed (`r`n) or just linefeed (`n).
OutputFile
(Optional) The name of the file to be kept open for the duration of the loop,
which is assumed to be in %A_WorkingDir% if an absolute path isn't specified.
Within the loop's body, use the FileAppend command with only one parameter
(the text to be written) to append to this special file. Appending to a file in this
manner performs better than using FileAppend in its 2-parameter mode
because the file does not need to be closed and re-opened for each operation.
Remember to include a linefeed (`n) after the text, if desired.
To append in binary mode rather than text mode, prepend an asterisk to the
filename. This causes each linefeed character (`n) to be written as as a single
linefeed (LF) rather than the Windows standard of CR+LF. For example:
*C:\My Unix File.txt.
The file is not opened if nothing is ever written to it. This happens if the Loop
performs zero iterations or if it never uses the FileAppend command. In
addition, the file is automatically opened in binary mode if the Loop's first use
of FileAppend writes any carriage return and linefeed pairs (`r`n). In other
words, the asterisk option described in the previous paragraph is put into
effect automatically.
Specifying an asterisk (*) for OutputFile sends any text written by FileAppend
to standard output (stdout). Although such output can be redirected to a file,
piped to another EXE, or captured by fancy text editors, it will not appear at
the command prompt it was launched from. For example, the following would
be valid if typed at a command prompt:
"%ProgramFiles%\AutoHotkey\AutoHotkey.exe" "My Script.ahk" >"Error
Log.txt"
Unlike the last parameter of most other commands, commas in OutputFile
must be escaped (`,).
Remarks
A file-read loop is useful when you want to operate each line contained in a text file, one at a time. It
performs better than using FileReadLine because: 1) the file can be kept open for the entire operation;
and 2) the file does not have to be re-scanned each time to find the requested line number.
The built-in variable A_LoopReadLine exists within any file-read loop. It contains the contents of the
current line excluding the carriage return and linefeed (`r`n) that marks the end of the line. If an
inner file-read loop is enclosed by an outer file-read loop, the innermost loop's file-line will take
precedence.
Lines up to 65,534 characters long can be read. If the length of a line exceeds this, its remaining
characters will be read during the next loop iteration.
StringSplit or a parsing loop is often used inside a file-read loop to parse the contents of each line
retrieved from InputFile. For example, if InputFile's lines are each a series of tab-delimited fields,
those fields can individually retrieved as in this example:
Loop, read, C:\Database Export.txt
{
Loop, parse, A_LoopReadLine, %A_Tab%
Printed Documentation
146
{
MsgBox, Field number %A_Index% is %A_LoopField%.
}
}
To load an entire file into variable, use FileRead because it performs much better than a loop
(especially for large files).
To have multiple files open simultaneously, use DllCall() as shown in this example.
See Loop for information about Blocks, Break, Continue, and the A_Index variable (which exists in
every type of loop).
Related
FileRead, FileReadLine, FileAppend, Sort, Loop, Break, Continue, Blocks, FileSetAttrib, FileSetTime
Examples
; Example #1: Only those lines of the 1st file that contain the word FAMILY will be written to the 2nd
file.
; Uncomment the first line to overwrite rather than append to any existing file.
;FileDelete, C:\Docs\Family Addresses.txt

Loop, read, C:\Docs\Address List.txt, C:\Docs\Family Addresses.txt
{
IfInString, A_LoopReadLine, family, FileAppend, %A_LoopReadLine%`n
}

; Example #2: Retrieve the last line from a text file.
Loop, read, C:\Log File.txt
last_line := A_LoopReadLine ; When loop finishes, this will hold the last line.

; Example #3: A working script that attempts to extract all FTP and HTTP
; URLs from a text or HTML file:
FileSelectFile, SourceFile, 3,, Pick a text or HTML file to analyze.
if SourceFile =
return ; This will exit in this case.

SplitPath, SourceFile,, SourceFilePath,, SourceFileNoExt
DestFile = %SourceFilePath%\%SourceFileNoExt% Extracted Links.txt

IfExist, %DestFile%
{
MsgBox, 4,, Overwrite the existing links file? Press No to append to it.`n`nFILE: %DestFile%
File, Directory, and Disk Management
147
IfMsgBox, Yes
FileDelete, %DestFile%
}

LinkCount = 0
Loop, read, %SourceFile%, %DestFile%
{
URLSearchString = %A_LoopReadLine%
Gosub, URLSearch
}
MsgBox %LinkCount% links were found and written to "%DestFile%".
return


URLSearch:
; It's done this particular way because some URLs have other URLs embedded inside them:
StringGetPos, URLStart1, URLSearchString, http://
StringGetPos, URLStart2, URLSearchString, ftp://
StringGetPos, URLStart3, URLSearchString, www.

; Find the left-most starting position:
URLStart = %URLStart1% ; Set starting default.
Loop
{
; It helps performance (at least in a script with many variables) to resolve
; "URLStart%A_Index%" only once:
ArrayElement := URLStart%A_Index%
if ArrayElement = ; End of the array has been reached.
break
if ArrayElement = -1 ; This element is disqualified.
continue
if URLStart = -1
URLStart = %ArrayElement%
else ; URLStart has a valid position in it, so compare it with ArrayElement.
{
if ArrayElement <> -1
if ArrayElement < %URLStart%
URLStart = %ArrayElement%
Printed Documentation
148
}
}

if URLStart = -1 ; No URLs exist in URLSearchString.
return

; Otherwise, extract this URL:
StringTrimLeft, URL, URLSearchString, %URLStart% ; Omit the beginning/irrelevant part.
Loop, parse, URL, %A_Tab%%A_Space%<> ; Find the first space, tab, or angle (if any).
{
URL = %A_LoopField%
break ; i.e. perform only one loop iteration to fetch the first "field".
}
; If the above loop had zero iterations because there were no ending characters found,
; leave the contents of the URL var untouched.

; If the URL ends in a double quote, remove it. For now, StringReplace is used, but
; note that it seems that double quotes can legitimately exist inside URLs, so this
; might damage them:
StringReplace, URLCleansed, URL, ",, All
FileAppend, %URLCleansed%`n
LinkCount += 1

; See if there are any other URLs in this line:
StringLen, CharactersToOmit, URL
CharactersToOmit += %URLStart%
StringTrimLeft, URLSearchString, URLSearchString, %CharactersToOmit%
Gosub, URLSearch ; Recursive call to self.
return
SetWorkingDir
Changes the script's current working directory.
SetWorkingDir, DirName
Parameters
DirName
The name of the new working directory, which is assumed to be a subfolder of
the current %A_WorkingDir% if an absolute path isn't specified.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
File, Directory, and Disk Management
149
Remarks
The script's working directory is the default directory that is used to access files and folders when an
absolute path has not been specified. In the following example, the file My Filename.txt is assumed to
be in %A_WorkingDir%: FileAppend, A Line of Text, My Filename.txt
A script's initial working directory is determined by how it was launched. For example, if it was run via
shortcut -- such as on the Start Menu -- its working directory is determined by the "Start in" field
within the shortcut's properties.
To make a script unconditionally use its own folder as its working directory, make its first line the
following:
SetWorkingDir %A_ScriptDir%
Once changed, the new working directory is instantly and globally in effect throughout the script. All
interrupted, paused, and newly launched threads are affected, including Timers.
Related
%A_WorkingDir%, %A_ScriptDir%, FileSelectFolder
Example
SetWorkingDir, D:\My Folder\Temp
SplitPath
Separates a file name or URL into its name, directory, extension, and drive.
SplitPath, InputVar [, OutFileName, OutDir, OutExtension, OutNameNoExt, OutDrive]
Parameters
InputVar Name of the variable containing the file name to be analyzed.
OutFileName
Name of the variable in which to store the file name without its path. The
file's extension is included.
OutDir
Name of the variable in which to store the directory of the file, including
drive letter or share name (if present). The final backslash is not included
even if the file is located in a drive's root directory.
OutExtension
Name of the variable in which to store the file's extension (e.g. TXT, DOC, or
EXE). The dot is not included.
OutNameNoExt
Name of the variable in which to store the file name without its path, dot
and extension.
OutDrive
Name of the variable in which to store the drive letter or server name of the
file. If the file is on a local or mapped drive, the variable will be set to the
drive letter followed by a colon (no backslash). If the file is on a network
path (UNC), the variable will be set to the share name, e.g. \\Workstation01
Remarks
Any of the output variables may be omitted if the corresponding information is not needed.
If InputVar contains a filename that lacks a drive letter (that is, it has no path or merely a relative
path), OutDrive will be made blank but all the other output variables will be set correctly. Similarly, if
there is no path present, OutDir will be made blank; and if there is a path but no file name present,
OutFileName and OutNameNoExt will be made blank.
Printed Documentation
150
Actual files and directories in the file system are not checked by this command. It simply analyzes the
string given in InputVar.
Wildcards (* and ?) and other characters illegal in filenames are treated the same as legal characters,
with the exception of colon, backslash, and period (dot), which are processed according to their nature
in delimiting the drive letter, directory, and extension of the file.
Support for URLs: If InputVar contains a colon-double-slash, such as http://domain.com or
ftp://domain.com, OutDir is set to the protocol prefix + domain name + directory (e.g.
http://domain.com/images) and OutDrive is set to the protocol prefix + domain name (e.g.
http://domain.com). All other variables are set according to their definitions above.
Related
A_LoopFileExt, StringSplit, StringGetPos, StringMid, StringTrimLeft, StringLeft, FileSelectFile,
FileSelectFolder
Example
FullFileName = C:\My Documents\Address List.txt

; To fetch only the bare filename from the above:
SplitPath, FullFileName, name

; To fetch only its directory:
SplitPath, FullFileName,, dir

; To fetch all info:
SplitPath, FullFileName, name, dir, ext, name_no_ext, drive

; The above will set the variables as follows:
; name = Address List.txt
; dir = C:\My Documents
; ext = txt
; name_no_ext = Address List
; drive = C:

151
Flow of Control
#Include / #IncludeAgain
Causes the script to behave as though the specified file's contents are present at this exact position.
#Include FileOrDirName
#IncludeAgain FileOrDirName
Parameters
FileOrDirName
The name of the file to be included, which is assumed to be in the
startup/working directory if an absolute path is not specified (except for
ahk2exe, which assumes the file is in the script's own directory). The file
name must not contain variable references (except %A_ScriptDir%), double
quotes, or wildcards. Escape sequences other than semicolon (`;) must not
be used, nor are they needed because characters such as percent signs are
treated literally. Note: SetWorkingDir has no effect on #Include because
#Include is processed before the script begins executing.
In v1.0.35.11+, specify a directory instead of a file to change the working
directory used by all subsequent occurrences of #Include and FileInstall. The
directory name must not contain variables other than %A_ScriptDir%. Note:
Changing the working directory in this way does not affect the script's initial
working directory when it starts running (A_WorkingDir). To change that, use
SetWorkingDir at the top of the script.
Remarks
A script behaves as though the included file's contents are physically present at the exact position of
the #Include directive (as though a copy-and-paste were done from the included file).
#Include ensures that FileName is included only once, even if multiple inclusions are encountered for
it. By contrast, #IncludeAgain allows multiple inclusions of the same file, while being the same as
#Include in all other respects.
The FileName parameter may optionally be preceded by *i and a single space, which causes the
program to ignore any failure to load the included file. For example: #Include *i SpecialOptions.ahk.
This option should be used only when the included file's contents are not essential to the main script's
operation.
Lines displayed in the main window via ListLines or the menu View->Lines are always numbered
according to their physical order within their own files. In other words, including a new file will change
the line numbering of the main script file by only one line, namely that of the #Include line itself
(except for compiled scripts, which merge their included files into one big script at the time of
compilation).
#Include is often used to load functions defined in an external file. Unlike subroutine labels, functions
can be included at the very top of the script without affecting the auto-execute section.
As with other # directives, #Include cannot be executed conditionally. In other words, this example
would not work:
if x = 1
#Include SomeFile.ahk ; This line takes effect regardless of the value of x.
y = 2 ; And this line would belong to the IF above, since # directives cannot belong to IFs.
Related
Printed Documentation
152
Functions, FileInstall
Example
#Include C:\My Documents\Scripts\Utility Subroutines.ahk
#Include %A_ScriptDir% ; Changes the working directory for #Includes and FileInstalls physically
beneath this point.
#Include C:\My Scripts ; Same as above but for an explicitly named directory.
{...} (block)
Denotes a block. Blocks are typically used with functions, Else, Loop, and IF-commands.
{
zero or more commands
}
Remarks
A block is used to bind two or more commands together. It can also be used to change which IF an
ELSE belongs to, as in this example where the block forces the ELSE to belong to the first IF rather
than the second:
if var1 = 1
{
if var2 = abc
sleep, 1
}
else
return
Although blocks can be used anywhere, currently they are only meaningful when used with functions,
Else, Loop, or an IF-type command such as IfEqual or IfWinExist.
If an IF, ELSE, or Loop has only a single command, that command need not be enclosed in a block.
However, there may be cases where doing so enhances the readability or maintainability of the script.
A block may be empty (contain zero commands), which may be useful in cases where you want to
comment out the contents of the block without removing the block itself.
One True Brace (OTB, K&R style): In v1.0.41+, the OTB style may optionally be used in the
following places: expression if-statements, the "else" keyword, normal loops, and function definitions.
This style puts the block's opening brace on the same line as the block's controlling statement rather
than underneath on a line by itself. For example:
if (x < y) {
...
} else {
...
}
Loop %RepeatCount% {
...
}
Flow of Control
153
MyFunction(x, y) {
...
}
Similarly, a command or other action may exist on the same line as an open-brace (v1.0.41.01+). For
example:
if x = 1
{ MsgBox This line appears to the right of an open-brace.
MsgBox This is the next line.
}
However, open-braces of the One True Brace style do not support commands to their right.
Related
Functions, Loop, Else, If, If(Expression)
Example
if x = 1
{
MsgBox, test1
Sleep, 5
}
else
MsgBox, test2
Break
Exits (terminates) a loop. Valid only inside a loop.
Break
The Break command applies to the innermost loop in which it is enclosed. The use of Break and
Continue are encouraged over goto since they usually make scripts more readable and maintainable.
Related
Loop, Continue, Blocks
Example
loop
{
...
if var > 25
break
...
if var <= 5
continue
Printed Documentation
154
}
Continue
Skips the rest of the current loop iteration and begins a new one. Valid only inside a loop.
Continue
The Continue command applies to the innermost loop in which it is enclosed. The use of Break and
Continue are encouraged over goto since they usually make scripts more readable and maintainable.
Related
Loop, Break, Blocks
Example
; This example displays 5 MsgBoxes, one for each number between 6 and 10.
; Note that in the first 5 iterations of the Loop, the "continue" command
; causes the loop to start over before it reaches the MsgBox line.
Loop, 10
{
if A_Index <= 5
continue
MsgBox %A_Index%
}
Else
Specifies the command(s) to perform if an IF-statement evaluates to FALSE. When more than one
command is present, enclose them in a block (braces).
Else
Remarks
Every use of ELSE must belong to (be associated with) an IF-statement above it. An ELSE always
belongs to the nearest unclaimed IF-statement above it unless a block is used to change that
behavior. An ELSE can be followed immediately by any other single command on the same line. This is
most often used for "else if" ladders (see examples).
When an IF or an ELSE owns more than one line, those lines must be enclosed in braces. However, if
only one line belongs to an IF or ELSE, the braces are optional. For example:
if count > 0
MsgBox Press OK to begin the process.
else
{
WinClose Untitled - Notepad
MsgBox There are no items present.
}
In v1.0.41+, the One True Brace (OTB) style may optionally be used around an "else". For example:
Flow of Control
155
if IsDone {
...
} else if (x < y) {
...
} else {
...
}
Related
See Blocks. Also, every IF-command can use ELSE, including IfWinActive, IfWinExist, IfMsgBox,
IfInString, IfBetween, IfIn, IF, and IF (expression).
Examples
IfWinExist, Untitled - Notepad
{
WinActivate
Send This is a test.{Enter}
}
else
{
WinActivate, Some Other Window
MouseClick, left, 100, 200
}


if x = 1
Gosub, a1
else if x = 2 ; "else if" style
Gosub, a2
else IfEqual, x, 3 ; alternate style
{
Gosub, a3
Sleep, 1
}
else Gosub, a4 ; i.e. Any single command can be on the same line with an ELSE.

; Also OK:
IfEqual, y, 1, Gosub, b1
else {
Printed Documentation
156
Sleep, 1
Gosub, b2
}
Exit
Exits the current thread or (if the script is not persistent contains no hotkeys) the entire script.
Exit [, ExitCode]
Parameters
ExitCode
An integer (i.e. negative, positive, zero, or an expression) that is returned to
its caller when the script exits. This code is accessible to any program that
spawned the script, such as another script (via RunWait) or a batch (.bat) file.
If omitted, ExitCode defaults to zero. Zero is traditionally used to indicate
success. Note: Windows 95 may be limited in how large ExitCode can be.
Remarks
If the script has no hotkeys, isn't persistent, and hasn't requested the Num/Scroll/CapsLock key(s) to
be kept AlwaysOn or AlwaysOff, it will terminate immediately when Exit is encountered (except if it
has an OnExit subroutine).
Otherwise, the Exit command terminates the current thread. In other words, the stack of subroutines
called directly or indirectly by a menu, timer, or hotkey subroutine will all be returned from as though
a Return were immediately encountered in each. If used directly inside such a subroutine -- rather
than in one of the subroutines called indirectly by it -- Exit is equivalent to Return.
Use ExitApp to completely terminate a script that is persistent or contains hotkeys.
Related
ExitApp, OnExit, Functions, Gosub, Return, Threads, #Persistent
Example
#z::
Gosub, Sub2
MsgBox, This msgbox will never happen because of the EXIT.
return

Sub2:
Exit ; Terminate this subroutine as well as the calling subroutine.
ExitApp
Terminates the script unconditionally.
ExitApp [, ExitCode]
Parameters
ExitCode
An integer (i.e. negative, positive, or zero) that is returned to its caller when
the script exits. This code is accessible to any program that spawned the
Flow of Control
157
script, such as another script (via RunWait) or a batch (.bat) file. If omitted,
ExitCode defaults to zero. Zero is traditionally used to indicate success. Note:
Windows 95 may be limited in how large ExitCode can be.
Remarks
The script is immediately terminated unless it has an OnExit subroutine. This is equivalent to choosing
"Exit" from the script's tray menu or main menu.
Exit and ExitApp behave identically when the script contains no hotkeys, is not persistent, and does
not ask for the Num/Scroll/Capslock key(s) to be kept AlwaysOn or AlwaysOff.
If the script has an OnExit subroutine, it will be run in response to ExitApp.
Related
Exit, OnExit, #Persistent
Example
#x::ExitApp ; Assign a hotkey to terminate this script.
Gosub
Jumps to the specified label and continues execution until Return is encountered.
Gosub, Label
Parameters
Label
The name of the label, hotkey label, or hotstring label to which to jump, which
causes the commands beneath Label to be executed until a Return or Exit is
encountered. "Return" causes the script to jump back to the first command
beneath the Gosub and resume execution there. "Exit" terminates the current
thread.
Remarks
As with the parameters of almost all other commands, Label can be a variable reference such as
%MyLabel%, in which case the name stored in the variable is used as the target. However,
performance is slightly reduced because the target label must be "looked up" each time rather than
only once when the script is first loaded.
When using a dynamic label such as %MyLabel%, an error dialog will be displayed if the label does not
exist. To avoid this, call IsLabel() beforehand. For example:
if IsLabel(VarContainingLabelName)
Gosub %VarContainingLabelName%
Although Gosub is useful for simple, general purpose subroutines, consider using functions for more
complex purposes.
Related
Return, Functions, IsLabel(), Blocks, Loop, Goto
Example
Gosub, Label1
MsgBox, The Label1 subroutine has returned (it is finished).
Printed Documentation
158
return

Label1:
MsgBox, The Label1 subroutine is now running.
return
Goto
Jumps to the specified label and continues execution.
Goto, Label
Parameters
Label The name of the label to which to jump.
Remarks
When using a dynamic label such as %MyLabel%, an error dialog will be displayed if the label does not
exist. To avoid this, call IsLabel() beforehand. For example:
if IsLabel(VarContainingLabelName)
Goto %VarContainingLabelName%
The use of Goto is discouraged because it generally makes scripts less readable and harder to
maintain. Consider using Else, Blocks, Break, and Continue as substitutes for Goto.
Related
Gosub, Return, IsLabel(), Else, Blocks, Break, Continue
Example
Goto, MyLabel
...
MyLabel:
Sleep, 100
...
If/IfEqual/IfNotEqual/IfLess/IfLessOrEqual/IfGreater/IfGreaterOrEqual
Specifies the command(s) to perform if the comparison of a variable to a value evalutes to TRUE.
When more than one command is present, enclose them in a block (braces).
IfEqual, var, value (same: if var = value)
IfNotEqual, var, value (same: if var <> value) (!= can be used in place of <>)
IfGreater, var, value (same: if var > value)
IfGreaterOrEqual, var, value (same: if var >= value)
IfLess, var, value (same: if var < value)
IfLessOrEqual, var, value (same: if var <= value)
If var ; If var's contents are blank or 0, it is considered false. Otherwise, it is true.

See also: IfInString
Flow of Control
159
Parameters
var The variable name.
value
A literal string, number, or variable reference (e.g. %var2%). Value can be
omitted if you wish to compare var to an empty string (blank).
Remarks
If both var and value are purely numeric, they will be compared as numbers rather than as strings.
Otherwise, they will be compared alphabetically as strings (that is, alphabetical order will determine
whether var is greater, equal, or less than value).
When an IF or an ELSE owns more than one line, those lines must be enclosed in braces. For example:
if count <= 0
{
WinClose Untitled - Notepad
MsgBox There are no items present.
}
However, if only one line belongs to the IF or ELSE, the braces are optional.
Another command can only appear on the same line as the IF statement if you use the command-
name style. In other words, these are valid:
IfEqual, x, 1, Sleep, 1
IfGreater, x, 1, EnvAdd, x, 2
But these are not valid:
if x = 1 Sleep 1
IfGreater, x, 1, x += 2
The One True Brace (OTB) style may not be used with these types of if-statements. It can only be
used with expression if-statements.
On a related note, the command "if var [not] between LowerBound and UpperBound" checks whether
a variable is between two values, and "if var [not] in value1,value2" can be used to check whether a
variable's contents exist within a list of values.
Related
IF (expression), Assign expression (:=), if var in/contains MatchList, if var between, IfInString, Blocks,
Else
Example
if counter >= 1
Sleep, 10

if counter >=1 ; If an IF has more than one line, enclose those lines in braces:
{
WinClose, Untitled - Notepad
Sleep 10
}
Printed Documentation
160

if MyVar = %MyVar2%
MsgBox The contents of MyVar and MyVar2 are identical.
else if MyVar =
{
MsgBox, 4,, MyVar is empty/blank. Continue?
IfMsgBox, No
Return
}
else if MyVar <> ,
MsgBox The value in MyVar is not a comma.
else
MsgBox The value in MyVar is a comma.

if Done
MsgBox The variable Done is neither empty nor zero.
if (expression)
Specifies the command(s) to perform if an expression evaluates to TRUE.
if (expression)
Remarks
An if-statement that contains an expression is differentiated from a traditional-if such as If FoundColor
<> Blue by making the character after the word "if" an open-parenthesis. Although this is usually
accomplished by enclosing the entire expression in parentheses, it can also be done with something
like if (x > 0) and (y > 0). In addition, the open-parenthesis may be omitted entirely if the first item
after the word "if" is a function call or an operator such as "not" or "!".
When an IF or an ELSE owns more than one line, those lines must be enclosed in braces. However, if
only one line belongs to an IF or ELSE, the braces are optional. See the examples below.
In v1.0.41+, the One True Brace (OTB) style may optionally be used with if-statements that are
expressions (but not traditional if-statements). For example:
if (x < y) {
...
}
if WinExist("Untitled - Notepad") {
WinActivate
}
if IsDone {
...
} else {
...
Flow of Control
161
}
Unlike an "else" statement -- which supports any type of statement immediately to its right -- an if-
statement supports only a "{" to its right.
On a related note, the command "if var [not] between LowerBound and UpperBound" checks whether
a variable is between two values, and "if var [not] in value1,value2" can be used to check whether a
variable's contents exist within a list of values.
Related
Expressions, Assign expression (:=), if var in/contains MatchList, if var between, IfInString, Blocks,
Else
Example
if (A_Index > 100 or Done)
return

if (A_TickCount - StartTime > 2*MaxTime + 100)
{
MsgBox Too much time has passed.
ExitApp
}

if (Color = "Blue" or Color = "White")
{
MsgBox The color is one of the allowed values.
ExitApp
}
else if (Color = "Silver")
{
MsgBox Silver is not an allowed color.
return
}
else
{
MsgBox This color is not recognized.
ExitApp
}
Loop (normal)
Perform a series of commands repeatedly: either the specified number of times or until break is
encountered.
Loop [, Count]
Printed Documentation
162
Parameters
Count
How many times (iterations) to perform the loop. If omitted, the Loop
continues indefinitely until a break or return is encountered.
If Count is a variable reference such as %ItemCount%, the loop is skipped
entirely whenever the variable is blank or contains a number less than 1.
Due to the need to support file-pattern loops, Count cannot be an expression.
However, as with all non-expression parameters, an expression can be forcibly
used by preceding it with a % and a space. For example: Loop % Count + 1.
In such cases, the expression is evaluated only once, right before the loop
begins.
Remarks
The loop command is usually followed by a block, which is a collection of statements that form the
body of the loop. However, a loop with only a single command does not require a block (an if-else
compound statement counts as a single command for this purpose).
A common use of this command is an infinite loop that uses the break command somewhere in the
loop's body to determine when to stop the loop.
The use of break and continue inside a loop are encouraged as alternatives to goto, since they
generally make a script more understandable and maintainable. To create a "While" loop, make the
first statement of the loop's body an IF statement that conditionally issues the break command. To
create a "Do...While" loop, use the same technique except put the IF statement as the last statement
in the loop's body.
The built-in variable A_Index contains the number of the current loop iteration. For example, the first
time the script executes the loop's body, this variable will contain the number 1. For the second time,
it will contain 2, and so on. If an inner loop is enclosed by an outer loop, the inner loop takes
precedence. The value will be 0 whenever the variable is referenced outside of a loop. This variable
works inside all types of loops, including file-loops and registry-loops.
In v1.0.41+, the One True Brace (OTB) style may optionally be used with normal loops (but not
specialized loops such as file-pattern and parsing). For example:
Loop {
...
}
Loop %RepeatCount% {
...
}
Specialized loops: Loops can be used to automatically retrieve files, folders, or registry items (one at a
time). See file-loop and registry-loop for details. In addition, file-reading loops can operate on the
entire contents of a file, one line at a time. Finally, parsing loops can operate on the individual fields
contained inside a delimited string.
Related
File loop, Registry loop, File-read loop, Parsing loop, Break, Continue, Blocks
Examples
Loop, 3
{
Flow of Control
163
MsgBox, Iteration number is %A_Index%. ; A_Index will be 1, 2, then 3
Sleep, 100
}

Loop
{
if a_index > 25
break ; Terminate the loop
if a_index < 20
continue ; Skip the below and start a new iteration
MsgBox, a_index = %a_index% ; This will display only the numbers 20 through 25
}
Loop (files & folders)
Retrieves the specified files or folders, one at a time.
Loop, FilePattern [, IncludeFolders?, Recurse?]
Parameters
FilePattern
The name of a single file or folder, or a wildcard pattern such as
C:\Temp\*.tmp. FilePattern is assumed to be in %A_WorkingDir% if an
absolute path isn't specified.
Both asterisks and question marks are supported as wildcards. A match
occurs when the pattern appears in either the file's long/normal name or its
8.3 short name.
If this parameter is a single file or folder (i.e. no wildcards) and Recurse is
set to 1, more than one match will be found if the specified file name
appears in more than one of the folders being searched.
IncludeFolders?
One of the following digits, or blank to use the default:
0 (default) Folders are not retrieved (only files).
1 All files and folders that match the wildcard pattern are retrieved.
2 Only folders are retrieved (no files).
Recurse?
One of the following digits, or blank to use the default:
0 (default) Subfolders are not recursed into.
1 Subfolders are recursed into so that files and folders contained therein are
retrieved if they match FilePattern. All subfolders will be recursed into, not
just those whose names match FilePattern.
Special Variables Available Inside a File-Loop
The following variables exist within any file-loop. If an inner file-loop is enclosed by an outer file-loop,
the innermost loop's file will take precedence:
A_LoopFileName
The name of the file or folder currently retrieved (without the
path).
A_LoopFileExt The file's extension (e.g. TXT, DOC, or EXE). The period (.) is not
Printed Documentation
164
[v1.0.36.02+] included.
A_LoopFileFullPath
The full path and name of the file/folder currently retrieved.
However, if FilePattern contains a relative path rather than an
absolute path, the path here will also be relative. In addition, any
short (8.3) folder names in FilePattern will still be short (see next
item to get the long version).
A_LoopFileLongPath
This is different than A_LoopFileFullPath in the following ways: 1) It
always contains the absolute/complete path of the file even if
FilePattern contains a relative path; 2) Any short (8.3) folder
names in FilePattern itself are converted to their long names; 3)
Characters in FilePattern are converted to uppercase or lowercase
to match the case stored in the file system. This is useful for
converting file names -- such as those passed into a script as
command line parameters -- to their exact path names as shown
by Explorer.
A_LoopFileShortPath
The 8.3 short path and name of the file/folder currently retrieved.
For example: C:\MYDOCU~1\ADDRES~1.txt. However, if
FilePattern contains a relative path rather than an absolute path,
the path here will also be relative.
To retrieve the complete 8.3 path and name for a single file or
folder, specify its name for FilePattern as in this example:
Loop, C:\My Documents\Address List.txt
ShortPathName = %A_LoopFileShortPath%
NOTE: This variable will be blank if the file does not have a short
name, which can happen on systems where
NtfsDisable8dot3NameCreation has been set in the registry. It will
also be blank if FilePattern contains a relative path and the body of
the loop uses SetWorkingDir to switch away from the working
directory in effect for the loop itself.
A_LoopFileShortName
The 8.3 short name, or alternate name of the file. If the file doesn't
have one (due to the long name being shorter than 8.3 or perhaps
because short-name generation is disabled on an NTFS file
system), A_LoopFileName will be retrieved instead.
A_LoopFileDir
The full path of the directory in which A_LoopFileName resides.
However, if FilePattern contains a relative path rather than an
absolute path, the path here will also be relative. A root directory
will not contain a trailing backslash. For example: C:
A_LoopFileTimeModified The time the file was last modified. Format YYYYMMDDHH24MISS.
A_LoopFileTimeCreated The time the file was created. Format YYYYMMDDHH24MISS.
A_LoopFileTimeAccessed The time the file was last accessed. Format YYYYMMDDHH24MISS.
A_LoopFileAttrib The attributes of the file currently retrieved.
A_LoopFileSize
The size in bytes of the file currently retrieved. Files larger than 4
gigabytes are also supported.
A_LoopFileSizeKB
The size in Kbytes of the file currently retrieved, rounded down to
the nearest integer.
A_LoopFileSizeMB
The size in Mbytes of the file currently retrieved, rounded down to
the nearest integer.
Remarks
A file-loop is useful when you want to operate on a collection of files and/or folders, one at a time.
Flow of Control
165
All matching files are retrieved, including hidden files. By contrast, OS features such as the DIR
command omit hidden files by default. To avoid processing hidden, system, and/or read-only files, use
something like the following inside the loop:
if A_LoopFileAttrib contains H,R,S ; Skip any file that is either H (Hidden), R (Read-only), or S
(System). Note: No spaces in "H,R,S".
continue ; Skip this file and move on to the next one.
To retrieve files' relative paths instead of absolute paths during a recursive search, use SetWorkingDir
to change to the base folder prior to the loop, and then omit the path from the Loop (e.g. Loop, *.*,
0, 1). That will cause A_LoopFileFullPath to contain the file's path relative to the base folder.
A file-loop can disrupt itself if it creates or renames files or folders within its own purview. For
example, if it renames files via FileMove or other means, each such file might be found twice: once as
its old name and again as its new name. To work around this, rename the files only after creating a
list of them. For example:
FileList =
Loop *.jpg
FileList = %FileList%%A_LoopFileName%`n
Loop, parse, FileList, `n
FileMove, %A_LoopField%, renamed_%A_LoopField%
Files in an NTFS file system are probably always retrieved in alphabetical order. Files in other file
systems are retrieved in no particular order. To ensure a particular ordering, use the Sort command as
shown in the Examples section below.
See Loop for information about Blocks, Break, Continue, and the A_Index variable (which exists in
every type of loop).
Related
Loop, Break, Continue, Blocks, SplitPath, FileSetAttrib, FileSetTime
Examples
; Example #1:
Loop, %A_ProgramFiles%\*.txt, , 1 ; Recurse into subfolders.
{
MsgBox, 4, , Filename = %A_LoopFileFullPath%`n`nContinue?
IfMsgBox, No
break
}

; Example #2: Calculate the size of a folder, including the files in all its subfolders:
SetBatchLines, -1 ; Make the operation run at maximum speed.
FolderSizeKB = 0
FileSelectFolder, WhichFolder ; Ask the user to pick a folder.
Loop, %WhichFolder%\*.*, , 1
FolderSizeKB += %A_LoopFileSizeKB%
MsgBox Size of %WhichFolder% is %FolderSizeKB% KB.
Printed Documentation
166

; Example #3: Retrieve file names sorted by name (see next example to sort by date):
FileList = ; Initialize to be blank.
Loop, C:\*.*
FileList = %FileList%%A_LoopFileName%`n
Sort, FileList, R ; The R option sorts in reverse order. See Sort for other options.
Loop, parse, FileList, `n
{
if A_LoopField = ; Ignore the blank item at the end of the list.
continue
MsgBox, 4,, File number %A_Index% is %A_LoopField%. Continue?
IfMsgBox, No
break
}

; Example #4: Retrieve file names sorted by modification date:
FileList =
Loop, %A_MyDocuments%\Photos\*.*, 1
FileList = %FileList%%A_LoopFileTimeModified%`t%A_LoopFileName%`n
Sort, FileList ; Sort by date.
Loop, parse, FileList, `n
{
if A_LoopField = ; Omit the last linefeed (blank item) at the end of the list.
continue
StringSplit, FileItem, A_LoopField, %A_Tab% ; Split into two parts at the tab char.
MsgBox, 4,, The next file (modified at %FileItem1%) is:`n%FileItem2%`n`nContinue?
IfMsgBox, No
break
}

; Example #5: Copy only the source files that are newer than their counterparts
; in the destination:
CopyIfNewer:
; Caller has set the variables CopySourcePattern and CopyDest for us.
Loop, %CopySourcePattern%
{
copy_it = n
IfNotExist, %CopyDest%\%A_LoopFileName% ; Always copy if target file doesn't yet exist.
Flow of Control
167
copy_it = y
else
{
FileGetTime, time, %CopyDest%\%A_LoopFileName%
EnvSub, time, %A_LoopFileTimeModified%, seconds ; Subtract the source file's time from the
destination's.
if time < 0 ; Source file is newer than destination file.
copy_it = y
}
if copy_it = y
{
FileCopy, %A_LoopFileFullPath%, %CopyDest%\%A_LoopFileName%, 1 ; Copy with
overwrite=yes
if ErrorLevel
MsgBox, Could not copy "%A_LoopFileFullPath%" to "%CopyDest%\%A_LoopFileName%".
}
}
Return

; Example #6: Convert filenames passed in via command-line parameters to long names,
; complete path, and correct uppercase/lowercase characters as stored in the file system.
Loop %0% ; For each file dropped onto the script (or passed as a parameter).
{
GivenPath := %A_Index% ; Retrieve the next command line parameter.
Loop %GivenPath%
LongPath = %A_LoopFileLongPath%
MsgBox The case-corrected long path name of file`n%GivenPath%`nis:`n%LongPath%
}
Loop (parse a string)
Retrieves substrings (fields) from a string, one at a time.
Loop, Parse, InputVar [, Delimiters, OmitChars]
Parameters
Parse
This parameter must be the word PARSE, and unlike other loop types, it must
not be a variable reference that resolves to the word PARSE.
InputVar
The name of the variable whose contents will be analyzed. Do not enclose the
name in percent signs unless you want the contents of the variable to be used
as the name.
Printed Documentation
168
Delimiters
If this parameter is blank or omitted, each character of InputVar will be treated
as a separate substring.
If this parameter is CSV, InputVar will be parsed in standard comma separated
value format. Here is an example of a CSV line produced by MS Excel: "first
field",SecondField,"the word ""special"" is quoted literally",,"last field, has
literal comma"
Otherwise, Delimiters contains one or more characters (case sensitive), each
of which is used to determine where the boundaries between substrings occur
in InputVar.
Delimiter characters are not considered to be part of the substrings
themselves. In addition, if there is nothing between a pair of delimiters within
InputVar, the corresponding substring will be empty.
For example: `, (an escaped comma) would divide the string based on every
occurrence of a comma. Similarly, %A_Tab%%A_Space% would start a new
substring every time a space or tab is encountered in InputVar.
To use a string as a delimiter rather than a character, first use StringReplace
to replace all occurrences of the string with a single character that is never
used literally in the text, e.g. one of these special characters: .
Consider this example, which uses the string <br> as a delimiter:
StringReplace, NewHTML, HTMLString, <br>, , All ; Replace each
<br> with a cent symbol.
Loop, parse, NewHTML, ; Parse the string based on the cent symbol.
{
..
}
OmitChars
An optional list of characters (case sensitive) to exclude from the beginning
and end of each substring. For example, if OmitChars is
%A_Space%%A_Tab%, spaces and tabs will be removed from the beginning
and end (but not the middle) of every retrieved substring.
If Delimiters is blank, OmitChars indicates which characters should be excluded
from consideration (the loop will not see them).
Unlike the last parameter of most other commands, commas in OmitChars
must be escaped (`,).
Remarks
A string parsing loop is useful when you want to operate on each field contained in a string, one at a
time. Parsing loops use less memory than StringSplit (since StringSplit creates a permanent array)
and in most cases they are easier to use.
The built-in variable A_LoopField exists within any parsing loop. It contains the contents of the
current substring (field) from InputVar. If an inner parsing loop is enclosed by an outer parsing loop,
the innermost loop's field will take precedence.
There is no restriction on the size of InputVar or its fields. In addition, if InputVar's contents change
during the execution of the loop, the loop will not "see" the changes because it is operating on a
temporary copy of the original contents.
To arrange the fields in a different order prior to parsing, use the Sort command.
Flow of Control
169
See Loop for information about Blocks, Break, Continue, and the A_Index variable (which exists in
every type of loop).
Related
StringSplit, file-reading loop, Loop, Break, Continue, Blocks, Sort, FileSetAttrib, FileSetTime
Examples
; Example #1:
Colors = red,green,blue
Loop, parse, Colors, `,
{
MsgBox, Color number %A_Index% is %A_LoopField%.
}

; Example #2: Read the lines inside a variable, one by one (similar to a file-reading loop).
; A file can be loaded into a variable via FileRead:
Loop, parse, FileContents, `n, `r ; Specifying `n prior to `r allows both Windows and Unix files to be
parsed.
{
MsgBox, 4, , Line number %A_Index% is %A_LoopField%.`n`nContinue?
IfMsgBox, No, break
}

; Example #3: This is the same as the example above except that it's for the clipboard.
; It's useful whenever the clipboard contains files, such as those copied from an open
; Explorer window (the program automatically converts such files to their file names):
Loop, parse, clipboard, `n, `r
{
MsgBox, 4, , File number %A_Index% is %A_LoopField%.`n`nContinue?
IfMsgBox, No, break
}

; Example #4: Parse a comma separated value (CSV) file:
Loop, read, C:\Database Export.csv
{
LineNumber = %A_Index%
Loop, parse, A_LoopReadLine, CSV
{
MsgBox, 4, , Field %LineNumber%-%A_Index% is:`n%A_LoopField%`n`nContinue?
IfMsgBox, No
Printed Documentation
170
return
}
}
Loop (read file contents)
Retrieves the lines in a text file, one at a time (performs better than FileReadLine).
Loop, Read, InputFile [, OutputFile]
Parameters
Read This parameter must be the word READ.
InputFile
The name of the text file whose contents will be read by the loop, which is
assumed to be in %A_WorkingDir% if an absolute path isn't specified.
Windows and Unix formats are supported; that is, the file's lines may end in
either carriage return and linefeed (`r`n) or just linefeed (`n).
OutputFile
(Optional) The name of the file to be kept open for the duration of the loop,
which is assumed to be in %A_WorkingDir% if an absolute path isn't specified.
Within the loop's body, use the FileAppend command with only one parameter
(the text to be written) to append to this special file. Appending to a file in this
manner performs better than using FileAppend in its 2-parameter mode
because the file does not need to be closed and re-opened for each operation.
Remember to include a linefeed (`n) after the text, if desired.
To append in binary mode rather than text mode, prepend an asterisk to the
filename. This causes each linefeed character (`n) to be written as as a single
linefeed (LF) rather than the Windows standard of CR+LF. For example:
*C:\My Unix File.txt.
The file is not opened if nothing is ever written to it. This happens if the Loop
performs zero iterations or if it never uses the FileAppend command. In
addition, the file is automatically opened in binary mode if the Loop's first use
of FileAppend writes any carriage return and linefeed pairs (`r`n). In other
words, the asterisk option described in the previous paragraph is put into
effect automatically.
Specifying an asterisk (*) for OutputFile sends any text written by FileAppend
to standard output (stdout). Although such output can be redirected to a file,
piped to another EXE, or captured by fancy text editors, it will not appear at
the command prompt it was launched from. For example, the following would
be valid if typed at a command prompt:
"%ProgramFiles%\AutoHotkey\AutoHotkey.exe" "My Script.ahk" >"Error
Log.txt"
Unlike the last parameter of most other commands, commas in OutputFile
must be escaped (`,).
Remarks
A file-read loop is useful when you want to operate each line contained in a text file, one at a time. It
performs better than using FileReadLine because: 1) the file can be kept open for the entire operation;
and 2) the file does not have to be re-scanned each time to find the requested line number.
The built-in variable A_LoopReadLine exists within any file-read loop. It contains the contents of the
current line excluding the carriage return and linefeed (`r`n) that marks the end of the line. If an
inner file-read loop is enclosed by an outer file-read loop, the innermost loop's file-line will take
precedence.
Flow of Control
171
Lines up to 65,534 characters long can be read. If the length of a line exceeds this, its remaining
characters will be read during the next loop iteration.
StringSplit or a parsing loop is often used inside a file-read loop to parse the contents of each line
retrieved from InputFile. For example, if InputFile's lines are each a series of tab-delimited fields,
those fields can individually retrieved as in this example:
Loop, read, C:\Database Export.txt
{
Loop, parse, A_LoopReadLine, %A_Tab%
{
MsgBox, Field number %A_Index% is %A_LoopField%.
}
}
To load an entire file into variable, use FileRead because it performs much better than a loop
(especially for large files).
To have multiple files open simultaneously, use DllCall() as shown in this example.
See Loop for information about Blocks, Break, Continue, and the A_Index variable (which exists in
every type of loop).
Related
FileRead, FileReadLine, FileAppend, Sort, Loop, Break, Continue, Blocks, FileSetAttrib, FileSetTime
Examples
; Example #1: Only those lines of the 1st file that contain the word FAMILY will be written to the 2nd
file.
; Uncomment the first line to overwrite rather than append to any existing file.
;FileDelete, C:\Docs\Family Addresses.txt

Loop, read, C:\Docs\Address List.txt, C:\Docs\Family Addresses.txt
{
IfInString, A_LoopReadLine, family, FileAppend, %A_LoopReadLine%`n
}

; Example #2: Retrieve the last line from a text file.
Loop, read, C:\Log File.txt
last_line := A_LoopReadLine ; When loop finishes, this will hold the last line.

; Example #3: A working script that attempts to extract all FTP and HTTP
; URLs from a text or HTML file:
FileSelectFile, SourceFile, 3,, Pick a text or HTML file to analyze.
if SourceFile =
return ; This will exit in this case.
Printed Documentation
172

SplitPath, SourceFile,, SourceFilePath,, SourceFileNoExt
DestFile = %SourceFilePath%\%SourceFileNoExt% Extracted Links.txt

IfExist, %DestFile%
{
MsgBox, 4,, Overwrite the existing links file? Press No to append to it.`n`nFILE: %DestFile%
IfMsgBox, Yes
FileDelete, %DestFile%
}

LinkCount = 0
Loop, read, %SourceFile%, %DestFile%
{
URLSearchString = %A_LoopReadLine%
Gosub, URLSearch
}
MsgBox %LinkCount% links were found and written to "%DestFile%".
return


URLSearch:
; It's done this particular way because some URLs have other URLs embedded inside them:
StringGetPos, URLStart1, URLSearchString, http://
StringGetPos, URLStart2, URLSearchString, ftp://
StringGetPos, URLStart3, URLSearchString, www.

; Find the left-most starting position:
URLStart = %URLStart1% ; Set starting default.
Loop
{
; It helps performance (at least in a script with many variables) to resolve
; "URLStart%A_Index%" only once:
ArrayElement := URLStart%A_Index%
if ArrayElement = ; End of the array has been reached.
break
if ArrayElement = -1 ; This element is disqualified.
continue
Flow of Control
173
if URLStart = -1
URLStart = %ArrayElement%
else ; URLStart has a valid position in it, so compare it with ArrayElement.
{
if ArrayElement <> -1
if ArrayElement < %URLStart%
URLStart = %ArrayElement%
}
}

if URLStart = -1 ; No URLs exist in URLSearchString.
return

; Otherwise, extract this URL:
StringTrimLeft, URL, URLSearchString, %URLStart% ; Omit the beginning/irrelevant part.
Loop, parse, URL, %A_Tab%%A_Space%<> ; Find the first space, tab, or angle (if any).
{
URL = %A_LoopField%
break ; i.e. perform only one loop iteration to fetch the first "field".
}
; If the above loop had zero iterations because there were no ending characters found,
; leave the contents of the URL var untouched.

; If the URL ends in a double quote, remove it. For now, StringReplace is used, but
; note that it seems that double quotes can legitimately exist inside URLs, so this
; might damage them:
StringReplace, URLCleansed, URL, ",, All
FileAppend, %URLCleansed%`n
LinkCount += 1

; See if there are any other URLs in this line:
StringLen, CharactersToOmit, URL
CharactersToOmit += %URLStart%
StringTrimLeft, URLSearchString, URLSearchString, %CharactersToOmit%
Gosub, URLSearch ; Recursive call to self.
return
Loop (registry)
Retrieves the contents of the specified registry subkey, one item at a time.
Printed Documentation
174
Loop, RootKey [, Key, IncludeSubkeys?, Recurse?]
Parameters
RootKey
Must be either HKEY_LOCAL_MACHINE (or HKLM), HKEY_USERS (or HKU),
HKEY_CURRENT_USER (or HKCU), HKEY_CLASSES_ROOT (or HKCR), or
HKEY_CURRENT_CONFIG (or HKCC).
To access a remote registry, prepend the computer name and a colon, as
in this example: \\workstation01:HKEY_LOCAL_MACHINE
Key
The name of the key (e.g. Software\SomeApplication). If blank or omitted,
the contents of RootKey will be retrieved.
IncludeSubkeys?
0 (default) Subkeys contained within Key are not retrieved (only the
values).
1 All values and subkeys are retrieved.
2 Only the subkeys are retrieved (not the values).
Recurse?
0 (default) Subkeys are not recursed into.
1 Subkeys are recursed into, so that all values and subkeys contained
therein are retrieved.
Remarks
A registry-loop is useful when you want to operate on a collection registry values or subkeys, one at a
time. The values and subkeys are retrieved in reverse order (bottom to top) so that RegDelete can be
used inside the loop without disrupting the loop.
The following variables exist within any registry-loop. If an inner registry-loop is enclosed by an outer
registry-loop, the innermost loop's registry item will take precedence:
A_LoopRegName
Name of the currently retrieved item, which can be either a value
name or the name of a subkey. Value names displayed by Windows
RegEdit as "(Default)" will be retrieved if a value has been assigned
to them, but A_LoopRegName will be blank for them.
A_LoopRegType
The type of the currently retrieved item, which is one of the
following words: KEY (i.e. the currently retrieved item is a subkey
not a value), REG_SZ, REG_EXPAND_SZ, REG_MULTI_SZ,
REG_DWORD, REG_QWORD, REG_BINARY, REG_LINK,
REG_RESOURCE_LIST, REG_FULL_RESOURCE_DESCRIPTOR,
REG_RESOURCE_REQUIREMENTS_LIST,
REG_DWORD_BIG_ENDIAN (probably rare on most Windows
hardware). It will be empty if the currently retrieved item is of an
unknown type.
A_LoopRegKey
The name of the root key being accessed (HKEY_LOCAL_MACHINE,
HKEY_USERS, HKEY_CURRENT_USER, HKEY_CLASSES_ROOT, or
HKEY_CURRENT_CONFIG). For remote registry access, this value
will not include the computer name.
A_LoopRegSubKey
Name of the current SubKey. This will be the same as the Key
parameter unless the Recurse parameter is being used to
recursively explore other subkeys. In that case, it will be the full
path of the currently retrieved item, not including the root key. For
example: Software\SomeApplication\My SubKey
A_LoopRegTimeModified
The time the current subkey or any of its values was last modified.
Format YYYYMMDDHH24MISS. This variable will be empty if the
currently retrieved item is not a subkey (i.e. A_LoopRegType is not
Flow of Control
175
the word KEY) or if the operating system is Win9x (since Win9x
does not track this info).
When used inside a registry-loop, the following commands can be used in a simplified way to indicate
that the currently retrieved item should be operated upon:
RegRead,
OutputVar
Reads the current item. If the current item is a key, ErrorLevel will be set
to 1 and OutputVar will be made empty.
RegWrite [, Value]
Writes to the current item. If Value is omitted, the item will be made 0 or
blank depending on its type. If the current item is a key, ErrorLevel will
be set to 1 and there will be no other effect.
RegDelete
Deletes the current item. If the current item is a key, it will be deleted
along with any subkeys and values it contains.
When accessing a remote registry (via the RootKey parameter described above), the following notes
apply:
The target machine must be running the Remote Registry service, or (for Windows Me/98/95) have
the Microsoft Remote Registry service installed (this can be obtained from Microsoft).
Access to a remote registry may fail if the target computer is not in the same domain as yours or the
local or remote username lacks sufficient permissions (however, see below for possible workarounds).
Depending on your username's domain, workgroup, and/or permissions, you may have to connect to a
shared device, such as by mapping a drive, prior to attempting remote registry access. Making such a
connection -- using a remote username and password that has permission to access or edit the
registry -- may as a side-effect enable remote registry access.
If you're already connected to the target computer as a different user (for example, a mapped drive
via user Guest), you may have to terminate that connection to allow the remote registry feature to
reconnect and re-authenticate you as your own currently logged-on username.
For Windows Server 2003 and Windows XP Professional, MSDN states: "If the computer is joined to a
workgroup and the "Force network logons using local accounts to authenticate as Guest" policy is
enabled, the function fails. Note that this policy is enabled by default if the computer is joined to a
workgroup."
For Windows XP Home Edition, MSDN states that "this function always fails".
If anyone knows for certain whether the last two items above apply to the local computer, the remote
computer, or both, please contact the author.
See Loop for information about Blocks, Break, Continue, and the A_Index variable (which exists in
every type of loop).
Related
Loop, Break, Continue, Blocks, RegRead, RegWrite, RegDelete
Examples
; Example: Delete Internet Explorer's history of URLs typed by the user:
Loop, HKEY_CURRENT_USER, Software\Microsoft\Internet Explorer\TypedURLs
RegDelete

; Example: A working test script:
Loop, HKEY_CURRENT_USER, Software\Microsoft\Windows, 1, 1
{
if a_LoopRegType = key
value =
Printed Documentation
176
else
{
RegRead, value
if ErrorLevel
value = *error*
}
MsgBox, 4, , %a_LoopRegName% = %value% (%a_LoopRegType%)`n`nContinue?
IfMsgBox, NO, break
}

; Example: A working example to recursively search the entire
; registry for particular value(s).
SetBatchLines -1 ; Makes searching occur at maximum speed.
RegSearchTarget = Notepad ; Tell the subroutine what to search for.
Gosub, RegSearch
return

RegSearch:
ContinueRegSearch = y
Loop, HKEY_LOCAL_MACHINE, , 1, 1
{
Gosub, CheckThisRegItem
if ContinueRegSearch = n ; It told us to stop.
return
}
Loop, HKEY_USERS, , 1, 1
{
Gosub, CheckThisRegItem
if ContinueRegSearch = n ; It told us to stop.
return
}
Loop, HKEY_CURRENT_CONFIG, , 1, 1
{
Gosub, CheckThisRegItem
if ContinueRegSearch = n ; It told us to stop.
return
}
; Note: I believe HKEY_CURRENT_USER does not need to be searched if HKEY_USERS
Flow of Control
177
; is being searched. The same might also be true for HKEY_CLASSES_ROOT if
; HKEY_LOCAL_MACHINE is being searched.
return

CheckThisRegItem:
if A_LoopRegType = KEY ; Remove these two lines if you want to check key names too.
return
RegRead, RegValue
if ErrorLevel
return
IfInString, RegValue, %RegSearchTarget%
{
MsgBox, 4, , The following match was
found:`n%A_LoopRegKey%\%A_LoopRegSubKey%\%A_LoopRegName%`nValue =
%RegValue%`n`nContinue?
IfMsgBox, No
ContinueRegSearch = n ; Tell our caller to stop searching.
}
return
OnExit
Specifies a subroutine to run automatically when the script exits.
OnExit [, Label]
Parameters
Label
If omitted, the script is returned to its normal exit behavior. Otherwise, specify
the name of the label whose contents will be executed (as a new thread) when
the script exits by any means.
IMPORTANT: Since the specified subroutine is called instead of terminating the script, that
subroutine must use the ExitApp command if termination is desired. Alternatively (as in the Examples
section below), the OnExit subroutine might display a MsgBox to prompt the user for confirmation --
and only if the user presses YES would the script execute ExitApp to close itself.
Remarks
The OnExit subroutine is called when the script exits by any means (except when it is killed by
something like "End Task"). It is also called whenever the #SingleInstance and Reload commands ask
a previous instance to terminate.
A script can detect and optionally abort a system shutdown or logoff via OnMessage(0x11,
"WM_QUERYENDSESSION").
The OnExit thread does not obey #MaxThreads (it will always launch when needed). In addition, while
it is running, it cannot be interrupted by any thread, including hotkeys, custom menu items, and timed
subroutines. However, it will be interrupted (and the script will terminate) if the user chooses Exit
from the tray menu or main menu, or the script is asked to terminate as a result of Reload or
Printed Documentation
178
#SingleInstance. Because of this, the OnExit subroutine should be designed to finish quickly unless
the user is aware of what it is doing.
If the OnExit thread encounters a failure condition such as a runtime error, the script will terminate.
This prevents a flawed OnExit subroutine from making a script impossible to terminate.
If the OnExit subroutine was launched due to an Exit or ExitApp command that specified an exit code,
that code is ignored and no longer available. A new exit code can be specified by the OnExit
subroutine if/when it calls ExitApp.
Whenever the OnExit subroutine is called by an exit attempt, it starts off fresh with the default values
for settings such as SendMode. These defaults can be changed in the auto-execute section.
The built-in variable A_ExitReason is blank unless the OnExit subroutine is currently running or has
been called at least once by a prior exit attempt. If not blank, it is one of the following words:
Logoff The user is logging off.
Shutdown The system is being shut down or restarted, such as by the Shutdown command.
Close
The script was sent a WM_CLOSE or WM_QUIT message, had a critical error, or is
being closed in some other way. Although all of these are unusual, WM_CLOSE
might be caused by WinClose having been used on the script's main window. To
prevent this, dismiss the main window with Send, !{F4}.
Error
A runtime error occurred in a script that has no hotkeys and that is not persistent.
An example of a runtime error is Run/RunWait being unable to launch the
specified program or document.
Menu
The user selected Exit from the main window's menu or from the standard tray
menu.
Exit The Exit or ExitApp command was used (includes custom menu items).
Reload The script is being reloaded via the Reload command or menu item.
Single
The script is being replaced by a new instance of itself as a result of
#SingleInstance.
Related
OnMessage(), OnClipboardChange, ExitApp, Shutdown, #Persistent, Threads, Gosub, Return, Menu
Example
#Persistent ; For demonstration purposes, keep the script running if the user chooses "No".
OnExit, ExitSub
return

ExitSub:
if A_ExitReason not in Logoff,Shutdown ; Avoid spaces around the comma in this line.
{
MsgBox, 4, , Are you sure you want to exit?
IfMsgBox, No
return
}
ExitApp ; The only way for an OnExit script to terminate itself is to use ExitApp in the OnExit
subroutine.
Flow of Control
179
Pause
Pauses the script's current thread.
Pause [, On|Off|Toggle, OperateOnUnderlyingThread?]
Parameters
On|Off|Toggle
If blank or omitted, it defaults to Toggle. Otherwise, specify
one of the following words:
Toggle: Pauses the current thread unless the thread beneath
it is paused, in which case the underlying thread is unpaused.
On: Pauses the current thread.
Off: If the thread beneath the current thread is paused, it will
be in an unpaused state when resumed. Otherwise, the
command has no effect.
OperateOnUnderlyingThread?
[v1.0.37.06+]
This parameter is ignored for "Pause Off". For the others, it is
ignored unless Pause is being turned on (including via Toggle).
Specify one of the following numbers:
0 or omitted: The command pauses the current thread; that
is, the one now running the Pause command.
1: The command marks the thread beneath the current thread
as paused so that when it resumes, it will finish the command
it was running (if any) and then enter a paused state. If there
is no thread beneath the current thread, the script itself is
paused, which prevents timers from running (this effect is the
same as having used the menu item "Pause Script" while the
script has no threads).
Remarks
Unlike Suspend -- which disables hotkeys and hotstrings-- pause will freeze the thread. As a side-
effect, any interrupted threads beneath it will lie dormant.
Whenever any thread is paused, timers will not run. By contrast, explicitly launched threads such as
hotkeys and menu items can still be launched; but when their threads finish, the underlying
interrupted thread will still be paused. In other words, each thread can be paused independently of
the others.
The color of the tray icon changes from green to red whenever the script's current thread is in a
paused state. This can be avoided by freezing the icon, which is achieved by specifying 1 for the last
parameter of the Menu command. For example:
Menu, Tray, Icon, C:\My Icon.ico, , 1
To disable timers without pausing the script, use "Thread, NoTimers".
The Pause command is similar in function to the built-in menu item "Pause Script".
A script is always halted (though not officially paused) while it is displaying any kind of menu (tray
menu, menu bar, GUI context menu, etc.)
Related
Suspend, Menu, ExitApp, Threads, SetTimer
Printed Documentation
180
Examples
Pause::Pause ; Assign the toggle-pause function to the "pause" key...
#p::Pause ; ... or assign it to Win+p or some other hotkey.
Return
Returns from a subroutine to which execution had previously jumped via function-call, Gosub, Hotkey
activation, GroupActivate, or other means.
Return [, Expression]
Parameters
Expression
This parameter should be omitted except when return is used inside a function.
Since this parameter is an expression, all of the following are valid examples:
return 3
return "literal string"
return MyVar
return i + 1
return true ; Returns the number 1 to mean "true".
return ItemCount < MaxItems ; Returns a true or false value.
return FindColor(TargetColor)
Known limitation: For backward compatibility and ease-of-use, the following
two examples are functionally identical:
return MyVar
return %MyVar%
In other words, a single variable enclosed in percent signs is treated as a non-
expression. To work around this, make it unambiguously an expression by
enclosing it in parentheses; for example: return (%MyVar%)
Remarks
If there is no caller to which to return, Return will do an Exit instead.
Related
Functions, Gosub, Exit, ExitApp, GroupActivate
Example
#z::
MsgBox The Win-Z hotkey was pressed.
Gosub MySubroutine
return

MySubroutine:
Flow of Control
181
Sleep 1000
return
SetBatchLines
Determines how fast a script will run (affects CPU utilization).
SetBatchLines, 20ms
SetBatchLines, LineCount
Parameters
20ms
(The 20ms is just an example). If the value ends in ms, it indicates how often
the script should sleep (each sleep is 10 ms long). In the following example,
the script will sleep for 10ms every time it has run for 20ms: SetBatchLines,
20ms
LineCount
The number of script lines to execute prior to sleeping for 10ms. The value can
be as high as 9223372036854775807.
Remarks
Use SetBatchLines -1 to never sleep (i.e. have the script run at maximum speed).
If this command is not used:
AutoIt v2 (.aut) scripts default to SetBatchLines 1, which sleeps after every line.
All other types of scripts (e.g. .ahk) default to SetBatchLines 10ms except in versions prior to
v1.0.16, which use 10 (lines) instead.
The "ms" method is recommended for scripts whenever speed and cooperation are important. For
example, on most systems a setting of 10ms will prevent the script from using any more than 50% of
an idle CPU's time. This allows scripts to run quickly while still maintaining a high level of cooperation
with CPU sensitive tasks such as games and video capture/playback.
The built-in variable A_BatchLines contains the current setting.
The speed of a script can also be impacted by the following commands, depending on the nature of
the script: SetWinDelay, SetControlDelay, SendMode, SetKeyDelay, SetMouseDelay, and
SetDefaultMouseSpeed.
Every newly launched thread (such as a hotkey, custom menu item, or timed subroutine) starts off
fresh with the default setting for this command. That default may be changed by using this command
in the auto-execute section (top part of the script).
Related
SetWinDelay, SetControlDelay, SendMode, SetKeyDelay, SetMouseDelay, SetDefaultMouseSpeed
Example
SetBatchLines, 10ms
SetBatchLines, 1000
SetTimer
Causes a subroutine to be launched automatically and repeatedly at a specified time interval.
SetTimer, Label [, Period|On|Off, Priority]
Printed Documentation
182
Parameters
Label
The name of the label or hotkey label to which to jump, which causes the
commands beneath Label to be executed until a Return or Exit is encountered.
As with the parameters of almost all other commands, Label can be a variable
reference such as %MyLabel%, in which case the name stored in the variable
is used as the target.
Period|On|Off
On: Re-enables a previously disabled timer at its former period. If the timer
doesn't exist, it is created (with a default period of 250).
Off: Disables an existing timer.
Period: Creates or updates a timer using this parameter as the number of
milliseconds that must pass since the last time the Label subroutine was
started. When this amount of time has passed, Label will be run again (unless
it is still running from the last time). The timer will be automatically enabled.
To prevent this, call the command a second time immediately afterward,
specifying OFF for this parameter.
If this parameter is blank and:
1) the timer does not exist: it will be created with a period of 250.
2) the timer already exists: it will be enabled and reset at its former period
unless a Priority is specified.
Priority
This optional parameter is an integer between -2147483648 and 2147483647
(or an expression) to indicate this timer's thread priority. If omitted, 0 will be
used. See Threads for details.
To change the priority of an existing timer without affecting it in any other
way, leave the parameter before this one blank.
Remarks
Timers are useful because they run asynchronously, meaning that they will run at the specified
frequency (interval) even when the script is waiting for a window, displaying a dialog, or busy with
another task. Examples of their many uses include taking some action when the user becomes idle (as
reflected by %A_TimeIdle%) or closing unwanted windows the moment they appear.
Although timers may give the illusion that the script is performing more than one task simultaneously,
this is not the case. Instead, timed subroutines are treated just like other threads: they can interrupt
or be interrupted by another thread, such as a hotkey subroutine. See Threads for details.
Whenever a timer is created, re-enabled, or updated with a new period, it will not run right away; its
time period must expire first. If you wish the timer's first execution to be immediate, use Gosub to
execute the timer's subroutine (however, this will not start a new thread like the timer itself does; so
settings such as SendMode will not start off at their defaults).
If SetTimer is used on an existing timer and parameter #2 is a number or the word ON (or it is
omitted), the timer's internal "time of last run" will be reset to the current time; in other words, the
entirety of its period must elapse before it will run again.
Currently, timers cannot run much more often than every 10ms on Windows XP/2000/NT and about
55ms on Windows 9x. Specifying a Period less than this will usually result in an actual interval of 10 or
55 (but this policy could change in future versions so shouldn't be relied upon).
A timer might not be able to run as often as specified under the following conditions:
Other applications are putting a heavy load on the CPU.
1. The timer subroutine itself takes longer than its own period to run, or there are too many
other competing timers (altering SetBatchLines may help).
Flow of Control
183
2. The timer has been interrupted by another thread, namely another timed subroutine, hotkey
subroutine, or custom menu item. If this happens and the interrupting thread takes a long
time to finish, the interrupted timer will be effectively disabled for the duration. However, any
other timers will continue to run by interrupting the thread that interrupted the first timer.
3. The script is uninterruptible as a result of Critical or Thread Interrupt/Priority. During such
times, timers will not run. Later, when the script becomes interruptible again, any overdue
timer will run once as soon as possible and then resume its normal schedule.
Because timers operate by temporarily interrupting the script's current activity, their subroutines
should be kept short (so that they finish quickly) whenever a long interruption would be undesirable.
Timers that stay in effect for the duration of a script should usually be created in the auto-execute
section. By contrast, a temporary timer might often be disabled by its own subroutine (see examples
at the bottom of this page).
Whenever a timed subroutine is run, it starts off fresh with the default values for settings such as
SendMode. These defaults can be changed in the auto-execute section.
Although timers will operate when the script is suspended, they will not run if the current thread has
"Thread NoTimers" in effect or whenever any thread is paused. In addition, they do not operate when
the user is navigating through one of the script's menus (such as the tray icon menu or a menu bar).
If hotkey response time is crucial (such as in games) and the script contains any timers whose
subroutines take longer than about 5 ms to execute, use the following command to avoid any chance
of a 15 ms delay. Such a delay would otherwise happen if a hotkey is pressed at the exact moment a
timer thread is in its period of uninterruptibility:
Thread, interrupt, 0 ; Make all threads always-interruptible.
If a timer is disabled while its subroutine is currently running, that subroutine will continue until it
completes.
The KeyHistory feature shows how many timers exist and how many are currently enabled.
In v1.0.36.03+, a timer's period can be no larger than 4294967295 milliseconds (49.7 days). In
earlier versions, the limit is 2147483647 milliseconds (24.8 days).
To keep a script running -- such as one that contains only timers -- use #Persistent.
Related
Gosub, Return, Threads, Thread (command), Critical, IsLabel(), Menu, #Persistent
Examples
; Example #1: Close unwanted windows whenever they appear:
#Persistent
SetTimer, CloseMailWarnings, 250
return

CloseMailWarnings:
WinClose, Microsoft Outlook, A timeout occured while communicating
WinClose, Microsoft Outlook, A connection to the server could not be established
return

; Example #2: Wait for a certain window to appear and then alert the user:
#Persistent
Printed Documentation
184
SetTimer, Alert1, 500
return

Alert1:
IfWinNotExist, Video Conversion, Process Complete
return
; Otherwise:
SetTimer, Alert1, Off ; i.e. the timer turns itself off here.
SplashTextOn, , , The video conversion is finished.
Sleep, 3000
SplashTextOff
return

; Example #3: Detection of single, double, and triple-presses of a hotkey. This
; allows a hotkey to perform a different operation depending on how many times
; you press it:
#c::
if winc_presses > 0 ; SetTimer already started, so we log the keypress instead.
{
winc_presses += 1
return
}
; Otherwise, this is the first press of a new series. Set count to 1 and start
; the timer:
winc_presses = 1
SetTimer, KeyWinC, 400 ; Wait for more presses within a 400 millisecond window.
return

KeyWinC:
SetTimer, KeyWinC, off
if winc_presses = 1 ; The key was pressed once.
{
Run, m:\ ; Open a folder.
}
else if winc_presses = 2 ; The key was pressed twice.
{
Run, m:\multimedia ; Open a different folder.
}
Flow of Control
185
else if winc_presses > 2
{
MsgBox, Three or more clicks detected.
}
; Regardless of which action above was triggered, reset the count to
; prepare for the next series of presses:
winc_presses = 0
return
Sleep
Waits the specified amount of time before continuing.
Sleep, Delay
Parameters
Delay
The amount of time to pause (in milliseconds) between 0 and 2147483647 (24
days), which can be an expression.
Remarks
Due to the granularity of the OS's time-keeping system, Delay is typically rounded up to the nearest
multiple of 10. For example, a delay between 1 and 10 (inclusive) is equivalent to 10 on most
Windows NT/2000/XP systems. However, due to hardware differences, some systems will round up to
a different value such as 15.
The actual delay time might wind up being longer than what was requested if the CPU is under load.
This is because the OS gives each needy process a slice of CPU time (typically 20 milliseconds) before
giving another timeslice to the script.
A delay of 0 yields the remainder of the script's current timeslice to any other processes that need it
(as long as they are not significantly lower in priority than the script). Thus, a delay of 0 produces an
actual delay between 0 and 20ms (or more), depending on the number of needy processes (if there
are no needy processes, there will be no delay at all). However, a Delay of 0 should always wind up
being shorter than any longer Delay would have been.
While sleeping, new threads can be launched via hotkey, custom menu item, or timer.
"Sleep -1": If the operating system is Windows NT4/2000/XP or later or AutoHotkey's version is
1.0.38.05 or later, a delay of -1 does not sleep but instead makes the script immediately check its
message queue. This can be used to force any pending interruptions to occur at a specific place rather
than somewhere more random. See Critical for more details.
Related
SetKeyDelay, SetMouseDelay, SetControlDelay, SetWinDelay, SetBatchLines
Example
Sleep, 1000 ; 1 second
Suspend
Disables or enables all or selected hotkeys.
Suspend [, Mode]
Printed Documentation
186
Parameters
Mode
On: Suspends all hotkeys except those explained the Remarks section.
Off: Re-enables all hotkeys.
Toggle (default): Changes to the opposite of its previous state (On or Off).
Permit: Does nothing except mark the current subroutine as being exempt
from suspension.
Remarks
Any hotkey subroutine whose first line is Suspend (except "Suspend On") will be exempt from
suspension. In other words, the hotkey will remain enabled even while suspension is ON. This allows
suspension to be turned off via such a hotkey.
To disable selected hotkeys or hotstrings automatically based on the type of window that is present,
use #IfWinActive/Exist.
Suspending a script's hotkeys does not stop the script's already-running threads (if any); use Pause to
do that.
When a script's hotkeys are suspended, its tray icon changes to the letter S. This can be avoided by
freezing the icon, which is done by specifying 1 for the last parameter of the Menu command. For
example:
Menu, Tray, Icon, C:\My Icon.ico, , 1
The built-in variable A_IsSuspended contains 1 if the script is suspended and 0 otherwise.
Related
#IfWinActive/Exist, Pause, Menu, ExitApp
Example
^!s::Suspend ; Assign the toggle-suspend function to a hotkey.

187
Functions
Functions
Table of Contents
Introduction and Simple Example
Parameters
Optional Parameters
Local Variables
Using #Include to Share Functions Among Multiple Scripts
Short-circuit Boolean Evaluation
Using Subroutines Within a Function
Return, Exit, and General Remarks
Built-in Functions
Introduction and Simple Example
A function is similar to a subroutine (Gosub) except that it can accept parameters (inputs) from its
caller. In addition, a function may optionally return a value to its caller. Consider the following simple
function which accepts two numbers and returns their sum:
Add(x, y)
{
return x + y ; "Return" expects an expression.
}
The above is known as a function definition because it creates a function named "Add" (not case
sensitive) and establishes that anyone who calls it must provide exactly two parameters (x and y). To
call the function, assign its result to a variable with the := operator as in this example:
Var := Add(2, 3) ; The number 5 will be stored in Var.
Also, a function may be called without storing its return value:
Add(2, 3)
But in this case, any value returned by the function is discarded; so unless the function produces
some effect other than its return value, the call would serve no purpose.
Since a function call is an expression, any variable names in its parameter list should not be enclosed
in percent signs. By contrast, literal strings should be enclosed in double quotes. For example:
if InStr(MyVar, "fox")
MsgBox The variable MyVar contains the word fox.
Finally, functions may be called in the parameters of any command (except OutputVar and InputVar
parameters such as those of StringLen). However, parameters that do not support expressions must
use the "% " prefix as in this example:
MsgBox % "The answer is: " . Add(3, 2)
The "% " prefix is also permitted in parameters that natively support expressions, but it is simply
ignored.
Printed Documentation
188
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 should not accept any
parameters, leave the parentheses empty; for example: GetCurrentTimestamp().
From the function's point of view, parameters are essentially the same as local variables 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.
Known limitation: It is not possible to pass Clipboard, built-in variables, or environment variables to a
function's ByRef parameter, even when #NoEnv is absent from the script. Passing a built-in variable to
a ByRef parameter will cause an error dialog to be displayed.
Optional Parameters [v1.0.35+]
When defining a function, one or more of its parameters can be marked as optional. This is done by
appending an equal sign followed by a default value. In the following example, the Z parameter is
marked optional:
Add(X, Y, Z = 0)
{
return X + Y + Z
}
When the caller passes three parameters to the function above, Z's default value is ignored. But when
the caller passes only two parameters, Z automatically receives the value 0.
It is not possible to have optional parameters isolated in the middle of the parameter list. In other
words, all parameters that lie to the right of the first optional parameter must also be marked
optional.
A parameter's default value must be one of the following: true, false, a literal integer, a literal floating
point number, or a literal empty string ("").
Local Variables and Global Variables
All variables referenced or created inside a function are local by default (except built-in variables such
as Clipboard, ErrorLevel, and A_TimeIdle). Each local variable's contents are visible only to lines that
lie inside the function. Consequently, a local variable may have the same name as a global variable
Functions
189
and both will have separate contents. Finally, all local variables start off blank each time the function
is called.
Global variables: To refer to an existing global variable inside a function (or create a new one), declare
the variable as global prior to using it. For example:
LogToFile(TextToLog)
{
global LogFileName ; This global variable was previously given a value somewhere outside
this function.
FileAppend, %TextToLog%`n, %LogFileName%
}
If a function needs to reference or create a large number of global variables, it can be defined to
assume that all its variables are global (except its parameters) by making its first line either the word
"global" or the declaration of a local variable. For example:
SetDefaults()
{
global ; This word can be omitted if the first line of this function will be something like
"local MyVar".
Var := 33 ; Assigns 33 to a global variable, first creating the variable if necessary.
local x, y, z ; Local variables must be declared in this mode, otherwise they would be
assumed global.
...
}
This assume-global mode can also be used by a function to create a global array, such as a loop that
assigns values to Array%A_Index%.
Static variables: A variable may be declared as static to cause its value to be remembered between
calls. For example:
LogToFile(TextToLog)
{
static LineCount
LineCount += 1 ; Maintain a tally locally (its value is remembered between calls).
global LogFileName
FileAppend, %LineCount%: %TextToLog%`n, %LogFileName%
}
Static variables are always implicitly local. In addition, the only way to detect that a static variable is
being used for the first time is to check whether it is blank.

More about locals and globals:
Multiple variables may be declared on the same line by separating them with commas as in these
examples:
global LogFileName, MaxRetries
static TotalAttempts, PrevResult
Because the words local, global, and static are processed immediately when the script launches, they
cannot be conditionally executed by means of an IF statement. In other words, any use of local,
Printed Documentation
190
global, or static inside an IF's or ELSE's block will take effect unconditionally. In addition, it is not
currently possible to declare a dynamic variable such as global Array%i%.
Within a function, any dynamic variable reference such as Array%i% will always resolve to a local
variable unless no variable of that name exists, in which case a global is used if it exists. If neither
exists and the usage requires the variable to be created, it will be created as a local variable unless
the assume-global mode is in effect. Note: any non-dynamic reference to a variable creates that
variable the moment the script launches. For example, a reference to %Array1% outside a function
creates Array1 as a global the moment the script launches. Conversely, a reference to %Array1%
inside a function immediately creates it as a local.
As a consequence of the above, a function can create a global array manually (by means such as
Array%i% := A_Index) only if it has been defined as an assume-global function.
For commands that create arrays (such as StringSplit), the resulting array will be local if the assume-
global mode is not in effect or if the array's first element has been declared as a local variable (this is
also true if one of the function's parameters is passed, even if that parameter is ByRef, because
parameters are similar to local variables). Conversely, if the first element has been declared global, a
global array will be created. The first element for StringSplit is ArrayName0. For other array-creating
commands such as WinGet List, the first element is ArrayName (i.e. without the number).
Using #Include to Share Functions Among Multiple Scripts
The #Include directive may be used (even at the top of a script) to load functions from an external
file.
Explanation: When the script's flow of execution encounters a function definition, it jumps over it
(using an instantaneous method) and resumes execution at the line after its closing brace.
Consequently, execution can never fall into a function from above, nor does the presence of one or
more functions at the very top of a script affect the auto-execute section.
Short-circuit Boolean Evaluation
When AND and OR are used within an expression, they will short-circuit to enhance performance
(regardless of whether any function calls are present). Short-circuiting operates by refusing to
evaluate parts of an expression that cannot possibly affect its final result. To illustrate the concept,
consider this example:
if (ColorName <> "" AND not FindColor(ColorName))
MsgBox %ColorName% could not be found.
In the example above, the FindColor() function will never get called if the ColorName variable is
empty. This is because the left side of the AND would be false, and thus its right side would be
incapable of making the final outcome true.
Because of this behavior, it's important to realize that any side-effects produced by a function -- such
as altering a global variable's contents -- might never occur if that function is called on the right side
of an AND or OR.
It should also be noted that short-circuit evaluation will cascade into nested ANDs and ORs. For
example, in the following expression, only the leftmost comparison will occur whenever ColorName is
blank. This is because the left side would then be enough to determine the final answer with certainty:
if (ColorName = "" OR FindColor(ColorName, Region1) OR FindColor(ColorName, Region2))
break ; Nothing to search for, or a match was found.
As shown by the examples above, any expensive (time-consuming) functions should generally be
called on the right side of an AND or OR to enhance performance. This technique can also be used to
prevent a function from being called when one of its parameters would be passed a value it considers
inappropriate, such as an empty string.
Functions
191
Using Subroutines Within a Function
Although a function cannot contain definitions of other functions, it can contain subroutines. As with
other subroutines, use Gosub to launch them and Return to return (in which case the Return would
belong to the Gosub and not the function).
Known limitation: Currently, the name of each subroutine (label) must be unique among those of the
entire script. The program will notify you if any duplicate labels exist.
If a function uses Gosub to jump to a public subroutine (one that lies outside of the function's braces),
all variables will be global and the function's own local variables will be inaccessible until the
subroutine returns.
Although the use of Goto is generally discouraged, it can be used inside a function to jump to another
position within the same function. This can help simplify complex functions that have many points of
return, all of which need to do some clean-up prior to returning.
Although a Goto whose target is outside the function is ignored, it is possible for a function to Gosub
an external/public subroutine and then do a Goto from there.
A function may contain subroutines for timers, GUI g-labels, menu items, and similar features. This is
generally done to encapsulate them in a separate file for use with #Include, which prevents them from
interfering with the script's auto-execute section. However, such subroutines should use only static
and global variables (not locals) if their function is ever called normally. This is because a subroutine
thread that interrupts a function-call thread (or vice versa) would be able to change the values of local
variables seen by the interrupted thread. Furthermore, any time a function returns to its caller, all of
its local variables are made blank to free their memory. Finally, when a function is entered by a
subroutine thread, any references to dynamic variables made by that thread are treated as globals
(including commands that create arrays).
Return, Exit, and General Remarks
If the flow of execution within a function reaches the function's closing brace prior to encountering a
Return, the function ends and returns a blank value (empty string) to its caller. A blank value is also
returned whenever the function explicitly omits Return's parameter.
When a function uses the Exit command to terminate the current thread, its caller does not receive a
return value at all. For example, the statement Var := Add(2, 3) would leave Var unchanged if Add()
exits. The same thing happens if a function causes a runtime error such as running a nonexistent file
(when UseErrorLevel is not in effect).
A function may alter the value of ErrorLevel for the purpose of returning an extra value that is easy to
remember.
To call a function with one or more blank values (empty strings), use an empty pair of quotes as in
this example: FindColor(ColorName, "")
Since the calling of a function does not start a new thread, any changes made by a function to settings
such as SendMode and SetTitleMatchMode will go into effect for its caller too.
The caller of a function may pass a nonexistent variable or array element to it, which is useful when
the function expects the corresponding parameter to be ByRef. For example, calling
GetNextLine(BlankArray%i%) would create the variable BlankArray%i% automatically as a local or
global (depending on whether the caller is inside a function and whether it has the assume-global
mode is in effect).
When used inside a function, ListVars displays a function's local variables along with their contents.
This can help debug a script.
Known limitation: Although a function may call itself recursively, if it passes one of its own local
variables or parameters to itself ByRef, the new layer's ByRef parameter will refer to its own variable
rather than the previous layer's. However, this issue does not occur when a function passes to itself a
global variable or a ByRef parameter that refers to a global or some other function's local.
Printed Documentation
192
Style and Naming Conventions
You might find that complex functions are more readable and maintainable if their special variables
are given a distinct prefix. For example, naming each parameter in a function's parameter list with a
leading "p" or "p_" makes their special nature easy to discern at a glance, especially when a function
has several dozen local variables competing for your attention. Similarly, the prefix "r" or "r_" could be
used for ByRef parameters, and "s" or "s_" could be used for static variables.
In v1.0.41+, the One True Brace (OTB) style may optionally be used to define functions. For example:
Add(x, y) {
return x + y
}
Built-in Functions
Any optional parameters at the end of a built-in function's parameter list may be completely omitted.
For example, WinExist("Untitled - Notepad") is valid because its other three parameters would be
considered to be blank.
A built-in function will be overridden if the script defines its own function of the same name. For
example, a script could have its own custom WinExist() function that is called instead of the standard
one.
External functions that reside in DLL files may be called with DllCall().
Frequently-used Functions
FileExist(FilePattern): Returns a blank value (empty string) if FilePattern does not exist (FilePattern
is assumed to be in A_WorkingDir if an absolute path isn't specified). Otherwise, it returns the
attribute string (a subset of "RASHNDOCT") of the first matching file or folder. If the file has no
attributes (rare), "X" is returned. FilePattern may be the exact name of a file or folder, or it may
contain wildcards (* or ?). Since an empty string is seen as "false", the function's return value can
always be used as a quasi-boolean value. For example, the statement if FileExist("C:\My File.txt")
would be true if the file exists and false otherwise. Similarly, the statement if InStr(FileExist("C:\My
Folder"), "D") would be true only if the file exists and is a directory. Corresponding commands: IfExist
and FileGetAttrib.
GetKeyState(KeyName [, "P" or "T"]): Unlike the GetKeyState command -- which returns D for
down and U for up -- this function returns true (1) if the key is down and false (0) if it is up. If
KeyName is invalid, an empty string is returned. See GetKeyState for other return values and usage
instructions.
InStr(Haystack, Needle [, CaseSensitive?, StartingPos]): Returns the position of the first
occurrence of the string Needle in the string Haystack. Unlike StringGetPos, position 1 is the first
character; this is because 0 is synonymous with "false", making it an intuitive "not found" indicator. If
the parameter CaseSensitive is omitted or false, the search is not case sensitive (the method of
insensitivity depends on StringCaseSense); otherwise, the case must match exactly. If StartingPos is
omitted, it defaults to 1 (the beginning of Haystack). Otherwise, specify 2 to start at Haystack's
second character, 3 to start at the third, etc. If StartingPos is beyond the length of Haystack, 0 is
returned. If StartingPos is 0, the search is conducted in reverse (right-to-left) so that the rightmost
match is found. Regardless of the value of StartingPos, the returned position is always relative to the
first character of Haystack. For example, the position of "abc" in "123abc789" is always 4. Related
items: RegExMatch(), IfInString, and StringGetPos.
RegExMatch(Haystack, NeedleRegEx [, UnquotedOutputVar = "", StartingPos = 1]): See
RegExMatch().
RegExReplace(Haystack, NeedleRegEx [, Replacement = "", OutputVarCount = "", Limit = -
1, StartingPos = 1]): See RegExReplace().
Functions
193
StrLen(String): Returns the length of String. If String is a variable to which ClipboardAll was
previously assigned, its total size is returned. Corresponding command: StringLen.
WinActive("WinTitle" [, "WinText", "ExcludeTitle", "ExcludeText"]): Returns the Unique ID
(HWND) of the active window if it matches the specified criteria. If it does not, the function returns 0.
Since all non-zero numbers are seen as "true", the statement if WinActive("WinTitle") is true
whenever WinTitle is active. Finally, WinTitle supports ahk_id, ahk_class, and other special strings.
See IfWinActive for details about these and other aspects of window activation.
WinExist("WinTitle" [, "WinText", "ExcludeTitle", "ExcludeText"]): Returns the Unique ID
(HWND) of the first matching window (0 if none) as a hexademinal integer. Since all non-zero
numbers are seen as "true", the statement if WinExist("WinTitle") is true whenever WinTitle exists.
Finally, WinTitle supports ahk_id, ahk_class, and other special strings. See IfWinExist for details about
these and other aspects of window searching.
Miscellaneous Functions
Asc(String): Returns the ASCII code (a number between 1 and 255) for the first character in String.
If String is empty, 0 is returned.
Chr(Number): Returns the single character corresponding to the ASCII code indicated by Number. If
Number is not between 1 and 255 inclusive, an empty string is returned. Common ASCII codes include
9 (tab), 10 (linefeed), 13 (carriage return), 32 (space), 48-57 (the digits 0-9), 65-90 (uppercase A-Z),
and 97-122 (lowercase a-z).
IsLabel(LabelName) [v1.0.38+]: Returns a non-zero number if LabelName exists in the script as a
subroutine, hotkey, or hotstring (do not include the trailing colon(s) in LabelName). For example, the
statement if IsLabel(VarContainingLabelName) would be true if the label exists, and false otherwise.
This is useful to avoid runtime errors when specifying a dynamic label in commands such as Gosub,
Hotkey, Menu, and Gui.
ListView and TreeView functions: See the ListView and TreeView pages for details.
OnMessage(MsgNumber [, "FunctionName"]): Monitors a message/event. See OnMessage for
details.
VarSetCapacity(UnquotedVarName [, RequestedCapacity, FillByte]): Enlarges a variable's
holding capacity or frees its memory. See VarSetCapacity for details.
General Math
Note: Math functions generally return a blank value (empty string) if any of the incoming parameters
are non-numeric.
Abs(Number): Returns the absolute value of Number. The return value is the same type as Number
(integer or floating point).
Ceil(Number): Returns Number rounded up to the nearest integer (without any .00 suffix). For
example, Ceil(1.2) is 2 and Ceil(-1.2) is -1.
Exp(N): Returns e (which is approximately 2.71828182845905) raised to the Nth power. N may be
negative and may contain a decimal point. To raise numbers other than e to a power, use the **
operator.
Floor(Number): Returns Number rounded down to the nearest integer (without any .00 suffix). For
example, Floor(1.2) is 1 and Floor(-1.2) is -2.
Log(Number): Returns the logarithm (base 10) of Number. The result is formatted as floating point.
If Number is negative, an empty string is returned.
Ln(Number): Returns the natural logarithm (base e) of Number. The result is formatted as floating
point. If Number is negative, an empty string is returned.
Mod(Dividend, Divisor): Modulo. Returns the remainder when Dividend is divided by Divisor. The
sign of the result is always the same as the sign of the first parameter. For example, both mod(5, 3)
and mod(5, -3) yield 2, but mod(-5, 3) and mod(-5, -3) yield -2. If either input is a floating point
Printed Documentation
194
number, the result is also a floating point number. For example, mod(5.0, 3) is 2.0 and mod(5, 3.5) is
1.5. If the second parameter is zero, the function yields a blank result (empty string).
Round(Number [, N]): If N is omitted or 0, Number is rounded to the nearest integer. If N is
positive number, Number is rounded to N decimal places. If N is negative, Number is rounded by N
digits to the left of the decimal point. For example, Round(345, -1) is 350 and Round (345, -2) is 300.
Unlike Transform Round, the result has no .000 suffix whenever N is omitted or less than 1. In
v1.0.44.01+, a value of N greater than zero displays exactly N decimal places rather than obeying
SetFormat. To avoid this, perform another math operation on Round()'s return value; for example:
Round(3.333, 1)+0.
Sqrt(Number): Returns the square root of Number. The result is formatted as floating point. If
Number is negative, the function yields a blank result (empty string).
Trigonometry
Sin(Number) | Cos(Number) | Tan(Number) : Returns the trigonometric sine|cosine|tangent of
Number. Number must be expressed in radians.
ASin(Number): Returns the arcsine (the number whose sine is Number) in radians. If Number is less
than -1 or greater than 1, the function yields a blank result (empty string).
ACos(Number): Returns the arccosine (the number whose cosine is Number) in radians. If Number is
less than -1 or greater than 1, the function yields a blank result (empty string).
ATan(Number): Returns the arctangent (the number whose tangent is Number) in radians.
Note: To convert a radians value to degrees, multiply it by 180/pi (approximately 57.29578). To
convert a degrees value to radians, multiply it by pi/180 (approximately 0.01745329252). The value
of pi (approximately 3.141592653589793) is 4 times the arctangent of 1.
Other Functions
Titan's Command Functions: Provides a callable function for each AutoHotkey command that has an
OutputVar. This library can be included in any script via #Include.
OnMessage() [v1.0.38+]
Specifies a function to run automatically when the script receives the specified message.
OnMessage(MsgNumber [, "FunctionName"])
Parameters
MsgNumber
The number of the message to monitor or query, which should be between 0
and 4294967295 (0xFFFFFFFF). If you do not wish to monitor a system
message (that is, one below 0x400), it is best to choose a number greater
than 4096 (0x1000) to the extent you have a choice. This reduces the chance
of interfering with messages used internally by current and future versions of
AutoHotkey.
FunctionName
The name of the function to be called automatically when the script receives
MsgNumber. Omit this parameter to retrieve the name of the function
currently monitoring MsgNumber (blank if none). Specify an empty string ("")
or an empty variable to turn off the monitoring of MsgNumber.
Return Values
If FunctionName is omitted, it returns the name of the function currently monitoring MsgNumber
(blank if none). However, no changes are made.
If FunctionName is explicitly blank (e.g. ""), it returns the name of the function currently monitoring
MsgNumber (blank if none), then disables the monitoring of MsgNumber.
Functions
195
If FunctionName is non-blank: If MsgNumber is already being monitored, it returns the name of that
function then puts the new function into effect. Otherwise, it assigns FunctionName to monitor
MsgNumber then returns the same FunctionName. In either case, a blank value is returned upon
failure. Failure occurs when FunctionName: 1) does not exist (perhaps due to missing quotes around
FunctionName); 2) accepts more than four parameters; or 3) has any ByRef or optional parameters. It
will also fail if the script attempts to monitor a new message when there are already 500 messages
being monitored.
The Function's Parameters
A function assigned to monitor one or more messages can accept up to four parameters:
MyMessageMonitor(wParam, lParam, msg, hwnd)
{
... body of function...
}
Although the names you give the parameters do not matter, the following information is sequentially
assigned to them:
Parameter #1: The message's WPARAM value, which is an integer between 0 and 4294967295.
Parameter #2: The message's LPARAM value, which is an integer between 0 and 4294967295.
Parameter #3: The message number, which is useful in cases where a function monitors more than
one message.
Parameter #4: The HWND (unique ID) of the window or control to which the message was sent. The
HWND can be used with ahk_id.
You can omit one or more parameters from the end of the list if the corresponding information is not
needed. For example, a function defined as MyMsgMonitor(wParam, lParam) would receive only the
first two parameters, and one defined as MyMsgMonitor() would receive none of them.
If an incoming WPARAM or LPARAM is intended to be a signed value, any negative numbers can be
revealed by following this example:
if wParam > 0x7FFFFFFF
wParam := -(~wParam) - 1
Additional Information Available to the Function
In addition to the parameters received above, a monitor function may also consult the values in the
following built-in variables:
A_Gui: Blank unless the message was sent to a GUI window or control, in which case A_Gui is
the Gui Window number (this window is also set as the function's default GUI window).
A_GuiControl: Blank unless the message was sent to a GUI control, in which case it contains
the control's variable name or other value as described at A_GuiControl. Some controls never
receive certain types of messages. For example, when the user clicks a text control, the
operating system sends WM_LBUTTONDOWN to the parent window rather than the control;
consequently, A_GuiControl is blank.
A_GuiX and A_GuiY: Both contain -2147483648 if the incoming message was sent via
SendMessage. If it was sent via PostMessage, they contain the mouse cursor's coordinates
(relative to the screen) at the time the message was posted.
A_EventInfo: Contains 0 if the message was sent via SendMessage. If sent via PostMessage, it
contains the tick-count time the message was posted.
A monitor function's last found window starts off as the parent window to which the message was sent
(even if it was sent to a control). If the window is hidden but not a GUI window (such as the script's
main window), turn on DetectHiddenWindows before using it. For example:
DetectHiddenWindows On
Printed Documentation
196
MsgParentWindow := WinExist() ; This stores the unique ID of the window to which the
message was sent.
What the Function Should Return
If a monitor function uses Return without any parameters, or it specifies a blank value such as "" (or it
never uses Return at all), the incoming message goes on to be processed normally when the function
finishes. The same thing happens if the function Exits or causes a runtime error such as running a
nonexistent file. By contrast, returning an integer between -2147483648 and 4294967295 causes that
number to be sent immediately as a reply; that is, the program does not process the message any
further. For example, a function monitoring WM_LBUTTONDOWN (0x201) may return an integer to
prevent the target window from being notified that a mouse click has occurred. In many cases (such
as a message arriving via PostMessage), it does not matter which integer is returned; but if in doubt,
0 is usually safest.
General Remarks
Unlike a normal function-call, the arrival of a monitored message calls the function as a new thread.
Because of this, the function starts off fresh with the default values for settings such as SendMode and
DetectHiddenWindows. These defaults can be changed in the auto-execute section.
Messages sent to a control (rather than being posted) are not monitored because the system routes
them directly to the control behind the scenes. This is seldom an issue for system-generated
messages because most of them are posted.
Any script that calls OnMessage anywhere is automatically persistent. It is also single-instance unless
#SingleInstance has been used to override that.
If a message arrives while its function is still running due to a previous arrival of the same message,
the function will not be called again; instead, the message will be treated as unmonitored. If this is
undesirable, a message greater than or equal to 0x312 can be buffered until its function completes by
specifying Critical as the first line of the function. Alternatively, Thread Interrupt can achieve the same
thing as long as it lasts long enough for the function to finish. By contrast, a message less than 0x312
cannot be buffered by Critical or Thread Interrupt; the only way to guarantee that no such messages
are missed is to ensure the function finishes in under 10 milliseconds. One way to do this is to have it
queue up a future thread by posting to its own script a monitored message number higher than
0x312. That message's function should use Critical as its first line to ensure that its messages are
buffered.
If a monitored message that is numerically less than 0x312 arrives while the script is absolutely
uninterruptible -- such as while a menu is displayed, a KeyDelay/MouseDelay is in progress, or the
clipboard is being opened -- the message's function will not be called and the message will be treated
as unmonitored. By contrast, a monitored message of 0x312 or higher will be buffered during these
uninterruptible periods; that is, its function will be called when the script becomes interruptible.
If a monitored message numerically less than 0x312 arrives while the script is uninterruptible merely
due to the settings of Thread Interrupt or Critical, the current thread will be interrupted so that the
function can be called. By contrast, a monitored message of 0x312 or higher will be buffered until the
thread finishes or becomes interruptible.
The priority of OnMessage threads is always 0. Consequently, no messages are monitored or buffered
when the current thread's priority is higher than 0.
Caution should be used when monitoring system messages (those below 0x400). For example, if a
monitor function does not finish quickly, the response to the message might take longer than the
system expects, which might cause side-effects. Unwanted behavior may also occur if a monitor
function returns an integer to suppress further processing of a message, but the system expected
different processing or a different response.
When the script is displaying a system dialog such as MsgBox, any message posted to a control is not
monitored. For example, if the script is displaying a MsgBox and the user clicks a button in a GUI
Functions
197
window, the WM_LBUTTONDOWN message is sent directly to the button without calling the monitor
function.
Although an external program may post messages directly to a script's thread via
PostThreadMessage() or other API call, this is not recommended because the messages would be lost
if the script is displaying a system window such as a MsgBox. Instead, it is usually best to post or send
the messages to the script's main window or one of its GUI windows.
Related
OnExit, OnClipboardChange, Post/SendMessage, Functions, List of Windows Messages, Threads,
Critical, DllCall()
Examples
; Example: The following is a working script that monitors mouse clicks in a GUI window.
; Related topic: GuiContextMenu

Gui, Add, Text,, Click anywhere in this window.
Gui, Add, Edit, w200 vMyEdit
Gui, Show
OnMessage(0x201, "WM_LBUTTONDOWN")
return

WM_LBUTTONDOWN(wParam, lParam)
{
X := lParam & 0xFFFF
Y := lParam >> 16
if A_GuiControl
Control := "`n(in control " . A_GuiControl . ")"
ToolTip You left-clicked in Gui window #%A_Gui% at client coordinates %X%x%Y%.%Control%
}

GuiClose:
ExitApp

; Example: The following script detects system shutdown/logoff and allows you to abort it.
; Related topic: OnExit

OnMessage(0x11, "WM_QUERYENDSESSION")
return

WM_QUERYENDSESSION(wParam, lParam)
{
Printed Documentation
198
ENDSESSION_LOGOFF = 0x80000000
if (lParam & ENDSESSION_LOGOFF) ; User is logging off.
EventType = Logoff
else ; System is either shutting down or restarting.
EventType = Shutdown
MsgBox, 4,, %EventType% in progress. Allow it?
IfMsgBox Yes
return true ; Tell the OS to allow the shutdown/logoff to continue.
else
return false ; Tell the OS to abort the shutdown/logoff.
}

; Example: Have a script receive a custom message and up to two numbers from some other script or
program
; (to send strings rather than numbers, see the example after this one).

OnMessage(0x5555, "MsgMonitor")
OnMessage(0x5556, "MsgMonitor")

MsgMonitor(wParam, lParam, msg)
{
; Since returning quickly is often important, it is better to use a ToolTip than
; something like MsgBox that would prevent the function from finishing:
ToolTip Message %msg% arrived:`nWPARAM: %wParam%`nLPARAM: %lParam%
}

; The following could be used inside some other script to run the function inside the above script:
SetTitleMatchMode 2
DetectHiddenWindows On
if WinExist("Name of Receiving Script.ahk ahk_class AutoHotkey")
PostMessage, 0x5555, 11, 22 ; The message is sent to the "last found window" due to WinExist()
above.
DetectHiddenWindows Off ; Must not be turned off until after PostMessage.

; Example: Send a string of any length from one script to another. This is a working example.
; To use it, save and run both of the following scripts then press Win+Space to show an
; InputBox that will prompt you to type in a string.

; Save the following script as "Receiver.ahk" then launch it:
Functions
199
OnMessage(0x4a, "Receive_WM_COPYDATA") ; 0x4a is WM_COPYDATA
return

Receive_WM_COPYDATA(wParam, lParam)
{
lpDataAddress := lParam + 8 ; This is the address of CopyDataStruct's lpData member.
lpData := 0 ; Init prior to accumulation in the loop.
Loop 4 ; For each byte in the lpData integer
{
lpData := lpData | (*lpDataAddress << 8 * (A_Index - 1)) ; Build the integer from its bytes.
lpDataAddress += 1 ; Move on to the next byte.
}
; lpData contains the address of the string to be copied (must be a zero-terminated string).
DataLength := DllCall("lstrlen", UInt, lpData)
if DataLength <= 0
ToolTip %A_ScriptName%`nA blank string was received or there was an error.
else
{
VarSetCapacity(CopyOfData, DataLength)
DllCall("lstrcpy", "str", CopyOfData, "uint", lpData) ; Copy the string out of the structure.
; Show it with ToolTip vs. MsgBox so we can return in a timely fashion:
ToolTip %A_ScriptName%`nReceived the following string:`n%CopyOfData%
}
return true ; Returning 1 (true) is the traditional way to acknowledge this message.
}

; Save the following script as "Sender.ahk" then launch it. After that, press the Win+Space hotkey.
TargetScriptTitle = Receiver.ahk ahk_class AutoHotkey

#space:: ; Win+Space hotkey. Press it to show an InputBox for entry of a message string.
InputBox, StringToSend, Send text via WM_COPYDATA, Enter some text to Send:
if ErrorLevel ; User pressed the Cancel button.
return
result := Send_WM_COPYDATA(StringToSend, TargetScriptTitle)
if result = FAIL
MsgBox SendMessage failed. Does the following WinTitle exist?:`n%TargetScriptTitle%
else if result = 0
MsgBox Message sent but the target window responded with 0, which may mean it ignored it.
Printed Documentation
200
return

Send_WM_COPYDATA(ByRef StringToSend, ByRef TargetScriptTitle) ; ByRef saves a little memory in
this case.
; This function sends the specified string to the specified window and returns the reply.
; The reply will be 1 if the target window processed the message or 0 if it ignored it.
{
VarSetCapacity(CopyDataStruct, 12, 0) ; Set up the structure's memory area.
; First set the structure's cbData member to the size of the string, including its zero terminator:
InsertInteger(StrLen(StringToSend) + 1, CopyDataStruct, 4) ; OS requires that this be done.
InsertInteger(&StringToSend, CopyDataStruct, 8) ; Set lpData to point to the string itself.
Prev_DetectHiddenWindows := A_DetectHiddenWindows
Prev_TitleMatchMode := A_TitleMatchMode
DetectHiddenWindows On
SetTitleMatchMode 2
SendMessage, 0x4a, 0, &CopyDataStruct,, %TargetScriptTitle% ; 0x4a is WM_COPYDATA. Must
use Send not Post.
DetectHiddenWindows %Prev_DetectHiddenWindows% ; Restore original setting for the caller.
SetTitleMatchMode %Prev_TitleMatchMode% ; Same.
return ErrorLevel ; Return SendMessage's reply back to our caller.
}

InsertInteger(pInteger, ByRef pDest, pOffset = 0, pSize = 4)
{
Loop %pSize% ; Copy each byte in the integer into the structure as raw binary data.
DllCall("RtlFillMemory", "int", &pDest + pOffset + A_Index-1, "uint", 1, "uchar", pInteger >>
8*(A_Index-1) & 0xFF)
}

; Example: See the WinLIRC client script for a demonstration of how to use OnMessage() to receive
; notification when data has arrived on a network connection.
RegExMatch() [v1.0.45+]
Determines whether a string contains a pattern (regular expression).
FoundPos := RegExMatch(Haystack, NeedleRegEx [, UnquotedOutputVar = "", StartingPos = 1])
Parameters
FoundPos
RegExMatch() returns the position of the leftmost occurrence of
NeedleRegEx in the string Haystack. Position 1 is the first character.
Zero is returned if the pattern is not found. If an error occurs (such as a
syntax error inside NeedleRegEx), an empty string is returned and
Functions
201
ErrorLevel is set to one of the values below instead of 0.
Haystack The string whose content is searched.
NeedleRegEx
The pattern to search for, which is a Perl-compatible regular expression
(PCRE). The pattern's options (if any) must be included at the beginning
of the string followed by an close-parenthesis. For example, the pattern
"i)abc.*123" would turn on the case-insensitive option and search for
"abc", followed by zero or more occurrences of any character, followed
by "123". If there are no options, the ")" is optional; for example,
")abc" is equivalent to "abc".
UnquotedOutputVar
Default mode: OutputVar is the unquoted name of a variable in which
to store the part of Haystack that matched the entire pattern. If the
pattern is not found (that is, if the function returns 0), this variable and
all array elements below are made blank.
If any capturing subpatterns are present inside NeedleRegEx, their
matches are stored in an array whose base name is OutputVar. For
example, if the variable's name is Match, the substring that matches the
first subpattern would be stored in Match1, the second would be stored
in Match2, and so on. The exception to this is named subpatterns: they
are stored by name instead of number. For example, the substring that
matches the named subpattern (?P<Year>\d{4}) would be stored in
MatchYear. If a particular subpattern does not match anything (or if the
function returns zero), the corresponding variable is made blank.
Position-and-length mode: If a capital P is present in the RegEx's
options -- such as "P)abc.*123" -- the length of the entire-pattern
match is stored in OutputVar (or 0 if no match). If any capturing
subpatterns are present, their positions and lengths are stored in two
arrays: OutputVarPos and OutputVarLen. For example, if the variable's
base name is Match, the one-based position of the first subpattern's
match would be stored in MatchPos1, and its length in MatchLen1. Zero
is stored in both if the pattern was not matched or the function returns
0. The exception to this is named subpatterns: they are stored by name
instead of number (e.g. MatchPosYear and MatchLenYear).
Within a function, to create an array that is global instead of local,
declare the base name of the array (e.g. Match) as a global variable
prior to using it. The converse is true for assume-global functions.
StartingPos
If StartingPos is omitted, it defaults to 1 (the beginning of Haystack).
Otherwise, specify 2 to start at the second character, 3 to start at the
third, and so on. If StartingPos is beyond the length of Haystack, the
search starts at the empty string that lies at the end of Haystack (which
typically results in no match).
If StartingPos is less than 1, it is considered to be an offset from the
end of Haystack. For example, 0 starts at the last character and -1
starts at the next-to-last character. If StartingPos tries to go beyond the
left side of Haystack, all of Haystack is searched.
Regardless of the value of StartingPos, the return value is always
relative to the first character of Haystack. For example, the position of
"abc" in "123abc789" is always 4.
ErrorLevel
ErrorLevel is set to one of the following:
Printed Documentation
202
0, which means that no error occurred.
1. A string in the following form: Compile error N at offset M: description. In that string, N is the
PCRE error number, M is the position of the offending character inside the regular expression,
and description is the text describing the error.
2. A negative number, which means an error occurred during the execution of the regular
expression. Although such errors are rare, the ones most likely to occur are recursion too deep
(-21) and reached match limit (-8). If these happen, try to redesign the pattern to be more
restrictive, such as using ? in place of * wherever feasible.
Options (case sensitive)
At the very beginning of a regular expression, specify zero or more of the following options followed
by an close-parenthesis. For example, the pattern "im)abc" would search for abc with the case-
insensitive and multiline options (the parenthesis can be omitted when there are no options). Although
this syntax breaks from tradition, it requires no special delimiters (such as forward-slash), and thus
there is no need to escape such delimiters inside the pattern. In addition, performance is improved
because the options are easier to parse.
i
Case-insensitive matching, which treats the letters A through Z as identical to their
lowercase counterparts.
m
Multiline. Views haystack as a collection of individual lines (if it contains newlines) rather
than as a single monolithic line. Specifically, it changes the following:
1) Circumflex (^) matches immediately after all internal newlines -- as well as at the
start of haystack where it always matches (but ^ does not match after a newline that
ends the string).
2) Dollar-sign ($) matches before any newlines in the string (as well as at the very end
where it always matches).
For example, the pattern "m)^abc$" matches the haystack "def`r`nabc" only because
the "m" option is present.
The "D" option is ignored when "m" is present.
s
DotAll. This causes a period (.) to match all characters including newlines (normally, it
does not match newlines). However, when the newline character is at its default of CRLF
(`r`n), two dots are required to match it (not one). Regardless of this option, a negative
class such as [^a] always matches newlines.
x
Ignores whitespace characters in the pattern except when escaped or inside a character
class. It also ignores characters between a non-escaped # outside a character class and
the next newline character, inclusive. This makes it possible to include comments inside
complicated patterns. However, this applies only to data characters; whitespace may
never appear within special character sequences such as (?(, which begins a conditional
subpattern.
A
Forces the pattern to be anchored; that is, it can match only at the start of haystack.
Under most conditions, this is equivalent to explicitly anchoring the pattern by means
such as "^".
D
Forces dollar-sign ($) to match at the very end of haystack, even if haystack's last item
is a newline. Without this option, $ instead matches right before the final newline (if
there is one). Note: This option is ignored when the "m" option is present.
J
Allows duplicate named subpatterns. This can be useful for patterns in which only one of
a collection of identically-named subpatterns can match. Note: If more than one instance
of a particular name matches something, only the leftmost one is stored. Also, variable
names are not case-sensitive.
U Ungreedy. Makes the quantifiers *+?{} consume only those characters absolutely
Functions
203
necessary to form a match, leaving the remaining ones available for the next part of the
pattern. When the "U" option is not in effect, an individual quantifier can be made non-
greedy by following it with a question mark. Conversely, when "U" is in effect, the
question mark makes an individual quantifier greedy.
X
PCRE_EXTRA. Enables PCRE features that are incompatible with Perl. Currently, the only
such feature is that any backslash in a pattern that is followed by a letter that has no
special meaning causes the match to fail and ErrorLevel to be set accordingly. This
option helps reserve unused backslash sequences for future use. Without this option, a
backslash followed by a letter with no special meaning is treated as a literal (e.g. \g and
g are both recognized as a literal g). Regardless of this option, non-alphabetic backslash
sequences that have no special meaning are always treated as literals (e.g. \/ and / are
both recognized as forward-slash).
P
Position mode. This causes RegExMatch() to yield the position and length of each match
rather than the matching substring. For details, see OutputVar above.
S
Study the pattern to try improve its performance. This is useful when a particular pattern
(especially a complex one) will be executed many times. If PCRE finds a way to improve
performance, that discovery is stored alongside the pattern in the cache for use by
subsequent executions of the same pattern.
`n
Switch from the default newline character (`r`n) to a solitary linefeed (`n), which is the
standard on UNIX systems.
`r
Switch from the default newline character (`r`n) to a solitary carriage return (`r). The
option `r`n is also recognized: it means CRLF (which is the default).
Note: Spaces and tabs may optionally be used to separate each option from the next.
Performance
To search for a simple substring inside a larger string, use InStr() because it is faster than
RegExMatch().
To improve performance, the 100 most recently used regular expressions are kept cached in memory
(in compiled form).
The study option (S) can sometimes improve the performance of a regular expression that is used
many times (such as in a loop).
Remarks
Most characters like abc123 can be used literally inside a regular expression. However, the characters
\.*?+[{|()^$ must be preceded by a backslash to be seen as literal. For example, \. is a literal
period and \\ is a literal backslash.
Within a regular expression, special characters such as tab and newline can be escaped with either an
accent (`) or a backslash (\). For example, `t is the same as \t.
A subpattern may be given a name such as the word "Year" in (?P<Year>\d{4}). Such names consist
of up to 32 alphanumeric characters and underscores. Although named subpatterns are also available
by their numbers during the RegEx operation itself (e.g. backreferences), they are stored in the output
array only by name (not by number). For example, if "Year" is the first subpattern, OutputVarYear
would be set to the matching substring, but OutputVar1 would not be changed at all (it would retain
its previous value, if any). However, if an unnamed subpattern occurs after "Year", it would be stored
in OutputVar2, not OutputVar1.
To learn the basics of regular expressions (or refresh your memory of pattern syntax), see the RegEx
Quick Reference.
AutoHotkey's regular expressions are implemented using Perl-compatible Regular Expressions (PCRE)
from www.pcre.org.
Printed Documentation
204
Related
RegExReplace(), InStr(), IfInString, StringGetPos, SetTitleMatchMode RegEx
Common sources of text data: FileRead, UrlDownloadToFile, Clipboard, GUI Edit controls
Examples
FoundPos := RegExMatch("xxxabc123xyz", "abc.*xyz") ; Returns 4, which is the position where the
match was found.
FoundPos := RegExMatch("abc123123", "123$") ; Returns 7 because the $ requires the match to be
at the end.
FoundPos := RegExMatch("abc123", "i)^ABC") ; Returns 1 because a match was achieved via the
case-insensitive option.
FoundPos := RegExMatch("abcXYZ123", "abc(.*)123", SubPat) ; Returns 1 and stores "XYZ" in
SubPat1.
FoundPos := RegExMatch("abc123abc456", "abc\d+", "", 2) ; Returns 7 instead of 1 due to
StartingPos 2 vs. 1.

; For general RegEx examples, see the RegEx Quick Reference.
RegExReplace() [v1.0.45+]
Replaces occurrences of a pattern (regular expression) inside a string.
NewStr := RegExReplace(Haystack, NeedleRegEx [, Replacement = "", OutputVarCount = "", Limit = -
1, StartingPos = 1])
Parameters
NewStr
RegExReplace() returns a version of Haystack whose contents have been
replaced by the operation. If no replacements are needed, Haystack is
returned unaltered. If an error occurs (such as a syntax error inside
NeedleRegEx), an empty string is returned and ErrorLevel is set to one of
the values below instead of 0.
Haystack The string whose content is searched and replaced.
NeedleRegEx
The pattern to search for, which is a Perl-compatible regular expression
(PCRE). The pattern's options (if any) must be included at the beginning of
the string followed by an close-parenthesis. For example, the pattern
"i)abc.*123" would turn on the case-insensitive option and search for "abc",
followed by zero or more occurrences of any character, followed by "123".
If there are no options, the ")" is optional; for example, ")abc" is equivalent
to "abc".
Replacement
The string that will be substituted for each match, which is plain text (not a
regular expression). It may include backreferences in the form $0 through
$9 (where $0 is the substring that matched the entire pattern). For
backreferences above 9 (and optionally those below 9 as well), use ${10},
${11}, and so on. For named subpatterns, use ${SubpatternName}. To
specify a literal $, use $$ (this is the only character that needs such special
treatment; backslashes are never needed to escape anything).
To convert the case of a subpattern, follow the $ with one of the following
characters: U or u (uppercase), L or l (lowercase), T or t (title case, in
which the first letter of each word is capitalized but all others are made
Functions
205
lowercase). For example, both $U1 and $U{1} would transcribe an
uppercase version of the first subpattern.
Nonexistent backreferences and those that did not match anything in
Haystack -- such as one of the subpatterns in (abc)|(xyz) -- are transcribed
as empty strings.
OutputVarCount
The unquoted name of a variable in which to store the number of
replacements that occurred (0 if none).
Limit
If Limit is omitted, it defaults to -1, which replaces all occurrences of the
pattern found in Haystack. Otherwise, specify the maximum number of
replacements to allow. The part of Haystack to the right of the last
replacement will be left unchanged.
StartingPos
If StartingPos is omitted, it defaults to 1 (the beginning of Haystack).
Otherwise, specify 2 to start at the second character, 3 to start at the third,
and so on. If StartingPos is beyond the length of Haystack, the search
starts at the empty string that lies at the end of Haystack (which typically
results in no replacements).
If StartingPos is less than 1, it is considered to be an offset from the end of
Haystack. For example, 0 starts at the last character and -1 starts at the
next-to-last character. If StartingPos tries to go beyond the left side of
Haystack, all of Haystack is searched.
Regardless of the value of StartingPos, the return value is always a
complete copy of Haystack -- the only difference is that more of its left side
might be unaltered compared to what would have happened with a
StartingPos of 1.
ErrorLevel
ErrorLevel is set to one of the following:
0, which means that no error occurred.
1. A string in the following form: Compile error N at offset M: description. In that string, N is the
PCRE error number, M is the position of the offending character inside the regular expression,
and description is the text describing the error.
2. A negative number, which means an error occurred during the execution of the regular
expression. Although such errors are rare, the ones most likely to occur are recursion too deep
(-21) and reached match limit (-8). If these happen, try to redesign the pattern to be more
restrictive, such as using ? in place of * wherever feasible.
Options
See Options for modifiers such as "i)abc", which turns off case-sensitivity in the pattern "abc".
Performance
To replace simple substrings, use StringReplace because it is faster than RegExReplace().
If you know what the maximum number of replacements will be, specifying that for the Limit
parameter improves performance because the search can be stopped early (this might also reduce the
memory load on the system during the operation). For example, if you know there can be only one
match near the beginning of a large string, specify a limit of 1.
To improve performance, the 100 most recently used regular expressions are kept cached in memory
(in compiled form).
The study option (S) can sometimes improve the performance of a regular expression that is used
many times (such as in a loop).
Printed Documentation
206
Remarks
Most characters like abc123 can be used literally inside a regular expression. However, the characters
\.*?+[{|()^$ must be preceded by a backslash to be seen as literal. For example, \. is a literal
period and \\ is a literal backslash.
Within a regular expression, special characters such as tab and newline can be escaped with either an
accent (`) or a backslash (\). For example, `t is the same as \t.
To learn the basics of regular expressions (or refresh your memory of pattern syntax), see the RegEx
Quick Reference.
Related
RegExMatch(), StringReplace, InStr()
Common sources of text data: FileRead, UrlDownloadToFile, Clipboard, GUI Edit controls
Examples
NewStr := RegExReplace("abc123123", "123$", "xyz") ; Returns "abc123xyz" because the $ allows a
match only at the end.
NewStr := RegExReplace("abc123", "i)^ABC") ; Returns "123" because a match was achieved via the
case-insensitive option.
NewStr := RegExReplace("abcXYZ123", "abc(.*)123", "aaa$1zzz") ; Returns "aaaXYZzzz" by means
of the $1 backreference.
NewStr := RegExReplace("abc123abc456", "abc\d+", "", ReplacementCount) ; Returns "" and stores
2 in ReplacementCount.

; For general RegEx examples, see the RegEx Quick Reference.
VarSetCapacity()
Enlarges a variable's holding capacity or frees its memory. Normally, this is necessary only for unusual
circumstances such as DllCall.
GrantedCapacity := VarSetCapacity(UnquotedVarName [, RequestedCapacity, FillByte])
Parameters
GrantedCapacity
The length of string that Var can now hold, which will be greater or equal
to RequestedCapacity. If VarName is not a valid variable name (such as
a literal string or number), 0 is returned. If the system has insufficient
memory to make the change (very rare), an error dialog will be
displayed and the current thread will exit.
UnquotedVarName
The name of the variable (not in quotes). For example:
VarSetCapacity(MyVar, 1000). This can also be a dynamic variable such
as Array%i% or a function's ByRef parameter.
RequestedCapacity
If omitted, the variable's current capacity will be returned and its
contents will not be altered. Otherwise, anything currently in the variable
is lost (the variable becomes blank).
Specify for RequestedCapacity the length of string that the variable
should be able to hold after the adjustment. This length does not include
the internal zero terminator. For example, specifying 1 would allow the
variable to hold up to one character in addition to its internal terminator.
Functions
207
Note: the variable will auto-expand if the script assigns it a larger value
later.
Since this function is often called simply to ensure the variable has a
certain minimum capacity, for performance reasons, it shrinks the
variable only when RequestedCapacity is 0. In other words, if the
variable's capacity is already greater than RequestedCapacity, it will not
be reduced (but the variable will still made blank for consistency).
Therefore, to explicitly shrink a variable, first free its memory with
VarSetCapacity(Var, 0) and then use VarSetCapacity(Var, NewCapacity)
-- or simply let it auto-expand from zero as needed.
For performance reasons, freeing a variable whose previous capacity was
between 1 and 63 might have no effect because its memory is of a
permanent type. In this case, the current capacity will be returned rather
than 0.
In v1.0.44.03+, specify -1 for RequestedCapacity to update the
variable's internally-stored length to the length of its current contents.
This is useful in cases where the variable has been altered indirectly,
such as by passing its address via DllCall(). In this mode,
VarSetCapacity() returns the length rather than the capacity.
FillByte
[v1.0.36.07+]
This parameter is normally omitted, in which case the memory of the
target variable is not initialized (instead, the variable is simply made
blank as described above). Otherwise, specify a number between 0 and
255. Each byte in the target variable's memory area (its current
capacity) is set to that number. Zero is by far the most common value,
which is useful in cases where the variable will hold raw binary data such
as a DllCall structure.
Remarks
In addition to its uses described at DllCall, this function can also be used to enhance performance
when building a string by means of gradual concatenation. This is because multiple automatic
resizings can be avoided when you have some idea of what the string's final length will be. In such a
case, RequestedCapacity need not be accurate: if the capacity is too small, performance is still
improved and the variable will begin auto-expanding when the capacity has been exhausted. If the
capacity is too large, some of the memory is wasted, but only temporarily because all the memory can
be freed after the operation by means of VarSetCapacity(Var, 0) or Var := "".
#MaxMem restricts only the automatic expansion that a variable does on its own. It does not affect
VarSetCapacity.
Related
DllCall, #MaxMem
Example
VarSetCapacity(MyVar, 10240000) ; ~10 MB
Loop
{
...
MyVar = %MyVar%%StringToConcatenate%
...
}

209
GUI, MsgBox, InputBox & Other Dialogs
FileSelectFile
Displays a standard dialog that allows the user to open or save file(s).
FileSelectFile, OutputVar [, Options, RootDir\Filename, Prompt, Filter]
Parameters
OutputVar
The name of the variable in which to store the filename(s) selected by the
user. This will be made blank if the user cancels the dialog (i.e. does not
wish to select a file).
Options
If omitted, it will default to zero, which is the same as having none of the
options below.
M: Multi-select. Specify the letter M to allow the user to select more than
one file via shift-click, control-click, or other means. M may optionally be
followed by a number as described below (for example, both M and M1 are
valid). To extract the individual files, see the example at the bottom of this
page.
S: Save button. Specify the letter S to cause the dialog to always contain
a Save button instead of an Open button. S may optionally be followed by
a number (or sum of numbers) as described below (for example, both S
and S24 are valid).
Even if M and S are absent, the following numbers can be used. To put
more than one of them into effect, add them up. For example, to use 8
and 16, specify the number 24.
1: File Must Exist
2: Path Must Exist
8: Prompt to Create New File
16: Prompt to OverWrite File
32 [v1.0.43.09+]: Shortcuts (.lnk files) are selected as-is rather than
being resolved to their targets. This option also prevents navigation into a
folder via a folder shortcut.
If the "Prompt to Overwrite" option is present without the "Prompt to
Create" option, the dialog will contain a Save button rather than an Open
button. This behavior is due to a quirk in Windows.
RootDir\Filename
If present, this parameter contains one or both of the following:
RootDir: The root (starting) directory, which is assumed to be a subfolder
in %A_WorkingDir% if an absolute path is not specified. If omitted or
blank, the starting directory will be a default that might depend on the OS
version (in WinNT/2k/XP and beyond, it will likely be the directory most
recently selected by the user during a prior use of FileSelectFile). In
v1.0.43.10+, a CLSID such as ::{20d04fe0-3aea-1069-a2d8-
08002b30309d} (i.e. My Computer) may also be specified, in which case
any subdirectory present after the CLSID should end in a backslash
(otherwise, the string after the last backslash will be interpreted as the
default filename, below).
Filename: The default filename to initially show in the dialog's edit field.
Only the naked filename (with no path) will be shown. To ensure that the
dialog is properly shown, ensure that no illegal characters are present
Printed Documentation
210
(such as /<|:").
Examples:
C:\My Pictures\Default Image Name.gif ; Both RootDir and
Filename are present.
C:\My Pictures ; Only RootDir is present.
My Pictures ; Only RootDir is present, and it's relative to the
current working directory.
My File ; Only Filename is present (but if "My File" exists as a
folder, it is assumed to be RootDir).
Prompt
Text displayed in the window to instruct the user what to do. If omitted or
blank, it will default to "Select File - %A_SCRIPTNAME%" (i.e. the name of
the current script).
Filter
Indicates which types of files are shown by the dialog.
Example: Documents (*.txt)
Example: Audio (*.wav; *.mp2; *.mp3)
If omitted, the filter defaults to All Files (*.*). An option for Text
Documents (*.txt) will also be available in the dialog's "files of type"
menu.
Otherwise, the filter uses the indicated string but also provides an option
for All Files (*.*) in the dialog's "files of type" drop-down list. To include
more than one file extension in the filter, separate them with semicolons
as illustrated in the example above.
ErrorLevel
ErrorLevel is set to 1 if the user dismissed the dialog without selecting a file (such as by pressing the
Cancel button). It is also set to 1 if the system refused to show the dialog (rare). Otherwise, it is set
to 0.
Remarks
If the user didn't select anything (e.g. pressed CANCEL), OutputVar is made blank.
If multi-select is not in effect, OutputVar is set to the full path and name of the single file chosen by
the user.
If the M option (multi-select) is in effect, OutputVar is set to a list of items, each of which except the
last is followed by a linefeed (`n) character. The first item in the list is the path that contains all the
selected files (this path will end in a backslash only if it is a root folder such as C:\). The other items
are the selected filenames (without path). For example:
C:\My Documents\New Folder [this is the path in which all the files below reside]
test1.txt [these are the naked filenames: no path info]
test2.txt
... etc.
(The example at the bottom of this page demonstrates how to extract the files one by one.)
When multi-select is in effect, the sum of the lengths of the selected filenames is limited to 64 KB.
Although this is typically enough to hold several thousand files, OutputVar will be made blank if the
limit is exceeded.
A GUI window may display a modal file-selection dialog by means of Gui +OwnDialogs. A modal dialog
prevents the user from interacting with the GUI window until the dialog is dismissed.
GUI, MsgBox, InputBox & Other Dialogs
211
Known limitation: A timer that launches during the display of a FileSelectFile dialog will postpone the
effect of the user's clicks inside the dialog until after the timer finishes. To work around this, avoid
using timers whose subroutines take a long time to finish, or disable all timers during the dialog:
Thread, NoTimers
FileSelectFile, OutputVar
Thread, NoTimers, false
Obsolete option: In v1.0.25.06+, the multi-select option "4" is obsolete. However, for compatibility
with older scripts, it still functions as it did before. Specifically, if the user selects only one file,
OutputVar will contain its full path and name followed by a linefeed (`n) character. If the user selects
more than one file, the format is the same as that of the M option described above, except that the
last item also ends in a linefeed (`n).
Related
FileSelectFolder, MsgBox, InputBox, ToolTip, GUI, CLSID List, parsing loop, SplitPath
Also, the operating system offers two standard dialogs that prompt the user to pick a font and/or
color. These dialogs can be displayed via DllCall() as demonstrated in the forum topics ChooseFont
and ChooseColor.
Examples
FileSelectFile, SelectedFile, 3, , Open a file, Text Documents (*.txt; *.doc)
if SelectedFile =
MsgBox, The user didn't select anything.
else
MsgBox, The user selected the following:`n%SelectedFile%


CLSID Example:
FileSelectFile, OutputVar,, ::{645ff040-5081-101b-9f08-00aa002f954e} ; Recycle Bin.

; Multi-Select Example:
FileSelectFile, files, M3 ; M3 = Multiselect existing files.
if files =
{
MsgBox, The user pressed cancel.
return
}
Loop, parse, files, `n
{
if a_index = 1
MsgBox, The selected files are all contained in %A_LoopField%.
else
{
Printed Documentation
212
MsgBox, 4, , The next file is %A_LoopField%. Continue?
IfMsgBox, No, break
}
}
return
FileSelectFolder
Displays a standard dialog that allows the user to select a folder.
FileSelectFolder, OutputVar [, StartingFolder, Options, Prompt]
Parameters
OutputVar
The name of the variable in which to store the user's selected folder. This will
be made blank if the user cancels the dialog (i.e. does not wish to select a
folder). If the user selects a root directory (such as C:\), OutputVar will
contain a trailing backslash. If this is undesirable, remove it as follows:
FileSelectFolder, Folder
StringRight, LastChar, Folder, 1
if LastChar = \
StringTrimRight, Folder, Folder, 1 ; Remove the trailing backslash.
StartingFolder
If blank or omitted, the dialog's initial selection will be the user's My
Documents folder (or possibly My Computer). A CLSID folder such as
::{20d04fe0-3aea-1069-a2d8-08002b30309d} (i.e. My Computer) may be
specified start navigation at a specific special folder.
Otherwise, the most common usage of this parameter in v1.0.36.03+ is an
asterisk followed immediately by the absolute path of the drive or folder to be
initially selected. For example, *C:\ would initially select the C drive.
Similarly, *C:\My Folder would initially select that particular folder.
The asterisk indicates that the user is permitted to navigate upward (closer to
the root) from the starting folder. Without the asterisk, the user would be
forced to select a folder inside StartingFolder (or StartingFolder itself). One
benefit of omitting the asterisk is that StartingFolder is initially shown in a
tree-expanded state, which may save the user from having to click the first
plus sign.
If the asterisk is present, upward navigation may optionally be restricted to a
folder other than Desktop. This is done by preceding the asterisk with the
absolute path of the uppermost folder followed by exactly one space or tab.
In the following example, the user would not be allowed to navigate any
higher than C:\My Folder (but the initial selection would be C:\My
Folder\Projects):
C:\My Folder *C:\My Folder\Projects
Options
One of the following numbers:
0: The options below are all disabled (except on Windows 2000, where the
"make new folder" button might appear anyway).
1 (default): A button is provided that allows the user to create new folders.
GUI, MsgBox, InputBox & Other Dialogs
213
However, the button will not be present on Windows 95/98/NT.
Add 2 to the above number to provide an edit field that allows the user to
type the name of a folder. For example, a value of 3 for this parameter
provides both an edit field and a "make new folder" button.
If the user types an invalid folder name in the edit field, OutputVar will be set
to the folder selected in the navigation tree rather than what the user
entered, at least on Windows XP.
This parameter can be an expression.
Prompt
Text displayed in the window to instruct the user what to do. If omitted or
blank, it will default to "Select Folder - %A_SCRIPTNAME%" (i.e. the name of
the current script).
ErrorLevel
ErrorLevel is set to 1 if the user dismissed the dialog without selecting a file (such as by pressing the
Cancel button). It is also set to 1 if the system refused to show the dialog (rare). Otherwise, it is set
to 0.
Remarks
A GUI window may display a modal folder-selection dialog by means of Gui +OwnDialogs. A modal
dialog prevents the user from interacting with the GUI window until the dialog is dismissed.
Known limitation: A timer that launches during the display of a FileSelectFolder dialog will postpone
the effect of the user's clicks inside the dialog until after the timer finishes. To work around this, avoid
using timers whose subroutines take a long time to finish, or disable all timers during the dialog:
Thread, NoTimers
FileSelectFolder, OutputVar,, 3
Thread, NoTimers, false
Related
FileSelectFile, MsgBox, InputBox, ToolTip, GUI, CLSID List, FileCopyDir, FileMoveDir, SplitPath
Also, the operating system offers two standard dialogs that prompt the user to pick a font and/or
color. These dialogs can be displayed via DllCall() as demonstrated in the forum topics ChooseFont
and ChooseColor.
Example
FileSelectFolder, OutputVar, , 3
if OutputVar =
MsgBox, You didn't select a folder.
else
MsgBox, You selected folder "%OutputVar%".

CLSID Example:
FileSelectFolder, OutputVar, ::{20d04fe0-3aea-1069-a2d8-08002b30309d} ; My Computer.
Printed Documentation
214
GUI
Creates and manages windows and controls. Such windows can be used as data entry forms or
custom user interfaces.
Gui, sub-command [, Param2, Param3, Param4]
Table of Contents
Add: Creates a control such as text, button, or checkbox.
Show: Displays the window. It can also minimize, maximize, or move the window.
Submit: Saves the user's input and optionally hides the window.
Cancel (or Hide): Hides the window.
Destroy: Deletes the window.
Font: Sets the typeface, size, style, and text color for subsequently created controls.
Color: Sets the background color for the window and/or its controls.
Margin: Sets the margin/spacing used whenever no explicit position has been specified for a
control.
Options and styles for a window: Sets various options for the appearance and behavior of the
window.
Menu: Adds or removes a menu bar.
Minimize / Maximize / Restore: Performs the indicated operation on the window.
Flash: Blinks the window and its taskbar button.
Default: Changes the current thread's default GUI window number.
Positioning and sizing of controls
Storing and responding to user input: variables and g-labels
Options and styles for controls
Window Events: GuiClose | GuiEscape | GuiSize | GuiContextMenu | GuiDropFiles
Creating Multiple GUI windows
GUI Events, Threads, and Subroutines
Miscellaneous: Keyboard Navigation | Window Appearance | General Remarks
Examples: Contains working scripts that demonstrate GUI windows and controls.
Add, ControlType [, Options, Text]
Adds a control to a GUI window (first creating the GUI window itself, if necessary).
ControlType is one of the following:
Text, Edit, UpDown, Picture
Button, Checkbox, Radio
DropDownList, ComboBox
ListBox, ListView, TreeView
Hotkey, DateTime, MonthCal
Slider, Progress
GroupBox, Tab, StatusBar
For example:
Gui, Add, Text,, Please enter your name:
Gui, Add, Edit, vName
Gui, Show
GUI, MsgBox, InputBox & Other Dialogs
215
Show [, Options, Title]
Unless otherwise specified in Options, this command makes the window visible, unminimizes it (if
necessary), activates it, and sets its title. If Title is omitted, the previous title is retained (or if none,
the script's file name is used).
Omit the X, Y, W, and H options below to have the window retain its previous size and position. If
there is no previous position, the window will be auto-centered in one or both dimensions if the X
and/or Y options mentioned below are absent. If there is no previous size, the window will be auto-
sized according to the size and positions of the controls it contains.
Zero or more of the following strings may be present in Options:
Wn: Specify for n the width (in pixels) of the window's client area (the client area excludes the
window's borders, title bar, and menu bar).
Hn: Specify for n the height of the window's client area, in pixels.
Xn: Specify for n the window's X-position on the screen, in pixels. Position 0 is the leftmost column of
pixels visible on the screen.
Yn: Specify for n the window's Y-position on the screen, in pixels. Position 0 is the topmost row of
pixels visible on the screen.
Center: Centers the window horizontally and vertically on the screen.
xCenter: Centers the window horizontally on the screen. For example: Gui, Show, xCenter y0
yCenter: Centers the window vertically on the screen.
AutoSize: Resizes the window to accommodate only its currently visible controls. This is useful to
resize the window after new controls are added, or existing controls are resized, hidden, or unhidden.
For example:
Gui, Show, AutoSize Center

One of the following may also be present:
Minimize: Minimizes the window and activates the one beneath it.
Maximize: Maximizes and activates the window.
Restore: Unminimizes or unmaximizes the window, if necessary. The window is also shown and
activated, if necessary.
NoActivate: Unminimizes or unmaximizes the window, if necessary. The window is also shown
without activating it.
NA: Shows the window without activating it. If the window is minimized, it will stay that way but will
probably rise higher in the z-order (which is the order seen in the alt-tab selector). If the window was
previously hidden, this will probably cause it to appear on top of the active window even though the
active window is not deactivated.
Hide: Hides the window and activates the one beneath it. This is identical in function to Gui Cancel
except that it allows a hidden window to be moved, resized, or given a new title without showing it.
For example: Gui, Show, Hide x55 y66 w300 h200, New Title
Submit [, NoHide]
Saves the contents of each control to its associated variable (if any) and hides the window unless the
NoHide option is present. For controls that produce multiple fields of output, such as a multi-select
ListBox, the output uses the window's current delimiter. If the window does not exist -- perhaps due
to having been destroyed via Gui Destroy -- this command has no effect.
Printed Documentation
216
Cancel
Hides the window without saving the controls' contents to their associated variables. If the window
does not exist -- perhaps due to having been destroyed via Gui Destroy -- this command has no
effect.
Destroy
Removes the window (if it exists) and all its controls, freeing the corresponding memory and system
resources. If the script later recreates the window, all of the window's properties such as color and
font will start off at their defaults (as though the window never existed). If Gui Destroy is not used, all
GUI windows are automatically destroyed when the script exits.
Font [, Options, FontName]
Sets the font typeface, size, style, and/or color for controls created from this point onward. For
example:
gui, font, s10, Verdana ; Set 10-point Verdana.
Omit the last two parameters to restore the font to the system's default GUI typeface, size, and color.
FontName may be the name of any font, such as one from the font table. If FontName is omitted or
does not exist on the system, the previous font's typeface will be used (or if none, the system's
default GUI typeface). This behavior is useful to make a GUI window have a similar font on multiple
systems, even if some of those systems lack the preferred font. For example, by using the following
commands in order, Verdana will be given preference over Arial, which in turn is given preference over
MS sans serif:
gui, font,, MS sans serif
gui, font,, Arial
gui, font,, Verdana ; Preferred font.
If the Options parameter is blank, the previous font's attributes will be used. Otherwise, specify one or
more of the following option letters as substitutes:
C: Color name (see color chart) or RGB value -- or specify the word Default to return to the system's
default color (black on most systems). Example values: cRed, cFFFFAA, cDefault. Note: Buttons do not
obey custom colors. Also, an individual control can be created with a font color other than the current
one by including the C option. For example: Gui, Add, Text, cRed, My Text
S: Size (in points). For example: s12
W: Weight (boldness), which is a number between 1 and 1000 (400 is normal and 700 is bold). For
example: w600
The following words are also supported: bold, italic, strike, underline, and norm. Norm returns the
font to normal weight/boldness and turns off italic, strike, and underline (but it retains the existing
color and size). It is possible to use norm to turn off all attributes and then selectively turn on others.
For example, specifying norm italic would set the font to normal then to italic.
To specify more than one option, include a space between each. For example: cBlue s12 bold
If a script creates multiple GUI windows, each window remembers its own "current font" for the
purpose of creating more controls.
On a related note, the operating system offers two standard dialogs that prompt the user to pick a
font and/or color. These dialogs can be displayed via DllCall() as demonstrated in the forum topics
ChooseFont and ChooseColor.
GUI, MsgBox, InputBox & Other Dialogs
217
Color [, WindowColor, ControlColor]
Sets the background color of the window and/or its controls. WindowColor is used as the background
for the GUI window itself. ControlColor is applied to all present and future controls in the window (with
the exception of a few types that do not support a custom color). Although ControlColor is initially
obeyed by ListViews and TreeViews, subsequent changes to ControlColor do not affect them. In such
cases, use GuiControl +BackgroundFF9977, MyListView to explicitly change the color.
Leave either parameter blank to retain the current color. Otherwise, specify one of the 16 primary
HTML color names or a 6-digit RGB color value (the 0x prefix is optional), or specify the word Default
to return either to its default color. Example values: Silver, FFFFAA, 0xFFFFAA, Default
By default, the window's background color is the system's color for the face of buttons, and the
controls' background color is the system's default window color (usually white).
The color of the menu bar and its submenus can be changed as in this example: Menu, MyMenuBar,
Color, White
To make the background transparent on Windows 2000/XP and beyond, use WinSet TransColor.
However, if you do this without first having assigned a custom window via "Gui, Color", buttons will
also become transparent. To prevent this, first assign a custom color and then make that color
transparent. For example:
Gui, Color, EEAA99
Gui +LastFound ; Make the GUI window the last found window.
WinSet, TransColor, EEAA99
To additionally remove the border and title bar from a window with a transparent background, use the
following after the window has been made transparent:
Gui -Caption ; Or use Gui, 2:-Caption if it is the second window, etc.
To illustrate the above, there is an example of an on-screen display (OSD) near the bottom of this
page.
Margin [, X, Y]
X and Y are the number of pixels of space to leave at the left/right and top/bottom sides of the
window when auto-positioning any control that lacks an explicit X or Y coordinate. Also, the margins
are used to determine the vertical and horizontal distance that separates auto-positioned controls
from each other. Finally, the margins are taken into account by the first use of Gui Show to calculate
the window's size (if no explicit size is specified).
If this command is not used, when the first control is added to a window, the window acquires a
default margin on all sides proportional to the size of the currently selected font (0.75 times font-
height for top & bottom, and 1.25 times font-height for left & right).
Although the margin may be changed during the course of adding controls, the change will affect only
controls added in the future, not ones that already exist. Finally, either X or Y may be blank to leave
the corresponding margin unchanged.
+/-Option1 +/-Option2 ...
One or more options may be specified immediately after the GUI command. For performance reasons,
it is better to set all options in a single line, and to do so before creating the window (that is, before
any use of other sub-commands such as "Gui Add").
The effect of this command is cumulative; that is, it alters only those settings that are explicitly
specified, leaving all the others unchanged.
Specify a plus sign to add the option and a minus sign to remove it. For example:
Gui +Resize -MaximizeBox ; Change the settings of the default GUI window.
Printed Documentation
218
Gui 2:+Resize -MaximizeBox ; Change the settings of the second GUI window.
AlwaysOnTop: Makes the window stay on top of all other windows, which is the same effect as
"WinSet AlwaysOnTop".
Border: Provides a thin-line border around the window. This is not common.
Caption (present by default): Provides a title bar and a thick window border/edge. When removing
the caption from a window that will use WinSet TransColor, remove it only after setting the
TransColor.
Delimiter [v1.0.36+]: Specifies that the window should use a field separator other than pipe (|)
whenever controls' contents are added via Gui Add, modified via GuiControl, or retrieved via Gui
Submit or GuiControlGet. Specify a single character immediately after the word Delimiter. For
example, Gui +Delimiter`n would use a linefeed character, which might be especially appropriate with
continuation sections. Similarly, Gui +Delimiter| would revert to the default delimiter. To use space or
tab, specify Gui +DelimiterSpace or Gui +DelimiterTab. Once the delimiter is changed, it affects all
existing and subsequent threads that operate on this particular window.
Disabled: Disables the window, which prevents the user from interacting with its controls. This is
often used on a window that owns other windows (see Owner).
Label [v1.0.44.09+]: Sets custom names for this window's special labels. For example, Gui
2:+LabelMyGui would use the labels MyGuiClose and MyGuiSize (if they exist) instead of 2GuiClose
and 2GuiSize. In other words, the string "2Gui" is replaced by "MyGui" in the names of all special
labels. This can also be used to make multiple windows share the same set of labels (in which case the
script may consult A_Gui to determine which window launched the subroutine).
LastFound: Sets the window to be the last found window (though this is unnecessary in a Gui thread
because it is done automatically), which allows commands such as WinSet to operate on it even if it is
hidden (that is, DetectHiddenWindows is not necessary). This is especially useful for changing the
properties of the window before showing it. For example:
Gui +LastFound
WinSet, TransColor, %CustomColor% 150
Gui Show
LastFoundExist [v1.0.43.09+]: Unlike other options, LastFoundExist is recognized only when no
other options appear on the same line. +LastFoundExist is the same as +LastFound except that the
window is not created if it does not already exist. The main use for this is to detect whether a
particular GUI window exists. For example:
Gui 2:+LastFoundExist
IfWinExist
MsgBox GUI #2 already exists.
MaximizeBox: Enables the maximize button in the title bar. This is also included as part of Resize
below.
MinimizeBox (present by default): Enables the minimize button in the title bar.
MinSize and MaxSize [v1.0.44.13+]: Determines the minimum and/or maximum size of the window,
such as when the user drags its edges to resize it. Specify the word MinSize and/or MaxSize with no
suffix to use the window's current size as the limit (if the window has no current size, it will use the
size from the first use of Gui Show). Alternatively, append the width, followed by an X, followed by the
height; for example: Gui +Resize +MinSize640x480. The dimensions are in pixels and they specify the
size of the window's client area (which excludes borders, title bar, and menu bar).
Either the width or the height may be omitted to leave it unchanged (e.g. +MinSize640x or
+MinSizex480). Furthermore, Min/MaxSize can be specified more than once to use the window's
current size for one dimension and an explicit size for the other. For example, +MinSize +MinSize640x
would use the window's current size for the height and 640 for the width.
GUI, MsgBox, InputBox & Other Dialogs
219
If MinSize and MaxSize are never used, the operating system's defaults are used (similarly, Gui -
MinSize -MaxSize can be used to return to the defaults). Note: the window must have +Resize to
allow resizing by the user.
OwnDialogs [v1.0.35.01+]: Gui +OwnDialogs should be specified in each thread (such as a
ButtonOK subroutine) for which subsequently displayed MsgBox, InputBox, FileSelectFile, and
FileSelectFolder dialogs should be owned by the window. Such dialogs become modal, meaning that
the user cannot interact with the GUI window until dismissing the dialog. By contrast, ToolTip,
Progress, and SplashImage windows do not become modal even though they become owned; they will
merely stay always on top of their owner. In either case, any owned dialog or window is automatically
destroyed when its GUI window is destroyed.
There is typically no need to turn this setting back off because it does not affect other threads.
However, if a thread needs to display both owned and unowned dialogs, it may turn off this setting via
Gui -OwnDialogs.
If no window number prefix is specified -- such as using Gui +OwnDialogs rather than Gui
2:+OwnDialogs -- the thread's default window will own the dialogs.
Owner: Use +owner to make the window owned by another (but once the window is created, -owner
has no effect). An owned window has no taskbar button by default, and when visible it is always on
top of its owner. It is also automatically destroyed when its owner is destroyed. +Owner must be used
after the window's owner is created but before the owned is created (that is, before commands such
as "Gui Add"). There are two ways to use +owner as shown in these examples:
gui, 2:+owner1 ; Make #2 window owned by #1 window.
gui, 2:+owner ; Make #2 window owned by script's main window to prevent display of a
taskbar button.
To prevent the user from interacting with the owner while one of its owned window is visible, disable
the owner via Gui +Disabled. Later (when the time comes to cancel or destroy the owned window), re-
enable the owner via Gui -Disabled. Do this prior to cancel/destroy so that the owner will be
reactivated automatically.
Resize: Makes the window resizable and enables its maximize button in the title bar. To avoid
enabling the maximize button, specify +Resize -MaximizeBox.
SysMenu (present by default): Specify -SysMenu (minus SysMenu) to omit the system menu and icon
in the window's upper left corner. This will also omit the minimize, maximize, and close buttons in the
title bar.
Theme: By specifying -Theme, all subsequently created controls in the window will have Classic
Theme appearance on Windows XP and beyond. To later create additional controls that obey the
current theme, turn it back on via +Theme. Note: This option has no effect on operating systems
older than Windows XP, nor does it have any effect on XP itself if the Classic Theme is in effect.
Finally, this setting may be changed for an individual control by specifying +Theme or -Theme in its
options.
ToolWindow: Provides a narrower title bar but the window will have no taskbar button.
(Unnamed Style): Specify a plus or minus sign followed immediately by a decimal or hexadecimal
style number.
(Unnamed ExStyle): Specify a plus or minus sign followed immediately by the letter E and a decimal
or hexadecimal extended style number. For example, +E0x40000 would add the WS_EX_APPWINDOW
style, which provides a taskbar button for a window that would otherwise lack one. Although the other
extended styles are not documented here (since they are rarely used), they can be discovered by
searching for WS_EX_APPWINDOW at www.microsoft.com.
Menu [, MenuName]
Attaches a menu bar to the window. Use the Menu command to create an ordinary menu for this
purpose. For example:
Printed Documentation
220
Menu, FileMenu, Add, &Open Ctrl+O, MenuFileOpen ; See remarks below about Ctrl+O.
Menu, FileMenu, Add, E&xit, MenuHandler
Menu, HelpMenu, Add, &About, MenuHandler
Menu, MyMenuBar, Add, &File, :FileMenu ; Attach the two sub-menus that were created
above.
Menu, MyMenuBar, Add, &Help, :HelpMenu
Gui, Menu, MyMenuBar
In the first line above, notice that &Open is followed by Ctrl+O (with a tab character in between). This
indicates a keyboard shortcut that the user may press instead of selecting the menu item. To enable
such a shortcut in the script, use a context-sensitive hotkey:
#IfWinActive GUI Window's Title ahk_class AutoHotkeyGUI
^o:: ; The Ctrl+O hotkey.
MenuFileOpen:
Gui +OwnDialogs ; Force the user to dismiss the FileSelectFile dialog before returning to the
main window.
FileSelectFile, SelectedFile
MsgBox You selected the file %SelectedFile%.
return

; The following part is needed only if the script will be run on Windows 95/98/Me:
#IfWinActive
$^o::Send ^o
To remove a window's current menu bar, use Gui Menu (that is, omit the last parameter).
Once a menu has been used as a menu bar, it should not be used as a popup menu or a submenu.
This is because menu bars internally require a different format (however, this restriction applies only
to the menu bar itself, not its submenus). If you need to work around this, create one menu to use as
the menu bar and another identical menu to use for everything else.
The use of certain destructive menu sub-commands such as Delete and DeleteAll against a menu that
is currently being used as a menu bar (and in some cases, its submenus) is not supported and will
cause an error dialog to be displayed (unless UseErrorLevel is in effect). Use the following steps to
make such changes: 1) detach the menu bar via Gui Menu (that is, omit MenuName); 2) make the
changes; 3) reattach the menu bar via Gui, Menu, MyMenuBar
Hide / Minimize / Maximize / Restore
"Gui Hide" is equivalent to Gui Cancel. The other three commands unhide the window (if necessary)
then perform the indicated operation on it. If the window does not exist -- perhaps due to having been
destroyed via Gui Destroy -- these commands have no effect.
Flash [, Off]
Blinks the window's button in the taskbar. This is done by inverting the color of the window's title bar
and/or taskbar button (if it has one). The optional word OFF causes the title bar and taskbar button to
return to their original colors (but the actual behavior might vary depending on OS version). In the
below example, the window will blink three times because each pair of flashes inverts then restores its
appearance:
Loop 6
GUI, MsgBox, InputBox & Other Dialogs
221
{
Gui Flash
Sleep 500 ; It's quite sensitive to this value; altering it may change the behavior in
unexpected ways.
}
Default
Changes the current thread's default GUI window number, which is used whenever a window number
is not specified for GuiControl, GuiControlGet, and the Gui command itself. In the following example,
the default window number is changed to two: Gui 2:Default. See thread's default window for more
information about the default window.
Positioning and Layout via SmartGUI Creator
Although the options described in the next section are suitable for simple layouts, you may find it
easier to use Rajat's SmartGUI Creator because it's entirely visual; that is, "what you see is what you
get". SmartGUI Creator is free and can be downloaded from
http://www.autohotkey.com/docs/SmartGUI/
Positioning and Sizing of Controls
If some dimensions and/or coordinates are omitted from Options, the control will be positioned
relative to the previous control and/or sized automatically according to its nature and contents.
The following options are supported:
R: Rows of text (can contain a floating point number such as R2.5). R is often preferable to specifying
H (Height). If both the R and H options are present, R will take precedence. For a GroupBox, this
setting is the number of controls for which to reserve space inside the box. For DropDownLists,
ComboBoxes, and ListBoxes, it is the number of items visible at one time inside the list portion of the
control (but on Windows XP or later, it is often desirable to omit both the R and H options for
DropDownList and ComboBox, which makes the popup list automatically take advantage of the
available height of the user's desktop). For other control types, R is the number of rows of text that
can visibly fit inside the control.
W: Width, in pixels. If omitted, the width is calculated automatically for some control types based on
their contents. The other controls types have the following default widths:
Tab controls: 30 times the current font size, plus 3 times the X-margin.
Vertical Progress Bars: Two times the current font size.
Horizontal Progress Bars, horizontal Sliders, DropDownLists, ComboBoxes, ListBoxes, GroupBoxes,
Edits, and Hotkeys: 15 times the current font size (except GroupBoxes, which multiply by 18 to
provide room inside for margins).
H: Height, in pixels. If both the H and R options are absent, DropDownLists, ComboBoxes, ListBoxes,
and empty multi-line Edit controls default to 3 rows; GroupBoxes default to 2 rows; vertical Sliders
and Progress Bars default to 5 rows; horizontal Sliders default to 30 pixels (except if a thickness has
been specified); horizontal Progress Bars default to 2 times the current font size; Hotkey controls
default to 1 row; and Tab controls default to 10 rows. For the other control types, the height is
calculated automatically based on their contents. Note that for DropDownLists and ComboBoxes, H is
the combined height of the control's always-visible portion and its list portion (but even if the height is
set too low, at least one item will always be visible in the list). Also, for all types of controls, specifying
the number of rows via the R option is usually preferable to using H because it prevents a control
from showing partial/incomplete rows of text.
wp+n, hp+n, wp-n, hp-n (where n is any number) can be used to set the width and/or height of a
control equal to the previously added control's width or height, with an optional plus or minus
adjustment. For example, wp would set a control's width to that of the previous control, and wp-50
would set it equal to 50 less than that of the previous control.
Printed Documentation
222
X: X-position. For example, specifying "x0 y0" would position the control in the upper left corner of
the window's client area, which is the area beneath the title bar and menu bar (if any). If X is omitted
but not Y, the control will be positioned to the right of all previously added controls, which can be
thought of as starting a new "column".
Y: Y-position. If Y is omitted but not X, the control will be positioned beneath all previously added
controls, which can be thought of as starting a new "row".
Omitting either X, Y or both is useful to make a GUI layout automatically adjust to any future changes
you might make to the size of controls or font. By contrast, specifying an absolute position for every
control might require you to manually shift the position of all controls that lie beneath and/or to the
right of a control that is being enlarged or reduced.
If both X and Y are omitted, the control will be positioned beneath the previous control using a
standard padding distance.
For X and Y, an optional plus sign can be included to position a control relative to the right or bottom
edge (respectively) of the control that was previously added. For example, specifying Y+10 would
position the control 10 pixels beneath the bottom of the previous control rather than using the
standard padding distance. Similarly, specifying X+10 would position the control 10 pixels to the right
of the previous control's right edge. Since negative numbers such as X-10 are reserved for absolute
positioning, to use a negative offset, include a plus sign in front of it. For example: X+-10
xp+n, yp+n, xp-n, yp-n (where n is any number) can be used to position controls relative to the
previous control's upper left corner, which is often useful for enclosing controls in a GroupBox.
xm and ym can be used to position a control at the leftmost and topmost margins of the window,
respectively (these two may also be followed by a plus/minus sign and a number). By specifying ym
without any x-position at all, the control will be positioned at the top margin but to the right of all
previously added controls, which can be thought of as starting a new "column". The converse is also
true.
xs and ys: these are similar to xm and ym except that they refer to coordinates that were saved by
having previously added a control with the word Section in its options (the first control of the window
always starts a new section, even if that word isn't specified in its options). By specifying ys without
any x-position at all, the control will be positioned at the previously saved y-position, but to the right
of all controls that have been added since the most recent use of the word Section; this can be
thought of as starting a new column within the section. For example:
gui, add, edit, w600 ; Add a fairly wide edit control at the top of the window.
gui, add, text, section, First Name: ; Save this control's position and start a new section.
gui, add, text,, Last Name:
gui, add, edit, ys ; Start a new column within this section.
gui, add, edit
gui, show
The converse of the above (specifying xs but omitting the y-position) is also true.
xs and ys may optionally be followed by a plus/minus sign and a number. Also, it is possible to specify
both the word Section and xs/ys in a control's options; this uses the previous section for itself but
establishes a new section for subsequent controls.
Options for Assigning Actions and Variables to Controls
V: Variable. Associates a variable with a control. Immediately after the letter V, specify the name of a
global variable (or a ByRef local that points to a global). For example, specifying vMyEdit would store
the control's contents in the variable MyEdit whenever the Gui Submit command is used. If a control is
not input-capable -- such as a Text control or GroupBox -- associating a variable with it can still be
helpful since that variable's name serves as the control's unique identifier for use with GuiControl,
GuiControlGet, and A_GuiControl. Note: Gui Submit does not change the contents of variables of non-
GUI, MsgBox, InputBox & Other Dialogs
223
input-capable controls (such as Text and GroupBox), nor certain others as documented in their
sections (such as ListView and TreeView).
G: Gosub (g-label). Launches a subroutine automatically when the user clicks or changes a control.
Immediately after the letter G, specify the name of the label to execute. gCancel may be specified to
perform an implicit Gui Cancel (but if a label named "Cancel" exists in the script, it will be executed
instead). The subroutine may consult the following built-in variables: A_Gui, A_GuiControl,
A_GuiControlEvent, and A_EventInfo.
Controls: Common Styles and Other Options
Note: In the absence of a preceding sign, a plus sign is assumed; for example, Wrap is the same as
+Wrap. By contrast, -Wrap would remove the word-wrapping property.
AltSubmit: Uses alternate submit method. For DropDownList, ComboBox, and ListBox this causes the
Gui Submit command to store the position of the selected item rather than its text. If no item is
selected, a ComboBox will still store the text in its edit field; similarly, a DropDownList or ListBox will
still make its output variable blank. Note: AltSubmit also affects the behavior of GuiControlGet when it
is used on a control that has this property.
C: Color of text (has no effect on buttons). Specify the letter C followed immediately by a color name
(see color chart) or RGB value (the 0x prefix is optional). Examples: cRed, cFF2211, c0xFF2211,
cDefault
Disabled: Makes an input-capable control appear in a disabled state, which prevents the user from
activating or modifying it. Use "GuiControl Enable" to enable it later. Note: To make an Edit control
read-only, specify the string ReadOnly instead. Also, the word Disabled may optionally be followed
immediately by a 0 or 1 to indicate the starting state (0 for enabled and 1 for disabled). In other
words, Disabled and Disabled%VarContainingOne% are the same.
Hidden: The control is initially invisible. Use "GuiControl Show" to show it later. The word Hidden may
optionally be followed immediately by a 0 or 1 to indicate the starting state (0 for visible and 1 for
hidden). In other words, Hidden and Hidden%VarContainingOne% are the same.
Left: Left-justifies the control's text within its available width.
Right: Right-justifies the control's text within its available width. For checkboxes and radio buttons,
this also puts the box itself on the right side of the control rather than the left.
Center: Centers the control's text within its available width.
Section: Starts a new section and saves this control's position for later use with the xs and ys
positioning options described above.
TabStop: Use -Tabstop (i.e. minus TabStop) to have an input-capable control skipped over when the
user presses the TAB key to navigate.
Wrap: Enables word-wrapping of the control's contents within its available width. Since nearly all
control types start off with word-wrapping enabled, precede Wrap with a minus sign to disable word-
wrapping.
VScroll: Provides a vertical scroll bar if appropriate for this type of control.
HScroll: Provides a horizontal scroll bar if appropriate for this type of control. The rest of this
paragraph applies to ListBox only. The horizontal scrolling width defaults to 3 times the width of the
ListBox. To specify a different scrolling width, include a number immediately after the word HScroll.
For example, HScroll500 would allow 500 pixels of scrolling inside the ListBox. However, if the
specified scrolling width is smaller than the width of the ListBox, no scroll bar will be shown (this can
be used to make it possible for the horizontal scroll bar to be added later via "GuiControl,
+HScroll500, MyScrollBar", which is otherwise impossible.
Printed Documentation
224
Controls: Uncommon Styles and Options
BackgroundTrans: Uses a transparent background, which allows any control that lies behind a Text,
Picture, or GroupBox control to show through. For example, a transparent Text control displayed on
top of a Picture control would make the text appear to be part of the picture. Use "GuiControl
+background" to remove this option later. See Picture control's AltSubmit section for more information
about transparent images. Known limitation: BackgroundTrans might not work properly for controls
inside a Tab control that contains a ListView.
-Background (i.e. minus Background): Uses the standard background color rather than the one set
by the "Gui Color" command. This is most often used to make a Tab control have its standard color
rather than the window color. Use "GuiControl +background" to remove this option later.
Border: Provides a thin-line border around the control. Most controls do not need this because they
already have a type-specific border. When adding a border to an existing control, it might be
necessary to increase the control's width and height by 1 pixel.
Theme: This option can be used to override the window's current theme setting on a per-control
basis. See Gui +/-Theme for details.
(Unnamed Style): Specify a plus or minus sign followed immediately by a decimal or hexadecimal
style number. If the sign is omitted, a plus sign is assumed.
(Unnamed ExStyle): Specify a plus or minus sign followed immediately by the letter E and a decimal
or hexadecimal extended style number. If the sign is omitted, a plus sign is assumed. For example,
E0x200 would add the WS_EX_CLIENTEDGE style, which provides a border with a sunken edge that
might be appropriate for pictures and other controls. Although the other extended styles are not
documented here (since they are rarely used), they can be discovered by searching for
WS_EX_CLIENTEDGE at www.microsoft.com.
Window Events
The following labels (subroutines) will be automatically associated with a GUI window if they exist in
the script:
GuiClose: Launched when the window is closed by any of the following: pressing its X button in the
title bar, selecting "Close" from its system menu, or closing it with WinClose. If this label is absent,
closing the window simply hides it, which is the same effect as Gui Cancel. One of the most common
actions to take in response to GuiClose is ExitApp; for example:
GuiClose:
ExitApp
GuiEscape: Launched when the user presses Escape while the GUI window is active. If this label is
absent, pressing Escape has no effect. Known limitation: If the first control in the window is disabled
(possibly depending on control type), the GuiEscape label will not be launched. There may be other
circumstances that produce this effect.
GuiSize: Launched when the window is resized, minimized, maximized, or restored. The built-in
variables A_GuiWidth and A_GuiHeight contain the new width and height of the window's client area,
which is the area excluding title bar, menu bar, and borders. In addition, A_EventInfo (v1.0.36+) and
ErrorLevel will both contain one of the following digits:
0: The window has been restored, or resized normally such as by dragging its edges.
1: The window has been minimized.
2: The window has been maximized.
A script may use GuiSize to reposition and resize controls in response to the user's resizing of the
window. This process can be made much easier by using #Include to load Titan's "Anchor" script.
GuiContextMenu [v1.0.36+]: Launched whenever the user right-clicks anywhere in the window
except the title bar and menu bar. It is also launched in response to pressing the Apps key or Shift-
F10. Unlike most other GUI labels, GuiContextMenu can have more than one concurrent thread. The
following built-in variables are available within GuiContextMenu:
GUI, MsgBox, InputBox & Other Dialogs
225
1. A_GuiControl, which contains the text or variable name of the control that received the event
(blank if none).
2. A_EventInfo: When a ListBox, ListView, or TreeView is the target of the context menu (as
determined by A_GuiControl above), A_EventInfo specifies which of the control's items is the
target:
ListBox or ListView: A_EventInfo contains the number of the currently focused row (0 if none).
TreeView: For right-clicks, A_EventInfo contains the clicked item's ID number (or 0 if the user
clicked somewhere other than an item). For the AppsKey and Shift-F10, A_EventInfo contains
the selected item's ID number.
3. A_GuiX and A_GuiY, which contain the X and Y coordinates of where the script should display
the menu (e.g. Menu, MyContext, Show, %A_GuiX%, %A_GuiY%). Coordinates are relative to
the upper-left corner of the window.
A_GuiEvent, which contains the word RightClick if the user right-clicked, or Normal if the menu was
triggered by the Apps key or Shift-F10.
Note: Since Edit and MonthCal controls have their own context menu, a right-click in one of them will
not launch GuiContextMenu.
GuiDropFiles: Launched whenever files/folders are dropped onto the window as part of a drag-and-
drop operation (but if the label is already running, drop events are ignored). The following built-in
variables are available within GuiDropFiles:
1. A_GuiControl, which contains the text or variable name of the control upon which the files
were dropped (blank if none).
2. A_EventInfo (v1.0.36+) and ErrorLevel, which both contain the number of files dropped.
A_GuiX and A_GuiY, which in v1.0.36+ contain the X and Y coordinates of where the files were
dropped.
3. A_GuiControlEvent, which contains the names of the files that were dropped, with each
filename except the last terminated by a linefeed (`n). To extract the individual files, use a
parsing loop as shown below:
; EXAMPLE #1:
Loop, parse, A_GuiControlEvent, `n
{
MsgBox, 4,, File number %A_Index% is:`n%A_LoopField%.`n`nContinue?
IfMsgBox, No, Break
}

; EXAMPLE #2: To extract only the first file, follow this example:
Loop, parse, A_GuiControlEvent, `n
{
FirstFile = %A_LoopField%
Break
}

; EXAMPLE #3: To process the files in alphabetical order, follow this example:
FileList = %A_GuiControlEvent%
Sort, FileList
Loop, parse, FileList, `n
Printed Documentation
226
MsgBox File number %A_Index% is:`n%A_LoopField%.
To temporarily disable drag-and-drop for a window, remove the WS_EX_ACCEPTFILES style via Gui -
E0x10. To re-enable it later, use Gui +E0x10.
Detecting and responding to other events: Other types of GUI events can be detected and acted
upon via OnMessage(). For example, a script can display context-sensitive help via ToolTip whenever
the user moves the mouse over particular controls in the window. This is demonstrated in the GUI
ToolTip example.
Creating Multiple GUI Windows
For windows other than the first, the window's number is used as a prefix for the special labels
mentioned above; for example, 2GuiEscape and 2GuiClose would be the default labels for the second
window. To use custom label names, see Gui +Label.
Each script may have up to 99 GUI windows simultaneously. To operate upon a window number other
than the default, include a number followed by a colon in front of the sub-command as in these
examples:
Gui, 2:Add, Text,, Text for about-box.
Gui, 2:Show
Gui 2:Default can be used to avoid the need for the "2:" prefix above.
Performance might be slightly better for lower window numbers than higher ones.
GUI Events, Threads, and Subroutines
A GUI thread is defined as any thread launched as a result of a GUI action. GUI actions include
selecting an item from a GUI window's menu bar, or triggering one of its g-labels (such as by pressing
a button).
The default window number for a GUI thread is that of the window that launched the thread. Non-
GUI threads use 1 as their default.
Whenever a GUI thread is launched, that thread's last found window starts off as the GUI window
itself. This allows commands for windows and controls -- such as WinMove, WinHide, WinSet,
WinSetTitle, and ControlGetFocus -- to omit WinTitle and WinText when operating upon the GUI
window itself (even if it is hidden).
Clicking on a control while its g-label is already running from a prior click will have no effect and the
event is discarded. To prevent this, use Critical as the subroutine's first line (however, this will also
buffer/defer other threads such as the press of a hotkey).
The built-in variables A_Gui and A_GuiControl contain the window number and Control ID that
launched the current thread. See their links for details.
All GUI threads start off fresh with the default values for settings such as SendMode. These defaults
can be changed in the auto-execute section.
To have multiple events perform the same subroutine, specify their labels consecutively above the
subroutine. For example:
GuiEscape:
GuiClose:
ButtonCancel:
ExitApp ; All of the above labels will perform this line and any that lie beneath it.
return
GUI, MsgBox, InputBox & Other Dialogs
227
Keyboard Navigation
A GUI window may be navigated via the TAB key, which moves keyboard focus to the next input-
capable control (controls from which the TabStop style has been removed are skipped). The order of
navigation is determined by the order in which the controls were originally added. When the window is
shown for the first time, the first input-capable control that has the TabStop style (which most control
types have by default) will have keyboard focus.
Certain controls may contain an ampersand (&) to create a keyboard shortcut, which is displayed in
the control's text as an underlined character. A user activates the shortcut by holding down the ALT
key then typing the corresponding character. For buttons, checkboxes, and radio buttons, pressing the
shortcut is the same as clicking the control. For GroupBoxes and Text controls, pressing the shortcut
causes keyboard focus to jump to the first input-capable tabstop control that was created after it.
However, if more than one control has the same shortcut key, pressing the shortcut will alternate
keyboard focus among all controls with the same shortcut.
To display a literal ampersand inside the control types mentioned above, specify two consecutive
ampersands as in this example: Save && Exit
Window Appearance
For its icon, a GUI window uses the tray icon that was in effect at the time the window was created.
Thus, to have a different icon, change the tray icon before creating the window. For example: Menu,
Tray, Icon, MyIcon.ico. It is also possible to have a different large icon for a window than its small icon
(the large icon is displayed in the alt-tab task switcher). This can be done via DllCall and
SendMessage; for example:
hIcon32 := DllCall("LoadImage", uint, 0
, str, "My Icon.ico" ; Icon filename (this file may contain multiple icons).
, uint, 1 ; Type of image: IMAGE_ICON
, int, 32, int, 32 ; Desired width and height of image (helps LoadImage decide which icon
is best).
, uint, 0x10) ; Flags: LR_LOADFROMFILE
Gui +LastFound
SendMessage, 0x80, 1, hIcon32 ; 0x80 is WM_SETICON; and 1 means ICON_BIG (vs. 0 for
ICON_SMALL).
Gui Show
Due to OS limitations, Checkboxes, Radio buttons, and GroupBoxes for which a non-default text color
was specified will take on Classic Theme appearance on Windows XP and beyond.
See also: window's margin.
General Remarks
Use GuiControl and GuiControlGet to operate upon individual controls in a GUI window.
Each GUI window may have up to 11,000 controls. However, use caution when creating more than
5000 controls because system instability may occur for certain control types.
Any script that uses the GUI command anywhere is automatically persistent (even if the GUI
command is never actually executed). It is also single-instance unless the #SingleInstance directive
has been used to override that.
Related
GuiControl, GuiControlGet, Menu, Control Types, ListView, TreeView, Control, ControlGet,
SplashImage, MsgBox, FileSelectFile, FileSelectFolder
Printed Documentation
228
Examples
; Example: Achieve an effect similar to SplashTextOn:

Gui, +AlwaysOnTop +Disabled -SysMenu +Owner ; +Owner avoids a taskbar button.
Gui, Add, Text,, Some text to display.
Gui, Show, NoActivate, Title of Window ; NoActivate avoids deactivating the currently active window.

; Example: Simple input-box:

Gui, Add, Text,, First name:
Gui, Add, Text,, Last name:
Gui, Add, Edit, vFirstName ym ; The ym option starts a new column of controls.
Gui, Add, Edit, vLastName
Gui, Add, Button, default, OK ; The label ButtonOK (if it exists) will be run when the button is
pressed.
Gui, Show,, Simple Input Example
return ; End of auto-execute section. The script is idle until the user does something.

GuiClose:
ButtonOK:
Gui, Submit ; Save the input from the user to each control's associated variable.
MsgBox You entered "%FirstName% %LastName%".
ExitApp

; Example: Tab control:

Gui, Add, Tab,, First Tab|Second Tab|Third Tab
Gui, Add, Checkbox, vMyCheckbox, Sample checkbox
Gui, Tab, 2
Gui, Add, Radio, vMyRadio, Sample radio1
Gui, Add, Radio,, Sample radio2
Gui, Tab, 3
Gui, Add, Edit, vMyEdit r5 ; r5 means 5 rows tall.
Gui, Tab ; i.e. subsequently-added controls will not belong to the tab control.
Gui, Add, Button, default xm, OK ; xm puts it at the bottom left corner.
Gui, Show
return

GUI, MsgBox, InputBox & Other Dialogs
229
ButtonOK:
GuiClose:
GuiEscape:
Gui, Submit ; Save each control's contents to its associated variable.
MsgBox You entered:`n%MyCheckbox%`n%MyRadio%`n%MyEdit%
ExitApp

; Example: ListBox containing files in a directory:

Gui, Add, Text,, Pick a file to launch from the list below.`nTo cancel, press ESCAPE or close this
window.
Gui, Add, ListBox, vMyListBox gMyListBox w640 r10
Gui, Add, Button, Default, OK
Loop, C:\*.* ; Change this folder and wildcard pattern to suit your preferences.
{
GuiControl,, MyListBox, %A_LoopFileFullPath%
}
Gui, Show
return

MyListBox:
if A_GuiControlEvent <> DoubleClick
return
; Otherwise, the user double-clicked a list item, so treat that the same as pressing OK.
; So fall through to the next label.
ButtonOK:
GuiControlGet, MyListBox ; Retrieve the ListBox's current selection.
MsgBox, 4,, Would you you like to launch the file or document below?`n`n%MyListBox%
IfMsgBox, No
return
; Otherwise, try to launch it:
Run, %MyListBox%,, UseErrorLevel
if ErrorLevel = ERROR
MsgBox Could not launch the specified file. Perhaps it is not associated with anything.
return

GuiClose:
GuiEscape:
Printed Documentation
230
ExitApp

Example: Display context-senstive help (via ToolTip) whenever the user moves the mouse over a
particular control:

Gui, Add, Edit, vMyEdit
MyEdit_TT := "This is a tooltip for the control whose variable is MyEdit."
Gui, Add, DropDownList, vMyDDL, Red|Green|Blue
MyDDL_TT := "Choose a color from the drop-down list."
Gui, Add, Checkbox, vMyCheck, This control has no tooltip.
Gui, Show
OnMessage(0x200, "WM_MOUSEMOVE")
return

WM_MOUSEMOVE()
{
static CurrControl, PrevControl, _TT ; _TT is kept blank for use by the ToolTip command below.
CurrControl := A_GuiControl
If (CurrControl <> PrevControl and not InStr(CurrControl, " "))
{
ToolTip ; Turn off any previous tooltip.
SetTimer, DisplayToolTip, 1000
PrevControl := CurrControl
}
return

DisplayToolTip:
SetTimer, DisplayToolTip, Off
ToolTip % %CurrControl%_TT ; The leading percent sign tell it to use an expression.
SetTimer, RemoveToolTip, 3000
return

RemoveToolTip:
SetTimer, RemoveToolTip, Off
ToolTip
return
}

GUI, MsgBox, InputBox & Other Dialogs
231

GuiClose:
ExitApp

; Example: On-screen display (OSD) via transparent window:

CustomColor = EEAA99 ; Can be any RGB color (it will be made transparent below).
Gui, +AlwaysOnTop +LastFound +ToolWindow ; +ToolWindow avoids a taskbar button and an alt-tab
menu item.
Gui, Color, %CustomColor%
Gui, Font, s24
Gui, Add, Text, vMyText cLime, XXXXX YYYYY ; XX & YY serve to auto-size the window.
; Make all pixels of this color transparent and make the text itself translucent (150):
WinSet, TransColor, %CustomColor% 150
Gui, -Caption ; Remove the title bar and window borders.
SetTimer, UpdateOSD, 200
Gosub, UpdateOSD ; Make the first update immediate rather than waiting for the timer.
Gui, Show, x0 y400 NoActivate ; NoActivate avoids deactivating the currently active window.
return

UpdateOSD:
MouseGetPos, MouseX, MouseY
GuiControl,, MyText, X%MouseX%, Y%MouseY%
return

; Example: A moving progress bar overlayed on a background image.

Gui, Color, White
Gui, Add, Picture, x0 y0 h350 w450, %A_WinDir%\system32\ntimage.gif
Gui, Add, Button, Default xp+20 yp+250, Start the Bar Moving
Gui, Add, Progress, vMyProgress w416
Gui, Add, Text, vMyText wp ; wp means "use width of previous".
Gui, Show
return

ButtonStartTheBarMoving:
Loop, %A_WinDir%\*.*
{
Printed Documentation
232
if A_Index > 100
break
GuiControl,, MyProgress, %A_Index%
GuiControl,, MyText, %A_LoopFileName%
Sleep 50
}
GuiControl,, MyText, Bar finished.
return

GuiClose:
ExitApp

; Example: Simple image viewer:

Gui, +Resize
Gui, Add, Button, default, &Load New Image
Gui, Add, Radio, ym+5 x+10 vRadio checked, Load &actual size
Gui, Add, Radio, ym+5 x+10, Load to &fit screen
Gui, Add, Pic, xm vPic
Gui, Show
return

ButtonLoadNewImage:
FileSelectFile, file,,, Select an image:, Images (*.gif; *.jpg; *.bmp; *.png; *.tif; *.ico; *.cur; *.ani;
*.exe; *.dll)
if file =
return
Gui, Submit, NoHide ; Save the values of the radio buttons.
if Radio = 1 ; Display image at its actual size.
{
Width = 0
Height = 0
}
else ; Second radio is selected: Resize the image to fit the screen.
{
Width := A_ScreenWidth - 28 ; Minus 28 to allow room for borders and margins inside.
Height = -1 ; "Keep aspect ratio" seems best.
}
GUI, MsgBox, InputBox & Other Dialogs
233
GuiControl,, Pic, *w%width% *h%height% %file% ; Load the image.
Gui, Show, xCenter y0 AutoSize, %file% ; Resize the window to match the picture size.
return

GuiClose:
ExitApp

; Example: Simple text editor with menu bar. This script requires v1.0.35.01+ (for OwnDialogs).

; Create the sub-menus for the menu bar:
Menu, FileMenu, Add, &New, FileNew
Menu, FileMenu, Add, &Open, FileOpen
Menu, FileMenu, Add, &Save, FileSave
Menu, FileMenu, Add, Save &As, FileSaveAs
Menu, FileMenu, Add ; Separator line.
Menu, FileMenu, Add, E&xit, FileExit
Menu, HelpMenu, Add, &About, HelpAbout

; Create the menu bar by attaching the sub-menus to it:
Menu, MyMenuBar, Add, &File, :FileMenu
Menu, MyMenuBar, Add, &Help, :HelpMenu

; Attach the menu bar to the window:
Gui, Menu, MyMenuBar

; Create the main Edit control and display the window:
Gui, +Resize ; Make the window resizable.
Gui, Add, Edit, vMainEdit WantTab W600 R20
Gui, Show,, Untitled
CurrentFileName = ; Indicate that there is no current file.
return

FileNew:
GuiControl,, MainEdit ; Clear the Edit control.
return

FileOpen:
Printed Documentation
234
Gui +OwnDialogs ; Force the user to dismiss the FileSelectFile dialog before returning to the main
window.
FileSelectFile, SelectedFileName, 3,, Open File, Text Documents (*.txt)
if SelectedFileName = ; No file selected.
return
Gosub FileRead
return

FileRead: ; Caller has set the variable SelectedFileName for us.
FileRead, MainEdit, %SelectedFileName% ; Read the file's contents into the variable.
if ErrorLevel
{
MsgBox Could not open "%SelectedFileName%".
return
}
GuiControl,, MainEdit, %MainEdit% ; Put the text into the control.
CurrentFileName = %SelectedFileName%
Gui, Show,, %CurrentFileName% ; Show file name in title bar.
return

FileSave:
if CurrentFileName = ; No filename selected yet, so do Save-As instead.
Goto FileSaveAs
Gosub SaveCurrentFile
return

FileSaveAs:
Gui +OwnDialogs ; Force the user to dismiss the FileSelectFile dialog before returning to the main
window.
FileSelectFile, SelectedFileName, S16,, Save File, Text Documents (*.txt)
if SelectedFileName = ; No file selected.
return
CurrentFileName = %SelectedFileName%
Gosub SaveCurrentFile
return

SaveCurrentFile: ; Caller has ensured that CurrentFileName is not blank.
IfExist %CurrentFileName%
{
GUI, MsgBox, InputBox & Other Dialogs
235
FileDelete %CurrentFileName%
if ErrorLevel
{
MsgBox The attempt to overwrite "%CurrentFileName%" failed.
return
}
}
GuiControlGet, MainEdit ; Retrieve the contents of the Edit control.
FileAppend, %MainEdit%, %CurrentFileName% ; Save the contents to the file.
; Upon success, Show file name in title bar (in case we were called by FileSaveAs):
Gui, Show,, %CurrentFileName%
return

HelpAbout:
Gui, 2:+owner1 ; Make the main window (Gui #1) the owner of the "about box" (Gui #2).
Gui +Disabled ; Disable main window.
Gui, 2:Add, Text,, Text for about box.
Gui, 2:Add, Button, Default, OK
Gui, 2:Show
return

2ButtonOK: ; This section is used by the "about box" above.
2GuiClose:
2GuiEscape:
Gui, 1:-Disabled ; Re-enable the main window (must be done prior to the next step).
Gui Destroy ; Destroy the about box.
return

GuiDropFiles: ; Support drag & drop.
Loop, parse, A_GuiControlEvent, `n
{
SelectedFileName = %A_LoopField% ; Get the first file only (in case there's more than one).
break
}
Gosub FileRead
return

GuiSize:
Printed Documentation
236
if ErrorLevel = 1 ; The window has been minimized. No action needed.
return
; Otherwise, the window has been resized or maximized. Resize the Edit control to match.
NewWidth := A_GuiWidth - 20
NewHeight := A_GuiHeight - 20
GuiControl, Move, MainEdit, W%NewWidth% H%NewHeight%
return

FileExit: ; User chose "Exit" from the File menu.
GuiClose: ; User closed the window.
ExitApp
GUI Control Types
Table of Contents
Text, Edit, UpDown, Picture
Button, Checkbox, Radio
DropDownList, ComboBox
ListBox, ListView, TreeView
Hotkey, DateTime, MonthCal
Slider, Progress
GroupBox, Tab, StatusBar
Text
Description: A region containing borderless text that the user cannot edit. Often used to label other
controls.
Example: Gui, Add, Text,, Please enter your name:
In this case, the last parameter is the string to display. It may contain linefeeds (`n) to start new
lines. In addition, a single long line can be broken up into several shorter ones by means of a
continuation section.
If a width (W) is specified in Options but no rows (R) or height (H), the text will be word-wrapped as
needed, and the control's height will be set automatically.
Since the control's contents are in the last parameter of the Gui command, literal commas do not need
to be escaped. This is also true for the last parameter of all other commands.
A g-label such as gMySubroutine may be listed in the control's options. This would cause the
MySubroutine label to be launched automatically whenever the user clicks the text. This can be used
to simulate an underlined, blue hyperlink as shown in the following working script:
Gui, Font, underline
Gui, Add, Text, cBlue gLaunchGoogle, Click here to launch Google.
Gui, Font, norm
Gui, Show
return

GUI, MsgBox, InputBox & Other Dialogs
237
LaunchGoogle:
Run www.google.com
return
A double-click can be detected by checking whether A_GuiControlEvent contains the word DoubleClick.
An ampersand (&) may be used in the text to underline one of its letters. For example:
Gui, Add, Text,, &First Name:
Gui, Add, Edit
In the example above, the letter F will be underlined, which allows the user to press the shortcut key
Alt+F to set keyboard focus to the first input-capable control that was added after the text control. To
instead display a literal ampersand, specify two consecutive ampersands (&&). To disable all special
treatment of ampersands, include 0x80 in the control's options.
Various general options such as Right, Center, and Hidden are applicable to text controls.
Edit
Description: An area where free-form text can be typed by the user.
Example: Gui, Add, Edit, r9 vMyEdit, Text to appear inside the edit control (omit this
parameter to start off empty).
The control will be multi-line if it has more than one row of text. For example, specifying r3 in Options
will create a 3-line edit control with the following default properties: a vertical scroll bar, word-
wrapping enabled, and the Enter key captured as part of the input rather than triggering the window's
default button.
To start a new line in a multi-line edit control, the last parameter (contents) may contain either a
solitary linefeed (`n) or a carriage return and linefeed (`r`n). Both methods produce literal `r`n pairs
inside the Edit control. However, when the control is saved to its variable via Gui Submit or
GuiControlGet, each `r`n in the text is always translated to a plain linefeed (`n). To write the text to
a file, follow this example: FileAppend, %MyEdit%, C:\Saved File.txt
If the control has word-wrapping enabled (which is the default for multi-line edit controls), any
wrapping that occurs as the user types will not produce linefeed characters (only the Enter keystroke
can do that).
Although multi-line edit controls are limited to 64 KB of text on Windows 95/98/Me, they may have as
much as 4 GB of text on Windows NT/2k/XP or later. As the user enters text, more memory is
allocated as needed.
In v1.0.35+, a g-label such as gMySubroutine may be listed in the control's options. This would cause
the MySubroutine label to be launched automatically whenever the user or the script changes the
contents of the control.
TIP: To load a text file into an Edit control, use FileRead and GuiControl. For example:
Gui, Add, Edit, R20 vMyEdit
FileRead, FileContents, C:\My File.txt
GuiControl,, MyEdit, %FileContents%
Edit Options (to remove an option rather than adding it, precede it with a minus sign):
Limit: Restricts the user's input to the visible width of the edit field. Alternatively, to limit input
to a specific number of characters, include a number immediately afterward. For example,
Limit10 would allow no more than 10 characters to be entered.
Lowercase: The characters typed by the user are automatically converted to lowercase.
Printed Documentation
238
Multi: Makes it possible to have more than one line of text. However, it is usually not necessary to
specify this because it will be auto-detected based on height (H), rows (R), or contents (Text).
Number: Prevents the user from typing anything other than digits into the field (however, it is still
possible to paste non-digits into it). An alternate way of forcing a numeric entry is to attach an
UpDown control to the Edit.
Password: Hides the user's input (such as for password entry) by substituting masking characters for
what the user types. If a non-default masking character is desired, include it immediately after the
word Password. For example, Password* would make the masking character an asterisk rather than
the black circle (bullet), which is the default on Windows XP. Note: This option has no effect for multi-
line edit controls.
ReadOnly: Prevents the user from changing the control's contents. However, the text can still be
scrolled, selected and copied to the clipboard.
Tn: The letter T may be used to set tab stops inside a multi-line edit control (since tab stops
determine the column positions to which literal TAB characters will jump, they can be used to format
the text into columns). If the letter T is not used, tab stops are set at every 32 dialog units (the width
of each "dialog unit" is determined by the operating system). If the letter T is used only once, tab
stops are set at every n units across the entire width of the control. For example, Gui, Add, Edit,
vMyEdit r16 t64 would double the default distance between tab stops. To have custom tab stops,
specify the letter T multiple times as in the following example: Gui, Add, Edit, vMyEdit r16 t8 t16 t32
t64 t128. One tab stop is set for each of the absolute column positions in the list, up to a maximum of
50 tab stops.
Uppercase: The characters typed by the user are automatically converted to uppercase.
WantCtrlA [v1.0.44+]: Specify -WantCtrlA (minus WantCtrlA) to prevent the user's press of Control-A
from selecting all text in the edit control.
WantReturn: Specify -WantReturn (that is, a minus sign followed by WantReturn) to prevent a multi-
line edit control from capturing the Enter keystroke. Pressing Enter will then be the same as pressing
the window's default button (if any). In this case, the user may press Control-Enter to start a new
line.
WantTab [v1.0.38.03+]: Causes a tab keystroke to produce a tab character rather than navigating to
the next control. Without this option, the user may press Control-Tab to produce a tab character
inside a multi-line edit control. Note: Although WantTab also works in a single-line edit control, each
tab character is displayed as an empty-box character (though it is stored as a real tab).
-Wrap (minus wrap): Turns off word-wrapping in a multi-line edit control. Since this style cannot be
changed after the control has been created, use one of the following to change it: 1) Destroy then
recreate the window and its control; or 2) Create two overlapping edit controls, one with wrapping
enabled and the other without it. The one not currently in use can be kept empty and/or hidden.
UpDown [v1.0.35+]
Description: A pair of arrow buttons that the user can click to increase or decrease a value. By default,
an UpDown control automatically snaps onto the previously added control. This previous control is
known as the UpDown's buddy control. The most common example is a "spinner", which is an UpDown
attached to an Edit control. For example:
Gui, Add, Edit
Gui, Add, UpDown, Range1-10, 5
In the example above, the Edit control is the UpDown's buddy control. Whenever the user presses one
of the arrow buttons, the number in the Edit control is automatically increased or decreased.
An UpDown's buddy control can also be a Text control or ListBox. However, due to OS limitations,
controls other than than these (such as ComboBox and DropDownList) might not work properly with
g-labels and other features.
GUI, MsgBox, InputBox & Other Dialogs
239
Specify the UpDown's starting position as the last parameter (if omitted, it starts off at 0 or the
number in the allowable range that is closest to 0).
When the Gui Submit command is used, the control's associated output variable (if any) receives the
current numeric position of the UpDown. If the UpDown is attached to an Edit control and you do not
wish to validate the user's input, it is best to use the UpDown's value rather than the Edit's. This is
because the UpDown will always yield an in-range number, even when the user has typed something
non-numeric or out-of-range in the Edit control. On a related note, numbers with more than three
digits get a thousands separator (such as comma) by default. These separators are stored in the Edit's
output variable but not that of the UpDown.
If the UpDown has a g-label, it will be launched whenever the user clicks one of the arrow buttons or
presses an arrow key on the keyboard. Each launch of the g-label also stores the UpDown's position in
its associated output variable (if any).
UpDown Options:
Horz: Make's the control's buttons point left/right rather than up/down. By default, Horz also makes
the control isolated (no buddy). This can be overridden by specifying Horz 16 in the control's options.
Left: Puts the UpDown on the left side of its buddy rather than the right.
Range: Sets the range to be something other than 0 to 100. After the word Range, specify the
minimum, a dash, and maximum. For example, Range1-1000 would allow a number between 1 and
1000 to be selected; Range-50-50 would allow a number between -50 and 50; and Range-10--5
would allow a number between -10 and -5. The minimum and maximum may be swapped to cause
the arrows to move in the opposite of their normal direction. The broadest allowable range is -
2147483648-2147483647. However, Windows 95 and NT4 require Internet Explorer 5.0 or later to
support a range broader than -32767-32767. Finally, if the buddy control is a ListBox, the range
defaults to 32767-0 for verticals and the inverse for horizontals (Horz).
Wrap: Causes the control to wrap around to the other end of its range when the user attempts to go
beyond the minimum or maximum. Without Wrap, the control stops when the minimum or maximum
is reached.
-16 (minus 16): Causes a vertical UpDown to be isolated; that is, it will have no buddy. This also
causes the control to obey any specified width, height, and position rather than conforming to the size
of its buddy control. In addition, an isolated UpDown tracks its own position internally. This position
can be retrieved normally by means such as Gui Submit.
Increments other than 1: In this script, NumEric demonstrates how to change an UpDown's increment
to a value other than 1 (such as 5 or 0.1).
Picture (or Pic)
Description: An area containing an image (see last two paragraphs for supported file types). The last
parameter is the filename of the image, which is assumed to be in A_WorkingDir if an absolute path
isn't specified.
Example: Gui, Add, Picture, w300 h-1, C:\My Pictures\Company Logo.gif
To retain the image's actual width and/or height, omit the W and/or H options. Otherwise, the image
is scaled to the specified width and/or height (this width and height also determines which icon to load
from a multi-icon .ICO file). To shrink or enlarge the image while preserving its aspect ratio, specify -1
for one of the dimensions and a positive number for the other. For example, specifying "w200 h-1"
would make the image 200 pixels wide and cause its height to be set automatically. If the picture
cannot be loaded or displayed (e.g. file not found), the control is left empty and its width and height
are set to zero.
A g-label such as gMySubroutine may be listed in the control's options. This would cause the
MySubroutine label to be launched automatically whenever the user clicks the picture. A double-click
can be detected by checking whether A_GuiControlEvent contains the word DoubleClick.
Printed Documentation
240
To use a picture as a background for other controls, the picture should normally be added prior to
those controls. However, if those controls are input-capable and the picture has a g-label, create the
picture after the other controls and include 0x4000000 (which is WS_CLIPSIBLINGS) in the picture's
Options. This trick also allows a picture to be the background behind a Tab control or ListView.
Icons, cursors, and animated cursors: Icons and cursors may be loaded from the following types
of files: ICO, CUR, ANI, EXE, DLL, CPL, SCR, and other types that contain icon resources. To use an
icon group other than the first one in the file, include in Options the word Icon followed by the number
of the group. In the following example, the default icon from the second icon group would be used:
Gui, Add, Picture, Icon2, C:\My Application.exe
Specifying the word AltSubmit in Options tells the program to use Microsoft's GDIPlus.dll to load the
image, which might result in a different appearance for GIF, BMP, and icon images. For example, it
would load an ICO/GIF that has a transparent background as a transparent bitmap, which allows the
BackgroundTrans option to take effect. If GDIPlus is not available (see next paragraph), AltSubmit is
ignored and the image is loaded using the normal method.
All operating systems support GIF, JPG, BMP, ICO, CUR, and ANI images. On Windows XP or later,
additional image formats such as PNG, TIF, Exif, WMF, and EMF are supported. Operating systems
older than XP can be given support by copying Microsoft's free GDI+ DLL into the AutoHotkey.exe
folder (but in the case of a compiled script, copy the DLL into the script's folder). To download the
DLL, search for the following phrase at www.microsoft.com: gdi redistributable
Due to an OS bug, animated cursors scaled to a size greater than 90x90 on Windows 95/98/Me might
crash the script.
Button
Description: A pushbutton, which can be pressed to trigger an action. In this case, the last parameter
is the name of the button (shown on the button itself), which may include linefeeds (`n) to start new
lines.
Example: Gui, Add, Button, Default, OK
The example above includes the word Default in its Options to make "OK" the default button. The
default button's action is automatically triggered whenever the user presses ENTER, except when the
keyboard focus is on a different button or a multi-line edit control having the WantReturn style. To
later change the default button to another button, follow this example, which makes the Cancel button
become the default: GuiControl, +default, Cancel. To later change the window to have no default
button, follow this example: GuiControl, -default, OK
An ampersand (&) may be used in the name button to underline one of its letters. For example:
Gui, Add, Button,, &Pause
In the example above, the letter P will be underlined, which allows the user to press Alt+P as shortcut
key. To display a literal ampersand, specify two consecutive ampersands (&&).
If a button lacks an explicit g-label, an automatic label is assumed. For example, if the first GUI
window contains an OK button, the ButtonOK label (if it exists) will be launched when the button is
pressed. For GUI windows other than the first, the window number is included in front of the button's
automatic label; for example: 2ButtonOK.
If the text on the button contains spaces, ampersands, linefeeds (`n) or carriage returns (`r), its
automatic label will omit those characters. For example, a button titled "&Pause" would have an
automatic label of ButtonPause. Similarly, a button titled "Save && Exit" would have an automatic
label of ButtonSaveExit (the double-ampersand is used to display a single, literal ampersand).
Known limitation: Certain desktop themes might not display a button's text properly. If this occurs, try
including -Wrap (minus Wrap) in the button's options. However, this also prevents having more than
one line of text.
GUI, MsgBox, InputBox & Other Dialogs
241
Checkbox
Description: A small box that can be checked or unchecked to represent On/Off, Yes/No, etc.
Example: Gui, Add, Checkbox, vShipToBillingAddress, Ship to billing address?
The last parameter is a label displayed next to the box, which is typically used as a prompt or
description of what the checkbox does. It may include linefeeds (`n) to start new lines. If a width (W)
is specified in Options but no rows (R) or height (H), the control's text will be word-wrapped as
needed, and the control's height will be set automatically. The checkbox's associated output variable
(if any) receives the number 1 for checked, 0 for unchecked, and -1 for gray/indeterminate.
Specify the word Check3 in Options to enable a third state that displays a gray checkmark instead of a
black one (the gray state indicates that the checkbox is neither checked nor unchecked). Specify the
word Checked or CheckedGray in Options to have the checkbox start off with a black or gray
checkmark, respectively. The word Checked may optionally be followed immediately by a 0, 1, or -1 to
indicate the starting state. In other words, "Checked" and "Checked%VarContainingOne%" are the
same.
A g-label such as gMySubroutine may be listed in the control's options. This would cause the
MySubroutine label to be launched automatically whenever the user clicks or changes the checkbox.
Radio
A Radio button is a small empty circle that can be checked (on) or unchecked (off).
Example: Gui, Add, Radio, vMyRadioGroup, Wait for all items to be in stock before shipping.
These controls usually appear in radio groups, each of which contains two or more radio buttons.
When the user clicks a radio button to turn it on, any others in its radio group are turned off
automatically (the user may also navigate inside a group with the arrow keys). A radio group is
created automatically around all consecutively added radio buttons. To start a new group, specify the
word Group in the Options of the first button of the new group -- or simply add a non-radio control in
between, since that automatically starts a new group.
For the last parameter, specify the label to display to the right of the radio button. This label is
typically used as a prompt or description, and it may include linefeeds (`n) to start new lines. If a
width (W) is specified in Options but no rows (R) or height (H), the control's text will be word-wrapped
as needed, and the control's height will be set automatically.
Specify the word Checked in Options to have the button start off in the "on" state. The word Checked
may optionally be followed immediately by a 0 or 1 to indicate the starting state: 0 for unchecked and
1 for checked. In other words, "Checked" and "Checked%VarContainingOne%" are the same.
The radio button's associated output variable (if any) receives the number 1 for "on" and 0 for "off".
However, if only one button in a radio group has a variable, that variable will instead receive the
number of the currently selected button: 1 is the first radio button (according to original creation
order), 2 is the second, and so on. If there is no button selected, 0 is stored.
A g-label such as gMySubroutine may be listed in the control's options. This would cause the
MySubroutine label to be launched automatically whenever the user turns on the button. Unlike the
single-variable mode in the previous paragraph, the g-label must be specified for each button in a
radio group for which the label should be launched. This allows the flexibility to ignore the clicks of
certain buttons. Finally, a double-click can be detected by checking whether A_GuiControlEvent
contains the word DoubleClick.
DropDownList (or DDL)
Description: A list of choices that is displayed in response to pressing a small button. In this case, the
last parameter is is a pipe-delimited list of choices such as Choice1|Choice2|Choice3.
Example: Gui, Add, DropDownList, vColorChoice, Black|White|Red|Green|Blue
Printed Documentation
242
To have one of the items pre-selected when the window first appears, include two pipe characters
after it. Alternatively, include in Options the word Choose followed immediately by the number to pre-
select. For example, Choose5 would pre-select the fifth item (as with other options, it can also be a
variable such as Choose%Var%). To change the choice or add/remove entries from the list after the
control has been created, use GuiControl.
Specify either the word Uppercase or Lowercase in Options to automatically convert all items in the list
to uppercase or lowercase. Specify the word Sort to automatically sort the contents of the list
alphabetically (this also affects any items added later via GuiControl). The Sort option also enables
incremental searching whenever the list is dropped down; this allows an item to be selected by typing
the first few characters of its name.
When the Gui Submit command is used, the control's associated output variable (if any) receives the
text of the currently selected item. However, if the control has the AltSubmit property, the output
variable will receive the item's position number instead (the first item is 1, the second is 2, etc.).
A g-label such as gMySubroutine may be listed in the control's options. This would cause the
MySubroutine label to be launched automatically whenever the user selects a new item.
Use the R or H option to control the height of the popup list. For example, specifying R5 would make
the list 5 rows tall. If both R and H are omitted, the list will automatically expand to take advantage of
the available height of the user's desktop (however, operating systems older than Windows XP will
show 3 rows by default).
The separator between fields may be changed to something other than pipe (|). For example Gui
+Delimiter`n would change it to linefeed and Gui +DelimiterTab would change it to tab (`t).
ComboBox
Description: Same as DropDownList but also permits free-form text to be entered as an alternative to
picking an item from the list.
Example: Gui, Add, ComboBox, vColorChoice, Red|Green|Blue|Black|White
In addition to allowing all the same options as DropDownList above, the word Limit may be included in
Options to restrict the user's input to the visible width of the ComboBox's edit field. Also, the word
Simple may be specified to make the ComboBox behave as though it is an Edit field with a ListBox
beneath it.
When the Gui Submit command is used, the control's associated output variable (if any) receives the
text of the currently selected item. However, if the control has the AltSubmit property, the output
variable will receive the item's position number instead (the first item is 1, the second is 2, etc.). If
either case, if there is no selected item, the output variable will be set to the contents of the
ComboBox's edit field.
A g-label such as gMySubroutine may be listed in the control's options. This would cause the
MySubroutine label to be launched automatically whenever the user selects a new item.
ListBox
Description: A relatively tall box containing a list of choices that can be selected. In this case, the last
parameter is is a pipe-delimited list of choices such as Choice1|Choice2|Choice3.
Example: Gui, Add, ListBox, vColorChoice, Red|Green|Blue|Black|White
To have list item(s) pre-selected when the window first appears, include two pipe characters after
each (the Multi option is required if more than one item is to be pre-selected). Alternatively, include in
Options the word Choose followed immediately by a single item number to pre-select. For example,
Choose5 would pre-select the fifth item. To change the choice or add/remove entries from the list
after the control has been created, use GuiControl.
When the Gui Submit command is used, the control's associated output variable (if any) receives the
text of the currently selected item. However, if the control has the AltSubmit property, the output
variable instead receives the item's position number (the first item is 1, the second is 2, etc.).
GUI, MsgBox, InputBox & Other Dialogs
243
A g-label such as gMySubroutine may be listed in the control's options. This would cause the
MySubroutine label to be launched automatically whenever the user selects a new item. If the user
double-clicks an item, the built-in variable A_GuiControlEvent will contain the string DoubleClick rather
than Normal. In v1.0.36+, the variable A_EventInfo will contain the position of the item that was
double-clicked (1 is the first item, 2 is the second, etc.).
When adding a large number of items to a ListBox, performance may be improved by using
GuiControl, -Redraw, MyListBox prior to the operation, and GuiControl, +Redraw, MyListBox afterward
(requires v1.0.36+).
ListBox Options:
Choose: See above.
Multi: Allows more than one item to be selected simultaneously via shift-click and control-click (to
avoid the need for shift/control-click, specify the number 8 instead of the word Multi). In this case, Gui
Submit stores a pipe delimited list of item-strings in the control's output variable. However, if the
AltSubmit option is in effect, Gui Submit stores a pipe-delimited list of item numbers instead. For
example, 1|2|3 would indicate that the first three items are selected. To extract the individual items
from the string, use a parsing loop such as this example:
Loop, parse, MyListBox, |
{
MsgBox Selection number %A_Index% is %A_LoopField%.
}
The separator between fields may be changed to something other than pipe (|). For example Gui
+Delimiter`n would change it to linefeed and Gui +DelimiterTab would change it to tab (`t).
ReadOnly: Prevents items from being visibly highlighted when they are selected (but Gui Submit will
still store the selected item).
Sort: Automatically sorts the contents of the list alphabetically (this also affects any items added later
via GuiControl). The Sort option also enables incremental searching, which allows an item to be
selected by typing the first few characters of its name.
Tn: The letter T may be used to set tab stops, which can be used to format the text into columns. If
the letter T is not used, tab stops are set at every 32 dialog units (the width of each "dialog unit" is
determined by the operating system). If the letter T is used only once, tab stops are set at every n
units across the entire width of the control. For example, "Gui, Add, ListBox, vMyListBox t64" would
double the default distance between tab stops. To have custom tab stops, specify the letter T multiple
times as in the following example: Gui, Add, ListBox, vMyListBox t8 t16 t32 t64 t128. One tab stop is
set for each of the absolute column positions in the list, up to a maximum of 50 tab stops.
ListView and TreeView
See separate pages ListView and TreeView.
Hotkey
Description: A box that looks like a single-line edit control but instead accepts a keyboard combination
pressed by the user. For example, if the user presses Control+Alt+C on an English keyboard layout,
the box would display "Ctrl + Alt + C".
When the Gui Submit command is used, the control's associated output variable (if any) receives the
hotkey modifiers and name, which are be compatible with the Hotkey command. Examples: ^!C,
+!Home, +^Down, ^Numpad1, !NumpadEnd. If there is no hotkey in the control, the output variable
is made blank. Note: Some keys are displayed the same even though they are retrieved as different
names. For example, both ^Numpad7 and ^NumpadHome might be displayed as Ctrl + Num 7.
By default, the control starts off with no hotkey specified. To instead have a default, specify its
modifiers and name as the last parameter as in this example: Gui, Add, Hotkey, vMyHotkey, ^!p
Printed Documentation
244
The only modifiers supported are ^ (Control), ! (Alt), and + (Shift). See the key list for available key
names.
In v1.0.35.01+, a g-label such as gMySubroutine may be listed in the control's options. This would
cause the MySubroutine label to be launched automatically whenever the user changes the hotkey.
Each launch of the g-label also stores the hotkey in control's associated output variable (if any). Note:
the g-label is launched even when an incomplete hotkey is present. For example, if the user holds
down the Control key, the g-label is launched once and the output variable contains only a caret (^).
When the user completes the hotkey, the label is launched again and the variable contains the
complete hotkey.
To restrict the types of hotkeys the user may enter, include the word Limit followed by the sum of one
or more of the following numbers:
1: Prevent unmodified keys
2: Prevent Shift-only keys
4: Prevent Control-only keys
8: Prevent Alt-only keys
16: Prevent Shift-Control keys
32: Prevent Shift-Alt keys
64: This value is not supported (it will not behave correctly).
128: Prevent Shift-Control-Alt keys.
For example, Limit1 would prevent unmodified hotkeys such as letters and numbers from being
entered, and Limit15 would require at least two modifier keys. If the user types a forbidden modifier
combination, the Control+Alt combination is automatically and visibly substituted.
The Hotkey control has limited capabilities. For example, it does not support mouse/joystick hotkeys
or the Windows key (LWin and RWin). One way to work around this is to provide one or more
checkboxes as a means for the user to enable extra modifiers such as the Windows key.
DateTime [v1.0.35+]
Description: A box that looks like a single-line edit control but instead accepts a date and/or time. A
drop-down calendar is also provided.
Example: Gui, Add, DateTime, vMyDateTime, LongDate
The last parameter may be one of the following:
(omitted): When omitted, the locale's short date format is used. For example, in some locales it would
look like: 6/1/2005
LongDate: Uses the locale's long date format. For example, in some locales it would look like:
Wednesday, June 01, 2005
Time: Shows only the time using the locale's time format. Although the date is not shown, it is still
present in the control and will be retrieved along with the time in the YYYYMMDDHH24MISS format.
(custom format): Specify any combination of date and time formats. For example, M/d/yy HH:mm
would look like 6/1/05 21:37. Similarly, dddd MMMM d, yyyy hh:mm:ss tt would look like Wednesday
June 1, 2005 09:37:45 PM. Letters and numbers to be displayed literally should be enclosed in single
quotes as in this example: 'Date:' MM/dd/yy 'Time:' hh:mm:ss tt. By contrast, non-alphanumeric
characters such as spaces, tabs, slashes, colons, commas, and other punctuation do not need to be
enclosed in single quotes. The exception to this is the single quote character itself: to produce it
literally, use four consecutive single quotes (''''), or just two if the quote is already inside an outer pair
of quotes.
DateTime Usage
To have a date other than today pre-selected, include in Options the word Choose followed
immediately by a date in YYYYMMDD format. For example, Choose20050531 would pre-select May 31,
2005 (as with other options, it can also be a variable such as Choose%Var%). To have no date/time
selected, specify ChooseNone. ChooseNone also creates a checkbox inside the control that is
GUI, MsgBox, InputBox & Other Dialogs
245
unchecked whenever the control has no date. Whenever the control has no date, Gui Submit and
GuiControlGet will retrieve a blank value (empty string).
The time of day may optionally be present. However, it must always be preceded by a date when
going into or coming out of the control. The format of the time portion is HH24MISS (hours, minutes,
seconds), where HH24 is expressed in 24-hour format; for example, 09 is 9am and 21 is 9pm. Thus, a
complete date-time string would have the format YYYYMMDDHH24MISS.
When specifying dates in the YYYYMMDDHH24MISS format, only the leading part needs to be present.
Any remaining element that has been omitted will be supplied with the following default values:
MM: Month 01
DD: Day 01
HH24: Hour 00
MI: Minute 00
SS: Second 00
Within the drop-down calendar, the today-string at the bottom can be clicked to select today's date. In
addition, the year and month name are clickable and allow easy navigation to a new month or year.
Keyboard navigation: Use the Up/Down arrow keys, NumpadPlus/Minus, and Home/End to increase or
decrease the control's values. Use LeftArrow and RightArrow to move from field to field inside the
control. Within the drop-down calendar, use the arrow keys to move from day to day; use
PageUp/Down to move backward/forward by one month; use Ctrl-PageUp/Down to move
backward/forward by one year; and use Home/End to select the first/last day of the month.
When the Gui Submit command is used, the control's associated output variable (if any) receives the
selected date and time in YYYYMMDDHH24MISS format. Both the date and the time are present
regardless of whether they were actually visible in the control.
If the control has a g-label, the label is launched whenever the user changes the date or time. For
each launch, the control's associated output variable (if any) is automatically updated with the
currently selected date/time.
Windows 95 and NT4 require DLL versions at least as new as those distributed with Internet Explorer
3.0 to support DateTime controls.
DateTime Options:
Choose: See above.
Range: Restricts how far back or forward in time the selected date can be. After the word Range,
specify the minimum and maximum dates in YYYYMMDD format (with a dash between them). For
example, Range20050101-20050615 would restrict the date to the first 5.5 months of 2005. Either
the minimum or maximum may be omitted to leave the control unrestricted in that direction. For
example, Range20010101 would prevent a date prior to 2001 from being selected and Range-
20091231 (leading dash) would prevent a date later than 2009 from being selected. Without the
Range option, any date between the years 1601 and 9999 can be selected. The time of day cannot be
restricted.
Right: Causes the drop-down calendar to drop down on the right side of the control instead of the left.
1: Specify the number 1 in Options to provide an up-down control to the right of the control to modify
date-time values, which replaces the of the drop-down month calendar that would otherwise be
available.
2: Specify the number 2 in Options to provide a checkbox inside the control that the user may
uncheck to indicate that no date/time is selected. Once the control is created, this option cannot be
changed.
MonthCal [v1.0.35+]
Description: A tall and wide control that displays all the days of the month in calendar format. The
user may select a single date or a range of dates.
Example: Gui, Add, MonthCal, vMyCalendar
Printed Documentation
246
To have a date other than today pre-selected, specify it as the last parameter in YYYYMMDD format
(e.g. 20050531). A range of dates may also be pre-selected by including a dash between two dates
(e.g. 20050525-20050531).
It is usually best to omit width (W) and height (H) for a MonthCal because it automatically sizes itself
to fit exactly one month. To display more than one month vertically, specify R2 or higher in Options.
To display more than one month horizontally, specify W-2 (W negative two) or higher. These options
may both be present to expand in both directions.
The today-string at the bottom of the control can be clicked to select today's date. In addition, the
year and month name are clickable and allow easy selection of a new year or month.
Unlike DateTime's drop-down calendar, keyboard navigation is generally not supported in a MonthCal.
When the Gui Submit command is used, the control's associated output variable (if any) receives the
selected date in YYYYMMDD format (without any time portion). However, when the multi-select option
is in effect, the minimum and maximum dates are retrieved with a dash between them (e.g.
20050101-20050108). If only a single date was selected in a multi-select calendar, the minimum and
maximum are both present but identical. StringSplit can be used to separate the dates. For example,
the following would put the minimum in Date1 and the maximum in Date2: StringSplit, Date,
MyMonthCal, -
If the MonthCal has a g-label, each launch of it updates the control's associated output variable (if
any) with the currently selected date or range. By default, the label is launched only when: 1) the user
changes the selection; or 2) every two minutes in case a new day has arrived (this behavior is a quirk
of the OS). However, if the word AltSubmit is in the control's Options (v1.0.35.09+), the g-label is
launched more often and the built-in variable A_GuiControlEvent will contain the word Normal for a
change of the date, the number 1 for a click of a date, and the number 2 when the MonthCal releases
"mouse capture". For example, if the user double-clicks a new date, the label would be launched five
times: Once with with Normal, twice with 1, and twice with 2. This can be used to detect double clicks
by measuring the time between instances of the number 1.
When specifying dates in the YYYYMMDD format, the MM and/or DD portions may be omitted, in which
case they are assumed to be 1. For example, 200205 is seen as 20020501, and 2005 is seen as
20050101.
Windows 95 and NT4 require DLL versions at least as new as those distributed with Internet Explorer
3.0 to support MonthCal controls.
MonthCal Options:
Multi: Multi-select. Allows the user to shift-click or click-drag to select a range of adjacent dates
(the user may still select a single date too). This option may be specified explicitly or put into
effect automatically by means of specifying a selection range when the control is created. For
example: Gui, Add, MonthCal, vMyCal, 20050101-20050108. Once the control is created, this
option cannot be changed.
Range: Restricts how far back or forward in time the calendar can go. After the word Range, specify
the minimum and maximum dates in YYYYMMDD format (with a dash between them). For example,
Range20050101-20050615 would restrict the selection to the first 5.5 months of 2005. Either the
minimum or maximum may be omitted to leave the calendar unrestricted in that direction. For
example, Range20010101 would prevent a date prior to 2001 from being selected and Range-
20091231 (leading dash) would prevent a date later than 2009 from being selected. Without the
Range option, any date between the years 1601 and 9999 can be selected.
4: Specify the number 4 in Options to display week numbers (1-52) to the left of each row of days.
Week 1 is defined as the first week that contains at least four days.
8: Specify the number 8 in Options to prevent the circling of today's date within the control.
16: Specify the number 16 in Options to prevent the display of today's date at the bottom of the
control.
GUI, MsgBox, InputBox & Other Dialogs
247
Slider
Description: A sliding bar that the user can move along a vertical or horizontal track. The standard
volume control in the taskbar's tray is an example of a slider.
Example: Gui, Add, Slider, vMySlider, 50
Specify the starting position of the slider as the last parameter. If the last parameter is omitted, the
slider starts off at 0 or the number in the allowable range that is closest to 0.
The user may slide the control by the following means: 1) dragging the bar with the mouse; 2)
clicking inside the bar's track area with the mouse; 3) turning the mouse wheel while the control has
focus; or 3) pressing the following keys while the control has focus: Arrow keys, Page-up, Page-down,
Home, and End.
When the Gui Submit command is used, the control's associated output variable (if any) receives the
current numeric position of the slider. The position is also stored in the output variable whenever the
control's g-label is launched.
If the slider has a g-label, by default it will be launched only when the user has stopped moving the
slider (such as by releasing the mouse button after having dragging it). However, if the word
AltSubmit is in the control's Options, the g-label is launched for all slider events and the built-in
variable A_GuiControlEvent will contain one of the following digits or strings:
0: The user pressed the Left-arrow or Up-arrow key.
1: The user pressed the Right-arrow or Down-arrow key.
2: The user pressed the Page-up key.
3: The user pressed the Page-down key.
4: The user moved the slider via the mouse wheel, or finished a drag-and-drop to a new position.
5: The user is currently dragging the slider via the mouse; that is, the mouse button is currently
down.
6: The user pressed the Home key to send the slider to the left or top side.
7: The user pressed the End key to send the slider to the right or bottom side.
Normal: The user has finished moving the slider, either via the mouse or the keyboard. Note: With the
exception of mouse wheel movement (#4), the g-label is launched again for the "normal" event even
though it was already launched for one of the digit-events above.
Slider Options:
Buddy1 and Buddy2: Specifies up to two existing controls to automatically reposition at the ends of
the slider. Buddy1 is displayed at the left or top side (depending on whether the Vertical option is
present). Buddy2 is displayed at the right or bottom side. After the word Buddy1 or Buddy2, specify
the variable name of an existing control. For example, Buddy1MyTopText would assign the control
whose variable name is MyTopText. Windows 95 and NT4 require Internet Explorer 3.0 or later to
support this option.
Center: The thumb (the bar moved by the user) will be blunt on both ends rather than pointed at one
end.
Invert: Reverses the control so that the lower value is considered to be on the right/bottom rather
than the left/top. This is typically used to make a vertical slider move in the direction of a traditional
volume control. Note: The ToolTip option described below will not obey the inversion and therefore
should not be used in this case.
Left: The thumb (the bar moved by the user) will point to the top rather than the bottom. But if the
Vertical option is in effect, the thumb will point to the left rather than the right.
Line: Specifies the number of positions to move when the user presses one of the arrow keys. After
the word Line, specify number of positions to move. For example: Line2
NoTicks: No tickmarks will be displayed.
Page: Specifies the number of positions to move when the user presses the Page-up or Page-down
key. After the word Page, specify number of positions to move. For example: Page10
Printed Documentation
248
Range: Sets the range to be something other than 0 to 100. After the word Range, specify the
minimum, a dash, and maximum. For example, Range1-1000 would allow a number between 1 and
1000 to be selected; Range-50-50 would allow a number between -50 and 50; and Range-10--5
would allow a number between -10 and -5.
Thick: Specifies the length of the thumb (the bar moved by the user). After the word Thick, specify
the thickness in pixels (e.g. Thick30). To go beyond a certain thickness on Windows XP or later, it is
probably necessary to either specify the Center option or remove the theme from the control (which
can be done by specifying -Theme in the control's options).
TickInterval: Provides tickmarks at the specified interval. After the word TickInterval, specify the
interval at which to display additional tickmarks (if the interval is omitted, it is assumed to be 1). For
example, TickInterval10 would display a tickmark once every 10 positions.
ToolTip: Creates a tooltip that reports the numeric position of the slider as the user is dragging it. To
have the tooltip appear in a non-default position, specify one of the following instead: ToolTipLeft or
ToolTipRight (for horizontal sliders); ToolTipTop or ToolTipBottom (for vertical sliders). Windows 95
and NT4 require Internet Explorer 3.0 or later to support this option.
Vertical: Makes the control slide up and down rather than left and right.
The above options can be changed after the control is created via GuiControl.
Progress
Description: A dual-color bar typically used to indicate how much progress has been made toward the
completion of an operation.
Example: Gui, Add, Progress, w300 h20 cBlue
Specify the starting position of the bar as the last parameter (if omitted, the bar starts off at 0 or the
number in the allowable range that is closest to 0). To later change the position of the bar, follow
these examples, all of which operate upon a progress bar whose associated variable name is
MyProgress:
GuiControl,, MyProgress, +20 ; Increase the current position by 20.
GuiControl,, MyProgress, 50 ; Set the current position to 50.
For horizontal Progress Bars, the thickness of the bar is equal to the control's height. For vertical
Progress Bars it is equal to the control's width.
Progress Options:
Cn: Changes the bar's color. Specify for n one of the 16 primary HTML color names or a 6-digit RGB
color value. Examples: cRed, cFFFF33, cDefault. If the C option is never used (or cDefault is
specified), the system's default bar color will be used.
BackgroundN: Changes the bar's background color. Specify for n one of the 16 primary HTML color
names or a 6-digit RGB color value. Examples: BackgroundGreen, BackgroundFFFF33,
BackgroundDefault. If the Background option is never used (or BackgroundDefault is specified), the
background color will be that of the window or tab control behind it.
Range: Sets the range to be something other than 0 to 100. After the word Range, specify the
minimum, a dash, and maximum. For example, Range0-1000 would allow a numbers between 0 and
1000; Range-50-50 would allow numbers between -50 and 50; and Range-10--5 would allow numbers
between -10 and -5. On Windows 95 and NT4, negative ranges and ranges beyond 65535 will not
behave correctly unless Internet Explorer 3.0 or later is installed.
-Smooth (minus Smooth): Displays a length of segments rather than a smooth continuous bar.
Specifying -Smooth is also one of the requirements to show a themed progress bar on Windows XP or
later. The other requirement is that the bar not have any custom colors; that is, that the C and
Background options be omitted. Windows 95 and NT4 require Internet Explorer 3.0 or later to support
this option.
GUI, MsgBox, InputBox & Other Dialogs
249
Vertical: Makes the bar rise or fall vertically rather than move along horizontally. Windows 95 and NT4
require Internet Explorer 3.0 or later to support this option.
The above options can be changed after the control is created via GuiControl.
GroupBox
Description: A rectangular border/frame, often used around other controls to indicate they are related.
In this case, the last parameter is the title of the box, which if present is displayed at its upper-left
edge.
Example: Gui, Add, GroupBox, w400 h300, Geographic Criteria
By default, a GroupBox's title may have only one line of text. This can be overridden by specifying
Wrap in Options.
Tab
Description: A large control containing multiple pages, each of which contains other controls. From
this point forward, these pages are referred to as "tabs".
Example: Gui, Add, Tab,, General|View|Appearance|Settings
The last parameter above is a pipe-delimited list of tab names. To have one of the tabs pre-selected
when the window first appears, include two pipe characters after it. Alternatively, include in Options
the word Choose followed immediately by the number to pre-select. For example, Choose5 would pre-
select the fifth tab (as with other options, it can also be a variable such as Choose%Var%). To change
the selected tab, add tabs, or remove tabs after the control has been created, use GuiControl.
After creating a Tab control, subsequently added controls automatically belong to its first tab. This can
be changed at any time by following these examples:
Gui, Tab ; Future controls are not part of any tab control.
Gui, Tab, 3 ; Future controls are owned by the third tab of the current tab control.
Gui, Tab, 3, 2 ; Future controls are owned by the third tab of the second tab control.
Gui, Tab, Name ; Future controls are owned by the tab whose name starts with Name (not
case sensitive).
Gui, Tab, Name,, Exact ; Same as above but requires exact match (case sensitive too).
[v1.0.37.03+]
It is also possible to use any of the examples above to assign controls to a tab or tab-control that does
not yet exist (except in the case of the Name method). But in that case, the relative positioning
options described below are not supported.
Positioning: When each tab of a Tab control receives its first sub-control, that sub-control will have a
special default position under the following conditions: 1) The X and Y coordinates are both omitted, in
which case the first sub-control is positioned at the upper-left corner of the tab control's interior (with
a standard margin), and sub-controls beyond the first are positioned beneath the previous control; 2)
The X+n and/or Y+n positioning options are specified, in which case the sub-control is positioned
relative to the upper-left corner of the tab control's interior. For example, specifying "x+10 y+10"
would position the control 10 pixels right and 10 pixels down from the upper left corner.
Sub-controls do not necessarily need to exist within their Tab control's boundaries: they will still be
hidden and shown whenever their tab is selected or de-selected. This behavior is especially
appropriate for the "buttons" style described below.
When the Gui Submit command is used, the control's associated output variable (if any) receives the
name of the currently selected tab. However, if the control has the AltSubmit property, the output
variable will receive the tab's position number instead (the first tab is 1, the second is 2, etc.).
A g-label such as gMySubroutine may be listed in the control's options. This would cause the
MySubroutine label to be launched automatically whenever the user changes to a new tab. If the tab
Printed Documentation
250
control has both a g-label and an output variable, whenever the user switches to a new tab, the
output variable will be set to the previously selected tab name (or number in the case of AltSubmit).
Keyboard navigation: The user may press Control-PageDown/PageUp to navigate from page to page in
a tab control; if the keyboard focus is on a control that does not belong to a Tab control, the window's
first Tab control will be navigated. Control-Tab and Control-Shift-Tab may also be used except that
they will not work if the currently focused control is a multi-line Edit control.
Each window may have no more than 255 tab controls. Each tab control may have no more than 256
tabs (pages).
Tab Options:
Choose: See above.
-Background (minus followed by the word background): Overrides the window's custom background
color and uses the system's default Tab control color. Specify +Theme -Background to make the Tab
control conform to the current desktop theme. However, most control types will look strange inside
such a Tab control because their backgrounds will not match that of the tab control. This can be fixed
for some control types (such as Text) by adding BackgroundTrans to their options.
Buttons: Creates a series of buttons at the top of the control rather than a series of tabs (in this case,
there will be no border by default because the display area does not typically contain controls).
Left/Right/Bottom: Specify one of these words to have the tabs on the left, right, or bottom side
instead of the top. See TCS_VERTICAL for limitations on Left and Right.
-Wrap: Prevents the tabs from taking up more than a single row (in which case if there are too many
tabs to fit, arrow buttons are displayed to allow the user to slide more tabs into view).
Icons in Tabs: An icon may be displayed next to each tab's name/text via SendMessage. This is
demonstrated in the forum topic Icons in tabs.
StatusBar [v1.0.44+]
Description: A row of text and/or icons attached to the bottom of a window. Typically used to report
changing conditions.
; Example:
Gui, Add, StatusBar,, Bar's starting text (omit to start off empty).
SB_SetText("There are " . RowCount . " rows selected.")
The simplest use of a status bar is to call SB_SetText() whenever something changes that should be
reported to the user. To report more than one piece of information, divide the bar into sections via
SB_SetParts(). To display icon(s) in the bar, call SB_SetIcon().
All of the following StatusBar functions operate upon the current thread's default GUI window (which
can be changed via Gui, 2:Default). If the default window does not exist or has no status bar, all SB
functions return 0 to indicate the problem.
SB_SetText(NewText [, PartNumber, Style]): Displays NewText in the specified part of the status
bar. If PartNumber is omitted, it defaults to 1. Otherwise, specify an integer between 1 and 256. If
Style is omitted, it defaults to 0, which uses a traditional border that makes that part of the bar look
sunken. Otherwise, specify 1 to have no border or 2 to have border that makes that part of the bar
look raised. Finally, up to two tab characters (`t) may be present anywhere in NewText: anything to
the right of the first tab is centered within the part, and anything to the right of the second tab is
right-justified. SB_SetText() returns 1 upon success and 0 upon failure.
SB_SetParts([Width1, Width2, ... Width255]): Divides the bar into multiple sections according to
the specified widths (in pixels). If all parameters are omitted, the bar is restored to having only a
single, long part. Otherwise, specify the width of each part except the last (the last will fill the
remaining width of the bar). For example, SB_SetParts(50, 50) would create three parts: the first two
of width 50 and the last one of all the remaining width. Note: Any parts "deleted" by SB_SetParts()
will start off with no text the next time they are shown (furthermore, their icons are automatically
GUI, MsgBox, InputBox & Other Dialogs
251
destroyed). Upon success, SB_SetParts() returns a non-zero value (the status bar's HWND). Upon
failure it returns 0.
SB_SetIcon(Filename [, IconNumber, PartNumber]): Displays a small icon to the left of the text
in the specified part (if PartNumber is omitted, it defaults to 1). Filename is the name of an icon
(.ICO), cursor (.CUR), or animated cursor (.ANI) file (animated cursors will not actually be animated in
the bar). Other sources of icons include the following types of files: EXE, DLL, CPL, SCR, and other
types that contain icon resources. To use an icon group other than the first one in the file, specify its
number for IconNumber. For example, SB_SetIcon("Shell32.dll", 2) would use the default icon from
the second icon group. SB_SetIcon() returns the icon's HICON upon success and 0 upon failure. The
HICON is a system resource that can be safely ignored by most scripts because it is destroyed
automatically when the status bar's window is destroyed. Similarly, any old icon is destroyed when
SB_SetIcon() replaces it with a new one. This can be avoided via:
Gui +LastFound
SendMessage, 0x40F, part_number - 1, my_hIcon, msctls_statusbar321 ; 0x40F is
SB_SETICON.
G-Label Notifications: A g-label such as gMySubroutine may be listed in the control's options. This
would cause the MySubroutine label to be launched automatically whenever the user clicks on the bar.
This subroutine may consult the built-in variables A_Gui and A_GuiControl. More importantly, it may
consult A_GuiEvent, which contains one of the following strings (for compatibility with future
versions, a script should not assume these are the only possible values):
Normal: The user left-clicked the bar. The variable A_EventInfo contains the part number
(however, the part number might be a very large integer if the user clicks near the sizing grip
at the right side of the bar).
RightClick: The user right-clicked the bar. The variable A_EventInfo contains the part
number. NOTE: GuiContextMenu will not be called for the status bar if it has a g-label. Also,
the g-label's RightClick event should be used instead of GuiContextMenu when the script
needs to know which part number the user clicked on (A_EventInfo).
DoubleClick: The user double-clicked the bar. The variable A_EventInfo contains the part
number.
R: The user double-right-clicked the bar. The variable A_EventInfo contains the part number.
Font and Color: Although the font size, face, and style can be set via "Gui Font" (just like normal
controls), the text color cannot be changed. Also, "Gui Color" is not obeyed; instead, the status bar's
background color may be changed by specifying in Options the word Background followed immediately
by a color name (see color chart) or RGB value (the 0x prefix is optional). Examples:
BackgroundSilver, BackgroundFFDD99, BackgroundDefault.
Hiding the StatusBar: Upon creation, the bar can be hidden via Gui, Add, StatusBar, Hidden
vMyStatusBar. To hide it sometime after creation, use GuiControl, Hide, MyStatusBar. To show it, use
GuiControl, Show, MyStatusBar. Note: Hiding the bar does not reduce the height of the window. If
that is desired, one easy way is Gui, Show, AutoSize.
Styles (rarely used): See the StatusBar styles table.
Known Limitations: 1) Any control that overlaps the status bar might sometimes get drawn on top
of it. One way to avoid this is to dynamically shrink such controls via the GuiSize label. 2) There is a
limit of one status bar per window.
Example: The bottom of the TreeView page demonstrates a multipart status bar.
Related Pages
ListView, TreeView, Gui, GuiControl, GuiControlGet, Menu
GuiControl
Makes a variety of changes to a control in a GUI window.
Printed Documentation
252
GuiControl, Sub-command, ControlID [, Param3]
Parameters
Sub-
command
See list below.
ControlID
If the target control has an associated variable, specify the variable's name as
the ControlID (this method takes precedence over the ones described next).
For this reason, it is usually best to assign a variable to any control that will
later be accessed via GuiControl or GuiControlGet, even if that control is not an
input-capable type (such as GroupBox or Text).
Otherwise, ControlID can be either ClassNN (the classname and instance
number of the control) or the name/text of the control, both of which can be
determined via Window Spy. When using name/text, the matching behavior is
determined by SetTitleMatchMode. Note: a picture control's file name (as it
was specified at the time the control was created) may be used as its
ControlID.
Param3
This parameter is omitted except where noted in the list of sub-commands
below.
ErrorLevel
ErrorLevel is set to 1 if the specified window/control does not exist or some other problem prevented
the command from working. Otherwise, it is set to 0.
Sub-commands
(Blank): Leave Sub-command blank to put new contents into the control via Param3. Specifically:
Picture: Param3 should be the filename of the new image to load (see Gui Picture for supported file
types). Zero or more of the following options may be specified immediately in front of the filename:
*wN (width N), *hN (height N), and *IconN (icon group number N in a DLL or EXE file). In the
following example, the default icon from the second icon group is loaded with a width of 100 and an
automatic height via "keep aspect ratio": GuiControl,, MyPic, *icon2 *w100 *h-1 C:\My
Application.exe. Specify *w0 *h0 to use the image's actual width and height. If *w and *h are
omitted, the image will be scaled to fit the current size of the control. When loading from a multi-icon
.ICO file, specifying a width and height also determines which icon to load. Note: Use only one space
or tab between the final option and the filename itself; any other spaces and tabs are treated as part
of the filename.
Text/Button/GroupBox/StatusBar: Specify for Param3 the control's new text. Since the control will not
expand automatically, use GuiControl, Move, MyText, W300 if the control needs to be widened. For
StatusBar, this sets the text of the first part only. (use SB_SetText() for greater flexibility).
Edit: Any linefeeds (`n) in Param3 that lack a preceding carriage return (`r) are automatically
translated to CR+LF (`r`n) to make them display properly. However, this is usually not a concern
because the "Gui Submit" and "GuiControlGet OutputVar" commands will automatically undo this
translation by replacing CR+LF with LF (`n).
Hotkey: Param3 can be blank to clear the control, or a set of modifiers with a key name. Examples:
^!c, ^Numpad1, +Home. The only modifiers supported are ^ (Control), ! (Alt), and + (Shift). See the
key list for available key names.
Checkbox: Param3 can be 0 to uncheck the button, 1 to check it, or -1 to give it a gray checkmark.
Otherwise, Param3 is assumed to be the control's new caption/text. See Text below for how to
override this behavior.
Radio: Same as Checkbox above. However, if the radio button is being checked (turned on) and it is a
member of a multi-radio group, the other radio buttons in its group will be automatically unchecked.
GUI, MsgBox, InputBox & Other Dialogs
253
To check a new button within a radio group that only has one variable, specify for ControlID the
name/text of the button if it is not the button with which the variable is directly associated.
DateTime/MonthCal: Specify for Param3 a date-time stamp in YYYYMMDDHH24MISS format. Specify
%A_Now% to use the current date and time (today). For DateTime controls, Param3 may be omitted
to cause the control to have no date/time selected (if it was created with that ability). For MonthCal
controls, a range may be specified if the control is multi-select.
UpDown/Slider/Progress: Param3 should be the new position of the control. If a Param3's first
character is a plus sign, the number will be assumed to be an offset from the current position. For
example, +10 would increase the position by 10 and +-10 (plus minus ten) would decrease it by 10. If
the new position would be outside the range of the control, the control is generally set to the nearest
valid value.
Tab/DropDownList/ComboBox/ListBox: Param3 should contain a pipe-delimited list of entries to be
appended at the end of the control's list. To replace (overwrite) the list instead, include a pipe as the
first character (e.g. |Red|Green|Blue). To make the control empty, specify only a pipe character (|).
To have one of the entries pre-selected, include two pipes after it (e.g. Red|Green||Blue). The
separator between fields may be changed to something other than pipe. For example Gui
+Delimiter`n would change it to linefeed and Gui +DelimiterTab would change it to tab (`t).
Tab controls: In addition to the behavior described in the paragraph above, a tab's sub-controls stay
associated with their original tab number; that is, they are never associated with their tab's actual
display-name. For this reason, renaming or removing a tab will not change the tab number to which
the sub-controls belong. For example, if there are three tabs "Red|Green|Blue" and the second tab is
removed by means of "GuiControl,, MyTab, |Red|Blue", the sub-controls originally associated with
Green will now be associated with Blue. Because of this behavior, only tabs at the end should
generally be removed. Tabs that are removed in this way can be added back later, at which time they
will reclaim their original set of controls.
ListView and TreeView: These are not supported when Sub-command is blank. Instead, use the built-
in ListView functions and TreeView functions.

Text: Behaves the same as the above except for:
Checkbox/Radio: Param3 is treated as the new text/caption even if it is -1, 0, or 1.
DateTime: Param3 is treated as the new date/time format displayed by the control. If Param3 is
omitted, any custom format is removed and the short-date format is put into effect.
ComboBox: In v1.0.38+, Param3 is treated as the text to put directly into the ComboBox's Edit
control.
Move: Moves and/or resizes the control. Specify one or more of the following option letters in
Param3: X (the x-coordinate relative to the GUI window's client area, which is the area not including
title bar, menu bar, and borders); Y (the y-coordinate), W (Width), H (Height). For example:
GuiControl, Move, MyEdit, x10 y20 w200 h100
GuiControl, Move, MyEdit, % "x" VarX+10 "y" VarY+5 "w" VarW*2 "h" VarH*1.5 ; Uses an
expression via "% " prefix.
MoveDraw [v1.0.41.02+]: Same as "Move" (above) except that it also repaints the region of the GUI
window occupied by the control. Although this may cause an unwanted flickering effect when called
repeatedly and rapidly, it solves painting artifacts for certain control types such as GroupBoxes. In
versions prior to 1.0.41.02, "MoveDraw" was the behavior used by "Move".
Focus: Sets keyboard focus to the control. To be effective, the window generally must not be
minimized or hidden.
Disable / Enable: Disables or enables (grays out) the control. For Tab controls, this will also enable
or disable all of the tab's sub-controls. However, any sub-control explicitly disabled via "GuiControl
Disable" will remember that setting and thus remain disabled even after its Tab control is re-enabled.
In v1.0.38.02+, the word Disable or Enable may optionally be followed immediately by a 0 or 1. A
zero causes the effect to be inverted. For example, Enable and Enable%VarContainingOne% would
both enable the control, but Enable%VarContainingZero% would disable it.
Printed Documentation
254
Hide / Show: Hides or shows the control. For Tab controls, this will also show or hide all of the tab's
sub-controls. If you additionally want to prevent a control's shortcut key (underlined letter) from
working, disable the control via "GuiControl Disable". In v1.0.38.02+, the word Hide or Show may
optionally be followed immediately by a 0 or 1. A zero causes the effect to be inverted. For example,
Show and Show%VarContainingOne% would both show the control, but Show%VarContainingZero%
would hide it.
Delete (not yet implemented): This sub-command does not yet exist. As a workaround, use Hide
and/or Disable (above), or destroy and recreate the entire window via Gui Destroy.
Choose, ControlID, N: Sets the selection in a ListBox, DropDownList, ComboBox, or Tab control to
be the Nth entry. N should be 1 for the first entry, 2 for the second, etc (if N is not an integer, the
ChooseString method described below will be used instead). Unlike Control Choose, this sub-command
will not trigger any g-label associated with the control unless N is preceded by a pipe character. For
example: GuiControl, Choose, MyListBox, |3.
To additionally cause a finishing event to occur (a double-click in the case of ListBox), include two
leading pipes instead of one (this is not supported for Tab controls).
To select or deselect all items in a multi-select ListBox, follow this example:
Gui +LastFound ; Avoids the need to specify WinTitle below.
PostMessage, 0x185, 1, -1, ListBox1 ; Select all items. 0x185 is LB_SETSEL.
PostMessage, 0x185, 0, -1, ListBox1 ; Deselect all items.
ChooseString, ControlID, String: Sets the selection (choice) in a ListBox, DropDownList,
ComboBox, or Tab control to be the entry whose leading part matches String. The search is not case
sensitive. For example, if a the control contains the item "UNIX Text", specifying the word unix
(lowercase) would be enough to select it. The pipe and double-pipe prefix are also supported (see
"Choose" above for details).
Font: Changes the control's font to the typeface, size, color, and style currently in effect for its
window. For example:
Gui, Font, s18 cRed Bold, Verdana ; If desired, use a line like this to set a new default font for
the window.
GuiControl, Font, MyEdit ; Put the above font into effect for a control.
+/-Option1 +/-Option2 ... : Add or remove various options and styles. All GUI options (control-
specific and general) are recognized. In the following example, the AltSubmit option is enabled but
control's g-label is removed: GuiControl, +AltSubmit -g, MyListBox
In the next example, the OK button is made the new default button:
GuiControl, +Default, OK
Although styles and extended styles are also recognized, some of them cannot be applied or removed
after a control has been created. ErrorLevel is set to 0 if at least one of the specified changes was
successfully applied. Otherwise, it is set to 1 to indicate that none of the changes could be applied.
Even if a change is successfully applied, the control might choose to ignore it.
Remarks
To operate upon a window number other than the default (see below), include a number followed by a
colon in front of the sub-command as in these examples:
GuiControl, 2:Show, MyButton
GuiControl, 2:, MyListBox, Item1|Item2
A GUI thread is defined as any thread launched as a result of a GUI action. GUI actions include
selecting an item from a GUI window's menu bar, or triggering one of its g-labels (such as by pressing
a button).
The default window number for a GUI thread is that of the window that launched the thread. Non-GUI
threads use 1 as their default.
GUI, MsgBox, InputBox & Other Dialogs
255
Related
Gui, GuiControlGet, Control
Examples
GuiControl,, MyListBox, |Red|Green|Blue ; Replace the current list with a new list.
GuiControl,, MyEdit, New text line 1.`nNew text line 2.
GuiControl,, MyRadio2, 1 ; Turn on this radio button and turn off all the others in its group.
GuiControl, Move, OK, x100 y200 ; Move the OK button to a new location.
GuiControl, Focus, LastName ; Set keyboard focus to the control whose variable or text is
"LastName".
GuiControlGet
Retrieves various types of information about a control in a GUI window.
GuiControlGet, OutputVar [, Sub-command, ControlID, Param4]
Parameters
OutputVar
The name of the variable in which to store the result. If the command cannot
complete (see ErrorLevel below), this variable is made blank.
Sub-
command
See list below.
ControlID
If blank or omitted, it defaults to the control whose associated output variable
is OutputVar.
If the target control has an associated variable, specify the variable's name as
the ControlID (this method takes precedence over the ones described next).
For this reason, it is usually best to assign a variable to any control that will
later be accessed via GuiControl or GuiControlGet, even if that control is not
input-capable (such as GroupBox or Text).
Otherwise, ControlID can be either ClassNN (the classname and instance
number of the control) or the name/text of the control, both of which can be
determined via Window Spy. When using name/text, the matching behavior is
determined by SetTitleMatchMode. Note: a picture control's file name (as it
was specified at the time the control was created) may be used as its
ControlID.
Param4
This parameter is omitted except where noted in the list of sub-commands
below.
ErrorLevel
ErrorLevel is set to 1 if the specified window/control does not exist or some other problem prevented
the command from working. Otherwise, it is set to 0.
Sub-commands
(Blank): Leave Sub-command blank to retrieve the control's contents. All control types are self-
explanatory except the following:
Picture: Retrieves the picture's file name as it was originally specified when the control was created.
This name does not change even if a new picture file name is specified.
Printed Documentation
256
Edit: Retrieves the contents but any line breaks in the text will be represented as plain linefeeds (`n)
rather than the traditional CR+LF (`r`n) used by non-GUI commands such as ControlGetText and
ControlSetText.
Hotkey: Retrieves a blank value if there is no hotkey in the control. Otherwise it retrieves the
modifiers and key name. Examples: ^!C, ^Home, +^NumpadHome.
Checkbox/Radio: Retrieves 1 if the control is checked, 0 if it is unchecked, or -1 if it has a gray
checkmark. To retrieve the control's text/caption instead, specify the word Text for Param4. Note:
Unlike the Gui Submit command, radio buttons are always retrieved individually, regardless of
whether they are in a radio group.
UpDown/Slider/Progress: Retrieves the control's current position.
Tab/DropDownList/ComboBox/ListBox: Retrieves the text of the currently selected item/tab (or its
position if the control has the AltSubmit property). For a ComboBox, if there is no selected item, the
text in the control's edit field is retrieved instead. For a multi-select ListBox, the output uses the
window's current delimiter.
ListView and TreeView: These are not supported when Sub-command is blank. Instead, use the built-
in ListView functions and TreeView functions.
StatusBar: Retrieves only the first part's text.
Note: To unconditionally retrieve any control's text/caption rather than its contents, specify the word
Text for Param4.

Pos: Retrieves the position and size of the control. The position is relative to the GUI window's client
area, which is the area not including title bar, menu bar, and borders. The information is stored in four
variables whose names all start with OutputVar. For example:
GuiControlGet, MyEdit, Pos
MsgBox The X coordinate is %MyEditX%. The Y coordinate is %MyEditY%. The width is
%MyEditW%. The height is %MyEditH%.
Within a function, to create a set of variables that is global instead of local, declare OutputVar as a
global variable prior to using this command (the converse is true for assume-global functions).

Focus: Retrieves the control identifier (ClassNN) for the control that currently has keyboard focus.
Since the specified GUI window must be active for one of its controls to have focus, OutputVar will be
made blank if it is not active. Example usage: GuiControlGet, focused_control, focus
FocusV [v1.0.43.06+]: Same as Focus (above) except that it retrieves the name of the focused
control's associated variable. If that control lacks an associated variable, the first 63 characters of the
control's text/caption is retrieved instead (this is most often used to avoid giving each button a
variable name).
Enabled: Retrieves 1 if the control is enabled or 0 if it is disabled.
Visible: Retrieves 1 if the control is visible or 0 if it is hidden.
Remarks
To operate upon a window number other than the default (see below), include a number followed by a
colon in front of the sub-command as in these examples:
GuiControlGet, MyEdit, 2:
GuiControlGet, MyEdit, 2:Pos
GuiControlGet, Outputvar, 2:Focus
A GUI thread is defined as any thread launched as a result of a GUI action. GUI actions include
selecting an item from a GUI window's menu bar, or triggering one of its g-labels (such as by pressing
a button).
GUI, MsgBox, InputBox & Other Dialogs
257
The default window number for a GUI thread is that of the window that launched the thread. Non-GUI
threads use 1 as their default.
Related
Gui, GuiControl, ControlGet
Examples
GuiControlGet, MyEdit
GuiControlGet, CtrlContents,, MyEdit ; Same as the above except uses a non-default output
variable.GuiControlGet, MyCheckbox1 ; Retrieves 1 if it is checked, 0 if it is unchecked.
GuiControlGet, MyCheckbox1,,, Text ; Retrieves the caption/text of the checkbox.
GuiControlGet, Pic, Pos, Static4 ; The position/size will be stored in PicX, PicY, PicW, and PicH
ListView [v1.0.36+]
Table of Contents
Introduction and Simple Example
Options and Styles
View Modes: Report (default), Icon, Tile, Small-Icon, and List.
Built-in Functions:
o Row functions (adding, modifying, and deleting rows)
o Column functions
o Getting data out of a ListView
G-Label Notifications
ImageLists (the means by which icons are added to a ListView)
ListView Remarks
Examples
Introduction and Simple Example
A List-View is one of the most elaborate controls provided by the operating system. In its most
recognizable form, it displays a tabular view of rows and columns, the most common example of
which is Explorer's list of files and folders (detail view).
Though it may be elaborate, a ListView's basic features are easy to use. The syntax for creating a
ListView is:
Gui, Add, ListView, Options, ColumnTitle1|ColumnTitle2|...
Here is a working script that creates and displays a ListView containing a list of files in the user's "My
Documents" folder:
; Create the ListView with two columns, Name and Size:
Gui, Add, ListView, r20 w700 gMyListView, Name|Size (KB)

; Gather a list of file names from a folder and put them into the ListView:
Loop, %A_MyDocuments%\*.*
LV_Add("", A_LoopFileName, A_LoopFileSizeKB)

Printed Documentation
258
LV_ModifyCol() ; Auto-size each column to fit its contents.
LV_ModifyCol(2, "Integer") ; For sorting purposes, indicate that column 2 is an integer.

; Display the window and return. The script will be notified whenever the user double clicks a
row.
Gui, Show
return

MyListView:
if A_GuiEvent = DoubleClick
{
LV_GetText(RowText, A_EventInfo) ; Get the row's first-column text.
ToolTip You double-clicked row number %A_EventInfo%. Text: "%RowText%"
}
return

GuiClose: ; Indicate that the script should exit automatically when the window is closed.
ExitApp
Options and Styles for "Gui, Add, ListView, Options"
AltSubmit: Notifies the script for more types of ListView events than normal. In other words, the g-
label is launched more often. See ListView Notifications for details.
Background: Specify the word Background followed immediately by a color name (see color chart) or
RGB value (the 0x prefix is optional). Examples: BackgroundSilver, BackgroundFFDD99. If this option
is not present, the ListView initially defaults to the background color set by the last parameter of Gui
Color (or if none, the system's default background color). Specifying BackgroundDefault applies the
system's default background color (usually white). For example, a ListView can be restored to the
default color via GuiControl, +BackgroundDefault, MyListView.
C: Text color. Specify the letter C followed immediately by a color name (see color chart) or RGB
value (the 0x prefix is optional). Examples: cRed, cFF2211, c0xFF2211, cDefault
Checked: Provides a checkbox at the left side of each row. When adding a row, specify the word
Check in its options to have the box to start off checked instead of unchecked. The user may either
click the checkbox or press the spacebar to check or uncheck a row.
Count: Specify the word Count followed immediately by the total number of rows that the ListView
will ultimately contain. This is not a limit: rows beyond the count can still be added. Instead, this
option serves as a hint to the control that allows it to allocate memory only once rather than each
time a row is added, which greatly improves row-adding performance (it may also improve sorting
performance). To improve performance even more, use GuiControl, -Redraw, MyListView prior to
adding a large number of rows. Afterward, use GuiControl, +Redraw, MyListView to re-enable
redrawing (which also repaints the control).
Grid: Provides horizontal and vertical lines to visually indicate the boundaries between rows and
columns.
Hdr: Specify -Hdr (minus Hdr) to omit the special top row that contains column titles. To make it
visible later, use GuiControl, +Hdr, MyListView.
GUI, MsgBox, InputBox & Other Dialogs
259
LV: Specify the string LV followed immediately by the number of an extended ListView style. These
styles are entirely separate from generic extended styles. For example, specifying -E0x200 would
remove the generic extended style WS_EX_CLIENTEDGE to eliminate the control's default border. By
contrast, specifying -LV0x20 would remove LVS_EX_FULLROWSELECT.
LV0x10: Specify -LV0x10 to prevent the user from dragging column headers to the left or right to
reorder them. However, it is usually not necessary to do this because the physical reordering of
columns does not affect the column order seen by the script. For example, the first column will always
be column 1 from the script's point of view, even if the user has physically moved it to the right of
other columns.
LV0x20: Specify -LV0x20 to require that a row be clicked at its first field to select it (normally, a click
on any field will select it). The advantage of this is that it makes it easier for the user to drag a
rectangle around a group of rows to select them.
Multi: Specify -Multi (minus Multi) to prevent the user from selecting more than one row at a time.
NoSortHdr: Prevents the header from being clickable. It will take on a flat appearance rather than its
normal button-like appearance. Unlike most other ListView styles, this one cannot be changed after
the ListView is created.
NoSort: Turns off the automatic sorting that occurs when the user clicks a column header. However,
the header will still behave visually like a button (unless NoSortHdr has been specified). In addition, g-
label will still receive the ColClick notification, to which it can respond with a custom sort or other
action.
ReadOnly: Specify -ReadOnly (minus ReadOnly) to allow editing of the text in the first column of
each row. To edit a row, select it then press the F2 key. Alternatively, you can click a row once to
select it, wait at least half a second, then click the same row again to edit it.
R: Rows of height (upon creation). Specify the letter R followed immediately by the number of rows
for which to make room inside the control. For example, R10 would make the control 10 rows tall. If
the ListView is created with a view mode other than report view, the control is sized to fit rows of
icons instead of rows of text. Note: adding icons to a ListView's rows will increase the height of each
row, which will make this option inaccurate.
Sort: The control is kept alphabetically sorted according to the contents of the first column.
SortDesc: Same as above except in descending order.
WantF2 [v1.0.44+]: Specify -WantF2 (minus WantF2) to prevent an F2 keystroke from editing the
currently focused row. This setting is ignored unless -ReadOnly is also in effect. Regardless of this
setting, the g-label still receives F2 notifications.
(Unnamed numeric styles): Since styles other than the above are rarely used, they do not have
names. See the ListView styles table for a list.
View Modes
A ListView has five viewing modes, of which the most common is report view (which is the default). To
use one of the other views, specify its name in the options list. The view can also be changed after the
control is created; for example: GuiControl, +IconSmall, MyListView
Icon: Shows a large-icon view. In this view and all the others except Report, the text in columns
other than the first is not visible. To display icons in this mode, the ListView must have a large-icon
ImageList assigned to it.
Tile [v1.0.36.03+]: Shows a large-icon view but with ergonomic differences such as displaying each
item's text to the right of the icon rather than underneath it. Checkboxes do not function in this view.
Also, attempting to show this view on operating systems older than Windows XP has no effect.
IconSmall: Shows a small-icon view.
List: Shows a small-icon view in list format, which displays the icons in columns. The number of
columns depends on the width of the control and the width of the widest text item in it.
Printed Documentation
260
Report: Switches back to report view, which is the initial default. For example: GuiControl, +Report,
MyListView
Built-in Functions for ListViews
All of the ListView functions operate upon the current thread's default GUI window (which can be
changed via Gui, 2:Default). If the default window does not exist or has no ListView controls, all
functions return zero to indicate the problem.
If the window has more than one ListView control, by default the functions operate upon the one most
recently added. To change this, specify Gui, ListView, ListViewName, where ListViewName is the name
of the ListView's associated variable or its ClassNN as shown by Window Spy. Once changed, all
existing and future threads will use the indicated ListView for subsequent operations.
When the phrase "row number" is used below, it refers to a row's current position within the ListView.
The top row is 1, the second row is 2, and so on. After a row is added, its row number tends to change
due to sorting, deleting, and inserting of other rows. Therefore, to locate specific row(s) based on their
contents, it is usually best to use LV_GetText() in a loop.
Row Functions
LV_Add([Options, Field1, Field2, ...]): Adds a new row to the bottom of the list. The parameters
Field1 and beyond are the columns of the new row, which can be text or numeric (including numeric
expression results). To make any field blank, specify "" or the equivalent. If there are too few fields to
fill all the columns, the columns at the end are left blank. If there are too many fields, the fields at the
end are completely ignored.
On failure, LV_Add() returns 0. Upon success, it returns the new row number, which is not necessarily
the last row if the ListView has the Sort or SortDesc style.
Row Options: The Options parameter is a string containing zero or more of the following words (not
case sensitive). Separate each word from the next with a space or tab. To remove an option, precede
it with a minus sign. To add an option, a plus sign is permitted but not required.
Check: Shows a checkmark in the row (if the ListView has checkboxes). To later uncheck it, use
LV_Modify(RowNumber, "-Check").
Col: Specify the word Col followed immediately by the column number at which to begin applying the
parameters Col1 and beyond. This is most commonly used with LV_Modify() to alter individual fields in
a row without affecting those that lie to their left.
Focus: Sets keyboard focus to the row (often used in conjunction with Select). To later de-focus it, use
LV_Modify(RowNumber, "-Focus").
Icon: Specify the word Icon followed immediately by the number of this row's icon, which is displayed
in the left side of the first column. If this option is absent, the first icon in the ImageList is used. To
display a blank icon, specify a number that is larger than the number of icons in the ImageList. If the
control lacks a small-icon ImageList, no icon is displayed nor is any space reserved for one in report
view.
Select: Selects the row. To later deselect it, use LV_Modify(RowNumber, "-Select"). When selecting
rows, it is usually best to ensure that at least one row always has the focus property because that
allows the Apps key to display its context menu (if any) near the focused row. The word Select may
optionally be followed immediately by a 0 or 1 to indicate the starting state. In other words, both
"Select" and "Select" . VarContainingOne are the same (the period used here is the concatenation
operator). This technique also works with Focus and Check below.
Vis [1.0.44+]: Ensures that the specified row is completely visible by scrolling the ListView, if
necessary. This has an effect only for LV_Modify(); for example: LV_Modify(RowNumber "Vis")

LV_Insert(RowNumber [, Options, Col1, Col2, ...]): Behaves identically to LV_Add() except for its
different first parameter, which specifies the row number for the newly inserted row. Any rows at or
GUI, MsgBox, InputBox & Other Dialogs
261
beneath RowNumber are shifted downward to make room for the new row. If RowNumber is greater
than the number of rows in the list (even as high as 2147483647), the new row is added to the end of
the list. For Options, see row options.
LV_Modify(RowNumber, Options [, NewCol1, NewCol2, ...]): Modifies the attributes and/or text
of a row, and returns 1 upon success and 0 upon failure. If RowNumber is 0, all rows in the control are
modified (in this case the function returns 1 on complete success and 0 if any part of the operation
failed). When only the first two parameters are present, only the row's attributes and not its text are
changed. Similarly, if there are too few parameters to cover all the columns, the columns at the end
are not changed. The ColN option may be used to update specific columns without affecting the
others. For other options, see row options.
LV_Delete([RowNumber]): If the parameter is omitted, all rows in the ListView are deleted.
Otherwise, only the specified RowNumber is deleted. It returns 1 upon success and 0 upon failure.
Column Functions
LV_ModifyCol([ColumnNumber, Options, ColumnTitle]): Modifies the attributes and/or text of
the specified column and its header. The first column is number 1 (not 0). If all parameters are
omitted, the width of every column is adjusted to fit the contents of the rows. If only the first
parameter is present, only the specified column is auto-sized. Auto-sizing has no effect when not in
Report (Details) view. This function returns 1 upon success and 0 upon failure.
Column Options: The Options parameter is a string containing zero or more of the following words
(not case sensitive). Separate each word from the next with a space or tab. To remove an option,
precede it with a minus sign. To add an option, a plus sign is permitted but not required.
Column Options: General
N: Specify for N the new width of the column, in pixels. This number can be unquoted if is the only
option. For example, the following are both valid: LV_ModifyCol(1, 50) .... LV_ModifyCol(1, "50
Integer").
Auto: Adjusts the column's width to fit its contents. This has no effect when not in Report (Details)
view.
AutoHdr: Adjusts the column's width to fit its contents and the column's header text, whichever is
wider. If applied to the last column, it will be made at least as wide as all the remaining space in the
ListView. It is usually best to apply this setting only after the rows have been added because that
allows any newly-arrived vertical scroll bar to be taken into account when sizing the last column. This
option has no effect when not in Report (Details) view.
Icon: Specify the word Icon followed immediately by the number of the ImageList's icon to display
next to the column header's text. Specify -Icon (minus icon) to remove any existing icon. On Windows
95/NT4, column icons require the DLLs distributed with Internet Explorer 3.0 or later.
IconRight: Puts the icon on the right side of the column rather than the left.
Column Options: Data Type
Float: Same as the above except for floating point numbers (hexadecimal format is not supported).
Sorting performance for Float and Text columns is up to 25 times slower than it is for integers.
Integer: For sorting purposes, indicates that this column contains integers. To be sorted properly,
each integer must be 32-bit; that is, within the range -2147483648 to 2147483647. If any of the
values are not integers, they will be considered zero when sorting (unless they start with a number, in
which case that number is used). Numbers may appear in either decimal or hexadecimal format (e.g.
0xF9E0).
Text: Changes the column back to text-mode sorting, which is the initial default for every column.
Only the first 8190 characters of text are significant for sorting purposes (except for the Logical
option, in which case the limit is 4094).
Column Options: Alignment / Justification
Printed Documentation
262
Center: Centers the text in the column. To center an Integer or Float column, specify the word Center
after the word Integer or Float.
Left: Left-justifies the column's text, which is the initial default for every column. On older operating
systems, the first column might have a forced left-justification.
Right: Right-justifies the column's text. This attribute need not be specified for Integer and Float
columns because they are right-justified by default. That default can be overridden by specifying
something such as "Integer Left" or "Float Center".
Column Options: Sorting
Case: The sorting of the column is case sensitive (affects only text columns). If the options Case,
CaseLocale, and Logical are all omitted, the uppercase letters A-Z are considered identical to their
lowercase counterparts for the purpose of the sort.
CaseLocale [v1.0.43.03+]: The sorting of the column is case insensitive based on the current user's
locale (affects only text columns). For example, most English and Western European locales treat the
letters A-Z and ANSI letters like and as identical to their lowercase counterparts. This method also
uses a "word sort", which treats hyphens and apostrophes in such a way that words like "coop" and
"co-op" stay together.
Desc: Descending order. The column starts off in descending order the first time the user sorts it.
Logical [v1.0.44.12+]: Same as CaseLocale except that any sequences of digits in the text are treated
as true numbers rather than mere characters. For example, the string T33 would be considered
greater than T4. Logical requires Windows XP or later (on older OSes, CaseLocale is automatically
used instead). In addition, Logical and Case are currently mutually exclusive: only the one most
recently specified will be in effect.
NoSort: Prevents a user's click on this column from having any automatic sorting effect. To disable
sorting for all columns rather than only a subset, include NoSort in the ListView's options. If the
ListView has a g-label, the ColClick notification will still be received when the user clicks a no-sort
column.
Sort: Immediately sorts the column in ascending order (even if it has the Desc option).
SortDesc: Immediately sorts the column in descending order.
Uni: Unidirectional sort. This prevents a second click on the same column from reversing the sort
direction.

LV_InsertCol(ColumnNumber [, Options, ColumnTitle]): Creates a new column, inserting it as
the specified ColumnNumber (shifting any other columns to the right to make room). The first column
is 1 (not 0). If ColumnNumber is larger than the number of columns currently in the control, the new
column is added to the end of the list. The newly inserted column starts off with empty contents
beneath it unless it is the first column, in which case it inherits the old first column's contents and the
old first column acquires blank contents. The new column's attributes -- such as whether or not it uses
integer sorting -- always start off at their defaults unless changed via Options. This function returns
the new column's position number (or 0 upon failure). The maximum number of columns in a ListView
is 200.
LV_DeleteCol(ColumnNumber): Deletes the specified column and all of the contents beneath it. It
returns 1 upon success and 0 upon failure. Once a column is deleted, the column numbers of any that
lie to its right are reduced by 1. Consequently, calling LV_DeleteCol(2) twice would delete the second
and third columns. On operating systems older than Windows XP, attempting to delete the original
first column might might fail and return 0.
Getting Data Out of a ListView
LV_GetCount(["Selected | Column"]): Returns the total number of rows in the control. However, if
the parameter is present and it is "S" or "Selected", the count includes only the selected/highlighted
GUI, MsgBox, InputBox & Other Dialogs
263
rows. In v1.0.36.03+, if the parameter is "Col" or "Column", the number of columns is retrieved. This
function is always instantaneous because the control keeps track of these counts.
This function is often used in the top line of a Loop, in which case the function would get called only
once (prior to the first iteration). For example:
Loop % LV_GetCount()
{
LV_GetText(RetrievedText, A_Index)
if InStr(RetrievedText, "some filter text")
LV_Modify(A_Index, "Select") ; Select each row whose first field contains the filter-text.
}
To retrieve the widths of a ListView's columns -- for uses such as saving them to an INI file to be
remembered beween sessions -- follow this example:
Gui +LastFound
Loop % LV_GetCount("Column")
{
SendMessage, 4125, A_Index - 1, 0, SysListView321 ; 4125 is LVM_GETCOLUMNWIDTH.
MsgBox Column %A_Index%'s width is %ErrorLevel%.
}
LV_GetNext([StartingRowNumber, "Checked | Focused"]): Returns the row number of the next
selected, checked, or focused row. If none is found, zero is returned. If StartingRowNumber is omitted
or less than 1, the search begins at the top of the list. Otherwise, the search begins at the row after
StartingRowNumber. If the second parameter is omitted, the function searches for the next
selected/highlighted row. Otherwise, specify "C" or "Checked" to find the next checked row; or "F" or
"Focused" to find the focused row (there is never more than one focused row in the entire list, and
sometimes there is none at all). The following example reports all selected rows in the ListView:
RowNumber = 0 ; This causes the first loop iteration to start the search at the top of the list.
Loop
{
RowNumber := LV_GetNext(RowNumber) ; Resume the search at the row after that found
by the previous iteration.
if not RowNumber ; The above returned zero, so there are no more selected rows.
break
LV_GetText(Text, RowNumber)
MsgBox The next selected row is #%RowNumber%, whose first field is "%Text%".
}
An alternate method to find out if a particular row number is checked is the following:
Gui +LastFound
SendMessage, 4140, RowNumber - 1, 0xF000, SysListView321 ; 4140 is
LVM_GETITEMSTATE. 0xF000 is LVIS_STATEIMAGEMASK.
IsChecked := (ErrorLevel >> 12) - 1 ; This sets IsChecked to true if RowNumber is checked
or false otherwise.
LV_GetText(OutputVar, RowNumber [, ColumnNumber]): Retrieves the text at the specified
RowNumber and ColumnNumber and stores it in OutputVar. If ColumnNumber is omitted, it defaults
Printed Documentation
264
to 1 (the text in the first column). If RowNumber is 0, the column header text is retrieved. If the text
is longer than 8191, only the first 8191 characters are retrieved. The function returns 1 upon success
and 0 upon failure. Upon failure, OutputVar is also made blank.
Column numbers seen by the script are not altered by any dragging and dropping of columns the user
may have done. For example, the original first column is still number 1 even if the user drags it to the
right of other columns.
G-Label Notifications (Primary)
A g-label such as gMySubroutine may be listed in the control's options. This would cause the
MySubroutine label to be launched automatically whenever the user performs an action in the control.
This subroutine may consult the built-in variables A_Gui and A_GuiControl. More importantly, it may
consult A_GuiEvent, which contains one of the following strings or letters (for compatibility with
future versions, a script should not assume these are the only possible values):
DoubleClick: The user has double-clicked a row. The variable A_EventInfo contains the row number.
R: The user has double-right-clicked within the control. In v1.0.36.03+, the variable A_EventInfo
contains the focused row number.
ColClick: The user has clicked a column header. The variable A_EventInfo contains the column
number, which is the original number assigned when the column was created; that is, it does not
reflect any dragging and dropping of columns done by the user. One possible response to a column
click is to sort by a hidden column (zero width) that contains data in a sort-friendly format (such as a
YYYYMMDD integer date). Such a hidden column can mirror some other column that displays the same
data in a more friendly format (such as MM/DD/YY). For example, a script could hide column 3 via
LV_ModifyCol(3, 0), then disable automatic sorting in the visible column 2 via LV_ModifyCol(2,
"NoSort"). Then in response to the ColClick notification for column 2, the script would sort the ListView
by the hidden column via LV_ModifyCol(3, "Sort").
D: The user has attempted to start dragging a row or icon (there is currently no built-in support for
dragging rows or icons). In v1.0.36.03+, the variable A_EventInfo contains the focused row number.
In v1.0.44+, this notification occurs even without AltSubmit.
d (lowercase D): Same as above except a right-click-drag rather than a left-drag.
e (lowercase E): The user has finished editing the first field of a row (the user may edit it only when
the ListView has -ReadOnly in its options). In v1.0.36.03+, the variable A_EventInfo contains the row
number.
G-Label Notifications (Secondary)
If the ListView has the word AltSubmit in its options, its g-label is launched more often and
A_GuiEvent may contain the following additional values:
Normal: The user has left-clicked a row. In v1.0.36.03+, the variable A_EventInfo contains the
focused row number.
RightClick: The user has right-clicked a row. In v1.0.36.03+, the variable A_EventInfo contains the
focused row number. In most cases, it is best not to display a menu in response to this. Instead, use
the GuiContextMenu label because it also recognizes the Apps key. For example:
GuiContextMenu: ; Launched in response to a right-click or press of the Apps key.
if A_GuiControl <> MyListView ; This check is optional. It displays the menu only for clicks
inside the ListView.
return
; Show the menu at the provided coordinates, A_GuiX and A_GuiY. These should be used
; because they provide correct coordinates even if the user pressed the Apps key:
Menu, MyContextMenu, Show, %A_GuiX%, %A_GuiY%
GUI, MsgBox, InputBox & Other Dialogs
265
return
A: A row has been activated, which by default occurs when it is double clicked. In v1.0.36.03+, the
variable A_EventInfo contains the row number.
C: The ListView has released mouse capture.
E: The user has begun editing the first field of a row (the user may edit it only when the ListView has
-ReadOnly in its options). In v1.0.36.03+, the variable A_EventInfo contains the row number.
F: The ListView has received keyboard focus.
f (lowercase F): The ListView has lost keyboard focus.
I: Item changed. A row has changed by becoming selected/deselected, checked/unchecked, etc. If the
user selects a new row, at least two such notifications are received: one for the de-selection of the
previous row, and one for the selection of the new row. In v1.0.44+, the variable A_EventInfo
contains the row number.
K: The user has pressed a key while the ListView has focus. A_EventInfo contains the virtual key code
of the key, which is a number between 1 and 255. If the key is alphabetic, on most keyboard layouts
it can be translated to the corresponding character via Chr(A_EventInfo). F2 keystrokes are received
regardless of WantF2. However, the Enter keystroke is not received; to receive it, use a default button
as described below.
M: Marquee. The user has started to drag a selection-rectangle around a group of rows or icons.
S: The user has begun scrolling the ListView.
s (lowercase S): The user has finished scrolling the ListView.
ImageList (the means by which icons are added to a ListView)
An Image-List is a group of identically sized icons stored in memory. Upon creation, each ImageList is
empty. The script calls IL_Add() repeatedly to add icons to the list, and each icon is assigned a
sequential number starting at 1. This is the number to which the script refers to display a particular
icon in a row or column header. Here is a working example that demonstrates how to put icons into a
ListView's rows:
Gui, Add, ListView, h200 w180, Icon & Number|Description ; Create a ListView.
ImageListID := IL_Create(10) ; Create an ImageList to hold 10 small icons.
LV_SetImageList(ImageListID) ; Assign the above ImageList to the current ListView.
Loop 10 ; Load the ImageList with a series of icons from the DLL.
IL_Add(ImageListID, "shell32.dll", A_Index) ; Omits the DLL's path so that it works on
Windows 9x too.
Loop 10 ; Add rows to the ListView (for demonstration purposes, one for each icon).
LV_Add("Icon" . A_Index, A_Index, "n/a")
LV_ModifyCol("Hdr") ; Auto-adjust the column widths.
Gui Show
return

GuiClose: ; Exit the script when the user closes the ListView's GUI window.
ExitApp
IL_Create([InitialCount, GrowCount, LargeIcons?]): Creates a new ImageList, initially empty,
and returns the unique ID of the ImageList (or 0 upon failure). InitialCount is the number of icons you
expect to put into the list immediately (if omitted, it defaults to 2). GrowCount is the number of icons
Printed Documentation
266
by which the list will grow each time it exceeds the current list capacity (if omitted, it defaults to 5).
LargeIcons should be a numeric value: If non-zero, the ImageList will contain large icons. If zero, it
will contain small icons (this is the default when omitted). Icons added to the list are scaled
automatically to conform to the system's dimensions for small and large icons.
LV_SetImageList(ImageListID [, 0|1|2]): This function is normally called prior to adding any
rows to the ListView. It sets the ImageList whose icons will be displayed by the ListView's rows (and
optionally, its columns). ImageListID is the number returned from a previous call to IL_Create(). If the
second parameter is omitted, the type of icons in the ImageList is detected automatically as large or
small. Otherwise, specify 0 for large icons, 1 for small icons, and 2 for state icons (state icons are not
yet directly supported, but they could be used via SendMessage).
A ListView may have up to two ImageLists: small-icon and/or large-icon. This is useful when the script
allows the user to switch to and from the large-icon view. To add more than one ImageList to a
ListView, call LV_SetImageList() a second time, specifying the ImageListID of the second list. A
ListView with both a large-icon and small-icon ImageList should ensure that both lists contain the
icons in the same order. This is because the same ID number is used to reference both the large and
small versions of a particular icon.
Although it is traditional for all viewing modes except Icon and Tile to show small icons, this can be
overridden by passing a large-icon list to LV_SetImageList and specifying 1 (small-icon) for the second
parameter. This also increases the height of each row in the ListView to fit the large icon.
If successful, LV_SetImageList() returns the ImageListID that was previously associated with the
ListView (or 0 if none). Any such detached ImageList should normally be destroyed via
IL_Destroy(ImageListID).
IL_Add(ImageListID, Filename [, IconNumber, ResizeNonIcon?]): Adds an icon or picture to
the specified ImageListID and returns the new icon's index (1 is the first icon, 2 is the second, and so
on). Filename is the name of an icon (.ICO), cursor (.CUR), or animated cursor (.ANI) file (animated
cursors will not actually be animated when displayed in a ListView). Other sources of icons include the
following types of files: EXE, DLL, CPL, SCR, and other types that contain icon resources. To use an
icon group other than the first one in the file, specify its number for IconNumber. In the following
example, the default icon from the second icon group would be used: IL_Add(ImageListID, "C:\My
Application.exe", 2).
Non-icon images such as BMP, GIF and JPG may also be loaded. However, in this case the last two
parameters should be specified to ensure correct behavior: IconNumber should be the
mask/transparency color number (0xFFFFFF [the color white] might be best for most pictures); and
ResizeNonIcon should be non-zero to cause the picture to be scaled to become a single icon, or zero
to divide up the image into however many icons can fit into its actual width.
All operating systems support GIF, JPG, BMP, ICO, CUR, and ANI images. On Windows XP or later,
additional image formats such as PNG, TIF, Exif, WMF, and EMF are supported. Operating systems
older than XP can be given support by copying Microsoft's free GDI+ DLL into the AutoHotkey.exe
folder (but in the case of a compiled script, copy the DLL into the script's folder). To download the
DLL, search for the following phrase at www.microsoft.com: gdi redistributable
IL_Destroy(ImageListID): Deletes the specified ImageList and returns 1 upon success and 0 upon
failure. It is normally not necessary to destroy ImageLists because once attached to a ListView, they
are destroyed automatically when the ListView or its parent window is destroyed. However, if the
ListView shares ImageLists with other ListViews (by having 0x40 in its options), the script should
explicitly destroy the ImageList after destroying all the ListViews that use it. Similarly, if the script
replaces one of a ListView's old ImageLists with a new one, it should explicitly destroy the old one.
ListView Remarks
The Gui Submit command has no effect on a ListView control. Therefore, the script may use the
ListView's associated variable (if any) to store other data without concern that it will ever be
overwritten.
After a column is sorted -- either by means of the user clicking its header or the script calling
LV_ModifyCol(1, "Sort") -- any subsequently added rows will appear at the bottom of the list rather
GUI, MsgBox, InputBox & Other Dialogs
267
than obeying the sort order. The exception to this is the Sort and SortDesc styles, which attempt to
move newly added rows into the correct positions.
To detect when the user has pressed Enter while a ListView has focus, use a default button (which can
be hidden if desired). For example:
Gui, Add, Button, Hidden Default, OK
...
ButtonOK:
GuiControlGet, FocusedControl, FocusV
if FocusedControl <> MyListView
return
MsgBox % "Enter was pressed. The focused row number is " . LV_GetNext(0, "Focused")
return
In addition to navigating from row to row with the keyboard, the user may also perform incremental
search by typing the first few characters of an item in the first column. This causes the selection to
jump to the nearest matching row.
Although any length of text can be stored in each field of a ListView, only the first 260 characters are
displayed.
Although the maximum number of rows in a ListView is limited only by available system memory, row-
adding performance can be greatly improved as described in the Count option.
To use a picture as a background behind a ListView, create the picture control after the ListView and
include 0x4000000 (which is WS_CLIPSIBLINGS) in the picture's Options.
It is best not to insert or delete columns directly with SendMessage. This is because the program
maintains a collection of sorting preferences for each column, which would then get out of sync.
Instead, use the built-in column functions.
A script may create more than one ListView per window. To operate upon a ListView other than the
default one, see built-in functions.
Windows 95 and NT4: If the system lacks version 4.70 or later of Comctl32.dll, Shell32.dll, and
Shlwapi.dll -- which are distributed with various updates and applications such as Internet Explorer
3.0 or later -- ListViews are more limited and some features might not behave as expected.
To perform actions such as resizing, hiding, or changing the font of a ListView, use GuiControl.
To extract text from external ListViews (those not owned by the script), use "ControlGet List".
Related
TreeView, Other Control Types, Gui, GuiContextMenu, GuiControl, GuiControlGet, ListView styles table
Examples
; Select or de-select all rows by specifying 0 as the row number:
LV_Modify(0, "Select") ; Select all.
LV_Modify(0, "-Select") ; De-select all.
LV_Modify(0, "-Check") ; Uncheck all the checkboxes.

; Auto-size all columns to fit their contents:
LV_ModifyCol() ; There are no parameters in this mode.
Printed Documentation
268

; MAIN EXAMPLE
; The following is a working script that is more elaborate than the one near the top of this page.
; It displays the files in a folder chosen by the user, with each file assigned the icon associated with
; its type. The user can double-click a file, or right-click one or more files to display a context menu.

; Allow the user to maximize or drag-resize the window:
Gui +Resize

; Create some buttons:
Gui, Add, Button, Default gButtonLoadFolder, Load a folder
Gui, Add, Button, x+20 gButtonClear, Clear List
Gui, Add, Button, x+20, Switch View

; Create the ListView and its columns:
Gui, Add, ListView, xm r20 w700 vMyListView gMyListView, Name|In Folder|Size (KB)|Type
LV_ModifyCol(3, "Integer") ; For sorting, indicate that the Size column is an integer.

; Create an ImageList so that the ListView can display some icons:
ImageListID1 := IL_Create(10)
ImageListID2 := IL_Create(10, 10, true) ; A list of large icons to go with the small ones.

; Attach the ImageLists to the ListView so that it can later display the icons:
LV_SetImageList(ImageListID1)
LV_SetImageList(ImageListID2)

; Create a popup menu to be used as the context menu:
Menu, MyContextMenu, Add, Open, ContextOpenFile
Menu, MyContextMenu, Add, Properties, ContextProperties
Menu, MyContextMenu, Add, Clear from ListView, ContextClearRows
Menu, MyContextMenu, Default, Open ; Make "Open" a bold font to indicate that double-click does the
same thing.

; Display the window and return. The OS will notify the script whenever the user
; performs an eligible action:
Gui, Show
return

GUI, MsgBox, InputBox & Other Dialogs
269

ButtonLoadFolder:
Gui +OwnDialogs ; Forces user to dismiss the following dialog before using main window.
FileSelectFolder, Folder,, 3, Select a folder to read:
if not Folder ; The user canceled the dialog.
return

; Check if the last character of the folder name is a backslash, which happens for root
; directories such as C:\. If it is, remove it to prevent a double-backslash later on.
StringRight, LastChar, Folder, 1
if LastChar = \
StringTrimRight, Folder, Folder, 1 ; Remove the trailing backslash.

; Ensure the variable has enough capacity to hold the longest file path. This is done
; because ExtractAssociatedIconA() needs to be able to store a new filename in it.
VarSetCapacity(Filename, 260)
sfi_size = 352
VarSetCapacity(sfi, sfi_size)

; Gather a list of file names from the selected folder and append them to the ListView:
GuiControl, -Redraw, MyListView ; Improve performance by disabling redrawing during load.
Loop %Folder%\*.*
{
FileName := A_LoopFileFullPath ; Must save it to a writable variable for use below.

; Build a unique extension ID to avoid characters that are illegal in variable names,
; such as dashes. This unique ID method also performs better because finding an item
; in the array does not require search-loop.
SplitPath, FileName,,, FileExt ; Get the file's extension.
if FileExt in EXE,ICO,ANI,CUR
{
ExtID := FileExt ; Special ID as a placeholder.
IconNumber = 0 ; Flag it as not found so that these types can each have a unique icon.
}
else ; Some other extension/file-type, so calculate its unique ID.
{
ExtID = 0 ; Initialize to handle extensions that are shorter than others.
Loop 7 ; Limit the extension to 7 characters so that it fits in a 64-bit value.
Printed Documentation
270
{
StringMid, ExtChar, FileExt, A_Index, 1
if not ExtChar ; No more characters.
break
; Derive a Unique ID by assigning a different bit position to each character:
ExtID := ExtID | (Asc(ExtChar) << (8 * (A_Index - 1)))
}
; Check if this file extension already has an icon in the ImageLists. If it does,
; several calls can be avoided and loading performance is greatly improved,
; especially for a folder containing hundreds of files:
IconNumber := IconArray%ExtID%
}
if not IconNumber ; There is not yet any icon for this extension, so load it.
{
; Get the high-quality small-icon associated with this file extension:
if not DllCall("Shell32\SHGetFileInfoA", "str", FileName, "uint", 0, "str", sfi, "uint", sfi_size,
"uint", 0x101) ; 0x101 is SHGFI_ICON+SHGFI_SMALLICON
IconNumber = 9999999 ; Set it out of bounds to display a blank icon.
else ; Icon successfully loaded.
{
; Extract the hIcon member from the structure:
hIcon = 0
Loop 4
hIcon += *(&sfi + A_Index-1) << 8*(A_Index-1)
; Add the HICON directly to the small-icon and large-icon lists.
; Below uses +1 to convert the returned index from zero-based to one-based:
IconNumber := DllCall("ImageList_ReplaceIcon", "uint", ImageListID1, "int", -1, "uint", hIcon)
+ 1
DllCall("ImageList_ReplaceIcon", "uint", ImageListID2, "int", -1, "uint", hIcon)
; Now that it's been copied into the ImageLists, the original should be destroyed:
DllCall("DestroyIcon", "uint", hIcon)
; Cache the icon to save memory and improve loading performance:
IconArray%ExtID% := IconNumber
}
}

; Create the new row in the ListView and assign it the icon number determined above:
LV_Add("Icon" . IconNumber, A_LoopFileName, A_LoopFileDir, A_LoopFileSizeKB, FileExt)
}
GUI, MsgBox, InputBox & Other Dialogs
271
GuiControl, +Redraw, MyListView ; Re-enable redrawing (it was disabled above).
LV_ModifyCol() ; Auto-size each column to fit its contents.
LV_ModifyCol(3, 60) ; Make the Size column at little wider to reveal its header.
return


ButtonClear:
LV_Delete() ; Clear the ListView, but keep icon cache intact for simplicity.
return

ButtonSwitchView:
if not IconView
GuiControl, +Icon, MyListView ; Switch to icon view.
else
GuiControl, +Report, MyListView ; Switch back to details view.
IconView := not IconView ; Invert in preparation for next time.
return

MyListView:
if A_GuiEvent = DoubleClick ; There are many other possible values the script can check.
{
LV_GetText(FileName, A_EventInfo, 1) ; Get the text of the first field.
LV_GetText(FileDir, A_EventInfo, 2) ; Get the text of the second field.
Run %FileDir%\%FileName%,, UseErrorLevel
if ErrorLevel
MsgBox Could not open "%FileDir%\%FileName%".
}
return

GuiContextMenu: ; Launched in response to a right-click or press of the Apps key.
if A_GuiControl <> MyListView ; Display the menu only for clicks inside the ListView.
return
; Show the menu at the provided coordinates, A_GuiX and A_GuiY. These should be used
; because they provide correct coordinates even if the user pressed the Apps key:
Menu, MyContextMenu, Show, %A_GuiX%, %A_GuiY%
return

ContextOpenFile: ; The user selected "Open" in the context menu.
Printed Documentation
272
ContextProperties: ; The user selected "Properties" in the context menu.
; For simplicitly, operate upon only the focused row rather than all selected rows:
FocusedRowNumber := LV_GetNext(0, "F") ; Find the focused row.
if not FocusedRowNumber ; No row is focused.
return
LV_GetText(FileName, FocusedRowNumber, 1) ; Get the text of the first field.
LV_GetText(FileDir, FocusedRowNumber, 2) ; Get the text of the second field.
IfInString A_ThisMenuItem, Open ; User selected "Open" from the context menu.
Run %FileDir%\%FileName%,, UseErrorLevel
else ; User selected "Properties" from the context menu.
Run Properties "%FileDir%\%FileName%",, UseErrorLevel
if ErrorLevel
MsgBox Could not perform requested action on "%FileDir%\%FileName%".
return

ContextClearRows: ; The user selected "Clear" in the context menu.
RowNumber = 0 ; This causes the first iteration to start the search at the top.
Loop
{
; Since deleting a row reduces the RowNumber of all other rows beneath it,
; subtract 1 so that the search includes the same row number that was previously
; found (in case adjacent rows are selected):
RowNumber := LV_GetNext(RowNumber - 1)
if not RowNumber ; The above returned zero, so there are no more selected rows.
break
LV_Delete(RowNumber) ; Clear the row from the ListView.
}
return

GuiSize: ; Expand or shrink the ListView in response to the user's resizing of the window.
if A_EventInfo = 1 ; The window has been minimized. No action needed.
return
; Otherwise, the window has been resized or maximized. Resize the ListView to match.
GuiControl, Move, MyListView, % "W" . (A_GuiWidth - 20) . " H" . (A_GuiHeight - 40)
return

GuiClose: ; When the window is closed, exit the script automatically:
ExitApp
GUI, MsgBox, InputBox & Other Dialogs
273
TreeView [v1.0.44+]
Table of Contents
Introduction and Simple Example
Options and Styles
Built-in Functions: 1) Add/modify/delete items; 2) Getting data out of a TreeView
G-Label Notifications
Remarks
Longer Example
Introduction and Simple Example
A Tree-View displays a hierarchy of items by indenting child items beneath their parents. The most
common example is Explorer's tree of drives and folders.
The syntax for creating a TreeView is:
Gui, Add, TreeView, Options
Here is a working script that creates and displays a simple hierarchy of items:
Gui, Add, TreeView
P1 := TV_Add("First parent")
P1C1 := TV_Add("Parent 1's first child", P1) ; Specify P1 to be this item's parent.
P2 := TV_Add("Second parent")
P2C1 := TV_Add("Parent 2's first child", P2)
P2C2 := TV_Add("Parent 2's second child", P2)
P2C2C1 := TV_Add("Child 2's first child", P2C2)

Gui, Show ; Show the window and its TreeView.
return

GuiClose: ; Exit the script when the user closes the TreeView's GUI window.
ExitApp
Options and Styles for "Gui, Add, TreeView, Options"
AltSubmit: Notifies the script for more types of TreeView events than normal. In other words, the g-
label is launched more often. See TreeView Notifications for details.
Background: Specify the word Background followed immediately by a color name (see color chart) or
RGB value (the 0x prefix is optional). Examples: BackgroundSilver, BackgroundFFDD99. If this option
is not present, the TreeView initially defaults to the background color set by the last parameter of Gui
Color (or if none, the system's default background color). Specifying BackgroundDefault applies the
system's default background color (usually white). For example, a TreeView can be restored to the
default color via GuiControl, +BackgroundDefault, MyTreeView.
Buttons: Specify -Buttons (minus Buttons) to avoid displaying a plus or minus button to the left of
each item that has children.
C: Text color. Specify the letter C followed immediately by a color name (see color chart) or RGB
value (the 0x prefix is optional). Examples: cRed, cFF2211, c0xFF2211, cDefault
Printed Documentation
274
Checked: Provides a checkbox at the left side of each item. When adding an item, specify the word
Check in its options to have the box to start off checked instead of unchecked. The user may either
click the checkbox or press the spacebar to check or uncheck an item. To discover which items in a
TreeView are currently checked, call TV_GetNext() or TV_Get().
HScroll: Specify -HScroll (minus HScroll) to disable horizontal scrolling in the control (in addition, the
control will not display any horizontal scroll bar). On operating systems older than Windows 2000/Me,
this option has no effect unless the system has Comctl32.dll 5.8 or greater (distributed with
applications such as Internet Explorer 5 or later).
ImageList: This is the means by which icons are added to a TreeView. Specify the word ImageList
followed immediately by the ImageListID returned from a previous call to IL_Create(). This option has
an effect only when creating a TreeView. Here is a working example:
ImageListID := IL_Create(10) ; Create an ImageList with initial capacity for 10 icons.
Loop 10 ; Load the ImageList with some standard system icons.
IL_Add(ImageListID, "shell32.dll", A_Index) ; Omits the DLL's path so that it works on
Windows 9x too.
Gui, Add, TreeView, ImageList%ImageListID%
TV_Add("Name of Item", 0, "Icon4") ; Add an item to the TreeView and give it a folder icon.
Gui Show
Lines: Specify -Lines (minus Lines) to avoid displaying a network of lines connecting parent items to
their children. However, removing these lines also prevents the plus/minus buttons from being shown
for top-level items.
ReadOnly: Specify -ReadOnly (minus ReadOnly) to allow editing of the text/name of each item. To
edit an item, select it then press the F2 key. Alternatively, you can click an item once to select it, wait
at least half a second, then click the same item again to edit it. After being edited, an item can be
alphabetically repositioned among its siblings via the following example:
Gui, Add, TreeView, -ReadOnly gMyTree
; ...
MyTree:
if (A_GuiEvent == "e") ; The user has finished editing an item (use == for case sensitive
comparison).
TV_Modify(TV_GetParent(A_EventInfo), "Sort") ; This works even if the item has no
parent.
return
R: Rows of height (upon creation). Specify the letter R followed immediately by the number of rows
for which to make room inside the control. For example, R10 would make the control 10 items tall.
WantF2: Specify -WantF2 (minus WantF2) to prevent an F2 keystroke from editing the currently
selected item. This setting is ignored unless -ReadOnly is also in effect. Regardless of this setting, the
g-label still receives F2 notifications.
(Unnamed numeric styles): Since styles other than the above are rarely used, they do not have
names. See the TreeView styles table for a list.
Built-in Functions for TreeViews
All of the TreeView functions operate upon the current thread's default GUI window (which can be
changed via Gui, 2:Default). If the default window does not exist or has no TreeView controls, all
functions return zero to indicate the problem.
If the window has more than one TreeView control, by default the functions operate upon the one
most recently added. To change this, specify Gui, TreeView, TreeViewName, where TreeViewName is
GUI, MsgBox, InputBox & Other Dialogs
275
the name of the TreeView's associated variable or its ClassNN as shown by Window Spy. Once
changed, all existing and future threads will use the indicated TreeView for subsequent operations.
Add, Modify, and Delete Items
TV_Add(Name, [ParentItemID, Options]): Adds a new item to the TreeView and returns its
unique Item ID number (or 0 upon failure). Name is the displayed text of the item, which can be text
or numeric (including numeric expression results). ParentItemID is the ID number of the new item's
parent (omit it or specify 0 to add the item at the top level). When adding a large number of items,
performance can be improved by using GuiControl, -Redraw, MyTreeView before adding the items, and
GuiControl, +Redraw, MyTreeView afterward.
Options for TV_Add() and TV_Modify(): The Options parameter is a string containing zero or more of
the following words (not case sensitive). Separate each word from the next with a space or tab. To
remove an option, precede it with a minus sign. To add an option, a plus sign is permitted but not
required.
Bold: Displays the item's name in a bold font. To later un-bold the item, use TV_Modify(ItemID, "-
Bold").
Check: Shows a checkmark to the left of the item (if the TreeView has checkboxes). To later uncheck
it, use TV_Modify(ItemID, "-Check"). The word Check may optionally be followed immediately by a 0
or 1 to indicate the starting state. In other words, both "Check" and "Check" . VarContainingOne are
the same (the period used here is the concatenation operator).
Expand: Expands the item to reveal its children (if any). To later collapse the item, use
TV_Modify(ItemID, "-Expand"). If there are no children, TV_Modify() returns 0 instead of the item's
ID. By contrast, TV_Add() marks the item as expanded in case children are added to it later. Unlike
"Select" (below), expanding an item does not automatically expand its parent. Finally, the word
Expand may optionally be followed immediately by a 0 or 1 to indicate the starting state. In other
words, both "Expand" and "Expand" . VarContainingOne are the same.
First | Sort | N: These options apply only to TV_Add(). They specify the new item's position relative to
its siblings (a sibling is any other item on the same level). If none of these options is present, the new
item is added as the last/bottom sibling. Otherwise, specify First to add the item as the first/top
sibling, or specify Sort to insert it among its siblings in alphabetical order. If a plain integer (N) is
specified, it is assumed to be ID number of the sibling after which to insert the new item (if integer N
is the only option present, it does not have to be enclosed in quotes).
Icon: Specify the word Icon followed immediately by the number of this item's icon, which is displayed
to the left of the item's name. If this option is absent, the first icon in the ImageList is used. To
display a blank icon, specify a number that is larger than the number of icons in the ImageList. If the
control lacks an ImageList, no icon is displayed nor is any space reserved for one.
Select: Selects the item. Since only one item at a time can be selected, any previously selected item is
automatically de-selected. In addition, this option reveals the newly selected item by expanding its
parent(s), if necessary. To find out the current selection, call TV_GetSelection().
Sort: For TV_Modify(), this option alphabetically sorts the children of the specified item. To instead
sort all top-level items, use TV_Modify(0, "Sort"). If there are no children, 0 is returned instead of the
ID of the modified item.
Vis: Ensures that the item is completely visible by scrolling the TreeView and/or expanding its parent,
if necessary.
VisFirst: Same as above except that the TreeView is also scrolled so that the item appears at the top,
if possible. This option is typically more effective when used with TV_Modify() than with TV_Add().

TV_Modify(ItemID [, Options, NewName]): Modifies the attributes and/or name of an item. It
returns the item's own ID upon success or 0 upon failure (or partial failure). When only the first
parameter is present, the specified item is selected. When NewName is omitted, the current name is
left unchanged. For Options, see the list above.
Printed Documentation
276
TV_Delete([ItemID]): If ItemID is omitted, all items in the TreeView are deleted. Otherwise, only
the specified ItemID is deleted. It returns 1 upon success and 0 upon failure.
Getting Data Out of a TreeView
TV_GetSelection(): Returns the selected item's ID number.
TV_GetCount(): Returns the total number of items in the control. This function is always
instantaneous because the control keeps track of the count.
TV_GetParent(ItemID): Returns the specified item's parent as an item ID. Items at the top level
have no parent and thus return 0.
TV_GetChild(ParentItemID): Returns the ID number of the specified item's first/top child (or 0 if
none).
TV_GetPrev(ItemID): Returns the ID number of the sibling above the specified item (or 0 if none).
TV_GetNext([ItemID, "Checked | Full"]): This has the following modes:
1. When all parameters are omitted, it returns the ID number of the first/top item in the
TreeView (or 0 if none).
2. When the only first parameter (ItemID) is present, it returns the ID number of the sibling
below the specified item (or 0 if none). If the first parameter is 0, it returns the ID number of
the first/top item in the TreeView (or 0 if none).
3. When the second parameter is "Full" or "F", the next item is retrieved regardless of its
relationship to the specified item. This allows the script to easily traverse the entire tree, item
by item. For example:
ItemID = 0 ; Causes the loop's first iteration to start the search at the top of
the tree.
Loop
{
ItemID := TV_GetNext(ItemID, "Full") ; Replace "Full" with "Checked" to
find all checkmarked items.
if not ItemID ; No more items in tree.
break
TV_GetText(ItemText, ItemID)
MsgBox The next Item is %ItemID%, whose text is "%ItemText%".
}
4. When the second parameter is either "Check", "Checked", or "C", the same behavior as above
is used except that any item without a checkmark is skipped over. This allows all checkmarked
items in the TreeView to be retrieved, one by one.
TV_GetText(OutputVar, ItemID): Retrieves the text/name of the specified ItemID and stores it in
OutputVar. If the text is longer than 8191, only the first 8191 characters are retrieved. Upon success,
the function returns the item's own ID. Upon failure, it returns 0 (and OutputVar is also made blank).
TV_Get(ItemID, "Expand | Check | Bold"): If the specified item has the specified attribute, its
own ItemID is returned. Otherwise, 0 is returned. For the second parameter, specify "E", "Expand", or
"Expanded" to determine if the item is currently expanded (that is, its children are being displayed);
specify "C", "Check", or "Checked" to determine if the item has a checkmark; or specify "B" or "Bold"
to determine if the item is currently bold in font.
Tip: Since an IF-statement sees any non-zero value as "true", the following two lines are functionally
identical:
1. if TV_Get(ItemID, "Check") = ItemID
GUI, MsgBox, InputBox & Other Dialogs
277
2. if TV_Get(ItemID, "Check")
G-Label Notifications (Primary)
A g-label such as gMySubroutine may be listed in the control's options. This would cause the
MySubroutine label to be launched automatically whenever the user performs an action in the control.
This subroutine may consult the built-in variables A_Gui and A_GuiControl. More importantly, it may
consult A_GuiEvent, which contains one of the following strings or letters (for compatibility with
future versions, a script should not assume these are the only possible values):
DoubleClick: The user has double-clicked an item. The variable A_EventInfo contains the item ID.
D: The user has attempted to start dragging an item (there is currently no built-in support for this).
The variable A_EventInfo contains the item ID.
d (lowercase D): Same as above except a right-click-drag rather than a left-drag.
e (lowercase E): The user has finished editing an item (the user may edit items only when the
TreeView has -ReadOnly in its options). The variable A_EventInfo contains the item ID.
S: A new item has been selected, either by the user or the script itself. The variable A_EventInfo
contains the newly selected item ID.
G-Label Notifications (Secondary)
If the TreeView has the word AltSubmit in its options, its g-label is launched more often and
A_GuiEvent may contain the following additional values:
Normal: The user has left-clicked an item. The variable A_EventInfo contains the item ID.
RightClick: The user has right-clicked an item. The variable A_EventInfo contains the item ID. In
most cases, it is best not to display a menu in response to this. Instead, use the GuiContextMenu label
because it also recognizes the Apps key. For example:
GuiContextMenu: ; Launched in response to a right-click or press of the Apps key.
if A_GuiControl <> MyTreeView ; This check is optional. It displays the menu only for clicks
inside the TreeView.
return
; Show the menu at the provided coordinates, A_GuiX and A_GuiY. These should be used
; because they provide correct coordinates even if the user pressed the Apps key:
Menu, MyContextMenu, Show, %A_GuiX%, %A_GuiY%
return
E: The user has begun editing an item (the user may edit items only when the TreeView has -
ReadOnly in its options). The variable A_EventInfo contains the item ID.
F: The TreeView has received keyboard focus.
f (lowercase F): The TreeView has lost keyboard focus.
K: The user has pressed a key while the TreeView has focus. A_EventInfo contains the virtual key
code of the key, which is a number between 1 and 255. If the key is alphabetic, on most keyboard
layouts it can be translated to the corresponding character via Chr(A_EventInfo). F2 keystrokes are
received regardless of WantF2. However, the Enter keystroke is not received; to receive it, use a
default button as described below.
+ (plus sign): An item has been expanded to reveal its children. The variable A_EventInfo contains
the item ID.
- (minus sign): An item has been collapsed to hide its children. The variable A_EventInfo contains the
item ID.
Printed Documentation
278
Remarks
The Gui Submit command has no effect on a TreeView control. Therefore, the script may use the
TreeView's associated variable (if any) to store other data without concern that it will ever be
overwritten.
To detect when the user has pressed Enter while a TreeView has focus, use a default button (which
can be hidden if desired). For example:
Gui, Add, Button, Hidden Default, OK
...
ButtonOK:
GuiControlGet, FocusedControl, FocusV
if FocusedControl <> MyTreeView
return
MsgBox % "Enter was pressed. The selected item ID is " . TV_GetSelection()
return
In addition to navigating from item to item with the keyboard, the user may also perform incremental
search by typing the first few characters of an item's name. This causes the selection to jump to the
nearest matching item.
Although any length of text can be stored in each item of a TreeView, only the first 260 characters are
displayed.
Although the theoretical maximum number of items in a TreeView is 65536, item-adding performance
will noticeably decrease long before then. This can be alleviated somewhat by using the redraw tip
described in TV_Add().
Unlike ListViews, a TreeView's ImageList is not automatically destroyed when the TreeView is
destroyed. Therefore, a script should call IL_Destroy(ImageListID) after destroying a TreeView's
window if the ImageList will not be used for anything else. However, this is not necessary if the script
will soon be exiting because all ImageLists are automatically destroyed at that time. On a related
note, a TreeView's original ImageList can be replaced with a new one via the following example:
Gui +LastFound
SendMessage, 0x1109, 0, NewImageListID, SysTreeView321 ; 0x1109 is TVM_SETIMAGELIST
if ErrorLevel ; The TreeView had a previous ImageList.
IL_Destroy(ErrorLevel) ; Destroying it is the most typical action.
A script may create more than one TreeView per window. To operate upon a TreeView other than the
default one, see built-in functions.
Windows 95 and NT4: If the system lacks version 4.70 or later of Comctl32.dll, Shell32.dll, and
Shlwapi.dll -- which are distributed with various updates and applications such as Internet Explorer
3.0 or later -- TreeViews are more limited and some features might not behave as expected.
To perform actions such as resizing, hiding, or changing the font of a TreeView, use GuiControl.
Related
ListView, Other Control Types, Gui, GuiContextMenu, GuiControl, GuiControlGet, TreeView styles table
Example
; The following is a working script that is more elaborate than the one near the top of this page.
; It creates and displays a TreeView containing all folders in the all-users Start Menu. When the
GUI, MsgBox, InputBox & Other Dialogs
279
; user selects a folder, its contents are shown in a ListView to the right (like Windows Explorer).
; In addition, a StatusBar control shows information about the currently selected folder.

; The following folder will be the root folder for the TreeView. Note that loading might take a long
; time if an entire drive such as C:\ is specified:
TreeRoot = %A_StartMenuCommon%
TreeViewWidth := 280
ListViewWidth := A_ScreenWidth - TreeViewWidth - 30

; Allow the user to maximize or drag-resize the window:
Gui +Resize

; Create an ImageList and put some standard system icons into it:
ImageListID := IL_Create(5)
Loop 5 ; Below omits the DLL's path so that it works on Windows 9x too:
IL_Add(ImageListID, "shell32.dll", A_Index)

; Create a TreeView and a ListView side-by-side to behave like Windows Explorer:
Gui, Add, TreeView, vMyTree r20 w%TreeViewWidth% gMyTree ImageList%ImageListID%
Gui, Add, ListView, vMyList r20 w%ListViewWidth% x+10, Name|Modified

; Set the ListView's column widths (this is optional):
Col2Width = 70 ; Narrow to reveal only the YYYYMMDD part.
LV_ModifyCol(1, ListViewWidth - Col2Width - 30) ; Allows room for vertical scrollbar.
LV_ModifyCol(2, Col2Width)

; Create a Status Bar to give info about the number of files and their total size:
Gui, Add, StatusBar
SB_SetParts(60, 85) ; Create three parts in the bar (the third part fills all the remaining width).

; Add folders and their subfolders to the tree. Display the status in case loading takes a long time:
SplashTextOn, 200, 25, TreeView and StatusBar Example, Loading the tree...
AddSubFoldersToTree(TreeRoot)
SplashTextOff

; Display the window and return. The OS will notify the script whenever the user performs an eligible
action:
Gui, Show,, %TreeRoot% ; Display the source directory (TreeRoot) in the title bar.
Printed Documentation
280
return

AddSubFoldersToTree(Folder, ParentItemID = 0)
{
; This function adds to the TreeView all subfolders in the specified folder.
; It also calls itself recursively to gather nested folders to any depth.
Loop %Folder%\*.*, 2 ; Retrieve all of Folder's sub-folders.
AddSubFoldersToTree(A_LoopFileFullPath, TV_Add(A_LoopFileName, ParentItemID, "Icon4"))
}

MyTree:
if A_GuiEvent <> S ; i.e. an event other than "select new tree item".
return ; Do nothing.
; Otherwise, populate the ListView with the contents of the selected folder.
; First determine the full path of the selected folder:
TV_GetText(SelectedItemText, A_EventInfo)
ParentID := A_EventInfo
Loop ; Build the full path to the selected folder.
{
ParentID := TV_GetParent(ParentID)
if not ParentID ; No more ancestors.
break
TV_GetText(ParentText, ParentID)
SelectedItemText = %ParentText%\%SelectedItemText%
}
SelectedFullPath = %TreeRoot%\%SelectedItemText%

; Put the files into the ListView:
LV_Delete() ; Clear all rows.
GuiControl, -Redraw, MyListView ; Improve performance by disabling redrawing during load.
FileCount = 0 ; Init prior to loop below.
TotalSize = 0
Loop %SelectedFullPath%\*.* ; For simplicity, this omits folders so that only files are shown in the
ListView.
{
LV_Add("", A_LoopFileName, A_LoopFileTimeModified)
FileCount += 1
TotalSize += A_LoopFileSize
GUI, MsgBox, InputBox & Other Dialogs
281
}
GuiControl, +Redraw, MyListView

; Update the three parts of the status bar to show info about the currently selected folder:
SB_SetText(FileCount . " files", 1)
SB_SetText(Round(TotalSize / 1024, 1) . " KB", 2)
SB_SetText(SelectedFullPath, 3)
return

GuiSize: ; Expand/shrink the ListView and TreeView in response to user's resizing of window.
if A_EventInfo = 1 ; The window has been minimized. No action needed.
return
; Otherwise, the window has been resized or maximized. Resize the controls to match.
GuiControl, Move, MyTree, % "H" . (A_GuiHeight - 30) ; -30 for StatusBar and margins.
GuiControl, Move, MyList, % "H" . (A_GuiHeight - 30) . " W" . (A_GuiWidth - TreeViewWidth - 30)
return

GuiClose: ; Exit the script when the user closes the TreeView's GUI window.
ExitApp
IfMsgBox
Checks which button was pushed by the user during the most recent MsgBox command.
IfMsgBox, ButtonName
Parameters
ButtonName
One of the following strings to represent which button the user pressed in the
most recent MsgBox command:
Yes
No
OK
Cancel
Abort
Ignore
Retry
Continue [v1.0.44.08+]
TryAgain [v1.0.44.08+]
Timeout (that is, the word "timeout" is present if the MsgBox timed out)
Related
MsgBox
Example
MsgBox, 4, , Would you like to continue?, 5 ; 5-second timeout.
Printed Documentation
282
IfMsgBox, No
Return ; User pressed the "No" button.
IfMsgBox, Timeout
Return ; i.e. Assume "No" if it timed out.
; Otherwise, continue:
...
InputBox
Displays an input box to ask the user to enter a string.
InputBox, OutputVar [, Title, Prompt, HIDE, Width, Height, X, Y, Font, Timeout, Default]
Parameters
OutputVar The name of the variable in which to store the text entered by the user.
Title
The title of the input box. If blank or omitted, it defaults to the name of the
script.
Prompt
The text of the input box, which is usually a message to the user indicating what
kind of input is expected. If Prompt is long, it can be broken up into several
shorter lines by means of a continuation section, which might improve readability
and maintainability.
HIDE
If this parameter is the word HIDE, the user's input will be masked, which is
useful for passwords.
Width
If this parameter is blank or omitted, the starting width of the window will be
375. This parameter can be an expression.
Height
If this parameter is blank or omitted, the starting height of the window will be
189. This parameter can be an expression.
X, Y
The X and Y coordinates of the window (use 0,0 to move it to the upper left
corner of the desktop), which can be expressions. If either coordinate is blank or
omitted, the dialog will be centered in that dimension. Either coordinate can be
negative to position the window partially or entirely off the desktop.
Font
Not yet implemented (leave blank). In the future it might accept something like
verdana:8
Timeout
Timeout in seconds (can contain a decimal point or be an expression). If this
value exceeds 2147483 (24.8 days), it will be set to 2147483. After the timeout
has elapsed, the InputBox window will be automatically closed and ErrorLevel will
be set to 2. OutputVar will still be set to what the user entered.
Default
A string that will appear in the InputBox's edit field when the dialog first appears.
The user can change it by backspacing or other means.
ErrorLevel
See below.
Remarks
The dialog allows the user to enter text and then press OK or CANCEL. The user can resize the dialog
window by dragging its borders.
If the user presses the CANCEL button: For AutoIt v2 (.aut) scripts, OutputVar is set to be blank and
ErrorLevel is not changed. For all other script types (e.g. .ahk, .ini) ErrorLevel is set to 1 (or 0 for OK)
GUI, MsgBox, InputBox & Other Dialogs
283
and OutputVar to the value entered. This allows the CANCEL button to perform a function other than
CANCEL should the script designer wish it.
If the dialog times out, ErrorLevel will be set to 2 for all types of scripts, including AutoIt v2 scripts.
For this reason, AutoIt v2 scripts should explicitly set ErrorLevel to 0 prior to using this command with
a timeout.
A GUI window may display a modal InputBox by means of Gui +OwnDialogs. A modal InputBox
prevents the user from interacting with the GUI window until the InputBox is dismissed.
Related
GUI, Input, MsgBox, FileSelectFile, FileSelectFolder, SplashTextOn, ToolTip
Example
InputBox, password, Enter Password, (your input will be hidden), hide
InputBox, UserInput, Phone Number, Please enter a phone number., , 640, 480
if ErrorLevel
MsgBox, CANCEL was pressed.
else
MsgBox, You entered "%UserInput%"
MsgBox
Displays the specified text in a small window containing one or more buttons (such as Yes and No).
MsgBox, Text
MsgBox [, Options, Title, Text, Timeout]
Parameters
Text
If all the parameters are omitted, the MsgBox will display the text "Press OK to
continue." Otherwise, this parameter is the text displayed inside the message
box to instruct the user what to do, or to present information.
Escape sequences can be used to denote special characters. For example, `n
indicates a linefeed character, which ends the current line and begins a new
one. Thus, using text1`n`ntext2 would create a blank line between text1 and
text2.
If Text is long, it can be broken up into several shorter lines by means of a
continuation section, which might improve readability and maintainability.
Options
Indicates the type of message box and the possible button combinations. If
blank or omitted, it defaults to 0. See the table below for allowed values.
This parameter will not be recognized if it contains an expression or a variable
reference such as %option%. Instead, use a literal numeric value.
Title
The title of the message box window. If omitted or blank, it defaults to the
name of the script (without path).
Timeout
(optional) Timeout in seconds (can contain a decimal point but cannot be an
expression). If this value exceeds 2147483 (24.8 days), it will be set to
2147483. After the timeout has elapsed the message box will be automatically
closed and the IfMsgBox command will see the value TIMEOUT.
Printed Documentation
284
Known limitation: If the MsgBox contains only an OK button, IfMsgBox will
think that the OK button was pressed if the MsgBox times out while its own
thread is interrupted by another.
The Options parameter can be a combination (sum) of one or more of the following values.
Function Value
OK (that is, only an OK button is displayed) 0
OK/Cancel 1
Abort/Retry/Ignore 2
Yes/No/Cancel 3
Yes/No 4
Retry/Cancel 5
Cancel/Try Again/Continue (2000/XP+) 6
Adds a Help button (see remarks below) 16384

Icon Hand (stop/error) 16
Icon Question 32
Icon Exclamation 48
Icon Asterisk (info) 64

Makes the 2nd button the default 256
Makes the 3rd button the default 512

System Modal (always on top) 4096
Task Modal 8192
Shows the MsgBox on default desktop
(Windows NT/2000/XP or later)
131072
Always-on-top (style WS_EX_TOPMOST)
(like System Modal but omits title bar icon)
262144

Make the text right-justified 524288
Right-to-left reading order for Hebrew/Arabic 1048576

Remarks
The table above is used by adding up the values you wish to be present in the MsgBox. For example,
to specify a SYSTEMMODAL box with the YES/NO buttons the Options value would be 4096+4 (4100).
MsgBox has smart comma handling, so it is usually not necessary to escape commas in the Text
parameter.
To determine which button the user pressed in the most recent MsgBox, use the IfMsgBox command.
For example:
MsgBox, 4,, Would you like to continue? (press Yes or No)
IfMsgBox Yes
MsgBox You pressed Yes.
GUI, MsgBox, InputBox & Other Dialogs
285

else
MsgBox You pressed No.
The names of the buttons can be customized by following this example.
Tip: Pressing Control-C while a MsgBox window is active will copy its text to the clipboard. This applies
to all MsgBoxes, not just those produced by AutoHotkey.
Using MsgBox with GUI windows: A GUI window may display a modal MsgBox by means of Gui
+OwnDialogs. A modal MsgBox prevents the user from interacting with the GUI window until the
MsgBox is dismissed. Note: In this case, it is not necessary to specify the System Modal or Task Modal
options from the table above.
When Gui +OwnDialogs is not in effect, the Task Modal option (8192) can be used to disable all the
script's windows until the user dismisses the MsgBox.
The Help button: When the Help button option (83) is present in Options, pressing the Help button
will have no effect unless both of the following are true:
1. The MsgBox is owned by a GUI window by means of Gui +OwnDialogs.
2. The script is monitoring the WM_HELP message (0x53). For example: OnMessage(0x53,
"WM_HELP"). When the WM_HELP() function is called, it may guide the user by means such as
showing another window or MsgBox.
The Close button (in MsgBox's title bar): Since the MsgBox window is a built-in feature of the
operating system, its X button (close) in the title bar is enabled only when certain buttons are present.
If there is only an OK button, clicking the X button is the same as pressing OK. Otherwise, the X
button is disabled unless there is a Cancel button, in which case clicking the X is the same as pressing
Cancel.
Related
IfMsgBox, InputBox, FileSelectFile, FileSelectFolder, ToolTip, GUI
Example
MsgBox This is the 1-parameter method. Commas (,) do not need to be escaped.
MsgBox, 4, , This is the 3-parameter method. Commas (,) do not need to be escaped.
MsgBox, 4, , Do you want to continue? (Press YES or NO)
IfMsgBox No
return
MsgBox, 4, , 4-parameter method: this MsgBox will time out in 5 seconds. Continue?, 5
IfMsgBox Timeout
MsgBox You didn't press YES or NO within the 5-second period.
else IfMsgBox No
return

; By preceding any parameter with "% ", it becomes an expression. In the following example,
; math is performed, an array element is accessed, and a function is called. All of these
; items are concatenated via the "." operator to form a single string displayed by MsgBox:
MsgBox % "New width for object #" . A_Index . " is: " . RestrictWidth(ObjectWidth%A_Index% *
ScalingFactor)
Printed Documentation
286

; The following example alerts the user that a MsgBox is going to steal focus (in case the user is
typing).
SplashTextOn,,, A MsgBox is about to appear.
Sleep 3000
SplashTextOff
MsgBox The backup process has completed.
Progress / SplashImage
Creates or updates a window containing a progress bar or an image.
SplashImage, Off
SplashImage [, ImageFile, Options, SubText, MainText, WinTitle, FontName]

Progress, Off
Progress, ProgressParam1 [, SubText, MainText, WinTitle, FontName]
Parameters
ImageFile
If this is the word OFF, the window is destroyed. If this is the word SHOW,
the window is shown if it is currently hidden.
Otherwise, this is the file name of the BMP, GIF, or JPG image to display (to
display other file formats such as PNG, TIF, and ICO, consider using the Gui
command to create a window containing a picture control).
ImageFile is assumed to be in %A_WorkingDir% if an absolute path isn't
specified. If ImageFile and Options are blank and the window already
exists, its image will be unchanged but its text will be updated to reflect
any new strings provided in SubText, MainText, and WinTitle.
For newly created windows, if ImageFile is blank or there is a problem
loading the image, the window will be displayed without the picture.
ProgressParam1
If the progress window already exists: If Param1 is the word OFF, the
window is destroyed. If Param1 is the word SHOW, the window is shown if
it is currently hidden.
Otherwise, if Param1 is an pure number, its bar's position is changed to
that value. If Param1 is blank, its bar position will be unchanged but its text
will be updated to reflect any new strings provided in SubText, MainText,
and WinTitle. In both of these modes, if the window doesn't yet exist, it will
be created with the defaults for all options.
If the progress window does not exist: A new progress window is created
(replacing any old one), and Param1 is a string of zero or more options
from the list below.
Options A string of zero or more options from the list below.
SubText
The text to display below the image or bar indicator. Although word-
wrapping will occur, to begin a new line explicitly, use linefeed (`n). To set
an existing window's text to be blank, specify %A_Space%. For the purpose
of auto-calculating the window's height, blank lines can be reserved in a
way similar to MainText below.
MainText
The text to display above the image or bar indicator (its font is semi-bold).
GUI, MsgBox, InputBox & Other Dialogs
287
Although word-wrapping will occur, to begin a new line explicitly, use
linefeed (`n).
If blank or omitted, no space will be reserved in the window for MainText.
To reserve space for single line to be added later, or to set an existing
window's text to be blank, specify %A_Space%. To reserve extra lines
beyond the first, append one or more linefeeds (`n).
Once the height of MainText's control area has been set, it cannot be
changed without recreating the window.
WinTitle
The title of the window. If omitted and the window is being newly created,
the title defaults to the name of the script (without path). If the B
(borderless) option has been specified, there will be no visible title bar but
the window can still be referred to by this title in commands such as
WinMove.
FontName
The name of the font to use for both MainText and SubText. The font table
lists the fonts included with the various versions of Windows. If unspecified
or if the font cannot be found, the system's default GUI font will be used.
See the options section below for how to change the size, weight, and color
of the font.
Window Size, Position, and Behavior
A: The window will not be always-on-top.
B: Borderless: The window will have no border and no title bar. To have a border but no title bar, use
B1 for a thin border or B2 for a dialog style border.
M: The window will be movable by the user (except if borderless). To additionally make the window
resizable (by means of dragging its borders), specify M1. To additionally include a system menu and a
set of minimize/maximize/close buttons in the title bar, specify M2.
Pn: For Progress windows, specify for n the starting position of the bar (the default is 0 or the number
in the allowable range that is closest to 0). To later change the position of the bar, follow this
example: Progress, 50
Rx-y: For Progress windows, specify for x-y the numerical range of the bar (if the R option is not
present, the default is 0-100). For example, R0-1000 would allow a numbers between 0 and 1000; R-
50-50 would allow numbers between -50 and 50; and R-10--5 would allow numbers between -10 and
-5. On Windows 95 and NT4, negative ranges and ranges beyond 65535 will not behave correctly
unless Internet Explorer 3.0 or later is installed.
T: The window will be given a button in the task bar and it will be unowned. Normally, there is no
button because the window is owned by the script's main window. This setting also prevents a GUI
window's Gui +OwnDialogs setting from taking ownership of a Splash or Progress window.
Hn: Specify for n the height of the window's client area (which is the area not including title bar and
borders). If unspecified, the height will be calculated automatically based on the height of the
image/bar and text in the window.
Wn: Specify for n the width of the window's client area. If unspecified, the width will be calculated
automatically for SplashImage (if there is an image). Otherwise, it will default to 300.
Xn: Specify for n the x-coordinate of the window's upper left corner. If unspecified, the window will be
horizontally centered on the screen.
Yn: Specify for n the y-coordinate of the window's upper left corner. If unspecified, the window will be
vertically centered on the screen.
Hide: The window will be initially hidden. Use Progress Show or SplashImage Show to show it later.
Printed Documentation
288
Layout of Objects in the Window
Cxy: Centered: If this option is absent, both SubText and MainText will be centered inside the
window. Specify 0 for x to make SubText left-justified. Specify a 1 to keep it centered. The same is
true for y except that it applies to MainText (y can be omitted). For example: c10
ZHn: Height of object: For Progress windows, specify for n the thickness of the progress bar (default
20). For SplashImage windows, specify for n the height to which to scale image. Specify -1 to make
the height proportional to the width specified in ZWn (i.e. "keep aspect ratio"). If unspecified, the
actual image height will be used. In either case, a value of 0 can be specified to omit the object
entirely, which allows the window to be used to display only text in custom fonts, sizes, and colors.
ZWn: Width of object (for SplashImage windows only): Specify for n the width to which to scale the
image. Specify -1 to make the width proportional to the height specified in ZHn (i.e. "keep aspect
ratio"). If unspecified, the actual image width will be used.
ZXn: Specify for n the amount of margin space to leave on the left/right sides of the window. The
default is 10 except for SplashImage windows with no text, which have a default of 0.
ZYn: Specify for n the amount of vertical blank space to leave at the top and bottom of the window
and between each control. The default is 5 except for SplashImage windows with no text, which have
a default of 0.
Note: To create a vertical progress bar or to have more layout flexibility, use the Gui command such
as this example:
Gui, Add, Progress, Vertical vMyProgress
Gui, Show
return
; ... later...
GuiControl,, MyProgress, +10 ; Move the bar upward by 10 percent. Omit the + to set an
absolute position.
Font Size and Weight
FMn: Specify for n the font size for MainText. Default 0, which causes 10 to be used on most systems.
This default is not affected by the system's selected font size in Control Panel > Display settings.
FSn: Specify for n the font size for SubText. Default 0, which causes 8 to be used on most systems.
WMn: Specify for n the font weight of MainText. The weight should be between 1 and 1000. If
unspecified, 600 (semi-bold) will be used.
WSn: Specify for n the font weight of SubText. The weight should be between 1 and 1000 (700 is
traditionally considered to be "bold"). If unspecified, 400 (normal) will be used.
Object Colors
A color can be one of the names from the list below or a 6-digit hexadecimal RGB value. For example,
specifying cw1A00FF would set a window background color with red component 1A, green component
00, and blue component FF.
Add a space after each color option if there are any more options that follow it. For example: cbRed
ct900000 cwBlue
CBn: Color of progress bar: Specify for n one of the 16 primary HTML color names or a 6-digit RGB
color value. If unspecified, the system's default bar color will be used. Specify the word Default to
return to the system's default progress bar color.
CTn: Color of text: Specify for n one of the 16 primary HTML color names or a 6-digit RGB color
value. If unspecified, the system's default text color (usually black) will be used. Specify the word
Default to return to the system's default text color.
GUI, MsgBox, InputBox & Other Dialogs
289
CWn: Color of window (background): Specify for n one of the 16 primary HTML color names or a 6-
digit RGB color value. If unspecified, the system's color for the face of buttons will be used (specify
the word Default to later return to this color). To make the background transparent on Windows
2000/XP and beyond, use WinSet TransColor.
Color names and RGB values

Black = 000000

Green = 008000

Silver = C0C0C0

Lime = 00FF00

Gray = 808080

Olive = 808000

White = FFFFFF

Yellow = FFFF00

Maroon = 800000

Navy = 000080

Red = FF0000

Blue = 0000FF

Purple = 800080

Teal = 008080

Fuchsia = FF00FF

Aqua = 00FFFF
Remarks
If the first parameter is the word OFF, the window is destroyed.
Each script can display up to 10 Progress windows and 10 SplashImage windows. Each window has a
number assigned to it at the time it is created. If unspecified, that number is 1 (the first). Otherwise,
precede the first parameter with the number of the window followed by a colon. For example, the
Progress command with 2:Off would turn off the number-2 Progress window, 2:75 would set its bar to
75%, 2: would change one or more of its text fields, and 2:B would create a new borderless Progress
window. Similarly, the SplashImage command with 2:Off would turn off the number-2 SplashImage
window, 2: would change one or more of its text fields, and 2:C:\My Images\Picture1.jpg would create
a new number-2 SplashImage window.
Upon creation, a window that would be larger than the desktop is automatically shrunk to fit.
A naked progress bar can be displayed by specifying no SubText, no MainText, and including the
following options: b zx0 zy0. A naked image can be displayed the same way except that only the B
option is needed.
On Windows XP or later, if there is a non-Classic theme is in effect, the interior of a progress bar may
appear as a series of segments rather than a smooth continuous bar. To avoid this, specify a bar color
explicitly such as cbBlue.
Use decimal (not hexadecimal) numbers for option letters that need them, except where noted.
Commands such as WinSet and WinMove can be used to change the attributes of an existing window
without having to recreate it.
A GUI window may take ownership of a Progress or Splash window by means of Gui +OwnDialogs.
This causes the Splash or Progress to stay always on top of its owner. In addition, the Progress or
Splash is automatically destroyed when its GUI window is destroyed.
Related
GUI, SplashTextOn, ToolTip
Printed Documentation
290
Examples
Progress, b w200, My SubText, My MainText, My Title
Progress, 50 ; Set the position of the bar to 50%.
Sleep, 4000
Progress, Off

; Create a window just to display some 18-point Courier text:
Progress, m2 b fs18 zh0, This is the Text.`nThis is a 2nd line., , , Courier New

; Create a simple SplashImage window:
SplashImage, C:\My Pictures\Company Logo.gif

; Create a borderless SplashImage window with some large text beneath the image:
SplashImage, C:\My Pictures\Company Logo.gif, b fs18, This is our company logo.
Sleep, 4000
SplashImage, Off

; Here is a working example that demonstrates how a Progress window can be
; overlayed on a SplashImage to make a professional looking Installer screen:
IfExist, C:\WINDOWS\system32\ntimage.gif, SplashImage, %A_WinDir%\system32\ntimage.gif, A,,,
Installation
Loop, %A_WinDir%\system32\*.*
{
Progress, %a_index%, %a_loopfilename%, Installing..., Draft Installtion
Sleep, 50
IfEqual, a_index, 100, break
}
; There is similar example at the bottom of the GUI page. Its advantage is that it uses only a single
; window and it gives you more control over window layout.
Progress / SplashImage
Creates or updates a window containing a progress bar or an image.
SplashImage, Off
SplashImage [, ImageFile, Options, SubText, MainText, WinTitle, FontName]

Progress, Off
Progress, ProgressParam1 [, SubText, MainText, WinTitle, FontName]
Parameters
ImageFile
If this is the word OFF, the window is destroyed. If this is the word SHOW,
GUI, MsgBox, InputBox & Other Dialogs
291
the window is shown if it is currently hidden.
Otherwise, this is the file name of the BMP, GIF, or JPG image to display (to
display other file formats such as PNG, TIF, and ICO, consider using the Gui
command to create a window containing a picture control).
ImageFile is assumed to be in %A_WorkingDir% if an absolute path isn't
specified. If ImageFile and Options are blank and the window already
exists, its image will be unchanged but its text will be updated to reflect
any new strings provided in SubText, MainText, and WinTitle.
For newly created windows, if ImageFile is blank or there is a problem
loading the image, the window will be displayed without the picture.
ProgressParam1
If the progress window already exists: If Param1 is the word OFF, the
window is destroyed. If Param1 is the word SHOW, the window is shown if
it is currently hidden.
Otherwise, if Param1 is an pure number, its bar's position is changed to
that value. If Param1 is blank, its bar position will be unchanged but its text
will be updated to reflect any new strings provided in SubText, MainText,
and WinTitle. In both of these modes, if the window doesn't yet exist, it will
be created with the defaults for all options.
If the progress window does not exist: A new progress window is created
(replacing any old one), and Param1 is a string of zero or more options
from the list below.
Options A string of zero or more options from the list below.
SubText
The text to display below the image or bar indicator. Although word-
wrapping will occur, to begin a new line explicitly, use linefeed (`n). To set
an existing window's text to be blank, specify %A_Space%. For the purpose
of auto-calculating the window's height, blank lines can be reserved in a
way similar to MainText below.
MainText
The text to display above the image or bar indicator (its font is semi-bold).
Although word-wrapping will occur, to begin a new line explicitly, use
linefeed (`n).
If blank or omitted, no space will be reserved in the window for MainText.
To reserve space for single line to be added later, or to set an existing
window's text to be blank, specify %A_Space%. To reserve extra lines
beyond the first, append one or more linefeeds (`n).
Once the height of MainText's control area has been set, it cannot be
changed without recreating the window.
WinTitle
The title of the window. If omitted and the window is being newly created,
the title defaults to the name of the script (without path). If the B
(borderless) option has been specified, there will be no visible title bar but
the window can still be referred to by this title in commands such as
WinMove.
FontName
The name of the font to use for both MainText and SubText. The font table
lists the fonts included with the various versions of Windows. If unspecified
or if the font cannot be found, the system's default GUI font will be used.
See the options section below for how to change the size, weight, and color
of the font.
Printed Documentation
292
Window Size, Position, and Behavior
A: The window will not be always-on-top.
B: Borderless: The window will have no border and no title bar. To have a border but no title bar, use
B1 for a thin border or B2 for a dialog style border.
M: The window will be movable by the user (except if borderless). To additionally make the window
resizable (by means of dragging its borders), specify M1. To additionally include a system menu and a
set of minimize/maximize/close buttons in the title bar, specify M2.
Pn: For Progress windows, specify for n the starting position of the bar (the default is 0 or the number
in the allowable range that is closest to 0). To later change the position of the bar, follow this
example: Progress, 50
Rx-y: For Progress windows, specify for x-y the numerical range of the bar (if the R option is not
present, the default is 0-100). For example, R0-1000 would allow a numbers between 0 and 1000; R-
50-50 would allow numbers between -50 and 50; and R-10--5 would allow numbers between -10 and
-5. On Windows 95 and NT4, negative ranges and ranges beyond 65535 will not behave correctly
unless Internet Explorer 3.0 or later is installed.
T: The window will be given a button in the task bar and it will be unowned. Normally, there is no
button because the window is owned by the script's main window. This setting also prevents a GUI
window's Gui +OwnDialogs setting from taking ownership of a Splash or Progress window.
Hn: Specify for n the height of the window's client area (which is the area not including title bar and
borders). If unspecified, the height will be calculated automatically based on the height of the
image/bar and text in the window.
Wn: Specify for n the width of the window's client area. If unspecified, the width will be calculated
automatically for SplashImage (if there is an image). Otherwise, it will default to 300.
Xn: Specify for n the x-coordinate of the window's upper left corner. If unspecified, the window will be
horizontally centered on the screen.
Yn: Specify for n the y-coordinate of the window's upper left corner. If unspecified, the window will be
vertically centered on the screen.
Hide: The window will be initially hidden. Use Progress Show or SplashImage Show to show it later.
Layout of Objects in the Window
Cxy: Centered: If this option is absent, both SubText and MainText will be centered inside the
window. Specify 0 for x to make SubText left-justified. Specify a 1 to keep it centered. The same is
true for y except that it applies to MainText (y can be omitted). For example: c10
ZHn: Height of object: For Progress windows, specify for n the thickness of the progress bar (default
20). For SplashImage windows, specify for n the height to which to scale image. Specify -1 to make
the height proportional to the width specified in ZWn (i.e. "keep aspect ratio"). If unspecified, the
actual image height will be used. In either case, a value of 0 can be specified to omit the object
entirely, which allows the window to be used to display only text in custom fonts, sizes, and colors.
ZWn: Width of object (for SplashImage windows only): Specify for n the width to which to scale the
image. Specify -1 to make the width proportional to the height specified in ZHn (i.e. "keep aspect
ratio"). If unspecified, the actual image width will be used.
ZXn: Specify for n the amount of margin space to leave on the left/right sides of the window. The
default is 10 except for SplashImage windows with no text, which have a default of 0.
ZYn: Specify for n the amount of vertical blank space to leave at the top and bottom of the window
and between each control. The default is 5 except for SplashImage windows with no text, which have
a default of 0.
Note: To create a vertical progress bar or to have more layout flexibility, use the Gui command such
as this example:
GUI, MsgBox, InputBox & Other Dialogs
293
Gui, Add, Progress, Vertical vMyProgress
Gui, Show
return
; ... later...
GuiControl,, MyProgress, +10 ; Move the bar upward by 10 percent. Omit the + to set an
absolute position.
Font Size and Weight
FMn: Specify for n the font size for MainText. Default 0, which causes 10 to be used on most systems.
This default is not affected by the system's selected font size in Control Panel > Display settings.
FSn: Specify for n the font size for SubText. Default 0, which causes 8 to be used on most systems.
WMn: Specify for n the font weight of MainText. The weight should be between 1 and 1000. If
unspecified, 600 (semi-bold) will be used.
WSn: Specify for n the font weight of SubText. The weight should be between 1 and 1000 (700 is
traditionally considered to be "bold"). If unspecified, 400 (normal) will be used.
Object Colors
A color can be one of the names from the list below or a 6-digit hexadecimal RGB value. For example,
specifying cw1A00FF would set a window background color with red component 1A, green component
00, and blue component FF.
Add a space after each color option if there are any more options that follow it. For example: cbRed
ct900000 cwBlue
CBn: Color of progress bar: Specify for n one of the 16 primary HTML color names or a 6-digit RGB
color value. If unspecified, the system's default bar color will be used. Specify the word Default to
return to the system's default progress bar color.
CTn: Color of text: Specify for n one of the 16 primary HTML color names or a 6-digit RGB color
value. If unspecified, the system's default text color (usually black) will be used. Specify the word
Default to return to the system's default text color.
CWn: Color of window (background): Specify for n one of the 16 primary HTML color names or a 6-
digit RGB color value. If unspecified, the system's color for the face of buttons will be used (specify
the word Default to later return to this color). To make the background transparent on Windows
2000/XP and beyond, use WinSet TransColor.
Color names and RGB values

Black = 000000

Green = 008000

Silver = C0C0C0

Lime = 00FF00

Gray = 808080

Olive = 808000

White = FFFFFF

Yellow = FFFF00

Maroon = 800000

Navy = 000080

Red = FF0000

Blue = 0000FF
Printed Documentation
294

Purple = 800080

Teal = 008080

Fuchsia = FF00FF

Aqua = 00FFFF
Remarks
If the first parameter is the word OFF, the window is destroyed.
Each script can display up to 10 Progress windows and 10 SplashImage windows. Each window has a
number assigned to it at the time it is created. If unspecified, that number is 1 (the first). Otherwise,
precede the first parameter with the number of the window followed by a colon. For example, the
Progress command with 2:Off would turn off the number-2 Progress window, 2:75 would set its bar to
75%, 2: would change one or more of its text fields, and 2:B would create a new borderless Progress
window. Similarly, the SplashImage command with 2:Off would turn off the number-2 SplashImage
window, 2: would change one or more of its text fields, and 2:C:\My Images\Picture1.jpg would create
a new number-2 SplashImage window.
Upon creation, a window that would be larger than the desktop is automatically shrunk to fit.
A naked progress bar can be displayed by specifying no SubText, no MainText, and including the
following options: b zx0 zy0. A naked image can be displayed the same way except that only the B
option is needed.
On Windows XP or later, if there is a non-Classic theme is in effect, the interior of a progress bar may
appear as a series of segments rather than a smooth continuous bar. To avoid this, specify a bar color
explicitly such as cbBlue.
Use decimal (not hexadecimal) numbers for option letters that need them, except where noted.
Commands such as WinSet and WinMove can be used to change the attributes of an existing window
without having to recreate it.
A GUI window may take ownership of a Progress or Splash window by means of Gui +OwnDialogs.
This causes the Splash or Progress to stay always on top of its owner. In addition, the Progress or
Splash is automatically destroyed when its GUI window is destroyed.
Related
GUI, SplashTextOn, ToolTip
Examples
Progress, b w200, My SubText, My MainText, My Title
Progress, 50 ; Set the position of the bar to 50%.
Sleep, 4000
Progress, Off

; Create a window just to display some 18-point Courier text:
Progress, m2 b fs18 zh0, This is the Text.`nThis is a 2nd line., , , Courier New

; Create a simple SplashImage window:
SplashImage, C:\My Pictures\Company Logo.gif

GUI, MsgBox, InputBox & Other Dialogs
295
; Create a borderless SplashImage window with some large text beneath the image:
SplashImage, C:\My Pictures\Company Logo.gif, b fs18, This is our company logo.
Sleep, 4000
SplashImage, Off

; Here is a working example that demonstrates how a Progress window can be
; overlayed on a SplashImage to make a professional looking Installer screen:
IfExist, C:\WINDOWS\system32\ntimage.gif, SplashImage, %A_WinDir%\system32\ntimage.gif, A,,,
Installation
Loop, %A_WinDir%\system32\*.*
{
Progress, %a_index%, %a_loopfilename%, Installing..., Draft Installtion
Sleep, 50
IfEqual, a_index, 100, break
}
; There is similar example at the bottom of the GUI page. Its advantage is that it uses only a single
; window and it gives you more control over window layout.
SplashTextOn / SplashTextOff
Creates a customizable text popup window.
SplashTextOff
SplashTextOn [, Width, Height, Title, Text]
Parameters
Width
The width in pixels of the Window. Default 200. This parameter can be an
expression.
Height
The height in pixels of the window (not including its title bar if the script's file
extension isn't .aut). Default 0 (i.e. just the title bar will be shown). This
parameter can be an expression.
Title The title of the window. Default empty (blank).
Text
The text of the window. Default empty (blank). If Text is long, it can be broken
up into several shorter lines by means of a continuation section, which might
improve readability and maintainability.
Remarks
To have more control over layout and font name/color/size, use the Progress command with the zh0
option, which omits the bar and displays only text. For example: Progress, zh0 fs18, Some 18-point
text to display.
Use the SplashTextOff command to remove an existing splash window.
The splash window is "always on top", meaning that it stays above all other normal windows. To
change this, use WinSet, AlwaysOnTop, Off, <insert title of splash window>. WinSet can also make
the splash window transparent.
WinMove can be used to reposition and resize the SplashText window after it has been displayed with
this command.
Printed Documentation
296
Unlike Progress, SplashImage, MsgBox, InputBox, FileSelectFile, and FileSelectFolder, only one
SplashText window per script is possible.
If SplashTextOn is used while the splash window is already displayed, the window will be recreated
with the new parameter values. However, rather than recreating the splash window every time you
wish to change its title or text, better performance can be achieved by using the following, especially if
the window needs to be changed frequently:
WinSetTitle, <insert title of splash window>, , NewTitle
ControlSetText, Static1, NewText, <insert title of splash window>
Related
Progress, SplashImage, ToolTip, MsgBox, InputBox, FileSelectFile, FileSelectFolder, WinMove, WinSet
Example
SplashTextOn, , , Displays only a title bar.
Sleep, 2000
SplashTextOn, 400, 300, Clipboard, The clipboard contains:`n%clipboard%
WinMove, Clipboard, , 0, 0 ; Move the splash window to the top left corner.
Msgbox, Press OK to dismiss the SplashText
SplashTextOff
ToolTip
Creates an always-on-top window anywhere on the screen.
ToolTip [, Text, X, Y, WhichToolTip]
Parameters
Text
If blank or omitted, the existing tooltip (if any) will be hidden. Otherwise, this
parameter is the text to display in the tooltip. To create a multi-line tooltip,
use the linefeed character (`n) in between each line, e.g. Line1`nLine2.
If Text is long, it can be broken up into several shorter lines by means of a
continuation section, which might improve readability and maintainability.
X, Y
The X and Y position of the tooltip relative to the active window (use
"CoordMode, ToolTip" to change to screen coordinates). If the coordinates are
omitted, the tooltip will be shown near the mouse cursor. X and Y can be
expressions.
WhichToolTip
Omit this parameter if you don't need multiple tooltips to appear
simultaneously. Otherwise, this is a number between 1 and 20 to indicate
which tooltip window to operate upon. If unspecified, that number is 1 (the
first). This parameter can be an expression.
Remarks
If the X & Y coordinates would cause the tooltip to run off screen, it is repositioned to be entirely
visible.
The tooltip is displayed until one of the following occurs:
The script terminates.
The ToolTip command is executed again with a blank Text parameter.
GUI, MsgBox, InputBox & Other Dialogs
297
The user clicks on the tooltip (this behavior may vary depending on operating system version).
A GUI window may be made the owner of a tooltip by means of Gui +OwnDialogs. Such a tooltip is
automatically destroyed when its owner is destroyed.
Related
CoordMode, TrayTip, GUI, Progress, SplashTextOn, MsgBox, InputBox, FileSelectFile, FileSelectFolder
Example
ToolTip, Multiline`nTooltip, 100, 150

; To have a ToolTip disappear after a certain amount of time
; without having to use Sleep (which stops the current thread):
#Persistent
ToolTip, Timed ToolTip`nThis will be displayed for 5 seconds.
SetTimer, RemoveToolTip, 5000
return

RemoveToolTip:
SetTimer, RemoveToolTip, Off
ToolTip
return
TrayTip
Creates a balloon message window near the tray icon. Requires Windows 2000/XP or later.
TrayTip [, Title, Text, Seconds, Options]
Parameters
Title
If all parameters are omitted, any TrayTip window currently displayed will be
removed.
Otherwise, this parameter is the title of the window, which can be up to 73
characters long (characters beyond this length are not shown).
If Title is blank, the title line will be entirely omitted from the balloon window,
making it vertically shorter.
Text
If this parameter is omitted or blank, any TrayTip window currently displayed
will be removed.
Otherwise, specify the message to display, which appears beneath Title. Only
the first 265 characters of Text will be displayed. Carriage return (`r) or
linefeed (`n) may be used to create multiple lines of text. For example:
Line1`nLine2
If Text is long, it can be broken up into several shorter lines by means of a
continuation section, which might improve readability and maintainability.
Printed Documentation
298
Seconds
The approximate number of seconds to display the window, after which it will
be automatically removed by the OS. Specifying a number less than 10 or
greater than 30 will usually cause the minimum (10) or maximum (30) display
time to be used instead. If blank or omitted, the minimum time will usually be
used. This parameter can be an expression.
This setting is currently unreliable due to the nature of its handling by the OS.
To have precise control over how long the TrayTip is displayed, use the Sleep
command followed by TrayTip with no parameters, or use SetTimer as
illustrated in the Examples section below.
Options
Specify one of the following numbers to have a small icon appear to the left of
Title:
1: Info icon
2: Warning icon
3: Error icon
If omitted, it defaults to 0, which is no icon. This parameter can be an
expression.
Remarks
TrayTip requires Windows 2000/XP or later. On older operating systems, the command does nothing.
TrayTip windows cannot be shown if the script lacks a tray icon (via #NoTrayIcon or Menu, tray,
NoIcon). Similarly, if the following REG_DWORD value exists and has been set to 0, TrayTip will not
function:
HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced >> EnableBalloonTips
Windows XP usually plays a sound when displaying a balloon tip. This sound can be disabled by adding
16 to the Options parameter.
On a related note, there is a tooltip displayed whenever the user hovers the mouse over the script's
tray icon. The contents of this tooltip can be changed via: Menu, Tray, Tip, My New Text
Related
ToolTip, SetTimer, Menu, SplashTextOn, MsgBox, InputBox, FileSelectFile, FileSelectFolder
Examples
TrayTip, MyTitle, Multiline`nText, 20, 17

; To have more precise control over the display time without
; having to use Sleep (which stops the current thread):
#Persistent
TrayTip, Timed TrayTip, This will be displayed for 5 seconds.
SetTimer, RemoveTrayTip, 5000
return

RemoveTrayTip:
SetTimer, RemoveTrayTip, Off
TrayTip
GUI, MsgBox, InputBox & Other Dialogs
299
return

; To have a TrayTip permanently displayed, use a timer to refresh it periodically:
SetTimer, RefreshTrayTip, 1000
Gosub, RefreshTrayTip ; Call it once to get it started right away.
return

RefreshTrayTip:
TrayTip, Refreshed TrayTip, This is a more permanent TrayTip., , 16
return

301
Keyboard Control
Hotkeys and Hotstrings
Hotkeys (Mouse, Joystick and Keyboard Shortcuts)
Table of Contents
Introduction and Simple Examples
Table of Hotkey Prefix Symbols (Modifiers)
Context-sensitive Hotkeys
Custom Combinations and Other Features
Mouse Wheel Hotkeys
Hotkey Tips and Remarks
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 Windows key, which is known as a
modifier:
#n::
Run Notepad
return
In the final line above, "return" 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 return 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::
Send Sincerely,{enter}John Smith ; This line sends keystrokes to the active (foremost)
window.
return
You can use the following modifier symbols to define hotkeys:
Symbol Description
# Win (Windows logo key)
! Alt
^ Control
+ Shift
&
An ampersand may be used between any two keys or mouse buttons to combine
them into a custom hotkey. See below for details. Such hotkeys are ignored (not
activated) on Windows 95/98/Me.
<
Use the left key of the pair. e.g. <!a is the same as !a except that only the left Alt
key will trigger it. This symbol is ignored on Windows 95/98/ME.
> Use the right key of the pair. This symbol is ignored on Windows 95/98/ME.
Printed Documentation
302
<^>!
AltGr (alternate graving). If your keyboard layout has an AltGr key instead of a
right-Alt key, this series of symbols can usually be used to stand for AltGr (requires
Windows NT/2k/XP or later). 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 modifer key(s) are down.
This symbol is ignored on Windows 95/98/ME.
~
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.
Notes: 1) Unlike the other prefix symbols, the tilde prefix may be present on some
of a hotkey's variants but absent on others; 2) Special hotkeys that are substitutes
for alt-tab always ignore the tilde prefix; 3) The tilde prefix is ignored on Windows
95/98/ME
$
This is usually only necessary if the script uses the Send command to send the keys
that comprise the hotkey itself, which might otherwise cause it to trigger itself. The
exact behavior of the $ prefix varies depending on operating system:
On Windows NT4/2k/XP or later: The $ prefix forces the keyboard hook to be used
to implement this hotkey, which as a side-effect prevents the Send command from
triggering it. The $ prefix is equivalent to having specified #UseHook somewhere
above the definition of this hotkey.
On Windows 95/98/Me: The hotkey is disabled during the execution of its thread
and re-enabled afterward. As a side-effect, if #MaxThreadsPerHotkey is set higher
than 1, it will behave as though set to 1 for such hotkeys.
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 LWin to become LControl:
*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; 2) "Up" requires Windows
Keyboard Control
303
NT4/2000/XP or later; and 3) 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::)
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.
(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 Control+Numpad0 or Control+Numpad1 will display this message.
return
A key or key-combination can be disabled for the entire system by having it do nothing. The following
example disables the right-side Windows key:
RWin::return
Context-sensitive Hotkeys [v1.0.41+]
The directives #IfWinActive/Exist can be used to make a hotkey perform a different action (or none at
all) depending on the type of window that is active or exists. For example:
#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.
Custom Combinations and Other Features [Windows NT/2000/XP or later]
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
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.
Printed Documentation
304
The presence of one of the above 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.
Numlock, Capslock, and Scrolllock: These keys may be forced to be "AlwaysOn" or "AlwaysOff".
For example: SetNumlockState AlwaysOn
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 Alt-Tab.
Mouse Wheel Hotkeys [Windows NT/2000/XP or later]
Hotkeys that fire upon turning the mouse wheel are supported via the key names WheelDown and
WheelUp. For example:
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.
In v1.0.43.03+, the built-in variable A_EventInfo contains the number of notches by which the
wheel was turned, which is always at least 1. Integers higher than 1 typically occur when the wheel is
being turned quickly (though how common this is depends on the granularity of the mouse hardware).
Example usage: ~WheelDown::ToolTip %A_EventInfo%
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 Control key:
~LControl & WheelUp:: ; Scroll left.
ControlGetFocus, fcontrol, A
Loop 2 ; <-- Increase this value to scroll faster.
SendMessage, 0x114, 0, 0, %fcontrol%, A ; 0x114 is WM_HSCROLL and the 0 after it is
SB_LINERIGHT.
return

~LControl & WheelDown:: ; Scroll right.
ControlGetFocus, fcontrol, A
Loop 2 ; <-- Increase this value to scroll faster.
SendMessage, 0x114, 1, 0, %fcontrol%, A ; 0x114 is WM_HSCROLL and the 1 after it is
SB_LINELEFT.
return
Finally, since mouse wheel hotkeys generate only down-events (never up-events), they cannot be
used as key-up hotkeys.
Hotkey Tips and Remarks
Keyboard Control
305
Each numpad key can be made to launch two different hotkey subroutines depending on the state of
Numlock. Alternatively, a numpad key can be made to launch the same subroutine regardless of the
Numlock state. For example:
NumpadEnd::
Numpad1::
MsgBox, This hotkey is launched regardless of whether Numlock is on.
return
If the tilde (~) operator is used with a prefix key even once, that prefix will always be sent through to
the active window. 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:
~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.
The Suspend command can temporarily disable all hotkeys except for ones you make exempt. For
greater selectivity, use #IfWinActive/Exist.
By means the Hotkey 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.
Joystick hotkeys do not currently support modifier prefixes such as ^ (Control) and # (Win). However,
you can use GetKeyState to mimic this effect as shown in the following example:
Joy2::
if not GetKeyState("Control") ; Neither the left nor right Control key is down.
return ; i.e. Do nothing.
MsgBox You pressed the first joystick's second button while holding down the Control key.
return
There may be times when a hotkey should wait for its own modifier keys to be released before
continuing. Consider the following example:
^!s::Send {Delete}
Pressing Control-Alt-S would cause the system to behave as though you pressed Control-Alt-Delete
(due to the system's aggressive detection of Ctrl-Alt-Delete). To work around this, use KeyWait to
wait for the keys to be released; for example:
^!s::
KeyWait Control
KeyWait Alt
Send {Delete}
return
A hotkey label can be used as the target of a Gosub or Goto. For example: Gosub ^!s
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 this FAQ topic.
Finally, each script is quasi multi-threaded, 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
MsgBox is being displayed by the current hotkey.
Alt-Tab Hotkeys
Printed Documentation
306
Each Alt-Tab hotkey must be a combination of two keys, which is typically achieved via the ampersand
symbol (&). In the following example, you would hold down the right Alt key and press J or K to
navigate the alt-tab menu:
RAlt & j::AltTab
RAlt & k::ShiftAltTab
AltTab and ShiftAltTab are two of the special commands that are only recognized when used on the
same line as a hotkey. Here is the complete list:
AltTab: If the menu is displayed, move forward in it. Otherwise, display the menu if the hotkey is an
"&" combination of two keys; otherwise, do nothing.
ShiftAltTab: Same as above except move backward in the menu.
AltTabAndMenu: If the menu is displayed, move forward in it. Otherwise, display the menu.
AltTabMenuDismiss: Close the Alt-tab menu.
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:
MButton::AltTabMenu
WheelDown::AltTab
WheelUp::ShiftAltTab
To cancel a hotkey-invoked Alt-tab menu without activating the selected window, use a hotkey such
as the following. It might require adjustment depending on: 1) the means by which the alt-tab menu
was originally displayed; and 2) whether the script has the keyboard hook installed.
LCtrl & CapsLock::AltTab
!MButton:: ; Middle mouse button. The ! prefix makes it fire while the Alt key is down (which
it is if the alt-tab menu is visible).
IfWinExist ahk_class #32771 ; Indicates that the alt-tab menu is present on the screen.
Send !{Escape}{Alt up}
return
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). Also, the presence of the alt-tab menu can
be detected via IfWinExist ahk_class #32771
Custom alt-tab actions can also be created via hotkeys. In the following example, you would press F1
to display the menu and advance forward in it. Then you would press F2 to activate the selected
window (or press Escape to cancel):
*F1::Send {Alt down}{tab} ; Asterisk is required in this case.
!F2::Send {Alt up} ; Release the Alt key, which activates the selected window.
~*Escape::
IfWinExist ahk_class #32771
Send {Escape}{Alt up} ; Cancel the menu without activating the selected window.
return
#HotkeyInterval
Along with #MaxHotkeysPerInterval, specifies the rate of hotkey activations beyond which a warning
dialog will be displayed.
Keyboard Control
307
#HotkeyInterval Milliseconds
Parameters
Milliseconds The length of the interval in milliseconds.
Remarks
If this directive is unspecified in the script, it will behave as though set to 2000.
For details and remarks, see #MaxHotkeysPerInterval.
Related
#MaxHotkeysPerInterval
Example
#HotkeyInterval 2000 ; This is the default value (milliseconds).
#MaxHotkeysPerInterval 200
#HotkeyModifierTimeout
Affects the behavior of hotkey modifiers: CTRL, ALT, WIN, and SHIFT.
#HotkeyModifierTimeout Milliseconds
Parameters
Milliseconds
The length of the interval in milliseconds. The value can be -1 so that it never
times out (modifier keys are always pushed back down after the Send), or 0 so
that it always times out (modifier keys are never pushed back down).
Remarks
This directive need not be used when:
Hotkeys send their keystrokes via the SendInput or SendPlay methods. This is because those
methods postpone the user's physical pressing and releasing of keys until after the Send
completes.
The script has the keyboard hook installed (you can see if your script uses the hook via the
"View->Key history" menu item in the main window, or via the KeyHistory command). This is
because the hook can keep track of which modifier keys (ALT/CTRL/WIN/SHIFT) the user is
physically holding down and doesn't need to use the timeout.
To illustrate the effect of this directive, consider this example:
^!a::Send, abc
When the Send command executes, the first thing it does is release the CTRL and ALT keys so that the
characters get sent properly. After sending all the keys, the command doesn't know whether it can
safely push back down CTRL and ALT (to match whether the user is still holding them down). But if
less than the specified number of milliseconds have elapsed, it will assume that the user hasn't had a
chance to release the keys yet and it will thus push them back down to match their physical state.
Otherwise, the modifier keys will not be pushed back down and the user will have to release and press
them again to get them to modify the same or another key.
The timeout should be set to a value less than the amount of time that the user typically holds down a
hotkey's modifiers before releasing them. Otherwise, the modifiers may be restored to the down
position (get stuck down) even when the user isn't physically holding them down.
You can reduce or eliminate the need for this directive with one of the following:
Install the keyboard hook by adding the line #InstallKeybdHook anywhere in the script
(however, the hook is not supported on Win9x).
Use the SendInput or SendPlay methods rather than the traditional SendEvent method.
When using the traditional SendEvent method, reduce SetKeyDelay to 0 or -1, which should
help because it sends the keystrokes more quickly.
Printed Documentation
308
If this is directive is unspecified in a script, it behaves as though set to 50.
Related
GetKeyState
Example
#HotkeyModifierTimeout 100
#Hotstring
Changes hotstring options or ending characters.
#Hotstring NoMouse
#Hotstring EndChars NewChars
#Hotstring NewOptions
Parameters
NoMouse
[v1.0.42.03+]
Prevents mouse clicks from resetting the hotstring recognizer as described
here. As a side-effect, this also prevents the mouse hook from being
required by hotstrings (though it will still be installed if the script requires it
for other purposes, such as mouse hotkeys). The presence of #Hotstring
NoMouse anywhere in the script affects all hotstrings, not just those
physically beneath it.
EndChars
NewChars
Specify the word EndChars followed a single space and then the new ending
characters. For example:
#Hotstring EndChars -()[]{}':;"/\,.?!`n `t
Since the new ending characters are in effect globally for the entire script --
regardless of where the EndChars directive appears -- there is no need to
specify EndChars more than once.
The maximum number of ending characters is 100. Characters beyond this
length are ignored.
To make tab an ending character, include `t in the list. To make space an
ending character, include it between two other characters in the list (or at
the beginning if the list contains only one other character, or no other
characters).
NewOptions
Specify new options as described in Hotstring Options. For example:
#Hotstring r s k0 c0
Unlike EndChars above, the #Hotstring directive is positional when used this
way. In other words, entire sections of hotstrings can have different default
options as in this example:
::btw::by the way

#Hotstring r c ; All the below hotstrings will use "send raw" and will
be case sensitive by default.
::al::airline
::CEO::Chief Executive Officer

#Hotstring c0 ; Make all hotstrings below this point case insensitive.
Related
Keyboard Control
309
Hotstrings
#IfWinActive / #IfWinExist [v1.0.41/42+]
Creates context-sensitive hotkeys and hotstrings. Such hotkeys perform a different action (or none at
all) depending on the type of window that is active or exists.
#IfWinActive [, WinTitle, WinText]
#IfWinExist [, WinTitle, WinText]
#IfWinNotActive [, WinTitle, WinText]
#IfWinNotExist [, WinTitle, WinText]
Parameters
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode as set in the auto-execute section). To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a window group, specify ahk_group GroupName. The ahk_pid and ahk_id
keywords are also supported, but it is more common for #IfWin to use them
indirectly via GroupAdd (alternatively, use "Hotkey IfWin"). Finally, the search
can be narrowed by specifying multiple criteria. For example: My File.txt
ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText has been turned on in the
auto-execute section (top part of the script).
ExcludeTitle
ExcludeText
Although these are not supported, they can be used indirectly by specifying
ahk_group MyGroup for WinTitle (where MyGroup is a group created via
GroupAdd, which supports ExcludeTitle/Text).
Basic Operation
The #IfWin directives make it easy to create context-sensitive hotkeys and hotstrings. For example:
#IfWinActive ahk_class Notepad
#space::MsgBox You pressed Win+Spacebar in Notepad.
The #IfWin directives are positional: they affect all hotkeys and hotstrings physically beneath them in
the script. They are also mutually exclusive; that is, only the most recent one will be in effect.
To turn off context sensitivity, specify any #IfWin directive but omit all of its parameters. For
example:
#IfWinActive
When #IfWin is turned off (or never used in a script), all hotkeys and hotstrings are enabled for all
windows (unless disabled via Suspend or the Hotkey command).
When a mouse or keyboard hotkey is disabled via #IfWin, it performs its native function; that is, it
passes through to the active window as though there is no such hotkey. There are two exceptions: 1)
Windows 95/98/Me: pressing an IfWin-disabled hotkey has no effect (not even its native function);
and 2) Joystick hotkeys: although #IfWin works, it never prevents other programs from seeing the
press of a button.
#IfWin can also be used to alter the behavior of an ordinary key like Enter or Space. This is useful
when a particular window ignores that key or performs some action you find undesirable. For
example:
#IfWinActive Reminders ahk_class #32770 ; The "reminders" window in Outlook.
Enter::Send !o ; Have an "Enter" keystroke open the selected reminder rather than snoozing
it.
#IfWinActive
Printed Documentation
310
Variant (Duplicate) Hotkeys
A particular hotkey or hotstring can be defined more than once in the script if each definition has
different #IfWin criteria. These are known as hotkey variants. For example:
#IfWinActive ahk_class Notepad
^!c::MsgBox You pressed Control+Alt+C in Notepad.
#IfWinActive ahk_class WordPadClass
^!c::MsgBox You pressed Control+Alt+C in WordPad.
#IfWinActive
^!c::MsgBox You pressed Control+Alt+C in a window other than Notepad/WordPad.
If more than one variant is eligible to fire, only the one closest to the top of the script will fire. The
exception to this is the global variant (the one with no #IfWin criteria): It always has the lowest
precedence; therefore, it will fire only if no other variant is eligible (this exception does not apply to
hotstrings).
When defining variants, the order of modifier symbols such as ^!+# does not matter. For example,
^!c is the same as !^c. However, any hotkey with a wildcard prefix (*) is an entirely separate hotkey
from a non-wildcard one (for example, *F1 and F1 would each have their own set of variants).
To have the same hotkey subroutine executed by more than one variant, the easiest way is to create
a stack of identical hotkeys, each with a different #IfWin directive above it. For example:
#IfWinActive ahk_class Notepad
#z::
#IfWinActive ahk_class WordPadClass
#z::
MsgBox You pressed Win+Z in either Notepad or WordPad.
return
Alternatively, a window group can be used via #IfWinActive ahk_group MyGroup.
To create hotkey variants dynamically (while the script is running), see "Hotkey IfWin".
General Remarks
#IfWin also restores prefix keys to their native function when appropriate (a prefix key is the "a" key
in a hotkey such as "a & b"). This occurs whenever there are no enabled hotkeys for a given prefix.
When Gosub or Goto is used to jump to a hotkey or hotstring label, it jumps to the variant closest to
the top of the script.
When a hotkey is currently disabled via #IfWin, its key or mouse button will appear with a "#"
character in KeyHistory's "Type" column. This can help debug a script.
Variable references such as %Var% are not currently supported. Therefore, percent signs must be
escaped via `% to allow future support for them. Similarly, literal commas must be escaped (via `,) to
allow additional parameters to be added in the future. If you need to work around this limitation, use
GroupAdd and ahk_group.
A label to which the Hotkey command has assigned a hotkey is not directly affected by #IfWin.
Instead, the use of #IfWin closest to the bottom of the script (if any) will be in effect for all hotkeys
created by the Hotkey command (unless "Hotkey IfWin" has been used to change that).
Alt-tab hotkeys are not affected by #IfWin: they are in effect for all windows.
The Last Found Window is set by #IfWinActive/Exist (though not by #IfWinNotActive/NotExist). For
example:
#IfWinExist ahk_class Notepad
Keyboard Control
311
#n::WinActivate ; Activates the window found by #IfWin.
The escape sequences `s and `t may be used if leading or trailing spaces/tabs are needed in one of
#IfWin's parameters.
For performance reasons, #IfWin does not continuously monitor the activation or existence of the
specified windows. Instead, it checks for a matching window only when you type a hotkey or
hotstring. If the right window is not present, your keystroke or mouse click is allowed to pass through
to the active window unaltered (except on Windows 95/98/Me).
Windows 95/98/Me: If the first variant of a hotkey has a $ prefix, all variants will be allowed to "send
themselves". This provides a means for a hotkey to perform its native function rather than doing
nothing at all. For example:
$^a::Send ^a ; The first variant must have a $ prefix to allow it to "send itself" on Windows
9x.
#IfWinActive ahk_class Notepad
^a::MsgBox You pressed Control-A while Notepad is active.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on in the auto-execute section (top part of the script).
In versions older than 1.0.42, #IfWin was more limited:
Windows 95/98/Me: With the exception of joystick hotkeys, the #IfWin directives were
ignored because they required the keyboard hook or mouse hook. In v1.0.42+, #IfWin is
supported.
Duplicate hotkeys (variants) were not allowed. Instead, window groups were typically used to
make a hotkey active in more than one type of window.
The Last Found Window was not set by #IfWin.
Related
Hotkey command, Hotkeys, Hotstrings, Suspend, IfWinActive, IfWinExist, SetTitleMatchMode,
DetectHiddenWindows
Examples
#IfWinActive ahk_class Notepad
^!a::MsgBox You pressed Ctrl-Alt-A while Notepad is active. ; This hotkey will have no effect if
pressed in other windows (and it will "pass through").
#c::MsgBox You pressed Win-C while Notepad is active.
::btw::This replacement text for "btw" will occur only in Notepad.
#IfWinActive
#c::MsgBox You pressed Win-C in a window other than Notepad.
#MaxHotkeysPerInterval
Along with #HotkeyInterval, specifies the rate of hotkey activations beyond which a warning dialog
will be displayed.
#MaxHotkeysPerInterval Value
Parameters
Value
The maximum number of hotkeys that can be pressed in the interval specified
by #HotkeyInterval without triggering a warning dialog.
Remarks
Printed Documentation
312
Care should be taken not to make the above too lenient because if you ever inadvertently introduce an
infinite loop of keystrokes (via a Send command that accidentally triggers other hotkeys), your
computer could become unresponsive due to the rapid flood of keyboard events.
As an oversimplified example, the hotkey ^c::Send ^c would produce an infinite loop of keystrokes.
To avoid this, add the $ prefix to the hotkey definition (e.g. $^c::) so that the hotkey cannot be
triggered by the Send command.
If this directive is unspecified in the script, it will behave as though set to 70.
Related
#HotkeyInterval
Example
#MaxHotkeysPerInterval 200
#MaxThreads
Sets the maximum number of simultaneous threads.
#MaxThreads Value
Parameters
Value The maximum total number of threads that can exist simultaneously (limit 20).
Remarks
This setting is global, meaning that it needs to be specified only once (anywhere in the script) to affect
the behavior of the entire script.
Although a value of 1 is allowed, it is not recommended because it would prevent new hotkeys from
launching whenever the script is displaying a MsgBox or other dialog. It would also prevent timers
from running whenever another thread is sleeping or waiting.
Any hotkey subroutine whose first line is ExitApp, Pause, Edit, Reload, KeyHistory, ListLines, ListVars,
or ListHotkeys will always run regardless of this setting.
If this setting is lower than #MaxThreadsPerHotkey, it effectively overrides that setting.
If this directive is unspecified in the script, it will behave as though set to 10.
Related
#MaxThreadsPerHotkey, Threads, #MaxHotkeysPerInterval, #HotkeyInterval, ListHotkeys, #MaxMem
Example
#MaxThreads 2
#MaxThreadsBuffer
Causes some or all hotkeys to buffer rather than ignore keypresses when their
#MaxThreadsPerHotkey limit has been reached.
#MaxThreadsBuffer On|Off
Parameters
On|Off
On: All hotkey subroutines between here and the next #MaxThreadsBuffer ON
directive will buffer rather than ignore presses of their hotkeys whenever their
subroutines are at their #MaxThreadsPerHotkey limit.
Off: This is the default behavior. A hotkey press will be ignored whenever that
hotkey is already running its maximum number of threads (usually 1, but this
can be changed with #MaxThreadsPerHotkey).
Keyboard Control
313
Remarks
This directive is rarely used because this type of buffering, which is OFF by default, usually does more
harm than good. For example, if you accidentally press a hotkey twice, having this setting ON would
cause that hotkey's subroutine to automatically run a second time if its first thread takes less than 1
second to finish (this type of buffer expires after 1 second, by design). Note that AutoHotkey buffers
hotkeys in several other ways (such as "Thread Interrupt" and "Critical"). It's just that this particular
way can be detrimental, thus it is OFF by default.
The main use for this directive is to increase the responsiveness of the keyboard's auto-repeat
feature. For example, when you hold down a hotkey whose #MaxThreadsPerHotkey setting is 1 (the
default), incoming keypresses are ignored if that hotkey subroutine is already running. Thus, when the
subroutine finishes, it must wait for the next auto-repeat keypress to come in, which might take 50ms
or more due to being caught in between keystrokes of the auto-repeat cycle. This 50ms delay can be
avoided by enabling this directive for any hotkey that needs the best possible response time while it is
being auto-repeated.
As with all # directives, this one should not be positioned in the script as though it were a command
(i.e. it is not necessary to have it contained within a subroutine). Instead, position it immediately
before the first hotkey label you wish to have affected by it.
Related
#MaxThreads, #MaxThreadsPerHotkey, Critical, Thread (command), Threads, Hotkey,
#MaxHotkeysPerInterval, #HotkeyInterval, ListHotkeys
Example
#MaxThreadsBuffer on
#x::MsgBox, This hotkey will use this type of buffering.
#y::MsgBox, And this one too.
#MaxThreadsBuffer off
#z::MsgBox, But not this one.
#MaxThreadsPerHotkey
Sets the maximum number of simultaneous threads per hotkey.
#MaxThreadsPerHotkey Value
Parameters
Value
The maximum number of threads that can be launched for a given hotkey
subroutine (limit 20).
Remarks
This setting is used to control how many "instances" of a given hotkey subroutine are allowed to exist
simultaneously. For example, if a hotkey has a max of 1 and it is pressed again while its subroutine is
already running, the press will be ignored. This is helpful to prevent accidental double-presses.
However, if you wish these keypresses to be buffered rather than ignored -- perhaps to increase the
responsiveness of the keyboard's auto-repeat feature -- use #MaxThreadsBuffer.
Unlike #MaxThreads, this setting is not global. Instead, position it before the first hotkey label you
wish to have affected by it, which will result in all subsequent hotkeys using that value until another
instance of this directive is encountered.
Any hotkey subroutine whose first line is ExitApp, Pause, Edit, Reload, KeyHistory, ListLines, ListVars,
or ListHotkeys will always run regardless of this setting.
The setting of #MaxThreads -- if lower than than this setting -- takes precedence.
If this directive is unspecified in the script, it will behave as though set to 1.
Related
Printed Documentation
314
#MaxThreads, #MaxThreadsBuffer, Critical, Threads, Hotkey, #MaxHotkeysPerInterval,
#HotkeyInterval, ListHotkeys
Example
#MaxThreadsPerHotkey 3
#UseHook
Forces the use of the hook to implement all or some keyboard hotkeys.
#UseHook [On|Off]
Parameters
On|Off
#UseHook without one of the following words after it is equivalent to
#UseHook On.
On: The keyboard hook will be used to implement all keyboard hotkeys
between here and the next #UseHook OFF (if any).
Off: Hotkeys will be implemented using the default method (RegisterHotkey()
if possible; otherwise, the keyboard hook).
Remarks
Normally, the windows API function RegisterHotkey() is used to implement a keyboard hotkey
whenever possible. However, the responsiveness of hotkeys might be better under some conditions if
the keyboard hook is used instead.
Turning this directive ON is equivalent to using the $ prefix in the definition of each affected hotkey.
The exception to this is Windows 95/98/Me, upon which #UseHook is ignored (though the $ prefix
works in a limited fashion).
As with all # directives -- which are processed only once when the script is launched -- #UseHook
should not be positioned in the script as though it were a command (that is, it is not necessary to
have it contained within a subroutine). Instead, position it immediately before the first hotkey label
you wish to have affected by it.
Hotkeys that use the keyboard hook cannot be triggered by means of the Send command. Similarly,
mouse hotkeys cannot be triggered by commands such as Click because all mouse hotkeys use the
mouse hook. To work around this, use Gosub to jump directly to the hotkey's subroutine. For
example: Gosub #LButton
If this directive does not appear in the script at all, it will behave as though set to OFF.
Related
#InstallKeybdHook, #InstallMouseHook, ListHotkeys
Example
#UseHook ; Force the use of the hook for hotkeys after this point.
#x::MsgBox, This hotkey will be implemented with the hook.
#y::MsgBox, And this one too.
#UseHook off
#z::MsgBox, But not this one.
Hotkey
Creates, modifies, enables, or disables a hotkey while the script is running.
Hotkey, KeyName [, Label, Options]
Hotkey, IfWinActive/Exist [, WinTitle, WinText]
Keyboard Control
315
Parameters
KeyName
Name of the hotkey's activation key, including any modifier symbols. For
example, specify #c for the Win+C hotkey.
If KeyName already exists as a hotkey, that hotkey will be updated with the
values of the command's other parameters.
KeyName can also be the name of an existing hotkey label (i.e. a double-colon
label), which will cause that hotkey to be updated with the values of the
command's other parameters.
When specifying an existing hotkey, KeyName is not case sensitive. In
addition, the order of modifier symbols such as ^!+# does not matter (except
in versions prior to 1.0.42). For example, ^!c is the same as !^c for matching
purposes.
The current IfWin setting determines the variant of a hotkey upon which the
Hotkey command will operate. If the variant does not yet exist, it will be
created.
When a hotkey is first created -- either by the Hotkey command or a double-
colon label in the script -- its key name and the ordering of its modifier
symbols becomes the permanent name of that hotkey as reflected by
A_ThisHotkey. This name does not change even if the Hotkey command later
accesses the hotkey with a different symbol ordering.
Label
The label name whose contents will be executed (as a new thread) when the
hotkey is pressed. Both normal labels and hotkey/hotstring labels can be used.
The trailing colon(s) should not be included. If Label is dynamic (e.g.
%VarContainingLabelName%), IsLabel(VarContainingLabelName) may be
called beforehand to verify that the label exists.
This parameter can be left blank if KeyName already exists as a hotkey, in
which case its label will not be changed. This is useful to change only the
hotkey's Options.
If the label is specified but the hotkey is disabled from a previous use
of this command, the hotkey will still be disabled afterward. To prevent
this, include the word ON in Options (but in versions prior to in v1.0.38.02,
instead use "Hotkey, KeyName, On" immediately afterward).
This parameter can also be one of the following special values:
On: The hotkey becomes enabled. No action is taken if the hotkey is already
On.
Off: The hotkey becomes disabled. No action is taken if the hotkey is already
Off.
Toggle: The hotkey is set to the opposite state (enabled or disabled).
AltTab (and others): These are special Alt-Tab hotkey actions that are
described here.
Note: The current IfWin setting determines the variant of a hotkey upon which
On/Off/Toggle will operate.
Options
A string of zero or more of the following letters with optional spaces in
between. For example: UseErrorLevel B0
UseErrorLevel [v1.0.42+]: If the command encounters a problem, this option
skips the warning dialog, sets ErrorLevel to one of the codes from the table
below, then allows the current thread to continue.
Printed Documentation
316
On [v1.0.38.02+]: Enables the hotkey if it is currently disabled.
Off [v1.0.42.02+]: Disables the hotkey if it is currently enabled. This is
typically used to create a hotkey in an initially-disabled state.
B or B0: Specify the letter B to buffer the hotkey as described in
#MaxThreadsBuffer. Specify B0 (B with the number 0) to disable this type of
buffering.
Pn: Specify the letter P followed by the hotkey's thread priority. If the P option
is omitted when creating a hotkey, 0 will be used.
Tn: Specify the letter T followed by a the number of threads to allow for this
hotkey as described in #MaxThreadsPerHotkey. For example: T5
If either or both of the B and T option letters are omitted and the hotkey
already exists, those options will not be changed. But if the hotkey does not
yet exist -- that is, it is about to be created by this command -- the options will
default to those most recently in effect. For example, the instance of
#MaxThreadsBuffer that occurs closest to the bottom of the script will be used.
If #MaxThreadsBuffer does not appear in the script, its default setting (OFF in
this case) will be used. This behavior also applies to #IfWin: the bottommost
occurrence applies to newly created hotkeys unless "Hotkey IfWin" has
executed since the script started.
Note: The current IfWin setting determines the variant of a hotkey upon which
the Hotkey command will operate. If the variant does not yet exist, it will be
created.
IfWinActive
IfWinExist
[v1.0.42+]
(IfWinNotActive and IfWinNotExist are also supported). These sub-commands
make all subsequently-created hotkeys context sensitive. See below for
details.
WinTitle
WinText
Within these parameters, any variable reference such as %var% becomes
permanent the moment the command finishes. In other words, subsequent
changes to the contents of the variable are not seen by existing IfWin hotkeys.
Like #IfWinActive/Exist, WinTitle and WinText use the default settings for
SetTitleMatchMode and DetectHiddenWindows as set in the auto-execute
section. See #IfWinActive/Exist for details.
ErrorLevel
ErrorLevel is changed only when: 1) the first parameter is IfWin[Not]Active/Exist, in which case it is
set to 1 if there was a problem or 0 otherwise; or 2) the word UseErrorLevel is present in the Options
parameter.
Error Description
1 The Label parameter specifies a nonexistent label name.
2
The KeyName parameter specifies one or more keys that are either not recognized or
not supported by the current keyboard layout/language.
3
Unsupported prefix key. For example, using the mouse wheel as a prefix in a hotkey
such as WheelDown & Enter is not supported.
4
The KeyName parameter is not suitable for use with the AltTab or ShiftAltTab actions.
A combination of two keys is required. For example: RControl & RShift::AltTab
5 The command attempted to modify a nonexistent hotkey.
6
The command attempted to modify a nonexistent variant of an existing hotkey. To
solve this, use "Hotkey IfWin" to set the criteria to match those of the hotkey to be
modified.
Keyboard Control
317
50
Windows 95/98/Me: The command completed successfully but the operating system
refused to activate the hotkey. This is usually caused by the hotkey being "in use" by
some other script or application (or the OS itself). This occurs only on Windows
95/98/Me because on other operating systems, the program will resort to the
keyboard hook to override the refusal.
51
Windows 95/98/Me: The command completed successfully but the hotkey is not
supported on Windows 95/98/Me. For example, mouse hotkeys and prefix hotkeys
such as "a & b" are not supported.
98
Creating this hotkey would exceed the 700-hotkey-per-script limit (however, each
hotkey can have an unlimited number of variants, and there is no limit to the number
of hotstrings).
99
Out of memory. This is very rare and usually happens only when the operating system
has become unstable.

Tip: The UseErrorLevel option can be used to test for the existence of a hotkey variant. For example:
Hotkey, ^!p,, UseErrorLevel
if ErrorLevel in 5,6
MsgBox The hotkey does not exist or it has no variant for the current IfWin criteria.
Remarks
If the goal is to disable selected hotkeys or hotstrings automatically based on the type of window that
is active, Hotkey, ^!c, Off is usually less convenient than using #IfWinActive/Exist (or their dynamic
counterparts "Hotkey IfWinActive/Exist" below).
Creating hotkeys via double-colon labels performs better than using the Hotkey command because the
hotkeys can all be enabled as a batch when the script starts (rather than one by one). Therefore, it is
best to use this command to create only those hotkeys whose key names are not known until after the
script has started running. One such case is when a script's hotkeys for various actions are
configurable via an INI file.
A given label can be the target of more than one hotkey. If it is known that a label was called by a
hotkey, you can determine which hotkey by checking the built-in variable A_ThisHotkey.
If the script is suspended, newly added/enabled hotkeys will also be suspended until the suspension is
turned off (unless they are exempt as described in the Suspend section).
The keyboard and/or mouse hooks will be installed or removed if justified by the changes made by
this command.
Although the Hotkey command cannot directly enable or disable hotkeys in scripts other than its own,
in most cases it can override them by creating or enabling the same hotkeys. Whether this works
depends on a combination of factors: 1) Whether the hotkey to be overridden is a hook hotkey in the
other script (non-hook hotkeys can always be overridden except on Win9x); 2) The fact that the most
recently started script's hotkeys generally take precedence over those in other scripts (therefore, if
the script intending to override was started most recently, its override should always succeed); 3)
Whether the enabling or creating of this hotkey will newly activate the keyboard or mouse hook (if so,
the override will always succeed).
Once a script has at least one hotkey, it becomes persistent, meaning that ExitApp rather than Exit
should be used to terminate it. Hotkey scripts are also automatically #SingleInstance unless
#SingleInstance Off has been specified.
Remarks About Hotkey, I fWinXX [ , WinTitle, WinText]
In v1.0.42+, the "Hotkey IfWin" commands allow context-sensitive hotkeys to be created and
modified while the script is running (by contrast, the #IfWinActive/Exist directives are positional and
take effect before the script begins executing). For example:
Hotkey, IfWinActive, ahk_class Notepad
Printed Documentation
318
Hotkey, ^!e, MyLabel ; Creates a hotkey that works only in Notepad.
Using "Hotkey IfWin" puts context sensitivity into effect for all subsequently created or modified
hotkeys. In addition, each IfWin sub-command is mutually exclusive; that is, only the most recent one
will be in effect.
To turn off context sensitivity (that is, to make subsequently-created hotkeys work in all windows),
specify any IfWin sub-command but omit the WinTitle/Text parameters. For example: Hotkey,
IfWinActive
If "Hotkey IfWin" is never used by a script, the bottommost use of the #IfWin directive (if any) will be
in effect for the Hotkey command.
When a mouse or keyboard hotkey is disabled via IfWin, it performs its native function; that is, it
passes through to the active window as though there is no such hotkey. There are two exceptions: 1)
Windows 95/98/Me: pressing an IfWin-disabled hotkey has no effect (not even its native function);
and 2) Joystick hotkeys: although IfWin works, it never prevents other programs from seeing the
press of a button.
Variant (Duplicate) Hotkeys [v1.0.42+]
A particular hotkey can be created more than once if each definition has different IfWin criteria. These
are known as hotkey variants. For example:
Hotkey, IfWinActive, ahk_class Notepad
Hotkey, ^!c, MyLabelForNotepad
Hotkey, IfWinActive, ahk_class WordPadClass
Hotkey, ^!c, MyLabelForWordPad
Hotkey, IfWinActive
Hotkey, ^!c, MyLabelForAllOtherWindows
If more than one variant of a hotkey is eligible to fire, only the one created earliest will fire. The
exception to this is the global variant (the one with no IfWin criteria): It always has the lowest
precedence, and thus will fire only if no other variant is eligible.
The order of modifier symbols such as ^!+# does not matter. For example, ^!c is the same as !^c.
However, any hotkey with a wildcard prefix (*) is an entirely separate hotkey from a non-wildcard one
(for example, *F1 and F1 would each have their own set of variants).
For more information about IfWin hotkeys, see #IfWin's General Remarks.
Related
Hotkey Symbols, #IfWinActive/Exist, #MaxThreadsBuffer, #MaxThreadsPerHotkey, Suspend,
IsLabel(), Threads, Thread, Critical, Gosub, Return, Menu, SetTimer
Examples
Hotkey, ^!z, MyLabel
return

MyLabel:
MsgBox You pressed %A_ThisHotkey%.
return

; Other examples:
Hotkey, RCtrl & RShift, AltTab ; Makes RCtrl & RShift operate like Alt-Tab.
Hotkey, #c, On ; Re-enables the Win-C hotkey.
Keyboard Control
319
Hotkey, $+#c, Off ; Disables the Shift-Win-C hotkey.
Hotkey, ^!a, , T5 ; Changes the hotkey to allow 5 threads.

Hotkey, IfWinActive, ahk_class Notepad
Hotkey, ^!c, MyLabelForNotepad ; Creates Ctrl-Alt-C as a hotkey that works only in Notepad.
ListHotkeys
Displays the hotkeys in use by the current script, whether their subroutines are currently running, and
whether or not they use the keyboard or mouse hook.
ListHotkeys
This command is equivalent to selecting the View->Hotkeys menu item in the main window.
If a hotkey has been disabled via the Hotkey command, it will be listed as OFF or PART ("PART" means
that only some of the hotkey's variants are disabled).
If any of a hotkey's subroutines are currently running, the total number of threads is displayed for that
hotkey.
Finally, the type of hotkey is also displayed, which is one of the following:
reg: The hotkey is implemented via the operating system's RegisterHotkey() function.
reg(no): Same as above except that this hotkey is inactive (due to being unsupported, disabled, or
suspended).
k-hook: The hotkey is implemented via the keyboard hook.
m-hook: The hotkey is implemented via the mouse hook.
2-hooks: The hotkey requires both the hooks mentioned above.
joypoll: The hotkey is implemented by polling the joystick at regular intervals.
Related
#InstallKeybdHook, #InstallMouseHook, #UseHook, KeyHistory, ListLines, ListVars,
#MaxThreadsPerHotkey, #MaxHotkeysPerInterval
Example
ListHotkeys
Pause
Pauses the script's current thread.
Pause [, On|Off|Toggle, OperateOnUnderlyingThread?]
Parameters
On|Off|Toggle
If blank or omitted, it defaults to Toggle. Otherwise, specify
one of the following words:
Toggle: Pauses the current thread unless the thread beneath
it is paused, in which case the underlying thread is unpaused.
On: Pauses the current thread.
Off: If the thread beneath the current thread is paused, it will
be in an unpaused state when resumed. Otherwise, the
command has no effect.
OperateOnUnderlyingThread?
[v1.0.37.06+]
This parameter is ignored for "Pause Off". For the others, it is
Printed Documentation
320
ignored unless Pause is being turned on (including via Toggle).
Specify one of the following numbers:
0 or omitted: The command pauses the current thread; that
is, the one now running the Pause command.
1: The command marks the thread beneath the current thread
as paused so that when it resumes, it will finish the command
it was running (if any) and then enter a paused state. If there
is no thread beneath the current thread, the script itself is
paused, which prevents timers from running (this effect is the
same as having used the menu item "Pause Script" while the
script has no threads).
Remarks
Unlike Suspend -- which disables hotkeys and hotstrings-- pause will freeze the thread. As a side-
effect, any interrupted threads beneath it will lie dormant.
Whenever any thread is paused, timers will not run. By contrast, explicitly launched threads such as
hotkeys and menu items can still be launched; but when their threads finish, the underlying
interrupted thread will still be paused. In other words, each thread can be paused independently of
the others.
The color of the tray icon changes from green to red whenever the script's current thread is in a
paused state. This can be avoided by freezing the icon, which is achieved by specifying 1 for the last
parameter of the Menu command. For example:
Menu, Tray, Icon, C:\My Icon.ico, , 1
To disable timers without pausing the script, use "Thread, NoTimers".
The Pause command is similar in function to the built-in menu item "Pause Script".
A script is always halted (though not officially paused) while it is displaying any kind of menu (tray
menu, menu bar, GUI context menu, etc.)
Related
Suspend, Menu, ExitApp, Threads, SetTimer
Examples
Pause::Pause ; Assign the toggle-pause function to the "pause" key...
#p::Pause ; ... or assign it to Win+p or some other hotkey.
Reload
Replaces the currently running instance of the script with a new one.
Reload
This command is useful for scripts that are frequently changed. By assigning a hotkey to this
command, you can easily restart the script after saving your changes in an editor.
When the script restarts, it is launched in its original working directory (the one that was in effect
when it was first launched). In other words, SetWorkingDir will not change the working directory that
will be used for the new instance.
If the script cannot be reloaded -- perhaps because it has a syntax error -- the original instance of the
script will continue running. Therefore, the reload command should be followed by whatever actions
you want taken in the event of a failure (such as a return to exit the current subroutine). To have the
original instance detect the failure, follow this example:
Reload
Keyboard Control
321
Sleep 1000 ; If successful, the reload will close this instance during the Sleep, so the line
below will never be reached.
MsgBox, 4,, The script could not be reloaded. Would you like to open it for editing?
IfMsgBox, Yes, Edit
return
Related
Edit
Example
^!r::Reload ; Assign Ctrl-Alt-R as a hotkey to restart the script.
Suspend
Disables or enables all or selected hotkeys.
Suspend [, Mode]
Parameters
Mode
On: Suspends all hotkeys except those explained the Remarks section.
Off: Re-enables all hotkeys.
Toggle (default): Changes to the opposite of its previous state (On or Off).
Permit: Does nothing except mark the current subroutine as being exempt
from suspension.
Remarks
Any hotkey subroutine whose first line is Suspend (except "Suspend On") will be exempt from
suspension. In other words, the hotkey will remain enabled even while suspension is ON. This allows
suspension to be turned off via such a hotkey.
To disable selected hotkeys or hotstrings automatically based on the type of window that is present,
use #IfWinActive/Exist.
Suspending a script's hotkeys does not stop the script's already-running threads (if any); use Pause to
do that.
When a script's hotkeys are suspended, its tray icon changes to the letter S. This can be avoided by
freezing the icon, which is done by specifying 1 for the last parameter of the Menu command. For
example:
Menu, Tray, Icon, C:\My Icon.ico, , 1
The built-in variable A_IsSuspended contains 1 if the script is suspended and 0 otherwise.
Related
#IfWinActive/Exist, Pause, Menu, ExitApp
Example
^!s::Suspend ; Assign the toggle-suspend function to a hotkey.
#InstallKeybdHook
Forces the unconditional installation of the keyboard hook.
#InstallKeybdHook
Remarks
Printed Documentation
322
The keyboard hook monitors keystrokes for the purpose of activating hotstrings and any keyboard
hotkeys not supported by RegisterHotkey (which is a function built into the operating system). It also
supports a few other features such as the Input command.
The keyboard hook is not supported under Windows 95/98/Me because those operating systems
require a different type of hook that must reside in a DLL file.
AutoHotkey does not install the keyboard and mouse hooks unconditionally because together they
consume at least 500 KB of memory. Therefore, the keyboard hook is normally installed only when the
script contains one of the following: 1) hotstrings; 2) one or more hotkeys that require the keyboard
hook (most do not); 3) SetCaps/Scroll/Numlock AlwaysOn/AlwaysOff; 4) the Input command, for
which the hook is installed upon first actual use.
By contrast, the #InstallKeybdHook directive will unconditionally install the keyboard hook, which
might be useful to allow KeyHistory to display the last 20 keystrokes (for debugging purposes), or to
avoid the need for #HotkeyModifierTimeout.
You can determine whether a script is using the hook via the KeyHistory command or menu item. You
can determine which hotkeys are using the hook via the ListHotkeys command or menu item.
This directive also makes a script persistent, meaning that ExitApp should be used to terminate it.
Related
#InstallMouseHook, #UseHook, Hotkey, Input, #Persistent, KeyHistory, Hotstrings, GetKeyState,
KeyWait
Example
#InstallKeybdHook
#InstallMouseHook
Forces the unconditional installation of the mouse hook.
#InstallMouseHook
Remarks
The mouse hook monitors mouse clicks for the purpose of activating mouse hotkeys and facilitating
hotstrings. It is not supported under Windows 95/98/Me because those operating systems require a
different type of hook that must reside in a DLL file.
AutoHotkey does not install the keyboard and mouse hooks unconditionally because together they
consume at least 500 KB of memory (but if the keyboard hook is installed, installing the mouse hook
only requires about 50 KB of additional memory; and vice versa). Therefore, the mouse hook is
normally installed only when the script contains one or more mouse hotkeys. It is also installed for
hotstrings, but that can be disabled via #Hotstring NoMouse.
By contrast, the #InstallMouseHook directive will unconditionally install the mouse hook, which might
be useful to allow KeyHistory to monitor mouse clicks.
You can determine whether a script is using the hook via the KeyHistory command or menu item. You
can determine which hotkeys are using the hook via the ListHotkeys command or menu item.
This directive also makes a script persistent, meaning that ExitApp should be used to terminate it.
Related
#InstallKeybdHook, #UseHook, Hotkey, #Persistent, KeyHistory, GetKeyState, KeyWait
Example
Keyboard Control
323
#InstallMouseHook
#KeyHistory
Sets the maximum number of keyboard and mouse events displayed by the KeyHistory window. You
can set it to 0 to disable key history.
#KeyHistory MaxEvents
Parameters
MaxEvents
The maximum number of keyboard and mouse events displayed by the
KeyHistory window. (default 40, limit 500). Specify 0 to disable key history
entirely.
Remarks
Because this setting is put into effect before the script begins running, it is only necessary to specify it
once (anywhere in the script).
Because each keystroke or mouse click consists of a down-event and an up-event, KeyHistory displays
only half as many "complete events" as specified here. For example, if the script contains
"#KeyHistory 50", up to 25 keystrokes and mouse clicks will be displayed.
Related
KeyHistory, #NoTrayIcon
Example
#KeyHistory 0 ; Disable key history.
#KeyHistory 100 ; Store up to 100 events.
BlockInput
Disables or enables the user's ability to interact with the computer via keyboard and mouse.
BlockInput, Mode
Parameters
Mode
Mode 1: One of the following words:
On: The user is prevented from interacting with the computer (mouse and
keyboard input has no effect).
Off: Input is re-enabled.
Mode 2 (has no effect on Windows 9x): This mode operates independently of
the other two. For example, BlockInput On will continue to block input until
BlockInput Off is used, even if one of the below is also in effect.
Send: The user's keyboard and mouse input is ignored while a Send or
SendRaw is in progress (the traditional SendEvent mode only). This prevents
the user's keystrokes from disrupting the flow of simulated keystrokes. When
the Send finishes, input is re-enabled (unless still blocked by a previous use of
BlockInput On).
Mouse: The user's keyboard and mouse input is ignored while a Click,
MouseMove, MouseClick, or MouseClickDrag is in progress (the traditional
SendEvent mode only). This prevents the user's mouse movements and clicks
Printed Documentation
324
from disrupting the simulated mouse events. When the mouse command
finishes, input is re-enabled (unless still blocked by a previous use of
BlockInput On).
SendAndMouse: A combination of the above two modes.
Default: Turns off both the Send and the Mouse modes, but does not change
the current state of input blocking. For example, if BlockInput On is currently
in effect, using BlockInput Default will not turn it off.
Mode 3 (has no effect on Windows 9x; requires v1.0.43.11+): This mode
operates independently of the other two. For example, if BlockInput On and
BlockInput MouseMove are both in effect, mouse movement will be blocked
until both are turned off.
MouseMove: The mouse cursor will not move in response to the user's
physical movement of the mouse (DirectInput applications are a possible
exception). When a script first uses this command, the mouse hook is installed
(if it is not already). In addition, the script becomes persistent, meaning that
ExitApp should be used to terminate it. The mouse hook will stay installed until
the next use of the Suspend or Hotkey command, at which time it is removed
if not required by any hotkeys or hotstrings (see #Hotstring NoMouse).
MouseMoveOff: Allows the user to move the mouse cursor.
Remarks
In preference to BlockInput, it is often better to use SendMode Input or SendMode Play so that
keystrokes and mouse clicks become uninterruptible. This is because unlike BlockInput, those modes
do not discard what the user types during the send; instead, those keystrokes are buffered and sent
afterward. Avoiding BlockInput also avoids the need to work around sticking keys as described in the
next paragraph.
If BlockInput becomes active while the user is holding down keys, it might cause those keys to
become "stuck down". This can be avoided by waiting for the keys to be released prior to turning
BlockInput on, as in this example:
^!p::
KeyWait Control ; Wait for the key to be released. Use one KeyWait for each of the hotkey's
modifiers.
KeyWait Alt
BlockInput On
; ... send keystrokes and mouse clicks ...
BlockInput Off
return
Input blocking is automatically and momentarily disabled whenever an ALT event is sent (then re-
enabled afterward).
The table below shows how BlockInput behavior varies depending on Windows' version; however,
pressing Ctrl+Alt+Del on any platform will re-enable input due to a Windows API feature.
Operating System "BlockI nput" Results

Windows 95 No effect.
Windows 98/Me
User input is blocked and AutoHotkey is unable to
simulate input.
Keyboard Control
325
Windows NT 4 (without
ServicePack 6)
No effect.
Windows NT 4 (with ServicePack
6)
User input is blocked but AutoHotkey can simulate
keystrokes and mouse clicks.
Windows 2000/XP
User input is blocked but AutoHotkey can simulate
keystrokes and mouse clicks.

Windows 98/Me: Although scripts are unable to send keystrokes and mouse clicks on these operating
systems during BlockInput, commands such as WinMove will still work. ControlSend might also work.
Certain types of hook hotkeys can still be triggered when BlockInput is on. Examples include
"MButton" (mouse hook) and "LWin & Space" (keyboard hook with explicit prefix rather than modifiers
"$#").
Input is automatically re-enabled when the script closes.
Related
SendMode, Send, Click, MouseMove, MouseClick, MouseClickDrag
Example
if A_OSType <> WIN32_WINDOWS ; i.e. it's not Windows 9x.
BlockInput, on
Run, notepad
WinWaitActive, Untitled - Notepad
Send, {F5} ; pastes time and date
BlockInput, off
ControlSend / ControlSendRaw
Sends simulated keystrokes to a window or control.
ControlSend [, Control, Keys, WinTitle, WinText, ExcludeTitle, ExcludeText]
ControlSendRaw: Same parameters as above.
Parameters
Control
Can be either ClassNN (the classname and instance number of the control) or
the name/text of the control, both of which can be determined via Window
Spy. When using name/text, the matching behavior is determined by
SetTitleMatchMode. If this parameter is blank or omitted, the target window's
topmost control will be used. If this parameter is ahk_parent, the keystrokes
will be sent directly to the control's parent window (see Automating Winamp
for an example).
To operate upon a control's HWND (window handle), leave the Control
parameter blank and specify ahk_id %ControlHwnd% for the WinTitle
parameter (this also works on hidden controls even when
DetectHiddenWindows is Off) . The HWND of a control is typically retrieved via
ControlGet Hwnd, MouseGetPos, or DllCall.
Keys
The sequence of keys to send (see the Send command for details). To send a
literal comma, escape it (`,). The rate at which characters are sent is
Printed Documentation
326
determined by SetKeyDelay.
Unlike the Send command, mouse clicks cannot be sent by ControlSend. Use
ControlClick for that.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the next 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
next 3 parameters are omitted, the active window will be used. To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a process identifier (PID), specify ahk_pid %VarContainingPID%. To use a
window group, specify ahk_group GroupName. To use a window's unique ID
number, specify ahk_id %VarContainingID%. The search can be narrowed by
specifying multiple criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
ControlSendRaw sends the keystrokes in the Keys parameter exactly as they appear rather than
translating {Enter} to an ENTER keystroke, ^c to Control-C, etc.
If the Control parameter is omitted, this command will attempt to send directly to the target window
by sending to its topmost control (which is often the correct one) or the window itself if there are no
controls. This is useful if a window does not appear to have any controls at all, or just for the
convenience of not having to worry about which control to send to.
By default, modifier keystrokes (Control, Alt, Shift, and Win) are sent as they normally would be by
the Send command. This allows command prompt and other console windows to properly detect
uppercase letters, control characters, etc. It may also improve reliability in other ways.
However, in some cases these modifier events may interfere with the active window, especially if the
user is actively typing during a ControlSend or if the Alt key is being sent (since Alt activates the
active window's menu bar). This can be avoided by explicitly sending modifier up and down events as
in this example:
ControlSend, Edit1, {Alt down}f{Alt up}, Untitled - Notepad
The method above also allows the sending of modifier keystrokes (Control/Alt/Shift/Win) while the
workstation is locked (protected by logon prompt).
BlockInput should be avoided when using ControlSend against a console window such as command
prompt. This is because it might prevent capitalization and modifier keys such as Control from working
properly.
The value of SetKeyDelay determines the speed at which keys are sent. If the target window does not
receive the keystrokes reliably, try increasing the press duration via the second parameter of
SetKeyDelay as in these examples:
SetKeyDelay, 10, 10
SetKeyDelay, 0, 10
SetKeyDelay, -1, 0
If the target control is an Edit control (or something similar), the following are usually more reliable
and faster than ControlSend:
Keyboard Control
327
Control, EditPaste, This text will be inserted at the caret position., ControlName, WinTitle
ControlSetText, ControlName, This text will entirely replace any current text., WinTitle
ControlSend is generally not capable of manipulating a window's menu bar. To work around this, use
WinMenuSelectItem. If that is not possible due to the nature of the menu bar, you could try to
discover the message that corresponds to the desired menu item by following the SendMessage
Tutorial.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
SetKeyDelay, Control, ControlGet, ControlGetText, ControlMove, ControlGetPos, ControlClick,
ControlSetText, ControlFocus, Send, Automating Winamp
Examples
ControlSend, Edit1, This is a line of text in the notepad window., Untitled
SetTitleMatchMode, 2
ControlSend, , abc, cmd.exe ; Send directly to a command prompt window.
GetKeyState
Checks if a keyboard key or mouse/joystick button is down or up. Also retrieves joystick status.
GetKeyState, OutputVar, KeyName [, Mode]
KeyIsDown := GetKeyState("KeyName" [, "Mode"])
Parameters
OutputVar
The name of the variable in which to store the retrieved key state, which is
either D for down or U for up (but the GetKeyState() function returns true (1)
for down and false (0) for up). The variable will be empty (blank) if the state of
the key could not be determined.
The items below apply only to joysticks:
1) For a joystick axis such as JoyX, OutputVar will be set to a floating point
number between 0 and 100 to indicate the joystick's position as a percentage
of that axis's range of motion. The format of the number can be changed via
SetFormat. This test script can be used to analyze your joystick(s).
2) When KeyName is JoyPOV, the retrieved value will be between 0 and
35900. The following approximate POV values are used by many joysticks:
-1: no angle to report
0: forward POV
9000 (i.e. 90 degrees): right POV
27000 (i.e. 270 degrees): left POV
18000 (i.e. 180 degrees): backward POV
KeyName
This can be just about any single character from the keyboard or one of the
key names from the key list, such as a mouse/joystick button (though mouse
button state usually cannot be detected on Windows 95/98/Me). Examples: B,
5, LWin, RControl, Alt, Enter, Escape, LButton, MButton, Joy1.
Alternatively, an explicit virtual key code such as vkFF may be specified. This is
useful in the rare case where a key has no name. The virtual key code of such
a key can be determined by following the steps at the bottom fo the key list
Printed Documentation
328
page.
Mode
This parameter is ignored when retrieving joystick status.
If omitted, the mode will default to that which retrieves the logical state of the
key. This is the state that the OS and the active window believe the key to be
in, but is not necessarily the same as the physical state.
Alternatively, one of these letters may be specified:
P: Retrieve the physical state (i.e. whether the user is physically holding it
down). Under Windows Me/98/95, the physical state (Mode = P) of a key is
likely always the same as its logical state. Under Windows NT/2000/XP and
beyond, the physical state of a key or mouse button will usually be the same
as the logical state unless the keyboard and/or mouse hooks are installed, in
which case it will accurately reflect whether or not the user is physically
holding down the key or button (as long as it was pressed down while the
script was running). You can determine if your script is using the hooks via the
KeyHistory command or menu item. You can force the hooks to be installed by
adding the #InstallKeybdHook and/or #InstallMouseHook directives to the
script.
T: Retrieve the toggle state (only valid for keys that can be toggled such as
Capslock, Numlock, Scrolllock, and Insert). A retrieved value of D means the
key is "on", while U means it's "off" (but the GetKeyState() function returns
true (1) for "on" and false (0) for "off").
Retrieving the toggle state of the Insert key might work only on Windows
2000/XP or later.
On Windows 9x, retrieving the toggle state might be less reliable. For example,
immediately after the key is pressed, its new state might not be retrieved
correctly until after the display of a window that's associated with the script,
such as a MsgBox.
Remarks
To wait for a key or mouse/joystick button to achieve a new state, it is usually easier to use KeyWait
instead of a GetKeyState loop.
Systems with unusual keyboard drivers might be slow to update the state of their keys, especially the
toggle-state of keys like Capslock. A script that checks the state of such a key immediately after it
changed may use Sleep beforehand to give the system time to update the key state.
For examples of using GetKeyState with a joystick, see the joystick remapping page and the Joystick-
To-Mouse script.
Related
GetKeyState(), KeyWait, Key List, Joystick remapping, KeyHistory, #InstallKeybdHook,
#InstallMouseHook
Examples
; Basic examples:
GetKeyState, state, RButton ; Right mouse button.
GetKeyState, state, Joy2 ; The second button of the first joystick.

GetKeyState, state, Shift
Keyboard Control
329
if state = D
MsgBox At least one Shift key is down.
else
MsgBox Neither Shift key is down.

GetKeyState, state, CapsLock, T ; D if CapsLock is ON or U otherwise.
state := GetKeyState("Capslock", "T") ; True if CapsLock is ON, false otherwise.

; Remapping example (this is only for illustration because it would be easier to use
; the built-in remapping feature):
; In the following hotkey, the mouse button is kept held down while NumpadAdd is
; down, which effectively transforms NumpadAdd into a mouse button. This method
; can also be used to repeat an action while the user is holding down a key or button:
*NumpadAdd::
MouseClick, left,,, 1, 0, D ; Hold down the left mouse button.
Loop
{
Sleep, 10
GetKeyState, state, NumpadAdd, P
if state = U ; The key has been released, so break out of the loop.
break
; ... insert here any other actions you want repeated.
}
MouseClick, left,,, 1, 0, U ; Release the mouse button.
return

; Example: Make joystick button behavior depend on joystick axis position.
joy2::
GetKeyState, joyx, JoyX
if joyx > 75
MsgBox Action #1 (button pressed while joystick was pushed to the right).
else if joyx < 25
MsgBox Action #2 (button pressed while joystick was pushed to the left).
else
MsgBox Action #3 (button pressed while joystick was centered horizontally).
return

; See the joystick remapping page and the Joystick-To-Mouse script for other examples.
Printed Documentation
330
List of Keys, Mouse Buttons, and Joystick Controls
Mouse (mouse hotkeys require Windows NT/2000/XP or later)
LButton - the left mouse button
RButton - the right mouse button
MButton - the middle or wheel mouse button
WheelDown - this is equivalent to rotating the mouse wheel down (toward you)
WheelUp - the opposite of the above. When WheelDown/Up are used as hotkeys, A_EventInfo
contains the number of turns/notches.
Supported only in Windows 2000/XP or later:
XButton1 - a button that appears only on certain mice
XButton2 - a button that appears only on certain mice
Keyboard
Note: The names of the letter and number keys are the same as that single letter or digit.
For example: b is the "b" key and 5 is the "5" key.
Space - the spacebar
Tab
Enter (or Return)
Escape (or Esc)
Backspace (or BS)
Delete (or Del)
Insert (or Ins)
Home
End
PgUp
PgDn
Up
Down
Left
Right
ScrollLock
CapsLock
NumLock
NumpadDiv - the slash key
NumpadMult - the asterisk key
NumpadAdd - the plus key
NumpadSub - the minus key
NumpadEnter - the Enter key
The following keys are used when Numlock is OFF:
NumpadDel
NumpadIns
NumpadClear - same physical key as Numpad5 on most keyboards
NumpadUp
NumpadDown
NumpadLeft
NumpadRight
NumpadHome
NumpadEnd
NumpadPgUp
NumpadPgDn
Keyboard Control
331
The following keys are used when Numlock is ON:
Numpad0
Numpad1
Numpad2
Numpad3
Numpad4
Numpad5
Numpad6
Numpad7
Numpad8
Numpad9
NumpadDot - the decimal point (period) key
F1 through F24 - The 12 or more function keys at the top of most keyboards.
AppsKey - this is the key that invokes the right-click context menu.
LWin - the left windows key
RWin - the right windows key. Note: unlike Control/Alt/Shift, there is no generic/neutral "Win" key
because the OS does not support it.
Control (or Ctrl)
Alt
Shift
Note: For the most part, these next 6 keys are not supported by Windows 95/98/Me. Use the above
instead:
LControl (or LCtrl) - the left control key
RControl (or RCtrl) - the right control key
LShift
RShift
LAlt - the left Alt key
RAlt - Note: If your keyboard layout has AltGr instead of RAlt, you can probably use it as a hotkey
prefix via <^>! as described here. In addition, "LControl & RAlt::" would make AltGr itself into a
hotkey.
PrintScreen
CtrlBreak
Pause
Break -- Since this is synonymous with Pause, use ^CtrlBreak in hotkeys instead of ^Pause or
^Break.
Help - this probably doesn't exist on most keyboards. It's usually not the same as F1.
Sleep - note that the sleep key on some keyboards might not work with this.
The following exist only on Multimedia or Internet keyboards that have extra buttons or keys:
Browser_Back
Browser_Forward
Browser_Refresh
Browser_Stop
Browser_Search
Browser_Favorites
Browser_Home
Volume_Mute
Volume_Down
Volume_Up
Media_Next
Media_Prev
Media_Stop
Media_Play_Pause
Launch_Mail
Launch_Media
Printed Documentation
332
Launch_App1
Launch_App2
SCnnn (where nnn is the scan code of a key) - Recognizes unusual keys not mentioned above. See
Special Keys for details.
VKnn (where nn is the hexadecimal virtual key code of a key) - Although this rarely-used method is
supported in all versions, only in v1.0.38.02+ does it prevent certain types of hotkeys from requiring
the keyboard hook. For example, the following hotkey does not use the keyboard hook, but as a side-
effect it is triggered by pressing either Home or NumpadHome: ^VK24::MsgBox You pressed Home or
NumpadHome while holding down Control.
Joystick
Joy1 through Joy32: The buttons of the joystick. To help determine the button numbers for your
joystick, use this test script. Note that hotkey prefix symbols such as ^ (control) and + (shift) are not
supported (though GetKeyState can be used as a substitute). Also note that the pressing of joystick
buttons always "passes through" to the active window if that window is designed to detect the
pressing of joystick buttons.
Although the following Joystick control names cannot be used as hotkeys, they can be used with
GetKeyState:
JoyX, JoyY, and JoyZ: The X (horizontal), Y (vertical), and Z (altitude/depth) axes of the joystick.
JoyR: The rudder or 4th axis of the joystick.
JoyU and JoyV: The 5th and 6th axes of the joystick.
JoyPOV: The point-of-view (hat) control.
JoyName: The name of the joystick or its driver.
JoyButtons: The number of buttons supported by the joystick (not always accurate).
JoyAxes: The number of axes supported by the joystick.
JoyInfo: Provides a string consisting of zero or more of the following letters to indicate the joystick's
capabilities: Z (has Z axis), R (has R axis), U (has U axis), V (has V axis), P (has POV control), D (the
POV control has a limited number of discrete/distinct settings), C (the POV control is continous/fine).
Example string: ZRUVPD
Multiple Joysticks: If the computer has more than one and you want to use one beyond the first,
include the joystick number in front of the control name. For example, 2joy1 is the second joystick's
first button.
Note: If you have trouble getting a script to recognize your joystick, one person reported needing to
specify a joystick number other than 1 even though only a single joystick was present. It is unclear
how this situation arises or whether it is normal, but experimenting with the joystick number in the
joystick test script can help determine if this applies to your system.
See Also:
Joystick remapping: methods of sending keystrokes and mouse clicks with a joystick.
Joystick-To-Mouse script: using a joystick as a mouse.
Hand-held Remote Controls
Respond to signals from hand-held remote controls via the WinLIRC client script.
Special Keys
If your keyboard or mouse has a key not listed above, you might still be able to make it a hotkey by
using the following steps (requires Windows XP/2000/NT or later):
1. Ensure that at least one script is running that is using the keyboard hook. You can tell if a
script has the keyboard hook by opening its main window and selecting "View->Key history"
from the menu bar.
2. Double-click that script's tray icon to open its main window.
3. Press one of the "mystery keys" on your keyboard.
Keyboard Control
333
4. Select the menu item "View->Key history"
5. Scroll down to the bottom of the page. Somewhere near the bottom are the key-down and
key-up events for your key. NOTE: Some keys do not generate events and thus will not be
visible here. If this is the case, you cannot directly make that particular key a hotkey because
your keyboard driver or hardware handles it at a level too low for AutoHotkey to access. For
possible solutions, see further below.
6. If your key is detectible, make a note of the 3-digit hexadecimal value in the second column of
the list (e.g. 159).
7. To define this key as a hotkey, follow this example:
SC159:: ; Replace 159 with your key's value.
MsgBox, %A_ThisHotKey% was pressed.
return
Reverse direction: To remap some other key to become a "mystery key", follow this example:
; Replace 159 with the value discovered above. Replace FF (if needed) with the
; key's virtual key, which can be discovered in the first column of the Key History screen.
#c::Send {vkFFsc159}
Alternate solutions: If your key or mouse button is not detectible by the Key History screen, one of
the following might help:
1. Reconfigure the software that came with your mouse or keyboard (sometimes accessible in the Control Panel or Start Menu) to have the "mystery key"
send some other keystroke. Such a keystroke can then be defined as a hotkey in a script. For example, if you configure a mystery key to send Control+F1,
you can then indirectly make that key as a hotkey by using ^F1:: in a script.
2. Try searching the forum or asking for help there. There may be ways to detect certain keys and buttons using techniques such as DllCall, OnMessage, and
RegisterRawInputDevices.
3. The following is a last resort and generally should be attempted only in desperation. This is because the chance of success is low and it may cause
unwanted side-effects that are difficult to undo:
Disable or remove any extra software that came with your keyboard or mouse or change its driver to a more standard one such as the one built into the
OS. This assumes there is such a driver for your particular keyboard or mouse and that you can live without the features provided by its custom driver and
software.
KeyHistory
Displays script info and a history of the most recent keystrokes and mouse clicks.
KeyHistory
Remarks
This command is equivalent to selecting the "View->Key history" menu item in the main window.
To disable key history, specify the following line anywhere in the script:
#KeyHistory 0
#KeyHistory can also be used to change the maximum number of events that will be displayed.
This feature is intended to help debug scripts and hotkeys. It can also be used to detect the scan code
of a non-standard keyboard key using the steps described at the bottom of the key list page (knowing
the scan code allows such a key to be made into a hotkey).
The virtual key (VK) of the wheel events WheelDown and WheelUp are placeholder values that do not
have any meaning outside of AutoHotkey. Also, the scan code for wheel events is actually the number
of notches by which the wheel was turned (typically 1).
If the script does not have the keyboard hook installed, the KeyHistory window will display only the
keyboard events generated by the script itself (i.e. not the user's). If the script does not have the
mouse hook installed, mouse button events will not be shown. You can find out if your script uses
either hook via "View->Key History" in the script's main window (accessible via "Open" in the tray
icon). You can force the hooks to be installed by adding either or both of the following lines to the
Printed Documentation
334
script:
#InstallKeybdHook
#InstallMouseHook
Related
#KeyHistory, #InstallKeybdHook, #InstallMouseHook, ListHotkeys, ListLines, ListVars, GetKeyState,
KeyWait
Examples
KeyHistory ; Display the history info in a window.
KeyWait
Waits for a key or mouse/joystick button to be released or pressed down.
KeyWait, KeyName [, Options]
Parameters
KeyName
This can be just about any single character from the keyboard or one of the
key names from the key list, such as a mouse/joystick button. Joystick
attributes other than buttons are not supported.
An explicit virtual key code such as vkFF may also be specified. This is useful in
the rare case where a key has no name and produces no visible character
when pressed. Its virtual key code can be determined by following the steps at
the bottom fo the key list page.
Options
If this parameter is blank, the command will wait indefinitely for the specified
key or mouse/joystick button to be physically released by the user. However, if
the keyboard hook is not installed and KeyName is a keyboard key released
artificially by means such as the Send command, the key will be seen as
having been physically released. The same is true for mouse buttons when the
mouse hook is not installed.
Options: A string of one or more of the following letters (in any order, with
optional spaces in between):
D: Wait for the key to be pushed down.
L: Check the logical state of the key, which is the state that the OS and the
active window believe the key to be in (not necessarily the same as the
physical state). This option is ignored for joystick buttons.
T: Timeout (e.g. T3). The number of seconds to wait before timing out and
setting ErrorLevel to 1. If the key or button achieves the specified state, the
command will not wait for the timeout to expire. Instead, it will immediately
set ErrorLevel to 0 and the script will continue executing.
The timeout value can be a floating point number such as 2.5, but it should not
be a hexadecimal value such as 0x03.
ErrorLevel
ErrorLevel is set to 1 if the command timed out or 0 otherwise.
Remarks
Keyboard Control
335
Under Windows Me/98/95, the physical state of a key or mouse button will likely always be the same
as its logical state.
Under Windows NT/2k/XP and beyond, the physical state of a key or mouse button will usually be the
same as the logical state unless the keyboard and/or mouse hooks are installed, in which case it will
accurately reflect whether or not the user is physically holding down the key. You can determine if
your script is using the hooks via the KeyHistory command or menu item. You can force either or both
of the hooks to be installed by adding the #InstallKeybdHook and #InstallMouseHook directives to the
script.
While the command is in a waiting state, new threads can be launched via hotkey, custom menu item,
or timer.
Related
GetKeyState, Key List, KeyHistory, #InstallKeybdHook, #InstallMouseHook, ClipWait, WinWait
Examples
; Example #1: Basic usage:
KeyWait, a ; Wait for the A key to be released.
KeyWait, LButton, D ; Wait for the left mouse button to be pressed down.
KeyWait, Joy1, D T3 ; Wait up to 3 seconds for the first joystick button to be pressed down.
KeyWait, LAlt, L ; Wait for the left-alt key to be logically released.

; Example #2: A simple hotkey:
~Capslock::
KeyWait, Capslock ; Wait for user to physically release it.
MsgBox You pressed and released the Capslock key.
return

; Example #3: Remapping a key or mouse button (this is only for illustration because it
; would be easier to use the built-in remapping feature):
; The left mouse button is kept held down while NumpadAdd is down, which effectively
; transforms NumpadAdd into the left mouse button.
*NumpadAdd::
MouseClick, left,,, 1, 0, D ; Hold down the left mouse button.
KeyWait, NumpadAdd ; Wait for the key to be released.
MouseClick, left,,, 1, 0, U ; Release the mouse button.
return

; Example #4: Detects when a key has been double-pressed (similar to double-click).
; KeyWait is used to stop the keyboard's auto-repeat feature from creating an unwanted
; double-press when you hold down the RControl key to modify another key. It does this by
; keeping the hotkey's thread running, which blocks the auto-repeats by relying upon
Printed Documentation
336
; #MaxThreadsPerHotkey being at its default setting of 1.
; Note: There is a more elaborate script to distinguish between single, double, and
; triple-presses at the bottom of the SetTimer page.
~RControl::
if (A_PriorHotkey <> "~RControl" or A_TimeSincePriorHotkey > 400)
{
; Too much time between presses, so this isn't a double-press.
KeyWait, RControl
return
}
MsgBox You double-pressed the right control key.
return
Input
Waits for the user to type a string (not supported on Windows 9x: it does nothing).
Input [, OutputVar, Options, EndKeys, MatchList]
Parameters
OutputVar
The name of the variable in which to store the text entered by the user (by
default, artificial input is also captured).
If this and the other parameters are omitted, any Input in progress in another
thread is terminated and its ErrorLevel is set to the word NewInput. By
contrast, the ErrorLevel of the current command will be set to 0 if it terminated
a prior Input, or 1 if there was no prior Input to terminate.
OutputVar does not store keystrokes per se. Instead, it stores characters
produced by keystrokes according to the active window's keyboard
layout/language. Consequently, keystrokes that do not produce characters
(such as PageUp and Escape) are not stored (though they can be recognized
via the EndKeys parameter below).
Whitespace characters such as TAB (`t) are stored literally. ENTER is stored as
linefeed (`n).
Options
A string of zero or more of the following letters (in any order, with optional
spaces in between):
B: Backspace is ignored. Normally, pressing backspace during an Input will
remove the most recently pressed character from the end of the string. Note:
If the input text is visible (such as in an editor) and the arrow keys or other
means are used to navigate within it, backspace will still remove the last
character rather than the one behind the caret (insertion point).
C: Case sensitive. Normally, MatchList is not case sensitive (in versions prior to
1.0.43.03, only the letters A-Z are recognized as having varying case, not
letters like /).
I: Ignore input generated by any AutoHotkey script, such as the Send
command.
L: Length limit (e.g. L5). The maximum allowed length of the input. When the
Keyboard Control
337
text reaches this length, the Input will be terminated and ErrorLevel will be set
to the word Max unless the text matches one of the MatchList phrases, in
which case ErrorLevel is set to the word Match. If unspecified, the length limit
is 16383, which is also the absolute maximum.
M: Modified keystrokes such as Control-A through Control-Z are recognized
and transcribed if they correspond to real ASCII characters. Consider this
example, which recognizes Control-C:
Transform, CtrlC, Chr, 3 ; Store the character for Ctrl-C in the CtrlC
var.
Input, OutputVar, L1 M
if OutputVar = %CtrlC%
MsgBox, You pressed Control-C.
ExitApp
Note: The characters Ctrl-A through Ctrl-Z correspond to Chr(1) through
Chr(26). Also, the M option might cause some keyboard shortcuts such as Ctrl-
LeftArrow to misbehave while an Input is in progress.
T: Timeout (e.g. T3). The number of seconds to wait before terminating the
Input and setting ErrorLevel to the word Timeout. If the Input times out,
OutputVar will be set to whatever text the user had time to enter. This value
can be a floating point number such as 2.5.
V: Visible. Normally, the user's input is blocked (hidden from the system). Use
this option to have the user's keystrokes sent to the active window.
*: Wildcard (find anywhere). Normally, what the user types must exactly
match one of the MatchList phrases for a match to occur. Use this option to
find a match more often by searching the entire length of the input text.
EndKeys
A list of zero or more keys, any one of which terminates the Input when
pressed (the EndKey itself is not written to OutputVar). When an Input is
terminated this way, ErrorLevel is set to the word EndKey followed by a colon
and the name of the EndKey. Examples:
EndKey:.
EndKey:Escape
The EndKey list uses a format similar to the Send command. For example,
specifying {Enter}.{Esc} would cause either ENTER, period (.), or ESCAPE to
terminate the Input. To use the braces themselves as end keys, specify {{}
and/or {}}.
To use Control, Alt, or Shift as end-keys, specify the left and/or right version of
the key, not the neutral version. For example, specify {LControl}{RControl}
rather than {Control}.
Although modified keys such as Control-C (^c) are not supported, certain keys
that require the shift key to be held down -- namely punctuation marks such
as ?!:@&{} -- are supported in v1.0.14+.
An explicit virtual key code such as {vkFF} may also be specified. This is useful
in the rare case where a key has no name and produces no visible character
when pressed. Its virtual key code can be determined by following the steps at
the bottom fo the key list page.
MatchList
A comma-separated list of key phrases, any of which will cause the Input to be
terminated (in which case ErrorLevel will be set to the word Match). The
Printed Documentation
338
entirety of what the user types must exactly match one of the phrases for a
match to occur (unless the * option is present). In addition, any spaces or
tabs around the delimiting commas are significant, meaning that they
are part of the match string. For example, if MatchList is "ABC , XYZ ", the user
must type a space after ABC or before XYZ to cause a match.
Two consecutive commas results in a single literal comma. For example, the
following would produce a single literal comma at the end of string:
"string1,,,string2". Similarly, the following list contains only a single item with
a literal comma inside it: "single,,item".
Because the items in MatchList are not treated as individual parameters, the
list can be contained entirely within a variable. In fact, all or part of it must be
contained in a variable if its length exceeds 16383 since that is the maximum
length of any script line. For example, MatchList might consist of
%List1%,%List2%,%List3% -- where each of the variables contains a large
sub-list of match phrases.
ErrorLevel
1 or 0
Whenever the command is used without parameters, ErrorLevel is set to 0 if it
successfully terminates a prior input, or 1 if there is no Input in progress.
NewInput The Input was interrupted by another thread that used the Input command.
Max
The Input reached the maximum allowed length and it does not match any of
the items in MatchList.
Timeout The Input timed out.
Match The Input matches one of the items in MatchList.
EndKey:name
One of the EndKeys was pressed to terminate the Input. In this case,
ErrorLevel contains the word EndKey followed by a colon and the name of the
terminating key without braces, e.g. EndKey:Enter, EndKey:Escape, etc.
Remarks
If this command is used while an Input is already in progress in another thread, that Input will be
terminated and its ErrorLevel will be set to the word NewInput. After that (if parameters were given),
the new Input will commence.
While an Input is in progress, new threads such as custom menu items and timed subroutines can still
be created. Similarly, keyboard hotkeys are still in effect if the Input is visible. If the Input is not
visible, only hook hotkeys can be triggered.
When a script first uses this command, the keyboard hook is installed (if it is not already). In addition,
the script becomes persistent, meaning that ExitApp should be used to terminate it. The keyboard
hook will stay installed until the next use of the Suspend or Hotkey command, at which time it is
removed if not required by any hotkeys or hotstrings.
If you use multiple languages or keyboard layouts, Input uses the keyboard layout of the active
window rather than the script's (regardless of whether the Input is visible). However, in versions prior
to 1.0.44.03, the script's own layout is used.
Although not as flexible, hotstrings are generally easier to use than the Input command.
Input does nothing on Windows 9x (not even changing ErrorLevel and OutputVar). To detect Windows
9x, use A_OSType.
Related
Hotstrings, InputBox, #InstallKeybdHook, Threads, if var in/contains MatchList
Keyboard Control
339
Examples
; Wait for the user to press any key. Keys that produce no visible character -- such as
; the modifier keys, function keys, and arrow keys -- are listed as end keys so that they
; will be detected too.
Input, SingleKey, L1,
{LControl}{RControl}{LAlt}{RAlt}{LShift}{RShift}{LWin}{RWin}{AppsKey}{F1}{F2}{F3}{F4}{F5}
{F6}{F7}{F8}{F9}{F10}{F11}{F12}{Left}{Right}{Up}{Down}{Home}{End}{PgUp}{PgDn}{Del}{
Ins}{BS}{Capslock}{Numlock}{PrintScreen}{Pause}

; This is a working hotkey example. Since the hotkey has the tilde (~)
; prefix, its own keystroke will pass through to the active window
; (except on Win9x). Thus, if you type [btw (or one of the other match
; phrases) in any editor, the script will automatically perform an
; action of your choice (such as replacing the typed text):

~[::
Input, UserInput, V T5 L4 C, {enter}.{esc}{tab}, btw,otoh,fl,ahk,ca
if ErrorLevel = Max
{
MsgBox, You entered "%UserInput%", which is the maximum length of text.
return
}
if ErrorLevel = Timeout
{
MsgBox, You entered "%UserInput%" at which time the input timed out.
return
}
if ErrorLevel = NewInput
return
IfInString, ErrorLevel, EndKey:
{
MsgBox, You entered "%UserInput%" and terminated the input with %ErrorLevel%.
return
}
; Otherwise, a match was found.
SetKeyDelay, -1 ; Most editors can handle the fastest speed.
if UserInput = btw
Send, {backspace 4}by the way
else if UserInput = otoh
Printed Documentation
340
Send, {backspace 5}on the other hand
else if UserInput = fl
Send, {backspace 3}Florida
else if UserInput = ca
Send, {backspace 3}California
else if UserInput = ahk
Run, www.autohotkey.com
return
Send / SendRaw / SendInput / SendPlay / SendEvent: Send Keys & Clicks
Sends simulated keystrokes and mouse clicks to the active window.
Send Keys
SendRaw Keys
SendInput Keys
SendPlay Keys
SendEvent Keys
Parameters
Keys
The sequence of keys to send. As with other commands, the comma in front of
the first parameter is optional.
SendRaw sends the keystrokes exactly as they appear rather than translating {Enter} to an ENTER
keystroke, ^c to Control-C, etc. To use raw mode with SendInput, SendPlay, or SendEvent, use
{Raw} instead; for example: SendInput {Raw}abc
In contrast to SendRaw, the other Send commands treat the following characters as modifiers (these
modifiers affect only the very next key):
!: Sends an ALT keystroke. For example, Send This is text!a would send the keys "This is text" and
then press ALT+a. Note: !A produces a different effect in some programs than !a. This is because !A
presses ALT+SHIFT+A and !a presses ALT+a. If in doubt, use lowercase.
+: Sends a SHIFT keystroke. For example, Send +abC would send the text "AbC", and Send !+a
would press ALT+SHIFT+a.
^: Sends a CONTROL keystroke. For example, Send ^!a would press CTRL+ALT+a, and Send
^{Home} would send CONTROL+HOME. Note: ^A produces a different effect in some programs than
^a. This is because ^A presses CONTROL+SHIFT+A and ^a presses CONTROL+a. If in doubt, use
lowercase.
#: Sends a WIN keystroke, therefore Send #e would hold down the Windows key and then press the
letter "e".

SendInput and SendPlay [v1.0.43+]: 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 SendInput and SendPlay below.
SendEvent [v1.0.43+]: 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. By default, Send is
synonymous SendEvent; but it can be made a synonym for SendInput or SendPlay via SendMode.
The following table lists the special keys that can be sent (each key name must be enclosed in
braces):
Keyboard Control
341
Key Name Resulting Keystroke
{F1} - {F24}
Function keys. For
example: {F12} is the
F12 key.
{!} !
{#} #
{+} +
{^} ^
{{} {
{}} }
{Enter}
ENTER key on the
main keyboard
{Escape} or {Esc} ESCAPE
{Space}
SPACE (this is only
needed for spaces
that appear either at
the beginning or the
end of the string to be
sent -- ones in the
middle can be literal
spaces)
{Tab} TAB
{Backspace} or {BS} Backspace
{Delete} or {Del} Delete
{Insert} or {Ins} Insert
{Up}
Up-arrow key on main
keyboard
{Down}
Down-arrow down key
on main keyboard
{Left}
Left-arrow key on
main keyboard
{Right}
Right-arrow key on
main keyboard
{Home}
Home key on main
keyboard
{End}
End key on main
keyboard
{PgUp}
Page-up key on main
keyboard
{PgDn}
Page-down key on
main keyboard

{CapsLock}
CapsLock (using
SetCapsLockState is
more reliable on
Printed Documentation
342
NT/2k/XP)
{ScrollLock}
ScrollLock (see also:
SetScrollLockState)
{NumLock}
NumLock (see also:
SetNumLockState)

{Control} or {Ctrl}
CONTROL (technical
info: sends the neutral
virtual key but the left
scan code)
{LControl} or {LCtrl}
Left CONTROL key
(technical info: same
as CONTROL for
Win9x, but on
NT/2k/XP it sends the
left virtual key rather
than the neutral one)
{RControl} or {RCtrl} Right CONTROL key
{Control Down} or {Ctrl Down}
Holds the CONTROL
key down until {Ctrl
Up} is sent.
XP/2000/NT: To hold
down the left or right
key instead, use
{RCtrl Down} and
{RCtrl Up}.

{Alt}
ALT (technical info:
sends the neutral
virtual key but the left
scan code)
{LAlt}
Left ALT key
(technical info: same
as ALT for Win9x, but
on NT/2k/XP it sends
the left virtual key
rather than the
neutral one)
{RAlt}
Right ALT key (or
AltGr, depending on
keyboard layout)
{Alt Down}
Holds the ALT key
down until {Alt Up} is
sent. XP/2000/NT: To
hold down the left or
right key instead, use
{RAlt Down} and
{RAlt Up}.

{Shift} SHIFT (technical info:
Keyboard Control
343
sends the neutral
virtual key but the left
scan code)
{LShift}
Left SHIFT key
(technical info: same
as SHIFT for Win9x,
but on NT/2k/XP it
sends the left virtual
key rather than the
neutral one)
{RShift} Right SHIFT key
{Shift Down}
Holds the SHIFT key
down until {Shift Up}
is sent. XP/2000/NT:
To hold down the left
or right key instead,
use {RShift Down}
and {RShift Up}.

{LWin} Left Windows key
{RWin} Right Windows key
{LWin Down}
Holds the left
Windows key down
until {LWin Up} is
sent
{RWin Down}
Holds the right
Windows key down
until {RWin Up} is
sent

{AppsKey}
Windows App key
(invokes the right-
click or context menu)
{Sleep} Computer SLEEP key.
{ASC nnnnn}
Sends an ALT+nnnnn
keypad combination,
which can be used to
generate special
characters that don't
exist on the keyboard.
To generate ASCII
characters, specify a
number between 1
and 255. To generate
ANSI characters
(standard in most
languages), specify a
number between 128
and 255, but precede
it with a leading zero,
e.g. {Asc 0133}.
Printed Documentation
344
To generate Unicode
characters, specify a
number between 256
and 65535 (without a
leading zero).
However, this is not
supported by all
applications.
Therefore, for greater
compatibility and
easier sending of long
Unicode strings, use
"Transform Unicode".
{vkXX}
{scYYY}
{vkXXscYYY}
Sends a keystroke
that has virtual key
XX and scan code YYY.
For example: Send
{vkFFsc159}. If the sc
or vk portion is
omitted, the most
appropriate value is
sent in its place.
The values for XX and
YYY are hexadecimal
and can usually be
determined from the
main window's View-
>Key history menu
item. See also:
Special Keys

{Numpad0} - {Numpad9}
Numpad digit keys (as
seen when Numlock is
ON). For example:
{Numpad5} is the
digit 5.
{NumpadDot}
Numpad Period (as
seen when Numlock is
ON).
{NumpadEnter} Enter key on keypad
{NumpadMult} Numpad Multiply
{NumpadDiv} Numpad Divide
{NumpadAdd} Numpad Add
{NumpadSub} Numpad Subtract

{NumpadDel}
Delete key on keypad
(this key and the
following Numpad
keys are used when
Numlock is OFF)
Keyboard Control
345
{NumpadIns} Insert key on keypad
{NumpadClear}
Clear key on keypad
(usually the '5' key
when Numlock is
OFF).
{NumpadUp}
Up-arrow key on
keypad
{NumpadDown}
Down-arrow key on
keypad
{NumpadLeft}
Left-arrow key on
keypad
{NumpadRight}
Right-arrow key on
keypad
{NumpadHome} Home key on keypad
{NumpadEnd} End key on keypad
{NumpadPgUp}
Page-up key on
keypad
{NumpadPgDn}
Page-down key on
keypad

{Browser_Back}
2000/XP Only: Select
the browser "back"
button
{Browser_Forward}
2000/XP Only: Select
the browser "forward"
button
{Browser_Refresh}
2000/XP Only: Select
the browser "refresh"
button
{Browser_Stop}
2000/XP Only: Select
the browser "stop"
button
{Browser_Search}
2000/XP Only: Select
the browser "search"
button
{Browser_Favorites}
2000/XP Only: Select
the browser
"favorites" button
{Browser_Home}
2000/XP Only: Launch
the browser and go to
the home page
{Volume_Mute}
2000/XP Only: Mute
the volume. Usually
equivalent to
SoundSet, +1, , mute
{Volume_Down}
2000/XP Only: Reduce
the volume. Usually
equivalent to
Printed Documentation
346
SoundSet -5
{Volume_Up}
2000/XP Only:
Increase the volume.
Usually equivalent to
SoundSet +5
{Media_Next}
2000/XP Only: Select
next track in media
player
{Media_Prev}
2000/XP Only: Select
previous track in
media player
{Media_Stop}
2000/XP Only: Stop
media player
{Media_Play_Pause}
2000/XP Only:
Play/pause media
player
{Launch_Mail}
2000/XP Only: Launch
the email application
{Launch_Media}
2000/XP Only: Launch
media player
{Launch_App1}
2000/XP Only: Launch
user app1
{Launch_App2}
2000/XP Only: Launch
user app2

{PrintScreen} Print Screen
{CtrlBreak} Ctrl+break
{Pause} Pause

{Click [Options]}
[v1.0.43+]
Sends a mouse click
using the same
options available in
the Click command.
For example, {Click}
would click the left
mouse button once at
the mouse cursor's
current position, and
{Click 100, 200}
would click at
coordinates 100, 200
(based on
CoordMode). To move
the mouse without
clicking, specify 0
after the coordinates;
for example: {Click
100, 200, 0}. The
delay between mouse
clicks is determined
Keyboard Control
347
by SetMouseDelay
(not SetKeyDelay).
{WheelDown}, {WheelUp}, {LButton}, {RButton}, {MButton},
{XButton1}, {XButton2}
Sends a mouse button
event at the cursor's
current position (to
have control over
position and other
options, use {Click}
above). The delay
between mouse clicks
is determined by
SetMouseDelay.
{Blind}
[v1.0.40+]
When {Blind} is the
first item in the string,
the program avoids
releasing
Alt/Control/Shift/Win
if they started out in
the down position. For
example, the hotkey
+s::Send {Blind}abc
would send ABC
rather than abc
because the user is
holding down the Shift
key.
{Blind} also causes
SetStoreCapslockMode
to be ignored; that is,
the state of Capslock
is not changed.
Finally, {Blind} omits
the extra Control
keystrokes that would
otherwise be sent;
such keystrokes
prevent: 1) Start
Menu appearance
during LWin/RWin
keystrokes; 2) menu
bar activation during
Alt keystrokes.
Blind-mode is used
internally when
remapping a key. For
example, the
remapping a::b 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.
{Blind} is not
supported by
Printed Documentation
348
SendRaw and
ControlSendRaw.
Furthermore, it is not
completely supported
by SendPlay,
especially when
dealing with the
modifier keys
(Control, Alt, Shift,
and Win).
{Raw}
[v1.0.43+]
Sends the keystrokes
exactly as they appear
rather than translating
{Enter} to an ENTER
keystroke, ^c to
Control-C, etc.
Although the string
{Raw} need not occur
at the beginning of
the string, once
specified, it stays in
effect for the
remainder of the
string.
General Remarks
In addition to letters A through Z, the following letters and symbols are also supported (however, if
your system's code page is something other than 1252 [US & Western Europe], this list might be
different):


To repeat keys: 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
{
Keyboard Control
349
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.
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 SendInput or SendPlay 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 continuation section 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 Send ^!{Delete} will have no effect.
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 SendEvent under the conditions described below, it uses
SetKeyDelay -1, 0 (unless SendEvent's KeyDelay is "-1,-1", in which case "-1,-1" is used). When
SendInput reverts to SendPlay, 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 SendEvent (or SendPlay if SendMode InputThenPlay 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 AutoHotkey v1.0.43+, it will not revert in these cases, making it less reliable
than SendPlay/Event.
When SendInput sends mouse clicks by means such as {Click}, and CoordMode Mouse, Relative 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.
Windows 95 (and NT4 pre-SP3): SendInput is not supported and will automatically revert to
SendEvent (or SendPlay if SendMode InputThenPlay is in effect).
SendPlay [v1.0.43+]
SendPlay's biggest advantage is its ability to "play back" keystrokes and mouse clicks in a broader
variety of games than the other modes. For example, a particular game may accept hotstrings only
when they have the SendPlay option.
Of the three sending modes, SendPlay is the most unusual because it does not simulate keystrokes
and mouse clicks per se. Instead, it creates a series of events (messages) that flow directly to the
active window (similar to ControlSend, but at a lower level).
Printed Documentation
350
Like SendInput, SendPlay's keystrokes do not get interspersed with keystrokes typed by the user.
Thus, if the user happens to type something during a SendPlay, those keystrokes are postponed until
afterward.
Although SendPlay is considerably slower than SendInput, it is usually faster than the traditional
SendEvent mode (even when KeyDelay is -1).
SendPlay is unable to trigger system hotkeys that involve the two Windows keys (LWin and RWin). For
example, it cannot display the Start Menu or use Win-R to show the Run dialog.
The Windows keys (LWin and RWin) are automatically blocked during a SendPlay if the keyboard hook
is installed. This prevents the Start Menu from appearing if the user accidentally presses a Windows
key during the send. By contrast, keys other than LWin and RWin do not need to be blocked because
the operating system automatically postpones them until after the SendPlay (via buffering).
SendPlay does not use the standard settings of SetKeyDelay and SetMouseDelay. Instead, it defaults
to no delay at all, which can be changed as shown in the following examples:
SetKeyDelay, 0, 10, Play ; Note that both 0 and -1 are the same in SendPlay mode.
SetMouseDelay, 10, Play
SendPlay is unable to turn on or off the Capslock, Numlock, or Scroll-lock keys. Similarly, it is unable
to change a key's state as seen by GetKeyState unless the keystrokes are sent to one of the script's
own windows. Even then, any changes to the left/right modifier keys (e.g. RControl) can be detected
only via their neutral counterparts (e.g. Control).
Unlike SendInput and SendEvent, the user may interrupt a SendPlay by pressing Control-Alt-Del or
Control-Escape. When this happens, the remaining keystrokes are not sent but the script continues
executing as though the SendPlay had completed normally.
Although SendPlay can send LWin and RWin events, they are sent directly to the active window rather
than performing their native operating system function. To work around this, use SendEvent. For
example, SendEvent #r would show the Start Menu's Run dialog.
Unlike SendInput, SendPlay works even on Windows 95 and NT4-pre-SP3.
Related
SendMode, SetKeyDelay, SetStoreCapslockMode, ControlSend, BlockInput, Hotstrings, WinActivate
Examples
Send Sincerely,{enter}John Smith ; Types a two-line signature.
Send !fs ; Select the File->Save menu (Alt+F followed by S).
Send {End}+{Left 4} ; Jump to the end of the text then send four shift+left-arrow keystrokes.
SendInput {Raw}A long series of raw characters sent via the fastest method (SendInput).
SendMode [v1.0.43+]
Makes Send synonymous with SendInput or SendPlay rather than the default (SendEvent). Also
makes Click and MouseMove/Click/Drag use the specified method.
SendMode Input|Play|Event|InputThenPlay
The first parameter is one of the following words:
Event: This is the starting default used by all scripts. It uses the SendEvent method for Send,
SendRaw, Click, and MouseMove/Click/Drag.
Input: Switches to the SendInput method for Send, SendRaw, Click, and MouseMove/Click/Drag.
Known limitations:
Keyboard Control
351
Windows Explorer ignores SendInput's simulation of certain navigational hotkeys such as
Alt+LeftArrow. To work around this, use either SendEvent !{Left} or SendInput {Backspace}.
InputThenPlay [v1.0.43.02+]: Same as above except that rather than falling back to Event mode
when SendInput is unavailable, it reverts to Play mode (below). This also causes the SendInput
command itself to revert to Play mode when SendInput is unavailable.
Play: Switches to the SendPlay method for Send, SendRaw, Click, and MouseMove/Click/Drag. Known
limitations:
Characters that do not exist in the current keyboard layout (such as in English) cannot be
sent. To work around this, use SendEvent.
Simulated mouse dragging might have no effect in RichEdit controls (and possibly others) such
as those of WordPad and Metapad. To use an alternate mode for a particular drag, follow this
example: SendEvent {Click 6, 52, down}{Click 45, 52, up}
Simulated mouse wheel rotation might have no effect in applications such as MS Word and
Notepad. To use an alternate mode for a particular rotation, follow this example: SendEvent
{WheelDown 5}
When using SendMode Play in the auto-execute section (top part of the script), all remapped
keys are affected and might lose some of their functionality. See SendPlay remapping
limitations for details.
Remarks
Since SendMode also changes the mode of Click and MouseMove/Click/Drag, there may be times when
you wish to use a different mode for a particular mouse event. The easiest way to do this is via
{Click}. For example:
SendEvent {Click 100, 200} ; SendEvent uses the older, traditional method of clicking.
If SendMode is used in the auto-execute section (top part of the script), it also affects keyboard and
mouse remapping. In particular, if you use SendMode Play with remapping, see SendPlay remapping
limitations.
Every newly launched thread (such as a hotkey, custom menu item, or timed subroutine) starts off
fresh with the default setting for this command. That default may be changed by using this command
in the auto-execute section (top part of the script).
Related
Send, SetKeyDelay, SetMouseDelay, Click, MouseClick, MouseClickDrag, MouseMove
Examples
SendMode Input
SendMode InputThenPlay
SetKeyDelay
Sets the delay that will occur after each keystroke sent by Send and ControlSend.
SetKeyDelay [, Delay, PressDuration, Play]
Parameters
Delay
Time in milliseconds, which can be an expression. Use -1 for no delay at all
and 0 for the smallest possible delay (however, if the Play parameter is
present, both 0 and -1 produce no delay). Leave this parameter blank to
retain the current Delay.
Printed Documentation
352
PressDuration
Certain games and other specialized applications may require a delay inside
each keystroke; that is, after the press of the key but before its release.
Use -1 for no delay at all (default) and 0 for the smallest possible delay
(however, if the Play parameter is present, both 0 and -1 produce no delay).
Omit this parameter to leave the current PressDuration unchanged.
Note: PressDuration also produces a delay after any change to the modifier
key state (CTRL, ALT, SHIFT, and WIN) needed to support the keys being
sent.
This parameter can be an expression.
Play
[v1.0.43+]
The word Play applies the above settings to the SendPlay mode rather than
the traditional SendEvent mode. If a script never uses this parameter, the
delay is always -1/-1 for SendPlay.
Remarks
Note: SetKeyDelay is not obeyed by SendInput; there is no delay between keystrokes in that mode.
This same is true for Send when SendMode Input is in effect.
A short delay (sleep) is done automatically after every keystroke sent by Send or ControlSend. This is
done to improve the reliability of scripts because a window sometimes can't keep up with a rapid flood
of keystrokes.
Due to the granularity of the OS's time-keeping system, delays might be rounded up to the nearest
multiple of 10. For example, a delay between 1 and 10 (inclusive) is equivalent to 10 on Windows XP
(and probably NT & 2k).
For Send/SendEvent mode, a delay of 0 internally executes a Sleep(0), which yields the remainder of
the script's timeslice to any other process that may need it. If there is none, Sleep(0) will not sleep at
all. By contrast, a delay of -1 will never sleep. For better reliability, 0 is recommended as an
alternative to -1.
When the delay is set to -1, a script's process-priority becomes an important factor in how fast it can
send keystrokes when using the traditional SendEvent mode. To raise a script's priority, use Process,
Priority,, High. Although this typically causes keystrokes to be sent faster than the active window can
process them, the system automatically buffers them. Buffered keystrokes continue to arrive in the
target window after the Send command completes (even if the window is no longer active). This is
usually harmless because any subsequent keystrokes sent to the same window get queued up behind
the ones already in the buffer.
If unset, the default Delay for the tradional SendEvent mode is 10 (20 for .aut scripts). For SendPlay
mode, the default Delay is -1. The default PressDuration is -1 for both modes.
The built-in variable A_KeyDelay contains the current setting of Delay for Send/SendEvent mode.
There is no built-in variable for either PressDuration or SendPlay's Delay.
Every newly launched thread (such as a hotkey, custom menu item, or timed subroutine) starts off
fresh with the default setting for this command. That default may be changed by using this command
in the auto-execute section (top part of the script).
Related
Send, ControlSend, SendMode, SetMouseDelay, SetControlDelay, SetWinDelay, SetBatchLines, Click
Example
SetKeyDelay, 0
Keyboard Control
353
SetCapsLockState/SetNumLockState/SetScrollLockState
Sets the state of the Capslock/NumLock/ScrollLock key. Can also force the key to stay on or off.
SetCapsLockState [, State]
SetNumLockState [, State]
SetScrollLockState [, State]
Parameters
State
If this parameter is omitted, the AlwaysOn/Off attribute of the key is removed
(if present). Otherwise, specify one of the following words:
On: Turns on the key and removes the AlwaysOn/Off attribute of the key (if
present).
Off: Turns off the key and removes the AlwaysOn/Off attribute of the key (if
present).
AlwaysOn: Forces the key to stay on permanently (has no effect on Windows
9x).
AlwaysOff: Forces the key to stay off permanently (has no effect on Windows
9x).
Remarks
These commands are currently not 100% reliable on Windows Me/98/95 due to the limitations of
those OSes. As an alternative, a key can be reliably toggled to its opposite state on Win9x via the
Send command; for example: Send {Capslock}
Keeping a key AlwaysOn or AlwaysOff requires the keyboard hook, which will be automatically
installed in such cases.
Related
SetStoreCapslockMode, GetKeyState
Examples
SetNumlockState, on
SetScrollLockState, AlwaysOff
SetStoreCapslockMode
Whether to restore the state of CapsLock after a Send.
SetStoreCapslockMode, On|Off
Parameters
On|Off
On: This is the initial setting for all scripts: The CapsLock key will be restored
to its former value if Send needed to change it temporarily for its operation.
Off: The state of the CapsLock key is not changed at all. As a result, Send will
invert the case of the characters if Capslock happens to be ON during the
operation.
Remarks
Printed Documentation
354
This setting is not reliable under Windows Me/98/95 due to the limitations of those OSes. This means
that the Capslock key will not always be turned off for Send and ControlSend. Even when it is
successfully turned off, it might not get turned back on after the keys are sent.
This command is rarely used because the default behavior is best in most cases.
Every newly launched thread (such as a hotkey, custom menu item, or timed subroutine) starts off
fresh with the default setting for this command. That default may be changed by using this command
in the auto-execute section (top part of the script).
Related
SetCaps/Num/ScrollLockState, Send, ControlSend
Example
SetStoreCapslockMode, off

355
Math Commands
EnvAdd
Sets a variable to the sum of itself plus the given value (can also add or subtract time from a date-
time value). Synonymous with: var += value
EnvAdd, Var, Value [, TimeUnits]
Var += Value [, TimeUnits]
Var++
Parameters
Var The name of the variable upon which to operate.
Value
Any integer, floating point number, or expression. Expressions are not
supported when TimeUnits is present.
TimeUnits
If present, this parameter directs the command to add Value to Var, treating
Var as a date-time stamp in the YYYYMMDDHH24MISS format and treating
Value as the integer or floating point number of units to add (specify a
negative number to perform subtraction). TimeUnits can be either Seconds,
Minutes, Hours, or Days (or just the first letter of each of these).
If Var is an empty variable, the current time will be used in its place. If Var
contains an invalid timestamp or a year prior to 1601, or if Value is non-
numeric, Var will be made blank to indicate the problem.
The built-in variable A_Now contains the current local time in
YYYYMMDDHH24MISS format.
To calculate the amount of time between two timestamps, use EnvSub.
Remarks
This command is equivalent to the shorthand style: Var += Value
Variables can be increased or decreased by 1 by using Var++, Var--, ++Var, or --Var.
If either Var or Value is blank or does not start with a number, it is considered to be 0 for the purpose
of the calculation (except when using TimeUnits, see above).
If either Var or Value contains a decimal point, the end result will be a floating point number in the
format set by SetFormat.
Related
EnvSub, EnvMult, EnvDiv, SetFormat, Expressions, If var is [not] type, SetEnv, FileGetTime
Example
EnvAdd, MyCount, 2
MyCount += 2 ; Equivalent to above

var1 = ; Make it blank so that the below will use the current time instead.
var1 += 31, days
MsgBox, %var1% ; The answer will be the date 31 days from now.
Printed Documentation
356
EnvDiv
Sets a variable to itself divided by the given value. Synonymous with: var /= value
EnvDiv, Var, Value
Parameters
Var The name of the variable upon which to operate.
Value Any integer, floating point number, or expression.
Remarks
This command is equivalent to the shorthand style: Var /= Value
Division by zero will result in an error-message window when the script is loaded (if possible) or
during runtime otherwise.
If either Var or Value is blank or does not start with a number, it is considered to be 0 for the purpose
of the calculation.
If either Var or Value contains a decimal point, the end result will be a floating point number in the
format set by SetFormat. Otherwise, the result will be truncated (e.g. 19 divided by 10 will yield 1).
Related
EnvAdd, EnvSub, EnvMult, SetFormat, Expressions, If var is [not] type, SetEnv, bitwise operations
(Transform)
Example
EnvDiv, MyCount, 2
MyCount /= 2 ; Equivalent to above
EnvMult
Sets a variable to itself times the given value. Synonymous with: var *= value
EnvMult, Var, Value
Parameters
Var The name of the variable upon which to operate.
Value Any integer, floating point number, or expression.
Remarks
This command is equivalent to the shorthand style: Var *= Value
If either Var or Value is blank or does not start with a number, it is considered to be 0 for the purpose
of the calculation.
If either Var or Value contains a decimal point, the end result will be a floating point number in the
format set by SetFormat.
Related
EnvAdd, EnvSub, EnvDiv, SetFormat, Expressions, If var is [not] type, SetEnv, bitwise operations
(Transform)
Math Commands
357
Example
EnvMult, MyCount, 2
MyCount *= 2 ; Equivalent to above
EnvSub
Sets a variable to itself minus the given value (can also compare date-time values). Synonymous
with: var -= value
EnvSub, Var, Value [, TimeUnits]
Var -= Value [, TimeUnits]
Var--
Parameters
Var The name of the variable upon which to operate.
Value
Any integer, floating point number, or expression. Expressions are not
supported when TimeUnits is present.
TimeUnits
If present, this parameter directs the command to subtract Value from Var as
though both of them are date-time stamps in the YYYYMMDDHH24MISS
format. TimeUnits can be either Seconds, Minutes, Hours, or Days (or just the
first letter of each of these). If Value is blank, the current time will be used in
its place. Similarly, if Var is an empty variable, the current time will be used in
its place.
The result is always rounded down to the nearest integer. For example, if the
actual difference between two timestamps is 1.999 days, it will be reported as
1 day. If higher precision is needed, specify Seconds for TimeUnits and divide
the result by 60.0, 3600.0, or 86400.0.
If either Var or Value is an invalid timestamp or contains a year prior to 1601,
Var will be made blank to indicate the problem.
The built-in variable A_Now contains the current local time in
YYYYMMDDHH24MISS format.
To precisely determine the elapsed time between two events, use the
A_TickCount method because it provides millisecond precision.
To add or subtract a certain number of seconds, minutes, hours, or days from
a timestamp, use EnvAdd (subtraction is achieved by adding a negative
number).
Remarks
This command is equivalent to the shorthand style: Var -= Value
Variables can be increased or decreased by 1 by using Var++, Var--, ++Var, or --Var.
If either Var or Value is blank or does not start with a number, it is considered to be 0 for the purpose
of the calculation (except when using TimeUnits; see above).
If either Var or Value contains a decimal point, the end result will be a floating point number in the
format set by SetFormat.
Related
EnvAdd, EnvMult, EnvDiv, SetFormat, Expressions, If var is [not] type, SetEnv, FileGetTime
Printed Documentation
358
Example
EnvSub, MyCount, 2
MyCount -= 2 ; Equivalent to above

var1 = 20050126
var2 = 20040126
EnvSub, var1, %var2%, days
MsgBox, %var1% ; The answer will be 366 since 2004 is a leap year.
if (expression)
Specifies the command(s) to perform if an expression evaluates to TRUE.
if (expression)
Remarks
An if-statement that contains an expression is differentiated from a traditional-if such as If FoundColor
<> Blue by making the character after the word "if" an open-parenthesis. Although this is usually
accomplished by enclosing the entire expression in parentheses, it can also be done with something
like if (x > 0) and (y > 0). In addition, the open-parenthesis may be omitted entirely if the first item
after the word "if" is a function call or an operator such as "not" or "!".
When an IF or an ELSE owns more than one line, those lines must be enclosed in braces. However, if
only one line belongs to an IF or ELSE, the braces are optional. See the examples below.
In v1.0.41+, the One True Brace (OTB) style may optionally be used with if-statements that are
expressions (but not traditional if-statements). For example:
if (x < y) {
...
}
if WinExist("Untitled - Notepad") {
WinActivate
}
if IsDone {
...
} else {
...
}
Unlike an "else" statement -- which supports any type of statement immediately to its right -- an if-
statement supports only a "{" to its right.
On a related note, the command "if var [not] between LowerBound and UpperBound" checks whether
a variable is between two values, and "if var [not] in value1,value2" can be used to check whether a
variable's contents exist within a list of values.
Related
Math Commands
359
Expressions, Assign expression (:=), if var in/contains MatchList, if var between, IfInString, Blocks,
Else
Example
if (A_Index > 100 or Done)
return

if (A_TickCount - StartTime > 2*MaxTime + 100)
{
MsgBox Too much time has passed.
ExitApp
}

if (Color = "Blue" or Color = "White")
{
MsgBox The color is one of the allowed values.
ExitApp
}
else if (Color = "Silver")
{
MsgBox Silver is not an allowed color.
return
}
else
{
MsgBox This color is not recognized.
ExitApp
}
If/IfEqual/IfNotEqual/IfLess/IfLessOrEqual/IfGreater/IfGreaterOrEqual
Specifies the command(s) to perform if the comparison of a variable to a value evalutes to TRUE.
When more than one command is present, enclose them in a block (braces).
IfEqual, var, value (same: if var = value)
IfNotEqual, var, value (same: if var <> value) (!= can be used in place of <>)
IfGreater, var, value (same: if var > value)
IfGreaterOrEqual, var, value (same: if var >= value)
IfLess, var, value (same: if var < value)
IfLessOrEqual, var, value (same: if var <= value)
If var ; If var's contents are blank or 0, it is considered false. Otherwise, it is true.

See also: IfInString
Parameters
Printed Documentation
360
var The variable name.
value
A literal string, number, or variable reference (e.g. %var2%). Value can be
omitted if you wish to compare var to an empty string (blank).
Remarks
If both var and value are purely numeric, they will be compared as numbers rather than as strings.
Otherwise, they will be compared alphabetically as strings (that is, alphabetical order will determine
whether var is greater, equal, or less than value).
When an IF or an ELSE owns more than one line, those lines must be enclosed in braces. For example:
if count <= 0
{
WinClose Untitled - Notepad
MsgBox There are no items present.
}
However, if only one line belongs to the IF or ELSE, the braces are optional.
Another command can only appear on the same line as the IF statement if you use the command-
name style. In other words, these are valid:
IfEqual, x, 1, Sleep, 1
IfGreater, x, 1, EnvAdd, x, 2
But these are not valid:
if x = 1 Sleep 1
IfGreater, x, 1, x += 2
The One True Brace (OTB) style may not be used with these types of if-statements. It can only be
used with expression if-statements.
On a related note, the command "if var [not] between LowerBound and UpperBound" checks whether
a variable is between two values, and "if var [not] in value1,value2" can be used to check whether a
variable's contents exist within a list of values.
Related
IF (expression), Assign expression (:=), if var in/contains MatchList, if var between, IfInString, Blocks,
Else
Example
if counter >= 1
Sleep, 10

if counter >=1 ; If an IF has more than one line, enclose those lines in braces:
{
WinClose, Untitled - Notepad
Sleep 10
}

Math Commands
361
if MyVar = %MyVar2%
MsgBox The contents of MyVar and MyVar2 are identical.
else if MyVar =
{
MsgBox, 4,, MyVar is empty/blank. Continue?
IfMsgBox, No
Return
}
else if MyVar <> ,
MsgBox The value in MyVar is not a comma.
else
MsgBox The value in MyVar is a comma.

if Done
MsgBox The variable Done is neither empty nor zero.
If var [not] between LowerBound and UpperBound
Checks whether a variable's contents are numerically or alphabetically between two values (inclusive).
if Var between LowerBound and UpperBound
if Var not between LowerBound and UpperBound
Parameters
Var The variable name whose contents will be checked.
LowerBound
To be within the specified range, Var must be greater than or equal to this
string, number, or variable reference.
UpperBound
To be within the specified range, Var must be less than or equal to this string,
number, or variable reference.
Remarks
If all three of the parameters are purely numeric, they will be compared as numbers rather than as
strings. Otherwise, they will be compared alphabetically as strings (that is, alphabetical order will
determine whether Var is within the specified range). In that case, "StringCaseSense On" can be used
to make the comparison case sensitive.
The operators "between", "is", "in", and "contains" are not supported in expressions.
Related
IfEqual/Greater/Less, if var in/contains MatchList, if var is type, IfInString, StringCaseSense, EnvAdd,
Blocks, Else
Example
if var between 1 and 5
MsgBox, %var% is in the range 1 to 5, inclusive.

Printed Documentation
362
if var not between 0.0 and 1.0
MsgBox %var% is not in the range 0.0 to 1.0, inclusive.

if var between blue and red
MsgBox %var% is alphabetically between blue and red.

LowerLimit = 1
UpperLimit = 10
InputBox, UserInput, Enter a number between %LowerLimit% and %UpperLimit%
if UserInput not between %LowerLimit% and %UpperLimit%
MsgBox Your input is not within the valid range.
If var is [not] type
Checks whether a variable's contents are numeric, uppercase, etc.
if var is type
if var is not type
Parameters
var The variable name.
type See the remarks below.
Remarks
Supported Types:
integer
True if var is non-empty and contains a purely numeric string (decimal or
hexadecimal) without a decimal point. Leading and trailing spaces and tabs are
allowed. The string may start with a plus or minus sign.
float
True if var is non-empty and contains a floating point number, that is, a purely
numeric string containing a decimal point. Leading and trailing spaces and tabs
are allowed. The string may start with a plus sign, minus sign, or decimal
point.
number
True if var contains an integer or floating point number (each of which is
described above).
digit
True if var is empty or contains only digits, which consist of the characters 0
through 9. Other characters such as the following are not allowed: spaces,
tabs, plus signs, minus signs, decimal points, hexadecimal digits, and the 0x
prefix.
xdigit
Hexadecimal digit: Same as digit except the characters A through F (uppercase
or lowercase) are also allowed. In v1.0.44.09+, a prefix of 0x is tolerated if
present.
alpha
True if var is empty or contains only alphabetic characters. False if there are
any digits, spaces, tabs, punctuation, or other non-alphabetic characters
anywhere in the string. For example, if var contains a space followed by a
letter, it is not considered to be alpha.
upper True if var is empty or contains only uppercase characters. False if there are
Math Commands
363
any digits, spaces, tabs, punctuation, or other non-uppercase characters
anywhere in the string.
lower
True if var is empty or contains only lowercase characters. False if there are
any digits, spaces, tabs, punctuation, or other non-lowercase characters
anywhere in the string.
alnum Same as alpha except that characters 0 through 9 are also allowed.
space
True if var is empty or contains only whitespace, which consists of the
following characters: space (%A_Space%), tab (%A_Tab% or `t), linefeed
(`n), return (`r), vertical tab (`v), and formfeed (`f).
time
True if var contains a valid date-time stamp, which can be all or just the
leading part of the YYYYMMDDHH24MISS format. For example, a 4-digit string
such as 2004 is considered valid. Use StringLen to determine whether
additional time components are present.
Years less than 1601 are not considered valid because the operating system
generally does not support them. The maximum year considered valid is 9999.
The word DATE may be used as a substitute for the word TIME, with the same
result.
Note: The operators "between", "is", "in", and "contains" are not supported in expressions.
Related
%A_YYYY%, SetFormat, FileGetTime, IfEqual, if var in/contains MatchList, if var between, StringLen,
IfInString, StringUpper, EnvAdd, Blocks, Else
Example
if var is float
MsgBox, %var% is a floating point number.
else if var is integer
MsgBox, %var% is an integer.
if var is time
MsgBox, %var% is also a valid date-time.
Random
Generates a pseudo-random number.
Random, OutputVar [, Min, Max]
Random,, NewSeed
Parameters
OutputVar
The name of the variable in which to store the result. The format of stored
floating point numbers is determined by SetFormat.
Min
The smallest number that can be generated, which can be negative, floating
point, or an expression. If omitted, the smallest number will be 0. The lowest
allowed value is -2147483648 for integers, but floating point numbers have
no restrictions.
Max The largest number that can be generated, which can be negative, floating
Printed Documentation
364
point, or an expression. If omitted, the largest number will be 2147483647
(which is also the largest allowed integer value -- but floating point numbers
have no restrictions).
NewSeed
[v1.0.42.03+]
Reseeds the random number generator with NewSeed (which can be an
expression). This affects all subsequently generated random numbers.
NewSeed should be an integer between 0 and 4294967295 (0xFFFFFFFF).
Reseeding can improve the quality/security of generated random numbers,
especially when NewSeed is a genuine random number rather than one of
lesser quality such as a pseudo-random number. Generally, reseeding does
not need to be done more than once.
If reseeding is never done by the script, the seed starts off as the low-order
32-bits of the 64-bit value that is the number of 100-nanosecond intervals
since January 1, 1601. This value travels from 0 to 4294967295 every ~7.2
minutes.
Remarks
This command creates a pseudo-randomly generated number, which is a number that simulates a true
random number but is really a number based on a complicated formula to make
determination/guessing of the next number extremely difficult.
If either Min or Max contains a decimal point, the end result will be a floating point number in the
format set by SetFormat. Otherwise, the result will be an integer.
Related
SetFormat
Example
Random, rand, 1, 10
Random, rand, 0.0, 1.0
Comments based on the original source
This function uses the Mersenne Twister random number generator, MT19937, written by Takuji
Nishimura and Makoto Matsumoto, Shawn Cokus, Matthe Bellew and Isaku Wada.
The Mersenne Twister is an algorithm for generating random numbers. It was designed with
consideration of the flaws in various other generators. The period, 2
19937
-1, and the order of
equidistribution, 623 dimensions, are far greater. The generator is also fast; it avoids multiplication
and division, and it benefits from caches and pipelines. For more information see the inventors' web
page at http://www.math.keio.ac.jp/~matumoto/emt.html
Copyright (C) 1997 - 2002, Makoto Matsumoto and Takuji Nishimura, All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted
provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions
and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of
conditions and the following disclaimer in the documentation and/or other materials provided
with the distribution.
3. The names of its contributors may not be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
Math Commands
365
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
Do NOT use for CRYPTOGRAPHY without securely hashing several returned values together, otherwise
the generator state can be learned after reading 624 consecutive values.
When you use this, send an email to: [email protected] with an appropriate reference to
your work. It would be nice to CC: [email protected] and [email protected] when
you write.
This above has been already been done for AutoHotkey, but if you use the Random command in a
publicly distributed application, consider sending an e-mail to the above people to thank them.
SetFormat
Sets the format of integers and floating point numbers generated by math operations.
SetFormat, NumberType, Format
Parameters
NumberType Must be either INTEGER or FLOAT.
Format
For NumberType INTEGER, this parameter must be H or HEX for hexadecimal,
or D for decimal. Hexadecimal numbers all start with the prefix 0x (e.g. 0xFF).
For NumberType FLOAT, this parameter is TotalWidth.DecimalPlaces (e.g. 0.6).
TotalWidth is typically 0 to indicate that number should not have any blank or
zero padding. If a higher value is used, numbers will be padded with spaces or
zeroes (see below) to make them that wide.
DecimalPlaces is the number of decimal places to display (rounding will occur).
If blank or zero, neither a decimal portion nor a decimal point will be
displayed, that is, the number will be stored as an integer rather than a
floating point number.
Padding: If TotalWidth is high enough to cause padding, spaces will be added
on the left side; that is, each number will be right-justified. To use left-
justification instead, precede TotalWidth with a minus sign. To pad with zeroes
instead of spaces, precede TotalWidth with a zero.
Remarks
If this command is not used in a script, integers default to decimal format, and floating point numbers
default to TotalWidth.DecimalPlaces = 0.6. Every newly launched thread (such as a hotkey, custom
menu item, or timed subroutine) starts off fresh with the default setting for this command. That
default may be changed by using this command in the auto-execute section (top part of the script).
You can determine whether a variable contains a numeric value by using "if var is
number/integer/float"
A variable containing an integer can be forced into the current integer format (hex or decimal) by
adding zero to it; for example: Var += 0. Similarly, a variable containing a floating point number (or
an integer, for that matter) can be forced into the current floating point format by adding 0.0 to it; for
Printed Documentation
366
example: Var += 0.0. However, to convert a floating point number into an integer, it is easier to use
Round(), Ceil(), or Floor().
The built-in variable A_FormatInteger contains the current integer format (H or D). A_FormatFloat
contains the current floating point format.
To pad an integer with zeros or spaces without having to use floating point math on it, follow this
example:
Var := " " . Var ; The quotes contain 10 spaces. To pad with zeros, substitute zeros
for the spaces.
StringRight, Var, Var, 10 ; This pads the number in Var with enough spaces to make its total
width 10 characters.
Floating Point Format
Since AutoHotkey stores all variables as strings, the stored precision of floating point numbers is
determined by DecimalPlaces. In other words, once a variable is rounded off, the extra precision is lost
and cannot be reclaimed without redoing the calculation using a higher value of DecimalPlaces.
Any leading or trailing spaces (i.e. padding) in a floating point value will be lost if that value is
explicitly assigned to another variable. Use the colon-equals operator (:=) or AutoTrim to prevent this.
For the current float format to take effect in a math operation such as addition, at least one of the
inputs must contain a decimal point.
A variable containing an integer can be "converted" into a floating point number by adding 0.0 to it,
e.g. Var += 0.0. However, if the current float format specifies no DecimalPlaces, use this instead:
if Var is integer
Var = %Var%.0
Hexadecimal Format
Hexadecimal numbers all start with the prefix 0x (e.g. 0xA9). They can be used anywhere a numerical
value is expected. For example, Sleep 0xFF is equivalent to Sleep 255 regardless of the current
integer format set by SetFormat.
To convert an integer from decimal to hexadecimal, use this example (the converse can be used to
convert in the opposite direction):
SetFormat, integer, hex
VariableContainingAnInteger += 0
SetFormat, integer, d
Related
Expression assignment (:=), EnvAdd, EnvSub, EnvMult, EnvDiv, AutoTrim, if var is type
Example
Var = 11.333333
SetFormat, float, 6.2
Var -= 1 ; Sets Var to be 10.33 with one leading space because the total width is 6.
SetFormat, float, 0.2
Var += 1 ; Sets Var to be 11.33 with no leading spaces.

SetFormat, float, 06.0
Var += 0 ; Sets Var to be 000011
Math Commands
367

SetFormat, integer, hex
Var += 0 ; Sets Var to be 0xb
SetFormat, integer, d
Transform
Performs miscellaneous math functions, bitwise operations, and tasks such as ASCII/Unicode
conversion.
Transform, OutputVar, Cmd, Value1 [, Value2]
Parameters
OutputVar
The name of the variable in which to store the result of Cmd. SetFormat
determines whether integers are stored as hexadecimal or decimal.
Cmd,
Value1/2
See list below.
Cmd, Value1, Value2
The Cmd, Value1 and Value2 parameters are dependent upon each other and their usage is described
below.
Unicode [, String]: Retrieves or stores Unicode text on the clipboard. Note: The entire clipboard may
be saved and restored by means of ClipboardAll, which allows "Transform Unicode" to operate without
losing the original contents of the clipboard.
There are two modes of operation as illustrated in the following examples:
Transform, OutputVar, Unicode ; Retrieves the clipboard's Unicode text as a UTF-8 string.
Transform, Clipboard, Unicode, %MyUTF_String% ; Places Unicode text onto the clipboard.
In the second example above, a literal UTF-8 string may be optionally used in place of
%MyUTF_String%.
Use a hotkey such as the following to determine the UTF-8 string that corresponds to a given Unicode
string:
^!u:: ; Control+Alt+U hotkey.
MsgBox Copy some Unicode text onto the clipboard, then return to this window and press OK
to continue.
Transform, ClipUTF, Unicode
Clipboard = Transform, Clipboard, Unicode, %ClipUTF%`r`n
MsgBox The clipboard now contains the following line that you can paste into your script.
When executed, this line will cause the original Unicode string you copied to be placed onto
the clipboard:`n`n%Clipboard%
return
Notes: 1) Windows 95 requires the Microsoft Layer for Unicode to support this command (Windows
98/Me/NT4 or later have built-in support); 2) The "Send {ASC nnnnn}" command is an alternate way
to produce Unicode characters, but it does not work in all applications.

Asc, String: Retrieves the ASCII code (a number between 1 and 255) for the first character in String.
If String is empty, OutputVar will also be made empty. For example: Transform, OutputVar, Asc,
%VarContainingString%. Corresponding function: Asc(String).
Printed Documentation
368
Chr, Value1: Retrieves the single character corresponding to the ASCII code indicated by Value1. If
Value1 is not between 1 and 255 inclusive, OutputVar will be made blank to indicate the problem. For
example: Transform, OutputVar, Chr, 130. Corresponding function: Chr(Number).
Deref, String: Expands variable references and escape sequences contained inside other variables.
Any badly formatted variable references will be omitted from the expanded result. The same is true if
OutputVar is expanded into itself; in other words, any references to OutputVar inside String's variables
will be omitted from the expansion (note however that String itself can be %OutputVar%). In the
following example, if var1 contains the string "test" and var2 contains the literal string "%var1%",
OutputVar will be set to the string "test": Transform, OutputVar, deref, %var2%. Within a function,
each variable in String always resolves to a local variable unless there is no such variable, in which
case it resolves to a global variable (or blank if none).
HTML, String: Converts String into its HTML equivalent by translating characters whose ASCII values
are above 127 to their HTML names (e.g. becomes &pound;). In addition, the four characters "&<>
are translated to &quot;&amp;&lt;&gt;. Finally, each linefeed (`n) is translated to <br>`n (i.e. <br>
followed by a linefeed).
Mod, Dividend, Divisor: Retrieves the remainder of Dividend divided by Divisor. If Divisor is zero,
OutputVar will be made blank. Dividend and Divisor can both contain a decimal point. If negative,
Divisor will be treated as positive for the calculation. In the following example, the result is 2:
Transform, OutputVar, mod, 5, 3. Corresponding function: Mod(Dividend, Divisor).
Pow, Base, Exponent: Retrieves Base raised to the power of Exponent. Both Base and Exponent
may contain a decimal point. If Exponent is negative, OutputVar will be formatted as a floating point
number even if Base and Exponent are both integers. A negative Base combined with a fractional
Exponent such as 1.5 is not supported; it will cause OutputVar to be made blank. See also: **
operator.
Exp, N: Retrieves e (which is approximately 2.71828182845905) raised to the Nth power. N may be
negative and may contain a decimal point. Corresponding function: Exp(N).
Sqrt, Value1: Retrieves the square root of Value1. If Value1 is negative, OutputVar will be made
blank. Corresponding function: Sqrt(Number).
Log, Value1: Retrieves the logarithm (base 10) of Value1. If Value1 is negative, OutputVar will be
made blank. Corresponding function: Log(Number).
Ln, Value1: Retrieves the natural logarithm (base e) of Value1. If Value1 is negative, OutputVar will
be made blank. Corresponding function: Ln(Number).
Round, Value1 [, N]: If N is omitted, OutputVar will be set to Value1 rounded to the nearest integer.
If N is positive number, Value1 will be rounded to N decimal places. If N is negative, Value1 will be
rounded by N digits to the left of the decimal point. For example, -1 rounds to the ones place, -2
rounds to the tens place, and-3 rounds to the hundreds place. Note: Round does not remove trailing
zeros when rounding decimal places. For example, 12.333 rounded to one decimal place would
become 12.300000. This behavior can be altered by using something like SetFormat, float, 0.1 prior to
the operation (in fact, SetFormat might eliminate the need to use Round in the first place).
Corresponding function: Round(Number [, N]).
Ceil, Value1: Retrieves Value1 rounded up to the nearest integer. Corresponding function:
Ceil(Number).
Floor, Value1: Retrieves Value1 rounded down to the nearest integer. Corresponding function:
Floor(Number).
Abs, Value1: Retrieves the absolute value of Value1, which is computed by removing the leading
minus sign (dash) from Value1 if it has one. Corresponding function: Abs(Number).
Sin, Value1: Retrieves the trigonometric sine of Value1. Value1 must be expressed in radians.
Corresponding function: Sin(Number).
Cos, Value1: Retrieves the trigonometric cosine of Value1. Value1 must be expressed in radians.
Corresponding function: Cos(Number).
Math Commands
369
Tan, Value1: Retrieves the trigonometric tangent of Value1. Value1 must be expressed in radians.
Corresponding function: Tan(Number).
ASin, Value1: Retrieves the arcsine (the number whose sine is Value1) in radians. If Value1 is less
than -1 or greater than 1, OutputVar will be made blank. Corresponding function: ASin(Number).
ACos, Value1: Retrieves the arccosine (the number whose cosine is Value1) in radians. If Value1 is
less than -1 or greater than 1, OutputVar will be made blank. Corresponding function: ACos(Number).
ATan, Value1: Retrieves the arctangent (the number whose tangent is Value1) in radians.
Corresponding function: ATan(Number).

NOTE: Each of the following bitwise operations has a more concise bitwise operator for use in
expressions.
BitNot, Value1: Stores the bit-inverted version of Value1 in OutputVar (if Value1 is floating point, it
is truncated to an integer prior to the calculation). If Value1 is between 0 and 4294967295 (0xffffffff),
it will be treated as an unsigned 32-bit value. Otherwise, it is treated as a signed 64-bit value. In the
following example, the result is 0xfffff0f0 (4294963440): Transform, OutputVar, BitNot, 0xf0f
BitAnd, Value1, Value2: Retrieves the result of the bitwise-AND of Value1 and Value2 (floating point
values are truncated to integers prior to the calculation). In the following example, the result is 0xff00
(65280): Transform, OutputVar, BitAnd, 0xff0f, 0xfff0
BitOr, Value1, Value2: Retrieves the result of the bitwise-OR of Value1 and Value2 (floating point
values are truncated to integers prior to the calculation). In the following example, the result is 0xf0f0
(61680): Transform, OutputVar, BitOr, 0xf000, 0x00f0
BitXOr, Value1, Value2: Retrieves the result of the bitwise-EXCLUSIVE-OR of Value1 and Value2
(floating point values are truncated to integers prior to the calculation). In the following example, the
result is 0xff00 (65280): Transform, OutputVar, BitXOr, 0xf00f, 0x0f0f
BitShiftLeft, Value1, Value2: Retrieves the result of shifting Value1 to the left by Value2 bit
positions, which is equivalent to multiplying Value1 by "2 to the Value2th power" (floating point values
are truncated to integers prior to the calculation). In the following example, the result is 8: Transform,
OutputVar, BitShiftLeft, 1, 3
BitShiftRight, Value1, Value2: Retrieves the result of shifting Value1 to the right by Value2 bit
positions, which is equivalent to dividing Value1 by "2 to the Value2th power", truncating the
remainder (floating point values are truncated to integers prior to the calculation). In the following
example, the result is 2: Transform, OutputVar, BitShiftRight, 17, 3
Remarks
Sub-commands that accept numeric parameters can also use expressions for those parameters.
If either Value1 or Value2 is a floating point number, the following Cmds will retrieve a floating point
number rather than an integer: Mod, Pow, Round, and Abs. The number of decimal places retrieved is
determined by SetFormat.
To convert a radians value to degrees, multiply it by 180/pi (approximately 57.29578). To convert a
degrees value to radians, multiply it by pi/180 (approximately 0.01745329252).
The value of pi (approximately 3.141592653589793) is 4 times the arctangent of 1.
Related
SetFormat, Expressions, EnvMult, EnvDiv, StringLower, if var is type
Example
Transform, OutputVar, Asc, A ; Get the ASCII code of the letter A.
Printed Documentation
370
Var := expression
Evaluates an expression and stores the result in a variable.
Var := expression
Parameters
Var The name of the variable in which to store the result of expression.
Expression See expressions and the examples below for details.
Remarks
The := operator is optimized so that it performs just as quickly as the = operator for simple cases
such as the following:
x := y ; Same performance as x = %y%
x := 5 ; Same performance as x = 5.
x := "literal string" ; Same performance as x = literal string.
The words true and false are built-in constants containing 1 and 0. They can be used to make a script
more readable as in these examples:
CaseSensitive := false
ContinueSearch := true
It is possible to create an array with this command and any others that accept an OutputVar. This is
done by making OuputVar contain a reference to another variable, e.g. Array%i% := Var/100 + 5.
See Arrays for more information.
Related
Expressions, IF (expression), Functions, SetEnv, EnvSet, EnvAdd, EnvSub, EnvMult, EnvDiv, If, Arrays
Examples
Var := 3
Var := "literal string"
Var := Price * (1 - Discount/100)

Finished := not Done or A_Index > 100
if not Finished
{
FileAppend, %NewText%`n, %TargetFile%
return
}
else
ExitApp

371
Misc. Commands
#NoTrayIcon
Disables the showing of a tray icon.
#NoTrayIcon
Specifying this anywhere in a script will prevent the showing of a tray icon for that script when it is
launched (even if the script is compiled into an EXE).
If you use this for a script that has hotkeys, you might want to bind a hotkey to the ExitApp
command. Otherwise, there will be no easy way to exit the program (without restarting the computer
or killing the process). For example: #x::ExitApp
The tray icon can be made to disappear or reappear at any time during the execution of the script by
using the command menu, tray, Icon or menu, tray, NoIcon. The only drawback of using the menu,
tray, NoIcon at the very top of the script is that the tray icon might be briefly visible when the script is
first launched. To avoid that, use #NoTrayIcon instead.
The built-in variable A_IconHidden contains 1 if the tray icon is currently hidden or 0 otherwise.
Related
Menu, ExitApp
Example
#NoTrayIcon
#SingleInstance
Determines whether a script is allowed to run again when it is already running.
#SingleInstance [force|ignore|off]
Parameters
force|ignore|off
This parameter determines what happens when a script is launched while a
previous instance of itself is already running. If #SingleInstance is specified
by itself (with no parameter), a dialog box is displayed asking whether to
keep the old instance or replace it with the new one. Otherwise:
The word FORCE skips the dialog box and replaces the old instance
automatically, which is similar in effect to the Reload command.
The word IGNORE skips the dialog box and leaves the old instance running.
In other words, attempts to launch an already-running script are ignored.
The word OFF allows multiple instances of a script.
Remarks
A script containing hotkeys, hotstrings, #Persistent, OnMessage(), or Gui is single-instance by default.
This behavior can be disabled or modified as described above.
Related
Reload, #Persistent
Printed Documentation
372
Example
#SingleInstance force
#SingleInstance ignore
#SingleInstance off
AutoTrim
Determines whether "Var1 = %Var2%" statements omit spaces and tabs from the beginning and end
of Var2.
AutoTrim, On|Off
Parameters
On|Off
On: In a statement such as Var1 = %Var2%, tabs and spaces at the beginning
and end of a Var2 are omitted from Var1. This is the default.
Off: Such tabs and spaces are not omitted. However, any literal tab and
spaces (including `t) are omitted regardless of this setting. For example, the
statement Var1 = `t%Var2% always ignores the `t character. To prevent this,
use one of the following:
Var1 = %A_Tab%%Var2%%A_Space% ; AutoTrim must be OFF for
this to work.
Var1 := "`t" . Var2 . " " ; The setting of AutoTrim doesn't matter
because this is an expression.
Remarks
If this command is not used by a script, the setting defaults to ON.
The built-in variable A_AutoTrim contains the current setting (On or Off).
The built-in variables A_Space and A_Tab contain a single space and single tab character,
respectively.
AutoTrim does not affect expression assignments such as Var := " string ". In other words, leading
and trailing spaces and tabs are always retained in such cases.
Every newly launched thread (such as a hotkey, custom menu item, or timed subroutine) starts off
fresh with the default setting for this command. That default may be changed by using this command
in the auto-execute section (top part of the script).
Related
SetEnv
Examples
AutoTrim, off
NewVar1 = %OldVar% ; If OldVar contains leading and trailing spaces, NewVar will have them too.
NewVar2 = %A_Space% ; With AutoTrim off, a single space can be assigned this way.

Var1 := "`t" . Var2 . " " ; The setting of AutoTrim doesn't matter because this is an expression.
Misc. Commands
373
BlockInput
Disables or enables the user's ability to interact with the computer via keyboard and mouse.
BlockInput, Mode
Parameters
Mode
Mode 1: One of the following words:
On: The user is prevented from interacting with the computer (mouse and
keyboard input has no effect).
Off: Input is re-enabled.
Mode 2 (has no effect on Windows 9x): This mode operates independently of
the other two. For example, BlockInput On will continue to block input until
BlockInput Off is used, even if one of the below is also in effect.
Send: The user's keyboard and mouse input is ignored while a Send or
SendRaw is in progress (the traditional SendEvent mode only). This prevents
the user's keystrokes from disrupting the flow of simulated keystrokes. When
the Send finishes, input is re-enabled (unless still blocked by a previous use of
BlockInput On).
Mouse: The user's keyboard and mouse input is ignored while a Click,
MouseMove, MouseClick, or MouseClickDrag is in progress (the traditional
SendEvent mode only). This prevents the user's mouse movements and clicks
from disrupting the simulated mouse events. When the mouse command
finishes, input is re-enabled (unless still blocked by a previous use of
BlockInput On).
SendAndMouse: A combination of the above two modes.
Default: Turns off both the Send and the Mouse modes, but does not change
the current state of input blocking. For example, if BlockInput On is currently
in effect, using BlockInput Default will not turn it off.
Mode 3 (has no effect on Windows 9x; requires v1.0.43.11+): This mode
operates independently of the other two. For example, if BlockInput On and
BlockInput MouseMove are both in effect, mouse movement will be blocked
until both are turned off.
MouseMove: The mouse cursor will not move in response to the user's
physical movement of the mouse (DirectInput applications are a possible
exception). When a script first uses this command, the mouse hook is installed
(if it is not already). In addition, the script becomes persistent, meaning that
ExitApp should be used to terminate it. The mouse hook will stay installed until
the next use of the Suspend or Hotkey command, at which time it is removed
if not required by any hotkeys or hotstrings (see #Hotstring NoMouse).
MouseMoveOff: Allows the user to move the mouse cursor.
Remarks
In preference to BlockInput, it is often better to use SendMode Input or SendMode Play so that
keystrokes and mouse clicks become uninterruptible. This is because unlike BlockInput, those modes
do not discard what the user types during the send; instead, those keystrokes are buffered and sent
afterward. Avoiding BlockInput also avoids the need to work around sticking keys as described in the
next paragraph.
Printed Documentation
374
If BlockInput becomes active while the user is holding down keys, it might cause those keys to
become "stuck down". This can be avoided by waiting for the keys to be released prior to turning
BlockInput on, as in this example:
^!p::
KeyWait Control ; Wait for the key to be released. Use one KeyWait for each of the hotkey's
modifiers.
KeyWait Alt
BlockInput On
; ... send keystrokes and mouse clicks ...
BlockInput Off
return
Input blocking is automatically and momentarily disabled whenever an ALT event is sent (then re-
enabled afterward).
The table below shows how BlockInput behavior varies depending on Windows' version; however,
pressing Ctrl+Alt+Del on any platform will re-enable input due to a Windows API feature.
Operating System "BlockI nput" Results

Windows 95 No effect.
Windows 98/Me
User input is blocked and AutoHotkey is unable to
simulate input.
Windows NT 4 (without
ServicePack 6)
No effect.
Windows NT 4 (with ServicePack
6)
User input is blocked but AutoHotkey can simulate
keystrokes and mouse clicks.
Windows 2000/XP
User input is blocked but AutoHotkey can simulate
keystrokes and mouse clicks.

Windows 98/Me: Although scripts are unable to send keystrokes and mouse clicks on these operating
systems during BlockInput, commands such as WinMove will still work. ControlSend might also work.
Certain types of hook hotkeys can still be triggered when BlockInput is on. Examples include
"MButton" (mouse hook) and "LWin & Space" (keyboard hook with explicit prefix rather than modifiers
"$#").
Input is automatically re-enabled when the script closes.
Related
SendMode, Send, Click, MouseMove, MouseClick, MouseClickDrag
Example
if A_OSType <> WIN32_WINDOWS ; i.e. it's not Windows 9x.
BlockInput, on
Run, notepad
WinWaitActive, Untitled - Notepad
Send, {F5} ; pastes time and date
Misc. Commands
375
BlockInput, off
ClipWait
Waits until the clipboard contains data.
ClipWait [, SecondsToWait, 1]
Parameters
SecondsToWait
If omitted, the command will wait indefinitely. Otherwise, it will wait no
longer than this many seconds (can contain a decimal point or be an
expression). Specifying 0 is the same as specifying 0.5.
1
If this parameter is omitted, the command is more selective, waiting
specifically for text or files to appear ("text" includes anything that would
produce text when you paste into Notepad). If this parameter is 1 (can be
an expression), the command waits for data of any kind to appear on the
clipboard.
ErrorLevel
If the wait period expires, ErrorLevel will be set to 1. Otherwise (i.e. the clipboard contains data),
ErrorLevel is set to 0.
Remarks
It's better to use this command than a loop of your own that checks to see if this clipboard is blank.
This is because the clipboard is never opened by this command, and thus it performs better and
avoids any chance of interfering with another application that may be using the clipboard.
This command considers anything convertible to text (e.g. HTML) to be text. It also considers files,
such as those copied in an Explorer window via Control-C, to be text. Such files are automatically
converted to their filenames (with full path) whenever the clipboard variable (%clipboard%) is
referred to in the script. See Clipboard for details.
When 1 is present as the last parameter, the command will be satisified when any data appears on the
clipboard. This can be used in conjunction with ClipboardAll to save non-textual items such as
pictures.
While the command is in a waiting state, new threads can be launched via hotkey, custom menu item,
or timer.
Related
Clipboard, WinWait, KeyWait
Example
clipboard = ; Empty the clipboard
Send, ^c
ClipWait, 2
if ErrorLevel
{
MsgBox, The attempt to copy text onto the clipboard failed.
return
}
Printed Documentation
376
MsgBox, clipboard = %clipboard%
return
CoordMode
Sets coordinate mode for various commands to be relative to either the active window or the screen.
CoordMode, ToolTip|Pixel|Mouse|Caret|Menu [, Screen|Relative]
Parameters
Param1
ToolTip: Affects ToolTip.
Pixel: Affects PixelGetColor, PixelSearch, and ImageSearch.
Mouse: Affects MouseGetPos, Click, and MouseMove/Click/Drag.
Caret: Affects the built-in variables A_CaretX and A_CaretY.
Menu: Affects the "Menu Show" command when coordinates are specified for
it.
Param2
If Param2 is omitted, it defaults to Screen.
Screen: Coordinates are relative to the desktop (entire screen).
Relative: Coordinates are relative to the active window.
Remarks
If this command is not used, all commands except those documented otherwise (e.g. WinMove and
InputBox) use coordinates that are relative to the active window.
Every newly launched thread (such as a hotkey, custom menu item, or timed subroutine) starts off
fresh with the default setting for this command. That default may be changed by using this command
in the auto-execute section (top part of the script).
Related
Click, MouseMove, MouseClick, MouseClickDrag, MouseGetPos, PixelGetColor, PixelSearch, ToolTip,
Menu
Example
CoordMode, ToolTip, Screen ; Place ToolTips at absolute screen coordinates:
CoordMode, ToolTip ; Same effect as the above because "screen" is the default.
Critical [v1.0.38.04+]
Prevents the current thread from being interrupted by other threads.
Critical [, Off]
If the first parameter is omitted (or the word On), the current thread is made critical, meaning that it
cannot be interrupted by another thread. If the first parameter is the word Off, the current thread
immediately becomes interruptible, regardless of the settings of "Thread Interrupt".
Unlike high-priority threads, events that occur during a critical thread are not discarded. For example,
if the user presses a hotkey while the current thread is critical, the hotkey is buffered indefinitely until
the current thread finishes or becomes noncritical, at which time the hotkey is launched as a new
thread.
Misc. Commands
377
A critical thread will be interrupted in emergencies. Emergencies consist of the OnExit subroutine and
any OnMessage() function that monitors a message number less than 0x312. To avoid these
interruptions, temporarily disable such functions.
When buffered events are waiting to start new threads, using "Critical Off" will not result in an
immediate interruption of the current thread. Instead, an average of 5 milliseconds will pass before an
interruption occurs. This makes it more than 99.999% likely that at least one line after "Critical Off"
will execute before an interruption. You can force interruptions to occur immediately by means of a
delay such as a Sleep -1 or a WinWait for a window that does not yet exist.
In v1.0.40.01+, a critical thread becomes interruptible when a MsgBox or other dialog is displayed.
However, unlike "Thread Interrupt", the thread becomes critical again after the user dismisses the
dialog.
Because Critical is a thread-specific setting, when a critical thread ends, the underlying/resumed
thread (if any) will automatically be noncritical. Consequently, there is no need to do "Critical Off"
right before ending a thread.
If Critical is not used in the auto-execute section (top part of the script), all threads start off as
noncritical (though the settings of "Thread Interrupt" will still apply). By contrast, if the auto-execute
section turns on Critical but never turns it off, every newly launched thread (such as a hotkey, custom
menu item, or timed subroutine) starts off critical.
The command "Thread NoTimers" is similar to Critical except that it prevents interruptions from timers
only.
Related
Thread (command), Threads, #MaxThreadsPerHotkey, #MaxThreadsBuffer, OnMessage, Hotkey,
Menu, SetTimer
Example
#space:: ; Win+Space hotkey.
Critical
ToolTip No new threads will launch until after this ToolTip disappears.
Sleep 3000
ToolTip ; Turn off the tip.
return ; Returning from a hotkey subroutine ends the thread. Any underlying thread to be resumed is
noncritical by definition.
DllCall()
Calls a function inside a DLL, such as a standard Windows API function.
Result := DllCall("[DllFile\]Function" [, Type1, Arg1, Type2, Arg2, "Cdecl ReturnType"])
Parameters
Result
The actual value returned by the function. If the function is of a type that
does not return a value, the result is an undefined integer. If the function
cannot be called due to an error, the return value is blank (an empty
string).
[DllFile\]Function
The DLL or EXE file name followed by a backslash and the name of the
function. For example: "MyDLL\MyFunction" (the file extension ".dll" is the
default when omitted). If an absolute path isn't specified, DllFile is
assumed to be in the system's PATH or A_WorkingDir.
Printed Documentation
378
DllFile may be omitted when calling a function that resides in User32.dll,
Kernel32.dll, or ComCtl32.dll (or Gdi32.dll in v1.0.36.07+). For example,
"User32\IsWindowVisible" produces the same result as "IsWindowVisible".
For these standard DLLs, the letter "A" suffix that appears on some API
functions may also be omitted. For example, "MessageBox" is the same as
"MessageBoxA".
Performance can be dramatically improved when making repeated calls to
a DLL by loading it beforehand.
Type1, Arg1
Each of these pairs represents a single parameter to be passed to the
function. The number of pairs is unlimited. For Type, see the types table
below. For Arg, specify the value to be passed to the function.
Cdecl
ReturnType
The word Cdecl is normally omitted because most functions use the
standard calling convention rather than the "C" calling convention
(functions such as wsprintf that accept a varying number of arguments are
one exception to this). If you omit Cdecl but the call yields ErrorLevel An -
- where n is the total size of the arguments you passed -- Cdecl might be
required.
If present, the word Cdecl should be listed before the return type (if any).
Separate each word from the next with a space or tab. For example:
"Cdecl Str"
ReturnType: If the function returns a 32-bit integer (Int), BOOL, or
nothing at all, ReturnType may be omitted. Otherwise, specify one of the
argument types from the types table below. The asterisk suffix is also
supported.
Types of Arguments and Return Values
Str
A string such as "Blue" or MyVar. If the called function modifies the string and the
argument is a naked variable, its contents will be updated. For example, the
following call would convert the contents of MyVar to uppercase:
DllCall("CharUpper", "str", MyVar)
However, if the function is designed to store a string larger than a variable's current
capacity, ensure that the variable is large enough before calling the function. This
can be achieved by calling VarSetCapacity(MyVar, 123), where 123 is the length
that MyVar must be able to hold.
A str argument must not be an expression that evaluates to a number (such as
i+1). If it is, the function will not be called and ErrorLevel will be set to -2.
The str type should generally be used with functions that expect LPSTR, LPCSTR,
LPTSTR, and similar types.
The asterisk variable "str *" is supported but very rarely used. It can be used with
functions that expect something like "char **" or "LPSTR *".
Int64
A 64-bit integer, whose range is -9223372036854775808 (-0x8000000000000000)
to 9223372036854775807 (0x7FFFFFFFFFFFFFFF).
Int
A 32-bit integer (the most common integer type), whose range is -2147483648 (-
0x80000000) to 2147483647 (0x7FFFFFFF). An Int is sometimes called a "Long".
An Int should also be used for each BOOL argument expected by a function (a BOOL
value should be either 1 or 0).
An unsigned Int (UInt) is also used quite frequently, such as for DWORD and
Misc. Commands
379
COLORREF. It is also used for almost all handles, such as HWND, HBRUSH, and
HBITMAP.
Note: To pass a NULL handle or pointer, pass the integer 0.
Short
A 16-bit integer, whose range is -32768 (-0x8000) to 32767 (0x7FFF). An unsigned
Short (UShort) can be used with functions that expect a WORD.
Char
An 8-bit integer, whose range is -128 (-0x80) to 127 (0x7F). An unsigned character
(UChar) can be used with functions that expect a BYTE.
Float A 32-bit floating point number, which provides 6 digits of precision.
Double A 64-bit floating point number, which provides 15 digits of precision.
* or P
(suffix)
Append an asterisk (with optional preceding space) to any of the above types to
cause the address of the argument to be passed rather than the value itself (the
called function must be designed to accept it). Since the value of such an argument
might be modified by the function, whenever a naked variable is passed as the
argument, that variable's contents will be updated. For example, the following call
would pass the current contents of MyVar to MyFunction but would also update
MyVar to reflect any changes made to it by MyFunction: DllCall("MyDll\MyFunction",
"int *", MyVar)
In general, an asterisk is used whenever a function has an argument type or return
type that starts with "LP" (except a string type such as LPSTR, for which "str"
should be used). The most common example is LPDWORD, which is a pointer to a
DWORD. Since a DWORD is an unsigned 32-bit integer, use "UInt *" or "UintP" to
represent LPDWORD.
Note: "char *" is not the same as "str" because "char *" passes the address of an 8-
bit number, but "str" passes the address of a series of characters.
U
(prefix)
Prepend the letter U to any of the integer types above to interpret it as an unsigned
integer (UInt64, UInt, UShort, and UChar). Strictly speaking, this is necessary only
for return values and asterisk variables because it does not matter whether an
argument passed by value is unsigned or signed (except for Int64).
A 32-bit unsigned integer (UInt) is an appropriate substitute for any DWORD,
HWND, or similar argument expected by a function. Also, an HWND value (the
handle of a window) is the same as the window's unique ID.
If a negative integer is specified for an unsigned argument, the integer will wrap
around into the unsigned domain. For example, when -1 is sent as a UInt, it would
become 0xFFFFFFFF. However, this technique is not supported for 64-bit integers
(UInt64).
Unsigned 64-bit integers are not fully supported. Therefore, to work with numbers
greater or equal to 0x8000000000000000, omit the U prefix and interpret any
negative values received from the function as large integers. For example, a
function that yields -1 as an Int64 is really yielding 0xFFFFFFFFFFFFFFFF if it is
designed to yield a UInt64.
ErrorLevel
ErrorLevel is set to one of the following values to indicate whether the call succeeded or failed.
0: Success.
-1 (negative 1): The [DllFile\]Function parameter is an expression that evaluates to a number. A
string is required.
Printed Documentation
380
-2: The return type or one of the specified arg types is invalid. This error can also be caused by
passing an expression that evaluates to a number to a string (str) argument.
-3: The specified DllFile could not be accessed. If no explicit path was specified for DllFile, the file
must exist in the system's PATH or A_WorkingDir. This error might also occur if the user lacks
permission to access the file.
-4: The specified function could not be found inside the DLL.
N (any positive number): The function was called but it aborted with fatal exception number N (for
example, 0xC0000005 means "access violation"). In such cases, the function returns a blank value
(empty string), but any asterisk variables will still be updated. An example of a fatal exception is
dereferencing an invalid pointer such as NULL. Since a Cdecl function never produces the "An" error in
the next paragraph, it may generate an exception when too few arguments are passed to it.
An (the letter A followed by an integer n): The function was called but was passed too many or too
few arguments. "n" is the number of bytes by which the argument list was incorrect. If n is positive,
too many arguments (or arguments that were too large) were passed, or the call requires CDecl. If n
is negative, too few arguments were passed. This situation should be corrected to ensure reliable
operation of the function. The presence of this error may also indicate that an exception occurred, in
which case the function returns a blank value.
Performance
When making repeated calls to a DLL, performance can be dramatically improved by loading it
explicitly (this is not necessary for a standard DLL such as User32 because it is always resident). This
practice avoids the need for DllCall to internally call LoadLibrary and FreeLibrary each time. For
example:
hModule := DllCall("LoadLibrary", "str", "MyFunctions.dll") ; Avoids the need for DllCall() in
the loop to load the library.
Loop, C:\My Documents\*.*, , 1
result := DllCall("MyFunctions\BackupFile", "str", A_LoopFileFullPath)
DllCall("FreeLibrary", "UInt", hModule) ; To conserve memory, the DLL may be unloaded
after using it.
Finally, when passing a string-variable to a function that will not change the length of the string,
performance is improved by passing the variable by address (e.g. &MyVar) rather than as a "str"
(especially when the string is very long). The following example converts a string to uppercase:
DllCall("CharUpper", uint, &MyVar)
Structures and Arrays [v1.0.36.07+]
A structure is a collection of members (fields) stored adjacently in memory. Most members tend to be
integers.
Functions that accept the address of a structure (or a memory-block array) can be called by storing
the structure's raw binary data in a normal variable. The following steps are generally used:
1) Call VarSetCapacity(MyStruct, 123, 0) to ensure that the target variable is large enough to hold the
structure's data. Replace 123 with a number that is at least as large as the size of the structure.
Specifying zero as the last parameter is optional; it initializes all members to be binary zero, which is
typically used to avoid calling InsertInteger() as often in the next step.
2) If the target function uses the values initially in the structure, call InsertInteger(123, MyStruct, 4)
to initialize any members that should be non-zero. Replace 123 with the integer to be put into the
target member (or specify &Var to store the address of a variable). Replace 4 with the offset of the
target member (see step #4 for description of "offset").
3) Call the target function, passing the address of MyStruct as a UInt argument. For example,
DllCall("MyDll\MyFunc", UInt, &MyStruct). The function will examine and/or change some of the
members.
Misc. Commands
381
4) Use MyInteger := ExtractInteger(MyStruct, 4) to retrieve any desired integers from the structure.
Replace 4 with the offset of the target member in the structure. The first member is always at offset
0. The second member is at offset 0 plus the size of the first member (typically 4). Members beyond
the second are at the offset of the previous member plus the size of the previous member. Most
members -- such as DWORD, Int, and other types of 32-bit integers -- are 4 bytes in size.
The following are the functions referenced above. They can be pasted into any script or included via
#Include. See Structure Examples for actual usages.
ExtractInteger(ByRef pSource, pOffset = 0, pIsSigned = false, pSize = 4)
; pSource is a string (buffer) whose memory area contains a raw/binary integer at pOffset.
; The caller should pass true for pSigned to interpret the result as signed vs. unsigned.
; pSize is the size of PSource's integer in bytes (e.g. 4 bytes for a DWORD or Int).
; pSource must be ByRef to avoid corruption during the formal-to-actual copying process
; (since pSource might contain valid data beyond its first binary zero).
{
Loop %pSize% ; Build the integer by adding up its bytes.
result += *(&pSource + pOffset + A_Index-1) << 8*(A_Index-1)
if (!pIsSigned OR pSize > 4 OR result < 0x80000000)
return result ; Signed vs. unsigned doesn't matter in these cases.
; Otherwise, convert the value (now known to be 32-bit) to its signed counterpart:
return -(0xFFFFFFFF - result + 1)
}

InsertInteger(pInteger, ByRef pDest, pOffset = 0, pSize = 4)
; The caller must ensure that pDest has sufficient capacity. To preserve any existing contents
in pDest,
; only pSize number of bytes starting at pOffset are altered in it.
{
Loop %pSize% ; Copy each byte in the integer into the structure as raw binary data.
DllCall("RtlFillMemory", "UInt", &pDest + pOffset + A_Index-1, "UInt", 1, "UChar",
pInteger >> 8*(A_Index-1) & 0xFF)
}
Remarks
In spite of the built-in exception handling, it is still possible to crash a script with DllCall. This can
happen when a function does not directly generate an exception but yields something inappropriate,
such as a bad pointer or a string that is not terminated. This might not be the function's fault if the
script passed it an unsuitable value such as a bad pointer or a "str" with insufficient capacity. A script
can also crash when it specifies an inappropriate argument type or return type, such as claiming that
an ordinary integer yielded by a function is an asterisk variable or str.
In v1.0.42.03+, the built-in variable A_LastError will contain the result of the operating system's
GetLastError() function, which is called immediately after the function is called (this has no
measurable impact on performance). A_LastError is a number between 0 and 4294967295 (always
formatted as decimal, not hexadecimal). Like ErrorLevel, A_LastError is a per-thread setting; that is,
interruptions by other threads cannot change it. However, A_LastError is also set by Run/RunWait.
Printed Documentation
382
When specifying an argument type or return type that does not contain a space or asterisk, the quotes
around it may be omitted. For example, str can be used in place of "str" and CDecl in place of "CDecl".
In addition, the letter P may be used in place of asterisk to allow the quotes to be omitted there as
well. For example: UIntP.
A function that returns the address of one of the strings that was passed into it might return an
identical string in a different memory address than expected. For example calling
CharLower(CharUpper(MyVar)) in a programming language would convert MyVar's contents to
lowercase. But when the same is done with DllCall(), MyVar would be uppercase after the following
call because CharLower would have operated on a different/temporary string whose contents were
identical to MyVar:
MyVar = ABC
result := DllCall("CharLower", str, DllCall("CharUpper", str, MyVar, str), str)
To work around this, change the two underlined "str" values above to UInt. This interprets
CharUpper's return value as a pure address that will get passed as an integer to CharLower.
When a variable's address (e.g. &MyVar) is passed to a function and that function alters the length of
the variable's contents, subsequent uses of the variable may behave incorrectly. To fix this, do one of
the following: 1) Pass MyVar as a "str" argument rather than as a uint/address; 2) In v1.0.44.03+,
call VarSetCapacity(MyVar, -1) to update the variable's internally-stored length after calling DllCall.
Any binary zero stored in a variable by a function will hide all data to the right of the zero; that is,
such data cannot be accessed or changed by most commands and functions. However, such data can
be manipulated by the address and dereference operators (& and *), as well as DllCall itself.
Related
VarSetCapacity, Functions, PostMessage, SysGet
Examples
; Example: Calls the Windows API function "MessageBox" and report which button the user presses.

WhichButton := DllCall("MessageBox", "int", "0", "str", "Press Yes or No", "str", "Title of box", "int", 4)
MsgBox You pressed button #%WhichButton%.

; Example: Changes the desktop wallpaper to the specified bitmap (.bmp) file.

DllCall("SystemParametersInfo", UInt, 0x14, UInt, 0, Str, A_WinDir . "\winnt.bmp", UInt, 2)

; Example: Calls the API function "IsWindowVisible" to find out if a Notepad window is visible.

DetectHiddenWindows On
if not DllCall("IsWindowVisible", "UInt", WinExist("Untitled - Notepad")) ; WinExist() returns an
HWND.
MsgBox The window is not visible.

; Example: Calls the API's wsprintf() to pad the number 432 with leading zeros to make it 10
characters wide (0000000432).

Misc. Commands
383
VarSetCapacity(ZeroPaddedNumber, 20) ; Ensure the variable is large enough to accept the new
string.
DllCall("wsprintf", "str", ZeroPaddedNumber, "str", "%010d", "int", 432, "Cdecl") ; Requires the Cdecl
calling convention.
MsgBox %ZeroPaddedNumber%

; Example: Demonstrates QueryPerformanceCounter(), which gives more precision than A_TickCount's
10ms.

DllCall("QueryPerformanceCounter", "Int64 *", CounterBefore)
Sleep 1000
DllCall("QueryPerformanceCounter", "Int64 *", CounterAfter)
MsgBox % "Elapsed QPC time is " . CounterAfter - CounterBefore

; Example: This is a hotkey that temporarily reduces the mouse cursor's speed, which facilitates
precise positioning.
; Hold down the F1 key to slow down the cursor. Release it to return to original speed.

F1::
SPI_GETMOUSESPEED = 0x70
SPI_SETMOUSESPEED = 0x71
; Retrieve the current speed so that it can be restored later:
DllCall("SystemParametersInfo", UInt, SPI_GETMOUSESPEED, UInt, 0, UIntP, OrigMouseSpeed, UInt,
0)
; Now set the mouse to the slower speed specified in the next-to-last parameter (the range is 1-20,
10 is default):
DllCall("SystemParametersInfo", UInt, SPI_SETMOUSESPEED, UInt, 0, UInt, 3, UInt, 0)
KeyWait F1 ; This prevents keyboard auto-repeat from doing the DllCall repeatedly.
return

F1 up::DllCall("SystemParametersInfo", UInt, 0x71, UInt, 0, UInt, OrigMouseSpeed, UInt, 0) ;
Restore the original speed.

; Example: When passed a window's Unique ID and the text or ClassNN of one of its controls,
; the following function returns the HWND (unique ID) of that control.
; v1.0.43.06+: This function has been superseded by the following command, which is more accurate.

ControlGet, OutputVar, Hwnd,, ClassNN, WinTitle

; Example: Monitors the active window and display the position of its vertical scroll bar in its
Printed Documentation
384
; focused control (with real-time updates). This requires v1.0.43.06+ because it uses ControlGet
Hwnd.

#Persistent
SetTimer, WatchScrollBar, 100
return

WatchScrollBar:
ActiveWindow := WinExist("A")
if not ActiveWindow ; No active window.
return
ControlGetFocus, FocusedControl, ahk_id %ActiveWindow%
if not FocusedControl ; No focused control.
return
; Display the vertical or horizontal scroll bar's position in a ToolTip:
ControlGet, ChildHWND, Hwnd,, %FocusedControl%, ahk_id %ActiveWindow%
ToolTip % DllCall("GetScrollPos", "UInt", ChildHWND, "Int", 1) ; Last parameter is 1 for SB_VERT, 0
for SB_HORZ.
return

; Example: This is a working script that writes some text to a file then reads it back into memory
(requires v1.0.34+).
; This method can be used to help performance in cases where multiple files are being read or written
simultaneously.

FileSelectFile, FileName, S16,, Create a new file:
if FileName =
return
GENERIC_WRITE = 0x40000000 ; Open the file for writing rather than reading.
CREATE_ALWAYS = 2 ; Create new file (overwriting any existing file).
hFile := DllCall("CreateFile", str, FileName, Uint, GENERIC_WRITE, Uint, 0, UInt, 0, UInt,
CREATE_ALWAYS, Uint, 0, UInt, 0)
if not hFile
{
MsgBox Can't open "%FileName%" for writing.
return
}
TestString = This is a test string.`r`n ; When writing a file this way, use `r`n rather than `n to start
a new line.
DllCall("WriteFile", UInt, hFile, str, TestString, UInt, StrLen(TestString), UIntP, BytesActuallyWritten,
UInt, 0)
Misc. Commands
385
DllCall("CloseHandle", UInt, hFile) ; Close the file.

; Now that the file was written, read its contents back into memory.
GENERIC_READ = 0x80000000 ; Open the file for reading rather than writing.
OPEN_EXISTING = 3 ; This mode indicates that the file to be opened must already exist.
FILE_SHARE_READ = 0x1 ; This and the next are whether other processes can open the file while we
have it open.
FILE_SHARE_WRITE = 0x2
hFile := DllCall("CreateFile", str, FileName, UInt, GENERIC_READ, UInt,
FILE_SHARE_READ|FILE_SHARE_WRITE, UInt, 0, UInt, OPEN_EXISTING, Uint, 0, UInt, 0)
if not hFile
{
MsgBox Can't open "%FileName%" for reading.
return
}
; Make the variable empty for testing purposes, but ensure it retains sufficient capacity:
BytesToRead := VarSetCapacity(TestString, StrLen(TestString))
DllCall("ReadFile", UInt, hFile, str, TestString, UInt, BytesToRead, UIntP, BytesActuallyRead, UInt, 0)
DllCall("CloseHandle", UInt, hFile) ; Close the file.
MsgBox The following string was read from the file: %TestString%

; Example: Hides the mouse cursor when you press Win+C. To later show the cursor, press Win+C
again.
; This script is from http://www.autohotkey.com/forum/topic6107.html

OnExit, ShowCursor ; Ensure the cursor is made visible when the script exits.
return

ShowCursor:
SystemCursor("On")
ExitApp

#c::SystemCursor("Toggle") ; Win+C hotkey to toggle the cursor on and off.

SystemCursor(OnOff=1) ; INIT = "I","Init"; OFF = 0,"Off"; TOGGLE = -1,"T","Toggle"; ON = others
{
static AndMask, XorMask, $, h_cursor
,c0,c1,c2,c3,c4,c5,c6,c7,c8,c9,c10,c11,c12,c13 ; system cursors
, b1,b2,b3,b4,b5,b6,b7,b8,b9,b10,b11,b12,b13 ; blank cursors
Printed Documentation
386
, h1,h2,h3,h4,h5,h6,h7,h8,h9,h10,h11,h12,h13 ; handles of default cursors
if (OnOff = "Init" or OnOff = "I" or $ = "") ; init when requested or at first call
{
$ = h ; active default cursors
VarSetCapacity( h_cursor,4444, 1 )
VarSetCapacity( AndMask, 32*4, 0xFF )
VarSetCapacity( XorMask, 32*4, 0 )
system_cursors =
32512,32513,32514,32515,32516,32642,32643,32644,32645,32646,32648,32649,32650
StringSplit c, system_cursors, `,
Loop %c0%
{
h_cursor := DllCall( "LoadCursor", "uint",0, "uint",c%A_Index% )
h%A_Index% := DllCall( "CopyImage", "uint",h_cursor, "uint",2, "int",0, "int",0, "uint",0 )
b%A_Index% := DllCall("CreateCursor","uint",0, "int",0, "int",0
, "int",32, "int",32, "uint",&AndMask, "uint",&XorMask )
}
}
if (OnOff = 0 or OnOff = "Off" or $ = "h" and (OnOff < 0 or OnOff = "Toggle" or OnOff = "T"))
$ = b ; use blank cursors
else
$ = h ; use the saved cursors

Loop %c0%
{
h_cursor := DllCall( "CopyImage", "uint",%$%%A_Index%, "uint",2, "int",0, "int",0, "uint",0 )
DllCall( "SetSystemCursor", "uint",h_cursor, "uint",c%A_Index% )
}
}

; Structure Example: Pass the address of a RECT structure to GetWindowRect(), which sets the
structure's
; members to the positions of the left, top, right, and bottom sides of a window (relative to the
screen).

Run Notepad
WinWait Untitled - Notepad ; This also sets the "last found window" for use with WinExist() below.
VarSetCapacity(Rect, 16) ; A RECT is a struct consisting of four 32-bit integers (i.e. 4*4=16).
DllCall("GetWindowRect", UInt, WinExist(), UInt, &Rect) ; WinExist() returns an HWND.
Misc. Commands
387
MsgBox % "Left " . ExtractInteger(Rect, 0, true) . " Top " . ExtractInteger(Rect, 4, true)
. " Right " . ExtractInteger(Rect, 8, true) . " Bottom " . ExtractInteger(Rect, 12, true)

; Structure Example: Pass to FillRect() the address of a RECT structure that indicates a part of the
; screen to temporarily paint red.

VarSetCapacity(Rect, 16, 0) ; Set capacity to hold four 4-byte integers and initialize them all to zero.
InsertInteger(A_ScreenWidth//2, Rect, 8) ; The third integer in the structure is "rect.right".
InsertInteger(A_ScreenHeight//2, Rect, 12) ; The fourth integer in the structure is "rect.bottom".
hDC := DllCall("GetDC", UInt, 0) ; Pass zero to get the desktop's device context.
hBrush := DllCall("CreateSolidBrush", UInt, 0x0000FF) ; Create a red brush (0x0000FF is in BGR
format).
DllCall("FillRect", UInt, hDC, Str, Rect, UInt, hBrush) ; Fill the specified rectangle using the brush
above.
DllCall("ReleaseDC", UInt, 0, UInt, hDC) ; Clean-up.
DllCall("DeleteObject", UInt, hBrush) ; Clean-up.

; Structure Example: Change the system's clock to the specified date and time. Use caution when
; changing to a date in the future as it may cause scheduled tasks to run prematurely!

SetSystemTime("20051008142211") ; Pass it a timestamp (local, not UTC).

SetSystemTime(YYYYMMDDHHMISS)
; Sets the system clock to the specified date and time.
; Caller must ensure that the incoming parameter is a valid date-time stamp
; (local time, not UTC). Returns non-zero upon success and zero otherwise.
{
; Convert the parameter from local time to UTC for use with SetSystemTime().
UTC_Delta -= %A_NowUTC%, Seconds ; Seconds is more accurate due to rounding issue.
UTC_Delta := Round(-UTC_Delta/60) ; Round to nearest minute to ensure accuracy.
YYYYMMDDHHMISS += %UTC_Delta%, Minutes ; Apply offset to convert to UTC.

VarSetCapacity(SystemTime, 16, 0) ; This struct consists of 8 UShorts (i.e. 8*2=16).

StringLeft, Int, YYYYMMDDHHMISS, 4 ; YYYY (year)
InsertInteger(Int, SystemTime, 0, 2)
StringMid, Int, YYYYMMDDHHMISS, 5, 2 ; MM (month of year, 1-12)
InsertInteger(Int, SystemTime, 2, 2)
StringMid, Int, YYYYMMDDHHMISS, 7, 2 ; DD (day of month)
Printed Documentation
388
InsertInteger(Int, SystemTime, 6, 2)
StringMid, Int, YYYYMMDDHHMISS, 9, 2 ; HH (hour in 24-hour time)
InsertInteger(Int, SystemTime, 8, 2)
StringMid, Int, YYYYMMDDHHMISS, 11, 2 ; MI (minute)
InsertInteger(Int, SystemTime, 10, 2)
StringMid, Int, YYYYMMDDHHMISS, 13, 2 ; SS (second)
InsertInteger(Int, SystemTime, 12, 2)

return DllCall("SetSystemTime", UInt, &SystemTime)
}

; More Structure Examples: See the WinLIRC client script for a demonstration of how to use DllCall()
to make
; a network connection to a TCP/IP server and receive data from it. Also, the operating system offers
two
; standard dialogs that prompt the user to pick a font and/or color. These dialogs use structures as
; demonstrated in the forum topics ChooseFont and ChooseColor.
Edit
Opens the current script for editing in the associated editor.
Edit
The Edit command opens the current script for editing using the associated "edit" verb in the registry
(or Notepad if no verb). However, if an editor window appears to have the script already open (based
on its window title), that window is activated instead of opening a new instance of the editor.
The Edit command is equivalent to selecting "Edit This Script" from the tray icon menu.
This command has no effect when operating from within a compiled script.
On a related note, the Extras folder included with AutoHotkey has some add-ons for editors such as
TextPad. In addition, context sensitive help for AutoHotkey commands can be enabled in any editor
via this example.
Related
Reload
Example
Edit ; opens the script for editing.
ImageSearch
Searches a region of the screen for an image.
ImageSearch, OutputVarX, OutputVarY, X1, Y1, X2, Y2, ImageFile
Parameters
Misc. Commands
389
OutputVarX/Y
The names of the variables in which to store the X and Y coordinates of the
upper-left pixel of where the image was found on the screen (if no match is
found, the variables are made blank). Coordinates are relative to the active
window unless CoordMode was used to change that.
Either or both of these parameters may be left blank, in which case ErrorLevel
(see below) can be used to determine whether a match was found.
X1,Y1
The X and Y coordinates of the upper left corner of the rectangle to search,
which can be expressions. Coordinates are relative to the active window
unless CoordMode was used to change that.
X2,Y2
The X and Y coordinates of the lower right corner of the rectangle to search,
which can be expressions. Coordinates are relative to the active window
unless CoordMode was used to change that.
ImageFile
The file name of an image, which is assumed to be in %A_WorkingDir% if an
absolute path isn't specified. All operating systems support GIF, JPG, BMP,
ICO, CUR, and ANI images (BMP images must be 16-bit or higher). Other
sources of icons include the following types of files: EXE, DLL, CPL, SCR, and
other types that contain icon resources. On Windows XP or later, additional
image formats such as PNG, TIF, Exif, WMF, and EMF are supported.
Operating systems older than XP can be given support by copying Microsoft's
free GDI+ DLL into the AutoHotkey.exe folder (but in the case of a compiled
script, copy the DLL into the script's folder). To download the DLL, search for
the following phrase at www.microsoft.com: gdi redistributable
Options: Zero or more of the following strings may be also be present
immediately before the name of the file. Separate each option from the next
with a single space or tab. For example: *2 *w100 *h-1 C:\Main Logo.bmp
*IconN: To use an icon group other than the first one in the file, specify
*Icon followed immediately by the number of the group. For example, *Icon2
would load the default icon from the second icon group.
*n: Specify for n a number between 0 and 255 (inclusive) to indicate the
allowed number of shades of variation in either direction for the intensity of
the red, green, and blue components of each pixel's color. For example, *2
would allow two shades of variation. This parameter is helpful if the coloring
of the image varies slightly or if ImageFile uses a format such as GIF or JPG
that does not accurately represent an image on the screen. If you specify 255
shades of variation, all colors will match. The default is 0 shades.
*TransN: This option makes it easier to find a match by specifying one color
within the image that will match any color on the screen. It is most commonly
used to find PNG, GIF, and TIF files that have some transparent areas
(however, icons do not need this option because their transparency is
automatically supported). For GIF files, *TransWhite might be most likely to
work. For PNG and TIF files, *TransBlack might be best. Otherwise, specify for
N some other color name or RGB value (see the color chart for guidance, or
use PixelGetColor in its RGB mode). Examples: *TransBlack, *TransFFFFAA,
*Trans0xFFFFAA
*wn and *hn: Width and height to which to scale the image (this width and
height also determines which icon to load from a multi-icon .ICO file). If both
these options are omitted, icons loaded from ICO, DLL, or EXE files are scaled
to the system's default small-icon size, which is usually 16 by 16 (you can
force the actual/internal size to be used by specifying *w0 *h0). Images that
are not icons are loaded at their actual size. To shrink or enlarge the image
while preserving its aspect ratio, specify -1 for one of the dimensions and a
positive number for the other. For example, specifying *w200 *h-1 would
Printed Documentation
390
make the image 200 pixels wide and cause its height to be set automatically.
ErrorLevel
ErrorLevel is set to 0 if the image was found in the specified region, 1 if it was not found, or 2 if there
was a problem that prevented the command from conducting the search (such as failure to open the
image file or a badly formatted option).
Remarks
ImageSearch can be used to detect graphical objects on the screen that either lack text or whose text
cannot be easily retrieved. For example, it can be used to discover the position of picture buttons,
icons, web page links, or game objects. Once located, such objects can be clicked via Click.
A strategy that is sometimes useful is to search for a small clipping from an image rather than the
entire image. This can improve reliability in cases where the image as a whole varies, but certain parts
within it are always the same. One way to extract a clipping is to:
1. Press Alt+PrintScreen while the image is visible in the active window. This places a screenshot
on the clipboard.
2. Open an image processing program such as Paint.
3. Paste the contents of the clipboard (that is, the screenshot).
4. Select a region that does not vary and that is unique to the image.
5. Copy and paste that region to a new image document.
6. Save it as a small file for use with ImageSearch.
To be a match, an image on the screen must be the same size as the one loaded via the ImageFile
parameter and its options.
The region to be searched must be visible; in other words, it is not possible to search a region of a
window hidden behind another window. By contrast, images that lie partially beneath the mouse
cursor can usually be detected. The exception to this is game cursors, which in most cases will
obstruct any images beneath them.
Since the search starts at the top row of the region and moves downward, if there is more than one
match, the one closest to the top will be found.
Icons containing a transparent color automatically allow that color to match any color on the screen.
Therefore, the color of what lies behind the icon does not matter.
v1.0.40.10+ supports 8-bit color screens (256-color) or higher. Older versions support 16-bit color or
higher.
The search behavior may vary depending on the display adapter's color depth (especially for GIF and
JPG files). Therefore, if a script will run under multiple color depths, it is best to test it on each depth
setting. You can use the shades-of-variation option (*n) to help make the behavior consistent across
multiple color depths.
If the image on the screen is translucent, ImageSearch will probably fail to find it. To work around
this, try the shades-of-variation option (*n) or make the window temporarily opaque via WinSet,
Transparent, Off.
Related
PixelSearch, PixelGetColor, CoordMode, MouseGetPos
Examples
ImageSearch, FoundX, FoundY, 40,40, 300, 300, C:\My Images\test.bmp

Misc. Commands
391
CoordMode Pixel ; Interprets the coordinates below as relative to the screen rather than the active
window.
ImageSearch, FoundX, FoundY, 0, 0, A_ScreenWidth, A_ScreenHeight, *Icon3
%A_ProgramFiles%\SomeApp\SomeApp.exe
if ErrorLevel = 2
MsgBox Could not conduct the search.
else if ErrorLevel = 1
MsgBox Icon could not be found on the screen.
else
MsgBox The icon was found at %FoundX%x%FoundY%.
ListLines
Displays the script lines most recently executed.
ListLines
Remarks
This command is equivalent to selecting the "View->Lines most recently executed" menu item in the
main window. It can help you debug a script.
On a related note, the built-in variables A_LineNumber and A_LineFile contain the currently executing
line number and the file name to which it belongs.
Related
KeyHistory, ListHotkeys, ListVars
Example
ListLines
ListVars
Displays the script's variables: their names and current contents.
ListVars
Remarks
This command is equivalent to selecting the "View->Variables" menu item in the main window. It can
help you debug a script.
Each line in the list consists of:
1) The name of the variable.
2) The length of the variable's contents and the variable's capacity. For example: [50 of 63]
3) The first 60 characters of the variable's contents.
If this command is used inside a function, the function's local variables will be listed first (above the
script's global variables).
Known limitation: If a function (or the list of global variables itself) contains more than 10,000
variables, this command might not show them in exact alphabetical order; that is, some might be
missing from the display.
Printed Documentation
392
Related
KeyHistory, ListHotkeys, ListLines
Example
ListVars
Menu
Creates, deletes, modifies and displays menus and menu items. Changes the tray icon and its tooltip.
Controls whether the main window of a compiled script can be opened.
Menu, MenuName, Cmd [, P3, P4, P5]
Parameters
MenuName
It can be TRAY or the name of any custom menu. A custom menu is
automatically created the first time its name is used with the Add command.
For example: Menu, MyMenu, Add, Item1
Once created, a custom menu can be displayed with the Show command. It
can also be attached as a submenu to one or more other menus via the Add
command.
Cmd, P3,
P4, P5
These 4 parameters are dependent on each other. See list below for the
allowed combinations.
Add or Change Items in a Menu
Add [, MenuItemName, Label-or-Submenu, Pn]: This is a multipurpose command that adds a
menu item, updates one with a new submenu or label, or converts one from a normal item into a
submenu (or vice versa). If MenuItemName does not yet exist, it will be added to the menu.
Otherwise, MenuItemName is updated with the newly specified Label-or-Submenu.
To add a menu separator line, omit all three parameters.
The label subroutine is run as a new thread when the user selects the menu item (similar to Gosub
and hotkey subroutines). If Label-or-Submenu is omitted, MenuItemName will be used as both the
label and the menu item's name.
To have MenuItemName become a submenu -- which is a menu item that opens a new menu when
selected -- specify for Label-or-Submenu a colon followed by the MenuName of an existing custom
menu. For example:
Menu, MySubmenu, add, Item1
Menu, tray, add, This Menu Item Is A Submenu, :MySubmenu
The final parameter may contain the letter P followed by the menu's thread priority, e.g. P1. If this
parameter is omitted when adding a menu item, the priority will be 0, which is the standard default. If
omitted when updating a menu item, the item's priority will not be changed. To change an existing
item's priority only, omit the Label-or-Submenu parameter. Use a decimal (not hexadecimal) number
as the priority.
Delete [, MenuItemName]: Deletes MenuItemName from the menu. Standard menu items such as
Exit (see below) cannot be individually deleted. If the default menu item is deleted, the effect will be
similar to having used the NoDefault option. If MenuItemName is omitted, the entire MenuName menu
will be deleted as will any menu items in other menus that use MenuName as a submenu.
DeleteAll: Deletes all custom menu items from the menu, leaving the menu empty unless it contains
the standard items (see below). Unlike a menu entirely deleted by the Delete command (see above),
Misc. Commands
393
an empty menu still exists and thus any other menus that use it as a submenu will retain those
submenus.
Rename, MenuItemName [, NewName]: Changes MenuItemName to NewName (if NewName is
blank, MenuItemName will be converted into a separator line). NewName must not be the same as
any existing custom menu item. The menu item's current target label or submenu is unchanged.
Check, MenuItemName: Adds a visible checkmark in the menu next to MenuItemName (if there
isn't one already).
Uncheck, MenuItemName: Removes the checkmark from MenuItemName if there is one.
ToggleCheck, MenuItemName: Adds a checkmark if there wasn't one; otherwise, removes it.
Enable, MenuItemName: Allows the user to once again select MenuItemName if was previously
disabled (grayed).
Disable, MenuItemName: Changes MenuItemName to a gray color to indicate that the user cannot
select it.
ToggleEnable, MenuItemName: Disables MenuItemName if it was previously enabled; otherwise,
enables it.
Default [, MenuItemName]: Changes the menu's default item to be MenuItemName and makes
that item's font bold (setting a default item in menus other than TRAY is currently purely cosmetic).
When the user double-clicks the tray icon, its default menu item is launched. If there is no default,
double-clicking has no effect. If MenuItemName is omitted, the effect is the same as having used
NoDefault below.
NoDefault: For the tray menu: Changes the menu back to having its standard default menu item,
which is OPEN for non-compiled scripts and none for compiled scripts (except when the MainWindow
option is in effect). If the OPEN menu item does not exist due to a previous use of the NoStandard
command below, there will be no default and thus double-clicking the tray icon will have no effect. For
menus other than TRAY: Any existing default item is returned to a non-bold font.
Standard: Inserts the standard menu items at the bottom of the menu (if they are not already
present). This command can be used with the tray menu or any other menu.
NoStandard: Removes all standard (non-custom) menu items from the tray menu (if they are
present).
Change the Tray Icon or ToolTip (MenuName must be TRAY)
Icon [, FileName, IconNumber, 1]: Changes the script's icon to one of the ones from FileName.
The following types of files are supported: ICO, CUR, ANI, EXE, DLL, CPL, SCR, and other types that
contain icon resources. To use an icon group other than the first one in the file, specify its number for
IconNumber (if omitted, it defaults to 1). For example, 2 would load the default icon from the second
icon group. Specify an asterisk (*) for FileName to restore the script to its default icon.
The last parameter: Specify 1 for the last parameter to freeze the icon, or 0 to unfreeze it (or leave it
blank to keep the frozen/unfrozen state unchanged). When the icon has been frozen, Pause and
Suspend will not change it. Note: To freeze the current icon, use Menu, Tray, Icon,,, 1 ; (or 0 to
unfreeze)
Changing the tray icon also changes the icon displayed by InputBox, Progress, and subsequently-
created GUI windows. Compiled scripts are also affected even if a custom icon was specified at the
time of compiling. Note: Changing the icon will not unhide the tray icon if it was previously hidden by
means such as #NoTrayIcon; to do that, use Menu, Tray, Icon (with no parameters).
Slight distortion may occur when loading tray icons from file types other than .ICO. This is especially
true for 16x16 icons. To prevent this, store the desired tray icon inside a .ICO file.
There are some icons built into the operating system's DLLs and CPLs that might be useful. For
example: Menu, Tray, Icon, Shell32.dll, 174 ; Omits the DLL's path so that it works on Windows 9x
too.
Printed Documentation
394
The built-in variables A_IconNumber and A_IconFile contain the number and name (with full path)
of the current icon (both are blank if the icon is the default).
Icon (with no parameters): Creates the tray icon if it isn't already present. This will override
#NoTrayIcon if that directive is also present in the script.
NoIcon: Removes the tray icon if it exists. If this command is used at the very top of the script, the
tray icon might be briefly visible when the script is launched. To prevent that, use #NoTrayIcon
instead. The built-in variable A_IconHidden contains 1 if the tray icon is currently hidden or 0
otherwise.
Tip [, Text]: Changes the tray icon's tooltip -- which is displayed when the mouse hovers over it. To
create a multi-line tooltip, use the linefeed character (`n) in between each line, e.g. Line1`nLine2.
Only the first 127 characters of Text are displayed. If Text is omitted, the tooltip is restored to its
default text. The built-in variable A_IconTip contains the current text of the tooltip (blank if the text
is at its default).
Misc.
Show [, X, Y]: Displays MenuName, allowing the user to select an item with arrow keys, menu
shortcuts (underlined letters), or the mouse. Any menu can be shown, including the tray menu but
with the exception of GUI menu bars. If both X and Y are omitted, the menu is displayed at the
current position of the mouse cursor. If only one of them is omitted, the mouse cursor's position will
be used for it. X and Y are relative to the active window. Specify "CoordMode, Menu" beforehand to
make them relative to the entire screen.
Color, ColorValue [, Single]: Changes the background color of the menu to ColorValue, which is one
of the 16 primary HTML color names or a 6-digit RGB color value (see color chart). Leave ColorValue
blank (or specify the word Default) to restore the menu to its default color. If the word Single is not
present as the next parameter, any submenus attached to this menu will also be changed in color.
This command has no effect on Windows 95/NT.
Click, ClickCount: Specify 1 for ClickCount to allow a single-click to activate the tray menu's default
menu item. Specify 2 for ClickCount to return to the default behavior (double-click). For example:
Menu, Tray, Click, 1
MainWindow: This command affects compiled scripts only. It allows the script's main window to be
opened via the tray icon, which is otherwise impossible. It also enables the items in the main window's
View menu -- such as "Lines most recently executed" -- allowing users to view the script's source code
and other info. MenuName must be TRAY.
NoMainWindow (default): This command affects compiled scripts only. It restores the script to its
default behavior, that is, it prevents the main window from being opened. Even while this option is in
effect, the following commands are still able to show the main window when they are encountered in
the script at runtime: ListLines, ListVars, ListHotkeys, and KeyHistory. MenuName must be TRAY.
UseErrorLevel [, off]: If this option is never used in the script, it defaults to OFF. The OFF setting
displays a dialog and terminates the current thread whenever the Menu command generates an error.
Specify Menu, Tray, UseErrorLevel to prevent the dialog and thread termination; instead, ErrorLevel
will be set to 1 if there was a problem or 0 otherwise. To turn this option back off, specify OFF for the
next parameter. This setting is global, meaning it affects all menus, not just MenuName.
Remarks
To underline one of the letters in a menu item's name, precede that letter with an ampersand (&).
When the menu is displayed, such an item can be selected by pressing the corresponding key on the
keyboard. To display a literal ampersand, specify two consecutive ampersands as in this example:
Save && Exit
The names of menus and menu items can be up to 260 characters long.
When referring to an existing menu or menu item, the name is not case sensitive but any ampersands
must be included. For example: &Open
Misc. Commands
395
Separator lines can be added to the menu by using Menu, tray, add (i.e. omit all other parameters).
However, separator lines currently cannot be individually deleted. To work around this, use Menu,
tray, DeleteAll and then re-add your custom menu items.
New menu items are always added at the bottom of the menu. For the tray menu: To put your menu
items on top of the standard menu items (after adding your own menu items) run Menu, tray,
NoStandard followed by Menu, tray, Standard.
The standard menu items such as "Pause Script" and "Suspend Hotkeys" cannot be individually
operated upon by any menu sub-command.
If a menu ever becomes completely empty -- such as by using Menu, MyMenu, DeleteAll -- it cannot
be shown. If the tray menu becomes empty, right-clicking and double-clicking the tray icon will have
no effect (in such cases it is usually better to use #NoTrayIcon).
If a menu item's subroutine is already running and the user selects the same menu item again, a new
thread will be created to run that same subroutine, interrupting the previous thread. To instead buffer
such events until later, use Critical as the subroutine's first line (however, this will also buffer/defer
other threads such as the press of a hotkey).
Whenever a subroutine is launched via a menu item, it starts off fresh with the default values for
settings such as SendMode. These defaults can be changed in the auto-execute section.
The built-in variables A_ThisMenuItem and A_ThisMenuItemPos contain the name and position of
the custom menu item most recently selected by the user (blank if none). Similarly, A_ThisMenu is
the name of the menu from which A_ThisMenuItem was selected. These variables are useful when
building a menu whose contents are not always the same. In such a case, it is usually best to point all
such menu items to the same label and have that label refer to the above variables to determine what
action to take.
To keep a non-hotkey, non-GUI script running -- such as one that contains only custom menus or
menu items -- use #Persistent.
Related
GUI, Threads, Thread, Critical, #NoTrayIcon, Gosub, Return, SetTimer, #Persistent
Examples
; EXAMPLE #1: This is a working script that adds a new menu item to the bottom of the tray icon
menu.

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

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

; EXAMPLE #2: This is a working script that creates a popup menu that is displayed when the user
presses the Win-Z hotkey.

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

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

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

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

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

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

; EXAMPLE #3: This is a working script that demonstrates some of the various menu commands.

#Persistent
#SingleInstance
menu, tray, add ; separator
menu, tray, add, TestToggle&Check
menu, tray, add, TestToggleEnable
menu, tray, add, TestDefault
menu, tray, add, TestStandard
menu, tray, add, TestDelete
menu, tray, add, TestDeleteAll
menu, tray, add, TestRename
menu, tray, add, Test
return

Misc. Commands
397
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

TestToggle&Check:
menu, tray, ToggleCheck, TestToggle&Check
menu, tray, Enable, TestToggleEnable ; Also enables the next test since it can't undo the disabling of
itself.
menu, tray, add, TestDelete ; Similar to above.
return

TestToggleEnable:
menu, tray, ToggleEnable, TestToggleEnable
return

TestDefault:
if default = TestDefault
{
menu, tray, NoDefault
default =
}
else
{
menu, tray, Default, TestDefault
default = TestDefault
}
return

TestStandard:
if standard <> n
{
menu, tray, NoStandard
standard = n
}
else
{
menu, tray, Standard
standard = y
}
return
Printed Documentation
398

TestDelete:
menu, tray, delete, TestDelete
return

TestDeleteAll:
menu, tray, DeleteAll
return

TestRename:
if NewName <> renamed
{
OldName = TestRename
NewName = renamed
}
else
{
OldName = renamed
NewName = TestRename
}
menu, tray, rename, %OldName%, %NewName%
return

Test:
MsgBox, You selected "%A_ThisMenuItem%" in menu "%A_ThisMenu%".
return
OutputDebug
Sends a string to the debugger (if any) for display.
OutputDebug, Text
Parameters
Text
The text to send to the debugger for display. This text may include linefeed
characters (`n) to start new lines. In addition, a single long line can be broken
up into several shorter ones by means of a continuation section.
Remarks
If the script's process has no debugger, the system debugger displays the string. If the system
debugger is not active, this command has no effect.
One example of a debugger is DebugView, which is free and available at www.sysinternals.com.
Misc. Commands
399
See also: other debugging methods
Related
FileAppend, continuation sections
Example
OutputDebug, %A_Now%: Because the window "%TargetWindowTitle%" did not exist, the process
was aborted.
PixelGetColor
Retrieves the color of the pixel at the specified x,y screen coordinates.
PixelGetColor, OutputVar, X, Y [, Alt|Slow|RGB]
Parameters
OutputVar
The name of the variable in which to store the color ID in hexadecimal blue-
green-red (BGR) format. For example, the color purple is defined 0x800080
because it has an intensity of 80 for its blue and red components but an
intensity of 00 for its green component.
X, Y
The X and Y coordinates of the pixel, which can be expressions. Coordinates
are relative to the active window unless CoordMode was used to change that.
Alt|Slow|RGB
This parameter may contain zero or more of the following words. If more than
one word is present, separate each from the next with a space (e.g. Alt RGB).
Alt [v1.0.43.10+]: Uses an alternate method to retrieve the color, which
should be used when the normal method produces invalid or inaccurate colors
for a particular type of window. This method is about 10% slower than the
normal method.
Slow [v1.0.43.10+]: Uses a more elaborate method to retrieve the color,
which may work in certain full-screen applications when the other methods
fail. This method is about three times slower than the normal method. Note:
Slow takes precedence over Alt, so there is no need to specify Alt in this case.
RGB: Retrieves the color in RGB vs. BGR format. In other words, the red and
the blue components are swapped. This is useful for retrieving colors
compatible with WinSet, Gui, Progress, and SplashImage.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
The pixel must be visible; in other words, it is not possible to retrieve the pixel color of a window
hidden behind another window. By contrast, pixels beneath the mouse cursor can usually be detected.
The exception to this is game cursors, which in most cases will hide any pixels beneath them.
Use Window Spy (available in tray icon menu) or the example at the bottom of this page to determine
the colors currently on the screen.
Known limitations:
A window that is partially transparent or that has one of its colors marked invisible
(TransColor) typically yields colors for the window behind itself rather than its own.
Printed Documentation
400
PixelGetColor might not produce accurate results for certain applications. If this occurs, try
specifying the word Alt or Slow in the last parameter.
Related
PixelSearch, ImageSearch, CoordMode, MouseGetPos
Example
^!z:: Control+Alt+Z hotkey.
MouseGetPos, MouseX, MouseY
PixelGetColor, color, %MouseX%, %MouseY%
MsgBox The color at the current cursor position is %color%.
return
PixelSearch
Searches a region of the screen for a pixel of the specified color.
PixelSearch, OutputVarX, OutputVarY, X1, Y1, X2, Y2, ColorID [, Variation, Fast|RGB]
Parameters
OutputVarX/Y
The names of the variables in which to store the X and Y coordinates of the
first pixel that matches ColorID (if no match is found, the variables are made
blank). Coordinates are relative to the active window unless CoordMode was
used to change that.
Either or both of these parameters may be left blank, in which case ErrorLevel
(see below) can be used to determine whether a match was found.
X1, Y1
The X and Y coordinates of the upper left corner of the rectangle to search,
which can be expressions. Coordinates are relative to the active window
unless CoordMode was used to change that.
X2, Y2
The X and Y coordinates of the lower right corner of the rectangle to search,
which can be expressions. Coordinates are relative to the active window
unless CoordMode was used to change that.
ColorID
The decimal or hexadecimal color ID to search for, in Blue-Green-Red (BGR)
format, which can be an expression. Color IDs can be determined using
Window Spy (accessible from the tray menu) or via PixelGetColor. For
example: 0x9d6346
Variation
A number between 0 and 255 (inclusive) to indicate the allowed number of
shades of variation in either direction for the intensity of the red, green, and
blue components of the color (can be an expression). This parameter is
helpful if the color sought is not always exactly the same shade. If you specify
255 shades of variation, all colors will match. The default is 0 shades.
Fast|RGB
This parameter may contain the word Fast, RGB, or both (if both are present,
separate them with a space; that is, Fast RGB).
Fast: Uses a faster searching method that in most cases dramatically reduces
the amount of CPU time used by the search. Version 1.0.40.10+ supports 8-
bit color screens (256-color) or higher; earlier versions support 16-bit color or
higher. However, the fast mode performs much better in 24-bit or 32-bit
color. If the screen's color depth is 16-bit or lower, the Variation parameter
Misc. Commands
401
might behave slightly differently in fast mode than it does in slow mode.
Finally, the fast mode searches the screen row by row (top down) instead of
column by column. Therefore, it might find a different pixel than that of the
slow mode if there is more than one matching pixel.
RGB: Causes ColorID to be interpreted as an RGB value instead of BGR. In
other words, the red and blue components are swapped.
ErrorLevel
ErrorLevel is set to 0 if the color was found in the specified region, 1 if it was not found, or 2 if there
was a problem that prevented the command from conducting the search.
Remarks
The region to be searched must be visible; in other words, it is not possible to search a region of a
window hidden behind another window. By contrast, pixels beneath the mouse cursor can usually be
detected. The exception to this is cursors in games, which in most cases will hide any pixels beneath
them.
Slow mode only: By default, the search starts at the upper-left pixel of the region and checks all pixels
vertically beneath it for a match. If no match is found there, the search continues to the right, column
by column, until it finds a matching pixel. The default left-to-right search order can be inverted by
swapping X1 and X2 in the parameter list. In other words, if X1 is greater than X2, the search will be
conducted from right to left, starting at column X1. Similarly, if Y1 is greater than Y2, each column of
pixels to be searched starting at the bottom rather than the top. Finally, if the region to be searched is
large and the search is repeated with high frequency, it may consume a lot of CPU time. To alleviate
this, keep the size of the area to a minimum.
Related
PixelGetColor, ImageSearch, CoordMode, MouseGetPos
Example
PixelSearch, Px, Py, 200, 200, 300, 300, 0x9d6346, 3, Fast
if ErrorLevel
MsgBox, That color was not found in the specified region.
else
MsgBox, A color within 3 shades of variation was found at X%Px% Y%Py%.
Reload
Replaces the currently running instance of the script with a new one.
Reload
This command is useful for scripts that are frequently changed. By assigning a hotkey to this
command, you can easily restart the script after saving your changes in an editor.
When the script restarts, it is launched in its original working directory (the one that was in effect
when it was first launched). In other words, SetWorkingDir will not change the working directory that
will be used for the new instance.
If the script cannot be reloaded -- perhaps because it has a syntax error -- the original instance of the
script will continue running. Therefore, the reload command should be followed by whatever actions
you want taken in the event of a failure (such as a return to exit the current subroutine). To have the
original instance detect the failure, follow this example:
Printed Documentation
402
Reload
Sleep 1000 ; If successful, the reload will close this instance during the Sleep, so the line
below will never be reached.
MsgBox, 4,, The script could not be reloaded. Would you like to open it for editing?
IfMsgBox, Yes, Edit
return
Related
Edit
Example
^!r::Reload ; Assign Ctrl-Alt-R as a hotkey to restart the script.
SetBatchLines
Determines how fast a script will run (affects CPU utilization).
SetBatchLines, 20ms
SetBatchLines, LineCount
Parameters
20ms
(The 20ms is just an example). If the value ends in ms, it indicates how often
the script should sleep (each sleep is 10 ms long). In the following example,
the script will sleep for 10ms every time it has run for 20ms: SetBatchLines,
20ms
LineCount
The number of script lines to execute prior to sleeping for 10ms. The value can
be as high as 9223372036854775807.
Remarks
Use SetBatchLines -1 to never sleep (i.e. have the script run at maximum speed).
If this command is not used:
AutoIt v2 (.aut) scripts default to SetBatchLines 1, which sleeps after every line.
All other types of scripts (e.g. .ahk) default to SetBatchLines 10ms except in versions prior to
v1.0.16, which use 10 (lines) instead.
The "ms" method is recommended for scripts whenever speed and cooperation are important. For
example, on most systems a setting of 10ms will prevent the script from using any more than 50% of
an idle CPU's time. This allows scripts to run quickly while still maintaining a high level of cooperation
with CPU sensitive tasks such as games and video capture/playback.
The built-in variable A_BatchLines contains the current setting.
The speed of a script can also be impacted by the following commands, depending on the nature of
the script: SetWinDelay, SetControlDelay, SendMode, SetKeyDelay, SetMouseDelay, and
SetDefaultMouseSpeed.
Every newly launched thread (such as a hotkey, custom menu item, or timed subroutine) starts off
fresh with the default setting for this command. That default may be changed by using this command
in the auto-execute section (top part of the script).
Related
SetWinDelay, SetControlDelay, SendMode, SetKeyDelay, SetMouseDelay, SetDefaultMouseSpeed
Misc. Commands
403
Example
SetBatchLines, 10ms
SetBatchLines, 1000
SetEnv (Var = Value)
Assigns the specified value to a variable.
SetEnv, Var, Value
Var = Value
Parameters
Var The name of the variable in which to store Value.
Value
The string or number to store. If the string is long, it can be broken up into
several shorter lines by means of a continuation section, which might improve
readability and maintainability.
Remarks
By default, any spaces or tabs at the beginning and end of Value are omitted from Var. To prevent
this, use AutoTrim Off beforehand. However, `t (the tab character) is unconditionally omitted. To
prevent this, use %A_Tab% in place of `t.
The name "SetEnv" is misleading and is used only for backward compatibility with AutoIt v2. Unlike
AutoIt v2, AutoHotkey does not store its variables in the environment. This is because performance
would be worse and also because the OS limits such variables to 32K. Use EnvSet instead of SetEnv to
write to an environment variable.
The memory occupied by a large variable can be freed by setting it equal to nothing, e.g. var =
It is possible to create an array with this command and any others that accept an OutputVar. This is
done by making OuputVar contain a reference to another variable, e.g. array%i% = 123. See Arrays
for more details.
Related
AutoTrim, EnvSet, EnvAdd, EnvSub, EnvMult, EnvDiv, If, Arrays
Example
Var1 = This is a string.
Color2 = 450
Color3 = %Var1%
Array%i% = %A_TICKCOUNT%
SetTimer
Causes a subroutine to be launched automatically and repeatedly at a specified time interval.
SetTimer, Label [, Period|On|Off, Priority]
Parameters
Label
The name of the label or hotkey label to which to jump, which causes the
commands beneath Label to be executed until a Return or Exit is encountered.
Printed Documentation
404
As with the parameters of almost all other commands, Label can be a variable
reference such as %MyLabel%, in which case the name stored in the variable
is used as the target.
Period|On|Off
On: Re-enables a previously disabled timer at its former period. If the timer
doesn't exist, it is created (with a default period of 250).
Off: Disables an existing timer.
Period: Creates or updates a timer using this parameter as the number of
milliseconds that must pass since the last time the Label subroutine was
started. When this amount of time has passed, Label will be run again (unless
it is still running from the last time). The timer will be automatically enabled.
To prevent this, call the command a second time immediately afterward,
specifying OFF for this parameter.
If this parameter is blank and:
1) the timer does not exist: it will be created with a period of 250.
2) the timer already exists: it will be enabled and reset at its former period
unless a Priority is specified.
Priority
This optional parameter is an integer between -2147483648 and 2147483647
(or an expression) to indicate this timer's thread priority. If omitted, 0 will be
used. See Threads for details.
To change the priority of an existing timer without affecting it in any other
way, leave the parameter before this one blank.
Remarks
Timers are useful because they run asynchronously, meaning that they will run at the specified
frequency (interval) even when the script is waiting for a window, displaying a dialog, or busy with
another task. Examples of their many uses include taking some action when the user becomes idle (as
reflected by %A_TimeIdle%) or closing unwanted windows the moment they appear.
Although timers may give the illusion that the script is performing more than one task simultaneously,
this is not the case. Instead, timed subroutines are treated just like other threads: they can interrupt
or be interrupted by another thread, such as a hotkey subroutine. See Threads for details.
Whenever a timer is created, re-enabled, or updated with a new period, it will not run right away; its
time period must expire first. If you wish the timer's first execution to be immediate, use Gosub to
execute the timer's subroutine (however, this will not start a new thread like the timer itself does; so
settings such as SendMode will not start off at their defaults).
If SetTimer is used on an existing timer and parameter #2 is a number or the word ON (or it is
omitted), the timer's internal "time of last run" will be reset to the current time; in other words, the
entirety of its period must elapse before it will run again.
Currently, timers cannot run much more often than every 10ms on Windows XP/2000/NT and about
55ms on Windows 9x. Specifying a Period less than this will usually result in an actual interval of 10 or
55 (but this policy could change in future versions so shouldn't be relied upon).
A timer might not be able to run as often as specified under the following conditions:
1. Other applications are putting a heavy load on the CPU.
2. The timer subroutine itself takes longer than its own period to run, or there are too many
other competing timers (altering SetBatchLines may help).
3. The timer has been interrupted by another thread, namely another timed subroutine, hotkey
subroutine, or custom menu item. If this happens and the interrupting thread takes a long
time to finish, the interrupted timer will be effectively disabled for the duration. However, any
other timers will continue to run by interrupting the thread that interrupted the first timer.
Misc. Commands
405
4. The script is uninterruptible as a result of Critical or Thread Interrupt/Priority. During such
times, timers will not run. Later, when the script becomes interruptible again, any overdue
timer will run once as soon as possible and then resume its normal schedule.
Because timers operate by temporarily interrupting the script's current activity, their subroutines
should be kept short (so that they finish quickly) whenever a long interruption would be undesirable.
Timers that stay in effect for the duration of a script should usually be created in the auto-execute
section. By contrast, a temporary timer might often be disabled by its own subroutine (see examples
at the bottom of this page).
Whenever a timed subroutine is run, it starts off fresh with the default values for settings such as
SendMode. These defaults can be changed in the auto-execute section.
Although timers will operate when the script is suspended, they will not run if the current thread has
"Thread NoTimers" in effect or whenever any thread is paused. In addition, they do not operate when
the user is navigating through one of the script's menus (such as the tray icon menu or a menu bar).
If hotkey response time is crucial (such as in games) and the script contains any timers whose
subroutines take longer than about 5 ms to execute, use the following command to avoid any chance
of a 15 ms delay. Such a delay would otherwise happen if a hotkey is pressed at the exact moment a
timer thread is in its period of uninterruptibility:
Thread, interrupt, 0 ; Make all threads always-interruptible.
If a timer is disabled while its subroutine is currently running, that subroutine will continue until it
completes.
The KeyHistory feature shows how many timers exist and how many are currently enabled.
In v1.0.36.03+, a timer's period can be no larger than 4294967295 milliseconds (49.7 days). In
earlier versions, the limit is 2147483647 milliseconds (24.8 days).
To keep a script running -- such as one that contains only timers -- use #Persistent.
Related
Gosub, Return, Threads, Thread (command), Critical, IsLabel(), Menu, #Persistent
Examples
; Example #1: Close unwanted windows whenever they appear:
#Persistent
SetTimer, CloseMailWarnings, 250
return

CloseMailWarnings:
WinClose, Microsoft Outlook, A timeout occured while communicating
WinClose, Microsoft Outlook, A connection to the server could not be established
return

; Example #2: Wait for a certain window to appear and then alert the user:
#Persistent
SetTimer, Alert1, 500
return

Printed Documentation
406
Alert1:
IfWinNotExist, Video Conversion, Process Complete
return
; Otherwise:
SetTimer, Alert1, Off ; i.e. the timer turns itself off here.
SplashTextOn, , , The video conversion is finished.
Sleep, 3000
SplashTextOff
return

; Example #3: Detection of single, double, and triple-presses of a hotkey. This
; allows a hotkey to perform a different operation depending on how many times
; you press it:
#c::
if winc_presses > 0 ; SetTimer already started, so we log the keypress instead.
{
winc_presses += 1
return
}
; Otherwise, this is the first press of a new series. Set count to 1 and start
; the timer:
winc_presses = 1
SetTimer, KeyWinC, 400 ; Wait for more presses within a 400 millisecond window.
return

KeyWinC:
SetTimer, KeyWinC, off
if winc_presses = 1 ; The key was pressed once.
{
Run, m:\ ; Open a folder.
}
else if winc_presses = 2 ; The key was pressed twice.
{
Run, m:\multimedia ; Open a different folder.
}
else if winc_presses > 2
{
MsgBox, Three or more clicks detected.
Misc. Commands
407
}
; Regardless of which action above was triggered, reset the count to
; prepare for the next series of presses:
winc_presses = 0
return
SysGet
Retrieves screen resolution, multi-monitor info, dimensions of system objects, and other system
properties.
SysGet, OutputVar, Sub-command [, Param3]
Parameters
OutputVar The name of the variable in which to store the result.
Sub-
command
See list below.
Param3 This parameter is omitted except where noted below.
Sub-commands
MonitorCount: Retrieves the total number of monitors. Unlike SM_CMONITORS mentioned in the
table below, MonitorCount includes all monitors, even those not being used as part of the desktop. On
Windows 95/NT the count is always 1.
MonitorPrimary: Retrieves the number of the primary monitor, which will be 1 in a single-monitor
system. On Windows 95/NT the primary monitor is always 1.
Monitor [, N] : Retrieves the bounding coordinates of monitor number N (if N is omitted, the primary
monitor is used). The information is stored in four variables whose names all start with OutputVar. If
N is too high or there is a problem retrieving the info, the variables are all made blank. For example:
SysGet, Mon2, Monitor, 2
MsgBox, Left: %Mon2Left% -- Top: %Mon2Top% -- Right: %Mon2Right% -- Bottom
%Mon2Bottom%.
Within a function, to create a set of variables that is global instead of local, declare Mon2 as a global
variable prior to using this command (the converse is true for assume-global functions).
MonitorWorkArea [, N]: Same as the above except the area is reduced to exclude the area occupied
by the taskbar and other registered desktop toolbars.
MonitorName [, N]: The operating system's name for monitor number N (if N is omitted, the
primary monitor is used).
(Numeric): Specify for Sub-command one of the numbers from the table below to retrieve the
corresponding value. The following example would store the number of mouse buttons in a variable
named "MouseButtonCount":
SysGet, MouseButtonCount, 43
Commonly Used
Number Description
80
SM_CMONITORS: Number of display monitors on the desktop (not including "non-
display pseudo-monitors"). Windows 95/NT: The retrieved value is always 0.
43 SM_CMOUSEBUTTONS: Number of buttons on mouse (0 if no mouse is installed).
Printed Documentation
408
16, 17
SM_CXFULLSCREEN, SM_CYFULLSCREEN: Width and height of the client area for a
full-screen window on the primary display monitor, in pixels.
61, 62
SM_CXMAXIMIZED, SM_CYMAXIMIZED: Default dimensions, in pixels, of a
maximized top-level window on the primary display monitor.
59, 60
SM_CXMAXTRACK, SM_CYMAXTRACK: Default maximum dimensions of a window
that has a caption and sizing borders, in pixels. This metric refers to the entire
desktop. The user cannot drag the window frame to a size larger than these
dimensions.
28, 29 SM_CXMIN, SM_CYMIN: Minimum width and height of a window, in pixels.
57, 58
SM_CXMINIMIZED, SM_CYMINIMIZED: Dimensions of a minimized window, in
pixels.
34, 35
SM_CXMINTRACK, SM_CYMINTRACK: Minimum tracking width and height of a
window, in pixels. The user cannot drag the window frame to a size smaller than
these dimensions. A window can override these values by processing the
WM_GETMINMAXINFO message.
0, 1
SM_CXSCREEN, SM_CYSCREEN: Width and height of the screen of the primary
display monitor, in pixels. These are the same as the built-in variables
A_ScreenWidth and A_ScreenHeight.
78, 79
SM_CXVIRTUALSCREEN, SM_CYVIRTUALSCREEN: Width and height of the virtual
screen, in pixels. The virtual screen is the bounding rectangle of all display
monitors. The SM_XVIRTUALSCREEN, SM_YVIRTUALSCREEN metrics are the
coordinates of the top-left corner of the virtual screen. Windows NT, Windows
95: The retrieved value is always 0.
19 SM_MOUSEPRESENT: Nonzero if a mouse is installed; zero otherwise.
75
SM_MOUSEWHEELPRESENT: Nonzero if a mouse with a wheel is installed; zero
otherwise. Windows 95: The retrieved value is always 0.
63
SM_NETWORK: Least significant bit is set if a network is present; otherwise, it is
cleared. The other bits are reserved for future use.
8193
SM_REMOTECONTROL: This system metric is used in a Terminal Services
environment. Its value is nonzero if the current session is remotely controlled; zero
otherwise. Windows 2000/NT, Windows Me/98/95: The retrieved value is
always 0.
4096
SM_REMOTESESSION: This system metric is used in a Terminal Services
environment. If the calling process is associated with a Terminal Services client
session, the return value is nonzero. If the calling process is associated with the
Terminal Server console session, the return value is zero. The console session is
not necessarily the physical console. Windows NT 4.0 SP3 and earlier,
Windows Me/98/95: The retrieved value is always 0.
70
SM_SHOWSOUNDS: Nonzero if the user requires an application to present
information visually in situations where it would otherwise present the information
only in audible form; zero otherwise.
8192
SM_SHUTTINGDOWN: Nonzero if the current session is shutting down; zero
otherwise. Windows 2000/NT, Windows Me/98/95: The retrieved value is
always 0.
23
SM_SWAPBUTTON: Nonzero if the meanings of the left and right mouse buttons
are swapped; zero otherwise.
76, 77
SM_XVIRTUALSCREEN, SM_YVIRTUALSCREEN: Coordinates for the left side and
the top of the virtual screen. The virtual screen is the bounding rectangle of all
display monitors. By contrast, the SM_CXVIRTUALSCREEN, SM_CYVIRTUALSCREEN
Misc. Commands
409
metrics (further above) are the width and height of the virtual screen. Windows
NT, Windows 95: The retrieved value is always 0.
Not Commonly Used
Number Description
56
SM_ARRANGE: Flags specifying how the system arranged minimized windows. See
MSDN for more information.
67
SM_CLEANBOOT: Specifies how the system was started:
0 Normal boot
1 Fail-safe boot
2 Fail-safe with network boot
5, 6
SM_CXBORDER, SM_CYBORDER: Width and height of a window border, in pixels.
This is equivalent to the SM_CXEDGE value for windows with the 3-D look.
13, 14
SM_CXCURSOR, SM_CYCURSOR: Width and height of a cursor, in pixels. The
system cannot create cursors of other sizes.
36, 37
SM_CXDOUBLECLK, SM_CYDOUBLECLK: Width and height of the rectangle around
the location of a first click in a double-click sequence, in pixels. The second click
must occur within this rectangle for the system to consider the two clicks a double-
click. (The two clicks must also occur within a specified time.)
68, 69
SM_CXDRAG, SM_CYDRAG: Width and height of a rectangle centered on a drag
point to allow for limited movement of the mouse pointer before a drag operation
begins. These values are in pixels. It allows the user to click and release the mouse
button easily without unintentionally starting a drag operation.
45, 46
SM_CXEDGE, SM_CYEDGE: Dimensions of a 3-D border, in pixels. These are the 3-
D counterparts of SM_CXBORDER and SM_CYBORDER.
7, 8
SM_CXFIXEDFRAME, SM_CYFIXEDFRAME (synonymous with SM_CXDLGFRAME,
SM_CYDLGFRAME): Thickness of the frame around the perimeter of a window that
has a caption but is not sizable, in pixels. SM_CXFIXEDFRAME is the height of the
horizontal border and SM_CYFIXEDFRAME is the width of the vertical border.
83, 84
SM_CXFOCUSBORDER, SM_CYFOCUSBORDER: Width (in pixels) of the left and
right edges and the height of the top and bottom edges of a control's focus
rectangle. Windows 2000/NT, Windows Me/98/95: The retrieved value is
always 0.
21, 22
SM_CXHSCROLL, SM_CYHSCROLL: Width of the arrow bitmap on a horizontal scroll
bar, in pixels; and height of a horizontal scroll bar, in pixels.
10 SM_CXHTHUMB: Width of the thumb box in a horizontal scroll bar, in pixels.
11, 12 SM_CXICON, SM_CYICON: Default width and height of an icon, in pixels.
38, 39
SM_CXICONSPACING, SM_CYICONSPACING: Dimensions of a grid cell for items in
large icon view, in pixels. Each item fits into a rectangle of this size when
arranged. These values are always greater than or equal to SM_CXICON and
SM_CYICON.
71, 72
SM_CXMENUCHECK, SM_CYMENUCHECK: Dimensions of the default menu check-
mark bitmap, in pixels.
54, 55
SM_CXMENUSIZE, SM_CYMENUSIZE: Dimensions of menu bar buttons, such as
the child window close button used in the multiple document interface, in pixels.
47, 48
SM_CXMINSPACING SM_CYMINSPACING: Dimensions of a grid cell for a minimized
window, in pixels. Each minimized window fits into a rectangle this size when
arranged. These values are always greater than or equal to SM_CXMINIMIZED and
Printed Documentation
410
SM_CYMINIMIZED.
30, 31
SM_CXSIZE, SM_CYSIZE: Width and height of a button in a window's caption or
title bar, in pixels.
32, 33
SM_CXSIZEFRAME, SM_CYSIZEFRAME: Thickness of the sizing border around the
perimeter of a window that can be resized, in pixels. SM_CXSIZEFRAME is the
width of the horizontal border, and SM_CYSIZEFRAME is the height of the vertical
border. Synonymous with SM_CXFRAME and SM_CYFRAME.
49, 50
SM_CXSMICON, SM_CYSMICON: Recommended dimensions of a small icon, in
pixels. Small icons typically appear in window captions and in small icon view.
52, 53 SM_CXSMSIZE SM_CYSMSIZE: Dimensions of small caption buttons, in pixels.
2, 20
SM_CXVSCROLL, SM_CYVSCROLL: Width of a vertical scroll bar, in pixels; and
height of the arrow bitmap on a vertical scroll bar, in pixels.
4 SM_CYCAPTION: Height of a caption area, in pixels.
18
SM_CYKANJIWINDOW: For double byte character set versions of the system, this
is the height of the Kanji window at the bottom of the screen, in pixels.
15 SM_CYMENU: Height of a single-line menu bar, in pixels.
51 SM_CYSMCAPTION: Height of a small caption, in pixels.
9 SM_CYVTHUMB: Height of the thumb box in a vertical scroll bar, in pixels.
42
SM_DBCSENABLED: Nonzero if User32.dll supports DBCS; zero otherwise.
Windows Me/98/95: Nonzero if the double-byte character-set (DBCS) version
of User.exe is installed; zero otherwise.
22 SM_DEBUG: Nonzero if the debug version of User.exe is installed; zero otherwise.
82
SM_IMMENABLED: Nonzero if Input Method Manager/Input Method Editor features
are enabled; zero otherwise. Windows NT, Windows Me/98/95: The retrieved
value is always 0.
SM_IMMENABLED indicates whether the system is ready to use a Unicode-based
IME on a Unicode application. To ensure that a language-dependent IME works,
check SM_DBCSENABLED and the system ANSI code page. Otherwise the ANSI-to-
Unicode conversion may not be performed correctly, or some components like
fonts or registry setting may not be present.
87
SM_MEDIACENTER: Nonzero if the current operating system is the Windows XP,
Media Center Edition, zero if not.
40
SM_MENUDROPALIGNMENT: Nonzero if drop-down menus are right-aligned with
the corresponding menu-bar item; zero if the menus are left-aligned.
74
SM_MIDEASTENABLED: Nonzero if the system is enabled for Hebrew and Arabic
languages, zero if not.
41
SM_PENWINDOWS: Nonzero if the Microsoft Windows for Pen computing
extensions are installed; zero otherwise.
44 SM_SECURE: Nonzero if security is present; zero otherwise.
81
SM_SAMEDISPLAYFORMAT: Nonzero if all the display monitors have the same color
format, zero otherwise. Note that two displays can have the same bit depth, but
different color formats. For example, the red, green, and blue pixels can be
encoded with different numbers of bits, or those bits can be located in different
places in a pixel's color value. Windows NT, Windows 95: The retrieved value is
always 0.
Misc. Commands
411
73
SM_SLOWMACHINE: Nonzero if the computer has a low-end (slow) processor; zero
otherwise.
86
SM_TABLETPC: Nonzero if the current operating system is the Windows XP Tablet
PC edition, zero if not.
Remarks
The built-in variables A_ScreenWidth and A_ScreenHeight contain the dimensions of the primary
monitor, in pixels.
Related
DllCall, WinGet
Examples
; Example #1:
SysGet, MouseButtonCount, 43
SysGet, VirtualScreenWidth, 78
SysGet, VirtualScreenHeight, 79

; Example #2: This is a working script that displays info about each monitor:
SysGet, MonitorCount, MonitorCount
SysGet, MonitorPrimary, MonitorPrimary
MsgBox, Monitor Count:`t%MonitorCount%`nPrimary Monitor:`t%MonitorPrimary%
Loop, %MonitorCount%
{
SysGet, MonitorName, MonitorName, %A_Index%
SysGet, Monitor, Monitor, %A_Index%
SysGet, MonitorWorkArea, MonitorWorkArea, %A_Index%
MsgBox, Monitor:`t#%A_Index%`nName:`t%MonitorName%`nLeft:`t%MonitorLeft%
(%MonitorWorkAreaLeft% work)`nTop:`t%MonitorTop% (%MonitorWorkAreaTop%
work)`nRight:`t%MonitorRight% (%MonitorWorkAreaRight% work)`nBottom:`t%MonitorBottom%
(%MonitorWorkAreaBottom% work)
}
Thread
Sets the priority or interruptibility of threads. It can also temporarily disable all timers.
Thread, NoTimers [, false]
Thread, Priority, n
Thread, Interrupt [, Duration, LineCount]

Thread, NoTimers [, false] [v1.0.40.01+]: Prevents interruptions from any timers until the current
thread either ends, executes "Thread, NoTimers, false", or is interrupted by another thread that allows
timers (in which case timers can interrupt the interrupting thread until it finishes).
If "Thread NoTimers" is not used in the auto-execute section (top part of the script), all threads start
off as interruptible by timers (though the settings of "Thread Interrupt" [below] will still apply). By
Printed Documentation
412
contrast, if the auto-execute section turns on NoTimers but never turns it off, every newly launched
thread (such as a hotkey, custom menu item, or timer) starts off immune to interruptions by timers.
Regardless of the default setting, timers will always operate when the script has no threads (unless
Pause has been turned on).
"Thread, NoTimers" is equivalent to "Thread, NoTimers, true". In addition, since the true/false
parameter is an expression, true resolves to 1, and false to 0.

Thread, Priority, n: Specify for n an integer between -2147483648 and 2147483647 (or an
expression) to indicate the current thread's new priority. This has no effect on other threads. See
Threads for details.
Due to its ability to buffer events, the command "Critical" is generally superior to "Thread Priority".
On a related note, the OS's priority level for the entire script can be changed as in this example:
Process, Priority,, High

Thread, Interrupt [, Duration, LineCount]: This command should be used sparingly because most
scripts perform more consistently with settings close to the defaults.
By default, every newly launched thread is uninterruptible for a Duration of 15 milliseconds or a
LineCount of 1000 script lines, whichever comes first. This gives the thread a chance to finish rather
than being immediately interrupted by another thread that is waiting to launch (such as a buffered
hotkey or a series of timed subroutines that are all due to be run).
If either component is 0, each newly launched thread is immediately interruptible. If either component
is -1, the thread cannot be interrupted as a result of that component.
The Interrupt setting is global, meaning that all subsequent threads will obey it, even if the setting is
changed somewhere other than the auto-execute section. However, interrupted threads are
unaffected because their period of uninterrutibility has already expired. Similarly, the current thread is
unaffected except if it is uninterruptible at the time the LineCount component is changed, in which
case the new LineCount will be in effect for it.
If a hotkey is pressed or a custom menu item is selected while the current thread is uninterruptible,
that event will be buffered. In other words, it will launch when the current thread finishes or becomes
interruptible, whichever comes first. The exception to this is when the current thread becomes
interruptible before it finishes, and it is of higher priority than the buffered event; in this case the
buffered event is unbuffered and discarded.
Regardless of this setting, a thread will become interruptible the moment it displays a MsgBox,
InputBox, FileSelectFile, or FileSelectFolder dialog.
Either parameter can be left blank to avoid changing it.
Remarks
Due to its greater flexibilty and its ability to buffer events, the command "Critical" is generally more
useful than "Thread Interrupt" and "Thread Priority".
Related
Critical, Threads, Hotkey, Menu, SetTimer, Process
Example
Thread, priority, 1 ; Make priority of current thread slightly above average.
Thread, interrupt, 0 ; Make each newly launched thread immediately interruptible:
Thread, interrupt, 50, 2000 ; Make each thread interruptible after 50ms or 2000 lines, whichever
comes first.
Misc. Commands
413
Transform
Performs miscellaneous math functions, bitwise operations, and tasks such as ASCII/Unicode
conversion.
Transform, OutputVar, Cmd, Value1 [, Value2]
Parameters
OutputVar
The name of the variable in which to store the result of Cmd. SetFormat
determines whether integers are stored as hexadecimal or decimal.
Cmd,
Value1/2
See list below.
Cmd, Value1, Value2
The Cmd, Value1 and Value2 parameters are dependent upon each other and their usage is described
below.
Unicode [, String]: Retrieves or stores Unicode text on the clipboard. Note: The entire clipboard may
be saved and restored by means of ClipboardAll, which allows "Transform Unicode" to operate without
losing the original contents of the clipboard.
There are two modes of operation as illustrated in the following examples:
Transform, OutputVar, Unicode ; Retrieves the clipboard's Unicode text as a UTF-8 string.
Transform, Clipboard, Unicode, %MyUTF_String% ; Places Unicode text onto the clipboard.
In the second example above, a literal UTF-8 string may be optionally used in place of
%MyUTF_String%.
Use a hotkey such as the following to determine the UTF-8 string that corresponds to a given Unicode
string:
^!u:: ; Control+Alt+U hotkey.
MsgBox Copy some Unicode text onto the clipboard, then return to this window and press OK
to continue.
Transform, ClipUTF, Unicode
Clipboard = Transform, Clipboard, Unicode, %ClipUTF%`r`n
MsgBox The clipboard now contains the following line that you can paste into your script.
When executed, this line will cause the original Unicode string you copied to be placed onto
the clipboard:`n`n%Clipboard%
return
Notes: 1) Windows 95 requires the Microsoft Layer for Unicode to support this command (Windows
98/Me/NT4 or later have built-in support); 2) The "Send {ASC nnnnn}" command is an alternate way
to produce Unicode characters, but it does not work in all applications.

Asc, String: Retrieves the ASCII code (a number between 1 and 255) for the first character in String.
If String is empty, OutputVar will also be made empty. For example: Transform, OutputVar, Asc,
%VarContainingString%. Corresponding function: Asc(String).
Chr, Value1: Retrieves the single character corresponding to the ASCII code indicated by Value1. If
Value1 is not between 1 and 255 inclusive, OutputVar will be made blank to indicate the problem. For
example: Transform, OutputVar, Chr, 130. Corresponding function: Chr(Number).
Deref, String: Expands variable references and escape sequences contained inside other variables.
Any badly formatted variable references will be omitted from the expanded result. The same is true if
OutputVar is expanded into itself; in other words, any references to OutputVar inside String's variables
Printed Documentation
414
will be omitted from the expansion (note however that String itself can be %OutputVar%). In the
following example, if var1 contains the string "test" and var2 contains the literal string "%var1%",
OutputVar will be set to the string "test": Transform, OutputVar, deref, %var2%. Within a function,
each variable in String always resolves to a local variable unless there is no such variable, in which
case it resolves to a global variable (or blank if none).
HTML, String: Converts String into its HTML equivalent by translating characters whose ASCII values
are above 127 to their HTML names (e.g. becomes &pound;). In addition, the four characters "&<>
are translated to &quot;&amp;&lt;&gt;. Finally, each linefeed (`n) is translated to <br>`n (i.e. <br>
followed by a linefeed).
Mod, Dividend, Divisor: Retrieves the remainder of Dividend divided by Divisor. If Divisor is zero,
OutputVar will be made blank. Dividend and Divisor can both contain a decimal point. If negative,
Divisor will be treated as positive for the calculation. In the following example, the result is 2:
Transform, OutputVar, mod, 5, 3. Corresponding function: Mod(Dividend, Divisor).
Pow, Base, Exponent: Retrieves Base raised to the power of Exponent. Both Base and Exponent
may contain a decimal point. If Exponent is negative, OutputVar will be formatted as a floating point
number even if Base and Exponent are both integers. A negative Base combined with a fractional
Exponent such as 1.5 is not supported; it will cause OutputVar to be made blank. See also: **
operator.
Exp, N: Retrieves e (which is approximately 2.71828182845905) raised to the Nth power. N may be
negative and may contain a decimal point. Corresponding function: Exp(N).
Sqrt, Value1: Retrieves the square root of Value1. If Value1 is negative, OutputVar will be made
blank. Corresponding function: Sqrt(Number).
Log, Value1: Retrieves the logarithm (base 10) of Value1. If Value1 is negative, OutputVar will be
made blank. Corresponding function: Log(Number).
Ln, Value1: Retrieves the natural logarithm (base e) of Value1. If Value1 is negative, OutputVar will
be made blank. Corresponding function: Ln(Number).
Round, Value1 [, N]: If N is omitted, OutputVar will be set to Value1 rounded to the nearest integer.
If N is positive number, Value1 will be rounded to N decimal places. If N is negative, Value1 will be
rounded by N digits to the left of the decimal point. For example, -1 rounds to the ones place, -2
rounds to the tens place, and-3 rounds to the hundreds place. Note: Round does not remove trailing
zeros when rounding decimal places. For example, 12.333 rounded to one decimal place would
become 12.300000. This behavior can be altered by using something like SetFormat, float, 0.1 prior to
the operation (in fact, SetFormat might eliminate the need to use Round in the first place).
Corresponding function: Round(Number [, N]).
Ceil, Value1: Retrieves Value1 rounded up to the nearest integer. Corresponding function:
Ceil(Number).
Floor, Value1: Retrieves Value1 rounded down to the nearest integer. Corresponding function:
Floor(Number).
Abs, Value1: Retrieves the absolute value of Value1, which is computed by removing the leading
minus sign (dash) from Value1 if it has one. Corresponding function: Abs(Number).
Sin, Value1: Retrieves the trigonometric sine of Value1. Value1 must be expressed in radians.
Corresponding function: Sin(Number).
Cos, Value1: Retrieves the trigonometric cosine of Value1. Value1 must be expressed in radians.
Corresponding function: Cos(Number).
Tan, Value1: Retrieves the trigonometric tangent of Value1. Value1 must be expressed in radians.
Corresponding function: Tan(Number).
ASin, Value1: Retrieves the arcsine (the number whose sine is Value1) in radians. If Value1 is less
than -1 or greater than 1, OutputVar will be made blank. Corresponding function: ASin(Number).
ACos, Value1: Retrieves the arccosine (the number whose cosine is Value1) in radians. If Value1 is
less than -1 or greater than 1, OutputVar will be made blank. Corresponding function: ACos(Number).
Misc. Commands
415
ATan, Value1: Retrieves the arctangent (the number whose tangent is Value1) in radians.
Corresponding function: ATan(Number).

NOTE: Each of the following bitwise operations has a more concise bitwise operator for use in
expressions.
BitNot, Value1: Stores the bit-inverted version of Value1 in OutputVar (if Value1 is floating point, it
is truncated to an integer prior to the calculation). If Value1 is between 0 and 4294967295 (0xffffffff),
it will be treated as an unsigned 32-bit value. Otherwise, it is treated as a signed 64-bit value. In the
following example, the result is 0xfffff0f0 (4294963440): Transform, OutputVar, BitNot, 0xf0f
BitAnd, Value1, Value2: Retrieves the result of the bitwise-AND of Value1 and Value2 (floating point
values are truncated to integers prior to the calculation). In the following example, the result is 0xff00
(65280): Transform, OutputVar, BitAnd, 0xff0f, 0xfff0
BitOr, Value1, Value2: Retrieves the result of the bitwise-OR of Value1 and Value2 (floating point
values are truncated to integers prior to the calculation). In the following example, the result is 0xf0f0
(61680): Transform, OutputVar, BitOr, 0xf000, 0x00f0
BitXOr, Value1, Value2: Retrieves the result of the bitwise-EXCLUSIVE-OR of Value1 and Value2
(floating point values are truncated to integers prior to the calculation). In the following example, the
result is 0xff00 (65280): Transform, OutputVar, BitXOr, 0xf00f, 0x0f0f
BitShiftLeft, Value1, Value2: Retrieves the result of shifting Value1 to the left by Value2 bit
positions, which is equivalent to multiplying Value1 by "2 to the Value2th power" (floating point values
are truncated to integers prior to the calculation). In the following example, the result is 8: Transform,
OutputVar, BitShiftLeft, 1, 3
BitShiftRight, Value1, Value2: Retrieves the result of shifting Value1 to the right by Value2 bit
positions, which is equivalent to dividing Value1 by "2 to the Value2th power", truncating the
remainder (floating point values are truncated to integers prior to the calculation). In the following
example, the result is 2: Transform, OutputVar, BitShiftRight, 17, 3
Remarks
Sub-commands that accept numeric parameters can also use expressions for those parameters.
If either Value1 or Value2 is a floating point number, the following Cmds will retrieve a floating point
number rather than an integer: Mod, Pow, Round, and Abs. The number of decimal places retrieved is
determined by SetFormat.
To convert a radians value to degrees, multiply it by 180/pi (approximately 57.29578). To convert a
degrees value to radians, multiply it by pi/180 (approximately 0.01745329252).
The value of pi (approximately 3.141592653589793) is 4 times the arctangent of 1.
Related
SetFormat, Expressions, EnvMult, EnvDiv, StringLower, if var is type
Example
Transform, OutputVar, Asc, A ; Get the ASCII code of the letter A.
UrlDownloadToFile
Downloads a file from the Internet.
UrlDownloadToFile, URL, Filename
Parameters
Printed Documentation
416
URL
URL of the file to download. For example, http://someorg.org might retrieve
the welcome page for that organization.
Filename
Name of the file to be created locally, which is assumed to be in
%A_WorkingDir% if an absolute path isn't specified. Any existing file will be
overwritten by the new file.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
The download might appear to succeed even when the remote file doesn't exist. This is because many
web servers send an error page instead of the missing file. This error page is what will be saved in
place of Filename.
Internet Explorer 3 or greater must be installed for this function to work. Firewalls or the presence of
multiple network adapters may cause this function to fail. Also, some websites may block such
downloads.
Caching:
In v1.0.44.07+, the URL is retrieved directly from the remote server (that is, never from
Internet Explorer's cache). To permit caching, precede the URL with *0 followed by a space;
for example: *0 http://someorg.org. The zero following the asterisk may be replaced by any
valid dwFlags number; for details, search www.microsoft.com for InternetOpenUrl.
In versions older than 1.0.44.07, the file is retrieved from the cache whenever possible. To
avoid this, specify a query string at the end of the URL. For example:
http://www.someorg.org/doc.html?fakeParam=42. Note: If you download the same file
frequently, the query string should be varied.
Proxies: UrlDownloadToFile will use a proxy server to access the Internet if such a proxy has been
configured in Microsoft Internet Explorer's settings.
Related
FileRead, FileCopy
Examples
UrlDownloadToFile, http://www.autohotkey.com/download/CurrentVersion.txt, C:\AutoHotkey Latest
Version.txt
UrlDownloadToFile, http://someorg.org/archive.zip, C:\SomeOrg's Archive.zip
VarSetCapacity()
Enlarges a variable's holding capacity or frees its memory. Normally, this is necessary only for unusual
circumstances such as DllCall.
GrantedCapacity := VarSetCapacity(UnquotedVarName [, RequestedCapacity, FillByte])
Parameters
GrantedCapacity
The length of string that Var can now hold, which will be greater or equal
to RequestedCapacity. If VarName is not a valid variable name (such as
a literal string or number), 0 is returned. If the system has insufficient
memory to make the change (very rare), an error dialog will be
displayed and the current thread will exit.
Misc. Commands
417
UnquotedVarName
The name of the variable (not in quotes). For example:
VarSetCapacity(MyVar, 1000). This can also be a dynamic variable such
as Array%i% or a function's ByRef parameter.
RequestedCapacity
If omitted, the variable's current capacity will be returned and its
contents will not be altered. Otherwise, anything currently in the variable
is lost (the variable becomes blank).
Specify for RequestedCapacity the length of string that the variable
should be able to hold after the adjustment. This length does not include
the internal zero terminator. For example, specifying 1 would allow the
variable to hold up to one character in addition to its internal terminator.
Note: the variable will auto-expand if the script assigns it a larger value
later.
Since this function is often called simply to ensure the variable has a
certain minimum capacity, for performance reasons, it shrinks the
variable only when RequestedCapacity is 0. In other words, if the
variable's capacity is already greater than RequestedCapacity, it will not
be reduced (but the variable will still made blank for consistency).
Therefore, to explicitly shrink a variable, first free its memory with
VarSetCapacity(Var, 0) and then use VarSetCapacity(Var, NewCapacity)
-- or simply let it auto-expand from zero as needed.
For performance reasons, freeing a variable whose previous capacity was
between 1 and 63 might have no effect because its memory is of a
permanent type. In this case, the current capacity will be returned rather
than 0.
In v1.0.44.03+, specify -1 for RequestedCapacity to update the
variable's internally-stored length to the length of its current contents.
This is useful in cases where the variable has been altered indirectly,
such as by passing its address via DllCall(). In this mode,
VarSetCapacity() returns the length rather than the capacity.
FillByte
[v1.0.36.07+]
This parameter is normally omitted, in which case the memory of the
target variable is not initialized (instead, the variable is simply made
blank as described above). Otherwise, specify a number between 0 and
255. Each byte in the target variable's memory area (its current
capacity) is set to that number. Zero is by far the most common value,
which is useful in cases where the variable will hold raw binary data such
as a DllCall structure.
Remarks
In addition to its uses described at DllCall, this function can also be used to enhance performance
when building a string by means of gradual concatenation. This is because multiple automatic
resizings can be avoided when you have some idea of what the string's final length will be. In such a
case, RequestedCapacity need not be accurate: if the capacity is too small, performance is still
improved and the variable will begin auto-expanding when the capacity has been exhausted. If the
capacity is too large, some of the memory is wasted, but only temporarily because all the memory can
be freed after the operation by means of VarSetCapacity(Var, 0) or Var := "".
#MaxMem restricts only the automatic expansion that a variable does on its own. It does not affect
VarSetCapacity.
Related
DllCall, #MaxMem
Printed Documentation
418
Example
VarSetCapacity(MyVar, 10240000) ; ~10 MB
Loop
{
...
MyVar = %MyVar%%StringToConcatenate%
...
}

419
Mouse Control
Click [v1.0.43+]
Clicks a mouse button at the specified coordinates. It can also hold down a mouse button, turn the
mouse wheel, or move the mouse.
Here are examples of common usages (all commas are optional):
Click (by itself) Clicks the left mouse button once at the mouse cursor's current position.
Click 44, 55
Clicks the left mouse button once at coordinates 44, 55 (based on
CoordMode).
Click right 44,
55
Same as above but clicks the right mouse button.
Click 2
Clicks the left mouse button twice at the cursor's current position (i.e.
double-click).
Click down Presses the left mouse button down and holds it.
Click up right Releases the right mouse button.
Zero or more of the following items can follow the word Click. Separate each item from the next with
at least one space, tab, and/or comma. The items can appear in any order except ClickCount, which
must occur somewhere to the right of the coordinates (if coordinates are present).
X, Y: The x/y coordinates to which the mouse cursor is moved prior to clicking. Coordinates are
relative to the active window unless CoordMode was used to change that. If omitted, the cursor's
current position is used.
Button Name: Left (default), Right, Middle (or just the first letter of each of these); or the fourth or
fifth mouse button (X1 or X2), which are supported on Windows 2000/XP or later. NOTE: Unlike
MouseClick, the left and right buttons behave consistently across all systems, even if the user has
swapped the buttons via the system's control panel.
Mouse Wheel [has no effect on operating systems older than Windows NT/2000/XP]: Specify
WheelUp or WU to turn the wheel upward (away from you); specify WheelDown or WD to turn the
wheel downward (toward you). In this case, ClickCount (below) is the number of notches to turn the
wheel. However, some applications do not obey a ClickCount higher than 1 for the mouse wheel. For
them, use a Loop such as the following:
Loop 5
Click WheelUp
ClickCount: The number of times to click the mouse (examples: Click 2 ... Click 100, 200, 2). If
omitted, the button is clicked once. If coordinates are specified, ClickCount must appear after them.
Specify zero (0) to move the mouse without clicking (for example: Click 100, 200, 0).
Down or Up: These words are normally omitted, in which case each click consists of a down-event
followed by an up-event. Otherwise, specify Down (or the letter D) to press the mouse button down
without releasing it. Later, use the word Up (or the letter U) to release the mouse button.
Relative: The word Rel or Relative treats the specified X and Y coordinates as offsets from the current
mouse position. In other words, the cursor will be moved from its current position by X pixels to the
right (left if negative) and Y pixels down (up if negative).
Remarks
Click is generally preferred over MouseClick because it automatically compensates if the user has
swapped the left and right mouse buttons via the system's control panel.
Printed Documentation
420
Click uses the sending method set by SendMode. To override this mode for a particular click, use a
specific Send command as in this example: SendEvent {Click, 100, 200}
To perform a shift-click or control-click, the Send {Click} method is generally easiest. For example:
Send +{Click 100, 200} ; Shift+LeftClick
Send ^{Click 100, 200, right} ; Control+RightClick
Unlike Send, Click does not automatically release the modifier keys (Control, Alt, Shift, and Win). For
example, if the Control key is currently down, Click would produce a control-click but Send {Click}
would produce a normal click.
The SendPlay mode is able to successfully generate mouse events in a broader variety of games than
the other modes. In addition, some applications and games may have trouble tracking the mouse if it
moves too quickly, in which case SetDefaultMouseSpeed can be used to reduce the speed (but only in
SendEvent mode).
The BlockInput command can be used to prevent any physical mouse activity by the user from
disrupting the simulated mouse events produced by the mouse commands. However, this is generally
not needed for the SendInput/Play modes because they automatically postpone the user's physical
mouse activity until afterward.
There is an automatic delay after every click-down and click-up of the mouse (except for turning the
mouse wheel and SendInput mode). Use SetMouseDelay to change the length of the delay.
Related
Send {Click}, SendMode, CoordMode, SetDefaultMouseSpeed, SetMouseDelay, MouseClick,
MouseClickDrag, MouseMove, BlockInput
Examples
Click ; Click left mouse button at mouse cursor's current position.
Click 100, 200 ; Click left mouse button at specified coordinates.
Click 100, 200, 0 ; Move the mouse without clicking.
Click 100, 200 right ; Click the right mouse button.
Click 2 ; Perform a double-click.
Click down ; Presses down the left mouse button and holds it.
Click up right ; Releases the right mouse button.
ControlClick
Sends a mouse button or mouse wheel event to a control.
ControlClick [, Control-or-Pos, WinTitle, WinText, WhichButton, ClickCount, Options, ExcludeTitle,
ExcludeText]
Parameters
Control-or-
Pos
If this parameter is blank, the target window's topmost control will be clicked
(or the target window itself if it has no controls). Otherwise, one of the two
modes below will be used.
Mode 1 (Position): Specify the X and Y coordinates relative to the target
window's upper left corner. The X coordinate must precede the Y coordinate
and there must be at least one space or tab between them. For example: X55
Y33. If there is a control at the specified coordinates, it will be sent the click-
Mouse Control
421
event at those exact coordinates. If there is no control, the target window itself
will be sent the event (which might have no effect depending on the nature of
the window). Note: In this mode, the X and Y option letters of the Options
parameter are ignored.
Mode 2 (ClassNN or Text): Specify either ClassNN (the classname and instance
number of the control) or the name/text of the control, both of which can be
determined via Window Spy. When using name/text, the matching behavior is
determined by SetTitleMatchMode.
By default, mode 2 takes precedence over mode 1. For example, in the
unlikely event that there is a control whose text or ClassNN has the format
"Xnnn Ynnn", it would be acted upon by Mode 2. To override this and use
mode 1 unconditionally, specify the word Pos in Options as in the following
example: ControlClick, x255 y152, WinTitle,,,, Pos
To operate upon a control's HWND (window handle), leave this parameter
blank and specify ahk_id %ControlHwnd% for the WinTitle parameter (this also
works on hidden controls even when DetectHiddenWindows is Off) . The HWND
of a control is typically retrieved via ControlGet Hwnd, MouseGetPos, or DllCall.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the other 3 window parameters
are omitted, the Last Found Window will be used. If this is the letter A and the
other 3 window parameters are omitted, the active window will be used. To
use a window class, specify ahk_class ExactClassName (shown by Window
Spy). To use a process identifier (PID), specify ahk_pid %VarContainingPID%.
To use a window group, specify ahk_group GroupName. To use a window's
unique ID number, specify ahk_id %VarContainingID%. The search can be
narrowed by specifying multiple criteria. For example: My File.txt ahk_class
Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
WhichButton
The button to click: LEFT, RIGHT, MIDDLE (or just the first letter of each of
these). If omitted or blank, the LEFT button will be used.
WheelUp (or WU) and WheelDown (or WD) are also supported on Windows
NT/2000/XP or later. In this case, ClickCount is the number of notches to turn
the wheel.
X1 (XButton1, the 4th mouse button) and X2 (XButton2, the 5th mouse
button) are also supported on Windows 2000/XP or later.
ClickCount
The number of clicks to send, which can be an expression. If omitted or blank,
1 click is sent.
Options
A series of zero or more of the following option letters. For example: d x50 y25
NA [v1.0.45+]: Avoids activating the window, which might also improve
reliability in cases where the user is physically moving the mouse during the
ControlClick. However, this mode might not work properly for all types of
windows and controls.
D: Press the mouse button down but do not release it (i.e. generate a down-
event). If both the D and U options are absent, a complete click (down and up)
will be sent.
U: Release the mouse button (i.e. generate an up-event). This option should
not be present if the D option is already present (and vice versa).
Printed Documentation
422
Pos: Specify the word Pos anywhere in Options to unconditionally use the X/Y
positioning mode as described in the Control-or-Pos parameter above.
Xn: Specify for n the X position to click at, relative to the control's upper left
corner. If unspecified, the click will occur at the horizontal-center of the
control.
Yn: Specify for n the Y position to click at, relative to the control's upper left
corner. If unspecified, the click will occur at the vertical-center of the control.
Use decimal (not hexadecimal) numbers for the X and Y options.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Reliability
To improve reliability -- especially during times when the user is physically moving the mouse during
the ControlClick -- try one or both of the following:
1) Use SetControlDelay -1 prior to ControlClick. This avoids holding the mouse button down during the
click, which in turn reduces interference from the user's physical movement of the mouse.
2) Specify the string NA anywhere in the sixth parameter (Options). This avoids activating the
window, and also avoids merging the script's input processing with that of the target window (which
as a side-effect prevents physical movement of the mouse from interfering, but usually only when the
target window is not active).
However, these modes might not work for all types of windows and controls.
Remarks
Not all applications obey a ClickCount higher than 1 for turning the mouse wheel. For those
applications, use a Loop to turn the wheel more than one notch as in this example, which turns it 5
notches:
Loop, 5
ControlClick, Control, WinTitle, WinText, WheelUp
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
SetControlDelay, Control, ControlGet, ControlGetText, ControlMove, ControlGetPos, ControlFocus,
ControlSetText, ControlSend, Click
Examples
ControlClick, OK, Some Window Title ; Clicks the OK button
ControlClick, x55 y77, WinTitle ; Clicks at a set of coordinates. Note the lack of a comma between X
and Y.
MouseClick
Clicks or holds down a mouse button, or turns the mouse wheel. NOTE: The Click command is
generally more flexible and easier to use.
Mouse Control
423
MouseClick [, WhichButton , X, Y, ClickCount, Speed, D|U, R]
Parameters
WhichButton
The button to click: Left (default), Right, Middle (or just the first letter of each
of these); or the fourth or fifth mouse button (X1 or X2), which are supported
on Windows 2000/XP or later. For example: MouseClick, X1. This parameter
may be omitted, in which case it defaults to Left.
Rotate the mouse wheel: On Windows NT/2000/XP or later, specify WheelUp or
WU to turn the wheel upward (away from you); specify WheelDown or WD to
turn the wheel downward (toward you). In this case, ClickCount is the number
of notches to turn the wheel.
To compensate automatically for cases where the user has swapped the left
and right mouse buttons via the system's control panel, use the Click
command instead.
X, Y
The x/y coordinates to which the mouse cursor is moved prior to clicking,
which can be expressions. Coordinates are relative to the active window unless
CoordMode was used to change that. If omitted, the cursor's current position is
used.
ClickCount
The number of times to click the mouse, which can be an expression. If
omitted, the button is clicked once.
Speed
The speed to move the mouse in the range 0 (fastest) to 100 (slowest), which
can be an expression. Note: a speed of 0 will move the mouse instantly. If
omitted, the default speed (as set by SetDefaultMouseSpeed or 2 otherwise)
will be used.
Speed is ignored for SendInput/Play modes; they move the mouse
instantaneously (though SetMouseDelay has a mode that applies to SendPlay).
To visually move the mouse more slowly -- such as a script that performs a
demonstration for an audience -- use SendEvent {Click 100, 200} or
SendMode Event (optionally in conjuction with BlockInput).
D|U
If this parameter is omitted, each click will consist of a "down" event followed
by an "up" event. Alternatively:
D = Press the mouse button down but do not release it (i.e. generate a down-
event).
U = Release the mouse button (i.e. generate an up-event).
R
If this parameter is the letter R, the X and Y coordinates will be treated as
offsets from the current mouse position. In other words, the cursor will be
moved from its current position by X pixels to the right (left if negative) and Y
pixels down (up if negative).
Remarks
This command uses the sending method set by SendMode.
The Click command is recommended over MouseClick because:
1. It automatically compensates when the left and right mouse buttons are swapped via the
control panel.
2. It is generally easier to use.
To perform a shift-click or control-click, use the Send command before and after the operation as
shown in these examples:
Printed Documentation
424
; Example #1:
Send, {Control down}
MouseClick, left, 55, 233
Send, {Control up}

; Example #2:
Send, {Shift down}
MouseClick, left, 55, 233
Send, {Shift up}
The SendPlay mode is able to successfully generate mouse events in a broader variety of games than
the other modes. In addition, some applications and games may have trouble tracking the mouse if it
moves too quickly. The speed parameter or SetDefaultMouseSpeed can be used to reduce the speed
(in the default SendEvent mode only).
Some applications do not obey a ClickCount higher than 1 for the mouse wheel. For them, use a Loop
such as the following:
Loop, 5
MouseClick, WheelUp
The BlockInput command can be used to prevent any physical mouse activity by the user from
disrupting the simulated mouse events produced by the mouse commands. However, this is generally
not needed for the SendInput/Play modes because they automatically postpone the user's physical
mouse activity until afterward.
There is an automatic delay after every click-down and click-up of the mouse (except for turning the
mouse wheel and SendInput mode). Use SetMouseDelay to change the length of the delay.
Related
CoordMode, SendMode, SetDefaultMouseSpeed, SetMouseDelay, Click, MouseClickDrag, MouseGetPos,
MouseMove, BlockInput
Examples
; Double click at the current mouse pos:
MouseClick, left
MouseClick, left

; Same as above:
MouseClick, left, , , 2

; Move to specified coordinates then right-click once:
MouseClick, right, 200, 300

; Here are two hotkeys that simulate the turning of the mouse wheel:
#up::MouseClick, WheelUp, , , 2 ; Turn it by two notches.
#down::MouseClick, WheelDown, , , 2
Mouse Control
425
MouseClickDrag
Clicks and holds the specified mouse button, moves the mouse to the destination coordinates, then
releases the button.
MouseClickDrag, WhichButton, X1, Y1, X2, Y2 [, Speed, R]
Parameters
WhichButton
The button to click: Left, Right, Middle (or just the first letter of each of these).
The fourth and fifth mouse buttons are supported on Windows 2000/XP or
later: Specify X1 for the fourth button and X2 for the fifth. For example:
MouseClickDrag, X1, ...
To compensate automatically for cases where the user has swapped the left
and right mouse buttons via the system's control panel, use the Click
command instead.
X1, Y1
The x/y coordinates of the drag's starting position, which can be expressions
(the mouse will be moved to these coordinates right before the drag is
started). Coordinates are relative to the active window unless CoordMode was
used to change that. If omitted, the mouse's current position is used.
X2, Y2
The x/y coordinates to drag the mouse to (that is, while the button is held
down), which can be expressions. Coordinates are relative to the active
window unless CoordMode was used to change that.
Speed
The speed to move the mouse in the range 0 (fastest) to 100 (slowest), which
can be an expression. Note: a speed of 0 will move the mouse instantly. If
omitted, the default speed (as set by SetDefaultMouseSpeed or 2 otherwise)
will be used.
Speed is ignored for SendInput/Play modes; they move the mouse
instantaneously (though SetMouseDelay has a mode that applies to SendPlay).
To visually move the mouse more slowly -- such as a script that performs a
demonstration for an audience -- use SendEvent {Click 100, 200} or
SendMode Event (optionally in conjuction with BlockInput).
R
If this parameter is the letter R, the X1 and Y1 coordinates will be treated as
offsets from the current mouse position. In other words, the cursor will be
moved from its current position by X1 pixels to the right (left if negative) and
Y1 pixels down (up if negative).
Similarly, the X2 and Y2 coordinates will be treated as offsets from the X1 and
Y1 coordinates. For example, the following would first move the cursor down
and to the right by 5 pixels from its starting position, and then drag it from
that position down and to the right by 10 pixels: MouseClickDrag, Left, 5, 5,
10, 10, , R
Remarks
This command uses the sending method set by SendMode.
Dragging can also be done via the various Send commands, which is more flexible because the mode
can be specified via the command name. For example:
SendEvent {Click 6, 52, down}{click 45, 52, up}
Another advantage of the method above is that unlike MouseClickDrag, it automatically compensates
when the user has swapped the left and right mouse buttons via the system's control panel.
Printed Documentation
426
The SendPlay mode is able to successfully generate mouse events in a broader variety of games than
the other modes. However, dragging via SendPlay might not work in RichEdit controls (and possibly
others) such as those of WordPad and Metapad.
Some applications and games may have trouble tracking the mouse if it moves too quickly. The speed
parameter or SetDefaultMouseSpeed can be used to reduce the speed (in the default SendEvent mode
only).
The BlockInput command can be used to prevent any physical mouse activity by the user from
disrupting the simulated mouse events produced by the mouse commands. However, this is generally
not needed for the SendInput/Play modes because they automatically postpone the user's physical
mouse activity until afterward.
There is an automatic delay after every click-down and click-up of the mouse (except for SendInput
mode). This delay also occurs after the movement of the mouse during the drag operation. Use
SetMouseDelay to change the length of the delay.
Related
CoordMode, SendMode, SetDefaultMouseSpeed, SetMouseDelay, Click, MouseClick, MouseGetPos,
MouseMove, BlockInput
Example
MouseClickDrag, left, 0, 200, 600, 400

; The following example opens MS Paint and draws a little house:
Run, mspaint.exe
WinWaitActive, ahk_class MSPaintApp,, 2
if ErrorLevel
return
MouseClickDrag, L, 150, 250, 150, 150
MouseClickDrag, L, 150, 150, 200, 100
MouseClickDrag, L, 200, 100, 250, 150
MouseClickDrag, L, 250, 150, 150, 150
MouseClickDrag, L, 150, 150, 250, 250
MouseClickDrag, L, 250, 250, 250, 150
MouseClickDrag, L, 250, 150, 150, 250
MouseClickDrag, L, 150, 250, 250, 250
MouseGetPos
Retrieves the current position of the mouse cursor, and optionally which window and control it is
hovering over.
MouseGetPos, [OutputVarX, OutputVarY, OutputVarWin, OutputVarControl, 1|2|3]
Parameters
OutputVarX/Y
The names of the variables in which to store the X and Y coordinates. The
retrieved coordinates are relative to the active window unless CoordMode
Mouse Control
427
was used to change to screen coordinates.
OutputVarWin
This optional parameter is the name of the variable in which to store the
unique ID number of the window under the mouse cursor. If the window
cannot be determined, this variable will be made blank.
The window does not have to be active to be detected. Hidden windows
cannot be detected.
OutputVarControl
This optional parameter is the name of the variable in which to store the
name (ClassNN) of the control under the mouse cursor. If the control
cannot be determined, this variable will be made blank.
The names of controls should always match those shown by the version of
Window Spy distributed with v1.0.14+ (but not necessarily older versions
of Window Spy). However, unlike Window Spy, the window under the
mouse cursor does not have to be active for a control to be detected.
1|2|3
If omitted, it defaults to 0. Otherwise, specify one of the following digits:
1: Uses a simpler method to determine OutputVarControl. This method
correctly retrieves the active/topmost child window of an Multiple
Document Interface (MDI) application such as SysEdit or TextPad.
However, it is less accurate for other purposes such as detecting controls
inside a GroupBox control.
2 [v1.0.43.06+]: Stores the control's HWND in OutputVarControl rather
than the control's ClassNN.
3 [v1.0.43.06+]: A combination of 1 and 2 above.
Remarks
Any of the output variables may be omitted if the corresponding information is not needed.
Related
CoordMode, WinGet, SetDefaultMouseSpeed, Click
Example
MouseGetPos, xpos, ypos
Msgbox, The cursor is at X%xpos% Y%ypos%.

; This example allows you to move the mouse around to see
; the title of the window currently under the cursor:
#Persistent
SetTimer, WatchCursor, 100
return

WatchCursor:
MouseGetPos, , , id, control
WinGetTitle, title, ahk_id %id%
Printed Documentation
428
WinGetClass, class, ahk_id %id%
ToolTip, ahk_id %id%`nahk_class %class%`n%title%`nControl: %control%
return
MouseMove
Moves the mouse cursor.
MouseMove, X, Y [, Speed, R]
Parameters
X, Y
The x/y coordinates to move the mouse to, which can be expressions.
Coordinates are relative to the active window unless CoordMode was used to
change that.
Speed
The speed to move the mouse in the range 0 (fastest) to 100 (slowest), which
can be an expression. Note: a speed of 0 will move the mouse instantly. If
omitted, the default speed (as set by SetDefaultMouseSpeed or 2 otherwise)
will be used.
Speed is ignored for SendInput/Play modes; they move the mouse
instantaneously (though SetMouseDelay has a mode that applies to SendPlay).
To visually move the mouse more slowly -- such as a script that performs a
demonstration for an audience -- use SendEvent {Click 100, 200} or
SendMode Event (optionally in conjuction with BlockInput).
R
If this parameter is the letter R, the X and Y coordinates will be treated as
offsets from the current mouse position. In other words, the cursor will be
moved from its current position by X pixels to the right (left if negative) and Y
pixels down (up if negative).
Remarks
This command uses the sending method set by SendMode.
The SendPlay mode is able to successfully generate mouse events in a broader variety of games than
the other modes. In addition, some applications and games may have trouble tracking the mouse if it
moves too quickly. The speed parameter or SetDefaultMouseSpeed can be used to reduce the speed
(in the default SendEvent mode only).
The BlockInput command can be used to prevent any physical mouse activity by the user from
disrupting the simulated mouse events produced by the mouse commands. However, this is generally
not needed for the SendInput/Play modes because they automatically postpone the user's physical
mouse activity until afterward.
There is an automatic delay after every movement of the mouse (except for SendInput mode). Use
SetMouseDelay to change the length of the delay.
The following is an alternate way to move the mouse cursor that may work better in certain multi-
monitor configurations:
DllCall("SetCursorPos", int, 100, int, 400) ; The first number is the X-coordinate and the
second is the Y (relative to the screen).
On a related note, the mouse cursor can be temporarily hidden via the hide-cursor example.
Related
CoordMode, SendMode, SetDefaultMouseSpeed, SetMouseDelay, Click, MouseClick, MouseClickDrag,
MouseGetPos, BlockInput
Mouse Control
429
Example
; Move the mouse to a new position:
MouseMove, 200, 100

; Move the mouse slowly (speed 50 vs. 2) by 20 pixels to the right and 30 pixels down
; from its current location:
MouseMove, 20, 30, 50, R
SetDefaultMouseSpeed
Sets the mouse speed that will be used if unspecified in Click and MouseMove/Click/Drag.
SetDefaultMouseSpeed, Speed
Parameters
Speed
The speed to move the mouse in the range 0 (fastest) to 100 (slowest). Note:
a speed of 0 will move the mouse instantly. This parameter can be an
expression.
Remarks
SetDefaultMouseSpeed is ignored for SendInput/Play modes; they move the mouse instantaneously
(however, SetMouseDelay has a mode that applies to SendPlay). To visually move the mouse more
slowly -- such as a script that performs a demonstration for an audience -- use SendEvent {Click 100,
200} or SendMode Event (optionally in conjuction with BlockInput).
If this command is not used, the default mouse speed is 2. The built-in variable
A_DefaultMouseSpeed contains the current setting.
The commands MouseClick, MouseMove, and MouseClickDrag all have a parameter to override the
default mouse speed.
Whenever Speed is greater than zero, SetMouseDelay also influences the speed by producing a delay
after each incremental move the mouse makes toward its destination.
Every newly launched thread (such as a hotkey, custom menu item, or timed subroutine) starts off
fresh with the default setting for this command. That default may be changed by using this command
in the auto-execute section (top part of the script).
Related
SendMode, Click, MouseClick, MouseMove, MouseClickDrag, SetWinDelay, SetControlDelay,
SetKeyDelay, SetKeyDelay
Example
SetDefaultMouseSpeed, 0 ; Move the mouse instantly.
SetMouseDelay
Sets the delay that will occur after each mouse movement or click.
SetMouseDelay, Delay [, Play]
Parameters
Printed Documentation
430
Delay
Time in milliseconds, which can be an expression. Use -1 for no delay at all
and 0 for the smallest possible delay (however, if the Play parameter is
present, both 0 and -1 produce no delay). If unset, the default delay is 10 for
the traditional SendEvent mode and -1 for SendPlay mode.
Play
[v1.0.43+]
The word Play applies the delay to the SendPlay mode rather than the
traditional Send/SendEvent mode. If a script never uses this parameter, the
delay is always -1 for SendPlay.
Remarks
A short delay (sleep) is done automatically after every mouse movement or click generated by Click
and MouseMove/Click/Drag (except for SendInput mode). This is done to improve the reliability of
scripts because a window sometimes can't keep up with a rapid flood of mouse events.
Due to the granularity of the OS's time-keeping system, delays might be rounded up to the nearest
multiple of 10. For example, a delay between 1 and 10 (inclusive) is equivalent to 10 on Windows XP
(and probably NT & 2k).
A delay of 0 internally executes a Sleep(0), which yields the remainder of the script's timeslice to any
other process that may need it. If there is none, Sleep(0) will not sleep at all. By contrast, a delay of -
1 will never sleep.
The built-in variable A_MouseDelay contains the current setting for Send/SendEvent mode (there is
no built-in variable for SendPlay mode).
Every newly launched thread (such as a hotkey, custom menu item, or timed subroutine) starts off
fresh with the default setting for this command. That default may be changed by using this command
in the auto-execute section (top part of the script).
Related
Click, MouseMove, MouseClick, MouseClickDrag, SendMode, SetKeyDelay, SetControlDelay,
SetWinDelay, SetBatchLines
Example
SetMouseDelay, 0

431
Process Management
Exit
Exits the current thread or (if the script is not persistent contains no hotkeys) the entire script.
Exit [, ExitCode]
Parameters
ExitCode
An integer (i.e. negative, positive, zero, or an expression) that is returned to
its caller when the script exits. This code is accessible to any program that
spawned the script, such as another script (via RunWait) or a batch (.bat) file.
If omitted, ExitCode defaults to zero. Zero is traditionally used to indicate
success. Note: Windows 95 may be limited in how large ExitCode can be.
Remarks
If the script has no hotkeys, isn't persistent, and hasn't requested the Num/Scroll/CapsLock key(s) to
be kept AlwaysOn or AlwaysOff, it will terminate immediately when Exit is encountered (except if it
has an OnExit subroutine).
Otherwise, the Exit command terminates the current thread. In other words, the stack of subroutines
called directly or indirectly by a menu, timer, or hotkey subroutine will all be returned from as though
a Return were immediately encountered in each. If used directly inside such a subroutine -- rather
than in one of the subroutines called indirectly by it -- Exit is equivalent to Return.
Use ExitApp to completely terminate a script that is persistent or contains hotkeys.
Related
ExitApp, OnExit, Functions, Gosub, Return, Threads, #Persistent
Example
#z::
Gosub, Sub2
MsgBox, This msgbox will never happen because of the EXIT.
return

Sub2:
Exit ; Terminate this subroutine as well as the calling subroutine.
ExitApp
Terminates the script unconditionally.
ExitApp [, ExitCode]
Parameters
ExitCode
An integer (i.e. negative, positive, or zero) that is returned to its caller when
the script exits. This code is accessible to any program that spawned the
script, such as another script (via RunWait) or a batch (.bat) file. If omitted,
ExitCode defaults to zero. Zero is traditionally used to indicate success. Note:
Printed Documentation
432
Windows 95 may be limited in how large ExitCode can be.
Remarks
The script is immediately terminated unless it has an OnExit subroutine. This is equivalent to choosing
"Exit" from the script's tray menu or main menu.
Exit and ExitApp behave identically when the script contains no hotkeys, is not persistent, and does
not ask for the Num/Scroll/Capslock key(s) to be kept AlwaysOn or AlwaysOff.
If the script has an OnExit subroutine, it will be run in response to ExitApp.
Related
Exit, OnExit, #Persistent
Example
#x::ExitApp ; Assign a hotkey to terminate this script.
OnExit
Specifies a subroutine to run automatically when the script exits.
OnExit [, Label]
Parameters
Label
If omitted, the script is returned to its normal exit behavior. Otherwise, specify
the name of the label whose contents will be executed (as a new thread) when
the script exits by any means.
IMPORTANT: Since the specified subroutine is called instead of terminating the script, that
subroutine must use the ExitApp command if termination is desired. Alternatively (as in the Examples
section below), the OnExit subroutine might display a MsgBox to prompt the user for confirmation --
and only if the user presses YES would the script execute ExitApp to close itself.
Remarks
The OnExit subroutine is called when the script exits by any means (except when it is killed by
something like "End Task"). It is also called whenever the #SingleInstance and Reload commands ask
a previous instance to terminate.
A script can detect and optionally abort a system shutdown or logoff via OnMessage(0x11,
"WM_QUERYENDSESSION").
The OnExit thread does not obey #MaxThreads (it will always launch when needed). In addition, while
it is running, it cannot be interrupted by any thread, including hotkeys, custom menu items, and timed
subroutines. However, it will be interrupted (and the script will terminate) if the user chooses Exit
from the tray menu or main menu, or the script is asked to terminate as a result of Reload or
#SingleInstance. Because of this, the OnExit subroutine should be designed to finish quickly unless
the user is aware of what it is doing.
If the OnExit thread encounters a failure condition such as a runtime error, the script will terminate.
This prevents a flawed OnExit subroutine from making a script impossible to terminate.
If the OnExit subroutine was launched due to an Exit or ExitApp command that specified an exit code,
that code is ignored and no longer available. A new exit code can be specified by the OnExit
subroutine if/when it calls ExitApp.
Whenever the OnExit subroutine is called by an exit attempt, it starts off fresh with the default values
for settings such as SendMode. These defaults can be changed in the auto-execute section.
Process Management
433
The built-in variable A_ExitReason is blank unless the OnExit subroutine is currently running or has
been called at least once by a prior exit attempt. If not blank, it is one of the following words:
Logoff The user is logging off.
Shutdown The system is being shut down or restarted, such as by the Shutdown command.
Close
The script was sent a WM_CLOSE or WM_QUIT message, had a critical error, or is
being closed in some other way. Although all of these are unusual, WM_CLOSE
might be caused by WinClose having been used on the script's main window. To
prevent this, dismiss the main window with Send, !{F4}.
Error
A runtime error occurred in a script that has no hotkeys and that is not persistent.
An example of a runtime error is Run/RunWait being unable to launch the
specified program or document.
Menu
The user selected Exit from the main window's menu or from the standard tray
menu.
Exit The Exit or ExitApp command was used (includes custom menu items).
Reload The script is being reloaded via the Reload command or menu item.
Single
The script is being replaced by a new instance of itself as a result of
#SingleInstance.
Related
OnMessage(), OnClipboardChange, ExitApp, Shutdown, #Persistent, Threads, Gosub, Return, Menu
Example
#Persistent ; For demonstration purposes, keep the script running if the user chooses "No".
OnExit, ExitSub
return

ExitSub:
if A_ExitReason not in Logoff,Shutdown ; Avoid spaces around the comma in this line.
{
MsgBox, 4, , Are you sure you want to exit?
IfMsgBox, No
return
}
ExitApp ; The only way for an OnExit script to terminate itself is to use ExitApp in the OnExit
subroutine.
Process
Performs one of the following operations on a process: checks if it exists; changes its priority; closes
it; waits for it to close.
Process, Cmd, PID-or-Name [, Param3]
Parameters
Printed Documentation
434
Cmd
One of the following words:
Exist: Sets ErrorLevel to the Process ID (PID) if a matching process exists, or
0 otherwise. In v1.0.36+, if the PID-or-Name parameter is blank, the script's
own PID is retrieved. An alternate, single-line method to retrieve the script's
PID is PID := DllCall("GetCurrentProcessId")
Close: If a matching process is successfully terminated, ErrorLevel is set to its
former Process ID (PID). Otherwise (there was no matching process or there
was a problem terminating it), it is set to 0. Since the process will be abruptly
terminated -- possibly interrupting its work at a critical point or resulting in the
loss of unsaved data in its windows (if it has any) -- this method should be
used only if a process cannot be closed by using WinClose on one of its
windows.
List: Although List is not yet supported, the examples section demonstrates
how to retrieve a list of processes via DllCall.
Priority: Changes the priority (as seen in Windows Task Manager) of the first
matching process to Param3 and sets ErrorLevel to its Process ID (PID). If the
PID-or-Name parameter is blank, the script's own priority will be changed. If
there is no matching process or there was a problem changing its priority,
ErrorLevel is set to 0.
Param3 should be one of the following letters or words: L (or Low), B (or
BelowNormal), N (or Normal), A (or AboveNormal), H (or High), R (or
Realtime). Since BelowNormal and AboveNormal are not supported on
Windows 95/98/Me/NT4, normal will be automatically substituted for them on
those operating systems. Note: Any process not designed to run at Realtime
priority might reduce system stability if set to that level.
Wait: Waits up to Param3 seconds (can contain a decimal point) for a
matching process to exist. If Param3 is omitted, the command will wait
indefinitely. If a matching process is discovered, ErrorLevel is set to its Process
ID (PID). If the command times out, ErrorLevel is set to 0.
WaitClose: Waits up to Param3 seconds (can contain a decimal point) for ALL
matching processes to close. If Param3 is omitted, the command will wait
indefinitely. If all matching processes are closed, ErrorLevel is set to 0. If the
command times out, ErrorLevel is set to the Process ID (PID) of the first
matching process that still exists.
PID-or-
Name
This parameter can be either a number (the PID) or a process name as
described below. It can also be left blank to change the priority of the script
itself.
PID: The Process ID, which is a number that uniquely identifies one specific
process (this number is valid only during the lifetime of that process). The PID
of a newly launched process can be determined via the Run command.
Similarly, the PID of a window can be determined with WinGet. The Process
command itself can also be used to discover a PID.
Name: The name of a process is usually the same as its executable (without
path), e.g. notepad.exe or winword.exe. Since a name might match multiple
running processes, only the first process will be operated upon. The name is
not case sensitive.
Param3 See Cmd above for details.
ErrorLevel
See Cmd above for details.
Process Management
435
Remarks
For Wait and WaitClose: Processes are checked every 100 milliseconds; the moment the condition is
satisfied, the command stops waiting. In other words, rather than waiting for the timeout to expire, it
immediately sets ErrorLevel as described above, then continues execution of the script. Also, while the
command is in a waiting state, new threads can be launched via hotkey, custom menu item, or timer.
To work under Windows NT4, the Process command requires the file PSAPI.DLL, which is normally
already present in the AutoHotkey installation directory (i.e. no extra installation steps should be
needed even for NT). However, to use it from within a compiled script on Windows NT4, include a copy
of PSAPI.DLL in the same folder as the script or in one of the directories in the system's PATH (though
some NT4 systems might already have the DLL).
Related
Run, WinGet, WinClose, WinKill, WinWait, WinWaitClose, IfWinExist
Examples
; Example #1:

Run Notepad.exe, , , NewPID
Process, priority, %NewPID%, High
MsgBox The newly launched notepad's PID is %NewPID%.

; Example #2:

Process, wait, Notepad.exe, 5.5
NewPID = %ErrorLevel% ; Save the value immediately since ErrorLevel is often changed.
if NewPID = 0
{
MsgBox The specified process did not appear within 5.5 seconds.
return
}
; Otherwise:
MsgBox A matching process has appeared (Process ID is %NewPID%).
Process, priority, %NewPID%, Low
Process, priority, , High ; Have the script set itself to high priority.
WinClose Untitled - Notepad
Process, WaitClose, %NewPID%, 5
if ErrorLevel ; The PID still exists.
MsgBox The process did not close within 5 seconds.

; Example #3: A hotkey to change the priority of the active window's process:

Printed Documentation
436
#z:: ; Win+Z hotkey
WinGet, active_pid, PID, A
WinGetTitle, active_title, A
Gui, 5:Add, Text,, Press ESCAPE to cancel, or double-click a new`npriority level for the following
window:`n%active_title%
Gui, 5:Add, ListBox, vMyListBox gMyListBox r5, Normal|High|Low|BelowNormal|AboveNormal
Gui, 5:Add, Button, default, OK
Gui, 5:Show,, Set Priority
return

5GuiEscape:
5GuiClose:
Gui, Destroy
return

MyListBox:
if A_GuiControlEvent <> DoubleClick
return
; else fall through to the next label:
5ButtonOK:
GuiControlGet, MyListBox
Gui, Destroy
Process, Priority, %active_pid%, %MyListBox%
if ErrorLevel
MsgBox Success: Its priority was changed to "%MyListBox%".
else
MsgBox Error: Its priority could not be changed to "%MyListBox%".
return

; Example #4: Retrieves a list of running processes via DllCall then shows them in a MsgBox.

d = `n ; string separator
s := 4096 ; size of buffers and arrays (4 KB)

Process, Exist ; sets ErrorLevel to the PID of this running script
; Get the handle of this script with PROCESS_QUERY_INFORMATION (0x0400)
h := DllCall("OpenProcess", "UInt", 0x0400, "Int", false, "UInt", ErrorLevel)
; Open an adjustable access token with this process (TOKEN_ADJUST_PRIVILEGES = 32)
Process Management
437
DllCall("Advapi32.dll\OpenProcessToken", "UInt", h, "UInt", 32, "UIntP", t)
VarSetCapacity(ti, 16, 0) ; structure of privileges
InsertInteger(1, ti, 0, 4) ; one entry in the privileges array...
; Retrieves the locally unique identifier of the debug privilege:
DllCall("Advapi32.dll\LookupPrivilegeValueA", "UInt", 0, "Str", "SeDebugPrivilege", "UIntP", luid)
InsertInteger(luid, ti, 4, 8)
InsertInteger(2, ti, 12, 4) ; enable this privilege: SE_PRIVILEGE_ENABLED = 2
; Update the privileges of this process with the new access token:
DllCall("Advapi32.dll\AdjustTokenPrivileges", "UInt", t, "Int", false, "UInt", &ti, "UInt", 0, "UInt", 0,
"UInt", 0)
DllCall("CloseHandle", "UInt", h) ; close this process handle to save memory

hModule := DllCall("LoadLibrary", "Str", "Psapi.dll") ; increase performance by preloading the libaray
s := VarSetCapacity(a, s) ; an array that receives the list of process identifiers:
DllCall("Psapi.dll\EnumProcesses", "UInt", &a, "UInt", s, "UIntP", r)
Loop, % r // 4 ; parse array for identifiers as DWORDs (32 bits):
{
id := ExtractInteger(a, A_Index * 4)
; Open process with: PROCESS_VM_READ (0x0010) | PROCESS_QUERY_INFORMATION (0x0400)
h := DllCall("OpenProcess", "UInt", 0x0010 | 0x0400, "Int", false, "UInt", id)
VarSetCapacity(m, s) ; an array that receives the list of module handles:
DllCall("Psapi.dll\EnumProcessModules", "UInt", h, "UInt", &m, "UInt", s, "UIntP", r)
VarSetCapacity(n, s, 0) ; a buffer that receives the base name of the module:
e := DllCall("Psapi.dll\GetModuleBaseNameA", "UInt", h, "UInt", m, "Str", n, "Chr", s)
DllCall("CloseHandle", "UInt", h) ; close process handle to save memory
If n ; if image is not null add to list:
l = %l%%n%%d%
}
DllCall("FreeLibrary", "UInt", hModule) ; unload the library to free memory
; Remove the first and last items in the list (possibly ASCII signitures)
StringMid, l, l, InStr(l, d) + 1, InStr(l, d, false, 0) - 2 - InStr(l, d)
StringReplace, l, l, %d%, %d%, UseErrorLevel ; gets the number of processes
;Sort, l, C ; uncomment this line to sort the list alphabetically
MsgBox, 0, %ErrorLevel% Processes, %l%

ExtractInteger(ByRef pSource, pOffset = 0, pIsSigned = false, pSize = 4) ; See DllCall for details.
{
Loop %pSize% ; Build the integer by adding up its bytes.
Printed Documentation
438
result += *(&pSource + pOffset + A_Index-1) << 8*(A_Index-1)
if (!pIsSigned OR pSize > 4 OR result < 0x80000000)
return result ; Signed vs. unsigned doesn't matter in these cases.
return -(0xFFFFFFFF - result + 1)
}

InsertInteger(pInteger, ByRef pDest, pOffset = 0, pSize = 4)
{
Loop %pSize% ; Copy each byte in the integer into the structure as raw binary data.
DllCall("RtlFillMemory", "UInt", &pDest + pOffset + A_Index-1, "UInt", 1, "UChar", pInteger >>
8*(A_Index-1) & 0xFF)
}
Run / RunWait
Runs an external program. Unlike Run, RunWait will wait until the program finishes before continuing.
Run, Target [, WorkingDir, Max|Min|Hide|UseErrorLevel, OutputVarPID]
Parameters
Target
A document, URL, executable file (.exe, .com, .bat, etc.), shortcut (.lnk), or
system verb to launch (see remarks). If Target is a local file and no path was
specified with it, A_WorkingDir will be searched first. If no matching file is
found there, the system will search for and launch the file if it is integrated
("known"), e.g. by being contained in one of the PATH folders.
To pass parameters, add them immediately after the program or document
name. If a parameter contains spaces, it is safest to enclose it in double
quotes (even though it may work without them in some cases).
WorkingDir
The working directory for the launched item. Do not enclose the name in
double quotes even if it contains spaces. If omitted, the script's own working
directory (A_WorkingDir) will be used.
Max|Min|Hide
UseErrorLevel
If omitted, Target will be launched normally. Alternatively, it can contain one
or more of these words:
Max: launch maximized
Min: launch minimized
Hide: launch hidden (cannot be used in combination with either of the above)
Some applications (e.g. Calc.exe) do not obey the requested startup state and
thus Max/Min/Hide will have no effect.
UseErrorLevel: UseErrorLevel can be specified alone or in addition to one of
the above words (by separating it from the other word with a space). If the
launch fails, this option skips the warning dialog, sets ErrorLevel to the word
ERROR, and allows the current thread to continue. If the launch succeeds,
RunWait sets ErrorLevel to the program's exit code, and Run sets it to 0.
In v1.0.42.03+, when UseErrorLevel is specified, the variable A_LastError is
set to the result of the operating system's GetLastError() function.
A_LastError is a number between 0 and 4294967295 (always formatted as
Process Management
439
decimal, not hexadecimal). Zero (0) means success, but any other number
means the launch failed. Each number corresponds to a specific error
condition (to get a list, search www.microsoft.com for "system error codes").
Like ErrorLevel, A_LastError is a per-thread setting; that is, interruptions by
other threads cannot change it. However, A_LastError is also set by DllCall.
OutputVarPID
The name of the variable in which to store the newly launched program's
unique Process ID (PID). The variable will be made blank if the PID could not
be determined, which usually happens if a system verb, document, or
shortcut is launched rather than a direct executable file. RunWait also
supports this parameter, though its OuputVarPID must be checked in another
thread (otherwise, the PID will be invalid because the process will have
terminated by the time the line following RunWait executes).
After the Run command retrieves a PID, any windows to be created by the
process might not exist yet. To wait for at least one window to be created,
use WinWait ahk_pid %OutputVarPID%
ErrorLevel
Run: Does not set ErrorLevel unless UseErrorLevel (above) is in effect, in which case ErrorLevel is set
to the word ERROR upon failure or 0 upon success.
RunWait: Sets ErrorLevel to the program's exit code (a signed 32-bit integer). If UseErrorLevel is in
effect and the launch failed, the word ERROR is stored.
Remarks
Unlike Run, RunWait will wait until Target is closed or exits, at which time ErrorLevel will be set to the
program's exit code (as a signed 32-bit integer). Some programs will appear to return immediately
even though they are still running; these programs spawn another process.
If Target contains any commas, they must be escaped as shown three times in the following example:
Run rundll32.exe shell32.dll`,Control_RunDLL desk.cpl`,`, 3 ; Opens Control Panel > Display
Properties > Settings
When running a program via Comspec (cmd.exe) -- perhaps because you need to redirect the
program's input or output -- if the path or name of the executable contains spaces, the entire string
should be enclosed in an outer pair of quotes. In the following example, the outer quotes are shown in
red and all the inner quotes are shown in black:
Run %comspec% /c ""C:\My Utility.exe" "param 1" "second param" >"C:\My File.txt""
If Target cannot be launched, an error window is displayed, after which the script will behave as
though it encountered an Exit command. To prevent this, include the string UseErrorLevel in the
third parameter.
Performance may be slightly improved if Target is an exact path, e.g. Run, C:\Windows\Notepad.exe
"C:\My Documents\Test.txt" rather than Run, C:\My Documents\Test.txt
Special CLSID folders may be opened via Run. For example:
Run ::{20d04fe0-3aea-1069-a2d8-08002b30309d} ; Opens the "My Computer" folder.
Run ::{645ff040-5081-101b-9f08-00aa002f954e} ; Opens the Recycle Bin.
System verbs correspond to actions available in a file's right-click menu in the Explorer. If a file is
launched without a verb, the default verb (usually "open") for that particular file type will be used. If
specified, the verb should be followed by the name of the target file. The following verbs are currently
supported:
properties Displays the Explorer's properties window for the indicated file. For example: Run,
Printed Documentation
440
properties "C:\My File.txt"
Note: The properties window will automatically close when the script terminates.
To prevent this, use WinWait to wait for the window to appear, then use
WinWaitClose to wait for the user to close it.
find
Opens an instance of the Explorer's Search Companion or Find File window at the
indicated folder. For example: Run, find D:\
explore
Opens an instance of Explorer at the indicated folder. For example: Run, explore
%A_ProgramFiles%
edit
Opens the indicated file for editing. It might not work if the indicated file's type
does not have an "edit" action associated with it. For example: Run, edit "C:\My
File.txt"
open
Opens the indicated file (normally not needed because it is the default action for
most file types). For example: Run, open "My File.txt"
print
Prints the indicated file with the associated application, if any. For example: Run,
print "My File.txt"
While RunWait is in a waiting state, new threads can be launched via hotkey, custom menu item, or
timer.
Related
RunAs, Process, Exit, CLSID List
Examples
Run, Notepad.exe, C:\My Documents, max

Run, mailto:[email protected]?subject=This is the subject line&body=This is the message body's
text.
Run, ReadMe.doc, , Max UseErrorLevel ; Launch maximized and don't display dialog if it fails.
if ErrorLevel = ERROR
MsgBox The document could not be launched.

RunWait, %comspec% /c dir c:\ >>c:\DirTest.txt, , min
Run, c:\DirTest.txt
Run, properties c:\DirTest.txt

Run, www.autohotkey.com ; i.e. any URL can be launched.
Run, mailto:[email protected] ; This should open the default e-mail application.

Run ::{20d04fe0-3aea-1069-a2d8-08002b30309d} ; Opens the "My Computer" folder.
Run ::{645ff040-5081-101b-9f08-00aa002f954e} ; Opens the Recycle Bin.
RunAs
Specifies a set of user credentials to use for all subsequent uses of Run and RunWait. Requires
Windows 2000/XP or later.
Process Management
441
RunAs [, User, Password, Domain]
Parameters
User
If this and the other parameters are all omitted, the RunAs feature will be
turned off, which restores Run and RunWait to their default behavior.
Otherwise, this is the username under which new processes will be created.
Password User's password.
Domain
User's domain. To use a local account, leave this blank. If that fails to work,
try using @YourComputerName.
Remarks
Only Windows XP/2000 or later are supported; this command has no effect on other operating
systems. NT4 users should install and use the SU command from the NT Resource Kit instead.
This command does nothing other than notify AutoHotkey to use (or not use) alternate user
credentials for all subsequent uses of Run and RunWait.
ErrorLevel is not changed by this command. If an invalid User, Password, or Domain is specified, Run
and RunWait will display an error message explaining the problem.
While the RunAs feature is in effect, Run and RunWait will not able to launch documents, URLs, or
system verbs. In other words, the file to be launched must be an executable file.
The "Secondary Logon" service must be set to manual or automatic for this command to work (the OS
should automatically start it upon demand if set to manual).
Related
Run, RunWait
Example
RunAs, Administrator, MyPassword
Run, RegEdit.exe
RunAs ; Reset to normal behavior.
Shutdown
Shuts down, restarts, or logs off the system.
Shutdown, Code
Parameters
Code A combination of shutdown codes listed below.
Remarks
The shutdown code is a combination of the following values:
Logoff 0
Shutdown 1
Reboot 2
Force 4
Printed Documentation
442
Power down 8
Suspend/Hibernate See DllCall example at the bottom of this page.
Add the required values together. For example, to shutdown and power down the code would be 9
(shutdown + power down = 1 + 8 = 9). Alternatively, an expression such as 1+8 can be specified.
The "Force" value (4) forces all open applications to close. It should only be used in an emergency
because it may cause any open applications to lose data.
The "Power down" value shuts down the system and turns off the power.
On a related note, a script can detect when the system is shutting down or the user is logging off via
OnExit.
Related
Run, ExitApp, OnExit
Example
; Force a reboot (reboot + force = 2 + 4 = 6):
Shutdown, 6

; Call the Windows API function "SetSuspendState" to have the system suspend or hibernate.
; Windows 95/NT4: Since this function does not exist, the following call would have no effect.
; Parameter #1: Pass 1 instead of 0 to hibernate rather than suspend.
; Parameter #2: Pass 1 instead of 0 to suspend immediately rather than asking each application for
permission.
; Parameter #3: Pass 1 instead of 0 to disable all wake events.
DllCall("PowrProf\SetSuspendState", "int", 0, "int", 0, "int", 0)
Sleep
Waits the specified amount of time before continuing.
Sleep, Delay
Parameters
Delay
The amount of time to pause (in milliseconds) between 0 and 2147483647 (24
days), which can be an expression.
Remarks
Due to the granularity of the OS's time-keeping system, Delay is typically rounded up to the nearest
multiple of 10. For example, a delay between 1 and 10 (inclusive) is equivalent to 10 on most
Windows NT/2000/XP systems. However, due to hardware differences, some systems will round up to
a different value such as 15.
The actual delay time might wind up being longer than what was requested if the CPU is under load.
This is because the OS gives each needy process a slice of CPU time (typically 20 milliseconds) before
giving another timeslice to the script.
A delay of 0 yields the remainder of the script's current timeslice to any other processes that need it
(as long as they are not significantly lower in priority than the script). Thus, a delay of 0 produces an
actual delay between 0 and 20ms (or more), depending on the number of needy processes (if there
Process Management
443
are no needy processes, there will be no delay at all). However, a Delay of 0 should always wind up
being shorter than any longer Delay would have been.
While sleeping, new threads can be launched via hotkey, custom menu item, or timer.
"Sleep -1": If the operating system is Windows NT4/2000/XP or later or AutoHotkey's version is
1.0.38.05 or later, a delay of -1 does not sleep but instead makes the script immediately check its
message queue. This can be used to force any pending interruptions to occur at a specific place rather
than somewhere more random. See Critical for more details.
Related
SetKeyDelay, SetMouseDelay, SetControlDelay, SetWinDelay, SetBatchLines
Example
Sleep, 1000 ; 1 second

445
Registry Management
Loop (registry)
Retrieves the contents of the specified registry subkey, one item at a time.
Loop, RootKey [, Key, IncludeSubkeys?, Recurse?]
Parameters
RootKey
Must be either HKEY_LOCAL_MACHINE (or HKLM), HKEY_USERS (or HKU),
HKEY_CURRENT_USER (or HKCU), HKEY_CLASSES_ROOT (or HKCR), or
HKEY_CURRENT_CONFIG (or HKCC).
To access a remote registry, prepend the computer name and a colon, as
in this example: \\workstation01:HKEY_LOCAL_MACHINE
Key
The name of the key (e.g. Software\SomeApplication). If blank or omitted,
the contents of RootKey will be retrieved.
IncludeSubkeys?
0 (default) Subkeys contained within Key are not retrieved (only the
values).
1 All values and subkeys are retrieved.
2 Only the subkeys are retrieved (not the values).
Recurse?
0 (default) Subkeys are not recursed into.
1 Subkeys are recursed into, so that all values and subkeys contained
therein are retrieved.
Remarks
A registry-loop is useful when you want to operate on a collection registry values or subkeys, one at a
time. The values and subkeys are retrieved in reverse order (bottom to top) so that RegDelete can be
used inside the loop without disrupting the loop.
The following variables exist within any registry-loop. If an inner registry-loop is enclosed by an outer
registry-loop, the innermost loop's registry item will take precedence:
A_LoopRegName
Name of the currently retrieved item, which can be either a value
name or the name of a subkey. Value names displayed by Windows
RegEdit as "(Default)" will be retrieved if a value has been assigned
to them, but A_LoopRegName will be blank for them.
A_LoopRegType
The type of the currently retrieved item, which is one of the
following words: KEY (i.e. the currently retrieved item is a subkey
not a value), REG_SZ, REG_EXPAND_SZ, REG_MULTI_SZ,
REG_DWORD, REG_QWORD, REG_BINARY, REG_LINK,
REG_RESOURCE_LIST, REG_FULL_RESOURCE_DESCRIPTOR,
REG_RESOURCE_REQUIREMENTS_LIST,
REG_DWORD_BIG_ENDIAN (probably rare on most Windows
hardware). It will be empty if the currently retrieved item is of an
unknown type.
A_LoopRegKey
The name of the root key being accessed (HKEY_LOCAL_MACHINE,
HKEY_USERS, HKEY_CURRENT_USER, HKEY_CLASSES_ROOT, or
HKEY_CURRENT_CONFIG). For remote registry access, this value
will not include the computer name.
A_LoopRegSubKey
Name of the current SubKey. This will be the same as the Key
parameter unless the Recurse parameter is being used to
Printed Documentation
446
recursively explore other subkeys. In that case, it will be the full
path of the currently retrieved item, not including the root key. For
example: Software\SomeApplication\My SubKey
A_LoopRegTimeModified
The time the current subkey or any of its values was last modified.
Format YYYYMMDDHH24MISS. This variable will be empty if the
currently retrieved item is not a subkey (i.e. A_LoopRegType is not
the word KEY) or if the operating system is Win9x (since Win9x
does not track this info).
When used inside a registry-loop, the following commands can be used in a simplified way to indicate
that the currently retrieved item should be operated upon:
RegRead,
OutputVar
Reads the current item. If the current item is a key, ErrorLevel will be set
to 1 and OutputVar will be made empty.
RegWrite [, Value]
Writes to the current item. If Value is omitted, the item will be made 0 or
blank depending on its type. If the current item is a key, ErrorLevel will
be set to 1 and there will be no other effect.
RegDelete
Deletes the current item. If the current item is a key, it will be deleted
along with any subkeys and values it contains.
When accessing a remote registry (via the RootKey parameter described above), the following notes
apply:
The target machine must be running the Remote Registry service, or (for Windows Me/98/95)
have the Microsoft Remote Registry service installed (this can be obtained from Microsoft).
Access to a remote registry may fail if the target computer is not in the same domain as yours
or the local or remote username lacks sufficient permissions (however, see below for possible
workarounds).
Depending on your username's domain, workgroup, and/or permissions, you may have to
connect to a shared device, such as by mapping a drive, prior to attempting remote registry
access. Making such a connection -- using a remote username and password that has
permission to access or edit the registry -- may as a side-effect enable remote registry access.
If you're already connected to the target computer as a different user (for example, a mapped
drive via user Guest), you may have to terminate that connection to allow the remote registry
feature to reconnect and re-authenticate you as your own currently logged-on username.
For Windows Server 2003 and Windows XP Professional, MSDN states: "If the computer is
joined to a workgroup and the "Force network logons using local accounts to authenticate as
Guest" policy is enabled, the function fails. Note that this policy is enabled by default if the
computer is joined to a workgroup."
For Windows XP Home Edition, MSDN states that "this function always fails".
If anyone knows for certain whether the last two items above apply to the local computer, the
remote computer, or both, please contact the author.
See Loop for information about Blocks, Break, Continue, and the A_Index variable (which exists in
every type of loop).
Related
Loop, Break, Continue, Blocks, RegRead, RegWrite, RegDelete
Examples
; Example: Delete Internet Explorer's history of URLs typed by the user:
Loop, HKEY_CURRENT_USER, Software\Microsoft\Internet Explorer\TypedURLs
RegDelete
Registry Management
447

; Example: A working test script:
Loop, HKEY_CURRENT_USER, Software\Microsoft\Windows, 1, 1
{
if a_LoopRegType = key
value =
else
{
RegRead, value
if ErrorLevel
value = *error*
}
MsgBox, 4, , %a_LoopRegName% = %value% (%a_LoopRegType%)`n`nContinue?
IfMsgBox, NO, break
}

; Example: A working example to recursively search the entire
; registry for particular value(s).
SetBatchLines -1 ; Makes searching occur at maximum speed.
RegSearchTarget = Notepad ; Tell the subroutine what to search for.
Gosub, RegSearch
return

RegSearch:
ContinueRegSearch = y
Loop, HKEY_LOCAL_MACHINE, , 1, 1
{
Gosub, CheckThisRegItem
if ContinueRegSearch = n ; It told us to stop.
return
}
Loop, HKEY_USERS, , 1, 1
{
Gosub, CheckThisRegItem
if ContinueRegSearch = n ; It told us to stop.
return
}
Loop, HKEY_CURRENT_CONFIG, , 1, 1
Printed Documentation
448
{
Gosub, CheckThisRegItem
if ContinueRegSearch = n ; It told us to stop.
return
}
; Note: I believe HKEY_CURRENT_USER does not need to be searched if HKEY_USERS
; is being searched. The same might also be true for HKEY_CLASSES_ROOT if
; HKEY_LOCAL_MACHINE is being searched.
return

CheckThisRegItem:
if A_LoopRegType = KEY ; Remove these two lines if you want to check key names too.
return
RegRead, RegValue
if ErrorLevel
return
IfInString, RegValue, %RegSearchTarget%
{
MsgBox, 4, , The following match was
found:`n%A_LoopRegKey%\%A_LoopRegSubKey%\%A_LoopRegName%`nValue =
%RegValue%`n`nContinue?
IfMsgBox, No
ContinueRegSearch = n ; Tell our caller to stop searching.
}
return
RegDelete
Deletes a subkey or value from the registry.
RegDelete, RootKey, SubKey [, ValueName]
Parameters
RootKey
Must be either HKEY_LOCAL_MACHINE, HKEY_USERS, HKEY_CURRENT_USER,
HKEY_CLASSES_ROOT, or HKEY_CURRENT_CONFIG (or the abbreviations for
each of these, such as HKLM). To access a remote registry, prepend the
computer name and a colon, as in this example:
\\workstation01:HKEY_LOCAL_MACHINE
SubKey The name of the subkey (e.g. Software\SomeApplication).
ValueName
The name of the value to delete. If omitted, the entire SubKey will be
deleted. To delete Subkey's default value -- which is the value displayed as
"(Default)" by RegEdit -- use the phrase AHK_DEFAULT for this parameter.
ErrorLevel
Registry Management
449
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
Deleting from the registry is potential dangerous - please exercise caution!
To retrieve and operate upon multiple registry keys or values, consider using a registry-loop.
For details about how to access the registry of a remote computer, see the remarks in registry-loop.
Related
RegRead, RegWrite, Registry-loop, IniDelete
Example
RegDelete, HKEY_LOCAL_MACHINE, Software\SomeApplication, TestValue
RegRead
Reads a value from the registry.
RegRead, OutputVar, RootKey, SubKey [, ValueName]
Parameters
OutputVar
The name of the variable in which to store the retrieved value. If the value
cannot be retrieved, the variable is made blank and ErrorLevel is set to 1.
RootKey
Must be either HKEY_LOCAL_MACHINE, HKEY_USERS, HKEY_CURRENT_USER,
HKEY_CLASSES_ROOT, or HKEY_CURRENT_CONFIG (or the abbreviations for
each of these, such as HKLM). To access a remote registry, prepend the
computer name and a colon, as in this example:
\\workstation01:HKEY_LOCAL_MACHINE
SubKey The name of the subkey (e.g. Software\SomeApplication).
ValueName
The name of the value to retrieve. If omitted, Subkey's default value will be
retrieved, which is the value displayed as "(Default)" by RegEdit. If there is no
default value (that is, if RegEdit displays "value not set"), OutputVar is made
blank and ErrorLevel is set to 1.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
Currently only the following value types are supported: REG_SZ, REG_EXPAND_SZ, REG_MULTI_SZ,
REG_DWORD, and REG_BINARY.
REG_DWORD values are always expressed as positive decimal numbers.
Although no more than 64 KB of data can be read from REG_BINARY values, the other types are
unlimited except under Windows 95/98/ME, which have a 64 KB limit for all types (the Win9x registry
is not capable of storing larger values).
When reading a REG_BINARY key the result is a string of hex characters. For example, the
REG_BINARY value of 01,a9,ff,77 will be read as the string 01A9FF77.
When reading a REG_MULTI_SZ key, each of the components ends in a linefeed character (`n). If
there are no components, OutputVar will be made blank. See FileSelectFile for an example of how to
Printed Documentation
450
extract the individual components from OutputVar. Note: Windows 95 does not support the
REG_MULTI_SZ value type.
To retrieve and operate upon multiple registry keys or values, consider using a registry-loop.
For details about how to access the registry of a remote computer, see the remarks in registry-loop.
Related
RegDelete, RegWrite, Registry-loop, IniRead
Example
RegRead, OutputVar, HKEY_LOCAL_MACHINE, SOFTWARE\Microsoft\Windows\CurrentVersion,
ProgramFilesDir
MsgBox, Program files are in: %OutputVar%
RegWrite
Writes a value to the registry.
RegWrite, ValueType, RootKey, SubKey [, ValueName, Value]
Parameters
ValueType
Must be either REG_SZ, REG_EXPAND_SZ, REG_MULTI_SZ, REG_DWORD, or
REG_BINARY.
RootKey
Must be either HKEY_LOCAL_MACHINE, HKEY_USERS, HKEY_CURRENT_USER,
HKEY_CLASSES_ROOT, or HKEY_CURRENT_CONFIG (or the abbreviations for
each of these, such as HKLM). To access a remote registry, prepend the
computer name and a colon, as in this example:
\\workstation01:HKEY_LOCAL_MACHINE
SubKey
The name of the subkey (e.g. Software\SomeApplication). If SubKey does not
exist, it is created (along with its ancestors, if necessary). If SubKey is left
blank, the value is written directly into RootKey (though some operating
systems might refuse to write in HKEY_CURRENT_USER's top level).
ValueName
The name of the value that will be written to. If blank or omitted, Subkey's
default value will be used, which is the value displayed as "(Default)" by
RegEdit.
Value
The value to be written. If omitted, it will default to an empty (blank) string, or
0, depending on ValueType. If the text is long, it can be broken up into several
shorter lines by means of a continuation section, which might improve
readability and maintainability.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
If ValueType is REG_DWORD, Value should be between -2147483648 and 4294967295 (0xFFFFFFFF).
Although no more than 64 KB of data can be written to REG_BINARY and REG_MULTI_SZ values, the
other types are unlimited except under Windows 95/98/ME, which have a 64 KB limit for all types. If
the 64 KB limit applies, data beyond that limit will not be written. In other words, only the first 64 KB
of a very large string will be saved to the registry.
Registry Management
451
When writing a REG_BINARY key, use a string of hex characters, e.g. the REG_BINARY value of
01,a9,ff,77 can be written by using the string 01A9FF77.
When writing a REG_MULTI_SZ key, you must separate each component from the next with a linefeed
character (`n). The last component may optionally end with a linefeed as well. No blank components
are allowed. In other words, do not specify two linefeeds in a row (`n`n) because that will result in a
shorter-than-expected value being written to the registry. Note: Windows 95 does not support the
REG_MULTI_SZ value type.
To retrieve and operate upon multiple registry keys or values, consider using a registry-loop.
For details about how to access the registry of a remote computer, see the remarks in registry-loop.
Related
RegDelete, RegRead, Registry-loop, IniWrite
Examples
RegWrite, REG_SZ, HKEY_LOCAL_MACHINE, SOFTWARE\TestKey, MyValueName, Test Value
RegWrite, REG_BINARY, HKEY_CURRENT_USER, Software\TEST_APP, TEST_NAME, 01A9FF77
RegWrite, REG_MULTI_SZ, HKEY_CURRENT_USER, Software\TEST_APP, TEST_NAME, Line1`nLine2

453
Sound Commands
SoundBeep
Emits a tone from the PC speaker.
SoundBeep [, Frequency, Duration]
Parameters
Frequency
The frequency of the sound, which can be an expression. It should be a
number between 37 and 32767. If omitted, the frequency will be 523.
Duration
The duration of the sound, in milliseconds (can be an expression). If omitted,
the duration will be 150.
Remarks
The script waits for the sound to finish before continuing. In addition, system responsiveness might be
reduced during sound production.
On Windows 9x, the Frequency and Duration parameters are ignored. Instead, the system default
sound event is played through the sound card. If the computer lacks a sound card, a standard beep is
played through the PC speaker.
To produce the standard system sounds instead of beeping the PC Speaker, see the asterisk mode of
SoundPlay.
Related
SoundPlay
Example
SoundBeep ; Play the default pitch and duration.
SoundBeep, 750, 500 ; Play a higher pitch for half a second.
SoundGet
Retrieves various settings from a sound device (master mute, master volume, etc.)
SoundGet, OutputVar [, ComponentType, ControlType, DeviceNumber]
Parameters
OutputVar
The name of the variable in which to store the retrieved setting, which is
either a floating point number between 0 and 100 (inclusive) or the word
ON or OFF (used only for ControlTypes ONOFF, MUTE, MONO, LOUDNESS,
STEREOENH, and BASSBOOST). The variable will be made blank if there
was a problem retrieving the setting. The format of the floating point
number, such as its decimal places, is determined by SetFormat.
ComponentType
If omitted or blank, it defaults to the word MASTER. Otherwise, it can be
one of the following words: MASTER (synonymous with SPEAKERS),
DIGITAL, LINE, MICROPHONE, SYNTH, CD, TELEPHONE, PCSPEAKER,
WAVE, AUX, or ANALOG (in addition, in v1.0.37.06+ it can be N/A; and in
v1.0.42.04+ it can be HEADPHONES). If the sound device lacks the
specified ComponentType, ErrorLevel will indicate the problem.
Printed Documentation
454
The component labled Auxiliary in some mixers might be accessible as
ANALOG rather than AUX.
If a device has more than one instance of ComponentType (two of type
LINE, for example), usually the first contains the playback settings and the
second contains the recording settings. To access an instance other than
the first, append a colon and a number to this parameter. For example:
Analog:2 is the second instance of the analog component.
ControlType
If omitted or blank, it defaults to VOLUME. Otherwise, it can be one of the
following words: VOLUME (or VOL), ONOFF, MUTE, MONO, LOUDNESS,
STEREOENH, BASSBOOST, PAN, QSOUNDPAN, BASS, TREBLE, or
EQUALIZER. In v1.0.37.06+, it can also be the number of a valid control
type (see soundcard analysis script). If the specified ComponentType lacks
the specified ControlType, ErrorLevel will indicate the problem.
DeviceNumber
If this parameter is omitted, it defaults to 1 (the first sound device), which
is usually the system's default device for recording and playback. Specify a
number higher than 1 to operate upon a different sound device. This
parameter can be an expression.
ErrorLevel
ErrorLevel is set to 0 if the command succeeded. Otherwise, it is set to one of the following phrases:
Invalid Control Type or Component Type
Can't Open Specified Mixer
Mixer Doesn't Support This Component Type
Mixer Doesn't Have That Many of That Component Type
Component Doesn't Support This Control Type
Can't Get Current Setting
Remarks
To discover the capabilities of the sound devices (mixers) installed on the system -- such as the
available component types and control types -- run the soundcard analysis script.
Use SoundSet to change a setting.
Related
SoundSet, SoundGetWaveVolume, SoundSetWaveVolume, SoundPlay
Examples
SoundGet, master_volume
MsgBox, Master volume is %master_volume% percent.

SoundGet, master_mute, , mute
MsgBox, Master Mute is currently %master_mute%.

SoundGet, bass_level, Master, bass
if ErrorLevel
MsgBox, Error Description: %ErrorLevel%
Sound Commands
455
else
MsgBox, The BASS level for MASTER is %bass_level% percent.

SoundGet, microphone_mute, Microphone, mute
if microphone_mute = Off
MsgBox, The microphone is not muted.
SoundGetWaveVolume
Retrieves the wave output volume for a sound device.
SoundGetWaveVolume, OutputVar [, DeviceNumber]
Parameters
OutputVar
The name of the variable in which to store the retrieved volume level, which
is a floating point number between 0 and 100 inclusive. The variable will be
made blank if there was a problem retrieving the volume. The format of the
floating point number, such as its decimal places, is determined by
SetFormat.
DeviceNumber
If this parameter is omitted, it defaults to 1 (the first sound device), which is
usually the system's default device for recording and playback. Specify a
number higher than 1 to operate upon a different sound device.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
The current wave output volume level can be set via SoundSetWaveVolume. Settings such as Master
Volume, Synth, Microphone, Mute, Treble, and Bass can be set and retrieved using SoundSet and
SoundGet.
Related
SoundSetWaveVolume, SoundSet, SoundGet, SoundPlay
Example
SoundGetWaveVolume, OutputVar
MsgBox, The current wave output volume level is %OutputVar%`%.
SoundPlay
Plays a sound, video, or other supported file type.
SoundPlay, Filename [, wait]
Parameters
Filename
The name of the file to be played, which is assumed to be in %A_WorkingDir%
if an absolute path isn't specified.
To produce standard system sounds, specify an asterisk followed by a number
Printed Documentation
456
as shown below. Note: the wait parameter has no effect in this mode.
*-1: Simple beep. If the sound card is not available, the sound is generated
using the speaker.
*16: Hand (stop/error)
*32: Question
*48: Exclamation
*64: Asterisk (info)
wait
If omitted, the script's current thread will move on to the next commmand(s)
while the file is playing. To avoid this, specify 1 or the word WAIT, which
causes the current thread to wait until the file is finished playing before
continuing. Even while waiting, new threads can be launched via hotkey,
custom menu item, or timer.
Known limitation: If the WAIT parameter is omitted, the OS might consider the
playing file to be "in use" until the script closes or until another file is played
(even a nonexistent file).
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
All Windows OSes should be able to play .wav files. However, other files (.mp3, .avi, etc.) might not
be playable if the right codecs or features aren't installed on the OS.
If a file is playing and the current script plays a second file, the first file will be stopped so that the
second one can play. On some systems, certain file types might stop playing even when an entirely
separate script plays a new file.
To stop a file that is currently playing, use SoundPlay on a nonexistent filename as in this example:
SoundPlay, Nonexistent.avi
If the script is terminated, any currently-playing file that it started will stop.
Related
SoundBeep, SoundGet, SoundSet, SoundGetWaveVolume, SoundSetWaveVolume, MsgBox, Threads
Example
SoundPlay, %A_WinDir%\Media\ding.wav
SoundSet
Changes various settings of a sound device (master mute, master volume, etc.)
SoundSet, NewSetting [, ComponentType, ControlType, DeviceNumber]
Parameters
NewSetting
Percentage number between -100 and 100 inclusive (it can be a floating
point number or expression). If the number begins with a plus or minus
sign, the current setting will be adjusted up or down by the indicated
amount. Otherwise, the setting will be set explicitly to the level indicated by
NewSetting.
For ControlTypes with only two possible settings -- namely ONOFF, MUTE,
Sound Commands
457
MONO, LOUDNESS, STEREOENH, and BASSBOOST -- any positive number
will turn on the setting and a zero will turn it off. However, if the number
begins with a plus or minus sign, the setting will be toggled (set to the
opposite of its current state).
ComponentType
If omitted or blank, it defaults to the word MASTER. Otherwise, it can be
one of the following words: MASTER (synonymous with SPEAKERS),
DIGITAL, LINE, MICROPHONE, SYNTH, CD, TELEPHONE, PCSPEAKER,
WAVE, AUX, or ANALOG (in addition, in v1.0.37.06+ it can be N/A; and in
v1.0.42.04+ it can be HEADPHONES). If the sound device lacks the
specified ComponentType, ErrorLevel will indicate the problem.
The component labeled Auxiliary in some mixers might be accessible as
ANALOG rather than AUX.
If a device has more than one instance of ComponentType (two of type
LINE, for example), usually the first contains the playback settings and the
second contains the recording settings. To access an instance other than
the first, append a colon and a number to this parameter. For example:
Analog:2 is the second instance of the analog component.
ControlType
If omitted or blank, it defaults to VOLUME. Otherwise, it can be one of the
following words: VOLUME (or VOL), ONOFF, MUTE, MONO, LOUDNESS,
STEREOENH, BASSBOOST, PAN, QSOUNDPAN, BASS, TREBLE, or
EQUALIZER. In v1.0.37.06+, it can also be the number of a valid control
type (see soundcard analysis script). If the specified ComponentType lacks
the specified ControlType, ErrorLevel will indicate the problem.
DeviceNumber
If this parameter is omitted, it defaults to 1 (the first sound device), which
is usually the system's default device for recording and playback. Specify a
number higher than 1 to operate upon a different sound device. This
parameter can be an expression.
ErrorLevel
ErrorLevel is set to 0 if the command succeeded. Otherwise, it is set to one of the following phrases:
Invalid Control Type or Component Type
Can't Open Specified Mixer
Mixer Doesn't Support This Component Type
Mixer Doesn't Have That Many of That Component Type
Component Doesn't Support This Control Type
Can't Get Current Setting
Can't Change Setting
Remarks
To discover the capabilities of the sound devices (mixers) installed on the system -- such as the
available component types and control types -- run the soundcard analysis script.
When SoundSet changes the volume of a component, all of that component's channels (e.g. left and
right) are set to the same level. In other words, any off-center "balance" that may have been set
previously is lost. This can be avoided for the WAVE component by using SoundSetWaveVolume
instead, which attempts to preserve the existing balance when changing the volume level.
Use SoundGet to retrieve the current value of a setting.
Related
Printed Documentation
458
SoundGet, SoundGetWaveVolume, SoundSetWaveVolume, SoundPlay
Examples
; BASIC EXAMPLES:
SoundSet, 50 ; Set the master volume to 50%
SoundSet +10 ; Increase master volume by 10%
SoundSet -10 ; Decrease master volume by 10%
SoundSet, 1, Microphone, mute ; mute the microphone
SoundSet, +1, , mute ; Toggle the master mute (set it to the opposite state)
SoundSet, +20, Master, bass ; Increase bass level by 20%.
if ErrorLevel
MsgBox, The BASS setting is not supported for MASTER.

; SOUNDCARD ANALYSIS
; Use the following script to discover your soundcard's capabilities (component types and control
types).
; This script requires v1.0.36+ because it uses a ListView.

SetBatchLines -1
SplashTextOn,,, Gathering Soundcard Info...

; Most of the pure numbers below probably don't exist in any mixer, but they're queried for
completeness.
; The numbers correspond to the following items (in order): CUSTOM, BOOLEANMETER,
SIGNEDMETER, PEAKMETER,
; UNSIGNEDMETER, BOOLEAN, BUTTON, DECIBELS, SIGNED, UNSIGNED, PERCENT, SLIDER, FADER,
SINGLESELECT, MUX,
; MULTIPLESELECT, MIXER, MICROTIME, MILLITIME
ControlTypes =
VOLUME,ONOFF,MUTE,MONO,LOUDNESS,STEREOENH,BASSBOOST,PAN,QSOUNDPAN,BASS,TREBLE,E
QUALIZER,0x00000000,
0x10010000,0x10020000,0x10020001,0x10030000,0x20010000,0x21010000,0x30040000,0x300200
00,0x30030000,0x30050000,0x40020000,0x50030000,0x70010000,0x70010001,0x71010000,0x710
10001,0x60030000,0x61030000

ComponentTypes =
MASTER,HEADPHONES,DIGITAL,LINE,MICROPHONE,SYNTH,CD,TELEPHONE,PCSPEAKER,WAVE,AUX,A
NALOG,N/A

; Create a ListView and prepare for the main loop:
Gui, Add, Listview, w400 h400 vMyListView, Component Type|Control Type|Setting|Mixer
LV_ModifyCol(4, "Integer")
Sound Commands
459
SetFormat, Float, 0.2 ; Limit number of decimal places in percentages to two.

Loop ; For each mixer number that exists in the system, query its capabilities.
{
CurrMixer := A_Index
SoundGet, Setting,,, %CurrMixer%
if ErrorLevel = Can't Open Specified Mixer ; Any error other than this indicates that the mixer
exists.
break

; For each component type that exists in this mixer, query its instances and control types:
Loop, parse, ComponentTypes, `,
{
CurrComponent := A_LoopField
; First check if this component type even exists in the mixer:
SoundGet, Setting, %CurrComponent%,, %CurrMixer%
if ErrorLevel = Mixer Doesn't Support This Component Type
continue ; Start a new iteration to move on to the next component type.
Loop ; For each instance of this component type, query its control types.
{
CurrInstance := A_Index
; First check if this instance of this instance even exists in the mixer:
SoundGet, Setting, %CurrComponent%:%CurrInstance%,, %CurrMixer%
; Checking for both of the following errors allows this script to run on older versions:
if ErrorLevel in Mixer Doesn't Have That Many of That Component Type,Invalid Control Type
or Component Type
break ; No more instances of this component type.
; Get the current setting of each control type that exists in this instance of this component:
Loop, parse, ControlTypes, `,
{
CurrControl := A_LoopField
SoundGet, Setting, %CurrComponent%:%CurrInstance%, %CurrControl%, %CurrMixer%
; Checking for both of the following errors allows this script to run on older versions:
if ErrorLevel in Component Doesn't Support This Control Type,Invalid Control Type or
Component Type
continue
if ErrorLevel ; Some other error, which is unexpected so show it in the results.
Setting := ErrorLevel
ComponentString := CurrComponent
Printed Documentation
460
if CurrInstance > 1
ComponentString = %ComponentString%:%CurrInstance%
LV_Add("", ComponentString, CurrControl, Setting, CurrMixer)
} ; For each control type.
} ; For each component instance.
} ; For each component type.
} ; For each mixer.

Loop % LV_GetCount("Col") ; Auto-size each column to fit its contents.
LV_ModifyCol(A_Index, "AutoHdr")

SplashTextOff
Gui, Show
return

GuiClose:
ExitApp
SoundSetWaveVolume
Changes the wave output volume for a sound device.
SoundSetWaveVolume, Percent [, DeviceNumber]
Parameters
Percent
Percentage number between -100 and 100 inclusive (it can be a floating
point number or an expression). If the number begins with a plus or minus
sign, the current volume level will be adjusted up or down by the indicated
amount. Otherwise, the volume will be set explicitly to the level indicated by
Percent.
DeviceNumber
If this parameter is omitted, it defaults to 1 (the first sound device), which is
usually the system's default device for recording and playback. Specify a
number higher than 1 to operate upon a different sound device.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
The current wave output volume level can be retrieved via SoundGetWaveVolume. Settings such as
Master Volume, Synth, Microphone, Mute, Treble, and Bass can be set and retrieved using SoundSet
and SoundGet.
Unlike SoundSet, this command attempts to preserve the existing balance between channels (e.g. left
and right) when changing the volume level.
Related
Sound Commands
461
SoundGetWaveVolume, SoundSet, SoundGet, SoundPlay
Examples
SoundSetWaveVolume, 50 ; Set the volume to its half-way point.
SoundSetVolume, -10 ; Decrease the current level by 10 (e.g. 80 would become 70).
SoundSetVolume, +20 ; Increase the current level by 20.

463
String Management
FormatTime
Transforms a YYYYMMDDHH24MISS timestamp into the specified date/time format.
FormatTime, OutputVar [, YYYYMMDDHH24MISS, Format]
Parameters
OutputVar The name of the variable in which to store the result.
YYYYMMDD...
Leave this parameter blank to use the current local date and time. Otherwise,
specify all or the leading part of a timestamp in the YYYYMMDDHH24MISS
format. If the date and/or time portion of the timestamp is invalid -- such as
February 29th of a non-leap year -- the date and/or time will be omitted from
OutputVar. Although only years between 1601 and 9999 are supported, a
formatted time can still be produced for earlier years as long as the time
portion is valid.
Format
If omitted, it defaults to the time followed by the long date, both of which will
be formatted according to the current user's locale. For example: 4:55 PM
Saturday, November 27, 2004
Otherwise, specify one or more of the date-time formats below, along with
any literal spaces and punctuation in between (commas do not need to be
escaped; they can be used normally). In the following example, note that M
must be capitalized: M/d/yyyy h:mm tt
Date Formats (case sensitive)
d Day of the month without leading zero (1 - 31)
dd Day of the month with leading zero (01 31)
ddd
Abbreviated name for the day of the week (e.g. Mon) in the current user's
language
dddd Full name for the day of the week (e.g. Monday) in the current user's language
M Month without leading zero (1 12)
MM Month with leading zero (01 12)
MMM Abbreviated month name (e.g. Jan) in the current user's language
MMMM Full month name (e.g. January) in the current user's language
y Year without century, without leading zero (0 99)
yy Year without century, with leading zero (00 - 99)
yyyy Year with century. For example: 2005
gg Period/era string for the current user's locale (blank if none)
Time Formats (case sensitive)
h Hours without leading zero; 12-hour format (1 - 12)
hh Hours with leading zero; 12-hour format (01 12)
H Hours without leading zero; 24-hour format (0 - 23)
HH Hours with leading zero; 24-hour format (00 23)
Printed Documentation
464
m Minutes without leading zero (0 59)
mm Minutes with leading zero (00 59)
s Seconds without leading zero (0 59)
ss Seconds with leading zero (00 59)
t Single character time marker, such as A or P (depends on locale)
tt Multi-character time marker, such as AM or PM (depends on locale)
The following formats must be used alone; that
is, with no other formats or text present in the
Format parameter. These formats are not case
sensitive.
(Blank)
Leave Format blank to produce the time followed by the long date. For
example, in some locales it might appear as 4:55 PM Saturday, November 27,
2004
Time Time representation for the current user's locale, such as 5:26 PM
ShortDate Short date representation for the current user's locale, such as 02/29/04
LongDate
Long date representation for the current user's locale, such as Friday, April 23,
2004
YearMonth Year and month format for the current user's locale, such as February, 2004
YDay Day of the year without leading zeros (1 366)
YDay0 Day of the year with leading zeros (001 366)
WDay Day of the week (1 7). Sunday is 1.
YWeek
The ISO 8601 full year and week number. For example: 200453. If the week
containing January 1st has four or more days in the new year, it is considered
week 1. Otherwise, it is the last week of the previous year, and the next week
is week 1. Consequently, both January 4th and the first Thursday of January
are always in week 1.
Additional Options
The following options can appear inside the YYYYMMDDHH24MISS parameter immediately after the
timestamp (if there is no timestamp, they may be used alone). In the following example, note the lack
of commas between the last four items:
FormatTime, OutputVar, 20040228 LSys D1 D4
R: Reverse. Have the date come before the time (meaningful only when Format is blank).
Ln: If this option is not present, the current user's locale is used to format the string. To use the
system's locale instead, specify LSys. To use a specific locale, specify the letter L followed by a
hexadecimal or decimal locale identifier (LCID). For information on how to construct an LCID, search
www.microsoft.com for the following phrase: Locale Identifiers
Dn: Date options. Specify for n one of the following numbers:
0: Force the default options to be used. This also causes the short date to be in effect.
1: Use short date (meaningful only when Format is blank; not compatible with 2 and 8).
2: Use long date (meaningful only when Format is blank; not compatible with 1 and 8).
4: Use alternate calendar (if any).
8: Use Year-Month format (meaningful only when Format is blank; not compatible with 1 and 2).
String Management
465
Requires Windows 2000 or later.
0x10: Add marks for left-to-right reading order layout. Has no effect except on Windows 2000 or later.
0x20: Add marks for right-to-left reading order layout. Has no effect except on Windows 2000 or later.
0x80000000: Do not obey any overrides the user may have in effect for the system's default date
format.
0x40000000: Use the system ANSI code page for string translation instead of the locale's code page.
Tn: Time options. Specify for n one of the following numbers:
0: Force the default options to be used. This also causes minutes and seconds to be shown.
1: Omit minutes and seconds.
2: Omit seconds.
4: Omit time marker (e.g. AM/PM).
8: Always use 24-hour time rather than 12-hour time.
12: Combination of the above two.
0x80000000: Do not obey any overrides the user may have in effect for the system's default time
format.
0x40000000: Use the system ANSI code page for string translation instead of the locale's code page.
Note: Dn and Tn may be repeated to put more than one option into effect, such as this example:
FormatTime, OutputVar, 20040228 D2 D4 T1 T8
Remarks
Letters and numbers that you want to be transcribed literally from Format into OutputVar should be
enclosed in single quotes as in this example: 'Date:' MM/dd/yy 'Time:' hh:mm:ss tt
By contrast, non-alphanumeric characters such as spaces, tabs, linefeeds (`n), slashes, colons,
commas, and other punctuation do not need to be enclosed in single quotes. The exception to this is
the single quote character itself: to produce it literally, use four consecutive single quotes (''''), or just
two if the quote is already inside an outer pair of quotes.
If Format contains date and time elements together, they must not be intermixed. In other words, the
string should be dividable into two halves: a time half and a date half. For example, a format string
consisting of "hh yyyy mm" would not produce the expected result because it has a date element in
between two time elements.
When Format contains a numeric day of the month (either d or dd) followed by the full month name
(MMMM), the genitive form of the month name is used (if the language has a genitive form).
If Format contains more than 2000 characters, OutputVar will be made blank.
On a related note, addition and subtraction of dates and times can be performed with EnvAdd and
EnvSub.
Related
Gui DateTime control, SetFormat, Transform, built-in date and time variables, FileGetTime
Examples
FormatTime, TimeString
MsgBox The current time and date (time first) is %TimeString%.

FormatTime, TimeString, R
MsgBox The current time and date (date first) is %TimeString%.

FormatTime, TimeString,, Time
MsgBox The current time is %TimeString%.
Printed Documentation
466

FormatTime, TimeString, T12, Time
MsgBox The current 24-hour time is %TimeString%.

FormatTime, TimeString,, LongDate
MsgBox The current date (long format) is %TimeString%.

FormatTime, TimeString, 20050423220133, dddd MMMM d, yyyy hh:mm:ss tt
MsgBox The specified date and time, when formatted, is %TimeString%.

FormatTime, TimeString, 200504, 'Month Name': MMMM`n'Day Name': dddd
MsgBox %TimeString%

FormatTime, YearWeek, 20050101, YWeek
MsgBox January 1st of 2005 is in the following ISO year and week number: %YearWeek%

; Change the date-time stamp of a file:
FileSelectFile, FileName, 3,, Pick a file
if FileName = ; The user didn't pick a file.
return
FileGetTime, FileTime, %FileName%
FormatTime, FileTime, %FileTime% ; Since the last parameter is omitted, the long date and time are
retrieved.
MsgBox The selected file was last modified at %FileTime%.

; The following function converts the specified number of seconds into the corresponding
; number of hours, minutes, and seconds (hh:mm:ss format).

MsgBox % FormatSeconds(7384) ; 7384 = 2 hours + 3 minutes + 4 seconds. It yields: 2:03:04

FormatSeconds(NumberOfSeconds) ; Convert the specified number of seconds to hh:mm:ss format.
{
time = 19990101 ; *Midnight* of an arbitrary date.
time += %NumberOfSeconds%, seconds
FormatTime, mmss, %time%, mm:ss
return NumberOfSeconds//3600 ":" mmss ; This method is used to support more than 24 hours
worth of sections.
}
String Management
467
If/IfEqual/IfNotEqual/IfLess/IfLessOrEqual/IfGreater/IfGreaterOrEqual
Specifies the command(s) to perform if the comparison of a variable to a value evalutes to TRUE.
When more than one command is present, enclose them in a block (braces).
IfEqual, var, value (same: if var = value)
IfNotEqual, var, value (same: if var <> value) (!= can be used in place of <>)
IfGreater, var, value (same: if var > value)
IfGreaterOrEqual, var, value (same: if var >= value)
IfLess, var, value (same: if var < value)
IfLessOrEqual, var, value (same: if var <= value)
If var ; If var's contents are blank or 0, it is considered false. Otherwise, it is true.

See also: IfInString
Parameters
var The variable name.
value
A literal string, number, or variable reference (e.g. %var2%). Value can be
omitted if you wish to compare var to an empty string (blank).
Remarks
If both var and value are purely numeric, they will be compared as numbers rather than as strings.
Otherwise, they will be compared alphabetically as strings (that is, alphabetical order will determine
whether var is greater, equal, or less than value).
When an IF or an ELSE owns more than one line, those lines must be enclosed in braces. For example:
if count <= 0
{
WinClose Untitled - Notepad
MsgBox There are no items present.
}
However, if only one line belongs to the IF or ELSE, the braces are optional.
Another command can only appear on the same line as the IF statement if you use the command-
name style. In other words, these are valid:
IfEqual, x, 1, Sleep, 1
IfGreater, x, 1, EnvAdd, x, 2
But these are not valid:
if x = 1 Sleep 1
IfGreater, x, 1, x += 2
The One True Brace (OTB) style may not be used with these types of if-statements. It can only be
used with expression if-statements.
On a related note, the command "if var [not] between LowerBound and UpperBound" checks whether
a variable is between two values, and "if var [not] in value1,value2" can be used to check whether a
variable's contents exist within a list of values.
Related
IF (expression), Assign expression (:=), if var in/contains MatchList, if var between, IfInString, Blocks,
Else
Printed Documentation
468
Example
if counter >= 1
Sleep, 10

if counter >=1 ; If an IF has more than one line, enclose those lines in braces:
{
WinClose, Untitled - Notepad
Sleep 10
}

if MyVar = %MyVar2%
MsgBox The contents of MyVar and MyVar2 are identical.
else if MyVar =
{
MsgBox, 4,, MyVar is empty/blank. Continue?
IfMsgBox, No
Return
}
else if MyVar <> ,
MsgBox The value in MyVar is not a comma.
else
MsgBox The value in MyVar is a comma.

if Done
MsgBox The variable Done is neither empty nor zero.
IfInString / IfNotInString
Checks if a variable contains the specified string.
IfInString, var, SearchString
IfNotInString, var, SearchString
Position := InStr(Haystack, Needle [, CaseSensitive?, StartingPos]]) ; See the InStr() function for
details.
Parameters
var The name of the variable whose contents will be searched for a match.
SearchString The string to search for.
Remarks
The built-in variables %A_Space% and %A_Tab% contain a single space and a single tab character,
respectively, which might be useful when searching for these characters alone.
String Management
469
Another command can appear on the same line as this one. In other words, both of these are
equivalent:
IfInString, MyVar, abc, Gosub, Process1
IfInString, MyVar, abc
Gosub, Process1
However, items other than named commands are not supported on the same line. For example:
IfInString, MyVar, abc, found := true ; Invalid.
Related
InStr(), RegExMatch(), StringGetPos, IfEqual, if var in/contains MatchList, if var between, if var is
type, Blocks, Else
Example
Haystack = abcdefghijklmnopqrs
Needle = abc
IfInString, Haystack, %Needle%
{
MsgBox, The string was found.
return
}
else
Sleep, 1
If var [not] in value1,value2,... If var [not] contains value1,value2,...
Checks whether a variable's contents match one of the items in a list.
if Var in MatchList
if Var not in MatchList
if Var contains MatchList
if Var not contains MatchList
Parameters
Var
The name of the variable whose contents will be checked. For the "in"
operator, an exact match with one of the list items is required. For the
"contains" operator, a match occurs more easily: whenever Var contains one of
the list items as a substring.
MatchList
A comma-separated list of strings, each of which will be compared to the
contents of Var for a match. Any spaces or tabs around the delimiting
commas are significant, meaning that they are part of the match string. For
example, if MatchList is set to ABC , XYZ then Var must contain either ABC
with a trailing space or XYZ with a leading space to cause a match.
Two consecutive commas results in a single literal comma. For example, the
following would produce a single literal comma at the end of string1: If Var In
string1,,,string2. Similarly, the following list contains only a single item with a
literal comma inside it: If Var In single,,item. To include a blank item in the
list, make the first character a comma as in this example: If Var In
Printed Documentation
470
,string1,string2 (when using the "contains" operator, a blank item will always
result in a match since the empty string is found in all strings).
Because the items in MatchList are not treated as individual parameters, the
list can be contained entirely within a variable. In fact, all or part of it must be
contained in a variable if its length exceeds 16383 since that is the maximum
length of any script line. For example, MatchList might consist of
%List1%,%List2%,%List3% -- where each of the sublists contains a large list
of match phrases.
Any single item in the list that is longer than 16384 characters will have those
extra characters treated as a new list item. Thus, it is usually best to avoid
including such items.
Remarks
The comparison is always done alphabetically, not numerically. For example, the string "11" would not
match the list item "11.0".
The "contains" operator is the same as using IfInString/IfNotInString except that multiple search
strings are supported (any one of which will cause a match).
"StringCaseSense On" can be used to make the comparison case sensitive.
If MatchList is long, it can be broken up into several shorter lines by means of a continuation section,
which might improve readability and maintainability.
The operators "between", "is", "in", and "contains" are not supported in expressions.
Related
if var between, IfEqual/Greater/Less, IfInString, StringCaseSense, Blocks, Else
Examples
if var in exe,bat,com
MsgBox The file extension is an executable type.

if var in 1,2,3,5,7,11 ; Avoid spaces in list.
MsgBox %var% is a small prime number.

if var contains 1,3 ; Note that it compares the values as strings, not numbers.
MsgBox Var contains the digit 1 or 3 (Var could be 1, 3, 10, 21, 23, etc.)

if var in %MyItemList%
MsgBox %var% is in the list.

InputBox, UserInput, Enter YES or NO
if UserInput not in yes,no
MsgBox Your input is not valid.

WinGetTitle, active_title, A
String Management
471
if active_title contains Address List.txt,Customer List.txt
MsgBox One of the desired windows is active.
if active_title not contains metapad,Notepad
MsgBox But the file is not open in either Metapad or Notepad.
If var is [not] type
Checks whether a variable's contents are numeric, uppercase, etc.
if var is type
if var is not type
Parameters
var The variable name.
type See the remarks below.
Remarks
Supported Types:
integer
True if var is non-empty and contains a purely numeric string (decimal or
hexadecimal) without a decimal point. Leading and trailing spaces and tabs are
allowed. The string may start with a plus or minus sign.
float
True if var is non-empty and contains a floating point number, that is, a purely
numeric string containing a decimal point. Leading and trailing spaces and tabs
are allowed. The string may start with a plus sign, minus sign, or decimal
point.
number
True if var contains an integer or floating point number (each of which is
described above).
digit
True if var is empty or contains only digits, which consist of the characters 0
through 9. Other characters such as the following are not allowed: spaces,
tabs, plus signs, minus signs, decimal points, hexadecimal digits, and the 0x
prefix.
xdigit
Hexadecimal digit: Same as digit except the characters A through F (uppercase
or lowercase) are also allowed. In v1.0.44.09+, a prefix of 0x is tolerated if
present.
alpha
True if var is empty or contains only alphabetic characters. False if there are
any digits, spaces, tabs, punctuation, or other non-alphabetic characters
anywhere in the string. For example, if var contains a space followed by a
letter, it is not considered to be alpha.
upper
True if var is empty or contains only uppercase characters. False if there are
any digits, spaces, tabs, punctuation, or other non-uppercase characters
anywhere in the string.
lower
True if var is empty or contains only lowercase characters. False if there are
any digits, spaces, tabs, punctuation, or other non-lowercase characters
anywhere in the string.
alnum Same as alpha except that characters 0 through 9 are also allowed.
space
True if var is empty or contains only whitespace, which consists of the
following characters: space (%A_Space%), tab (%A_Tab% or `t), linefeed
(`n), return (`r), vertical tab (`v), and formfeed (`f).
Printed Documentation
472
time
True if var contains a valid date-time stamp, which can be all or just the
leading part of the YYYYMMDDHH24MISS format. For example, a 4-digit string
such as 2004 is considered valid. Use StringLen to determine whether
additional time components are present.
Years less than 1601 are not considered valid because the operating system
generally does not support them. The maximum year considered valid is 9999.
The word DATE may be used as a substitute for the word TIME, with the same
result.
Note: The operators "between", "is", "in", and "contains" are not supported in expressions.
Related
%A_YYYY%, SetFormat, FileGetTime, IfEqual, if var in/contains MatchList, if var between, StringLen,
IfInString, StringUpper, EnvAdd, Blocks, Else
Example
if var is float
MsgBox, %var% is a floating point number.
else if var is integer
MsgBox, %var% is an integer.
if var is time
MsgBox, %var% is also a valid date-time.
Loop (parse a string)
Retrieves substrings (fields) from a string, one at a time.
Loop, Parse, InputVar [, Delimiters, OmitChars]
Parameters
Parse
This parameter must be the word PARSE, and unlike other loop types, it must
not be a variable reference that resolves to the word PARSE.
InputVar
The name of the variable whose contents will be analyzed. Do not enclose the
name in percent signs unless you want the contents of the variable to be used
as the name.
Delimiters
If this parameter is blank or omitted, each character of InputVar will be treated
as a separate substring.
If this parameter is CSV, InputVar will be parsed in standard comma separated
value format. Here is an example of a CSV line produced by MS Excel: "first
field",SecondField,"the word ""special"" is quoted literally",,"last field, has
literal comma"
Otherwise, Delimiters contains one or more characters (case sensitive), each
of which is used to determine where the boundaries between substrings occur
in InputVar.
Delimiter characters are not considered to be part of the substrings
themselves. In addition, if there is nothing between a pair of delimiters within
String Management
473
InputVar, the corresponding substring will be empty.
For example: `, (an escaped comma) would divide the string based on every
occurrence of a comma. Similarly, %A_Tab%%A_Space% would start a new
substring every time a space or tab is encountered in InputVar.
To use a string as a delimiter rather than a character, first use StringReplace
to replace all occurrences of the string with a single character that is never
used literally in the text, e.g. one of these special characters: .
Consider this example, which uses the string <br> as a delimiter:
StringReplace, NewHTML, HTMLString, <br>, , All ; Replace each
<br> with a cent symbol.
Loop, parse, NewHTML, ; Parse the string based on the cent symbol.
{
..
}
OmitChars
An optional list of characters (case sensitive) to exclude from the beginning
and end of each substring. For example, if OmitChars is
%A_Space%%A_Tab%, spaces and tabs will be removed from the beginning
and end (but not the middle) of every retrieved substring.
If Delimiters is blank, OmitChars indicates which characters should be excluded
from consideration (the loop will not see them).
Unlike the last parameter of most other commands, commas in OmitChars
must be escaped (`,).
Remarks
A string parsing loop is useful when you want to operate on each field contained in a string, one at a
time. Parsing loops use less memory than StringSplit (since StringSplit creates a permanent array)
and in most cases they are easier to use.
The built-in variable A_LoopField exists within any parsing loop. It contains the contents of the
current substring (field) from InputVar. If an inner parsing loop is enclosed by an outer parsing loop,
the innermost loop's field will take precedence.
There is no restriction on the size of InputVar or its fields. In addition, if InputVar's contents change
during the execution of the loop, the loop will not "see" the changes because it is operating on a
temporary copy of the original contents.
To arrange the fields in a different order prior to parsing, use the Sort command.
See Loop for information about Blocks, Break, Continue, and the A_Index variable (which exists in
every type of loop).
Related
StringSplit, file-reading loop, Loop, Break, Continue, Blocks, Sort, FileSetAttrib, FileSetTime
Examples
; Example #1:
Colors = red,green,blue
Loop, parse, Colors, `,
{
Printed Documentation
474
MsgBox, Color number %A_Index% is %A_LoopField%.
}

; Example #2: Read the lines inside a variable, one by one (similar to a file-reading loop).
; A file can be loaded into a variable via FileRead:
Loop, parse, FileContents, `n, `r ; Specifying `n prior to `r allows both Windows and Unix files to be
parsed.
{
MsgBox, 4, , Line number %A_Index% is %A_LoopField%.`n`nContinue?
IfMsgBox, No, break
}

; Example #3: This is the same as the example above except that it's for the clipboard.
; It's useful whenever the clipboard contains files, such as those copied from an open
; Explorer window (the program automatically converts such files to their file names):
Loop, parse, clipboard, `n, `r
{
MsgBox, 4, , File number %A_Index% is %A_LoopField%.`n`nContinue?
IfMsgBox, No, break
}

; Example #4: Parse a comma separated value (CSV) file:
Loop, read, C:\Database Export.csv
{
LineNumber = %A_Index%
Loop, parse, A_LoopReadLine, CSV
{
MsgBox, 4, , Field %LineNumber%-%A_Index% is:`n%A_LoopField%`n`nContinue?
IfMsgBox, No
return
}
}
RegExMatch() [v1.0.45+]
Determines whether a string contains a pattern (regular expression).
FoundPos := RegExMatch(Haystack, NeedleRegEx [, UnquotedOutputVar = "", StartingPos = 1])
Parameters
FoundPos RegExMatch() returns the position of the leftmost occurrence of
String Management
475
NeedleRegEx in the string Haystack. Position 1 is the first character.
Zero is returned if the pattern is not found. If an error occurs (such as a
syntax error inside NeedleRegEx), an empty string is returned and
ErrorLevel is set to one of the values below instead of 0.
Haystack The string whose content is searched.
NeedleRegEx
The pattern to search for, which is a Perl-compatible regular expression
(PCRE). The pattern's options (if any) must be included at the beginning
of the string followed by an close-parenthesis. For example, the pattern
"i)abc.*123" would turn on the case-insensitive option and search for
"abc", followed by zero or more occurrences of any character, followed
by "123". If there are no options, the ")" is optional; for example,
")abc" is equivalent to "abc".
UnquotedOutputVar
Default mode: OutputVar is the unquoted name of a variable in which
to store the part of Haystack that matched the entire pattern. If the
pattern is not found (that is, if the function returns 0), this variable and
all array elements below are made blank.
If any capturing subpatterns are present inside NeedleRegEx, their
matches are stored in an array whose base name is OutputVar. For
example, if the variable's name is Match, the substring that matches the
first subpattern would be stored in Match1, the second would be stored
in Match2, and so on. The exception to this is named subpatterns: they
are stored by name instead of number. For example, the substring that
matches the named subpattern (?P<Year>\d{4}) would be stored in
MatchYear. If a particular subpattern does not match anything (or if the
function returns zero), the corresponding variable is made blank.
Position-and-length mode: If a capital P is present in the RegEx's
options -- such as "P)abc.*123" -- the length of the entire-pattern
match is stored in OutputVar (or 0 if no match). If any capturing
subpatterns are present, their positions and lengths are stored in two
arrays: OutputVarPos and OutputVarLen. For example, if the variable's
base name is Match, the one-based position of the first subpattern's
match would be stored in MatchPos1, and its length in MatchLen1. Zero
is stored in both if the pattern was not matched or the function returns
0. The exception to this is named subpatterns: they are stored by name
instead of number (e.g. MatchPosYear and MatchLenYear).
Within a function, to create an array that is global instead of local,
declare the base name of the array (e.g. Match) as a global variable
prior to using it. The converse is true for assume-global functions.
StartingPos
If StartingPos is omitted, it defaults to 1 (the beginning of Haystack).
Otherwise, specify 2 to start at the second character, 3 to start at the
third, and so on. If StartingPos is beyond the length of Haystack, the
search starts at the empty string that lies at the end of Haystack (which
typically results in no match).
If StartingPos is less than 1, it is considered to be an offset from the
end of Haystack. For example, 0 starts at the last character and -1
starts at the next-to-last character. If StartingPos tries to go beyond the
left side of Haystack, all of Haystack is searched.
Regardless of the value of StartingPos, the return value is always
relative to the first character of Haystack. For example, the position of
"abc" in "123abc789" is always 4.
Printed Documentation
476
ErrorLevel
ErrorLevel is set to one of the following:
1. 0, which means that no error occurred.
2. A string in the following form: Compile error N at offset M: description. In that string, N is the
PCRE error number, M is the position of the offending character inside the regular expression,
and description is the text describing the error.
3. A negative number, which means an error occurred during the execution of the regular
expression. Although such errors are rare, the ones most likely to occur are recursion too deep
(-21) and reached match limit (-8). If these happen, try to redesign the pattern to be more
restrictive, such as using ? in place of * wherever feasible.
Options (case sensitive)
At the very beginning of a regular expression, specify zero or more of the following options followed
by an close-parenthesis. For example, the pattern "im)abc" would search for abc with the case-
insensitive and multiline options (the parenthesis can be omitted when there are no options). Although
this syntax breaks from tradition, it requires no special delimiters (such as forward-slash), and thus
there is no need to escape such delimiters inside the pattern. In addition, performance is improved
because the options are easier to parse.
i
Case-insensitive matching, which treats the letters A through Z as identical to their
lowercase counterparts.
m
Multiline. Views haystack as a collection of individual lines (if it contains newlines) rather
than as a single monolithic line. Specifically, it changes the following:
1) Circumflex (^) matches immediately after all internal newlines -- as well as at the
start of haystack where it always matches (but ^ does not match after a newline that
ends the string).
2) Dollar-sign ($) matches before any newlines in the string (as well as at the very end
where it always matches).
For example, the pattern "m)^abc$" matches the haystack "def`r`nabc" only because
the "m" option is present.
The "D" option is ignored when "m" is present.
s
DotAll. This causes a period (.) to match all characters including newlines (normally, it
does not match newlines). However, when the newline character is at its default of CRLF
(`r`n), two dots are required to match it (not one). Regardless of this option, a negative
class such as [^a] always matches newlines.
x
Ignores whitespace characters in the pattern except when escaped or inside a character
class. It also ignores characters between a non-escaped # outside a character class and
the next newline character, inclusive. This makes it possible to include comments inside
complicated patterns. However, this applies only to data characters; whitespace may
never appear within special character sequences such as (?(, which begins a conditional
subpattern.
A
Forces the pattern to be anchored; that is, it can match only at the start of haystack.
Under most conditions, this is equivalent to explicitly anchoring the pattern by means
such as "^".
D
Forces dollar-sign ($) to match at the very end of haystack, even if haystack's last item
is a newline. Without this option, $ instead matches right before the final newline (if
there is one). Note: This option is ignored when the "m" option is present.
J
Allows duplicate named subpatterns. This can be useful for patterns in which only one of
a collection of identically-named subpatterns can match. Note: If more than one instance
String Management
477
of a particular name matches something, only the leftmost one is stored. Also, variable
names are not case-sensitive.
U
Ungreedy. Makes the quantifiers *+?{} consume only those characters absolutely
necessary to form a match, leaving the remaining ones available for the next part of the
pattern. When the "U" option is not in effect, an individual quantifier can be made non-
greedy by following it with a question mark. Conversely, when "U" is in effect, the
question mark makes an individual quantifier greedy.
X
PCRE_EXTRA. Enables PCRE features that are incompatible with Perl. Currently, the only
such feature is that any backslash in a pattern that is followed by a letter that has no
special meaning causes the match to fail and ErrorLevel to be set accordingly. This
option helps reserve unused backslash sequences for future use. Without this option, a
backslash followed by a letter with no special meaning is treated as a literal (e.g. \g and
g are both recognized as a literal g). Regardless of this option, non-alphabetic backslash
sequences that have no special meaning are always treated as literals (e.g. \/ and / are
both recognized as forward-slash).
P
Position mode. This causes RegExMatch() to yield the position and length of each match
rather than the matching substring. For details, see OutputVar above.
S
Study the pattern to try improve its performance. This is useful when a particular pattern
(especially a complex one) will be executed many times. If PCRE finds a way to improve
performance, that discovery is stored alongside the pattern in the cache for use by
subsequent executions of the same pattern.
`n
Switch from the default newline character (`r`n) to a solitary linefeed (`n), which is the
standard on UNIX systems.
`r
Switch from the default newline character (`r`n) to a solitary carriage return (`r). The
option `r`n is also recognized: it means CRLF (which is the default).
Note: Spaces and tabs may optionally be used to separate each option from the next.
Performance
To search for a simple substring inside a larger string, use InStr() because it is faster than
RegExMatch().
To improve performance, the 100 most recently used regular expressions are kept cached in memory
(in compiled form).
The study option (S) can sometimes improve the performance of a regular expression that is used
many times (such as in a loop).
Remarks
Most characters like abc123 can be used literally inside a regular expression. However, the characters
\.*?+[{|()^$ must be preceded by a backslash to be seen as literal. For example, \. is a literal
period and \\ is a literal backslash.
Within a regular expression, special characters such as tab and newline can be escaped with either an
accent (`) or a backslash (\). For example, `t is the same as \t.
A subpattern may be given a name such as the word "Year" in (?P<Year>\d{4}). Such names consist
of up to 32 alphanumeric characters and underscores. Although named subpatterns are also available
by their numbers during the RegEx operation itself (e.g. backreferences), they are stored in the output
array only by name (not by number). For example, if "Year" is the first subpattern, OutputVarYear
would be set to the matching substring, but OutputVar1 would not be changed at all (it would retain
its previous value, if any). However, if an unnamed subpattern occurs after "Year", it would be stored
in OutputVar2, not OutputVar1.
To learn the basics of regular expressions (or refresh your memory of pattern syntax), see the RegEx
Quick Reference.
Printed Documentation
478
AutoHotkey's regular expressions are implemented using Perl-compatible Regular Expressions (PCRE)
from www.pcre.org.
Related
RegExReplace(), InStr(), IfInString, StringGetPos, SetTitleMatchMode RegEx
Common sources of text data: FileRead, UrlDownloadToFile, Clipboard, GUI Edit controls
Examples
FoundPos := RegExMatch("xxxabc123xyz", "abc.*xyz") ; Returns 4, which is the position where the
match was found.
FoundPos := RegExMatch("abc123123", "123$") ; Returns 7 because the $ requires the match to be
at the end.
FoundPos := RegExMatch("abc123", "i)^ABC") ; Returns 1 because a match was achieved via the
case-insensitive option.
FoundPos := RegExMatch("abcXYZ123", "abc(.*)123", SubPat) ; Returns 1 and stores "XYZ" in
SubPat1.
FoundPos := RegExMatch("abc123abc456", "abc\d+", "", 2) ; Returns 7 instead of 1 due to
StartingPos 2 vs. 1.

; For general RegEx examples, see the RegEx Quick Reference.
RegExReplace() [v1.0.45+]
Replaces occurrences of a pattern (regular expression) inside a string.
NewStr := RegExReplace(Haystack, NeedleRegEx [, Replacement = "", OutputVarCount = "", Limit = -
1, StartingPos = 1])
Parameters
NewStr
RegExReplace() returns a version of Haystack whose contents have been
replaced by the operation. If no replacements are needed, Haystack is
returned unaltered. If an error occurs (such as a syntax error inside
NeedleRegEx), an empty string is returned and ErrorLevel is set to one of
the values below instead of 0.
Haystack The string whose content is searched and replaced.
NeedleRegEx
The pattern to search for, which is a Perl-compatible regular expression
(PCRE). The pattern's options (if any) must be included at the beginning of
the string followed by an close-parenthesis. For example, the pattern
"i)abc.*123" would turn on the case-insensitive option and search for "abc",
followed by zero or more occurrences of any character, followed by "123".
If there are no options, the ")" is optional; for example, ")abc" is equivalent
to "abc".
Replacement
The string that will be substituted for each match, which is plain text (not a
regular expression). It may include backreferences in the form $0 through
$9 (where $0 is the substring that matched the entire pattern). For
backreferences above 9 (and optionally those below 9 as well), use ${10},
${11}, and so on. For named subpatterns, use ${SubpatternName}. To
specify a literal $, use $$ (this is the only character that needs such special
treatment; backslashes are never needed to escape anything).
String Management
479
To convert the case of a subpattern, follow the $ with one of the following
characters: U or u (uppercase), L or l (lowercase), T or t (title case, in
which the first letter of each word is capitalized but all others are made
lowercase). For example, both $U1 and $U{1} would transcribe an
uppercase version of the first subpattern.
Nonexistent backreferences and those that did not match anything in
Haystack -- such as one of the subpatterns in (abc)|(xyz) -- are transcribed
as empty strings.
OutputVarCount
The unquoted name of a variable in which to store the number of
replacements that occurred (0 if none).
Limit
If Limit is omitted, it defaults to -1, which replaces all occurrences of the
pattern found in Haystack. Otherwise, specify the maximum number of
replacements to allow. The part of Haystack to the right of the last
replacement will be left unchanged.
StartingPos
If StartingPos is omitted, it defaults to 1 (the beginning of Haystack).
Otherwise, specify 2 to start at the second character, 3 to start at the third,
and so on. If StartingPos is beyond the length of Haystack, the search
starts at the empty string that lies at the end of Haystack (which typically
results in no replacements).
If StartingPos is less than 1, it is considered to be an offset from the end of
Haystack. For example, 0 starts at the last character and -1 starts at the
next-to-last character. If StartingPos tries to go beyond the left side of
Haystack, all of Haystack is searched.
Regardless of the value of StartingPos, the return value is always a
complete copy of Haystack -- the only difference is that more of its left side
might be unaltered compared to what would have happened with a
StartingPos of 1.
ErrorLevel
ErrorLevel is set to one of the following:
1. 0, which means that no error occurred.
2. A string in the following form: Compile error N at offset M: description. In that string, N is the
PCRE error number, M is the position of the offending character inside the regular expression,
and description is the text describing the error.
3. A negative number, which means an error occurred during the execution of the regular
expression. Although such errors are rare, the ones most likely to occur are recursion too deep
(-21) and reached match limit (-8). If these happen, try to redesign the pattern to be more
restrictive, such as using ? in place of * wherever feasible.
Options
See Options for modifiers such as "i)abc", which turns off case-sensitivity in the pattern "abc".
Performance
To replace simple substrings, use StringReplace because it is faster than RegExReplace().
If you know what the maximum number of replacements will be, specifying that for the Limit
parameter improves performance because the search can be stopped early (this might also reduce the
memory load on the system during the operation). For example, if you know there can be only one
match near the beginning of a large string, specify a limit of 1.
Printed Documentation
480
To improve performance, the 100 most recently used regular expressions are kept cached in memory
(in compiled form).
The study option (S) can sometimes improve the performance of a regular expression that is used
many times (such as in a loop).
Remarks
Most characters like abc123 can be used literally inside a regular expression. However, the characters
\.*?+[{|()^$ must be preceded by a backslash to be seen as literal. For example, \. is a literal
period and \\ is a literal backslash.
Within a regular expression, special characters such as tab and newline can be escaped with either an
accent (`) or a backslash (\). For example, `t is the same as \t.
To learn the basics of regular expressions (or refresh your memory of pattern syntax), see the RegEx
Quick Reference.
Related
RegExMatch(), StringReplace, InStr()
Common sources of text data: FileRead, UrlDownloadToFile, Clipboard, GUI Edit controls
Examples
NewStr := RegExReplace("abc123123", "123$", "xyz") ; Returns "abc123xyz" because the $ allows a
match only at the end.
NewStr := RegExReplace("abc123", "i)^ABC") ; Returns "123" because a match was achieved via the
case-insensitive option.
NewStr := RegExReplace("abcXYZ123", "abc(.*)123", "aaa$1zzz") ; Returns "aaaXYZzzz" by means
of the $1 backreference.
NewStr := RegExReplace("abc123abc456", "abc\d+", "", ReplacementCount) ; Returns "" and stores
2 in ReplacementCount.

; For general RegEx examples, see the RegEx Quick Reference.
SetEnv (Var = Value)
Assigns the specified value to a variable.
SetEnv, Var, Value
Var = Value
Parameters
Var The name of the variable in which to store Value.
Value
The string or number to store. If the string is long, it can be broken up into
several shorter lines by means of a continuation section, which might improve
readability and maintainability.
Remarks
By default, any spaces or tabs at the beginning and end of Value are omitted from Var. To prevent
this, use AutoTrim Off beforehand. However, `t (the tab character) is unconditionally omitted. To
prevent this, use %A_Tab% in place of `t.
String Management
481
The name "SetEnv" is misleading and is used only for backward compatibility with AutoIt v2. Unlike
AutoIt v2, AutoHotkey does not store its variables in the environment. This is because performance
would be worse and also because the OS limits such variables to 32K. Use EnvSet instead of SetEnv to
write to an environment variable.
The memory occupied by a large variable can be freed by setting it equal to nothing, e.g. var =
It is possible to create an array with this command and any others that accept an OutputVar. This is
done by making OuputVar contain a reference to another variable, e.g. array%i% = 123. See Arrays
for more details.
Related
AutoTrim, EnvSet, EnvAdd, EnvSub, EnvMult, EnvDiv, If, Arrays
Example
Var1 = This is a string.
Color2 = 450
Color3 = %Var1%
Array%i% = %A_TICKCOUNT%
SetFormat
Sets the format of integers and floating point numbers generated by math operations.
SetFormat, NumberType, Format
Parameters
NumberType Must be either INTEGER or FLOAT.
Format
For NumberType INTEGER, this parameter must be H or HEX for hexadecimal,
or D for decimal. Hexadecimal numbers all start with the prefix 0x (e.g. 0xFF).
For NumberType FLOAT, this parameter is TotalWidth.DecimalPlaces (e.g. 0.6).
TotalWidth is typically 0 to indicate that number should not have any blank or
zero padding. If a higher value is used, numbers will be padded with spaces or
zeroes (see below) to make them that wide.
DecimalPlaces is the number of decimal places to display (rounding will occur).
If blank or zero, neither a decimal portion nor a decimal point will be
displayed, that is, the number will be stored as an integer rather than a
floating point number.
Padding: If TotalWidth is high enough to cause padding, spaces will be added
on the left side; that is, each number will be right-justified. To use left-
justification instead, precede TotalWidth with a minus sign. To pad with zeroes
instead of spaces, precede TotalWidth with a zero.
Remarks
If this command is not used in a script, integers default to decimal format, and floating point numbers
default to TotalWidth.DecimalPlaces = 0.6. Every newly launched thread (such as a hotkey, custom
menu item, or timed subroutine) starts off fresh with the default setting for this command. That
default may be changed by using this command in the auto-execute section (top part of the script).
Printed Documentation
482
You can determine whether a variable contains a numeric value by using "if var is
number/integer/float"
A variable containing an integer can be forced into the current integer format (hex or decimal) by
adding zero to it; for example: Var += 0. Similarly, a variable containing a floating point number (or
an integer, for that matter) can be forced into the current floating point format by adding 0.0 to it; for
example: Var += 0.0. However, to convert a floating point number into an integer, it is easier to use
Round(), Ceil(), or Floor().
The built-in variable A_FormatInteger contains the current integer format (H or D). A_FormatFloat
contains the current floating point format.
To pad an integer with zeros or spaces without having to use floating point math on it, follow this
example:
Var := " " . Var ; The quotes contain 10 spaces. To pad with zeros, substitute zeros
for the spaces.
StringRight, Var, Var, 10 ; This pads the number in Var with enough spaces to make its total
width 10 characters.
Floating Point Format
Since AutoHotkey stores all variables as strings, the stored precision of floating point numbers is
determined by DecimalPlaces. In other words, once a variable is rounded off, the extra precision is lost
and cannot be reclaimed without redoing the calculation using a higher value of DecimalPlaces.
Any leading or trailing spaces (i.e. padding) in a floating point value will be lost if that value is
explicitly assigned to another variable. Use the colon-equals operator (:=) or AutoTrim to prevent this.
For the current float format to take effect in a math operation such as addition, at least one of the
inputs must contain a decimal point.
A variable containing an integer can be "converted" into a floating point number by adding 0.0 to it,
e.g. Var += 0.0. However, if the current float format specifies no DecimalPlaces, use this instead:
if Var is integer
Var = %Var%.0
Hexadecimal Format
Hexadecimal numbers all start with the prefix 0x (e.g. 0xA9). They can be used anywhere a numerical
value is expected. For example, Sleep 0xFF is equivalent to Sleep 255 regardless of the current
integer format set by SetFormat.
To convert an integer from decimal to hexadecimal, use this example (the converse can be used to
convert in the opposite direction):
SetFormat, integer, hex
VariableContainingAnInteger += 0
SetFormat, integer, d
Related
Expression assignment (:=), EnvAdd, EnvSub, EnvMult, EnvDiv, AutoTrim, if var is type
Example
Var = 11.333333
SetFormat, float, 6.2
Var -= 1 ; Sets Var to be 10.33 with one leading space because the total width is 6.
SetFormat, float, 0.2
String Management
483
Var += 1 ; Sets Var to be 11.33 with no leading spaces.

SetFormat, float, 06.0
Var += 0 ; Sets Var to be 000011

SetFormat, integer, hex
Var += 0 ; Sets Var to be 0xb
SetFormat, integer, d
Sort
Arranges a variable's contents in alphabetical, numerical, or random order (optionally removing
duplicates).
Sort, VarName [, Options]
Parameters
VarName The name of the variable whose contents will be sorted.
Options See list below.
Options
A string of zero or more of the following letters (in any order, with optional spaces in between):
C: Case sensitive sort (ignored if the N option is also present). If both C and CL are omitted, the
uppercase letters A-Z are considered identical to their lowercase counterparts for the purpose of the
sort.
CL [v1.0.43.03+]: Case insensitive sort based on the current user's locale. For example, most English
and Western European locales treat the letters A-Z and ANSI letters like and as identical to their
lowercase counterparts. This method also uses a "word sort", which treats hyphens and apostrophes
in such a way that words like "coop" and "co-op" stay together. Depending on the content of the items
being sorted, the performance will be 1 to 8 times worse than the default method of insensitivity.
Dx: Specifies x as the delimiter character, which determines where each item in VarName begins and
ends. If this option is not present, x defaults to linefeed (`n), which correctly sorts VarName if its lines
end in either LF (`n) or CR+LF (`r`n).
N: Numeric sort: Each item is assumed to be a number rather than a string (for example, if this option
is not present, the string 233 is considered to be less than the string 40 due to alphabetical ordering).
Both decimal and hexadecimal strings (e.g. 0xF1) are considered to be numeric. Strings that do not
start with a number are considered to be zero for the purpose of the sort. Numbers are treated as 64-
bit floating point values so that the decimal portion of each number (if any) is taken into account.
Pn: Sorts items based on character position n (do not use hexadecimal for n). If this option is not
present, n defaults to 1, which is the position of the first character. The sort compares each string to
the others starting at its nth character. If n is greater than the length of any string, that string is
considered to be blank for the purpose of the sort. When used with option N (numeric sort), the
string's character position is used, which is not necessarily the same as the number's digit position.
R: Sorts in reverse order (alphabetically or numerically depending on the other options).
Random: Sorts in random order. This option causes all other options except D, Z, and U to be
ignored. Examples:
Sort, MyVar, Random
Sort, MyVar, Random Z D|
Printed Documentation
484
U: Removes duplicate items from the list so that every item is unique. ErrorLevel is set to the number
of items removed (0 if none). If the C option is in effect, the case of items must match for them to be
considered identical. If the N option is in effect, an item such as 2 would be considered a duplicate of
2.0. If either the Pn or \ (backslash) option is in effect, the entire item must be a duplicate, not just
the substring that is used for sorting. If the Random option is in effect, duplicates are removed only if
they appear adjacent to each other as a result of the sort. For example, when "A|B|A" is sorted
randomly, the result could contain either one or two A's.
Z: To understand this option, consider a variable that contains RED`nGREEN`nBLUE`n. If the Z option
is not present, the last linefeed (`n) is considered to be part of the last item, and thus there are only 3
items. But by specifying Z, the last `n (if present) will be considered to delimit a blank item at the end
of the list, and thus there are 4 items (the last being blank).
\: Sorts items based on the substring that follows the last backslash in each. If an item has no
backslash, the entire item is used as the substring. This option is useful for sorting bare filenames (i.e.
excluding their paths), such as the example below, in which the AAA.txt line is sorted above the
BBB.txt line because their directories are ignored for the purpose of the sort:
C:\BBB\AAA.txt
C:\AAA\BBB.txt
Note: Options N and P are ignored when the backslash option is present.
Remarks
This command is typically used to sort a variable that contains a list of lines, with each line ending in a
linefeed character (`n). One way to get a list of lines into a variable is to load an entire file via
FileRead.
If VarName is Clipboard and the clipboard contains files (such as those copied from an open Explorer
window), those files will be replaced with a sorted list of their filenames. In other words, after the
operation, the clipboard will no longer contain the files themselves.
ErrorLevel is changed by this command only when the U option is in effect.
The maximum capacity of a variable can be increased via #MaxMem.
If a large variable was sorted and later its contents are no longer needed, you can free its memory by
making it blank, e.g. MyVar =
Related
FileRead, file-reading loop, parsing loop, StringSplit, clipboard, #MaxMem
Example
MyVar = 5,3,7,9,1,13,999,-4
Sort MyVar, N D, ; Sort numerically, use comma as delimiter.
MsgBox %MyVar% ; The result is -4,1,3,5,7,9,13,999

; This example makes Win+C a hotkey to copy files from an open
; Explorer window and put their sorted filenames onto the clipboard:
#c::
Clipboard = ; Must be blank for detection to work.
Send ^c
ClipWait 2
if ErrorLevel
return
String Management
485
Sort Clipboard
MsgBox Ready to be pasted:`n%Clipboard%
return
StringCaseSense
Determines whether string comparisons are case sensitive (default is "not case sensitive").
StringCaseSense, On|Off|Locale
Parameters
On|Off|Locale
On: String comparisons are case sensitive. This setting also makes the
expression equal sign operator (=) and the case-insensitive mode of InStr()
use the locale method described below.
Off: The letters A-Z are considered identical to their lowercase counterparts.
This is the starting default for all scripts due to backward compatibility and
performance (Locale is 1 to 8 times slower than Off depending on the nature
of the strings being compared).
Locale [v1.0.43.03+]: String comparisons are case insensitive according to
the rules of the current user's locale. For example, most English and Western
European locales treat the letters A-Z and ANSI letters like and as
identical to their lowercase counterparts. This setting applies to:
Expression equal sign operator (=).
InStr(): When its CaseSensitive parameter is omitted or false, it uses the locale method of insensitivity instead of
the "A-Z only" method.
All other commands, functions, and operators that are documented as obeying StringCaseSense.
Remarks
The command affects the behavior of IfEqual (and its family), IF (expression), IfInString,
StringReplace and StringGetPos, and others that are explicitly documented as obeying
StringCaseSense.
The built-in variable A_StringCaseSense contains the current setting (the word On, Off, or Locale).
Every newly launched thread (such as a hotkey, custom menu item, or timed subroutine) starts off
fresh with the default setting for this command. That default may be changed by using this command
in the auto-execute section (top part of the script).
Related
IfEqual, IfInString, if var between, StringReplace, StringGetPos
Example
StringCaseSense Locale
StringGetPos
Retrieves the position of the specified substring within a string.
StringGetPos, OutputVar, InputVar, SearchText [, L#|R#, Offset]
Position := InStr(Haystack, Needle [, CaseSensitive?, StartingPos]) ; See the InStr() function for
details.
Printed Documentation
486
Parameters
OutputVar
The name of the variable in which to store the retrieved position relative to the
first character of InputVar. Position 0 is the first character for StringGetPos and
position 1 is the first character for InStr().
InputVar
The name of the input variable, whose contents will be searched. Do not
enclose the name in percent signs unless you want the contents of the variable
to be used as the name.
SearchText
The string to search for. Matching is not case sensitive unless StringCaseSense
has been turned on.
L#|R#
This affects which occurrence will be found if SearchText occurs more than
once within InputVar. If this parameter is omitted, InputVar will be searched
starting from the left for the first match. If this parameter is 1 or the letter R,
the search will start looking at the right side of InputVar and will continue
leftward until the first match is found.
To find a match other than the first, specify the letter L or R followed by the
number of the occurrence. For example, to find the fourth occurrence from the
right, specify r4. Note: If the number is less than or equal to zero, no match
will be found.
Offset
The number of characters on the leftmost or rightmost side (depending on the
parameter above) to skip over. If omitted, the default is 0. For example, the
following would start searching at the tenth character from the left:
StringGetPos, OutputVar, InputVar, abc, , 9. This parameter can be an
expression.
ErrorLevel
ErrorLevel is set to 1 if the specified occurrence of SearchText could not be found within InputVar, or 0
otherwise.
Remarks
Unlike StringMid and InStr(), 0 is defined as the position of the first character for StringGetPos.
The retrieved position is always relative to the first character of InputVar, regardless of whether
L#|R# and/or Offset are specified. For example, if the string "abc" is found in 123abc789, its reported
position will always be 3 regardless of the method by which it was found.
If the specified occurrence of SearchText does not exist within InputVar, OutputVar will be set to -1
and ErrorLevel will be set to 1.
Use SplitPath to more easily parse a file path into its directory, filename, and extension.
The built-in variables %A_Space% and %A_Tab% contain a single space and a single tab character,
respectively. They are useful when searching for spaces and tabs alone or at the beginning or end of
SearchText.
Related
InStr(), RegExMatch(), IfInString, if var in/contains MatchList, StringReplace, SplitPath, StringLeft,
StringRight, StringMid, StringTrimLeft, StringTrimRight, StringLen, StringLower, StringUpper, if var is
type

Examples
Haystack = abcdefghijklmnopqrs
String Management
487
Needle = def
StringGetPos, pos, Haystack, %Needle%
if pos >= 0
MsgBox, The string was found at position %pos%.

; Example #2:
; Divides up the full path name of a file into components.
; Note that it would be much easier to use StringSplit or a
; parsing loop to do this, so the below is just for illustration.
FileSelectFile, file, , , Pick a filename in a deeply nested folder:
if file <>
{
StringLen, pos_prev, file
pos_prev += 1 ; Adjust to be the position after the last char.
Loop
{
; Search from the right for the Nth occurrence:
StringGetPos, pos, file, \, R%A_Index%
if ErrorLevel
break
length := pos_prev - pos - 1
pos_prev := pos
pos += 2 ; Adjust for use with StringMid.
StringMid, path_component, file, %pos%, %length%
MsgBox Path component #%a_index% (from the right) is:`n%path_component%
}
}
StringLeft / StringRight
Retrieves a number of characters from the left or right-hand side of a string.
StringLeft, OutputVar, InputVar, Count
StringRight, OutputVar, InputVar, Count
Parameters
OutputVar
The name of the variable in which to store the substring extracted from
InputVar.
InputVar
The name of the variable whose contents will be extracted from. Do not
enclose the name in percent signs unless you want the contents of the variable
to be used as the name.
Count The number of characters to extract, which can be an expression. If Count is
Printed Documentation
488
less than or equal to zero, OutputVar will be made empty (blank). If Count
exceeds the length of InputVar, OutputVar will be set equal to the entirety of
InputVar.
Remarks
For this and all other commands, OutputVar is allowed to be the same variable as an InputVar.
Related
IfInString, StringGetPos, StringMid, StringTrimLeft, StringTrimRight, StringLen, StringLower,
StringUpper, StringReplace
Example
String = This is a test.
StringLeft, OutputVar, String, 4 ; Stores the string "This" in OutputVar.
StringRight, OutputVar, String, 5 ; Stores the string "test." in OutputVar.
StringLen
Retrieves the count of how many characters are in a string.
StringLen, OutputVar, InputVar
Length := StrLen(String)
Parameters
OutputVar The name of the variable in which to store the length.
InputVar
The name of the variable whose contents will be measured. Do not enclose the
name in percent signs unless you want the contents of the variable to be used
as the name.
Remarks
If InputVar is a variable to which ClipboardAll was previously assigned, StringLen will report its total
size.
Related
StrLen(), IfInString, StringGetPos, StringMid, StringTrimLeft, StringTrimRight, StringLeft, StringRight,
StringLower, StringUpper, StringReplace
Example
StringLen, length, InputVar
MsgBox, The length of InputVar is %length%.

MsgBox % "The length of MyVar is " . StrLen(MyVar)
StringLower / StringUpper
Converts a string to lowercase or uppercase.
StringLower, OutputVar, InputVar [, T]
StringUpper, OutputVar, InputVar [, T]
String Management
489
Parameters
OutputVar The name of the variable in which to store newly converted string.
InputVar
The name of the variable whose contents will be read from. Do not enclose the
name in percent signs unless you want the contents of the variable to be used
as the name.
T
If this parameter is the letter T, the string will be converted to title case. For
example, "GONE with the WIND" would become "Gone With The Wind".
Remarks
To detect whether a character or string is entirely uppercase or lowercase, use "if var is [not]
upper/lower".
For this and all other commands, OutputVar is allowed to be the same variable as an InputVar.
Related
IfInString, StringGetPos, StringMid, StringTrimLeft, StringTrimRight, StringLeft, StringRight,
StringLen, StringReplace
Example
StringUpper, String1, String1 ; i.e. output can be the same as input.
StringLower, String2, String2
StringMid
Retrieves one or more characters from the specified position in a string.
StringMid, OutputVar, InputVar, StartChar [, Count , L]
Parameters
OutputVar
The name of the variable in which to store the substring extracted from
InputVar.
InputVar
The name of the variable from whose contents the substring will be extracted.
Do not enclose the name in percent signs unless you want the contents of the
variable to be used as the name.
StartChar
The position of the first character to be extracted, which can be an expression.
Unlike StringGetPos, 1 is the first character. If StartChar is less than 1, it will
be assumed to be 1. If StartChar is beyond the end of the string, OutputVar is
made empty (blank).
Count
In v1.0.43.10+, this parameter may be omitted or left blank, which is the
same as specifying an integer large enough to retrieve all characters from the
string.
Otherwise, specify the number of characters to extract, which can be an
expression. If Count is less than or equal to zero, OutputVar will be made
empty (blank). If Count exceeds the length of InputVar measured from
StartChar, OutputVar will be set equal to the entirety of InputVar starting at
StartChar.
L
The letter L can be used to extract characters that lie to the left of StartChar
rather than to the right. In the following example, OutputVar will be set to
Printed Documentation
490
Red:
InputVar = The Red Fox
StringMid, OutputVar, InputVar, 7, 3, L
If the L option is present and StartChar is less than 1, OutputVar will be made
blank. If StartChar is beyond the length of InputVar, only those characters
within reach of Count will be extracted. For example, the below will set
OutputVar to Fox:
InputVar = The Red Fox
StringMid, OutputVar, InputVar, 14, 6, L
Remarks
For this and all other commands, OutputVar is allowed to be the same variable as InputVar.
Related
IfInString, StringGetPos, StringLeft, StringRight, StringTrimLeft, StringTrimRight, StringLen,
StringLower, StringUpper, StringReplace
Example
Source = Hello this is a test.
StringMid, the_word_this, Source, 7, 4
StringReplace
Replaces the specified substring with a new string.
StringReplace, OutputVar, InputVar, SearchText [, ReplaceText, ReplaceAll?]
Parameters
OutputVar
The name of the variable in which to store the result of the replacement
process.
InputVar
The name of the variable whose contents will be read from. Do not enclose the
name in percent signs unless you want the contents of the variable to be used
as the name.
SearchText
The string to search for. Matching is not case sensitive unless StringCaseSense
has been turned on.
ReplaceText
SearchText will be replaced with this text. If omitted or blank, SearchText will
be replaced with blank (empty). In other words, it will be omitted from
OutputVar.
ReplaceAll?
If omitted, only the first occurrence of SearchText will be replaced. But if this
parameter is 1, A, or All, all occurrences will be replaced.
Specify the word UseErrorLevel to store in ErrorLevel the number of
occurrences replaced (0 if none). UseErrorLevel implies "All".
ErrorLevel
When the last parameter is UseErrorLevel, ErrorLevel is given the number occurrences replaced (0 if
none). Otherwise, ErrorLevel is set to 1 if SearchText is not found within InputVar, or 0 if it is found.
Remarks
String Management
491
For this and all other commands, OutputVar is allowed to be the same variable as an InputVar.
The built-in variables %A_Space% and %A_Tab% contain a single space and a single tab character,
respectively. They are useful when searching for spaces and tabs alone or at the beginning or end of
SearchText.
In v1.0.45, the AllSlow option became obsolete due to improvements to performance and memory
utilization. Although it may still be specified, it has no effect.
Related
RegExReplace(), IfInString, StringLeft, StringRight, StringMid, StringTrimLeft, StringTrimRight,
StringLen, StringLower, StringUpper, StringGetPos, if var is type
Examples
; Remove all CR+LF's from the clipboard contents:
StringReplace, clipboard, clipboard, `r`n, , All

; Replace all spaces with pluses:
StringReplace, NewStr, OldStr, %A_SPACE%, +, All

; Remove all blank lines from the text in a variable:
Loop
{
StringReplace, MyString, MyString, `r`n`r`n, `r`n, UseErrorLevel
if ErrorLevel = 0 ; No more replacements needed.
break
}
StringSplit
Separates a string into an array of substrings using the specified delimiters.
StringSplit, OutputArray, InputVar [, Delimiters, OmitChars]
Parameters
OutputArray
The name of the array in which to store each substring extracted from
InputVar. For example, if MyArray is specified, the command will put the
number of substrings produced (0 if none) into MyArray0, the first substring
into MyArray1, the second into MyArray2, and so on.
Within a function, to create an array that is global instead of local, declare
MyArray0 as a global variable inside the function (the converse is true for
assume-global functions).
InputVar
The name of the variable whose contents will be analyzed. Do not enclose the
name in percent signs unless you want the contents of the variable to be used
as the name. NOTE: InputVar must not be one of the variables in OutputArray.
Delimiters
If this parameter is blank or omitted, each character of InputVar will be treated
Printed Documentation
492
as a separate substring.
Otherwise, Delimiters contains one or more characters (case sensitive), each
of which is used to determine where the boundaries between substrings occur
in InputVar. Since the delimiter characters are not considered to be part of the
substrings themselves, they are never copied into OutputArray. Also, if there is
nothing between a pair of delimiters within InputVar, the corresponding array
element will be blank.
For example: `, (an escaped comma) would divide the string based on every
occurrence of a comma. Similarly, %A_Tab%%A_Space% would create a new
array element every time a space or tab is encountered in InputVar.
To use a string as a delimiter rather than a character, first use StringReplace
to replace all occurrences of the string with a single character that is never
used literally in the text. Consider this example, which uses the string <br> as
a delimiter:
StringReplace, NewHTML, HTMLString, <br>, ``, All ; Replace each
<br> with an accent.
StringSplit, MyArray, NewHTML, `` ; Split the string based on the
accent character.
OmitChars
An optional list of characters (case sensitive) to exclude from the beginning
and end of each array element. For example, if OmitChars is
%A_Space%%A_Tab%, spaces and tabs will be removed from the beginning
and end (but not the middle) of every element.
If Delimiters is blank, OmitChars indicates which characters should be excluded
from the array.
Unlike the last parameter of most other commands, commas in OmitChars
must be escaped (`,).
Remarks
If the array elements already exist, the command will change the values of only the first N elements,
where N is the number of substrings present in InputVar. Any elements beyond N that existed
beforehand will be unchanged. Therefore, it is safest to use the zero element (MyArray0) to determine
how many items were actually produced by the command.
Whitespace characters such as spaces and tabs will be preserved unless those characters are
themselves delimiters. Tabs and spaces can be trimmed from both ends of any variable by assigning it
to itself while AutoTrim is off (the default). For example: MyArray1 = %MyArray1%
To split a string that is in standard CSV (comma separated value) format, use a parsing loop since it
has built-in CSV handling.
To arrange the fields in a different order prior to splitting them, use the Sort command.
If you do not need the substrings to be permanently stored in memory, consider using a parsing loop -
- especially if InputVar is very large, in which case a large amount of memory would be saved. For
example:
Colors = red,green,blue
Loop, parse, Colors, `,
MsgBox Color number %A_Index% is %A_LoopField%.
Related
String Management
493
Parsing loop, Arrays, Sort, SplitPath, IfInString, StringGetPos, StringMid, StringTrimLeft,
StringTrimRight, StringLen, StringLower, StringUpper, StringReplace
Examples
TestString = This is a test.
StringSplit, word_array, TestString, %A_Space%, . ; Omits periods.
MsgBox, The 4th word is %word_array4%.

Colors = red,green,blue
StringSplit, ColorArray, Colors, `,
Loop, %ColorArray0%
{
this_color := ColorArray%a_index%
MsgBox, Color number %a_index% is %this_color%.
}
StringTrimLeft / StringTrimRight
Removes a number of characters from the left or right-hand side of a string.
StringTrimLeft, OutputVar, InputVar, Count
StringTrimRight, OutputVar, InputVar, Count
Parameters
OutputVar The name of the variable in which to store the shortened version of InputVar.
InputVar
The name of the variable whose contents will be read from. Do not enclose the
name in percent signs unless you want the contents of the variable to be used
as the name.
Count
The number of characters to remove, which can be an expression. If Count is
less than or equal to zero, OutputVar will be set equal to the entirety of
InputVar. If Count exceeds the length of InputVar, OutputVar will be made
empty (blank).
Remarks
For this and all other commands, OutputVar is allowed to be the same variable as an InputVar.
Related
IfInString, StringGetPos, StringMid, StringLeft, StringRight, StringLen, StringLower, StringUpper,
StringReplace
Example
String = This is a test.
StringTrimLeft, OutputVar, String, 5 ; Stores the string "is a test." in OutputVar.
StringTrimRight, OutputVar, String, 6 ; Stores the string "This is a" in OutputVar.

495
Window Management
Controls
Control
Makes a variety of changes to a control.
Control, Cmd [, Value, Control, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
Cmd, Value See list below.
Control
Can be either ClassNN (the classname and instance number of the control) or
the name/text of the control, both of which can be determined via Window
Spy. When using name/text, the matching behavior is determined by
SetTitleMatchMode. If this parameter is blank, the target window's topmost
control will be used.
To operate upon a control's HWND (window handle), leave the Control
parameter blank and specify ahk_id %ControlHwnd% for the WinTitle
parameter (this also works on hidden controls even when
DetectHiddenWindows is Off) . The HWND of a control is typically retrieved via
ControlGet Hwnd, MouseGetPos, or DllCall.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the next 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
next 3 parameters are omitted, the active window will be used. To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a process identifier (PID), specify ahk_pid %VarContainingPID%. To use a
window group, specify ahk_group GroupName. To use a window's unique ID
number, specify ahk_id %VarContainingID%. The search can be narrowed by
specifying multiple criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
Cmd, Value
The Cmd and Value parameters are dependent upon each other and their usage is described below.
Check: Turns on (checks) a radio button or checkbox.
Uncheck: Turns off a radio button or checkbox.
Enable: Enables a control if it was previously disabled.
Disable: Disables or "grays out" a control.
Show: Shows a control if it was previously hidden.
Hide: Hides a control. If you additionally want to prevent a control's shortcut key (underlined letter)
from working, disable the control via "Control Disable".
Style,N or ExStyle,N: Changes the style or extended style of a control, respectively. If the first
character of N is a plus or minus sign, the style(s) in N are added or removed, respectively. If the first
character is a caret (^), the style(s) in N are each toggled to the opposite state. If the first character
Printed Documentation
496
is a digit, the control's style is overwritten completely; that is, it becomes N. ErrorLevel is set to 1 if
the target window/control is not found or the style is not allowed to be applied (which happens more
often on Windows 9x).
Certain style changes require that the entire window be redrawn using WinSet Redraw. Also, the
styles table lists some of the style numbers. For example:
Control, Style, ^0x800000, Edit1, WinTitle ; Set the WS_BORDER style to its opposite state.
ShowDropDown: Drops a ComboBox so that its choices become visible.
HideDropDown: Reverses the above.
TabLeft [, Count]: Moves left by one or more tabs in a SysTabControl32. Count is assumed to be 1 if
omitted or blank. To instead select a tab directly by number, replace the number 5 below with one
less than the tab number you wish to select. In other words, 0 selects the first tab, 1 selects the
second, and so on:
SendMessage, 0x130C, 5,, SysTabControl321, WinTitle ; 0x130C is TCM_SETCURSEL.
TabRight [, Count]: Moves right by one or more tabs in a SysTabControl32. Count is assumed to be
1 if omitted or blank.
Add, String: Adds String as a new entry at the bottom of a ListBox or ComboBox (v1.0.42+ also
supports TListBox, TComboBox, and possibly others).
Delete, N: Deletes the Nth entry from a ListBox or ComboBox (v1.0.42+ also supports TListBox,
TComboBox, and possibly others). N should be 1 for the first entry, 2 for the second, etc.
Choose, N: Sets the selection in a ListBox or ComboBox to be the Nth entry (v1.0.42+ also supports
TListBox, TComboBox, and possibly others). N should be 1 for the first entry, 2 for the second, etc. To
select or deselect all items in a multi-select listbox, follow these examples:
PostMessage, 0x185, 1, -1, ListBox1, WinTitle ; Select all listbox items. 0x185 is LB_SETSEL.
ChooseString, String: Sets the selection (choice) in a ListBox or ComboBox to be the entry whose
leading part matches String (v1.0.42+ also supports TListBox, TComboBox, and possibly others). The
search is not case sensitive. For example, if a ListBox/ComboBox contains the item "UNIX Text",
specifying the word unix (lowercase) would be enough to select it.
EditPaste, String: Pastes String at the caret/insert position in an Edit control.
ErrorLevel
ErrorLevel is set to 1 of there was a problem or 0 otherwise.
Remarks
To improve reliability, a delay is done automatically after every use of this command (except for Style
and ExStyle). That delay can be changed via SetControlDelay.
To discover the name of the control that the mouse is currently hovering over, use MouseGetPos.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
SetControlDelay, ControlGet, GuiControl, ControlGetText, ControlSetText, ControlMove,
ControlGetPos, ControlClick, ControlFocus, ControlSend, WinSet
Example
Control, HideDropDown, , ComboBox1, Some Window Title
ControlClick
Sends a mouse button or mouse wheel event to a control.
Window Management
497
ControlClick [, Control-or-Pos, WinTitle, WinText, WhichButton, ClickCount, Options, ExcludeTitle,
ExcludeText]
Parameters
Control-or-
Pos
If this parameter is blank, the target window's topmost control will be clicked
(or the target window itself if it has no controls). Otherwise, one of the two
modes below will be used.
Mode 1 (Position): Specify the X and Y coordinates relative to the target
window's upper left corner. The X coordinate must precede the Y coordinate
and there must be at least one space or tab between them. For example: X55
Y33. If there is a control at the specified coordinates, it will be sent the click-
event at those exact coordinates. If there is no control, the target window itself
will be sent the event (which might have no effect depending on the nature of
the window). Note: In this mode, the X and Y option letters of the Options
parameter are ignored.
Mode 2 (ClassNN or Text): Specify either ClassNN (the classname and instance
number of the control) or the name/text of the control, both of which can be
determined via Window Spy. When using name/text, the matching behavior is
determined by SetTitleMatchMode.
By default, mode 2 takes precedence over mode 1. For example, in the
unlikely event that there is a control whose text or ClassNN has the format
"Xnnn Ynnn", it would be acted upon by Mode 2. To override this and use
mode 1 unconditionally, specify the word Pos in Options as in the following
example: ControlClick, x255 y152, WinTitle,,,, Pos
To operate upon a control's HWND (window handle), leave this parameter
blank and specify ahk_id %ControlHwnd% for the WinTitle parameter (this also
works on hidden controls even when DetectHiddenWindows is Off) . The HWND
of a control is typically retrieved via ControlGet Hwnd, MouseGetPos, or DllCall.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the other 3 window parameters
are omitted, the Last Found Window will be used. If this is the letter A and the
other 3 window parameters are omitted, the active window will be used. To
use a window class, specify ahk_class ExactClassName (shown by Window
Spy). To use a process identifier (PID), specify ahk_pid %VarContainingPID%.
To use a window group, specify ahk_group GroupName. To use a window's
unique ID number, specify ahk_id %VarContainingID%. The search can be
narrowed by specifying multiple criteria. For example: My File.txt ahk_class
Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
WhichButton
The button to click: LEFT, RIGHT, MIDDLE (or just the first letter of each of
these). If omitted or blank, the LEFT button will be used.
WheelUp (or WU) and WheelDown (or WD) are also supported on Windows
NT/2000/XP or later. In this case, ClickCount is the number of notches to turn
the wheel.
X1 (XButton1, the 4th mouse button) and X2 (XButton2, the 5th mouse
button) are also supported on Windows 2000/XP or later.
ClickCount
The number of clicks to send, which can be an expression. If omitted or blank,
1 click is sent.
Printed Documentation
498
Options
A series of zero or more of the following option letters. For example: d x50 y25
NA [v1.0.45+]: Avoids activating the window, which might also improve
reliability in cases where the user is physically moving the mouse during the
ControlClick. However, this mode might not work properly for all types of
windows and controls.
D: Press the mouse button down but do not release it (i.e. generate a down-
event). If both the D and U options are absent, a complete click (down and up)
will be sent.
U: Release the mouse button (i.e. generate an up-event). This option should
not be present if the D option is already present (and vice versa).
Pos: Specify the word Pos anywhere in Options to unconditionally use the X/Y
positioning mode as described in the Control-or-Pos parameter above.
Xn: Specify for n the X position to click at, relative to the control's upper left
corner. If unspecified, the click will occur at the horizontal-center of the
control.
Yn: Specify for n the Y position to click at, relative to the control's upper left
corner. If unspecified, the click will occur at the vertical-center of the control.
Use decimal (not hexadecimal) numbers for the X and Y options.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Reliability
To improve reliability -- especially during times when the user is physically moving the mouse during
the ControlClick -- try one or both of the following:
1) Use SetControlDelay -1 prior to ControlClick. This avoids holding the mouse button down during the
click, which in turn reduces interference from the user's physical movement of the mouse.
2) Specify the string NA anywhere in the sixth parameter (Options). This avoids activating the
window, and also avoids merging the script's input processing with that of the target window (which
as a side-effect prevents physical movement of the mouse from interfering, but usually only when the
target window is not active).
However, these modes might not work for all types of windows and controls.
Remarks
Not all applications obey a ClickCount higher than 1 for turning the mouse wheel. For those
applications, use a Loop to turn the wheel more than one notch as in this example, which turns it 5
notches:
Loop, 5
ControlClick, Control, WinTitle, WinText, WheelUp
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
SetControlDelay, Control, ControlGet, ControlGetText, ControlMove, ControlGetPos, ControlFocus,
ControlSetText, ControlSend, Click
Examples
ControlClick, OK, Some Window Title ; Clicks the OK button
Window Management
499
ControlClick, x55 y77, WinTitle ; Clicks at a set of coordinates. Note the lack of a comma between X
and Y.
ControlFocus
Sets input focus to a given control on a window.
ControlFocus [, Control, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
Control
Can be either ClassNN (the classname and instance number of the control) or
the name/text of the control, both of which can be determined via Window
Spy. When using name/text, the matching behavior is determined by
SetTitleMatchMode. If this parameter is blank or omitted, the target window's
topmost control will be used.
To operate upon a control's HWND (window handle), leave the Control
parameter blank and specify ahk_id %ControlHwnd% for the WinTitle
parameter (this also works on hidden controls even when
DetectHiddenWindows is Off) . The HWND of a control is typically retrieved via
ControlGet Hwnd, MouseGetPos, or DllCall.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the next 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
next 3 parameters are omitted, the active window will be used. To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a process identifier (PID), specify ahk_pid %VarContainingPID%. To use a
window group, specify ahk_group GroupName. To use a window's unique ID
number, specify ahk_id %VarContainingID%. The search can be narrowed by
specifying multiple criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
To be effective, the control's window generally must not be minimized or hidden.
To improve reliability, a delay is done automatically after every use of this command. That delay can
be changed via SetControlDelay.
To discover the name of the control that the mouse is currently hovering over, use MouseGetPos.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
SetControlDelay, ControlGetFocus, Control, ControlGet, ControlMove, ControlGetPos, ControlClick,
ControlGetText, ControlSetText, ControlSend
Example
ControlFocus, OK, Some Window Title ; Set focus to the OK button
Printed Documentation
500
ControlGet
Retrieves various types of information about a control.
ControlGet, OutputVar, Cmd [, Value, Control, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
OutputVar The name of the variable in which to store the result of Cmd.
Cmd, Value See list below.
Control
Can be either ClassNN (the classname and instance number of the control) or
the name/text of the control, both of which can be determined via Window
Spy. When using name/text, the matching behavior is determined by
SetTitleMatchMode. If this parameter is blank, the target window's topmost
control will be used.
To operate upon a control's HWND (window handle), leave the Control
parameter blank and specify ahk_id %ControlHwnd% for the WinTitle
parameter (this also works on hidden controls even when
DetectHiddenWindows is Off) . The HWND of a control is typically retrieved via
ControlGet Hwnd, MouseGetPos, or DllCall.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the next 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
next 3 parameters are omitted, the active window will be used. To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a process identifier (PID), specify ahk_pid %VarContainingPID%. To use a
window group, specify ahk_group GroupName. To use a window's unique ID
number, specify ahk_id %VarContainingID%. The search can be narrowed by
specifying multiple criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
Cmd, Value
The Cmd and Value parameters are dependent upon each other and their usage is described below.
List: Retrieves a list of items from a ListView, ListBox, ComboBox, or DropDownList.
ListView [v1.0.37+]: The most common example of a ListView is Explorer's list of files and folders (the
desktop is also a ListView). The syntax for ListView retrieval is:
ControlGet, OutputVar, List, Options, SysListView321, WinTitle, WinText
If the Options parameter is blank or omitted, all the text in the control is retrieved. Each row except
the last will end with a linefeed character (`n). Within each row, each field (column) except the last
will end with a tab character (`t).
Specify for Options zero or more of the following words, each separated from the next with a space or
tab:
Selected: Retrieves only the selected (highlighted) rows rather than all rows. If none, OutputVar is
made blank.
Focused: Retrieves only the focused row. If none, OutputVar is made blank.
Col4: Retrieves only the fourth column (field) rather than all columns (replace 4 with a number of your
choice).
Count: Retrieves a single number that is the total number of rows in the control.
Window Management
501
Count Selected: Retrieves the number of selected (highlighted) rows.
Count Focused: Retrieves the row number (position) of the focused row (0 if none).
Count Col: Retrieves the number of columns in the control (or -1 if the count cannot be determined).
NOTE: Some applications store their ListView text privately, which prevents their text from being
retrieved. In these cases, ErrorLevel will usually be set to 0 (indicating success) but all the retrieved
fields will be empty. Also note that ListView text retrieval is not restricted by #MaxMem.
Upon success, ErrorLevel is set to 0. Upon failure, it is set to 1 and OutputVar is made blank. Failure
occurs when: 1) the target window or control does not exist; 2) the target control is not of type
SysListView32; 3) the process owning the ListView could not be opened, perhaps due to a lack of user
permissions or because it is locked; 4) the ColN option specifies a nonexistent column.
To extract the individual rows and fields out of a ListView, use a parsing loop as in this example:
ControlGet, List, List, Selected, SysListView321, WinTitle
Loop, Parse, List, `n ; Rows are delimited by linefeeds (`n).
{
RowNumber := A_Index
Loop, Parse, A_LoopField, %A_Tab% ; Fields (columns) in each row are delimited by tabs
(A_Tab).
MsgBox Row #%RowNumber% Col #%A_Index% is %A_LoopField%.
}
On a related note, the columns in a ListView can be resized via SendMessage as shown in this
example:
SendMessage, 4126, 0, 80, SysListView321, WinTitle ; 4126 is the message
LVM_SETCOLUMNWIDTH.
; In the above, 0 indicates the first column (specify 1 for the second, 2 for the third, etc.)
Also, 80 is the new width.
; Replace 80 with -1 to autosize the column. Replace it with -2 to do the same but also take
into account the header text width.
ListBox, ComboBox, DropDownList: All the text is retrieved from the control (that is, the ListView
options above such as Count and Selected are not supported). v1.0.42+ also supports TListBox,
TComboBox, and possibly others.
Each row except the last will be terminated by a linefeed character (`n). To access the items
individually, use a parsing loop as in this example:
ControlGet, List, List,, ComboBox1, WinTitle
Loop, Parse, List, `n
MsgBox Item number %A_Index% is %A_LoopField%.
Checked: Sets OutputVar to be 1 if the checkbox or radio button is checked or 0 if not.
Enabled: Sets OutputVar to be 1 if Control is enabled, or 0 if disabled.
Visible: Sets OutputVar to be 1 if Control is visible, or 0 if hidden.
Tab: Sets OutputVar to the tab number of a SysTabControl32 control. The first tab is 1, the second is
2, etc. To instead discover how many tabs (pages) exist in a tab control, follow this example:
SendMessage, 0x1304,,, SysTabControl321, WinTitle ; 0x1304 is TCM_GETITEMCOUNT.
TabCount = %ErrorLevel%
FindString, String: Sets OutputVar to the entry number of a ListBox or ComboBox that is an exact
match for String (v1.0.42+ also supports TListBox, TComboBox, and possibly others). The first entry
Printed Documentation
502
in the control is 1, the second 2, and so on. If no match is found, OutputVar is made blank and
ErrorLevel is set to 1.
Choice: Sets OutputVar to be the name of the currently selected entry in a ListBox or ComboBox
(v1.0.42+ also supports TListBox, TComboBox, and possibly others). To instead retrieve the position
of the selected item, follow this example (use only one of the first two lines):
SendMessage, 0x188, 0, 0, ListBox1, WinTitle ; 0x188 is LB_GETCURSEL (for a ListBox).
SendMessage, 0x147, 0, 0, ComboBox1, WinTitle ; 0x147 is CB_GETCURSEL (for a
DropDownList or ComboBox).
ChoicePos = %ErrorLevel% ; It will be -1 if there is no item selected.
ChoicePos += 1 ; Convert from 0-based to 1-based, i.e. so that the first item is known as 1,
not 0.
LineCount: Sets OutputVar to be the number of lines in an Edit control. All Edit controls have at least
1 line, even if the control is empty.
CurrentLine: Sets OutputVar to be the line number in an Edit control where the caret (insert point)
resides. The first line is 1. If there is text selected in the control, OutputVar is set to the line number
where the selection begins.
CurrentCol: Sets OutputVar to be the column number in an Edit control where the caret (text
insertion point) resides. The first column is 1. If there is text selected in the control, OutputVar is set
to the column number where the selection begins.
Line, N: Sets OutputVar to be the text of line N in an Edit control. Line 1 is the first line. Depending
on the nature of the control, OutputVar might end in a carriage return (`r) or a carriage return +
linefeed (`r`n).
Selected: Sets OutputVar to be the selected text in an Edit control. If no text is selected, OutputVar
will be made blank and ErrorLevel will be set to 0 (i.e. no error). Certain types of controls, such as
RichEdit20A, might not produce the correct text in some cases (e.g. Metapad).
Style: Retrieves an 8-digit hexadecimal number representing the style of the control. See the styles
table for a listing of some styles.
ExStyle: Retrieves an 8-digit hexadecimal number representing the extended style of the control.
Hwnd [v1.0.43.06+]: Retrieves the window handle (HWND) of the specified control. For example:
ControlGet, OutputVar, Hwnd,, Edit1, WinTitle. A control's HWND is often used with PostMessage,
SendMessage, and DllCall. On a related note, a control's HWND can also be retrieved via
MouseGetPos. Finally, a control's HWND can be used directly as an ahk_id WinTitle (this also works on
hidden controls even when DetectHiddenWindows is Off).
ErrorLevel
Upon success, ErrorLevel is set to 0. If a problem occurred -- such as a nonexistent window or control
-- ErrorLevel is set to 1 and OutputVar is made blank.
Remarks
Unlike commands that change a control, ControlGet does not have an automatic delay; that is,
SetControlDelay does not affect it.
To discover the name of the control that the mouse is currently hovering over, use MouseGetPos. To
get a list of controls in a window, use WinGet ControlList.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
Control, GuiControlGet, ControlMove, ControlGetText, ControlSetText, ControlGetPos, ControlClick,
ControlFocus, ControlSend, WinGet
Example
Window Management
503
ControlGet, OutputVar, Line, 1, Edit1, Some Window Title

ControlGet, WhichTab, Tab, , SysTabControl321, Some Window Title
if ErrorLevel
MsgBox There was a problem.
else
MsgBox Tab #%WhichTab% is active.
ControlGetFocus
Retrieves which control of the target window has input focus, if any.
ControlGetFocus, OutputVar [, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
OutputVar
The name of the variable in which to store the identifier of the control, which
consists of its classname followed by its sequence number within its parent
window, e.g. Button12.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the next 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
next 3 parameters are omitted, the active window will be used. To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a process identifier (PID), specify ahk_pid %VarContainingPID%. To use a
window group, specify ahk_group GroupName. To use a window's unique ID
number, specify ahk_id %VarContainingID%. The search can be narrowed by
specifying multiple criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
ErrorLevel
ErrorLevel is set to 0 if the control with input focus was successfully retrieved. Otherwise (e.g. the
target window doesn't exist or none of its controls have input focus) it will be set to 1.
Remarks
The control retrieved by this command is the one that has keyboard focus, that is, the one that would
receive keystrokes if the user were to type any.
The target window must be active to have a focused control. If the window is not active, OutputVar
will be made blank.
If ControlFocus is executed repeatedly at a high frequency (i.e. every 500 ms or faster), it will
probably disrupt the user's ability to double-click. There is no known workaround.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
ControlFocus, ControlMove, ControlClick, ControlGetText, ControlSetText, ControlSend
Example
Printed Documentation
504
ControlGetFocus, OutputVar, Untitled - Notepad
if ErrorLevel
MsgBox, The target window doesn't exist or none of its controls has input focus.
else
MsgBox, Control with focus = %OutputVar%
ControlGetPos
Retrieves the position and size of a control.
ControlGetPos [, X, Y, Width, Height, Control, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
X, Y
The names of the variables in which to store the X and Y coordinates (in
pixels) of Control's upper left corner. These coordinates are relative to the
target window's upper-left corner and thus are the same as those used by
ControlMove.
If either X or Y is omitted, the corresponding values will not be stored.
Width/Height
The names of the variables in which to store Control's width and height (in
pixels). If omitted, the corresponding values will not be stored.
Control
Can be either ClassNN (the classname and instance number of the control) or
the name/text of the control, both of which can be determined via Window
Spy. When using name/text, the matching behavior is determined by
SetTitleMatchMode. If this parameter is blank, the target window's topmost
control will be used.
To operate upon a control's HWND (window handle), leave the Control
parameter blank and specify ahk_id %ControlHwnd% for the WinTitle
parameter (this also works on hidden controls even when
DetectHiddenWindows is Off) . The HWND of a control is typically retrieved via
ControlGet Hwnd, MouseGetPos, or DllCall.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the next 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
next 3 parameters are omitted, the active window will be used. To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a process identifier (PID), specify ahk_pid %VarContainingPID%. To use a
window group, specify ahk_group GroupName. To use a window's unique ID
number, specify ahk_id %VarContainingID%. The search can be narrowed by
specifying multiple criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
Remarks
If no matching window or control is found, the output variables will be made blank.
Unlike commands that change a control, ControlGetPos does not have an automatic delay
(SetControlDelay does not affect it).
Window Management
505
To discover the name of the control that the mouse is currently hovering over, use MouseGetPos. To
retrieve a list of all controls in a window, use WinGet.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
ControlMove, WinGetPos, Control, ControlGet, ControlGetText, ControlSetText, ControlClick,
ControlFocus, ControlSend
Example
; This working example will continuously update and display the
; name and position of the control currently under the mouse cursor:
Loop
{
Sleep, 100
MouseGetPos, , , WhichWindow, WhichControl
ControlGetPos, x, y, w, h, %WhichControl%, ahk_id %WhichWindow%
ToolTip, %WhichControl%`nX%X%`tY%Y%`nW%W%`t%H%
}
ControlGetText
Retrieves text from a control.
ControlGetText, OutputVar [, Control, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
OutputVar
The name of the variable in which to store the retrieved text.
Control
Can be either ClassNN (the classname and instance number of the control) or
the name/text of the control, both of which can be determined via Window
Spy. When using name/text, the matching behavior is determined by
SetTitleMatchMode. If this parameter is blank or omitted, the target window's
topmost control will be used.
To operate upon a control's HWND (window handle), leave the Control
parameter blank and specify ahk_id %ControlHwnd% for the WinTitle
parameter (this also works on hidden controls even when
DetectHiddenWindows is Off) . The HWND of a control is typically retrieved via
ControlGet Hwnd, MouseGetPos, or DllCall.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the next 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
next 3 parameters are omitted, the active window will be used. To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a process identifier (PID), specify ahk_pid %VarContainingPID%. To use a
window group, specify ahk_group GroupName. To use a window's unique ID
number, specify ahk_id %VarContainingID%. The search can be narrowed by
specifying multiple criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
Printed Documentation
506
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
Note: To retrieve text from a ListView, ListBox, or ComboBox, use ControlGet List instead.
If the retrieved text appears to be truncated (incomplete), try using VarSetCapacity(OutputVar, 55)
prior to ControlGetText [replace 55 with a size that is considerably longer than the truncated text].
This is necessary because some applications do not respond properly to the WM_GETTEXTLENGTH
message, which causes AutoHotkey to make the output variable too small to fit all the text.
The amount of text retrieved is limited to a variable's maximum capacity (which can be changed via
the #MaxMem directive). As a result, this command might use a large amount RAM if the target
control (e.g. an editor with a large document open) contains a large quantity of text. However, a
variable's memory can be freed after use by assigning it to nothing, i.e. OutputVar =
Text retrieved from most control types uses carriage return and linefeed (`r`n) rather than a solitary
linefeed (`n) to mark the end of each line.
It is not necessary to do SetTitleMatchMode Slow because ControlGetText always retrieves the text
using the slow method (since it works on a broader range of control types).
To retrieve a list of all controls in a window, use WinGet ControlList.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
ControlSetText, WinGetText, Control, ControlGet, ControlMove, ControlFocus, ControlClick,
ControlSend, #MaxMem
Example
ControlGetText, OutputVar, Edit1, Untitled -
ControlMove
Moves or resizes a control.
ControlMove, Control, X, Y, Width, Height [, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
Control
Can be either ClassNN (the classname and instance number of the control) or
the name/text of the control, both of which can be determined via Window
Spy. When using name/text, the matching behavior is determined by
SetTitleMatchMode. If this parameter is blank, the target window's topmost
control will be used.
To operate upon a control's HWND (window handle), leave the Control
parameter blank and specify ahk_id %ControlHwnd% for the WinTitle
parameter (this also works on hidden controls even when
DetectHiddenWindows is Off) . The HWND of a control is typically retrieved via
ControlGet Hwnd, MouseGetPos, or DllCall.
X, Y
The X and Y coordinates (in pixels) of the upper left corner of Control's new
location, which can be expressions. If either coordinate is blank, Control's
position in that dimension will not be changed. The coordinates are relative to
Window Management
507
the upper-left corner of the Control's parent window; ControlGetPos or Window
Spy can be used to determine them.
Width,
Height
The new width and height of Control (in pixels), which can be expressions. If
either parameter is blank or omitted, Control's size in that dimension will not
be changed.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the next 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
next 3 parameters are omitted, the active window will be used. To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a process identifier (PID), specify ahk_pid %VarContainingPID%. To use a
window group, specify ahk_group GroupName. To use a window's unique ID
number, specify ahk_id %VarContainingID%. The search can be narrowed by
specifying multiple criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
To improve reliability, a delay is done automatically after every use of this command. That delay can
be changed via SetControlDelay.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
ControlGetPos, WinMove, SetControlDelay, Control, ControlGet, ControlGetText, ControlSetText,
ControlClick, ControlFocus, ControlSend
Example
SetTimer, ControlMoveTimer
InputBox, OutputVar, My Input Box
return

ControlMoveTimer:
IfWinNotExist, My Input Box
return
; Otherwise the above set the "last found" window for us:
SetTimer, ControlMoveTimer, off
WinActivate
ControlMove, OK, 10, , 200 ; Move the OK button to the left and increase its width.
return
Printed Documentation
508
ControlSend / ControlSendRaw
Sends simulated keystrokes to a window or control.
ControlSend [, Control, Keys, WinTitle, WinText, ExcludeTitle, ExcludeText]
ControlSendRaw: Same parameters as above.
Parameters
Control
Can be either ClassNN (the classname and instance number of the control) or
the name/text of the control, both of which can be determined via Window
Spy. When using name/text, the matching behavior is determined by
SetTitleMatchMode. If this parameter is blank or omitted, the target window's
topmost control will be used. If this parameter is ahk_parent, the keystrokes
will be sent directly to the control's parent window (see Automating Winamp
for an example).
To operate upon a control's HWND (window handle), leave the Control
parameter blank and specify ahk_id %ControlHwnd% for the WinTitle
parameter (this also works on hidden controls even when
DetectHiddenWindows is Off) . The HWND of a control is typically retrieved via
ControlGet Hwnd, MouseGetPos, or DllCall.
Keys
The sequence of keys to send (see the Send command for details). To send a
literal comma, escape it (`,). The rate at which characters are sent is
determined by SetKeyDelay.
Unlike the Send command, mouse clicks cannot be sent by ControlSend. Use
ControlClick for that.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the next 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
next 3 parameters are omitted, the active window will be used. To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a process identifier (PID), specify ahk_pid %VarContainingPID%. To use a
window group, specify ahk_group GroupName. To use a window's unique ID
number, specify ahk_id %VarContainingID%. The search can be narrowed by
specifying multiple criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
ControlSendRaw sends the keystrokes in the Keys parameter exactly as they appear rather than
translating {Enter} to an ENTER keystroke, ^c to Control-C, etc.
If the Control parameter is omitted, this command will attempt to send directly to the target window
by sending to its topmost control (which is often the correct one) or the window itself if there are no
controls. This is useful if a window does not appear to have any controls at all, or just for the
convenience of not having to worry about which control to send to.
By default, modifier keystrokes (Control, Alt, Shift, and Win) are sent as they normally would be by
the Send command. This allows command prompt and other console windows to properly detect
uppercase letters, control characters, etc. It may also improve reliability in other ways.
Window Management
509
However, in some cases these modifier events may interfere with the active window, especially if the
user is actively typing during a ControlSend or if the Alt key is being sent (since Alt activates the
active window's menu bar). This can be avoided by explicitly sending modifier up and down events as
in this example:
ControlSend, Edit1, {Alt down}f{Alt up}, Untitled - Notepad
The method above also allows the sending of modifier keystrokes (Control/Alt/Shift/Win) while the
workstation is locked (protected by logon prompt).
BlockInput should be avoided when using ControlSend against a console window such as command
prompt. This is because it might prevent capitalization and modifier keys such as Control from working
properly.
The value of SetKeyDelay determines the speed at which keys are sent. If the target window does not
receive the keystrokes reliably, try increasing the press duration via the second parameter of
SetKeyDelay as in these examples:
SetKeyDelay, 10, 10
SetKeyDelay, 0, 10
SetKeyDelay, -1, 0
If the target control is an Edit control (or something similar), the following are usually more reliable
and faster than ControlSend:
Control, EditPaste, This text will be inserted at the caret position., ControlName, WinTitle
ControlSetText, ControlName, This text will entirely replace any current text., WinTitle
ControlSend is generally not capable of manipulating a window's menu bar. To work around this, use
WinMenuSelectItem. If that is not possible due to the nature of the menu bar, you could try to
discover the message that corresponds to the desired menu item by following the SendMessage
Tutorial.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
SetKeyDelay, Control, ControlGet, ControlGetText, ControlMove, ControlGetPos, ControlClick,
ControlSetText, ControlFocus, Send, Automating Winamp
Examples
ControlSend, Edit1, This is a line of text in the notepad window., Untitled
SetTitleMatchMode, 2
ControlSend, , abc, cmd.exe ; Send directly to a command prompt window.
ControlSetText
Changes the text of a control.
ControlSetText [, Control, NewText, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
Control
Can be either ClassNN (the classname and instance number of the control) or
the name/text of the control, both of which can be determined via Window
Spy. When using name/text, the matching behavior is determined by
SetTitleMatchMode. If this parameter is blank, the target window's topmost
control will be used.
To operate upon a control's HWND (window handle), leave the Control
parameter blank and specify ahk_id %ControlHwnd% for the WinTitle
parameter (this also works on hidden controls even when
DetectHiddenWindows is Off) . The HWND of a control is typically retrieved via
ControlGet Hwnd, MouseGetPos, or DllCall.
Printed Documentation
510
NewText
The new text to set into the control. If blank or omitted, the control is made
blank.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the next 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
next 3 parameters are omitted, the active window will be used. To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a process identifier (PID), specify ahk_pid %VarContainingPID%. To use a
window group, specify ahk_group GroupName. To use a window's unique ID
number, specify ahk_id %VarContainingID%. The search can be narrowed by
specifying multiple criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
Most control types use carriage return and linefeed (`r`n) rather than a solitary linefeed (`n) to mark
the end of each line. To translate a block of text containing `n characters, follow this example:
StringReplace, MyVar, MyVar, `n, `r`n, All
To improve reliability, a delay is done automatically after every use of this command. That delay can
be changed via SetControlDelay.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
SetControlDelay, ControlGetText, ControlGet, Control, ControlMove, ControlGetPos, ControlClick,
ControlFocus, ControlSend
Example
ControlSetText, Edit1, New Text Here, Untitled -
Menu
Creates, deletes, modifies and displays menus and menu items. Changes the tray icon and its tooltip.
Controls whether the main window of a compiled script can be opened.
Menu, MenuName, Cmd [, P3, P4, P5]
Parameters
MenuName
It can be TRAY or the name of any custom menu. A custom menu is
automatically created the first time its name is used with the Add command.
For example: Menu, MyMenu, Add, Item1
Once created, a custom menu can be displayed with the Show command. It
can also be attached as a submenu to one or more other menus via the Add
command.
Cmd, P3,
P4, P5
These 4 parameters are dependent on each other. See list below for the
allowed combinations.
Window Management
511
Add or Change Items in a Menu
Add [, MenuItemName, Label-or-Submenu, Pn]: This is a multipurpose command that adds a
menu item, updates one with a new submenu or label, or converts one from a normal item into a
submenu (or vice versa). If MenuItemName does not yet exist, it will be added to the menu.
Otherwise, MenuItemName is updated with the newly specified Label-or-Submenu.
To add a menu separator line, omit all three parameters.
The label subroutine is run as a new thread when the user selects the menu item (similar to Gosub
and hotkey subroutines). If Label-or-Submenu is omitted, MenuItemName will be used as both the
label and the menu item's name.
To have MenuItemName become a submenu -- which is a menu item that opens a new menu when
selected -- specify for Label-or-Submenu a colon followed by the MenuName of an existing custom
menu. For example:
Menu, MySubmenu, add, Item1
Menu, tray, add, This Menu Item Is A Submenu, :MySubmenu
The final parameter may contain the letter P followed by the menu's thread priority, e.g. P1. If this
parameter is omitted when adding a menu item, the priority will be 0, which is the standard default. If
omitted when updating a menu item, the item's priority will not be changed. To change an existing
item's priority only, omit the Label-or-Submenu parameter. Use a decimal (not hexadecimal) number
as the priority.
Delete [, MenuItemName]: Deletes MenuItemName from the menu. Standard menu items such as
Exit (see below) cannot be individually deleted. If the default menu item is deleted, the effect will be
similar to having used the NoDefault option. If MenuItemName is omitted, the entire MenuName menu
will be deleted as will any menu items in other menus that use MenuName as a submenu.
DeleteAll: Deletes all custom menu items from the menu, leaving the menu empty unless it contains
the standard items (see below). Unlike a menu entirely deleted by the Delete command (see above),
an empty menu still exists and thus any other menus that use it as a submenu will retain those
submenus.
Rename, MenuItemName [, NewName]: Changes MenuItemName to NewName (if NewName is
blank, MenuItemName will be converted into a separator line). NewName must not be the same as
any existing custom menu item. The menu item's current target label or submenu is unchanged.
Check, MenuItemName: Adds a visible checkmark in the menu next to MenuItemName (if there
isn't one already).
Uncheck, MenuItemName: Removes the checkmark from MenuItemName if there is one.
ToggleCheck, MenuItemName: Adds a checkmark if there wasn't one; otherwise, removes it.
Enable, MenuItemName: Allows the user to once again select MenuItemName if was previously
disabled (grayed).
Disable, MenuItemName: Changes MenuItemName to a gray color to indicate that the user cannot
select it.
ToggleEnable, MenuItemName: Disables MenuItemName if it was previously enabled; otherwise,
enables it.
Default [, MenuItemName]: Changes the menu's default item to be MenuItemName and makes
that item's font bold (setting a default item in menus other than TRAY is currently purely cosmetic).
When the user double-clicks the tray icon, its default menu item is launched. If there is no default,
double-clicking has no effect. If MenuItemName is omitted, the effect is the same as having used
NoDefault below.
NoDefault: For the tray menu: Changes the menu back to having its standard default menu item,
which is OPEN for non-compiled scripts and none for compiled scripts (except when the MainWindow
option is in effect). If the OPEN menu item does not exist due to a previous use of the NoStandard
Printed Documentation
512
command below, there will be no default and thus double-clicking the tray icon will have no effect. For
menus other than TRAY: Any existing default item is returned to a non-bold font.
Standard: Inserts the standard menu items at the bottom of the menu (if they are not already
present). This command can be used with the tray menu or any other menu.
NoStandard: Removes all standard (non-custom) menu items from the tray menu (if they are
present).
Change the Tray Icon or ToolTip (MenuName must be TRAY)
Icon [, FileName, IconNumber, 1]: Changes the script's icon to one of the ones from FileName.
The following types of files are supported: ICO, CUR, ANI, EXE, DLL, CPL, SCR, and other types that
contain icon resources. To use an icon group other than the first one in the file, specify its number for
IconNumber (if omitted, it defaults to 1). For example, 2 would load the default icon from the second
icon group. Specify an asterisk (*) for FileName to restore the script to its default icon.
The last parameter: Specify 1 for the last parameter to freeze the icon, or 0 to unfreeze it (or leave it
blank to keep the frozen/unfrozen state unchanged). When the icon has been frozen, Pause and
Suspend will not change it. Note: To freeze the current icon, use Menu, Tray, Icon,,, 1 ; (or 0 to
unfreeze)
Changing the tray icon also changes the icon displayed by InputBox, Progress, and subsequently-
created GUI windows. Compiled scripts are also affected even if a custom icon was specified at the
time of compiling. Note: Changing the icon will not unhide the tray icon if it was previously hidden by
means such as #NoTrayIcon; to do that, use Menu, Tray, Icon (with no parameters).
Slight distortion may occur when loading tray icons from file types other than .ICO. This is especially
true for 16x16 icons. To prevent this, store the desired tray icon inside a .ICO file.
There are some icons built into the operating system's DLLs and CPLs that might be useful. For
example: Menu, Tray, Icon, Shell32.dll, 174 ; Omits the DLL's path so that it works on Windows 9x
too.
The built-in variables A_IconNumber and A_IconFile contain the number and name (with full path)
of the current icon (both are blank if the icon is the default).
Icon (with no parameters): Creates the tray icon if it isn't already present. This will override
#NoTrayIcon if that directive is also present in the script.
NoIcon: Removes the tray icon if it exists. If this command is used at the very top of the script, the
tray icon might be briefly visible when the script is launched. To prevent that, use #NoTrayIcon
instead. The built-in variable A_IconHidden contains 1 if the tray icon is currently hidden or 0
otherwise.
Tip [, Text]: Changes the tray icon's tooltip -- which is displayed when the mouse hovers over it. To
create a multi-line tooltip, use the linefeed character (`n) in between each line, e.g. Line1`nLine2.
Only the first 127 characters of Text are displayed. If Text is omitted, the tooltip is restored to its
default text. The built-in variable A_IconTip contains the current text of the tooltip (blank if the text
is at its default).
Misc.
Show [, X, Y]: Displays MenuName, allowing the user to select an item with arrow keys, menu
shortcuts (underlined letters), or the mouse. Any menu can be shown, including the tray menu but
with the exception of GUI menu bars. If both X and Y are omitted, the menu is displayed at the
current position of the mouse cursor. If only one of them is omitted, the mouse cursor's position will
be used for it. X and Y are relative to the active window. Specify "CoordMode, Menu" beforehand to
make them relative to the entire screen.
Color, ColorValue [, Single]: Changes the background color of the menu to ColorValue, which is one
of the 16 primary HTML color names or a 6-digit RGB color value (see color chart). Leave ColorValue
blank (or specify the word Default) to restore the menu to its default color. If the word Single is not
Window Management
513
present as the next parameter, any submenus attached to this menu will also be changed in color.
This command has no effect on Windows 95/NT.
Click, ClickCount: Specify 1 for ClickCount to allow a single-click to activate the tray menu's default
menu item. Specify 2 for ClickCount to return to the default behavior (double-click). For example:
Menu, Tray, Click, 1
MainWindow: This command affects compiled scripts only. It allows the script's main window to be
opened via the tray icon, which is otherwise impossible. It also enables the items in the main window's
View menu -- such as "Lines most recently executed" -- allowing users to view the script's source code
and other info. MenuName must be TRAY.
NoMainWindow (default): This command affects compiled scripts only. It restores the script to its
default behavior, that is, it prevents the main window from being opened. Even while this option is in
effect, the following commands are still able to show the main window when they are encountered in
the script at runtime: ListLines, ListVars, ListHotkeys, and KeyHistory. MenuName must be TRAY.
UseErrorLevel [, off]: If this option is never used in the script, it defaults to OFF. The OFF setting
displays a dialog and terminates the current thread whenever the Menu command generates an error.
Specify Menu, Tray, UseErrorLevel to prevent the dialog and thread termination; instead, ErrorLevel
will be set to 1 if there was a problem or 0 otherwise. To turn this option back off, specify OFF for the
next parameter. This setting is global, meaning it affects all menus, not just MenuName.
Remarks
To underline one of the letters in a menu item's name, precede that letter with an ampersand (&).
When the menu is displayed, such an item can be selected by pressing the corresponding key on the
keyboard. To display a literal ampersand, specify two consecutive ampersands as in this example:
Save && Exit
The names of menus and menu items can be up to 260 characters long.
When referring to an existing menu or menu item, the name is not case sensitive but any ampersands
must be included. For example: &Open
Separator lines can be added to the menu by using Menu, tray, add (i.e. omit all other parameters).
However, separator lines currently cannot be individually deleted. To work around this, use Menu,
tray, DeleteAll and then re-add your custom menu items.
New menu items are always added at the bottom of the menu. For the tray menu: To put your menu
items on top of the standard menu items (after adding your own menu items) run Menu, tray,
NoStandard followed by Menu, tray, Standard.
The standard menu items such as "Pause Script" and "Suspend Hotkeys" cannot be individually
operated upon by any menu sub-command.
If a menu ever becomes completely empty -- such as by using Menu, MyMenu, DeleteAll -- it cannot
be shown. If the tray menu becomes empty, right-clicking and double-clicking the tray icon will have
no effect (in such cases it is usually better to use #NoTrayIcon).
If a menu item's subroutine is already running and the user selects the same menu item again, a new
thread will be created to run that same subroutine, interrupting the previous thread. To instead buffer
such events until later, use Critical as the subroutine's first line (however, this will also buffer/defer
other threads such as the press of a hotkey).
Whenever a subroutine is launched via a menu item, it starts off fresh with the default values for
settings such as SendMode. These defaults can be changed in the auto-execute section.
The built-in variables A_ThisMenuItem and A_ThisMenuItemPos contain the name and position of
the custom menu item most recently selected by the user (blank if none). Similarly, A_ThisMenu is
the name of the menu from which A_ThisMenuItem was selected. These variables are useful when
building a menu whose contents are not always the same. In such a case, it is usually best to point all
such menu items to the same label and have that label refer to the above variables to determine what
action to take.
Printed Documentation
514
To keep a non-hotkey, non-GUI script running -- such as one that contains only custom menus or
menu items -- use #Persistent.
Related
GUI, Threads, Thread, Critical, #NoTrayIcon, Gosub, Return, SetTimer, #Persistent
Examples
; EXAMPLE #1: This is a working script that adds a new menu item to the bottom of the tray icon
menu.

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

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

; EXAMPLE #2: This is a working script that creates a popup menu that is displayed when the user
presses the Win-Z hotkey.

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

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

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

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

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

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

; EXAMPLE #3: This is a working script that demonstrates some of the various menu commands.

#Persistent
#SingleInstance
menu, tray, add ; separator
menu, tray, add, TestToggle&Check
menu, tray, add, TestToggleEnable
menu, tray, add, TestDefault
menu, tray, add, TestStandard
menu, tray, add, TestDelete
menu, tray, add, TestDeleteAll
menu, tray, add, TestRename
menu, tray, add, Test
return

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

TestToggle&Check:
menu, tray, ToggleCheck, TestToggle&Check
menu, tray, Enable, TestToggleEnable ; Also enables the next test since it can't undo the disabling of
itself.
menu, tray, add, TestDelete ; Similar to above.
return

TestToggleEnable:
menu, tray, ToggleEnable, TestToggleEnable
return

TestDefault:
if default = TestDefault
{
menu, tray, NoDefault
default =
}
Printed Documentation
516
else
{
menu, tray, Default, TestDefault
default = TestDefault
}
return

TestStandard:
if standard <> n
{
menu, tray, NoStandard
standard = n
}
else
{
menu, tray, Standard
standard = y
}
return

TestDelete:
menu, tray, delete, TestDelete
return

TestDeleteAll:
menu, tray, DeleteAll
return

TestRename:
if NewName <> renamed
{
OldName = TestRename
NewName = renamed
}
else
{
OldName = renamed
NewName = TestRename
Window Management
517
}
menu, tray, rename, %OldName%, %NewName%
return

Test:
MsgBox, You selected "%A_ThisMenuItem%" in menu "%A_ThisMenu%".
return
PostMessage / SendMessage
Sends a message to a window or control (SendMessage additionally waits for acknowledgement).
PostMessage, Msg [, wParam, lParam, Control, WinTitle, WinText, ExcludeTitle, ExcludeText]
SendMessage, Msg [, wParam, lParam, Control, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
Msg
The message number to send, which can be an expression. See the message
list to determine the number.
wParam
The first component of the message, which can be an expression. If blank or
omitted, 0 will be sent.
lParam
The second component of the message, which can be an expression. If blank
or omitted, 0 will be sent.
Control
If this parameter is blank or omitted, the message will be sent directly to the
target window rather than one of its controls. Otherwise, this parameter can
be either ClassNN (the classname and instance number of the control) or the
name/text of the control, both of which can be determined via Window Spy.
When using name/text, the matching behavior is determined by
SetTitleMatchMode.
To operate upon a control's HWND (window handle), leave the Control
parameter blank and specify ahk_id %ControlHwnd% for the WinTitle
parameter (this also works on hidden controls even when
DetectHiddenWindows is Off). The HWND of a control is typically retrieved via
ControlGet Hwnd, MouseGetPos, or DllCall.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the next 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
next 3 parameters are omitted, the active window will be used. To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a process identifier (PID), specify ahk_pid %VarContainingPID%. To use a
window group, specify ahk_group GroupName. To use a window's unique ID
number, specify ahk_id %VarContainingID% (also accepts a control's HWND).
The search can be narrowed by specifying multiple criteria. For example: My
File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
ErrorLevel
Printed Documentation
518
PostMessage: ErrorLevel is set to 1 if there was a problem such as the target window or control not
existing. Otherwise, it is set to 0.
SendMessage: ErrorLevel is set to the word FAIL if there was a problem. Otherwise, it is set to the
numeric result of the message, which might sometimes be a "reply" depending on the nature of the
message and its target window.
Remarks
These commands should be used with caution because sending a message to the wrong window (or
sending an invalid message) might cause unexpected behavior or even crash the target application.
This is because most applications are not designed to expect certain types of messages from external
sources.
PostMessage places the message in the message queue associated with the target window. It does not
wait for acknowledgement or reply. By contrast, SendMessage waits up to 5 seconds for the target
window to process the message. If the message is not processed within this time, the command
finishes and sets ErrorLevel to the word FAIL.
The parameters Msg, wParam, and lParam should all be integers between -2147483648 and
4294967295 (0xFFFFFFFF). As with all integer values in AutoHotkey, a prefix of 0x indicates a hex
value. For example, 0xFF is equivalent to 255.
A string may be sent via wParam or lParam by specifying the address of a variable. The following
example uses the address operator (&) to do this:
SendMessage, 0xC, 0, &MyVar, ClassNN, WinTitle
In v1.0.43.06+, a string put into MyVar by the receiver of the message is properly recognized without
the need for extra steps. However, this works only if the parameter's first character is an ampersand
(&); for example, 5+&MyVar would not work but &MyVar or &MyVar+5 would work.
In v1.0.40.05+, a quoted/literal string may also be sent as in the following working example (the &
operator should not be used in this case):
Run Notepad
WinWait Untitled - Notepad
SendMessage, 0xC, 0, "New Notepad Title" ; 0XC is WM_SETTEXT
To send a message to all windows in the system, including those that are hidden or disabled, specify
ahk_id 0xFFFF for WinTitle (0xFFFF is HWND_BROADCAST). This technique should be used only for
messages intended to be broadcast, such as the following example:
SendMessage, 0x1A,,,, ahk_id 0xFFFF ; 0x1A is WM_SETTINGCHANGE
To have a script receive a message, use OnMessage().
See the Message Tutorial for an introduction to using these commands.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
Message List, Message Tutorial, OnMessage(), Automating Winamp, DllCall, ControlSend,
WinMenuSelectItem
Examples
#o:: ; Win+O hotkey that turns off the monitor.
Sleep 1000 ; Give user a chance to release keys (in case their release would wake up the monitor
again).
; Turn Monitor Off:
SendMessage, 0x112, 0xF170, 2,, Program Manager ; 0x112 is WM_SYSCOMMAND, 0xF170 is
SC_MONITORPOWER.
Window Management
519
; Note for the above: Use -1 in place of 2 to turn the monitor on.
; Use 1 in place of 2 to activate the monitor's low-power mode.
return

; Start the user's chosen screen saver:
SendMessage, 0x112, 0xF140, 0,, Program Manager ; 0x112 is WM_SYSCOMMAND, and 0xF140 is
SC_SCREENSAVE.

; Scroll up by one line (for a control that has a vertical scroll bar):
ControlGetFocus, control, A
SendMessage, 0x115, 0, 0, %control%, A

; Scroll down by one line:
ControlGetFocus, control, A
SendMessage, 0x115, 1, 0, %control%, A

; Switch the active window's keyboard layout/language to English:
PostMessage, 0x50, 0, 0x4090409,, A ; 0x50 is WM_INPUTLANGCHANGEREQUEST.

; This example asks Winamp which track number is currently active:
SetTitleMatchMode, 2
SendMessage, 1024, 0, 120, - Winamp
if ErrorLevel <> FAIL
{
ErrorLevel++ ; Winamp's count starts at "0", so adjust by 1.
MsgBox, Track #%ErrorLevel% is active or playing.
}



; See Automating Winamp for more information.


; To find the process ID of an AHK script (an alternative to "WinGet PID"):
SetTitleMatchMode, 2
DetectHiddenWindows, on
SendMessage, 0x44, 0x405, 0, , SomeOtherScript.ahk - AutoHotkey v
MsgBox %ErrorLevel% is the process id.
Printed Documentation
520
SetControlDelay
Sets the delay that will occur after each control-modifying command.
SetControlDelay, Delay
Parameters
Delay
Time in milliseconds, which can be an expression. Use -1 for no delay at all
and 0 for the smallest possible delay. If unset, the default delay is 20.
Remarks
A short delay (sleep) is done automatically after every Control command that changes a control,
namely Control, ControlMove, ControlClick, ControlFocus, and ControlSetText (ControlSend uses
SetKeyDelay). This is done to improve the reliability of scripts because a control sometimes needs a
period of "rest" after being changed by one of these commands. The rest period allows it to update
itself and respond to the next command that the script may attempt to send to it.
Although a delay of -1 (no delay at all) is allowed, it is recommended that at least 0 be used, to
increase confidence that the script will run correctly even when the CPU is under load.
A delay of 0 internally executes a Sleep(0), which yields the remainder of the script's timeslice to any
other process that may need it. If there is none, Sleep(0) will not sleep at all.
If the CPU is slow or under load, or if window animation is enabled, higher delay values may be
needed.
The built-in variable A_ControlDelay contains the current setting.
Every newly launched thread (such as a hotkey, custom menu item, or timed subroutine) starts off
fresh with the default setting for this command. That default may be changed by using this command
in the auto-execute section (top part of the script).
Related
Control, ControlMove, ControlClick, ControlFocus, ControlSetText, SetWinDelay, SetKeyDelay,
SetMouseDelay, SetBatchLines
Example
SetControlDelay, 0
WinMenuSelectItem
Invokes a menu item from the menu bar of the specified window.
WinMenuSelectItem, WinTitle, WinText, Menu [, SubMenu1, SubMenu2, SubMenu3, SubMenu4,
SubMenu5, SubMenu6, ExcludeTitle, ExcludeText]
Parameters
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the other 3 window parameters
are blank or omitted, the Last Found Window will be used. If this is the letter A
and the other 3 window parameters are blank or omitted, the active window
will be used. To use a window class, specify ahk_class ExactClassName (shown
by Window Spy). To use a process identifier (PID), specify ahk_pid
%VarContainingPID%. To use a window group, specify ahk_group GroupName.
To use a window's unique ID number, specify ahk_id %VarContainingID%. The
search can be narrowed by specifying multiple criteria. For example: My
File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
Window Management
521
Menu
The name of the top-level menu, e.g. File, Edit, View. It can also be the
position of the desired menu item by using 1& to represent the first menu, 2&
the second, and so on.
SubMenu1 The name of the menu item to select or its position (see above).
SubMenu2
If SubMenu1 itself contains a menu, this is the name of the menu item inside,
or its position.
SubMenu3 Same as above.
SubMenu4 Same as above.
SubMenu5 Same as above.
SubMenu6 Same as above.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
For this command to work, the target window need not be active. However, some windows might need
to be in a non-minimized state.
This command will not work with applications that use non-standard menu bars. Examples include
Microsoft Outlook and Outlook Express, which use disguised toolbars for their menu bars. In these
cases, consider using ControlSend or PostMessage , which should be able to interact with some of
these non-standard menu bars.
The menu name parameters are not case sensitive (i.e. File->Save is the same as file->save) and the
use of ampersand (&) to indicate the underlined letter in a menu item is not necessary (i.e. &File is
the same as File).
The menu name parameters can also specify positions. This method exists to support menus that
don't contain text (perhaps because they contain pictures of text rather than actual text). Position 1&
is the first menu item (e.g. the File menu), position 2& is the second menu item (e.g. the Edit menu),
and so on. Menu separator lines count as menu items for the purpose of determining the position of a
menu item.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
ControlSend, PostMessage
Example
; This will select File->Open in Notepad:
WinMenuSelectItem, Untitled - Notepad, , File, Open

; Same as above except it's done by position vs. name:
WinMenuSelectItem, Untitled - Notepad, , 1&, 2&
Window Groups
GroupActivate
Activates the next window in a window group that was defined with GroupAdd.
Printed Documentation
522
GroupActivate, GroupName [, R]
Parameters
GroupName The name of the group to activate, as originally defined by GroupAdd.
R
This determines whether the oldest or the newest window is activated
whenever no members of the group are currently active. If omitted, the oldest
window is always activated. If it's the letter R, the newest window (the one
most recently active) is activated, but only if no members of the group are
active when the command is given. "R" is useful in cases where you
temporarily switch to working on an unrelated task. When you return to the
group via GroupActivate, GroupDeactivate, or GroupClose, the window you
were most recently working with is activated rather than the oldest window.
Remarks
This command causes the first window that matches any of the group's window specifications to be
activated. Using it a second time will activate the next window in the series and so on. Normally, it is
assigned to a hotkey so that this window-traversal behavior is automated by pressing that key.
When a window is activated immediately after another window was activated, task bar buttons may
start flashing on some systems (depending on OS and settings). To prevent this, use
#WinActivateForce.
See GroupAdd for more details about window groups.
Related
GroupAdd, GroupDeactivate, GroupClose, #WinActivateForce
Example
GroupActivate, MyGroup, R
GroupAdd
Adds a window specification to a window group, creating the group if necessary.
GroupAdd, GroupName [, WinTitle, WinText, Label, ExcludeTitle, ExcludeText]
Parameters
GroupName
The name of the group to which to add this window specification. If the group
doesn't exist, it will be created. Group names are not case sensitive.
WinTitle
The title or partial title of the target window(s). It can be blank. Note:
Although SetTitleMatchMode and DetectHiddenWindows do not directly affect
the behavior of this command, they do affect the other group commands such
as GroupActivate and GroupClose. They also affect the use of ahk_group in any
other command's WinTitle.
To use a window class, specify ahk_class ExactClassName (shown by Window
Spy). To use a process identifier (PID), specify ahk_pid %VarContainingPID%.
To use a window's unique ID number, specify ahk_id %VarContainingID%. To
use a window group, specify ahk_group GroupName (i.e. groups may contain
other groups).
The search can be narrowed by specifying multiple criteria. For example: My
File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON at the time that
GroupActivate, GroupDeactivate, and GroupClose are used.
Window Management
523
Label
The label of a subroutine to run if no windows matching this specification exist
when the GroupActivate command is used. The label is jumped to as though a
Gosub had been used. Omit or leave blank for none.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
Remarks
Each use of this command adds a new rule to a group. In other words, a group consists of a set of
criteria rather than a fixed list of windows. Later, when a group is used by a command such as
GroupActivate, each window on the desktop is checked against each of these criteria. If a window
matches one of the criteria in the group, it is considered a match.
A window group is typically used to bind together a collection of related windows, which is useful for
tasks that involve many related windows, or an application that owns many subwindows. For example,
if you frequently work with many instances of a graphics program or text editor, you can use
GroupActivate on a hotkey to visit each instance of that program, one at a time, without having to use
alt-tab or task bar buttons to locate them.
Since the entries in each group need to be added only once, this command is typically used in the
auto-execute section (top part of the script). Attempts to add duplicate entries to a group are ignored.
To include all windows in a group (except the special Program Manager window), use this example:
GroupAdd, AllWindows ; But in versions prior to 1.0.36.05, use the next line instead.
GroupAdd, AllWindows, , , , Program Manager
All windowing commands can operate upon a window group by specifying ahk_group MyGroupName
for the WinTitle parameter. The commands WinMinimize, WinMaximize, WinRestore, WinHide,
WinShow, WinClose, and WinKill will act upon all the group's windows. To instead act upon only the
topmost window, follow this example:
WinHide % "ahk_id " . WinExist("ahk_group MyGroup")
By contrast, the other window commands such as WinActivate and IfWinExist will operate only upon
the topmost window of the group.
Related
GroupActivate, GroupDeactivate, GroupClose
Examples
; In the autoexecute section at the top of the script:
GroupAdd, MSIE, ahk_class IEFrame ; Add only Internet Explorer windows to this group.
return ; End of autoexecute section.

; Assign a hotkey to activate this group, which traverses
; through all open MSIE windows, one at a time (i.e. each
; press of the hotkey).
Numpad1::GroupActivate, MSIE, r

; Here's a more complex group for MS Outlook 2002.
; In the autoexecute section at the top of the script:
SetTitleMatchMode, 2
GroupAdd, mail, Message - Microsoft Word ; This is for mails currently being composed
Printed Documentation
524
GroupAdd, mail, - Message ( ; This is for already opened items
; Need extra text to avoid activation of a phantom window:
GroupAdd, mail, Advanced Find, Sear&ch for the word(s)
GroupAdd, mail, , Recurrence:
GroupAdd, mail, Reminder
GroupAdd, mail, - Microsoft Outlook
return ; End of autoexecute section.


Numpad5::GroupActivate, mail ; Assign a hotkey to visit each Outlook window, one at a time.
GroupClose
Closes the active window if it was just activated by GroupActivate or GroupDeactivate. It then
activates the next window in the series. It can also close all windows in a group.
GroupClose, GroupName [, A|R]
Parameters
GroupName The name of the group as originally defined by GroupAdd.
A|R
If it's the letter A, all members of the group will be closed. This is the same
effect as WinClose ahk_group GroupName.
Otherwise: If the command closes the active window, it will then activate the
next window in the series. This parameter determines whether the oldest or
the newest window is activated. If omitted, the oldest window is always
activated. If it's the letter R, the newest window (the one most recently active)
is activated, but only if no members of the group are active when the
command is given. "R" is useful in cases where you temporarily switch to
working on an unrelated task. When you return to the group via
GroupActivate, GroupDeactivate, or GroupClose, the window you were most
recently working with is activated rather than the oldest window.
Remarks
When the A|R parameter is not "A", the behavior of this command is determined by whether the
previous action on GroupName was GroupActivate or GroupDeactivate. If it was GroupDeactivate, this
command will close the active window only if it is not a member of the group (otherwise it will do
nothing). If it was GroupActivate or nothing, this command will close the active window only if it is a
member of the group (otherwise it will do nothing). This behavior allows GroupClose to be assigned to
a hotkey as a companion to GroupName's GroupActivate or GroupDeactivate hotkey.
See GroupAdd for more details about window groups.
Related
GroupAdd, GroupActivate, GroupDeactivate
Example
GroupClose, MyGroup, R
GroupDeactivate
Similar to GroupActivate except activates the next window not in the group.
GroupDeactivate, GroupName [, R]
Window Management
525
Parameters
GroupName The name of the target group, as originally defined by GroupAdd.
R
This determines whether the oldest or the newest non-member window is
activated whenever a member of the group is currently active. If omitted, the
oldest non-member window is always activated. If it's the letter R, the newest
non-member window (the one most recently active) is activated, but only if a
member of the group is active when the command is given. "R" is useful in
cases where you temporarily switch to working on an unrelated task. When
you return to the group via GroupActivate, GroupDeactivate, or GroupClose,
the window you were most recently working with is activated rather than the
oldest window.
Remarks
GroupDeactivate causes the first window that does not match any of the group's window
specifications to be activated. Using GroupDeactivate a second time will activate the next window in
the series and so on. Normally, GroupDeactivate is assigned to a hotkey so that this window-traversal
behavior is automated by pressing that key.
This command is useful in cases where you have a collection of favorite windows that are almost
always running. By adding these windows to a group, you can use GroupDeactivate to visit each
window that isn't one of your favorites and decide whether to close it. This allows you to clean up your
desktop much more quickly than doing it manually.
See GroupAdd for more details about window groups.
Related
GroupAdd, GroupActivate, GroupClose
Example
GroupDeactivate, MyFavoriteWindows ; Visit non-favorite windows to clean up desktop.
#WinActivateForce
Skips the gentle method of of activating a window and goes straight to the forceful method.
#WinActivateForce
Specifying this anywhere in a script will cause commands that activate a window -- such as
WinActivate, WinActivateBottom, and GroupActivate -- to skip the "gentle" method of activating a
window and go straight to the more forceful methods.
Although this directive will usually not change how quickly or reliably a window is activated, it might
prevent task bar buttons from flashing when different windows are activated quickly one after the
other.
Windows 95 and NT will probably never need this setting since they are more permissive about
allowing windows to be activated.
Related
WinActivate, WinActivateBottom, GroupActivate
Example
#WinActivateForce
DetectHiddenText
Determines whether invisible text in a window is "seen" for the purpose of finding the window. This
affects commands such as IfWinExist and WinActivate.
Printed Documentation
526
DetectHiddenText, On|Off
Parameters
On|Off
On: This is the default for non-AutoIt v2 scripts (e.g. .ahk, .ini). Hidden text
will be detected.
Off: This is the default for AutoIt v2 scripts. Hidden text is not detected.
Remarks
"Hidden text" is a term that refers to those controls of a window that are not visible. Their text is thus
considered "hidden". Turning off DetectHiddenText can be useful in cases where you want to detect
the difference between the different panes of a multi-pane window or multi-tabbed dialog. Use
Window Spy to determine which text of the currently-active window is hidden. All commands that
accept a WinText parameter are affected by this setting, including WinActivate, IfWinActive, WinWait,
and IfWinExist.
The built-in variable A_DetectHiddenText contains the current setting (On or Off).
Every newly launched thread (such as a hotkey, custom menu item, or timed subroutine) starts off
fresh with the default setting for this command. That default may be changed by using this command
in the auto-execute section (top part of the script).
Related
DetectHiddenWindows
Example
DetectHiddenText, off
DetectHiddenWindows
Determines whether invisible windows are "seen" by the script.
DetectHiddenWindows, On|Off
Parameters
On|Off
On: Hidden windows are detected.
Off: This is the default. Hidden windows are not detected, except by the
WinShow command.
Remarks
Turning on DetectHiddenWindows can make scripting harder in some cases since some hidden system
windows might accidentally match the title or text of another window you're trying to work with. So
most scripts should leave this setting turn off. However, turning it on may be useful if you wish to
work with hidden windows directly without first using WinShow to unhide them.
All windowing commands except WinShow are affected by this setting, including WinActivate,
IfWinActive, WinWait, IfWinExist. In other words, WinShow will always unhide a hidden window even if
hidden windows are not being detected.
The built-in variable A_DetectHiddenWindows contains the current setting (On or Off).
In v1.0.40.05+, a child window (control) may be accessed via the ahk_id method even when hidden;
that is, the setting of DetectHiddenWindows does not matter.
Window Management
527
Every newly launched thread (such as a hotkey, custom menu item, or timed subroutine) starts off
fresh with the default setting for this command. That default may be changed by using this command
in the auto-execute section (top part of the script).
Related
DetectHiddenText
Example
DetectHiddenWindows, on
IfWinActive / IfWinNotActive
Checks if the specified window exists and is currently active (foremost).
IfWinActive [, WinTitle, WinText, ExcludeTitle, ExcludeText]
IfWinNotActive [, WinTitle, WinText, ExcludeTitle, ExcludeText]
UniqueID := WinActive("WinTitle", "WinText", "ExcludeTitle", "ExcludeText")
Parameters
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the other 3 parameters are
omitted, the Last Found Window will be used. To use a window class, specify
ahk_class ExactClassName (shown by Window Spy). To use a process identifier
(PID), specify ahk_pid %VarContainingPID%. To use a window group, specify
ahk_group GroupName. To use a window's unique ID number, specify ahk_id
%VarContainingID%. The search can be narrowed by specifying multiple
criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle
Windows whose titles include this value will not be considered. Note: Due to
backward compatibility with .aut scripts, this parameter will be interpreted as a
command if it exactly matches the name of a command. To work around this,
use the WinActive() function instead.
ExcludeText Windows whose text include this value will not be considered.
Remarks
If all parameters are omitted, the Last Found Window will be used.
If either of these commands determines that the active window is a qualified match, the Last Found
Window will be updated to be the active window. In other words, if IfWinActive evaluates to "true" or
IfWinNotActive evaluates to "false", the Last Found Window will be updated.
The function WinActive() returns the Unique ID (HWND) of the active window if it matches the
specified criteria. If it does not, the function returns 0. Since all non-zero numbers are seen as "true",
the statement if WinActive("WinTitle") is true whenever WinTitle is active.
SetWinDelay does not apply to IfWinExist/IfWinActive.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
Printed Documentation
528
IfWinExist, SetTitleMatchMode, DetectHiddenWindows, Last Found Window, WinActivate,
WinWaitActive, WinWait, WinWaitClose, #IfWinActive/Exist
Example
IfWinActive, Untitled - Notepad
{
WinMaximize ; Maximizes the Notepad window found by IfWinActive above.
Send, Some text.{Enter}
return
}

if WinActive("ahk_class Notepad") or WinActive("ahk_class" . ClassName) ; "ahk_class" need not
have a space after it.
WinClose ; Uses the last found window.
IfWinExist / IfWinNotExist
Checks if the specified window exists.
IfWinExist [, WinTitle, WinText, ExcludeTitle, ExcludeText]
IfWinNotExist [, WinTitle, WinText, ExcludeTitle, ExcludeText]
UniqueID := WinExist("WinTitle", "WinText", "ExcludeTitle", "ExcludeText")
Parameters
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the other 3 parameters are all
omitted, the Last Found Window will be used (i.e. that specific window is
checked to see whether it still exists). To use a window class, specify ahk_class
ExactClassName (shown by Window Spy). To use a process identifier (PID),
specify ahk_pid %VarContainingPID%. To use a window group, specify
ahk_group GroupName. To use a window's unique ID number, specify ahk_id
%VarContainingID%. The search can be narrowed by specifying multiple
criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle
Windows whose titles include this value will not be considered. Note: Due to
backward compatibility with .aut scripts, this parameter will be interpreted as a
command if it exactly matches the name of a command. To work around this,
use the WinExist() function instead.
ExcludeText Windows whose text include this value will not be considered.
Remarks
If all parameters are omitted, the Last Found Window will be checked to see if it still exists (or doesn't
exist in the case of IfWinNotExist).
If either of these commands determines that a qualified window exists, the Last Found Window will be
updated to be that window. In other words, if IfWinExist evaluates to true or IfWinNotExist evaluates
to false, the Last Found Window will be updated.
Window Management
529
The function WinExist() returns the Unique ID (HWND) of the first matching window (0 if none). Since
all non-zero numbers are seen as "true", the statement if WinExist("WinTitle") is true whenever
WinTitle exists.
To discover the HWND of a control (for use with Post/SendMessage or DllCall), use ControlGet Hwnd
or MouseGetPos.
SetWinDelay does not apply to IfWinExist/IfWinActive.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
IfWinActive, SetTitleMatchMode, DetectHiddenWindows, Last Found Window, Process, WinActivate,
WinWaitActive, WinWait, WinWaitClose, #IfWinActive/Exist
Examples
IfWinExist, Untitled - Notepad
{
WinActivate ; Automatically uses the window found above.
WinMaximize ; same
Send, Some text.{Enter}
return
}

IfWinNotExist, Calculator
return
else
{
WinActivate ; The above "IfWinNotExist" also set the "last found" window for us.
WinMove, 40, 40 ; Move it to a new position.
return
}

if WinExist("ahk_class Notepad") or WinExist("ahk_class" . ClassName)
WinActivate ; Uses the last found window.

MsgBox % "The active window's ID is " . WinExist("A")
SetTitleMatchMode
Sets the matching behavior of the WinTitle parameter in commands such as WinWait.
SetTitleMatchMode, MatchMode
SetTitleMatchMode, Fast|Slow
Parameters
Printed Documentation
530
MatchMode
One of the following digits or the word RegEx:
1: A window's title must start with the specified WinTitle to be a match.
2: A window's title can contain WinTitle anywhere inside it to be a match.
3: A window's title must exactly match WinTitle to be a match.
RegEx (v1.0.45+): Changes WinTitle, WinText, ExcludeTitle, and ExcludeText
to support regular expressions. Do not enclose such expressions in quotes. For
example: WinActivate Untitled.*Notepad. RegEx also applies to ahk_group and
ahk_class; for example, ahk_class IEFrame searches for any window whose
class name contains IEFrame anywhere (this is because by default, regular
expressions find a match anywhere in the target string). Note: For WinText,
each text element (i.e. each control's text) is matched against the RegEx
separately. Therefore, it is not possible to have a match span more than one
text element.
The modes above also affect ExcludeTitle in the same way as WinTitle. For
example, mode 3 requires that a window's title exactly match ExcludeTitle for
that window to be excluded.
Fast|Slow
Fast: This is the default behavior. Performance may be substantially better
than Slow, but certain WinText elements for some types of windows may not
be "seen" by the various window commands.
Slow: Can be much slower, but all possible WinText is retrieved from every
window as a windowing command searches through them for a match. Window
Spy reveals which parts of a Window's text (if any) require the slow mode.
Remarks
This command affects the behavior of all windowing commands, e.g. IfWinExist and WinActivate.
If unspecified, TitleMatchMode defaults to 1 and fast.
Generally, the slow mode should only be used if the target window cannot be uniquely identified by its
title and fast-mode text. This is because the slow mode can be extremely slow if there are any
application windows that are busy or "not responding".
The customized version of Window Spy distributed with AutoHotkey reports slow text in a separate
section so that its easy to determine whether the slow mode is needed.
If you wish to change both attributes, run the command twice as in this example:
SetTitleMatchMode, 2
SetTitleMatchMode, slow
The built-in variables A_TitleMatchMode and A_TitleMatchModeSpeed contain the current
settings.
Regardless of the current TitleMatchMode, WinTitle, WinText, ExcludeTitle and ExcludeText are case
sensitive. The only exception is the case-insensitive option of the RegEx mode; for example: i) untitled
- notepad
Every newly launched thread (such as a hotkey, custom menu item, or timed subroutine) starts off
fresh with the default setting for this command. That default may be changed by using this command
in the auto-execute section (top part of the script).
Related
SetWinDelay, IfWinExist, WinActivate, RegExMatch()
Example
Window Management
531
SetTitleMatchMode 2
; OR:
SetTitleMatchMode RegEx

SetTitleMatchMode Slow ; Slow/Fast can be set independently of all the other modes.
SetWinDelay
Sets the delay that will occur after each windowing command, such as WinActivate.
SetWinDelay, Delay
Parameters
Delay
Time in milliseconds, which can be an expression. Use -1 for no delay at all
and 0 for the smallest possible delay. If unset, the default delay is 100.
Remarks
A short delay (sleep) is done automatically after every windowing command except IfWinActive and
IfWinExist. This is done to improve the reliability of scripts because a window sometimes needs a
period of "rest" after being created, activated, minimized, etc. so that it has a chance to update itself
and respond to the next command that the script may attempt to send to it.
Although a delay of -1 (no delay at all) is allowed, it is recommended that at least 0 be used, to
increase confidence that the script will run correctly even when the CPU is under load.
A delay of 0 internally executes a Sleep(0), which yields the remainder of the script's timeslice to any
other process that may need it. If there is none, Sleep(0) will not sleep at all.
If the CPU is slow or under load, or if window animation is enabled, higher delay values may be
needed.
The built-in variable A_WinDelay contains the current setting.
Every newly launched thread (such as a hotkey, custom menu item, or timed subroutine) starts off
fresh with the default setting for this command. That default may be changed by using this command
in the auto-execute section (top part of the script).
Related
SetControlDelay, SetKeyDelay, SetMouseDelay, SetBatchLines, SendMode
Example
SetWinDelay, 10
StatusBarGetText
Retrieves the text from a standard status bar control.
StatusBarGetText, OutputVar [, Part#, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
OutputVar The name of the variable in which to store the retrieved text.
Part#
Which part number of the bar to retrieve, which can be an expression. Default
1, which is usually the part that contains the text of interest.
Printed Documentation
532
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the other 3 window parameters
are blank or omitted, the Last Found Window will be used. If this is the letter A
and the other 3 window parameters are blank or omitted, the active window
will be used. To use a window class, specify ahk_class ExactClassName (shown
by Window Spy). To use a process identifier (PID), specify ahk_pid
%VarContainingPID%. To use a window group, specify ahk_group GroupName.
To use a window's unique ID number, specify ahk_id %VarContainingID%. The
search can be narrowed by specifying multiple criteria. For example: My
File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
ErrorLevel
ErrorLevel is set to 1 if there is a problem or 0 otherwise. If there was a problem, OutputVar is also
made blank.
Remarks
This command attempts to read the first standard status bar on a window (Microsoft common control:
msctls_statusbar32). Some programs use their own status bars or special versions of the MS common
control, in which case the text cannot be retrieved.
Rather than using this command in a loop, it is usually more efficient to use StatusBarWait, which
contains optimizations that avoid the overhead of repeated calls to StatusBarGetText.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
StatusBarWait, WinGetTitle, WinGetText, ControlGetText
Example
StatusBarGetText, RetrievedText, 1, Search Results
IfInString, RetrievedText, found, MsgBox, Search results have been found.
StatusBarWait
Waits until a window's status bar contains the specified string.
StatusBarWait [, BarText, Seconds, Part#, WinTitle, WinText, Interval, ExcludeTitle, ExcludeText]
Parameters
BarText
The text or partial text for the which the command will wait to appear. Default
is blank (empty), which means to wait for the status bar to become blank. The
text is case sensitive and the matching behavior is determined by
SetTitleMatchMode, similar to WinTitle below.
Seconds
The number of seconds (can contain a decimal point or be an expression) to
wait before timing out, in which case ErrorLevel will be set to 1. Default is
blank, which means wait indefinitely. Specifying 0 is the same as specifying
Window Management
533
0.5.
Part#
Which part number of the bar to retrieve, which can be an expression. Default
1, which is usually the part that contains the text of interest.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the other 3 window parameters
are blank or omitted, the Last Found Window will be used. If this is the letter A
and the other 3 window parameters are blank or omitted, the active window
will be used. To use a window class, specify ahk_class ExactClassName (shown
by Window Spy). To use a process identifier (PID), specify ahk_pid
%VarContainingPID%. To use a window group, specify ahk_group GroupName.
To use a window's unique ID number, specify ahk_id %VarContainingID%. The
search can be narrowed by specifying multiple criteria. For example: My
File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
Interval
How often the status bar should be checked while the command is waiting (in
milliseconds), which can be an expression. Default is 50.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
ErrorLevel
ErrorLevel is set to 1 if the command times out before a match could be found in the status bar. It is
set to 2 if the status bar could not be accessed. It is set to 0 if a match is found.
Remarks
StatusBarWait attempts to read the first standard status bar on a window (class msctls_statusbar32).
Some programs use their own status bars or special versions of the MS common control. Such bars
are not supported.
Rather than using StatusBarGetText in a loop, it is usually more efficient to use StatusBarWait
because it contains optimizations that avoid the overhead that repeated calls to StatusBarGetText
would incur.
StatusBarWait determines its target window before it begins waiting for a match. If that target window
is closed, the command will stop waiting even if there is another window matching the specified
WinTitle and WinText.
While the command is in a waiting state, new threads can be launched via hotkey, custom menu item,
or timer.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
StatusBarGetText, WinGetTitle, WinGetText, ControlGetText
Example
IfWinExist, Search Results ; Sets the Last Found window to simplify the below.
{
WinActivate
Send, {tab 2}!o*.txt{enter}
Printed Documentation
534
Sleep, 400 ; Give the status bar time to change to "Searching".
StatusBarWait, found, 30
if ErrorLevel
MsgBox, The command timed out or there was a problem.
else
MsgBox, The search successfully completed.
}
WinActivate
Activates the specified window (makes it foremost).
WinActivate [, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If all parameters are omitted, the Last
Found Window will be activated. To use a window class, specify ahk_class
ExactClassName (shown by Window Spy). To use a process identifier (PID),
specify ahk_pid %VarContainingPID%. To use a window group, specify
ahk_group GroupName. To use a window's unique ID number, specify ahk_id
%VarContainingID%. The search can be narrowed by specifying multiple
criteria. For example: My File.txt ahk_class Notepad The search can be
narrowed by specifying multiple criteria. For example: My File.txt ahk_class
Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
Remarks
If the window is minimized, it is automatically restored prior to being activated.
Six attempts will be made to activate the target window over the course of 60ms. Thus, it is usually
unnecessary to follow WinActive with WinWaitActive.
If a matching window is already active, that window will be kept active rather than activating any
other matching window beneath it. In general, if more than one window matches, the topmost (most
recently used) will be activated. You can activate the bottommost (least recently used) via
WinActivateBottom.
When a window is activated immediately after the activation of some other window, task bar buttons
might start flashing on some systems (depending on OS and settings). To prevent this, use
#WinActivateForce.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
WinActivateBottom, #WinActivateForce, SetTitleMatchMode, DetectHiddenWindows, Last Found
Window, IfWinExist, IfWinActive, WinWaitActive, WinWait, WinWaitClose, WinClose, GroupActivate,
WinSet
Window Management
535
Example
IfWinExist, Untitled - Notepad
WinActivate ; use the window found above
else
WinActivate, Calculator
WinActivateBottom
Same as WinActivate except that it activates the bottommost (least recently active) matching window
rather than the topmost.
WinActivateBottom [, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). To use a window class, specify ahk_class
ExactClassName (shown by Window Spy). To use a process identifier (PID),
specify ahk_pid %VarContainingPID%. To use a window group, specify
ahk_group GroupName. To use a window's unique ID number, specify ahk_id
%VarContainingID%. The search can be narrowed by specifying multiple
criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
Remarks
If there is only one matching window, WinActivateBottom behaves identically to WinActivate.
Window groups are more advanced than this command, so consider using them for more features and
flexibility.
If the window is minimized, it is automatically restored prior to being activated.
Six attempts will be made to activate the target window over the course of 60ms. Thus, it is usually
unnecessary to follow it with the WinWaitActive command.
Unlike WinActivate, the Last Found Window cannot be used because it might not be the bottommost
window. Therefore, at least one of the parameters must be non-blank.
When a window is activated immediately after another window was activated, task bar buttons may
start flashing on some systems (depending on OS and settings). To prevent this, use
#WinActivateForce.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
WinActivate, #WinActivateForce, SetTitleMatchMode, DetectHiddenWindows, IfWinExist, IfWinActive,
WinWaitActive, WinWait, WinWaitClose, GroupActivate
Example
Printed Documentation
536
; This hotkey allows you to visit all open browser windows in order from oldest to newest:
#i::
SetTitleMatchMode, 2
WinActivateBottom, - Microsoft Internet Explorer
return
WinClose
Closes the specified window.
WinClose [, WinTitle, WinText, SecondsToWait, ExcludeTitle, ExcludeText]
Parameters
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the other 3 window
parameters are blank or omitted, the Last Found Window will be used. If this
is the letter A and the other 3 window parameters are blank or omitted, the
active window will be used. To use a window class, specify ahk_class
ExactClassName (shown by Window Spy). To use a process identifier (PID),
specify ahk_pid %VarContainingPID%. To close a group of windows, specify
ahk_group GroupName (WinText, ExcludeTitle, and ExcludeText must be
blank in this case). To use a window's unique ID number, specify ahk_id
%VarContainingID%. The search can be narrowed by specifying multiple
criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
SecondsToWait
If omitted or blank, the command will not wait at all. If 0, it will wait 500ms.
Otherwise, it will wait the indicated number of seconds (can contain a
decimal point or be an expression) for the window to close. If the window
does not close within that period, the script will continue. ErrorLevel is not
set by this command, so use IfWinExist or WinWaitClose if you need to
determine for certain that a window is closed. While the command is in a
waiting state, new threads can be launched via hotkey, custom menu item,
or timer.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
Remarks
This command sends a close message to a window. The result depends on the window (it may ask to
save data, etc.)
If a matching window is active, that window will be closed in preference to any other matching window
beneath it. In general, if more than one window matches, the topmost (most recently used) will be
closed.
This command operates only upon the topmost matching window except when WinTitle is ahk_group
GroupName, in which case all windows in the group are affected.
WinClose sends a WM_CLOSE message to the target window, which is a somewhat forceful method of
closing it. An alternate method of closing is to send the following message. It might produce different
behavior because it is similar in effect to pressing Alt-F4 or clicking the window's close button in its
title bar:
Window Management
537
PostMessage, 0x112, 0xF060,,, WinTitle, WinText ; 0x112 = WM_SYSCOMMAND, 0xF060 =
SC_CLOSE
If a window does not close via WinClose, you can force it to close with WinKill.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
WinKill, WinWaitClose, Process, WinActivate, SetTitleMatchMode, DetectHiddenWindows, Last Found
Window, IfWinExist, IfWinActive, WinWaitActive, WinWait, GroupActivate
Example
IfWinExist, Untitled - Notepad
WinClose ; use the window found above
else
WinClose, Calculator
WinGet
Retrieves the specified window's unique ID, process ID, process name, or a list of its controls. It can
also retrieve a list of all windows matching the specified criteria.
WinGet, OutputVar [, Cmd, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
OutputVar The name of the variable in which to store the result of Cmd.
Cmd See list below.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the other 3 parameters are
omitted, the Last Found Window will be used. To use a window class, specify
ahk_class ExactClassName (shown by Window Spy). To use a process identifier
(PID), specify ahk_pid %VarContainingPID%. To use a window's unique ID
number, specify ahk_id %VarContainingID%.
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
Cmd is the operation to perform, which if blank defaults to ID. It can be one of the following words:
ID: Retrieves the unique ID number (HWND/handle) of a window. If there is no matching window,
OutputVar is made blank. The functions WinExist() and WinActive() can also be used to retrieve the ID
of a window; for example, WinExist("A") is a fast way to get the ID of the active window. To discover
the HWND of a control (for use with Post/SendMessage or DllCall), use ControlGet Hwnd or
MouseGetPos.
IDLast: Same as above except it retrieves the ID of the last/bottommost window if there is more than
one match. If there is only one match, it performs identically to ID. This concept is similar to that used
by WinActivateBottom.
PID: Retrieves the Process ID (PID) of a window.
Printed Documentation
538
ProcessName: Retrieves the name of the process (e.g. notepad.exe) that owns a window. If there
are no matching windows, OutputVar is made blank.
Count: Retrieves the number of existing windows that match the specified WinTitle, WinText,
ExcludeTitle, and ExcludeText (0 if none). To count all windows on the system, omit all four title/text
parameters. Hidden windows are included only if DetectHiddenWindows has been turned on.
List: Retrieves the unique ID numbers of all existing windows that match the specified WinTitle,
WinText, ExcludeTitle, and ExcludeText (to retrieve all windows on the entire system, omit all four
title/text parameters). Each ID number is stored in an array element whose name begins with
OutputVar's own name, while OutputVar itself is set to the number of retrieved items (0 if none). For
example, if OutputVar is MyArray and two matching windows are discovered, MyArray1 will be set to
the ID of the first window, MyArray2 will be set to the ID of the second window, and MyArray itself will
be set to the number 2. Windows are retrieved in order from topmost to bottommost (according to
how they are stacked on the desktop). Hidden windows are included only if DetectHiddenWindows has
been turned on. Within a function, to create an array that is global instead of local, declare MyArray as
a global variable prior to using this command (the converse is true for assume-global functions).
MinMax: Retrieves the minimized/maximized state for a window. OuputVar is made blank if no
matching window exists; otherwise, it is set to one of the following numbers:
-1: The window is minimized (WinRestore can unminimize it).
1: The window is maximized (WinRestore can unmaximize it).
0: The window is neither minimized nor maximized.
ControlList: Retrieves the control names for all controls in a window. If no matching window exists or
there are no controls in the window, OutputVar is made blank. Otherwise, each control name consists
of its class name followed immediately by its sequence number (ClassNN), as shown by Window Spy.
Each item except the last is terminated by a linefeed (`n). To examine the individual control names
one by one, use a parsing loop as shown in the examples section below.
Controls are sorted according to their Z-order, which is usually the same order as TAB key navigation
if the window supports tabbing.
The control currently under the mouse cursor can be retrieved via MouseGetPos.
ControlListHwnd [v1.0.43.06+]: Same as above except it retrieves the window handle (HWND) of
each control rather than its ClassNN.
Transparent: Retrieves the degree of transparency of a window (see WinSet for how to set
transparency). OutputVar is made blank if: 1) the OS is older than Windows XP; 2) there are no
matching windows; 3) the window has no transparency level; or 4) other conditions (caused by OS
behavior) such as the window having been minimized, restored, and/or resized since it was made
transparent. Otherwise, a number between 0 and 255 is stored, where 0 indicates an invisible window
and 255 indicates an opaque window. For example:
MouseGetPos,,, MouseWin
WinGet, Transparent, Transparent, ahk_id %MouseWin% ; Transparency of window under the
mouse cursor.
TransColor: Retrieves the color that is marked transparent in a window (see WinSet for how to set
the TransColor). OutputVar is made blank if: 1) the OS is older than Windows XP; 2) there are no
matching windows; 3) the window has no transparent color; or 4) other conditions (caused by OS
behavior) such as the window having been minimized, restored, and/or resized since it was made
transparent. Otherwise, a six-digit hexadecimal RGB color is stored, e.g. 0x00CC99. For example:
MouseGetPos,,, MouseWin
WinGet, TransColor, TransColor, ahk_id %MouseWin% ; TransColor of the window under the
mouse cursor.
Style or ExStyle: Retrieves an 8-digit hexadecimal number representing style or extended style
(respectively) of a window. If there are no matching windows, OutputVar is made blank. The following
example determines whether a window has the WS_DISABLED style:
Window Management
539
WinGet, Style, Style, My Window Title
if (Style & 0x8000000) ; 0x8000000 is WS_DISABLED.
... the window is disabled, so perform appropriate action.
The next example determines whether a window has the WS_EX_TOPMOST style (always-on-top):
WinGet, ExStyle, ExStyle, My Window Title
if (ExStyle & 0x8) ; 0x8 is WS_EX_TOPMOST.
... the window is always-on-top, so perform appropriate action.
See the styles table for a partial listing of styles.
Remarks
A window's ID number is valid only during its lifetime. In other words, if an application restarts, all of
its windows will get new ID numbers.
ID numbers retrieved by this command are numeric (the prefix "ahk_id" is not included) and are
stored in hexadecimal format regardless of the setting of SetFormat.
The ID of the window under the mouse cursor can be retrieved with MouseGetPos.
Although ID numbers are currently 32-bit unsigned values, they may become 64-bit in future
versions. Therefore, it is unsafe to perform numerical operations such as addition on these values
because such operations require that their input strings be parsable as signed rather than unsigned
values.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
WinGetClass, Process, WinGetTitle, MouseGetPos, ControlGet, ControlFocus, GroupAdd
Examples
; Example #1: Maximize the active window and report its unique ID:
WinGet, active_id, ID, A
WinMaximize, ahk_id %active_id%
MsgBox, The active window's ID is "%active_id%".

; Example #2: This will visit all windows on the entire system and display info about each of them:
WinGet, id, list,,, Program Manager
Loop, %id%
{
this_id := id%A_Index%
WinActivate, ahk_id %this_id%
WinGetClass, this_class, ahk_id %this_id%
WinGetTitle, this_title, ahk_id %this_id%
MsgBox, 4, , Visiting All Windows`n%a_index% of %id%`nahk_id %this_id%`nahk_class
%this_class%`n%this_title%`n`nContinue?
IfMsgBox, NO, break
Printed Documentation
540
}

; Example #3: Extract the individual control names from a ControlList:
WinGet, ActiveControlList, ControlList, A
Loop, Parse, ActiveControlList, `n
{
MsgBox, 4,, Control #%a_index% is "%A_LoopField%". Continue?
IfMsgBox, No
break
}

; Example #4: Display in real time the active window's control list:
#Persistent
SetTimer, WatchActiveWindow, 200
return
WatchActiveWindow:
WinGet, ControlList, ControlList, A
ToolTip, %ControlList%
return
WinGetActiveStats
Combines the functions of WinGetActiveTitle and WinGetPos into one command.
WinGetActiveStats, Title, Width, Height, X, Y
Parameters
Title The name of the variable in which to store the title of the active window.
Width/Height
The names of the variables in which to store the width and height of the active
window.
X, Y
The names of the variables in which to store the X and Y coordinates of the
active window's upper left corner.
Remarks
If no matching window is found, the output variables will be made blank.
This command is equivalent to the following sequence:
WinGetTitle, Title, A
WinGetPos, X, Y, Width, Height, A
If the active window is a hidden window and DetectHiddenWindows is off (the default), all commands
except WinShow will fail to "see" it. If there is no active window for this reason or any other, this
command will set all of its output variables to be blank.
Related
WinGetPos, WinGetActiveTitle, WinGetTitle, WinGetClass, WinGetText, ControlGetText
Window Management
541
Example
WinGetActiveStats, Title, Width, Height, X, Y
MsgBox, The active window "%Title%" is %Width% wide`, %Height% tall`, and positioned at
%X%`,%Y%.
WinGetActiveTitle
Retrieves the title of the active window.
WinGetActiveTitle, OutputVar
Parameters
OutputVar The name of the variable in which to store the title of the active window.
Remarks
This command is equivalent to: WinGetTitle, OutputVar, A
Related
WinGetPos, WinGetActiveStats, WinGetTitle, WinGetClass, WinGetText, ControlGetText
Example
WinGetActiveTitle, Title
MsgBox, The active window is "%Title%".
WinGetClass
Retrieves the specified window's class name.
WinGetClass, OutputVar [, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
OutputVar The name of the variable in which to store the retrieved class name.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the next 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
next 3 parameters are omitted, the active window will be used. To use a
process identifier (PID), specify ahk_pid %VarContainingPID%. To use a
window group, specify ahk_group GroupName. To use a window's unique ID
number, specify ahk_id %VarContainingID%. The search can be narrowed by
specifying multiple criteria. For example: My File.txt ahk_pid
%VarContainingPID%
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
Remarks
Only the class name is retrieved (the prefix "ahk_class" is not included in OutputVar).
Printed Documentation
542
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
WinGet, WinGetTitle
Example
WinGetClass, class, A
MsgBox, The active window's class is "%class%".
WinGetPos
Retrieves the position and size of the specified window.
WinGetPos [, X, Y, Width, Height, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
X, Y
The names of the variables in which to store the X and Y coordinates of the
target window's upper left corner. If omitted, the corresponding values will not
be stored.
Width/Height
The names of the variables in which to store the width and height of the target
window. If omitted, the corresponding values will not be stored.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the next 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
next 3 parameters are omitted, the active window will be used. To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a process identifier (PID), specify ahk_pid %VarContainingPID%. To use a
window group, specify ahk_group GroupName. To use a window's unique ID
number, specify ahk_id %VarContainingID%. The search can be narrowed by
specifying multiple criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
Remarks
If no matching window is found, the output variables will be made blank.
If the WinTitle Program Manager is used, the command will retrieve the size of the desktop, which is
usually the same as the current screen resolution.
A minimized window will still have a position and size. The values returned in this case may vary
depending on OS and configuration.
To discover the name of the window and control that the mouse is currently hovering over, use
MouseGetPos.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
Window Management
543
WinMove, ControlGetPos, WinGetActiveStats, WinGetActiveTitle, WinGetTitle, WinGetText,
ControlGetText
Example
WinGetPos, X, Y, Width, Height, Calculator
MsgBox, Calculator is at %X%`,%Y%

WinGetPos, X, Y, , , A ; "A" to get the active window's pos.
MsgBox, The active window is at %X%`,%Y%

IfWinExist, Untitled - Notepad
{
WinGetPos, Xpos, Ypos ; Uses the window found above.
MsgBox, Notepad is at %Xpos%`,%Ypos%
}
WinGetText
Retrieves the text from the specified window.
WinGetText, OutputVar [, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
OutputVar The name of the variable in which to store the retrieved text.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the next 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
next 3 parameters are omitted, the active window will be used. To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a process identifier (PID), specify ahk_pid %VarContainingPID%. To use a
window group, specify ahk_group GroupName. To use a window's unique ID
number, specify ahk_id %VarContainingID%. The search can be narrowed by
specifying multiple criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
ErrorLevel
ErrorLevel is set to 1 if there was a problem or 0 otherwise.
Remarks
The text retrieved is generally the same as what Window Spy shows for that window. However, if
DetectHiddenText has been turned off, hidden text is omitted from OutputVar.
Printed Documentation
544
Each text element ends with a carriage return and linefeed (CR+LF), which can be represented in the
script as `r`n. To extract individual lines or substrings, use commands such as StringGetPos and
StringMid. A parsing loop can also be used to examine each line or word one by one.
If the retrieved text appears to be truncated (incomplete), try using VarSetCapacity(OutputVar, 55)
prior to WinGetText [replace 55 with a size that is considerably longer than the truncated text]. This is
necessary because some applications do not respond properly to the WM_GETTEXTLENGTH message,
which causes AutoHotkey to make the output variable too small to fit all the text.
The amount of text retrieved is limited to a variable's maximum capacity (which can be changed via
the #MaxMem directive). As a result, this command might use a large amount of RAM if the target
window (e.g. an editor with a large document open) contains a large quantity of text. To avoid this, it
might be possible to retrieve only portions of the window's text by using ControlGetText instead. In
any case, a variable's memory can be freed later by assigning it to nothing, i.e. OutputVar =
Windows 95/98/ME may be limited to 64 KB for some text elements of certain windows.
To retrieve a list of all controls in a window, follow this example: WinGet, OutputVar, ControlList,
WinTitle
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
ControlGetText, WinGetActiveStats, WinGetActiveTitle, WinGetTitle, WinGetPos, #MaxMem
Example
Run, Calc.exe
WinWait, Calculator
WinGetText, text ; The window found above will be used.
MsgBox, The text is:`n%text%
WinGetTitle
Retrieves the title of the specified window.
WinGetTitle, OutputVar [, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
OutputVar The name of the variable in which to store the retrieved title.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the next 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
next 3 parameters are omitted, the active window will be used. To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a process identifier (PID), specify ahk_pid %VarContainingPID%. To use a
window group, specify ahk_group GroupName. To use a window's unique ID
number, specify ahk_id %VarContainingID%. The search can be narrowed by
specifying multiple criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
Window Management
545
Remarks
To discover the name of the window that the mouse is currently hovering over, use MouseGetPos.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
WinGetActiveStats, WinGetActiveTitle, WinGetClass, WinGet, WinGetText, ControlGetText, WinGetPos
Example
WinGetTitle, Title, A
MsgBox, The active window is "%Title%".
WinHide
Hides the specified window.
WinHide [, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the other 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
other 3 parameters are omitted, the active window will be used. To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a process identifier (PID), specify ahk_pid %VarContainingPID%. To hide a
group of windows, specify ahk_group GroupName (WinText, ExcludeTitle, and
ExcludeText must be blank in this case). To use a window's unique ID number,
specify ahk_id %VarContainingID%. The search can be narrowed by specifying
multiple criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
Remarks
Use WinShow to unhide a hidden window (DetectHiddenWindows can be either On or Off to do this).
This command operates only upon the topmost matching window except when WinTitle is ahk_group
GroupName, in which case all windows in the group are affected.
The Explorer taskbar may be hidden/shown as follows:
WinHide ahk_class Shell_TrayWnd
WinShow ahk_class Shell_TrayWnd
Related
WinShow, SetTitleMatchMode, DetectHiddenWindows, Last Found Window, WinSet
Example
Run, notepad.exe
Printed Documentation
546
WinWait, Untitled - Notepad
Sleep, 500
WinHide ; use the window found above
Sleep, 1000
WinShow
WinKill
Forces the specified window to close.
WinKill [, WinTitle, WinText, SecondsToWait, ExcludeTitle, ExcludeText]
Parameters
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the other 3 window
parameters are blank or omitted, the Last Found Window will be used. If this
is the letter A and the other 3 window parameters are blank or omitted, the
active window will be used. To use a window class, specify ahk_class
ExactClassName (shown by Window Spy). To use a process identifier (PID),
specify ahk_pid %VarContainingPID%. To kill a group of windows, specify
ahk_group GroupName (WinText, ExcludeTitle, and ExcludeText must be
blank in this case). To use a window's unique ID number, specify ahk_id
%VarContainingID%. The search can be narrowed by specifying multiple
criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
SecondsToWait
If omitted or blank, the command will not wait at all. If 0, it will wait 500ms.
Otherwise, it will wait the indicated number of seconds (can contain a
decimal point or be an expression) for the window to close. If the window
does not close within that period, the script will continue. ErrorLevel is not
set by this command, so use IfWinExist or WinWaitClose if you need to
determine for certain that a window is closed.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
Remarks
This command first makes a brief attempt to close the window normally. If that fails, it will attempt to
force the window closed by terminating its process.
If a matching window is active, that window will be closed in preference to any other matching window
beneath it. In general, if more than one window matches, the topmost (most recently used) will be
closed.
This command operates only upon the topmost matching window except when WinTitle is ahk_group
GroupName, in which case all windows in the group are affected.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
WinClose, WinWaitClose, Process, WinActivate, SetTitleMatchMode, DetectHiddenWindows, Last Found
Window, IfWinExist, IfWinActive, WinWaitActive, WinWait, GroupActivate
Window Management
547
Example
IfWinExist, Untitled - Notepad
WinKill ; use the window found above
else
WinKill, Calculator
WinMaximize
Enlarges the specified window to its maximum size.
WinMaximize [, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the next 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
next 3 parameters are omitted, the active window will be used. To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a process identifier (PID), specify ahk_pid %VarContainingPID%. To
maximize a group of windows, specify ahk_group GroupName (WinText,
ExcludeTitle, and ExcludeText must be blank in this case). To use a window's
unique ID number, specify ahk_id %VarContainingID%. The search can be
narrowed by specifying multiple criteria. For example: My File.txt ahk_class
Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
Remarks
Use WinRestore to unmaximize a window and WinMinimize to minimize it.
If a particular type of window does not respond correctly to WinMaximize, try using the following
instead:
PostMessage, 0x112, 0xF030,,, WinTitle, WinText ; 0x112 = WM_SYSCOMMAND, 0xF030 =
SC_MAXIMIZE
This command operates only upon the topmost matching window except when WinTitle is ahk_group
GroupName, in which case all windows in the group are affected.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
WinRestore, WinMinimize
Example
Run, notepad.exe
WinWait, Untitled - Notepad
Printed Documentation
548
WinMaximize ; use the window found above

^Up::WinMaximize, A ; Assign a hotkey to maximize the active window.
WinMinimize
Collapses the specified window into a button on the task bar.
WinMinimize [, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the next 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
next 3 parameters are omitted, the active window will be used. To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a process identifier (PID), specify ahk_pid %VarContainingPID%. To
minimize a group of windows, specify ahk_group GroupName (WinText,
ExcludeTitle, and ExcludeText must be blank in this case). To use a window's
unique ID number, specify ahk_id %VarContainingID%. The search can be
narrowed by specifying multiple criteria. For example: My File.txt ahk_class
Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
Remarks
Use WinRestore or WinMaximize to unminimize a window.
If a particular type of window does not respond correctly to WinMinimize, try using the following
instead:
PostMessage, 0x112, 0xF020,,, WinTitle, WinText ; 0x112 = WM_SYSCOMMAND, 0xF020 =
SC_MINIMIZE
This command operates only upon the topmost matching window except when WinTitle is ahk_group
GroupName, in which case all windows in the group are affected.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
WinRestore, WinMaximize, WinMinimizeAll
Example
Run, notepad.exe
WinWait, Untitled - Notepad
WinMinimize ; use the window found above

^Down::WinMinimize, A ; Assign a hotkey to minimize the active window.
Window Management
549
WinMinimizeAll / WinMinimizeAllUndo
Minimizes or unminimizes all windows.
WinMinimizeAll
WinMinimizeAllUndo
On most systems, this is equivalent to Explorer's Win-M and Win-D hotkeys.
Related
WinMinimize, GroupAdd
Example
WinMinimizeAll
WinMinimizeAllUndo
WinMove
Changes the position and/or size of the specified window.
WinMove, X, Y
WinMove, WinTitle, WinText, X, Y [, Width, Height, ExcludeTitle, ExcludeText]
Parameters
X, Y
The X and Y coordinates (in pixels) of the upper left corner of the target
window's new location, which can be expressions. The upper-left pixel of the
screen is at 0, 0.
If these are the only parameters given with the command, the Last Found
Window will be used as the target window.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the other 3 window parameters
are blank or omitted, the Last Found Window will be used. If this is the letter A
and the other 3 window parameters are blank or omitted, the active window
will be used. To use a window class, specify ahk_class ExactClassName (shown
by Window Spy). To use a process identifier (PID), specify ahk_pid
%VarContainingPID%. To use a window group, specify ahk_group GroupName.
To use a window's unique ID number, specify ahk_id %VarContainingID%. The
search can be narrowed by specifying multiple criteria. For example: My
File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
Width,
Height
The new width and height of the window (in pixels), which can be expressions.
If either is omitted, blank, or the word DEFAULT, the size in that dimension will
not be changed.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
Remarks
Printed Documentation
550
If Width and Height are small (or negative), the window will go no smaller than 112 x 27 pixels. If
Width and Height are large, the window will go no larger than approximately 12 pixels beyond the
dimensions of the desktop.
Negative values are allowed for the x and y coordinates to support multi-monitor systems and to allow
a window to be moved entirely off screen.
Although WinMove cannot move minimized windows, it can move hidden windows if
DetectHiddenWindows is on.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
ControlMove, WinGetPos, WinHide, WinMinimize, WinMaximize, WinSet
Example
Run, calc.exe
WinWait, Calculator
WinMove, 0, 0 ; Move the window found by WinWait to the upper-left corner of the screen.

SplashTextOn, 400, 300, Clipboard, The clipboard contains:`n%clipboard%
WinMove, Clipboard, , 0, 0 ; Move the splash window to the top left corner.
Msgbox, Press OK to dismiss the SplashText
SplashTextOff

; The following function centers the specified window on the screen:
CenterWindow(WinTitle)
{
WinGetPos,,, Width, Height, %WinTitle%
WinMove, %WinTitle%,, (A_ScreenWidth/2)-(Width/2), (A_ScreenHeight/2)-(Height/2)
}
WinRestore
Unminimizes or unmaximizes the specified window if it is minimized or maximized.
WinRestore [, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the next 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
next 3 parameters are omitted, the active window will be used. To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a process identifier (PID), specify ahk_pid %VarContainingPID%. To
restore a group of windows, specify ahk_group GroupName (WinText,
ExcludeTitle, and ExcludeText must be blank in this case). To use a window's
unique ID number, specify ahk_id %VarContainingID%. The search can be
Window Management
551
narrowed by specifying multiple criteria. For example: My File.txt ahk_class
Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
Remarks
If a particular type of window does not respond correctly to WinRestore, try using the following
instead:
PostMessage, 0x112, 0xF120,,, WinTitle, WinText ; 0x112 = WM_SYSCOMMAND, 0xF120 =
SC_RESTORE
This command operates only upon the topmost matching window except when WinTitle is ahk_group
GroupName, in which case all windows in the group are affected.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
WinMinimize, WinMaximize
Example
WinRestore, Untitled - Notepad
WinSet
Makes a variety of changes to the specified window, such as "always on top" and transparency.
WinSet, Attribute, Value [, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
Attribute,
Value
See list below.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the next 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
next 3 parameters are omitted, the active window will be used. To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a process identifier (PID), specify ahk_pid %VarContainingPID%. To use a
window group, specify ahk_group GroupName. To use a window's unique ID
number, specify ahk_id %VarContainingID%. The search can be narrowed by
specifying multiple criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
Attribute, Value
Printed Documentation
552
AlwaysOnTop, [On|Off|Toggle]: Makes a window stay on top of all other windows. Use ON to turn
on the setting, OFF to turn it off, or TOGGLE to set it to the opposite of its current state. If omitted, it
defaults to TOGGLE. The word Topmost can be used in place of AlwaysOnTop.
Bottom: Sends a window to the bottom of stack; that is, beneath all other windows. The effect is
similar to pressing Alt-Escape. For example: WinSet, Bottom,, WinTitle
Top [v1.0.36.01+]: Brings a window to the top of the stack without explicitly activating it. However,
the system default settings will probably cause it to activate in most cases. In addition, this command
may have no effect due to the operating system's protection against applications that try to steal
focus from the user (it may depend on factors such as what type of window is currently active and
what the user is currently doing). One possible work-around is to make the window briefly
AlwaysOnTop, then turn off AlwaysOnTop.
Disable or Enable: Disables or enables a window (respectively). When a window is disabled, the user
cannot move it or interact with its controls. In addition, disabled windows are omitted from the alt-tab
list.
Redraw: Attempts to update the appearance/contents of a window by informing the OS that the
window's rectangle needs to be redrawn. If this method does not work for a particular window, try
WinMove. If that does not work, try the following:
WinHide, WinTitle
WinShow, WinTitle

Style,N or ExStyle,N: Changes the style or extended style of a window, respectively. If the first
character of N is a plus or minus sign, the style(s) in N are added or removed, respectively. If the first
character is a caret (^), the style(s) in N are each toggled to the opposite state. If the first character
is a digit, the window's style is overwritten completely; that is, it becomes N.
ErrorLevel is set to 1 upon failure and 0 upon success. Failure occurs if the target window is not found
or the style is not allowed to be applied (which happens more often on Windows 9x).
After applying certain style changes to a visible window, it might be necessary to redraw the window
using WinSet Redraw (see below). Finally, the styles table lists some of the common style numbers.
Examples:
WinSet, Style, -0xC00000, A ; Remove the active window's title bar (WS_CAPTION).
WinSet, ExStyle, ^0x80, WinTitle ; Toggle the WS_EX_TOOLWINDOW attribute, which
removes/adds the window from the alt-tab list.

Region [, Options]: Changes the shape of a window to be the specified rectangle, ellipse, or
polygon. If the Options parameter is blank, the window is restored to its original/default display area.
Otherwise, one or more of the following options can be specified, each separated from the others with
space(s):
Wn: Width of rectangle or ellipse. For example: w200
Hn: Height of rectangle or ellipse. For example: h300
X-Y: Each of these is a pair of X/Y coordinates. For example, 200-0 would use 200 for the X
coordinate and 0 for the Y.
E: Makes the region an ellipse rather than a rectangle. This option is valid only when W and H are
present.
R[w-h]: Makes the region a rectangle with rounded corners. For example, R30-30 would use a 30x30
ellipse for each corner. If w-h is omitted, 30-30 is used. R is valid only when W and H are present.
Rectangle or ellipse: If the W and H options are present, the new display area will be a rectangle
whose upper left corner is specified by the first (and only) pair of X-Y coordinates. However, if the E
option is also present, the new display area will be an ellipse rather than a rectangle. For example:
WinSet, Region, 50-0 W200 H250 E, WinTitle
Polygon: When the W and H options are absent, the new display area will be a polygon determined by
multiple pairs of X-Y coordinates (each pair of coordinates is a point inside the window relative to its
upper left corner). For example, if three pairs of coordinates are specified, the new display area will be
Window Management
553
a triangle in most cases. The order of the coordinate pairs with respect to each other is sometimes
important. In addition, the word Wind maybe be present in Options to use the winding method
instead of the alternating method to determine the polygon's region.
ErrorLevel is set to 1 upon failure and 0 upon success. Failure occurs when: 1) the target window does
not exist; 2) one or more Options are invalid; 3) more than 2000 pairs of coordinates were specified;
or 4) the specified region is invalid or could not be applied to the target window; 5) the version is
earlier than 1.0.38.02 and an X-coordinate has a leading plus or minus sign.
See the bottom of this page for examples of how to use this command.

Transparent, N: Makes a window semi-transparent. Specify for N a number between 0 and 255 to
indicate the degree of transparency: 0 makes the window invisible while 255 makes it opaque.
Transparency may be turned off completely for a window by specifying the word OFF. This is different
than specifying 255 because it may improve performance and reduce usage of system resources. This
command has no effect on Windows 9x and NT4.
Setting "Transparent" to 255 prior to turning it off might avoid window redrawing problems such as a
black background. If the window still fails to be redrawn correctly, see Redraw for a possible
workaround.
To make the task bar transparent, use WinSet, Transparent, 150, ahk_class Shell_TrayWnd. Similarly,
to make the Start Menu transparent, follow this example:
DetectHiddenWindows, on
WinSet, Transparent, 150, ahk_class BaseBar ; To make the Start Menu's submenus
transparent, also include the script below.
To make all or selected menus on the entire system transparent, keep a script such as the following
always running. Note that although such a script cannot make its own menus transparent, it can make
those of other scripts transparent:
#Persistent
SetTimer, WatchForMenu, 5
return ; End of auto-execute section.

WatchForMenu:
DetectHiddenWindows, on ; Might allow detection of menu sooner.
IfWinExist, ahk_class #32768
WinSet, Transparent, 150 ; Uses the window found by the above line.
return
TransColor, Color [N]: Makes all pixels of the chosen color invisible inside the target window, which
allows the contents of the window behind it to show through (has no effect on Windows 9x and NT4).
If the user clicks on an invisible pixel, the click will "fall through" to the window behind it. Specify for
Color a color name or RGB value (see the color chart for guidance, or use PixelGetColor in its RGB
mode). To additionally make the visible part of the window partially transparent, append a space (not
a comma) followed by the transparency level (0-255). For example: WinSet, TransColor, EEAA99 150,
WinTitle
TransColor is often used to create on-screen displays and other visual effects. There is an example of
an on-screen display near the bottom of the Gui page.
The word OFF may be specified to completely turn off transparency for a window. Both of the following
are identical in function:
WinSet, Transparent, Off, WinTitle
WinSet, TransColor, Off, WinTitle
Printed Documentation
554
To change a window's existing TransColor, it is probably necessary to turn off transparency before
making the change. In addition, if the caption is to be removed from a Gui window via Gui -Caption, it
should be removed only after setting the TransColor.
Remarks
ErrorLevel is not changed by this command except where indicated above.
Although transparency is supported on Windows 2000/XP or later, retrieving the current transparency
settings of a window is possible only on Windows XP or later (via WinGet).
A script's SplashText window can be made non-AlwaysOnTop via:
WinSet, AlwaysOnTop, Off, My Splash Window Title
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
WinGet, WinHide, WinSetTitle, WinMove, WinActivate, Control
Examples
WinSet, Transparent, 200, Untitled - Notepad ; Make the window a little bit transparent.
WinSet, TransColor, White, Untitled - Notepad ; Make all white pixels invisible.
WinSet, AlwaysOnTop, toggle, Calculator ; Toggle the always-on-top status of Calculator.

; Longer Example:
; Here are some hotkeys that demonstrate the effects of "Transparent" and
; "TransColor". NOTE: If you press one of the hotkeys while the mouse cursor
; is hovering over a pixel that is invisible as a result of TransColor, the window
; visible beneath that pixel will be acted upon instead! Also, Win+G will
; have an effect only on Windows XP because retrieval of transparency settings
; is not supported by Windows 2000:

#t:: ; Press Win+T to make the color under the mouse cursor invisible.
MouseGetPos, MouseX, MouseY, MouseWin
PixelGetColor, MouseRGB, %MouseX%, %MouseY%, RGB
; In seems necessary to turn off any existing transparency first:
WinSet, TransColor, Off, ahk_id %MouseWin%
WinSet, TransColor, %MouseRGB% 220, ahk_id %MouseWin%
return

#o:: ; Press Win+O to turn off transparency for the window under the mouse.
MouseGetPos,,, MouseWin
WinSet, TransColor, Off, ahk_id %MouseWin%
return
Window Management
555

#g:: ; Press Win+G to show the current settings of the window under the mouse.
MouseGetPos,,, MouseWin
WinGet, Transparent, Transparent, ahk_id %MouseWin%
WinGet, TransColor, TransColor, ahk_id %MouseWin%
ToolTip Translucency:`t%Transparent%`nTransColor:`t%TransColor%
return

; Examples of "WinSet Region":
WinSet, Region, 50-0 W200 H250, WinTitle ; Make all parts of the window outside this rectangle
invisible.
WinSet, Region, 50-0 W200 H250 R40-40, WinTitle ; Same as above but with corners rounded to
40x40.
WinSet, Region, 50-0 W200 H250 E, WinTitle ; An ellipse instead of a rectangle.
WinSet, Region, 50-0 250-0 150-250, WinTitle ; A triangle with apex pointing down.
WinSet, Region,, WinTitle ; Restore the window to its original/default display area.

; Here is a region with a more complex area. It creates a see-through rectangular hole inside a
window.
; There are two rectangles specified below: an outer and an inner. Each rectangle consists of 5 pairs
; of X/Y coordinates because the first pair is repeated at the end to "close off" each rectangle.
WinSet, Region, 0-0 300-0 300-300 0-300 0-0 100-100 200-100 200-200 100-200 100-100,
WinTitle
WinSetTitle
Changes the title of the specified window.
WinSetTitle, NewTitle
WinSetTitle, WinTitle, WinText, NewTitle [, ExcludeTitle, ExcludeText]
Parameters
NewTitle
The new title for the window. If this is the only parameter given, the Last
Found Window will be used.
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the next 3 parameters are
omitted, the Last Found Window will be used. If this is the letter A and the
next 3 parameters are omitted, the active window will be used. To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a process identifier (PID), specify ahk_pid %VarContainingPID%. To use a
window group, specify ahk_group GroupName. To use a window's unique ID
number, specify ahk_id %VarContainingID%. The search can be narrowed by
specifying multiple criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
Printed Documentation
556
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
Remarks
A change to a window's title might be merely temporary if the application that owns the window
frequently changes the title.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
WinMove, WinGetActiveStats, WinGetActiveTitle, WinGetText, ControlGetText, WinGetPos, WinSet
Example
WinSetTitle, Untitled - Notepad, , This is a new title

; Alternate:
Run, notepad.exe
WinWaitActive, Untitled - Notepad
WinSetTitle, This is a new title ; Uses the window found above by WinWaitActive
WinShow
Unhides the specified window.
WinShow [, WinTitle, WinText, ExcludeTitle, ExcludeText]
Parameters
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the other 3 parameters are
omitted, the Last Found Window will be used. To use a window class, specify
ahk_class ExactClassName (shown by Window Spy). To use a process identifier
(PID), specify ahk_pid %VarContainingPID%. To show a group of windows,
specify ahk_group GroupName (WinText, ExcludeTitle, and ExcludeText must
be blank in this case). To use a window's unique ID number, specify ahk_id
%VarContainingID%. The search can be narrowed by specifying multiple
criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
Remarks
By default, WinShow is the only command that can always detect hidden windows. Other commands
can detect them only if DetectHiddenWindows has been turned on.
This command operates only upon the topmost matching window except when WinTitle is ahk_group
GroupName, in which case all windows in the group are affected.
Window Management
557
Related
WinHide, SetTitleMatchMode, DetectHiddenWindows, Last Found Window
Example
Run, notepad.exe
WinWait, Untitled - Notepad
Sleep, 500
WinHide ; Because its parameter is omitted, it uses the window found above.
Sleep, 1000
WinShow
WinWait
Waits until the specified window exists.
WinWait [, WinTitle, WinText, Seconds, ExcludeTitle, ExcludeText]
Parameters
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). To use a window class, specify ahk_class
ExactClassName (shown by Window Spy). To use a process identifier (PID),
specify ahk_pid %VarContainingPID%. To use a window group, specify
ahk_group GroupName. The search can be narrowed by specifying multiple
criteria. For example: My File.txt ahk_class Notepad
WinTitle may be blank only when WinText, ExcludeTitle, or ExcludeText is
present.
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
Seconds
How many seconds to wait before timing out and setting ErrorLevel to 1. Leave
blank to wait indefinitely. Specifying 0 is the same as specifying 0.5. This
parameter can be an expression.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
ErrorLevel
ErrorLevel is set to 1 if the command timed out or 0 otherwise.
Remarks
If a matching window comes into existence, the command will not wait for Seconds to expire. Instead,
it will immediately set ErrorLevel to 0, update the Last Found Window, and the script will continue
executing.
While the command is in a waiting state, new threads can be launched via hotkey, custom menu item,
or timer.
Printed Documentation
558
If another thread changes the contents of any variable(s) that were used for this command's
parameters, the command will not see the change -- it will continue to use the title and text that were
originally present in the variables when the command first started waiting.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
WinWaitActive, WinWaitClose, IfWinExist, IfWinActive, Process, SetTitleMatchMode,
DetectHiddenWindows
Example
Run, notepad.exe
WinWait, Untitled - Notepad, , 3
if ErrorLevel
{
MsgBox, WinWait timed out.
return
}
else
WinMinimize ; Minimize the window found by WinWait.
WinWaitActive / WinWaitNotActive
Waits until the specified window is active or not active.
WinWaitActive [, WinTitle, WinText, Seconds, ExcludeTitle, ExcludeText]
WinWaitNotActive [, WinTitle, WinText, Seconds, ExcludeTitle, ExcludeText]
Parameters
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the other 3 window parameters
are blank or omitted, the Last Found Window will be used. To use a window
class, specify ahk_class ExactClassName (shown by Window Spy). To use a
process identifier (PID), specify ahk_pid %VarContainingPID%. To use a
window group, specify ahk_group GroupName. To use a window's unique ID
number, specify ahk_id %VarContainingID%. The search can be narrowed by
specifying multiple criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
Seconds
How many seconds to wait before timing out and setting ErrorLevel to 1. Leave
blank to wait indefinitely. Specifying 0 is the same as specifying 0.5. This
parameter can be an expression.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
ErrorLevel
ErrorLevel is set to 1 if the command timed out or 0 otherwise.
Window Management
559
Remarks
If a matching window satisfies the command's expectation, the command will not wait for Seconds to
expire. Instead, it will immediately set ErrorLevel to 0 and the script will continue executing.
Both WinWaitActive and WinWaitNotActive will update the Last Found Window if a qualified window is
active when the command begins. In addition, WinWaitActive will update the Last Found Window if a
qualified window becomes active before the command times out.
While the command is in a waiting state, new threads can be launched via hotkey, custom menu item,
or timer.
If another thread changes the contents of any variable(s) that were used for this command's
parameters, the command will not see the change -- it will continue to use the title and text that were
originally present in the variables when the command first started waiting.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
WinWait, WinWaitClose, IfWinExist, IfWinActive, SetTitleMatchMode, DetectHiddenWindows
Example
Run, notepad.exe
WinWaitActive, Untitled - Notepad, , 2
if ErrorLevel
{
MsgBox, WinWait timed out.
return
}
else
WinMinimize ; minimize the window found by WinWaitActive.
WinWaitClose
Waits until the specified window does not exist.
WinWaitClose [, WinTitle, WinText, Seconds, ExcludeTitle, ExcludeText]
Parameters
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode). If this and the other 3 window parameters
are blank or omitted, the Last Found Window will be used. To use a window
class, specify ahk_class ExactClassName (shown by Window Spy). To use a
process identifier (PID), specify ahk_pid %VarContainingPID%. To use a
window group, specify ahk_group GroupName. To use a window's unique ID
number, specify ahk_id %VarContainingID%. The search can be narrowed by
specifying multiple criteria. For example: My File.txt ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText is ON.
Printed Documentation
560
Seconds
How many seconds to wait before timing out and setting ErrorLevel to 1. Leave
blank to wait indefinitely. Specifying 0 is the same as specifying 0.5. This
parameter can be an expression.
ExcludeTitle Windows whose titles include this value will not be considered.
ExcludeText Windows whose text include this value will not be considered.
ErrorLevel
ErrorLevel is set to 1 if the command timed out or 0 otherwise.
Remarks
Whenever no instances of the specified window exist, the command will not wait for Seconds to
expire. Instead, it will immediately set ErrorLevel to 0 and the script will continue executing.
While the command is in a waiting state, new threads can be launched via hotkey, custom menu item,
or timer.
If another thread changes the contents of any variable(s) that were used for this command's
parameters, the command will not see the change -- it will continue to use the title and text that were
originally present in the variables when the command first started waiting.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on.
Related
WinClose, WinWait, WinWaitActive, IfWinExist, IfWinActive, Process, SetTitleMatchMode,
DetectHiddenWindows
Example
Run, notepad.exe
WinWait, Untitled - Notepad
WinWaitClose ; Wait for the exact window found by WinWait to be closed.
MsgBox, Notepad is now closed.

561
#Directives
#AllowSameLineComments
Only for AutoIt v2 (.aut) scripts: Allows a comment to appear on the same line as a command.
#AllowSameLineComments
Specifying this directive at the top of any AutoIt v2 (.aut) script will enable the use of same-line
comments, which are normally disabled for compatibility reasons. If not used at the top of the script,
same-line comments are not supported above the point where the directive occurs.
Example
#AllowSameLineComments
Sleep, 1 ; This comment is a same-line comment.
#ClipboardTimeout
Changes how long the script keeps trying to access the clipboard when the first attempt fails.
#ClipboardTimeout Milliseconds
Parameters
Milliseconds
The length of the interval in milliseconds. Specify -1 to have it keep trying
indefinitely. Specify 0 to have it try only once. Scripts that do not contain this
directive use a 1000 ms timeout.
Remarks
Some applications keep the clipboard open for long periods of time, perhaps to write or read large
amounts of data. In such cases, increasing this setting causes the script to wait longer before giving
up and displaying an error message.
This settings applies to all clipboard operations, the simplest of which are the following examples:
Var = %Clipboard%
Clipboard = New Text
Whenever the script is waiting for the clipboard to become available, new threads cannot be launched
and timers will not run. However, if the user presses a hotkey, selects a custom menu item, or
performs a GUI action such as pressing a button, that event will be buffered until later; in other
words, its subroutine will be performed after the clipboard finally becomes available.
In v1.0.42.03+, this directive also causes the reading of clipboard data to be reattempted if the first
attempt fails (in prior versions, only the opening of the clipboard was reattempted).
Related
Clipboard, Thread
Example
#ClipboardTimeout 2000
#CommentFlag
Changes the script's comment symbol from semicolon to some other string.
#CommentFlag NewString
Printed Documentation
562
Parameters
NewString
One or more characters that should be used as the new comment flag. Up to
15 characters may be specified.
Remarks
The default comment flag is semicolon (;).
The comment flag is used to indicate that text that follows it should not be acted upon by the script
(comments are not loaded into memory when a script is launched, so they do not affect performance).
A comment flag that appears on the same line as a command is not considered to mark a comment
unless it has at least one space or tab to its left. For example:
MsgBox, Test1 ; This is a comment.
MsgBox, Test2; This is not a comment and will be displayed by MsgBox.
Related
#EscapeChar
Example
#CommentFlag // ; Change to C++ comment style.
#ErrorStdOut
Sends any syntax error that prevents a script from launching to stdout rather than displaying a dialog.
#ErrorStdOut
This allows fancy editors such as Textpad, Scite, Crimson, and EditPlus to jump to the offending line
when a syntax error occurs. See below for setup instructions.
Although syntax errors are sent to standard output (stdout), they cannot currently be displayed at the
command prompt. However, you can have the command prompt redirect the output to a file as in this
example:
"C:\Program Files\AutoHotkey\AutoHotkey.exe" /ErrorStdOut "My Script.ahk" >"Error Log.txt"
You can also pipe the output directly to the clipboard by downloading cb.zip (4 KB) and then following
this example:
"C:\Program Files\AutoHotkey\AutoHotkey.exe" /ErrorStdOut "My Script.ahk" |cb.exe
Since this directive would have to be added to every script, it's usually better to set up your editor to
use the command line parameter /ErrorStdOut when launching an AutoHotkey script.
Instructions for specific editors:
EditPlus:
From the menu bar, select Tools > Configure User Tools.
Press button: Add Tool > Program
Menu Text: Your choice
Command: C:\Program Files\AutoHotkey\AutoHotkey.exe
Argument: /ErrorStdOut "$(FilePath)"
Initial directory: $(FileDir)
Capture output: Yes
TextPad:
From the menu bar, select Configure > Preferences.
Expand the Tools entry.
Press the Add button and select "Program".
Copy and paste (adjust to your path): C:\Windows\System32\cmd.exe -- then press OK.
#Directives
563
Triple-click the newly added item (cmd.exe) in the ListBox and rename it to your choice (e.g. Launch
Script).
Press Apply.
Select the new item in the tree at the left and enter the following information:
Command (should already be filled in): cmd.exe (or the full path to it)
Parameters (adjust to your path, if necessary): /c ""C:\Program Files\AutoHotkey\AutoHotkey.exe"
/ErrorStdOut "$File""
Initial folder: $FileDir
Check the following boxes: 1) Run minimized; 2) Capture output.
Press OK. The newly added item should now exist in the Tools menu.
Related
FileAppend (because it can also send text to stdout)
Example
#ErrorStdOut
#EscapeChar (and explanation of escape sequences)
Changes the script's escape character (e.g. accent vs. backslash).
#EscapeChar NewChar
Parameters
NewChar Specify a single character.
Remarks
The escape character is used to indicate that the character immediately following it should be
interpreted differently than it normally would.
The default escape character for AutoIt v2 (.aut) scripts is backslash (\). For all other file extensions,
including all compiled scripts, the escape character defaults to accent/backtick (`). When a .aut script
is auto-converted into a .ahk script, the backslash escape character is globally replaced with the
accent character.
Escape Sequences (when accent is the escape
character)
Type This To Get This
`,
, (literal comma). Note: Commas that appear within the last parameter of a
command do not need to be escaped because the program knows to treat
them literally. The same is true for all parameters of MsgBox because it has
smart comma handling.
`% % (literal percent)
``
` (literal accent; i.e. two consecutive escape characters result in a single literal
character)
`;
; (literal semicolon). Note: This is necessary only if a semicolon has a space
or tab to its left. If it does not, it will be recognized correctly without being
escaped.
`::
:: (literal pair of colons). In v1.0.40+, it is no longer necessary to escape
these.
Printed Documentation
564
`n newline (linefeed/LF)
`r carriage return (CR)
`b backspace
`t tab (the more typical horizontal variety)
`v
vertical tab -- corresponds to Ascii value 11. It can also be manifest in some
applications by typing Control+K.
`a
alert (bell) -- corresponds to Ascii value 7. It can also be manifest in some
applications by typing Control+G.
`f
formfeed -- corresponds to Ascii value 12. It can also be manifest in some
applications by typing Control+L.
Send
When the Send command or Hotstrings are used in their default (non-raw)
mode, characters such as {}^!+# have special meaning. Therefore, to use
them literally in these cases, enclose them in braces. For example: Send
{^}{!}{{}
""
Within an expression, two consecutive quotes enclosed inside a literal string
resolve to a single literal quote. For example: Var := "The color ""red"" was
found."
Related
The following rarely used directives also exist; their usage is shown in these examples:
#DerefChar # ; Change it from its normal default, which is %.
#Delimiter / ; Change it from its normal default, which is comma.
Example
#EscapeChar \ ; Change it to be backslash instead of the default of accent (`).
#HotkeyInterval
Along with #MaxHotkeysPerInterval, specifies the rate of hotkey activations beyond which a warning
dialog will be displayed.
#HotkeyInterval Milliseconds
Parameters
Milliseconds The length of the interval in milliseconds.
Remarks
If this directive is unspecified in the script, it will behave as though set to 2000.
For details and remarks, see #MaxHotkeysPerInterval.
Related
#MaxHotkeysPerInterval
Example
#HotkeyInterval 2000 ; This is the default value (milliseconds).
#MaxHotkeysPerInterval 200
#Directives
565
#HotkeyModifierTimeout
Affects the behavior of hotkey modifiers: CTRL, ALT, WIN, and SHIFT.
#HotkeyModifierTimeout Milliseconds
Parameters
Milliseconds
The length of the interval in milliseconds. The value can be -1 so that it never
times out (modifier keys are always pushed back down after the Send), or 0 so
that it always times out (modifier keys are never pushed back down).
Remarks
This directive need not be used when:
Hotkeys send their keystrokes via the SendInput or SendPlay methods. This is because those
methods postpone the user's physical pressing and releasing of keys until after the Send
completes.
The script has the keyboard hook installed (you can see if your script uses the hook via the
"View->Key history" menu item in the main window, or via the KeyHistory command). This is
because the hook can keep track of which modifier keys (ALT/CTRL/WIN/SHIFT) the user is
physically holding down and doesn't need to use the timeout.
To illustrate the effect of this directive, consider this example:
^!a::Send, abc
When the Send command executes, the first thing it does is release the CTRL and ALT keys so that the
characters get sent properly. After sending all the keys, the command doesn't know whether it can
safely push back down CTRL and ALT (to match whether the user is still holding them down). But if
less than the specified number of milliseconds have elapsed, it will assume that the user hasn't had a
chance to release the keys yet and it will thus push them back down to match their physical state.
Otherwise, the modifier keys will not be pushed back down and the user will have to release and press
them again to get them to modify the same or another key.
The timeout should be set to a value less than the amount of time that the user typically holds down a
hotkey's modifiers before releasing them. Otherwise, the modifiers may be restored to the down
position (get stuck down) even when the user isn't physically holding them down.
You can reduce or eliminate the need for this directive with one of the following:
Install the keyboard hook by adding the line #InstallKeybdHook anywhere in the script
(however, the hook is not supported on Win9x).
Use the SendInput or SendPlay methods rather than the traditional SendEvent method.
When using the traditional SendEvent method, reduce SetKeyDelay to 0 or -1, which should
help because it sends the keystrokes more quickly.
If this is directive is unspecified in a script, it behaves as though set to 50.
Related
GetKeyState
Example
#HotkeyModifierTimeout 100
#Hotstring
Changes hotstring options or ending characters.
Printed Documentation
566
#Hotstring NoMouse
#Hotstring EndChars NewChars
#Hotstring NewOptions
Parameters
NoMouse
[v1.0.42.03+]
Prevents mouse clicks from resetting the hotstring recognizer as described
here. As a side-effect, this also prevents the mouse hook from being
required by hotstrings (though it will still be installed if the script requires it
for other purposes, such as mouse hotkeys). The presence of #Hotstring
NoMouse anywhere in the script affects all hotstrings, not just those
physically beneath it.
EndChars
NewChars
Specify the word EndChars followed a single space and then the new ending
characters. For example:
#Hotstring EndChars -()[]{}':;"/\,.?!`n `t
Since the new ending characters are in effect globally for the entire script --
regardless of where the EndChars directive appears -- there is no need to
specify EndChars more than once.
The maximum number of ending characters is 100. Characters beyond this
length are ignored.
To make tab an ending character, include `t in the list. To make space an
ending character, include it between two other characters in the list (or at
the beginning if the list contains only one other character, or no other
characters).
NewOptions
Specify new options as described in Hotstring Options. For example:
#Hotstring r s k0 c0
Unlike EndChars above, the #Hotstring directive is positional when used this
way. In other words, entire sections of hotstrings can have different default
options as in this example:
::btw::by the way

#Hotstring r c ; All the below hotstrings will use "send raw" and will
be case sensitive by default.
::al::airline
::CEO::Chief Executive Officer

#Hotstring c0 ; Make all hotstrings below this point case insensitive.
Related
Hotstrings
#IfWinActive / #IfWinExist [v1.0.41/42+]
Creates context-sensitive hotkeys and hotstrings. Such hotkeys perform a different action (or none at
all) depending on the type of window that is active or exists.
#IfWinActive [, WinTitle, WinText]
#IfWinExist [, WinTitle, WinText]
#Directives
567
#IfWinNotActive [, WinTitle, WinText]
#IfWinNotExist [, WinTitle, WinText]
Parameters
WinTitle
The title or partial title of the target window (the matching behavior is
determined by SetTitleMatchMode as set in the auto-execute section). To use a
window class, specify ahk_class ExactClassName (shown by Window Spy). To
use a window group, specify ahk_group GroupName. The ahk_pid and ahk_id
keywords are also supported, but it is more common for #IfWin to use them
indirectly via GroupAdd (alternatively, use "Hotkey IfWin"). Finally, the search
can be narrowed by specifying multiple criteria. For example: My File.txt
ahk_class Notepad
WinText
If present, this parameter must be a substring from a single text element of
the target window (as revealed by the included Window Spy utility). Hidden
text elements are detected if DetectHiddenText has been turned on in the
auto-execute section (top part of the script).
ExcludeTitle
ExcludeText
Although these are not supported, they can be used indirectly by specifying
ahk_group MyGroup for WinTitle (where MyGroup is a group created via
GroupAdd, which supports ExcludeTitle/Text).
Basic Operation
The #IfWin directives make it easy to create context-sensitive hotkeys and hotstrings. For example:
#IfWinActive ahk_class Notepad
#space::MsgBox You pressed Win+Spacebar in Notepad.
The #IfWin directives are positional: they affect all hotkeys and hotstrings physically beneath them in
the script. They are also mutually exclusive; that is, only the most recent one will be in effect.
To turn off context sensitivity, specify any #IfWin directive but omit all of its parameters. For
example:
#IfWinActive
When #IfWin is turned off (or never used in a script), all hotkeys and hotstrings are enabled for all
windows (unless disabled via Suspend or the Hotkey command).
When a mouse or keyboard hotkey is disabled via #IfWin, it performs its native function; that is, it
passes through to the active window as though there is no such hotkey. There are two exceptions: 1)
Windows 95/98/Me: pressing an IfWin-disabled hotkey has no effect (not even its native function);
and 2) Joystick hotkeys: although #IfWin works, it never prevents other programs from seeing the
press of a button.
#IfWin can also be used to alter the behavior of an ordinary key like Enter or Space. This is useful
when a particular window ignores that key or performs some action you find undesirable. For
example:
#IfWinActive Reminders ahk_class #32770 ; The "reminders" window in Outlook.
Enter::Send !o ; Have an "Enter" keystroke open the selected reminder rather than snoozing
it.
#IfWinActive
Variant (Duplicate) Hotkeys
A particular hotkey or hotstring can be defined more than once in the script if each definition has
different #IfWin criteria. These are known as hotkey variants. For example:
#IfWinActive ahk_class Notepad
Printed Documentation
568
^!c::MsgBox You pressed Control+Alt+C in Notepad.
#IfWinActive ahk_class WordPadClass
^!c::MsgBox You pressed Control+Alt+C in WordPad.
#IfWinActive
^!c::MsgBox You pressed Control+Alt+C in a window other than Notepad/WordPad.
If more than one variant is eligible to fire, only the one closest to the top of the script will fire. The
exception to this is the global variant (the one with no #IfWin criteria): It always has the lowest
precedence; therefore, it will fire only if no other variant is eligible (this exception does not apply to
hotstrings).
When defining variants, the order of modifier symbols such as ^!+# does not matter. For example,
^!c is the same as !^c. However, any hotkey with a wildcard prefix (*) is an entirely separate hotkey
from a non-wildcard one (for example, *F1 and F1 would each have their own set of variants).
To have the same hotkey subroutine executed by more than one variant, the easiest way is to create
a stack of identical hotkeys, each with a different #IfWin directive above it. For example:
#IfWinActive ahk_class Notepad
#z::
#IfWinActive ahk_class WordPadClass
#z::
MsgBox You pressed Win+Z in either Notepad or WordPad.
return
Alternatively, a window group can be used via #IfWinActive ahk_group MyGroup.
To create hotkey variants dynamically (while the script is running), see "Hotkey IfWin".
General Remarks
#IfWin also restores prefix keys to their native function when appropriate (a prefix key is the "a" key
in a hotkey such as "a & b"). This occurs whenever there are no enabled hotkeys for a given prefix.
When Gosub or Goto is used to jump to a hotkey or hotstring label, it jumps to the variant closest to
the top of the script.
When a hotkey is currently disabled via #IfWin, its key or mouse button will appear with a "#"
character in KeyHistory's "Type" column. This can help debug a script.
Variable references such as %Var% are not currently supported. Therefore, percent signs must be
escaped via `% to allow future support for them. Similarly, literal commas must be escaped (via `,) to
allow additional parameters to be added in the future. If you need to work around this limitation, use
GroupAdd and ahk_group.
A label to which the Hotkey command has assigned a hotkey is not directly affected by #IfWin.
Instead, the use of #IfWin closest to the bottom of the script (if any) will be in effect for all hotkeys
created by the Hotkey command (unless "Hotkey IfWin" has been used to change that).
Alt-tab hotkeys are not affected by #IfWin: they are in effect for all windows.
The Last Found Window is set by #IfWinActive/Exist (though not by #IfWinNotActive/NotExist). For
example:
#IfWinExist ahk_class Notepad
#n::WinActivate ; Activates the window found by #IfWin.
The escape sequences `s and `t may be used if leading or trailing spaces/tabs are needed in one of
#IfWin's parameters.
#Directives
569
For performance reasons, #IfWin does not continuously monitor the activation or existence of the
specified windows. Instead, it checks for a matching window only when you type a hotkey or
hotstring. If the right window is not present, your keystroke or mouse click is allowed to pass through
to the active window unaltered (except on Windows 95/98/Me).
Windows 95/98/Me: If the first variant of a hotkey has a $ prefix, all variants will be allowed to "send
themselves". This provides a means for a hotkey to perform its native function rather than doing
nothing at all. For example:
$^a::Send ^a ; The first variant must have a $ prefix to allow it to "send itself" on Windows
9x.
#IfWinActive ahk_class Notepad
^a::MsgBox You pressed Control-A while Notepad is active.
Window titles and text are case sensitive. Hidden windows are not detected unless
DetectHiddenWindows has been turned on in the auto-execute section (top part of the script).
In versions older than 1.0.42, #IfWin was more limited:
Windows 95/98/Me: With the exception of joystick hotkeys, the #IfWin directives were
ignored because they required the keyboard hook or mouse hook. In v1.0.42+, #IfWin is
supported.
Duplicate hotkeys (variants) were not allowed. Instead, window groups were typically used to
make a hotkey active in more than one type of window.
The Last Found Window was not set by #IfWin.
Related
Hotkey command, Hotkeys, Hotstrings, Suspend, IfWinActive, IfWinExist, SetTitleMatchMode,
DetectHiddenWindows
Examples
#IfWinActive ahk_class Notepad
^!a::MsgBox You pressed Ctrl-Alt-A while Notepad is active. ; This hotkey will have no effect if
pressed in other windows (and it will "pass through").
#c::MsgBox You pressed Win-C while Notepad is active.
::btw::This replacement text for "btw" will occur only in Notepad.
#IfWinActive
#c::MsgBox You pressed Win-C in a window other than Notepad.
#Include / #IncludeAgain
Causes the script to behave as though the specified file's contents are present at this exact position.
#Include FileOrDirName
#IncludeAgain FileOrDirName
Parameters
FileOrDirName
The name of the file to be included, which is assumed to be in the
startup/working directory if an absolute path is not specified (except for
ahk2exe, which assumes the file is in the script's own directory). The file
name must not contain variable references (except %A_ScriptDir%), double
quotes, or wildcards. Escape sequences other than semicolon (`;) must not
be used, nor are they needed because characters such as percent signs are
Printed Documentation
570
treated literally. Note: SetWorkingDir has no effect on #Include because
#Include is processed before the script begins executing.
In v1.0.35.11+, specify a directory instead of a file to change the working
directory used by all subsequent occurrences of #Include and FileInstall. The
directory name must not contain variables other than %A_ScriptDir%. Note:
Changing the working directory in this way does not affect the script's initial
working directory when it starts running (A_WorkingDir). To change that, use
SetWorkingDir at the top of the script.
Remarks
A script behaves as though the included file's contents are physically present at the exact position of
the #Include directive (as though a copy-and-paste were done from the included file).
#Include ensures that FileName is included only once, even if multiple inclusions are encountered for
it. By contrast, #IncludeAgain allows multiple inclusions of the same file, while being the same as
#Include in all other respects.
The FileName parameter may optionally be preceded by *i and a single space, which causes the
program to ignore any failure to load the included file. For example: #Include *i SpecialOptions.ahk.
This option should be used only when the included file's contents are not essential to the main script's
operation.
Lines displayed in the main window via ListLines or the menu View->Lines are always numbered
according to their physical order within their own files. In other words, including a new file will change
the line numbering of the main script file by only one line, namely that of the #Include line itself
(except for compiled scripts, which merge their included files into one big script at the time of
compilation).
#Include is often used to load functions defined in an external file. Unlike subroutine labels, functions
can be included at the very top of the script without affecting the auto-execute section.
As with other # directives, #Include cannot be executed conditionally. In other words, this example
would not work:
if x = 1
#Include SomeFile.ahk ; This line takes effect regardless of the value of x.
y = 2 ; And this line would belong to the IF above, since # directives cannot belong to IFs.
Related
Functions, FileInstall
Example
#Include C:\My Documents\Scripts\Utility Subroutines.ahk
#Include %A_ScriptDir% ; Changes the working directory for #Includes and FileInstalls physically
beneath this point.
#Include C:\My Scripts ; Same as above but for an explicitly named directory.
#InstallKeybdHook
Forces the unconditional installation of the keyboard hook.
#InstallKeybdHook
Remarks
#Directives
571
The keyboard hook monitors keystrokes for the purpose of activating hotstrings and any keyboard
hotkeys not supported by RegisterHotkey (which is a function built into the operating system). It also
supports a few other features such as the Input command.
The keyboard hook is not supported under Windows 95/98/Me because those operating systems
require a different type of hook that must reside in a DLL file.
AutoHotkey does not install the keyboard and mouse hooks unconditionally because together they
consume at least 500 KB of memory. Therefore, the keyboard hook is normally installed only when the
script contains one of the following: 1) hotstrings; 2) one or more hotkeys that require the keyboard
hook (most do not); 3) SetCaps/Scroll/Numlock AlwaysOn/AlwaysOff; 4) the Input command, for
which the hook is installed upon first actual use.
By contrast, the #InstallKeybdHook directive will unconditionally install the keyboard hook, which
might be useful to allow KeyHistory to display the last 20 keystrokes (for debugging purposes), or to
avoid the need for #HotkeyModifierTimeout.
You can determine whether a script is using the hook via the KeyHistory command or menu item. You
can determine which hotkeys are using the hook via the ListHotkeys command or menu item.
This directive also makes a script persistent, meaning that ExitApp should be used to terminate it.
Related
#InstallMouseHook, #UseHook, Hotkey, Input, #Persistent, KeyHistory, Hotstrings, GetKeyState,
KeyWait
Example
#InstallKeybdHook
#InstallMouseHook
Forces the unconditional installation of the mouse hook.
#InstallMouseHook
Remarks
The mouse hook monitors mouse clicks for the purpose of activating mouse hotkeys and facilitating
hotstrings. It is not supported under Windows 95/98/Me because those operating systems require a
different type of hook that must reside in a DLL file.
AutoHotkey does not install the keyboard and mouse hooks unconditionally because together they
consume at least 500 KB of memory (but if the keyboard hook is installed, installing the mouse hook
only requires about 50 KB of additional memory; and vice versa). Therefore, the mouse hook is
normally installed only when the script contains one or more mouse hotkeys. It is also installed for
hotstrings, but that can be disabled via #Hotstring NoMouse.
By contrast, the #InstallMouseHook directive will unconditionally install the mouse hook, which might
be useful to allow KeyHistory to monitor mouse clicks.
You can determine whether a script is using the hook via the KeyHistory command or menu item. You
can determine which hotkeys are using the hook via the ListHotkeys command or menu item.
This directive also makes a script persistent, meaning that ExitApp should be used to terminate it.
Related
#InstallKeybdHook, #UseHook, Hotkey, #Persistent, KeyHistory, GetKeyState, KeyWait
Example
Printed Documentation
572
#InstallMouseHook
#KeyHistory
Sets the maximum number of keyboard and mouse events displayed by the KeyHistory window. You
can set it to 0 to disable key history.
#KeyHistory MaxEvents
Parameters
MaxEvents
The maximum number of keyboard and mouse events displayed by the
KeyHistory window. (default 40, limit 500). Specify 0 to disable key history
entirely.
Remarks
Because this setting is put into effect before the script begins running, it is only necessary to specify it
once (anywhere in the script).
Because each keystroke or mouse click consists of a down-event and an up-event, KeyHistory displays
only half as many "complete events" as specified here. For example, if the script contains
"#KeyHistory 50", up to 25 keystrokes and mouse clicks will be displayed.
Related
KeyHistory, #NoTrayIcon
Example
#KeyHistory 0 ; Disable key history.
#KeyHistory 100 ; Store up to 100 events.
#MaxHotkeysPerInterval
Along with #HotkeyInterval, specifies the rate of hotkey activations beyond which a warning dialog
will be displayed.
#MaxHotkeysPerInterval Value
Parameters
Value
The maximum number of hotkeys that can be pressed in the interval specified
by #HotkeyInterval without triggering a warning dialog.
Remarks
Care should be taken not to make the above too lenient because if you ever inadvertently introduce an
infinite loop of keystrokes (via a Send command that accidentally triggers other hotkeys), your
computer could become unresponsive due to the rapid flood of keyboard events.
As an oversimplified example, the hotkey ^c::Send ^c would produce an infinite loop of keystrokes.
To avoid this, add the $ prefix to the hotkey definition (e.g. $^c::) so that the hotkey cannot be
triggered by the Send command.
If this directive is unspecified in the script, it will behave as though set to 70.
Related
#HotkeyInterval
#Directives
573
Example
#MaxHotkeysPerInterval 200
#MaxMem
Sets the maximum capacity of each variable to the specified number of megabytes.
#MaxMem Megabytes
Parameters
Megabytes
The number of megabytes to allow for each variable. A value larger than 4095
is considered to be 4095. A value less than 1 is considered to be 1.
Remarks
If this directive is unspecified in the script, it will behave as though set to 64.
The purpose of limiting each variable's capacity is to prevent a buggy script from consuming all
available system memory. Raising or lowering the limit does not affect the performance of a script,
nor does it change how much memory the script actually uses (except in the case of WinGetText and
ControlGetText, which will be capable of retrieving more text if #MaxMem is increased).
This setting is global, meaning that it needs to be specified only once (anywhere in the script) to affect
the behavior of the entire script.
This setting restricts only the automatic expansion that a variable does on its own. It does not affect
VarSetCapacity.
Related
VarSetCapacity, Variables, Sort, WinGetText, ControlGetText, #MaxThreads
Example
#MaxMem 256 ; Allow 256 MB per variable.
#MaxThreads
Sets the maximum number of simultaneous threads.
#MaxThreads Value
Parameters
Value The maximum total number of threads that can exist simultaneously (limit 20).
Remarks
This setting is global, meaning that it needs to be specified only once (anywhere in the script) to affect
the behavior of the entire script.
Although a value of 1 is allowed, it is not recommended because it would prevent new hotkeys from
launching whenever the script is displaying a MsgBox or other dialog. It would also prevent timers
from running whenever another thread is sleeping or waiting.
Any hotkey subroutine whose first line is ExitApp, Pause, Edit, Reload, KeyHistory, ListLines, ListVars,
or ListHotkeys will always run regardless of this setting.
If this setting is lower than #MaxThreadsPerHotkey, it effectively overrides that setting.
Printed Documentation
574
If this directive is unspecified in the script, it will behave as though set to 10.
Related
#MaxThreadsPerHotkey, Threads, #MaxHotkeysPerInterval, #HotkeyInterval, ListHotkeys, #MaxMem
Example
#MaxThreads 2
#MaxThreadsBuffer
Causes some or all hotkeys to buffer rather than ignore keypresses when their
#MaxThreadsPerHotkey limit has been reached.
#MaxThreadsBuffer On|Off
Parameters
On|Off
On: All hotkey subroutines between here and the next #MaxThreadsBuffer ON
directive will buffer rather than ignore presses of their hotkeys whenever their
subroutines are at their #MaxThreadsPerHotkey limit.
Off: This is the default behavior. A hotkey press will be ignored whenever that
hotkey is already running its maximum number of threads (usually 1, but this
can be changed with #MaxThreadsPerHotkey).
Remarks
This directive is rarely used because this type of buffering, which is OFF by default, usually does more
harm than good. For example, if you accidentally press a hotkey twice, having this setting ON would
cause that hotkey's subroutine to automatically run a second time if its first thread takes less than 1
second to finish (this type of buffer expires after 1 second, by design). Note that AutoHotkey buffers
hotkeys in several other ways (such as "Thread Interrupt" and "Critical"). It's just that this particular
way can be detrimental, thus it is OFF by default.
The main use for this directive is to increase the responsiveness of the keyboard's auto-repeat
feature. For example, when you hold down a hotkey whose #MaxThreadsPerHotkey setting is 1 (the
default), incoming keypresses are ignored if that hotkey subroutine is already running. Thus, when the
subroutine finishes, it must wait for the next auto-repeat keypress to come in, which might take 50ms
or more due to being caught in between keystrokes of the auto-repeat cycle. This 50ms delay can be
avoided by enabling this directive for any hotkey that needs the best possible response time while it is
being auto-repeated.
As with all # directives, this one should not be positioned in the script as though it were a command
(i.e. it is not necessary to have it contained within a subroutine). Instead, position it immediately
before the first hotkey label you wish to have affected by it.
Related
#MaxThreads, #MaxThreadsPerHotkey, Critical, Thread (command), Threads, Hotkey,
#MaxHotkeysPerInterval, #HotkeyInterval, ListHotkeys
Example
#MaxThreadsBuffer on
#x::MsgBox, This hotkey will use this type of buffering.
#y::MsgBox, And this one too.
#Directives
575
#MaxThreadsBuffer off
#z::MsgBox, But not this one.
#MaxThreadsPerHotkey
Sets the maximum number of simultaneous threads per hotkey.
#MaxThreadsPerHotkey Value
Parameters
Value
The maximum number of threads that can be launched for a given hotkey
subroutine (limit 20).
Remarks
This setting is used to control how many "instances" of a given hotkey subroutine are allowed to exist
simultaneously. For example, if a hotkey has a max of 1 and it is pressed again while its subroutine is
already running, the press will be ignored. This is helpful to prevent accidental double-presses.
However, if you wish these keypresses to be buffered rather than ignored -- perhaps to increase the
responsiveness of the keyboard's auto-repeat feature -- use #MaxThreadsBuffer.
Unlike #MaxThreads, this setting is not global. Instead, position it before the first hotkey label you
wish to have affected by it, which will result in all subsequent hotkeys using that value until another
instance of this directive is encountered.
Any hotkey subroutine whose first line is ExitApp, Pause, Edit, Reload, KeyHistory, ListLines, ListVars,
or ListHotkeys will always run regardless of this setting.
The setting of #MaxThreads -- if lower than than this setting -- takes precedence.
If this directive is unspecified in the script, it will behave as though set to 1.
Related
#MaxThreads, #MaxThreadsBuffer, Critical, Threads, Hotkey, #MaxHotkeysPerInterval,
#HotkeyInterval, ListHotkeys
Example
#MaxThreadsPerHotkey 3
#NoEnv [v1.0.43.08+]
Avoids checking empty variables to see if they are environment variables (recommended for all new
scripts).
#NoEnv
Specifying the line #NoEnv anywhere in a script prevents empty variables from being looked up as
potential environment variables. For example:
#NoEnv
MsgBox %WinDir%
The above would not retrieve the "WinDir" environment variable (though that could be solved by
doing WinDir := A_WinDir near the top of the script).
Specifying #NoEnv is recommended for all new scripts because:
Printed Documentation
576
1. It significantly improves performance whenever empty variables are used in an expression or
command. It also improves DllCall's performance when unquoted parameter types are used
(e.g. int vs. "int").
2. It prevents script bugs caused by environment variables whose names unexpectedly match
variables used by the script.
3. A future version of AutoHotkey might make this behavior the default (though such a change is
not expected until April 2007 at the earliest).
To help ease the transition to #NoEnv, the built-in variables Comspec and ProgramFiles have been
added. They contain the same strings as the corresponding environment variables.
When #NoEnv is in effect, the script should use EnvGet to retrieve environment variables, or use built-
in variables like A_WinDir.
Related
EnvGet, Comspec, ProgramFiles, A_WinDir
#NoTrayIcon
Disables the showing of a tray icon.
#NoTrayIcon
Specifying this anywhere in a script will prevent the showing of a tray icon for that script when it is
launched (even if the script is compiled into an EXE).
If you use this for a script that has hotkeys, you might want to bind a hotkey to the ExitApp
command. Otherwise, there will be no easy way to exit the program (without restarting the computer
or killing the process). For example: #x::ExitApp
The tray icon can be made to disappear or reappear at any time during the execution of the script by
using the command menu, tray, Icon or menu, tray, NoIcon. The only drawback of using the menu,
tray, NoIcon at the very top of the script is that the tray icon might be briefly visible when the script is
first launched. To avoid that, use #NoTrayIcon instead.
The built-in variable A_IconHidden contains 1 if the tray icon is currently hidden or 0 otherwise.
Related
Menu, ExitApp
Example
#NoTrayIcon
#Persistent
Keeps a script permanently running (that is, until the user closes it or ExitApp is encountered).
#Persistent
If this directive is present anywhere in the script, that script will stay running after the auto-execute
section (top part of the script) completes. This is useful in cases where a script contains timers and/or
custom menu items but not hotkeys, hotstrings, or any use of OnMessage() or Gui.
If this directive is added to an existing script, you might want to change some or all occurrences of
Exit to be ExitApp. This is because Exit will not terminate a persistent script; it terminates only the
current thread.
In v1.0.16+, this directive also makes a script single-instance. To override this or change the way
single-instance behaves, see #SingleInstance.
#Directives
577
Related
#SingleInstance, SetTimer, Menu, Exit, ExitApp
Example
#Persistent
#SingleInstance
Determines whether a script is allowed to run again when it is already running.
#SingleInstance [force|ignore|off]
Parameters
force|ignore|off
This parameter determines what happens when a script is launched while a
previous instance of itself is already running. If #SingleInstance is specified
by itself (with no parameter), a dialog box is displayed asking whether to
keep the old instance or replace it with the new one. Otherwise:
The word FORCE skips the dialog box and replaces the old instance
automatically, which is similar in effect to the Reload command.
The word IGNORE skips the dialog box and leaves the old instance running.
In other words, attempts to launch an already-running script are ignored.
The word OFF allows multiple instances of a script.
Remarks
A script containing hotkeys, hotstrings, #Persistent, OnMessage(), or Gui is single-instance by default.
This behavior can be disabled or modified as described above.
Related
Reload, #Persistent
Example
#SingleInstance force
#SingleInstance ignore
#SingleInstance off
#UseHook
Forces the use of the hook to implement all or some keyboard hotkeys.
#UseHook [On|Off]
Parameters
On|Off
#UseHook without one of the following words after it is equivalent to
#UseHook On.
On: The keyboard hook will be used to implement all keyboard hotkeys
between here and the next #UseHook OFF (if any).
Printed Documentation
578
Off: Hotkeys will be implemented using the default method (RegisterHotkey()
if possible; otherwise, the keyboard hook).
Remarks
Normally, the windows API function RegisterHotkey() is used to implement a keyboard hotkey
whenever possible. However, the responsiveness of hotkeys might be better under some conditions if
the keyboard hook is used instead.
Turning this directive ON is equivalent to using the $ prefix in the definition of each affected hotkey.
The exception to this is Windows 95/98/Me, upon which #UseHook is ignored (though the $ prefix
works in a limited fashion).
As with all # directives -- which are processed only once when the script is launched -- #UseHook
should not be positioned in the script as though it were a command (that is, it is not necessary to
have it contained within a subroutine). Instead, position it immediately before the first hotkey label
you wish to have affected by it.
Hotkeys that use the keyboard hook cannot be triggered by means of the Send command. Similarly,
mouse hotkeys cannot be triggered by commands such as Click because all mouse hotkeys use the
mouse hook. To work around this, use Gosub to jump directly to the hotkey's subroutine. For
example: Gosub #LButton
If this directive does not appear in the script at all, it will behave as though set to OFF.
Related
#InstallKeybdHook, #InstallMouseHook, ListHotkeys
Example
#UseHook ; Force the use of the hook for hotkeys after this point.
#x::MsgBox, This hotkey will be implemented with the hook.
#y::MsgBox, And this one too.
#UseHook off
#z::MsgBox, But not this one.
#WinActivateForce
Skips the gentle method of of activating a window and goes straight to the forceful method.
#WinActivateForce
Specifying this anywhere in a script will cause commands that activate a window -- such as
WinActivate, WinActivateBottom, and GroupActivate -- to skip the "gentle" method of activating a
window and go straight to the more forceful methods.
Although this directive will usually not change how quickly or reliably a window is activated, it might
prevent task bar buttons from flashing when different windows are activated quickly one after the
other.
Windows 95 and NT will probably never need this setting since they are more permissive about
allowing windows to be activated.
Related
WinActivate, WinActivateBottom, GroupActivate
Example
#Directives
579
#WinActivateForce

581
Index
#
#AllowSameLineComments ..................... 561
#ClipboardTimeout ................................ 561
#CommentFlag...................................... 561
#ErrorStdOut ........................................ 562
#EscapeChar ........................................ 563
#HotkeyInterval ............................. 306, 564
#HotkeyModifierTimeout.................. 307, 565
#Hotstring..................................... 308, 565
#IfWinActive.................................. 309, 566
#IfWinExist.................................... 309, 566
#Include ....................................... 151, 569
#IncludeAgain................................ 151, 569
#InstallKeybdHook ......................... 321, 570
#InstallMouseHook ......................... 322, 571
#KeyHistory................................... 323, 572
#MaxHotkeysPerInterval.................. 311, 572
#MaxMem ............................................ 573
#MaxThreads ................................. 312, 573
#MaxThreadsBuffer......................... 312, 574
#MaxThreadsPerHotkey................... 313, 575
#NoEnv................................................ 575
#NoTrayIcon.................................. 371, 576
#Persistent ........................................... 576
#SingleInstance ............................. 371, 577
#UseHook ..................................... 314, 577
#WinActivateForce.......................... 525, 578
:
:= ....................................................... 370
A
A_Index ............................................... 161
A_LoopField ................................... 167, 472
A_LoopRegKey ............................... 173, 445
A_LoopRegName ............................ 173, 445
A_LoopRegSubKey.......................... 173, 445
A_LoopRegTimeModified .................. 173, 445
A_LoopRegType.............................. 173, 445
abbreviation expansion .............................23
activate a window................................... 534
add ......................................................355
AllowSameLineComments ........................ 561
alnum............................................362, 471
alpha.............................................362, 471
AlwaysOnTop (WinSet)............................ 551
append to file.........................................111
ASCII conversion.............................367, 413
attributes of files and folders.................... 118
auto-execute section.................................39
AutoIt v2 ................................................69
auto-replace text as you type it ..................23
AutoTrim............................................... 372
B
balloon tip............................................. 297
beep the PC speaker ............................... 453
between (check if var between two values) 361
BlockInput......................................323, 373
blocks (lines enclosed in braces)............... 152
Break ...................................................153
buffering........................................312, 574
button list (mouse and joystick) ......... 35, 330
button state...........................................327
C
case sensitive strings .............................. 485
Changelog...............................................91
choose file......................................129, 209
choose folder ..................................133, 212
class name of a window........................... 541
Click.....................................................419
click the mouse...................................... 422
ClipWait .........................................103, 375
close a window....................................... 536
color of pixels ........................................ 400
commands, alphabetical list .......................77
CommentFlag ........................................ 561
Printed Documentation
582
comments in scripts ................................. 39
Continue............................................... 154
Control ................................................. 495
ControlClick ................................... 420, 496
ControlFocus ......................................... 499
ControlGet ............................................ 500
ControlGetFocus .................................... 503
ControlGetPos ....................................... 504
ControlGetText ...................................... 505
ControlMove.......................................... 506
ControlSend................................... 325, 508
ControlSendRaw............................. 325, 508
ControlSetText ...................................... 509
convert a .aut file to .ahk.......................... 69
coordinates........................................... 376
CoordMode ........................................... 376
copy file ............................................... 113
copy folder/directory .............................. 114
create file ............................................. 111
create folder/directory............................ 115
Critical ................................................. 376
current directory.................................... 148
D
dates and times (compare) ..................... 357
dates and times (math) .......................... 355
dates and times (of files) ........................ 136
debugger.............................................. 398
decimal places................................ 365, 481
delete files............................................ 117
delete folder/directory ............................ 129
Delimiter .............................................. 563
DerefChar............................................. 563
DetectHiddenText .................................. 525
DetectHiddenWindows ............................ 526
dialog FileSelectFile......................... 129, 209
dialog FileSelectFolder ..................... 133, 212
dialog InputBox ..................................... 282
dialog MsgBox....................................... 283
digit ..............................................362, 471
disk space ............................................. 110
DllCall() ................................................ 377
download a file....................................... 415
drag the mouse...................................... 425
Drive ....................................................107
DriveGet ............................................... 108
DriveSpaceFree...................................... 110
E
Edit ......................................................388
Else......................................................154
EndRepeat............................................. 161
EnvAdd................................................. 355
EnvDiv.................................................. 356
EnvGet ................................................. 104
environment variables (change them) ....... 104
EnvMult ................................................ 356
EnvSet.................................................. 104
EnvSub................................................. 357
EnvUpdate............................................. 105
ErrorStdOut ...........................................562
escape sequence .................................... 563
EscapeChar ........................................... 563
Exit ...............................................156, 431
ExitApp..........................................156, 431
F
FAQ (Frequently Asked Questions) ..............11
file attributes .........................................134
file or folder (does it exist)....................... 137
file pattern .....................................140, 163
file, creating ..........................................111
file, reading....................................144, 170
FileAppend ............................................111
FileCopy................................................113
FileCopyDir............................................ 114
FileCreateDir..........................................115
FileCreateShortcut ..................................116
FileDelete..............................................117
Index
583
FileGetAttrib.......................................... 118
FileGetShortcut ..................................... 119
FileGetSize............................................ 120
FileGetTime .......................................... 121
FileGetVersion....................................... 121
FileInstall ............................................. 122
FileMove............................................... 123
FileMoveDir........................................... 125
FileRead ............................................... 127
FileReadLine.......................................... 126
FileRecycle............................................ 128
FileRecycleEmpty................................... 128
FileRemoveDir ....................................... 129
FileSelectFile.................................. 129, 209
FileSelectFolder .............................. 133, 212
FileSetAttrib.......................................... 134
FileSetTime........................................... 136
find a file.............................................. 137
find a string .......................................... 485
find a window........................................ 528
floating point (check if it is one)........ 362, 471
floating point (SetFormat)................ 365, 481
focus.................................................... 499
folder/directory copy .............................. 114
folder/directory create............................ 115
folder/directory move............................. 125
folder/directory remove .......................... 129
folder/directory select...................... 133, 212
format, numbers............................. 365, 481
FormatTime .......................................... 463
free space............................................. 110
functions (defining and calling) ........... 61, 187
G
game automation................................... 400
GetKeyState ......................................... 327
Gosub .................................................. 157
Goto .................................................... 158
GroupActivate ....................................... 521
GroupAdd..............................................522
GroupClose............................................ 524
GroupDeactivate .................................... 524
Gui .......................................................214
Gui control types .................................... 236
GuiControl ............................................. 251
GuiControlGet ........................................ 255
H
hexadecimal format .........................365, 481
hidden text............................................ 525
hidden windows ..................................... 526
HKEY_CLASSES_ROOT ............................ 449
HKEY_CURRENT_CONFIG ........................ 449
HKEY_CURRENT_USER............................ 449
HKEY_LOCAL_MACHINE........................... 449
HKEY_USERS......................................... 449
hook..............................................321, 570
Hotkey.................................................. 314
hotkey basics................................... 17, 301
hotkey list ............................................. 319
HotkeyInterval ................................306, 564
HotkeyModifierTimeout.....................307, 565
hotstrings and auto-replace .......................23
I
ID number for a window.......................... 537
If 158, 359, 467
If (expression) ................................160, 358
If var [not] between Low and High............ 361
If var [not] in/contains MatchList .............. 469
If var is [not] type...........................362, 471
IfEqual....................................158, 359, 467
IfExist...................................................137
IfGreater.................................158, 359, 467
IfGreaterOrEqual ......................158, 359, 467
IfInString ..............................................468
IfLess .....................................158, 359, 467
IfLessOrEqual ..........................158, 359, 467
IfMsgBox...............................................281
Printed Documentation
584
IfNotEqual .............................. 158, 359, 467
IfNotExist ............................................. 137
IfNotInString......................................... 468
IfWinActive ........................................... 527
IfWinExist............................................. 528
IfWinNotActive ...................................... 527
IfWinNotExist ........................................ 528
ImageSearch ........................................ 388
Include.......................................... 151, 569
IniDelete .............................................. 138
IniRead ................................................ 139
IniWrite................................................ 139
Input ................................................... 336
InputBox .............................................. 282
Install .................................................. 122
InstallKeybdHook............................ 321, 570
InstallMouseHook ........................... 322, 571
integer (check if it is one) ................ 362, 471
integer (SetFormat) ........................ 365, 481
Interrupt .............................................. 411
J
Joystick........................................... 35, 330
K
key list (keyboard, mouse, joystick) .... 35, 330
key state .............................................. 327
keyboard hook ............................... 321, 570
KeyHistory............................................ 333
keystrokes, sending ............................... 340
KeyWait ............................................... 334
L
labels................................................... 157
LeftClick ............................................... 422
LeftClickDrag ........................................ 425
length of a string ................................... 488
ListHotkeys........................................... 319
ListLines............................................... 391
ListVars................................................ 391
ListView controls (GUI) ........................... 257
lnk (link/shortcut) file ............................. 116
logoff....................................................441
Loop.....................................................161
Loop (registry)................................173, 445
Loop, FilePattern .............................140, 163
Loop, Parse a string.........................167, 472
Loop, Read file contents ...................144, 170
lParam.................................................. 517
M
MaxHotkeysPerInterval.....................311, 572
MaxThreads....................................312, 573
MaxThreadsBuffer............................312, 574
MaxThreadsPerHotkey......................313, 575
Menu.............................................392, 510
messages, receiving................................ 194
messages, sending ................................. 517
modal (always on top) ............................ 283
mouse hook....................................322, 571
mouse speed .........................................429
mouse wheel ......................................... 422
MouseClick ............................................ 422
MouseClickDrag...................................... 425
MouseGetPos .........................................426
MouseMove ...........................................428
move a window...................................... 549
move file............................................... 123
move folder/directory.............................. 125
MsgBox................................................. 283
multiply ................................................ 356
mute (changing it)..................................456
N
NoTimers ..............................................411
NoTrayIcon.....................................371, 576
number..........................................362, 471
number format................................365, 481
O
OnExit ...........................................177, 432
OnMessage() ......................................... 194
Index
585
open file............................................... 126
OutputDebug ........................................ 398
P
parameters passed into a script ................. 39
parse a string (Loop)....................... 167, 472
parse a string (StringSplit) ...................... 491
Pause............................................ 179, 319
PID (Process ID).................................... 433
PixelGetColor ........................................ 399
PixelSearch........................................... 400
play a sound or video file ........................ 455
PostMessage ......................................... 517
prefix and suffix keys ........................ 17, 301
print a file............................................. 438
priority of a process ............................... 433
priority of a thread................................. 411
Process ................................................ 433
Progress........................................ 286, 290
properties of a file or folder ..................... 438
Q
quit script ...................................... 156, 431
R
Random ............................................... 363
read file................................................ 126
READONLY............................................ 118
reboot.................................................. 441
REG_BINARY......................................... 449
REG_DWORD ........................................ 449
REG_EXPAND_SZ................................... 449
REG_MULTI_SZ ..................................... 449
REG_SZ ............................................... 449
RegDelete............................................. 448
RegExMatch()................................. 200, 474
RegExReplace() .............................. 204, 478
registry loop .................................. 173, 445
RegRead............................................... 449
RegWrite .............................................. 450
Reload .......................................... 320, 401
remap keys or mouse buttons ....................29
remove folder/directory........................... 129
rename file............................................ 123
Repeat.................................................. 161
resize a window ..................................... 549
restart the computer............................... 441
Return .................................................. 180
RGB colors ............................................399
RightClick.............................................. 422
RightClickDrag ....................................... 425
Run......................................................438
RunAs...................................................440
RunWait................................................ 438
S
Script Showcase.......................................87
Scripts....................................................39
select file .......................................129, 209
select folder....................................133, 212
Send ....................................................340
SendMessage......................................... 517
SendMode ............................................. 350
SendRaw............................................... 340
SetBatchLines .................................181, 402
SetCapsLockState................................... 353
SetControlDelay ..................................... 520
SetDefaultMouseSpeed............................ 429
SetEnv...........................................403, 480
SetFormat ......................................365, 481
SetKeyDelay..........................................351
SetMouseDelay ...................................... 429
SetNumLockState................................... 353
SetScrollLockState..................................353
SetStoreCapslockMode ............................ 353
SetTimer ........................................181, 403
SetTitleMatchMode ................................. 529
SetWinDelay..........................................531
SetWorkingDir ....................................... 148
shortcut file ...........................................116
Printed Documentation
586
Shutdown............................................. 441
SingleInstance................................ 371, 577
size of a file/folder ................................. 120
size of a window.................................... 542
Sleep ............................................ 185, 442
Sort ..................................................... 483
SoundBeep ........................................... 453
SoundGet ............................................. 453
SoundGetWaveVolume ........................... 455
SoundPlay ............................................ 455
SoundSet ............................................. 456
SoundSetWaveVolume............................ 460
space............................................ 362, 471
speed of a script ............................. 181, 402
SplashImage.................................. 286, 290
SplashTextOff........................................ 295
SplashTextOn........................................ 295
SplitPath .............................................. 149
standard output (stdout)......................... 111
StatusBarGetText .................................. 531
StatusBarWait ....................................... 532
string (search for).................................. 468
StringCaseSense.................................... 485
StringGetPos......................................... 485
StringLeft ............................................. 487
StringLen.............................................. 488
StringLower .......................................... 488
StringMid.............................................. 489
StringReplace........................................ 490
StringRight ........................................... 487
StringSplit ............................................ 491
StringTrimLeft ....................................... 493
StringTrimRight ..................................... 493
StringUpper .......................................... 488
subtract ............................................... 357
Suspend........................................ 185, 321
SysGet ................................................. 407
T
terminate a window................................ 546
terminate script...............................156, 431
Thread.................................................. 411
time ..............................................362, 471
Timer (timed subroutines) ................181, 403
times and dates (compare) ...................... 357
times and dates (math)........................... 355
times and dates (of files)......................... 136
title of a window..................................... 555
ToolTip ................................................. 296
Transform......................................367, 413
transparency of a window........................ 551
tray icon ........................................371, 576
tray menu (customizing) ..................392, 510
TrayTip ................................................. 297
TreeView controls (GUI) .......................... 273
Trim.....................................................372
Tutorial .................................................... 3
U
Unicode text and clipboard................367, 413
URLDownloadToFile ................................ 415
UseHook ........................................314, 577
user (run as a different user) ................... 440
V
variable (change the value of) ...........403, 480
variable comparison..................158, 359, 467
variable list............................................ 391
variable type ..................................362, 471
variables (explanation)..............................47
VarSetCapacity() .............................206, 416
version of a file ...................................... 121
volume (changing it)............................... 456
W
wait (sleep) ....................................185, 442
wait for a key to be released or pressed..... 334
WheelDown ........................................... 422
WheelUp ............................................... 422
Index
587
whitespace ........................................... 372
wildcards (for files & folders) ............ 140, 163
WinActivate .......................................... 534
WinActivateBottom ................................ 535
WinActivateForce ............................ 525, 578
WinClose .............................................. 536
WinGet................................................. 537
WinGetActiveStats ................................. 540
WinGetActiveTitle .................................. 541
WinGetClass.......................................... 541
WinGetPos ............................................ 542
WinGetText........................................... 543
WinGetTitle........................................... 544
WinHide ............................................... 545
WinKill ................................................. 546
WinMaximize......................................... 547
WinMenuSelectItem ............................... 520
WinMinimize.......................................... 548
WinMinimizeAll ....................................... 549
WinMinimizeAllUndo................................ 549
WinMove............................................... 549
WinRestore............................................550
WinSet.................................................. 551
WinSetTitle............................................ 555
WinShow............................................... 556
WinSize (via WinMove)............................ 549
WinWait ................................................ 557
WinWaitActive........................................ 558
WinWaitClose.........................................559
WinWaitNotActive................................... 558
working directory ................................... 148
wParam ................................................ 517
write file ............................................... 111
X
XButton ................................................ 422