target/docs/Tutorial.htm

<!DOCTYPE html>
<html lang="nl">
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="author" content="tidbit" />
<meta name="description" content="Learn how to download and install AutoHotkey, to create a script, to use hotkeys and hotstrings, to send keystrokes, to run programs, etc." />
<meta name="keywords" content="ahk, autohotkey, tutorial, beginners guide" />
<title>Beginner Tutorial | AutoHotkey</title>
<link href="static/theme.css" rel="stylesheet" type="text/css" />
<script src="static/content.js" type="text/javascript"></script>
</head>
<body>
<h1>AutoHotkey Beginner Tutorial <span style="opacity: 0.4">by tidbit</span></h1>
<h2 id="s0">Table of Contents</h2>
<ol>
    <li><a href="#s1">The Basics</a>
    <ol type="a">
        <li><a href="#s11">Downloading and installing AutoHotkey</a></li>
        <li><a href="#s12">How to create a script</a></li>
        <li><a href="#s13">You cannot merge commands</a></li>
        <li><a href="#s14">How to find the help file on your computer</a></li>
    </ol>
    </li>
    <li><a href="#s2">Hotkeys &amp; Hotstrings</a>
    <ol type="a">
        <li><a href="#s21">Keys and their mysterious symbols</a></li>
        <li><a href="#s22">Window specific hotkeys/hotstrings</a></li>
        <li><a href="#s23">Multiple hotkeys/hotstrings per file</a></li>
        <li><a href="#s24">Examples</a></li>
    </ol>
    </li>
    <li><a href="#s3">Sending Keystrokes</a>
    <ol type="a">
        <li><a href="#s31">Games</a></li>
    </ol>
    </li>
    <li><a href="#s4">Running Programs &amp; Websites</a></li>
    <li><a href="#s5">Commands vs. Functions()</a>
    <ol type="a">
        <li><a href="#s51">Code blocks</a></li>
    </ol>
    </li>
    <li><a href="#s6">Variables</a>
    <ol type="a">
        <li><a href="#s61">When to use percents</a></li>
        <li><a href="#s62">Getting user input</a></li>
        <li><a href="#s63">Other Examples?</a></li>
    </ol>
    </li>
    <li><a href="#s7">Objects</a>
    <ol type="a">
        <li><a href="#s71">Creating Objects</a></li>
        <li><a href="#s72">Using Objects</a></li>
    </ol>
    </li>
    <li><a href="#s8">Other Helpful Goodies</a>
    <ol type="a">
        <li><a href="#s81">The mysterious square brackets</a></li>
        <li><a href="#s82">Finding your AHK version</a></li>
        <li><a href="#s83">Trial and Error</a></li>
        <li><a href="#s84">Indentation</a></li>
        <li><a href="#s85">Asking for Help</a></li>
        <li><a href="#s86">Other links</a></li>
    </ol>
    </li>
</ol>

<h2 id="s1">1 - The Basics</h2>
<p class="note">Before we begin our journey, let me give some advice. Throughout this tutorial you will see a lot of text and a lot of code. For optimal learning power, it is advised that you read the text and <b>try</b> the code. Then, study the code. You can copy and paste most examples on this page. If you get confused, try reading the section again.</p>

<h3 id="s11">a. Downloading and installing AutoHotkey</h3>
<p id="local_note" class="note" style="display: none">Since you're viewing this documentation locally, you've probably already installed AutoHotkey and can skip to section b.</p>
<script type="text/javascript">
  if ('file:mk:ms-its:'.indexOf(location.protocol) != -1)
    document.getElementById("local_note").removeAttribute("style");
</script>
<p>Before learning to use AutoHotkey (AHK), you will need to download it. After downloading it, you may possibly need to install it. But that depends on the version you want. For this guide we will use the Installer since it is easiest to set up.</p>

<p>Text instructions:</p>
<ol>
    <li>Go to the AutoHotkey Homepage: <a href="https://www.autohotkey.com/">https://www.autohotkey.com/</a></li>
    <li>Click Download: <a href="https://www.autohotkey.com/download/ahk-install.exe">https://www.autohotkey.com/download/ahk-install.exe</a></li>
    <li>During installation of AutoHotkey, you will be asked to choose from UNICODE or ANSI. In short, you would probably want to choose UNICODE. It has support for non-English letters and numbers (characters). Keep going until you see an Install button.</li>
    <li>Once done, great! Continue on to section b.</li>
</ol>
<p class="note">For a video instruction, watch <a href="https://youtu.be/HcgQlGeaPHw">Install and Hello World</a> on YouTube.</p>

<h3 id="s12">b. How to create a script</h3>
<p>Once you have AutoHotkey installed, you will probably want it to do stuff. AutoHotkey is not magic, we all wish it was, but it is not. So we will need to tell it what to do. This process is called "Scripting".</p>

<p>Text instructions:</p>
<ol>
    <li>Right-Click on your desktop.</li>
    <li>Find "New" in the menu.</li>
    <li>Click "AutoHotkey Script" inside the "New" menu.</li>
    <li>Give the script a new name. It must end with a .ahk extension. For example: MyScript.ahk</li>
    <li>Find the newly created file on your desktop and right-click it.</li>
    <li>Click "Edit Script".</li>
    <li>A window should have popped up, probably Notepad. If so, SUCCESS!
    <p>So now that you have created a script, we need to add stuff into the file. For a list of all built-in commands, function and variables, see <a href="#s5">section 5</a>.</p>
    <p>Here is a very basic script containing a hotkey which types text using the <a href="commands/Send.htm">Send</a> command when the hotkey is pressed:</p>
    <pre>^j::
Send, My First Script
return</pre>
    <p>We will get more in-depth later on. Until then, here's an explanation of the above code:</p>
    <ul>
        <li>The first line: <code>^j::</code> is the hotkey. <code>^</code> means <kbd>Ctrl</kbd>, <code>j</code> is the letter <kbd>J</kbd>. Anything to the <b>left</b> of <code>::</code> are the keys you need to press.</li>
        <li>The second line: <code>Send, My First Script</code> is how you <strong>send</strong> keystrokes. <code>Send</code> is the command, anything after the comma (,) will be typed.</li>
        <li>The third line: <code>return</code>. This will become your best friend. It literally <strong>stops</strong> code from going any further, to the lines below. This will prevent many issues when you start having a lot of stuff in your scripts.</li>
    </ul>
    </li>
    <li>Save the File.</li>
    <li>Double-click the file/icon in the desktop to run it. Open notepad or (anything you can type in) and press <kbd>Ctrl</kbd> and <kbd>J</kbd>.</li>
    <li>Hip Hip Hooray! Your first script is done. Go get some reward snacks then return to reading the rest of this tutorial.</li>
</ol>

<p class="note">For a video instruction, watch <a href="https://youtu.be/HcgQlGeaPHw">Install and Hello World</a> on YouTube.</p>

<h3 id="s13">c. You cannot merge commands</h3>
<p>When you are making your code, you might have the urge to put several commands on the same line or inside of each other, don't. <a href="#s5">In section 5</a> we'll talk about why it doesn't work as you might expect and what you can do instead.</p>

<h3 id="s14">d. How to find the help file on your computer</h3>
<p>There are a few ways to do this, I'll assume you have it installed to the default locations:</p>
<p>Method 1:</p>
<ol>
    <li>Find the Start menu or Start Orb on your screen, usually in the lower left.</li>
    <li>Click <b>Programs</b> or <b>All Programs</b>.</li>
    <li>Find <b>AutoHotkey</b> in the list.</li>
    <li>You should then see <b>AutoHotkey Help File</b>. Click it.</li>
    <li>Done!</li>
</ol>
<p>Method 2:</p>
<ol>
    <li>Go to your desktop.</li>
    <li>Find <b>My Computer</b> or <b>Computer</b>. Open it.</li>
    <li>Go into your harddrive that contains <b>AutoHotkey</b>. Probably <b>C:\</b> drive.</li>
    <li>Search within all <b>Program Files</b> folders for <b>AutoHotkey</b>.</li>
    <li>Look for <b>AutoHotkey.chm</b> or a file that says AutoHotkey and has a yellow question mark on it.</li>
    <li>Done!</li>
</ol>

<h2 id="s2">2 - Hotkeys &amp; Hotstrings</h2>

<p>What is a hotkey? A hotkey is a key that is hot to the touch. ... Just kidding. It is a key or key combination that the person at the keyboard presses to trigger some actions. For example:</p>
<pre>^j::
Send, My First Script
return</pre>
<p>What is a hotstring? Hotstrings are mainly used to expand abbreviations as you type them (auto-replace), they can also be used to launch any scripted action. For example:</p>
<pre>::ftw::Free the whales</pre>
<p>The difference between the two examples is that the hotkey will be triggered when you press <kbd>Ctrl</kbd>+<kbd>J</kbd> while the hotstring will convert your typed "ftw" into "Free the whales".</p>
<p><i>"So, how exactly does a person such as myself create a hotkey?"</i> Good question. A hotkey is created by using a single pair of colons. The key or key combo needs to go on the <b>left</b> of the <code>::</code>. And the content needs to go below, followed by a <code>return</code>.</p>
<p class="note"><strong>Note:</strong> There are exceptions, but those tend to cause confusion a lot of the time. So it won't be covered in the tutorial, at least, not right now.</p>
<pre>Esc::
MsgBox, Escape!!!!
return
</pre>
<p>A hotstring has a pair of colons on each side of the text you want to trigger the text replacement. While the text to replace your typed text goes on the <b>right</b> of the second pair of colons.</p>
<p>Hotstrings, as mentioned above, can also launch scripted actions. That's fancy talk for <i>"do pretty much anything"</i>. Same with hotkeys.</p>
<pre>::btw::
MsgBox, You typed btw.
return</pre>
<p>A nice thing to know is that you can have many lines of code for each hotkey, hotstring, label, and a lot of other things we haven't talked about yet.</p>
<pre>^j::
MsgBox, Wow!
MsgBox, There are
Run, notepad.exe
WinActivate, Untitled - Notepad
WinWaitActive, Untitled - Notepad
Send, 7 lines{!}{Enter}
SendInput, inside the CTRL{+}J hotkey.
return</pre>

<h3 id="s21">a. Keys and their mysterious symbols</h3>
<p>You might be wondering <i>"How the crud am I supposed to know that ^ means <kbd>Ctrl</kbd>?!"</i>. Well, good question. To help you learn what ^ and other symbols mean, gaze upon this chart:</p>
<table class="info">
    <tr>
        <th class="center">Symbol</th>
        <th abbr="Descr">Description</th>
    </tr>
    <tr>
        <td class="center bold">#</td>
        <td><kbd>Win</kbd> (Windows logo key)</td>
    </tr>
    <tr>
        <td class="center bold">!</td>
        <td><kbd>Alt</kbd></td>
    </tr>
    <tr>
        <td class="center bold">^</td>
        <td><kbd>Ctrl</kbd></td>
    </tr>
    <tr>
        <td class="center bold">+</td>
        <td><kbd>Shift</kbd></td>
    </tr>
    <tr>
        <td class="center bold">&amp;</td>
        <td>An ampersand may be used between any two keys or mouse buttons to combine them into a custom hotkey.</td>
    </tr>
</table>
<p><strong>(For the full list of symbols, see the <a href="Hotkeys.htm">Hotkey</a> page)</strong></p>
<p>Additionally, for a list of all/most hotkey names that can be used on the <b>left</b> side of a hotkey's double-colon, see <a href="KeyList.htm">List of Keys, Mouse Buttons, and Joystick Controls</a>.</p>
<p>You can define a custom combination of two (and only two) keys (except joystick buttons) by using <code>&nbsp;&amp;&nbsp;</code> between them. In the example below, you would hold down Numpad0 then press Numpad1 or Numpad2 to trigger one of the hotkeys:</p>

<pre>Numpad0 &amp; Numpad1::
MsgBox, You pressed Numpad1 while holding down Numpad0.
return

Numpad0 &amp; Numpad2::
Run, notepad.exe
return</pre>

<p>But you are now wondering if hotstrings have any cool modifiers since hotkeys do. Yes, they do! Hotstring modifiers go between the first set of colons. For example:</p>
<pre>:*:ftw::Free the whales</pre>

<p class="note">Visit <a href="Hotkeys.htm">Hotkeys</a> and <a href="Hotstrings.htm">Hotstrings</a> for additional hotkey and hotstring modifiers, information and examples.</p>
<h3 id="s22">b. Window specific hotkeys/hotstrings</h3>

<p>Sometime you might want a hotkey or hotstring to only work (or be disabled) in a certain window. To do this, you will need to use either of these fancy commands with a # in-front of them:</p>
<pre>#IfWinActive
#IfWinExist</pre>
<p>These special commands (technically called "directives") create context-sensitive hotkeys and hotstrings. Simply specify a window title. But in some cases you might want to specify criteria such as HWND, group or class. Those are a bit advanced and are covered more in-depth here: <a href="misc/WinTitle.htm">The WinTitle Parameter &amp; the Last Found Window</a>.</p>
<pre>#IfWinActive Untitled - Notepad
#Space::
MsgBox, You pressed WIN+SPACE in Notepad.
return</pre>
<p>To turn off context sensitivity for subsequent hotkeys or hotstrings, specify any #IfWin directive but leave all of its parameters blank. For example:</p>
<pre>
<em>; Untitled - Notepad</em>
#IfWinActive Untitled - Notepad
!q::
MsgBox, You pressed ALT+Q in Notepad.
return

<em>; Any window that isn't Untitled - Notepad</em>
#IfWinActive
!q::
MsgBox, You pressed ALT+Q in any window.
return</pre>
<p>When #IfWin directives are never used in a script, all hotkeys and hotstrings are enabled for all windows.</p>
<p>The #IfWin directives are positional: they affect all hotkeys and hotstrings physically beneath them in the script. They are also mutually exclusive; that is, only the most recent one will be in effect.</p>
<pre><em>; Notepad</em>
#IfWinActive ahk_class Notepad
#Space::
MsgBox, You pressed WIN+SPACE in Notepad.
return
::msg::You typed msg in Notepad

<em>; MSPaint</em>
#IfWinActive Untitled - Paint
#Space::
MsgBox, You pressed WIN+SPACE in MSPaint!
return
::msg::You typed msg in MSPaint!</pre>
<p class="note">For more in-depth information and similar commands, check out the <a href="commands/_IfWinActive.htm">#IfWinActive</a> page.</p>
<h3 id="s23">c. Multiple hotkeys/hotstrings per file</h3>
<p>This, for some reason crosses some people's minds. So I'll set it clear: AutoHotkey has the ability to have <i>as many</i> hotkeys and hotstrings in one file as you want. Whether it's 1, or 3253 (or more).</p>
<pre>#i::
Run, https://www.google.com/
return

^p::
Run, notepad.exe
return

~j::
Send, ack
return

:*:acheiv::achiev
::achievment::achievement
::acquaintence::acquaintance
:*:adquir::acquir
::aquisition::acquisition
:*:agravat::aggravat
:*:allign::align
::ameria::America</pre>
<p>The above code is perfectly acceptable. Multiple hotkeys, multiple hotstrings. All in one big happy script file.</p>

<h3 id="s24">d. Examples</h3>
<pre class="NoIndent">::btw::by the way  <em>; Replaces "btw" with "by the way" as soon as you press an <a href="Hotstrings.htm#EndChars">default ending character</a>.</em></pre>
<pre class="NoIndent">:*:btw::by the way  <em>; Replaces "btw" with "by the way" without needing an ending character.</em></pre>
<pre class="NoIndent">^n::  <em>; CTRL+N hotkey</em>
Run, notepad.exe  <em>; Run Notepad when you press CTRL+N.</em>
return  <em>; This ends the hotkey. The code below this will not be executed when pressing the hotkey.</em></pre>
<pre class="NoIndent">^b::  <em>; CTRL+B hotkey</em>
Send, {Ctrl down}c{Ctrl up}  <em>; Copies the selected text. ^c could be used as well, but this method is more secure.</em>
SendInput, [b]{Ctrl down}v{Ctrl up}[/b] <em>; Wraps the selected text in BBCode tags to make it bold in a forum.</em>
return  <em>; This ends the hotkey. The code below this will not be executed when pressing the hotkey.</em></pre>

<h2 id="s3">3 - Sending Keystrokes</h2>
<p>So now you decided that you want to send (type) keys to a program. We can do that. Use the <a href="commands/Send.htm">Send</a> command. This command literally sends keystrokes, to simulate typing or pressing of keys.</p>
<p>But before we get into things, we should talk about some common issues that people have.</p>
<p>Just like hotkeys, the Send command has special keys too. <a href="commands/Send.htm">Lots and lots of them</a>. Here are the four most common symbols:</p>
<table class="info">
    <tr>
        <th class="center">Symbol</th>
        <th abbr="Descr">Description</th>
    </tr>
    <tr>
        <td class="center bold">!</td>
        <td>Sends <kbd>Alt</kbd>. For example, <code>Send, This is text!a</code> would send the keys "This is text" and then press <kbd>Alt</kbd>+<kbd>A</kbd>. <strong>Note</strong>: <code>!A</code> produces a different effect in some programs than <code>!a</code>. This is because <code>!A</code> presses <kbd>Alt</kbd>+<kbd>Shift</kbd>+<kbd>A</kbd> and <code>!a</code> presses <kbd>Alt</kbd>+<kbd>A</kbd>. If in doubt, use lowercase.</td>
    </tr>
    <tr>
        <td class="center bold">+</td>
        <td>Sends <kbd>Shift</kbd>. For example, <code>Send, +abC</code> would send the text "AbC", and <code>Send, !+a</code> would press <kbd>Alt</kbd>+<kbd>Shift</kbd>+<kbd>A</kbd>.</td>
    </tr>
    <tr>
        <td class="center bold">^</td>
        <td>Sends <kbd>Ctrl</kbd>. For example, <code>Send, ^!a</code> would press <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>A</kbd>, and <code>Send, ^{Home}</code> would send <kbd>Ctrl</kbd>+<kbd>Home</kbd>. <strong>Note</strong>: <code>^A</code> produces a different effect in some programs than <code>^a</code>. This is because <code>^A</code> presses <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>A</kbd> and <code>^a</code> presses <kbd>Ctrl</kbd>+<kbd>A</kbd>. If in doubt, use lowercase.</td>
    </tr>
    <tr>
        <td class="center bold">#</td>
        <td>Sends <kbd>Win</kbd> (the key with the Windows logo) therefore <code>Send #e</code> would hold down <kbd>Win</kbd> and then press <kbd>E</kbd>.</td>
    </tr>
</table>
<p>The <a href="commands/Send.htm">gigantic table on the Send page</a> shows pretty much every special key built-in to AHK. For example: <code>{Enter}</code> and <code>{Space}</code>.</p>
<p class="warning"><strong>Caution:</strong> This table <b>does not</b> apply to <a href="Hotkeys.htm">hotkeys</a>. Meaning, you do not wrap <kbd>Ctrl</kbd> or <kbd>Enter</kbd> (or any other key) inside curly brackets when making a hotkey.</p>
<p>An example showing what shouldn't be done to a hotkey:</p>
<pre><em>; When making a hotkey...
; WRONG</em>
{LCtrl}::
Send, AutoHotkey
return

<em>; CORRECT</em>
LCtrl::
Send, AutoHotkey
return</pre>
<p>A common issue lots of people have is, they assume that the curly brackets are put in the documentation pages just for fun. But in fact <b>they are needed</b>. It's how AHK knows that <code>{!}</code> means "exclamation point" and not "press <kbd>Alt</kbd>". So please remember to check the table on the <a href="commands/Send.htm">Send</a> page and make sure you have your brackets in the right places. For example:</p>
<pre>Send, This text has been typed{!} <em>; Notice the ! between the curly brackets? That's because if it wasn't, AHK would press the ALT key.</em>
</pre>
<pre><em>; Same as above, but with the ENTER key. AHK would type out "Enter" if
; it wasn't wrapped in curly brackets.</em>
Send, Multiple Enter lines have Enter been sent. <em>; WRONG</em>
Send, Multiple{Enter}lines have{Enter}been sent. <em>; CORRECT</em>
</pre>
<p>Another common issue is that people think that <b>everything</b> needs to be wrapped in brackets with the Send command. That is FALSE. If it's not in the chart, it does not need brackets. You do <b>not</b> need to wrap common letters, numbers or even some symbols such as <code>.</code> (period) in curly brackets. Also, with the Send commands you are able to send more than one letter, number or symbol at a time. So no need for a bunch of Send commands with one letter each. For example:</p>
<pre>Send, {a}       <em>; WRONG</em>
Send, {b}       <em>; WRONG</em>
Send, {c}       <em>; WRONG</em>
Send, {a}{b}{c} <em>; WRONG</em>
Send, {abc}     <em>; WRONG</em>
Send, abc       <em>; CORRECT</em></pre>

<p>To hold down or release a key, enclose the key name in curly brackets and then use the word UP or DOWN. For example:</p>
<pre><em>; This is how you hold one key down and press another key (or keys).
; If one method doesn't work in your program, please try the other.</em>
Send, ^s                     <em>; Both of these send CTRL+S</em>
Send, {Ctrl down}s{Ctrl up}  <em>; Both of these send CTRL+S</em>
Send, {Ctrl down}c{Ctrl up}
Send, {b down}{b up}
Send, {Tab down}{Tab up}
Send, {Up down}  <em>; Press down the up-arrow key.</em>
Sleep, 1000      <em>; Keep it down for one second.</em>
Send, {Up up}    <em>; Release the up-arrow key.</em></pre>

<p>But now you are wondering <i>"How can I make my really long Send commands readable?"</i>. Easy. Use what is known as a continuation section. Simply specify an opening parenthesis on a new line, then your content, finally a closing parenthesis on its own line. For more information, read about <a href="Scripts.htm#continuation">Continuation Sections</a>.</p>
<pre>Send,
(
Line 1
Line 2
Apples are a fruit.
)</pre>
<p class="note"><strong>Note:</strong> There are several different forms of Send. Each has their own special features. If one form of Send does not work for your needs, try another type of Send. Simply replace the command name "Send" with one of the following: SendRaw, SendInput, SendPlay, SendEvent. For more information on what each one does, <a href="commands/Send.htm">read this</a>.</p>

<h3 id="s31">a. Games </h3>
<p class="warning"><strong>This is important:</strong> A lot of games, especially modern ones, have cheat prevention software. Things like GameGuard, Hackshield, PunkBuster and several others. Not only is bypassing these systems in violation of the games policies and could get you banned, they are complex to work around.</p>
<p>If a game has a cheat prevention system and your hotkeys, hotstrings and Send commands do not work, you are out of luck. However there are methods that can increase the chance of working in some games, but there is no magical <i>"make it work in my game now!!!"</i> button. So try <b>ALL</b> of these before giving up.</p>

<p>There are also known issues with DirectX. If you are having issues and you know the game uses DirectX, try the stuff described on the <a href="FAQ.htm#games">FAQ</a> page. More DirectX issues may occur when using <a href="commands/PixelSearch.htm">PixelSearch</a>, <a href="commands/PixelGetColor.htm">PixelGetColor</a> or <a href="commands/ImageSearch.htm">ImageSearch</a>. Colors might turn out black (0x000000) no matter the color you try to get. You should also try running the game in windowed mode, if possible. That fixes some DirectX issues.</p>
<p>There is no single solution to make AutoHotkey work in all programs. If everything you try fails, it may not be possible to use AutoHotkey for your needs.</p>

<h2 id="s4">4 - Running Programs &amp; Websites</h2>
<p>To run a program such as <i>mspaint.exe, calc.exe, script.ahk</i> or even a folder, you can use the <a href="commands/Run.htm">Run</a> command. It can even be used to open URLs such as <a href="https://www.autohotkey.com/">https://www.autohotkey.com/</a> . If your computer is setup to run the type of program you want to run, it's very simple:</p>
<pre><em>; Run a program. Note that most programs will require a FULL file path:</em>
Run, %A_ProgramFiles%\Some_Program\Program.exe

<em>; Run a website:</em>
Run, https://www.autohotkey.com</pre>
<p>There are some other advanced features as well, such as command line parameters and CLSID. If you want to learn more about that stuff, visit the <a href="commands/Run.htm">Run</a> page. </p>
<p>Here are a few more samples:</p>
<pre><em>; Several programs do not need a full path, such as Windows-standard programs:</em>
Run, notepad.exe
Run, mspaint.exe

<em>; Run the "My Documents" folder using a <a href="Variables.htm#BuiltIn">built-in variable</a>:</em>
Run, %A_MyDocuments%

<em>; Run some websites:</em>
Run, https://www.autohotkey.com
Run, https://www.google.com</pre>
<p class="note">For more in-depth information and examples, check out the <a href="commands/Run.htm">Run</a> page.</p>

<h2 id="s5">5 - Commands vs. Functions()</h2>
<p>AutoHotkey has two main types of things used by the scripter to create code: Commands and functions.</p>
<p class="note">A list of all commands and built-in functions can be found <a href="commands/index.htm">here</a>.</p>
<h3 id="Commands">Commands</h3>
<p>You can tell what a command is by looking at its syntax (the way it looks). Commands do not use parentheses around the parameters like functions do. So a command would look like this:</p>
<pre>Command, Parameter1, Parameter2, Parameter3</pre>
<p>When using commands, you cannot squish other commands onto the same line as a previous command (exception: <a href="commands/IfEqual.htm">IfEqual</a>). You cannot put commands inside the parameters of other commands. For example:</p>
<pre>MsgBox, Hello Run, notepad.exe   <em>; Wrong</em>
MsgBox, Hello, Run, notepad.exe  <em>; Wrong</em>

MsgBox, Hello      <em>; Correct</em>
Run, notepad.exe</pre>

<p>Commands also differ from function in that they use "legacy syntax". This means that you <strong>need</strong> percent signs around a variable, such as <code>%Var%</code>, and that any text and numbers do not need to be in quotation marks, such as <code>This is some text</code>. Additionally, you cannot do math in the parameters, unlike functions.</p>
<p class="note">You can do math in parameters if you force an expression with a single <code>%</code>, but that will not be covered.</p>
<h3 id="Functions">Functions</h3>
<p>As stated above, functions are different because they use parentheses. A typical function looks like:</p>
<pre>Function(Parameter1, Parameter2, Parameter3)</pre>
<p>Functions have a few main differences:</p>
<ol>
    <li>You can do math in them:
        <pre>SubStr(37 * 12, 1, 2)
SubStr(A_Hour - 12, 2)</pre>
    </li>
    <li>Variables do not need to be wrapped in percent signs:
        <pre>SubStr(A_Now, 7, 2)</pre>
    </li>
    <li>Functions can go inside of functions:
        <pre>SubStr(A_AhkPath, InStr(A_AhkPath, "AutoHotkey"))</pre>
    </li>
    <li>Text needs to be wrapped in quotes:
        <pre>SubStr("I'm scripting, awesome!", 16)</pre>
    </li>
</ol>

<p>A function usually return a value differently than a command does. Commands need an <i>OutputVar</i> parameter, functions do not. The most common way assigning the value of a function to a variable is like so:</p>
<pre><span style="color:#ff4400"><b>MyVar</b></span> := SubStr("I'm scripting, awesome!", 16)</pre>
<p class="note">This isn't the only way, but the most common. You are using <code>MyVar</code> to store the return value of the function that is to the right of the <code>:=</code> operator. See <a href="Functions.htm">Functions</a> for more details.</p>
<p>In short:</p>
<pre><em>; These are commands:</em>
MsgBox, This is some text.
StringReplace, Output, Input, AutoHotKey, AutoHotkey, All
SendInput, This is awesome{!}{!}{!}

<em>; These are functions:</em>
SubStr("I'm scripting, awesome!", 16)
FileExist(VariableContainingPath)
Output := SubStr("I'm scripting, awesome!", 16)</pre>

<h3 id="s51">a. Code blocks</h3>
<p><a href="commands/Block.htm">Code blocks</a> are lines of code surrounded by little curly brackets (<code>{</code> and <code>}</code>). They group a section of code together so that AutoHotkey knows it's one big family and that it needs to stay together. They are most often used with functions and control flow statements such as <a href="commands/IfExpression.htm">If</a> and <a href="commands/Loop.htm">Loop</a>. Without them, only the first line in the block is called.</p>
<p>In the following code, both lines are run only if <em>MyVar</em> equals 5:</p>
<pre>if (MyVar = 5)
{
    MsgBox, MyVar equals %MyVar%!!
    ExitApp
}</pre>
<p>In the following code, the message box is only shown if <em>MyVar</em> equals 5. The script will always exit, even if <em>MyVar</em> <b>is not</b> 5:</p>
<pre>if (MyVar = 5)
    MsgBox, MyVar equals %MyVar%!!
    ExitApp</pre>
<p>This is perfectly fine since the if-statement only had one line of code associated with it. It's exactly the same as above, but I outdented the second line so we know it's separated from the if-statement:</p>
<pre>if (MyVar = 5)
    MsgBox, MyVar equals %MyVar%!!
MsgBox, We are now 'outside' of the if-statement. We did not need curly brackets since there was only one line below it.</pre>

<h2 id="s6">6 - Variables</h2>
<p><a href="Variables.htm">Variables</a> are like little post-it notes that hold some information. They can be used to store text, numbers, data from functions and commands or even mathematical equations. Without them, programming and scripting would be much more tedious.</p>
<p>Variables can be assigned a few ways. We'll cover the most common forms. Please pay attention to the equal sign (<code>=</code>).</p>
<dl>
    <dt>Legacy text assignment</dt>
    <dd>
        <pre class="NoIndent">MyVar = Text</pre>
        <p>This is the simplest form for a variable, a legacy assignment. Simply type in your text and done.</p>
    </dd>
    <dt>Legacy variable assignment</dt>
    <dd>
        <pre class="NoIndent">MyVar = %MyVar2%</pre>
        <p>Same as above, but you are assigning a value of a variable to another variable.</p>
    </dd>
    <dt>Legacy mixed assignment</dt>
    <dd>
        <pre class="NoIndent">MyVar = %MyVar2% some text %MyVar3%.</pre>
        <p>A combination of the two legacy assignments above.</p>
    </dd>
    <dt>Expression text assignment</dt>
    <dd>
        <pre class="NoIndent">MyVar := "Text"</pre>
        <p>This is an expression assignment, due to the <code>:</code> before the <code>=</code>. Any text needs to be in quotes.</p>
    </dd>
    <dt>Expression variable assignment</dt>
    <dd>
        <pre class="NoIndent">MyVar := MyVar2</pre>
        <p>In expression mode, variables do not need percent signs.</p>
    </dd>
    <dt>Expression number assignment</dt>
    <dd>
        <pre class="NoIndent">MyVar := 6 + 8 / 3 * 2 - Sqrt(9)</pre>
        <p>Thanks to expressions, you can do math!</p>
    </dd>
    <dt>Expression mixed assignment</dt>
    <dd>
        <pre class="NoIndent">MyVar := "The value of 5 + " MyVar2 " is: " 5 + MyVar2</pre>
        <p>A combination of the three expression assignments above.</p>
    </dd>
</dl>
<p class="note">Equal signs (<b>=</b>) with a symbol in front of it such as <code>:=</code> <code>+=</code> <code>-=</code> <code>.=</code> etc. are called <b>assignment operators</b> and always require an expression.</p>

<h3 id="s61">a. When to use percents</h3>
<p>One of the most common issues with AutoHotkey involving variables is when to use the percent signs (<b>%</b>). Hopefully this will clear some confusion.</p>
<p>When to use percent signs:</p>
<ul>
    <li>When you are using commands (see above), except when the parameter is <em>OutputVar</em> or <em>InputVar</em>.</li>
    <li>When you are assigning a value to a variable using the legacy mode (an equal sign with no symbol in front of it).</li>
</ul>
<p>When <b>not</b> to use percent signs:</p>
<ul>
    <li>In parameters that are input or output variables. For example: <code>StringLen, <strong>OutputVar</strong>, <strong>InputVar</strong></code></li>
    <li>On the left side of an assignment: <code><strong>Var</strong> = 123abc</code></li>
    <li>On the left side of legacy (non-expression) if-statements: <code>if <strong>Var1</strong> &lt; %Var2%</code></li>
    <li>Everywhere in expressions. For example:
      <pre>
  if (<strong>Var1</strong> != <strong>Var2</strong>)
  <strong>Var1</strong> := <strong>Var2</strong> + 100</pre></li>
</ul>

<h3 id="s62">b. Getting user input</h3>
<p>Sometimes you want to have the user to choose the value of stuff. There are several ways of doing this, but the simplest way is <a href="commands/InputBox.htm">InputBox</a>. Here is a simple example on how to ask the user a couple of questions and doing some stuff with what was entered:</p>
<pre>InputBox, OutputVar, Question 1, What is your first name?
if (OutputVar = "Bill")
    MsgBox, That's an awesome name`, %OutputVar%.

InputBox, OutputVar2, Question 2, Do you like AutoHotkey?
if (OutputVar2 = "yes")
    MsgBox, Thank you for answering %OutputVar2%`, %OutputVar%! We will become great friends.
else
    MsgBox, %OutputVar%`, That makes me sad.</pre>

<h3 id="s63">c. Other Examples?</h3>
<pre class="NoIndent"><a href="commands/MsgBox.htm">MsgBox</a>, 4,, Would you like to continue?
<a href="commands/IfMsgBox.htm">IfMsgBox</a>, No
    return  <em>; If No, stop the code from going further.</em>
MsgBox, You pressed YES.  <em>; Otherwise, the user picked yes.</em></pre>
<pre class="NoIndent"><em>; Some examples showing when to use percents and when not:</em>
Var = Text  <em>; Assign some text to a variable (legacy).</em>
Number := 6  <em>; Assign a number to a variable (expression).</em>
Var2 = %Var%  <em>; Assign a variable to another (legacy).</em>
Var3 := Var  <em>; Assign a variable to another (expression).</em>
Var4 .= Var  <em>; Append a variable to the end of another (expression).</em>
Var5 += Number  <em>; Add the value of a variable to another (expression).</em>
Var5 -= Number  <em>; Subtract the value of a variable from another (expression).</em>
Var6 := SubStr(Var, 2, 2)  <em>; Variable inside a function. This is always an expression.</em>
Var7 = %Var% Text  <em>; Assigns a variable to another with some extra text (legacy).</em>
Var8 := Var " Text"  <em>; Assigns a variable to another with some extra text (expression).</em>
MsgBox, %Var%  <em>; Variable inside a command. </em>
StringSplit, Var, Var, x  <em>; Variable inside a command that uses InputVar and OutputVar.</em>
if (Number = 6)  <em>; Whenever an IF has parentheses, it'll be an expression. So no percent signs.</em>
if (Var != Number)  <em>; Whenever an IF has parentheses, it'll be an expression. So no percent signs.</em>
if Number = 6  <em>; Without parentheses, the IF is legacy. However, only variables on the 'right side' need percent signs. </em>
if Var1 &lt; %Var2%  <em>; Without parentheses, the IF is legacy. However, only variables on the 'right side' need percent signs.</em></pre>
<h2 id="s7">7 - Objects</h2>
<p><a href="Objects.htm">Objects</a> are a way of organizing your data for more efficient usage. Sometimes objects are referred to as arrays, but it's important to note that all arrays are just objects. We call objects different things depending on what we are using them for, but all objects are the same.</p>
<p>An object is basically a collection of variables. The variable names are known as "Keys", and the contents of the variables are "Values".</p>
<p>When you hear people calling an object an <i>array</i> or <i>indexed array</i>, it usually means that all the keys are sequential numbers 1 and up. When you hear people calling an object an <i>associative array</i>, it means that the keys are either strings (text) or non-sequential numbers. Sometimes it's a mix of both, and sequential numbers too!</p>
<p>There are no restrictions to what a key or value can be, and they can even be other arrays! When the values are arrays too, this is referred to as a <i>nested array</i>, and these will be explained later.</p>
<p>There are a number of reasons you might want to use an object for something. Some examples:</p>
<ul>
    <li>You want to have a numbered list of things, such as a grocery list (this would be referred to as an indexed array)</li>
    <li>You want to represent a grid, perhaps for a board game (this would be done with nested objects)</li>
    <li>You have a list of things where each thing has a name, such as the characteristics of a fruit (this would be referred to as an associative array)</li>
</ul>

<h3 id="s71">a. Creating Objects</h3>
<p>There are a few ways to create an object, and the most common ones are listed below:</p>
<dl>
    <dt>Bracket syntax</dt>
    <dd>
        <pre class="NoIndent">MyObject := ["one", "two", "three", 17]</pre>
        <p>This will start you off with what is sometimes called an "indexed array". An indexed array is an object representing a list of items, numbered 1 and up. In this example, the value <code>"one"</code> is stored in object key <code>1</code> (aka index 1), and the value <code>17</code> is stored in object key <code>4</code> (aka index 4).</p>
    </dd>
    <dt>Brace syntax</dt>
    <dd>
        <pre class="NoIndent">Banana := {"Color": "Yellow", "Taste": "Delicious", "Price": 3}</pre>
        <p>This will let you start of by defining what is sometimes called an "associative array". An associative array is a collection of data where each item has a name. In this example, the value <code>"Yellow"</code> is stored in the object key <code>"Color"</code>. Also, the value <code>3</code> is stored in the object key <code>"Price"</code>.</p>
    </dd>
    <dt>Array function</dt>
    <dd>
        <pre class="NoIndent">MyObject := Array("one", "two", "three", 17)</pre>
        <p>This is equivalent to the bracket syntax, but wrapped in a function.</p>
    </dd>
    <dt>Object function</dt>
    <dd>
        <pre class="NoIndent">Banana := Object("Color", "Yellow", "Taste", "Delicious", "Price", 3)</pre>
        <p>This is equivalent to the brace syntax, but wrapped in a function.</p>
    </dd>
</dl>
<p>It's important to remember that every one of these definitions all create the same thing (objects), just with different keys.</p>

<h3 id="s72">b. Using Objects</h3>
<p>There are many ways to use objects, including retrieving values, setting values, adding more values, and more.</p>

<h4 id="To_set_values">To set values:</h4>
<dl>
    <dt>Bracket notation</dt>
    <dd>
        <pre class="NoIndent">Banana["Pickled"] := True <em>; This banana has been pickled. Eww.</em></pre>
        <p>Setting values in an object is as simple as setting the value of a variable. All you have to do is put your bracket notation on the left side of an expression assignment operator <code>:=</code>.</p>
    </dd>
    <dt>Dot notation</dt>
    <dd>
        <pre class="NoIndent">Banana.Consistency := "Mushy"</pre>
        <p>The same as above but with the dot notation.</p>
    </dd>
</dl>

<h4 id="To_retrieve_values">To retrieve values:</h4>
<dl>
    <dt>Bracket notation</dt>
    <dd>
        <pre class="NoIndent">Value := Banana["Color"]</pre>
        <p>This allows you to use an expression as the key to get the value from your object. In this case, I used the simple expression <code>"Color"</code>, which is (unsurprisingly) the key <code>Color</code>. You will get a message box with the word "Yellow", because that is what we set the key <code>Color</code> to in the <a href="#s71">previous section</a>.</p>
    </dd>
    <dt>Dot notation</dt>
    <dd>
        <pre class="NoIndent">Value := Banana.Color</pre>
        <p>This only lets you use literal strings for the keys. You cannot use variables in your keys with dot notation.</p>
    </dd>
</dl>

<h4 id="To_add_new_keys_and_values">To add new keys and values:</h4>
<dl>
    <dt>Bracket notation</dt>
    <dd>
        <pre class="NoIndent">MyObject["NewerKey"] := 3.1415</pre>
        <p>To directly add a key and value, just set a key that doesn't exist yet.</p>
    </dd>
    <dt>Dot notation</dt>
    <dd>
        <pre class="NoIndent">MyObject.NewKey := "Shiny"</pre>
        <p>The same as above but with the dot notation.</p>
    </dd>
    <dt>InsertAt method</dt>
    <dd>
        <pre class="NoIndent">MyObject.InsertAt(Index, Value1, Value2, Value3...)</pre>
        <p><i>Index</i> is any integer key. This will shift ALL higher integer keys up by the number of values which were inserted, even if there are gaps (for example, only keys 1 and 100 exist, and you insert a value at key 50, it will shift 100 up to 101).</p>
    </dd>
    <dt>Push method</dt>
    <dd>
        <pre class="NoIndent">MyObject.Push(Value1, Value2, Value3...)</pre>
        <p>This "appends" the values to the end of the array <i>MyObject</i>. In other words, it inserts the values at the highest integer key plus one.</p>
    </dd>
</dl>

<h4 id="To_remove_keys_and_values">To remove keys and values:</h4>
<dl>
    <dt>Blanking the value out</dt>
    <dd>
        <pre class="NoIndent">Banana.Consistency := ""</pre>
        <p>The simplest way to remove a value is to just blank it out. You can do this by setting it to <code>""</code>, also known as an <i>empty string</i>. This doesn't remove the key, but it will make the value appear identical to an unset value. It is possible to tell that the key still exists by using the <a href="objects/Object.htm#HasKey">HasKey</a> method, and it will still come up in a <a href="commands/For.htm">For</a> loop.</p>
    </dd>
    <dt>Delete method</dt>
    <dd>
        <pre class="NoIndent">RemovedValue := MyObject.Delete(AnyKey)</pre>
        <p>This and the next methods below remove the key <i>and</i> the value. The previous value of <code>MyObject[AnyKey]</code> will be stored in <i>RemovedValue</i>.</p>
        <pre class="NoIndent">NumberOfRemovedKeys := MyObject.Delete(FirstKey, LastKey)</pre>
        <p>Allows you to remove a range of numbered/integer or string keys between <em>FirstKey</em> and <em>LastKey</em>. The value it gives will be the number of keys that were removed, which is useful if you have a gap between your keys (e.g. you specify keys 1 through four, but key number 2 doesn't exist, this will set <em>NumberOfRemovedKeys</em> to 3 as only three keys were there to be removed).</p>
    </dd>
    <dt>Pop method</dt>
    <dd>
        <pre class="NoIndent">MyObject.Pop()</pre>
        <p>This removes the highest integer key, and returns the value. There are no keys higher than it to be affected.</p>
    </dd>
    <dt>RemoveAt method</dt>
    <dd>
        <pre class="NoIndent">RemovedValue := MyObject.RemoveAt(Index)</pre>
        <pre class="NoIndent">NumberOfRemovedKeys := MyObject.RemoveAt(Index, Length)</pre>
        <p>This removes all keys from <i>Index</i> to <i>Index + Length - 1</i> (inclusive). If <i>Length</i> is omitted it defaults to 1. After removing the keys it takes all higher numbered/integer keys and moves them down to fill the gap, so that if there was a value at <i>Index + Length</i> it will now be at <i>Index</i>. This is similar to how the InsertAt method with multiple specified values works.</p>
    </dd>
</dl>

<h2 id="s8">8 - Other Helpful Goodies</h2>
<p>We have reached the end of our journey, my good friend. I hope you have learned something. But before we go, here are some other things that I think you should know. Enjoy!</p>

<h3 id="s81">a. The mysterious square brackets</h3>
<p>Throughout the documentation, you will see these two symbols (<code>[</code> and <code>]</code>) surrounding code in the yellow syntax box at the top of almost all pages. Anything inside of these brackets are <b><i>OPTIONAL</i></b>. Meaning the stuff inside can be left out if you don't need them. When writing your code, it is very important to <b>NOT</b> type the square brackets in your code.</p>
<p>On the <a href="commands/ControlGetText.htm">ControlGetText</a> page you will see this:</p>
<pre class="Syntax"><span class="func">ControlGetText</span>, OutputVar <span class="optional">, Control, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre>
<p>So you could simply do this if you wanted:</p>
<pre>ControlGetText, OutputVar</pre>
<p>Or add in some more details:</p>
<pre>ControlGetText, OutputVar, Control, WinTitle</pre>
<p>What if you wanted to use <em>ExcludeTitle</em> but not fill in <em>WinText</em> or <em>WinTitle</em>? Simple!</p>
<pre>ControlGetText, OutputVar, Control,,, ExcludeTitle</pre>
<p>Please note that you cannot IGNORE parameters, but you can leave them blank. If you were to ignore <code>WinTitle, WinText</code>, it would look like this and cause issues:</p>
<pre>ControlGetText, OutputVar, Control, ExcludeTitle</pre>

<h3 id="s82">b. Finding your AHK version</h3>
<p>Run this code to see your AHK version:</p>
<pre>MsgBox, %A_AhkVersion%</pre>
<p>Or look for "AutoHotkey Help File" or "AutoHotkey.chm" in the start menu or your installation directory.</p>

<h3 id="s83">c. Trial and Error</h3>
<p>Trial and Error is a very common and effective way of learning. Instead of asking for help on every little thing, sometimes spending some time alone (sometimes hours or days) and trying to get something to work will help you learn faster.</p>
<p>If you try something and it gives you an error, study that error. Then try to fix your code. Then try running it again. If you still get an error, modify your code some more. Keep trying and failing until your code fails no more. You will learn a lot this way by reading the documentation, reading errors and learning what works and what doesn't. Try, fail, try, fail, try, try, try, fail, fail, <b>succeed!</b></p>
<p>This is how a lot of "pros" have learned. But don't be afraid to ask for help, we don't bite (hard). Learning takes time, the "pros" you encounter did not learn to be masters in just a few hours or days.</p>
<p class="note">"If at first you don't succeed, try, try, try again." - Hickson, William E.</p>
<h3 id="s84">d. Indentation</h3>
<p>This stuff (indentation) is very important! Your code will run perfectly fine without it, but it will be a major headache for you and other to read your code. Small code (25 lines or less) will probably be fine to read without indentation, but it'll soon get sloppy. It's best you learn to indent ASAP. Indentation has no set style, but it's best to keep everything consistent.</p>
<p>"<b>What is indentation?</b>" you ask? It's simply spacing to break up your code so you can see what belongs to what. People usually use 3 or 4 spaces or 1 tab per "level".</p>
<p>Not indented:</p>
<pre>if (car = "old")
{
MsgBox, The car is really old.
if (wheels = "flat")
{
MsgBox, This car is not safe to drive.
return
}
else
{
MsgBox, Be careful! This old car will be dangerous to drive.
}
}
else
{
MsgBox, My`, what a shiny new vehicle you have there.
}</pre>
<p>Indented:</p>

<pre>if (car = "old")
{
    MsgBox, The car is really old.
    if (wheels = "flat")
    {
        MsgBox, This car is not safe to drive.
        return
    }
    else
    {
        MsgBox, Be careful! This old car will be dangerous to drive.
    }
}
else
{
    MsgBox, My`, what a shiny new vehicle you have there.
}</pre>
<p>See Wikipedia's <a href="https://en.wikipedia.org/wiki/Indentation_style">Indentation style</a> page for various styles and examples. Choose what you like or learn to indent how you think it's easiest to read.</p>

<h3 id="s85">e. Asking for Help</h3>
<p>Before you ask, try doing some research yourself or try to code it yourself. If that did not yield results that satisfy you, read below.</p>
<ul>
    <li>Don't be afraid to ask for help, even the smartest people ask others for help.</li>
    <li>Don't be afraid to show what you tried, even if you think it's silly.</li>
    <li>Post anything you have tried.</li>
    <li>Pretend <i>everyone but you</i> is a doorknob and knows nothing. Give as much information as you can to educate us doorknobs at what you are trying to do. Help us help you.</li>
    <li>Be patient.</li>
    <li>Be polite.</li>
    <li>Be open.</li>
    <li>Be kind.</li>
    <li>Enjoy!</li>
</ul>
<p>If you don't get an answer right away, wait at least 1 day (24 hours) before asking for more help. We love to help, but we also do this for free on our own time. We might be at work, sleeping, gaming, with family or just too busy to help.</p>
<p>And while you wait for help, you can try learning and doing it yourself. It's a good feeling, making something yourself without help.</p>

<h3 id="s86">f. Other links</h3>
<p><a href="FAQ.htm">Frequently Asked Questions (FAQ)</a></p>
</body>
</html>