AutoIt Wiki - User contributions [en]

Decompiling FAQ

2017-06-26T09:59:25Z

BrewManNH: /* Is there a 3rd-party decompiler? */

Below are frequently asked questions about decompiling AutoIt scripts.

__TOC__

== Is there a decompiler available? ==
Yes, sort of. The official decompiler will only decompile scripts compiled with AutoIt v3.2.5.1 and earlier. Any script compiled with a version later than that will not decompile.

== Where can I find the decompiler? ==
If the version of AutoIt is v3.2.5.1 or lower, then the decompiler is located at ''C:\Program Files\AutoIt3\Extras\Exe2Aut\Exe2Aut.exe'' by default. The directory may be different if you performed a custom installation. For all other newer versions, the decompiler has been removed.

== What if I need to decompile a script compiled with a newer version of AutoIt? ==
You are mostly out of luck. Take the opportunity to learn how to properly back up your important files. The developers can decompile scripts but you must be prepared to prove you own the script. This is not done very often and the developers reserve the right to say no for any reason.

== Is there a 3rd-party decompiler? ==
Yes. There is software in existence which can decompile all versions of AutoIt. Creation or '''use''' of such software may be a violation of the law depending on your local laws. '''DO NOT USE IT.'''

== What happens if I use the 3rd-party decompiler? ==
If you mention you have used a 3rd-party decompiler you will be permanently blocked from the forum and issue tracker. You may be blocked for any of the following:
* Admitting you have decompiled your own script with a 3rd-party decompiler.
* Admitting you have decompiled another user's script with a 3rd-party decompiler.
* Posting any script that has been decompiled by a 3rd-party decompiler.
This includes decompiling scripts users have posted in binary-only form. Under no circumstances are scripts to be decompiled unless the author grants their explicit permission and the script can be decompiled with the official decompiler.

== Are my compiled scripts safe? ==
No. Any unscrupulous user may decompile your compiled script. There is not much you can do to stop decompilation. A determined user will get your source code if they truly want it.

== I designed a counter-measure to break the 3rd-party decompiler, may I share it? ==
No. It is theoretically possible to modify compiled scripts in a way that it still works but a decompiler fails to extract the source. However, tools that are capable of doing this violate the reverse engineering clause of the AutoIt license (the very same clause the 3rd-party decompiler violates).

== Where in the AutoIt license does it mention decompilation? ==
This clause:
:Reverse engineering. You may not reverse engineer or disassemble the SOFTWARE PRODUCT or compiled scripts that were created with the SOFTWARE PRODUCT.
That clause covers both reverse engineering how AutoIt works (in order to create a working decompiler or a counter-measure to decompiling) as well as decompilation of compiled scripts.

Decompiling FAQ

2017-06-26T09:56:13Z

BrewManNH: /* Where can I find the decompiler? */

Below are frequently asked questions about decompiling AutoIt scripts.

__TOC__

== Is there a decompiler available? ==
Yes, sort of. The official decompiler will only decompile scripts compiled with AutoIt v3.2.5.1 and earlier. Any script compiled with a version later than that will not decompile.

== Where can I find the decompiler? ==
If the version of AutoIt is v3.2.5.1 or lower, then the decompiler is located at ''C:\Program Files\AutoIt3\Extras\Exe2Aut\Exe2Aut.exe'' by default. The directory may be different if you performed a custom installation. For all other newer versions, the decompiler has been removed.

== What if I need to decompile a script compiled with a newer version of AutoIt? ==
You are mostly out of luck. Take the opportunity to learn how to properly back up your important files. The developers can decompile scripts but you must be prepared to prove you own the script. This is not done very often and the developers reserve the right to say no for any reason.

== Is there a 3rd-party decompiler? ==
Yes. There is software in existence which can decompile all versions of AutoIt. This software is in direct violation of the AutoIt license agreement. Creation or '''use''' of such software may be a violation of the law depending on your local laws. '''DO NOT USE IT.
'''

== What happens if I use the 3rd-party decompiler? ==
If you mention you have used a 3rd-party decompiler you will be permanently blocked from the forum and issue tracker. You may be blocked for any of the following:
* Admitting you have decompiled your own script with a 3rd-party decompiler.
* Admitting you have decompiled another user's script with a 3rd-party decompiler.
* Posting any script that has been decompiled by a 3rd-party decompiler.
This includes decompiling scripts users have posted in binary-only form. Under no circumstances are scripts to be decompiled unless the author grants their explicit permission and the script can be decompiled with the official decompiler.

== Are my compiled scripts safe? ==
No. Any unscrupulous user may decompile your compiled script. There is not much you can do to stop decompilation. A determined user will get your source code if they truly want it.

== I designed a counter-measure to break the 3rd-party decompiler, may I share it? ==
No. It is theoretically possible to modify compiled scripts in a way that it still works but a decompiler fails to extract the source. However, tools that are capable of doing this violate the reverse engineering clause of the AutoIt license (the very same clause the 3rd-party decompiler violates).

== Where in the AutoIt license does it mention decompilation? ==
This clause:
:Reverse engineering. You may not reverse engineer or disassemble the SOFTWARE PRODUCT or compiled scripts that were created with the SOFTWARE PRODUCT.
That clause covers both reverse engineering how AutoIt works (in order to create a working decompiler or a counter-measure to decompiling) as well as decompilation of compiled scripts.

Best coding practices

2016-07-20T20:27:30Z

BrewManNH: /* Include-once directive */

Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.

'''Note''': You must use AutoIt v3.3.10.0 or above to run the examples below.

__TOC__

== Using Functions ==
If a function sets the @error flag, you should always check it before using a return value - if @error indicates an error then the function return value is generally undefined.

Learn more about using Functions by reading "[https://www.autoitscript.com/autoit3/docs/function_notes.htm Function Notes]" from HelpFile.

== Names of Variables ==
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.

{| class="wikitable"
|-
! prefix !! covering type !! example
|-
| a || Arrays || $aArray[0]
|-
| b || Booleans || $bBool = True
|-
| d || Binaries || $dBinary = Binary("0x80000000")
|-
| e || Constant variable || Local Const $eEulersConstant = 2.7182818284590452
|-
| f || Floating point || $fFloat = 0.123
|-
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")
|-
| i || Integer || $iInteger = 10
|-
| id || An AutoIt controlID || $idButton_Ok = GUICtrlCreateButton("OK", 5, 5)
|-
| m || Maps || $mMap[]
|-
| n || General number (no preference) || $nNumber = 0
|-
| p || Pointers || $pRect = DllStructGetPtr($tRECT)
|-
| s || Strings (chars included) || $sString = "Hello world"
|-
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)
|-
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Day; endstruct"
|-
|v || Variant || $vData = ClipGet()
|}

Variables are named following this schema:
{| class="wikitable"
|-
! dollar prefix !! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| $ || a || h || Handles
|}

Examples:
<syntaxhighlight lang="autoit">
; Assign a local variable the integer 7
Local $iWeekDays = 7

; Assign a local variable the value of Pi
Local $fPi = 3.14159265358979

; Assign a local variable an array of strings
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']

; Assign a local variable an array of numbers
Local $anArray[4] = [0, 0.25, 3 / 4, 12]
</syntaxhighlight>
 

== Variable Initialization ==
When initializing variables there are several points to consider. It is bad practice to hog memory by assigning data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.

Examples:
<syntaxhighlight lang="autoit">
; Inconsistent data types are considered bad
Local $iInteger = "0"
Local $sString = False

; Correct initialization
Local $iInteger = 0
Local $sString = ''
</syntaxhighlight>
 

In the following table, recommended default values are shown for each data type. Some data types have more than one possibile default value which can be used for initialization.

{| class="wikitable"
|-
! Default Value !! covering type
|-
| Binary("") || $d
|-
| "" || $s, $v
|-
| 0 || $a, $h, $i, $id, $m, $n, $o, $p, $t, $tag, $v
|-
| 0.0 || $f
|-
| Null || $o, $s, $v
|-
| False (or True) || $b
|}

 
Example:
<syntaxhighlight lang="autoit">
; Declare and initialize a variable with the recommended default value
Local $vUndefined = Null ; This does not require much memory

; Some time later:
$vUndefined = 0xB0AD1CEA ; Assign an appropriate value as and when needed
</syntaxhighlight>
 

To reduce bloat, multiple variables can be declared on a single line. When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to follow and manage in a future, however the best layout will vary according to circumstance.

Example:
<syntaxhighlight lang="autoit">
; Not recommended
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types

; Recommended
Local $iLeft = 10, $iTop = 10 ; Integers
Local $idButton_Go = GUICtrlCreateButton("Go", $iLeft, $iTop) ; ControlIds
Local $idButton_Quit = GUICtrlCreateButton("Quit", 50, 10) ; ControlIds
</syntaxhighlight>
 

In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data type, variables declared without being initialized should be considered as being undefined.
 

== Scopes of Variables ==
Variables should also be named according to their scope.
{| class="wikitable"
|-
! Global UDF variable !! Global variable !! Local variable
|-
| $__g_iSomeVar || $g_iSomeVar || $iSomeVar
|}
With this method, you will avoid unwanted re-assignments.

Example:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Assign a Global variable the number 0
Global $iSomeVar1 = 0
; Assign a Global variable the number 5
Global $g_iSomeVar2 = 5

SomeFunc()

Func SomeFunc()
; Assign Local variables respectively the numbers 3 and 4
Local $iSomeVar1 = 3, $iSomeVar2 = 4

; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global"

; Display the value of $iSomeVar1
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)

; Display the value of $iSomeVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)

; Display the value of $g_iSomeVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $g_iSomeVar2: " & $g_iSomeVar2)
EndFunc
</syntaxhighlight>

* A variable declared globally (with the Global keyword) is visible anywhere in the script. Always declare your global variables in the global scope, not in a function. It will prevent another function from using it before its declaration and the declaration is implicit (see [[#jumpsec1|examples]]).

* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.
:Declaration in the global scope: the variable is visible everywhere; declare it as Local if this one is only to be used in the same scope, i.e. outside of any functions. A variable declared as Local in the Global scope is still a Global variable, it's only for the sake of code clarity that you'd use the Local declaration in the Global scope.
:Declaration in a function: the variable is visible by the function itself and nowhere else.

Structure of a code scope:
<syntaxhighlight lang="autoit">
; Global scope

; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function)
#include <MsgBoxConstants.au3>

; This scope is either Global or Local, depending on where you use the variables

; Assign a Global variable the number 0 (which corresponds to an initialization of a variable number), its scope is Global because it's used in at least one function
Global $g_iVar1 = 0

; Assign a Local variable the string "foo", its scope is Local because it's use is used only in this scope
Local $sVar2 = "foo"

; Display the content of $sVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $sVar2)

; Re-assign a Local variable the string returned by the function MyFunc
$sVar2 = MyFunc()

; Re-Display the content of $sVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $sVar2)

; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope)
Func MyFunc()
; Local scope

; Display the content of $g_iVar1
MsgBox($MB_SYSTEMMODAL, "", "Value of $g_iVar1: " & $g_iVar1)

; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope
Local $sVar3 = "bar"

; Display the content of $sVar3
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)

; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called
Return $sVar3
EndFunc ;==>MyFunc
</syntaxhighlight>

Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).

Example 1:
<syntaxhighlight lang="autoit">
; Include the Array UDF, it's needed here for the _ArrayDisplay function
#include <Array.au3>

; Assign a Local variable an array containing numbers with a size of 5
; Note than an array is 0 based, to access the first element the code is: $aiArray[0]
Local $aiArray[5] = [1, 2, 3, 4, 5]

; Display the contents
_ArrayDisplay($aiArray)

; Empty the array (and keep its size)
Dim $aiArray[5]

; Display the contents
_ArrayDisplay($aiArray)
</syntaxhighlight>
Remark: The variable type of an emptied array is a string, every non initialized variable is a string.

Example 2:
<syntaxhighlight lang="autoit">
#include <Array.au3>

; Call MyFunc with default parameters ($vParam1 = 0)
MyFunc()

; Assign a Local variable an array containing integers
Local $aiArray[3] = [3, 4, 5]
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray)
MyFunc($aiArray)

Func MyFunc($vParam1 = 0)
; If $vParam1 is NOT an array then redeclare it to an array
If Not IsArray($vParam1) Then
Dim $vParam1[3] = [0, 1, 2]
EndIf

; Display the array
_ArrayDisplay($vParam1)
EndFunc ;==>MyFunc
</syntaxhighlight>

And for the ReDim keyword, limit its use to resize an array when you want to keep its content:
<syntaxhighlight lang="autoit">
; Include the Array UDF, it's needed here for the _ArrayDisplay function
#include <Array.au3>

; Assign a Local variable an array containing numbers with a size of 5
; Note than an array is 0 based, to access the first element the code is: $aiArray[0]
Local $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents
_ArrayDisplay($aArray)

; Resize the array (and keep its content)
ReDim $aArray[3]

; Display the contents
_ArrayDisplay($aArray)
</syntaxhighlight>

Why using Dim over Local/Global is not always a good option:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

Dim $g_vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."

MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")

Example()

Func Example()
MsgBox($MB_SYSTEMMODAL, "", $g_vVariableThatIsGlobal) ; That looks alright to me as it displays the following text: This is a variable that has "Program Scope" aka Global

Local $vReturn = SomeFunc() ; Call some random function

MsgBox($MB_SYSTEMMODAL, $vReturn, $g_vVariableThatIsGlobal) ; The Global variable ($g_vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc"
EndFunc ;==>Example

Func SomeFunc()
; This should create a variable in Local scope if the variable name doesn"t already exist
; For argument sake I totally forgot that I declared a variable already with the same name
; Well I only want this to be changed in the function and not the variable at the top of the script
; Should be OK right? Think again
Dim $g_vVariableThatIsGlobal = ""

For $i = 1 To 10
$g_vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $g_vVariableThatIsGlobal
Next
Return $g_vVariableThatIsGlobal
EndFunc ;==>SomeFunc
</syntaxhighlight>

Declaring Global variables in a Function is never a good idea:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Calling Example() first will initialise the Global variable $g_vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error
; Now look at Example 2
Example()

Func Example()
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script
Global $g_vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $g_vVariableThatIsGlobal) ; As the variable was initialised this will not return an error
EndFunc ;==>SomeFunc
</syntaxhighlight>

Example 2:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Calling SomeFunc() first will bypass the Global variable $g_vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $g_vVariableThatIsGlobal contains
SomeFunc()

Func Example()
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script
Global $g_vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $g_vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."
EndFunc ;==>SomeFunc
</syntaxhighlight>

Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition
For $i = 1 To 10 ; $i is in 'loop scope.'
Local $iInt = $i
Next
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10
</syntaxhighlight>

<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Declaring variables outside of loops is more efficient in the long run
Local $iInt = 0
For $i = 1 To 10 ; $i is in 'loop scope.'
$iInt = $i
Next
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10
</syntaxhighlight>

There is no requirement to declare the iteration count variable in a loop:
<syntaxhighlight lang="autoit">
; Correct
Local Const $iCount = 99
Local $aArray[$iCount]
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it
$aArray[$i] = $i
Next

; Incorrect
Local Const $iCount = 99
Local $aArray[$iCount]
Local $i ; This is only used to store the iteration count value in the loop and therefore doesn't need to be declared.
For $i = 0 To UBound($iCount) - 1
$aArray[$i] = $i
Next
</syntaxhighlight>
As you can see, there is the Const keyword in the example, we are going to talk about it.

== Const, Static, Enum ==

=== Const ===
We won't talk about the advantages of using a constant variable, they are neglibible (for your information, an AutoIt constant variable is marked as read-only and remains a read-only variable when compiled).

The Const keyword may be used first by some of you to avoid re-assignments.
The best way to use them is for real static values, meaning that these values won't change regardless of the instance of the program.

Example:
<syntaxhighlight lang="autoit">
; Not recommended
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes

; Recommended
Local Const $iMyAge = 19
</syntaxhighlight>

=== Static ===
Static variables are the solution to global variables being used in only one function.
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.
<syntaxhighlight lang="autoit">
Example()

Func Example()
SomeFunc() ; This will display a message box of 1, 1
SomeFunc() ; This will display a message box of 1, 2
SomeFunc() ; This will display a message box of 1, 3
EndFunc ;==>Example

Func SomeFunc()
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. Also, the variable can't be
; accessed from anywhere else in the script apart from the Function it was declared in
Local Static $vVariableThatIsStatic = 0
Local $vVariableThatIsLocal = 0
$vVariableThatIsLocal += 1 ; This will always be 1 as it is destroyed once returned from SomeFunc
$vVariableThatIsStatic += 1 ; This will increase by 1
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)
EndFunc ;==>SomeFunc
</syntaxhighlight>

=== Enum ===
This statement is often practical in certain situations:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

Example()

Func Example()
; Create variables in Local scope and enumerate through the variables. Default is to start from 0
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4

; Create an array in Local scope with 4 elements
Local $aAnimalNames[4]

; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]

; Display the values of the array
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)

; Sometimes using this approach for accessing an element is more practical than using a numerical value, due to the fact changing the index value of
; the enum constant has no affect on it's position in the array. Therefore changing the location of $eCat in the array is as simple as changing the order
; it appears in the initial declaration e.g

; Local Enum $eDog, $eMouse, $eCat, $eHamster

; Now $eCat is the 2nd element in the array. If you were using numerical values, you would have to manually change all references of $aAnimalNames[0] to
; $aAnimalNames[2], as well as for the other elements which have now shifted
EndFunc ;==>Example
</syntaxhighlight>

== Au3Check directive ==
As you may know (and we hope), the Au3Check tool checks your code for syntax errors, variables used without being declared etc. which is a good thing to fix your script.

With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:
<syntaxhighlight lang="autoit">
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7
</syntaxhighlight>
|Note: this directive is only used if you've installed the full version of [https://www.autoitscript.com/cgi-bin/getfile.pl?../autoit3/scite/download/SciTE4AutoIt3.exe Scite4AutoIt3]

== Magic Numbers ==
Magic numbers are arbitrary numbers interspersed throughout a program's source code which do not have an associated identifier. The downside to this is not being able to derive a meaning from the number.

For example:
<syntaxhighlight lang="autoit">
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")
</syntaxhighlight>
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.

The corrected example:
<syntaxhighlight lang="autoit">
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")
</syntaxhighlight>

Example 2:
<syntaxhighlight lang="autoit">
; Imagine you're a new user to AutoIt and you come across this code, where would you find -3, -4 or -5 in the help file?
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean
; why would you, the help file is there for a reason
Example()

Func Example()
Local $hGUI = GUICreate('')
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case -3 ; Doesn't really tell much about what it does
ExitLoop

Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?
MsgBox(4096, '', 'Do something when this action takes place.')

EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example
</syntaxhighlight>

Did you understand the numbers were these:
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

Example()

Func Example()
Local $hGUI = GUICreate('')
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action
ExitLoop

Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.')

EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example
</syntaxhighlight>

[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]

== Include-once directive ==
This one is designed for standard includes and UDFs, it's highly recommended to use it only for that.

Those includes may be used in more than one file of your project because they are needed for some includes or your script itself.
In that case, the code would be duplicated, which is not a good thing especially if you have constants declared in those files, in so far as the constants cannot be redeclared/reassigned you will get error messages about trying to redeclare them; same thing for functions, you can't use a function name more than once.

Put the directive at the top of your UDF (library) to avoid it from being included more than once :
<syntaxhighlight lang="autoit">
#include-once
</syntaxhighlight>

Best coding practices

2016-07-20T20:22:52Z

BrewManNH: /* Magic Numbers */

Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.

'''Note''': You must use AutoIt v3.3.10.0 or above to run the examples below.

__TOC__

== Using Functions ==
If a function sets the @error flag, you should always check it before using a return value - if @error indicates an error then the function return value is generally undefined.

Learn more about using Functions by reading "[https://www.autoitscript.com/autoit3/docs/function_notes.htm Function Notes]" from HelpFile.

== Names of Variables ==
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.

{| class="wikitable"
|-
! prefix !! covering type !! example
|-
| a || Arrays || $aArray[0]
|-
| b || Booleans || $bBool = True
|-
| d || Binaries || $dBinary = Binary("0x80000000")
|-
| e || Constant variable || Local Const $eEulersConstant = 2.7182818284590452
|-
| f || Floating point || $fFloat = 0.123
|-
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")
|-
| i || Integer || $iInteger = 10
|-
| id || An AutoIt controlID || $idButton_Ok = GUICtrlCreateButton("OK", 5, 5)
|-
| m || Maps || $mMap[]
|-
| n || General number (no preference) || $nNumber = 0
|-
| p || Pointers || $pRect = DllStructGetPtr($tRECT)
|-
| s || Strings (chars included) || $sString = "Hello world"
|-
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)
|-
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Day; endstruct"
|-
|v || Variant || $vData = ClipGet()
|}

Variables are named following this schema:
{| class="wikitable"
|-
! dollar prefix !! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| $ || a || h || Handles
|}

Examples:
<syntaxhighlight lang="autoit">
; Assign a local variable the integer 7
Local $iWeekDays = 7

; Assign a local variable the value of Pi
Local $fPi = 3.14159265358979

; Assign a local variable an array of strings
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']

; Assign a local variable an array of numbers
Local $anArray[4] = [0, 0.25, 3 / 4, 12]
</syntaxhighlight>
 

== Variable Initialization ==
When initializing variables there are several points to consider. It is bad practice to hog memory by assigning data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.

Examples:
<syntaxhighlight lang="autoit">
; Inconsistent data types are considered bad
Local $iInteger = "0"
Local $sString = False

; Correct initialization
Local $iInteger = 0
Local $sString = ''
</syntaxhighlight>
 

In the following table, recommended default values are shown for each data type. Some data types have more than one possibile default value which can be used for initialization.

{| class="wikitable"
|-
! Default Value !! covering type
|-
| Binary("") || $d
|-
| "" || $s, $v
|-
| 0 || $a, $h, $i, $id, $m, $n, $o, $p, $t, $tag, $v
|-
| 0.0 || $f
|-
| Null || $o, $s, $v
|-
| False (or True) || $b
|}

 
Example:
<syntaxhighlight lang="autoit">
; Declare and initialize a variable with the recommended default value
Local $vUndefined = Null ; This does not require much memory

; Some time later:
$vUndefined = 0xB0AD1CEA ; Assign an appropriate value as and when needed
</syntaxhighlight>
 

To reduce bloat, multiple variables can be declared on a single line. When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to follow and manage in a future, however the best layout will vary according to circumstance.

Example:
<syntaxhighlight lang="autoit">
; Not recommended
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types

; Recommended
Local $iLeft = 10, $iTop = 10 ; Integers
Local $idButton_Go = GUICtrlCreateButton("Go", $iLeft, $iTop) ; ControlIds
Local $idButton_Quit = GUICtrlCreateButton("Quit", 50, 10) ; ControlIds
</syntaxhighlight>
 

In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data type, variables declared without being initialized should be considered as being undefined.
 

== Scopes of Variables ==
Variables should also be named according to their scope.
{| class="wikitable"
|-
! Global UDF variable !! Global variable !! Local variable
|-
| $__g_iSomeVar || $g_iSomeVar || $iSomeVar
|}
With this method, you will avoid unwanted re-assignments.

Example:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Assign a Global variable the number 0
Global $iSomeVar1 = 0
; Assign a Global variable the number 5
Global $g_iSomeVar2 = 5

SomeFunc()

Func SomeFunc()
; Assign Local variables respectively the numbers 3 and 4
Local $iSomeVar1 = 3, $iSomeVar2 = 4

; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global"

; Display the value of $iSomeVar1
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)

; Display the value of $iSomeVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)

; Display the value of $g_iSomeVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $g_iSomeVar2: " & $g_iSomeVar2)
EndFunc
</syntaxhighlight>

* A variable declared globally (with the Global keyword) is visible anywhere in the script. Always declare your global variables in the global scope, not in a function. It will prevent another function from using it before its declaration and the declaration is implicit (see [[#jumpsec1|examples]]).

* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.
:Declaration in the global scope: the variable is visible everywhere; declare it as Local if this one is only to be used in the same scope, i.e. outside of any functions. A variable declared as Local in the Global scope is still a Global variable, it's only for the sake of code clarity that you'd use the Local declaration in the Global scope.
:Declaration in a function: the variable is visible by the function itself and nowhere else.

Structure of a code scope:
<syntaxhighlight lang="autoit">
; Global scope

; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function)
#include <MsgBoxConstants.au3>

; This scope is either Global or Local, depending on where you use the variables

; Assign a Global variable the number 0 (which corresponds to an initialization of a variable number), its scope is Global because it's used in at least one function
Global $g_iVar1 = 0

; Assign a Local variable the string "foo", its scope is Local because it's use is used only in this scope
Local $sVar2 = "foo"

; Display the content of $sVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $sVar2)

; Re-assign a Local variable the string returned by the function MyFunc
$sVar2 = MyFunc()

; Re-Display the content of $sVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $sVar2)

; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope)
Func MyFunc()
; Local scope

; Display the content of $g_iVar1
MsgBox($MB_SYSTEMMODAL, "", "Value of $g_iVar1: " & $g_iVar1)

; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope
Local $sVar3 = "bar"

; Display the content of $sVar3
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)

; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called
Return $sVar3
EndFunc ;==>MyFunc
</syntaxhighlight>

Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).

Example 1:
<syntaxhighlight lang="autoit">
; Include the Array UDF, it's needed here for the _ArrayDisplay function
#include <Array.au3>

; Assign a Local variable an array containing numbers with a size of 5
; Note than an array is 0 based, to access the first element the code is: $aiArray[0]
Local $aiArray[5] = [1, 2, 3, 4, 5]

; Display the contents
_ArrayDisplay($aiArray)

; Empty the array (and keep its size)
Dim $aiArray[5]

; Display the contents
_ArrayDisplay($aiArray)
</syntaxhighlight>
Remark: The variable type of an emptied array is a string, every non initialized variable is a string.

Example 2:
<syntaxhighlight lang="autoit">
#include <Array.au3>

; Call MyFunc with default parameters ($vParam1 = 0)
MyFunc()

; Assign a Local variable an array containing integers
Local $aiArray[3] = [3, 4, 5]
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray)
MyFunc($aiArray)

Func MyFunc($vParam1 = 0)
; If $vParam1 is NOT an array then redeclare it to an array
If Not IsArray($vParam1) Then
Dim $vParam1[3] = [0, 1, 2]
EndIf

; Display the array
_ArrayDisplay($vParam1)
EndFunc ;==>MyFunc
</syntaxhighlight>

And for the ReDim keyword, limit its use to resize an array when you want to keep its content:
<syntaxhighlight lang="autoit">
; Include the Array UDF, it's needed here for the _ArrayDisplay function
#include <Array.au3>

; Assign a Local variable an array containing numbers with a size of 5
; Note than an array is 0 based, to access the first element the code is: $aiArray[0]
Local $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents
_ArrayDisplay($aArray)

; Resize the array (and keep its content)
ReDim $aArray[3]

; Display the contents
_ArrayDisplay($aArray)
</syntaxhighlight>

Why using Dim over Local/Global is not always a good option:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

Dim $g_vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."

MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")

Example()

Func Example()
MsgBox($MB_SYSTEMMODAL, "", $g_vVariableThatIsGlobal) ; That looks alright to me as it displays the following text: This is a variable that has "Program Scope" aka Global

Local $vReturn = SomeFunc() ; Call some random function

MsgBox($MB_SYSTEMMODAL, $vReturn, $g_vVariableThatIsGlobal) ; The Global variable ($g_vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc"
EndFunc ;==>Example

Func SomeFunc()
; This should create a variable in Local scope if the variable name doesn"t already exist
; For argument sake I totally forgot that I declared a variable already with the same name
; Well I only want this to be changed in the function and not the variable at the top of the script
; Should be OK right? Think again
Dim $g_vVariableThatIsGlobal = ""

For $i = 1 To 10
$g_vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $g_vVariableThatIsGlobal
Next
Return $g_vVariableThatIsGlobal
EndFunc ;==>SomeFunc
</syntaxhighlight>

Declaring Global variables in a Function is never a good idea:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Calling Example() first will initialise the Global variable $g_vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error
; Now look at Example 2
Example()

Func Example()
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script
Global $g_vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $g_vVariableThatIsGlobal) ; As the variable was initialised this will not return an error
EndFunc ;==>SomeFunc
</syntaxhighlight>

Example 2:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Calling SomeFunc() first will bypass the Global variable $g_vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $g_vVariableThatIsGlobal contains
SomeFunc()

Func Example()
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script
Global $g_vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $g_vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."
EndFunc ;==>SomeFunc
</syntaxhighlight>

Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition
For $i = 1 To 10 ; $i is in 'loop scope.'
Local $iInt = $i
Next
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10
</syntaxhighlight>

<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Declaring variables outside of loops is more efficient in the long run
Local $iInt = 0
For $i = 1 To 10 ; $i is in 'loop scope.'
$iInt = $i
Next
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10
</syntaxhighlight>

There is no requirement to declare the iteration count variable in a loop:
<syntaxhighlight lang="autoit">
; Correct
Local Const $iCount = 99
Local $aArray[$iCount]
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it
$aArray[$i] = $i
Next

; Incorrect
Local Const $iCount = 99
Local $aArray[$iCount]
Local $i ; This is only used to store the iteration count value in the loop and therefore doesn't need to be declared.
For $i = 0 To UBound($iCount) - 1
$aArray[$i] = $i
Next
</syntaxhighlight>
As you can see, there is the Const keyword in the example, we are going to talk about it.

== Const, Static, Enum ==

=== Const ===
We won't talk about the advantages of using a constant variable, they are neglibible (for your information, an AutoIt constant variable is marked as read-only and remains a read-only variable when compiled).

The Const keyword may be used first by some of you to avoid re-assignments.
The best way to use them is for real static values, meaning that these values won't change regardless of the instance of the program.

Example:
<syntaxhighlight lang="autoit">
; Not recommended
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes

; Recommended
Local Const $iMyAge = 19
</syntaxhighlight>

=== Static ===
Static variables are the solution to global variables being used in only one function.
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.
<syntaxhighlight lang="autoit">
Example()

Func Example()
SomeFunc() ; This will display a message box of 1, 1
SomeFunc() ; This will display a message box of 1, 2
SomeFunc() ; This will display a message box of 1, 3
EndFunc ;==>Example

Func SomeFunc()
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. Also, the variable can't be
; accessed from anywhere else in the script apart from the Function it was declared in
Local Static $vVariableThatIsStatic = 0
Local $vVariableThatIsLocal = 0
$vVariableThatIsLocal += 1 ; This will always be 1 as it is destroyed once returned from SomeFunc
$vVariableThatIsStatic += 1 ; This will increase by 1
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)
EndFunc ;==>SomeFunc
</syntaxhighlight>

=== Enum ===
This statement is often practical in certain situations:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

Example()

Func Example()
; Create variables in Local scope and enumerate through the variables. Default is to start from 0
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4

; Create an array in Local scope with 4 elements
Local $aAnimalNames[4]

; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]

; Display the values of the array
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)

; Sometimes using this approach for accessing an element is more practical than using a numerical value, due to the fact changing the index value of
; the enum constant has no affect on it's position in the array. Therefore changing the location of $eCat in the array is as simple as changing the order
; it appears in the initial declaration e.g

; Local Enum $eDog, $eMouse, $eCat, $eHamster

; Now $eCat is the 2nd element in the array. If you were using numerical values, you would have to manually change all references of $aAnimalNames[0] to
; $aAnimalNames[2], as well as for the other elements which have now shifted
EndFunc ;==>Example
</syntaxhighlight>

== Au3Check directive ==
As you may know (and we hope), the Au3Check tool checks your code for syntax errors, variables used without being declared etc. which is a good thing to fix your script.

With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:
<syntaxhighlight lang="autoit">
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7
</syntaxhighlight>
|Note: this directive is only used if you've installed the full version of [https://www.autoitscript.com/cgi-bin/getfile.pl?../autoit3/scite/download/SciTE4AutoIt3.exe Scite4AutoIt3]

== Magic Numbers ==
Magic numbers are arbitrary numbers interspersed throughout a program's source code which do not have an associated identifier. The downside to this is not being able to derive a meaning from the number.

For example:
<syntaxhighlight lang="autoit">
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")
</syntaxhighlight>
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.

The corrected example:
<syntaxhighlight lang="autoit">
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")
</syntaxhighlight>

Example 2:
<syntaxhighlight lang="autoit">
; Imagine you're a new user to AutoIt and you come across this code, where would you find -3, -4 or -5 in the help file?
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean
; why would you, the help file is there for a reason
Example()

Func Example()
Local $hGUI = GUICreate('')
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case -3 ; Doesn't really tell much about what it does
ExitLoop

Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?
MsgBox(4096, '', 'Do something when this action takes place.')

EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example
</syntaxhighlight>

Did you understand the numbers were these:
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

Example()

Func Example()
Local $hGUI = GUICreate('')
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action
ExitLoop

Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.')

EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example
</syntaxhighlight>

[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]

== Include-once directive ==
This one is designed for standard includes and UDFs, it's highly recommended to use it.

Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions

Put the directive in top of your UDF (library) to avoid itself to be included more than once :
<syntaxhighlight lang="autoit">
#include-once
</syntaxhighlight>

Best coding practices

2016-07-20T20:21:00Z

BrewManNH: /* Au3Check directive */

Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.

'''Note''': You must use AutoIt v3.3.10.0 or above to run the examples below.

__TOC__

== Using Functions ==
If a function sets the @error flag, you should always check it before using a return value - if @error indicates an error then the function return value is generally undefined.

Learn more about using Functions by reading "[https://www.autoitscript.com/autoit3/docs/function_notes.htm Function Notes]" from HelpFile.

== Names of Variables ==
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.

{| class="wikitable"
|-
! prefix !! covering type !! example
|-
| a || Arrays || $aArray[0]
|-
| b || Booleans || $bBool = True
|-
| d || Binaries || $dBinary = Binary("0x80000000")
|-
| e || Constant variable || Local Const $eEulersConstant = 2.7182818284590452
|-
| f || Floating point || $fFloat = 0.123
|-
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")
|-
| i || Integer || $iInteger = 10
|-
| id || An AutoIt controlID || $idButton_Ok = GUICtrlCreateButton("OK", 5, 5)
|-
| m || Maps || $mMap[]
|-
| n || General number (no preference) || $nNumber = 0
|-
| p || Pointers || $pRect = DllStructGetPtr($tRECT)
|-
| s || Strings (chars included) || $sString = "Hello world"
|-
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)
|-
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Day; endstruct"
|-
|v || Variant || $vData = ClipGet()
|}

Variables are named following this schema:
{| class="wikitable"
|-
! dollar prefix !! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| $ || a || h || Handles
|}

Examples:
<syntaxhighlight lang="autoit">
; Assign a local variable the integer 7
Local $iWeekDays = 7

; Assign a local variable the value of Pi
Local $fPi = 3.14159265358979

; Assign a local variable an array of strings
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']

; Assign a local variable an array of numbers
Local $anArray[4] = [0, 0.25, 3 / 4, 12]
</syntaxhighlight>
 

== Variable Initialization ==
When initializing variables there are several points to consider. It is bad practice to hog memory by assigning data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.

Examples:
<syntaxhighlight lang="autoit">
; Inconsistent data types are considered bad
Local $iInteger = "0"
Local $sString = False

; Correct initialization
Local $iInteger = 0
Local $sString = ''
</syntaxhighlight>
 

In the following table, recommended default values are shown for each data type. Some data types have more than one possibile default value which can be used for initialization.

{| class="wikitable"
|-
! Default Value !! covering type
|-
| Binary("") || $d
|-
| "" || $s, $v
|-
| 0 || $a, $h, $i, $id, $m, $n, $o, $p, $t, $tag, $v
|-
| 0.0 || $f
|-
| Null || $o, $s, $v
|-
| False (or True) || $b
|}

 
Example:
<syntaxhighlight lang="autoit">
; Declare and initialize a variable with the recommended default value
Local $vUndefined = Null ; This does not require much memory

; Some time later:
$vUndefined = 0xB0AD1CEA ; Assign an appropriate value as and when needed
</syntaxhighlight>
 

To reduce bloat, multiple variables can be declared on a single line. When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to follow and manage in a future, however the best layout will vary according to circumstance.

Example:
<syntaxhighlight lang="autoit">
; Not recommended
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types

; Recommended
Local $iLeft = 10, $iTop = 10 ; Integers
Local $idButton_Go = GUICtrlCreateButton("Go", $iLeft, $iTop) ; ControlIds
Local $idButton_Quit = GUICtrlCreateButton("Quit", 50, 10) ; ControlIds
</syntaxhighlight>
 

In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data type, variables declared without being initialized should be considered as being undefined.
 

== Scopes of Variables ==
Variables should also be named according to their scope.
{| class="wikitable"
|-
! Global UDF variable !! Global variable !! Local variable
|-
| $__g_iSomeVar || $g_iSomeVar || $iSomeVar
|}
With this method, you will avoid unwanted re-assignments.

Example:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Assign a Global variable the number 0
Global $iSomeVar1 = 0
; Assign a Global variable the number 5
Global $g_iSomeVar2 = 5

SomeFunc()

Func SomeFunc()
; Assign Local variables respectively the numbers 3 and 4
Local $iSomeVar1 = 3, $iSomeVar2 = 4

; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global"

; Display the value of $iSomeVar1
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)

; Display the value of $iSomeVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)

; Display the value of $g_iSomeVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $g_iSomeVar2: " & $g_iSomeVar2)
EndFunc
</syntaxhighlight>

* A variable declared globally (with the Global keyword) is visible anywhere in the script. Always declare your global variables in the global scope, not in a function. It will prevent another function from using it before its declaration and the declaration is implicit (see [[#jumpsec1|examples]]).

* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.
:Declaration in the global scope: the variable is visible everywhere; declare it as Local if this one is only to be used in the same scope, i.e. outside of any functions. A variable declared as Local in the Global scope is still a Global variable, it's only for the sake of code clarity that you'd use the Local declaration in the Global scope.
:Declaration in a function: the variable is visible by the function itself and nowhere else.

Structure of a code scope:
<syntaxhighlight lang="autoit">
; Global scope

; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function)
#include <MsgBoxConstants.au3>

; This scope is either Global or Local, depending on where you use the variables

; Assign a Global variable the number 0 (which corresponds to an initialization of a variable number), its scope is Global because it's used in at least one function
Global $g_iVar1 = 0

; Assign a Local variable the string "foo", its scope is Local because it's use is used only in this scope
Local $sVar2 = "foo"

; Display the content of $sVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $sVar2)

; Re-assign a Local variable the string returned by the function MyFunc
$sVar2 = MyFunc()

; Re-Display the content of $sVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $sVar2)

; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope)
Func MyFunc()
; Local scope

; Display the content of $g_iVar1
MsgBox($MB_SYSTEMMODAL, "", "Value of $g_iVar1: " & $g_iVar1)

; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope
Local $sVar3 = "bar"

; Display the content of $sVar3
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)

; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called
Return $sVar3
EndFunc ;==>MyFunc
</syntaxhighlight>

Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).

Example 1:
<syntaxhighlight lang="autoit">
; Include the Array UDF, it's needed here for the _ArrayDisplay function
#include <Array.au3>

; Assign a Local variable an array containing numbers with a size of 5
; Note than an array is 0 based, to access the first element the code is: $aiArray[0]
Local $aiArray[5] = [1, 2, 3, 4, 5]

; Display the contents
_ArrayDisplay($aiArray)

; Empty the array (and keep its size)
Dim $aiArray[5]

; Display the contents
_ArrayDisplay($aiArray)
</syntaxhighlight>
Remark: The variable type of an emptied array is a string, every non initialized variable is a string.

Example 2:
<syntaxhighlight lang="autoit">
#include <Array.au3>

; Call MyFunc with default parameters ($vParam1 = 0)
MyFunc()

; Assign a Local variable an array containing integers
Local $aiArray[3] = [3, 4, 5]
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray)
MyFunc($aiArray)

Func MyFunc($vParam1 = 0)
; If $vParam1 is NOT an array then redeclare it to an array
If Not IsArray($vParam1) Then
Dim $vParam1[3] = [0, 1, 2]
EndIf

; Display the array
_ArrayDisplay($vParam1)
EndFunc ;==>MyFunc
</syntaxhighlight>

And for the ReDim keyword, limit its use to resize an array when you want to keep its content:
<syntaxhighlight lang="autoit">
; Include the Array UDF, it's needed here for the _ArrayDisplay function
#include <Array.au3>

; Assign a Local variable an array containing numbers with a size of 5
; Note than an array is 0 based, to access the first element the code is: $aiArray[0]
Local $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents
_ArrayDisplay($aArray)

; Resize the array (and keep its content)
ReDim $aArray[3]

; Display the contents
_ArrayDisplay($aArray)
</syntaxhighlight>

Why using Dim over Local/Global is not always a good option:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

Dim $g_vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."

MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")

Example()

Func Example()
MsgBox($MB_SYSTEMMODAL, "", $g_vVariableThatIsGlobal) ; That looks alright to me as it displays the following text: This is a variable that has "Program Scope" aka Global

Local $vReturn = SomeFunc() ; Call some random function

MsgBox($MB_SYSTEMMODAL, $vReturn, $g_vVariableThatIsGlobal) ; The Global variable ($g_vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc"
EndFunc ;==>Example

Func SomeFunc()
; This should create a variable in Local scope if the variable name doesn"t already exist
; For argument sake I totally forgot that I declared a variable already with the same name
; Well I only want this to be changed in the function and not the variable at the top of the script
; Should be OK right? Think again
Dim $g_vVariableThatIsGlobal = ""

For $i = 1 To 10
$g_vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $g_vVariableThatIsGlobal
Next
Return $g_vVariableThatIsGlobal
EndFunc ;==>SomeFunc
</syntaxhighlight>

Declaring Global variables in a Function is never a good idea:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Calling Example() first will initialise the Global variable $g_vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error
; Now look at Example 2
Example()

Func Example()
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script
Global $g_vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $g_vVariableThatIsGlobal) ; As the variable was initialised this will not return an error
EndFunc ;==>SomeFunc
</syntaxhighlight>

Example 2:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Calling SomeFunc() first will bypass the Global variable $g_vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $g_vVariableThatIsGlobal contains
SomeFunc()

Func Example()
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script
Global $g_vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $g_vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."
EndFunc ;==>SomeFunc
</syntaxhighlight>

Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition
For $i = 1 To 10 ; $i is in 'loop scope.'
Local $iInt = $i
Next
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10
</syntaxhighlight>

<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Declaring variables outside of loops is more efficient in the long run
Local $iInt = 0
For $i = 1 To 10 ; $i is in 'loop scope.'
$iInt = $i
Next
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10
</syntaxhighlight>

There is no requirement to declare the iteration count variable in a loop:
<syntaxhighlight lang="autoit">
; Correct
Local Const $iCount = 99
Local $aArray[$iCount]
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it
$aArray[$i] = $i
Next

; Incorrect
Local Const $iCount = 99
Local $aArray[$iCount]
Local $i ; This is only used to store the iteration count value in the loop and therefore doesn't need to be declared.
For $i = 0 To UBound($iCount) - 1
$aArray[$i] = $i
Next
</syntaxhighlight>
As you can see, there is the Const keyword in the example, we are going to talk about it.

== Const, Static, Enum ==

=== Const ===
We won't talk about the advantages of using a constant variable, they are neglibible (for your information, an AutoIt constant variable is marked as read-only and remains a read-only variable when compiled).

The Const keyword may be used first by some of you to avoid re-assignments.
The best way to use them is for real static values, meaning that these values won't change regardless of the instance of the program.

Example:
<syntaxhighlight lang="autoit">
; Not recommended
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes

; Recommended
Local Const $iMyAge = 19
</syntaxhighlight>

=== Static ===
Static variables are the solution to global variables being used in only one function.
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.
<syntaxhighlight lang="autoit">
Example()

Func Example()
SomeFunc() ; This will display a message box of 1, 1
SomeFunc() ; This will display a message box of 1, 2
SomeFunc() ; This will display a message box of 1, 3
EndFunc ;==>Example

Func SomeFunc()
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. Also, the variable can't be
; accessed from anywhere else in the script apart from the Function it was declared in
Local Static $vVariableThatIsStatic = 0
Local $vVariableThatIsLocal = 0
$vVariableThatIsLocal += 1 ; This will always be 1 as it is destroyed once returned from SomeFunc
$vVariableThatIsStatic += 1 ; This will increase by 1
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)
EndFunc ;==>SomeFunc
</syntaxhighlight>

=== Enum ===
This statement is often practical in certain situations:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

Example()

Func Example()
; Create variables in Local scope and enumerate through the variables. Default is to start from 0
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4

; Create an array in Local scope with 4 elements
Local $aAnimalNames[4]

; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]

; Display the values of the array
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)

; Sometimes using this approach for accessing an element is more practical than using a numerical value, due to the fact changing the index value of
; the enum constant has no affect on it's position in the array. Therefore changing the location of $eCat in the array is as simple as changing the order
; it appears in the initial declaration e.g

; Local Enum $eDog, $eMouse, $eCat, $eHamster

; Now $eCat is the 2nd element in the array. If you were using numerical values, you would have to manually change all references of $aAnimalNames[0] to
; $aAnimalNames[2], as well as for the other elements which have now shifted
EndFunc ;==>Example
</syntaxhighlight>

== Au3Check directive ==
As you may know (and we hope), the Au3Check tool checks your code for syntax errors, variables used without being declared etc. which is a good thing to fix your script.

With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:
<syntaxhighlight lang="autoit">
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7
</syntaxhighlight>
|Note: this directive is only used if you've installed the full version of [https://www.autoitscript.com/cgi-bin/getfile.pl?../autoit3/scite/download/SciTE4AutoIt3.exe Scite4AutoIt3]

== Magic Numbers ==
Magic numbers are arbitrary numbers interspersed throughout a program's source code which do not have an associated identifier. The downside to this is not being able to derive a meaning from the number.

For example:
<syntaxhighlight lang="autoit">
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")
</syntaxhighlight>
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.

The corrected example:
<syntaxhighlight lang="autoit">
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")
</syntaxhighlight>

Example 2:
<syntaxhighlight lang="autoit">
; Imagine you're a new user to AutoIt and you come across this code, where would you find -3, -4 or -5 in the help file?
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean
; why would you, the help file is there for a reason
Example()

Func Example()
Local $hGUI = GUICreate('')
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case -3 ; Doesn't really tell much about what it does
ExitLoop

Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?
MsgBox(4096, '', 'Do something when this action takes place.')

EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example
</syntaxhighlight>

Did you understand the numbers were these:
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

Example()

Func Example()
Local $hGUI = GUICreate('')
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action
ExitLoop

Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file

EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example
</syntaxhighlight>

[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]

== Include-once directive ==
This one is designed for standard includes and UDFs, it's highly recommended to use it.

Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions

Put the directive in top of your UDF (library) to avoid itself to be included more than once :
<syntaxhighlight lang="autoit">
#include-once
</syntaxhighlight>

Best coding practices

2016-07-20T20:16:39Z

BrewManNH: /* Static */

Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.

'''Note''': You must use AutoIt v3.3.10.0 or above to run the examples below.

__TOC__

== Using Functions ==
If a function sets the @error flag, you should always check it before using a return value - if @error indicates an error then the function return value is generally undefined.

Learn more about using Functions by reading "[https://www.autoitscript.com/autoit3/docs/function_notes.htm Function Notes]" from HelpFile.

== Names of Variables ==
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.

{| class="wikitable"
|-
! prefix !! covering type !! example
|-
| a || Arrays || $aArray[0]
|-
| b || Booleans || $bBool = True
|-
| d || Binaries || $dBinary = Binary("0x80000000")
|-
| e || Constant variable || Local Const $eEulersConstant = 2.7182818284590452
|-
| f || Floating point || $fFloat = 0.123
|-
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")
|-
| i || Integer || $iInteger = 10
|-
| id || An AutoIt controlID || $idButton_Ok = GUICtrlCreateButton("OK", 5, 5)
|-
| m || Maps || $mMap[]
|-
| n || General number (no preference) || $nNumber = 0
|-
| p || Pointers || $pRect = DllStructGetPtr($tRECT)
|-
| s || Strings (chars included) || $sString = "Hello world"
|-
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)
|-
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Day; endstruct"
|-
|v || Variant || $vData = ClipGet()
|}

Variables are named following this schema:
{| class="wikitable"
|-
! dollar prefix !! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| $ || a || h || Handles
|}

Examples:
<syntaxhighlight lang="autoit">
; Assign a local variable the integer 7
Local $iWeekDays = 7

; Assign a local variable the value of Pi
Local $fPi = 3.14159265358979

; Assign a local variable an array of strings
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']

; Assign a local variable an array of numbers
Local $anArray[4] = [0, 0.25, 3 / 4, 12]
</syntaxhighlight>
 

== Variable Initialization ==
When initializing variables there are several points to consider. It is bad practice to hog memory by assigning data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.

Examples:
<syntaxhighlight lang="autoit">
; Inconsistent data types are considered bad
Local $iInteger = "0"
Local $sString = False

; Correct initialization
Local $iInteger = 0
Local $sString = ''
</syntaxhighlight>
 

In the following table, recommended default values are shown for each data type. Some data types have more than one possibile default value which can be used for initialization.

{| class="wikitable"
|-
! Default Value !! covering type
|-
| Binary("") || $d
|-
| "" || $s, $v
|-
| 0 || $a, $h, $i, $id, $m, $n, $o, $p, $t, $tag, $v
|-
| 0.0 || $f
|-
| Null || $o, $s, $v
|-
| False (or True) || $b
|}

 
Example:
<syntaxhighlight lang="autoit">
; Declare and initialize a variable with the recommended default value
Local $vUndefined = Null ; This does not require much memory

; Some time later:
$vUndefined = 0xB0AD1CEA ; Assign an appropriate value as and when needed
</syntaxhighlight>
 

To reduce bloat, multiple variables can be declared on a single line. When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to follow and manage in a future, however the best layout will vary according to circumstance.

Example:
<syntaxhighlight lang="autoit">
; Not recommended
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types

; Recommended
Local $iLeft = 10, $iTop = 10 ; Integers
Local $idButton_Go = GUICtrlCreateButton("Go", $iLeft, $iTop) ; ControlIds
Local $idButton_Quit = GUICtrlCreateButton("Quit", 50, 10) ; ControlIds
</syntaxhighlight>
 

In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data type, variables declared without being initialized should be considered as being undefined.
 

== Scopes of Variables ==
Variables should also be named according to their scope.
{| class="wikitable"
|-
! Global UDF variable !! Global variable !! Local variable
|-
| $__g_iSomeVar || $g_iSomeVar || $iSomeVar
|}
With this method, you will avoid unwanted re-assignments.

Example:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Assign a Global variable the number 0
Global $iSomeVar1 = 0
; Assign a Global variable the number 5
Global $g_iSomeVar2 = 5

SomeFunc()

Func SomeFunc()
; Assign Local variables respectively the numbers 3 and 4
Local $iSomeVar1 = 3, $iSomeVar2 = 4

; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global"

; Display the value of $iSomeVar1
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)

; Display the value of $iSomeVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)

; Display the value of $g_iSomeVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $g_iSomeVar2: " & $g_iSomeVar2)
EndFunc
</syntaxhighlight>

* A variable declared globally (with the Global keyword) is visible anywhere in the script. Always declare your global variables in the global scope, not in a function. It will prevent another function from using it before its declaration and the declaration is implicit (see [[#jumpsec1|examples]]).

* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.
:Declaration in the global scope: the variable is visible everywhere; declare it as Local if this one is only to be used in the same scope, i.e. outside of any functions. A variable declared as Local in the Global scope is still a Global variable, it's only for the sake of code clarity that you'd use the Local declaration in the Global scope.
:Declaration in a function: the variable is visible by the function itself and nowhere else.

Structure of a code scope:
<syntaxhighlight lang="autoit">
; Global scope

; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function)
#include <MsgBoxConstants.au3>

; This scope is either Global or Local, depending on where you use the variables

; Assign a Global variable the number 0 (which corresponds to an initialization of a variable number), its scope is Global because it's used in at least one function
Global $g_iVar1 = 0

; Assign a Local variable the string "foo", its scope is Local because it's use is used only in this scope
Local $sVar2 = "foo"

; Display the content of $sVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $sVar2)

; Re-assign a Local variable the string returned by the function MyFunc
$sVar2 = MyFunc()

; Re-Display the content of $sVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $sVar2)

; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope)
Func MyFunc()
; Local scope

; Display the content of $g_iVar1
MsgBox($MB_SYSTEMMODAL, "", "Value of $g_iVar1: " & $g_iVar1)

; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope
Local $sVar3 = "bar"

; Display the content of $sVar3
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)

; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called
Return $sVar3
EndFunc ;==>MyFunc
</syntaxhighlight>

Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).

Example 1:
<syntaxhighlight lang="autoit">
; Include the Array UDF, it's needed here for the _ArrayDisplay function
#include <Array.au3>

; Assign a Local variable an array containing numbers with a size of 5
; Note than an array is 0 based, to access the first element the code is: $aiArray[0]
Local $aiArray[5] = [1, 2, 3, 4, 5]

; Display the contents
_ArrayDisplay($aiArray)

; Empty the array (and keep its size)
Dim $aiArray[5]

; Display the contents
_ArrayDisplay($aiArray)
</syntaxhighlight>
Remark: The variable type of an emptied array is a string, every non initialized variable is a string.

Example 2:
<syntaxhighlight lang="autoit">
#include <Array.au3>

; Call MyFunc with default parameters ($vParam1 = 0)
MyFunc()

; Assign a Local variable an array containing integers
Local $aiArray[3] = [3, 4, 5]
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray)
MyFunc($aiArray)

Func MyFunc($vParam1 = 0)
; If $vParam1 is NOT an array then redeclare it to an array
If Not IsArray($vParam1) Then
Dim $vParam1[3] = [0, 1, 2]
EndIf

; Display the array
_ArrayDisplay($vParam1)
EndFunc ;==>MyFunc
</syntaxhighlight>

And for the ReDim keyword, limit its use to resize an array when you want to keep its content:
<syntaxhighlight lang="autoit">
; Include the Array UDF, it's needed here for the _ArrayDisplay function
#include <Array.au3>

; Assign a Local variable an array containing numbers with a size of 5
; Note than an array is 0 based, to access the first element the code is: $aiArray[0]
Local $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents
_ArrayDisplay($aArray)

; Resize the array (and keep its content)
ReDim $aArray[3]

; Display the contents
_ArrayDisplay($aArray)
</syntaxhighlight>

Why using Dim over Local/Global is not always a good option:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

Dim $g_vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."

MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")

Example()

Func Example()
MsgBox($MB_SYSTEMMODAL, "", $g_vVariableThatIsGlobal) ; That looks alright to me as it displays the following text: This is a variable that has "Program Scope" aka Global

Local $vReturn = SomeFunc() ; Call some random function

MsgBox($MB_SYSTEMMODAL, $vReturn, $g_vVariableThatIsGlobal) ; The Global variable ($g_vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc"
EndFunc ;==>Example

Func SomeFunc()
; This should create a variable in Local scope if the variable name doesn"t already exist
; For argument sake I totally forgot that I declared a variable already with the same name
; Well I only want this to be changed in the function and not the variable at the top of the script
; Should be OK right? Think again
Dim $g_vVariableThatIsGlobal = ""

For $i = 1 To 10
$g_vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $g_vVariableThatIsGlobal
Next
Return $g_vVariableThatIsGlobal
EndFunc ;==>SomeFunc
</syntaxhighlight>

Declaring Global variables in a Function is never a good idea:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Calling Example() first will initialise the Global variable $g_vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error
; Now look at Example 2
Example()

Func Example()
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script
Global $g_vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $g_vVariableThatIsGlobal) ; As the variable was initialised this will not return an error
EndFunc ;==>SomeFunc
</syntaxhighlight>

Example 2:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Calling SomeFunc() first will bypass the Global variable $g_vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $g_vVariableThatIsGlobal contains
SomeFunc()

Func Example()
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script
Global $g_vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $g_vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."
EndFunc ;==>SomeFunc
</syntaxhighlight>

Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition
For $i = 1 To 10 ; $i is in 'loop scope.'
Local $iInt = $i
Next
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10
</syntaxhighlight>

<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Declaring variables outside of loops is more efficient in the long run
Local $iInt = 0
For $i = 1 To 10 ; $i is in 'loop scope.'
$iInt = $i
Next
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10
</syntaxhighlight>

There is no requirement to declare the iteration count variable in a loop:
<syntaxhighlight lang="autoit">
; Correct
Local Const $iCount = 99
Local $aArray[$iCount]
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it
$aArray[$i] = $i
Next

; Incorrect
Local Const $iCount = 99
Local $aArray[$iCount]
Local $i ; This is only used to store the iteration count value in the loop and therefore doesn't need to be declared.
For $i = 0 To UBound($iCount) - 1
$aArray[$i] = $i
Next
</syntaxhighlight>
As you can see, there is the Const keyword in the example, we are going to talk about it.

== Const, Static, Enum ==

=== Const ===
We won't talk about the advantages of using a constant variable, they are neglibible (for your information, an AutoIt constant variable is marked as read-only and remains a read-only variable when compiled).

The Const keyword may be used first by some of you to avoid re-assignments.
The best way to use them is for real static values, meaning that these values won't change regardless of the instance of the program.

Example:
<syntaxhighlight lang="autoit">
; Not recommended
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes

; Recommended
Local Const $iMyAge = 19
</syntaxhighlight>

=== Static ===
Static variables are the solution to global variables being used in only one function.
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.
<syntaxhighlight lang="autoit">
Example()

Func Example()
SomeFunc() ; This will display a message box of 1, 1
SomeFunc() ; This will display a message box of 1, 2
SomeFunc() ; This will display a message box of 1, 3
EndFunc ;==>Example

Func SomeFunc()
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. Also, the variable can't be
; accessed from anywhere else in the script apart from the Function it was declared in
Local Static $vVariableThatIsStatic = 0
Local $vVariableThatIsLocal = 0
$vVariableThatIsLocal += 1 ; This will always be 1 as it is destroyed once returned from SomeFunc
$vVariableThatIsStatic += 1 ; This will increase by 1
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)
EndFunc ;==>SomeFunc
</syntaxhighlight>

=== Enum ===
This statement is often practical in certain situations:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

Example()

Func Example()
; Create variables in Local scope and enumerate through the variables. Default is to start from 0
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4

; Create an array in Local scope with 4 elements
Local $aAnimalNames[4]

; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]

; Display the values of the array
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)

; Sometimes using this approach for accessing an element is more practical than using a numerical value, due to the fact changing the index value of
; the enum constant has no affect on it's position in the array. Therefore changing the location of $eCat in the array is as simple as changing the order
; it appears in the initial declaration e.g

; Local Enum $eDog, $eMouse, $eCat, $eHamster

; Now $eCat is the 2nd element in the array. If you were using numerical values, you would have to manually change all references of $aAnimalNames[0] to
; $aAnimalNames[2], as well as for the other elements which have now shifted
EndFunc ;==>Example
</syntaxhighlight>

== Au3Check directive ==
As you may know (and we hope), the Au3Check tool checks your code for syntax errors, variables used without being declared etc. which is a good thing to fix your script.

With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:
<syntaxhighlight lang="autoit">
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7
</syntaxhighlight>

== Magic Numbers ==
Magic numbers are arbitrary numbers interspersed throughout a program's source code which do not have an associated identifier. The downside to this is not being able to derive a meaning from the number.

For example:
<syntaxhighlight lang="autoit">
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")
</syntaxhighlight>
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.

The corrected example:
<syntaxhighlight lang="autoit">
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")
</syntaxhighlight>

Example 2:
<syntaxhighlight lang="autoit">
; Imagine you're a new user to AutoIt and you come across this code, where would you find -3, -4 or -5 in the help file?
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean
; why would you, the help file is there for a reason
Example()

Func Example()
Local $hGUI = GUICreate('')
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case -3 ; Doesn't really tell much about what it does
ExitLoop

Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?
MsgBox(4096, '', 'Do something when this action takes place.')

EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example
</syntaxhighlight>

Did you understand the numbers were these:
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

Example()

Func Example()
Local $hGUI = GUICreate('')
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action
ExitLoop

Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file

EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example
</syntaxhighlight>

[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]

== Include-once directive ==
This one is designed for standard includes and UDFs, it's highly recommended to use it.

Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions

Put the directive in top of your UDF (library) to avoid itself to be included more than once :
<syntaxhighlight lang="autoit">
#include-once
</syntaxhighlight>

Best coding practices

2016-07-20T20:14:37Z

BrewManNH: /* Const */

Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.

'''Note''': You must use AutoIt v3.3.10.0 or above to run the examples below.

__TOC__

== Using Functions ==
If a function sets the @error flag, you should always check it before using a return value - if @error indicates an error then the function return value is generally undefined.

Learn more about using Functions by reading "[https://www.autoitscript.com/autoit3/docs/function_notes.htm Function Notes]" from HelpFile.

== Names of Variables ==
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.

{| class="wikitable"
|-
! prefix !! covering type !! example
|-
| a || Arrays || $aArray[0]
|-
| b || Booleans || $bBool = True
|-
| d || Binaries || $dBinary = Binary("0x80000000")
|-
| e || Constant variable || Local Const $eEulersConstant = 2.7182818284590452
|-
| f || Floating point || $fFloat = 0.123
|-
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")
|-
| i || Integer || $iInteger = 10
|-
| id || An AutoIt controlID || $idButton_Ok = GUICtrlCreateButton("OK", 5, 5)
|-
| m || Maps || $mMap[]
|-
| n || General number (no preference) || $nNumber = 0
|-
| p || Pointers || $pRect = DllStructGetPtr($tRECT)
|-
| s || Strings (chars included) || $sString = "Hello world"
|-
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)
|-
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Day; endstruct"
|-
|v || Variant || $vData = ClipGet()
|}

Variables are named following this schema:
{| class="wikitable"
|-
! dollar prefix !! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| $ || a || h || Handles
|}

Examples:
<syntaxhighlight lang="autoit">
; Assign a local variable the integer 7
Local $iWeekDays = 7

; Assign a local variable the value of Pi
Local $fPi = 3.14159265358979

; Assign a local variable an array of strings
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']

; Assign a local variable an array of numbers
Local $anArray[4] = [0, 0.25, 3 / 4, 12]
</syntaxhighlight>
 

== Variable Initialization ==
When initializing variables there are several points to consider. It is bad practice to hog memory by assigning data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.

Examples:
<syntaxhighlight lang="autoit">
; Inconsistent data types are considered bad
Local $iInteger = "0"
Local $sString = False

; Correct initialization
Local $iInteger = 0
Local $sString = ''
</syntaxhighlight>
 

In the following table, recommended default values are shown for each data type. Some data types have more than one possibile default value which can be used for initialization.

{| class="wikitable"
|-
! Default Value !! covering type
|-
| Binary("") || $d
|-
| "" || $s, $v
|-
| 0 || $a, $h, $i, $id, $m, $n, $o, $p, $t, $tag, $v
|-
| 0.0 || $f
|-
| Null || $o, $s, $v
|-
| False (or True) || $b
|}

 
Example:
<syntaxhighlight lang="autoit">
; Declare and initialize a variable with the recommended default value
Local $vUndefined = Null ; This does not require much memory

; Some time later:
$vUndefined = 0xB0AD1CEA ; Assign an appropriate value as and when needed
</syntaxhighlight>
 

To reduce bloat, multiple variables can be declared on a single line. When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to follow and manage in a future, however the best layout will vary according to circumstance.

Example:
<syntaxhighlight lang="autoit">
; Not recommended
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types

; Recommended
Local $iLeft = 10, $iTop = 10 ; Integers
Local $idButton_Go = GUICtrlCreateButton("Go", $iLeft, $iTop) ; ControlIds
Local $idButton_Quit = GUICtrlCreateButton("Quit", 50, 10) ; ControlIds
</syntaxhighlight>
 

In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data type, variables declared without being initialized should be considered as being undefined.
 

== Scopes of Variables ==
Variables should also be named according to their scope.
{| class="wikitable"
|-
! Global UDF variable !! Global variable !! Local variable
|-
| $__g_iSomeVar || $g_iSomeVar || $iSomeVar
|}
With this method, you will avoid unwanted re-assignments.

Example:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Assign a Global variable the number 0
Global $iSomeVar1 = 0
; Assign a Global variable the number 5
Global $g_iSomeVar2 = 5

SomeFunc()

Func SomeFunc()
; Assign Local variables respectively the numbers 3 and 4
Local $iSomeVar1 = 3, $iSomeVar2 = 4

; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global"

; Display the value of $iSomeVar1
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)

; Display the value of $iSomeVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)

; Display the value of $g_iSomeVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $g_iSomeVar2: " & $g_iSomeVar2)
EndFunc
</syntaxhighlight>

* A variable declared globally (with the Global keyword) is visible anywhere in the script. Always declare your global variables in the global scope, not in a function. It will prevent another function from using it before its declaration and the declaration is implicit (see [[#jumpsec1|examples]]).

* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.
:Declaration in the global scope: the variable is visible everywhere; declare it as Local if this one is only to be used in the same scope, i.e. outside of any functions. A variable declared as Local in the Global scope is still a Global variable, it's only for the sake of code clarity that you'd use the Local declaration in the Global scope.
:Declaration in a function: the variable is visible by the function itself and nowhere else.

Structure of a code scope:
<syntaxhighlight lang="autoit">
; Global scope

; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function)
#include <MsgBoxConstants.au3>

; This scope is either Global or Local, depending on where you use the variables

; Assign a Global variable the number 0 (which corresponds to an initialization of a variable number), its scope is Global because it's used in at least one function
Global $g_iVar1 = 0

; Assign a Local variable the string "foo", its scope is Local because it's use is used only in this scope
Local $sVar2 = "foo"

; Display the content of $sVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $sVar2)

; Re-assign a Local variable the string returned by the function MyFunc
$sVar2 = MyFunc()

; Re-Display the content of $sVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $sVar2)

; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope)
Func MyFunc()
; Local scope

; Display the content of $g_iVar1
MsgBox($MB_SYSTEMMODAL, "", "Value of $g_iVar1: " & $g_iVar1)

; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope
Local $sVar3 = "bar"

; Display the content of $sVar3
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)

; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called
Return $sVar3
EndFunc ;==>MyFunc
</syntaxhighlight>

Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).

Example 1:
<syntaxhighlight lang="autoit">
; Include the Array UDF, it's needed here for the _ArrayDisplay function
#include <Array.au3>

; Assign a Local variable an array containing numbers with a size of 5
; Note than an array is 0 based, to access the first element the code is: $aiArray[0]
Local $aiArray[5] = [1, 2, 3, 4, 5]

; Display the contents
_ArrayDisplay($aiArray)

; Empty the array (and keep its size)
Dim $aiArray[5]

; Display the contents
_ArrayDisplay($aiArray)
</syntaxhighlight>
Remark: The variable type of an emptied array is a string, every non initialized variable is a string.

Example 2:
<syntaxhighlight lang="autoit">
#include <Array.au3>

; Call MyFunc with default parameters ($vParam1 = 0)
MyFunc()

; Assign a Local variable an array containing integers
Local $aiArray[3] = [3, 4, 5]
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray)
MyFunc($aiArray)

Func MyFunc($vParam1 = 0)
; If $vParam1 is NOT an array then redeclare it to an array
If Not IsArray($vParam1) Then
Dim $vParam1[3] = [0, 1, 2]
EndIf

; Display the array
_ArrayDisplay($vParam1)
EndFunc ;==>MyFunc
</syntaxhighlight>

And for the ReDim keyword, limit its use to resize an array when you want to keep its content:
<syntaxhighlight lang="autoit">
; Include the Array UDF, it's needed here for the _ArrayDisplay function
#include <Array.au3>

; Assign a Local variable an array containing numbers with a size of 5
; Note than an array is 0 based, to access the first element the code is: $aiArray[0]
Local $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents
_ArrayDisplay($aArray)

; Resize the array (and keep its content)
ReDim $aArray[3]

; Display the contents
_ArrayDisplay($aArray)
</syntaxhighlight>

Why using Dim over Local/Global is not always a good option:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

Dim $g_vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."

MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")

Example()

Func Example()
MsgBox($MB_SYSTEMMODAL, "", $g_vVariableThatIsGlobal) ; That looks alright to me as it displays the following text: This is a variable that has "Program Scope" aka Global

Local $vReturn = SomeFunc() ; Call some random function

MsgBox($MB_SYSTEMMODAL, $vReturn, $g_vVariableThatIsGlobal) ; The Global variable ($g_vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc"
EndFunc ;==>Example

Func SomeFunc()
; This should create a variable in Local scope if the variable name doesn"t already exist
; For argument sake I totally forgot that I declared a variable already with the same name
; Well I only want this to be changed in the function and not the variable at the top of the script
; Should be OK right? Think again
Dim $g_vVariableThatIsGlobal = ""

For $i = 1 To 10
$g_vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $g_vVariableThatIsGlobal
Next
Return $g_vVariableThatIsGlobal
EndFunc ;==>SomeFunc
</syntaxhighlight>

Declaring Global variables in a Function is never a good idea:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Calling Example() first will initialise the Global variable $g_vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error
; Now look at Example 2
Example()

Func Example()
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script
Global $g_vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $g_vVariableThatIsGlobal) ; As the variable was initialised this will not return an error
EndFunc ;==>SomeFunc
</syntaxhighlight>

Example 2:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Calling SomeFunc() first will bypass the Global variable $g_vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $g_vVariableThatIsGlobal contains
SomeFunc()

Func Example()
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script
Global $g_vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $g_vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."
EndFunc ;==>SomeFunc
</syntaxhighlight>

Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition
For $i = 1 To 10 ; $i is in 'loop scope.'
Local $iInt = $i
Next
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10
</syntaxhighlight>

<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Declaring variables outside of loops is more efficient in the long run
Local $iInt = 0
For $i = 1 To 10 ; $i is in 'loop scope.'
$iInt = $i
Next
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10
</syntaxhighlight>

There is no requirement to declare the iteration count variable in a loop:
<syntaxhighlight lang="autoit">
; Correct
Local Const $iCount = 99
Local $aArray[$iCount]
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it
$aArray[$i] = $i
Next

; Incorrect
Local Const $iCount = 99
Local $aArray[$iCount]
Local $i ; This is only used to store the iteration count value in the loop and therefore doesn't need to be declared.
For $i = 0 To UBound($iCount) - 1
$aArray[$i] = $i
Next
</syntaxhighlight>
As you can see, there is the Const keyword in the example, we are going to talk about it.

== Const, Static, Enum ==

=== Const ===
We won't talk about the advantages of using a constant variable, they are neglibible (for your information, an AutoIt constant variable is marked as read-only and remains a read-only variable when compiled).

The Const keyword may be used first by some of you to avoid re-assignments.
The best way to use them is for real static values, meaning that these values won't change regardless of the instance of the program.

Example:
<syntaxhighlight lang="autoit">
; Not recommended
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes

; Recommended
Local Const $iMyAge = 19
</syntaxhighlight>

=== Static ===
Static variables are the solution to the global variables used in only one function.
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.
<syntaxhighlight lang="autoit">
Example()

Func Example()
SomeFunc() ; This will display a message box of 1, 1
SomeFunc() ; This will display a message box of 1, 2
SomeFunc() ; This will display a message box of 1, 3
EndFunc ;==>Example

Func SomeFunc()
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be
; accessed from anywhere else in the script apart from the Function it was declared in
Local Static $vVariableThatIsStatic = 0
Local $vVariableThatIsLocal = 0
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc
$vVariableThatIsStatic += 1 ; This will increase by 1
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)
EndFunc ;==>SomeFunc
</syntaxhighlight>

=== Enum ===
This statement is often practical in certain situations:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

Example()

Func Example()
; Create variables in Local scope and enumerate through the variables. Default is to start from 0
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4

; Create an array in Local scope with 4 elements
Local $aAnimalNames[4]

; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]

; Display the values of the array
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)

; Sometimes using this approach for accessing an element is more practical than using a numerical value, due to the fact changing the index value of
; the enum constant has no affect on it's position in the array. Therefore changing the location of $eCat in the array is as simple as changing the order
; it appears in the initial declaration e.g

; Local Enum $eDog, $eMouse, $eCat, $eHamster

; Now $eCat is the 2nd element in the array. If you were using numerical values, you would have to manually change all references of $aAnimalNames[0] to
; $aAnimalNames[2], as well as for the other elements which have now shifted
EndFunc ;==>Example
</syntaxhighlight>

== Au3Check directive ==
As you may know (and we hope), the Au3Check tool checks your code for syntax errors, variables used without being declared etc. which is a good thing to fix your script.

With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:
<syntaxhighlight lang="autoit">
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7
</syntaxhighlight>

== Magic Numbers ==
Magic numbers are arbitrary numbers interspersed throughout a program's source code which do not have an associated identifier. The downside to this is not being able to derive a meaning from the number.

For example:
<syntaxhighlight lang="autoit">
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")
</syntaxhighlight>
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.

The corrected example:
<syntaxhighlight lang="autoit">
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")
</syntaxhighlight>

Example 2:
<syntaxhighlight lang="autoit">
; Imagine you're a new user to AutoIt and you come across this code, where would you find -3, -4 or -5 in the help file?
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean
; why would you, the help file is there for a reason
Example()

Func Example()
Local $hGUI = GUICreate('')
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case -3 ; Doesn't really tell much about what it does
ExitLoop

Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?
MsgBox(4096, '', 'Do something when this action takes place.')

EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example
</syntaxhighlight>

Did you understand the numbers were these:
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

Example()

Func Example()
Local $hGUI = GUICreate('')
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action
ExitLoop

Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file

EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example
</syntaxhighlight>

[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]

== Include-once directive ==
This one is designed for standard includes and UDFs, it's highly recommended to use it.

Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions

Put the directive in top of your UDF (library) to avoid itself to be included more than once :
<syntaxhighlight lang="autoit">
#include-once
</syntaxhighlight>

Best coding practices

2016-07-20T20:11:30Z

BrewManNH: /* Scopes of Variables */

Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.

'''Note''': You must use AutoIt v3.3.10.0 or above to run the examples below.

__TOC__

== Using Functions ==
If a function sets the @error flag, you should always check it before using a return value - if @error indicates an error then the function return value is generally undefined.

Learn more about using Functions by reading "[https://www.autoitscript.com/autoit3/docs/function_notes.htm Function Notes]" from HelpFile.

== Names of Variables ==
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.

{| class="wikitable"
|-
! prefix !! covering type !! example
|-
| a || Arrays || $aArray[0]
|-
| b || Booleans || $bBool = True
|-
| d || Binaries || $dBinary = Binary("0x80000000")
|-
| e || Constant variable || Local Const $eEulersConstant = 2.7182818284590452
|-
| f || Floating point || $fFloat = 0.123
|-
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")
|-
| i || Integer || $iInteger = 10
|-
| id || An AutoIt controlID || $idButton_Ok = GUICtrlCreateButton("OK", 5, 5)
|-
| m || Maps || $mMap[]
|-
| n || General number (no preference) || $nNumber = 0
|-
| p || Pointers || $pRect = DllStructGetPtr($tRECT)
|-
| s || Strings (chars included) || $sString = "Hello world"
|-
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)
|-
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Day; endstruct"
|-
|v || Variant || $vData = ClipGet()
|}

Variables are named following this schema:
{| class="wikitable"
|-
! dollar prefix !! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| $ || a || h || Handles
|}

Examples:
<syntaxhighlight lang="autoit">
; Assign a local variable the integer 7
Local $iWeekDays = 7

; Assign a local variable the value of Pi
Local $fPi = 3.14159265358979

; Assign a local variable an array of strings
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']

; Assign a local variable an array of numbers
Local $anArray[4] = [0, 0.25, 3 / 4, 12]
</syntaxhighlight>
 

== Variable Initialization ==
When initializing variables there are several points to consider. It is bad practice to hog memory by assigning data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.

Examples:
<syntaxhighlight lang="autoit">
; Inconsistent data types are considered bad
Local $iInteger = "0"
Local $sString = False

; Correct initialization
Local $iInteger = 0
Local $sString = ''
</syntaxhighlight>
 

In the following table, recommended default values are shown for each data type. Some data types have more than one possibile default value which can be used for initialization.

{| class="wikitable"
|-
! Default Value !! covering type
|-
| Binary("") || $d
|-
| "" || $s, $v
|-
| 0 || $a, $h, $i, $id, $m, $n, $o, $p, $t, $tag, $v
|-
| 0.0 || $f
|-
| Null || $o, $s, $v
|-
| False (or True) || $b
|}

 
Example:
<syntaxhighlight lang="autoit">
; Declare and initialize a variable with the recommended default value
Local $vUndefined = Null ; This does not require much memory

; Some time later:
$vUndefined = 0xB0AD1CEA ; Assign an appropriate value as and when needed
</syntaxhighlight>
 

To reduce bloat, multiple variables can be declared on a single line. When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to follow and manage in a future, however the best layout will vary according to circumstance.

Example:
<syntaxhighlight lang="autoit">
; Not recommended
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types

; Recommended
Local $iLeft = 10, $iTop = 10 ; Integers
Local $idButton_Go = GUICtrlCreateButton("Go", $iLeft, $iTop) ; ControlIds
Local $idButton_Quit = GUICtrlCreateButton("Quit", 50, 10) ; ControlIds
</syntaxhighlight>
 

In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data type, variables declared without being initialized should be considered as being undefined.
 

== Scopes of Variables ==
Variables should also be named according to their scope.
{| class="wikitable"
|-
! Global UDF variable !! Global variable !! Local variable
|-
| $__g_iSomeVar || $g_iSomeVar || $iSomeVar
|}
With this method, you will avoid unwanted re-assignments.

Example:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Assign a Global variable the number 0
Global $iSomeVar1 = 0
; Assign a Global variable the number 5
Global $g_iSomeVar2 = 5

SomeFunc()

Func SomeFunc()
; Assign Local variables respectively the numbers 3 and 4
Local $iSomeVar1 = 3, $iSomeVar2 = 4

; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global"

; Display the value of $iSomeVar1
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)

; Display the value of $iSomeVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)

; Display the value of $g_iSomeVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $g_iSomeVar2: " & $g_iSomeVar2)
EndFunc
</syntaxhighlight>

* A variable declared globally (with the Global keyword) is visible anywhere in the script. Always declare your global variables in the global scope, not in a function. It will prevent another function from using it before its declaration and the declaration is implicit (see [[#jumpsec1|examples]]).

* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.
:Declaration in the global scope: the variable is visible everywhere; declare it as Local if this one is only to be used in the same scope, i.e. outside of any functions. A variable declared as Local in the Global scope is still a Global variable, it's only for the sake of code clarity that you'd use the Local declaration in the Global scope.
:Declaration in a function: the variable is visible by the function itself and nowhere else.

Structure of a code scope:
<syntaxhighlight lang="autoit">
; Global scope

; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function)
#include <MsgBoxConstants.au3>

; This scope is either Global or Local, depending on where you use the variables

; Assign a Global variable the number 0 (which corresponds to an initialization of a variable number), its scope is Global because it's used in at least one function
Global $g_iVar1 = 0

; Assign a Local variable the string "foo", its scope is Local because it's use is used only in this scope
Local $sVar2 = "foo"

; Display the content of $sVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $sVar2)

; Re-assign a Local variable the string returned by the function MyFunc
$sVar2 = MyFunc()

; Re-Display the content of $sVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $sVar2)

; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope)
Func MyFunc()
; Local scope

; Display the content of $g_iVar1
MsgBox($MB_SYSTEMMODAL, "", "Value of $g_iVar1: " & $g_iVar1)

; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope
Local $sVar3 = "bar"

; Display the content of $sVar3
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)

; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called
Return $sVar3
EndFunc ;==>MyFunc
</syntaxhighlight>

Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).

Example 1:
<syntaxhighlight lang="autoit">
; Include the Array UDF, it's needed here for the _ArrayDisplay function
#include <Array.au3>

; Assign a Local variable an array containing numbers with a size of 5
; Note than an array is 0 based, to access the first element the code is: $aiArray[0]
Local $aiArray[5] = [1, 2, 3, 4, 5]

; Display the contents
_ArrayDisplay($aiArray)

; Empty the array (and keep its size)
Dim $aiArray[5]

; Display the contents
_ArrayDisplay($aiArray)
</syntaxhighlight>
Remark: The variable type of an emptied array is a string, every non initialized variable is a string.

Example 2:
<syntaxhighlight lang="autoit">
#include <Array.au3>

; Call MyFunc with default parameters ($vParam1 = 0)
MyFunc()

; Assign a Local variable an array containing integers
Local $aiArray[3] = [3, 4, 5]
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray)
MyFunc($aiArray)

Func MyFunc($vParam1 = 0)
; If $vParam1 is NOT an array then redeclare it to an array
If Not IsArray($vParam1) Then
Dim $vParam1[3] = [0, 1, 2]
EndIf

; Display the array
_ArrayDisplay($vParam1)
EndFunc ;==>MyFunc
</syntaxhighlight>

And for the ReDim keyword, limit its use to resize an array when you want to keep its content:
<syntaxhighlight lang="autoit">
; Include the Array UDF, it's needed here for the _ArrayDisplay function
#include <Array.au3>

; Assign a Local variable an array containing numbers with a size of 5
; Note than an array is 0 based, to access the first element the code is: $aiArray[0]
Local $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents
_ArrayDisplay($aArray)

; Resize the array (and keep its content)
ReDim $aArray[3]

; Display the contents
_ArrayDisplay($aArray)
</syntaxhighlight>

Why using Dim over Local/Global is not always a good option:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

Dim $g_vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."

MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")

Example()

Func Example()
MsgBox($MB_SYSTEMMODAL, "", $g_vVariableThatIsGlobal) ; That looks alright to me as it displays the following text: This is a variable that has "Program Scope" aka Global

Local $vReturn = SomeFunc() ; Call some random function

MsgBox($MB_SYSTEMMODAL, $vReturn, $g_vVariableThatIsGlobal) ; The Global variable ($g_vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc"
EndFunc ;==>Example

Func SomeFunc()
; This should create a variable in Local scope if the variable name doesn"t already exist
; For argument sake I totally forgot that I declared a variable already with the same name
; Well I only want this to be changed in the function and not the variable at the top of the script
; Should be OK right? Think again
Dim $g_vVariableThatIsGlobal = ""

For $i = 1 To 10
$g_vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $g_vVariableThatIsGlobal
Next
Return $g_vVariableThatIsGlobal
EndFunc ;==>SomeFunc
</syntaxhighlight>

Declaring Global variables in a Function is never a good idea:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Calling Example() first will initialise the Global variable $g_vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error
; Now look at Example 2
Example()

Func Example()
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script
Global $g_vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $g_vVariableThatIsGlobal) ; As the variable was initialised this will not return an error
EndFunc ;==>SomeFunc
</syntaxhighlight>

Example 2:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Calling SomeFunc() first will bypass the Global variable $g_vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $g_vVariableThatIsGlobal contains
SomeFunc()

Func Example()
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script
Global $g_vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $g_vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."
EndFunc ;==>SomeFunc
</syntaxhighlight>

Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition
For $i = 1 To 10 ; $i is in 'loop scope.'
Local $iInt = $i
Next
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10
</syntaxhighlight>

<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Declaring variables outside of loops is more efficient in the long run
Local $iInt = 0
For $i = 1 To 10 ; $i is in 'loop scope.'
$iInt = $i
Next
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10
</syntaxhighlight>

There is no requirement to declare the iteration count variable in a loop:
<syntaxhighlight lang="autoit">
; Correct
Local Const $iCount = 99
Local $aArray[$iCount]
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it
$aArray[$i] = $i
Next

; Incorrect
Local Const $iCount = 99
Local $aArray[$iCount]
Local $i ; This is only used to store the iteration count value in the loop and therefore doesn't need to be declared.
For $i = 0 To UBound($iCount) - 1
$aArray[$i] = $i
Next
</syntaxhighlight>
As you can see, there is the Const keyword in the example, we are going to talk about it.

== Const, Static, Enum ==

=== Const ===
We won't talk about the advantages of a constant variable, they are neglibible (for your information, an AutoIt constant variable is marked as read-only and remains a variable as read-only when compiled).

The Const keyword may be used in a first by some of you to avoid re-assignments.
The best way to use them is not this last case, the constants should be used for real static variables, meaning that their value won't change regardless to the instance of the program.

Example:
<syntaxhighlight lang="autoit">
; Not recommended
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes

; Recommended
Local Const $iMyAge = 19
</syntaxhighlight>

=== Static ===
Static variables are the solution to the global variables used in only one function.
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.
<syntaxhighlight lang="autoit">
Example()

Func Example()
SomeFunc() ; This will display a message box of 1, 1
SomeFunc() ; This will display a message box of 1, 2
SomeFunc() ; This will display a message box of 1, 3
EndFunc ;==>Example

Func SomeFunc()
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be
; accessed from anywhere else in the script apart from the Function it was declared in
Local Static $vVariableThatIsStatic = 0
Local $vVariableThatIsLocal = 0
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc
$vVariableThatIsStatic += 1 ; This will increase by 1
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)
EndFunc ;==>SomeFunc
</syntaxhighlight>

=== Enum ===
This statement is often practical in certain situations:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

Example()

Func Example()
; Create variables in Local scope and enumerate through the variables. Default is to start from 0
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4

; Create an array in Local scope with 4 elements
Local $aAnimalNames[4]

; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]

; Display the values of the array
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)

; Sometimes using this approach for accessing an element is more practical than using a numerical value, due to the fact changing the index value of
; the enum constant has no affect on it's position in the array. Therefore changing the location of $eCat in the array is as simple as changing the order
; it appears in the initial declaration e.g

; Local Enum $eDog, $eMouse, $eCat, $eHamster

; Now $eCat is the 2nd element in the array. If you were using numerical values, you would have to manually change all references of $aAnimalNames[0] to
; $aAnimalNames[2], as well as for the other elements which have now shifted
EndFunc ;==>Example
</syntaxhighlight>

== Au3Check directive ==
As you may know (and we hope), the Au3Check tool checks your code for syntax errors, variables used without being declared etc. which is a good thing to fix your script.

With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:
<syntaxhighlight lang="autoit">
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7
</syntaxhighlight>

== Magic Numbers ==
Magic numbers are arbitrary numbers interspersed throughout a program's source code which do not have an associated identifier. The downside to this is not being able to derive a meaning from the number.

For example:
<syntaxhighlight lang="autoit">
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")
</syntaxhighlight>
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.

The corrected example:
<syntaxhighlight lang="autoit">
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")
</syntaxhighlight>

Example 2:
<syntaxhighlight lang="autoit">
; Imagine you're a new user to AutoIt and you come across this code, where would you find -3, -4 or -5 in the help file?
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean
; why would you, the help file is there for a reason
Example()

Func Example()
Local $hGUI = GUICreate('')
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case -3 ; Doesn't really tell much about what it does
ExitLoop

Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?
MsgBox(4096, '', 'Do something when this action takes place.')

EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example
</syntaxhighlight>

Did you understand the numbers were these:
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

Example()

Func Example()
Local $hGUI = GUICreate('')
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action
ExitLoop

Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file

EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example
</syntaxhighlight>

[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]

== Include-once directive ==
This one is designed for standard includes and UDFs, it's highly recommended to use it.

Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions

Put the directive in top of your UDF (library) to avoid itself to be included more than once :
<syntaxhighlight lang="autoit">
#include-once
</syntaxhighlight>

Best coding practices

2016-07-20T19:46:44Z

BrewManNH: /* Names of Variables */

Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.

'''Note''': You must use AutoIt v3.3.10.0 or above to run the examples below.

__TOC__

== Using Functions ==
If a function sets the @error flag, you should always check it before using a return value - if @error indicates an error then the function return value is generally undefined.

Learn more about using Functions by reading "[https://www.autoitscript.com/autoit3/docs/function_notes.htm Function Notes]" from HelpFile.

== Names of Variables ==
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.

{| class="wikitable"
|-
! prefix !! covering type !! example
|-
| a || Arrays || $aArray[0]
|-
| b || Booleans || $bBool = True
|-
| d || Binaries || $dBinary = Binary("0x80000000")
|-
| e || Constant variable || Local Const $eEulersConstant = 2.7182818284590452
|-
| f || Floating point || $fFloat = 0.123
|-
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")
|-
| i || Integer || $iInteger = 10
|-
| id || An AutoIt controlID || $idButton_Ok = GUICtrlCreateButton("OK", 5, 5)
|-
| m || Maps || $mMap[]
|-
| n || General number (no preference) || $nNumber = 0
|-
| p || Pointers || $pRect = DllStructGetPtr($tRECT)
|-
| s || Strings (chars included) || $sString = "Hello world"
|-
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)
|-
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Day; endstruct"
|-
|v || Variant || $vData = ClipGet()
|}

Variables are named following this schema:
{| class="wikitable"
|-
! dollar prefix !! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| $ || a || h || Handles
|}

Examples:
<syntaxhighlight lang="autoit">
; Assign a local variable the integer 7
Local $iWeekDays = 7

; Assign a local variable the value of Pi
Local $fPi = 3.14159265358979

; Assign a local variable an array of strings
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']

; Assign a local variable an array of numbers
Local $anArray[4] = [0, 0.25, 3 / 4, 12]
</syntaxhighlight>
 

== Variable Initialization ==
When initializing variables there are several points to consider. It is bad practice to hog memory by assigning data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.

Examples:
<syntaxhighlight lang="autoit">
; Inconsistent data types are considered bad
Local $iInteger = "0"
Local $sString = False

; Correct initialization
Local $iInteger = 0
Local $sString = ''
</syntaxhighlight>
 

In the following table, recommended default values are shown for each data type. Some data types have more than one possibile default value which can be used for initialization.

{| class="wikitable"
|-
! Default Value !! covering type
|-
| Binary("") || $d
|-
| "" || $s, $v
|-
| 0 || $a, $h, $i, $id, $m, $n, $o, $p, $t, $tag, $v
|-
| 0.0 || $f
|-
| Null || $o, $s, $v
|-
| False (or True) || $b
|}

 
Example:
<syntaxhighlight lang="autoit">
; Declare and initialize a variable with the recommended default value
Local $vUndefined = Null ; This does not require much memory

; Some time later:
$vUndefined = 0xB0AD1CEA ; Assign an appropriate value as and when needed
</syntaxhighlight>
 

To reduce bloat, multiple variables can be declared on a single line. When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to follow and manage in a future, however the best layout will vary according to circumstance.

Example:
<syntaxhighlight lang="autoit">
; Not recommended
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types

; Recommended
Local $iLeft = 10, $iTop = 10 ; Integers
Local $idButton_Go = GUICtrlCreateButton("Go", $iLeft, $iTop) ; ControlIds
Local $idButton_Quit = GUICtrlCreateButton("Quit", 50, 10) ; ControlIds
</syntaxhighlight>
 

In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data type, variables declared without being initialized should be considered as being undefined.
 

== Scopes of Variables ==
Variables should also be named according to their scope.
{| class="wikitable"
|-
! Global UDF variable !! Global variable !! Local variable
|-
| $__g_iSomeVar || $g_iSomeVar || $iSomeVar
|}
With this method, you will avoid non wanted re-assignments.

Example:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Assign a Global variable the number 0
Global $iSomeVar1 = 0
; Assign a Global variable the number 5
Global $g_iSomeVar2 = 5

SomeFunc()

Func SomeFunc()
; Assign Local variables respectively the numbers 3 and 4
Local $iSomeVar1 = 3, $iSomeVar2 = 4

; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global"

; Display the value of $iSomeVar1
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)

; Display the value of $iSomeVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)

; Display the value of $g_iSomeVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $g_iSomeVar2: " & $g_iSomeVar2)
EndFunc
</syntaxhighlight>

* A variable declared globally (with the Global keyword) is visible anywhere in the script. Always declare your global variables in the global scope, not in the functions. It will prevent another function to use it before its declaration and the declaration is implicit (see [[#jumpsec1|examples]]).

* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.
:Declaration in the global scope: the variable is nonetheless visible everywhere; declare it as Local if this one is only used in the same scope
:Declaration in a function: the variable is visible by the function itself and nowhere else.

Structure of a code scope:
<syntaxhighlight lang="autoit">
; Global scope

; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function)
#include <MsgBoxConstants.au3>

; This scope is either Global or Local, depending on where do you use the variables

; Assign a Global variable the number 0 (which corresponds to an initialization of a variable number), its scope is Global because it's used at least in one function
Global $g_iVar1 = 0

; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope
Local $sVar2 = "foo"

; Display the content of $sVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $sVar2)

; Re-assign a Local variable the string returned by the function MyFunc
$sVar2 = MyFunc()

; Re-Display the content of $sVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $sVar2)

; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope)
Func MyFunc()
; Local scope

; Display the content of $g_iVar1
MsgBox($MB_SYSTEMMODAL, "", "Value of $g_iVar1: " & $g_iVar1)

; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope
Local $sVar3 = "bar"

; Display the content of $sVar3
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)

; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called
Return $sVar3
EndFunc ;==>MyFunc
</syntaxhighlight>

Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).

Example 1:
<syntaxhighlight lang="autoit">
; Include the Array UDF, it's needed here for the _ArrayDisplay function
#include <Array.au3>

; Assign a Local variable an array containing numbers with a size of 5
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0]
Local $aiArray[5] = [1, 2, 3, 4, 5]

; Display the contents
_ArrayDisplay($aiArray)

; Empty the array (and keep its size)
Dim $aiArray[5]

; Display the contents
_ArrayDisplay($aiArray)
</syntaxhighlight>
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.

Example 2:
<syntaxhighlight lang="autoit">
#include <Array.au3>

; Call MyFunc with default parameters ($vParam1 = 0)
MyFunc()

; Assign a Local variable an array containing integers
Local $aiArray[3] = [3, 4, 5]
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray)
MyFunc($aiArray)

Func MyFunc($vParam1 = 0)
; If $vParam1 is NOT an array then redeclare it to an array
If Not IsArray($vParam1) Then
Dim $vParam1[3] = [0, 1, 2]
EndIf

; Display the array
_ArrayDisplay($vParam1)
EndFunc ;==>MyFunc
</syntaxhighlight>

And for the ReDim keyword, limit its use to resize an array you want to keep its content:
<syntaxhighlight lang="autoit">
; Include the Array UDF, it's needed here for the _ArrayDisplay function
#include <Array.au3>

; Assign a Local variable an array containing numbers with a size of 5
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0]
Local $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents
_ArrayDisplay($aArray)

; Resize the array (and keep its content)
ReDim $aArray[3]

; Display the contents
_ArrayDisplay($aArray)
</syntaxhighlight>

Why using Dim over Local/Global is not always a good option:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

Dim $g_vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."

MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")

Example()

Func Example()
MsgBox($MB_SYSTEMMODAL, "", $g_vVariableThatIsGlobal) ; That looks alright to me as it displays the following text: This is a variable that has "Program Scope" aka Global

Local $vReturn = SomeFunc() ; Call some random function

MsgBox($MB_SYSTEMMODAL, $vReturn, $g_vVariableThatIsGlobal) ; The Global variable ($g_vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc"
EndFunc ;==>Example

Func SomeFunc()
; This should create a variable in Local scope if the variable name doesn"t already exist
; For argument sake I totally forgot that I declared a variable already with the same name
; Well I only want this to be changed in the function and not the variable at the top of the script
; Should be OK right? Think again
Dim $g_vVariableThatIsGlobal = ""

For $i = 1 To 10
$g_vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $g_vVariableThatIsGlobal
Next
Return $g_vVariableThatIsGlobal
EndFunc ;==>SomeFunc
</syntaxhighlight>

Declaring Global variables in a Function is never a good idea:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Calling Example() first will initialise the Global variable $g_vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error
; Now look at Example 2
Example()

Func Example()
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script
Global $g_vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $g_vVariableThatIsGlobal) ; As the variable was initialised this will not return an error
EndFunc ;==>SomeFunc
</syntaxhighlight>

Example 2:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Calling SomeFunc() first will bypass the Global variable $g_vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $g_vVariableThatIsGlobal contains
SomeFunc()

Func Example()
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script
Global $g_vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $g_vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."
EndFunc ;==>SomeFunc
</syntaxhighlight>

Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition
For $i = 1 To 10 ; $i is in 'loop scope.'
Local $iInt = $i
Next
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10
</syntaxhighlight>

<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

; Declaring variables outside of loops is more efficient in the long run
Local $iInt = 0
For $i = 1 To 10 ; $i is in 'loop scope.'
$iInt = $i
Next
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10
</syntaxhighlight>

There is no requirement to declare the iteration count variable in a loop:
<syntaxhighlight lang="autoit">
; Correct
Local Const $iCount = 99
Local $aArray[$iCount]
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it
$aArray[$i] = $i
Next

; Incorrect
Local Const $iCount = 99
Local $aArray[$iCount]
Local $i ; This is only used to store the iteration count value in the loop and therefore doesn't need to be declared. This is known as loop scope
For $i = 0 To UBound($iCount) - 1
$aArray[$i] = $i
Next
</syntaxhighlight>
As you can see, there is the Const keyword in the example, we are going to talk about it.

== Const, Static, Enum ==

=== Const ===
We won't talk about the advantages of a constant variable, they are neglibible (for your information, an AutoIt constant variable is marked as read-only and remains a variable as read-only when compiled).

The Const keyword may be used in a first by some of you to avoid re-assignments.
The best way to use them is not this last case, the constants should be used for real static variables, meaning that their value won't change regardless to the instance of the program.

Example:
<syntaxhighlight lang="autoit">
; Not recommended
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes

; Recommended
Local Const $iMyAge = 19
</syntaxhighlight>

=== Static ===
Static variables are the solution to the global variables used in only one function.
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.
<syntaxhighlight lang="autoit">
Example()

Func Example()
SomeFunc() ; This will display a message box of 1, 1
SomeFunc() ; This will display a message box of 1, 2
SomeFunc() ; This will display a message box of 1, 3
EndFunc ;==>Example

Func SomeFunc()
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be
; accessed from anywhere else in the script apart from the Function it was declared in
Local Static $vVariableThatIsStatic = 0
Local $vVariableThatIsLocal = 0
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc
$vVariableThatIsStatic += 1 ; This will increase by 1
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)
EndFunc ;==>SomeFunc
</syntaxhighlight>

=== Enum ===
This statement is often practical in certain situations:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>

Example()

Func Example()
; Create variables in Local scope and enumerate through the variables. Default is to start from 0
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4

; Create an array in Local scope with 4 elements
Local $aAnimalNames[4]

; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]

; Display the values of the array
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)

; Sometimes using this approach for accessing an element is more practical than using a numerical value, due to the fact changing the index value of
; the enum constant has no affect on it's position in the array. Therefore changing the location of $eCat in the array is as simple as changing the order
; it appears in the initial declaration e.g

; Local Enum $eDog, $eMouse, $eCat, $eHamster

; Now $eCat is the 2nd element in the array. If you were using numerical values, you would have to manually change all references of $aAnimalNames[0] to
; $aAnimalNames[2], as well as for the other elements which have now shifted
EndFunc ;==>Example
</syntaxhighlight>

== Au3Check directive ==
As you may know (and we hope), the Au3Check tool checks your code for syntax errors, variables used without being declared etc. which is a good thing to fix your script.

With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:
<syntaxhighlight lang="autoit">
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7
</syntaxhighlight>

== Magic Numbers ==
Magic numbers are arbitrary numbers interspersed throughout a program's source code which do not have an associated identifier. The downside to this is not being able to derive a meaning from the number.

For example:
<syntaxhighlight lang="autoit">
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")
</syntaxhighlight>
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.

The corrected example:
<syntaxhighlight lang="autoit">
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")
</syntaxhighlight>

Example 2:
<syntaxhighlight lang="autoit">
; Imagine you're a new user to AutoIt and you come across this code, where would you find -3, -4 or -5 in the help file?
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean
; why would you, the help file is there for a reason
Example()

Func Example()
Local $hGUI = GUICreate('')
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case -3 ; Doesn't really tell much about what it does
ExitLoop

Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?
MsgBox(4096, '', 'Do something when this action takes place.')

EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example
</syntaxhighlight>

Did you understand the numbers were these:
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

Example()

Func Example()
Local $hGUI = GUICreate('')
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action
ExitLoop

Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file

EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example
</syntaxhighlight>

[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]

== Include-once directive ==
This one is designed for standard includes and UDFs, it's highly recommended to use it.

Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions

Put the directive in top of your UDF (library) to avoid itself to be included more than once :
<syntaxhighlight lang="autoit">
#include-once
</syntaxhighlight>

Free Software

2014-10-27T20:33:51Z

BrewManNH: /* Passwords & Encryption */

'''Welcome To The Free Software Page ~ This page is a place to find useful free software recommended by the AutoIt community'''

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Archive '''</blockquote> =====
<blockquote>
* [http://www.7-zip.org/ 7 Zip] ~ Compression Utility ~ CyberSlug
* [http://legroom.net/software/uniextract Universal Extractor] ~ decompress and extract files from any type of archive or installer ~ wakillon

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Antivirus, Malware & Spyware Programs '''</blockquote> =====
<blockquote>
* [http://www.lavasoft.com/products/ad_aware_free.php Ad-Aware] ~ Antivirus Package ~ /dev/null
* [http://www.avast.com/index Avast] ~ Antivirus Package ~ killaz219
* [http://www.avira.com/en/avira-free-antivirus Avira] ~ Antivirus Package ~ MSLx Fanboy
* [http://free.avg.com/gb-en/homepage AVG Free] ~ Antivirus Package ~ LxP
* [http://antivirus.baidu.com/en/ Baidu Antivirus] ~ Antivirus ~ wakillon
* [http://www.trendmicro.co.uk/products/free-tools-and-services/ Hijack This] ~ Threat Removal Tool. Should only be used if you know what you are doing. ~ jefhal
* [http://www.microsoft.com/security/pc-security/mse.aspx Microsoft Security Essentials (WIN7 only)] ~ Malware/Spyware Tool ~ Valuater
* [http://www.safer-networking.org/en/index.html Spybot - Search & Destroy] ~ Spyware Removal ~ BigDod
* [http://www.javacoolsoftware.com/spywareblaster.html SpywareBlaster] ~ Spyware Tool ~ forger

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Audio '''</blockquote> =====
<blockquote>
* [http://audacity.sourceforge.net/ Audacity] ~ Audio Recording & Editing Tool ~ jefhal
* [http://mediaarea.net/en/MediaInfo MediaInfo] ~ Display technical and tag data for video and audio files ~ wakillon
* [http://mp3gain.sourceforge.net/ MP3Gain] ~ Normalize Music Files ~ maqleod
* [http://www.mp3tag.de/en/index.html Mp3tag] ~ Mp3 Metadata Editor ~ ning
* [http://www.synthfont.com/ SynthFont] ~ Midi Editing ~ LxP

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Browsers '''</blockquote> =====
<blockquote>
* [http://www.qksoft.com/favorites-management-master/ Bookmark Master] ~ IE Bookmark Manager ~ MHz
* [http://toolbarcleaner.com/ Toolbar Cleaner] ~ Remove unwanted toolbars, apps, add-ons, and plug-ins ~ wakillon
----
* [http://en.browser.baidu.com/ Baidu Spark Browser] ~ Web Browser ~ wakillon
* [http://chromium.woolyss.com/ Chromium] ~ Web Browser ~ wakillon
* [http://www.mozilla.org/en-US/firefox/fx/ Firefox] ~ Web Browser ~ LxP
* [http://www.srware.net/en/software_srware_iron.php Iron] ~ Web Browser ~ wakillon
* [http://www.maxthon.com/ Maxthon] ~ Web Browser ~ MHz
* [http://www.opera.com/ Opera] ~ Browser ~ photonbuddy
* [http://support.apple.com/kb/dl1531 Safari] ~ Web Browser ~ wakillon
* [http://www.slimbrowser.net/en/ Slim Browser] ~ Web Browser ~ jefhal
* [http://browser.yandex.com/ Yandex] ~ Web Browser ~ wakillon

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' CD & DVD Software '''</blockquote> =====
<blockquote>
* [http://www.daemon-tools.cc/eng/products/dtLite Daemon Tools Lite] ~ Virtual Disc Emulator ~ CyberSlug
* [http://www.deepburner.com/?r=products&pr=deepburner&prr=features DeepBurner ] ~ CD/DVD Burner ~ MSLx Fanboy
* [http://www.magiciso.com/tutorials/miso-magicdisc-mount.htm MagicDisc] ~ Virtual CD/DVD-ROM ~ wakillon

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Coding '''</blockquote> =====
<blockquote>
* [http://www.autoitscript.com/site/ AutoIt] ~ Scripting Language ~ layer
* [http://www.jrsoftware.org/isinfo.php Inno Setup] ~ Program Installer Setup ~ gcriaco
* [http://notepad-plus-plus.org/ Notepad++] ~ Source Code Editing ~ maqleod
* [http://www.pspad.com/en/ PSPad] ~ Universal Editor ~ LxP

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Commandline '''</blockquote> =====
<blockquote>
* [http://curl.haxx.se/ curl] ~ Commandline Https/Http/Ftp Client ~ /dev/null
* [http://www.ffmpeg.org/ FFmpeg] ~ Record, convert and stream audio and video ~ wakillon
* [http://www.poweradmin.com/paexec PAExec] ~ Launch Remote Windows Apps (PSEXEC '''Free''' alternative) ~ Pincopanco

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Document Management '''</blockquote> =====
<blockquote>
* [http://www.openoffice.org/ Apache OpenOffice] ~ Office Suite ~ MSLx Fanboy
* [http://www.libreoffice.org/ LibreOffice] ~ Office Suite ~ Chimaera
* [http://liquidninja.com/metapad/ Metapad] ~ Notepad alternative ~ LxP
* [http://www.vim.org/ Vim] ~ Text Editor ~ /dev/null

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Explorer Replacements '''</blockquote> =====
<blockquote>
* [http://explorerplusplus.com/ Explorer++] ~ File manager for Windows ~ wakillon
* [http://www.softwareok.com/?Freeware/Q-Dir Q-Dir] ~ File manager for Windows ~ wakillon
* [http://wde.codeplex.com/ Windows Double Explorer] ~ File manager for Windows ~ wakillon
</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' FTP / Web Servers & Remote '''</blockquote> =====
<blockquote>
* [http://www.jtsoft.com.pl/ A-Term] ~ Terminal emulator with API (COM / DLL) ~ mlipok
* [http://httpd.apache.org/ Apache] ~ Web Server ~ maqleod
* [http://filezilla-project.org/ Filezilla] ~ FTP Client & Server ~ MHz
* [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html putty] ~ SSP client ~ /dev/null
* [http://www.realvnc.com/ RealVNC] ~ Remote Control Software ~ ning
* [http://www.smartftp.com/ SmartFTP] ~ FTP client ~ LxP
* [http://www.teamviewer.com TeamViewer] ~ Remote Desktop Software (More features than RealVNC and its free!)
* [http://www.ayera.com/teraterm/ TeraTerm Pro Web] ~ Enhanced Telnet/SSH2 Client ~ /dev/null
* [http://winscp.net/eng/index.php WinSCP] ~ FTP over SSH ~ LxP

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Image Editing '''</blockquote> =====
<blockquote>
* [http://blog.bahraniapps.com/ GifCam] ~ Animated gif creation ~ wakillon
* [http://imageresizer.codeplex.com/ Image Resizer] ~ Image Manipulation ~ maqleod
* [http://inkscape.org/ Inkscape] ~ Vector Graphics Editor ~ Josbe
* [http://www.irfanview.com/ IrfanView] ~ Universal image editor ~ LxP
* [http://www.photofiltre-studio.com/pf7-en.htm PhotoFiltre] ~ Photo Editor ~ wakillon
* [http://picasa.google.co.uk/ Picasa] ~ Photo Editing Tool ~ jefhal
* [http://www.gimp.org/ The Gimp] ~ Image Editing ~ Blue_Drache
* [http://www.xnview.com/en/index.html XnView] ~ Multimedia Convertor ~ LxP

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Internet Messaging '''</blockquote> =====
<blockquote>
* [http://www.miranda-im.org/ Miranda] ~ Multi IM ~ Lazycat
* [http://www.pidgin.im/ Pidgin] ~ Formerly Gaim ~ LxP

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Mail '''</blockquote> =====
<blockquote>
* [http://www.poppeeper.com/ POP Peeper] ~ Email Client&Notifier ~ wakillon
* [http://www.mozilla.org/en-US/thunderbird/ Thunderbird] ~ Email software ~ LxP

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Maintenance '''</blockquote> =====
<blockquote>
* [http://security.baidu.co.th/en/ Baidu PC Faster] ~ Advanced Optimization & Security Software ~ wakillon
* [http://www.piriform.com/ccleaner CCleaner] ~ PC Cleanup Tool ~ Valuater
* [http://eraser.heidi.ie/ Eraser] ~ Stubborn File Removal ~ maqleod
* [http://www.free-codecs.com/download/K_Lite_Codec_Pack.htm K-Lite Codec Pack] ~ Codecs ~ maqleod
* [http://www.bleepingcomputer.com/files/killbox.php Pocket Killbox] ~ Stubborn File Removal Tool ~ jefhal
* [http://www.steffengerlach.de/freeware/ Scanner] ~ Hard disk usage monitor ~ LxP

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Media Players '''</blockquote> =====
<blockquote>
* [http://www.foobar2000.org/ foobar2000] ~ Advanced audio player~ LxP
* [http://www.jetaudio.com/download/ JetAudio Basic] ~ Media Player ~ wakillon
* [http://sourceforge.net/projects/guliverkli/ Media Player Classic] ~ Media player~ LxP
* [http://mpc-hc.sourceforge.net/ Media Player Classic ( Home Cinema Edition )] ~ HD Video player ~ Chimaera
* [http://www.videolan.org/vlc/ VLC ] ~ Media Player ~ MSLx Fanboy
* [http://www.winamp.com/ WinAmp] ~ Media player ~ killaz219

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Network & Internet '''</blockquote> =====
<blockquote>
* [http://keir.net/neutron.html Neutron] ~ Accurate time ~ LxP
* [http://www.uvnc.com/index.php UltraVNC] ~ Visual remote computing ~ LxP
* [http://www.poweradmin.com/paexec PAExec] ~ Launch Remote Windows Apps (PSEXEC '''Free''' alternative) ~ Pincopanco

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Passwords & Encryption '''</blockquote> =====
<blockquote>
* [http://www.essentialpim.com/?r=products&pr=essentialpim&prr=features EssentialPIM] ~ Personal Information Manager ~ Josbe
* [http://keepass.info/ Keepass] ~ Password Manager ~ /dev/null
* [http://passwordsafe.sourceforge.net/ Password Safe] ~ Password Management ~ maqleod
* [http://www.truecrypt.org/ TrueCrypt] ~ Encryption ~ photonbuddy
* [https://lastpass.com/ LastPass] ~ Password Management ~ BrewManNH

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' PDF '''</blockquote> =====
<blockquote>
* [http://get.adobe.com/reader/ Adobe Reader] ~ PDF Reader ~ LxP
* [http://www.cutepdf.com/Products/CutePDF/writer.asp Cute PDF] ~ Convert To PDF ~ CyberSlug
* [http://www.foxitsoftware.com/Secure_PDF_Reader/ Foxit Reader] ~ PDF Reader ~ ReFran
* [http://www.pdfforge.org/ PDF Creator] ~ PDF writer ~ LxP
* [http://www.acropdf.com/products.html PDF Speedup] ~ Speed up Adobe ~ LxP

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Privacy * '''</blockquote> =====
<blockquote>* '''Using some of the software in this section will prevent normal access to the AutoIt site as proxies are not allowed. Discussions on automating these types of products is not permitted.'''</blockquote>
<blockquote>
* [http://www.privoxy.org/ Privoxy] ~ To filter incoming web pages ~ LxP
* [https://www.torproject.org/index.html Tor] ~ Anonymity software ~ killaz219

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Resource Management '''</blockquote> =====
<blockquote>
* [http://www.angusj.com/resourcehacker/ Resource Hacker] ~ Extract exe resources ~ LxP
* [http://www.chmaas.handshake.de/delphi/freeware/xvi32/xvi32.htm#new XVI32] ~ Hex Editor ~ /dev/null
* [http://www.httrack.com/index.php HTTTrack] ~ Website Copier ~ gcriaco
* [http://www.cthing.com/Meazure.asp Meazure] ~ Window Info Tool ~ MHz
----
* [http://www.nliteos.com/index.html nLite] ~ Win XP Deployment Tool ~ beerman
* [http://www.vlite.net/ vLite] ~ Win Vista Deployment Tool ~ Chimaera
* [http://www.rt7lite.com/ RT 7 Lite] ~ Win 7 Deployment Tool ~ Chimaera
* [http://www.2kr2.rt7lite.com/ RT Server Customizer] ~ Win Server 2008 R2 Deployment Tool ~ Chimaera
</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Searches and Comparison '''</blockquote> =====
<blockquote>
* [http://www.mythicsoft.com/page.aspx?type=agentransack&page=home Agent Ransack] ~ File Finder With Regex ~ OldGuyWalking
* [http://tools.tortoisesvn.net/grepWin.html grepWin] ~ File Finder With Regex ~ mlipok
* [http://www.wingrep.com/index.htm WinGrep] ~ File Finder With Regex ~ mlipok
* [http://winmerge.org WinMerge] ~ File Finder With Regex ~ mlipok

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Startup Applications Management '''</blockquote> =====
<blockquote>
* [http://codestuff.obninsk.ru/products_starter.html Starter] ~ Manage Windows startup applications ~ wakillon
* [http://www.windowsstartup.com/ Startup Inspector] ~ Manage Windows startup applications ~ wakillon
* [http://download.cnet.com/StartupMonitor/3000-2084_4-10637539.html Startup Monitor] ~ Startup applications Monitoring ~ wakillon

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Task Scheduling '''</blockquote> =====
<blockquote>
* [http://www.codeproject.com/Articles/5371/ToDoList-6-4-6-An-effective-and-flexible-way-to-ke ToDoList] ~ Task Scheduler ~ Valik

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Video Editing '''</blockquote> =====
<blockquote>
* [http://www.erightsoft.com/SUPER.html SUPER] ~ Audio & Video Converter, Recorder ~ wakillon
* [http://www.virtualdub.org/ Virtualdub ] ~ Video Capture / Processing Utility ~ HardCopy

</blockquote>

===== <blockquote style="background-color:white; padding:1em; border:2px solid #8FBC8F">''' Learning '''</blockquote> =====
<blockquote>
* [http://www.greatis.com/utilities/justtype/ Just Type] ~ Just Type ~ mLipok

</blockquote>

Documentation

2014-10-27T20:24:14Z

BrewManNH: /* Online */

There is extensive AutoIt documentation available and this documentation is your recommended reference. Many developers keep the documentation or ''AutoIt Help File'', as it is better known, constantly open to look up functions and keywords.

= Using the help file =

[[File:Using-helpfile.png|300x226px|frame|Help file showing index]]
If you have AutoIt installed then you can find it in the SciTE editor if you press [F1], or in the start menu under AutoIt > AutoIt Help File.

There are three common methods of using the help file. You can use the Contents tab to browse the help file by category, which allows you to quickly find the resource you're after based on the type of script you're writing. Alternatively, you can use the Index tab to search for a resource page by title; this is practical if you know the name of the function you're after. Finally, by using the Search tab you can search all documents for a word or phrase. This is helpful when looking for words that may appear in multiple resource pages.

As another alternative, if you are not finding the resource you're after, you can use Google to search in the online documentation.

When in doubt, if you cannot find the answer to your problem, use the [[forums]].

= Offline =

An offline copy of the help file is available for download on the official AutoIt home page. You download the [[AutoIt Full Installation]] or the [[AutoIt Self Extracting Archive]] which both contain the AutoIt help file.

== Source ==

The source code for the help file is available to anyone so that they can expand, modify or translate the original. After editing, the help file source code can be submitted to the development team.

= Online =

There is also online documentation available if you do not have or want to download the offline version. This is less convenient to use for regular development since some features that the offline help file offers are not supported.

The online copy can be found here: [http://www.autoitscript.com/autoit3/docs/ Online documentation]

If you'd like to try AutoIt Online in your Webbrowser you can use [http://www.script-example.com/themen/AutoIT-Online-Compiler.php script-example.com free AutoIt Web Compiler]

== Searching ==

Similar to the forums, you can use Google or your search engine of choice as a valuable searching tool. You start your query with ''site:http://www.autoitscript.com/autoit3/docs/'' and then your search query.

A finished query may look like:
<syntaxhighlight lang="html4strict">
site:http://www.autoitscript.com/autoit3/docs/ GUICtrlCreateButton
</syntaxhighlight>

= Other languages =

The AutoIt help file is available in a few other languages beside English.

You can find these help files here:
[http://www.autoitscript.com/autoit3/docs.shtml Non-english documentation]

FAQ

2014-01-08T19:44:42Z

BrewManNH: clarified some text in regards to decompiling and obfuscation

This is a list of frequently asked questions asked on the forums.

Other FAQs include:
* The one found in the [http://www.autoitscript.com/autoit3/docs/faq.htm AutoIt HelpFile]. Much of it is about the transition from V2 to V3, but most is still relevant and should be a port of call, as well as this one.

==How can I debug my script?==

=== In SciTE ===
This one has a myriad of answers, but the most effective is to begin by using the [http://www.autoitscript.com/autoit3/scite/ SciTE4AutoIt3 Editor] to create or edit scripts. This program is useful in debugging for the following reasons:

* Syntax highlighting allows for immediate viewing of any mistakes from unended script tags or quotes. This allows the scripter to visibly see the difference between the following portions of code.
[[File:FAQ_Q1_2.jpg|center|Incorrect code]]
And the correct version:
[[File:FAQ_Q1_3.jpg|center||Correct Code]]
* Global syntax check built directly into the tools menu allows you to check an entire script for problems all at once.
* Built-in code tidying program that correctly indents untidy code and repairs messy scripts to allow them to be more readable. It also corrects problems with incorrectly capitalised function names and variables.
* Per-line trace insertion allows you to log every line of code executed to debug errors.
* Debug MsgBoxes or ConsoleWrites are able to be added anywhere in the script directly from SciTE. ConsoleWrite lines are less intrusive and prevent the added annoyance to the user of MsgBoxes.

[[File:FAQ_Q1_4.jpg|center|Picture of SciTE4AutoIt3]]

=== Using more code to check @error value ===
Nearly all functions will return something. Most of the time when a function fails, it returns 0 and sets @error. You can use this information not only to create scripts that handle for different errors but to debug and find out exactly why you are having problems. Check the help file for specific functions and their return values.

=== Via the Tray icon===
You can add this line at the top of your script (1 is on, 0 is off) to enable debugging from the tray icon.

<syntaxhighlight lang="autoit">AutoItSetOption ("TrayIconDebug", 1);0-off</syntaxhighlight>
Then if you run the script (uncompiled as an AU3 file), you can mouse over the AutoIt icon in the system tray (down by the clock) to display debugging information.

[[File:FAQ_Q1_1.jpg|center|Example output for TrayIconDebug]]

=== OutputDebugString native call ===
You can also debug a script on any computer by adding the following code to your script:

<syntaxhighlight lang="autoit">Func dbg($msg)
DllCall("kernel32.dll", "none", "OutputDebugString", "str", $msg)
EndFunc</syntaxhighlight>
Then, when you need to add a debug line, call it as necessary. Example:

<syntaxhighlight lang="autoit">dbg("The value of Variable 1 at this time is " & $var1)</syntaxhighlight>
This debugging is completely transparent to the user, and is only viewable with a program such as DebugView from SysInternals. This method of debugging has the added advantage of being available to the developer in situations where is not acceptable or feasable to install SciTE on a client's unit.

=== Graphical debugger ===
Stumpii created a [http://www.autoitscript.com/forum/index.php?showtopic=21834 Graphical AutoIt Debugger], similar to Dev-C++'s debugging style.

[[File:FAQ_Q1_5.jpg|center|Stumpii's Graphical AutoIt Debugger]]

==How can I run something that is not an exe file [.txt, .msi, .pdf,.jpg etc.] [or] How can I open a webpage in the default browser?==
It was for this reason that the ShellExecute function was created. Here is one example:

<syntaxhighlight lang="autoit">ShellExecute("C:\autoitscripts\test.au3", "", "", "edit", @SW_MAXIMIZE)</syntaxhighlight>

You can also specify a web address this way:

<syntaxhighlight lang="autoit">ShellExecute("http://www.autoitscript.com/forum", "", "", "open")</syntaxhighlight>

If you normally are able to right-click the file and select print, then you can also print the file from AutoIt using this function:

<syntaxhighlight lang="autoit">ShellExecute("C:\boot.ini", "", "", "print")</syntaxhighlight>

If you wish to open the file with the default program, you can do as follows (BETA ONLY):
<syntaxhighlight lang="autoit">ShellExecute("C:\autoitscripts\test.au3")</syntaxhighlight>

If you wish your script to wait until the process is finished, you can use the ShellExecuteWait function with the same parameters.

Note:
The default verb is the verb configured in the registry. If no verb is set as default in the registry then the "open" verb is used. If the "open" verb is not present then the first verb listed in the registry is used (except on Windows 2000).

==How can I prevent more than one copy of my script from running at once / detect another copy of my script running?==

=== _Singleton function ===
There are a few different ways to go about this. You can use a function called _Singleton to detect multiple instances of your script. An example of how to use this code:

<syntaxhighlight lang="autoit">#include <Misc.au3>
_Singleton("TheNameOfMyScript")</syntaxhighlight>

In this instance, the script will bring up some messages explaining to the user of the occurring events.
This example will show you how the above function can be used in a real world application.
<syntaxhighlight lang="autoit">#include <Misc.au3>
If _Singleton("MyScriptName", 1) = 0 Then
; If successful, running our script a second time should cause us to fall through here
MsgBox(16, "User Generated Error Message", "Error: This script is already running!")
Else
; We have detected that we are the only instance running, now we will run a second instance to display _Singleton's function!
MsgBox(64, "Information!", "We are the first instance of this script, press OK to run another instance and trigger the error message!")
Switch @Compiled
Case 1
Run(FileGetShortName(@ScriptFullPath));when running an app, it's usually better to use its short name
Case 0
Run(FileGetShortName(@AutoItExe) & ' /AutoIt3ExecuteScript ' & FileGetShortName(@ScriptFullPath))
EndSwitch
Sleep(1000)
MsgBox(64, "Information!", "We ran a second instance, you should have recieved an error message!", 5)
EndIf
Exit</syntaxhighlight>

===_MutexExists function ===
Another method is to use _MutexExists.

<syntaxhighlight lang="autoit">
If _MutexExists("MydeswswScriptName") Then
; We know the script is already running. Let the user know.
MsgBox(0, "Script Name", "This script is already running. Using multiple copies of this script at the same time is unsupported!")
Exit
EndIf

;Function Author- Martin
Func _MutexExists($sOccurenceName)
Local $ERROR_ALREADY_EXISTS = 183, $handle, $lastError
$sOccurenceName = StringReplace($sOccurenceName, "", ""); to avoid error
$handle = DllCall("kernel32.dll", "int", "CreateMutex", "int", 0, "long", 1, "str", $sOccurenceName)
$lastError = DllCall("kernel32.dll", "int", "GetLastError")
Return $lastError[0] = $ERROR_ALREADY_EXISTS
EndFunc;==>_MutexExists</syntaxhighlight>

==How can I run my script as a service?==
This is also a question with multiple answers, and none of them are the only way to do it. The first question to ask yourself is whether or not you wish to install the service on other computers besides your own.

=== On your own computer - One time only ===
The easiest way to do this is to use Pirmasoft RunAsSvc. This program makes services easy to install and easy to remove when necessary.

=== On all computers that run your script===
To do this you can use SRVANY.EXE and [http://www.autoitscript.com/forum/index.php?showtopic=6487 ServiceControl.au3]. You can then use this code to install your script as a service:

<syntaxhighlight lang="autoit">
#include "ServiceControl.au3"
$servicename = "MyServiceName"
_CreateService("", $servicename, "My AutoIt Script", "C:\Path_to_\srvany.exe", "LocalSystem", "", 0x110)
RegWrite("HKLM\SYSTEM\CurrentControlSet\Services\" & $servicename & "\Parameters", "Application", "REG_SZ", @ScriptFullPath)
</syntaxhighlight>

Or use the following code to delete this service:

<syntaxhighlight lang="autoit">
#include "ServiceControl.au3"
$servicename = "MyServiceName"
_DeleteService("", $servicename)
</syntaxhighlight>

There is one caveat to setting up AutoIt as a service. If the service is not installed using the above code, it must have the "allow service to interact with the desktop" setting or else automation functions such as Control* or Win* functions will not function. To assure the service does indeed have this setting, use the following code:

<syntaxhighlight lang="autoit">RegWrite("HKLM\SYSTEM\CurrentControlSet\Services\[ServiceName]", "Type", "REG_DWORD", 0x110)</syntaxhighlight>

==How can I create/start/stop or otherwise control a service?==
There are two include libraries that are designed specifically to interact with services. These are the following:

* [http://www.autoitscript.com/forum/index.php?showtopic=6487 ServiceControl.au3] made by SumTingWong. Functionality:
** _StartService()
** _StopService()
** _ServiceExists()
** _ServiceRunning()
** _CreateService()
** _DeleteService()
* [http://www.autoitscript.com/forum/index.php?showtopic=22165 _NTServices.au3] made by CatchFish. Functionality:
** _ServiceStart()
** _ServiceStop()
** _ServiceStatus()
** _ServicePause()

==How can I display a progress bar while copying files or directories?==
There are a many different topics on how to do this. For more, just search the forums for [http://www.autoitscript.com/forum/index.php?act=Search&CODE=show&searchid=22030d4d4effe5e32da23fdb69ed772f&search_in=posts&result_type=topics&highlite=%2BCopy%2B Progress Copy + Progress].
* [http://www.autoitscript.com/forum/index.php?showtopic=11313 Copy with progress dialog]... By ezztabi
* [http://www.autoitscript.com/forum/index.php?showtopic=11888 Yet another copy with progress]... By SumTingWong
* [http://www.autoit.de/index.php?page=Thread&postID=58875 _MultiFileCopy]... By Oscar (German Forums)
* [http://www.autoitscript.com/forum/index.php?showtopic=19370&st=45&p=186198&#entry186198 _FileCopy]... By Jos

[[File:FAQ_Q6_1.jpg|center|Copy progress dialog by ezztabi]]

==How can I make a hotkey that only works in my GUI?==
It used to be quite tedious setting hotkeys to only work in your GUI. Now there is an easier way with the function GUISetAccelerators.

(From Helpfile example)
<syntaxhighlight lang="autoit">
; A simple custom messagebox that uses the MessageLoop mode
#include <GUIConstantsEx.au3>

GUICreate("Custom Msgbox", 210, 80)

GUICtrlCreateLabel("Please click a button!", 10, 10)
$YesID = GUICtrlCreateButton("Yes", 10, 50, 50, 20)
$NoID = GUICtrlCreateButton("No", 80, 50, 50, 20)
$ExitID = GUICtrlCreateButton("Exit", 150, 50, 50, 20)

; Set accelerators for Ctrl+y and Ctrl+n
Dim $AccelKeys[2][2]=[["^y", $YesID], ["^n", $NoID]]
GUISetAccelerators($AccelKeys)

GUISetState(); display the GUI

Do
$msg = GUIGetMsg()

Select
Case $msg = $YesID
MsgBox(0, "You clicked on", "Yes")
Case $msg = $NoID
MsgBox(0, "You clicked on", "No")
Case $msg = $ExitID
MsgBox(0, "You clicked on", "Exit")
Case $msg = $GUI_EVENT_CLOSE
MsgBox(0, "You clicked on", "Close")
EndSelect
Until $msg = $GUI_EVENT_CLOSE Or $msg = $ExitID
</syntaxhighlight>

==How can I perform an action while a key is held down?==
You can use the _IsPressed() function to determine when a key is held down. The values that can be specified in this function are listed in the AutoIt Help File under User Defined Functions -> Misc Management -> _IsPressed. The following example will press the left mouse button while the k key is held down.

<syntaxhighlight lang="autoit">#include <Misc.au3>
$pressed = 0
While 1
If _IsPressed("4B") Then
If Not $pressed Then
ToolTip("K Key being held down")
MouseDown("left")
$pressed = 1
EndIf
Else
If $pressed Then
ToolTip("")
MouseUp("left")
$pressed = 0
EndIf
EndIf
Sleep(250)
WEnd</syntaxhighlight>

==How can I run my script on a remote computer over the network?==
The answer to this question depends on how much experience you have in networking. If the target system is a Windows 2000 or Windows XP Pro system to which you have administrator access then you may use one of the following programs:

* PsExec from SysInternals
* BeyondExec from BeyondLogic

With either of these programs it is possible to launch any process on a remote system and even copy your script to the target computer before starting it. Neither these programs nor any others will work with Windows XP Home Edition unless you create a custom "command listener" that you manually install on the target system.

NOTE: Those of you with more advanced programming skills and a little imagination can figure out how to use the service control libraries and srvany.exe to do this same thing without either of the above mentioned programs.

==How can I make a User Defined Function with optional parameters like the ones I see in the Help File?==
You can specify optional parameters by giving them a default value in the Func declaration. An example of how this is

done:
<syntaxhighlight lang="autoit">
Func testme($param1, $param2 = "nothing", $param3 = 5)
MsgBox(0, "", "Parameter one is required. The value of Parameter 1 is " & $param1 & @CRLF & _
"Parameter 2 is optional. The value of Parameter 2 is " & $param2 & @CRLF & _
"Parameter 3 is optional. The value of Parameter 3 is " & $param3)
EndFunc</syntaxhighlight>

If testme() is called with only one parameter [I.E. testme("test")] then the output is:
<blockquote>
Parameter one is required. The value of Parameter 1 is test 
Parameter 2 is optional. The value of Parameter 2 is nothing 
Parameter 3 is optional. The value of Parameter 3 is 5 
</blockquote>
However, if the function is called with more than one parameter like this testme("test", "something"), then the output is
<blockquote>
Parameter one is required. The value of Parameter 1 is test 
Parameter 2 is optional. The value of Parameter 2 is something 
Parameter 3 is optional. The value of Parameter 3 is 5 
</blockquote>

==How can I make my script start every time windows starts?==
You can use one of the following codes to allow your script to start with Windows:
<syntaxhighlight lang="autoit">RegWrite("HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Run", "MyProgramName", "REG_SZ", @ScriptFullPath)</syntaxhighlight>
or
<syntaxhighlight lang="autoit">FileCreateShortcut(@ScriptFullPath, @StartupCommonDir & "\MyProgramName.lnk")</syntaxhighlight>

==How can I have the script delete itself?==
The following function will delete the running script or .exe once it has finished execution.

'''WARNING: Make a copy of your script before calling this function!!!'''

<syntaxhighlight lang="autoit">
Func _SelfDelete($iDelay = 0)
Local $sCmdFile
FileDelete(@TempDir & "\scratch.bat")
$sCmdFile = 'ping -n ' & $iDelay & ' 127.0.0.1 > nul' & @CRLF _
& ':loop' & @CRLF _
& 'del "' & @ScriptFullPath & '"' & @CRLF _
& 'if exist "' & @ScriptFullPath & '" goto loop' & @CRLF _
& 'del %0'
FileWrite(@TempDir & "\scratch.bat", $sCmdFile)
Run(@TempDir & "\scratch.bat", @TempDir, @SW_HIDE)
EndFunc;==>_SelfDelete
</syntaxhighlight>

==How can I create a clickable website hyperlink in my gui?==
[[File:FAQ_Q13_1.jpg|center|Example GUI using Gary's UDF.]]

Gary Frost has made great advances in this area and has provided a [http://www.autoitscript.com/forum/index.php?showtopic=23111&st=0 UDF here] to help with doing this.

==How can I change the screen resolution / refresh rate / color depth?==
[http://www.autoitscript.com/forum/index.php?showtopic=20121 ChangeResolution.au3] is a library function created to make changes to these settings.

== How can I get the screen resolution in multiple monitor setups?==
The following code was worked out by Larry to determine the total screen resolution of multiple monitors:

<syntaxhighlight lang="autoit">
$aTSR = _GetTotalScreenResolution()
MsgBox(0, "Total Screen Resolution", "Width = " & $aTSR[0] & @CRLF & _
"Height = " & $aTSR[1])

;Original code by Larry.
;Edited by BrettF
Func _GetTotalScreenResolution()
Local $aRet[2]
Global Const $SM_VIRTUALWIDTH = 78
Global Const $SM_VIRTUALHEIGHT = 79
$VirtualDesktopWidth = DllCall("user32.dll", "int", "GetSystemMetrics", "int", $SM_VIRTUALWIDTH)
$aRet[0] = $VirtualDesktopWidth[0]
$VirtualDesktopHeight = DllCall("user32.dll", "int", "GetSystemMetrics", "int", $SM_VIRTUALHEIGHT)
$aRet[1] = $VirtualDesktopHeight[0]
Return $aRet
EndFunc
</syntaxhighlight>

== How can I register a file type with my program [or] How can I make files with a certain extension open in my program?==
[[File:FAQ_Q16_1.jpg|center|Example of how a file type can be registered.]]
File registration can be a tricky business for those who have not done it before. The first thing to be done is to modify your script to allow it to accept files from the command line. Here is one example of how to do this:

<syntaxhighlight lang="autoit">
;$cmdline[0] is the number of parameters passed
If $cmdline[0] <> 0 Then
$filename = $cmdline[1]
;Do something with the file here
MsgBox(0, "UXYFixer", 'The file name passed to the command line is "' & $filename & '"')
Else
; We did not get any command line parameters.
; If this is a command line only program, you would want to
; alert the user that the command line parameters were incorrect.
; If this is a GUI program (like a notepad program), you would
; want to simply continue from here without opening a file.
MsgBox(0, "UXYFixer", 'Command line parameters incorrect.' & @CRLF & 'Command line usage: "' & @ScriptName & '" "file to process"')
EndIf</syntaxhighlight>
After your script is ready to accept files, you can begin to register the file type you need with your program. To prevent errors, this-is-me has created a UDF that will allow you to do this easily:

Here is an example of how to register and unregister a file extension using this UDF:
<syntaxhighlight lang="autoit">#include "FileRegister.au3"
;================================================
;
; Description: FileRegister($ext, $cmd, $verb [, $def [, $icon = "" [, $desc = "" ]]])
; Registers a file type in Explorer
;
; Parameter(s): $ext - File Extension without period eg. "zip"
; $cmd - Program path with arguments eg. '"C:\test\testprog.exe" "%1"'
; (%1 is 1st argument, %2 is 2nd, etc.)
; $verb - Name of action to perform on file
; eg. "Open with ProgramName" or "Extract Files"
; $def - Action is the default action for this filetype
; (1 for true 0 for false)
; If the file is not already associated, this will be the default.
; $icon - Default icon for filetype including resource # if needed
; eg. "C:\test\testprog.exe,0" or "C:\test\filetype.ico"
; $desc - File Description eg. "Zip File" or "ProgramName Document"
;
;================================================

FileRegister("uxy", '"' & @ScriptFullPath & '" "%1"', "Open in UXYFixer", 1, @ScriptFullPath & ',0', "UXYFixer Document")

;========================================
;
; Description: FileUnRegister($ext, $verb)
; UnRegisters a verb for a file type in Explorer
; Parameter(s): $ext - File Extension without period eg. "zip"
; $verb - Name of file action to remove
; eg. "Open with ProgramName" or "Extract Files"
;
;========================================

FileUnRegister("uxy", "Open in UXYFixer")</syntaxhighlight>

'''Download here:'''
[http://www.autoitscript.com/forum/index.php?app=core&module=attach&section=attach&attach_id=26378 FileRegister.au3]

==Why doesn't my combobox (GUICtrlCreateCombo) show a dropdown list when clicked?==
When using GUICtrlCreateCombo be sure to enter the desired height for your combobox list in the "height" parameter. Windows XP automatically selects an appropriate height for combo boxes, but other versions of Windows usually do not.
<syntaxhighlight lang="autoit">$combo = GUICtrlCreateCombo("",10,10,200,20)</syntaxhighlight>
Would correctly be changed to:
<syntaxhighlight lang="autoit">$combo = GUICtrlCreateCombo("",10,10,200,200)</syntaxhighlight>

==Why isn't my thread getting any replies?==

=== Asking the right question right ===
Did you give a good description of the problem? If your title or explanation of the issue is not descriptive, users are likely to bypass your issue instead of helping. Post titles such as "Help Me", "I Have A Problem", "Question", "Help me fix my code", "This code doesn't work" or similarly worded titles will not readily draw forum users to your post. Experienced users (which are your best hope of resolving the issue) will often skip your post altogether in cases like this. An example of a post title descriptive enough to attract users to assist you is "Problem with WinWaitClose" or "Loop never ends".

=== Example for reproduction ===
Did you post example code? If you have not posted an example of the code you are having an issue with, then you will not recieve support. When posting a non-working script, please do so in the smallest amount of stand-alone code possible. If the code you post cannot run by itself on another person's computer, they will not be able to recreate the issue.

=== Speak English and speak it right ===
Did you use proper English? Here are guidelines for posting properly in the english language:
* Use proper case. THIS IS CONSIDERED YELLING. If you post in ALL UPPERCASE or all lowercase then you will look like a doofus.
* Use proper punctuation. Complete sentences need only one trailing punctuation mark -- not three!!! Writing a sentance without simple punctuation such as commas or other punctuation is considered lazy, which is considered a good judge of the poster's coding style. If you cannot summon the strength to write a sentence with correct punctuation, you will most likely miss simple coding mistakes such as unterminated quotes.

=== Breaking forum rules, law, modesty, or common Sense ===
Make sure you are not giving the impression of breaking forum rules, http://www.autoitscript.com/forum/forum-2/announcement-15-forum-rules-7-nov-2012/. Make sure you are not doing anything that can be perceived as breaking the law.

==Why does the Ctrl key get stuck down after I run my script?==

=== Keys virtually stuck ===
It could equally be the Shift Or the Alt key.

If you use Send In a script And you have a problem With keys being stuck down Then Send is the most likely culprit. A similar problem can occur With BlockInput. The solution is generally quite simple. If there is a key like Shift Or Alt held down at the start of the Send sequence, but that key is released by the time the Send sequence finishes Then the key will get 'stuck' down. As an example of a solution, you could replace the Send function in your script with the _SendEx function below.

The _SendEx function waits for the Shift, Alt And Ctrl keys to be released or pops up a warning if the $warn parameter is not an empty string. Therefore it is not intended to be used when one of these modifier keys has been set to be down using any combination of {ALTDOWN}, {SHIFTDOWN} and {ALTDOWN}.
<syntaxhighlight lang="autoit">
#include < Misc.au3 >
;Send the string $ss after the Shift Alt and Ctrl keys are released. Optionally give a warning after 1 sec if any of those keys are still down.
;Requires misc.au3 to be included in the script for the _IsPressed function.
Func _SendEx($ss, $warn = "")
Local $iT = TimerInit()

While _IsPressed("10") Or _IsPressed("11") Or _IsPressed("12")
If $warn <> "" And TimerDiff($iT) > 1000 Then
MsgBox(262144, "Warning", $warn)
EndIf
Sleep(50)
WEnd
Send($ss)
EndFunc;==>_SendEx</syntaxhighlight>

=== General unstuck method ===
Shilbiz also discovered that the following can 'clear' locked down keys.
<syntaxhighlight lang="autoit"> ControlSend("", "", "", "text", 0)</syntaxhighlight>

==How can I use Pixel functions?==

=== Using a color change as an event ===
The following is an example of using the pixel to check if the colour has changed in a specific region.
<syntaxhighlight lang="autoit">
Local $PixelCheck = 0, $NewCheck
$PixelCheck = PixelCheckSum(40, 50, 60, 70); Get the checksum for this area.
While 1; Keep going
$NewCheck = PixelCheckSum(40, 50, 60, 70)
If $PixelCheck <> $NewCheck Then
; The old pixel checksum and the new one are different.
$PixelCheck = $NewCheck; Update the $PixelCheck to the new value
; Let us know it has changed. Change this to what you want to happen when the colour in the region changes.
Msgbox(48,"PixelChecksum","Pixel region has changed !")
EndIf
Sleep(50); Just to give the CPU a bit of a break.
Wend</syntaxhighlight>

=== Searching for a specific pixel color ===
This is an example of searching for a specific pixel (red), both pure red (0xFF0000) and red in a few different shades.
<syntaxhighlight lang="autoit">; Find a pure red pixel in the range 0,0-20,300
$coord = PixelSearch( 0, 0, 20, 300, 0xFF0000 )
If Not @error Then
MsgBox(0, "X and Y are:", $coord[0] & "," & $coord[1])
EndIf

; Find a pure red pixel or a red pixel within 10 shades variations of pure red
$coord = PixelSearch( 0, 0, 20, 300, 0xFF0000, 10 )
If Not @error Then
MsgBox(0, "X and Y are:", $coord[0] & "," & $coord[1])
EndIf</syntaxhighlight>

==Why doesn't my script work on a locked workstation?==
On a locked station any window will never be active (active is only dialog with text "Press Ctrl+Alt+Del"). In Windows locked state applications run hidden (behind that visible dialog) and do not have focus and active status. So generally don't use Send() MouseClick() WinActivate() WinWaitActive() WinActive() etc. Instead use ControlSend() ControlSetText() ControlClick() WinWait() WinExists() WinMenuSelectItem() etc. This way you may have your script resistive against another active windows. It's possible to run such a script from scheduler on locked Windows stations.

==Where can I learn AutoIt? Are there any tutorials?==
To learn AutoIt you have two main options available to you:

AutoIt 1-2-3, an interactive classroom by Valuater. You may find it here:
[http://www.autoitscript.com/forum/index.php?showtopic=21048 http://www.autoitscript.com/forum/index.php?showtopic=21048]

There is also updated LxP's AutoIt tutorial by BrettF. You can find it here:
[http://www.autoitscript.com/forum/index.php?showtopic=84960 http://www.autoitscript.com/forum/index.php?showtopic=84960]

There is also a book; AutoIt v3: Your Quick Guide by Andy Flessner.
You can buy the book from here:
[http://oreilly.com/catalog/9780596515126/ http://oreilly.com/catalog/9780596515126/]

On YouTube there are many videos available:
[http://www.youtube.com/results?search_query=autoit+tutorial&search_type=&aq=0&oq=AutoIt http://www.youtube.com/results?search_query=autoit+tutorial&search_type=&aq=0&oq=AutoIt]

==Why does my script no longer decompile?==
Decompilation is no longer supported, and is only available for the older versions of AutoIt (Version 3.2.5.1 and earlier compiled scripts).

Please '''do not''' post on this topic, but search the forums for more information. Posting topics like this will usually get the topic locked.

Also posting the source (if a hacked decompiler was used) of other compiled scripts, or otherwise mentioning these hacked decompilers will probably get you banned. It is also in violation of the AutoIt EULA (End-User-License-Agreement).

<blockquote>You may not reverse engineer or disassemble the SOFTWARE PRODUCT or compiled scripts that were created with the SOFTWARE PRODUCT.</blockquote>

Please see the [[Decompiling FAQ]] for more information.

==How can I get a window handle when all I have is a PID?==
Refer to the following example showing converting and use when manipulating the window. The function is based on work by Smoke_N/Hubertus and Helge.
<syntaxhighlight lang="autoit">;Run process
$iPID = Run("Notepad.exe")

;Allow window to initialize...
Sleep (500)

;Get HWND.
$hWnd = _GetHwndFromPID($iPID)

;Maximize
WinSetState($hWnd, "", @SW_MAXIMIZE)

;Wait 2 seconds
Sleep(2000)

;Minimize
WinSetState($hWnd, "", @SW_MINIMIZE)

;Wait 2 seconds
Sleep(2000)

;Restore window
WinSetState($hWnd, "", @SW_RESTORE)

;Wait 2 seconds
Sleep(2000)

;Move top left corner of screen, and resize to 800x600
WinMove($hWnd, "", 0, 0, 800, 600)

;Wait 2 seconds
Sleep(2000)

;Calculate Center of screen.
$x = (@DesktopWidth / 2) - 400; Desktop width divided by 2, then minus half the width of the window
$y = (@DesktopHeight / 2) - 300; Desktop height divided by 2, then minus half the height of the window

;Move to center of screen
WinMove($hWnd, "", $x, $y)

;Wait 2 seconds
Sleep(2000)

;Close notepad
WinClose($hWnd)

;Function for getting HWND from PID
Func _GetHwndFromPID($PID)
$hWnd = 0
$winlist = WinList()
Do
For $i = 1 To $winlist[0][0]
If $winlist[$i][0] <> "" Then
$iPID2 = WinGetProcess($winlist[$i][1])
If $iPID2 = $PID Then
$hWnd = $winlist[$i][1]
ExitLoop
EndIf
EndIf
Next
Until $hWnd <> 0
Return $hWnd
EndFunc;==>_GetHwndFromPID</syntaxhighlight>

==How can I use single or double quotes in strings?==
It is a fairly simple concept once you get the basics down. Basically there are a few different ways to go about mixing quotes in strings.

A string in AutoIt can be encased in either single(') or double (") quotes. So if you want to add only one type of quote into your string, your first port of call is to use the other type of quote to encase the string. Like so:

<syntaxhighlight lang="autoit">$var = "I am a 'quote' inside the string"
MsgBox (0, "Test 1", $var)
$var = 'I wish I could be a "quote" inside the string!'
MsgBox (0, "Test 1", $var)</syntaxhighlight>

If you have to have both types of quotes in the string, the easiest way is to escape the quote ending the string as so to speak. To do this, use two quotes instead of one. Like so:

<syntaxhighlight lang="autoit">$var = 'I am a single ''quote'' inside the string made using "single quote!"'
MsgBox (0, "Test 1", $var)</syntaxhighlight>

==When should I bump my threads?==
As a courtesy to other users you should only bump your post once in a 24 hour period. Doing this allows all users the chance to get helped equally. Also refer to [http://www.autoitscript.com/forum/index.php?showtopic=95704&view=findpost&p=688050 Why isn't my thread getting any replies?], as this will help you get replies.

==How can I protect my code from decompilation?==
The fact of the matter is '''you can't fully protect your code'''. AutoIt is an interpreted language, so all scripts are interpreted, and that script has to get stored somewhere. There is still hope though. You can take certain measures to make the decompiled code less usable to the person that decompiled it. The first step is to obfuscate your code. This causes the code to become less readable. Basically variables and functions are renamed, making it very hard to make head or tail of what is what.

Please see the [[Decompiling FAQ]] for more information.

==How can I decompile my AutoIt EXEs?==
You cannot decompile your AutoIt compiled scripts unless it was compiled with AutoIt 3.2.5.1 or earlier.

If you wish to simulate decompilation for your script, you can do this using the following simple example:

<syntaxhighlight lang="autoit">;Original Author SmokeN
If $CMDLINE[0] Then
If $CMDLINE[1] == "/SOURCE" AND $CMDLINE[2] == "MYPASSWORD" Then
FileInstall("ThisSCript.au3", @ScriptDir & "\DecompiledScript.au3")
EndIf
EndIf</syntaxhighlight>

Then if you run the exe with the following command line parameters your source will be installed.

<blockquote>myscript.exe /SOURCE MYPASSWORD</blockquote>

== What is proper forum etiquette? What rules are there for the forum?==
Proper forum etiquette will ensure you will stay a member of these forums. So try to follow these rules. Also see this [http://www.autoitscript.com/forum/index.php?showtopic=95704&st=15&p=688050&#entry688050 FAQ post], as you should follow what is outlined there as well.

* Use proper English. MSN speak and the like makes it very hard to understand what you want. Keep posts in proper case because UPPERCASE is considered yelling and lowercase makes you look stupid. Don't use more punctuation marks than necessary. For example ?!!!? and ????? is completely unnecessary.
* Before posting help with a script, make sure you follow these steps:
*# Search for your issue.
*#* There are many thousands of posts on this forum, and chances are your question has been asked before. Make sure to use a variety of terms to maximize your results.
*# Read the helpfile
*#* Most if not all things in the help file will have an example (native functions) or two. Give them a go to try see how the functions work. Most of the time it helps!
*# Give it a go
*#* Seriously, if you can't be bothered to give it a go, then why should we be bothered to help you? If you feel you can't do it and you don't try then how will you ever know? We always prefer that you give it a go because you can learn from your mistakes and hopefully understand it better.
*# Post your problem
*#* Make sure you post in the correct forum.
*#** AutoIt Specific
*#*** General Help and Support (Most support questions)
*#*** GUI Support (Support for the Graphical User Interface)
*#** Non-AutoIT
*#*** Chat
*#*** Developer Chat (Usually for C++ questions.)
*#* Include a detailed description in the content of the post, and a detailed title
*#** Titles such as 'Help' and 'What's wrong?' are not acceptable. To get the most help with your problem, be as descriptive as you can in the title, but keep in mind your title cannot be too long.
*#** Make sure you also include a descriptive question. Just saying 'what is wrong with the following' is also not acceptable, as we will have no idea what the problem is. Describe what you think is wrong and what is not working. It makes our job easier.
*#* Always include your code
*#** It shows us that you have tried and gives us a head start with something to play with.
* Usually asking for a script is not taken too well, within reason. Keep in mind that this is a support forum, so please acknowledge that. Most of us would rather that you learn rather than just having a script written for you. If you do need something written for you, maybe try [http://www.rentacoder.com/ RentACoder], as they are more suited to requests.
* Don't PM other members asking for them to look at threads of to help you unless they request it. It is actually quite rude and annoying to receive PMs of that nature.
* Lurk a little before you dive right in. Read a number of posts, or check out the group's archives. Get a feel for the tone of the forum so you can participate accordingly.
* Say online exactly what you would say in person. In other words, if you wouldn't say it to the person's face in front of your Grandmother, you shouldn't type it here.
* Remember your face doesn't show. Words alone can convey sentiment, but without benefit of inflection or facial expression, they can be misconstrued. Use descriptive wording, emoticons or .gifs to ensure your meaning is clear. By the same token, don't jump to conclusions about another person's intent in posting an unclear comment. When in doubt, ask for clarification.
* Be respectful. Internet etiquette is similar to standard etiquette in this area. Appreciate that your opinion is one of many. You can disagree with another person without being disrespectful or rude to other people.
* Ignore Trolls. If you engage in conversation with one, you'll raise your blood pressure and empower the troll. You can't win a flame war, and you can't sway a troll's opinion. Often, they don't even care about the subject. They live for the conflict and nothing more. Trolls are common and not worthy of your time. Ignore their posts no matter how inflammatory and eventually they'll get bored and move on.
* When you have found an answer for your question:
*# Do not edit your post to be blank or to have worthless information. People may be searching for the same issue you have, so be courteous to them by leaving your question there.
*# It is also optional to add the likes of [SOLVED] into the title, and redirecting people to the answer that helped you. It can make the lives of people searching easier.
* Finally follow the rules:
** [http://www.autoitscript.com/forum/forum-6/announcement-13-forum-rules/ Forum rules]
** [http://www.autoitscript.com/forum/index.php?showtopic=54168 Rules for the Chat forum]
** [http://www.autoitscript.com/forum/index.php?showtopic=65889 Rules for asking for source code]
** [http://www.autoitscript.com/forum/index.php?showtopic=37739 General policies and forum settings]

Some general points taken from [http://www.ehow.com/how_2106033_use-proper-forum-etiquette.html here].

==Are there forums available in my local language?==
Yes there are some available. Some forum members here participate in multiple forums.
* [http://www.autoit.de/ German Forums]
* [http://www.autoit.fr/ French Forums]
* [http://www.autoit.es/ Spanish Forums]
* [http://autoit-script.ru/ Russian Forums]

Please note that these are independent, community-run message boards and not just a translation of this board.

Forums

2013-05-24T16:05:05Z

BrewManNH: /* Yahoo group */ edited the information as the page is closed.

In order to receive support and share your own scripts you may sign up for one of either forums.

= Official forums =
The official forums are a very good place to get help and share scripts. It has a lot of members and is often praised for its quick and professional help and support. One of the advantages of AutoIt over other, more global, languages - is the concentrated community. There you are posting alongside the developers of the code, so chances are they know what they're talking about!

[http://www.autoitscript.com/forum/index.php AutoIt Forums]

== Searching the forums ==
Before you post a question it is always better to search the forums first to see if your question has been answered before.
There are two ways to search the forum:

* '''Internal search engine'''
[http://www.autoitscript.com/forum/index.php?act=Search Search]
* '''Google'''
Enter into Google: site:www.autoitscript.com/forum/ your search query.

Google search cannot be used to search the Chat forum.

Example: [http://www.google.com/search?hl=en&q=site:www.autoitscript.com/forum/+script Search for "script" on the forums using Google.]

See also: [[Searching_autoitscript_forum | Searching the Forum]]

== Code of conduct ==
Before you post a question or start a new script, it is always better to search the forums first if your question has been answered before or see if you can find a similar script made by someone else and shared.

Please think about asking '''the right question''' and asking '''the question right!'''

These are must read topics before posting anything:
* [http://www.autoitscript.com/forum/index.php?showtopic=54168 Chat forum rules]
* [http://www.autoitscript.com/forum/index.php?showtopic=14632 Keylogger rules]
* [http://www.autoitscript.com/forum/index.php?showtopic=65889 Asking for source code]
* [http://www.autoitscript.com/forum/index.php?showtopic=37289 FAQ1] [http://www.autoitscript.com/forum/index.php?showtopic=23822 FAQ2]
* [http://www.autoitscript.com/forum/index.php?showtopic=34658 Are my AutoIt EXEs really infected?]

= Unofficial forums =
These are the other unofficial forums, often in other languages than English.

* French forums: http://www.autoit.fr/
* German forums: http://www.autoit.de/
* Polish forums: http://www.autoit.xaa.pl/
* Portuguese forums: http://www.autoitbrasil.com/
* Spanish forums: http://www.autoit.es/

= Yahoo group =
<strike>As an alternative to the official forums, or if you just like Yahoo groups more, you can use the available Yahoo group to ask questions and share scripts.</strike>

The Yahoo group page has been closed to new messages.

[http://groups.yahoo.com/group/AutoItList/ AutoIt Yahoo group]

= Useful links =
* [http://www.autoitscript.com/forum/index.php?showtopic=94713 General Tips for using AutoIt] - Some tips that a lot of people will find useful.

FAQ

2013-05-22T19:43:07Z

BrewManNH: /* Using a color change as an event */ fixed typo

This is a list of frequently asked questions asked on the forums.

Other FAQs include:
* The one found in the [http://www.autoitscript.com/autoit3/docs/faq.htm AutoIt HelpFile]. Much of it is about the transition from V2 to V3, but most is still relevant and should be a port of call, as well as this one.

==How can I debug my script?==

=== In SciTE ===
This one has a myriad of answers, but the most effective is to begin by using the [http://www.autoitscript.com/autoit3/scite/ SciTE4AutoIt3 Editor] to create or edit scripts. This program is useful in debugging for the following reasons:

* Syntax highlighting allows for immediate viewing of any mistakes from unended script tags or quotes. This allows the scripter to visibly see the difference between the following portions of code.
[[File:FAQ_Q1_2.jpg|center|Incorrect code]]
And the correct version:
[[File:FAQ_Q1_3.jpg|center||Correct Code]]
* Global syntax check built directly into the tools menu allows you to check an entire script for problems all at once.
* Built-in code tidying program that correctly indents untidy code and repairs messy scripts to allow them to be more readable. It also corrects problems with incorrectly capitalised function names and variables.
* Per-line trace insertion allows you to log every line of code executed to debug errors.
* Debug MsgBoxes or ConsoleWrites are able to be added anywhere in the script directly from SciTE. ConsoleWrite lines are less intrusive and prevent the added annoyance to the user of MsgBoxes.

[[File:FAQ_Q1_4.jpg|center|Picture of SciTE4AutoIt3]]

=== Using more code to check @error value ===
Nearly all functions will return something. Most of the time when a function fails, it returns 0 and sets @error. You can use this information not only to create scripts that handle for different errors but to debug and find out exactly why you are having problems. Check the help file for specific functions and their return values.

=== Via the Tray icon===
You can add this line at the top of your script (1 is on, 0 is off) to enable debugging from the tray icon.

<syntaxhighlight lang="autoit">AutoItSetOption ("TrayIconDebug", 1);0-off</syntaxhighlight>
Then if you run the script (uncompiled as an AU3 file), you can mouse over the AutoIt icon in the system tray (down by the clock) to display debugging information.

[[File:FAQ_Q1_1.jpg|center|Example output for TrayIconDebug]]

=== OutputDebugString native call ===
You can also debug a script on any computer by adding the following code to your script:

<syntaxhighlight lang="autoit">Func dbg($msg)
DllCall("kernel32.dll", "none", "OutputDebugString", "str", $msg)
EndFunc</syntaxhighlight>
Then, when you need to add a debug line, call it as necessary. Example:

<syntaxhighlight lang="autoit">dbg("The value of Variable 1 at this time is " & $var1)</syntaxhighlight>
This debugging is completely transparent to the user, and is only viewable with a program such as DebugView from SysInternals. This method of debugging has the added advantage of being available to the developer in situations where is not acceptable or feasable to install SciTE on a client's unit.

=== Graphical debugger ===
Stumpii created a [http://www.autoitscript.com/forum/index.php?showtopic=21834 Graphical AutoIt Debugger], similar to Dev-C++'s debugging style.

[[File:FAQ_Q1_5.jpg|center|Stumpii's Graphical AutoIt Debugger]]

==How can I run something that is not an exe file [.txt, .msi, .pdf,.jpg etc.] [or] How can I open a webpage in the default browser?==
It was for this reason that the ShellExecute function was created. Here is one example:

<syntaxhighlight lang="autoit">ShellExecute("C:\autoitscripts\test.au3", "", "", "edit", @SW_MAXIMIZE)</syntaxhighlight>

You can also specify a web address this way:

<syntaxhighlight lang="autoit">ShellExecute("http://www.autoitscript.com/forum", "", "", "open")</syntaxhighlight>

If you normally are able to right-click the file and select print, then you can also print the file from AutoIt using this function:

<syntaxhighlight lang="autoit">ShellExecute("C:\boot.ini", "", "", "print")</syntaxhighlight>

If you wish to open the file with the default program, you can do as follows (BETA ONLY):
<syntaxhighlight lang="autoit">ShellExecute("C:\autoitscripts\test.au3")</syntaxhighlight>

If you wish your script to wait until the process is finished, you can use the ShellExecuteWait function with the same parameters.

Note:
The default verb is the verb configured in the registry. If no verb is set as default in the registry then the "open" verb is used. If the "open" verb is not present then the first verb listed in the registry is used (except on Windows 2000).

==How can I prevent more than one copy of my script from running at once / detect another copy of my script running?==

=== _Singleton function ===
There are a few different ways to go about this. You can use a function called _Singleton to detect multiple instances of your script. An example of how to use this code:

<syntaxhighlight lang="autoit">#include <Misc.au3>
_Singleton("TheNameOfMyScript")</syntaxhighlight>

In this instance, the script will bring up some messages explaining to the user of the occurring events.
This example will show you how the above function can be used in a real world application.
<syntaxhighlight lang="autoit">#include <Misc.au3>
If _Singleton("MyScriptName", 1) = 0 Then
; If successful, running our script a second time should cause us to fall through here
MsgBox(16, "User Generated Error Message", "Error: This script is already running!")
Else
; We have detected that we are the only instance running, now we will run a second instance to display _Singleton's function!
MsgBox(64, "Information!", "We are the first instance of this script, press OK to run another instance and trigger the error message!")
Switch @Compiled
Case 1
Run(FileGetShortName(@ScriptFullPath));when running an app, it's usually better to use its short name
Case 0
Run(FileGetShortName(@AutoItExe) & ' /AutoIt3ExecuteScript ' & FileGetShortName(@ScriptFullPath))
EndSwitch
Sleep(1000)
MsgBox(64, "Information!", "We ran a second instance, you should have recieved an error message!", 5)
EndIf
Exit</syntaxhighlight>

===_MutexExists function ===
Another method is to use _MutexExists.

<syntaxhighlight lang="autoit">
If _MutexExists("MydeswswScriptName") Then
; We know the script is already running. Let the user know.
MsgBox(0, "Script Name", "This script is already running. Using multiple copies of this script at the same time is unsupported!")
Exit
EndIf

;Function Author- Martin
Func _MutexExists($sOccurenceName)
Local $ERROR_ALREADY_EXISTS = 183, $handle, $lastError
$sOccurenceName = StringReplace($sOccurenceName, "", ""); to avoid error
$handle = DllCall("kernel32.dll", "int", "CreateMutex", "int", 0, "long", 1, "str", $sOccurenceName)
$lastError = DllCall("kernel32.dll", "int", "GetLastError")
Return $lastError[0] = $ERROR_ALREADY_EXISTS
EndFunc;==>_MutexExists</syntaxhighlight>

==How can I run my script as a service?==
This is also a question with multiple answers, and none of them are the only way to do it. The first question to ask yourself is whether or not you wish to install the service on other computers besides your own.

=== On your own computer - One time only ===
The easiest way to do this is to use Pirmasoft RunAsSvc. This program makes services easy to install and easy to remove when necessary.

=== On all computers that run your script===
To do this you can use SRVANY.EXE and [http://www.autoitscript.com/forum/index.php?showtopic=6487 ServiceControl.au3]. You can then use this code to install your script as a service:

<syntaxhighlight lang="autoit">
#include "ServiceControl.au3"
$servicename = "MyServiceName"
_CreateService("", $servicename, "My AutoIt Script", "C:\Path_to_\srvany.exe", "LocalSystem", "", 0x110)
RegWrite("HKLM\SYSTEM\CurrentControlSet\Services\" & $servicename & "\Parameters", "Application", "REG_SZ", @ScriptFullPath)
</syntaxhighlight>

Or use the following code to delete this service:

<syntaxhighlight lang="autoit">
#include "ServiceControl.au3"
$servicename = "MyServiceName"
_DeleteService("", $servicename)
</syntaxhighlight>

There is one caveat to setting up AutoIt as a service. If the service is not installed using the above code, it must have the "allow service to interact with the desktop" setting or else automation functions such as Control* or Win* functions will not function. To assure the service does indeed have this setting, use the following code:

<syntaxhighlight lang="autoit">RegWrite("HKLM\SYSTEM\CurrentControlSet\Services\[ServiceName]", "Type", "REG_DWORD", 0x110)</syntaxhighlight>

==How can I create/start/stop or otherwise control a service?==
There are two include libraries that are designed specifically to interact with services. These are the following:

* [http://www.autoitscript.com/forum/index.php?showtopic=6487 ServiceControl.au3] made by SumTingWong. Functionality:
** _StartService()
** _StopService()
** _ServiceExists()
** _ServiceRunning()
** _CreateService()
** _DeleteService()
* [http://www.autoitscript.com/forum/index.php?showtopic=22165 _NTServices.au3] made by CatchFish. Functionality:
** _ServiceStart()
** _ServiceStop()
** _ServiceStatus()
** _ServicePause()

==How can I display a progress bar while copying files or directories?==
There are a many different topics on how to do this. For more, just search the forums for [http://www.autoitscript.com/forum/index.php?act=Search&CODE=show&searchid=22030d4d4effe5e32da23fdb69ed772f&search_in=posts&result_type=topics&highlite=%2BCopy%2B Progress Copy + Progress].
* [http://www.autoitscript.com/forum/index.php?showtopic=11313 Copy with progress dialog]... By ezztabi
* [http://www.autoitscript.com/forum/index.php?showtopic=11888 Yet another copy with progress]... By SumTingWong
* [http://www.autoit.de/index.php?page=Thread&postID=58875 _MultiFileCopy]... By Oscar (German Forums)
* [http://www.autoitscript.com/forum/index.php?showtopic=19370&st=45&p=186198&#entry186198 _FileCopy]... By Jos

[[File:FAQ_Q6_1.jpg|center|Copy progress dialog by ezztabi]]

==How can I make a hotkey that only works in my GUI?==
It used to be quite tedious setting hotkeys to only work in your GUI. Now there is an easier way with the function GUISetAccelerators.

(From Helpfile example)
<syntaxhighlight lang="autoit">
; A simple custom messagebox that uses the MessageLoop mode
#include <GUIConstantsEx.au3>

GUICreate("Custom Msgbox", 210, 80)

GUICtrlCreateLabel("Please click a button!", 10, 10)
$YesID = GUICtrlCreateButton("Yes", 10, 50, 50, 20)
$NoID = GUICtrlCreateButton("No", 80, 50, 50, 20)
$ExitID = GUICtrlCreateButton("Exit", 150, 50, 50, 20)

; Set accelerators for Ctrl+y and Ctrl+n
Dim $AccelKeys[2][2]=[["^y", $YesID], ["^n", $NoID]]
GUISetAccelerators($AccelKeys)

GUISetState(); display the GUI

Do
$msg = GUIGetMsg()

Select
Case $msg = $YesID
MsgBox(0, "You clicked on", "Yes")
Case $msg = $NoID
MsgBox(0, "You clicked on", "No")
Case $msg = $ExitID
MsgBox(0, "You clicked on", "Exit")
Case $msg = $GUI_EVENT_CLOSE
MsgBox(0, "You clicked on", "Close")
EndSelect
Until $msg = $GUI_EVENT_CLOSE Or $msg = $ExitID
</syntaxhighlight>

==How can I perform an action while a key is held down?==
You can use the _IsPressed() function to determine when a key is held down. The values that can be specified in this function are listed in the AutoIt Help File under User Defined Functions -> Misc Management -> _IsPressed. The following example will press the left mouse button while the k key is held down.

<syntaxhighlight lang="autoit">#include <Misc.au3>
$pressed = 0
While 1
If _IsPressed("4B") Then
If Not $pressed Then
ToolTip("K Key being held down")
MouseDown("left")
$pressed = 1
EndIf
Else
If $pressed Then
ToolTip("")
MouseUp("left")
$pressed = 0
EndIf
EndIf
Sleep(250)
WEnd</syntaxhighlight>

==How can I run my script on a remote computer over the network?==
The answer to this question depends on how much experience you have in networking. If the target system is a Windows 2000 or Windows XP Pro system to which you have administrator access then you may use one of the following programs:

* PsExec from SysInternals
* BeyondExec from BeyondLogic

With either of these programs it is possible to launch any process on a remote system and even copy your script to the target computer before starting it. Neither these programs nor any others will work with Windows XP Home Edition unless you create a custom "command listener" that you manually install on the target system.

NOTE: Those of you with more advanced programming skills and a little imagination can figure out how to use the service control libraries and srvany.exe to do this same thing without either of the above mentioned programs.

==How can I make a User Defined Function with optional parameters like the ones I see in the Help File?==
You can specify optional parameters by giving them a default value in the Func declaration. An example of how this is

done:
<syntaxhighlight lang="autoit">
Func testme($param1, $param2 = "nothing", $param3 = 5)
MsgBox(0, "", "Parameter one is required. The value of Parameter 1 is " & $param1 & @CRLF & _
"Parameter 2 is optional. The value of Parameter 2 is " & $param2 & @CRLF & _
"Parameter 3 is optional. The value of Parameter 3 is " & $param3)
EndFunc</syntaxhighlight>

If testme() is called with only one parameter [I.E. testme("test")] then the output is:
<blockquote>
Parameter one is required. The value of Parameter 1 is test 
Parameter 2 is optional. The value of Parameter 2 is nothing 
Parameter 3 is optional. The value of Parameter 3 is 5 
</blockquote>
However, if the function is called with more than one parameter like this testme("test", "something"), then the output is
<blockquote>
Parameter one is required. The value of Parameter 1 is test 
Parameter 2 is optional. The value of Parameter 2 is something 
Parameter 3 is optional. The value of Parameter 3 is 5 
</blockquote>

==How can I make my script start every time windows starts?==
You can use one of the following codes to allow your script to start with Windows:
<syntaxhighlight lang="autoit">RegWrite("HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Run", "MyProgramName", "REG_SZ", @ScriptFullPath)</syntaxhighlight>
or
<syntaxhighlight lang="autoit">FileCreateShortcut(@ScriptFullPath, @StartupCommonDir & "\MyProgramName.lnk")</syntaxhighlight>

==How can I have the script delete itself?==
The following function will delete the running script or .exe once it has finished execution.

'''WARNING: Make a copy of your script before calling this function!!!'''

<syntaxhighlight lang="autoit">
Func _SelfDelete($iDelay = 0)
Local $sCmdFile
FileDelete(@TempDir & "\scratch.bat")
$sCmdFile = 'ping -n ' & $iDelay & ' 127.0.0.1 > nul' & @CRLF _
& ':loop' & @CRLF _
& 'del "' & @ScriptFullPath & '"' & @CRLF _
& 'if exist "' & @ScriptFullPath & '" goto loop' & @CRLF _
& 'del %0'
FileWrite(@TempDir & "\scratch.bat", $sCmdFile)
Run(@TempDir & "\scratch.bat", @TempDir, @SW_HIDE)
EndFunc;==>_SelfDelete
</syntaxhighlight>

==How can I create a clickable website hyperlink in my gui?==
[[File:FAQ_Q13_1.jpg|center|Example GUI using Gary's UDF.]]

Gary Frost has made great advances in this area and has provided a [http://www.autoitscript.com/forum/index.php?showtopic=23111&st=0 UDF here] to help with doing this.

==How can I change the screen resolution / refresh rate / color depth?==
[http://www.autoitscript.com/forum/index.php?showtopic=20121 ChangeResolution.au3] is a library function created to make changes to these settings.

== How can I get the screen resolution in multiple monitor setups?==
The following code was worked out by Larry to determine the total screen resolution of multiple monitors:

<syntaxhighlight lang="autoit">
$aTSR = _GetTotalScreenResolution()
MsgBox(0, "Total Screen Resolution", "Width = " & $aTSR[0] & @CRLF & _
"Height = " & $aTSR[1])

;Original code by Larry.
;Edited by BrettF
Func _GetTotalScreenResolution()
Local $aRet[2]
Global Const $SM_VIRTUALWIDTH = 78
Global Const $SM_VIRTUALHEIGHT = 79
$VirtualDesktopWidth = DllCall("user32.dll", "int", "GetSystemMetrics", "int", $SM_VIRTUALWIDTH)
$aRet[0] = $VirtualDesktopWidth[0]
$VirtualDesktopHeight = DllCall("user32.dll", "int", "GetSystemMetrics", "int", $SM_VIRTUALHEIGHT)
$aRet[1] = $VirtualDesktopHeight[0]
Return $aRet
EndFunc
</syntaxhighlight>

== How can I register a file type with my program [or] How can I make files with a certain extension open in my program?==
[[File:FAQ_Q16_1.jpg|center|Example of how a file type can be registered.]]
File registration can be a tricky business for those who have not done it before. The first thing to be done is to modify your script to allow it to accept files from the command line. Here is one example of how to do this:

<syntaxhighlight lang="autoit">
;$cmdline[0] is the number of parameters passed
If $cmdline[0] <> 0 Then
$filename = $cmdline[1]
;Do something with the file here
MsgBox(0, "UXYFixer", 'The file name passed to the command line is "' & $filename & '"')
Else
; We did not get any command line parameters.
; If this is a command line only program, you would want to
; alert the user that the command line parameters were incorrect.
; If this is a GUI program (like a notepad program), you would
; want to simply continue from here without opening a file.
MsgBox(0, "UXYFixer", 'Command line parameters incorrect.' & @CRLF & 'Command line usage: "' & @ScriptName & '" "file to process"')
EndIf</syntaxhighlight>
After your script is ready to accept files, you can begin to register the file type you need with your program. To prevent errors, this-is-me has created a UDF that will allow you to do this easily:

Here is an example of how to register and unregister a file extension using this UDF:
<syntaxhighlight lang="autoit">#include "FileRegister.au3"
;================================================
;
; Description: FileRegister($ext, $cmd, $verb [, $def [, $icon = "" [, $desc = "" ]]])
; Registers a file type in Explorer
;
; Parameter(s): $ext - File Extension without period eg. "zip"
; $cmd - Program path with arguments eg. '"C:\test\testprog.exe" "%1"'
; (%1 is 1st argument, %2 is 2nd, etc.)
; $verb - Name of action to perform on file
; eg. "Open with ProgramName" or "Extract Files"
; $def - Action is the default action for this filetype
; (1 for true 0 for false)
; If the file is not already associated, this will be the default.
; $icon - Default icon for filetype including resource # if needed
; eg. "C:\test\testprog.exe,0" or "C:\test\filetype.ico"
; $desc - File Description eg. "Zip File" or "ProgramName Document"
;
;================================================

FileRegister("uxy", '"' & @ScriptFullPath & '" "%1"', "Open in UXYFixer", 1, @ScriptFullPath & ',0', "UXYFixer Document")

;========================================
;
; Description: FileUnRegister($ext, $verb)
; UnRegisters a verb for a file type in Explorer
; Parameter(s): $ext - File Extension without period eg. "zip"
; $verb - Name of file action to remove
; eg. "Open with ProgramName" or "Extract Files"
;
;========================================

FileUnRegister("uxy", "Open in UXYFixer")</syntaxhighlight>

'''Download here:'''
[http://www.autoitscript.com/forum/index.php?app=core&module=attach&section=attach&attach_id=26378 FileRegister.au3]

==Why doesn't my combobox (GUICtrlCreateCombo) show a dropdown list when clicked?==
When using GUICtrlCreateCombo be sure to enter the desired height for your combobox list in the "height" parameter. Windows XP automatically selects an appropriate height for combo boxes, but other versions of Windows usually do not.
<syntaxhighlight lang="autoit">$combo = GUICtrlCreateCombo("",10,10,200,20)</syntaxhighlight>
Would correctly be changed to:
<syntaxhighlight lang="autoit">$combo = GUICtrlCreateCombo("",10,10,200,200)</syntaxhighlight>

==Why isn't my thread getting any replies?==

=== Asking the right question right ===
Did you give a good description of the problem? If your title or explanation of the issue is not descriptive, users are likely to bypass your issue instead of helping. Post titles such as "Help Me", "I Have A Problem", "Question", "Help me fix my code", "This code doesn't work" or similarly worded titles will not readily draw forum users to your post. Experienced users (which are your best hope of resolving the issue) will often skip your post altogether in cases like this. An example of a post title descriptive enough to attract users to assist you is "Problem with WinWaitClose" or "Loop never ends".

=== Example for reproduction ===
Did you post example code? If you have not posted an example of the code you are having an issue with, then you will not recieve support. When posting a non-working script, please do so in the smallest amount of stand-alone code possible. If the code you post cannot run by itself on another person's computer, they will not be able to recreate the issue.

=== Speak English and speak it right ===
Did you use proper English? Here are guidelines for posting properly in the english language:
* Use proper case. THIS IS CONSIDERED YELLING. If you post in ALL UPPERCASE or all lowercase then you will look like a doofus.
* Use proper punctuation. Complete sentences need only one trailing punctuation mark -- not three!!! Writing a sentance without simple punctuation such as commas or other punctuation is considered lazy, which is considered a good judge of the poster's coding style. If you cannot summon the strength to write a sentence with correct punctuation, you will most likely miss simple coding mistakes such as unterminated quotes.

=== Breaking forum rules, law, modesty, or common Sense ===
Make sure you are not giving the impression of breaking forum rules, http://www.autoitscript.com/forum/forum-2/announcement-15-forum-rules-7-nov-2012/. Make sure you are not doing anything that can be perceived as breaking the law.

==Why does the Ctrl key get stuck down after I run my script?==

=== Keys virtually stuck ===
It could equally be the Shift Or the Alt key.

If you use Send In a script And you have a problem With keys being stuck down Then Send is the most likely culprit. A similar problem can occur With BlockInput. The solution is generally quite simple. If there is a key like Shift Or Alt held down at the start of the Send sequence, but that key is released by the time the Send sequence finishes Then the key will get 'stuck' down. As an example of a solution, you could replace the Send function in your script with the _SendEx function below.

The _SendEx function waits for the Shift, Alt And Ctrl keys to be released or pops up a warning if the $warn parameter is not an empty string. Therefore it is not intended to be used when one of these modifier keys has been set to be down using any combination of {ALTDOWN}, {SHIFTDOWN} and {ALTDOWN}.
<syntaxhighlight lang="autoit">
#include < Misc.au3 >
;Send the string $ss after the Shift Alt and Ctrl keys are released. Optionally give a warning after 1 sec if any of those keys are still down.
;Requires misc.au3 to be included in the script for the _IsPressed function.
Func _SendEx($ss, $warn = "")
Local $iT = TimerInit()

While _IsPressed("10") Or _IsPressed("11") Or _IsPressed("12")
If $warn <> "" And TimerDiff($iT) > 1000 Then
MsgBox(262144, "Warning", $warn)
EndIf
Sleep(50)
WEnd
Send($ss)
EndFunc;==>_SendEx</syntaxhighlight>

=== General unstuck method ===
Shilbiz also discovered that the following can 'clear' locked down keys.
<syntaxhighlight lang="autoit"> ControlSend("", "", "", "text", 0)</syntaxhighlight>

==How can I use Pixel functions?==

=== Using a color change as an event ===
The following is an example of using the pixel to check if the colour has changed in a specific region.
<syntaxhighlight lang="autoit">
Local $PixelCheck = 0, $NewCheck
$PixelCheck = PixelCheckSum(40, 50, 60, 70); Get the checksum for this area.
While 1; Keep going
$NewCheck = PixelCheckSum(40, 50, 60, 70)
If $PixelCheck <> $NewCheck Then
; The old pixel checksum and the new one are different.
$PixelCheck = $NewCheck; Update the $PixelCheck to the new value
; Let us know it has changed. Change this to what you want to happen when the colour in the region changes.
Msgbox(48,"PixelChecksum","Pixel region has changed !")
EndIf
Sleep(50); Just to give the CPU a bit of a break.
Wend</syntaxhighlight>

=== Searching for a specific pixel color ===
This is an example of searching for a specific pixel (red), both pure red (0xFF0000) and red in a few different shades.
<syntaxhighlight lang="autoit">; Find a pure red pixel in the range 0,0-20,300
$coord = PixelSearch( 0, 0, 20, 300, 0xFF0000 )
If Not @error Then
MsgBox(0, "X and Y are:", $coord[0] & "," & $coord[1])
EndIf

; Find a pure red pixel or a red pixel within 10 shades variations of pure red
$coord = PixelSearch( 0, 0, 20, 300, 0xFF0000, 10 )
If Not @error Then
MsgBox(0, "X and Y are:", $coord[0] & "," & $coord[1])
EndIf</syntaxhighlight>

==Why doesn't my script work on a locked workstation?==
On a locked station any window will never be active (active is only dialog with text "Press Ctrl+Alt+Del"). In Windows locked state applications run hidden (behind that visible dialog) and do not have focus and active status. So generally don't use Send() MouseClick() WinActivate() WinWaitActive() WinActive() etc. Instead use ControlSend() ControlSetText() ControlClick() WinWait() WinExists() WinMenuSelectItem() etc. This way you may have your script resistive against another active windows. It's possible to run such a script from scheduler on locked Windows stations.

==Where can I learn AutoIt? Are there any tutorials?==
To learn AutoIt you have two main options available to you:

AutoIt 1-2-3, an interactive classroom by Valuater. You may find it here:
[http://www.autoitscript.com/forum/index.php?showtopic=21048 http://www.autoitscript.com/forum/index.php?showtopic=21048]

There is also updated LxP's AutoIt tutorial by BrettF. You can find it here:
[http://www.autoitscript.com/forum/index.php?showtopic=84960 http://www.autoitscript.com/forum/index.php?showtopic=84960]

There is also a book; AutoIt v3: Your Quick Guide by Andy Flessner.
You can buy the book from here:
[http://oreilly.com/catalog/9780596515126/ http://oreilly.com/catalog/9780596515126/]

On YouTube there are many videos available:
[http://www.youtube.com/results?search_query=autoit+tutorial&search_type=&aq=0&oq=AutoIt http://www.youtube.com/results?search_query=autoit+tutorial&search_type=&aq=0&oq=AutoIt]

==Why does my script no longer decompile?==
Decompilation is no longer supported, and is only available for the older versions of AutoIt (Version 3.2.5.1 and earlier compiled scripts).

Please '''do not''' post on this topic, but search the forums for more information. Posting topics like this will usually get the topic locked.

Also posting the source (if a hacked decompiler was used) of other compiled scripts, or otherwise mentioning these hacked decompilers will probably get you banned. It is also in violation of the AutoIt EULA (End-User-License-Agreement).

<blockquote>You may not reverse engineer or disassemble the SOFTWARE PRODUCT or compiled scripts that were created with the SOFTWARE PRODUCT.</blockquote>

Please see the [[Decompiling FAQ]] for more information.

==How can I get a window handle when all I have is a PID?==
Refer to the following example showing converting and use when manipulating the window. The function is based on work by Smoke_N/Hubertus and Helge.
<syntaxhighlight lang="autoit">;Run process
$iPID = Run("Notepad.exe")

;Allow window to initialize...
Sleep (500)

;Get HWND.
$hWnd = _GetHwndFromPID($iPID)

;Maximize
WinSetState($hWnd, "", @SW_MAXIMIZE)

;Wait 2 seconds
Sleep(2000)

;Minimize
WinSetState($hWnd, "", @SW_MINIMIZE)

;Wait 2 seconds
Sleep(2000)

;Restore window
WinSetState($hWnd, "", @SW_RESTORE)

;Wait 2 seconds
Sleep(2000)

;Move top left corner of screen, and resize to 800x600
WinMove($hWnd, "", 0, 0, 800, 600)

;Wait 2 seconds
Sleep(2000)

;Calculate Center of screen.
$x = (@DesktopWidth / 2) - 400; Desktop width divided by 2, then minus half the width of the window
$y = (@DesktopHeight / 2) - 300; Desktop height divided by 2, then minus half the height of the window

;Move to center of screen
WinMove($hWnd, "", $x, $y)

;Wait 2 seconds
Sleep(2000)

;Close notepad
WinClose($hWnd)

;Function for getting HWND from PID
Func _GetHwndFromPID($PID)
$hWnd = 0
$winlist = WinList()
Do
For $i = 1 To $winlist[0][0]
If $winlist[$i][0] <> "" Then
$iPID2 = WinGetProcess($winlist[$i][1])
If $iPID2 = $PID Then
$hWnd = $winlist[$i][1]
ExitLoop
EndIf
EndIf
Next
Until $hWnd <> 0
Return $hWnd
EndFunc;==>_GetHwndFromPID</syntaxhighlight>

==How can I use single or double quotes in strings?==
It is a fairly simple concept once you get the basics down. Basically there are a few different ways to go about mixing quotes in strings.

A string in AutoIt can be encased in either single(') or double (") quotes. So if you want to add only one type of quote into your string, your first port of call is to use the other type of quote to encase the string. Like so:

<syntaxhighlight lang="autoit">$var = "I am a 'quote' inside the string"
MsgBox (0, "Test 1", $var)
$var = 'I wish I could be a "quote" inside the string!'
MsgBox (0, "Test 1", $var)</syntaxhighlight>

If you have to have both types of quotes in the string, the easiest way is to escape the quote ending the string as so to speak. To do this, use two quotes instead of one. Like so:

<syntaxhighlight lang="autoit">$var = 'I am a single ''quote'' inside the string made using "single quote!"'
MsgBox (0, "Test 1", $var)</syntaxhighlight>

==When should I bump my threads?==
As a courtesy to other users you should only bump your post once in a 24 hour period. Doing this allows all users the chance to get helped equally. Also refer to [http://www.autoitscript.com/forum/index.php?showtopic=95704&view=findpost&p=688050 Why isn't my thread getting any replies?], as this will help you get replies.

==How can I protect my code from decompilation?==
The fact of the matter is '''you can't fully protect your code'''. AutoIt is an interpreted language, so all scripts are interpreted, and that script has to get stored somewhere. There is still hope though. You can take certain measures to prevent decompiled code from being usable to the person that decompiled. The first step is to obfuscate your code. This causes the code to become unreadable. Basically variables and functions are renamed, making it very hard to make head or tail of what is what.

Please see the [[Decompiling FAQ]] for more information.

==How can I decompile my AutoIt EXEs?==
You cannot decompile your AutoIt compiled scripts unless it was compiled with AutoIt 3.2.5.1 or earlier.

If you wish to simulate decompilation for your script, you can do this using the following simple example:

<syntaxhighlight lang="autoit">;Original Author SmokeN
If $CMDLINE[0] Then
If $CMDLINE[1] == "/SOURCE" AND $CMDLINE[2] == "MYPASSWORD" Then
FileInstall("ThisSCript.au3", @ScriptDir & "\DecompiledScript.au3")
EndIf
EndIf</syntaxhighlight>

Then if you run the exe with the following command line parameters your source will be installed.

<blockquote>myscript.exe /SOURCE MYPASSWORD</blockquote>

== What is proper forum etiquette? What rules are there for the forum?==
Proper forum etiquette will ensure you will stay a member of these forums. So try to follow these rules. Also see this [http://www.autoitscript.com/forum/index.php?showtopic=95704&st=15&p=688050&#entry688050 FAQ post], as you should follow what is outlined there as well.

* Use proper English. MSN speak and the like makes it very hard to understand what you want. Keep posts in proper case because UPPERCASE is considered yelling and lowercase makes you look stupid. Don't use more punctuation marks than necessary. For example ?!!!? and ????? is completely unnecessary.
* Before posting help with a script, make sure you follow these steps:
*# Search for your issue.
*#* There are many thousands of posts on this forum, and chances are your question has been asked before. Make sure to use a variety of terms to maximize your results.
*# Read the helpfile
*#* Most if not all things in the help file will have an example (native functions) or two. Give them a go to try see how the functions work. Most of the time it helps!
*# Give it a go
*#* Seriously, if you can't be bothered to give it a go, then why should we be bothered to help you? If you feel you can't do it and you don't try then how will you ever know? We always prefer that you give it a go because you can learn from your mistakes and hopefully understand it better.
*# Post your problem
*#* Make sure you post in the correct forum.
*#** AutoIt Specific
*#*** General Help and Support (Most support questions)
*#*** GUI Support (Support for the Graphical User Interface)
*#** Non-AutoIT
*#*** Chat
*#*** Developer Chat (Usually for C++ questions.)
*#* Include a detailed description in the content of the post, and a detailed title
*#** Titles such as 'Help' and 'What's wrong?' are not acceptable. To get the most help with your problem, be as descriptive as you can in the title, but keep in mind your title cannot be too long.
*#** Make sure you also include a descriptive question. Just saying 'what is wrong with the following' is also not acceptable, as we will have no idea what the problem is. Describe what you think is wrong and what is not working. It makes our job easier.
*#* Always include your code
*#** It shows us that you have tried and gives us a head start with something to play with.
* Usually asking for a script is not taken too well, within reason. Keep in mind that this is a support forum, so please acknowledge that. Most of us would rather that you learn rather than just having a script written for you. If you do need something written for you, maybe try [http://www.rentacoder.com/ RentACoder], as they are more suited to requests.
* Don't PM other members asking for them to look at threads of to help you unless they request it. It is actually quite rude and annoying to receive PMs of that nature.
* Lurk a little before you dive right in. Read a number of posts, or check out the group's archives. Get a feel for the tone of the forum so you can participate accordingly.
* Say online exactly what you would say in person. In other words, if you wouldn't say it to the person's face in front of your Grandmother, you shouldn't type it here.
* Remember your face doesn't show. Words alone can convey sentiment, but without benefit of inflection or facial expression, they can be misconstrued. Use descriptive wording, emoticons or .gifs to ensure your meaning is clear. By the same token, don't jump to conclusions about another person's intent in posting an unclear comment. When in doubt, ask for clarification.
* Be respectful. Internet etiquette is similar to standard etiquette in this area. Appreciate that your opinion is one of many. You can disagree with another person without being disrespectful or rude to other people.
* Ignore Trolls. If you engage in conversation with one, you'll raise your blood pressure and empower the troll. You can't win a flame war, and you can't sway a troll's opinion. Often, they don't even care about the subject. They live for the conflict and nothing more. Trolls are common and not worthy of your time. Ignore their posts no matter how inflammatory and eventually they'll get bored and move on.
* When you have found an answer for your question:
*# Do not edit your post to be blank or to have worthless information. People may be searching for the same issue you have, so be courteous to them by leaving your question there.
*# It is also optional to add the likes of [SOLVED] into the title, and redirecting people to the answer that helped you. It can make the lives of people searching easier.
* Finally follow the rules:
** [http://www.autoitscript.com/forum/forum-6/announcement-13-forum-rules/ Forum rules]
** [http://www.autoitscript.com/forum/index.php?showtopic=54168 Rules for the Chat forum]
** [http://www.autoitscript.com/forum/index.php?showtopic=65889 Rules for asking for source code]
** [http://www.autoitscript.com/forum/index.php?showtopic=37739 General policies and forum settings]

Some general points taken from [http://www.ehow.com/how_2106033_use-proper-forum-etiquette.html here].

==Are there forums available in my local language?==
Yes there are some available. Some forum members here participate in multiple forums.
* [http://www.autoit.de/ German Forums]
* [http://www.autoit.fr/ French Forums]
* [http://www.autoit.es/ Spanish Forums]
* [http://autoit-script.ru/ Russian Forums]

Please note that these are independent, community-run message boards and not just a translation of this board.

Label

2013-01-15T17:49:17Z

BrewManNH:

A Label is a simple, plain piece of text appearing in a [[Graphical User Interface|GUI]].

== Summary ==
A Label is a GUI control, which consists of a simple, plain piece of text. The function for creating a Label is {{Help File|GuiCtrlCreateLabel}}. You can change the text of the label using {{Help File|GuiCtrlSetData}} and read it using {{Help File|GuiCtrlRead}} functions.

== Example ==
This example demonstrates the creation of a GUI label.
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

Opt('MustDeclareVars', 1)

Example()

Func Example()
GUICreate("My GUI") ; will create a dialog box that when displayed is centered

GUISetHelp("notepad") ; will run notepad if F1 is typed

Opt("GUICoordMode", 2)

Local Const $widthCell = 70

GUICtrlCreateLabel("Line 1 Cell 1", 10, 30, $widthCell) ; first cell 70 width
GUICtrlCreateLabel("Line 2 Cell 1", -1, 0) ; next line
GUICtrlCreateLabel("Line 3 Cell 2", 0, 0) ; next line and next cell
GUICtrlCreateLabel("Line 3 Cell 3", 0, -1) ; next cell same line
GUICtrlCreateLabel("Line 4 Cell 1", -3 * $widthCell, 0) ; next line Cell1

GUISetState() ; will display an empty dialog box

; Run the GUI until the dialog is closed
Do
Until GUIGetMsg() = $GUI_EVENT_CLOSE

EndFunc ;==>Example
</syntaxhighlight>

Snippets ( Internet )

2013-01-15T15:12:15Z

BrewManNH: /* _ValidIP */

__TOC__

[[category:Snippets]]

{{Snippet Credit Header}}

== Auto-Check For User To Update ==

{{Snippet Header
| AuthorURL = 4920-valuater
| AuthorName = Valuater
}}

<syntaxhighlight lang="autoit">
; Auto-Check For User To Update

Global $Udif, $QT_web = "www.XPCleanMenu.HostRocket.com"
Call("Set_Updater")

;test
$Uask = MsgBox(68, "Update Notification", " Your last update was more than " & $Udif & " days ago." & @CRLF & @CRLF & "Would you like to check for new updates now?")

If $Uask = 6 Then MsgBox(0, "", "Success. The update was ran.")

Func Set_Updater()
If Not FileExists(@SystemDir & "\UpDate.dat") Then
FileWrite(@SystemDir & "\UpDate.dat", @YDAY)
Else
$Uold = FileReadLine(@SystemDir & "\UpDate.dat", 1)

If $Uold >=320 Then
FileDelete(@SystemDir & "\UpDate.dat")
Return
EndIf

$Udif = @YDAY - $Uold

If $Udif >= 45 Then
$Uask = MsgBox(68, "UpDate Notification", " Your last UpDate was more than " & $Udif & " days ago " & @CRLF & @CRLF & "Would you like to check for new updates now? " & @CRLF & @CRLF)

If $Uask = 6 Then
Run(@ProgramFilesDir & "\Internet Explorer\iexplore.exe " & $QT_web)
WinWaitActive("")
EndIf

FileDelete(@SystemDir & "\UpDate.dat")

FileWrite(@SystemDir & "\UpDate.dat", @YDAY)
EndIf
EndIf
EndFunc
</syntaxhighlight>

[[#top | Return To Contents]]

== _GetIEVersion ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Check IE Version.
ConsoleWrite(_GetIEVersion() & @CRLF)

Func _GetIEVersion()
Return StringRegExpReplace(RegRead('HKEY_LOCAL_MACHINE\Software\Microsoft\Internet Explorer\', 'Version'), '^(\d+\.\d+).*', '$1')
EndFunc ;==>_GetIEVersion
</syntaxhighlight>

[[#top | Return To Contents]]

== _GetTimeOnline ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
| Desc = Retrieve the current time from TimeAPI.org. Ideal if your Windows clock is out of sync.
}}

<syntaxhighlight lang="autoit">
; Retrieve the current time from TimeAPI.org. Ideal if your Windows clock is out of sync.
ConsoleWrite(_GetTimeOnline(0) & @CRLF) ; TimeZone UTC.

; #FUNCTION# ====================================================================================================================
; Name ..........: _GetTimeOnline
; Description ...: Retrieve the current date and time from TimeAPI.org.
; Syntax ........: _GetTimeOnline($iTimeZone)
; Parameters ....: $iTimeZone - An integer value of the timezone .
; 0 - UTC (Universal Time)
; 1 - EST (Eastern Time)
; 2 - CST (Central Time)
; 3 - MST (Mountain Time)
; 4 - PST (Pacific Time)
; 5 - AKST (Alaska Time)
; 6 - HAST (Hawaii-Aleutian Time)
; Return values .: Success: Returns the current Date and Time in the format YYYY/MM/DD HH:MM:SS
; Failure: Sets @error to non-zero and returns the same format as a successful return but using the system time.
; Author ........: guinness
; Link ..........: According to http://www.programmableweb.com/api/timeapi, this is for non-commercial use.
; Example .......: Yes
; ===============================================================================================================================
Func _GetTimeOnline($iTimeZone)
Local $aTimeZone[7] = ['utc', 'est', 'cst', 'mst', 'pst', 'akst', 'hast']

Local $sRead = BinaryToString(InetRead('http://www.timeapi.org/' & $aTimeZone[$iTimeZone] & '/now?format=\Y/\m/\d%20\H:\M:\S'))

If @error Then
Return SetError(1, 0, @YEAR & '/' & @MON & '/' & @MDAY & ' ' & @HOUR & ':' & @MIN & ':' & @SEC)
EndIf

Return $sRead
EndFunc ;==>_GetTimeOnline
</syntaxhighlight>

[[#top | Return To Contents]]

== _HTML_StripTags ==

{{Snippet Header
| AuthorURL = 25246-robjong
| AuthorName = Robjong
}}

<syntaxhighlight lang="autoit">
MsgBox(4096, "", _HTML_StripTags("This should be # - (#)"))

; Strip HTML tags from HTML syntax. By Robjong.
Func _HTML_StripTags($sHTMLData) ; http://www.autoitscript.com/forum/topic/...tml-data/page__view__findpost_
If $sHTMLData = "" Then Return SetError(1, 0, $sHTMLData)

Local $oHTML = ObjCreate("HTMLFILE")

If @error Then Return SetError(1, 0, $sHTMLData)

$oHTML.Open()
$oHTML.Write($sHTMLData)

Return SetError(0, 0, $oHTML.Body.InnerText)
EndFunc ;==>_HTML_StripTags
</syntaxhighlight>

[[#top | Return To Contents]]

== _InetGetOutOfProcess ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_InetGetOutOfProcess('http://google.com', @TempDir & '\Google.tmp') & @CRLF)

; Download a file by spawning a new AutoIt process.
Func _InetGetOutOfProcess($sURL, $sFilePath, $iOptions = 0)
Return RunWait('"' & @AutoItExe & '" /AutoIt3ExecuteLine ' & '"Exit InetGet(""' & $sURL & '"", ""' & $sFilePath & '"", ' & $iOptions & ', 0)"') > 0
EndFunc ;==>_InetGetOutOfProcess
</syntaxhighlight>

[[#top | Return To Contents]]

== _IsInternetConnected ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite("Internet Is Connected" & " = " & _IsInternetConnected() & @CRLF) ; ( Returns "True" Or "False" )

Func _IsInternetConnected()
Local $aReturn = DllCall('connect.dll', 'long', 'IsInternetConnected')
If @error Then
Return SetError(1, 0, False)
EndIf
Return $aReturn[0] = 0
EndFunc ;==>_IsInternetConnected
</syntaxhighlight>

[[#top | Return To Contents]]

== _IsIP ==

{{Snippet Header
| AuthorURL = 4813-smoke-n
| AuthorName = SmOke_N
| Desc = Checks to see if a string is a valid IP address.
}}

<syntaxhighlight lang="autoit">
;Checks to see if a string is a valid IP address.

If _IsIP("127.0.0.1") Then Msgbox(0, "", "Valid IP address.")

Func _IsIP($ip)
Return StringRegExp ($ip, "^(25[0-5]|2[0-4][0-9]|[0-1]{1}[0-9]{2}|[1-9]{1}[0-9]{1}|[1-9])\.(25[0-5]|2[0-4][0-9]|[0-1]{1}[0-9]{2}|[1-9]{1}[0-9]{1}|[1-9]|0)\.(25[0-5]|2[0-4][0-9]|[0-1]{1}[0-9]{2}|[1-9]{1}[0-9]{1}|[1-9]|0)\.(25[0-5]|2[0-4][0-9]|[0-1]{1}[0-9]{2}|[1-9]{1}[0-9]{1}|[0-9])$")
EndFunc
</syntaxhighlight>

[[#top | Return To Contents]]

== _IsValidIP ==

{{Snippet Header
| AuthorURL = 20477-mrcreator
| AuthorName = MrCreatoR
}}

<syntaxhighlight lang="autoit">
#include <Array.au3>

Local Const $sString = @IPAddress2 & ":8080" ;8080 is port value (for example)

Local Const $GetValidIp = _IsValidIP($sString, ":")

ConsoleWrite($GetValidIp)

Local $IPsArray = _StringToIPArray('99.77.88.255 567567567 text 155.99.66.6 some more text ' & @IPAddress1 & ',' & @IPAddress2)

_ArrayDisplay($IPsArray)

Func _IsValidIP($sString, Const $sDelim = "")
If Not StringInStr($sString, ".") Then Return 0

If $sDelim <> "" Then $sString = StringLeft($sString, StringInStr($sString, $sDelim) - 1)

If StringLen($sString) > 15 Then Return 0

Local $Dot_Split = StringSplit($sString, ".")

Local $iUbound = UBound($Dot_Split) - 1

If $iUbound <> 4 Then Return 0

For $i = 1 To $iUbound
If $Dot_Split[$i] = "" Then Return 0
If StringRegExp($Dot_Split[$i], '[^0-9]') Or Number($Dot_Split[$i]) > 255 Then Return 0
Next

If $sDelim <> "" Then Return $sString
Return 1
EndFunc

Func _StringToIPArray($sString)
Local $avArray = StringRegExp($sString, '([0-9]+\.[0-9]+\.[0-9]+\.[0-9]+)', 3)
Local $avRetArr[1], $iUbound

For $i = 0 To UBound($avArray)-1
If _IsValidIP($avArray[$i]) Then
$iUbound = UBound($avRetArr)
ReDim $avRetArr[$iUbound+1]
$avRetArr[$iUbound] = $avArray[$i]
EndIf
Next

If $iUbound = 0 Then Return SetError(1, 0, 0)

$avRetArr[0] = $iUbound
Return $avRetArr
EndFunc
</syntaxhighlight>

[[#top | Return To Contents]]

== _IsValidURL ==

{{Snippet Header
| AuthorURL = 44525-jscript
| AuthorName = JScript
}}

<syntaxhighlight lang="autoit">
;Author: JScript - Snippet Version No. = 1.0
;Snippet was Created Using AutoIt Version = 3.3.8.1, Creation Date = 22/05/12.

ConsoleWrite("Is Valid URL? " & _IsValidURL("http:www.autoitscript.com") & @CRLF)
ConsoleWrite("Is Valid URL? " & _IsValidURL("www.autoitscript.com") & @CRLF)

Func _IsValidURL($sPath)
Local Const $sRet = DllCall("Shlwapi.dll", "BOOL", "PathIsURL", "str", $sPath)
Return $sRet[0]
EndFunc ;==>_IsValidURL
</syntaxhighlight>

[[#top | Return To Contents]]

== _Toggle_Images ==

{{Snippet Header
| AuthorURL = 8730-big-daddy
| AuthorName = big_daddy
| Desc = Toggle Internet Images On/Off
}}

<syntaxhighlight lang="autoit">
; Toggle Internet Images On/Off

#include <IE.au3>

Opt("WinTitleMatchMode", 2)

_Toggle_Images(1)
Global Const $oIE = _IECreate ()

_IENavigate ($oIE, "http:\\www.google.com")

While WinExists("Internet Explorer")
Sleep(250)
WEnd
_Toggle_Images()

Func _Toggle_Images($On_Off=0)
If $On_Off == 0 Then
RegWrite("HKEY_CURRENT_USER\Software\Microsoft\Internet Explorer\Main", "Display Inline Images", "REG_SZ", "yes")
Else
RegWrite("HKEY_CURRENT_USER\Software\Microsoft\Internet Explorer\Main", "Display Inline Images", "REG_SZ", "no")
EndIf
EndFunc ;==>_Toggle_Images()
</syntaxhighlight>

[[#top | Return To Contents]]

== _Tracert ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <Constants.au3>

ConsoleWrite(_Tracert("www.duckduckgo.com") & @CRLF)

Func _Tracert(Const $sURL)
; -d = Do Not Resolve Host & -h Is The Number Of Hops.
Local Const $sData = _RunStdOutRead('tracert -d -h 1 ' & $sURL, @SystemDir)

Local Const $aReturn = StringRegExp($sData, '\[([\d.]{7,15})\]', 3)

If @error Then
Return SetError(1, 0, -1)
EndIf

Return $aReturn[0]
EndFunc ;==>_Tracert

Func _RunStdOutRead($sCommand, $sWorkingDirectory = @SystemDir)
Local Const $iPID = Run(@ComSpec & ' /c ' & $sCommand, $sWorkingDirectory, @SW_HIDE, $STDOUT_CHILD + $STDERR_CHILD), $sOutput = ''

While 1
$sOutput &= StdoutRead($iPID)

If @error Then
ExitLoop
EndIf
WEnd

Return $sOutput
EndFunc ;==>_RunStdOutRead
</syntaxhighlight>

[[#top | Return To Contents]]

== _ValidIP ==

{{Snippet Header
| AuthorURL = 58912-brewmannh
| AuthorName = BrewManNH
}}

<syntaxhighlight lang="autoit">
#include <Array.au3> ; This is only needed for the _ArrayDisplay function used in the example below, and is not needed for the _ValidIP function

; IPv4 validation script
Global Const $IPAddress = "192.168.2.1"

Global Const $Return = _ValidIP($IPAddress)

If $Return < 0 Then
Switch @error
Case 1
MsgBox(64, "", "Error in IP address: " & $IPAddress & @LF & "Error code is: 1 - IP address starts with an invalid number = 0, 127 , 169 or is > 239")
Case 2
MsgBox(64, "", "Error in IP address: " & $IPAddress & @LF & "Error code is: 2 - one of the octets of the IP address is out of the range 0-255 or contains invalid characters")
Case 3
MsgBox(64, "", "Error in IP address: " & $IPAddress & @LF & "Error code is: 3 - IP Address is not a valid dotted IP address (ex. valid address 190.40.100.20)")
Case 4
MsgBox(64, "", "Error in IP address: " & $IPAddress & @LF & "Error code is: 4 - Last octet is either 0 or 255")
EndSwitch
Else
MsgBox(48, "", $IPAddress & " is a valid Class " & $Return[5] & " IP address")
_ArrayDisplay($Return)
EndIf

; FUNCTION# ===========================================================================================================
; Name...........: _ValidIP
; Description ...: Verifies whether an IP address is a valid IPv4 address or not
; Syntax.........: _ValidIP($sIP)
; Parameters ....: $sIP - IP address to validate
;
; Return values .: Success - Array containing split IP Address, IP address in Hex, and the Class of the IP address
; array[0] - [3] = the IP address split into octets
; array[4] = IP address in Hex
; array[5] = Class of the IP address [A through D]
; Failure - -1, sets @error
; |1 - IP address starts with an invalid number = 0, 127 , 169 or is > 239
; |2 - one of the octets of the IP address is out of the range 0-255 or contains invalid characters
; |3 - IP Address is not a valid dotted IP address (ex. valid address 190.40.100.20)
; |4 - Last octet ends in 0 or 255 which are invalid for an IP address
; Author ........: BrewManNH
; Modified.......:
; Remarks .......: This will accept an IP address that is 4 octets long, and contains only numbers and falls within
; valid IP address values. Class A networks can't start with 0 or 127. 169.xx.xx.xx is reserved and is
; invalid and any address that starts above 239, ex. 240.xx.xx.xx is reserved. The address range
; 224-239 1s reserved as well for Multicast groups but can be a valid IP address range if you're using
; it as such. Any IP address ending in 0 or 255 is also invalid for an IP
; Related .......:
; Link ..........:
; Example .......: Yes
; =====================================================================================================================
Func _ValidIP($sIP)
Local $adIPAddressInfo[6]

Local $aArray = StringSplit($sIP, ".", 2)

If Not IsArray($aArray) Or UBound($aArray) <> 4 Then Return SetError(3, 0, -1)

Local $dString = "0x"

If $aArray[0] <= 0 Or $aArray[0] > 239 Or $aArray[0] = 127 Or $aArray[0] = 169 Then
Return SetError(1, 0, -1)
EndIf

For $I = 0 To 3
If $I < 3 Then
If $aArray[$I] < 0 Or $aArray[$I] > 255 Or Not StringIsDigit($aArray[$I]) Then
Return SetError(2, 0, -1)
EndIf
Else
If Not StringIsDigit($aArray[$I]) Then
Return SetError(2, 0, -1)
EndIf

If $aArray[$I] < 1 Or $aArray[$I] > 254 Then
Return SetError(4, 0, -1)
EndIf
EndIf

$dString &= StringRight(Hex($aArray[$I]), 2)

$adIPAddressInfo[$I] = $aArray[$I]
Next

$adIPAddressInfo[4] = $dString

Switch $aArray[0]
Case 1 To 126
$adIPAddressInfo[5] = "A"
Return $adIPAddressInfo
Case 128 To 191
$adIPAddressInfo[5] = "B"
Return $adIPAddressInfo
Case 192 To 223
$adIPAddressInfo[5] = "C"
Return $adIPAddressInfo
Case 224 To 239
$adIPAddressInfo[5] = "D"
Return $adIPAddressInfo
EndSwitch
EndFunc ;==>_ValidIP
</syntaxhighlight>

UDF-spec

2012-12-26T21:10:10Z

BrewManNH: /* Constants */

[[Category:UDF]]
{{WIP}}This page is still under construction.

----

A library is a collection of one or more User Defined Functions (UDFs). However, the term UDF is often used to describe the collection as a whole. If a UDF is to be considered for inclusion in the standard set distributed with AutoIt then it must meet all the criteria detailed here, but it's also good practice to always write in conformance with at least the majority of this document, as that is what will be expected by people reading your code later.

== Basic Requirements ==
Firstly, the code itself should meet the following basic requirements:

* Be tidied. Just hit <code>Ctrl+T</code> from SciTE or run Tidy manually. The only flag needed is <code>/sf</code>.
* Pass Au3Check with no errors using the strictest settings: <code>-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7</code>
* Support everything AutoIt supports. In some cases features may not be able to support everything, in which case this should be checked for and return errors appropriately. This applies to: windows OS versions (AutoIt has support for all OS' from windows 2000), unicode and ansi strings, 64 and 32 bit machines.
* Ideally it will be able to run cleanly when obfuscated. Although there will be some cases where this is not possible, please consider it when writing UDFs, and avoid the use of Execute and similar statements. If it does not, then document it as such.

== UDF Outline ==
The library itself has a header that details important information such as the minimum OS and AutoIt versions, and what system dlls are required. There is also a number of other sections that are required that list what is present in the UDF.

=== Includes ===
Since a UDF is designed to define functions, it should only be included once. As a result, the <code>#include-once</code> directive should be used. This is typically the first line of the UDF, followed by the includes used by the UDF. Include statements should use the double quoted form, as the library is expected to work in the same directory as libraries it depends on. Non standard libraries can be used if necessary, but this should be documented and linked to so users can download it as well. It goes without saying that a UDF based on non-standard UDFs cannot itself become a standard.

=== Index ===
The index follows the following template (taken from <code>WinAPI.au3</code>):

<syntaxhighlight lang="autoit">; #INDEX# =======================================================================================================================
; Title .........: Windows API
; AutoIt Version : 3.2
; Description ...: Windows API calls that have been translated to AutoIt functions.
; Author(s) .....: Paul Campbell (PaulIA), gafrost, Siao, Zedna, arcker, Prog@ndy, PsaltyDS, Raik, jpm
; Dll ...........: kernel32.dll, user32.dll, gdi32.dll, comdlg32.dll, shell32.dll, ole32.dll, winspool.drv
; ===============================================================================================================================</syntaxhighlight>

The only required element in the index header is <code>Title</code>. All others are ignored by the processor, but should be included for reference

The <code>Dll</code> field can remain empty in many cases where no dlls are called directly. This header must be defined.

=== Other Sections ===
Other sections, in order of appearance, are as follows.

==== Variables ====
All global variables needed to be declared in the UDF are defined in this section. They should follow the variable rules for globals. Individual variables do not need to be documented, as it is assumed they are for internal use only. Any globals designed to be accessible for the user should instead be wrapped by a function (or multiple functions if globals must be retrieved and set). The template for this section is:

<syntaxhighlight lang="autoit">; #VARIABLES# ===================================================================================================================
Global $__gvMyGlobal = 0
; ===============================================================================================================================</syntaxhighlight>

If no globals are needed then this section may be ommitted. Please consider the use of global variables carefully, and read through the section on global variables.

==== Constants ====
Any global constant values are defined in this section. This should be constants only designated for use within the library itself. Constants that may be needed by the user should be defined in a separate file, named <code>UDFConstants.au3</code> where <code>UDF</code> is the name of the parent file. For example <code>File.au3</code> uses constants defined in <code>FileConstants.au3</code>. The exception to that rule is control UDFs which miss out the prepended 'GUI' when naming constant files, so <code>GUIButton.au3</code> uses constants from <code>ButtonConstants.au3</code>. The template for this section is:

<syntaxhighlight lang="autoit">; #CONSTANTS# ===================================================================================================================
Global Const $__MYUDFCONSTANT_FOOBAR = 42
; ===============================================================================================================================</syntaxhighlight>

If no constants are needed in this section, either because none are used or because they are stored in a separate file, then it may be ommitted. Please read the section on global constants for specific info on naming and definition of constants.

==== Listing ====
This defines all functions and structures currently used functions in the library. It MUST be the second defined header item after [[#Index]]. It is a simple list with each function on a line where the functions and structures appear in the same order as they do in the code, which is alphabetical order and structures first. A simple way to generate this list is to create a small script that searches for function definitions and outputs them in the correct format, an example of which is [http://www.autoitscript.com/forum/topic/120820-function-name-lister/ here]. In addition there is a second section that lists functions and structures for internal use only, this does not need to appear if none are defined.

The template for these sections are:

<syntaxhighlight lang="autoit">; #CURRENT# =====================================================================================================================
;$tagSTRUCT
;_MyUDF_Function
; ===============================================================================================================================

; #INTERNAL_USE_ONLY# ===========================================================================================================
;$tagINTERNALSTRUCT
;__MyUDF_InternalFunction
; ===============================================================================================================================</syntaxhighlight>

This section still needs to be defined for files that only define constants. It should also be noted that there MUST NOT be a space between the <code>;</code> and the function/structure name.

==== Undocumented Listing ====
There is a final kind of listing that lists functions for which no documentation exists, or they have been deprecated and are only included for backwards compatibility. These are listed in a section with the header <code>NO_DOC_FUNCTION</code>. This is very rarely used, and is reserved only for functions that can be utilised by the user, or that would have been in the past, as opposed to those for internal use only.

Template:

<syntaxhighlight lang="autoit">; #NO_DOC_FUNCTION# =============================================================================================================
;_MyUDF_Function
; ===============================================================================================================================</syntaxhighlight>

==== Renamed Functions ====
Although it should not be the case in new UDFs, many of the older ones (particularly to do with controls) have had script breaking name changes to functions. These are documented in the UDF to ensure updating old scripts is as easy as possible. The basic format for this is:

<syntaxhighlight lang="autoit">; #NO_DOC_FUNCTION# =============================================================================================================
;_MyUDF_OldFunction ; --> _MyUDF_NewFunction
; ===============================================================================================================================</syntaxhighlight>

The space padding is optional. This section is ignored as far as the docs are concerned, and is usually omitted.

== Functions ==
=== Naming ===
Function names must start with an underscore, and the first word is the library name. There is then usually another underscore before the rest of the function name. The library name should be consistent across all the functions in the library, and can be shortened if a logical abbreviation is available (e.g. <code>Window</code> ==> <code>Win</code>). Each word should be capitalized, but no underscores are placed in the rest of the name, for example <code>_WinAPI_GetWindowLong</code>.

For control libraries, the first part of the function name is changed slightly. For example the UDF for listviews would use <code>_GUICtrlListview_*</code>. When a function wraps a dll call, then the second part should closely resemble the function name as it appears in other languages. This also applies to functions acting as a wrapper to <code>SendMessage</code>.

Functions are defined in alphabetical order by name, which is the same as using <code>Tidy</code> with the <code>/sf</code> flag set.

=== Parameters ===
Parameters should follow the variable naming scheme ([[#Naming_2|here]]). All parameters must be checked to ensure they are valid, and return unique and documented error codes if they are not. For functions involving a specific type of control, this includes checking the class name using <code>_WinAPI_IsClassName</code>.

Parameters that are optional or byref should be documented as such, and the effect these have explicitly stated. For example a byref parameter should detail exactly what the expected output is as well as the input.

=== Headers ===
All functions have a documentation header that describes the function. This uses the following template:

<syntaxhighlight lang="autoit">; #FUNCTION# ====================================================================================================================
; Name...........: _WinAPI_GetMousePos
; Description ...: Returns the current mouse position
; Syntax.........: _WinAPI_GetMousePos([$fToClient = False[, $hWnd = 0]])
; Parameters ....: $fToClient - If True, the coordinates will be converted to client coordinates
; $hWnd - Window handle used to convert coordinates if $fToClient is True
; Return values .: Success - $tagPOINT structure with current mouse position
; Failure - Zero
; Author ........: Paul Campbell (PaulIA)
; Modified.......:
; Remarks .......: This function takes into account the current MouseCoordMode setting when obtaining the mouse position. It
; will also convert screen to client coordinates based on the parameters passed.
; Related .......: $tagPOINT, _WinAPI_GetMousePosX, _WinAPI_GetMousePosY
; Link ..........:
; Example .......: Yes
; ===============================================================================================================================
Func _WinAPI_GetMousePos($fToClient = False, $hWnd = 0)</syntaxhighlight>

The header is 129 characters wide, and any text within it should be wrapped to that length. For example the <code>Remarks</code> in the above header has been extended to cover two lines. The exception to that rule is the <code>Syntax</code> line, which should not be wrapped. Some of the parameters in the header are optional, in which case they should remain, but be left empty (for example the <code>Link</code> and <code>Modified</code> lines in the above header). In others, they are needed, but can be empty or not used such as <code>Parameters</code> or <code>Return Values</code>. In this case the value should be 'None', as they will still be present in the documentation.

There are some flags that can be used within function headers:

* '''+''' in column 20 is the continuation flag for the previous line (used in Parameters, Return Values)
* '''|''' in column 20 is a new line in the right side of the table when the help file is generated (used in Parameters, Return Values)
* '''-''' in column 20 will create new row in the table, used for things like Defaults for a style (used in Parameters, Return Values)
* '''+''' in column 2 of Remarks is a blank line
Name
:Specifies the name of the function. This will be identical to how it appeas in the Func statement in the code itself.
Description
:Gives a short summary of what the function does. This should only be a single line, as it is only designed to give a short impression of what is happening. For the standard set of includes distributed with AutoIt3, this value is also used in the SciTE calltips.
Syntax
:Describes the syntax of the function call. This differs slightly from what appears in the code itself for optional parameters, which are enclosed in square brackets ("[ ]"). Since subsequent parameters must also be optional, and cannot be defined unless all the previous ones have been given, these brackets are nested in the form: Function([param1[, param2[,param3]]]). Note that the opening bracket appears before the comma seperator.
Parameters
:This is a list of the arguments accepted by the function. Each is listed, followed by a dash ("-") and a description of what it is. The dash can be padded for neatness, although the amount of padding depends on how long the parameter names are. If the parameter is optional then the meaning of the default value should be given, similarly if it's used to pass data back to the program in the form of byref then the changes made should also be detailed. For more information on parameters see Parameters.
Return values
:Details what is returned by the function. This often comes in the form of Success and Failure values, but this is not always the case. Any setting of the @error of @extended flags should be detailed, along with their meanings, in some cases it is enough to say that @error is set to non-zero in the event of an error, in most cases though a list of values for @error should be given.
Author
:This is the original writer of the function. It should contain the username, so that any queries about the code can be made through the forum, but you can give as much or little information as you feel appropriate.
Modified
:This is a list of modifications made. At it's most basic this is just a list of users who have made changes, but ideally it includes some information about what they did, in which cases it follows the same form as other multi-value lines, with the username and description of modifications seperated by a dash.
Remarks
:This is anything the user should know about a function in order to use it. For example exceptional cases and recommended ways to handle the function should all be detailed here, as well as additional info about possible reasons for failure and how to deal with them.
Related
:A comma seperated list of functions or structures related to the function.
Link
:A link to additional information about the function. For many system function wrappers, this will be <code>@@MsdnLink@@ FunctionName</code>, which represents that the user should search MSDN for the function.
Example
:A simple yes or no value specifying whether the function has an example. If this is no then your UDF is not ready to be released. The [[#Examples]] section has more information on the format and location of examples.

The easiest way to generate the header is to copy and paste the following blank template in:

<syntaxhighlight lang="autoit">; #FUNCTION# ====================================================================================================================
; Name...........:
; Description ...:
; Syntax.........:
; Parameters ....:
; Return values .:
; Author ........:
; Modified.......:
; Remarks .......:
; Related .......:
; Link ..........:
; Example .......:
; ===============================================================================================================================</syntaxhighlight>

There are also a number of plugins for SciTE that will generate a header and maybe fill in certain known values for you such as Name, Syntax and Parameters. The most complete one that conforms to these standards is [http://code.google.com/p/m-a-t/wiki/UDFHeaderGenerator here], but there are two others [http://www.autoitscript.com/forum/topic/28270-lua-script-for-udf-header/ here] and [http://www.autoitscript.com/forum/topic/28270-lua-script-for-udf-header/page__view__findpost__p__200823 here].

=== Internal use only ===
Functions can also be marked for use only within the library and not to be documented for use by the user. These are named according to the same rules as normal functions but begin with a double underscore ("__"). The header is exactly the same except with the first line replaced, to make the blank template:

<syntaxhighlight lang="autoit">; #INTERNAL_USE_ONLY# ===========================================================================================================
; Name...........:
; Description ...:
; Syntax.........:
; Parameters ....:
; Return values .:
; Author ........:
; Modified.......:
; Remarks .......:
; Related .......:
; Link ..........:
; Example .......:
; ===============================================================================================================================</syntaxhighlight>

== Structures ==
Structures are defined as global constants, and follow the naming pattern <code>$tagSTRUCTNAME</code>. The struct name should be as it appears on MSDN if it's used in the windows API, or follow a similar pattern if not. It should go without saying that they must work for both 32 and 64 bit machines, including resolving any alignment issues. Elements should also be named as they appear on MSDN if they are taken from there, which includes the hungarian notation prefix. Although many standard UDFs do not follow that rule, importantly <code>StructureConstants.au3</code>, the rule still stands.

=== Headers ===
Structures need a header similar to functions, but with some minor differences. The same rules apply in terms of wrapping and line length however. The header follow this standard template:

<syntaxhighlight lang="autoit">; #STRUCTURE# ===================================================================================================================
; Name...........: $tagPOINT
; Description ...: Defines the x and y coordinates of a point
; Fields ........: X - Specifies the x-coordinate of the point
; Y - Specifies the y-coordinate of the point
; Author ........: Paul Campbell (PaulIA)
; Remarks .......:
; Related .......:
; ===============================================================================================================================
Global Const $tagPOINT = "long X;long Y"</syntaxhighlight>

It is essentially a shortened header, with the only thing new is the Fields line, which effectively replaces the Parameters field in terms of usage. All the same rules apply as listed [[#Function Header Fields|here]].

The blank template is:

<syntaxhighlight lang="autoit">; #STRUCTURE# ===================================================================================================================
; Name...........:
; Description ...:
; Fields ........:
; Author ........:
; Remarks .......:
; Related .......:
; ===============================================================================================================================</syntaxhighlight>

Structures may also be marked for internal use only. In this case the header ramains the same, but the sections first line changes. The blank template is:

<syntaxhighlight lang="autoit">; #INTERNAL_USE_ONLY# ===========================================================================================================
; Name...........:
; Description ...:
; Fields ........:
; Author ........:
; Remarks .......:
; Related .......:
; ===============================================================================================================================</syntaxhighlight>

== Variables ==
For code readability, there are special rules dealing with variables, particularly naming. All variables should be declared at the beginning of their scope, which usually means at the start of the function in which they are used, but could mean the top of the UDF itself in the [[#Variables|Variables section]].

=== Naming ===
A variable's first letter signifies the expected type of the variable. This should be as follows:

* <code>$a<letter></code> - Array (the following letter describes the data type taken from the rest of the data types below, if it varies then <code>v</code> should be used. A counter as the first element is ignored, so the array returned by StringSplit (with default options) would actually be marked as $as despite the integer in the zeroeth element).
* <code>$d</code> - Binary data.
* <code>$h</code> - Handle, usually to a file or window. NB: AutoIt handled controls return IDs, and so use $id instead.
* <code>$id</code> - An AutoIt control Id.
* <code>$i</code> - Integer.
* <code>$b</code> - Boolean.
* <code>$f</code> - Floating point number.
* <code>$n</code> - general number with no preference for floating point or integer.
* <code>$s</code> - String.
* <code>$v</code> - Variant (unknown/variable type of data) .
* <code>$p</code> - Pointer. It is assumed that it points to a struct so no further letters are needed. The type of struct being pointed to should be inferrable from the variable name e.g. <code>$pWindowRect</code> can be assumed to be a pointer to a <code>$tagRECT</code> structure.
* <code>$t</code> - Structure returned from DllStructCreate.
* <code>$tag</code> - Struct definition string.Structure definitions should conform to the structure guidelines.

=== Globals ===
The use of globals in a UDF is generally frowned upon, and byref parameters and static variables should be used where possible instead. However, in cases where this is not possible and a global must be used they should be defined using the following naming pattern: <code>$__g<VARNAME>_<UDF></code> where <code><VARNAME></code> is the name as it would usually appear according to the variable naming rules above and <code><UDF></code> is the name of the library in which it appears. This ensures there will never be a conflict with user variables of other UDF globals. They should be declared at the top of the UDF in the Variables section.

Globals are always private. If they need to be accessed by the user then functions need to be written wrapping that operation and values should be checked. Notable exceptions are debug variables, which are designed for developer purposes and may be used by some users in extreme cases. These are named <code>$Debug_<UDF></code> although the <code><UDF></code> part is often shortened so <code>GUIEdit.au3</code> uses <code>$Debug_Ed</code>. It is not required that a UDF has debugging symbols, but they are allowed to remain in releases.

=== Constants ===
There are two types of constants, internal and public. Public constants are designed to be utilised by the user, and are referenced in functions that use them. They include styles and flags. Internal constants are designed for use only within the library, so that values used fairly often can be held in one place to allow for easy updating. Both kinds of constant are always typed in all upper case. Constants taken from the windows API should appear exactly as they are defined there, but internal constants follow the naming pattern: <code>$__<UDF>CONSTANT_<NAME></code>.

=== The <code>Dim</code> statement ===
Should not be used.

== Examples ==
All functions and structures that are made public to the user need to have a good quality example. This means that it should:

* Be simple. Ideally the only functions used are basic functions like ConsoleWrite and MsgBox and the function that the example is written for. Writing a single example that covers a wide range of functions is not nearly as easy to use as writing an example per function that clearly demonstrates its use.
* Be readable. Everything should be explained step by step in comments.
* Be correct. In addition to passing the same Au3Check flags as the UDF itself (<code>-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7</code>) it should always be written with best practice being the main consideration. This takes preference over the first point, just because code is shorter and looks easier doesn't mean it's right.
* Examples should represent all the functionality. If there is more than one way of using a function then include more than one example of how to use it.

Examples are stored in individual files called <code><FUNCTION>.au3</code>. The files should be kept in a folder called <code>Examples</code>. To remain correct all examples should be wrapped in functions, such that the only code executed in the global scope is calling the function. This is usually named <code>Example</code>, though where multiple examples exists they are named <code>Example1</code>, <code>Example2</code>, ..., <code>ExampleN</code>.

<syntaxhighlight lang="autoit">#include <GUIConstantsEx.au3>

Opt("MustDeclareVars", 1)

Example()

Func Example()
Local $idButton_1, $idButton_2, $iMsg, $hGUI

$hGUI = GUICreate("My GUI Button") ; Will create a dialog box that when displayed is centered

$idButton_1 = GUICtrlCreateButton("Run Notepad", 4, 4, 80, 30)
$idButton_2 = GUICtrlCreateButton("Button Test", 4, 38, 80, 30)

GUISetState() ; will display a dialog box with 2 button

; Run the GUI until the dialog is closed
While 1
$iMsg = GUIGetMsg()
Select
Case $iMsg = $GUI_EVENT_CLOSE
ExitLoop
Case $iMsg = $idButton_1
Run("Notepad.exe") ; Will Run/Open Notepad
Case $iMsg = $idButton_2
MsgBox(0, "Testing", "Button 2 was pressed") ; Will demonstrate Button 2 being pressed
EndSelect
WEnd
GUIDelete($hGUI)
EndFunc ;==>Example</syntaxhighlight>

== Template UDF ==
Here is an example of a UDF called <code>MyUDF.au3</code>:

<syntaxhighlight lang="autoit">#include-once

#include "MyUDFConstants.au3"
#include "AnInclude.au3"

; #INDEX# =======================================================================================================================
; Title .........: MyUDF
; AutoIt Version : 3.3.6.1
; Language ......: English
; Description ...: An example UDF that does very little.
; ===============================================================================================================================

; #CURRENT# =====================================================================================================================
;$tagMYSTRUCT
;_MyUDF_Function
; ===============================================================================================================================

; #STRUCTURE# ===================================================================================================================
; Name...........: $tagMYSTRUCT
; Description ...: An example of a structure.
; Fields ........: hFoo - A handle to foo that does something.
; iBar - An integer that does something.
; Author ........: Matt Diesel (Mat)
; Remarks .......:
; Related .......: _MyUDF_Function
; ===============================================================================================================================
Global Const $tagMYSTRUCT = "ptr hFoo; int iBar"

; #FUNCTION# ====================================================================================================================
; Name...........: _MyUDF_Function
; Description ...: A function that does something.
; Syntax.........: _MyUDF_Function(ByRef $avAnArray, $iAnInt[, $hAHandle = 0[, $nSomeNumber = 42]])
; Parameters ....: $avAnArray - [byref] An array of anything. The value of anything is changed and passed out using this
; parameter. The array should only have one dimension
; $iAnInt - An integer that does very little.
; $hAHandle - [optional] A handle. Default is zero.
; $nSomeNumber - [optional] A number of some kind. Default is 42.
; Return values .: Success - A MYSTRUCT structure.
; Failure - Returns zero and sets the @error flag:
; |1 - The $avAnArray is invalid.
; Author ........: Matt Diesel (Mat)
; Modified.......:
; Remarks .......:
; Related .......: $tagMYSTRUCT
; Link ..........:
; Example .......: No
; ===============================================================================================================================
Func _MyUDF_Function(ByRef $avAnArray, $iAnInt, $hAHandle = 0, $nSomeNumber = 42)
; 1 - Error Checking for parameters.
If Not IsArray($avAnArray) Or UBound($avAnArray, 0) <> 1 Then Return SetError(1, 0, 0) ; The $avAnArray is invalid.

; 2 - Declaration of locals.
Local $tMS = DllStructCreate($tagMYSTRUCT)

; 3 - Function code
DllStructSetData($tMS, "hFoo", $hAHandle)
DllStructSetData($tMS, "iBar", $iAnInt * $nSomeNumber)

Return $tMS
EndFunc ;==>_MyUDF_Function</syntaxhighlight>

UDF-spec

2012-12-26T21:05:38Z

BrewManNH: /* Naming */

[[Category:UDF]]
{{WIP}}This page is still under construction.

----

A library is a collection of one or more User Defined Functions (UDFs). However, the term UDF is often used to describe the collection as a whole. If a UDF is to be considered for inclusion in the standard set distributed with AutoIt then it must meet all the criteria detailed here, but it's also good practice to always write in conformance with at least the majority of this document, as that is what will be expected by people reading your code later.

== Basic Requirements ==
Firstly, the code itself should meet the following basic requirements:

* Be tidied. Just hit <code>Ctrl+T</code> from SciTE or run Tidy manually. The only flag needed is <code>/sf</code>.
* Pass Au3Check with no errors using the strictest settings: <code>-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7</code>
* Support everything AutoIt supports. In some cases features may not be able to support everything, in which case this should be checked for and return errors appropriately. This applies to: windows OS versions (AutoIt has support for all OS' from windows 2000), unicode and ansi strings, 64 and 32 bit machines.
* Ideally it will be able to run cleanly when obfuscated. Although there will be some cases where this is not possible, please consider it when writing UDFs, and avoid the use of Execute and similar statements. If it does not, then document it as such.

== UDF Outline ==
The library itself has a header that details important information such as the minimum OS and AutoIt versions, and what system dlls are required. There is also a number of other sections that are required that list what is present in the UDF.

=== Includes ===
Since a UDF is designed to define functions, it should only be included once. As a result, the <code>#include-once</code> directive should be used. This is typically the first line of the UDF, followed by the includes used by the UDF. Include statements should use the double quoted form, as the library is expected to work in the same directory as libraries it depends on. Non standard libraries can be used if necessary, but this should be documented and linked to so users can download it as well. It goes without saying that a UDF based on non-standard UDFs cannot itself become a standard.

=== Index ===
The index follows the following template (taken from <code>WinAPI.au3</code>):

<syntaxhighlight lang="autoit">; #INDEX# =======================================================================================================================
; Title .........: Windows API
; AutoIt Version : 3.2
; Description ...: Windows API calls that have been translated to AutoIt functions.
; Author(s) .....: Paul Campbell (PaulIA), gafrost, Siao, Zedna, arcker, Prog@ndy, PsaltyDS, Raik, jpm
; Dll ...........: kernel32.dll, user32.dll, gdi32.dll, comdlg32.dll, shell32.dll, ole32.dll, winspool.drv
; ===============================================================================================================================</syntaxhighlight>

The only required element in the index header is <code>Title</code>. All others are ignored by the processor, but should be included for reference

The <code>Dll</code> field can remain empty in many cases where no dlls are called directly. This header must be defined.

=== Other Sections ===
Other sections, in order of appearance, are as follows.

==== Variables ====
All global variables needed to be declared in the UDF are defined in this section. They should follow the variable rules for globals. Individual variables do not need to be documented, as it is assumed they are for internal use only. Any globals designed to be accessible for the user should instead be wrapped by a function (or multiple functions if globals must be retrieved and set). The template for this section is:

<syntaxhighlight lang="autoit">; #VARIABLES# ===================================================================================================================
Global $__gvMyGlobal = 0
; ===============================================================================================================================</syntaxhighlight>

If no globals are needed then this section may be ommitted. Please consider the use of global variables carefully, and read through the section on global variables.

==== Constants ====
Any global constant values are defined in this section. This should be constants only designated for use within the library itself. Constants that may be needed by the user should be defined in a seperate file, named <code>UDFConstants.au3</code> where <code>UDF</code> is the name of the parent file. For example <code>File.au3</code> uses constants defined in <code>FileConstants.au3</code>. The exception to that rule is control UDFs which miss out the prepended 'GUI' when naming constant files, so <code>GUIButton.au3</code> uses constants from <code>ButtonConstants.au3</code>. The template for this section is:

<syntaxhighlight lang="autoit">; #CONSTANTS# ===================================================================================================================
Global Const $__MYUDFCONSTANT_FOOBAR = 42
; ===============================================================================================================================</syntaxhighlight>

If no constants are needed in this section, either because non are used or because they are stored in a seperate file, then it may be ommitted. Please read the section on global constants for specific info on naming and definition of constants.

==== Listing ====
This defines all functions and structures currently used functions in the library. It MUST be the second defined header item after [[#Index]]. It is a simple list with each function on a line where the functions and structures appear in the same order as they do in the code, which is alphabetical order and structures first. A simple way to generate this list is to create a small script that searches for function definitions and outputs them in the correct format, an example of which is [http://www.autoitscript.com/forum/topic/120820-function-name-lister/ here]. In addition there is a second section that lists functions and structures for internal use only, this does not need to appear if none are defined.

The template for these sections are:

<syntaxhighlight lang="autoit">; #CURRENT# =====================================================================================================================
;$tagSTRUCT
;_MyUDF_Function
; ===============================================================================================================================

; #INTERNAL_USE_ONLY# ===========================================================================================================
;$tagINTERNALSTRUCT
;__MyUDF_InternalFunction
; ===============================================================================================================================</syntaxhighlight>

This section still needs to be defined for files that only define constants. It should also be noted that there MUST NOT be a space between the <code>;</code> and the function/structure name.

==== Undocumented Listing ====
There is a final kind of listing that lists functions for which no documentation exists, or they have been deprecated and are only included for backwards compatibility. These are listed in a section with the header <code>NO_DOC_FUNCTION</code>. This is very rarely used, and is reserved only for functions that can be utilised by the user, or that would have been in the past, as opposed to those for internal use only.

Template:

<syntaxhighlight lang="autoit">; #NO_DOC_FUNCTION# =============================================================================================================
;_MyUDF_Function
; ===============================================================================================================================</syntaxhighlight>

==== Renamed Functions ====
Although it should not be the case in new UDFs, many of the older ones (particularly to do with controls) have had script breaking name changes to functions. These are documented in the UDF to ensure updating old scripts is as easy as possible. The basic format for this is:

<syntaxhighlight lang="autoit">; #NO_DOC_FUNCTION# =============================================================================================================
;_MyUDF_OldFunction ; --> _MyUDF_NewFunction
; ===============================================================================================================================</syntaxhighlight>

The space padding is optional. This section is ignored as far as the docs are concerned, and is usually omitted.

== Functions ==
=== Naming ===
Function names must start with an underscore, and the first word is the library name. There is then usually another underscore before the rest of the function name. The library name should be consistent across all the functions in the library, and can be shortened if a logical abbreviation is available (e.g. <code>Window</code> ==> <code>Win</code>). Each word should be capitalized, but no underscores are placed in the rest of the name, for example <code>_WinAPI_GetWindowLong</code>.

For control libraries, the first part of the function name is changed slightly. For example the UDF for listviews would use <code>_GUICtrlListview_*</code>. When a function wraps a dll call, then the second part should closely resemble the function name as it appears in other languages. This also applies to functions acting as a wrapper to <code>SendMessage</code>.

Functions are defined in alphabetical order by name, which is the same as using <code>Tidy</code> with the <code>/sf</code> flag set.

=== Parameters ===
Parameters should follow the variable naming scheme ([[#Naming_2|here]]). All parameters must be checked to ensure they are valid, and return unique and documented error codes if they are not. For functions involving a specific type of control, this includes checking the class name using <code>_WinAPI_IsClassName</code>.

Parameters that are optional or byref should be documented as such, and the effect these have explicitly stated. For example a byref parameter should detail exactly what the expected output is as well as the input.

=== Headers ===
All functions have a documentation header that describes the function. This uses the following template:

<syntaxhighlight lang="autoit">; #FUNCTION# ====================================================================================================================
; Name...........: _WinAPI_GetMousePos
; Description ...: Returns the current mouse position
; Syntax.........: _WinAPI_GetMousePos([$fToClient = False[, $hWnd = 0]])
; Parameters ....: $fToClient - If True, the coordinates will be converted to client coordinates
; $hWnd - Window handle used to convert coordinates if $fToClient is True
; Return values .: Success - $tagPOINT structure with current mouse position
; Failure - Zero
; Author ........: Paul Campbell (PaulIA)
; Modified.......:
; Remarks .......: This function takes into account the current MouseCoordMode setting when obtaining the mouse position. It
; will also convert screen to client coordinates based on the parameters passed.
; Related .......: $tagPOINT, _WinAPI_GetMousePosX, _WinAPI_GetMousePosY
; Link ..........:
; Example .......: Yes
; ===============================================================================================================================
Func _WinAPI_GetMousePos($fToClient = False, $hWnd = 0)</syntaxhighlight>

The header is 129 characters wide, and any text within it should be wrapped to that length. For example the <code>Remarks</code> in the above header has been extended to cover two lines. The exception to that rule is the <code>Syntax</code> line, which should not be wrapped. Some of the parameters in the header are optional, in which case they should remain, but be left empty (for example the <code>Link</code> and <code>Modified</code> lines in the above header). In others, they are needed, but can be empty or not used such as <code>Parameters</code> or <code>Return Values</code>. In this case the value should be 'None', as they will still be present in the documentation.

There are some flags that can be used within function headers:

* '''+''' in column 20 is the continuation flag for the previous line (used in Parameters, Return Values)
* '''|''' in column 20 is a new line in the right side of the table when the help file is generated (used in Parameters, Return Values)
* '''-''' in column 20 will create new row in the table, used for things like Defaults for a style (used in Parameters, Return Values)
* '''+''' in column 2 of Remarks is a blank line
Name
:Specifies the name of the function. This will be identical to how it appeas in the Func statement in the code itself.
Description
:Gives a short summary of what the function does. This should only be a single line, as it is only designed to give a short impression of what is happening. For the standard set of includes distributed with AutoIt3, this value is also used in the SciTE calltips.
Syntax
:Describes the syntax of the function call. This differs slightly from what appears in the code itself for optional parameters, which are enclosed in square brackets ("[ ]"). Since subsequent parameters must also be optional, and cannot be defined unless all the previous ones have been given, these brackets are nested in the form: Function([param1[, param2[,param3]]]). Note that the opening bracket appears before the comma seperator.
Parameters
:This is a list of the arguments accepted by the function. Each is listed, followed by a dash ("-") and a description of what it is. The dash can be padded for neatness, although the amount of padding depends on how long the parameter names are. If the parameter is optional then the meaning of the default value should be given, similarly if it's used to pass data back to the program in the form of byref then the changes made should also be detailed. For more information on parameters see Parameters.
Return values
:Details what is returned by the function. This often comes in the form of Success and Failure values, but this is not always the case. Any setting of the @error of @extended flags should be detailed, along with their meanings, in some cases it is enough to say that @error is set to non-zero in the event of an error, in most cases though a list of values for @error should be given.
Author
:This is the original writer of the function. It should contain the username, so that any queries about the code can be made through the forum, but you can give as much or little information as you feel appropriate.
Modified
:This is a list of modifications made. At it's most basic this is just a list of users who have made changes, but ideally it includes some information about what they did, in which cases it follows the same form as other multi-value lines, with the username and description of modifications seperated by a dash.
Remarks
:This is anything the user should know about a function in order to use it. For example exceptional cases and recommended ways to handle the function should all be detailed here, as well as additional info about possible reasons for failure and how to deal with them.
Related
:A comma seperated list of functions or structures related to the function.
Link
:A link to additional information about the function. For many system function wrappers, this will be <code>@@MsdnLink@@ FunctionName</code>, which represents that the user should search MSDN for the function.
Example
:A simple yes or no value specifying whether the function has an example. If this is no then your UDF is not ready to be released. The [[#Examples]] section has more information on the format and location of examples.

The easiest way to generate the header is to copy and paste the following blank template in:

<syntaxhighlight lang="autoit">; #FUNCTION# ====================================================================================================================
; Name...........:
; Description ...:
; Syntax.........:
; Parameters ....:
; Return values .:
; Author ........:
; Modified.......:
; Remarks .......:
; Related .......:
; Link ..........:
; Example .......:
; ===============================================================================================================================</syntaxhighlight>

There are also a number of plugins for SciTE that will generate a header and maybe fill in certain known values for you such as Name, Syntax and Parameters. The most complete one that conforms to these standards is [http://code.google.com/p/m-a-t/wiki/UDFHeaderGenerator here], but there are two others [http://www.autoitscript.com/forum/topic/28270-lua-script-for-udf-header/ here] and [http://www.autoitscript.com/forum/topic/28270-lua-script-for-udf-header/page__view__findpost__p__200823 here].

=== Internal use only ===
Functions can also be marked for use only within the library and not to be documented for use by the user. These are named according to the same rules as normal functions but begin with a double underscore ("__"). The header is exactly the same except with the first line replaced, to make the blank template:

<syntaxhighlight lang="autoit">; #INTERNAL_USE_ONLY# ===========================================================================================================
; Name...........:
; Description ...:
; Syntax.........:
; Parameters ....:
; Return values .:
; Author ........:
; Modified.......:
; Remarks .......:
; Related .......:
; Link ..........:
; Example .......:
; ===============================================================================================================================</syntaxhighlight>

== Structures ==
Structures are defined as global constants, and follow the naming pattern <code>$tagSTRUCTNAME</code>. The struct name should be as it appears on MSDN if it's used in the windows API, or follow a similar pattern if not. It should go without saying that they must work for both 32 and 64 bit machines, including resolving any alignment issues. Elements should also be named as they appear on MSDN if they are taken from there, which includes the hungarian notation prefix. Although many standard UDFs do not follow that rule, importantly <code>StructureConstants.au3</code>, the rule still stands.

=== Headers ===
Structures need a header similar to functions, but with some minor differences. The same rules apply in terms of wrapping and line length however. The header follow this standard template:

<syntaxhighlight lang="autoit">; #STRUCTURE# ===================================================================================================================
; Name...........: $tagPOINT
; Description ...: Defines the x and y coordinates of a point
; Fields ........: X - Specifies the x-coordinate of the point
; Y - Specifies the y-coordinate of the point
; Author ........: Paul Campbell (PaulIA)
; Remarks .......:
; Related .......:
; ===============================================================================================================================
Global Const $tagPOINT = "long X;long Y"</syntaxhighlight>

It is essentially a shortened header, with the only thing new is the Fields line, which effectively replaces the Parameters field in terms of usage. All the same rules apply as listed [[#Function Header Fields|here]].

The blank template is:

<syntaxhighlight lang="autoit">; #STRUCTURE# ===================================================================================================================
; Name...........:
; Description ...:
; Fields ........:
; Author ........:
; Remarks .......:
; Related .......:
; ===============================================================================================================================</syntaxhighlight>

Structures may also be marked for internal use only. In this case the header ramains the same, but the sections first line changes. The blank template is:

<syntaxhighlight lang="autoit">; #INTERNAL_USE_ONLY# ===========================================================================================================
; Name...........:
; Description ...:
; Fields ........:
; Author ........:
; Remarks .......:
; Related .......:
; ===============================================================================================================================</syntaxhighlight>

== Variables ==
For code readability, there are special rules dealing with variables, particularly naming. All variables should be declared at the beginning of their scope, which usually means at the start of the function in which they are used, but could mean the top of the UDF itself in the [[#Variables|Variables section]].

=== Naming ===
A variable's first letter signifies the expected type of the variable. This should be as follows:

* <code>$a<letter></code> - Array (the following letter describes the data type taken from the rest of the data types below, if it varies then <code>v</code> should be used. A counter as the first element is ignored, so the array returned by StringSplit (with default options) would actually be marked as $as despite the integer in the zeroeth element).
* <code>$d</code> - Binary data.
* <code>$h</code> - Handle, usually to a file or window. NB: AutoIt handled controls return IDs, and so use $id instead.
* <code>$id</code> - An AutoIt control Id.
* <code>$i</code> - Integer.
* <code>$b</code> - Boolean.
* <code>$f</code> - Floating point number.
* <code>$n</code> - general number with no preference for floating point or integer.
* <code>$s</code> - String.
* <code>$v</code> - Variant (unknown/variable type of data) .
* <code>$p</code> - Pointer. It is assumed that it points to a struct so no further letters are needed. The type of struct being pointed to should be inferrable from the variable name e.g. <code>$pWindowRect</code> can be assumed to be a pointer to a <code>$tagRECT</code> structure.
* <code>$t</code> - Structure returned from DllStructCreate.
* <code>$tag</code> - Struct definition string.Structure definitions should conform to the structure guidelines.

=== Globals ===
The use of globals in a UDF is generally frowned upon, and byref parameters and static variables should be used where possible instead. However, in cases where this is not possible and a global must be used they should be defined using the following naming pattern: <code>$__g<VARNAME>_<UDF></code> where <code><VARNAME></code> is the name as it would usually appear according to the variable naming rules above and <code><UDF></code> is the name of the library in which it appears. This ensures there will never be a conflict with user variables of other UDF globals. They should be declared at the top of the UDF in the Variables section.

Globals are always private. If they need to be accessed by the user then functions need to be written wrapping that operation and values should be checked. Notable exceptions are debug variables, which are designed for developer purposes and may be used by some users in extreme cases. These are named <code>$Debug_<UDF></code> although the <code><UDF></code> part is often shortened so <code>GUIEdit.au3</code> uses <code>$Debug_Ed</code>. It is not required that a UDF has debugging symbols, but they are allowed to remain in releases.

=== Constants ===
There are two types of constants, internal and public. Public constants are designed to be utilised by the user, and are referenced in functions that use them. They include styles and flags. Internal constants are designed for use only within the library, so that values used fairly often can be held in one place to allow for easy updating. Both kinds of constant are always typed in all upper case. Constants taken from the windows API should appear exactly as they are defined there, but internal constants follow the naming pattern: <code>$__<UDF>CONSTANT_<NAME></code>.

=== The <code>Dim</code> statement ===
Should not be used.

== Examples ==
All functions and structures that are made public to the user need to have a good quality example. This means that it should:

* Be simple. Ideally the only functions used are basic functions like ConsoleWrite and MsgBox and the function that the example is written for. Writing a single example that covers a wide range of functions is not nearly as easy to use as writing an example per function that clearly demonstrates its use.
* Be readable. Everything should be explained step by step in comments.
* Be correct. In addition to passing the same Au3Check flags as the UDF itself (<code>-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7</code>) it should always be written with best practice being the main consideration. This takes preference over the first point, just because code is shorter and looks easier doesn't mean it's right.
* Examples should represent all the functionality. If there is more than one way of using a function then include more than one example of how to use it.

Examples are stored in individual files called <code><FUNCTION>.au3</code>. The files should be kept in a folder called <code>Examples</code>. To remain correct all examples should be wrapped in functions, such that the only code executed in the global scope is calling the function. This is usually named <code>Example</code>, though where multiple examples exists they are named <code>Example1</code>, <code>Example2</code>, ..., <code>ExampleN</code>.

<syntaxhighlight lang="autoit">#include <GUIConstantsEx.au3>

Opt("MustDeclareVars", 1)

Example()

Func Example()
Local $idButton_1, $idButton_2, $iMsg, $hGUI

$hGUI = GUICreate("My GUI Button") ; Will create a dialog box that when displayed is centered

$idButton_1 = GUICtrlCreateButton("Run Notepad", 4, 4, 80, 30)
$idButton_2 = GUICtrlCreateButton("Button Test", 4, 38, 80, 30)

GUISetState() ; will display a dialog box with 2 button

; Run the GUI until the dialog is closed
While 1
$iMsg = GUIGetMsg()
Select
Case $iMsg = $GUI_EVENT_CLOSE
ExitLoop
Case $iMsg = $idButton_1
Run("Notepad.exe") ; Will Run/Open Notepad
Case $iMsg = $idButton_2
MsgBox(0, "Testing", "Button 2 was pressed") ; Will demonstrate Button 2 being pressed
EndSelect
WEnd
GUIDelete($hGUI)
EndFunc ;==>Example</syntaxhighlight>

== Template UDF ==
Here is an example of a UDF called <code>MyUDF.au3</code>:

<syntaxhighlight lang="autoit">#include-once

#include "MyUDFConstants.au3"
#include "AnInclude.au3"

; #INDEX# =======================================================================================================================
; Title .........: MyUDF
; AutoIt Version : 3.3.6.1
; Language ......: English
; Description ...: An example UDF that does very little.
; ===============================================================================================================================

; #CURRENT# =====================================================================================================================
;$tagMYSTRUCT
;_MyUDF_Function
; ===============================================================================================================================

; #STRUCTURE# ===================================================================================================================
; Name...........: $tagMYSTRUCT
; Description ...: An example of a structure.
; Fields ........: hFoo - A handle to foo that does something.
; iBar - An integer that does something.
; Author ........: Matt Diesel (Mat)
; Remarks .......:
; Related .......: _MyUDF_Function
; ===============================================================================================================================
Global Const $tagMYSTRUCT = "ptr hFoo; int iBar"

; #FUNCTION# ====================================================================================================================
; Name...........: _MyUDF_Function
; Description ...: A function that does something.
; Syntax.........: _MyUDF_Function(ByRef $avAnArray, $iAnInt[, $hAHandle = 0[, $nSomeNumber = 42]])
; Parameters ....: $avAnArray - [byref] An array of anything. The value of anything is changed and passed out using this
; parameter. The array should only have one dimension
; $iAnInt - An integer that does very little.
; $hAHandle - [optional] A handle. Default is zero.
; $nSomeNumber - [optional] A number of some kind. Default is 42.
; Return values .: Success - A MYSTRUCT structure.
; Failure - Returns zero and sets the @error flag:
; |1 - The $avAnArray is invalid.
; Author ........: Matt Diesel (Mat)
; Modified.......:
; Remarks .......:
; Related .......: $tagMYSTRUCT
; Link ..........:
; Example .......: No
; ===============================================================================================================================
Func _MyUDF_Function(ByRef $avAnArray, $iAnInt, $hAHandle = 0, $nSomeNumber = 42)
; 1 - Error Checking for parameters.
If Not IsArray($avAnArray) Or UBound($avAnArray, 0) <> 1 Then Return SetError(1, 0, 0) ; The $avAnArray is invalid.

; 2 - Declaration of locals.
Local $tMS = DllStructCreate($tagMYSTRUCT)

; 3 - Function code
DllStructSetData($tMS, "hFoo", $hAHandle)
DllStructSetData($tMS, "iBar", $iAnInt * $nSomeNumber)

Return $tMS
EndFunc ;==>_MyUDF_Function</syntaxhighlight>

UDF-spec

2012-12-26T21:02:19Z

BrewManNH: /* Examples */

[[Category:UDF]]
{{WIP}}This page is still under construction.

----

A library is a collection of one or more User Defined Functions (UDFs). However, the term UDF is often used to describe the collection as a whole. If a UDF is to be considered for inclusion in the standard set distributed with AutoIt then it must meet all the criteria detailed here, but it's also good practice to always write in conformance with at least the majority of this document, as that is what will be expected by people reading your code later.

== Basic Requirements ==
Firstly, the code itself should meet the following basic requirements:

* Be tidied. Just hit <code>Ctrl+T</code> from SciTE or run Tidy manually. The only flag needed is <code>/sf</code>.
* Pass Au3Check with no errors using the strictest settings: <code>-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7</code>
* Support everything AutoIt supports. In some cases features may not be able to support everything, in which case this should be checked for and return errors appropriately. This applies to: windows OS versions (AutoIt has support for all OS' from windows 2000), unicode and ansi strings, 64 and 32 bit machines.
* Ideally it will be able to run cleanly when obfuscated. Although there will be some cases where this is not possible, please consider it when writing UDFs, and avoid the use of Execute and similar statements. If it does not, then document it as such.

== UDF Outline ==
The library itself has a header that details important information such as the minimum OS and AutoIt versions, and what system dlls are required. There is also a number of other sections that are required that list what is present in the UDF.

=== Includes ===
Since a UDF is designed to define functions, it should only be included once. As a result, the <code>#include-once</code> directive should be used. This is typically the first line of the UDF, followed by the includes used by the UDF. Include statements should use the double quoted form, as the library is expected to work in the same directory as libraries it depends on. Non standard libraries can be used if necessary, but this should be documented and linked to so users can download it as well. It goes without saying that a UDF based on non-standard UDFs cannot itself become a standard.

=== Index ===
The index follows the following template (taken from <code>WinAPI.au3</code>):

<syntaxhighlight lang="autoit">; #INDEX# =======================================================================================================================
; Title .........: Windows API
; AutoIt Version : 3.2
; Description ...: Windows API calls that have been translated to AutoIt functions.
; Author(s) .....: Paul Campbell (PaulIA), gafrost, Siao, Zedna, arcker, Prog@ndy, PsaltyDS, Raik, jpm
; Dll ...........: kernel32.dll, user32.dll, gdi32.dll, comdlg32.dll, shell32.dll, ole32.dll, winspool.drv
; ===============================================================================================================================</syntaxhighlight>

The only required element in the index header is <code>Title</code>. All others are ignored by the processor, but should be included for reference

The <code>Dll</code> field can remain empty in many cases where no dlls are called directly. This header must be defined.

=== Other Sections ===
Other sections, in order of appearance, are as follows.

==== Variables ====
All global variables needed to be declared in the UDF are defined in this section. They should follow the variable rules for globals. Individual variables do not need to be documented, as it is assumed they are for internal use only. Any globals designed to be accessible for the user should instead be wrapped by a function (or multiple functions if globals must be retrieved and set). The template for this section is:

<syntaxhighlight lang="autoit">; #VARIABLES# ===================================================================================================================
Global $__gvMyGlobal = 0
; ===============================================================================================================================</syntaxhighlight>

If no globals are needed then this section may be ommitted. Please consider the use of global variables carefully, and read through the section on global variables.

==== Constants ====
Any global constant values are defined in this section. This should be constants only designated for use within the library itself. Constants that may be needed by the user should be defined in a seperate file, named <code>UDFConstants.au3</code> where <code>UDF</code> is the name of the parent file. For example <code>File.au3</code> uses constants defined in <code>FileConstants.au3</code>. The exception to that rule is control UDFs which miss out the prepended 'GUI' when naming constant files, so <code>GUIButton.au3</code> uses constants from <code>ButtonConstants.au3</code>. The template for this section is:

<syntaxhighlight lang="autoit">; #CONSTANTS# ===================================================================================================================
Global Const $__MYUDFCONSTANT_FOOBAR = 42
; ===============================================================================================================================</syntaxhighlight>

If no constants are needed in this section, either because non are used or because they are stored in a seperate file, then it may be ommitted. Please read the section on global constants for specific info on naming and definition of constants.

==== Listing ====
This defines all functions and structures currently used functions in the library. It MUST be the second defined header item after [[#Index]]. It is a simple list with each function on a line where the functions and structures appear in the same order as they do in the code, which is alphabetical order and structures first. A simple way to generate this list is to create a small script that searches for function definitions and outputs them in the correct format, an example of which is [http://www.autoitscript.com/forum/topic/120820-function-name-lister/ here]. In addition there is a second section that lists functions and structures for internal use only, this does not need to appear if none are defined.

The template for these sections are:

<syntaxhighlight lang="autoit">; #CURRENT# =====================================================================================================================
;$tagSTRUCT
;_MyUDF_Function
; ===============================================================================================================================

; #INTERNAL_USE_ONLY# ===========================================================================================================
;$tagINTERNALSTRUCT
;__MyUDF_InternalFunction
; ===============================================================================================================================</syntaxhighlight>

This section still needs to be defined for files that only define constants. It should also be noted that there MUST NOT be a space between the <code>;</code> and the function/structure name.

==== Undocumented Listing ====
There is a final kind of listing that lists functions for which no documentation exists, or they have been deprecated and are only included for backwards compatibility. These are listed in a section with the header <code>NO_DOC_FUNCTION</code>. This is very rarely used, and is reserved only for functions that can be utilised by the user, or that would have been in the past, as opposed to those for internal use only.

Template:

<syntaxhighlight lang="autoit">; #NO_DOC_FUNCTION# =============================================================================================================
;_MyUDF_Function
; ===============================================================================================================================</syntaxhighlight>

==== Renamed Functions ====
Although it should not be the case in new UDFs, many of the older ones (particularly to do with controls) have had script breaking name changes to functions. These are documented in the UDF to ensure updating old scripts is as easy as possible. The basic format for this is:

<syntaxhighlight lang="autoit">; #NO_DOC_FUNCTION# =============================================================================================================
;_MyUDF_OldFunction ; --> _MyUDF_NewFunction
; ===============================================================================================================================</syntaxhighlight>

The space padding is optional. This section is ignored as far as the docs are concerned, and is usually omitted.

== Functions ==
=== Naming ===
Function names must start with an underscore, and the first word is the library name. There is then usually another underscore before the rest of the function name. The library name should be consistent across all the functions in the library, and can be shortened if a logical abbreviation is available (e.g. <code>Window</code> ==> <code>Win</code>). Each word should be capitalized, but no underscores are placed in the rest of the name, for example <code>_WinAPI_GetWindowLong</code>.

For control libraries, the first part of the function name is changed slightly. For example the UDF for listviews would use <code>_GUICtrlListview_*</code>. When a function wraps a dll call, then the second part should closely resemble the function name as it appears in other languages. This also applies to functions acting as a wrapper to <code>SendMessage</code>.

Functions are defined in alphabetical order by name, which is the same as using <code>Tidy</code> with the <code>/sf</code> flag set.

=== Parameters ===
Parameters should follow the variable naming scheme ([[#Naming_2|here]]). All parameters must be checked to ensure they are valid, and return unique and documented error codes if they are not. For functions involving a specific type of control, this includes checking the class name using <code>_WinAPI_IsClassName</code>.

Parameters that are optional or byref should be documented as such, and the effect these have explicitly stated. For example a byref parameter should detail exactly what the expected output is as well as the input.

=== Headers ===
All functions have a documentation header that describes the function. This uses the following template:

<syntaxhighlight lang="autoit">; #FUNCTION# ====================================================================================================================
; Name...........: _WinAPI_GetMousePos
; Description ...: Returns the current mouse position
; Syntax.........: _WinAPI_GetMousePos([$fToClient = False[, $hWnd = 0]])
; Parameters ....: $fToClient - If True, the coordinates will be converted to client coordinates
; $hWnd - Window handle used to convert coordinates if $fToClient is True
; Return values .: Success - $tagPOINT structure with current mouse position
; Failure - Zero
; Author ........: Paul Campbell (PaulIA)
; Modified.......:
; Remarks .......: This function takes into account the current MouseCoordMode setting when obtaining the mouse position. It
; will also convert screen to client coordinates based on the parameters passed.
; Related .......: $tagPOINT, _WinAPI_GetMousePosX, _WinAPI_GetMousePosY
; Link ..........:
; Example .......: Yes
; ===============================================================================================================================
Func _WinAPI_GetMousePos($fToClient = False, $hWnd = 0)</syntaxhighlight>

The header is 129 characters wide, and any text within it should be wrapped to that length. For example the <code>Remarks</code> in the above header has been extended to cover two lines. The exception to that rule is the <code>Syntax</code> line, which should not be wrapped. Some of the parameters in the header are optional, in which case they should remain, but be left empty (for example the <code>Link</code> and <code>Modified</code> lines in the above header). In others, they are needed, but can be empty or not used such as <code>Parameters</code> or <code>Return Values</code>. In this case the value should be 'None', as they will still be present in the documentation.

There are some flags that can be used within function headers:

* '''+''' in column 20 is the continuation flag for the previous line (used in Parameters, Return Values)
* '''|''' in column 20 is a new line in the right side of the table when the help file is generated (used in Parameters, Return Values)
* '''-''' in column 20 will create new row in the table, used for things like Defaults for a style (used in Parameters, Return Values)
* '''+''' in column 2 of Remarks is a blank line
Name
:Specifies the name of the function. This will be identical to how it appeas in the Func statement in the code itself.
Description
:Gives a short summary of what the function does. This should only be a single line, as it is only designed to give a short impression of what is happening. For the standard set of includes distributed with AutoIt3, this value is also used in the SciTE calltips.
Syntax
:Describes the syntax of the function call. This differs slightly from what appears in the code itself for optional parameters, which are enclosed in square brackets ("[ ]"). Since subsequent parameters must also be optional, and cannot be defined unless all the previous ones have been given, these brackets are nested in the form: Function([param1[, param2[,param3]]]). Note that the opening bracket appears before the comma seperator.
Parameters
:This is a list of the arguments accepted by the function. Each is listed, followed by a dash ("-") and a description of what it is. The dash can be padded for neatness, although the amount of padding depends on how long the parameter names are. If the parameter is optional then the meaning of the default value should be given, similarly if it's used to pass data back to the program in the form of byref then the changes made should also be detailed. For more information on parameters see Parameters.
Return values
:Details what is returned by the function. This often comes in the form of Success and Failure values, but this is not always the case. Any setting of the @error of @extended flags should be detailed, along with their meanings, in some cases it is enough to say that @error is set to non-zero in the event of an error, in most cases though a list of values for @error should be given.
Author
:This is the original writer of the function. It should contain the username, so that any queries about the code can be made through the forum, but you can give as much or little information as you feel appropriate.
Modified
:This is a list of modifications made. At it's most basic this is just a list of users who have made changes, but ideally it includes some information about what they did, in which cases it follows the same form as other multi-value lines, with the username and description of modifications seperated by a dash.
Remarks
:This is anything the user should know about a function in order to use it. For example exceptional cases and recommended ways to handle the function should all be detailed here, as well as additional info about possible reasons for failure and how to deal with them.
Related
:A comma seperated list of functions or structures related to the function.
Link
:A link to additional information about the function. For many system function wrappers, this will be <code>@@MsdnLink@@ FunctionName</code>, which represents that the user should search MSDN for the function.
Example
:A simple yes or no value specifying whether the function has an example. If this is no then your UDF is not ready to be released. The [[#Examples]] section has more information on the format and location of examples.

The easiest way to generate the header is to copy and paste the following blank template in:

<syntaxhighlight lang="autoit">; #FUNCTION# ====================================================================================================================
; Name...........:
; Description ...:
; Syntax.........:
; Parameters ....:
; Return values .:
; Author ........:
; Modified.......:
; Remarks .......:
; Related .......:
; Link ..........:
; Example .......:
; ===============================================================================================================================</syntaxhighlight>

There are also a number of plugins for SciTE that will generate a header and maybe fill in certain known values for you such as Name, Syntax and Parameters. The most complete one that conforms to these standards is [http://code.google.com/p/m-a-t/wiki/UDFHeaderGenerator here], but there are two others [http://www.autoitscript.com/forum/topic/28270-lua-script-for-udf-header/ here] and [http://www.autoitscript.com/forum/topic/28270-lua-script-for-udf-header/page__view__findpost__p__200823 here].

=== Internal use only ===
Functions can also be marked for use only within the library and not to be documented for use by the user. These are named according to the same rules as normal functions but begin with a double underscore ("__"). The header is exactly the same except with the first line replaced, to make the blank template:

<syntaxhighlight lang="autoit">; #INTERNAL_USE_ONLY# ===========================================================================================================
; Name...........:
; Description ...:
; Syntax.........:
; Parameters ....:
; Return values .:
; Author ........:
; Modified.......:
; Remarks .......:
; Related .......:
; Link ..........:
; Example .......:
; ===============================================================================================================================</syntaxhighlight>

== Structures ==
Structures are defined as global constants, and follow the naming pattern <code>$tagSTRUCTNAME</code>. The struct name should be as it appears on MSDN if it's used in the windows API, or follow a similar pattern if not. It should go without saying that they must work for both 32 and 64 bit machines, including resolving any alignment issues. Elements should also be named as they appear on MSDN if they are taken from there, which includes the hungarian notation prefix. Although many standard UDFs do not follow that rule, importantly <code>StructureConstants.au3</code>, the rule still stands.

=== Headers ===
Structures need a header similar to functions, but with some minor differences. The same rules apply in terms of wrapping and line length however. The header follow this standard template:

<syntaxhighlight lang="autoit">; #STRUCTURE# ===================================================================================================================
; Name...........: $tagPOINT
; Description ...: Defines the x and y coordinates of a point
; Fields ........: X - Specifies the x-coordinate of the point
; Y - Specifies the y-coordinate of the point
; Author ........: Paul Campbell (PaulIA)
; Remarks .......:
; Related .......:
; ===============================================================================================================================
Global Const $tagPOINT = "long X;long Y"</syntaxhighlight>

It is essentially a shortened header, with the only thing new is the Fields line, which effectively replaces the Parameters field in terms of usage. All the same rules apply as listed [[#Function Header Fields|here]].

The blank template is:

<syntaxhighlight lang="autoit">; #STRUCTURE# ===================================================================================================================
; Name...........:
; Description ...:
; Fields ........:
; Author ........:
; Remarks .......:
; Related .......:
; ===============================================================================================================================</syntaxhighlight>

Structures may also be marked for internal use only. In this case the header ramains the same, but the sections first line changes. The blank template is:

<syntaxhighlight lang="autoit">; #INTERNAL_USE_ONLY# ===========================================================================================================
; Name...........:
; Description ...:
; Fields ........:
; Author ........:
; Remarks .......:
; Related .......:
; ===============================================================================================================================</syntaxhighlight>

== Variables ==
For code readability, there are special rules dealing with variables, particularly naming. All variables should be declared at the beginning of their scope, which usually means at the start of the function in which they are used, but could mean the top of the UDF itself in the [[#Variables|Variables section]].

=== Naming ===
A variables first letter signifies the expected type of the variable. This should be as follows:

* <code>$a<letter></code> - Array (the following letter describes the data type taken from the rest of the data types below, if it varies then <code>v</code> should be used. A counter as the first element is ignored, so the array returned by StringSplit (with default options) would actually be marked as $as despite the integer in the zeroeth element).
* <code>$d</code> - Binary data.
* <code>$h</code> - Handle, usually to a file or window. NB: AutoIt handled controls return IDs, and so use $id instead.
* <code>$id</code> - An AutoIt control Id.
* <code>$i</code> - Integer.
* <code>$b</code> - Boolean.
* <code>$f</code> - Floating point number.
* <code>$n</code> - general number with no preference for floating point or integral.
* <code>$s</code> - String.
* <code>$v</code> - Variant (unknown/variable type of data) .
* <code>$p</code> - Pointer. It is assumed that it points to a struct so no further letters are needed. The type of struct being pointed to should be inferrable from the variable name e.g. <code>$pWindowRect</code> can be assumed to be a pointer to a <code>$tagRECT</code> structure.
* <code>$t</code> - Structure returned from DllStructCreate.
* <code>$tag</code> - Struct definition string.Structure definitions should conform to the structure guidelines.

=== Globals ===
The use of globals in a UDF is generally frowned upon, and byref parameters and static variables should be used where possible instead. However, in cases where this is not possible and a global must be used they should be defined using the following naming pattern: <code>$__g<VARNAME>_<UDF></code> where <code><VARNAME></code> is the name as it would usually appear according to the variable naming rules above and <code><UDF></code> is the name of the library in which it appears. This ensures there will never be a conflict with user variables of other UDF globals. They should be declared at the top of the UDF in the Variables section.

Globals are always private. If they need to be accessed by the user then functions need to be written wrapping that operation and values should be checked. Notable exceptions are debug variables, which are designed for developer purposes and may be used by some users in extreme cases. These are named <code>$Debug_<UDF></code> although the <code><UDF></code> part is often shortened so <code>GUIEdit.au3</code> uses <code>$Debug_Ed</code>. It is not required that a UDF has debugging symbols, but they are allowed to remain in releases.

=== Constants ===
There are two types of constants, internal and public. Public constants are designed to be utilised by the user, and are referenced in functions that use them. They include styles and flags. Internal constants are designed for use only within the library, so that values used fairly often can be held in one place to allow for easy updating. Both kinds of constant are always typed in all upper case. Constants taken from the windows API should appear exactly as they are defined there, but internal constants follow the naming pattern: <code>$__<UDF>CONSTANT_<NAME></code>.

=== The <code>Dim</code> statement ===
Should not be used.

== Examples ==
All functions and structures that are made public to the user need to have a good quality example. This means that it should:

* Be simple. Ideally the only functions used are basic functions like ConsoleWrite and MsgBox and the function that the example is written for. Writing a single example that covers a wide range of functions is not nearly as easy to use as writing an example per function that clearly demonstrates its use.
* Be readable. Everything should be explained step by step in comments.
* Be correct. In addition to passing the same Au3Check flags as the UDF itself (<code>-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7</code>) it should always be written with best practice being the main consideration. This takes preference over the first point, just because code is shorter and looks easier doesn't mean it's right.
* Examples should represent all the functionality. If there is more than one way of using a function then include more than one example of how to use it.

Examples are stored in individual files called <code><FUNCTION>.au3</code>. The files should be kept in a folder called <code>Examples</code>. To remain correct all examples should be wrapped in functions, such that the only code executed in the global scope is calling the function. This is usually named <code>Example</code>, though where multiple examples exists they are named <code>Example1</code>, <code>Example2</code>, ..., <code>ExampleN</code>.

<syntaxhighlight lang="autoit">#include <GUIConstantsEx.au3>

Opt("MustDeclareVars", 1)

Example()

Func Example()
Local $idButton_1, $idButton_2, $iMsg, $hGUI

$hGUI = GUICreate("My GUI Button") ; Will create a dialog box that when displayed is centered

$idButton_1 = GUICtrlCreateButton("Run Notepad", 4, 4, 80, 30)
$idButton_2 = GUICtrlCreateButton("Button Test", 4, 38, 80, 30)

GUISetState() ; will display a dialog box with 2 button

; Run the GUI until the dialog is closed
While 1
$iMsg = GUIGetMsg()
Select
Case $iMsg = $GUI_EVENT_CLOSE
ExitLoop
Case $iMsg = $idButton_1
Run("Notepad.exe") ; Will Run/Open Notepad
Case $iMsg = $idButton_2
MsgBox(0, "Testing", "Button 2 was pressed") ; Will demonstrate Button 2 being pressed
EndSelect
WEnd
GUIDelete($hGUI)
EndFunc ;==>Example</syntaxhighlight>

== Template UDF ==
Here is an example of a UDF called <code>MyUDF.au3</code>:

<syntaxhighlight lang="autoit">#include-once

#include "MyUDFConstants.au3"
#include "AnInclude.au3"

; #INDEX# =======================================================================================================================
; Title .........: MyUDF
; AutoIt Version : 3.3.6.1
; Language ......: English
; Description ...: An example UDF that does very little.
; ===============================================================================================================================

; #CURRENT# =====================================================================================================================
;$tagMYSTRUCT
;_MyUDF_Function
; ===============================================================================================================================

; #STRUCTURE# ===================================================================================================================
; Name...........: $tagMYSTRUCT
; Description ...: An example of a structure.
; Fields ........: hFoo - A handle to foo that does something.
; iBar - An integer that does something.
; Author ........: Matt Diesel (Mat)
; Remarks .......:
; Related .......: _MyUDF_Function
; ===============================================================================================================================
Global Const $tagMYSTRUCT = "ptr hFoo; int iBar"

; #FUNCTION# ====================================================================================================================
; Name...........: _MyUDF_Function
; Description ...: A function that does something.
; Syntax.........: _MyUDF_Function(ByRef $avAnArray, $iAnInt[, $hAHandle = 0[, $nSomeNumber = 42]])
; Parameters ....: $avAnArray - [byref] An array of anything. The value of anything is changed and passed out using this
; parameter. The array should only have one dimension
; $iAnInt - An integer that does very little.
; $hAHandle - [optional] A handle. Default is zero.
; $nSomeNumber - [optional] A number of some kind. Default is 42.
; Return values .: Success - A MYSTRUCT structure.
; Failure - Returns zero and sets the @error flag:
; |1 - The $avAnArray is invalid.
; Author ........: Matt Diesel (Mat)
; Modified.......:
; Remarks .......:
; Related .......: $tagMYSTRUCT
; Link ..........:
; Example .......: No
; ===============================================================================================================================
Func _MyUDF_Function(ByRef $avAnArray, $iAnInt, $hAHandle = 0, $nSomeNumber = 42)
; 1 - Error Checking for parameters.
If Not IsArray($avAnArray) Or UBound($avAnArray, 0) <> 1 Then Return SetError(1, 0, 0) ; The $avAnArray is invalid.

; 2 - Declaration of locals.
Local $tMS = DllStructCreate($tagMYSTRUCT)

; 3 - Function code
DllStructSetData($tMS, "hFoo", $hAHandle)
DllStructSetData($tMS, "iBar", $iAnInt * $nSomeNumber)

Return $tMS
EndFunc ;==>_MyUDF_Function</syntaxhighlight>