# Version 1.0.24 https://github.com/phil294/AHK_X11 ©2022 Philip Waritschlager Original Docs (this site): ©2003-2004 Chris Mallett, portions ©AutoIt Team

What is it?

• Free & open source (GNU General Public License).
• A simple yet powerful hotkey (shortcut key) scripting language, supporting both mouse and keyboard macros (if you're new to scripting, it might be easier than you think; check out the quick-start tutorial).
• A word recognition engine that expands abbreviations as you type them (auto-replace).
• A regular scripting language. The program includes a script compiler that converts a script to an EXE executable. It also includes AutoScriptWriter, a macro recorder written by Larry Keys.
  
• A keyboard, joystick, and mouse remapper.
• AHK_X11 is a complete reimplementation of AutoHotkey for X11-based systems such as most Linux systems. It is still in development as of 2022/08. A lot of work is done but several commands are still missing. You can find installation details below and/or on the GitHub page linked above.
• These docs are based on the original AHK docs from December 2004, complemented by annotations (see Legend above - not super accurate though). Black text was not changed and should work (except some code samples). AHK_X11 only aims at implementing the spec from that time. This "Classic AHK" approach means that more modern features such as expressions or functions are not supported.
• In short, this doc file should be accurate and tell you everything you need.

Who might benefit?

• Those wishing to automate repetitive tasks.
• Those having an interest in creating hotkeys that:
  • aren't limited to only those combinations allowed by Windows;
  • are more flexible and capable of greater complexity than those of most other hotkey apps;
  • are more responsive (take effect more quickly) than standard Windows hotkeys.
• Anyone concerned about, or already suffering from Repetitive Stress Injury (RSI). For example, the mouse wheel can be used as an entire substitute for Alt-Tab.

More benefits

• 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 a set of new commands and benefit from enhancements to old ones.
• Catch silly errors and typos early (at load-time) rather than later (during runtime) when you may be less prepared to deal with them: Each script is thoroughly checked before it begins running.
• Take complete control of your keyboard, joystick, and mouse: AutoHotkey has far better hotkey support than Windows provides (and is more responsive too). It's also more powerful than most commercially available hotkey applications. For example, Windows' built-in hotkeys, such as Win-E and Win-R, can be selectively overridden. Also, any two keys and/or mouse buttons can be combined to become a hotkey.
• Gain a significant boost in performance.

Acknowledgements

A special thanks to Jonathan Bennett, whose generosity in releasing AutoIt2 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 AutoIt2 command set, as well as the Window Spy and the script compiler, were adapted directly from the AutoIt3 source code. So thanks to Jon and the other AutoIt3 authors for those as well.

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

This brief introduction will help you start scripting your own macros and hotkeys right away.

Tutorial Contents

• Installation
• Creating a script
• Launching a program or document
• Sending keystrokes & mouse clicks
• Activating and manipulating windows
• Getting input from the user with MsgBox, InputBox, etc.
• Using variables and the clipboard
• Manipulating files and folders
• Overview of other features

# Installation

1. Download the latest program in portable AppImage format from here.
2. Run it, for example by double clicking. If this does not work, then you also need to mark it as executable. This usually works via right click / file properties.
3. Now the installer should open. Click install and your setup is complete.
4. Please be aware that so far, there is *no* auto-update function. New features are being added all the time right now, so you should probably repeat the above steps then and again. The documentation (this very site) will always be up to date.

# Creating a script

1. Open Windows Explorer and select a directory of your choice.
2. Pull down the File menu and choose New >> AutoHotkey Script (or Text Document).
3. Type a name for the file, ensuring that it ends in .ahk. Example: Test.ahk
4. Right-click the file and choose Edit Script. Open with... -> Your text editor of choice (but *don't* set it as default)
5. On a new blank line, type the following:
   #z::Run www.google.com

The # means the Windows key ("Super key"), so the #z means holding down the Windows key then pressing Z 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:

1. Save and close the file.
2. In Windows Explorer, double-click the script to launch it. A new tray icon appears.
3. Press Win+Z. A web page opens in the default browser.
4. To exit or edit the script, right click its tray icon.

Note: Each script can contain any number of hotkeys (in the absence of hotkeys, a script will perform a series of sequential actions the moment it is launched). In addition, multiple scripts can be running simultaneously, each with its own tray icon.

# Launching a program or document

The Run command is used to launch a program, document, URL, or shortcut, as in the following examples:
Run, gedit
Run, %A_Home%/Documents/Address List.doc

Run, www.yahoo.com
Run, mailto:someone@anywhere.com

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, gedit
^!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, www.google.com
Run, gedit
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_Home%/bin/program

In the above example, %A_Home% is an environment variable maintained by the operating system. By using it rather than something like /home/yourname, the script is made more portable, meaning that it would be more likely to run successfully on another computer with another username.

To have the script wait for the program or document to close before continuing, use RunWait instead of Run. In this example, the MsgBox command will not run until after the user closes Gedit (untested):
RunWait, gedit
MsgBox, The user has finished (Gedit has been closed).

This topic continues here with the following advanced information: launching a program in a minimized/maximized/hidden state, specifying a working directory, passing parameters, using system verbs, and discovering a program's exit code.

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. Be sure that a window such as an editor or draft e-mail message is active before pressing the hotkey:
#s::
Send, Sincerely,{enter}John Smith
return

In the above example, all characters are sent literally except {enter} (which results in a simulated press of the Enter key). The next example illustrates some of the other commonly used special characters:
Send, ^c!{tab}pasted:^v

The above example 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.

Mouse Clicks: To send a mouse click to a window it is first necessary to determine the X & Y coordinates where the click should occur. This can be done with either AutoScriptWriter or Window Spy, which is included with AutoHotkey. The following steps apply to the Window Spy method:

1. Launch Window Spy from the program's tray-icon menu or the Start Menu.
2. 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).
3. 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).
4. Use the coordinates discovered above with the MouseClick command as in this example, which clicks the left mouse button:
   MouseClick, left, 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 with each WinActivate.

Some of the other commonly used window commands are:

• WinWaitActive: Waits for a window to become active (typically used immediately after a Run command).
• IfWinActive: Checks if a window is currently active.
• WinClose: Closes a window.
• WinMove: Moves or resizes a window.
• WinMinimize, WinMaximize, WinRestore: Minimizes, maximizes, or restores a 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
; 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.

# Using variables and the clipboard

All variables are global; that is, their contents may be read or altered by any subroutine in the entire script. In addition, there are no data types: all variables contain strings (sequences of characters or digits). Finally, variables do not need to be declared: the program ensures they exist when needed.

To assign a string to a variable, follow these examples:

MyVar1 = 123
MyVar2 = my string

if MyVar2 = my string
{
	MsgBox MyVar2 contains the string "my string".
}
if MyVar1 >= 100
{
	MsgBox MyVar1 contains a number greater than or equal to 100.
}

To assign the contents of a variable to a second variable, enclose the first variable's name in percent signs. In the example below, MyVarConcatenated will be assigned the string "123 my string" (without the double quotes):

MyVarConcatenated = %MyVar1% %MyVar2%

To compare the contents of a variable with that of another, consider this example:

MyVar = 200
MyVarLimit = 100

if MyVar > %MyVarLimit%
{
	MsgBox The number in MyVar, which is %MyVar%, is beyond the limit of %MyVarLimit%.
}

By contrast, here are some examples of incorrect variable usage:

MyVar2 = MyVar1  ; Wrong because it assigns the literal string "MyVar1" to MyVar2.
if MyVar > MyVarLimit  ; Wrong because there should be percent signs around MyVarLimit.
if %MyVar% > %MyVarLimit%  ; Wrong because MyVar should not have percent signs.

As seen in the examples above, the rule of thumb is to enclose a variable in percent signs whenever it is used on the right side of an assignment or comparison.

Math:AutoHotkey is currently limited to one math operation per line. For example, an assignment that might be written as "x = y + 5" in another language would need to be done in two steps:
x = %y%
x += 5

In the example above, the += symbol means "increase the variable on the left by the number at the right". In a similar way, subtraction, multiplication, and division are accomplished via -=, *=, and /=, respectively. Advanced math operations such as logarithms, trigonometry, raising a number to a power, and bitwise manipulations are possible via the Transform command.

Clipboard: The variable named Clipboard is a special variable containing the current text on the Windows clipboard. It can be used just like any other variable. For example, the following line replaces the current contents of the clipboard with new text:

clipboard = A line of text.`nA second line of text.`n

In the above line, `n (accent followed by the letter "n") is a special string used to indicate a special character: linefeed. This character starts 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.

# Manipulating files and folders

To append text to a file, consider 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

Some of the other commonly used file and folder commands are:

• File-reading Loop: Retrieve the lines in a text file, one by one.
• IfExist: Determine whether a file or folder exists.
• File Loop: Retrieve the files and folders contained in a folder, one at a time.
• FileCopy: Copy one or more files. Use FileCopyDir to copy an entire folder.
• FileMove: Move or rename one or more files. Use FileMoveDir to move an entire folder.
• FileDelete: Delete one or more files. Use FileRemoveDir to delete an entire folder.
• FileRecycle: Send one or more files (or an entire folder) to the recycle bin.
• FileSelectFile and FileSelectFolder: Display a dialog for the user to pick a file or folder.
• 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.

# Overview of other features

(this section is still under development, see the command list for an overview of every command

When are quotation marks used with commands and their parameters?

Single quotes (') and double quotes (") have no special meaning within the AutoHotkey language; they are always treated literally as if they were normal characters. However, when AutoHotkey launches a program or document, the operating system usually requires double quotes around any command-line parameter that contains spaces, such as in this example: Run, gedit "/home/Documents/Address List.txt"

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). Example:
Run, /opt/app/bin, /opt/app

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

The left and right mouse buttons should be assignable normally (for example, "#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+F12, you can then indirectly configure that button as a hotkey by using ^F12:: in the 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 symbols and punctuation marks be defined as hotkeys?

Symbols that don't require the shift key to be held down can be defined normally (except for semicolon, which should be defined as `;::). For example, this line would make accent (`) become a hotkey: `::MsgBox, Accent was pressed.

However, symbols that require the shift key to be held down (such as @ and ?) can be defined as hotkeys by including the SHIFT modifier in the definition of the symbol's unshifted key. For example, this line would make Control-Asterisk become a hotkey: ^+8::MsgBox, Ctrl-* was pressed.

How can a combination of modifier keys be made a hotkey?

The modifier symbols must always apply to a named key. For example, to define Ctrl+Alt+Win as a hotkey, use ^!LWin or ^!RWin rather than ^!#. To define the spacebar, use ^Space rather than "^ ". Note that the modifier keys must be pressed before the named key, so in the first example Ctrl+Alt must be held down prior to pressing LWin or RWin.

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 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.

In the following example, NumpadEnter is made to perform normally except when a window titled "CAD Editor" is active. Note the use of the $ prefix in "$NumpadEnter", which is required to let the hotkey "send itself":

$NumpadEnter::
IfWinNotActive, CAD Editor
{
	Send, {NumpadEnter}
	return
}
; Otherwise, the desired application is active, so do a custom action:
Send, abc
return

This next example is more pure than the above, but it will only work if the "CAD Editor" application is designed to ignore the NumpadEnter key itself. The tilde prefix (~) makes NumpadEnter into a non-suppressed hotkey, meaning that the NumpadEnter keystroke itself is always sent to the active window, the only difference being that it triggers a hotkey action:

~NumpadEnter::
IfWinNotActive, CAD Editor
	return
Send, abc
return

How can a repeating action be stopped without exiting the script?

To stop an action that is repeating inside a Loop, consider the following example hotkey, which 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::
#MaxThreadsPerHotkey 1
if KeepWinZRunning = y  ; This means an underlying thread is already running the loop below.
{
	KeepWinZRunning =  ; Make it blank to signal that thread's loop to stop.
	return  ; End this thread so that the one underneath will resume and see the change.
}
; Otherwise:
KeepWinZRunning = y
Loop,
{
	ToolTip, Press Win-Z again to stop this from flashing.
	Sleep, 1000
	ToolTip
	if KeepWinZRunning =  ; The user signaled the loop to stop by pressing Win-Z again.
		break  ; Break out of this loop.
	Sleep, 1000
}
return

Note: 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.

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

How to avoid trouble with ALT hotkeys that use the Send command?

The trouble is caused by the fact that the ALT key tends to activate the menu bar of the active window. The following example shows a workaround that may fix the problem in some cases: !a::Send, {AltUp}{Alt}Text To Send.

How can context sensitive help for AutoHotkey commands be used in any editor?

Rajat created this script.

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.

How can the output of a command line operation be retrieved?

A small freeware utility cb.zip 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. Example:
RunWait %comspec% /c dir | cb.exe
MsgBox %clipboard% This is possible with the optional option OutputVarStdout.

How to 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 <> 0
   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.

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.

How can MsgBox's button names be changed?

Here is an example.

How can performance be improved for games or at other times when the CPU is under heavy load?

If you find that hotkeys and/or GetKeyState are less responsive than expected while the CPU is under heavy load, raising the script's priority may help. To do this, include the following line near the top of the script, which increases its priority from normal to high. This tells the operating system to pay more attention to it:
Process, Priority, , High

Hotkeys

Hotkeys are defined by creating a subroutine label in a script file with two colons instead of one. In the below example, Win-Y will become a hotkey which implicitly gosubs the #y label, executing the statements until the first return or exit is encountered:

#y::
WinActivate, Untitled - Notepad
return

If a hotkey label needs only a single line, it can be included to the right of the double-colon. In other words, the return is implicit:

#y::WinActivate, Untitled - Notepad

You can use the following symbols to define hotkeys:

(See the Key List for a complete list of key and mouse/joystick button names)

Hotkey labels can be used as if they were normal labels: You can Gosub/Goto them and define more than one hotkey label to do the same subroutine, such as in this example:
^Numpad0::
^Numpad1::
MsgBox, Both of the above hotkeys will execute this subroutine.
return

A key or key combination can be disabled for the entire system by having it do nothing. For example, to disable the right Windows key:
RWIN::return

Hotkeys can be also be created, disabled, or enabled while the script is running by using the Hotkey command.

Note: The program 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.

See advanced features for an overview. Here is some more detailed information:

You can define a custom combination of two keys by using " & " between them. In the below example, you would hold down Numpad0 then press the second key to trigger the hotkey:
Numpad0 & Numpad1::AltTab
Numpad0 & Numpad2::ShiftAltTab

In the above example, Numpad0 becomes a prefix key. Prefix keys can also be assigned their own actions such as in this example, but their action will only be triggered when the key is released and didn't modify any hotkeys while it was held down:
Numpad0::Run, calc.exe

In v1.0.10+, 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 right-click will be non-suppressed 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.

# AltTab and ShiftAltTab are two of the special commands that are only recognized when used with hotkeys. They can also be used with mouse buttons and mousewheel rotation, as can any other script commands as well. Example:
LAlt & LButton::AltTab
LAlt & WheelDown::AltTab
LAlt & WheelUp::ShiftAltTab

The mouse wheel can be made into an entire substitute for Alt-tab. Clicking the button will display the menu and turning the wheel will navigate through it:
MButton::AltTabMenu
WheelDown::AltTab
WheelUp::ShiftAltTab

The other Alt-tab actions available are AltTabAndMenu (if the menu is displayed, move forward in it; otherwise, display the menu) and AltTabMenuDismiss (close the Alt-tab menu). Currently, all Alt-tab actions must be assigned directly to a hotkey as in the examples above (i.e. they can't be used as though they were commands).

You can force the Numlock, Capslock, and Scrolllock keys to be AlwaysOn or AlwaysOff. For example:
SetNumlockState, AlwaysOn

Windows' built-in hotkeys such as Win-E (#e) and Win-R (#r) can be individually overridden by assigning them to an action in the script. This feature is not implemented on Win95/98/ME due to the limitations of those OSes. See the override page for details.

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, such as in this example:
NumpadEnd::
Numpad1::
MsgBox, This hotkey is launched regardless of whether Numlock is on.
return

Magic words, abbreviation expansion (auto-replace), and "hot strings" (requires XP/2k/NT): These are described in the hotstrings section.

Hotstrings and Auto-replace

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).

When the user types a hotstring, its action is triggered, much like a hotkey. However, unlike hotkeys, the keystrokes that comprise a hotstring are never suppressed, that is, they are never hidden from the active window.

To define a hotstring, enclose the triggering abbreviation between pairs of double 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 the user types it. However, by default the user must complete the abbreviation by typing one of the standard ending characters such as space, period, or enter. Ending characters consist of the following: -()[]{}':;"/\,.?!`n `t (note that `n is Enter, `t is Tab, and that there is a plain space between `n and `t). This set of characters can be changed by following this example, which sets the new ending characters for all hotstrings, not just the ones physically beneath it:
#Hotstring EndChars -()[]{}:;'"/\,.?!`n `t

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 this example:
::btw::
MsgBox You typed "btw".
return

Even though the above is not an auto-replace hotstring, the abbreviation typed by the user is erased by default. This is done via automatic backspacing, which can be disabled as described in the options below.

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. Example:
   #Hotstring c r ; Case sensitive and "send raw"
2. By including one or more of the following options inside a hotstring's first pair of colons. Example:
   :cr:Btw::By the way ; Case sensitive and "send raw"

Note: When specifying more than one option from the list below, spaces may be optionally included between them.

B0 (B followed by a zero): Automatic backspacing is not done to erase the abbreviation typed by the user. Use a plain B to turn backspacing back on after it was previously turned off.

C: Case sensitive: When typed by the user, the abbreviation must exactly match the case defined in the script. Use C0 to turn case sensitivity back off. Note: If you need to define two hotstrings that are identical except for their varying case, use extra spaces between the first pair of colons to distinguish one from the other. This is necessary because hotstrings are labels, and each label must be unique. In the below example, the first hotstring is made distinct from the second by including an extra space between its first pair of colons:
:c :ceo::chief executive officer
:c:CEO::Chief Executive Officer

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 typed by the user. Use C0 to make hotstrings conform again.

Hotstrings that conform to typed case will produce the replacement text in all caps if the user typed the abbreviation in all caps. If the user typed only the first letter in caps, the first letter of the replacement will also be capitalized (if it is a letter). If the user typed the case in any other way, the replacement is sent exactly as defined.

Kn: Key-delay: A delay of length 0 is normally done between keystrokes for all hotstrings that use auto-backspacing or auto-replacement. Zero is recommended for most purposes since it is both fast and able to cooperate well with other processes (due to internally doing a Sleep 0). If a different delay is desired, specify for n the new delay. Use -1 to have no delay at all, which is useful to make auto-replacements faster if your CPU is frequently under heavy load from background processes. Only considered for the automatic backspacing. For the speed of the actual typing, use SetKeyDelay instead.

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 a space 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.

P: The priority of the hotstring. This option has no effect on auto-replace hotstrings. Yes it does

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. Use R0 to turn this option back off.

*: An ending character (e.g. space, period, or enter) is not required to trigger the hotstring. Use *0 to turn this option back off. In the example below, the replacement occurs the moment the @ character is typed:
:*:js@::jsmith@somedomain.com

?: 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.

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 Send command in the body of the hotstring's subroutine.Yes they are

The built-in variable A_EndChar contains 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), it will be blank. This variable is useful when making hotstrings that use the Send command or whose behavior should vary depending on which ending character was typed by the user. 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, accents 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 syntax is 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). In the following example, the hotstring would be triggered when the user types "ab" followed by a tab: ::ab`t::

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 only by AutoHotkey's maximum line length, which is 16,383 characters.

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 typed by the user, only the first one will take effect.

Any backspacing done by the user 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 the user's keystrokes. In other words, the hotstring will still fire even though the triggering abbreviation is never visible. In addition, the backspace key will undo the most recently typed keystroke even though you can't see the effect.

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. However, if there are no options between the colons, you must escape the colon pair as in this example: Gosub `::btw

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 wherein 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 from 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.

List of Keys and Mouse/Joystick Buttons

Mouse

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

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

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
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
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

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
Launch_App1
Launch_App2

Scripts

How Scripts Are Run -- The Auto-execute Section

Scripts are optimized and validated when launched. Any syntax errors will be displayed, and they must be corrected before the script can run.

The program loads a script into memory line by line, and each line may be up to 16,383 characters long. After this, it runs the script from the top, continuing until it encounters a Return, Exit, hotkey/hotstring label, or the physical end of the script (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 and hotstrings 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 subroutine launched by a hotkey, hotstring, custom 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
SetKeyDelay
SetMouseDelay
SetWinDelay
SetControlDelay
SetDefaultMouseSpeed
CoordMode
SetStoreCapslockMode
AutoTrim
SetFormat
StringCaseSense

NOTE: 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.

Escape Sequences

AutoHotkey's default escape character is accent ` (upper left corner of most English keyboards). This avoids the need for backslashes in filenames to be escaped. For example, in a .ahk script a filename can be written as /a/b\c/d rather than needing double-backslashes.

Since commas and percent signs have special meaning in the AutoHotkey language, use `, to specify a literal comma and `% to specify an actual percent sign. One of the exceptions to this is MsgBox, which does not require commas to be escaped. See #EscapeChar for a complete list of escape sequences.

Comments in Scripts

Scripts can be commented by using a semicolon at the beginning of a line. 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:

; This line is a full line comment.
WinActivate, Untitled - 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.
*/

Tip: The first comma of any command may be omitted. Example:
MsgBox This is ok.
MsgBox, This is ok too.

# Convert a Script to an EXE executable (ahk2exe)

A script compiler is included with the program.

Once a script is compiled, it becomes a standalone executable, meaning that it can be used even on machines where AutoHotkey isn't present (and such EXEexecutables 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.

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" "Compile with ahk_x11" (only available if the script compiler option was chosen when AutoHotkey was installed). This will create an EXEexecutable (same filename, but without the .ahk) 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. Portable binaries have no icons on Linux.

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] ahk_x11 --compile MyScript.ahk [MyBinary]
   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.

Important 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.

• 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 (semicolon'd lines) originally present will be lost.

• 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: ResHacker will corrupt compiled scripts, which is why only the AutoHotkeySC.bin file should be edited.

Loop, %0%
            {
              StringTrimRight, param, %A_Index%, 0
              MsgBox, 4,, Parameter #%A_Index% is %param%.  Continue?
              IfMsgBox, No
                break
            }

Variables

Introduction

Variables are areas of memory set aside to hold values. A value (or string as it is sometimes called) can be any series of characters or digits. For example, the following line assigns a value to the variable named MyVar:
MyVar = 123abc

To later retrieve the contents of the variable, make a reference to it by enclosing its name in percent signs, as in this example:
MsgBox, The value in the variable named MyVar is %MyVar%.

However, the parameters of some commands are explicitly defined as input or output variables. In these cases, do not enclose the variable in percent signs. For example, neither of the following variables should have percent signs around them: StringLen, OutputVar, InputVar

Variable names may consist of numbers, letters, and the following punctuation: # _ @ $ ? [ ]
(the square brackets might typically be used for arrays, though this is optional). In addition, variable names may start with a number, or even be entirely numeric.

Notes about variable capacity and memory usage:

• 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 =

# Environment Variables vs. "Normal" Variables

Naming Variables to Improve Maintainability

Since all variables are global, in a large or complex script it is usually best to use unique names for variables to reduce the possibility of bugs and unwanted side-effects. For example, to call a subroutine in a way that mimics passing parameters and receiving a return value, a convention similar to the following might be useful:

; Set input "parameters" by using a prefix/acronym to indicate who they're for.
; "gce" stands for "GetColorExists":
gce_x1 = 30
gce_x2 = 50
gce_y1 = 0
gce_y2 = 200
Gosub, GetColorExists
MsgBox The subroutine's output is %ColorExists%.
return

GetColorExists:
...
; Set the output for the caller using the variable name indicated by the subroutine's name:
ColorExists = y
...
return

# Built-in Variables

The following built-in variables can also be used. 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_BatchLines, A_TitleMatchMode, (...more...)
• User Idle Time: A_TimeIdle, A_TimeIdlePhysical
• GUI Windows and Menu Bars: A_Gui, A_GuiControl, A_GuiControlEvent
• 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, ErrorLevel
• Loop: A_Index, (...more...)

Special Characters

# Script Properties

# Date and Time

# Script Settings

User Idle Time

GUI Windows and Menu Bars

# Hotkeys, Hotstrings, and Custom Menu Items

# Operating System and User Info

Misc.

# Loop

The "Last Found" Window

This is the window most recently found by IfWin[Not]Exist, IfWin[Not]Active, WinWait[Not]Active, or WinWait. It can make scripts easier to create and maintain since the WinTitle and WinText of the target window do not need to be repeated for every windowing command. In addition, scripts perform better because they don't need to search for the target window again after it's been found the first time.

The "last found" window can be used by all of the windowing commands except WinWait, WinActivateBottom, and GroupAdd. To use it, simply omit all four window parameters (WinTitle, WinText, ExcludeTitle, and ExcludeText).

Each thread retains its own value of the "last found" window, meaning that if the current thread is interrupted by another, when the original thread is resumed it will still have its original value of of the "last found" window, not that of the interrupting thread.

Related Notes:

• If multiple windows match the WinTitle/Text criteria of a windowing command such as WinMove, the most recently active window is used.
• Almost all of the windowing commands can be told to operate upon the active window by specifying the letter A as the WinTitle parameter and omitting WinText, ExcludeTitle, and ExcludeText.
• In v1.0.09+, all windowing commands can operate upon a class of windows by specifying for WinTitle the class text shown by Window Spy or retrieved by WinGetClass.
• In v1.0.12+, all windowing commands can operate upon a specific window via its unique ID number, which is retrieved by WinGet.
  

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
}


; Make a hotkey to maximize a window.
; Specify just "A" to make it operate on the active window:
^Up::WinMaximize, A

AutoHotkey Command List -- Click on a command name for details.

ClipWait

Waits until the clipboard contains text or files.

Parameters

ErrorLevel

If the wait period expires, ErrorLevel will be set to 1. Otherwise (i.e. the clipboard contains text), 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 checks for non-zero text contents in a loop with slight exponential back-off (max 0.5s).

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.

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 <> 0
{
	MsgBox, The attempt to copy text onto the clipboard failed.
	return
}
MsgBox, clipboard = %clipboard%
return

EnvSet

Writes a value to a variable contained in the environment.

Parameters

ErrorLevel

ErrorLevel is set to 1 if there was a problem or 0 otherwise.

Remarks

This command exists separately from SetEnv because unlike AutoIt2, AutoHotkey does not store its variables in the environment. This is because performance would be worse and also because the OS limits environment variables to 32K (AutoHotkey variables, including the clipboard, are essentially unlimited in size).

Unless EnvUpdate is used, an environment variable set in this way will only be accessible to programs that the script spawns via Run or RunWait.  Once the script terminates, the variables will cease to exist.

Note: An EnvGet command is not provided because referencing a blank or undefined variable will automatically trigger that behavior. For example, in the following line, the value of the ProgramFiles variable (if undefined in the script) will be fetched from the environment:
TargetFile = %ProgramFiles%\Something\setup.ini Use EnvGet to retrieve env vars. AHK_X11 behaves like #NoEnv in newer AHK versions by default.

Related

EnvUpdate, SetEnv, Run, RunWait

Example

EnvSet, AutGUI, Some text to put in the variable.

DriveSpaceFree

Retrieves the free disk space of a drive, in Megabytes.

Parameters

Remarks

OutputVar is set to the amount of free disk space in Megabytes (rounded down to the nearest Megabyte).

Related

Drive, DriveGet

Example

DriveSpaceFree, FreeSpace, %A_Home%

FileAppend

Appends text to a text file.

Parameters

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.

Related

FileReadLine, FileReadLine, IniWrite, file-read loop, FileDelete

Example

FileAppend, Another line.`n, c:\My Documents\Test.txt

FileCopy

Copies one or more files. File modification date is not preserved, file name matching is case sensitive.

Parameters

ErrorLevel

ErrorLevel is set to the number of files that could not be copied due to an error, or 0 otherwise.

Remarks

The operation will continue even if error(s) are encountered.

To copy an entire folder (including its subfolders), use FileCopyDir.

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.

FileCreateDir

Creates a directory/folder.

Parameters

ErrorLevel

ErrorLevel is set to 1 if there was a problem or 0 otherwise.

Remarks

Related

FileRemoveDir

Example

FileCreateDir, /a/b/Folder2

FileDelete

Deletes one or more files.

Parameters

ErrorLevel

ErrorLevel is set to 1 if there was a problem or 0 otherwise.

Remarks

None

Related

FileRecycle, FileCopy, FileMove

Example

FileDelete, /a/b/*.tmp

FileGetSize

Retrieves the size of a file in bytes, KB, or MB.

Parameters

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).

Related

FileGetAttrib, FileSetAttrib, FileGetTime, FileSetTime, FileGetVersion, File-loop

Example

FileGetSize, size, %A_Home%/test.doc ; Retrieve the size in bytes.
FileGetSize, size, /tmp/test.doc, K ; Retrieve the size in Kbytes.

FileReadLine

Reads the specified line from a file and stores the text in a variable.

Parameters

ErrorLevel

ErrorLevel is set to 1 if there was a problem or 0 otherwise.

Remarks

Although any leading and trailing tabs and spaces present in the line will be written to OutputVar, the newline 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 off (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 a file-read loop instead).

Related

FileAppend, file-read loop, IniRead

Example

i = 0
Loop
{
	i += 1
	FileReadLine, line, %A_Home%/Documents/ContactList.txt, %i%
	if ErrorLevel <> 0
		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.
return

FileRead

Reads the specified file into a variable.

Parameters

ErrorLevel

ErrorLevel is set to 1 if there was a problem or 0 otherwise.

Example

i = 0
	FileRead, text, %A_Home%/Documents/ContactList.txt
	MsgBox, text is "%text%"

FileRecycle

Sends a file or directory to the recycle bin, if possible.

Parameters

ErrorLevel

ErrorLevel is set to 1 if there was a problem or 0 otherwise.

Remarks

None

Related

FileRecycleEmpty, FileDelete, FileCopy, FileMove

Example

FileRecycle, %A_Home%/temp files/*.tmp

FileRecycleEmpty

Empties the recycle bin.

Parameters

ErrorLevel

ErrorLevel is set to 1 if there was a problem or 0 otherwise.

Remarks

This commands requires MS Internet Explorer 4 or greater to be installed.

Related

FileRecycle, FileDelete, FileCopy, FileMove

Example

FileRecycleEmpty

FileSelectFile

Displays a standard dialog that allows the user to select file(s).

Parameters

Remarks

OutputVar will be set to the full path and name of file chosen by the user. If the user didn't select a file (e.g. pressed CANCEL), OutputVar will be made blank.

If Options permit it and the user selected more than one file, OutputVar will be set to a list of items, each of which is followed by a newline (`n) character (including the last item). The first item in the list is the directory that contains all of the selected files. The other items are the selected filenames, not including their path. For example:
C:\My Documents\Test [this is the directory in which all the below files reside]
test1.txt [these names are the naked filenames: no path info]
test2.txt
... etc
(See Examples below for more information)

See the RootDir parameter above for how to put a default filename in the dialog's edit field.

Related

FileSelectFolder, MsgBox, InputBox, ToolTip, SplitPath

Example

FileSelectFile, SelectedFile, 3, , Open a file, Text Documents (*.txt)
if SelectedFile =
	MsgBox, The user didn't select anything.
else
	MsgBox, The user selected the following:`n%SelectedFile%


; MULTI-SELECT EXAMPLE:
FileSelectFile, files, 7  ; 7 = Multiselect existing files.
if files =
{
	MsgBox, The user pressed cancel.
	return
}
Loop, parse, files, `n
{
	if A_LoopField =  ; A blank field marks the end of the list.
		break
	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
	}
}
return

FileSelectFolder

Displays a standard dialog that allows the user to select a folder.

Parameters

Remarks

None.

Related

FileSelectFile, MsgBox, InputBox, ToolTip, FileCopyDir, FileMoveDir, SplitPath

Example

FileSelectFolder, OutputVar, , 3
if OutputVar =
	MsgBox, You didn't select a folder.
else
	MsgBox, You selected folder "%OutputVar%".

FileSetAttrib

Changes the attributes of one or more files or folders. Wildcards are supported.

Parameters

ErrorLevel

ErrorLevel is set to the number of files that failed to be changed (if any) or 0 otherwise.

Remarks

The Attributes parameter consists of a collection of operators and attribute letters.

Operators:

Attribute letters:
R = READONLY
A = ARCHIVE
S = SYSTEM
H = HIDDEN
N = NORMAL (this is only valid when used without any other attributes)
O = OFFLINE
T = TEMPORARY
X = EXECUTABLE

Note: Currently, the compression state of files cannot be changed with this command.

Currently, only executable rights (for the current user) can be toggled with this (it switches between 755 and 644 internally). Linux file system permission rights are much more capable than that. For more complex use cases, use chown or chmod with something like: RunWait, chmod 666 filename

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

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.

Parameters

ErrorLevel

ErrorLevel is set to the number of files that failed to be changed (if any) or 0 otherwise.

Remarks

Under Windows 95/98/ME, changing the timestamp of folders is not supported. Attempts to do so are ignored.

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:

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.

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, e.g. 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, , /tmp/*.txt

; Set the modification date (time will be midnight):
FileSetTime, 20040122, %A_Home%/Documents/test.doc

; Set the creation date. The time will be set to 4:55pm:
FileSetTime, 200401221655, %A_Home%/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, /tmp/*.*, M, 1

IfExist / IfNotExist

Checks for the existence of a file or directory.

Parameters

Remarks

None

Related

Blocks, Else, File-loops

Examples

IfExist, /mnt/drive
	MsgBox, The drive exists.
IfExist, %A_Home%/Documents/*.txt
	MsgBox, At least one .txt file exists.
IfNotExist, /tmp/FlagFile.txt
	MsgBox, The target file does not exist.

IniDelete

Deletes a value from a standard format .ini file.

Parameters

ErrorLevel

ErrorLevel is set to 1 if there was a problem or 0 otherwise.

Remarks

A standard ini file looks like:

[SectionName]
Key=Value

Related

IniRead, IniWrite, RegDelete

Example

IniDelete, /tmp/myfile.ini, section2, key

IniRead

Reads a value from a standard format .ini file.

Parameters

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

A standard ini file looks like:

[SectionName]
Key=Value

Related

IniDelete, IniWrite, RegRead

Example

IniRead, OutputVar, /tmp/myfile.ini, section2, key
MsgBox, The value is %OutputVar%.

IniWrite

Writes a value to a standard format .ini file.

Parameters

ErrorLevel

ErrorLevel is set to 1 if there was a problem or 0 otherwise.

Remarks

A standard ini file looks like:

[SectionName]
Key=Value

Related

IniDelete, IniRead, RegWrite

Example

IniWrite, this is a new value, /tmp/myfile.ini, section2, key

Loop (files & folders)

Retrieves the specified files or folders, one at a time.

Parameters

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 (unsure). By contrast, OS features such as the DIR ls command omit hidden files by default.

Files on an NTFS file system are probably always retrieved in alphabetical order. Files on other file systems are retrieved in no particular order. To ensure a particular ordering, use the Sort command as shown in the Examples below.

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:

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, FileSetAttrib, FileSetTime

Examples

; Example #1:
Loop, %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
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, %UserProfile%\Recent\*.*, 1  ; UserProfile exists as an environment variable on some OSes.
	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.
		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 <> 0
			MsgBox, Could not copy "%A_LoopFileFullPath%" to "%CopyDest%\%A_LoopFileName%".
	}
}
Return

Loop (read file contents)

Retrieves the lines in a text file, one by one (performs better than FileReadLine).

Parameters

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 in the file. 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, Database Export.txt
{
	Loop, parse, A_LoopReadLine, %A_Tab%
	{
		MsgBox, Field number %a_index% is %A_LoopField%.
	}
} 

See Loop for information about Blocks, Break, Continue, and the A_Index variable (which exists in every type of loop).

Related

FileReadLine, FileAppend, 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
; this line to overwrite rather than append to any existing file:
;FileDelete, %A_Home%/Documents/Family Addresses.txt

Loop, read, %A_Home%/Documents/Address List.txt, %A_Home%/Documents/Family Addresses.txt
{
	IfInString, A_LoopReadLine, family, FileAppend, %A_LoopReadLine%`n
}

; Example #2: 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%
	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:
	StringTrimLeft, ArrayElement, URLStart%A_Index%, 0
	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%
	}
}

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.

Parameters

ErrorLevel

ErrorLevel is set to 1 if there was a problem or 0 otherwise.

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.

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%, FileSelectFolder

Example

SetWorkingDir, D:\My Folder\Temp

SplitPath

Separates a file name into its name, directory, extension, and drive.

Parameters

Remarks

Any of the output variables may be omitted if the corresponding information is not needed.

If InputVar contains a filename with no path or just a relative path (e.g. Address List.txt), 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.

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 slash, and period (dot), which are processed according to their nature in delimiting the drive letter, directory, and extension of the file.

Related

StringSplit, StringGetPos, StringMid, StringTrimLeft, StringLeft, FileSelectFile, FileSelectFolder

Example

FullFileName = %A_Home%/My Documents/Address List.txt

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

; Or, 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 = /home/your-user-name/My Documents
; ext = txt
; name_no_ext = Address List
; drive = C:

#Include / #IncludeAgain

Causes the script to behave as though the specified file's contents are present.

Parameters

Remarks

#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.

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 not change the line numbering of the main script file.

As with other # directives, this one cannot be executed conditionally. In other words, this example would not work:

if x = 1
	#Include SomeFile.ahk  ; This is invalid.

Related

None

Example

{...} (block)

Denotes a block. Blocks are typically used with Else, Loop, and IF-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 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.

Related

Loop, Else, If

Example

if x = 1
{
	MsgBox, test1
	Sleep, 5
}
else
	MsgBox, test2

Break

Exits (terminates) a loop. Valid only inside a loop.

Parameters

Remarks

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
}

Continue

Skips the rest of the current loop iteration and begins a new one. Valid only inside a loop.

Parameters

Remarks

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 20 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-command evaluates to FALSE.

Remarks

Every use of this command must "belong to" (be associated with) an IF-command above it. An ELSE always belongs to the nearest unclaimed IF-command 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).

Related

See Blocks. Also, every IF-command can use ELSE, including IfWinActive, IfWinExist, IfMsgBox, IfInString, IfBetween, IfIn, and the IF command itself.

Examples

IfWinExist, Untitled - Notepad
{
	WinActivate
	Sleep, 1
}
else
{
	WinActivate, Some Other Window
	Sleep, 1
}


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 {
	Sleep, 1
	Gosub, b2
}

Exit

Exits the current thread or (if the script is not persistent contains no hotkeys) the entire script.

Parameters

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, 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.

Parameters

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.

Parameters

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 might suffer slightly because the the target label must be "looked up" every time it is encountered rather than only once when the script is first loaded.

Related

Return, Blocks, Loop, Goto

Example

Gosub, Label1
MsgBox, The Label1 subroutine has returned (it is finished).
return

Label1:
MsgBox, The Label1 subroutine is now running.
return

Goto

Jumps to the specified label and continues execution.

Parameters

Remarks

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, Else, Blocks, Break, Continue

Example

Goto, MyLabel
...
MyLabel:
Sleep, 100
...

Loop (normal)

Perform a series of command repeatedly: either the specified number of times or until break is encountered.

Parameters

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).

The simplest 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.

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-read loops can operate on the entire contents of a file, one line at a time, and parsing loops can operate on the delimited substrings contained within a string, one field at a time.

Related

File loop, Registry loop, File-read loop, Parsing loop, Break, Continue, Blocks

Examples

Loop, 3
{
	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 (parse a string)

Retrieves substrings (fields) from a string, one by one.

Parameters

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, 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: This one is 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 #3: 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
	}
}

Pause

Pauses the script's current thread.

Parameters

Remarks

Unlike Suspend -- which disables hotkeys -- pause will freeze the current thread (and as a result, all interrupted threads beneath it will lie dormant).

New hotkeys can still be launched while the script is paused, 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 The icon changes to a loading symbol whenever the script's current thread is in a paused state.

This command mirrors the function of the "Pause Script" tray menu item.

A script is always halted (though not officially paused) while its tray menu or main window's menu is displayed.

Related

Suspend, ExitApp, Threads

Example

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 Gosub, Hotkey activation, GroupActivate, or other means.

Parameters

None

Remarks

Due to its hotkey nature, if there is no caller to which to return, Return will do an Exit.

Related

Gosub, Exit, ExitApp, GroupActivate

Example

#z::
MsgBox, The Win-Z hotkey was pressed.
Gosub, WinZ
return

WinZ:
Sleep, 1000
return

SetTimer

Causes a subroutine to be launched automatically and repeatedly at a specified time interval.

Parameters

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 enabled, 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 first execution to be immediate, use the Gosub command immediately after the SetTimer command.

# Similarly, if SetTimer is used on an existing timer and parameter #2 is a number or the word ON, 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. An easy way to reset a timer is to omit all parameters except the first. Example: SetTimer, TimerName

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 behavior may change in future versions so shouldn't be relied upon).

Timers with very short periods might not be able to run as often as expected if the current setting of SetBatchLines restricts the speed of the script too much. Similarly, if the total number of lines to be executed in all timed subroutines is large, you may need to alter SetBatchLines to allow them to run as often as specified.

In addition, 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.

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 the examples).

Whenever a timed subroutine is run, it starts off fresh with the default values for settings such as SetKeyDelay. These defaults can be changed in the auto-execute section.

Although timers will operate when the script is suspended, they will not run whenever any thread is paused. In addition, they do not operate when the user is navigating through the tray icon menu or the main window's menu.

If hotkey response time is critical (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.

To keep a non-hotkey script running -- such as one that contains only timers -- use #Persistent.

Related

Gosub, Return, Threads, Thread, Menu, #Persistent

Examples

; Example #1: Close unwanted windows whenever they appear:
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:
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.
}
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.

Parameters

Remarks

Due to the granularity of the OS's time-keeping system, Delay 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).

The actual delay time may wind up being longer than what was requested if the CPU is under load.

A delay of 0 will yield the remainder of the script's current timeslice to any other processes that need it, in which case an actual delay between 0 and 20ms (or more) may occur. If there are no needy processes, there will be no delay at all. However, a Delay of 0 should always wind up being shorter on most OSes than any longer Delay would have been.

While sleeping, new threads can be launched via hotkey, custom menu item, or timer.

Related

SetKeyDelay, SetMouseDelay, SetControlDelay, SetWinDelay, SetBatchLines

Example

Sleep, 1000 ; 1 second

Suspend

Disables all or selected hotkeys.

Parameters

Remarks

Any hotkey subroutine whose first line is Suspend -- except "Suspend, on" (in v1.0.07+) -- 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.

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. The icon changes to a keyboard symbol.

Related

Pause, ExitApp

Example

^!s::Suspend ; Assign the toggle-suspend function to a hotkey.

GUI

Creates and manages windows and controls. Such windows can be used as data entry forms or custom user interfaces.

Table of Contents

• Menu: Adds or removes a menu bar.
• Color: Sets the background color for the window and/or its controls.
• Font: Sets the typeface, size, style, and text color for subsequently created controls.
• Options: Sets various options for the appearance and behavior of the window.
• Flash: Blinks the window and its taskbar button.
• Show: Displays the window.
• Submit: Saves the user's input and optionally hides the window.
• Cancel: Hides the window.
• Destroy: Deletes the window.
• Default: Changes the current thread's default GUI window number.
• Add: Creates a control. Click one of the following types for details:
  • Text, Edit, Hotkey, Picture
  • GroupBox, Button, Checkbox, Radio
  • DropDownList, ComboBox, ListBox
  • Slider, Progress, Tab
• Positioning and sizing of controls
• Acting upon user input: Variables and G-Labels
• Other options and styles
• Remarks
• Examples

# Color [, WindowColor, ControlColor]

Sets the background color of the window and/or its controls. 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).

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, 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 as in this example:
Gui, Color, EEAA99
WinSet, TransColor, EEAA99, My Window Title ; But first turn DetectHiddenWindows on if needed.

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) at the bottom of this page.

# +/-Option1 +/-Option2 ...

One or more options may be specified immediately after the GUI command. For performance reasons, it is better to do this 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. Example:
Gui, -resize +owner ; Change the current/default GUI window.
Gui, 2:-resize +owner ; Change the second GUI window.

Options other than Resize and Owner require version 1.0.21 or greater.

Border: Provides a thin-line border around the window. This is not common.

Caption: Provides a title bar and a thick window border/edge. [Default]

MaximizeBox: Enables the maximize button in the title bar. This is also included as part of Resize below. MinimizeBox and MaximizeBox can only be used together. They only work before you have run Gui, Show.

MinimizeBox: Enables the minimize button in the title bar. [Default] MinimizeBox and MaximizeBox can only be used together. They only work before you have run Gui, Show.

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.

This option must be used after the window's owner is created but before the owned is created (via a command 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, +owner ; Make #1 window owned by script's main window.

On a related note, to temporarily prevent the user from interacting with a window -- such as while one of its owned windows is visible -- disable the window via "Gui, 1:+0x8000000". To re-enable it later, use "Gui, 1:-0x8000000" followed by "Gui, 1:Show".

Resize: Makes the window resizable and enables its maximize button in the title bar. To avoid enabling the maximize button, specify "+Resize -MaximizeButton".

SysMenu: Provides an icon with a drop-down menu in the upper left corner of the title bar. [Default]

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 in the window 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.

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. You can find a list of Styles with their respective numbers here. Currently, only one code is supported: WS_POPUP (Gui, +0x80000000). This prevents the window from ever grabbing focus. This option only works when you specify it before any other Gui command as the type can only be set at internal window creation time.

(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 style numbers are not yet documented here (since they are rarely used), they can be discovered on the Internet.You can find a list of ExStyles with their respective numbers here. Currently, only one code is supported: WS_EX_NOACTIVATE (Gui, +E0x8000000). It doesn't seem to work really, try WS_POPUP instead (see "Unnamed Style" above).

# Show [, Options, Title]

Makes the window visible, 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). Leave Options blank 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.

For Options, the following single letters are supported but rarely needed due to auto-sizing and centering mentioned above: W (Width), H (Height), X (X-position), and Y (Y-position). Include a number immediately after each option letter. The specified Width and Height are that of the client area, which will often be smaller than the width and height reported by WinGetPos because the client area excludes the title bar, menu bar, and window edges.

Another option is the word Center, which centers the window in both dimensions. Similarly, the string xCenter or yCenter may be specified to center the window in only one dimension. Examples:
Gui, Show, Center
Gui, Show, xCenter y0

In v1.0.24, the word 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. Example: Gui, Show, AutoSize Center

# Submit [, NoHide]

Saves the contents of each control to its associated variable (if any) and hides the window unless the word NoHide is present. If the window does not exist -- perhaps due to having been destroyed via "Gui Destroy" -- this command has no effect.

# Cancel (the word Hide can also be used)

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 this command is not used, all GUI windows are automatically destroyed when the script exits.

# Add, ControlType [, Options, Text]

Adds a control to a parent window (first creating the parent window itself, if necessary).

# ControlType is one of the following:

• Text, Edit, Hotkey, Picture
• GroupBox, Button, Checkbox, Radio
• DropDownList, ComboBox, ListBox
• Slider, Progress, Tab

# Text: Unmodifiable text with no border; often used to label other controls. In this case, Text is the string to display. It may contain linefeeds (`n) to start new lines. 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.

# Edit: An area where free-form text can be typed. In this case, Text is the default text to display inside the edit field (linefeed [`n] may be used to start new lines in a multi-line edit control). 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. Note: To type a literal tab inside a multi-line edit control, the user may press Control-Tab.

The R option is not supported, use W/H instead. However, to make the edit be a multi-line one, specify any R > 1.

When a multi-line edit control is saved to its variable via Gui Submit or GuiControlGet, 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. If the control has word-wrapping enabled, any wrapping that occurs as the user types will not result in 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.

Edit Options (to remove an option rather than adding it, precede it with a minus sign)

# Picture (or Pic): An area containing an image (see last paragraph for supported file types). The Text parameter is the filename of the image, which is assumed to be in %A_WorkingDir% if an absolute path isn't specified. You can also specify a standard icon name by prefixing it with "icon:". Example: Gui, Add, Picture, , icon:appointment-new. 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. 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 height and width are set to zero.

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.

# Button: A pushbutton, which can be pressed to trigger an action. In this case, Text is the name of the button (shown on the button itself), which may include linefeeds (`n) to start new lines. Include the word Default in Options to make it 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 OK button become the default: GuiControl, +default, OK. To later change the window to have no default button, follow this example: GuiControl, -default, OK

# Checkbox: A small box that can be checked or unchecked to represent On/Off, Yes/No, etc. 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 Text parameter is a label displayed next to the box, 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), Text will be word-wrapped as needed, and the control's height will be set automatically. The variable associated with a checkbox (if any) receives the number 1 for checked, 0 for unchecked, and -1 for gray/indeterminate.

# DropDownList (or DDL): A list of choices that is displayed in response to pressing a small button. In this case, Text is is a pipe-delimited list of choices such as Choice1|Choice2|Choice3. 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. 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 will receive the item's position number instead (the first item is 1, the second is 2, etc.).

Options for Size and Position

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:

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.

# 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 point size. 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.

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). A window's margin size is proportional to the font size that was in effect when its first control was added. 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.

# In v1.0.20+, xs and ys 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. 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, which uses the previous section for itself but establishes a new section for subsequent controls.

# Options for Assigning Actions and Variables to Controls

# V: Variable. To associate a variable with a control, include the letter V followed immediately by the name of the variable. Example: vMyEdit. This variable will be given the contents of its control whenever the Gui Submit command is used. If a control is not input-capable -- such as a Text control or GroupBox -- assigning a variable to it can still be helpful since that variable's name serves as the control's unique identifier for use with GuiControl and GuiControlGet. Note: Gui Submit does not change the contents of variables associated with control types such as Text and GroupBox.

# G: Gosub. To launch a subroutine in response to the press of a button, changing of a checkbox/radio, selection of a new choice in a ListBox/ComboBox/DropDownList/Tab control, or the clicking of a Picture or Text control: include the letter G followed immediately by the name of the label to execute. The special label gCancel will perform an implicit "Gui Cancel", but only if no "Cancel" label exists in the script.

The G option may be omitted for a button, in which case an automatic label is assumed. For example, if the script contains an OK button and a ButtonOK label, that label will be launched when the button is pressed. However, 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 "&OK" (that is, containing the letter O underlined as a shortcut key) would have an automatic label of ButtonOK. Similarly, a button titled "Save && Exit" would have an automatic label of ButtonSaveExit. For GUI windows other than the first (see remarks section), the window number is included in front of the button's automatic label, e.g. 2ButtonOK.

You can detect a double-click by checking the contents of the built-in variable A_GuiControlEvent. The following control types support this: Text, Picture, Radio, and ListBox. [requires v1.0.20+]

A label specified by the G option cannot contain spaces because spaces are used to separate items in the options list. To work around this, include an additional label above the desired target label as in this example:

MyLabel:
::my hotstring::
MsgBox Both the above labels will execute this subroutine.
return

The following labels will be automatically associated with a GUI window if they exist in the script:

GuiEscape: Launched when the user presses Escape. If this label is absent, pressing Escape has no effect.

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".

Loop, parse, A_GuiControlEvent, `n
{
	MsgBox, 4,, File number %A_Index% is:`n%A_LoopField%.`n`nContinue?
	IfMsgBox, No, Break
}

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

; To process the files in alphabetical order, follow this example:
FileList = %A_GuiControlEvent%
Sort, FileList
Loop, parse, FileList, `n
{
	MsgBox, 4,, File number %A_Index% is:`n%A_LoopField%.`n`nContinue?
	IfMsgBox, No, Break
}

To have multiple events perform the same subroutine, specify their labels consecutively above the subroutine. For example:
GuiEscape:
GuiClose:
ButtonCancel:
Gui, Cancel ; All of the above labels will execute this subroutine.
return

For windows other than the first (see below), the window's number is used as a prefix, e.g. 2GuiEscape and 2GuiClose.

; Example #1: 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 #2: 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

ButtonOK:
GuiClose:
GuiEscape:
Gui, submit
MsgBox You entered:`n%MyCheckbox%`n%MyRadio%`n%MyEdit%
ExitApp

Example #3: 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:
ExitApp

Example #4: On-screen display (OSD):
CustomColor = EEAA99  ; Can be any RGB color (it will be made transparent below).
Gui, color, %CustomColor%
Gui, font, s24
Gui, add, text, vMyText cLime, XXXXX YYYYY  ; XX & YY serve to auto-size the window.
Gui, show, x0 y400
WinWait, A  ; Set the "last found" window for use with the next two commands.
; Make all pixels of this color transparent and make the text itself translucent (150):
WinSet, TransColor, %CustomColor% 150
WinSet, AlwaysOnTop, On
; Remove the borders. Due to a quirk in Windows, this must be done after transparency:
Gui, -Caption
SetTimer, UpdateOSD, 500
return

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

Example #5: Simple image viewer.  This script requires v1.0.24.
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%
	Width -= 28  ; Allow room for borders and margins inside.
	Height = -1 ; Keep aspect ratio seems best.
}
GuiControl,, Pic, *w%width% *h%height% %file%
Gui, Show, xCenter y0 AutoSize, %file%  ; Resize the window to match the picture size.
return

GuiClose:
ExitApp

GuiControl

Makes a variety of changes to a control in a GUI window.

Parameters

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. All control types are self-explanatory except the following:

Picture: Param3 should be the filename of the new image to load (see Gui for supported file types). In v1.0.24+, one or more of the following options may be specified immediately in front of the filename: *wN (width N), *hN (height N), and *IconN (icon number N). In the following example, the second icon is loaded with a width of 100 and an automatic height to "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. 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.

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 transparent 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.

Slider/Progress: Param3 should be the new position of the slider/bar. 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.

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 have one of the entries pre-selected, include two consecutive pipe characters after it (e.g. Red|Green||Blue). The rest of this paragraph applies only to Tab controls. 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 deleting 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 deleted by means of "GuiControl,, MyTab, |Red|Blue", the sub-controls originally associated with Green will now be associated with Blue.

Text [v1.0.22+]: Behaves the same as the above except for radio buttons and checkboxes, in which case Param3 is treated as the new text/caption even if it is -1, 0, or 1.

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). Example: x10 y20 w200 h100

Focus: Sets keyboard focus to the control.

Enable or Disable: Enables or disables (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.

Show or Hide: Shows or hides the control. For Tab controls, this will also show or hide all of the tab's sub-controls.

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. 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).

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 details).

Font [v1.0.23+]: Changes the control's font to the typeface, size, color, and style currently in effect for its window. That font can be changed beforehand by means such as this example: Gui, Font, s18 cRed Bold, Verdana

+/-Option1 +/-Option2 ... [v1.0.21+]: Add or remove various options and styles. All of the options described in Gui Add 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, many of them cannot be applied or removed after a control has been created. Attempts to do so will silently have no effect, and in most such cases, ErrorLevel will be set to 0 (indicating "no error") rather than 1.

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.

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".

IfMsgBox

Checks which button was pushed by the user during the most recent MsgBox command.

Parameters

Remarks

None

Related

MsgBox

Example

MsgBox, 4, , Would you like to continue?, 5  ; 5-second timeout.
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.

Parameters

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: ErrorLevel is set to 1 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.

Related

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 <> 0
	MsgBox, CANCEL was pressed.
else
	MsgBox, You entered "%UserInput%"

MsgBox

Displays a simple message box with one or more buttons and with optional timeout.

Parameters

Remarks

This command has smart comma handling, so it is usually not necessary to escape commas in the Text parameter.

The Options parameter can be a combination of the following values.

For example, to specify a SYSTEMMODAL box with the YES/NO buttons the Options value would be 4096+4 (4100).

To determine which button the user pressed in the most recent MsgBox, use the IfMsgBox command.

The text on the buttons can be changed by following this example.

The windows shown by this command are a built-in feature of Windows. As such, the X button (close) in the title bar is enabled only when certain buttons are present in the dialog: 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. Pressing Escape on a window without a X still closes the window as if a fictional Cancel button were pressed.

Pressing Control-C while a MsgBox dialog is active will copy its text to the clipboard. This applies to all MsgBoxes, not just those produced by AutoHotkey.

In headless mode (when there is no graphical display), MsgBox falls back to Echo.

Related

IfMsgBox, InputBox, FileSelectFile, FileSelectFolder, ToolTip

Example

MsgBox, This is the 1-param method.  Commas, do, not, need to be escaped.
MsgBox, 4, , This is the 3-param method, non-escaped commas ok.`n`nContinue?
IfMsgBox, No
	return
MsgBox, 4, , This MsgBox will time out in 5 seconds.  Continue?, 5
IfMsgBox, Timeout
	MsgBox, The previous MsgBox timed out.
else IfMsgBox, No
	return