AutoIt Wiki - User contributions [en]

Best coding practices

2016-02-06T12:04:43Z

Guinness:

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

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>

Best coding practices

2016-02-06T12:02:01Z

Guinness: Tidied comments

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
|-
| i || Integer || $iInteger = 10
|-
| f || Floating point || $fFloat = 0.123
|-
| n || General number (no preference) || $nNumber = 0
|-
| a || Arrays || $aArray[0]
|-
| m || Maps || $mMap[]
|-
| s || Strings (chars included) || $sString = "hello world"
|-
| b || Booleans || $bBool = True
|-
| d || Binaries || $dBinary = Binary("0x80000000")
|-
| id || An AutoIt controlID || $idButton_Ok = GUICtrlCreateButton("OK", 5, 5)
|-
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")
|-
| p || Pointers || $pRect = DllStructGetPtr($tRECT)
|-
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"
|-
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)
|-
| o || Objects || $oShell = ObjCreate("shell.application")
|-
| v || Variant || $vData = ClipGet()
|-
| e || Constant variable || Local Const $eEulersConstant = 2.7182818284590452
|}

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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents
_ArrayDisplay($aArray)

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

; Display the contents
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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>

Best coding practices

2016-02-06T11:59:49Z

Guinness: Typos

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
|-
| i || Integer || $iInteger = 10
|-
| f || Floating point || $fFloat = 0.123
|-
| n || General number (no preference) || $nNumber = 0
|-
| a || Arrays || $aArray[0]
|-
| m || Maps || $mMap[]
|-
| s || Strings (chars included) || $sString = "hello world"
|-
| b || Booleans || $bBool = True
|-
| d || Binaries || $dBinary = Binary("0x80000000")
|-
| id || An AutoIt controlID || $idButton_Ok = GUICtrlCreateButton("OK", 5, 5)
|-
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")
|-
| p || Pointers || $pRect = DllStructGetPtr($tRECT)
|-
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"
|-
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)
|-
| o || Objects || $oShell = ObjCreate("shell.application")
|-
| v || Variant || $vData = ClipGet()
|-
| e || Constant variable || Local Const $eEulersConstant = 2.7182818284590452
|}

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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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>

Best coding practices

2015-09-04T06:11:04Z

Guinness: /* 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
|-
| i || Integer || $iInteger = 10
|-
| f || Floating point || $fFloat = 0.123
|-
| n || General number (no preference) || $nNumber = 0
|-
| a || Arrays || $aArray[0]
|-
| m || Maps || $mMap[]
|-
| s || Strings (chars included) || $sString = "hello world"
|-
| b || Booleans || $bBool = True
|-
| d || Binaries || $dBinary = Binary("0x80000000")
|-
| id || An AutoIt controlId || $idButton = GUICtrlCreateButton("OK", 5, 5)
|-
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")
|-
| p || Pointers || $pRect = DllStructGetPtr($tRECT)
|-
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"
|-
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)
|-
| o || Objects || $oShell = ObjCreate("shell.application")
|-
| v || Variant || $vData = ClipGet()
|-
| e || Constant variable || Local Const $eEulersConstant = 2.7182818284590452
|}

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 $idGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idQuit = 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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 efficent 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>

UDF-spec

2015-09-04T06:09:00Z

Guinness: /* Globals */

[[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.
* Not use any magic numbers. Ever. None. At all. No excuses.

== 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 $__g_vMyGlobal = 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 scope and type of the variable. See [[Best_coding_practices#Names_of_Variables|Names of Variables]]

=== 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></code> where <code><VARNAME></code> is the name as it would usually appear according to the variable naming rules above. 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.
* Not make any permanent changes to the users computer. For example, if demonstrating a File function, be sure to delete the file after it has been used. The same applies for any function that makes a change to the environment: the changes MUST be undone.

Always remember, the readability of code in an example is MORE important than the readability of code inside the UDF itself.

Examples are stored in script 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>.

<syntaxhighlight lang="autoit">#include <Constants.au3>
#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($MB_SYSTEMMODAL, "Testing", "Button 2 was pressed") ; Will demonstrate Button 2 being pressed
EndSelect
WEnd
GUIDelete($hGUI)
EndFunc ;==>Example</syntaxhighlight>

=== Multiple Examples ===
The helpfile now supports multiple examples per function. In order to maintain backwards compatibility with any other tools that use examples, the first file is still named <code><FUNCTION>.au3</code>, but any additional examples are named <code><FUNCTION>[n].au3</code> where n is an integer counter starting at 2.

== Template UDF ==
Here is an example of a UDF called <code>MyUDF.au3</code>:

<syntaxhighlight lang="autoit">#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7
#include-once

#include "MyUDFConstants.au3"
#include "AnInclude.au3"

; #INDEX# =======================================================================================================================
; Title .........: MyUDF
; AutoIt Version : 3.3.10.2
; Language ......: English
; Author(s) .....:
; Modifiers .....:
; Forum link ....: a link to the main forum topic (if aplicable)
; 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>

Best coding practices

2015-09-04T05:21:09Z

Guinness:

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 Apps 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
|-
| i || Integer || $iInteger = 10
|-
| f || Floating point || $fFloat = 0.123
|-
| n || General number (no preference) || $nNumber = 0
|-
| a || Arrays || $aArray[0]
|-
| m || Maps || $mMap[]
|-
| s || Strings (chars included) || $sString = "hello world"
|-
| b || Booleans || $bBool = True
|-
| d || Binaries || $dBinary = Binary("0x80000000")
|-
| id || An AutoIt controlId || $idButton = GUICtrlCreateButton("OK", 5, 5)
|-
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")
|-
| p || Pointers || $pRect = DllStructGetPtr($tRECT)
|-
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"
|-
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)
|-
| o || Objects || $oShell = ObjCreate("shell.application")
|-
| v || Variant || $vData = ClipGet()
|-
| e || Constant variable || Local Const $eEulersConstant = 2.7182818284590452
|}

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 $idGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idQuit = 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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 efficent 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>

Best coding practices

2015-09-04T05:04:52Z

Guinness:

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 Apps 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
|-
| i || Integer || $iInteger = 10
|-
| f || Floating point || $fFloat = 0.123
|-
| n || General number (no preference) || $nNumber = 0
|-
| a || Arrays || $aArray[0]
|-
| m || Maps || $mMap[]
|-
| s || Strings (chars included) || $sString = "hello world"
|-
| b || Booleans || $bBool = True
|-
| d || Binaries || $dBinary = Binary("0x80000000")
|-
| id || An AutoIt controlId || $idButton = GUICtrlCreateButton("OK", 5, 5)
|-
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")
|-
| p || Pointers || $pRect = DllStructGetPtr($tRECT)
|-
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"
|-
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)
|-
| o || Objects || $oShell = ObjCreate("shell.application")
|-
| v || Variant || $vData = ClipGet()
|-
| e || Constant variable || Local Const $eEulersConstant = 2.7182818284590452
|}

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 $idGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idQuit = 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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 efficent 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>

Best coding practices

2015-09-04T05:03:18Z

Guinness: /* Variable Initialization */

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 Apps 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
|-
| i || Integer || $iInteger = 10
|-
| f || Floating point || $fFloat = 0.123
|-
| n || General number (no preference) || $nNumber = 0
|-
| a || Arrays || $aArray[0]
|-
| m || Maps || $mMap[]
|-
| s || Strings (chars included) || $sString = "hello world"
|-
| b || Booleans || $bBool = True
|-
| d || Binaries || $dBinary = Binary("0x80000000")
|-
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)
|-
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")
|-
| p || Pointers || $pRect = DllStructGetPtr($tRECT)
|-
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"
|-
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)
|-
| o || Objects || $oShell = ObjCreate("shell.application")
|-
| v || Variant || $vData = ClipGet()
|-
| e || Constant variable || Local Const $eEulersConstant = 2.7182818284590452
|}

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 $idGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idQuit = 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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 efficent 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>

Best coding practices

2015-09-04T05:02:21Z

Guinness: /* 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 Apps 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
|-
| i || Integer || $iInteger = 10
|-
| f || Floating point || $fFloat = 0.123
|-
| n || General number (no preference) || $nNumber = 0
|-
| a || Arrays || $aArray[0]
|-
| m || Maps || $mMap[]
|-
| s || Strings (chars included) || $sString = "hello world"
|-
| b || Booleans || $bBool = True
|-
| d || Binaries || $dBinary = Binary("0x80000000")
|-
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)
|-
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")
|-
| p || Pointers || $pRect = DllStructGetPtr($tRECT)
|-
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"
|-
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)
|-
| o || Objects || $oShell = ObjCreate("shell.application")
|-
| v || Variant || $vData = ClipGet()
|-
| e || Constant variable || Local Const $eEulersConstant = 2.7182818284590452
|}

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 $idGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idQuit = 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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 efficent 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>

Talk:UDF-spec

2015-09-04T04:59:07Z

Guinness: /* Coding Practice */

This page is currently under construction by Mat. It is being ported from this page: [http://dl.dropbox.com/u/22257420/Programming/UdfSpec.html]

All content has been copied across, but links may not work and formatting may be broken.

--[[User:Mat|Mat]] 09:28, 16 November 2011 (GMT)

== Outdated information ==
New updates to AutoIt are including changes to the syntax. Certain sections of this document will need to be revisited.

== Notes ==
* There are a number of places where current headers differ slightly from these standards.
** Structures aren't using the Related field. It was added here as it is looked for by the docs generator, and should be there anyway.
** Structures have a varied naming convention, not always following the rule of including the type notation. Particularly StructureConstants.au3.
* The header for _WinAPI_GetMousePos isn't as it appears above, but it should be.
* Variable naming is still a matter of personal style. As long as it's readable and makes sense then it is acceptable. That part remains a guideline as opposed to a standard.
* There probably needs to be two versions of this document. One for MVPs working directly with the UDFs and examples and another for other community members working on non-standard UDFs.

== Coding Practice ==

This page does not currently cover coding practices other than naming conventions. The topic of programming best practice is very broad and so I have no intention of adding it to this page.

Useful links:
* [https://www.autoitscript.com/wiki/Best_coding_practices Best Coding Practices In AutoIt]
* [http://www.autoitscript.com/forum/topic/146866-best-coding-practices-in-autoit/ Best Coding Practices In AutoIt [Forums<nowiki>]</nowiki>]

--[[User:Mdiesel|Mdiesel]] ([[User talk:Mdiesel|talk]]) 01:38, 7 January 2013 (UTC)
--[[User:guinness|guinness]] ([[User talk:guinness|talk]]) 06:57, 4 September 2015 (UTC)

== Variable naming conventions ==

The variable prefix system is only designed to be a recommendation. The idea is that variable naming should be something someone else can read and understand easily.

A usage prefix is preferred to a type prefix. For example, dll struct strings are always prefixed $tag, rather than $s. If there is a logical usage prefix then it should be used rather than the type prefixes showed.

There is also discussion about floats and boolean prefixes [http://www.autoitscript.com/forum/topic/146866-best-coding-practices-in-autoit/page__st__240#entry1072359 here].

Talk:UDF-spec

2015-09-04T04:57:47Z

Guinness: /* Coding Practice */

This page is currently under construction by Mat. It is being ported from this page: [http://dl.dropbox.com/u/22257420/Programming/UdfSpec.html]

All content has been copied across, but links may not work and formatting may be broken.

--[[User:Mat|Mat]] 09:28, 16 November 2011 (GMT)

== Outdated information ==
New updates to AutoIt are including changes to the syntax. Certain sections of this document will need to be revisited.

== Notes ==
* There are a number of places where current headers differ slightly from these standards.
** Structures aren't using the Related field. It was added here as it is looked for by the docs generator, and should be there anyway.
** Structures have a varied naming convention, not always following the rule of including the type notation. Particularly StructureConstants.au3.
* The header for _WinAPI_GetMousePos isn't as it appears above, but it should be.
* Variable naming is still a matter of personal style. As long as it's readable and makes sense then it is acceptable. That part remains a guideline as opposed to a standard.
* There probably needs to be two versions of this document. One for MVPs working directly with the UDFs and examples and another for other community members working on non-standard UDFs.

== Coding Practice ==

This page does not currently cover coding practices other than naming conventions. The topic of programming best practice is very broad and so I have no intention of adding it to this page.

Useful links:
* [http://www.autoitscript.com/forum/topic/146866-best-coding-practices-in-autoit/ Best Coding Practices In AutoIt [Forums<nowiki>]</nowiki>]
* [https://www.autoitscript.com/wiki/Best_coding_practices Best Coding Practices In AutoIt [Forums<nowiki>]</nowiki>]

--[[User:Mdiesel|Mdiesel]] ([[User talk:Mdiesel|talk]]) 01:38, 7 January 2013 (UTC)
--[[User:guinness|guinness]] ([[User talk:guinness|talk]]) 06:57, 4 September 2015 (UTC)

== Variable naming conventions ==

The variable prefix system is only designed to be a recommendation. The idea is that variable naming should be something someone else can read and understand easily.

A usage prefix is preferred to a type prefix. For example, dll struct strings are always prefixed $tag, rather than $s. If there is a logical usage prefix then it should be used rather than the type prefixes showed.

There is also discussion about floats and boolean prefixes [http://www.autoitscript.com/forum/topic/146866-best-coding-practices-in-autoit/page__st__240#entry1072359 here].

Best coding practices

2015-04-01T05:05:29Z

Guinness: /* 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__

== Names of Variables ==
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps 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
|-
| i || Integer || $iInteger = 10
|-
| f || Floating point || $fFloat = 0.123
|-
| n || General number (no preference) || $nNumber = 0
|-
| a || Arrays || $aArray[0]
|-
| m || Maps || $mMap[]
|-
| s || Strings (chars included) || $sString = "hello world"
|-
| b || Booleans || $bBool = True
|-
| d || Binaries || $dBinary = Binary("0x80000000")
|-
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)
|-
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")
|-
| p || Pointers || $pRect = DllStructGetPtr($tRECT)
|-
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"
|-
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)
|-
| o || Objects || $oShell = ObjCreate("shell.application")
|-
| v || Variant || $vData = ClipGet()
|-
| e || Constant variable || Local Const $eEulersConstant = 2.7182818284590452
|}

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, 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 $idGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idQuit = 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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 efficent 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>

Best coding practices

2015-04-01T04:59:02Z

Guinness: /* 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__

== Names of Variables ==
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps 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
|-
| i || Integer || $iInteger = 10
|-
| f || Floating point || $fFloat = 0.123
|-
| n || General number (no preference) || $nNumber = 0
|-
| a || Arrays || $aArray[0]
|-
| m || Maps || $mMap[]
|-
| s || Strings (chars included) || $sString = "hello world"
|-
| b || Booleans || $bBool = True
|-
| d || Binaries || $dBinary = Binary("0x80000000")
|-
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)
|-
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")
|-
| p || Pointers || $pRect = DllStructGetPtr($tRECT)
|-
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"
|-
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)
|-
| o || Objects || $oShell = ObjCreate("shell.application")
|-
| v || Variant || $vData = ClipGet()
|-
| e || Constant variable || Local Const $eEulersConstant = 2.7182818284590452
|}

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, 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 $idGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idQuit = 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 $_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 $_iVar1.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 $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, "", $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, $vVariableThatIsGlobal) ; The Global variable ($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 $vVariableThatIsGlobal = ""

For $i = 1 To 10
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.
Next
Return $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 $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 efficent 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>

Variables - using Global, Local, Static and ByRef

2015-03-25T04:13:54Z

Guinness:

[[Category:Tutorials]]
These keywords confuse many coders - this tutorial should help make their use clear.

In most programming languages you can define the scope of variables - this determines the visibility or accessibility of the variable from different parts of the program.

In AutoIt there are two possible scopes: ''Global'' and ''Local''.

- A '''Global''' variable is visible throughout your script - any part of the script can both read its value and, importantly, change it.

- A '''Local''' variable exists only within the function in which it is declared and is destroyed when the function terminates. It is invisible to any other function unless it is passed as a parameter.

Additionally declaring a variable as '''Static''' changes its behaviour slightly. A ''Global Static'' variable serves no useful purpose as it is essentially the same as a normal ''Global'' variable. However, a ''Local Static'' variable exists only within the function in which it is declared, but is NOT destroyed when the function ends and can be reused when the function is next entered. You can assign an initial value to this variable when it is created - if it is already in existence then the assignment is ignored. Note that the order of the keywords is not important.

Why do we need to scope variables? Well, it is often useful to have a single variable used throughout the script - perhaps the name of an Ini file which if declared as ''Global'' can then be read by any function that requires it. And ''Local'' variables allow us to save resources by only using variables as long as we need - for example if we create a large array which is only needed within a single function.

We scope variables by using the ''Global, Local'' and ''Static'' keywords when the variables are first declared - look at the examples below. By default, AutoIt scopes any variables declared in the main body of a script (that is not between a ''Func'' and ''EndFunc'' pair) as ''Global'' and any variables declared within function declarations as ''Local''. But it is a good idea to explicitly declare your variables to make sure that you get what you want. For example, you can declare a variable as ''Global'' within a function - although you may get a gentle reminder when you run your script within SciTE that this is not recommended. But there is no point declaring any variables in the main body of a script as ''Local'' - they will be ''Global'' regardless. If you use the ''AutoItSetOption("MustDeclareVars", 1)'' directive you ''must'' declare the scope of your variables or you will get error messages.

In the Help file pages for ''Global, Local'' and ''Static'' you will also see mention of ''Dim'' and ''ReDim''. Using ''Dim'' will declare a variable and satisfy the ''AutoItSetOption'' just mentioned, but will let AutoIt scope the variable using the default settings as described above. It is much better practice to use ''Global'' or ''Local'' to set the scope you require explicitly. Despite its similar name, ''ReDim'' is only used to resize arrays without destroying the content and is outside the scope of this tutorial.

Let us now look at a simple example when we read and change ''Global'' variables in a function:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3> ; only required for MsgBox constants

Global $Var_1 = "Variable 1"
Global $Var_2 = "Variable 2"

; Read the variables
MsgBox($MB_SYSTEMMODAL, "Reading", "In The Main Script" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 2 = " & $Var_2)

; Read the variables in a function
Function()

; And now read the variables again - see that $iVar_2 has changed
MsgBox($MB_SYSTEMMODAL, "Reading", "Back In The Main Script" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 2 = " & $Var_2)

Func Function()
; Read the variables
MsgBox($MB_SYSTEMMODAL, "Reading", "In The Function" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 2 = " & $Var_2)
; Now let us change one of the variables WITHIN the function
$Var_2 = "Changed Variable 2"
EndFunc ;==>Function
</syntaxhighlight>
Here is a simple example showing how ''Local'' variables are only visible ''inside'' their own function:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3> ; only required for MsgBox constants

Global $Var_1 = "Variable 1"

; Read the variable
MsgBox($MB_SYSTEMMODAL, "Reading", "In The Main Script" & @CRLF & @CRLF & "Variable 1 = " & $Var_1)

; Now run a function
Function()

; And now try to read Variable 3 outside the function
MsgBox($MB_SYSTEMMODAL, "Reading", "Back In The Main Script" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 3 = " & $Var_3)

Func Function()
; Declare a Local variable
Local $Var_3 = "Variable 3"
; Read the variables
MsgBox($MB_SYSTEMMODAL, "Reading", "In The Function" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 3 = " & $Var_3)
EndFunc ;==>Function

</syntaxhighlight>
You should have got errors telling you that ''$Var3'' was "''possibly used before declaration''" and an "''undeclared global variable''". This is because ''$Var3'' exists only ''within'' the function - when the function ends it is destroyed.

This means that we can use the same variable name in different functions without causing a problem - very useful for simple variables which are only used temporarily:
<syntaxhighlight lang="autoit">
#include <MsgConstants.au3>; only required for MsgBox constants

Function_1()

Func Function_1()
; Declare the variable in this function
Local $sString = "Variable in Function One"
; Read the value
MsgBox($MB_SYSTEMMODAL, "Reading", "In Function One" & @CRLF & @CRLF & "Variable = " & $sString)

; Now run Function Two
Function_2()

; Now read the variable again - we still get the variable from this function
; The variable in Function 2 has been destroyed now the function has terminated
MsgBox($MB_SYSTEMMODAL, "Reading", "In Function One" & @CRLF & @CRLF & "Variable = " & $sString)
EndFunc ;==>Function_1

Func Function_2()
; Declare a variable with the same name
Local $sString = "Variable in Function Two"
; Read this variable - see how we get the value in this function, not the value in Function One
MsgBox($MB_SYSTEMMODAL, "Reading", "In Function Two" & @CRLF & @CRLF & "Variable = " & $sString)
EndFunc ;==>Function_2
</syntaxhighlight>
AutoIt even allows you to use the same name for ''Global'' and ''Local'' variables, although this is ''not'' recommended as it could easily lead to confusion. If there is a naming conflict of this kind, AutoIt uses the ''Local'' value as you can see here:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>; only required for MsgBox constants

; Declare the variable as Global
Global $sString = "Global Variable in the Main Script"

; Read it
MsgBox($MB_SYSTEMMODAL, "Reading", "In the Main Script" & @CRLF & @CRLF & "Variable = " & $sString)

; Run the functions which declare Local variables with the same name
Function_1()

; And now see that the Global variable still exists unchanged
MsgBox($MB_SYSTEMMODAL, "Reading", "In the Main Script" & @CRLF & @CRLF & "Variable = " & $sString)

Func Function_1()
; Declare a variable with the SAME name as Local to this function
Local $sString = "Variable in Function One"
; Read the value - we get the value of the Local variable in this function, not the Global one
MsgBox($MB_SYSTEMMODAL, "Reading", "In Function One" & @CRLF & @CRLF & "Variable = " & $sString)
EndFunc ;==>Function_1
</syntaxhighlight>

A good use for ''Static'' variables is when you need to maintain a record of a value within a function even though the function itself ends. An example might be that you want to do something the first time a function is called, but not subsequently:
<syntaxhighlight lang="autoit">
Foo()
Foo()
Foo()

Func Foo()
; Set the flag only on the first entry into the function
; This assignment will be ignored on subsequent entries
Local Static $bFoo_First_Pass = True

; Check the flag
If $bFoo_First_Pass Then
; Immediately clear the flag to prevent running on subsequent passes
$bFoo_First_Pass = False
; Run on first pass because flag is set
ConsoleWrite("First pass" & @CRLF)
Else
; Flag remains cleared for subsequent passes
ConsoleWrite("Not first pass" & @CRLF)
EndIf
EndFunc ;==>Foo
</syntaxhighlight>
As the ''Local'' part of their declaration implies, you can use the same name for ''Static'' variables in different functions - even though they are not destroyed when the functions end:
<syntaxhighlight lang="autoit">
For $i = 1 To 5
Function_1()
Function_2()
Next

Func Function_1()
; Declare the variable as Static - remember this only happens once
Local Static $vVar = 0
; Increase the value of the variable each time we enter the function
$vVar += 10
; And show that it has retained its value as the function exits
ConsoleWrite("In Function_1: " & $vVar & @CRLF)
EndFunc ;==>Function_1

Func Function_2()
; Use the same variable name
Local Static $vVar = 0
$vVar += 100
ConsoleWrite("In Function_2: " & $vVar & @CRLF)
EndFunc ;==>Function_2
</syntaxhighlight>

As a general rule, try to have as few ''Global'' variables as you can. Remember that you can share ''Local'' variables between functions - and even change their values - by passing them as parameters as we will see in the ''ByRef'' section below. And declaring a variable as ''Static'' allows you retain its value even though the function in which it is used has ended.

=Passing variables as parameters using ByRef=
When you call a function in AutoIt, you can pass parameters to the function by including them in the parentheses following the function name like this - ''Function(Parameter_1, Parameter_2)''. Passing variables in this way means that you can use variables that have been declared as ''Local'' within other functions. Note that the parameters are automatically declared as ''Local'' variables within the called function and so do not need to be declared again in the code.

Variables can be passed as parameters to a function in 2 ways:

'''By Value''' - This is the default. The parameter is treated as a ''Local'' variable within the function to which it is passed and any changes made to it are lost when the function ends. So no changes are made to the ''Local'' variable within the original function.

'''By Reference''' - This is used when ''ByRef'' is added ''before'' the variable name in the parameter list of the function declaration. Now any changes to the variable made in the function to which it is passed also affect the ''Local'' variable in the original function. If you do not understand why this is such a powerful capability, you need to read the ''Global/Local'' section again!

Here is a small example to show how parameters are passed when calling a function:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>; only required for MsgBox constants

Func_A()

Func Func_A()
; Declare variables
Local $iVar_A1 = 10
Local $iVar_A2 = 20
; And read them
MsgBox($MB_SYSTEMMODAL, "Read", "Initial read in Func A:" & @CRLF & "Var A1 = " & $iVar_A1 & @CRLF & "Var A2 = " & $iVar_A2)

; Now pass these variables to another function - we use the names we have already declared in this function
Func_B($iVar_A1, $iVar_A2)

; We changed the parameters in Func_B - but nothing happened to the variables in this function
MsgBox($MB_SYSTEMMODAL, "Read", "Second read in Func A:" & @CRLF & "Var A1 = " & $iVar_A1 & @CRLF & "Var A2 = " & $iVar_A2)
EndFunc ;==>Func_A

Func Func_B($iVar_B1, $iVar_B2) ; There is no need to declare the variables as parameters are automatically Local in scope
; Now read these variables - note that they have the same value as the variables in Func_A
MsgBox($MB_SYSTEMMODAL, "Read", "Initial read in Func B:" & @CRLF & "Var B1 = " & $iVar_B1 & @CRLF & "Var B2 = " & $iVar_B2)

; Let us change them
$iVar_B1 = 100
$iVar_B2 = 200

; And confirm that they have changed
MsgBox($MB_SYSTEMMODAL, "Read", "Second read in Func B:" & @CRLF & "Var B1 = " & $iVar_B1 & @CRLF & "Var B2 = " & $iVar_B2)

; Now return to the other function
EndFunc ;==>Func_B
</syntaxhighlight>
As you can see, the ''Local'' variables within ''Func_A'' are read perfectly by ''Func_B'' when passed as parameters, even though they were declared as ''Local'' in ''Func_A''. However, although ''Func_B'' changes the value of the variables, the values of the original variables within ''Func_A'' are not changed.

If we want to change the value of the variables in ''Func_A'' from within ''Func_B'', we need to use the ''ByRef'' keyword as explained above and illustrated here:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>; only required for MsgBox constants

Func_A()

Func Func_A()
; Declare variables
Local $iVar_A1 = 10
Local $iVar_A2 = 20

; And read them
MsgBox($MB_SYSTEMMODAL, "Read", "Initial read in Func A:" & @CRLF & "Var A1 = " & $iVar_A1 & @CRLF & "Var A2 = " & $iVar_A2)

; Now pass these variables to another function - but this time we will pass $iVar_A2 By Reference
Func_B($iVar_A1, $iVar_A2)

; We changed the parameters in Func_B - this time we see that we have changed $iVar_A2
MsgBox($MB_SYSTEMMODAL, "Read", "Second read in Func A:" & @CRLF & "Var A1 = " & $iVar_A1 & @CRLF & "Var A2 = " & $iVar_A2)
EndFunc ;==>Func_A

Func Func_B($iVar_B1, ByRef $iVar_B2) ; Note the ByRef keyword in the function declaration for the second parameter
; Now read these variables - they have the same value as the variables in Func_A
MsgBox($MB_SYSTEMMODAL, "Read", "Initial read in Func B:" & @CRLF & "Var B1 = " & $iVar_B1 & @CRLF & "Var B2 = " & $iVar_B2)

; Let us change them
$iVar_B1 = 100
$iVar_B2 = 200

; And confirm that they have changed
MsgBox($MB_SYSTEMMODAL, "Read", "Second read in Func B:" & @CRLF & "Var B1 = " & $iVar_B1 & @CRLF & "Var B2 = " & $iVar_B2)

; Now return to the other function
EndFunc ;==>Func_B
</syntaxhighlight>

A couple of more advanced points:

- It was mentioned earlier that when you pass variables to functions AutoIt makes local copies of these variables unless you declare that they are to be passed ''ByRef''. In the special case of arrays, which are typically larger than a simple variable, AutoIt will only make a local copy if you change the array inside the function - merely accessing the array will use the original version. So passing the array ''ByRef'' is only advantageous if you intend to modify the array within the function - however, it does no harm to force the issue by using the keyword.

- If you are dealing with a simple variable of considerable size (the text of a file for example) then passing it ''ByRef'' is a sensible action. But if you want to make sure that the variable cannot be altered inside the function, you can declare it as ''Const ByRef'' in the function definition as shown here:
<syntaxhighlight lang="autoit">
Local $sString = "A very large chunk of data which we do not want to change"

Foo($sString)

Func Foo(Const ByRef $sText) ; The data is not copied, but also cannot be changed
; Uncomment this line to see what happens when we try
;$sText = "New value"
EndFunc ;==>Foo
</syntaxhighlight>

''ByRef'' is a very powerful feature - but use it carefully, or you may find that you have changed a variable when you did not want to!

Variables - using Global, Local, Static and ByRef

2015-03-25T04:11:59Z

Guinness:

[[Category:Tutorials]]
These keywords confuse many coders - this tutorial should help make their use clear.

In most programming languages you can define the scope of variables - this determines the visibility or accessibility of the variable from different parts of the program.

In AutoIt there are two possible scopes: ''Global'' and ''Local''.

- A '''Global''' variable is visible throughout your script - any part of the script can both read its value and, importantly, change it.

- A '''Local''' variable exists only within the function in which it is declared and is destroyed when the function terminates. It is invisible to any other function unless it is passed as a parameter.

Additionally declaring a variable as '''Static''' changes its behaviour slightly. A ''Global Static'' variable serves no useful purpose as it is essentially the same as a normal ''Global'' variable. However, a ''Local Static'' variable exists only within the function in which it is declared, but is NOT destroyed when the function ends and can be reused when the function is next entered. You can assign an initial value to this variable when it is created - if it is already in existence then the assignment is ignored. Note that the order of the keywords is not important.

Why do we need to scope variables? Well, it is often useful to have a single variable used throughout the script - perhaps the name of an Ini file which if declared as ''Global'' can then be read by any function that requires it. And ''Local'' variables allow us to save resources by only using variables as long as we need - for example if we create a large array which is only needed within a single function.

We scope variables by using the ''Global, Local'' and ''Static'' keywords when the variables are first declared - look at the examples below. By default, AutoIt scopes any variables declared in the main body of a script (that is not between a ''Func'' and ''EndFunc'' pair) as ''Global'' and any variables declared within function declarations as ''Local''. But it is a good idea to explicitly declare your variables to make sure that you get what you want. For example, you can declare a variable as ''Global'' within a function - although you may get a gentle reminder when you run your script within SciTE that this is not recommended. But there is no point declaring any variables in the main body of a script as ''Local'' - they will be ''Global'' regardless. If you use the ''AutoItSetOption("MustDeclareVars", 1)'' directive you ''must'' declare the scope of your variables or you will get error messages.

In the Help file pages for ''Global, Local'' and ''Static'' you will also see mention of ''Dim'' and ''ReDim''. Using ''Dim'' will declare a variable and satisfy the ''AutoItSetOption'' just mentioned, but will let AutoIt scope the variable using the default settings as described above. It is much better practice to use ''Global'' or ''Local'' to set the scope you require explicitly. Despite its similar name, ''ReDim'' is only used to resize arrays without destroying the content and is outside the scope of this tutorial.

Let us now look at a simple example when we read and change ''Global'' variables in a function:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3> ; only required for MsgBox constants

Global $Var_1 = "Variable 1"
Global $Var_2 = "Variable 2"

; Read the variables
MsgBox($MB_SYSTEMMODAL, "Reading", "In The Main Script" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 2 = " & $Var_2)

; Read the variables in a function
_Function()

; And now read the variables again - see that $iVar_2 has changed
MsgBox($MB_SYSTEMMODAL, "Reading", "Back In The Main Script" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 2 = " & $Var_2)

Func _Function()
; Read the variables
MsgBox($MB_SYSTEMMODAL, "Reading", "In The Function" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 2 = " & $Var_2)
; Now let us change one of the variables WITHIN the function
$Var_2 = "Changed Variable 2"
EndFunc ;==>_Function
</syntaxhighlight>
Here is a simple example showing how ''Local'' variables are only visible ''inside'' their own function:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3> ; only required for MsgBox constants

Global $Var_1 = "Variable 1"

; Read the variable
MsgBox($MB_SYSTEMMODAL, "Reading", "In The Main Script" & @CRLF & @CRLF & "Variable 1 = " & $Var_1)

; Now run a function
_Function()

; And now try to read Variable 3 outside the function
MsgBox($MB_SYSTEMMODAL, "Reading", "Back In The Main Script" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 3 = " & $Var_3)

Func _Function()
; Declare a Local variable
Local $Var_3 = "Variable 3"
; Read the variables
MsgBox($MB_SYSTEMMODAL, "Reading", "In The Function" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 3 = " & $Var_3)
EndFunc ;==>_Function

</syntaxhighlight>
You should have got errors telling you that ''$Var3'' was "''possibly used before declaration''" and an "''undeclared global variable''". This is because ''$Var3'' exists only ''within'' the function - when the function ends it is destroyed.

This means that we can use the same variable name in different functions without causing a problem - very useful for simple variables which are only used temporarily:
<syntaxhighlight lang="autoit">
#include <MsgConstants.au3>; only required for MsgBox constants

Function_1()

Func Function_1()
; Declare the variable in this function
Local $sString = "Variable in Function One"
; Read the value
MsgBox($MB_SYSTEMMODAL, "Reading", "In Function One" & @CRLF & @CRLF & "Variable = " & $sString)

; Now run Function Two
Function_2()

; Now read the variable again - we still get the variable from this function
; The variable in Function 2 has been destroyed now the function has terminated
MsgBox($MB_SYSTEMMODAL, "Reading", "In Function One" & @CRLF & @CRLF & "Variable = " & $sString)
EndFunc ;==>Function_1

Func Function_2()
; Declare a variable with the SAME name
Local $sString = "Variable in Function Two"
; Read this variable - see how we get the value in this function, not the value in Function One
MsgBox($MB_SYSTEMMODAL, "Reading", "In Function Two" & @CRLF & @CRLF & "Variable = " & $sString)
EndFunc ;==>Function_2
</syntaxhighlight>
AutoIt even allows you to use the same name for ''Global'' and ''Local'' variables, although this is ''not'' recommended as it could easily lead to confusion. If there is a naming conflict of this kind, AutoIt uses the ''Local'' value as you can see here:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>; only required for MsgBox constants

; Declare the variable as Global
Global $sString = "Global Variable in the Main Script"

; Read it
MsgBox($MB_SYSTEMMODAL, "Reading", "In the Main Script" & @CRLF & @CRLF & "Variable = " & $sString)

; Run the functions which declare Local variables with the same name
Function_1()

; And now see that the Global variable still exists unchanged
MsgBox($MB_SYSTEMMODAL, "Reading", "In the Main Script" & @CRLF & @CRLF & "Variable = " & $sString)

Func Function_1()
; Declare a variable with the SAME name as Local to this function
Local $sString = "Variable in Function One"
; Read the value - we get the value of the Local variable in this function, not the Global one
MsgBox($MB_SYSTEMMODAL, "Reading", "In Function One" & @CRLF & @CRLF & "Variable = " & $sString)
EndFunc ;==>Function_1
</syntaxhighlight>

A good use for ''Static'' variables is when you need to maintain a record of a value within a function even though the function itself ends. An example might be that you want to do something the first time a function is called, but not subsequently:
<syntaxhighlight lang="autoit">
Foo()
Foo()
Foo()

Func Foo()
; Set the flag only on the first entry into the function
; This assignment will be ignored on subsequent entries
Local Static $bFoo_First_Pass = True

; Check the flag
If $bFoo_First_Pass Then
; Immediately clear the flag to prevent running on subsequent passes
$bFoo_First_Pass = False
; Run on first pass because flag is set
ConsoleWrite("First pass" & @CRLF)
Else
; Flag remains cleared for subsequent passes
ConsoleWrite("Not first pass" & @CRLF)
EndIf
EndFunc ;==>Foo
</syntaxhighlight>
As the ''Local'' part of their declaration implies, you can use the same name for ''Static'' variables in different functions - even though they are not destroyed when the functions end:
<syntaxhighlight lang="autoit">
For $i = 1 To 5
_Function_1()
_Function_2()
Next

Func _Function_1()
; Declare the variable as Static - remember this only happens once
Local Static $vVar = 0
; Increase the value of the variable each time we enter the function
$vVar += 10
; And show that it has retained its value as the function exits
ConsoleWrite("In Function_1: " & $vVar & @CRLF)
EndFunc ;==>_Function_1

Func _Function_2()
; Use the same variable name
Local Static $vVar = 0
$vVar += 100
ConsoleWrite("In Function_2: " & $vVar & @CRLF)
EndFunc ;==>_Function_2
</syntaxhighlight>

As a general rule, try to have as few ''Global'' variables as you can. Remember that you can share ''Local'' variables between functions - and even change their values - by passing them as parameters as we will see in the ''ByRef'' section below. And declaring a variable as ''Static'' allows you retain its value even though the function in which it is used has ended.

=Passing variables as parameters using ByRef=
When you call a function in AutoIt, you can pass parameters to the function by including them in the parentheses following the function name like this - ''Function(Parameter_1, Parameter_2)''. Passing variables in this way means that you can use variables that have been declared as ''Local'' within other functions. Note that the parameters are automatically declared as ''Local'' variables within the called function and so do not need to be declared again in the code.

Variables can be passed as parameters to a function in 2 ways:

'''By Value''' - This is the default. The parameter is treated as a ''Local'' variable within the function to which it is passed and any changes made to it are lost when the function ends. So no changes are made to the ''Local'' variable within the original function.

'''By Reference''' - This is used when ''ByRef'' is added ''before'' the variable name in the parameter list of the function declaration. Now any changes to the variable made in the function to which it is passed also affect the ''Local'' variable in the original function. If you do not understand why this is such a powerful capability, you need to read the ''Global/Local'' section again!

Here is a small example to show how parameters are passed when calling a function:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>; only required for MsgBox constants

Func_A()

Func Func_A()
; Declare variables
Local $iVar_A1 = 10
Local $iVar_A2 = 20
; And read them
MsgBox($MB_SYSTEMMODAL, "Read", "Initial read in Func A:" & @CRLF & "Var A1 = " & $iVar_A1 & @CRLF & "Var A2 = " & $iVar_A2)

; Now pass these variables to another function - we use the names we have already declared in this function
Func_B($iVar_A1, $iVar_A2)

; We changed the parameters in Func_B - but nothing happened to the variables in this function
MsgBox($MB_SYSTEMMODAL, "Read", "Second read in Func A:" & @CRLF & "Var A1 = " & $iVar_A1 & @CRLF & "Var A2 = " & $iVar_A2)
EndFunc ;==>Func_A

Func Func_B($iVar_B1, $iVar_B2) ; There is no need to declare the variables as parameters are automatically Local in scope
; Now read these variables - note that they have the same value as the variables in Func_A
MsgBox($MB_SYSTEMMODAL, "Read", "Initial read in Func B:" & @CRLF & "Var B1 = " & $iVar_B1 & @CRLF & "Var B2 = " & $iVar_B2)

; Let us change them
$iVar_B1 = 100
$iVar_B2 = 200

; And confirm that they have changed
MsgBox($MB_SYSTEMMODAL, "Read", "Second read in Func B:" & @CRLF & "Var B1 = " & $iVar_B1 & @CRLF & "Var B2 = " & $iVar_B2)

; Now return to the other function
EndFunc ;==>Func_B
</syntaxhighlight>
As you can see, the ''Local'' variables within ''Func_A'' are read perfectly by ''Func_B'' when passed as parameters, even though they were declared as ''Local'' in ''Func_A''. However, although ''Func_B'' changes the value of the variables, the values of the original variables within ''Func_A'' are not changed.

If we want to change the value of the variables in ''Func_A'' from within ''Func_B'', we need to use the ''ByRef'' keyword as explained above and illustrated here:
<syntaxhighlight lang="autoit">
#include <MsgBoxConstants.au3>; only required for MsgBox constants

Func_A()

Func Func_A()
; Declare variables
Local $iVar_A1 = 10
Local $iVar_A2 = 20

; And read them
MsgBox($MB_SYSTEMMODAL, "Read", "Initial read in Func A:" & @CRLF & "Var A1 = " & $iVar_A1 & @CRLF & "Var A2 = " & $iVar_A2)

; Now pass these variables to another function - but this time we will pass $iVar_A2 By Reference
Func_B($iVar_A1, $iVar_A2)

; We changed the parameters in Func_B - this time we see that we have changed $iVar_A2
MsgBox($MB_SYSTEMMODAL, "Read", "Second read in Func A:" & @CRLF & "Var A1 = " & $iVar_A1 & @CRLF & "Var A2 = " & $iVar_A2)
EndFunc ;==>Func_A

Func Func_B($iVar_B1, ByRef $iVar_B2) ; Note the ByRef keyword in the function declaration for the second parameter
; Now read these variables - they have the same value as the variables in Func_A
MsgBox($MB_SYSTEMMODAL, "Read", "Initial read in Func B:" & @CRLF & "Var B1 = " & $iVar_B1 & @CRLF & "Var B2 = " & $iVar_B2)

; Let us change them
$iVar_B1 = 100
$iVar_B2 = 200

; And confirm that they have changed
MsgBox($MB_SYSTEMMODAL, "Read", "Second read in Func B:" & @CRLF & "Var B1 = " & $iVar_B1 & @CRLF & "Var B2 = " & $iVar_B2)

; Now return to the other function
EndFunc ;==>Func_B
</syntaxhighlight>

A couple of more advanced points:

- It was mentioned earlier that when you pass variables to functions AutoIt makes local copies of these variables unless you declare that they are to be passed ''ByRef''. In the special case of arrays, which are typically larger than a simple variable, AutoIt will only make a local copy if you change the array inside the function - merely accessing the array will use the original version. So passing the array ''ByRef'' is only advantageous if you intend to modify the array within the function - however, it does no harm to force the issue by using the keyword.

- If you are dealing with a simple variable of considerable size (the text of a file for example) then passing it ''ByRef'' is a sensible action. But if you want to make sure that the variable cannot be altered inside the function, you can declare it as ''Const ByRef'' in the function definition as shown here:
<syntaxhighlight lang="autoit">
Local $sString = "A very large chunk of data which we do not want to change"

Foo($sString)

Func Foo(Const ByRef $sText) ; The data is not copied, but also cannot be changed
; Uncomment this line to see what happens when we try
;$sText = "New value"
EndFunc ;==>Foo
</syntaxhighlight>

''ByRef'' is a very powerful feature - but use it carefully, or you may find that you have changed a variable when you did not want to!

Best coding practices

2015-03-10T21:14:02Z

Guinness: /* Variable Initialization */

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.

A few notes:
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.

__TOC__

== Names of Variables ==
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps 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
|-
| i || Integer || $iInteger = 10
|-
| f || Floating point || $fFloat = 0.123
|-
| n || General number (no preference) || $nNumber = 0
|-
| a || Arrays || $aArray[0]
|-
| m || Maps || $mMap[]
|-
| s || Strings (chars included) || $sString = "hello world"
|-
| b || Booleans || $bBool = True
|-
| d || Binaries || $dBinary = Binary("0x80000000")
|-
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)
|-
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")
|-
| fu || Functions || $fuMessage = MsgBox
|-
| p || Pointers || $pRect = DllStructGetPtr($tRECT)
|-
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"
|-
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)
|-
| o || Objects || $oShell = ObjCreate("shell.application")
|-
| v || Variant || $vData = ClipGet()
|-
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd
|-
| k || Keywords || $kKeyword = Default
|}

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 || $fu, $o, $s, $v
|-
| False (or True) || $b
|-
| Default || $k
|}

 
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, 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 $idGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idQuit = 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 ==
To make the transition, the variables are also 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 $_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 $_iSomeVar2.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_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 $_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 $_iVar1.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 $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, "", $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, $vVariableThatIsGlobal) ; The Global variable ($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 $vVariableThatIsGlobal = ""

For $i = 1 To 10
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.
Next
Return $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 $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 efficent 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>

UDF-spec

2015-03-06T20:05:40Z

Guinness: /* 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.
* Not use any magic numbers. Ever. None. At all. No excuses.

== 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. See [[Best_coding_practices#Names_of_Variables|Names of Variables]]

=== 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.
* Not make any permanent changes to the users computer. For example, if demonstrating a File function, be sure to delete the file after it has been used. The same applies for any function that makes a change to the environment: the changes MUST be undone.

Always remember, the readability of code in an example is MORE important than the readability of code inside the UDF itself.

Examples are stored in script 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>.

<syntaxhighlight lang="autoit">#include <Constants.au3>
#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($MB_SYSTEMMODAL, "Testing", "Button 2 was pressed") ; Will demonstrate Button 2 being pressed
EndSelect
WEnd
GUIDelete($hGUI)
EndFunc ;==>Example</syntaxhighlight>

=== Multiple Examples ===
The helpfile now supports multiple examples per function. In order to maintain backwards compatibility with any other tools that use examples, the first file is still named <code><FUNCTION>.au3</code>, but any additional examples are named <code><FUNCTION>[n].au3</code> where n is an integer counter starting at 2.

== Template UDF ==
Here is an example of a UDF called <code>MyUDF.au3</code>:

<syntaxhighlight lang="autoit">#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7
#include-once

#include "MyUDFConstants.au3"
#include "AnInclude.au3"

; #INDEX# =======================================================================================================================
; Title .........: MyUDF
; AutoIt Version : 3.3.10.2
; Language ......: English
; Author(s) .....:
; Modifiers .....:
; Forum link ....: a link to the main forum topic (if aplicable)
; 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>

Best coding practices

2015-03-06T20:04:02Z

Guinness: /* Names of Variables */

Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.

A few notes:
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.

__TOC__

== Names of Variables ==
The [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is adopted however it's simplified and regroup all the types of numbers in one type. 
In AutoIt the Hungarian notation strives to encode 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. 
Variables are initialized with the "default" value (or the most logical representation) of their type. See below in the table for specific value.

{| class="wikitable"
|-
! prefix !! covering type !! example
|-
| i || Integer || $i = 0
|-
| f || Floating point || $f = 0.0
|-
| n || General number (no preference) || $n = 0
|-
| a || Arrays || Local $a[0]
|-
| m || Maps || Local $m[]
|-
| s || Strings (chars included) || $s = ""
|-
| b || Booleans || $b = False or $b = True
|-
| d || Binaries || $d = Binary("")
|-
| id || An AutoIt controlid || $id = 0
|-
| h || Handles (and GUI handles) || $h = 0
|-
| fu || Functions || $fu = Null
|-
| p || Pointers || $p = 0
|-
| tag || Structures definition || $tag = 0
|-
| t || Structures || $t = 0
|-
| o || Objects || $o = 0 or $o = Null
|-
| v || Variant || $v = 0 or $v = "" (or $v = Null)
|-
| e || Enumerations || N/A
|-
| k || Keywords || $k = Default
|}

The variables are named following this schema:
{| class="wikitable"
|-
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| i || f || MyFlag
|}

Example:
<syntaxhighlight lang="autoit">
; Assign a Local variable the number 5.
Local $iSomeVar = 5

; Assign a Local variable the number 1.
Local $ifMyFlag = 1

; Assign a Local variable an array of numbers.
Local $aiArray = 0

; Re-declare the array to size and fill it.
Local $aiArray[3] = [0, 0.25, 3 / 4]
</syntaxhighlight>

Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.

Example:
<syntaxhighlight lang="autoit">
;Bad
Local $iSomeVar1, $aiArray = 0
Local $iSomeVar2 = 5

;Good
Local $iSomeVar1 = 0, $iSomeVar2 = 5
Local $aiArray = 0
</syntaxhighlight>
You can still categorize your variables and declare for example the $iSomeVar2 on another line.

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

Local $vValue ; Bad, this is initially blank.
Local $vVal = 0 ; Good

MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)

; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt
; is a little less forgiving in that it initialises the variable as being blank and doesn't throw any error, unlike some moder C++ compilers.
</syntaxhighlight>

== Scopes of Variables ==
To make the transition, the variables are also 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 $_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 $_iSomeVar2.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_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 $_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 $_iVar1.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 $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, "", $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, $vVariableThatIsGlobal) ; The Global variable ($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 $vVariableThatIsGlobal = ""

For $i = 1 To 10
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.
Next
Return $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 $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 efficent 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">
;Bad
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes.

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

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

2015-03-06T20:03:20Z

Guinness: /* Names of Variables */

Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.

A few notes:
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.

__TOC__

== Names of Variables ==
The [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is adopted however it's simplified and regroup all the types of numbers in one type. 
In AutoIt the Hungarian notation strives to encode 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. 
Variables are initialized with the "default" value (or the most logical representation) of their type. See below in the table for specific value.

{| class="wikitable"
|-
! prefix !! covering type !! example
|-
| i || Integer || $i = 0
|-
| f || Floating point || $f = 0.0
|-
| n || General number (no preference) || $n = 0
|-
| a || Arrays || Local $a[0] = ""
|-
| m || Maps || Local $m[]
|-
| s || Strings (chars included) || $s = ""
|-
| b || Booleans || $b = False or $b = True
|-
| d || Binaries || $d = Binary("")
|-
| id || An AutoIt controlid || $id = 0
|-
| h || Handles (and GUI handles) || $h = 0
|-
| fu || Functions || $fu = Null
|-
| p || Pointers || $p = 0
|-
| tag || Structures definition || $tag = 0
|-
| t || Structures || $t = 0
|-
| o || Objects || $o = 0 or $o = Null
|-
| v || Variant || $v = 0 or $v = "" (or $v = Null)
|-
| e || Enumerations || N/A
|-
| k || Keywords || $k = Default
|}

The variables are named following this schema:
{| class="wikitable"
|-
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| i || f || MyFlag
|}

Example:
<syntaxhighlight lang="autoit">
; Assign a Local variable the number 5.
Local $iSomeVar = 5

; Assign a Local variable the number 1.
Local $ifMyFlag = 1

; Assign a Local variable an array of numbers.
Local $aiArray = 0

; Re-declare the array to size and fill it.
Local $aiArray[3] = [0, 0.25, 3 / 4]
</syntaxhighlight>

Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.

Example:
<syntaxhighlight lang="autoit">
;Bad
Local $iSomeVar1, $aiArray = 0
Local $iSomeVar2 = 5

;Good
Local $iSomeVar1 = 0, $iSomeVar2 = 5
Local $aiArray = 0
</syntaxhighlight>
You can still categorize your variables and declare for example the $iSomeVar2 on another line.

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

Local $vValue ; Bad, this is initially blank.
Local $vVal = 0 ; Good

MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)

; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt
; is a little less forgiving in that it initialises the variable as being blank and doesn't throw any error, unlike some moder C++ compilers.
</syntaxhighlight>

== Scopes of Variables ==
To make the transition, the variables are also 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 $_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 $_iSomeVar2.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_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 $_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 $_iVar1.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 $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, "", $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, $vVariableThatIsGlobal) ; The Global variable ($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 $vVariableThatIsGlobal = ""

For $i = 1 To 10
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.
Next
Return $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 $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 efficent 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">
;Bad
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes.

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

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

2015-03-06T19:59:46Z

Guinness: Fixed comment

Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.

A few notes:
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.

__TOC__

== Names of Variables ==
The [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is adopted however it's simplified and regroup all the types of numbers in one type. 
In AutoIt the Hungarian notation strives to encode 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. 
Variables are initialized with the "default" value (or the most logical representation) of their type. See below in the table for specific value.

{| class="wikitable"
|-
! prefix !! covering type !! example
|-
| i || Integer || $i = 0
|-
| f || Floating point || $f = 0.0
|-
| n || General number (no preference) || $n = 0
|-
| a || Arrays || Dim $a[1] and $a[0] = "Value"
|-
| m || Maps || Dim $m[] and $m["key"] = "Value"
|-
| s || Strings (chars included) || $s = "" or $s = Null
|-
| b || Booleans || $b = False or $b = True
|-
| d || Binaries || $d = Binary("")
|-
| id || An AutoIt controlid || $id = 0
|-
| h || Handles (and GUI handles) || $h = 0
|-
| fu || Functions || $fu = Null
|-
| p || Pointers || $p = 0
|-
| tag || Structures definition || $tag = 0
|-
| t || Structures || $t = 0
|-
| o || Objects || $o = 0 or $o = Null
|-
| v || Variant || $v = 0 or $v = "" (or $v = Null)
|-
| e || Enumerations || N/A
|-
| k || Keywords || $k = Default
|}

The variables are named following this schema:
{| class="wikitable"
|-
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| i || f || MyFlag
|}

Example:
<syntaxhighlight lang="autoit">
; Assign a Local variable the number 5.
Local $iSomeVar = 5

; Assign a Local variable the number 1.
Local $ifMyFlag = 1

; Assign a Local variable an array of numbers.
Local $aiArray = 0

; Re-declare the array to size and fill it.
Local $aiArray[3] = [0, 0.25, 3 / 4]
</syntaxhighlight>

Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.

Example:
<syntaxhighlight lang="autoit">
;Bad
Local $iSomeVar1, $aiArray = 0
Local $iSomeVar2 = 5

;Good
Local $iSomeVar1 = 0, $iSomeVar2 = 5
Local $aiArray = 0
</syntaxhighlight>
You can still categorize your variables and declare for example the $iSomeVar2 on another line.

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

Local $vValue ; Bad, this is initially blank.
Local $vVal = 0 ; Good

MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)

; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt
; is a little less forgiving in that it initialises the variable as being blank and doesn't throw any error, unlike some moder C++ compilers.
</syntaxhighlight>

== Scopes of Variables ==
To make the transition, the variables are also 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 $_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 $_iSomeVar2.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_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 $_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 $_iVar1.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 $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, "", $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, $vVariableThatIsGlobal) ; The Global variable ($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 $vVariableThatIsGlobal = ""

For $i = 1 To 10
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.
Next
Return $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 $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 efficent 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">
;Bad
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes.

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

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>

Snippets ( AutoIt )

2015-01-16T21:42:59Z

Guinness: /* _IsInTrial */

__TOC__
[[category:Snippets]]

{{Snippet Credit Header}}

== AutoItWinShow ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

Example()

Func Example()
; Display AutoIt's Hidden Window. See AutoItWinGetTitle and AutoItWinSetTitle for more details.
AutoItWinShow()

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
EndSwitch
WEnd
EndFunc ;==>Example

; Display AutoIt's Hidden Window. Returns the handle of the window.
Func AutoItWinShow()
Local Const $hWnd = WinGetHandle(AutoItWinGetTitle()) ; Get the handle of the AutoIt Hidden Window by finding out the title of the AutoIt Hidden Window.
WinMove($hWnd, '', (@DesktopWidth / 2) - 250, (@DesktopHeight / 2) - 250, 500, 500) ; Move the AutoIt Hidden Window and re-size for a better view of the data that will be set.
WinSetState($hWnd, '', @SW_SHOW) ; Show the AutoIt Hidden Window, normally this is hidden, but in the interest of this example I'm displaying it.
Return $hWnd
EndFunc ;==>AutoItWinShow
</syntaxhighlight>

[[#top | ReturnToContents]]

== AutoItWinGetText ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Example()

Func Example()
; Display AutoIt's Hidden Window. See AutoItWinGetTitle and AutoItWinSetTitle for more details.
AutoItWinShow()

; Add a text string to AutoIt's Hidden Window. Compile to see the text in AutoIt's Hidden Window.
AutoItWinSetText('Welcome to AutoIt V' & @AutoItVersion & @CRLF)

; Add a text string to AutoIt's Hidden Window. Compile to see the text in AutoIt's Hidden Window.
AutoItWinSetText('Windows Type: ' & @OSType & @CRLF)

; Display the text stored in AutoIt's Hidden Window.
MsgBox(4096, '', AutoItWinGetText())

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
EndSwitch
WEnd
EndFunc ;==>Example

; Retrieve the text in AutoIt's Hidden Window.
Func AutoItWinGetText()
Local Const $hWnd = WinGetHandle(AutoItWinGetTitle()) ; Get the handle of the AutoIt Hidden Window by finding out the title of the AutoIt Hidden Window.
Return ControlGetText($hWnd, '', ControlGetHandle($hWnd, '', 'Edit1'))
EndFunc ;==>AutoItWinGetText

; Add text to AutoIt's Hidden Window.
Func AutoItWinSetText($sString)
Local Const $hWnd = WinGetHandle(AutoItWinGetTitle()) ; Get the handle of the AutoIt Hidden Window by finding out the title of the AutoIt Hidden Window.
Return ControlSetText($hWnd, "", ControlGetHandle($hWnd, "", 'Edit1'), ControlGetText($hWnd, '', ControlGetHandle($hWnd, '', 'Edit1')) & $sString)
EndFunc ;==>AutoItWinSetText

; Display AutoIt's Hidden Window. Returns the handle of the window.
Func AutoItWinShow()
Local Const $hWnd = WinGetHandle(AutoItWinGetTitle()) ; Get the handle of the AutoIt Hidden Window by finding out the title of the AutoIt Hidden Window.
WinMove($hWnd, '', (@DesktopWidth / 2) - 250, (@DesktopHeight / 2) - 250, 500, 500) ; Move the AutoIt Hidden Window and re-size for a better view of the data that will be set.
WinSetState($hWnd, '', @SW_SHOW) ; Show the AutoIt Hidden Window, normally this is hidden, but in the interest of this example I'm displaying it.
Return $hWnd
EndFunc ;==>AutoItWinShow
</syntaxhighlight>

[[#top | ReturnToContents]]

== _DockToWindow ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#include <WinAPI.au3>
#include <WindowsConstants.au3>

If (Not ProcessExists("SciTE.exe")) Then
Exit MsgBox(4096, '', "Please start SciTE.exe")
EndIf

Example()

Func Example()
; Create a GUI, similar to SciTE Jump's GUI.
Local Const $hGUI = GUICreate('', 215, 400, -1, -1, BitOR($GUI_SS_DEFAULT_GUI, $WS_MAXIMIZEBOX, $WS_SIZEBOX))

GUISetState(@SW_SHOWNORMAL, $hGUI)

; Dock the first window to left and adjust the width based on the width of the second GUI.
_DockToWindow(WinGetHandle("[CLASS:SciTEWindow]"), $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example

Func _DockToWindow(Const $hHandle_1, Const $hHandle_2)
; Retrieve the working area, this is minus the taskbar dimensions so slightly different to @DesktopHeight and @DesktopWidth which is the
; monitors height and width.
Local Const $SPI_GETWORKAREA = 48
Local Const $tWorkArea = DllStructCreate($tagRECT)
_WinAPI_SystemParametersInfo($SPI_GETWORKAREA, 0, DllStructGetPtr($tWorkArea))

; Retieve the position of the second GUI.
Local Const $aClientSize_2 = WinGetPos($hHandle_2)

; Set the state of the windows to 'Restore'.
WinSetState($hHandle_1, '', @SW_RESTORE)
WinSetState($hHandle_2, '', @SW_RESTORE)

; Move the first to the far left of the screen and adjust the width to the total screen width minus the width of the second GUI. e.g. 1366 - 215
WinMove($hHandle_1, '', DllStructGetData($tWorkArea, 'Left'), DllStructGetData($tWorkArea, 'Top'), DllStructGetData($tWorkArea, 'Right') - DllStructGetData($tWorkArea, 'Left') - $aClientSize_2[2], DllStructGetData($tWorkArea, 'Bottom') - DllStructGetData($tWorkArea, 'Top'))

; Move the second window to the far right in between the remaining space and adjust the height of the GUI.
WinMove($hHandle_2, '', DllStructGetData($tWorkArea, 'Right') - DllStructGetData($tWorkArea, 'Left') - $aClientSize_2[2], DllStructGetData($tWorkArea, 'Top'), $aClientSize_2[2], DllStructGetData($tWorkArea, 'Bottom') - DllStructGetData($tWorkArea, 'Top'))
EndFunc ;==>_DockToWindow
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FuncExists ==

{{Snippet Header
| AuthorURL = 52-geosoft
| AuthorName = GEOSoft
}}

<syntaxhighlight lang="autoit">
MsgBox(0, "TEST", "Function Exists = " & _FuncExists("_FuncExists", @ScriptFullPath))

Func _FuncExists($sFunc, $sPath)
If Not FileExists($sPath) Then Return SetError(1)
Local Const $sStr = FileRead($sPath)
Local Const $sRegEx = "(?i)(?m:^|\n)\s*Func\s+(" & $sFunc & ")\s*\("
Local Const $aRegEx = StringRegExp($sStr, $sRegEx, 1)
If IsArray($aRegEx) Then Return 1
Return 0
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FunctionSort ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Get the list of Functions in a script and sort by alphabetical order.

#include <Array.au3>
#include <String.au3>

Local $sFile = FileOpenDialog(@ScriptName, "Select an AutoIt file.", "Au3 (*.au3)")

If @error Then
Exit
EndIf
ClipPut(_FunctionSort($sFile))

Func _FunctionSort($sFilePath)
Local Const $sRead = FileRead($sFilePath)

Local $aReturn = StringRegExp("Func _Count()" & @CRLF & "EndFunc ;==>_Count" & $sRead, '(?s)(?i)Func(.*?)EndFunc', 3)

If @error Then
Return SetError(1, 0, 0)
EndIf

$aReturn[0] = UBound($aReturn, 1) - 1

_ArraySort($aReturn, 0, 1)

Local $sReturn

For $A = 1 To $aReturn[0]
$sReturn &= "Func" & $aReturn[$A] & "EndFunc" & @CRLF & @CRLF
Next

Return $sReturn
EndFunc ;==>_FunctionSort
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsBeta ==

{{Snippet Header
| AuthorURL = 10673-mlipok
| AuthorName = mLipok
}}

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

Example()

Func Example()
Local $aTest[10]
_ArrayUnique($aTest, 0, 5)
Local $iError = @error
ConsoleWrite('$iError = ' & $iError & @CRLF)
If _IsBeta() Then
If $iError = 3 Then
MsgBox($MB_SYSTEMMODAL, '@error', '3 - $iBase or $iCase contains an invalid value' & @CRLF & @AutoItVersion)
EndIf
Else
If $iError = 2 Then
MsgBox($MB_SYSTEMMODAL, '@error', '2 - $iBase or $iCase contains an invalid value' & @CRLF & @AutoItVersion)
EndIf
EndIf
EndFunc ;==>Example

Func _IsBeta()
Return Mod(StringSplit(@AutoItVersion, '.')[3], 2) == 1
EndFunc ;==>_IsBeta
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsButton ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <ButtonConstants.au3>
#include <Constants.au3>
#include <WinAPI.au3>

Example()

Func Example()
Local Const $hGUI = GUICreate('')
Local Const $iLabel = GUICtrlCreateButton('', 0, 0, 50, 50)
Local Const $iCheckbox = GUICtrlCreateCheckbox('', 0, 0, 100, 20) ; This is considered a 'Button' by _WinAPI_GetClassName too.

GUISetState(@SW_SHOWNORMAL, $hGUI)

MsgBox(4096, '', 'AutoIt Button ID: ' & _IsButton($iLabel) & @CRLF & _
'AutoIt Button Handle: ' & _IsButton(GUICtrlGetHandle($iLabel)) & @CRLF & _
'AutoIt Checkbox ID: ' & _IsButton($iCheckbox) & @CRLF & _
'AutoIt Checkbox Handle: ' & _IsButton(GUICtrlGetHandle($iCheckbox)) & @CRLF)

Return GUIDelete($hGUI)
EndFunc ;==>Example

; Check if a variable is referencing a Button control.
Func _IsButton($hWnd)
If IsHWnd($hWnd) = 0 Then
$hWnd = GUICtrlGetHandle($hWnd)
EndIf

Local Const $sClassName = _WinAPI_GetClassName($hWnd)

If $sClassName = 'Button' Then
Local Const $aStyle[5] = [4, $BS_CHECKBOX, $BS_AUTOCHECKBOX, $BS_RADIOBUTTON, $BS_AUTORADIOBUTTON]

Local Const $iLong = _WinAPI_GetWindowLong($hWnd, $GWL_STYLE)

For $i = 1 To $aStyle[0]
If BitAND($iLong, $aStyle[$i]) = $aStyle[$i] Then
Return False
EndIf
Next

Return True
EndIf

Return False
EndFunc ;==>_IsButton
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsControlID ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Check if a Control ID is a native AutoIt control.

#include <GUIListView.au3>
#include <WinAPI.au3>

Example()

Func Example()
Local Const $hGUI = GUICreate('')
Local Const $iControlID = GUICtrlCreateLabel('', 0, 0, 500, 500)
Local Const $hListView = _GUICtrlListView_Create($hGUI, 'Example', 0, 0, 500, 500)

GUISetState(@SW_SHOWNORMAL, $hGUI)

MsgBox(4096, '', 'AutoIt ControlID: ' & _IsControlID($iControlID) & @CRLF & _
'Random Number: ' & _IsControlID(Random(42, 99, 1)) & @CRLF & _
'AutoIt ControlID Handle: ' & _IsControlID(GUICtrlGetHandle($iControlID)) & @CRLF & _
'ListView UDF Handle: ' & _IsControlID($hListView) & @CRLF & _
'ListView UDF Handle: ' & _IsControlID(GUICtrlGetHandle($hListView)) & @CRLF)

_GUICtrlListView_Destroy($hListView)

Return GUIDelete($hGUI)
EndFunc ;==>Example

Func _IsControlID($iControlID)
If IsHWnd($iControlID) Then
$iControlID = _WinAPI_GetDlgCtrlID($iControlID)
EndIf

Return IsHWnd(GUICtrlGetHandle($iControlID)) = 1
EndFunc ;==>_IsControlID
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetAutoItIncludesFromSciTE ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

ConsoleWrite(_GetAutoItIncludesFromSciTE() & @CRLF)

; Retrieve the AutoIt includes path from the SciTE process.
Func _GetAutoItIncludesFromSciTE()
Local $sRelativePath = '..\Include'
Local Const $sWorkingDir = @WorkingDir
FileChangeDir(_WinAPI_PathRemoveFileSpec(_WinAPI_GetProcessFileName(ProcessExists('SciTE.exe'))))
$sRelativePath = _WinAPI_GetFullPathName($sRelativePath)
FileChangeDir($sWorkingDir)
Return _WinAPI_PathRemoveBackslash($sRelativePath)
EndFunc ;==>_GetAutoItIncludesFromSciTE
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetAutoItInstall ==

{{Snippet Header
|AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Get the AutoIt installation folder.

ConsoleWrite(_GetAutoItInstall() & @CRLF)

Func _GetAutoItInstall()
Return StringLeft(@AutoItExe, StringInStr(@AutoItExe, "\", 2, -1) - 1)
EndFunc ;==>_GetAutoItInstall
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetAutoItInstallEx ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_GetAutoItInstallEx() & @CRLF)

; Get the installation of AutoIt. An improved version of _GetAutoItInstall.
Func _GetAutoItInstallEx()
Local $aWow6432Node[2] = ['', 'Wow6432Node\'], $aFiles[4] = [3, @ProgramFilesDir, EnvGet("PROGRAMFILES"), EnvGet("PROGRAMFILES(X86)")]
Local $sFilePath = RegRead('HKEY_LOCAL_MACHINE\SOFTWARE\' & $aWow6432Node[@AutoItX64] & 'AutoIt v3\AutoIt\', 'InstallDir')
If @error Then
For $A = 1 To $aFiles[0]
$aFiles[$A] &= '\AutoIt'
If FileExists($aFiles[$A]) Then
Return $aFiles[$A]
EndIf
Next
Return SetError(1, 0, '')
Else
Return $sFilePath
EndIf
EndFunc ;==>_GetAutoItInstallEx
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetAutoItInstallFromSciTE ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_GetAutoItInstallFromSciTE() & @CRLF)

; Retrieve the AutoIt installation path from the SciTE process.
Func _GetAutoItInstallFromSciTE()
Local $sRelativePath = '..\', $sWorkingDir = @WorkingDir
FileChangeDir( _WinAPI_PathRemoveFileSpec(_WinAPI_GetProcessFileName(ProcessExists("SciTE.exe"))))
$sRelativePath = _WinAPI_GetFullPathName($sRelativePath)
FileChangeDir($sWorkingDir)
Return _WinAPI_PathRemoveBackslash($sRelativePath)
EndFunc ;==>_GetAutoItInstallFromSciTE
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetClasses ==

{{Snippet Header
| AuthorURL = 24-cyberslug
| AuthorName = CyberSlug
}}

<syntaxhighlight lang="autoit">
; Get ALL Controls Info

Example()

Func Example()
; Run Calculator
Run("calc.exe")

; Wait 10 seconds for the Calculator window to appear.
Local const $hWnd = WinWait("[CLASS:CalcFrame]", '', 10)

; Retrieve a list of all the controls in the Calculator window using the handle returned by WinWait.
MsgBox(4096, '', _GetClasses($hWnd))

; Close the Calculator window using the handle returned by WinWait.
WinClose($hWnd)
EndFunc ;==>Example

; This function returns an @LF-separated list of controls on the specified window.
Func _GetClasses($sTitle, $sText = '')
Local $iCount_Button = 0, $iCount_Edit = 0, $iCount_Static = 0
Local $aClasses = StringSplit(WinGetClassList($sTitle, $sText), @LF)
Local $aClassID[$aClasses[0] + 1] = [$aClasses[0]]

For $i = 1 To $aClasses[0]
Select
Case $aClasses[$i] = "Button"
$iCount_Button += 1
$aClassID[$i] = $aClasses[$i] & $iCount_Button
Case $aClasses[$i] = "Edit"
$iCount_Edit += 1
$aClassID[$i] = $aClasses[$i] & $iCount_Edit
$aClasses[$i] = "Input"
Case $aClasses[$i] = "Static"
$iCount_Static += 1
$aClassID[$i] = $aClasses[$i] & $iCount_Static
$aClasses[$i] = "Label"
Case Else
If $aClasses[$i] <> "" Then
$aClassID[$i] = $aClasses[$i] & "?"
EndIf
EndSelect
Next

; Combine the results.
Local $sReturn = ""

For $i = 1 To $aClassID[0]
$sReturn &= $aClassID[$i] & @LF
Next

Return $sReturn
EndFunc ;==>_GetClasses
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; FileRead Alternative

Func _GetFile($sFile, $iFormat = 0)
Local $hFileOpen = FileOpen($sFile, $iFormat)
If $hFileOpen = -1 Then
Return SetError(1, 0, "")
EndIf
Local $sData = FileRead($hFileOpen)
FileClose($hFileOpen)
Return $sData
EndFunc ;==>_GetFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetTitle ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Get the title of your program.

ConsoleWrite(_GetTitle('Example') & @CRLF)
; The second parameter would normally be @ScriptDir & '\Uninstall.exe' for example, but for this demonstration I'm using the full path.
ConsoleWrite(_GetTitle('Example', @ScriptFullPath) & @CRLF)

Func _GetTitle($sProgramName, $sInstallPath = '')
Local $aOSArch[2] = ['', ' (64-bit)'], $aPortable[2] = [' (Portable)', '']
Return $sProgramName & $aOSArch[@AutoItX64] & $aPortable[FileExists($sInstallPath)]
EndFunc ;==>_GetTitle
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetXML ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Simple Way Of Parsing XML Data.

#include <Array.au3>

Global $aReturn, $sXMLData

$sXMLData = "<data>This is a Simple example of XML</data><data>This is a Simple example of XML and is the Second String.</data>"
$aReturn = _GetXML($sXMLData, "data")
_ArrayDisplay($aReturn, "_GetXML()")

Func _GetXML($sString, $sData)
Local $aError[2] = [1, $sString], $aReturn
$aReturn = StringRegExp('<' & $sData & '></' & $sData & '>' & $sString, '(?s)(?i)<' & $sData & '>(.*?)</' & $sData & '>', 3)
If @error Then
Return SetError(1, 0, $aError)
EndIf
$aReturn[0] = UBound($aReturn, 1) - 1
Return SetError(0, 0, $aReturn)
EndFunc ;==>_GetXML
</syntaxhighlight>

[[#top | ReturnToContents]]

== Include Source With Exe ==

{{Snippet Header
| AuthorURL = 54985-jlogan3o13
| AuthorName = JLogan3o13
}}

<syntaxhighlight lang="autoit">
;recover source .au3 file with /Extract switch
; The above code would be copied into the top of your script. The source location (C:\Test.au3 in my example) is the full path to your script file.
;Once compiled, if you run the script from the Run line with the /Extract switch, it will extact the original .au3 file into the Temp directory and will exit without actually executing the script.
If StringInStr($cmdlineRaw, "/Extract") Then
FileInstall("C:\Test.au3", @TempDir & "\Test.au3", 1)
Exit
EndIf
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsANSIFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

ConsoleWrite(_IsANSIFile(@ScriptFullPath) & @LF) ; Returns True.

Func _IsANSIFile($sFilePath)
Return FileGetEncoding($sFilePath) = $FO_READ
EndFunc ;==>_IsUnicodeFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsUnicodeFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

ConsoleWrite(_IsUnicodeFile(@ScriptFullPath) & @LF) ; Returns False.

Func _IsUnicodeFile($sFilePath)
Return FileGetEncoding($sFilePath) = $FO_UNICODE
EndFunc ;==>_IsUnicodeFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsAu3File ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_IsAu3File(@AutoItExe) & @CRLF)
ConsoleWrite(_IsAu3File(@ScriptFullPath) & @CRLF)

; Checks whether the filepath is an au3 file.
Func _IsAu3File($sFilePath)
Return StringTrimLeft($sFilePath, StringInStr($sFilePath, ".", 2, -1)) = "au3"
EndFunc ;==>_IsAu3File
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsDefault ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
If _IsDefault(Default) Then
MsgBox(0, "_IsDefault() - 1", "This was a Default variable.")
EndIf

If _IsDefault(-1) Then
MsgBox(0, "_IsDefault() - 2", "This was a Default variable.")
EndIf

If _IsDefault("Other") Then
MsgBox(0, "_IsDefault() - 3", "This was a Default variable.")
EndIf

Func _IsDefault($sDefault)
Return StringRegExp($sDefault, "(?-i)\s|Default|-1|0")
EndFunc ;==>_IsDefault
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsInTrial ==

{{Snippet Header
| AuthorURL = 4813-smoke-n
| AuthorName = SmOke_N
}}

<syntaxhighlight lang="autoit">
#include <Date.au3> ; Required for _DateDiff()

ConsoleWrite('Date trial started: ' & @YEAR & '/' & @MON & '/01' & @CRLF & _
'Today''s date: ' & @YEAR & '/' & @MON & '/' & @MDAY & @CRLF & _
'Trial period: 30 days' & @CRLF & _
'Is the trial period still valid: ' & _IsInTrial(@YEAR & '/' & @MON & '/01', 30) & @CRLF)

; Check if a trial period date is still valid.
Func _IsInTrial($sDateString, $iDays)
Return (_DateDiff('D', $sDateString, _NowCalcDate()) < $iDays)
EndFunc ;==>_IsInTrial
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsVisible ==

{{Snippet Header
| AuthorURL =
| AuthorName = Multiple
}}

<syntaxhighlight lang="autoit">
; Check if the Notepad Window is visible.

Example()

Func Example()
; Run Notepad
Run("notepad.exe")

; Wait 10 seconds for the Notepad window to appear.
Local $hWnd = WinWait("[CLASS:Notepad]", "", 10)

; Check if the Notepad window is visible and display the appropriate message box.
If _IsVisible($hWnd) Then
MsgBox(4096, "", "Notepad is visible.")
Else
MsgBox(4096, "", "Notepad isn't visible.")
EndIf

; Close the Notepad window using the handle returned by WinWait.
WinClose($hWnd)
EndFunc ;==>Example

; Check if the window is visible.
Func _IsVisible($hWnd)
Return BitAND(WinGetState($hWnd), 2) = 2
EndFunc ;==>_IsVisible
</syntaxhighlight>

[[#top | ReturnToContents]]

== Open Help File to Desired Page ==

{{Snippet Header
| AuthorURL = 1967-garyfrost
| AuthorName = GaryFrost
}}

<syntaxhighlight lang="autoit">
; Open help file / Open a desired page

Global Const $sAutoItPath = RegRead("HKEY_LOCAL_MACHINE\SOFTWARE\AutoIt v3\AutoIt", "InstallDir")

Run(@WindowsDir & "\hh.exe " & $sAutoItPath & "\AutoIt3.chm::/html/functions/GUICtrlCreateUpdown.htm")
</syntaxhighlight>

[[#top | ReturnToContents]]

== _RunAU3 ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
_RunAU3("AU3_Example.txt", '"This is a commandline example!"')

Func _RunAU3($sFilePath, $sCommandLine = "", $sWorkingDir = "", $iShowFlag = @SW_SHOW, $iOptFlag = 0)
Return Run('"' & @AutoItExe & '" /AutoIt3ExecuteScript "' & $sFilePath & '" ' & $sCommandLine, $sWorkingDir, $iShowFlag, $iOptFlag)
EndFunc ;==>_RunAU3

Func _RunWaitAU3($sFilePath, $sCommandLine = "", $sWorkingDir = "", $iShowFlag = @SW_SHOW, $iOptFlag = 0)
Local $iPID
$iPID = RunWait('"' & @AutoItExe & '" /AutoIt3ExecuteScript "' & $sFilePath & '" ' & $sCommandLine, $sWorkingDir, $iShowFlag, $iOptFlag)
If @error Then
Return SetError(@error, 1, 0)
EndIf
Return $iPID
EndFunc ;==>_RunWaitAU3
</syntaxhighlight>

[[#top | ReturnToContents]]

== Run Any au3 File From Your Program ==

{{Snippet Header
| AuthorURL = 4920-valuater
| AuthorName = Valuater
}}

<syntaxhighlight lang="autoit">
; Run Any Au3 File From Your Program

Global Const $sFilePath = @ScriptDir & "\Test.au3"

If @Compiled Then
Global Const $sFileExe = FileGetShortName(@AutoItExe & ' /AutoIt3ExecuteScript "' & $sFilePath & '"')
Run($sFileExe)
Else
Global Const $sFileAu3 = FileGetShortName($sFilePath)
Run(@AutoItExe & " " & $sFileAu3, "", @SW_HIDE)
EndIf
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ScriptName ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_ScriptName() & @CRLF)

; Return the @ScriptName minus the .exe or .au3 extension.
Func _ScriptName()
Return StringLeft(@ScriptName, StringInStr(@ScriptName, '.', 2, -1) - 1)
EndFunc ;==>_ScriptName
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ScriptVersion ==

{{Snippet Header
| AuthorURL = 31149-milesahead
| AuthorName = MilesAhead
}}

<syntaxhighlight lang="autoit">
#NoTrayIcon

#Region ;**** Directives created by AutoIt3Wrapper_GUI ****
#AutoIt3Wrapper_UseUpx=n
#AutoIt3Wrapper_Res_Fileversion=1.2.3.4
#AutoIt3Wrapper_Res_LegalCopyright=2012 www.favessoft.com
#AutoIt3Wrapper_Res_Language=1033
#AutoIt3Wrapper_AU3Check_Parameters=-d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7
#EndRegion ;**** Directives created by AutoIt3Wrapper_GUI ****

Global $version = _ScriptVersion()

Global $msg = "ScriptVerDemo" & " " & $version & " Copyright (c) 2012 www.favessoft.com" & @CRLF & @CRLF

MsgBox(0x1040, "", $msg)

; return File Version string from compiled or .au3 script
; returns "" if no version info available
; Note: The .au3 script must contain #AutoItWrapper
; directives with file version or "" is returned.
Func _ScriptVersion(Const $Script = @ScriptFullPath)
If StringRight($Script,4) = ".exe" Then
Return FileGetVersion($Script)
Else
Local Const $scriptHandle = FileOpen($Script)
Local $ver
Local $found = False
Local $pos

If $scriptHandle <> -1 Then
Do
$ver = FileReadLine($scriptHandle)
$sPos = StringInStr($ver, "_Fileversion=")

If $sPos Then
$ver = StringMid($ver, $sPos + StringLen("_Fileversion="))
$found = True
ExitLoop
EndIf
Until StringLeft($ver, 1) <> "#"

FileClose($scriptHandle)
EndIf
EndIf

If Not $found Then $ver = ""

Return $ver
EndFunc ;==>_ScriptVersion
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SetFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; FileWrite Alternative

Func _SetFile(Const $sString, Const $sFile, Const $iOverwrite = 0)
Local Const $hFileOpen = FileOpen($sFile, $iOverwrite + 1)

FileWrite($hFileOpen, $sString)
FileClose($hFileOpen)

If @error Then
Return SetError(1, 0, $sString)
EndIf

Return $sString
EndFunc ;==>_SetFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ShowHelp ==

{{Snippet Header
| AuthorURL = 60350-chimaera
| AuthorName = Chimaera
}}

<syntaxhighlight lang="autoit">
HotKeySet("{F1}", "_ShowHelp")

Func _ShowHelp()
Return ShellExecute(@ProgramFilesDir & "\AutoIt3\AutoIt3Help.exe") ; change this to the location of your own helpfile.
EndFunc ;==>_ShowHelp
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SingletonPID ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Local $iSingleton = _SingletonPID('RandomName', 1)

If $iSingleton = 0 Then
MsgBox(4096, '', 'This is the first instance of the program running: ' & $iSingleton)
Else
MsgBox(4096, '', 'There is another instance running. This PID is: ' & $iSingleton)
EndIf

; #FUNCTION# ====================================================================================================================
; Name ..........: _SingletonPID
; Description ...: Enforce a design paradigm where only one instance of the script may be running.
; Syntax ........: _SingletonPID($sOccurenceName[, $iFlag = 0])
; Parameters ....: $sOccurenceName - String to identify the occurrence of the script.
; $iFlag - [optional] Optional parameters. Default is 0.
; 0 - Exit the script with the exit code -1 if another instance already exists.
; 1 - Return the PID of the main executable and without exiting the script too.
; Return values .: Success - 0 No other process is running.
; Failure - The PID of the main executable.
; Author ........: guinness with initial ideas by Valik for _Singleton & KaFu for _EnforceSingleInstance.
; Example .......: Yes
; ===============================================================================================================================
Func _SingletonPID(Const $sOccurenceName, Const $iFlag = 0)
Local $hHandle = WinGetHandle($sOccurenceName)

If @error Then
AutoItWinSetTitle($sOccurenceName)
$hHandle = WinGetHandle($sOccurenceName)
ControlSetText($hHandle, '', ControlGetHandle($hHandle, '', 'Edit1'), @AutoItPID)
Else
If BitAND($iFlag, 1) Then
Return Number(ControlGetText($hHandle, '', ControlGetHandle($hHandle, '', 'Edit1')))
Else
Exit -1
EndIf
EndIf

Return 0
EndFunc ;==>_SingletonPID
</syntaxhighlight>

[[#top | ReturnToContents]]

== _Sort ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

ConsoleWrite(_Sort("$sVariable" & @CRLF & "$iVariable" & @CRLF & "$tVariable" & @CRLF & "$pVariable"))

Func _Sort(Const $sSortList)
Local Const $iPID = Run("sort.exe", @SystemDir, @SW_HIDE, $STDIN_CHILD + $STDOUT_CHILD), $sOutput = ""

StdinWrite($iPID, $sSortList)
StdinWrite($iPID)

While 1
$sOutput &= StdoutRead($iPID)

If @error Then
ExitLoop
EndIf
WEnd

Return $sOutput
EndFunc ;==>_Sort
</syntaxhighlight>

[[#top | ReturnToContents]]

== Speak Object and Save to WAV File ==

{{Snippet Header
| AuthorURL = 52278-solidsnake26
| AuthorName = SolidSnake26
}}

<syntaxhighlight lang="autoit">
; Speak Object and save to wav file

_SpeakToWAV("AutoIt Snippets", @ScriptDir & "\SavedFile.wav")

Func _SpeakToWAV(Const $sText, Const $sFilePath)
Local $ObjVoice = ObjCreate("Sapi.SpVoice")

Local $ObjFile = ObjCreate("Sapi.SpFileStream.1")

$ObjVoice.Speak($sText)

$ObjFile.Open($sFilePath, 3)

$ObjVoice.AudioOutputStream = $ObjFile
EndFunc ;==>_SpeakToWAV
</syntaxhighlight>

[[#top | ReturnToContents]]

== _VariableSwap ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Global $sString_1 = 'This is string 1.'
Global $sString_2 = 'This is string 2.'

ConsoleWrite('$sString_1: ' & $sString_1 & @CRLF)
ConsoleWrite('$sString_2: ' & $sString_2 & @CRLF & @CRLF)

_VariableSwap($sString_1, $sString_2)

ConsoleWrite('$sString_1: ' & $sString_1 & @CRLF)
ConsoleWrite('$sString_2: ' & $sString_2 & @CRLF & @CRLF)

; Swap the contents of two variables.
Func _VariableSwap(ByRef $vVariable_1, ByRef $vVariable_2) ; Similar to _ArraySwap though not obvious to some this isn't limited to arrays.
Local Const $vTemp = $vVariable_1
$vVariable_1 = $vVariable_2
$vVariable_2 = $vTemp
EndFunc ;==>_VariableSwap
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinAPI_CharLower ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_WinAPI_CharLower("EXAMPLE") & @CRLF) ; Similar to StringLower.

; Convert characters to lowercase.
Func _WinAPI_CharLower($sString)
Local $aReturn = DllCall('user32.dll', 'wstr', 'CharLowerW', 'wstr', $sString)
If @error Then
Return SetError(1, 0, $sString)
EndIf
Return $aReturn[0]
EndFunc ;==>_WinAPI_CharLower
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinAPI_CharUpper ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_WinAPI_CharUpper("example") & @CRLF) ; Similar to StringUpper.

; Convert characters to uppercase.
Func _WinAPI_CharUpper($sString)
Local $aReturn = DllCall('user32.dll', 'wstr', 'CharUpperW', 'wstr', $sString)
If @error Then
Return SetError(1, 0, $sString)
EndIf
Return $aReturn[0]
EndFunc ;==>_WinAPI_CharUpper
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinAPI_PathFileExists ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; An API Alternative To FileExist.

ConsoleWrite(_WinAPI_PathFileExists(@ScriptFullPath) & @LF) ; File.
ConsoleWrite(_WinAPI_PathFileExists("C:\") & @LF) ; Drive.
ConsoleWrite(_WinAPI_PathFileExists(@ProgramFilesDir) & @LF) ; Directory.
ConsoleWrite(_WinAPI_PathFileExists("Z:\File.txt") & @LF) ; Shouldn't exist!

Func _WinAPI_PathFileExists($sFilePath)
Local $aReturn = DllCall('shlwapi.dll', 'int', 'PathFileExistsW', 'wstr', $sFilePath)
If @error Then
Return SetError(1, 0, 0)
EndIf
Return $aReturn[0]
EndFunc ;==>_WinAPI_PathFileExists
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinActiveByExe ==

{{Snippet Header
| AuthorURL = 4813-smoke-n
| AuthorName = SmOke_N
}}

<syntaxhighlight lang="autoit">
; Window Active/Activate by Exe, Open Notepad whilst script is running

While 1
If _WinActiveByExe('notepad.exe', False) Then MsgBox(64, 'info', 'true')
Sleep(100)
WEnd

Func _WinActiveByExe($sExe, $iActive = True);False to WinActivate, True to just see if it's active
If Not ProcessExists($sExe) Then Return SetError(1, 0, 0)
Local $aPL = ProcessList($sExe)
Local $aWL = WinList()
For $iCC = 1 To $aWL[0][0]
For $xCC = 1 To $aPL[0][0]
If $aWL[$iCC][0] <> '' And _
WinGetProcess($aWL[$iCC][1]) = $aPL[$xCC][1] And _
BitAND(WinGetState($aWL[$iCC][1]), 2) Then
If $iActive And WinActive($aWL[$iCC][1]) Then Return 1
If Not $iActive And Not WinActive($aWL[$iCC][1]) Then
WinActivate($aWL[$iCC][1])
Return 1
EndIf
EndIf
Next
Next
Return SetError(2, 0, 0)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WindowShake ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Shake a window left to right.

Example()

Func Example()
; Run Notepad
Run("notepad.exe")

; Wait 10 seconds for the Notepad window to appear.
Local $hWnd = WinWait("[CLASS:Notepad]", "", 10)

; Wait for 1 second.
Sleep(1000)

; Shake the Notepad window left to right.
_WindowShake($hWnd)

; Wait for 1 second.
Sleep(1000)

; Close the Notepad window using the handle returned by WinWait.
WinClose($hWnd)
EndFunc ;==>Example

Func _WindowShake($sTitle, $sText = '', $iDistance = 20)
Local $hWnd = WinGetHandle($sTitle, $sText)
Local $aWinGetPos = WinGetPos($hWnd)
If @error Then
Return SetError(1, 0, 0)
EndIf
Local $aArray[5] = [4, $aWinGetPos[0] + $iDistance, $aWinGetPos[0], $aWinGetPos[0] + $iDistance, $aWinGetPos[0]]

For $i = 1 To $aArray[0]
WinMove($hWnd, '', $aArray[$i], Default)
Sleep(100)
Next
EndFunc ;==>_WindowShake
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinGetDetails ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

Global $aArray = _WinGetDetails('[ACTIVE]') ; Returns the Window's title, PID, folder path filename.

If @error Then
Exit
EndIf

_ArrayDisplay($aArray)

Func _WinGetDetails($sTitle, $sText = '') ; Based on code of _WinGetPath by GaryFrost.
Local $aReturn[5] = [4, '-WinTitle', '-PID', '-FolderPath', '-FileName'], $aStringSplit

If StringLen($sText) > 0 Then
$aReturn[1] = WinGetTitle($sTitle, $sText)
Else
$aReturn[1] = WinGetTitle($sTitle)
EndIf
$aReturn[2] = WinGetProcess($aReturn[1])

Local $oWMIService = ObjGet('winmgmts:\\.\root\CIMV2')
Local $oItems = $oWMIService.ExecQuery('Select * From Win32_Process Where ProcessId = ' & $aReturn[2], 'WQL', 0x30)
If IsObj($oItems) Then
For $oItem In $oItems
If $oItem.ExecutablePath Then
$aStringSplit = StringSplit($oItem.ExecutablePath, '\')
$aReturn[3] = ''
For $A = 1 To $aStringSplit[0] - 1
$aReturn[3] &= $aStringSplit[$A] & '\'
Next
$aReturn[3] = StringTrimRight($aReturn[3], 1)
$aReturn[4] = $aStringSplit[$aStringSplit[0]]
Return $aReturn
EndIf
Next
EndIf
Return SetError(1, 0, $aReturn)
EndFunc ;==>_WinGetPath
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinGetNumeratedClassList ==

{{Snippet Header
| AuthorURL = 20477-mrcreator
| AuthorName = MrCreatoR
}}

<syntaxhighlight lang="autoit">
; Description: Retrieves the numerated classes from a window.

Func _WinGetNumeratedClassList($sTitle)
Local $sClassList = WinGetClassList($sTitle)
Local $aClassList = StringSplit($sClassList, @LF)
Local $sRetClassList = "", $sHold_List = "|"
Local $aiInHold, $iInHold

For $i = 1 To UBound($aClassList) - 1
If $aClassList[$i] = "" Then ContinueLoop

If StringRegExp($sHold_List, "\|" & $aClassList[$i] & "~(\d+)\|") Then
$aiInHold = StringRegExp($sHold_List, ".*\|" & $aClassList[$i] & "~(\d+)\|.*", 1)
$iInHold = Number($aiInHold[UBound($aiInHold)-1])

If $iInHold = 0 Then $iInHold += 1

$aClassList[$i] &= "~" & $iInHold + 1
$sHold_List &= $aClassList[$i] & "|"

$sRetClassList &= $aClassList[$i] & @LF
Else
$aClassList[$i] &= "~1"
$sHold_List &= $aClassList[$i] & "|"
$sRetClassList &= $aClassList[$i] & @LF
EndIf
Next

Return StringReplace(StringStripWS($sRetClassList, 3), "~", "")
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinGetHandleByPID ==

{{Snippet Header
| AuthorURL = 4813-smoke-n
| AuthorName = SmOke_N
}}

<syntaxhighlight lang="autoit">
; Get Window Handle by PID

#include <Array.au3>

Global $a1 = _WinGetHandleByPID(232)
Global $a2 = _WinGetHandleByPID("notepad.exe", -1)
Global $a3 = _WinGetHandleByPID("notepad.exe", 0)
Global $a4 = _WinGetHandleByPID("notepad.exe", 1)

_ArrayDisplay($a1, "1")
_ArrayDisplay($a2, "2")
_ArrayDisplay($a3, "3")
_ArrayDisplay($a4, "4")

;$nVisible = -1 "All (Visble or not)", $nVisible = 0 "Not Visible Only", $nVisible = 1 "Visible Only"
Func _WinGetHandleByPID($vProc, $nVisible = 1)
$vProc = ProcessExists($vProc);

If Not $vProc Then Return SetError(1, 0, 0)

Local $aWL = WinList()

Local $aTemp[UBound($aWL)][2]

Local $nAdd = 0

For $iCC = 1 To $aWL[0][0]
If $nVisible = -1 And WinGetProcess($aWL[$iCC][1]) = $vProc Then
$nAdd += 1
$aTemp[$nAdd][0] = $aWL[$iCC][0]
$aTemp[$nAdd][1] = $aWL[$iCC][1]
ElseIf $nVisible = 0 And WinGetProcess($aWL[$iCC][1]) = $vProc And _
BitAND(WinGetState($aWL[$iCC][1]), 2) = 0 Then
$nAdd += 1
$aTemp[$nAdd][0] = $aWL[$iCC][0]
$aTemp[$nAdd][1] = $aWL[$iCC][1]
ElseIf $nVisible > 0 And WinGetProcess($aWL[$iCC][1]) = $vProc And _
BitAND(WinGetState($aWL[$iCC][1]), 2) Then
$nAdd += 1
$aTemp[$nAdd][0] = $aWL[$iCC][0]
$aTemp[$nAdd][1] = $aWL[$iCC][1]
EndIf
Next

If $nAdd = 0 Then Return SetError(2, 0, 0) ; No windows found

ReDim $aTemp[$nAdd + 1][2]

$aTemp[0][0] = $nAdd

Return $aTemp
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

Snippets ( AutoIt )

2015-01-16T21:36:35Z

Guinness: /* _IsVisible */

__TOC__
[[category:Snippets]]

{{Snippet Credit Header}}

== AutoItWinShow ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

Example()

Func Example()
; Display AutoIt's Hidden Window. See AutoItWinGetTitle and AutoItWinSetTitle for more details.
AutoItWinShow()

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
EndSwitch
WEnd
EndFunc ;==>Example

; Display AutoIt's Hidden Window. Returns the handle of the window.
Func AutoItWinShow()
Local Const $hWnd = WinGetHandle(AutoItWinGetTitle()) ; Get the handle of the AutoIt Hidden Window by finding out the title of the AutoIt Hidden Window.
WinMove($hWnd, '', (@DesktopWidth / 2) - 250, (@DesktopHeight / 2) - 250, 500, 500) ; Move the AutoIt Hidden Window and re-size for a better view of the data that will be set.
WinSetState($hWnd, '', @SW_SHOW) ; Show the AutoIt Hidden Window, normally this is hidden, but in the interest of this example I'm displaying it.
Return $hWnd
EndFunc ;==>AutoItWinShow
</syntaxhighlight>

[[#top | ReturnToContents]]

== AutoItWinGetText ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Example()

Func Example()
; Display AutoIt's Hidden Window. See AutoItWinGetTitle and AutoItWinSetTitle for more details.
AutoItWinShow()

; Add a text string to AutoIt's Hidden Window. Compile to see the text in AutoIt's Hidden Window.
AutoItWinSetText('Welcome to AutoIt V' & @AutoItVersion & @CRLF)

; Add a text string to AutoIt's Hidden Window. Compile to see the text in AutoIt's Hidden Window.
AutoItWinSetText('Windows Type: ' & @OSType & @CRLF)

; Display the text stored in AutoIt's Hidden Window.
MsgBox(4096, '', AutoItWinGetText())

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
EndSwitch
WEnd
EndFunc ;==>Example

; Retrieve the text in AutoIt's Hidden Window.
Func AutoItWinGetText()
Local Const $hWnd = WinGetHandle(AutoItWinGetTitle()) ; Get the handle of the AutoIt Hidden Window by finding out the title of the AutoIt Hidden Window.
Return ControlGetText($hWnd, '', ControlGetHandle($hWnd, '', 'Edit1'))
EndFunc ;==>AutoItWinGetText

; Add text to AutoIt's Hidden Window.
Func AutoItWinSetText($sString)
Local Const $hWnd = WinGetHandle(AutoItWinGetTitle()) ; Get the handle of the AutoIt Hidden Window by finding out the title of the AutoIt Hidden Window.
Return ControlSetText($hWnd, "", ControlGetHandle($hWnd, "", 'Edit1'), ControlGetText($hWnd, '', ControlGetHandle($hWnd, '', 'Edit1')) & $sString)
EndFunc ;==>AutoItWinSetText

; Display AutoIt's Hidden Window. Returns the handle of the window.
Func AutoItWinShow()
Local Const $hWnd = WinGetHandle(AutoItWinGetTitle()) ; Get the handle of the AutoIt Hidden Window by finding out the title of the AutoIt Hidden Window.
WinMove($hWnd, '', (@DesktopWidth / 2) - 250, (@DesktopHeight / 2) - 250, 500, 500) ; Move the AutoIt Hidden Window and re-size for a better view of the data that will be set.
WinSetState($hWnd, '', @SW_SHOW) ; Show the AutoIt Hidden Window, normally this is hidden, but in the interest of this example I'm displaying it.
Return $hWnd
EndFunc ;==>AutoItWinShow
</syntaxhighlight>

[[#top | ReturnToContents]]

== _DockToWindow ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#include <WinAPI.au3>
#include <WindowsConstants.au3>

If (Not ProcessExists("SciTE.exe")) Then
Exit MsgBox(4096, '', "Please start SciTE.exe")
EndIf

Example()

Func Example()
; Create a GUI, similar to SciTE Jump's GUI.
Local Const $hGUI = GUICreate('', 215, 400, -1, -1, BitOR($GUI_SS_DEFAULT_GUI, $WS_MAXIMIZEBOX, $WS_SIZEBOX))

GUISetState(@SW_SHOWNORMAL, $hGUI)

; Dock the first window to left and adjust the width based on the width of the second GUI.
_DockToWindow(WinGetHandle("[CLASS:SciTEWindow]"), $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example

Func _DockToWindow(Const $hHandle_1, Const $hHandle_2)
; Retrieve the working area, this is minus the taskbar dimensions so slightly different to @DesktopHeight and @DesktopWidth which is the
; monitors height and width.
Local Const $SPI_GETWORKAREA = 48
Local Const $tWorkArea = DllStructCreate($tagRECT)
_WinAPI_SystemParametersInfo($SPI_GETWORKAREA, 0, DllStructGetPtr($tWorkArea))

; Retieve the position of the second GUI.
Local Const $aClientSize_2 = WinGetPos($hHandle_2)

; Set the state of the windows to 'Restore'.
WinSetState($hHandle_1, '', @SW_RESTORE)
WinSetState($hHandle_2, '', @SW_RESTORE)

; Move the first to the far left of the screen and adjust the width to the total screen width minus the width of the second GUI. e.g. 1366 - 215
WinMove($hHandle_1, '', DllStructGetData($tWorkArea, 'Left'), DllStructGetData($tWorkArea, 'Top'), DllStructGetData($tWorkArea, 'Right') - DllStructGetData($tWorkArea, 'Left') - $aClientSize_2[2], DllStructGetData($tWorkArea, 'Bottom') - DllStructGetData($tWorkArea, 'Top'))

; Move the second window to the far right in between the remaining space and adjust the height of the GUI.
WinMove($hHandle_2, '', DllStructGetData($tWorkArea, 'Right') - DllStructGetData($tWorkArea, 'Left') - $aClientSize_2[2], DllStructGetData($tWorkArea, 'Top'), $aClientSize_2[2], DllStructGetData($tWorkArea, 'Bottom') - DllStructGetData($tWorkArea, 'Top'))
EndFunc ;==>_DockToWindow
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FuncExists ==

{{Snippet Header
| AuthorURL = 52-geosoft
| AuthorName = GEOSoft
}}

<syntaxhighlight lang="autoit">
MsgBox(0, "TEST", "Function Exists = " & _FuncExists("_FuncExists", @ScriptFullPath))

Func _FuncExists($sFunc, $sPath)
If Not FileExists($sPath) Then Return SetError(1)
Local Const $sStr = FileRead($sPath)
Local Const $sRegEx = "(?i)(?m:^|\n)\s*Func\s+(" & $sFunc & ")\s*\("
Local Const $aRegEx = StringRegExp($sStr, $sRegEx, 1)
If IsArray($aRegEx) Then Return 1
Return 0
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FunctionSort ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Get the list of Functions in a script and sort by alphabetical order.

#include <Array.au3>
#include <String.au3>

Local $sFile = FileOpenDialog(@ScriptName, "Select an AutoIt file.", "Au3 (*.au3)")

If @error Then
Exit
EndIf
ClipPut(_FunctionSort($sFile))

Func _FunctionSort($sFilePath)
Local Const $sRead = FileRead($sFilePath)

Local $aReturn = StringRegExp("Func _Count()" & @CRLF & "EndFunc ;==>_Count" & $sRead, '(?s)(?i)Func(.*?)EndFunc', 3)

If @error Then
Return SetError(1, 0, 0)
EndIf

$aReturn[0] = UBound($aReturn, 1) - 1

_ArraySort($aReturn, 0, 1)

Local $sReturn

For $A = 1 To $aReturn[0]
$sReturn &= "Func" & $aReturn[$A] & "EndFunc" & @CRLF & @CRLF
Next

Return $sReturn
EndFunc ;==>_FunctionSort
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsBeta ==

{{Snippet Header
| AuthorURL = 10673-mlipok
| AuthorName = mLipok
}}

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

Example()

Func Example()
Local $aTest[10]
_ArrayUnique($aTest, 0, 5)
Local $iError = @error
ConsoleWrite('$iError = ' & $iError & @CRLF)
If _IsBeta() Then
If $iError = 3 Then
MsgBox($MB_SYSTEMMODAL, '@error', '3 - $iBase or $iCase contains an invalid value' & @CRLF & @AutoItVersion)
EndIf
Else
If $iError = 2 Then
MsgBox($MB_SYSTEMMODAL, '@error', '2 - $iBase or $iCase contains an invalid value' & @CRLF & @AutoItVersion)
EndIf
EndIf
EndFunc ;==>Example

Func _IsBeta()
Return Mod(StringSplit(@AutoItVersion, '.')[3], 2) == 1
EndFunc ;==>_IsBeta
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsButton ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <ButtonConstants.au3>
#include <Constants.au3>
#include <WinAPI.au3>

Example()

Func Example()
Local Const $hGUI = GUICreate('')
Local Const $iLabel = GUICtrlCreateButton('', 0, 0, 50, 50)
Local Const $iCheckbox = GUICtrlCreateCheckbox('', 0, 0, 100, 20) ; This is considered a 'Button' by _WinAPI_GetClassName too.

GUISetState(@SW_SHOWNORMAL, $hGUI)

MsgBox(4096, '', 'AutoIt Button ID: ' & _IsButton($iLabel) & @CRLF & _
'AutoIt Button Handle: ' & _IsButton(GUICtrlGetHandle($iLabel)) & @CRLF & _
'AutoIt Checkbox ID: ' & _IsButton($iCheckbox) & @CRLF & _
'AutoIt Checkbox Handle: ' & _IsButton(GUICtrlGetHandle($iCheckbox)) & @CRLF)

Return GUIDelete($hGUI)
EndFunc ;==>Example

; Check if a variable is referencing a Button control.
Func _IsButton($hWnd)
If IsHWnd($hWnd) = 0 Then
$hWnd = GUICtrlGetHandle($hWnd)
EndIf

Local Const $sClassName = _WinAPI_GetClassName($hWnd)

If $sClassName = 'Button' Then
Local Const $aStyle[5] = [4, $BS_CHECKBOX, $BS_AUTOCHECKBOX, $BS_RADIOBUTTON, $BS_AUTORADIOBUTTON]

Local Const $iLong = _WinAPI_GetWindowLong($hWnd, $GWL_STYLE)

For $i = 1 To $aStyle[0]
If BitAND($iLong, $aStyle[$i]) = $aStyle[$i] Then
Return False
EndIf
Next

Return True
EndIf

Return False
EndFunc ;==>_IsButton
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsControlID ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Check if a Control ID is a native AutoIt control.

#include <GUIListView.au3>
#include <WinAPI.au3>

Example()

Func Example()
Local Const $hGUI = GUICreate('')
Local Const $iControlID = GUICtrlCreateLabel('', 0, 0, 500, 500)
Local Const $hListView = _GUICtrlListView_Create($hGUI, 'Example', 0, 0, 500, 500)

GUISetState(@SW_SHOWNORMAL, $hGUI)

MsgBox(4096, '', 'AutoIt ControlID: ' & _IsControlID($iControlID) & @CRLF & _
'Random Number: ' & _IsControlID(Random(42, 99, 1)) & @CRLF & _
'AutoIt ControlID Handle: ' & _IsControlID(GUICtrlGetHandle($iControlID)) & @CRLF & _
'ListView UDF Handle: ' & _IsControlID($hListView) & @CRLF & _
'ListView UDF Handle: ' & _IsControlID(GUICtrlGetHandle($hListView)) & @CRLF)

_GUICtrlListView_Destroy($hListView)

Return GUIDelete($hGUI)
EndFunc ;==>Example

Func _IsControlID($iControlID)
If IsHWnd($iControlID) Then
$iControlID = _WinAPI_GetDlgCtrlID($iControlID)
EndIf

Return IsHWnd(GUICtrlGetHandle($iControlID)) = 1
EndFunc ;==>_IsControlID
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetAutoItIncludesFromSciTE ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

ConsoleWrite(_GetAutoItIncludesFromSciTE() & @CRLF)

; Retrieve the AutoIt includes path from the SciTE process.
Func _GetAutoItIncludesFromSciTE()
Local $sRelativePath = '..\Include'
Local Const $sWorkingDir = @WorkingDir
FileChangeDir(_WinAPI_PathRemoveFileSpec(_WinAPI_GetProcessFileName(ProcessExists('SciTE.exe'))))
$sRelativePath = _WinAPI_GetFullPathName($sRelativePath)
FileChangeDir($sWorkingDir)
Return _WinAPI_PathRemoveBackslash($sRelativePath)
EndFunc ;==>_GetAutoItIncludesFromSciTE
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetAutoItInstall ==

{{Snippet Header
|AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Get the AutoIt installation folder.

ConsoleWrite(_GetAutoItInstall() & @CRLF)

Func _GetAutoItInstall()
Return StringLeft(@AutoItExe, StringInStr(@AutoItExe, "\", 2, -1) - 1)
EndFunc ;==>_GetAutoItInstall
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetAutoItInstallEx ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_GetAutoItInstallEx() & @CRLF)

; Get the installation of AutoIt. An improved version of _GetAutoItInstall.
Func _GetAutoItInstallEx()
Local $aWow6432Node[2] = ['', 'Wow6432Node\'], $aFiles[4] = [3, @ProgramFilesDir, EnvGet("PROGRAMFILES"), EnvGet("PROGRAMFILES(X86)")]
Local $sFilePath = RegRead('HKEY_LOCAL_MACHINE\SOFTWARE\' & $aWow6432Node[@AutoItX64] & 'AutoIt v3\AutoIt\', 'InstallDir')
If @error Then
For $A = 1 To $aFiles[0]
$aFiles[$A] &= '\AutoIt'
If FileExists($aFiles[$A]) Then
Return $aFiles[$A]
EndIf
Next
Return SetError(1, 0, '')
Else
Return $sFilePath
EndIf
EndFunc ;==>_GetAutoItInstallEx
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetAutoItInstallFromSciTE ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_GetAutoItInstallFromSciTE() & @CRLF)

; Retrieve the AutoIt installation path from the SciTE process.
Func _GetAutoItInstallFromSciTE()
Local $sRelativePath = '..\', $sWorkingDir = @WorkingDir
FileChangeDir( _WinAPI_PathRemoveFileSpec(_WinAPI_GetProcessFileName(ProcessExists("SciTE.exe"))))
$sRelativePath = _WinAPI_GetFullPathName($sRelativePath)
FileChangeDir($sWorkingDir)
Return _WinAPI_PathRemoveBackslash($sRelativePath)
EndFunc ;==>_GetAutoItInstallFromSciTE
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetClasses ==

{{Snippet Header
| AuthorURL = 24-cyberslug
| AuthorName = CyberSlug
}}

<syntaxhighlight lang="autoit">
; Get ALL Controls Info

Example()

Func Example()
; Run Calculator
Run("calc.exe")

; Wait 10 seconds for the Calculator window to appear.
Local const $hWnd = WinWait("[CLASS:CalcFrame]", '', 10)

; Retrieve a list of all the controls in the Calculator window using the handle returned by WinWait.
MsgBox(4096, '', _GetClasses($hWnd))

; Close the Calculator window using the handle returned by WinWait.
WinClose($hWnd)
EndFunc ;==>Example

; This function returns an @LF-separated list of controls on the specified window.
Func _GetClasses($sTitle, $sText = '')
Local $iCount_Button = 0, $iCount_Edit = 0, $iCount_Static = 0
Local $aClasses = StringSplit(WinGetClassList($sTitle, $sText), @LF)
Local $aClassID[$aClasses[0] + 1] = [$aClasses[0]]

For $i = 1 To $aClasses[0]
Select
Case $aClasses[$i] = "Button"
$iCount_Button += 1
$aClassID[$i] = $aClasses[$i] & $iCount_Button
Case $aClasses[$i] = "Edit"
$iCount_Edit += 1
$aClassID[$i] = $aClasses[$i] & $iCount_Edit
$aClasses[$i] = "Input"
Case $aClasses[$i] = "Static"
$iCount_Static += 1
$aClassID[$i] = $aClasses[$i] & $iCount_Static
$aClasses[$i] = "Label"
Case Else
If $aClasses[$i] <> "" Then
$aClassID[$i] = $aClasses[$i] & "?"
EndIf
EndSelect
Next

; Combine the results.
Local $sReturn = ""

For $i = 1 To $aClassID[0]
$sReturn &= $aClassID[$i] & @LF
Next

Return $sReturn
EndFunc ;==>_GetClasses
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; FileRead Alternative

Func _GetFile($sFile, $iFormat = 0)
Local $hFileOpen = FileOpen($sFile, $iFormat)
If $hFileOpen = -1 Then
Return SetError(1, 0, "")
EndIf
Local $sData = FileRead($hFileOpen)
FileClose($hFileOpen)
Return $sData
EndFunc ;==>_GetFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetTitle ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Get the title of your program.

ConsoleWrite(_GetTitle('Example') & @CRLF)
; The second parameter would normally be @ScriptDir & '\Uninstall.exe' for example, but for this demonstration I'm using the full path.
ConsoleWrite(_GetTitle('Example', @ScriptFullPath) & @CRLF)

Func _GetTitle($sProgramName, $sInstallPath = '')
Local $aOSArch[2] = ['', ' (64-bit)'], $aPortable[2] = [' (Portable)', '']
Return $sProgramName & $aOSArch[@AutoItX64] & $aPortable[FileExists($sInstallPath)]
EndFunc ;==>_GetTitle
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetXML ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Simple Way Of Parsing XML Data.

#include <Array.au3>

Global $aReturn, $sXMLData

$sXMLData = "<data>This is a Simple example of XML</data><data>This is a Simple example of XML and is the Second String.</data>"
$aReturn = _GetXML($sXMLData, "data")
_ArrayDisplay($aReturn, "_GetXML()")

Func _GetXML($sString, $sData)
Local $aError[2] = [1, $sString], $aReturn
$aReturn = StringRegExp('<' & $sData & '></' & $sData & '>' & $sString, '(?s)(?i)<' & $sData & '>(.*?)</' & $sData & '>', 3)
If @error Then
Return SetError(1, 0, $aError)
EndIf
$aReturn[0] = UBound($aReturn, 1) - 1
Return SetError(0, 0, $aReturn)
EndFunc ;==>_GetXML
</syntaxhighlight>

[[#top | ReturnToContents]]

== Include Source With Exe ==

{{Snippet Header
| AuthorURL = 54985-jlogan3o13
| AuthorName = JLogan3o13
}}

<syntaxhighlight lang="autoit">
;recover source .au3 file with /Extract switch
; The above code would be copied into the top of your script. The source location (C:\Test.au3 in my example) is the full path to your script file.
;Once compiled, if you run the script from the Run line with the /Extract switch, it will extact the original .au3 file into the Temp directory and will exit without actually executing the script.
If StringInStr($cmdlineRaw, "/Extract") Then
FileInstall("C:\Test.au3", @TempDir & "\Test.au3", 1)
Exit
EndIf
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsANSIFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

ConsoleWrite(_IsANSIFile(@ScriptFullPath) & @LF) ; Returns True.

Func _IsANSIFile($sFilePath)
Return FileGetEncoding($sFilePath) = $FO_READ
EndFunc ;==>_IsUnicodeFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsUnicodeFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

ConsoleWrite(_IsUnicodeFile(@ScriptFullPath) & @LF) ; Returns False.

Func _IsUnicodeFile($sFilePath)
Return FileGetEncoding($sFilePath) = $FO_UNICODE
EndFunc ;==>_IsUnicodeFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsAu3File ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_IsAu3File(@AutoItExe) & @CRLF)
ConsoleWrite(_IsAu3File(@ScriptFullPath) & @CRLF)

; Checks whether the filepath is an au3 file.
Func _IsAu3File($sFilePath)
Return StringTrimLeft($sFilePath, StringInStr($sFilePath, ".", 2, -1)) = "au3"
EndFunc ;==>_IsAu3File
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsDefault ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
If _IsDefault(Default) Then
MsgBox(0, "_IsDefault() - 1", "This was a Default variable.")
EndIf

If _IsDefault(-1) Then
MsgBox(0, "_IsDefault() - 2", "This was a Default variable.")
EndIf

If _IsDefault("Other") Then
MsgBox(0, "_IsDefault() - 3", "This was a Default variable.")
EndIf

Func _IsDefault($sDefault)
Return StringRegExp($sDefault, "(?-i)\s|Default|-1|0")
EndFunc ;==>_IsDefault
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsInTrial ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <Date.au3> ; Required for _DateDiff()

ConsoleWrite('Date trial started: ' & @YEAR & '/' & @MON & '/01' & @CRLF & _
'Today''s date: ' & @YEAR & '/' & @MON & '/' & @MDAY & @CRLF & _
'Trial period: 30 days' & @CRLF & _
'Is the trial period still valid: ' & _IsInTrial(@YEAR & '/' & @MON & '/01', 30) & @CRLF)

; Check if a trial period date is still valid.
Func _IsInTrial($sDateString, $iDays) ; Based on the idea found here: http://www.autoitscript.com/forum/topic/...ial-time/page__view__findpost_
Return (_DateDiff('D', $sDateString, @YEAR & '/' & @MON & '/' & @MDAY) < $iDays)
EndFunc ;==>_IsInTrial
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsVisible ==

{{Snippet Header
| AuthorURL =
| AuthorName = Multiple
}}

<syntaxhighlight lang="autoit">
; Check if the Notepad Window is visible.

Example()

Func Example()
; Run Notepad
Run("notepad.exe")

; Wait 10 seconds for the Notepad window to appear.
Local $hWnd = WinWait("[CLASS:Notepad]", "", 10)

; Check if the Notepad window is visible and display the appropriate message box.
If _IsVisible($hWnd) Then
MsgBox(4096, "", "Notepad is visible.")
Else
MsgBox(4096, "", "Notepad isn't visible.")
EndIf

; Close the Notepad window using the handle returned by WinWait.
WinClose($hWnd)
EndFunc ;==>Example

; Check if the window is visible.
Func _IsVisible($hWnd)
Return BitAND(WinGetState($hWnd), 2) = 2
EndFunc ;==>_IsVisible
</syntaxhighlight>

[[#top | ReturnToContents]]

== Open Help File to Desired Page ==

{{Snippet Header
| AuthorURL = 1967-garyfrost
| AuthorName = GaryFrost
}}

<syntaxhighlight lang="autoit">
; Open help file / Open a desired page

Global Const $sAutoItPath = RegRead("HKEY_LOCAL_MACHINE\SOFTWARE\AutoIt v3\AutoIt", "InstallDir")

Run(@WindowsDir & "\hh.exe " & $sAutoItPath & "\AutoIt3.chm::/html/functions/GUICtrlCreateUpdown.htm")
</syntaxhighlight>

[[#top | ReturnToContents]]

== _RunAU3 ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
_RunAU3("AU3_Example.txt", '"This is a commandline example!"')

Func _RunAU3($sFilePath, $sCommandLine = "", $sWorkingDir = "", $iShowFlag = @SW_SHOW, $iOptFlag = 0)
Return Run('"' & @AutoItExe & '" /AutoIt3ExecuteScript "' & $sFilePath & '" ' & $sCommandLine, $sWorkingDir, $iShowFlag, $iOptFlag)
EndFunc ;==>_RunAU3

Func _RunWaitAU3($sFilePath, $sCommandLine = "", $sWorkingDir = "", $iShowFlag = @SW_SHOW, $iOptFlag = 0)
Local $iPID
$iPID = RunWait('"' & @AutoItExe & '" /AutoIt3ExecuteScript "' & $sFilePath & '" ' & $sCommandLine, $sWorkingDir, $iShowFlag, $iOptFlag)
If @error Then
Return SetError(@error, 1, 0)
EndIf
Return $iPID
EndFunc ;==>_RunWaitAU3
</syntaxhighlight>

[[#top | ReturnToContents]]

== Run Any au3 File From Your Program ==

{{Snippet Header
| AuthorURL = 4920-valuater
| AuthorName = Valuater
}}

<syntaxhighlight lang="autoit">
; Run Any Au3 File From Your Program

Global Const $sFilePath = @ScriptDir & "\Test.au3"

If @Compiled Then
Global Const $sFileExe = FileGetShortName(@AutoItExe & ' /AutoIt3ExecuteScript "' & $sFilePath & '"')
Run($sFileExe)
Else
Global Const $sFileAu3 = FileGetShortName($sFilePath)
Run(@AutoItExe & " " & $sFileAu3, "", @SW_HIDE)
EndIf
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ScriptName ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_ScriptName() & @CRLF)

; Return the @ScriptName minus the .exe or .au3 extension.
Func _ScriptName()
Return StringLeft(@ScriptName, StringInStr(@ScriptName, '.', 2, -1) - 1)
EndFunc ;==>_ScriptName
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ScriptVersion ==

{{Snippet Header
| AuthorURL = 31149-milesahead
| AuthorName = MilesAhead
}}

<syntaxhighlight lang="autoit">
#NoTrayIcon

#Region ;**** Directives created by AutoIt3Wrapper_GUI ****
#AutoIt3Wrapper_UseUpx=n
#AutoIt3Wrapper_Res_Fileversion=1.2.3.4
#AutoIt3Wrapper_Res_LegalCopyright=2012 www.favessoft.com
#AutoIt3Wrapper_Res_Language=1033
#AutoIt3Wrapper_AU3Check_Parameters=-d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7
#EndRegion ;**** Directives created by AutoIt3Wrapper_GUI ****

Global $version = _ScriptVersion()

Global $msg = "ScriptVerDemo" & " " & $version & " Copyright (c) 2012 www.favessoft.com" & @CRLF & @CRLF

MsgBox(0x1040, "", $msg)

; return File Version string from compiled or .au3 script
; returns "" if no version info available
; Note: The .au3 script must contain #AutoItWrapper
; directives with file version or "" is returned.
Func _ScriptVersion(Const $Script = @ScriptFullPath)
If StringRight($Script,4) = ".exe" Then
Return FileGetVersion($Script)
Else
Local Const $scriptHandle = FileOpen($Script)
Local $ver
Local $found = False
Local $pos

If $scriptHandle <> -1 Then
Do
$ver = FileReadLine($scriptHandle)
$sPos = StringInStr($ver, "_Fileversion=")

If $sPos Then
$ver = StringMid($ver, $sPos + StringLen("_Fileversion="))
$found = True
ExitLoop
EndIf
Until StringLeft($ver, 1) <> "#"

FileClose($scriptHandle)
EndIf
EndIf

If Not $found Then $ver = ""

Return $ver
EndFunc ;==>_ScriptVersion
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SetFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; FileWrite Alternative

Func _SetFile(Const $sString, Const $sFile, Const $iOverwrite = 0)
Local Const $hFileOpen = FileOpen($sFile, $iOverwrite + 1)

FileWrite($hFileOpen, $sString)
FileClose($hFileOpen)

If @error Then
Return SetError(1, 0, $sString)
EndIf

Return $sString
EndFunc ;==>_SetFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ShowHelp ==

{{Snippet Header
| AuthorURL = 60350-chimaera
| AuthorName = Chimaera
}}

<syntaxhighlight lang="autoit">
HotKeySet("{F1}", "_ShowHelp")

Func _ShowHelp()
Return ShellExecute(@ProgramFilesDir & "\AutoIt3\AutoIt3Help.exe") ; change this to the location of your own helpfile.
EndFunc ;==>_ShowHelp
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SingletonPID ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Local $iSingleton = _SingletonPID('RandomName', 1)

If $iSingleton = 0 Then
MsgBox(4096, '', 'This is the first instance of the program running: ' & $iSingleton)
Else
MsgBox(4096, '', 'There is another instance running. This PID is: ' & $iSingleton)
EndIf

; #FUNCTION# ====================================================================================================================
; Name ..........: _SingletonPID
; Description ...: Enforce a design paradigm where only one instance of the script may be running.
; Syntax ........: _SingletonPID($sOccurenceName[, $iFlag = 0])
; Parameters ....: $sOccurenceName - String to identify the occurrence of the script.
; $iFlag - [optional] Optional parameters. Default is 0.
; 0 - Exit the script with the exit code -1 if another instance already exists.
; 1 - Return the PID of the main executable and without exiting the script too.
; Return values .: Success - 0 No other process is running.
; Failure - The PID of the main executable.
; Author ........: guinness with initial ideas by Valik for _Singleton & KaFu for _EnforceSingleInstance.
; Example .......: Yes
; ===============================================================================================================================
Func _SingletonPID(Const $sOccurenceName, Const $iFlag = 0)
Local $hHandle = WinGetHandle($sOccurenceName)

If @error Then
AutoItWinSetTitle($sOccurenceName)
$hHandle = WinGetHandle($sOccurenceName)
ControlSetText($hHandle, '', ControlGetHandle($hHandle, '', 'Edit1'), @AutoItPID)
Else
If BitAND($iFlag, 1) Then
Return Number(ControlGetText($hHandle, '', ControlGetHandle($hHandle, '', 'Edit1')))
Else
Exit -1
EndIf
EndIf

Return 0
EndFunc ;==>_SingletonPID
</syntaxhighlight>

[[#top | ReturnToContents]]

== _Sort ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

ConsoleWrite(_Sort("$sVariable" & @CRLF & "$iVariable" & @CRLF & "$tVariable" & @CRLF & "$pVariable"))

Func _Sort(Const $sSortList)
Local Const $iPID = Run("sort.exe", @SystemDir, @SW_HIDE, $STDIN_CHILD + $STDOUT_CHILD), $sOutput = ""

StdinWrite($iPID, $sSortList)
StdinWrite($iPID)

While 1
$sOutput &= StdoutRead($iPID)

If @error Then
ExitLoop
EndIf
WEnd

Return $sOutput
EndFunc ;==>_Sort
</syntaxhighlight>

[[#top | ReturnToContents]]

== Speak Object and Save to WAV File ==

{{Snippet Header
| AuthorURL = 52278-solidsnake26
| AuthorName = SolidSnake26
}}

<syntaxhighlight lang="autoit">
; Speak Object and save to wav file

_SpeakToWAV("AutoIt Snippets", @ScriptDir & "\SavedFile.wav")

Func _SpeakToWAV(Const $sText, Const $sFilePath)
Local $ObjVoice = ObjCreate("Sapi.SpVoice")

Local $ObjFile = ObjCreate("Sapi.SpFileStream.1")

$ObjVoice.Speak($sText)

$ObjFile.Open($sFilePath, 3)

$ObjVoice.AudioOutputStream = $ObjFile
EndFunc ;==>_SpeakToWAV
</syntaxhighlight>

[[#top | ReturnToContents]]

== _VariableSwap ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Global $sString_1 = 'This is string 1.'
Global $sString_2 = 'This is string 2.'

ConsoleWrite('$sString_1: ' & $sString_1 & @CRLF)
ConsoleWrite('$sString_2: ' & $sString_2 & @CRLF & @CRLF)

_VariableSwap($sString_1, $sString_2)

ConsoleWrite('$sString_1: ' & $sString_1 & @CRLF)
ConsoleWrite('$sString_2: ' & $sString_2 & @CRLF & @CRLF)

; Swap the contents of two variables.
Func _VariableSwap(ByRef $vVariable_1, ByRef $vVariable_2) ; Similar to _ArraySwap though not obvious to some this isn't limited to arrays.
Local Const $vTemp = $vVariable_1
$vVariable_1 = $vVariable_2
$vVariable_2 = $vTemp
EndFunc ;==>_VariableSwap
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinAPI_CharLower ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_WinAPI_CharLower("EXAMPLE") & @CRLF) ; Similar to StringLower.

; Convert characters to lowercase.
Func _WinAPI_CharLower($sString)
Local $aReturn = DllCall('user32.dll', 'wstr', 'CharLowerW', 'wstr', $sString)
If @error Then
Return SetError(1, 0, $sString)
EndIf
Return $aReturn[0]
EndFunc ;==>_WinAPI_CharLower
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinAPI_CharUpper ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_WinAPI_CharUpper("example") & @CRLF) ; Similar to StringUpper.

; Convert characters to uppercase.
Func _WinAPI_CharUpper($sString)
Local $aReturn = DllCall('user32.dll', 'wstr', 'CharUpperW', 'wstr', $sString)
If @error Then
Return SetError(1, 0, $sString)
EndIf
Return $aReturn[0]
EndFunc ;==>_WinAPI_CharUpper
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinAPI_PathFileExists ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; An API Alternative To FileExist.

ConsoleWrite(_WinAPI_PathFileExists(@ScriptFullPath) & @LF) ; File.
ConsoleWrite(_WinAPI_PathFileExists("C:\") & @LF) ; Drive.
ConsoleWrite(_WinAPI_PathFileExists(@ProgramFilesDir) & @LF) ; Directory.
ConsoleWrite(_WinAPI_PathFileExists("Z:\File.txt") & @LF) ; Shouldn't exist!

Func _WinAPI_PathFileExists($sFilePath)
Local $aReturn = DllCall('shlwapi.dll', 'int', 'PathFileExistsW', 'wstr', $sFilePath)
If @error Then
Return SetError(1, 0, 0)
EndIf
Return $aReturn[0]
EndFunc ;==>_WinAPI_PathFileExists
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinActiveByExe ==

{{Snippet Header
| AuthorURL = 4813-smoke-n
| AuthorName = SmOke_N
}}

<syntaxhighlight lang="autoit">
; Window Active/Activate by Exe, Open Notepad whilst script is running

While 1
If _WinActiveByExe('notepad.exe', False) Then MsgBox(64, 'info', 'true')
Sleep(100)
WEnd

Func _WinActiveByExe($sExe, $iActive = True);False to WinActivate, True to just see if it's active
If Not ProcessExists($sExe) Then Return SetError(1, 0, 0)
Local $aPL = ProcessList($sExe)
Local $aWL = WinList()
For $iCC = 1 To $aWL[0][0]
For $xCC = 1 To $aPL[0][0]
If $aWL[$iCC][0] <> '' And _
WinGetProcess($aWL[$iCC][1]) = $aPL[$xCC][1] And _
BitAND(WinGetState($aWL[$iCC][1]), 2) Then
If $iActive And WinActive($aWL[$iCC][1]) Then Return 1
If Not $iActive And Not WinActive($aWL[$iCC][1]) Then
WinActivate($aWL[$iCC][1])
Return 1
EndIf
EndIf
Next
Next
Return SetError(2, 0, 0)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WindowShake ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Shake a window left to right.

Example()

Func Example()
; Run Notepad
Run("notepad.exe")

; Wait 10 seconds for the Notepad window to appear.
Local $hWnd = WinWait("[CLASS:Notepad]", "", 10)

; Wait for 1 second.
Sleep(1000)

; Shake the Notepad window left to right.
_WindowShake($hWnd)

; Wait for 1 second.
Sleep(1000)

; Close the Notepad window using the handle returned by WinWait.
WinClose($hWnd)
EndFunc ;==>Example

Func _WindowShake($sTitle, $sText = '', $iDistance = 20)
Local $hWnd = WinGetHandle($sTitle, $sText)
Local $aWinGetPos = WinGetPos($hWnd)
If @error Then
Return SetError(1, 0, 0)
EndIf
Local $aArray[5] = [4, $aWinGetPos[0] + $iDistance, $aWinGetPos[0], $aWinGetPos[0] + $iDistance, $aWinGetPos[0]]

For $i = 1 To $aArray[0]
WinMove($hWnd, '', $aArray[$i], Default)
Sleep(100)
Next
EndFunc ;==>_WindowShake
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinGetDetails ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

Global $aArray = _WinGetDetails('[ACTIVE]') ; Returns the Window's title, PID, folder path filename.

If @error Then
Exit
EndIf

_ArrayDisplay($aArray)

Func _WinGetDetails($sTitle, $sText = '') ; Based on code of _WinGetPath by GaryFrost.
Local $aReturn[5] = [4, '-WinTitle', '-PID', '-FolderPath', '-FileName'], $aStringSplit

If StringLen($sText) > 0 Then
$aReturn[1] = WinGetTitle($sTitle, $sText)
Else
$aReturn[1] = WinGetTitle($sTitle)
EndIf
$aReturn[2] = WinGetProcess($aReturn[1])

Local $oWMIService = ObjGet('winmgmts:\\.\root\CIMV2')
Local $oItems = $oWMIService.ExecQuery('Select * From Win32_Process Where ProcessId = ' & $aReturn[2], 'WQL', 0x30)
If IsObj($oItems) Then
For $oItem In $oItems
If $oItem.ExecutablePath Then
$aStringSplit = StringSplit($oItem.ExecutablePath, '\')
$aReturn[3] = ''
For $A = 1 To $aStringSplit[0] - 1
$aReturn[3] &= $aStringSplit[$A] & '\'
Next
$aReturn[3] = StringTrimRight($aReturn[3], 1)
$aReturn[4] = $aStringSplit[$aStringSplit[0]]
Return $aReturn
EndIf
Next
EndIf
Return SetError(1, 0, $aReturn)
EndFunc ;==>_WinGetPath
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinGetNumeratedClassList ==

{{Snippet Header
| AuthorURL = 20477-mrcreator
| AuthorName = MrCreatoR
}}

<syntaxhighlight lang="autoit">
; Description: Retrieves the numerated classes from a window.

Func _WinGetNumeratedClassList($sTitle)
Local $sClassList = WinGetClassList($sTitle)
Local $aClassList = StringSplit($sClassList, @LF)
Local $sRetClassList = "", $sHold_List = "|"
Local $aiInHold, $iInHold

For $i = 1 To UBound($aClassList) - 1
If $aClassList[$i] = "" Then ContinueLoop

If StringRegExp($sHold_List, "\|" & $aClassList[$i] & "~(\d+)\|") Then
$aiInHold = StringRegExp($sHold_List, ".*\|" & $aClassList[$i] & "~(\d+)\|.*", 1)
$iInHold = Number($aiInHold[UBound($aiInHold)-1])

If $iInHold = 0 Then $iInHold += 1

$aClassList[$i] &= "~" & $iInHold + 1
$sHold_List &= $aClassList[$i] & "|"

$sRetClassList &= $aClassList[$i] & @LF
Else
$aClassList[$i] &= "~1"
$sHold_List &= $aClassList[$i] & "|"
$sRetClassList &= $aClassList[$i] & @LF
EndIf
Next

Return StringReplace(StringStripWS($sRetClassList, 3), "~", "")
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinGetHandleByPID ==

{{Snippet Header
| AuthorURL = 4813-smoke-n
| AuthorName = SmOke_N
}}

<syntaxhighlight lang="autoit">
; Get Window Handle by PID

#include <Array.au3>

Global $a1 = _WinGetHandleByPID(232)
Global $a2 = _WinGetHandleByPID("notepad.exe", -1)
Global $a3 = _WinGetHandleByPID("notepad.exe", 0)
Global $a4 = _WinGetHandleByPID("notepad.exe", 1)

_ArrayDisplay($a1, "1")
_ArrayDisplay($a2, "2")
_ArrayDisplay($a3, "3")
_ArrayDisplay($a4, "4")

;$nVisible = -1 "All (Visble or not)", $nVisible = 0 "Not Visible Only", $nVisible = 1 "Visible Only"
Func _WinGetHandleByPID($vProc, $nVisible = 1)
$vProc = ProcessExists($vProc);

If Not $vProc Then Return SetError(1, 0, 0)

Local $aWL = WinList()

Local $aTemp[UBound($aWL)][2]

Local $nAdd = 0

For $iCC = 1 To $aWL[0][0]
If $nVisible = -1 And WinGetProcess($aWL[$iCC][1]) = $vProc Then
$nAdd += 1
$aTemp[$nAdd][0] = $aWL[$iCC][0]
$aTemp[$nAdd][1] = $aWL[$iCC][1]
ElseIf $nVisible = 0 And WinGetProcess($aWL[$iCC][1]) = $vProc And _
BitAND(WinGetState($aWL[$iCC][1]), 2) = 0 Then
$nAdd += 1
$aTemp[$nAdd][0] = $aWL[$iCC][0]
$aTemp[$nAdd][1] = $aWL[$iCC][1]
ElseIf $nVisible > 0 And WinGetProcess($aWL[$iCC][1]) = $vProc And _
BitAND(WinGetState($aWL[$iCC][1]), 2) Then
$nAdd += 1
$aTemp[$nAdd][0] = $aWL[$iCC][0]
$aTemp[$nAdd][1] = $aWL[$iCC][1]
EndIf
Next

If $nAdd = 0 Then Return SetError(2, 0, 0) ; No windows found

ReDim $aTemp[$nAdd + 1][2]

$aTemp[0][0] = $nAdd

Return $aTemp
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

Snippets ( AutoIt )

2015-01-16T21:36:12Z

Guinness: /* _IsVisible */

__TOC__
[[category:Snippets]]

{{Snippet Credit Header}}

== AutoItWinShow ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

Example()

Func Example()
; Display AutoIt's Hidden Window. See AutoItWinGetTitle and AutoItWinSetTitle for more details.
AutoItWinShow()

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
EndSwitch
WEnd
EndFunc ;==>Example

; Display AutoIt's Hidden Window. Returns the handle of the window.
Func AutoItWinShow()
Local Const $hWnd = WinGetHandle(AutoItWinGetTitle()) ; Get the handle of the AutoIt Hidden Window by finding out the title of the AutoIt Hidden Window.
WinMove($hWnd, '', (@DesktopWidth / 2) - 250, (@DesktopHeight / 2) - 250, 500, 500) ; Move the AutoIt Hidden Window and re-size for a better view of the data that will be set.
WinSetState($hWnd, '', @SW_SHOW) ; Show the AutoIt Hidden Window, normally this is hidden, but in the interest of this example I'm displaying it.
Return $hWnd
EndFunc ;==>AutoItWinShow
</syntaxhighlight>

[[#top | ReturnToContents]]

== AutoItWinGetText ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Example()

Func Example()
; Display AutoIt's Hidden Window. See AutoItWinGetTitle and AutoItWinSetTitle for more details.
AutoItWinShow()

; Add a text string to AutoIt's Hidden Window. Compile to see the text in AutoIt's Hidden Window.
AutoItWinSetText('Welcome to AutoIt V' & @AutoItVersion & @CRLF)

; Add a text string to AutoIt's Hidden Window. Compile to see the text in AutoIt's Hidden Window.
AutoItWinSetText('Windows Type: ' & @OSType & @CRLF)

; Display the text stored in AutoIt's Hidden Window.
MsgBox(4096, '', AutoItWinGetText())

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
EndSwitch
WEnd
EndFunc ;==>Example

; Retrieve the text in AutoIt's Hidden Window.
Func AutoItWinGetText()
Local Const $hWnd = WinGetHandle(AutoItWinGetTitle()) ; Get the handle of the AutoIt Hidden Window by finding out the title of the AutoIt Hidden Window.
Return ControlGetText($hWnd, '', ControlGetHandle($hWnd, '', 'Edit1'))
EndFunc ;==>AutoItWinGetText

; Add text to AutoIt's Hidden Window.
Func AutoItWinSetText($sString)
Local Const $hWnd = WinGetHandle(AutoItWinGetTitle()) ; Get the handle of the AutoIt Hidden Window by finding out the title of the AutoIt Hidden Window.
Return ControlSetText($hWnd, "", ControlGetHandle($hWnd, "", 'Edit1'), ControlGetText($hWnd, '', ControlGetHandle($hWnd, '', 'Edit1')) & $sString)
EndFunc ;==>AutoItWinSetText

; Display AutoIt's Hidden Window. Returns the handle of the window.
Func AutoItWinShow()
Local Const $hWnd = WinGetHandle(AutoItWinGetTitle()) ; Get the handle of the AutoIt Hidden Window by finding out the title of the AutoIt Hidden Window.
WinMove($hWnd, '', (@DesktopWidth / 2) - 250, (@DesktopHeight / 2) - 250, 500, 500) ; Move the AutoIt Hidden Window and re-size for a better view of the data that will be set.
WinSetState($hWnd, '', @SW_SHOW) ; Show the AutoIt Hidden Window, normally this is hidden, but in the interest of this example I'm displaying it.
Return $hWnd
EndFunc ;==>AutoItWinShow
</syntaxhighlight>

[[#top | ReturnToContents]]

== _DockToWindow ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#include <WinAPI.au3>
#include <WindowsConstants.au3>

If (Not ProcessExists("SciTE.exe")) Then
Exit MsgBox(4096, '', "Please start SciTE.exe")
EndIf

Example()

Func Example()
; Create a GUI, similar to SciTE Jump's GUI.
Local Const $hGUI = GUICreate('', 215, 400, -1, -1, BitOR($GUI_SS_DEFAULT_GUI, $WS_MAXIMIZEBOX, $WS_SIZEBOX))

GUISetState(@SW_SHOWNORMAL, $hGUI)

; Dock the first window to left and adjust the width based on the width of the second GUI.
_DockToWindow(WinGetHandle("[CLASS:SciTEWindow]"), $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example

Func _DockToWindow(Const $hHandle_1, Const $hHandle_2)
; Retrieve the working area, this is minus the taskbar dimensions so slightly different to @DesktopHeight and @DesktopWidth which is the
; monitors height and width.
Local Const $SPI_GETWORKAREA = 48
Local Const $tWorkArea = DllStructCreate($tagRECT)
_WinAPI_SystemParametersInfo($SPI_GETWORKAREA, 0, DllStructGetPtr($tWorkArea))

; Retieve the position of the second GUI.
Local Const $aClientSize_2 = WinGetPos($hHandle_2)

; Set the state of the windows to 'Restore'.
WinSetState($hHandle_1, '', @SW_RESTORE)
WinSetState($hHandle_2, '', @SW_RESTORE)

; Move the first to the far left of the screen and adjust the width to the total screen width minus the width of the second GUI. e.g. 1366 - 215
WinMove($hHandle_1, '', DllStructGetData($tWorkArea, 'Left'), DllStructGetData($tWorkArea, 'Top'), DllStructGetData($tWorkArea, 'Right') - DllStructGetData($tWorkArea, 'Left') - $aClientSize_2[2], DllStructGetData($tWorkArea, 'Bottom') - DllStructGetData($tWorkArea, 'Top'))

; Move the second window to the far right in between the remaining space and adjust the height of the GUI.
WinMove($hHandle_2, '', DllStructGetData($tWorkArea, 'Right') - DllStructGetData($tWorkArea, 'Left') - $aClientSize_2[2], DllStructGetData($tWorkArea, 'Top'), $aClientSize_2[2], DllStructGetData($tWorkArea, 'Bottom') - DllStructGetData($tWorkArea, 'Top'))
EndFunc ;==>_DockToWindow
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FuncExists ==

{{Snippet Header
| AuthorURL = 52-geosoft
| AuthorName = GEOSoft
}}

<syntaxhighlight lang="autoit">
MsgBox(0, "TEST", "Function Exists = " & _FuncExists("_FuncExists", @ScriptFullPath))

Func _FuncExists($sFunc, $sPath)
If Not FileExists($sPath) Then Return SetError(1)
Local Const $sStr = FileRead($sPath)
Local Const $sRegEx = "(?i)(?m:^|\n)\s*Func\s+(" & $sFunc & ")\s*\("
Local Const $aRegEx = StringRegExp($sStr, $sRegEx, 1)
If IsArray($aRegEx) Then Return 1
Return 0
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FunctionSort ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Get the list of Functions in a script and sort by alphabetical order.

#include <Array.au3>
#include <String.au3>

Local $sFile = FileOpenDialog(@ScriptName, "Select an AutoIt file.", "Au3 (*.au3)")

If @error Then
Exit
EndIf
ClipPut(_FunctionSort($sFile))

Func _FunctionSort($sFilePath)
Local Const $sRead = FileRead($sFilePath)

Local $aReturn = StringRegExp("Func _Count()" & @CRLF & "EndFunc ;==>_Count" & $sRead, '(?s)(?i)Func(.*?)EndFunc', 3)

If @error Then
Return SetError(1, 0, 0)
EndIf

$aReturn[0] = UBound($aReturn, 1) - 1

_ArraySort($aReturn, 0, 1)

Local $sReturn

For $A = 1 To $aReturn[0]
$sReturn &= "Func" & $aReturn[$A] & "EndFunc" & @CRLF & @CRLF
Next

Return $sReturn
EndFunc ;==>_FunctionSort
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsBeta ==

{{Snippet Header
| AuthorURL = 10673-mlipok
| AuthorName = mLipok
}}

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

Example()

Func Example()
Local $aTest[10]
_ArrayUnique($aTest, 0, 5)
Local $iError = @error
ConsoleWrite('$iError = ' & $iError & @CRLF)
If _IsBeta() Then
If $iError = 3 Then
MsgBox($MB_SYSTEMMODAL, '@error', '3 - $iBase or $iCase contains an invalid value' & @CRLF & @AutoItVersion)
EndIf
Else
If $iError = 2 Then
MsgBox($MB_SYSTEMMODAL, '@error', '2 - $iBase or $iCase contains an invalid value' & @CRLF & @AutoItVersion)
EndIf
EndIf
EndFunc ;==>Example

Func _IsBeta()
Return Mod(StringSplit(@AutoItVersion, '.')[3], 2) == 1
EndFunc ;==>_IsBeta
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsButton ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <ButtonConstants.au3>
#include <Constants.au3>
#include <WinAPI.au3>

Example()

Func Example()
Local Const $hGUI = GUICreate('')
Local Const $iLabel = GUICtrlCreateButton('', 0, 0, 50, 50)
Local Const $iCheckbox = GUICtrlCreateCheckbox('', 0, 0, 100, 20) ; This is considered a 'Button' by _WinAPI_GetClassName too.

GUISetState(@SW_SHOWNORMAL, $hGUI)

MsgBox(4096, '', 'AutoIt Button ID: ' & _IsButton($iLabel) & @CRLF & _
'AutoIt Button Handle: ' & _IsButton(GUICtrlGetHandle($iLabel)) & @CRLF & _
'AutoIt Checkbox ID: ' & _IsButton($iCheckbox) & @CRLF & _
'AutoIt Checkbox Handle: ' & _IsButton(GUICtrlGetHandle($iCheckbox)) & @CRLF)

Return GUIDelete($hGUI)
EndFunc ;==>Example

; Check if a variable is referencing a Button control.
Func _IsButton($hWnd)
If IsHWnd($hWnd) = 0 Then
$hWnd = GUICtrlGetHandle($hWnd)
EndIf

Local Const $sClassName = _WinAPI_GetClassName($hWnd)

If $sClassName = 'Button' Then
Local Const $aStyle[5] = [4, $BS_CHECKBOX, $BS_AUTOCHECKBOX, $BS_RADIOBUTTON, $BS_AUTORADIOBUTTON]

Local Const $iLong = _WinAPI_GetWindowLong($hWnd, $GWL_STYLE)

For $i = 1 To $aStyle[0]
If BitAND($iLong, $aStyle[$i]) = $aStyle[$i] Then
Return False
EndIf
Next

Return True
EndIf

Return False
EndFunc ;==>_IsButton
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsControlID ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Check if a Control ID is a native AutoIt control.

#include <GUIListView.au3>
#include <WinAPI.au3>

Example()

Func Example()
Local Const $hGUI = GUICreate('')
Local Const $iControlID = GUICtrlCreateLabel('', 0, 0, 500, 500)
Local Const $hListView = _GUICtrlListView_Create($hGUI, 'Example', 0, 0, 500, 500)

GUISetState(@SW_SHOWNORMAL, $hGUI)

MsgBox(4096, '', 'AutoIt ControlID: ' & _IsControlID($iControlID) & @CRLF & _
'Random Number: ' & _IsControlID(Random(42, 99, 1)) & @CRLF & _
'AutoIt ControlID Handle: ' & _IsControlID(GUICtrlGetHandle($iControlID)) & @CRLF & _
'ListView UDF Handle: ' & _IsControlID($hListView) & @CRLF & _
'ListView UDF Handle: ' & _IsControlID(GUICtrlGetHandle($hListView)) & @CRLF)

_GUICtrlListView_Destroy($hListView)

Return GUIDelete($hGUI)
EndFunc ;==>Example

Func _IsControlID($iControlID)
If IsHWnd($iControlID) Then
$iControlID = _WinAPI_GetDlgCtrlID($iControlID)
EndIf

Return IsHWnd(GUICtrlGetHandle($iControlID)) = 1
EndFunc ;==>_IsControlID
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetAutoItIncludesFromSciTE ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

ConsoleWrite(_GetAutoItIncludesFromSciTE() & @CRLF)

; Retrieve the AutoIt includes path from the SciTE process.
Func _GetAutoItIncludesFromSciTE()
Local $sRelativePath = '..\Include'
Local Const $sWorkingDir = @WorkingDir
FileChangeDir(_WinAPI_PathRemoveFileSpec(_WinAPI_GetProcessFileName(ProcessExists('SciTE.exe'))))
$sRelativePath = _WinAPI_GetFullPathName($sRelativePath)
FileChangeDir($sWorkingDir)
Return _WinAPI_PathRemoveBackslash($sRelativePath)
EndFunc ;==>_GetAutoItIncludesFromSciTE
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetAutoItInstall ==

{{Snippet Header
|AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Get the AutoIt installation folder.

ConsoleWrite(_GetAutoItInstall() & @CRLF)

Func _GetAutoItInstall()
Return StringLeft(@AutoItExe, StringInStr(@AutoItExe, "\", 2, -1) - 1)
EndFunc ;==>_GetAutoItInstall
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetAutoItInstallEx ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_GetAutoItInstallEx() & @CRLF)

; Get the installation of AutoIt. An improved version of _GetAutoItInstall.
Func _GetAutoItInstallEx()
Local $aWow6432Node[2] = ['', 'Wow6432Node\'], $aFiles[4] = [3, @ProgramFilesDir, EnvGet("PROGRAMFILES"), EnvGet("PROGRAMFILES(X86)")]
Local $sFilePath = RegRead('HKEY_LOCAL_MACHINE\SOFTWARE\' & $aWow6432Node[@AutoItX64] & 'AutoIt v3\AutoIt\', 'InstallDir')
If @error Then
For $A = 1 To $aFiles[0]
$aFiles[$A] &= '\AutoIt'
If FileExists($aFiles[$A]) Then
Return $aFiles[$A]
EndIf
Next
Return SetError(1, 0, '')
Else
Return $sFilePath
EndIf
EndFunc ;==>_GetAutoItInstallEx
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetAutoItInstallFromSciTE ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_GetAutoItInstallFromSciTE() & @CRLF)

; Retrieve the AutoIt installation path from the SciTE process.
Func _GetAutoItInstallFromSciTE()
Local $sRelativePath = '..\', $sWorkingDir = @WorkingDir
FileChangeDir( _WinAPI_PathRemoveFileSpec(_WinAPI_GetProcessFileName(ProcessExists("SciTE.exe"))))
$sRelativePath = _WinAPI_GetFullPathName($sRelativePath)
FileChangeDir($sWorkingDir)
Return _WinAPI_PathRemoveBackslash($sRelativePath)
EndFunc ;==>_GetAutoItInstallFromSciTE
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetClasses ==

{{Snippet Header
| AuthorURL = 24-cyberslug
| AuthorName = CyberSlug
}}

<syntaxhighlight lang="autoit">
; Get ALL Controls Info

Example()

Func Example()
; Run Calculator
Run("calc.exe")

; Wait 10 seconds for the Calculator window to appear.
Local const $hWnd = WinWait("[CLASS:CalcFrame]", '', 10)

; Retrieve a list of all the controls in the Calculator window using the handle returned by WinWait.
MsgBox(4096, '', _GetClasses($hWnd))

; Close the Calculator window using the handle returned by WinWait.
WinClose($hWnd)
EndFunc ;==>Example

; This function returns an @LF-separated list of controls on the specified window.
Func _GetClasses($sTitle, $sText = '')
Local $iCount_Button = 0, $iCount_Edit = 0, $iCount_Static = 0
Local $aClasses = StringSplit(WinGetClassList($sTitle, $sText), @LF)
Local $aClassID[$aClasses[0] + 1] = [$aClasses[0]]

For $i = 1 To $aClasses[0]
Select
Case $aClasses[$i] = "Button"
$iCount_Button += 1
$aClassID[$i] = $aClasses[$i] & $iCount_Button
Case $aClasses[$i] = "Edit"
$iCount_Edit += 1
$aClassID[$i] = $aClasses[$i] & $iCount_Edit
$aClasses[$i] = "Input"
Case $aClasses[$i] = "Static"
$iCount_Static += 1
$aClassID[$i] = $aClasses[$i] & $iCount_Static
$aClasses[$i] = "Label"
Case Else
If $aClasses[$i] <> "" Then
$aClassID[$i] = $aClasses[$i] & "?"
EndIf
EndSelect
Next

; Combine the results.
Local $sReturn = ""

For $i = 1 To $aClassID[0]
$sReturn &= $aClassID[$i] & @LF
Next

Return $sReturn
EndFunc ;==>_GetClasses
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; FileRead Alternative

Func _GetFile($sFile, $iFormat = 0)
Local $hFileOpen = FileOpen($sFile, $iFormat)
If $hFileOpen = -1 Then
Return SetError(1, 0, "")
EndIf
Local $sData = FileRead($hFileOpen)
FileClose($hFileOpen)
Return $sData
EndFunc ;==>_GetFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetTitle ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Get the title of your program.

ConsoleWrite(_GetTitle('Example') & @CRLF)
; The second parameter would normally be @ScriptDir & '\Uninstall.exe' for example, but for this demonstration I'm using the full path.
ConsoleWrite(_GetTitle('Example', @ScriptFullPath) & @CRLF)

Func _GetTitle($sProgramName, $sInstallPath = '')
Local $aOSArch[2] = ['', ' (64-bit)'], $aPortable[2] = [' (Portable)', '']
Return $sProgramName & $aOSArch[@AutoItX64] & $aPortable[FileExists($sInstallPath)]
EndFunc ;==>_GetTitle
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetXML ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Simple Way Of Parsing XML Data.

#include <Array.au3>

Global $aReturn, $sXMLData

$sXMLData = "<data>This is a Simple example of XML</data><data>This is a Simple example of XML and is the Second String.</data>"
$aReturn = _GetXML($sXMLData, "data")
_ArrayDisplay($aReturn, "_GetXML()")

Func _GetXML($sString, $sData)
Local $aError[2] = [1, $sString], $aReturn
$aReturn = StringRegExp('<' & $sData & '></' & $sData & '>' & $sString, '(?s)(?i)<' & $sData & '>(.*?)</' & $sData & '>', 3)
If @error Then
Return SetError(1, 0, $aError)
EndIf
$aReturn[0] = UBound($aReturn, 1) - 1
Return SetError(0, 0, $aReturn)
EndFunc ;==>_GetXML
</syntaxhighlight>

[[#top | ReturnToContents]]

== Include Source With Exe ==

{{Snippet Header
| AuthorURL = 54985-jlogan3o13
| AuthorName = JLogan3o13
}}

<syntaxhighlight lang="autoit">
;recover source .au3 file with /Extract switch
; The above code would be copied into the top of your script. The source location (C:\Test.au3 in my example) is the full path to your script file.
;Once compiled, if you run the script from the Run line with the /Extract switch, it will extact the original .au3 file into the Temp directory and will exit without actually executing the script.
If StringInStr($cmdlineRaw, "/Extract") Then
FileInstall("C:\Test.au3", @TempDir & "\Test.au3", 1)
Exit
EndIf
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsANSIFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

ConsoleWrite(_IsANSIFile(@ScriptFullPath) & @LF) ; Returns True.

Func _IsANSIFile($sFilePath)
Return FileGetEncoding($sFilePath) = $FO_READ
EndFunc ;==>_IsUnicodeFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsUnicodeFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

ConsoleWrite(_IsUnicodeFile(@ScriptFullPath) & @LF) ; Returns False.

Func _IsUnicodeFile($sFilePath)
Return FileGetEncoding($sFilePath) = $FO_UNICODE
EndFunc ;==>_IsUnicodeFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsAu3File ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_IsAu3File(@AutoItExe) & @CRLF)
ConsoleWrite(_IsAu3File(@ScriptFullPath) & @CRLF)

; Checks whether the filepath is an au3 file.
Func _IsAu3File($sFilePath)
Return StringTrimLeft($sFilePath, StringInStr($sFilePath, ".", 2, -1)) = "au3"
EndFunc ;==>_IsAu3File
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsDefault ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
If _IsDefault(Default) Then
MsgBox(0, "_IsDefault() - 1", "This was a Default variable.")
EndIf

If _IsDefault(-1) Then
MsgBox(0, "_IsDefault() - 2", "This was a Default variable.")
EndIf

If _IsDefault("Other") Then
MsgBox(0, "_IsDefault() - 3", "This was a Default variable.")
EndIf

Func _IsDefault($sDefault)
Return StringRegExp($sDefault, "(?-i)\s|Default|-1|0")
EndFunc ;==>_IsDefault
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsInTrial ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <Date.au3> ; Required for _DateDiff()

ConsoleWrite('Date trial started: ' & @YEAR & '/' & @MON & '/01' & @CRLF & _
'Today''s date: ' & @YEAR & '/' & @MON & '/' & @MDAY & @CRLF & _
'Trial period: 30 days' & @CRLF & _
'Is the trial period still valid: ' & _IsInTrial(@YEAR & '/' & @MON & '/01', 30) & @CRLF)

; Check if a trial period date is still valid.
Func _IsInTrial($sDateString, $iDays) ; Based on the idea found here: http://www.autoitscript.com/forum/topic/...ial-time/page__view__findpost_
Return (_DateDiff('D', $sDateString, @YEAR & '/' & @MON & '/' & @MDAY) < $iDays)
EndFunc ;==>_IsInTrial
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsVisible ==

{{Snippet Header
| AuthorURL = none
| AuthorName = Multiple
}}

<syntaxhighlight lang="autoit">
; Check if the Notepad Window is visible.

Example()

Func Example()
; Run Notepad
Run("notepad.exe")

; Wait 10 seconds for the Notepad window to appear.
Local $hWnd = WinWait("[CLASS:Notepad]", "", 10)

; Check if the Notepad window is visible and display the appropriate message box.
If _IsVisible($hWnd) Then
MsgBox(4096, "", "Notepad is visible.")
Else
MsgBox(4096, "", "Notepad isn't visible.")
EndIf

; Close the Notepad window using the handle returned by WinWait.
WinClose($hWnd)
EndFunc ;==>Example

; Check if the window is visible.
Func _IsVisible($hWnd)
Return BitAND(WinGetState($hWnd), 2) = 2
EndFunc ;==>_IsVisible
</syntaxhighlight>

[[#top | ReturnToContents]]

== Open Help File to Desired Page ==

{{Snippet Header
| AuthorURL = 1967-garyfrost
| AuthorName = GaryFrost
}}

<syntaxhighlight lang="autoit">
; Open help file / Open a desired page

Global Const $sAutoItPath = RegRead("HKEY_LOCAL_MACHINE\SOFTWARE\AutoIt v3\AutoIt", "InstallDir")

Run(@WindowsDir & "\hh.exe " & $sAutoItPath & "\AutoIt3.chm::/html/functions/GUICtrlCreateUpdown.htm")
</syntaxhighlight>

[[#top | ReturnToContents]]

== _RunAU3 ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
_RunAU3("AU3_Example.txt", '"This is a commandline example!"')

Func _RunAU3($sFilePath, $sCommandLine = "", $sWorkingDir = "", $iShowFlag = @SW_SHOW, $iOptFlag = 0)
Return Run('"' & @AutoItExe & '" /AutoIt3ExecuteScript "' & $sFilePath & '" ' & $sCommandLine, $sWorkingDir, $iShowFlag, $iOptFlag)
EndFunc ;==>_RunAU3

Func _RunWaitAU3($sFilePath, $sCommandLine = "", $sWorkingDir = "", $iShowFlag = @SW_SHOW, $iOptFlag = 0)
Local $iPID
$iPID = RunWait('"' & @AutoItExe & '" /AutoIt3ExecuteScript "' & $sFilePath & '" ' & $sCommandLine, $sWorkingDir, $iShowFlag, $iOptFlag)
If @error Then
Return SetError(@error, 1, 0)
EndIf
Return $iPID
EndFunc ;==>_RunWaitAU3
</syntaxhighlight>

[[#top | ReturnToContents]]

== Run Any au3 File From Your Program ==

{{Snippet Header
| AuthorURL = 4920-valuater
| AuthorName = Valuater
}}

<syntaxhighlight lang="autoit">
; Run Any Au3 File From Your Program

Global Const $sFilePath = @ScriptDir & "\Test.au3"

If @Compiled Then
Global Const $sFileExe = FileGetShortName(@AutoItExe & ' /AutoIt3ExecuteScript "' & $sFilePath & '"')
Run($sFileExe)
Else
Global Const $sFileAu3 = FileGetShortName($sFilePath)
Run(@AutoItExe & " " & $sFileAu3, "", @SW_HIDE)
EndIf
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ScriptName ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_ScriptName() & @CRLF)

; Return the @ScriptName minus the .exe or .au3 extension.
Func _ScriptName()
Return StringLeft(@ScriptName, StringInStr(@ScriptName, '.', 2, -1) - 1)
EndFunc ;==>_ScriptName
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ScriptVersion ==

{{Snippet Header
| AuthorURL = 31149-milesahead
| AuthorName = MilesAhead
}}

<syntaxhighlight lang="autoit">
#NoTrayIcon

#Region ;**** Directives created by AutoIt3Wrapper_GUI ****
#AutoIt3Wrapper_UseUpx=n
#AutoIt3Wrapper_Res_Fileversion=1.2.3.4
#AutoIt3Wrapper_Res_LegalCopyright=2012 www.favessoft.com
#AutoIt3Wrapper_Res_Language=1033
#AutoIt3Wrapper_AU3Check_Parameters=-d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7
#EndRegion ;**** Directives created by AutoIt3Wrapper_GUI ****

Global $version = _ScriptVersion()

Global $msg = "ScriptVerDemo" & " " & $version & " Copyright (c) 2012 www.favessoft.com" & @CRLF & @CRLF

MsgBox(0x1040, "", $msg)

; return File Version string from compiled or .au3 script
; returns "" if no version info available
; Note: The .au3 script must contain #AutoItWrapper
; directives with file version or "" is returned.
Func _ScriptVersion(Const $Script = @ScriptFullPath)
If StringRight($Script,4) = ".exe" Then
Return FileGetVersion($Script)
Else
Local Const $scriptHandle = FileOpen($Script)
Local $ver
Local $found = False
Local $pos

If $scriptHandle <> -1 Then
Do
$ver = FileReadLine($scriptHandle)
$sPos = StringInStr($ver, "_Fileversion=")

If $sPos Then
$ver = StringMid($ver, $sPos + StringLen("_Fileversion="))
$found = True
ExitLoop
EndIf
Until StringLeft($ver, 1) <> "#"

FileClose($scriptHandle)
EndIf
EndIf

If Not $found Then $ver = ""

Return $ver
EndFunc ;==>_ScriptVersion
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SetFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; FileWrite Alternative

Func _SetFile(Const $sString, Const $sFile, Const $iOverwrite = 0)
Local Const $hFileOpen = FileOpen($sFile, $iOverwrite + 1)

FileWrite($hFileOpen, $sString)
FileClose($hFileOpen)

If @error Then
Return SetError(1, 0, $sString)
EndIf

Return $sString
EndFunc ;==>_SetFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ShowHelp ==

{{Snippet Header
| AuthorURL = 60350-chimaera
| AuthorName = Chimaera
}}

<syntaxhighlight lang="autoit">
HotKeySet("{F1}", "_ShowHelp")

Func _ShowHelp()
Return ShellExecute(@ProgramFilesDir & "\AutoIt3\AutoIt3Help.exe") ; change this to the location of your own helpfile.
EndFunc ;==>_ShowHelp
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SingletonPID ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Local $iSingleton = _SingletonPID('RandomName', 1)

If $iSingleton = 0 Then
MsgBox(4096, '', 'This is the first instance of the program running: ' & $iSingleton)
Else
MsgBox(4096, '', 'There is another instance running. This PID is: ' & $iSingleton)
EndIf

; #FUNCTION# ====================================================================================================================
; Name ..........: _SingletonPID
; Description ...: Enforce a design paradigm where only one instance of the script may be running.
; Syntax ........: _SingletonPID($sOccurenceName[, $iFlag = 0])
; Parameters ....: $sOccurenceName - String to identify the occurrence of the script.
; $iFlag - [optional] Optional parameters. Default is 0.
; 0 - Exit the script with the exit code -1 if another instance already exists.
; 1 - Return the PID of the main executable and without exiting the script too.
; Return values .: Success - 0 No other process is running.
; Failure - The PID of the main executable.
; Author ........: guinness with initial ideas by Valik for _Singleton & KaFu for _EnforceSingleInstance.
; Example .......: Yes
; ===============================================================================================================================
Func _SingletonPID(Const $sOccurenceName, Const $iFlag = 0)
Local $hHandle = WinGetHandle($sOccurenceName)

If @error Then
AutoItWinSetTitle($sOccurenceName)
$hHandle = WinGetHandle($sOccurenceName)
ControlSetText($hHandle, '', ControlGetHandle($hHandle, '', 'Edit1'), @AutoItPID)
Else
If BitAND($iFlag, 1) Then
Return Number(ControlGetText($hHandle, '', ControlGetHandle($hHandle, '', 'Edit1')))
Else
Exit -1
EndIf
EndIf

Return 0
EndFunc ;==>_SingletonPID
</syntaxhighlight>

[[#top | ReturnToContents]]

== _Sort ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

ConsoleWrite(_Sort("$sVariable" & @CRLF & "$iVariable" & @CRLF & "$tVariable" & @CRLF & "$pVariable"))

Func _Sort(Const $sSortList)
Local Const $iPID = Run("sort.exe", @SystemDir, @SW_HIDE, $STDIN_CHILD + $STDOUT_CHILD), $sOutput = ""

StdinWrite($iPID, $sSortList)
StdinWrite($iPID)

While 1
$sOutput &= StdoutRead($iPID)

If @error Then
ExitLoop
EndIf
WEnd

Return $sOutput
EndFunc ;==>_Sort
</syntaxhighlight>

[[#top | ReturnToContents]]

== Speak Object and Save to WAV File ==

{{Snippet Header
| AuthorURL = 52278-solidsnake26
| AuthorName = SolidSnake26
}}

<syntaxhighlight lang="autoit">
; Speak Object and save to wav file

_SpeakToWAV("AutoIt Snippets", @ScriptDir & "\SavedFile.wav")

Func _SpeakToWAV(Const $sText, Const $sFilePath)
Local $ObjVoice = ObjCreate("Sapi.SpVoice")

Local $ObjFile = ObjCreate("Sapi.SpFileStream.1")

$ObjVoice.Speak($sText)

$ObjFile.Open($sFilePath, 3)

$ObjVoice.AudioOutputStream = $ObjFile
EndFunc ;==>_SpeakToWAV
</syntaxhighlight>

[[#top | ReturnToContents]]

== _VariableSwap ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Global $sString_1 = 'This is string 1.'
Global $sString_2 = 'This is string 2.'

ConsoleWrite('$sString_1: ' & $sString_1 & @CRLF)
ConsoleWrite('$sString_2: ' & $sString_2 & @CRLF & @CRLF)

_VariableSwap($sString_1, $sString_2)

ConsoleWrite('$sString_1: ' & $sString_1 & @CRLF)
ConsoleWrite('$sString_2: ' & $sString_2 & @CRLF & @CRLF)

; Swap the contents of two variables.
Func _VariableSwap(ByRef $vVariable_1, ByRef $vVariable_2) ; Similar to _ArraySwap though not obvious to some this isn't limited to arrays.
Local Const $vTemp = $vVariable_1
$vVariable_1 = $vVariable_2
$vVariable_2 = $vTemp
EndFunc ;==>_VariableSwap
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinAPI_CharLower ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_WinAPI_CharLower("EXAMPLE") & @CRLF) ; Similar to StringLower.

; Convert characters to lowercase.
Func _WinAPI_CharLower($sString)
Local $aReturn = DllCall('user32.dll', 'wstr', 'CharLowerW', 'wstr', $sString)
If @error Then
Return SetError(1, 0, $sString)
EndIf
Return $aReturn[0]
EndFunc ;==>_WinAPI_CharLower
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinAPI_CharUpper ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_WinAPI_CharUpper("example") & @CRLF) ; Similar to StringUpper.

; Convert characters to uppercase.
Func _WinAPI_CharUpper($sString)
Local $aReturn = DllCall('user32.dll', 'wstr', 'CharUpperW', 'wstr', $sString)
If @error Then
Return SetError(1, 0, $sString)
EndIf
Return $aReturn[0]
EndFunc ;==>_WinAPI_CharUpper
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinAPI_PathFileExists ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; An API Alternative To FileExist.

ConsoleWrite(_WinAPI_PathFileExists(@ScriptFullPath) & @LF) ; File.
ConsoleWrite(_WinAPI_PathFileExists("C:\") & @LF) ; Drive.
ConsoleWrite(_WinAPI_PathFileExists(@ProgramFilesDir) & @LF) ; Directory.
ConsoleWrite(_WinAPI_PathFileExists("Z:\File.txt") & @LF) ; Shouldn't exist!

Func _WinAPI_PathFileExists($sFilePath)
Local $aReturn = DllCall('shlwapi.dll', 'int', 'PathFileExistsW', 'wstr', $sFilePath)
If @error Then
Return SetError(1, 0, 0)
EndIf
Return $aReturn[0]
EndFunc ;==>_WinAPI_PathFileExists
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinActiveByExe ==

{{Snippet Header
| AuthorURL = 4813-smoke-n
| AuthorName = SmOke_N
}}

<syntaxhighlight lang="autoit">
; Window Active/Activate by Exe, Open Notepad whilst script is running

While 1
If _WinActiveByExe('notepad.exe', False) Then MsgBox(64, 'info', 'true')
Sleep(100)
WEnd

Func _WinActiveByExe($sExe, $iActive = True);False to WinActivate, True to just see if it's active
If Not ProcessExists($sExe) Then Return SetError(1, 0, 0)
Local $aPL = ProcessList($sExe)
Local $aWL = WinList()
For $iCC = 1 To $aWL[0][0]
For $xCC = 1 To $aPL[0][0]
If $aWL[$iCC][0] <> '' And _
WinGetProcess($aWL[$iCC][1]) = $aPL[$xCC][1] And _
BitAND(WinGetState($aWL[$iCC][1]), 2) Then
If $iActive And WinActive($aWL[$iCC][1]) Then Return 1
If Not $iActive And Not WinActive($aWL[$iCC][1]) Then
WinActivate($aWL[$iCC][1])
Return 1
EndIf
EndIf
Next
Next
Return SetError(2, 0, 0)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WindowShake ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Shake a window left to right.

Example()

Func Example()
; Run Notepad
Run("notepad.exe")

; Wait 10 seconds for the Notepad window to appear.
Local $hWnd = WinWait("[CLASS:Notepad]", "", 10)

; Wait for 1 second.
Sleep(1000)

; Shake the Notepad window left to right.
_WindowShake($hWnd)

; Wait for 1 second.
Sleep(1000)

; Close the Notepad window using the handle returned by WinWait.
WinClose($hWnd)
EndFunc ;==>Example

Func _WindowShake($sTitle, $sText = '', $iDistance = 20)
Local $hWnd = WinGetHandle($sTitle, $sText)
Local $aWinGetPos = WinGetPos($hWnd)
If @error Then
Return SetError(1, 0, 0)
EndIf
Local $aArray[5] = [4, $aWinGetPos[0] + $iDistance, $aWinGetPos[0], $aWinGetPos[0] + $iDistance, $aWinGetPos[0]]

For $i = 1 To $aArray[0]
WinMove($hWnd, '', $aArray[$i], Default)
Sleep(100)
Next
EndFunc ;==>_WindowShake
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinGetDetails ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

Global $aArray = _WinGetDetails('[ACTIVE]') ; Returns the Window's title, PID, folder path filename.

If @error Then
Exit
EndIf

_ArrayDisplay($aArray)

Func _WinGetDetails($sTitle, $sText = '') ; Based on code of _WinGetPath by GaryFrost.
Local $aReturn[5] = [4, '-WinTitle', '-PID', '-FolderPath', '-FileName'], $aStringSplit

If StringLen($sText) > 0 Then
$aReturn[1] = WinGetTitle($sTitle, $sText)
Else
$aReturn[1] = WinGetTitle($sTitle)
EndIf
$aReturn[2] = WinGetProcess($aReturn[1])

Local $oWMIService = ObjGet('winmgmts:\\.\root\CIMV2')
Local $oItems = $oWMIService.ExecQuery('Select * From Win32_Process Where ProcessId = ' & $aReturn[2], 'WQL', 0x30)
If IsObj($oItems) Then
For $oItem In $oItems
If $oItem.ExecutablePath Then
$aStringSplit = StringSplit($oItem.ExecutablePath, '\')
$aReturn[3] = ''
For $A = 1 To $aStringSplit[0] - 1
$aReturn[3] &= $aStringSplit[$A] & '\'
Next
$aReturn[3] = StringTrimRight($aReturn[3], 1)
$aReturn[4] = $aStringSplit[$aStringSplit[0]]
Return $aReturn
EndIf
Next
EndIf
Return SetError(1, 0, $aReturn)
EndFunc ;==>_WinGetPath
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinGetNumeratedClassList ==

{{Snippet Header
| AuthorURL = 20477-mrcreator
| AuthorName = MrCreatoR
}}

<syntaxhighlight lang="autoit">
; Description: Retrieves the numerated classes from a window.

Func _WinGetNumeratedClassList($sTitle)
Local $sClassList = WinGetClassList($sTitle)
Local $aClassList = StringSplit($sClassList, @LF)
Local $sRetClassList = "", $sHold_List = "|"
Local $aiInHold, $iInHold

For $i = 1 To UBound($aClassList) - 1
If $aClassList[$i] = "" Then ContinueLoop

If StringRegExp($sHold_List, "\|" & $aClassList[$i] & "~(\d+)\|") Then
$aiInHold = StringRegExp($sHold_List, ".*\|" & $aClassList[$i] & "~(\d+)\|.*", 1)
$iInHold = Number($aiInHold[UBound($aiInHold)-1])

If $iInHold = 0 Then $iInHold += 1

$aClassList[$i] &= "~" & $iInHold + 1
$sHold_List &= $aClassList[$i] & "|"

$sRetClassList &= $aClassList[$i] & @LF
Else
$aClassList[$i] &= "~1"
$sHold_List &= $aClassList[$i] & "|"
$sRetClassList &= $aClassList[$i] & @LF
EndIf
Next

Return StringReplace(StringStripWS($sRetClassList, 3), "~", "")
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinGetHandleByPID ==

{{Snippet Header
| AuthorURL = 4813-smoke-n
| AuthorName = SmOke_N
}}

<syntaxhighlight lang="autoit">
; Get Window Handle by PID

#include <Array.au3>

Global $a1 = _WinGetHandleByPID(232)
Global $a2 = _WinGetHandleByPID("notepad.exe", -1)
Global $a3 = _WinGetHandleByPID("notepad.exe", 0)
Global $a4 = _WinGetHandleByPID("notepad.exe", 1)

_ArrayDisplay($a1, "1")
_ArrayDisplay($a2, "2")
_ArrayDisplay($a3, "3")
_ArrayDisplay($a4, "4")

;$nVisible = -1 "All (Visble or not)", $nVisible = 0 "Not Visible Only", $nVisible = 1 "Visible Only"
Func _WinGetHandleByPID($vProc, $nVisible = 1)
$vProc = ProcessExists($vProc);

If Not $vProc Then Return SetError(1, 0, 0)

Local $aWL = WinList()

Local $aTemp[UBound($aWL)][2]

Local $nAdd = 0

For $iCC = 1 To $aWL[0][0]
If $nVisible = -1 And WinGetProcess($aWL[$iCC][1]) = $vProc Then
$nAdd += 1
$aTemp[$nAdd][0] = $aWL[$iCC][0]
$aTemp[$nAdd][1] = $aWL[$iCC][1]
ElseIf $nVisible = 0 And WinGetProcess($aWL[$iCC][1]) = $vProc And _
BitAND(WinGetState($aWL[$iCC][1]), 2) = 0 Then
$nAdd += 1
$aTemp[$nAdd][0] = $aWL[$iCC][0]
$aTemp[$nAdd][1] = $aWL[$iCC][1]
ElseIf $nVisible > 0 And WinGetProcess($aWL[$iCC][1]) = $vProc And _
BitAND(WinGetState($aWL[$iCC][1]), 2) Then
$nAdd += 1
$aTemp[$nAdd][0] = $aWL[$iCC][0]
$aTemp[$nAdd][1] = $aWL[$iCC][1]
EndIf
Next

If $nAdd = 0 Then Return SetError(2, 0, 0) ; No windows found

ReDim $aTemp[$nAdd + 1][2]

$aTemp[0][0] = $nAdd

Return $aTemp
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

Snippets ( AutoIt )

2015-01-16T21:31:31Z

Guinness: /* _WinAPI_CharLower */

__TOC__
[[category:Snippets]]

{{Snippet Credit Header}}

== AutoItWinShow ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

Example()

Func Example()
; Display AutoIt's Hidden Window. See AutoItWinGetTitle and AutoItWinSetTitle for more details.
AutoItWinShow()

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
EndSwitch
WEnd
EndFunc ;==>Example

; Display AutoIt's Hidden Window. Returns the handle of the window.
Func AutoItWinShow()
Local Const $hWnd = WinGetHandle(AutoItWinGetTitle()) ; Get the handle of the AutoIt Hidden Window by finding out the title of the AutoIt Hidden Window.
WinMove($hWnd, '', (@DesktopWidth / 2) - 250, (@DesktopHeight / 2) - 250, 500, 500) ; Move the AutoIt Hidden Window and re-size for a better view of the data that will be set.
WinSetState($hWnd, '', @SW_SHOW) ; Show the AutoIt Hidden Window, normally this is hidden, but in the interest of this example I'm displaying it.
Return $hWnd
EndFunc ;==>AutoItWinShow
</syntaxhighlight>

[[#top | ReturnToContents]]

== AutoItWinGetText ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Example()

Func Example()
; Display AutoIt's Hidden Window. See AutoItWinGetTitle and AutoItWinSetTitle for more details.
AutoItWinShow()

; Add a text string to AutoIt's Hidden Window. Compile to see the text in AutoIt's Hidden Window.
AutoItWinSetText('Welcome to AutoIt V' & @AutoItVersion & @CRLF)

; Add a text string to AutoIt's Hidden Window. Compile to see the text in AutoIt's Hidden Window.
AutoItWinSetText('Windows Type: ' & @OSType & @CRLF)

; Display the text stored in AutoIt's Hidden Window.
MsgBox(4096, '', AutoItWinGetText())

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
EndSwitch
WEnd
EndFunc ;==>Example

; Retrieve the text in AutoIt's Hidden Window.
Func AutoItWinGetText()
Local Const $hWnd = WinGetHandle(AutoItWinGetTitle()) ; Get the handle of the AutoIt Hidden Window by finding out the title of the AutoIt Hidden Window.
Return ControlGetText($hWnd, '', ControlGetHandle($hWnd, '', 'Edit1'))
EndFunc ;==>AutoItWinGetText

; Add text to AutoIt's Hidden Window.
Func AutoItWinSetText($sString)
Local Const $hWnd = WinGetHandle(AutoItWinGetTitle()) ; Get the handle of the AutoIt Hidden Window by finding out the title of the AutoIt Hidden Window.
Return ControlSetText($hWnd, "", ControlGetHandle($hWnd, "", 'Edit1'), ControlGetText($hWnd, '', ControlGetHandle($hWnd, '', 'Edit1')) & $sString)
EndFunc ;==>AutoItWinSetText

; Display AutoIt's Hidden Window. Returns the handle of the window.
Func AutoItWinShow()
Local Const $hWnd = WinGetHandle(AutoItWinGetTitle()) ; Get the handle of the AutoIt Hidden Window by finding out the title of the AutoIt Hidden Window.
WinMove($hWnd, '', (@DesktopWidth / 2) - 250, (@DesktopHeight / 2) - 250, 500, 500) ; Move the AutoIt Hidden Window and re-size for a better view of the data that will be set.
WinSetState($hWnd, '', @SW_SHOW) ; Show the AutoIt Hidden Window, normally this is hidden, but in the interest of this example I'm displaying it.
Return $hWnd
EndFunc ;==>AutoItWinShow
</syntaxhighlight>

[[#top | ReturnToContents]]

== _DockToWindow ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#include <WinAPI.au3>
#include <WindowsConstants.au3>

If (Not ProcessExists("SciTE.exe")) Then
Exit MsgBox(4096, '', "Please start SciTE.exe")
EndIf

Example()

Func Example()
; Create a GUI, similar to SciTE Jump's GUI.
Local Const $hGUI = GUICreate('', 215, 400, -1, -1, BitOR($GUI_SS_DEFAULT_GUI, $WS_MAXIMIZEBOX, $WS_SIZEBOX))

GUISetState(@SW_SHOWNORMAL, $hGUI)

; Dock the first window to left and adjust the width based on the width of the second GUI.
_DockToWindow(WinGetHandle("[CLASS:SciTEWindow]"), $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example

Func _DockToWindow(Const $hHandle_1, Const $hHandle_2)
; Retrieve the working area, this is minus the taskbar dimensions so slightly different to @DesktopHeight and @DesktopWidth which is the
; monitors height and width.
Local Const $SPI_GETWORKAREA = 48
Local Const $tWorkArea = DllStructCreate($tagRECT)
_WinAPI_SystemParametersInfo($SPI_GETWORKAREA, 0, DllStructGetPtr($tWorkArea))

; Retieve the position of the second GUI.
Local Const $aClientSize_2 = WinGetPos($hHandle_2)

; Set the state of the windows to 'Restore'.
WinSetState($hHandle_1, '', @SW_RESTORE)
WinSetState($hHandle_2, '', @SW_RESTORE)

; Move the first to the far left of the screen and adjust the width to the total screen width minus the width of the second GUI. e.g. 1366 - 215
WinMove($hHandle_1, '', DllStructGetData($tWorkArea, 'Left'), DllStructGetData($tWorkArea, 'Top'), DllStructGetData($tWorkArea, 'Right') - DllStructGetData($tWorkArea, 'Left') - $aClientSize_2[2], DllStructGetData($tWorkArea, 'Bottom') - DllStructGetData($tWorkArea, 'Top'))

; Move the second window to the far right in between the remaining space and adjust the height of the GUI.
WinMove($hHandle_2, '', DllStructGetData($tWorkArea, 'Right') - DllStructGetData($tWorkArea, 'Left') - $aClientSize_2[2], DllStructGetData($tWorkArea, 'Top'), $aClientSize_2[2], DllStructGetData($tWorkArea, 'Bottom') - DllStructGetData($tWorkArea, 'Top'))
EndFunc ;==>_DockToWindow
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FuncExists ==

{{Snippet Header
| AuthorURL = 52-geosoft
| AuthorName = GEOSoft
}}

<syntaxhighlight lang="autoit">
MsgBox(0, "TEST", "Function Exists = " & _FuncExists("_FuncExists", @ScriptFullPath))

Func _FuncExists($sFunc, $sPath)
If Not FileExists($sPath) Then Return SetError(1)
Local Const $sStr = FileRead($sPath)
Local Const $sRegEx = "(?i)(?m:^|\n)\s*Func\s+(" & $sFunc & ")\s*\("
Local Const $aRegEx = StringRegExp($sStr, $sRegEx, 1)
If IsArray($aRegEx) Then Return 1
Return 0
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FunctionSort ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Get the list of Functions in a script and sort by alphabetical order.

#include <Array.au3>
#include <String.au3>

Local $sFile = FileOpenDialog(@ScriptName, "Select an AutoIt file.", "Au3 (*.au3)")

If @error Then
Exit
EndIf
ClipPut(_FunctionSort($sFile))

Func _FunctionSort($sFilePath)
Local Const $sRead = FileRead($sFilePath)

Local $aReturn = StringRegExp("Func _Count()" & @CRLF & "EndFunc ;==>_Count" & $sRead, '(?s)(?i)Func(.*?)EndFunc', 3)

If @error Then
Return SetError(1, 0, 0)
EndIf

$aReturn[0] = UBound($aReturn, 1) - 1

_ArraySort($aReturn, 0, 1)

Local $sReturn

For $A = 1 To $aReturn[0]
$sReturn &= "Func" & $aReturn[$A] & "EndFunc" & @CRLF & @CRLF
Next

Return $sReturn
EndFunc ;==>_FunctionSort
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsBeta ==

{{Snippet Header
| AuthorURL = 10673-mlipok
| AuthorName = mLipok
}}

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

Example()

Func Example()
Local $aTest[10]
_ArrayUnique($aTest, 0, 5)
Local $iError = @error
ConsoleWrite('$iError = ' & $iError & @CRLF)
If _IsBeta() Then
If $iError = 3 Then
MsgBox($MB_SYSTEMMODAL, '@error', '3 - $iBase or $iCase contains an invalid value' & @CRLF & @AutoItVersion)
EndIf
Else
If $iError = 2 Then
MsgBox($MB_SYSTEMMODAL, '@error', '2 - $iBase or $iCase contains an invalid value' & @CRLF & @AutoItVersion)
EndIf
EndIf
EndFunc ;==>Example

Func _IsBeta()
Return Mod(StringSplit(@AutoItVersion, '.')[3], 2) == 1
EndFunc ;==>_IsBeta
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsButton ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <ButtonConstants.au3>
#include <Constants.au3>
#include <WinAPI.au3>

Example()

Func Example()
Local Const $hGUI = GUICreate('')
Local Const $iLabel = GUICtrlCreateButton('', 0, 0, 50, 50)
Local Const $iCheckbox = GUICtrlCreateCheckbox('', 0, 0, 100, 20) ; This is considered a 'Button' by _WinAPI_GetClassName too.

GUISetState(@SW_SHOWNORMAL, $hGUI)

MsgBox(4096, '', 'AutoIt Button ID: ' & _IsButton($iLabel) & @CRLF & _
'AutoIt Button Handle: ' & _IsButton(GUICtrlGetHandle($iLabel)) & @CRLF & _
'AutoIt Checkbox ID: ' & _IsButton($iCheckbox) & @CRLF & _
'AutoIt Checkbox Handle: ' & _IsButton(GUICtrlGetHandle($iCheckbox)) & @CRLF)

Return GUIDelete($hGUI)
EndFunc ;==>Example

; Check if a variable is referencing a Button control.
Func _IsButton($hWnd)
If IsHWnd($hWnd) = 0 Then
$hWnd = GUICtrlGetHandle($hWnd)
EndIf

Local Const $sClassName = _WinAPI_GetClassName($hWnd)

If $sClassName = 'Button' Then
Local Const $aStyle[5] = [4, $BS_CHECKBOX, $BS_AUTOCHECKBOX, $BS_RADIOBUTTON, $BS_AUTORADIOBUTTON]

Local Const $iLong = _WinAPI_GetWindowLong($hWnd, $GWL_STYLE)

For $i = 1 To $aStyle[0]
If BitAND($iLong, $aStyle[$i]) = $aStyle[$i] Then
Return False
EndIf
Next

Return True
EndIf

Return False
EndFunc ;==>_IsButton
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsControlID ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Check if a Control ID is a native AutoIt control.

#include <GUIListView.au3>
#include <WinAPI.au3>

Example()

Func Example()
Local Const $hGUI = GUICreate('')
Local Const $iControlID = GUICtrlCreateLabel('', 0, 0, 500, 500)
Local Const $hListView = _GUICtrlListView_Create($hGUI, 'Example', 0, 0, 500, 500)

GUISetState(@SW_SHOWNORMAL, $hGUI)

MsgBox(4096, '', 'AutoIt ControlID: ' & _IsControlID($iControlID) & @CRLF & _
'Random Number: ' & _IsControlID(Random(42, 99, 1)) & @CRLF & _
'AutoIt ControlID Handle: ' & _IsControlID(GUICtrlGetHandle($iControlID)) & @CRLF & _
'ListView UDF Handle: ' & _IsControlID($hListView) & @CRLF & _
'ListView UDF Handle: ' & _IsControlID(GUICtrlGetHandle($hListView)) & @CRLF)

_GUICtrlListView_Destroy($hListView)

Return GUIDelete($hGUI)
EndFunc ;==>Example

Func _IsControlID($iControlID)
If IsHWnd($iControlID) Then
$iControlID = _WinAPI_GetDlgCtrlID($iControlID)
EndIf

Return IsHWnd(GUICtrlGetHandle($iControlID)) = 1
EndFunc ;==>_IsControlID
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetAutoItIncludesFromSciTE ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

ConsoleWrite(_GetAutoItIncludesFromSciTE() & @CRLF)

; Retrieve the AutoIt includes path from the SciTE process.
Func _GetAutoItIncludesFromSciTE()
Local $sRelativePath = '..\Include'
Local Const $sWorkingDir = @WorkingDir
FileChangeDir(_WinAPI_PathRemoveFileSpec(_WinAPI_GetProcessFileName(ProcessExists('SciTE.exe'))))
$sRelativePath = _WinAPI_GetFullPathName($sRelativePath)
FileChangeDir($sWorkingDir)
Return _WinAPI_PathRemoveBackslash($sRelativePath)
EndFunc ;==>_GetAutoItIncludesFromSciTE
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetAutoItInstall ==

{{Snippet Header
|AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Get the AutoIt installation folder.

ConsoleWrite(_GetAutoItInstall() & @CRLF)

Func _GetAutoItInstall()
Return StringLeft(@AutoItExe, StringInStr(@AutoItExe, "\", 2, -1) - 1)
EndFunc ;==>_GetAutoItInstall
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetAutoItInstallEx ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_GetAutoItInstallEx() & @CRLF)

; Get the installation of AutoIt. An improved version of _GetAutoItInstall.
Func _GetAutoItInstallEx()
Local $aWow6432Node[2] = ['', 'Wow6432Node\'], $aFiles[4] = [3, @ProgramFilesDir, EnvGet("PROGRAMFILES"), EnvGet("PROGRAMFILES(X86)")]
Local $sFilePath = RegRead('HKEY_LOCAL_MACHINE\SOFTWARE\' & $aWow6432Node[@AutoItX64] & 'AutoIt v3\AutoIt\', 'InstallDir')
If @error Then
For $A = 1 To $aFiles[0]
$aFiles[$A] &= '\AutoIt'
If FileExists($aFiles[$A]) Then
Return $aFiles[$A]
EndIf
Next
Return SetError(1, 0, '')
Else
Return $sFilePath
EndIf
EndFunc ;==>_GetAutoItInstallEx
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetAutoItInstallFromSciTE ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_GetAutoItInstallFromSciTE() & @CRLF)

; Retrieve the AutoIt installation path from the SciTE process.
Func _GetAutoItInstallFromSciTE()
Local $sRelativePath = '..\', $sWorkingDir = @WorkingDir
FileChangeDir( _WinAPI_PathRemoveFileSpec(_WinAPI_GetProcessFileName(ProcessExists("SciTE.exe"))))
$sRelativePath = _WinAPI_GetFullPathName($sRelativePath)
FileChangeDir($sWorkingDir)
Return _WinAPI_PathRemoveBackslash($sRelativePath)
EndFunc ;==>_GetAutoItInstallFromSciTE
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetClasses ==

{{Snippet Header
| AuthorURL = 24-cyberslug
| AuthorName = CyberSlug
}}

<syntaxhighlight lang="autoit">
; Get ALL Controls Info

Example()

Func Example()
; Run Calculator
Run("calc.exe")

; Wait 10 seconds for the Calculator window to appear.
Local const $hWnd = WinWait("[CLASS:CalcFrame]", '', 10)

; Retrieve a list of all the controls in the Calculator window using the handle returned by WinWait.
MsgBox(4096, '', _GetClasses($hWnd))

; Close the Calculator window using the handle returned by WinWait.
WinClose($hWnd)
EndFunc ;==>Example

; This function returns an @LF-separated list of controls on the specified window.
Func _GetClasses($sTitle, $sText = '')
Local $iCount_Button = 0, $iCount_Edit = 0, $iCount_Static = 0
Local $aClasses = StringSplit(WinGetClassList($sTitle, $sText), @LF)
Local $aClassID[$aClasses[0] + 1] = [$aClasses[0]]

For $i = 1 To $aClasses[0]
Select
Case $aClasses[$i] = "Button"
$iCount_Button += 1
$aClassID[$i] = $aClasses[$i] & $iCount_Button
Case $aClasses[$i] = "Edit"
$iCount_Edit += 1
$aClassID[$i] = $aClasses[$i] & $iCount_Edit
$aClasses[$i] = "Input"
Case $aClasses[$i] = "Static"
$iCount_Static += 1
$aClassID[$i] = $aClasses[$i] & $iCount_Static
$aClasses[$i] = "Label"
Case Else
If $aClasses[$i] <> "" Then
$aClassID[$i] = $aClasses[$i] & "?"
EndIf
EndSelect
Next

; Combine the results.
Local $sReturn = ""

For $i = 1 To $aClassID[0]
$sReturn &= $aClassID[$i] & @LF
Next

Return $sReturn
EndFunc ;==>_GetClasses
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; FileRead Alternative

Func _GetFile($sFile, $iFormat = 0)
Local $hFileOpen = FileOpen($sFile, $iFormat)
If $hFileOpen = -1 Then
Return SetError(1, 0, "")
EndIf
Local $sData = FileRead($hFileOpen)
FileClose($hFileOpen)
Return $sData
EndFunc ;==>_GetFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetTitle ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Get the title of your program.

ConsoleWrite(_GetTitle('Example') & @CRLF)
; The second parameter would normally be @ScriptDir & '\Uninstall.exe' for example, but for this demonstration I'm using the full path.
ConsoleWrite(_GetTitle('Example', @ScriptFullPath) & @CRLF)

Func _GetTitle($sProgramName, $sInstallPath = '')
Local $aOSArch[2] = ['', ' (64-bit)'], $aPortable[2] = [' (Portable)', '']
Return $sProgramName & $aOSArch[@AutoItX64] & $aPortable[FileExists($sInstallPath)]
EndFunc ;==>_GetTitle
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetXML ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Simple Way Of Parsing XML Data.

#include <Array.au3>

Global $aReturn, $sXMLData

$sXMLData = "<data>This is a Simple example of XML</data><data>This is a Simple example of XML and is the Second String.</data>"
$aReturn = _GetXML($sXMLData, "data")
_ArrayDisplay($aReturn, "_GetXML()")

Func _GetXML($sString, $sData)
Local $aError[2] = [1, $sString], $aReturn
$aReturn = StringRegExp('<' & $sData & '></' & $sData & '>' & $sString, '(?s)(?i)<' & $sData & '>(.*?)</' & $sData & '>', 3)
If @error Then
Return SetError(1, 0, $aError)
EndIf
$aReturn[0] = UBound($aReturn, 1) - 1
Return SetError(0, 0, $aReturn)
EndFunc ;==>_GetXML
</syntaxhighlight>

[[#top | ReturnToContents]]

== Include Source With Exe ==

{{Snippet Header
| AuthorURL = 54985-jlogan3o13
| AuthorName = JLogan3o13
}}

<syntaxhighlight lang="autoit">
;recover source .au3 file with /Extract switch
; The above code would be copied into the top of your script. The source location (C:\Test.au3 in my example) is the full path to your script file.
;Once compiled, if you run the script from the Run line with the /Extract switch, it will extact the original .au3 file into the Temp directory and will exit without actually executing the script.
If StringInStr($cmdlineRaw, "/Extract") Then
FileInstall("C:\Test.au3", @TempDir & "\Test.au3", 1)
Exit
EndIf
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsANSIFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

ConsoleWrite(_IsANSIFile(@ScriptFullPath) & @LF) ; Returns True.

Func _IsANSIFile($sFilePath)
Return FileGetEncoding($sFilePath) = $FO_READ
EndFunc ;==>_IsUnicodeFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsUnicodeFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

ConsoleWrite(_IsUnicodeFile(@ScriptFullPath) & @LF) ; Returns False.

Func _IsUnicodeFile($sFilePath)
Return FileGetEncoding($sFilePath) = $FO_UNICODE
EndFunc ;==>_IsUnicodeFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsAu3File ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_IsAu3File(@AutoItExe) & @CRLF)
ConsoleWrite(_IsAu3File(@ScriptFullPath) & @CRLF)

; Checks whether the filepath is an au3 file.
Func _IsAu3File($sFilePath)
Return StringTrimLeft($sFilePath, StringInStr($sFilePath, ".", 2, -1)) = "au3"
EndFunc ;==>_IsAu3File
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsDefault ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
If _IsDefault(Default) Then
MsgBox(0, "_IsDefault() - 1", "This was a Default variable.")
EndIf

If _IsDefault(-1) Then
MsgBox(0, "_IsDefault() - 2", "This was a Default variable.")
EndIf

If _IsDefault("Other") Then
MsgBox(0, "_IsDefault() - 3", "This was a Default variable.")
EndIf

Func _IsDefault($sDefault)
Return StringRegExp($sDefault, "(?-i)\s|Default|-1|0")
EndFunc ;==>_IsDefault
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsInTrial ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <Date.au3> ; Required for _DateDiff()

ConsoleWrite('Date trial started: ' & @YEAR & '/' & @MON & '/01' & @CRLF & _
'Today''s date: ' & @YEAR & '/' & @MON & '/' & @MDAY & @CRLF & _
'Trial period: 30 days' & @CRLF & _
'Is the trial period still valid: ' & _IsInTrial(@YEAR & '/' & @MON & '/01', 30) & @CRLF)

; Check if a trial period date is still valid.
Func _IsInTrial($sDateString, $iDays) ; Based on the idea found here: http://www.autoitscript.com/forum/topic/...ial-time/page__view__findpost_
Return (_DateDiff('D', $sDateString, @YEAR & '/' & @MON & '/' & @MDAY) < $iDays)
EndFunc ;==>_IsInTrial
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsVisible ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Check if the Notepad Window is visible.

Example()

Func Example()
; Run Notepad
Run("notepad.exe")

; Wait 10 seconds for the Notepad window to appear.
Local $hWnd = WinWait("[CLASS:Notepad]", "", 10)

; Check if the Notepad window is visible and display the appropriate message box.
If _IsVisible($hWnd) Then
MsgBox(4096, "", "Notepad is visible.")
Else
MsgBox(4096, "", "Notepad isn't visible.")
EndIf

; Close the Notepad window using the handle returned by WinWait.
WinClose($hWnd)
EndFunc ;==>Example

; Check if the window is visible.
Func _IsVisible($hWnd)
Return BitAND(WinGetState($hWnd), 2) = 2
EndFunc ;==>_IsVisible
</syntaxhighlight>

[[#top | ReturnToContents]]

== Open Help File to Desired Page ==

{{Snippet Header
| AuthorURL = 1967-garyfrost
| AuthorName = GaryFrost
}}

<syntaxhighlight lang="autoit">
; Open help file / Open a desired page

Global Const $sAutoItPath = RegRead("HKEY_LOCAL_MACHINE\SOFTWARE\AutoIt v3\AutoIt", "InstallDir")

Run(@WindowsDir & "\hh.exe " & $sAutoItPath & "\AutoIt3.chm::/html/functions/GUICtrlCreateUpdown.htm")
</syntaxhighlight>

[[#top | ReturnToContents]]

== _RunAU3 ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
_RunAU3("AU3_Example.txt", '"This is a commandline example!"')

Func _RunAU3($sFilePath, $sCommandLine = "", $sWorkingDir = "", $iShowFlag = @SW_SHOW, $iOptFlag = 0)
Return Run('"' & @AutoItExe & '" /AutoIt3ExecuteScript "' & $sFilePath & '" ' & $sCommandLine, $sWorkingDir, $iShowFlag, $iOptFlag)
EndFunc ;==>_RunAU3

Func _RunWaitAU3($sFilePath, $sCommandLine = "", $sWorkingDir = "", $iShowFlag = @SW_SHOW, $iOptFlag = 0)
Local $iPID
$iPID = RunWait('"' & @AutoItExe & '" /AutoIt3ExecuteScript "' & $sFilePath & '" ' & $sCommandLine, $sWorkingDir, $iShowFlag, $iOptFlag)
If @error Then
Return SetError(@error, 1, 0)
EndIf
Return $iPID
EndFunc ;==>_RunWaitAU3
</syntaxhighlight>

[[#top | ReturnToContents]]

== Run Any au3 File From Your Program ==

{{Snippet Header
| AuthorURL = 4920-valuater
| AuthorName = Valuater
}}

<syntaxhighlight lang="autoit">
; Run Any Au3 File From Your Program

Global Const $sFilePath = @ScriptDir & "\Test.au3"

If @Compiled Then
Global Const $sFileExe = FileGetShortName(@AutoItExe & ' /AutoIt3ExecuteScript "' & $sFilePath & '"')
Run($sFileExe)
Else
Global Const $sFileAu3 = FileGetShortName($sFilePath)
Run(@AutoItExe & " " & $sFileAu3, "", @SW_HIDE)
EndIf
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ScriptName ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_ScriptName() & @CRLF)

; Return the @ScriptName minus the .exe or .au3 extension.
Func _ScriptName()
Return StringLeft(@ScriptName, StringInStr(@ScriptName, '.', 2, -1) - 1)
EndFunc ;==>_ScriptName
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ScriptVersion ==

{{Snippet Header
| AuthorURL = 31149-milesahead
| AuthorName = MilesAhead
}}

<syntaxhighlight lang="autoit">
#NoTrayIcon

#Region ;**** Directives created by AutoIt3Wrapper_GUI ****
#AutoIt3Wrapper_UseUpx=n
#AutoIt3Wrapper_Res_Fileversion=1.2.3.4
#AutoIt3Wrapper_Res_LegalCopyright=2012 www.favessoft.com
#AutoIt3Wrapper_Res_Language=1033
#AutoIt3Wrapper_AU3Check_Parameters=-d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7
#EndRegion ;**** Directives created by AutoIt3Wrapper_GUI ****

Global $version = _ScriptVersion()

Global $msg = "ScriptVerDemo" & " " & $version & " Copyright (c) 2012 www.favessoft.com" & @CRLF & @CRLF

MsgBox(0x1040, "", $msg)

; return File Version string from compiled or .au3 script
; returns "" if no version info available
; Note: The .au3 script must contain #AutoItWrapper
; directives with file version or "" is returned.
Func _ScriptVersion(Const $Script = @ScriptFullPath)
If StringRight($Script,4) = ".exe" Then
Return FileGetVersion($Script)
Else
Local Const $scriptHandle = FileOpen($Script)
Local $ver
Local $found = False
Local $pos

If $scriptHandle <> -1 Then
Do
$ver = FileReadLine($scriptHandle)
$sPos = StringInStr($ver, "_Fileversion=")

If $sPos Then
$ver = StringMid($ver, $sPos + StringLen("_Fileversion="))
$found = True
ExitLoop
EndIf
Until StringLeft($ver, 1) <> "#"

FileClose($scriptHandle)
EndIf
EndIf

If Not $found Then $ver = ""

Return $ver
EndFunc ;==>_ScriptVersion
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SetFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; FileWrite Alternative

Func _SetFile(Const $sString, Const $sFile, Const $iOverwrite = 0)
Local Const $hFileOpen = FileOpen($sFile, $iOverwrite + 1)

FileWrite($hFileOpen, $sString)
FileClose($hFileOpen)

If @error Then
Return SetError(1, 0, $sString)
EndIf

Return $sString
EndFunc ;==>_SetFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ShowHelp ==

{{Snippet Header
| AuthorURL = 60350-chimaera
| AuthorName = Chimaera
}}

<syntaxhighlight lang="autoit">
HotKeySet("{F1}", "_ShowHelp")

Func _ShowHelp()
Return ShellExecute(@ProgramFilesDir & "\AutoIt3\AutoIt3Help.exe") ; change this to the location of your own helpfile.
EndFunc ;==>_ShowHelp
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SingletonPID ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Local $iSingleton = _SingletonPID('RandomName', 1)

If $iSingleton = 0 Then
MsgBox(4096, '', 'This is the first instance of the program running: ' & $iSingleton)
Else
MsgBox(4096, '', 'There is another instance running. This PID is: ' & $iSingleton)
EndIf

; #FUNCTION# ====================================================================================================================
; Name ..........: _SingletonPID
; Description ...: Enforce a design paradigm where only one instance of the script may be running.
; Syntax ........: _SingletonPID($sOccurenceName[, $iFlag = 0])
; Parameters ....: $sOccurenceName - String to identify the occurrence of the script.
; $iFlag - [optional] Optional parameters. Default is 0.
; 0 - Exit the script with the exit code -1 if another instance already exists.
; 1 - Return the PID of the main executable and without exiting the script too.
; Return values .: Success - 0 No other process is running.
; Failure - The PID of the main executable.
; Author ........: guinness with initial ideas by Valik for _Singleton & KaFu for _EnforceSingleInstance.
; Example .......: Yes
; ===============================================================================================================================
Func _SingletonPID(Const $sOccurenceName, Const $iFlag = 0)
Local $hHandle = WinGetHandle($sOccurenceName)

If @error Then
AutoItWinSetTitle($sOccurenceName)
$hHandle = WinGetHandle($sOccurenceName)
ControlSetText($hHandle, '', ControlGetHandle($hHandle, '', 'Edit1'), @AutoItPID)
Else
If BitAND($iFlag, 1) Then
Return Number(ControlGetText($hHandle, '', ControlGetHandle($hHandle, '', 'Edit1')))
Else
Exit -1
EndIf
EndIf

Return 0
EndFunc ;==>_SingletonPID
</syntaxhighlight>

[[#top | ReturnToContents]]

== _Sort ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

ConsoleWrite(_Sort("$sVariable" & @CRLF & "$iVariable" & @CRLF & "$tVariable" & @CRLF & "$pVariable"))

Func _Sort(Const $sSortList)
Local Const $iPID = Run("sort.exe", @SystemDir, @SW_HIDE, $STDIN_CHILD + $STDOUT_CHILD), $sOutput = ""

StdinWrite($iPID, $sSortList)
StdinWrite($iPID)

While 1
$sOutput &= StdoutRead($iPID)

If @error Then
ExitLoop
EndIf
WEnd

Return $sOutput
EndFunc ;==>_Sort
</syntaxhighlight>

[[#top | ReturnToContents]]

== Speak Object and Save to WAV File ==

{{Snippet Header
| AuthorURL = 52278-solidsnake26
| AuthorName = SolidSnake26
}}

<syntaxhighlight lang="autoit">
; Speak Object and save to wav file

_SpeakToWAV("AutoIt Snippets", @ScriptDir & "\SavedFile.wav")

Func _SpeakToWAV(Const $sText, Const $sFilePath)
Local $ObjVoice = ObjCreate("Sapi.SpVoice")

Local $ObjFile = ObjCreate("Sapi.SpFileStream.1")

$ObjVoice.Speak($sText)

$ObjFile.Open($sFilePath, 3)

$ObjVoice.AudioOutputStream = $ObjFile
EndFunc ;==>_SpeakToWAV
</syntaxhighlight>

[[#top | ReturnToContents]]

== _VariableSwap ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Global $sString_1 = 'This is string 1.'
Global $sString_2 = 'This is string 2.'

ConsoleWrite('$sString_1: ' & $sString_1 & @CRLF)
ConsoleWrite('$sString_2: ' & $sString_2 & @CRLF & @CRLF)

_VariableSwap($sString_1, $sString_2)

ConsoleWrite('$sString_1: ' & $sString_1 & @CRLF)
ConsoleWrite('$sString_2: ' & $sString_2 & @CRLF & @CRLF)

; Swap the contents of two variables.
Func _VariableSwap(ByRef $vVariable_1, ByRef $vVariable_2) ; Similar to _ArraySwap though not obvious to some this isn't limited to arrays.
Local Const $vTemp = $vVariable_1
$vVariable_1 = $vVariable_2
$vVariable_2 = $vTemp
EndFunc ;==>_VariableSwap
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinAPI_CharLower ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_WinAPI_CharLower("EXAMPLE") & @CRLF) ; Similar to StringLower.

; Convert characters to lowercase.
Func _WinAPI_CharLower($sString)
Local $aReturn = DllCall('user32.dll', 'wstr', 'CharLowerW', 'wstr', $sString)
If @error Then
Return SetError(1, 0, $sString)
EndIf
Return $aReturn[0]
EndFunc ;==>_WinAPI_CharLower
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinAPI_CharUpper ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_WinAPI_CharUpper("example") & @CRLF) ; Similar to StringUpper.

; Convert characters to uppercase.
Func _WinAPI_CharUpper($sString)
Local $aReturn = DllCall('user32.dll', 'wstr', 'CharUpperW', 'wstr', $sString)
If @error Then
Return SetError(1, 0, $sString)
EndIf
Return $aReturn[0]
EndFunc ;==>_WinAPI_CharUpper
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinAPI_PathFileExists ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; An API Alternative To FileExist.

ConsoleWrite(_WinAPI_PathFileExists(@ScriptFullPath) & @LF) ; File.
ConsoleWrite(_WinAPI_PathFileExists("C:\") & @LF) ; Drive.
ConsoleWrite(_WinAPI_PathFileExists(@ProgramFilesDir) & @LF) ; Directory.
ConsoleWrite(_WinAPI_PathFileExists("Z:\File.txt") & @LF) ; Shouldn't exist!

Func _WinAPI_PathFileExists($sFilePath)
Local $aReturn = DllCall('shlwapi.dll', 'int', 'PathFileExistsW', 'wstr', $sFilePath)
If @error Then
Return SetError(1, 0, 0)
EndIf
Return $aReturn[0]
EndFunc ;==>_WinAPI_PathFileExists
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinActiveByExe ==

{{Snippet Header
| AuthorURL = 4813-smoke-n
| AuthorName = SmOke_N
}}

<syntaxhighlight lang="autoit">
; Window Active/Activate by Exe, Open Notepad whilst script is running

While 1
If _WinActiveByExe('notepad.exe', False) Then MsgBox(64, 'info', 'true')
Sleep(100)
WEnd

Func _WinActiveByExe($sExe, $iActive = True);False to WinActivate, True to just see if it's active
If Not ProcessExists($sExe) Then Return SetError(1, 0, 0)
Local $aPL = ProcessList($sExe)
Local $aWL = WinList()
For $iCC = 1 To $aWL[0][0]
For $xCC = 1 To $aPL[0][0]
If $aWL[$iCC][0] <> '' And _
WinGetProcess($aWL[$iCC][1]) = $aPL[$xCC][1] And _
BitAND(WinGetState($aWL[$iCC][1]), 2) Then
If $iActive And WinActive($aWL[$iCC][1]) Then Return 1
If Not $iActive And Not WinActive($aWL[$iCC][1]) Then
WinActivate($aWL[$iCC][1])
Return 1
EndIf
EndIf
Next
Next
Return SetError(2, 0, 0)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WindowShake ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Shake a window left to right.

Example()

Func Example()
; Run Notepad
Run("notepad.exe")

; Wait 10 seconds for the Notepad window to appear.
Local $hWnd = WinWait("[CLASS:Notepad]", "", 10)

; Wait for 1 second.
Sleep(1000)

; Shake the Notepad window left to right.
_WindowShake($hWnd)

; Wait for 1 second.
Sleep(1000)

; Close the Notepad window using the handle returned by WinWait.
WinClose($hWnd)
EndFunc ;==>Example

Func _WindowShake($sTitle, $sText = '', $iDistance = 20)
Local $hWnd = WinGetHandle($sTitle, $sText)
Local $aWinGetPos = WinGetPos($hWnd)
If @error Then
Return SetError(1, 0, 0)
EndIf
Local $aArray[5] = [4, $aWinGetPos[0] + $iDistance, $aWinGetPos[0], $aWinGetPos[0] + $iDistance, $aWinGetPos[0]]

For $i = 1 To $aArray[0]
WinMove($hWnd, '', $aArray[$i], Default)
Sleep(100)
Next
EndFunc ;==>_WindowShake
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinGetDetails ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

Global $aArray = _WinGetDetails('[ACTIVE]') ; Returns the Window's title, PID, folder path filename.

If @error Then
Exit
EndIf

_ArrayDisplay($aArray)

Func _WinGetDetails($sTitle, $sText = '') ; Based on code of _WinGetPath by GaryFrost.
Local $aReturn[5] = [4, '-WinTitle', '-PID', '-FolderPath', '-FileName'], $aStringSplit

If StringLen($sText) > 0 Then
$aReturn[1] = WinGetTitle($sTitle, $sText)
Else
$aReturn[1] = WinGetTitle($sTitle)
EndIf
$aReturn[2] = WinGetProcess($aReturn[1])

Local $oWMIService = ObjGet('winmgmts:\\.\root\CIMV2')
Local $oItems = $oWMIService.ExecQuery('Select * From Win32_Process Where ProcessId = ' & $aReturn[2], 'WQL', 0x30)
If IsObj($oItems) Then
For $oItem In $oItems
If $oItem.ExecutablePath Then
$aStringSplit = StringSplit($oItem.ExecutablePath, '\')
$aReturn[3] = ''
For $A = 1 To $aStringSplit[0] - 1
$aReturn[3] &= $aStringSplit[$A] & '\'
Next
$aReturn[3] = StringTrimRight($aReturn[3], 1)
$aReturn[4] = $aStringSplit[$aStringSplit[0]]
Return $aReturn
EndIf
Next
EndIf
Return SetError(1, 0, $aReturn)
EndFunc ;==>_WinGetPath
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinGetNumeratedClassList ==

{{Snippet Header
| AuthorURL = 20477-mrcreator
| AuthorName = MrCreatoR
}}

<syntaxhighlight lang="autoit">
; Description: Retrieves the numerated classes from a window.

Func _WinGetNumeratedClassList($sTitle)
Local $sClassList = WinGetClassList($sTitle)
Local $aClassList = StringSplit($sClassList, @LF)
Local $sRetClassList = "", $sHold_List = "|"
Local $aiInHold, $iInHold

For $i = 1 To UBound($aClassList) - 1
If $aClassList[$i] = "" Then ContinueLoop

If StringRegExp($sHold_List, "\|" & $aClassList[$i] & "~(\d+)\|") Then
$aiInHold = StringRegExp($sHold_List, ".*\|" & $aClassList[$i] & "~(\d+)\|.*", 1)
$iInHold = Number($aiInHold[UBound($aiInHold)-1])

If $iInHold = 0 Then $iInHold += 1

$aClassList[$i] &= "~" & $iInHold + 1
$sHold_List &= $aClassList[$i] & "|"

$sRetClassList &= $aClassList[$i] & @LF
Else
$aClassList[$i] &= "~1"
$sHold_List &= $aClassList[$i] & "|"
$sRetClassList &= $aClassList[$i] & @LF
EndIf
Next

Return StringReplace(StringStripWS($sRetClassList, 3), "~", "")
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinGetHandleByPID ==

{{Snippet Header
| AuthorURL = 4813-smoke-n
| AuthorName = SmOke_N
}}

<syntaxhighlight lang="autoit">
; Get Window Handle by PID

#include <Array.au3>

Global $a1 = _WinGetHandleByPID(232)
Global $a2 = _WinGetHandleByPID("notepad.exe", -1)
Global $a3 = _WinGetHandleByPID("notepad.exe", 0)
Global $a4 = _WinGetHandleByPID("notepad.exe", 1)

_ArrayDisplay($a1, "1")
_ArrayDisplay($a2, "2")
_ArrayDisplay($a3, "3")
_ArrayDisplay($a4, "4")

;$nVisible = -1 "All (Visble or not)", $nVisible = 0 "Not Visible Only", $nVisible = 1 "Visible Only"
Func _WinGetHandleByPID($vProc, $nVisible = 1)
$vProc = ProcessExists($vProc);

If Not $vProc Then Return SetError(1, 0, 0)

Local $aWL = WinList()

Local $aTemp[UBound($aWL)][2]

Local $nAdd = 0

For $iCC = 1 To $aWL[0][0]
If $nVisible = -1 And WinGetProcess($aWL[$iCC][1]) = $vProc Then
$nAdd += 1
$aTemp[$nAdd][0] = $aWL[$iCC][0]
$aTemp[$nAdd][1] = $aWL[$iCC][1]
ElseIf $nVisible = 0 And WinGetProcess($aWL[$iCC][1]) = $vProc And _
BitAND(WinGetState($aWL[$iCC][1]), 2) = 0 Then
$nAdd += 1
$aTemp[$nAdd][0] = $aWL[$iCC][0]
$aTemp[$nAdd][1] = $aWL[$iCC][1]
ElseIf $nVisible > 0 And WinGetProcess($aWL[$iCC][1]) = $vProc And _
BitAND(WinGetState($aWL[$iCC][1]), 2) Then
$nAdd += 1
$aTemp[$nAdd][0] = $aWL[$iCC][0]
$aTemp[$nAdd][1] = $aWL[$iCC][1]
EndIf
Next

If $nAdd = 0 Then Return SetError(2, 0, 0) ; No windows found

ReDim $aTemp[$nAdd + 1][2]

$aTemp[0][0] = $nAdd

Return $aTemp
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

Snippets ( AutoIt )

2015-01-16T21:31:02Z

Guinness: /* _WinAPI_CharUpper */

__TOC__
[[category:Snippets]]

{{Snippet Credit Header}}

== AutoItWinShow ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

Example()

Func Example()
; Display AutoIt's Hidden Window. See AutoItWinGetTitle and AutoItWinSetTitle for more details.
AutoItWinShow()

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
EndSwitch
WEnd
EndFunc ;==>Example

; Display AutoIt's Hidden Window. Returns the handle of the window.
Func AutoItWinShow()
Local Const $hWnd = WinGetHandle(AutoItWinGetTitle()) ; Get the handle of the AutoIt Hidden Window by finding out the title of the AutoIt Hidden Window.
WinMove($hWnd, '', (@DesktopWidth / 2) - 250, (@DesktopHeight / 2) - 250, 500, 500) ; Move the AutoIt Hidden Window and re-size for a better view of the data that will be set.
WinSetState($hWnd, '', @SW_SHOW) ; Show the AutoIt Hidden Window, normally this is hidden, but in the interest of this example I'm displaying it.
Return $hWnd
EndFunc ;==>AutoItWinShow
</syntaxhighlight>

[[#top | ReturnToContents]]

== AutoItWinGetText ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Example()

Func Example()
; Display AutoIt's Hidden Window. See AutoItWinGetTitle and AutoItWinSetTitle for more details.
AutoItWinShow()

; Add a text string to AutoIt's Hidden Window. Compile to see the text in AutoIt's Hidden Window.
AutoItWinSetText('Welcome to AutoIt V' & @AutoItVersion & @CRLF)

; Add a text string to AutoIt's Hidden Window. Compile to see the text in AutoIt's Hidden Window.
AutoItWinSetText('Windows Type: ' & @OSType & @CRLF)

; Display the text stored in AutoIt's Hidden Window.
MsgBox(4096, '', AutoItWinGetText())

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
EndSwitch
WEnd
EndFunc ;==>Example

; Retrieve the text in AutoIt's Hidden Window.
Func AutoItWinGetText()
Local Const $hWnd = WinGetHandle(AutoItWinGetTitle()) ; Get the handle of the AutoIt Hidden Window by finding out the title of the AutoIt Hidden Window.
Return ControlGetText($hWnd, '', ControlGetHandle($hWnd, '', 'Edit1'))
EndFunc ;==>AutoItWinGetText

; Add text to AutoIt's Hidden Window.
Func AutoItWinSetText($sString)
Local Const $hWnd = WinGetHandle(AutoItWinGetTitle()) ; Get the handle of the AutoIt Hidden Window by finding out the title of the AutoIt Hidden Window.
Return ControlSetText($hWnd, "", ControlGetHandle($hWnd, "", 'Edit1'), ControlGetText($hWnd, '', ControlGetHandle($hWnd, '', 'Edit1')) & $sString)
EndFunc ;==>AutoItWinSetText

; Display AutoIt's Hidden Window. Returns the handle of the window.
Func AutoItWinShow()
Local Const $hWnd = WinGetHandle(AutoItWinGetTitle()) ; Get the handle of the AutoIt Hidden Window by finding out the title of the AutoIt Hidden Window.
WinMove($hWnd, '', (@DesktopWidth / 2) - 250, (@DesktopHeight / 2) - 250, 500, 500) ; Move the AutoIt Hidden Window and re-size for a better view of the data that will be set.
WinSetState($hWnd, '', @SW_SHOW) ; Show the AutoIt Hidden Window, normally this is hidden, but in the interest of this example I'm displaying it.
Return $hWnd
EndFunc ;==>AutoItWinShow
</syntaxhighlight>

[[#top | ReturnToContents]]

== _DockToWindow ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#include <WinAPI.au3>
#include <WindowsConstants.au3>

If (Not ProcessExists("SciTE.exe")) Then
Exit MsgBox(4096, '', "Please start SciTE.exe")
EndIf

Example()

Func Example()
; Create a GUI, similar to SciTE Jump's GUI.
Local Const $hGUI = GUICreate('', 215, 400, -1, -1, BitOR($GUI_SS_DEFAULT_GUI, $WS_MAXIMIZEBOX, $WS_SIZEBOX))

GUISetState(@SW_SHOWNORMAL, $hGUI)

; Dock the first window to left and adjust the width based on the width of the second GUI.
_DockToWindow(WinGetHandle("[CLASS:SciTEWindow]"), $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example

Func _DockToWindow(Const $hHandle_1, Const $hHandle_2)
; Retrieve the working area, this is minus the taskbar dimensions so slightly different to @DesktopHeight and @DesktopWidth which is the
; monitors height and width.
Local Const $SPI_GETWORKAREA = 48
Local Const $tWorkArea = DllStructCreate($tagRECT)
_WinAPI_SystemParametersInfo($SPI_GETWORKAREA, 0, DllStructGetPtr($tWorkArea))

; Retieve the position of the second GUI.
Local Const $aClientSize_2 = WinGetPos($hHandle_2)

; Set the state of the windows to 'Restore'.
WinSetState($hHandle_1, '', @SW_RESTORE)
WinSetState($hHandle_2, '', @SW_RESTORE)

; Move the first to the far left of the screen and adjust the width to the total screen width minus the width of the second GUI. e.g. 1366 - 215
WinMove($hHandle_1, '', DllStructGetData($tWorkArea, 'Left'), DllStructGetData($tWorkArea, 'Top'), DllStructGetData($tWorkArea, 'Right') - DllStructGetData($tWorkArea, 'Left') - $aClientSize_2[2], DllStructGetData($tWorkArea, 'Bottom') - DllStructGetData($tWorkArea, 'Top'))

; Move the second window to the far right in between the remaining space and adjust the height of the GUI.
WinMove($hHandle_2, '', DllStructGetData($tWorkArea, 'Right') - DllStructGetData($tWorkArea, 'Left') - $aClientSize_2[2], DllStructGetData($tWorkArea, 'Top'), $aClientSize_2[2], DllStructGetData($tWorkArea, 'Bottom') - DllStructGetData($tWorkArea, 'Top'))
EndFunc ;==>_DockToWindow
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FuncExists ==

{{Snippet Header
| AuthorURL = 52-geosoft
| AuthorName = GEOSoft
}}

<syntaxhighlight lang="autoit">
MsgBox(0, "TEST", "Function Exists = " & _FuncExists("_FuncExists", @ScriptFullPath))

Func _FuncExists($sFunc, $sPath)
If Not FileExists($sPath) Then Return SetError(1)
Local Const $sStr = FileRead($sPath)
Local Const $sRegEx = "(?i)(?m:^|\n)\s*Func\s+(" & $sFunc & ")\s*\("
Local Const $aRegEx = StringRegExp($sStr, $sRegEx, 1)
If IsArray($aRegEx) Then Return 1
Return 0
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FunctionSort ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Get the list of Functions in a script and sort by alphabetical order.

#include <Array.au3>
#include <String.au3>

Local $sFile = FileOpenDialog(@ScriptName, "Select an AutoIt file.", "Au3 (*.au3)")

If @error Then
Exit
EndIf
ClipPut(_FunctionSort($sFile))

Func _FunctionSort($sFilePath)
Local Const $sRead = FileRead($sFilePath)

Local $aReturn = StringRegExp("Func _Count()" & @CRLF & "EndFunc ;==>_Count" & $sRead, '(?s)(?i)Func(.*?)EndFunc', 3)

If @error Then
Return SetError(1, 0, 0)
EndIf

$aReturn[0] = UBound($aReturn, 1) - 1

_ArraySort($aReturn, 0, 1)

Local $sReturn

For $A = 1 To $aReturn[0]
$sReturn &= "Func" & $aReturn[$A] & "EndFunc" & @CRLF & @CRLF
Next

Return $sReturn
EndFunc ;==>_FunctionSort
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsBeta ==

{{Snippet Header
| AuthorURL = 10673-mlipok
| AuthorName = mLipok
}}

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

Example()

Func Example()
Local $aTest[10]
_ArrayUnique($aTest, 0, 5)
Local $iError = @error
ConsoleWrite('$iError = ' & $iError & @CRLF)
If _IsBeta() Then
If $iError = 3 Then
MsgBox($MB_SYSTEMMODAL, '@error', '3 - $iBase or $iCase contains an invalid value' & @CRLF & @AutoItVersion)
EndIf
Else
If $iError = 2 Then
MsgBox($MB_SYSTEMMODAL, '@error', '2 - $iBase or $iCase contains an invalid value' & @CRLF & @AutoItVersion)
EndIf
EndIf
EndFunc ;==>Example

Func _IsBeta()
Return Mod(StringSplit(@AutoItVersion, '.')[3], 2) == 1
EndFunc ;==>_IsBeta
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsButton ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <ButtonConstants.au3>
#include <Constants.au3>
#include <WinAPI.au3>

Example()

Func Example()
Local Const $hGUI = GUICreate('')
Local Const $iLabel = GUICtrlCreateButton('', 0, 0, 50, 50)
Local Const $iCheckbox = GUICtrlCreateCheckbox('', 0, 0, 100, 20) ; This is considered a 'Button' by _WinAPI_GetClassName too.

GUISetState(@SW_SHOWNORMAL, $hGUI)

MsgBox(4096, '', 'AutoIt Button ID: ' & _IsButton($iLabel) & @CRLF & _
'AutoIt Button Handle: ' & _IsButton(GUICtrlGetHandle($iLabel)) & @CRLF & _
'AutoIt Checkbox ID: ' & _IsButton($iCheckbox) & @CRLF & _
'AutoIt Checkbox Handle: ' & _IsButton(GUICtrlGetHandle($iCheckbox)) & @CRLF)

Return GUIDelete($hGUI)
EndFunc ;==>Example

; Check if a variable is referencing a Button control.
Func _IsButton($hWnd)
If IsHWnd($hWnd) = 0 Then
$hWnd = GUICtrlGetHandle($hWnd)
EndIf

Local Const $sClassName = _WinAPI_GetClassName($hWnd)

If $sClassName = 'Button' Then
Local Const $aStyle[5] = [4, $BS_CHECKBOX, $BS_AUTOCHECKBOX, $BS_RADIOBUTTON, $BS_AUTORADIOBUTTON]

Local Const $iLong = _WinAPI_GetWindowLong($hWnd, $GWL_STYLE)

For $i = 1 To $aStyle[0]
If BitAND($iLong, $aStyle[$i]) = $aStyle[$i] Then
Return False
EndIf
Next

Return True
EndIf

Return False
EndFunc ;==>_IsButton
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsControlID ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Check if a Control ID is a native AutoIt control.

#include <GUIListView.au3>
#include <WinAPI.au3>

Example()

Func Example()
Local Const $hGUI = GUICreate('')
Local Const $iControlID = GUICtrlCreateLabel('', 0, 0, 500, 500)
Local Const $hListView = _GUICtrlListView_Create($hGUI, 'Example', 0, 0, 500, 500)

GUISetState(@SW_SHOWNORMAL, $hGUI)

MsgBox(4096, '', 'AutoIt ControlID: ' & _IsControlID($iControlID) & @CRLF & _
'Random Number: ' & _IsControlID(Random(42, 99, 1)) & @CRLF & _
'AutoIt ControlID Handle: ' & _IsControlID(GUICtrlGetHandle($iControlID)) & @CRLF & _
'ListView UDF Handle: ' & _IsControlID($hListView) & @CRLF & _
'ListView UDF Handle: ' & _IsControlID(GUICtrlGetHandle($hListView)) & @CRLF)

_GUICtrlListView_Destroy($hListView)

Return GUIDelete($hGUI)
EndFunc ;==>Example

Func _IsControlID($iControlID)
If IsHWnd($iControlID) Then
$iControlID = _WinAPI_GetDlgCtrlID($iControlID)
EndIf

Return IsHWnd(GUICtrlGetHandle($iControlID)) = 1
EndFunc ;==>_IsControlID
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetAutoItIncludesFromSciTE ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

ConsoleWrite(_GetAutoItIncludesFromSciTE() & @CRLF)

; Retrieve the AutoIt includes path from the SciTE process.
Func _GetAutoItIncludesFromSciTE()
Local $sRelativePath = '..\Include'
Local Const $sWorkingDir = @WorkingDir
FileChangeDir(_WinAPI_PathRemoveFileSpec(_WinAPI_GetProcessFileName(ProcessExists('SciTE.exe'))))
$sRelativePath = _WinAPI_GetFullPathName($sRelativePath)
FileChangeDir($sWorkingDir)
Return _WinAPI_PathRemoveBackslash($sRelativePath)
EndFunc ;==>_GetAutoItIncludesFromSciTE
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetAutoItInstall ==

{{Snippet Header
|AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Get the AutoIt installation folder.

ConsoleWrite(_GetAutoItInstall() & @CRLF)

Func _GetAutoItInstall()
Return StringLeft(@AutoItExe, StringInStr(@AutoItExe, "\", 2, -1) - 1)
EndFunc ;==>_GetAutoItInstall
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetAutoItInstallEx ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_GetAutoItInstallEx() & @CRLF)

; Get the installation of AutoIt. An improved version of _GetAutoItInstall.
Func _GetAutoItInstallEx()
Local $aWow6432Node[2] = ['', 'Wow6432Node\'], $aFiles[4] = [3, @ProgramFilesDir, EnvGet("PROGRAMFILES"), EnvGet("PROGRAMFILES(X86)")]
Local $sFilePath = RegRead('HKEY_LOCAL_MACHINE\SOFTWARE\' & $aWow6432Node[@AutoItX64] & 'AutoIt v3\AutoIt\', 'InstallDir')
If @error Then
For $A = 1 To $aFiles[0]
$aFiles[$A] &= '\AutoIt'
If FileExists($aFiles[$A]) Then
Return $aFiles[$A]
EndIf
Next
Return SetError(1, 0, '')
Else
Return $sFilePath
EndIf
EndFunc ;==>_GetAutoItInstallEx
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetAutoItInstallFromSciTE ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_GetAutoItInstallFromSciTE() & @CRLF)

; Retrieve the AutoIt installation path from the SciTE process.
Func _GetAutoItInstallFromSciTE()
Local $sRelativePath = '..\', $sWorkingDir = @WorkingDir
FileChangeDir( _WinAPI_PathRemoveFileSpec(_WinAPI_GetProcessFileName(ProcessExists("SciTE.exe"))))
$sRelativePath = _WinAPI_GetFullPathName($sRelativePath)
FileChangeDir($sWorkingDir)
Return _WinAPI_PathRemoveBackslash($sRelativePath)
EndFunc ;==>_GetAutoItInstallFromSciTE
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetClasses ==

{{Snippet Header
| AuthorURL = 24-cyberslug
| AuthorName = CyberSlug
}}

<syntaxhighlight lang="autoit">
; Get ALL Controls Info

Example()

Func Example()
; Run Calculator
Run("calc.exe")

; Wait 10 seconds for the Calculator window to appear.
Local const $hWnd = WinWait("[CLASS:CalcFrame]", '', 10)

; Retrieve a list of all the controls in the Calculator window using the handle returned by WinWait.
MsgBox(4096, '', _GetClasses($hWnd))

; Close the Calculator window using the handle returned by WinWait.
WinClose($hWnd)
EndFunc ;==>Example

; This function returns an @LF-separated list of controls on the specified window.
Func _GetClasses($sTitle, $sText = '')
Local $iCount_Button = 0, $iCount_Edit = 0, $iCount_Static = 0
Local $aClasses = StringSplit(WinGetClassList($sTitle, $sText), @LF)
Local $aClassID[$aClasses[0] + 1] = [$aClasses[0]]

For $i = 1 To $aClasses[0]
Select
Case $aClasses[$i] = "Button"
$iCount_Button += 1
$aClassID[$i] = $aClasses[$i] & $iCount_Button
Case $aClasses[$i] = "Edit"
$iCount_Edit += 1
$aClassID[$i] = $aClasses[$i] & $iCount_Edit
$aClasses[$i] = "Input"
Case $aClasses[$i] = "Static"
$iCount_Static += 1
$aClassID[$i] = $aClasses[$i] & $iCount_Static
$aClasses[$i] = "Label"
Case Else
If $aClasses[$i] <> "" Then
$aClassID[$i] = $aClasses[$i] & "?"
EndIf
EndSelect
Next

; Combine the results.
Local $sReturn = ""

For $i = 1 To $aClassID[0]
$sReturn &= $aClassID[$i] & @LF
Next

Return $sReturn
EndFunc ;==>_GetClasses
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; FileRead Alternative

Func _GetFile($sFile, $iFormat = 0)
Local $hFileOpen = FileOpen($sFile, $iFormat)
If $hFileOpen = -1 Then
Return SetError(1, 0, "")
EndIf
Local $sData = FileRead($hFileOpen)
FileClose($hFileOpen)
Return $sData
EndFunc ;==>_GetFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetTitle ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Get the title of your program.

ConsoleWrite(_GetTitle('Example') & @CRLF)
; The second parameter would normally be @ScriptDir & '\Uninstall.exe' for example, but for this demonstration I'm using the full path.
ConsoleWrite(_GetTitle('Example', @ScriptFullPath) & @CRLF)

Func _GetTitle($sProgramName, $sInstallPath = '')
Local $aOSArch[2] = ['', ' (64-bit)'], $aPortable[2] = [' (Portable)', '']
Return $sProgramName & $aOSArch[@AutoItX64] & $aPortable[FileExists($sInstallPath)]
EndFunc ;==>_GetTitle
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetXML ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Simple Way Of Parsing XML Data.

#include <Array.au3>

Global $aReturn, $sXMLData

$sXMLData = "<data>This is a Simple example of XML</data><data>This is a Simple example of XML and is the Second String.</data>"
$aReturn = _GetXML($sXMLData, "data")
_ArrayDisplay($aReturn, "_GetXML()")

Func _GetXML($sString, $sData)
Local $aError[2] = [1, $sString], $aReturn
$aReturn = StringRegExp('<' & $sData & '></' & $sData & '>' & $sString, '(?s)(?i)<' & $sData & '>(.*?)</' & $sData & '>', 3)
If @error Then
Return SetError(1, 0, $aError)
EndIf
$aReturn[0] = UBound($aReturn, 1) - 1
Return SetError(0, 0, $aReturn)
EndFunc ;==>_GetXML
</syntaxhighlight>

[[#top | ReturnToContents]]

== Include Source With Exe ==

{{Snippet Header
| AuthorURL = 54985-jlogan3o13
| AuthorName = JLogan3o13
}}

<syntaxhighlight lang="autoit">
;recover source .au3 file with /Extract switch
; The above code would be copied into the top of your script. The source location (C:\Test.au3 in my example) is the full path to your script file.
;Once compiled, if you run the script from the Run line with the /Extract switch, it will extact the original .au3 file into the Temp directory and will exit without actually executing the script.
If StringInStr($cmdlineRaw, "/Extract") Then
FileInstall("C:\Test.au3", @TempDir & "\Test.au3", 1)
Exit
EndIf
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsANSIFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

ConsoleWrite(_IsANSIFile(@ScriptFullPath) & @LF) ; Returns True.

Func _IsANSIFile($sFilePath)
Return FileGetEncoding($sFilePath) = $FO_READ
EndFunc ;==>_IsUnicodeFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsUnicodeFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

ConsoleWrite(_IsUnicodeFile(@ScriptFullPath) & @LF) ; Returns False.

Func _IsUnicodeFile($sFilePath)
Return FileGetEncoding($sFilePath) = $FO_UNICODE
EndFunc ;==>_IsUnicodeFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsAu3File ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_IsAu3File(@AutoItExe) & @CRLF)
ConsoleWrite(_IsAu3File(@ScriptFullPath) & @CRLF)

; Checks whether the filepath is an au3 file.
Func _IsAu3File($sFilePath)
Return StringTrimLeft($sFilePath, StringInStr($sFilePath, ".", 2, -1)) = "au3"
EndFunc ;==>_IsAu3File
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsDefault ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
If _IsDefault(Default) Then
MsgBox(0, "_IsDefault() - 1", "This was a Default variable.")
EndIf

If _IsDefault(-1) Then
MsgBox(0, "_IsDefault() - 2", "This was a Default variable.")
EndIf

If _IsDefault("Other") Then
MsgBox(0, "_IsDefault() - 3", "This was a Default variable.")
EndIf

Func _IsDefault($sDefault)
Return StringRegExp($sDefault, "(?-i)\s|Default|-1|0")
EndFunc ;==>_IsDefault
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsInTrial ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <Date.au3> ; Required for _DateDiff()

ConsoleWrite('Date trial started: ' & @YEAR & '/' & @MON & '/01' & @CRLF & _
'Today''s date: ' & @YEAR & '/' & @MON & '/' & @MDAY & @CRLF & _
'Trial period: 30 days' & @CRLF & _
'Is the trial period still valid: ' & _IsInTrial(@YEAR & '/' & @MON & '/01', 30) & @CRLF)

; Check if a trial period date is still valid.
Func _IsInTrial($sDateString, $iDays) ; Based on the idea found here: http://www.autoitscript.com/forum/topic/...ial-time/page__view__findpost_
Return (_DateDiff('D', $sDateString, @YEAR & '/' & @MON & '/' & @MDAY) < $iDays)
EndFunc ;==>_IsInTrial
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsVisible ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Check if the Notepad Window is visible.

Example()

Func Example()
; Run Notepad
Run("notepad.exe")

; Wait 10 seconds for the Notepad window to appear.
Local $hWnd = WinWait("[CLASS:Notepad]", "", 10)

; Check if the Notepad window is visible and display the appropriate message box.
If _IsVisible($hWnd) Then
MsgBox(4096, "", "Notepad is visible.")
Else
MsgBox(4096, "", "Notepad isn't visible.")
EndIf

; Close the Notepad window using the handle returned by WinWait.
WinClose($hWnd)
EndFunc ;==>Example

; Check if the window is visible.
Func _IsVisible($hWnd)
Return BitAND(WinGetState($hWnd), 2) = 2
EndFunc ;==>_IsVisible
</syntaxhighlight>

[[#top | ReturnToContents]]

== Open Help File to Desired Page ==

{{Snippet Header
| AuthorURL = 1967-garyfrost
| AuthorName = GaryFrost
}}

<syntaxhighlight lang="autoit">
; Open help file / Open a desired page

Global Const $sAutoItPath = RegRead("HKEY_LOCAL_MACHINE\SOFTWARE\AutoIt v3\AutoIt", "InstallDir")

Run(@WindowsDir & "\hh.exe " & $sAutoItPath & "\AutoIt3.chm::/html/functions/GUICtrlCreateUpdown.htm")
</syntaxhighlight>

[[#top | ReturnToContents]]

== _RunAU3 ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
_RunAU3("AU3_Example.txt", '"This is a commandline example!"')

Func _RunAU3($sFilePath, $sCommandLine = "", $sWorkingDir = "", $iShowFlag = @SW_SHOW, $iOptFlag = 0)
Return Run('"' & @AutoItExe & '" /AutoIt3ExecuteScript "' & $sFilePath & '" ' & $sCommandLine, $sWorkingDir, $iShowFlag, $iOptFlag)
EndFunc ;==>_RunAU3

Func _RunWaitAU3($sFilePath, $sCommandLine = "", $sWorkingDir = "", $iShowFlag = @SW_SHOW, $iOptFlag = 0)
Local $iPID
$iPID = RunWait('"' & @AutoItExe & '" /AutoIt3ExecuteScript "' & $sFilePath & '" ' & $sCommandLine, $sWorkingDir, $iShowFlag, $iOptFlag)
If @error Then
Return SetError(@error, 1, 0)
EndIf
Return $iPID
EndFunc ;==>_RunWaitAU3
</syntaxhighlight>

[[#top | ReturnToContents]]

== Run Any au3 File From Your Program ==

{{Snippet Header
| AuthorURL = 4920-valuater
| AuthorName = Valuater
}}

<syntaxhighlight lang="autoit">
; Run Any Au3 File From Your Program

Global Const $sFilePath = @ScriptDir & "\Test.au3"

If @Compiled Then
Global Const $sFileExe = FileGetShortName(@AutoItExe & ' /AutoIt3ExecuteScript "' & $sFilePath & '"')
Run($sFileExe)
Else
Global Const $sFileAu3 = FileGetShortName($sFilePath)
Run(@AutoItExe & " " & $sFileAu3, "", @SW_HIDE)
EndIf
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ScriptName ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_ScriptName() & @CRLF)

; Return the @ScriptName minus the .exe or .au3 extension.
Func _ScriptName()
Return StringLeft(@ScriptName, StringInStr(@ScriptName, '.', 2, -1) - 1)
EndFunc ;==>_ScriptName
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ScriptVersion ==

{{Snippet Header
| AuthorURL = 31149-milesahead
| AuthorName = MilesAhead
}}

<syntaxhighlight lang="autoit">
#NoTrayIcon

#Region ;**** Directives created by AutoIt3Wrapper_GUI ****
#AutoIt3Wrapper_UseUpx=n
#AutoIt3Wrapper_Res_Fileversion=1.2.3.4
#AutoIt3Wrapper_Res_LegalCopyright=2012 www.favessoft.com
#AutoIt3Wrapper_Res_Language=1033
#AutoIt3Wrapper_AU3Check_Parameters=-d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7
#EndRegion ;**** Directives created by AutoIt3Wrapper_GUI ****

Global $version = _ScriptVersion()

Global $msg = "ScriptVerDemo" & " " & $version & " Copyright (c) 2012 www.favessoft.com" & @CRLF & @CRLF

MsgBox(0x1040, "", $msg)

; return File Version string from compiled or .au3 script
; returns "" if no version info available
; Note: The .au3 script must contain #AutoItWrapper
; directives with file version or "" is returned.
Func _ScriptVersion(Const $Script = @ScriptFullPath)
If StringRight($Script,4) = ".exe" Then
Return FileGetVersion($Script)
Else
Local Const $scriptHandle = FileOpen($Script)
Local $ver
Local $found = False
Local $pos

If $scriptHandle <> -1 Then
Do
$ver = FileReadLine($scriptHandle)
$sPos = StringInStr($ver, "_Fileversion=")

If $sPos Then
$ver = StringMid($ver, $sPos + StringLen("_Fileversion="))
$found = True
ExitLoop
EndIf
Until StringLeft($ver, 1) <> "#"

FileClose($scriptHandle)
EndIf
EndIf

If Not $found Then $ver = ""

Return $ver
EndFunc ;==>_ScriptVersion
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SetFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; FileWrite Alternative

Func _SetFile(Const $sString, Const $sFile, Const $iOverwrite = 0)
Local Const $hFileOpen = FileOpen($sFile, $iOverwrite + 1)

FileWrite($hFileOpen, $sString)
FileClose($hFileOpen)

If @error Then
Return SetError(1, 0, $sString)
EndIf

Return $sString
EndFunc ;==>_SetFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ShowHelp ==

{{Snippet Header
| AuthorURL = 60350-chimaera
| AuthorName = Chimaera
}}

<syntaxhighlight lang="autoit">
HotKeySet("{F1}", "_ShowHelp")

Func _ShowHelp()
Return ShellExecute(@ProgramFilesDir & "\AutoIt3\AutoIt3Help.exe") ; change this to the location of your own helpfile.
EndFunc ;==>_ShowHelp
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SingletonPID ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Local $iSingleton = _SingletonPID('RandomName', 1)

If $iSingleton = 0 Then
MsgBox(4096, '', 'This is the first instance of the program running: ' & $iSingleton)
Else
MsgBox(4096, '', 'There is another instance running. This PID is: ' & $iSingleton)
EndIf

; #FUNCTION# ====================================================================================================================
; Name ..........: _SingletonPID
; Description ...: Enforce a design paradigm where only one instance of the script may be running.
; Syntax ........: _SingletonPID($sOccurenceName[, $iFlag = 0])
; Parameters ....: $sOccurenceName - String to identify the occurrence of the script.
; $iFlag - [optional] Optional parameters. Default is 0.
; 0 - Exit the script with the exit code -1 if another instance already exists.
; 1 - Return the PID of the main executable and without exiting the script too.
; Return values .: Success - 0 No other process is running.
; Failure - The PID of the main executable.
; Author ........: guinness with initial ideas by Valik for _Singleton & KaFu for _EnforceSingleInstance.
; Example .......: Yes
; ===============================================================================================================================
Func _SingletonPID(Const $sOccurenceName, Const $iFlag = 0)
Local $hHandle = WinGetHandle($sOccurenceName)

If @error Then
AutoItWinSetTitle($sOccurenceName)
$hHandle = WinGetHandle($sOccurenceName)
ControlSetText($hHandle, '', ControlGetHandle($hHandle, '', 'Edit1'), @AutoItPID)
Else
If BitAND($iFlag, 1) Then
Return Number(ControlGetText($hHandle, '', ControlGetHandle($hHandle, '', 'Edit1')))
Else
Exit -1
EndIf
EndIf

Return 0
EndFunc ;==>_SingletonPID
</syntaxhighlight>

[[#top | ReturnToContents]]

== _Sort ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

ConsoleWrite(_Sort("$sVariable" & @CRLF & "$iVariable" & @CRLF & "$tVariable" & @CRLF & "$pVariable"))

Func _Sort(Const $sSortList)
Local Const $iPID = Run("sort.exe", @SystemDir, @SW_HIDE, $STDIN_CHILD + $STDOUT_CHILD), $sOutput = ""

StdinWrite($iPID, $sSortList)
StdinWrite($iPID)

While 1
$sOutput &= StdoutRead($iPID)

If @error Then
ExitLoop
EndIf
WEnd

Return $sOutput
EndFunc ;==>_Sort
</syntaxhighlight>

[[#top | ReturnToContents]]

== Speak Object and Save to WAV File ==

{{Snippet Header
| AuthorURL = 52278-solidsnake26
| AuthorName = SolidSnake26
}}

<syntaxhighlight lang="autoit">
; Speak Object and save to wav file

_SpeakToWAV("AutoIt Snippets", @ScriptDir & "\SavedFile.wav")

Func _SpeakToWAV(Const $sText, Const $sFilePath)
Local $ObjVoice = ObjCreate("Sapi.SpVoice")

Local $ObjFile = ObjCreate("Sapi.SpFileStream.1")

$ObjVoice.Speak($sText)

$ObjFile.Open($sFilePath, 3)

$ObjVoice.AudioOutputStream = $ObjFile
EndFunc ;==>_SpeakToWAV
</syntaxhighlight>

[[#top | ReturnToContents]]

== _VariableSwap ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Global $sString_1 = 'This is string 1.'
Global $sString_2 = 'This is string 2.'

ConsoleWrite('$sString_1: ' & $sString_1 & @CRLF)
ConsoleWrite('$sString_2: ' & $sString_2 & @CRLF & @CRLF)

_VariableSwap($sString_1, $sString_2)

ConsoleWrite('$sString_1: ' & $sString_1 & @CRLF)
ConsoleWrite('$sString_2: ' & $sString_2 & @CRLF & @CRLF)

; Swap the contents of two variables.
Func _VariableSwap(ByRef $vVariable_1, ByRef $vVariable_2) ; Similar to _ArraySwap though not obvious to some this isn't limited to arrays.
Local Const $vTemp = $vVariable_1
$vVariable_1 = $vVariable_2
$vVariable_2 = $vTemp
EndFunc ;==>_VariableSwap
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinAPI_CharLower ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
;Convert characters to upper or lower case

ConsoleWrite(_WinAPI_CharLower("EXAMPLE") & @CRLF) ; Similar to StringLower.

; Convert characters to lowercase.
Func _WinAPI_CharLower($sString)
Local $aReturn = DllCall('user32.dll', 'wstr', 'CharLowerW', 'wstr', $sString)
If @error Then
Return SetError(1, 0, $sString)
EndIf
Return $aReturn[0]
EndFunc ;==>_WinAPI_CharLower
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinAPI_CharUpper ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_WinAPI_CharUpper("example") & @CRLF) ; Similar to StringUpper.

; Convert characters to uppercase.
Func _WinAPI_CharUpper($sString)
Local $aReturn = DllCall('user32.dll', 'wstr', 'CharUpperW', 'wstr', $sString)
If @error Then
Return SetError(1, 0, $sString)
EndIf
Return $aReturn[0]
EndFunc ;==>_WinAPI_CharUpper
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinAPI_PathFileExists ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; An API Alternative To FileExist.

ConsoleWrite(_WinAPI_PathFileExists(@ScriptFullPath) & @LF) ; File.
ConsoleWrite(_WinAPI_PathFileExists("C:\") & @LF) ; Drive.
ConsoleWrite(_WinAPI_PathFileExists(@ProgramFilesDir) & @LF) ; Directory.
ConsoleWrite(_WinAPI_PathFileExists("Z:\File.txt") & @LF) ; Shouldn't exist!

Func _WinAPI_PathFileExists($sFilePath)
Local $aReturn = DllCall('shlwapi.dll', 'int', 'PathFileExistsW', 'wstr', $sFilePath)
If @error Then
Return SetError(1, 0, 0)
EndIf
Return $aReturn[0]
EndFunc ;==>_WinAPI_PathFileExists
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinActiveByExe ==

{{Snippet Header
| AuthorURL = 4813-smoke-n
| AuthorName = SmOke_N
}}

<syntaxhighlight lang="autoit">
; Window Active/Activate by Exe, Open Notepad whilst script is running

While 1
If _WinActiveByExe('notepad.exe', False) Then MsgBox(64, 'info', 'true')
Sleep(100)
WEnd

Func _WinActiveByExe($sExe, $iActive = True);False to WinActivate, True to just see if it's active
If Not ProcessExists($sExe) Then Return SetError(1, 0, 0)
Local $aPL = ProcessList($sExe)
Local $aWL = WinList()
For $iCC = 1 To $aWL[0][0]
For $xCC = 1 To $aPL[0][0]
If $aWL[$iCC][0] <> '' And _
WinGetProcess($aWL[$iCC][1]) = $aPL[$xCC][1] And _
BitAND(WinGetState($aWL[$iCC][1]), 2) Then
If $iActive And WinActive($aWL[$iCC][1]) Then Return 1
If Not $iActive And Not WinActive($aWL[$iCC][1]) Then
WinActivate($aWL[$iCC][1])
Return 1
EndIf
EndIf
Next
Next
Return SetError(2, 0, 0)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WindowShake ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Shake a window left to right.

Example()

Func Example()
; Run Notepad
Run("notepad.exe")

; Wait 10 seconds for the Notepad window to appear.
Local $hWnd = WinWait("[CLASS:Notepad]", "", 10)

; Wait for 1 second.
Sleep(1000)

; Shake the Notepad window left to right.
_WindowShake($hWnd)

; Wait for 1 second.
Sleep(1000)

; Close the Notepad window using the handle returned by WinWait.
WinClose($hWnd)
EndFunc ;==>Example

Func _WindowShake($sTitle, $sText = '', $iDistance = 20)
Local $hWnd = WinGetHandle($sTitle, $sText)
Local $aWinGetPos = WinGetPos($hWnd)
If @error Then
Return SetError(1, 0, 0)
EndIf
Local $aArray[5] = [4, $aWinGetPos[0] + $iDistance, $aWinGetPos[0], $aWinGetPos[0] + $iDistance, $aWinGetPos[0]]

For $i = 1 To $aArray[0]
WinMove($hWnd, '', $aArray[$i], Default)
Sleep(100)
Next
EndFunc ;==>_WindowShake
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinGetDetails ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

Global $aArray = _WinGetDetails('[ACTIVE]') ; Returns the Window's title, PID, folder path filename.

If @error Then
Exit
EndIf

_ArrayDisplay($aArray)

Func _WinGetDetails($sTitle, $sText = '') ; Based on code of _WinGetPath by GaryFrost.
Local $aReturn[5] = [4, '-WinTitle', '-PID', '-FolderPath', '-FileName'], $aStringSplit

If StringLen($sText) > 0 Then
$aReturn[1] = WinGetTitle($sTitle, $sText)
Else
$aReturn[1] = WinGetTitle($sTitle)
EndIf
$aReturn[2] = WinGetProcess($aReturn[1])

Local $oWMIService = ObjGet('winmgmts:\\.\root\CIMV2')
Local $oItems = $oWMIService.ExecQuery('Select * From Win32_Process Where ProcessId = ' & $aReturn[2], 'WQL', 0x30)
If IsObj($oItems) Then
For $oItem In $oItems
If $oItem.ExecutablePath Then
$aStringSplit = StringSplit($oItem.ExecutablePath, '\')
$aReturn[3] = ''
For $A = 1 To $aStringSplit[0] - 1
$aReturn[3] &= $aStringSplit[$A] & '\'
Next
$aReturn[3] = StringTrimRight($aReturn[3], 1)
$aReturn[4] = $aStringSplit[$aStringSplit[0]]
Return $aReturn
EndIf
Next
EndIf
Return SetError(1, 0, $aReturn)
EndFunc ;==>_WinGetPath
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinGetNumeratedClassList ==

{{Snippet Header
| AuthorURL = 20477-mrcreator
| AuthorName = MrCreatoR
}}

<syntaxhighlight lang="autoit">
; Description: Retrieves the numerated classes from a window.

Func _WinGetNumeratedClassList($sTitle)
Local $sClassList = WinGetClassList($sTitle)
Local $aClassList = StringSplit($sClassList, @LF)
Local $sRetClassList = "", $sHold_List = "|"
Local $aiInHold, $iInHold

For $i = 1 To UBound($aClassList) - 1
If $aClassList[$i] = "" Then ContinueLoop

If StringRegExp($sHold_List, "\|" & $aClassList[$i] & "~(\d+)\|") Then
$aiInHold = StringRegExp($sHold_List, ".*\|" & $aClassList[$i] & "~(\d+)\|.*", 1)
$iInHold = Number($aiInHold[UBound($aiInHold)-1])

If $iInHold = 0 Then $iInHold += 1

$aClassList[$i] &= "~" & $iInHold + 1
$sHold_List &= $aClassList[$i] & "|"

$sRetClassList &= $aClassList[$i] & @LF
Else
$aClassList[$i] &= "~1"
$sHold_List &= $aClassList[$i] & "|"
$sRetClassList &= $aClassList[$i] & @LF
EndIf
Next

Return StringReplace(StringStripWS($sRetClassList, 3), "~", "")
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WinGetHandleByPID ==

{{Snippet Header
| AuthorURL = 4813-smoke-n
| AuthorName = SmOke_N
}}

<syntaxhighlight lang="autoit">
; Get Window Handle by PID

#include <Array.au3>

Global $a1 = _WinGetHandleByPID(232)
Global $a2 = _WinGetHandleByPID("notepad.exe", -1)
Global $a3 = _WinGetHandleByPID("notepad.exe", 0)
Global $a4 = _WinGetHandleByPID("notepad.exe", 1)

_ArrayDisplay($a1, "1")
_ArrayDisplay($a2, "2")
_ArrayDisplay($a3, "3")
_ArrayDisplay($a4, "4")

;$nVisible = -1 "All (Visble or not)", $nVisible = 0 "Not Visible Only", $nVisible = 1 "Visible Only"
Func _WinGetHandleByPID($vProc, $nVisible = 1)
$vProc = ProcessExists($vProc);

If Not $vProc Then Return SetError(1, 0, 0)

Local $aWL = WinList()

Local $aTemp[UBound($aWL)][2]

Local $nAdd = 0

For $iCC = 1 To $aWL[0][0]
If $nVisible = -1 And WinGetProcess($aWL[$iCC][1]) = $vProc Then
$nAdd += 1
$aTemp[$nAdd][0] = $aWL[$iCC][0]
$aTemp[$nAdd][1] = $aWL[$iCC][1]
ElseIf $nVisible = 0 And WinGetProcess($aWL[$iCC][1]) = $vProc And _
BitAND(WinGetState($aWL[$iCC][1]), 2) = 0 Then
$nAdd += 1
$aTemp[$nAdd][0] = $aWL[$iCC][0]
$aTemp[$nAdd][1] = $aWL[$iCC][1]
ElseIf $nVisible > 0 And WinGetProcess($aWL[$iCC][1]) = $vProc And _
BitAND(WinGetState($aWL[$iCC][1]), 2) Then
$nAdd += 1
$aTemp[$nAdd][0] = $aWL[$iCC][0]
$aTemp[$nAdd][1] = $aWL[$iCC][1]
EndIf
Next

If $nAdd = 0 Then Return SetError(2, 0, 0) ; No windows found

ReDim $aTemp[$nAdd + 1][2]

$aTemp[0][0] = $nAdd

Return $aTemp
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

Best coding practices

2014-06-27T09:37:43Z

Guinness: /* Names of Variables */

Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.

A few notes:
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.

__TOC__

== Names of Variables ==
The [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is adopted however it's simplified and regroup all the types of numbers in one type.

Variables are initialized with the "default" value (or the most efficient value) of their type. See below in the table for specific value.

{| class="wikitable"
|-
! prefix !! covering type !! initialization
|-
| i || Integer || $i = 0
|-
| f || Floating point || $f = 0.0
|-
| n || General number (no preference) || $n = 0
|-
| a || Arrays || $a = 0 or $a[0]
|-
| s || Strings (chars included) || $s = "" or $s = Null
|-
| b || Booleans || $b = False or $b = True
|-
| d || Binaries || $d = Binary("")
|-
| id || An AutoIt controlid || $id = 0
|-
| h || Handles (and GUI handles) || $h = 0
|-
| fu || Functions || $fu = Null
|-
| p || Pointers || $p = 0
|-
| tag || Structures definition || $tag = 0
|-
| t || Structures || $t = 0
|-
| o || Objects || $o = 0 or $o = Null
|-
| v || Variant || $v = 0 or $v = "" (or $v = Null)
|-
| e || Enumerations || N/A
|-
| k || Keywords || $k = Default
|}

The variables are named following this schema:
{| class="wikitable"
|-
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| i || f || MyFlag
|}

Example:
<syntaxhighlight lang="autoit">
; Assign a Local variable the number 5.
Local $iSomeVar = 5

; Assign a Local variable the number 1.
Local $ifMyFlag = 1

; Assign a Local variable an array of numbers.
Local $aiArray = 0

; Re-declare the array to size and fill it.
Local $aiArray[3] = [0, 0.25, 3 / 4]
</syntaxhighlight>

Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.

Example:
<syntaxhighlight lang="autoit">
;Bad
Local $iSomeVar1, $aiArray = 0
Local $iSomeVar2 = 5

;Good
Local $iSomeVar1 = 0, $iSomeVar2 = 5
Local $aiArray = 0
</syntaxhighlight>
You can still categorize your variables and declare for example the $iSomeVar2 on another line.

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

Local $vValue ; Bad, this is initially blank.
Local $vVal = 0 ; Good

MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)

; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt
; is a little less forgiving in that it initialises the variable as being blank and doesn't throw any error, unlike some moder C++ compilers.
</syntaxhighlight>

== Scopes of Variables ==
To make the transition, the variables are also 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 $_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 $_iSomeVar2.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_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 $_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 $_iVar1.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 $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, "", $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, $vVariableThatIsGlobal) ; The Global variable ($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 $vVariableThatIsGlobal = ""

For $i = 1 To 10
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.
Next
Return $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 $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 efficent 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">
;Bad
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes.

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

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>

UDF-spec

2014-06-27T09:32:54Z

Guinness: /* Basic Requirements */

[[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.
* Not use any magic numbers. Ever. None. At all. No excuses.

== 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.
* Not make any permanent changes to the users computer. For example, if demonstrating a File function, be sure to delete the file after it has been used. The same applies for any function that makes a change to the environment: the changes MUST be undone.

Always remember, the readability of code in an example is MORE important than the readability of code inside the UDF itself.

Examples are stored in script 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>.

<syntaxhighlight lang="autoit">#include <Constants.au3>
#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($MB_SYSTEMMODAL, "Testing", "Button 2 was pressed") ; Will demonstrate Button 2 being pressed
EndSelect
WEnd
GUIDelete($hGUI)
EndFunc ;==>Example</syntaxhighlight>

=== Multiple Examples ===
The helpfile now supports multiple examples per function. In order to maintain backwards compatibility with any other tools that use examples, the first file is still named <code><FUNCTION>.au3</code>, but any additional examples are named <code><FUNCTION>[n].au3</code> where n is an integer counter starting at 2.

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

Best coding practices

2014-06-27T09:31:28Z

Guinness: /* Scopes of Variables */

Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.

A few notes:
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.

__TOC__

== Names of Variables ==
The [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is adopted however it's simplified and regroup all the types of numbers in one type.

Variables are initialized with the "default" value (or the most efficient value) of their type. See below in the table for specific value.

{| class="wikitable"
|-
! prefix !! covering type !! initialization
|-
| i || Integer || $i = 0
|-
| f || Floating point || $f = 0.0
|-
| n || General number (no preference) || $n = 0
|-
| a || Arrays || $a = 0 or $a[0]
|-
| s || Strings (chars included) || $s = "" or $s = Null
|-
| b || Booleans || $b = False or $b = True
|-
| d || Binaries || $d = Binary("")
|-
| id || An AutoIt controlid || $id = 0
|-
| h || Handles (and GUI handles) || $h = 0
|-
| fu || Functions || $fu = Null
|-
| p || Pointers || $p = 0
|-
| tag || Structures definition || $tag = 0
|-
| t || Structures || $t = 0
|-
| o || Objects || $o = 0
|-
| v || Variant || $v = 0 or $v = "" (or $v = Null)
|-
| e || Enumerations || N/A
|-
| k || Keywords || $k = Default
|}

The variables are named following this schema:
{| class="wikitable"
|-
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| i || f || MyFlag
|}

Example:
<syntaxhighlight lang="autoit">
; Assign a Local variable the number 5.
Local $iSomeVar = 5

; Assign a Local variable the number 1.
Local $ifMyFlag = 1

; Assign a Local variable an array of numbers.
Local $aiArray = 0

; Re-declare the array to size and fill it.
Local $aiArray[3] = [0, 0.25, 3 / 4]
</syntaxhighlight>

Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.

Example:
<syntaxhighlight lang="autoit">
;Bad
Local $iSomeVar1, $aiArray = 0
Local $iSomeVar2 = 5

;Good
Local $iSomeVar1 = 0, $iSomeVar2 = 5
Local $aiArray = 0
</syntaxhighlight>
You can still categorize your variables and declare for example the $iSomeVar2 on another line.

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

Local $vValue ; Bad, this is initially blank.
Local $vVal = 0 ; Good

MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)

; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt
; is a little less forgiving in that it initialises the variable as being blank and doesn't throw any error, unlike some moder C++ compilers.
</syntaxhighlight>

== Scopes of Variables ==
To make the transition, the variables are also 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 $_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 $_iSomeVar2.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_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 $_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 $_iVar1.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 $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, "", $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, $vVariableThatIsGlobal) ; The Global variable ($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 $vVariableThatIsGlobal = ""

For $i = 1 To 10
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.
Next
Return $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 $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 efficent 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">
;Bad
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes.

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

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

2014-06-27T08:24:59Z

Guinness:

Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.

A few notes:
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.

__TOC__

== Names of Variables ==
The [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is adopted however it's simplified and regroup all the types of numbers in one type.

Variables are initialized with the "default" value (or the most efficient value) of their type. See below in the table for specific value.

{| class="wikitable"
|-
! prefix !! covering type !! initialization
|-
| i || Integer || $i = 0
|-
| f || Floating point || $f = 0.0
|-
| n || General number (no preference) || $n = 0
|-
| a || Arrays || $a = 0 or $a[0]
|-
| s || Strings (chars included) || $s = "" or $s = Null
|-
| b || Booleans || $b = False or $b = True
|-
| d || Binaries || $d = Binary("")
|-
| id || An AutoIt controlid || $id = 0
|-
| h || Handles (and GUI handles) || $h = 0
|-
| fu || Functions || $fu = Null
|-
| p || Pointers || $p = 0
|-
| tag || Structures definition || $tag = 0
|-
| t || Structures || $t = 0
|-
| o || Objects || $o = 0
|-
| v || Variant || $v = 0 or $v = "" (or $v = Null)
|-
| e || Enumerations || N/A
|-
| k || Keywords || $k = Default
|}

The variables are named following this schema:
{| class="wikitable"
|-
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| i || f || MyFlag
|}

Example:
<syntaxhighlight lang="autoit">
; Assign a Local variable the number 5.
Local $iSomeVar = 5

; Assign a Local variable the number 1.
Local $ifMyFlag = 1

; Assign a Local variable an array of numbers.
Local $aiArray = 0

; Re-declare the array to size and fill it.
Local $aiArray[3] = [0, 0.25, 3 / 4]
</syntaxhighlight>

Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.

Example:
<syntaxhighlight lang="autoit">
;Bad
Local $iSomeVar1, $aiArray = 0
Local $iSomeVar2 = 5

;Good
Local $iSomeVar1 = 0, $iSomeVar2 = 5
Local $aiArray = 0
</syntaxhighlight>
You can still categorize your variables and declare for example the $iSomeVar2 on another line.

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

Local $vValue ; Bad, this is initially blank.
Local $vVal = 0 ; Good

MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)

; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt
; is a little less forgiving in that it initialises the variable as being blank and doesn't throw any error, unlike some moder C++ compilers.
</syntaxhighlight>

== Scopes of Variables ==
To make the transition, the variables are also named according to their scope.
{| class="wikitable"
|-
! Global UDF variable !! Global variable !! Local variable
|-
| $__iSomeVar or $g__iSomeVar || $_iSomeVar or $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 $_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 $_iSomeVar2.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_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 $_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 $_iVar1.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 $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, "", $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, $vVariableThatIsGlobal) ; The Global variable ($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 $vVariableThatIsGlobal = ""

For $i = 1 To 10
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.
Next
Return $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 $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 efficent 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">
;Bad
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes.

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

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

2014-06-27T08:24:18Z

Guinness: /* Scopes of Variables */

Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.

A few notes:
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.

__TOC__

== Names of Variables ==
The [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is adopted however it's simplified and regroup all the types of numbers in one type.

Variables are initialized with the "default" value (or the most efficient value) of their type. See below in the table for specific value.

{| class="wikitable"
|-
! prefix !! covering type !! initialization
|-
| i || Integer || $i = 0
|-
| f || Floating point || $f = 0.0
|-
| n || General number (no preference) || $n = 0
|-
| a || Arrays || $a = 0 or $a[0]
|-
| s || Strings (chars included) || $s = "" or $s = Null
|-
| b || Booleans || $b = False or $b = True
|-
| d || Binaries || $d = Binary("")
|-
| id || An AutoIt controlid || $id = 0
|-
| h || Handles (and GUI handles) || $h = 0
|-
| fu || Functions || $fu = Null
|-
| p || Pointers || $p = 0
|-
| tag || Structures definition || $tag = 0
|-
| t || Structures || $t = 0
|-
| o || Objects || $o = 0
|-
| v || Variant || $v = 0 or $v = "" (or $v = Null)
|-
| e || Enumerations || N/A
|-
| k || Keywords || $k = Default
|}

The variables are named following this schema:
{| class="wikitable"
|-
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| i || f || MyFlag
|}

Example:
<syntaxhighlight lang="autoit">
; Assign a Local variable the number 5.
Local $iSomeVar = 5

; Assign a Local variable the number 1.
Local $ifMyFlag = 1

; Assign a Local variable an array of numbers.
Local $aiArray = 0

; Re-declare the array to size and fill it.
Local $aiArray[3] = [0, 0.25, 3 / 4]
</syntaxhighlight>

Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.

Example:
<syntaxhighlight lang="autoit">
;Bad
Local $iSomeVar1, $aiArray = 0
Local $iSomeVar2 = 5

;Good
Local $iSomeVar1 = 0, $iSomeVar2 = 5
Local $aiArray = 0
</syntaxhighlight>
You can still categorize your variables and declare for example the $iSomeVar2 on another line.

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

Local $vValue ; Bad, this is initially blank.
Local $vVal = 0 ; Good

MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)

; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt
; is a little less forgiving in that it initialises the variable as being blank and doesn't throw any error, unlike some moder C++ compilers.
</syntaxhighlight>

== Scopes of Variables ==
To make the transition, the variables are also named according to their scope.
{| class="wikitable"
|-
! Global UDF variable !! Global variable !! Local variable
|-
| $__iSomeVar or $g__iSomeVar || $_iSomeVar or $g_iSomeVar || $iSomeVar
|}
With this method, you will avoid non wanted re-assignments.

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

; Assign a Global variable the number 0.
Global $iSomeVar1 = 0
; Assign a Global variable the number 5.
Global $_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 $_iSomeVar2.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_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 $_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 $_iVar1.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 $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, "", $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, $vVariableThatIsGlobal) ; The Global variable ($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 $vVariableThatIsGlobal = ""

For $i = 1 To 10
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.
Next
Return $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 $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 efficent 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">
;Bad
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes.

;Good
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 <MessageBoxConstants.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.

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

2014-06-27T08:23:14Z

Guinness: /* Names of Variables */

Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.

A few notes:
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.

__TOC__

== Names of Variables ==
The [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is adopted however it's simplified and regroup all the types of numbers in one type.

Variables are initialized with the "default" value (or the most efficient value) of their type. See below in the table for specific value.

{| class="wikitable"
|-
! prefix !! covering type !! initialization
|-
| i || Integer || $i = 0
|-
| f || Floating point || $f = 0.0
|-
| n || General number (no preference) || $n = 0
|-
| a || Arrays || $a = 0 or $a[0]
|-
| s || Strings (chars included) || $s = "" or $s = Null
|-
| b || Booleans || $b = False or $b = True
|-
| d || Binaries || $d = Binary("")
|-
| id || An AutoIt controlid || $id = 0
|-
| h || Handles (and GUI handles) || $h = 0
|-
| fu || Functions || $fu = Null
|-
| p || Pointers || $p = 0
|-
| tag || Structures definition || $tag = 0
|-
| t || Structures || $t = 0
|-
| o || Objects || $o = 0
|-
| v || Variant || $v = 0 or $v = "" (or $v = Null)
|-
| e || Enumerations || N/A
|-
| k || Keywords || $k = Default
|}

The variables are named following this schema:
{| class="wikitable"
|-
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| i || f || MyFlag
|}

Example:
<syntaxhighlight lang="autoit">
; Assign a Local variable the number 5.
Local $iSomeVar = 5

; Assign a Local variable the number 1.
Local $ifMyFlag = 1

; Assign a Local variable an array of numbers.
Local $aiArray = 0

; Re-declare the array to size and fill it.
Local $aiArray[3] = [0, 0.25, 3 / 4]
</syntaxhighlight>

Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.

Example:
<syntaxhighlight lang="autoit">
;Bad
Local $iSomeVar1, $aiArray = 0
Local $iSomeVar2 = 5

;Good
Local $iSomeVar1 = 0, $iSomeVar2 = 5
Local $aiArray = 0
</syntaxhighlight>
You can still categorize your variables and declare for example the $iSomeVar2 on another line.

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

Local $vValue ; Bad, this is initially blank.
Local $vVal = 0 ; Good

MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)

; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt
; is a little less forgiving in that it initialises the variable as being blank and doesn't throw any error, unlike some moder C++ compilers.
</syntaxhighlight>

== Scopes of Variables ==
To make the transition, the variables are also named according to their scope.
{| class="wikitable"
|-
! Global UDF variable !! Global variable !! Local variable
|-
| $__iSomeVar or $g__iSomeVar || $_iSomeVar or $g_iSomeVar || $iSomeVar
|}
With this method, you will avoid non wanted re-assignments.

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

; Assign a Global variable the number 0.
Global $iSomeVar1 = 0
; Assign a Global variable the number 5.
Global $_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 $_iSomeVar2.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_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 <MessageBoxConstants.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 $_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 $_iVar1.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 <MessageBoxConstants.au3>

Dim $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, "", $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, $vVariableThatIsGlobal) ; The Global variable ($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 $vVariableThatIsGlobal = ""

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

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

; Calling Example() first will initialise the Global variable $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

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

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

; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 <MessageBoxConstants.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 <MessageBoxConstants.au3>

; Declaring variables outside of loops is more efficent 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">
;Bad
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes.

;Good
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 <MessageBoxConstants.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.

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

2014-06-27T08:22:41Z

Guinness: /* Names of Variables */

Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.

A few notes:
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.

__TOC__

== Names of Variables ==
The [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is adopted however it's simplified and regroup all the types of numbers in one type.

Variables are initialized with the "default" value (or the most efficient value) of their type. See below in the table for specific value.

{| class="wikitable"
|-
! prefix !! covering type !! initialization
|-
| i || Integer || $i = 0
|-
| f || Floating point || $f = 0.0
|-
| n || General number (no preference) || $n = 0
|-
| a || Arrays || $a = 0 or $a[0]
|-
| s || Strings (chars included) || $s = "" or $s = Null
|-
| b || Booleans || $b = False or $b = True
|-
| d || Binaries || $d = Binary("")
|-
| id || An AutoIt controlid || $id = 0
|-
| h || Handles (and GUI handles) || $h = 0
|-
| fu || Functions || $fu = Null
|-
| p || Pointers || $p = 0
|-
| tag || Structures definition || $tag = 0
|-
| t || Structures || $t = 0
|-
| o || Objects || $o = 0
|-
| v || Variant || $v = 0 or $v = "" (or $v = Null)
|-
| e || Enumerations || N/A
|-
| k || Keywords || $k = Default
|}

The variables are named following this schema:
{| class="wikitable"
|-
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| i || f || MyFlag
|}

Example:
<syntaxhighlight lang="autoit">
; Assign a Local variable the number 5.
Local $iSomeVar = 5

; Assign a Local variable the number 1.
Local $ifMyFlag = 1

; Assign a Local variable an array of numbers.
Local $aiArray = 0

; Re-declare the array to size and fill it.
Local $aiArray[3] = [0, 0.25, 3 / 4]
</syntaxhighlight>

Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.

Example:
<syntaxhighlight lang="autoit">
;Bad
Local $iSomeVar1, $aiArray = 0
Local $iSomeVar2 = 5

;Good
Local $iSomeVar1 = 0, $iSomeVar2 = 5
Local $aiArray = 0
</syntaxhighlight>
You can still categorize your variables and declare for example the $iSomeVar2 on another line.

Example2:
<syntaxhighlight lang="autoit">
#include <Constants.au3>

Local $vValue ; Bad, this is initially blank.
Local $vVal = 0 ; Good

MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)

; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt
; is a little less forgiving in that it initialises the variable as being blank and doesn't throw any error, unlike some moder C++ compilers.
</syntaxhighlight>

== Scopes of Variables ==
To make the transition, the variables are also named according to their scope.
{| class="wikitable"
|-
! Global UDF variable !! Global variable !! Local variable
|-
| $__iSomeVar or $g__iSomeVar || $_iSomeVar or $g_iSomeVar || $iSomeVar
|}
With this method, you will avoid non wanted re-assignments.

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

; Assign a Global variable the number 0.
Global $iSomeVar1 = 0
; Assign a Global variable the number 5.
Global $_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 $_iSomeVar2.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_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 <MessageBoxConstants.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 $_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 $_iVar1.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 <MessageBoxConstants.au3>

Dim $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, "", $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, $vVariableThatIsGlobal) ; The Global variable ($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 $vVariableThatIsGlobal = ""

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

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

; Calling Example() first will initialise the Global variable $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

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

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

; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 <MessageBoxConstants.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 <MessageBoxConstants.au3>

; Declaring variables outside of loops is more efficent 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">
;Bad
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes.

;Good
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 <MessageBoxConstants.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.

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

2014-06-27T08:21:57Z

Guinness:

Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.

A few notes:
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.

__TOC__

== Names of Variables ==
The [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is adopted however it's simplified and regroup all the types of numbers in one type.

Variables are initialized with the "default" value (or the most efficient value) of their type. See below in the table for specific value.

{| class="wikitable"
|-
! prefix !! covering type !! initialization
|-
| i || Integer || $i = 0
|-
| f || Floating point || $f = 0.0
|-
| n || General number (no preference) || $n = 0
|-
| a || Arrays || $a = 0 or $a[0]
|-
| s || Strings (chars included) || $s = "" or $s = Null
|-
| b || Booleans || $b = False or $b = True
|-
| d || Binaries || $d = Binary("")
|-
| id || An AutoIt controlid || $id = 0
|-
| h || Handles (and GUI handles) || $h = 0
|-
| k (ND) || Keywords || $k = Default
|-
| fu (ND) || Functions || $fu = Null
|-
| p || Pointers || $p = 0
|-
| tag || Structures definition || $tag = 0
|-
| t || Structures || $t = 0
|-
| o || Objects || $o = 0
|-
| v || Variant || $v = 0 or $v = "" (or $v = Null)
|-
| e || Enumerations || N/A
|}

The variables are named following this schema:
{| class="wikitable"
|-
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| i || f || MyFlag
|}

Example:
<syntaxhighlight lang="autoit">
; Assign a Local variable the number 5.
Local $iSomeVar = 5

; Assign a Local variable the number 1.
Local $ifMyFlag = 1

; Assign a Local variable an array of numbers.
Local $aiArray = 0

; Re-declare the array to size and fill it.
Local $aiArray[3] = [0, 0.25, 3 / 4]
</syntaxhighlight>

Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.

Example:
<syntaxhighlight lang="autoit">
;Bad
Local $iSomeVar1, $aiArray = 0
Local $iSomeVar2 = 5

;Good
Local $iSomeVar1 = 0, $iSomeVar2 = 5
Local $aiArray = 0
</syntaxhighlight>
You can still categorize your variables and declare for example the $iSomeVar2 on another line.

Example2:
<syntaxhighlight lang="autoit">
#include <Constants.au3>

Local $vValue ; Bad, this is initially blank.
Local $vVal = 0 ; Good

MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)

; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt
; is a little less forgiving in that it initialises the variable as being blank and doesn't throw any error, unlike some moder C++ compilers.
</syntaxhighlight>

== Scopes of Variables ==
To make the transition, the variables are also named according to their scope.
{| class="wikitable"
|-
! Global UDF variable !! Global variable !! Local variable
|-
| $__iSomeVar or $g__iSomeVar || $_iSomeVar or $g_iSomeVar || $iSomeVar
|}
With this method, you will avoid non wanted re-assignments.

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

; Assign a Global variable the number 0.
Global $iSomeVar1 = 0
; Assign a Global variable the number 5.
Global $_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 $_iSomeVar2.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_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 <MessageBoxConstants.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 $_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 $_iVar1.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 <MessageBoxConstants.au3>

Dim $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, "", $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, $vVariableThatIsGlobal) ; The Global variable ($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 $vVariableThatIsGlobal = ""

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

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

; Calling Example() first will initialise the Global variable $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

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

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

; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 <MessageBoxConstants.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 <MessageBoxConstants.au3>

; Declaring variables outside of loops is more efficent 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">
;Bad
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes.

;Good
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 <MessageBoxConstants.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.

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

2014-06-27T08:20:51Z

Guinness: /* Names of Variables */

Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.

A few notes:
* "(ND)" stands for "Not decided", meaning that the writer decided himself the best coding practice and it has to be validated by another MVP/a Developer.
* You must use the latest beta to run the below examples.

__TOC__

== Names of Variables ==
The [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is adopted however it's simplified and regroup all the types of numbers in one type.

Variables are initialized with the "default" value (or the most efficient value) of their type. See below in the table for specific value.

{| class="wikitable"
|-
! prefix !! covering type !! initialization
|-
| i || Integer || $i = 0
|-
| f || Floating point || $f = 0.0
|-
| n || General number (no preference) || $n = 0
|-
| a || Arrays || $a = 0 or $a[0]
|-
| s || Strings (chars included) || $s = "" or $s = Null
|-
| b || Booleans || $b = False or $b = True
|-
| d || Binaries || $d = Binary("")
|-
| id || An AutoIt controlid || $id = 0
|-
| h || Handles (and GUI handles) || $h = 0
|-
| k (ND) || Keywords || $k = Default
|-
| fu (ND) || Functions || $fu = Null
|-
| p || Pointers || $p = 0
|-
| tag || Structures definition || $tag = 0
|-
| t || Structures || $t = 0
|-
| o || Objects || $o = 0
|-
| v || Variant || $v = 0 or $v = "" (or $v = Null)
|-
| e || Enumerations || N/A
|}

The variables are named following this schema:
{| class="wikitable"
|-
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| i || f || MyFlag
|}

Example:
<syntaxhighlight lang="autoit">
; Assign a Local variable the number 5.
Local $iSomeVar = 5

; Assign a Local variable the number 1.
Local $ifMyFlag = 1

; Assign a Local variable an array of numbers.
Local $aiArray = 0

; Re-declare the array to size and fill it.
Local $aiArray[3] = [0, 0.25, 3 / 4]
</syntaxhighlight>

Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.

Example:
<syntaxhighlight lang="autoit">
;Bad
Local $iSomeVar1, $aiArray = 0
Local $iSomeVar2 = 5

;Good
Local $iSomeVar1 = 0, $iSomeVar2 = 5
Local $aiArray = 0
</syntaxhighlight>
You can still categorize your variables and declare for example the $iSomeVar2 on another line.

Example2:
<syntaxhighlight lang="autoit">
#include <Constants.au3>

Local $vValue ; Bad, this is initially blank.
Local $vVal = 0 ; Good

MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)

; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt
; is a little less forgiving in that it initialises the variable as being blank and doesn't throw any error, unlike some moder C++ compilers.
</syntaxhighlight>

== Scopes of Variables ==
To make the transition, the variables are also named according to their scope.
{| class="wikitable"
|-
! Global UDF variable !! Global variable !! Local variable
|-
| $__iSomeVar or $g__iSomeVar || $_iSomeVar or $g_iSomeVar || $iSomeVar
|}
With this method, you will avoid non wanted re-assignments.

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

; Assign a Global variable the number 0.
Global $iSomeVar1 = 0
; Assign a Global variable the number 5.
Global $_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 $_iSomeVar2.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_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 <MessageBoxConstants.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 $_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 $_iVar1.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 <MessageBoxConstants.au3>

Dim $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, "", $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, $vVariableThatIsGlobal) ; The Global variable ($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 $vVariableThatIsGlobal = ""

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

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

; Calling Example() first will initialise the Global variable $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

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

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

; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 <MessageBoxConstants.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 <MessageBoxConstants.au3>

; Declaring variables outside of loops is more efficent 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">
;Bad
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes.

;Good
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 <MessageBoxConstants.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.

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

2014-06-27T08:18:30Z

Guinness: /* Names of Variables */

Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.

A few notes:
* "(ND)" stands for "Not decided", meaning that the writer decided himself the best coding practice and it has to be validated by another MVP/a Developer.
* You must use the latest beta to run the below examples.

__TOC__

== Names of Variables ==
The [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is adopted however it's simplified and regroup all the types of numbers in one type.

Variables are initialized with the "default" value (or the most efficient value) of their type. See below in the table for specific value.

{| class="wikitable"
|-
! prefix !! covering type !! initialization
|-
| i || Integer || $i = 0
|-
| f || Floating point || $f = 0.0
|-
| n || General number (no pref) || $n = 0
|-
| a || Arrays || $a = 0 or $a[0]
|-
| s || Strings (chars included) || $s = ""
|-
| b || Booleans || $b = False or $b = True
|-
| d || Binaries || $d = Binary("")
|-
| id || An AutoIt controlid || $id = 0
|-
| h || Handles (and GUI handles) || $h = 0
|-
| k (ND) || Keywords || Null (ND)
|-
| fu (ND) || Functions || Null (ND)
|-
| p || Pointers || $p = 0
|-
| tag || Structures definition || $tag = 0
|-
| t || Structures || $t = 0
|-
| o || Objects || $o = 0
|-
| v || Variant || $v = 0 or $v = "" (or $v = Null)
|-
| e || Enumerations || N/A
|}

The variables are named following this schema:
{| class="wikitable"
|-
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| i || f || MyFlag
|}

Example:
<syntaxhighlight lang="autoit">
; Assign a Local variable the number 5.
Local $iSomeVar = 5

; Assign a Local variable the number 1.
Local $ifMyFlag = 1

; Assign a Local variable an array of numbers.
Local $aiArray = 0

; Re-declare the array to size and fill it.
Local $aiArray[3] = [0, 0.25, 3 / 4]
</syntaxhighlight>

Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.

Example:
<syntaxhighlight lang="autoit">
;Bad
Local $iSomeVar1, $aiArray = 0
Local $iSomeVar2 = 5

;Good
Local $iSomeVar1 = 0, $iSomeVar2 = 5
Local $aiArray = 0
</syntaxhighlight>
You can still categorize your variables and declare for example the $iSomeVar2 on another line.

Example2:
<syntaxhighlight lang="autoit">
#include <Constants.au3>

Local $vValue ; Bad, this is initially blank.
Local $vVal = 0 ; Good

MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)

; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt
; is a little less forgiving in that it initialises the variable as being blank and doesn't throw any error, unlike some moder C++ compilers.
</syntaxhighlight>

== Scopes of Variables ==
To make the transition, the variables are also named according to their scope.
{| class="wikitable"
|-
! Global UDF variable !! Global variable !! Local variable
|-
| $__iSomeVar or $g__iSomeVar || $_iSomeVar or $g_iSomeVar || $iSomeVar
|}
With this method, you will avoid non wanted re-assignments.

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

; Assign a Global variable the number 0.
Global $iSomeVar1 = 0
; Assign a Global variable the number 5.
Global $_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 $_iSomeVar2.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_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 <MessageBoxConstants.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 $_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 $_iVar1.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 <MessageBoxConstants.au3>

Dim $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, "", $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, $vVariableThatIsGlobal) ; The Global variable ($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 $vVariableThatIsGlobal = ""

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

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

; Calling Example() first will initialise the Global variable $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

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

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

; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 <MessageBoxConstants.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 <MessageBoxConstants.au3>

; Declaring variables outside of loops is more efficent 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">
;Bad
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes.

;Good
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 <MessageBoxConstants.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.

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

2014-06-27T08:14:52Z

Guinness: /* Scopes of Variables */

Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.

A few notes:
* "(ND)" stands for "Not decided", meaning that the writer decided himself the best coding practice and it has to be validated by another MVP/a Developer.
* You must use the latest beta to run the below examples.

__TOC__

== Names of Variables ==
The [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is adopted however it's simplified and regroup all the types of numbers in one type.

Variables are initialized with the "default" value (or the most efficient value) of their type. See below in the table for specific value.

{| class="wikitable"
|-
! prefix !! covering type !! initialization
|-
| i || Integer || $i = 0
|-
| f || Floating point || $f = 0.0
|-
| n || General number (no pref) || $n = 0
|-
| a || Arrays || $a = 0 or $a[0]
|-
| s || Strings (chars included) || $s = ""
|-
| b || Booleans || $b = False or $b = True
|-
| d || Binaries || $d = Binary("")
|-
| id || An AutoIt controlid || $id = 0
|-
| h || Handles (and GUI handles) || $h = 0
|-
| k (ND) || Keywords || Null (ND)
|-
| fu (ND) || Functions || Null (ND)
|-
| p || Pointers || $p = 0
|-
| tag || Structures definition || $tag = "somedef"
|-
| t || Structures || $t = 0
|-
| o || Objects || $o = 0
|-
| v || Variant || $v = 0 or $v = "" (or $v = Null)
|}

The variables are named following this schema:
{| class="wikitable"
|-
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| i || f || MyFlag
|}

Example:
<syntaxhighlight lang="autoit">
; Assign a Local variable the number 5.
Local $iSomeVar = 5

; Assign a Local variable the number 1.
Local $ifMyFlag = 1

; Assign a Local variable an array of numbers.
Local $aiArray = 0

; Re-declare the array to size and fill it.
Local $aiArray[3] = [0, 0.25, 3 / 4]
</syntaxhighlight>

Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.

Example:
<syntaxhighlight lang="autoit">
;Bad
Local $iSomeVar1, $aiArray = 0
Local $iSomeVar2 = 5

;Good
Local $iSomeVar1 = 0, $iSomeVar2 = 5
Local $aiArray = 0
</syntaxhighlight>
You can still categorize your variables and declare for example the $iSomeVar2 on another line.

Example2:
<syntaxhighlight lang="autoit">
#include <Constants.au3>

Local $vValue ; Bad, this is initially blank.
Local $vVal = 0 ; Good

MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)

; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt
; is a little less forgiving in that it initialises the variable as being blank and doesn't throw any error, unlike some moder C++ compilers.
</syntaxhighlight>

== Scopes of Variables ==
To make the transition, the variables are also named according to their scope.
{| class="wikitable"
|-
! Global UDF variable !! Global variable !! Local variable
|-
| $__iSomeVar or $g__iSomeVar || $_iSomeVar or $g_iSomeVar || $iSomeVar
|}
With this method, you will avoid non wanted re-assignments.

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

; Assign a Global variable the number 0.
Global $iSomeVar1 = 0
; Assign a Global variable the number 5.
Global $_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 $_iSomeVar2.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_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 <MessageBoxConstants.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 $_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 $_iVar1.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 IsArray($vParam1) = 0 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 <MessageBoxConstants.au3>

Dim $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, "", $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, $vVariableThatIsGlobal) ; The Global variable ($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 $vVariableThatIsGlobal = ""

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

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

; Calling Example() first will initialise the Global variable $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

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

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

; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 <MessageBoxConstants.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 <MessageBoxConstants.au3>

; Declaring variables outside of loops is more efficent 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">
;Bad
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes.

;Good
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 <MessageBoxConstants.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.

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

2014-06-27T08:10:38Z

Guinness: /* Names of Variables */

Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.

A few notes:
* "(ND)" stands for "Not decided", meaning that the writer decided himself the best coding practice and it has to be validated by another MVP/a Developer.
* You must use the latest beta to run the below examples.

__TOC__

== Names of Variables ==
The [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is adopted however it's simplified and regroup all the types of numbers in one type.

Variables are initialized with the "default" value (or the most efficient value) of their type. See below in the table for specific value.

{| class="wikitable"
|-
! prefix !! covering type !! initialization
|-
| i || Integer || $i = 0
|-
| f || Floating point || $f = 0.0
|-
| n || General number (no pref) || $n = 0
|-
| a || Arrays || $a = 0 or $a[0]
|-
| s || Strings (chars included) || $s = ""
|-
| b || Booleans || $b = False or $b = True
|-
| d || Binaries || $d = Binary("")
|-
| id || An AutoIt controlid || $id = 0
|-
| h || Handles (and GUI handles) || $h = 0
|-
| k (ND) || Keywords || Null (ND)
|-
| fu (ND) || Functions || Null (ND)
|-
| p || Pointers || $p = 0
|-
| tag || Structures definition || $tag = "somedef"
|-
| t || Structures || $t = 0
|-
| o || Objects || $o = 0
|-
| v || Variant || $v = 0 or $v = "" (or $v = Null)
|}

The variables are named following this schema:
{| class="wikitable"
|-
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| i || f || MyFlag
|}

Example:
<syntaxhighlight lang="autoit">
; Assign a Local variable the number 5.
Local $iSomeVar = 5

; Assign a Local variable the number 1.
Local $ifMyFlag = 1

; Assign a Local variable an array of numbers.
Local $aiArray = 0

; Re-declare the array to size and fill it.
Local $aiArray[3] = [0, 0.25, 3 / 4]
</syntaxhighlight>

Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.

Example:
<syntaxhighlight lang="autoit">
;Bad
Local $iSomeVar1, $aiArray = 0
Local $iSomeVar2 = 5

;Good
Local $iSomeVar1 = 0, $iSomeVar2 = 5
Local $aiArray = 0
</syntaxhighlight>
You can still categorize your variables and declare for example the $iSomeVar2 on another line.

Example2:
<syntaxhighlight lang="autoit">
#include <Constants.au3>

Local $vValue ; Bad, this is initially blank.
Local $vVal = 0 ; Good

MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)

; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt
; is a little less forgiving in that it initialises the variable as being blank and doesn't throw any error, unlike some moder C++ compilers.
</syntaxhighlight>

== Scopes of Variables ==
To make the transition, the variables are also named according to their scope.
{| class="wikitable"
|-
! Global UDF variable !! Global variable !! Local variable
|-
| $__iSomeVar or $g__iSomeVar || $_iSomeVar or $g_iSomeVar || $iSomeVar
|}
With this method, you will avoid non wanted re-assignments.

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

; Assign a Global variable the number 0.
Global $iSomeVar1 = 0
; Assign a Global variable the number 5.
Global $_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 $_iSomeVar2.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_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 <MessageBoxConstants.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 $_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 MyFunc1.
$_sVar2 = MyFunc1()

; 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 MyFunc1()
; Local scope.

; Display the content of $_iVar1.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_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
</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 $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

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

; Display the contents.
_ArrayDisplay($aArray)
</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 MyFunc1 with default parameters ($vParam1 = 0).
MyFunc1()

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

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

; Display the array.
_ArrayDisplay($vParam1)
EndFunc ;==>MyFunc1
</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 <MessageBoxConstants.au3>

Dim $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, "", $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, $vVariableThatIsGlobal) ; The Global variable ($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 $vVariableThatIsGlobal = ""

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

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

; Calling Example() first will initialise the Global variable $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

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

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

; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $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 $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $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 <MessageBoxConstants.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 <MessageBoxConstants.au3>

; Declaring variables outside of loops is more efficent 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">
;Bad
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes.

;Good
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 <MessageBoxConstants.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.

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>

Snippets ( Hardware Information )

2014-05-12T19:47:00Z

Guinness: /* _GetUnusedDrives */

__TOC__
[[category:Snippets]]

{{Snippet Credit Header}}

== _ComputerNameAndModel ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Can return nothing relevant if machine is not a factory build
Global $aArray = _ComputerNameAndModel() ; Returns an Array with 2 indexes.
MsgBox(64, "_ComputerNameAndModel()", 'The Product is a "' & $aArray[0] & '" and the Serial Number is "' & $aArray[1] & '".')

Func _ComputerNameAndModel()
Local $aReturn[2] = ["(Unknown)", "(Unknown)"], $oColItems, $oWMIService

$oWMIService = ObjGet("winmgmts:\\.\root\cimv2")
$oColItems = $oWMIService.ExecQuery("Select * From Win32_ComputerSystemProduct", "WQL", 0x30)
If IsObj($oColItems) Then
For $oObjectItem In $oColItems
$aReturn[0] = $oObjectItem.Name
$aReturn[1] = $oObjectItem.IdentifyingNumber
Next
Return $aReturn
EndIf
Return SetError(1, 0, $aReturn)
EndFunc ;==>_ComputerNameAndModel
</syntaxhighlight>

[[#top | Return To Contents]]

== _GetComputerModel ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Can return nothing relevant if machine is not a factory build
ConsoleWrite(_GetComputerModel() & @CRLF)

Func _GetComputerModel()
Local $oWMIService = ObjGet("winmgmts:\\.\")

Local $oColItems = $oWMIService.ExecQuery("Select * From Win32_ComputerSystem", "WQL", 0x30)
Local $sDescription

If IsObj($oColItems) Then
For $oObjectItem In $oColItems
$sDescription &= $oObjectItem.Model
Next

Return $sDescription
EndIf

Return SetError(1, 1, 0)
EndFunc ;==>_GetComputerModel
</syntaxhighlight>

[[#top|Return To Contents]]

== _GetComputerModel_2 ==

{{Snippet Header
| AuthorURL = 84272-rindeal
| AuthorName = rindeal
| Desc=Faster version of the snippet above
}}

<syntaxhighlight lang="autoit">
; Can return nothing relevant if machine is not a factory build
ConsoleWrite(_GetComputerModel() & @CRLF)

Func _GetComputerModel()
Return RegRead("HKEY_LOCAL_MACHINE\HARDWARE\DESCRIPTION\System\BIOS", "SystemProductName")
EndFunc ;==>_GetComputerModel
</syntaxhighlight>

[[#top|Return To Contents]]

== _GetDriveBusType ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <APIConstants.au3>
#include <WinAPIEx.au3>

Local $aDrive = DriveGetDrive('ALL')
For $i = 1 To $aDrive[0]
ConsoleWrite(StringUpper($aDrive[$i]) & ' => ' & _GetDriveBusType($aDrive[$i]) & @CRLF)
Next

; Get a string representation of a drive's bus type.
Func _GetDriveBusType($sDrive)
Local $aArray[14][2] = [[$DRIVE_BUS_TYPE_UNKNOWN, 'UNKNOWN'], _
[$DRIVE_BUS_TYPE_SCSI, 'SCSI'], _
[$DRIVE_BUS_TYPE_ATAPI, 'ATAPI'], _
[$DRIVE_BUS_TYPE_ATA, 'ATA'], _
[$DRIVE_BUS_TYPE_1394, '1394'], _
[$DRIVE_BUS_TYPE_SSA, 'SSA'], _
[$DRIVE_BUS_TYPE_FIBRE, 'FIBRE'], _
[$DRIVE_BUS_TYPE_USB, 'USB'], _
[$DRIVE_BUS_TYPE_RAID, 'RAID'], _
[$DRIVE_BUS_TYPE_ISCSI, 'ISCSI'], _
[$DRIVE_BUS_TYPE_SAS, 'SAS'], _
[$DRIVE_BUS_TYPE_SATA, 'SATA'], _
[$DRIVE_BUS_TYPE_SD, 'SD'], _
[$DRIVE_BUS_TYPE_MMC, 'MMC']]
Local $iDriveType = _WinAPI_GetDriveBusType($sDrive)
If @error Then
Return $aArray[0][1]
EndIf
Return $aArray[$iDriveType][1]
EndFunc ;==>_GetDriveBusType
</syntaxhighlight>

[[#top|Return To Contents]]

== _GetUnusedDrives ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

;~ Retrieve unused drive letters.
Local $aDrives = _GetUnusedDrives()
_ArrayDisplay($aDrives)

Func _GetUnusedDrives()
Local $sReturn = 'B:|C:|D:|E:|F:|G:|H:|I:|J:|K:|L:|M:|N:|O:|P:|Q:|R:|S:|T:|U:|V:|W:|X:|Y:|Z:|'
Local $aArray = DriveGetDrive('ALL')
If @error Then
Local $aError = [0]
$aArray = $aError
$aError = 0
EndIf

For $i = 1 To $aArray[0]
$sReturn = StringReplace($sReturn, $aArray[$i] & '|', '')
Next
Return StringSplit(StringTrimRight($sReturn, StringLen('|')), '|')
EndFunc ;==>_GetUnusedDrives
</syntaxhighlight>

[[#top|Return To Contents]]

== _IsSubst ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
| Desc=Checks if a drive is a subst drive.
}}

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

ConsoleWrite(_IsSubst(@HomeDrive) & @CRLF)

; Checks if a drive is a subst drive.
Func _IsSubst($sDrive)
Return _WinAPI_PathIsDirectory(StringReplace(_WinAPI_QueryDosDevice(StringLeft($sDrive, 1) & ":"), "\??\", ""))
EndFunc ;==>_IsSubst
</syntaxhighlight>

[[#top|Return To Contents]]

== _IsTrueCrypt ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
| Desc=Check if a drive is a TrueCrypt drive.
}}

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

ConsoleWrite("Is " & @HomeDrive & "\ a TrueCrypt drive?: " & _IsTrueCrypt(@HomePath) & @CRLF)

; Check if a drive is a TrueCrypt drive.
Func _IsTrueCrypt($sDrive)
Return StringInStr(_WinAPI_QueryDosDevice(StringLeft($sDrive, StringLen('A')) & ':'), 'TrueCrypt') > 0
EndFunc ;==>_IsTrueCrypt
</syntaxhighlight>

[[#top|Return To Contents]]

== _MonitorToggle ==

{{Snippet Header
| AuthorURL = 7688-greenmachine
| AuthorName = greenmachine
| Desc = Toggle Monitor On/Off.
}}

<syntaxhighlight lang="autoit">
#include <SendMessage.au3>
#include <WindowsConstants.au3>

_MonitorToggle(1)
Sleep(1000)
_MonitorToggle(0)

; Toggle Monitor On/Off.
Func _MonitorToggle($iTurnOff = 1)
Local $hWnd = WinGetHandle("[CLASS:Progman]"), $SC_MONITORPOWER = 61808
If $iTurnOff Then
Return _SendMessage($hWnd, $WM_SYSCOMMAND, $SC_MONITORPOWER, 2)
Else
Return _SendMessage($hWnd, $WM_SYSCOMMAND, $SC_MONITORPOWER, -1)
EndIf
EndFunc ;==>_MonitorToggle
</syntaxhighlight>

[[#top|Return To Contents]]

== _GetTotalScreenResolution ==

{{Snippet Header
| AuthorURL = 28010-larrydalooza
| AuthorName = LarryDalooza
| ModifierURL = 16404-brettf
| ModifierName = BrettF
}}

<syntaxhighlight lang="autoit">
Global Const $aTSR = _GetTotalScreenResolution()

MsgBox(0, "Total Screen Resolution", "Width = " & $aTSR[0] & @TAB & "Height = " & $aTSR[1])

Func _GetTotalScreenResolution()
Local Const $SM_VIRTUALWIDTH = 78
Local Const $VirtualDesktopWidth = DllCall("user32.dll", "int", "GetSystemMetrics", "int", $SM_VIRTUALWIDTH)

Local Const $SM_VIRTUALHEIGHT = 79
Local Const $VirtualDesktopHeight = DllCall("user32.dll", "int", "GetSystemMetrics", "int", $SM_VIRTUALHEIGHT)

Local Const $aRet[2] = [$VirtualDesktopWidth[0], $VirtualDesktopHeight[0]]

Return $aRet
EndFunc
</syntaxhighlight>

[[#top|Return To Contents]]

Snippets ( Hardware Information )

2014-05-12T19:43:06Z

Guinness: /* _IsTrueCrypt */

__TOC__
[[category:Snippets]]

{{Snippet Credit Header}}

== _ComputerNameAndModel ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Can return nothing relevant if machine is not a factory build
Global $aArray = _ComputerNameAndModel() ; Returns an Array with 2 indexes.
MsgBox(64, "_ComputerNameAndModel()", 'The Product is a "' & $aArray[0] & '" and the Serial Number is "' & $aArray[1] & '".')

Func _ComputerNameAndModel()
Local $aReturn[2] = ["(Unknown)", "(Unknown)"], $oColItems, $oWMIService

$oWMIService = ObjGet("winmgmts:\\.\root\cimv2")
$oColItems = $oWMIService.ExecQuery("Select * From Win32_ComputerSystemProduct", "WQL", 0x30)
If IsObj($oColItems) Then
For $oObjectItem In $oColItems
$aReturn[0] = $oObjectItem.Name
$aReturn[1] = $oObjectItem.IdentifyingNumber
Next
Return $aReturn
EndIf
Return SetError(1, 0, $aReturn)
EndFunc ;==>_ComputerNameAndModel
</syntaxhighlight>

[[#top | Return To Contents]]

== _GetComputerModel ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Can return nothing relevant if machine is not a factory build
ConsoleWrite(_GetComputerModel() & @CRLF)

Func _GetComputerModel()
Local $oWMIService = ObjGet("winmgmts:\\.\")

Local $oColItems = $oWMIService.ExecQuery("Select * From Win32_ComputerSystem", "WQL", 0x30)
Local $sDescription

If IsObj($oColItems) Then
For $oObjectItem In $oColItems
$sDescription &= $oObjectItem.Model
Next

Return $sDescription
EndIf

Return SetError(1, 1, 0)
EndFunc ;==>_GetComputerModel
</syntaxhighlight>

[[#top|Return To Contents]]

== _GetComputerModel_2 ==

{{Snippet Header
| AuthorURL = 84272-rindeal
| AuthorName = rindeal
| Desc=Faster version of the snippet above
}}

<syntaxhighlight lang="autoit">
; Can return nothing relevant if machine is not a factory build
ConsoleWrite(_GetComputerModel() & @CRLF)

Func _GetComputerModel()
Return RegRead("HKEY_LOCAL_MACHINE\HARDWARE\DESCRIPTION\System\BIOS", "SystemProductName")
EndFunc ;==>_GetComputerModel
</syntaxhighlight>

[[#top|Return To Contents]]

== _GetDriveBusType ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <APIConstants.au3>
#include <WinAPIEx.au3>

Local $aDrive = DriveGetDrive('ALL')
For $i = 1 To $aDrive[0]
ConsoleWrite(StringUpper($aDrive[$i]) & ' => ' & _GetDriveBusType($aDrive[$i]) & @CRLF)
Next

; Get a string representation of a drive's bus type.
Func _GetDriveBusType($sDrive)
Local $aArray[14][2] = [[$DRIVE_BUS_TYPE_UNKNOWN, 'UNKNOWN'], _
[$DRIVE_BUS_TYPE_SCSI, 'SCSI'], _
[$DRIVE_BUS_TYPE_ATAPI, 'ATAPI'], _
[$DRIVE_BUS_TYPE_ATA, 'ATA'], _
[$DRIVE_BUS_TYPE_1394, '1394'], _
[$DRIVE_BUS_TYPE_SSA, 'SSA'], _
[$DRIVE_BUS_TYPE_FIBRE, 'FIBRE'], _
[$DRIVE_BUS_TYPE_USB, 'USB'], _
[$DRIVE_BUS_TYPE_RAID, 'RAID'], _
[$DRIVE_BUS_TYPE_ISCSI, 'ISCSI'], _
[$DRIVE_BUS_TYPE_SAS, 'SAS'], _
[$DRIVE_BUS_TYPE_SATA, 'SATA'], _
[$DRIVE_BUS_TYPE_SD, 'SD'], _
[$DRIVE_BUS_TYPE_MMC, 'MMC']]
Local $iDriveType = _WinAPI_GetDriveBusType($sDrive)
If @error Then
Return $aArray[0][1]
EndIf
Return $aArray[$iDriveType][1]
EndFunc ;==>_GetDriveBusType
</syntaxhighlight>

[[#top|Return To Contents]]

== _GetUnusedDrives ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

;~ Retrieve unused drive letters.
Local $aDrives = _GetUnusedDrives()
_ArrayDisplay($aDrives)

Func _GetUnusedDrives()
Local $aReturn[1] = [0], $sReturn = ''

For $i = 1 To 26
$sReturn &= Chr($i + 64) & ':|'
Next

Local $aArray = DriveGetDrive('ALL')
If @error Then
$aArray = $aReturn
EndIf

For $i = 1 To $aArray[0]
$sReturn = StringReplace($sReturn, StringLeft($aArray[$i], 1) & ':|', '')
Next
Return StringSplit(StringTrimRight($sReturn, 1), '|')
EndFunc ;==>_GetUnusedDrives
</syntaxhighlight>

[[#top|Return To Contents]]

== _IsSubst ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
| Desc=Checks if a drive is a subst drive.
}}

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

ConsoleWrite(_IsSubst(@HomeDrive) & @CRLF)

; Checks if a drive is a subst drive.
Func _IsSubst($sDrive)
Return _WinAPI_PathIsDirectory(StringReplace(_WinAPI_QueryDosDevice(StringLeft($sDrive, 1) & ":"), "\??\", ""))
EndFunc ;==>_IsSubst
</syntaxhighlight>

[[#top|Return To Contents]]

== _IsTrueCrypt ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
| Desc=Check if a drive is a TrueCrypt drive.
}}

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

ConsoleWrite("Is " & @HomeDrive & "\ a TrueCrypt drive?: " & _IsTrueCrypt(@HomePath) & @CRLF)

; Check if a drive is a TrueCrypt drive.
Func _IsTrueCrypt($sDrive)
Return StringInStr(_WinAPI_QueryDosDevice(StringLeft($sDrive, StringLen('A')) & ':'), 'TrueCrypt') > 0
EndFunc ;==>_IsTrueCrypt
</syntaxhighlight>

[[#top|Return To Contents]]

== _MonitorToggle ==

{{Snippet Header
| AuthorURL = 7688-greenmachine
| AuthorName = greenmachine
| Desc = Toggle Monitor On/Off.
}}

<syntaxhighlight lang="autoit">
#include <SendMessage.au3>
#include <WindowsConstants.au3>

_MonitorToggle(1)
Sleep(1000)
_MonitorToggle(0)

; Toggle Monitor On/Off.
Func _MonitorToggle($iTurnOff = 1)
Local $hWnd = WinGetHandle("[CLASS:Progman]"), $SC_MONITORPOWER = 61808
If $iTurnOff Then
Return _SendMessage($hWnd, $WM_SYSCOMMAND, $SC_MONITORPOWER, 2)
Else
Return _SendMessage($hWnd, $WM_SYSCOMMAND, $SC_MONITORPOWER, -1)
EndIf
EndFunc ;==>_MonitorToggle
</syntaxhighlight>

[[#top|Return To Contents]]

== _GetTotalScreenResolution ==

{{Snippet Header
| AuthorURL = 28010-larrydalooza
| AuthorName = LarryDalooza
| ModifierURL = 16404-brettf
| ModifierName = BrettF
}}

<syntaxhighlight lang="autoit">
Global Const $aTSR = _GetTotalScreenResolution()

MsgBox(0, "Total Screen Resolution", "Width = " & $aTSR[0] & @TAB & "Height = " & $aTSR[1])

Func _GetTotalScreenResolution()
Local Const $SM_VIRTUALWIDTH = 78
Local Const $VirtualDesktopWidth = DllCall("user32.dll", "int", "GetSystemMetrics", "int", $SM_VIRTUALWIDTH)

Local Const $SM_VIRTUALHEIGHT = 79
Local Const $VirtualDesktopHeight = DllCall("user32.dll", "int", "GetSystemMetrics", "int", $SM_VIRTUALHEIGHT)

Local Const $aRet[2] = [$VirtualDesktopWidth[0], $VirtualDesktopHeight[0]]

Return $aRet
EndFunc
</syntaxhighlight>

[[#top|Return To Contents]]

Snippets ( Windows OS )

2014-05-12T19:41:59Z

Guinness: /* _ProcessCloseFromPath() */

__TOC__

{{Snippet Credit Header}}

===== _CancelPrinterJobs() =====
{{Snippet Header
|AuthorURL=35302-guinness
|AuthorName=guinness
}}

<syntaxhighlight lang = "autoit">
; Cancel printer jobs for the default printer or the printer name provided.

ConsoleWrite(_CancelPrinterJobs() & @CRLF)
ConsoleWrite(_CancelPrinterJobs('HP Printer 1234') & @CRLF)

Func _CancelPrinterJobs($sPrinterName = '')
If StringStripWS($sPrinterName, 8) = '' Then
$sPrinterName = 'Default = True'
Else
$sPrinterName = 'Name = "' & $sPrinterName & '"'
EndIf
Local $iResult = 0, $oWMIService = ObjGet('winmgmts:\\' & '.' & '\root\cimv2')
Local $oColItems = $oWMIService.ExecQuery('Select * From Win32_Printer Where ' & $sPrinterName)
If IsObj($oColItems) Then
For $oObjectItem In $oColItems
$iResult = $oObjectItem.CancelAllJobs()
Next
EndIf
Return $iResult
EndFunc ;==>_CancelPrinterJobs
</syntaxhighlight>

[[#top | ReturnToContents]]

===== _CheckElevationEnabled() =====
{{Snippet Header
|AuthorURL=52374-johnone
|AuthorName=JohnOne
}}

<syntaxhighlight lang = "autoit">
; OS dependent = Vista, server 2008 SP1 and WIN7
;#### Example ####
Local $bUAC = _CheckElevationEnabled()
If @error Then
Exit MsgBox(0,"Error",@error)
EndIf
MsgBox(0,"UAC Enabled",$bUAC)

;Checks if Use Access Control (UAC) is Enabled.
Func _CheckElevationEnabled()
Local $struct = DllStructCreate("BOOL")
Local $aRtn = DllCall("kernel32.dll","DWORD","CheckElevationEnabled","ptr", DllStructGetPtr($struct))
If @error Then
Return SetError(@error)
EndIf
Return SetError($aRtn[0],0,DllStructGetData($struct,1))
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

===== _IsDeskTopLocked() =====
{{Snippet Header
|AuthorURL=1967-garyfrost
|AuthorName=GaryFrost
}}

<syntaxhighlight lang="autoit">
; Detect if System is Locked

Global Const $DESKTOP_ENUMERATE = 0x40
Global Const $SPI_GETSCREENSAVERRUNNING = 114
Global Const $DESKTOP_SWITCHDESKTOP = 0x100

HotKeySet("{ESC}", "_Terminate")

AdlibEnable("IsDeskTopLocked", 500)

While 1
Sleep(10)
WEnd

Func _IsDeskTopLocked()
Local $p_lngHwnd, $p_lngRtn, $p_lngErr, $p_lngScreenSaver, $p_blnIsScreenSaver
;~ ' ------------------------------------------
;~ ' First check for screen saver one of 2 ways,
;~ ' based of OS
;~ ' ------------------------------------------
If @OSTYPE = "WIN32_WINDOWS" Then
;~ ' ---------------------------------------
;~ ' Pre W2K -- Note, will only be TRUE if
;~ ' the "Password Protected" box is
;~ ' checked.
;~ ' ---------------------------------------
$p_lngHwnd = DllCall("user32.dll", "int", "OpenDesktopA", "str", "screen-saver", "int", 0, "int", False, "int", $DESKTOP_ENUMERATE)
If $p_lngHwnd[0] <> 0 Then
$p_blnIsScreenSaver = True
Else
$p_blnIsScreenSaver = False
EndIf
Else
;~ ' ---------------------------------------
;~ ' W2K+ -- Will determine if screen saver
;~ ' is running whether or not the
;~ ' "Password Protected" box is checked
;~ ' ---------------------------------------
$p_lngRtn = DllCall("user32.dll", "int", "SystemParametersInfoA", "int", $SPI_GETSCREENSAVERRUNNING, "int", 0, "int", $p_lngScreenSaver, "int", 0)
If $p_lngRtn[0] = 0 Then
ConsoleWrite("Error detecting screen saver" & @LF)
Else
$p_blnIsScreenSaver = $p_lngScreenSaver
EndIf

EndIf
;~ ' ------------------------------------------
;~ ' If screen saver is *not* running, then
;~ ' check for locked workstation
;~ ' ------------------------------------------
If $p_blnIsScreenSaver Then
If @OSTYPE = "WIN32_WINDOWS" Then
ConsoleWrite("Screen saver is running..., Handle #" & $p_lngHwnd[0] & @LF)
$p_lngHwnd = DllCall("user32.dll", "int", "CloseDesktop", "int", $p_lngHwnd[0])
Else
ConsoleWrite("Screen saver is running on W2K+" & @LF)
EndIf
Else
$p_lngHwnd = DllCall("user32.dll", "int", "OpenDesktopA", "str", "Default", "int", 0, "int", False, "int", $DESKTOP_SWITCHDESKTOP)

If $p_lngHwnd[0] = 0 Then
ConsoleWrite("Error with OpenDesktop" & @LF)
Else
$p_lngRtn = DllCall("user32.dll", "int", "SwitchDesktop", "int", $p_lngHwnd[0])
$p_lngErr = _GetLastErrorMessage()

If $p_lngRtn[0] = 0 Then
If $p_lngErr = 0 Then
ConsoleWrite("Desktop is locked" & @LF)
Else
ConsoleWrite("Error with SwitchDesktop" & @LF)
EndIf
Else
ConsoleWrite("Not locked!" & @LF)
EndIf
$p_lngHwnd = DllCall("user32.dll", "int", "CloseDesktop", "int", $p_lngHwnd[0])
EndIf
EndIf
EndFunc ;==>IsDeskTopLocked

Func _Terminate()
Exit
EndFunc ;==>_Terminate

;===============================================
; _GetLastErrorMessage($DisplayMsgBox="")
; Format the last windows error as a string and return it
; if $DisplayMsgBox <> "" Then it will display a message box w/ the error
; Return Window's error as a string
;===============================================
Func _GetLastErrorMessage($DisplayMsgBox = "")
Local $ret, $s
Local $p = DllStructCreate("char[4096]")
Local Const $FORMAT_MESSAGE_FROM_SYSTEM = 0x00001000
If @error Then Return ""
$ret = DllCall("Kernel32.dll", "int", "GetLastError")
$ret = DllCall("kernel32.dll", "int", "FormatMessage", _
"int", $FORMAT_MESSAGE_FROM_SYSTEM, _
"ptr", 0, _
"int", $ret[0], _
"int", 0, _
"ptr", DllStructGetPtr($p), _
"int", 4096, _
"ptr", 0)
$s = DllStructGetData($p, 1)
If $DisplayMsgBox <> "" Then MsgBox(0, "_GetLastErrorMessage", $DisplayMsgBox & @CRLF & $s)
Return $s
EndFunc ;==>_GetLastErrorMessage
</syntaxhighlight>

[[#top | ReturnToContents]]

===== _DisplayWindowsSwitcher() =====
{{Snippet Header
| AuthorURL=66537-knightz93
| AuthorName=Knightz93
| ModifierURL=35302-guinness
| ModifierName=guinness
}}

<syntaxhighlight lang = "autoit">
HotKeySet("{ESC}", "_Exit") ; Press the ESC key to escape.

HotKeySet("!3", "_DisplayWindowsSwitcher") ; Press Alt+3 to display the Windows Switcher, though this in Windows is also Win Key + Tab.

While 1
Sleep(100)
WEnd

; Only works on Windows 7+
Func _DisplayWindowsSwitcher()
Local $oShell = ObjCreate("shell.application")
If @error Then
Return SetError(1, 0, 0)
EndIf
$oShell.WindowSwitcher()
EndFunc ;==>_DisplayWindowsSwitcher

Func _Exit()
Exit
EndFunc ;==>_Exit
</syntaxhighlight>

[[#top | ReturnToContents]]

===== _DisableWindowsLock() =====
{{Snippet Header
|AuthorURL=35302-guinness
|AuthorName=guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite('Disable Windows Lock: ' & _DisableWindowsLock() & @CRLF)
MsgBox(4096, '', 'Select Win + L to see the result of using _DisableWindowsLock.')
ConsoleWrite('Disable Windows Lock: ' & _DisableWindowsLock() & @CRLF)

; Disable the locking of Windows. Returns 1 - disabled or 0 - enabled.
Func _DisableWindowsLock()
Local $i64Bit = ''

If @OSArch = 'X64' Then
$i64Bit = '64'
EndIf
Local $iRegRead = Number(Not RegRead('HKEY_CURRENT_USER' & $i64Bit & '\Software\Microsoft\Windows\CurrentVersion\Policies\System', 'DisableLockWorkstation'))
Return SetError(Not RegWrite('HKEY_CURRENT_USER' & $i64Bit & '\Software\Microsoft\Windows\CurrentVersion\Policies\System', 'DisableLockWorkstation', 'REG_DWORD', $iRegRead), 0, $iRegRead)
EndFunc ;==>_DisableWindowsLock
</syntaxhighlight>

[[#top | ReturnToContents]]

===== _IsFontExists() =====
{{Snippet Header
|AuthorURL=35302-guinness
|AuthorName=guinness
}}

<syntaxhighlight lang="autoit">
#include <APIConstants.au3>
#include <WinAPIEx.au3>

ConsoleWrite(_IsFontExists("WebDings.ttf") & @CRLF)

Func _IsFontExists($sFontType)
Return FileExists(_WinAPI_ShellGetSpecialFolderPath($CSIDL_FONTS) & "\" & $sFontType) ; WebDings.ttf
EndFunc ;==>_IsFontExists
</syntaxhighlight>

[[#top | ReturnToContents]]

===== _GetDesktopWallpaper() =====
{{Snippet Header
|AuthorURL=35302-guinness
|AuthorName=guinness
}}

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

ConsoleWrite( _GetDesktopWallpaper() & @CRLF)

Func _GetDesktopWallpaper()
Local $SPI_GETDESKWALLPAPER = 0x0073
Local $tPATH = DllStructCreate('wchar[260]')
_WinAPI_SystemParametersInfo($SPI_GETDESKWALLPAPER, 260, DllStructGetPtr($tPATH))
Return DllStructGetData($tPATH, 1)
EndFunc ;==>_GetDesktopWallpaper
</syntaxhighlight>

[[#top | ReturnToContents]]

===== _GetOSVersion() =====
{{Snippet Header
|AuthorURL=7108-xenobiologist
|AuthorName=Xenobiologist
}}

<syntaxhighlight lang="autoit">
MsgBox(0,0, _GetOSVersion())

Func _GetOSVersion()
Local $objWMIService = ObjGet("winmgmts:{impersonationLevel=impersonate}!\\.\root\cimv2")
Local $colSettings = $objWMIService.ExecQuery("Select * from Win32_OperatingSystem")
For $objOperatingSystem In $colSettings
Return "Windows " & StringMid($objOperatingSystem.Caption, 19)
Next
EndFunc ;==>_getOSVersion
</syntaxhighlight>

[[#top | ReturnToContents]]

===== _InstallDate() =====
{{Snippet Header
|AuthorURL=35302-guinness
|AuthorName=guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_InstallDate() & @CRLF)

Func _InstallDate()
Local $oWMIService = ObjGet("winmgmts:{impersonationLevel = impersonate}!\\" & "." & "\root\cimv2")
Local $oColFiles = $oWMIService.ExecQuery("Select * From Win32_OperatingSystem")
If IsObj($oColFiles) Then
For $oObjectFile In $oColFiles
Return StringRegExpReplace($oObjectFile.InstallDate, "\A(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})(?:.*)", "$3/$2/$1 $4:$5:$6")
Next
EndIf
Return SetError(1, 0, 0)
EndFunc ;==>_InstallDate
</syntaxhighlight>

[[#top | ReturnToContents]]

===== Installed version of Windows with mathematical operators =====
{{Snippet Header
|AuthorURL=52-geosoft
|AuthorName=GEOSoft
}}

<syntaxhighlight lang="autoit">
; Test the installed version of Windows with mathematical operators.

Global Const $2K_VER = 5.0
Global Const $XP_VER = 5.1
Global Const $XP64_VER = 5.2
Global Const $VISTA_VER = 6.0
Global Const $W7_VER = 6.1

$iCurrVer = RegRead("HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion", "CurrentVersion")
MsgBox(0, "Result", $iCurrVer >= $VISTA_VER)
</syntaxhighlight>

[[#top|Return To Contents]]

===== _IsElevationRequired() =====
{{Snippet Header
|AuthorURL=52374-johnone
|AuthorName=JohnOne
}}

<syntaxhighlight lang="autoit">
; OS dependent = Vista, server 2008 SP1 and WIN7
;#### Example 1 ####
Global $bool = _IsElevationRequired("C:\Windows\notepad.exe") ;Pass path of an exe that does not normally need elevated privileges
If @error Then
Exit MsgBox(0,"Error",@error)
EndIf
;should show 0
MsgBox(0,"Elevation notepad",$bool)

;#### Example 2 ####
$bool = _IsElevationRequired("C:\Windows\regedit.exe") ;Pass path of an exe that does normally need elevated privileges
If @error Then
Exit MsgBox(0,"Error",@error)
EndIf
;should show 1
MsgBox(0,"Elevation regedit",$bool)

Func _IsElevationRequired($szPath) ;Checks if an executable (.exe) needs elevated permissions to run.
Local Const $BAD_ARG = 6
If StringRight($szPath,3) <> "exe" Then
Return SetError($BAD_ARG)
EndIf
Local $aRtn = DllCall("shell32.dll","BOOL",865,"wstr",$szPath)
If @error Then
Return SetError(@error)
EndIf
Return $aRtn[0]
EndFunc ;===>_IsElevationRequired
</syntaxhighlight>

[[#top|Return To Contents]]

===== _IsServer() =====
{{Snippet Header
|AuthorURL=35302-guinness
|AuthorName=guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite( _IsServer() & @CRLF)

Func _IsServer() ; MSDN: http://msdn.microsoft.com/en-us/library/windows/desktop/aa394239(v=vs.85).aspx
Local $oWMIService = ObjGet("winmgmts://./root/cimv2"), $oWMIServiceItem
Local $oColItems = $oWMIService.ExecQuery("Select * From Win32_OperatingSystem")
If IsObj($oColItems) Then
For $oWMIServiceItem In $oColItems
If $oWMIServiceItem.ProductType = 2 Or $oWMIServiceItem.ProductType = 3 Then
Return 1
EndIf
Next
EndIf
Return SetError(1, 0, 0)
EndFunc ;==>_IsServer
</syntaxhighlight>

[[#top|Return To Contents]]

===== _IsPrimaryOS() =====
{{Snippet Header
|AuthorURL=35302-guinness
|AuthorName=guinness
}}

<syntaxhighlight lang="autoit">
; Tell if the current OS is the primary OS.

ConsoleWrite("_IsPrimaryOS() >> " & _IsPrimaryOS() & @LF)

Func _IsPrimaryOS($sComputerName = @ComputerName)
Local $oColItems, $oWMIService

$oWMIService = ObjGet("winmgmts:\\" & $sComputerName & "\root\cimv2")
If @error Then
Return SetError(1, 0, 1)
EndIf
$oColItems = $oWMIService.ExecQuery("Select * From Win32_SystemOperatingSystem", "WQL", 0x30)
If IsObj($oColItems) Then
For $oObjectItem In $oColItems
Return $oObjectItem.PrimaryOS
Next
EndIf
Return SetError(1, 0, 1)
EndFunc ;==>_IsPrimaryOS
</syntaxhighlight>

[[#top|Return To Contents]]

===== _IsSafeMode() =====
{{Snippet Header
|AuthorURL=35302-guinness
|AuthorName=guinness
}}

<syntaxhighlight lang="autoit">
#include <WinAPI.au3>
#include <WindowsConstants.au3>

ConsoleWrite(_IsSafeMode() & @CRLF)

Func _IsSafeMode()
Return _WinAPI_GetSystemMetrics($SM_CLEANBOOT) > 0
EndFunc ;==>_IsSafeMode
</syntaxhighlight>

[[#top|Return To Contents]]

===== _IsVirtualMachine() =====
{{Snippet Header
|AuthorURL=35302-guinness
|AuthorName=guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite( _IsVirtualMachine() & @LF)

Func _IsVirtualMachine() ; Returns True or False.
Local $oColItems, $oWMIService
$oWMIService = ObjGet("winmgmts:\\localhost\root\cimv2")
$oColItems = $oWMIService.ExecQuery("Select * From Win32_ComputerSystemProduct", "WQL", 0x30)
If IsObj($oColItems) Then
For $oObjectItem In $oColItems
Return StringRegExp($oObjectItem.Name, 'VirtualBox|VMWare|Virtual PC') = 1
Next
EndIf
Return False
EndFunc ;==>_IsVirtualMachine
</syntaxhighlight>

[[#top|Return To Contents]]

===== _IsVistaAbove() =====
{{Snippet Header
|AuthorURL=35302-guinness
|AuthorName=guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_IsVistaAbove() & @CRLF) ; Returns True is greater or equal to Windows Vista.

Func _IsVistaAbove()
Return RegRead("HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\", "CurrentVersion") >= 6.0
EndFunc ;==>_IsVistaAbove
</syntaxhighlight>

[[#top|Return To Contents]]

===== _IsWindowsTablet() =====
{{Snippet Header
|AuthorURL=35302-guinness
|AuthorName=guinness
}}

<syntaxhighlight lang="autoit">
#include <WinAPI.au3>
#include <WindowsConstants.au3>

MsgBox(64, "_IsWindowsTablet()", _IsWindowsTablet())

Func _IsWindowsTablet()
Return _WinAPI_GetSystemMetrics($SM_TABLETPC) > 0
EndFunc ;==>_IsWindowsTablet
</syntaxhighlight>

[[#top|Return To Contents]]

===== _OSArch() =====
{{Snippet Header
|AuthorURL=35302-guinness
|AuthorName=guinness
}}

<syntaxhighlight lang="autoit">
#cs
If you're using Windows x86 then '' is returned otherwise if you're using x64 then '64' is returned.
#ce
ConsoleWrite("Program" & _OSArch() & ".exe" & @LF)

Func _OSArch()
Return StringRegExpReplace(@OSArch, "(?i)x86|\D+", "") ; Thanks to wraithdu.
EndFunc ;==>_OSArch
</syntaxhighlight>

[[#top|Return To Contents]]

===== _OSSerial() =====
{{Snippet Header
|AuthorURL=35302-guinness
|AuthorName=guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_OSSerial() & @CRLF)

Func _OSSerial()
Local $oWMIService = ObjGet("winmgmts:{impersonationLevel = impersonate}!\\" & "." & "\root\cimv2")
Local $oColFiles = $oWMIService.ExecQuery("Select * From Win32_OperatingSystem")
If IsObj($oColFiles) Then
For $oObjectFile In $oColFiles
Return $oObjectFile.SerialNumber
Next
EndIf
Return SetError(1, 0, 0)
EndFunc ;==>OSSerial
</syntaxhighlight>

[[#top|Return To Contents]]

===== _OSVersion() =====
{{Snippet Header
|AuthorURL=35302-guinness
|AuthorName=guinness
}}

<syntaxhighlight lang="autoit">
; Get the OS version number without an API call.

MsgBox(0, "_OSVersion()", _OSVersion())
MsgBox(0, "_OSVersionEx()", _OSVersionEx())

Func _OSVersion()
Return RegRead("HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\", "CurrentVersion")
EndFunc ;==>_OSVersion

Func _OSVersionEx()
Return StringLeft(FileGetVersion(@SystemDir & "\WinVer.exe"), 3)
EndFunc ;==>_OSVersionEx
</syntaxhighlight>

[[#top|Return To Contents]]

===== _ProcessCloseFromPath() =====
{{Snippet Header
|AuthorURL=35302-guinness
|AuthorName=guinness
}}

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

Example()

Func Example()
; Close a process using the filepath rather than the filename, which is what ProcessClose requires.

; Run Notepad
Run("notepad.exe")

; Wait 10 seconds for the Notepad window to appear.
WinWait("[CLASS:Notepad]", "", 10)

; Wait for 2 seconds.
Sleep(2000)

Local $sNotepad = @SystemDir & "\notepad.exe"
MsgBox($MB_SYSTEMMODAL, "", "Path of Notepad: " & $sNotepad)

; Close the Notepad process using the filepath.
_ProcessCloseFromPath($sNotepad)
EndFunc ;==>Example

Func _ProcessCloseFromPath($sFilePath)
Return FileExists($sFilePath) ? ProcessClose(StringTrimLeft($sFilePath, StringInStr($sFilePath, "\", Default, -1))) : SetError(1, 0, 0)
EndFunc ;==>_ProcessCloseFromPath
</syntaxhighlight>

[[#top|Return To Contents]]

===== _UnDockPC() =====
{{Snippet Header
|AuthorURL=35302-guinness
|AuthorName=guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_UnDockPC() & @CRLF)

; Ejects the computer from its docking station.
Func _UnDockPC()
Local $oShell = ObjCreate('shell.application')
If @error Then
Return SetError(1, 0, 0)
EndIf
$oShell.EjectPC()
Return 1
EndFunc ;==>_UnDockPC
</syntaxhighlight>

[[#top|Return To Contents]]

===== _WMPlayer_Location() =====
{{Snippet Header
|AuthorURL=35302-guinness
|AuthorName=guinness
}}

<syntaxhighlight lang="autoit">
; Get the location of Windows Media Player.

#include <WinAPI.au3>

ConsoleWrite(_WMPLayer_Location() & @CRLF)

Func _WMPlayer_Location()
Local $aReturn = StringRegExp(_WinAPI_ExpandEnvironmentStrings(RegRead("HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Applications\wmplayer.exe\shell\open\command", "")), '(?s)(?i)"(.*?)"', 3)
If @error Then
Return SetError(1, 0, "")
EndIf
Return $aReturn[0]
EndFunc ;==>_WMPlayer_Location
</syntaxhighlight>

[[#top|Return To Contents]]

[[category:Snippets]]

Snippets ( Files & Folders )

2014-05-12T19:35:36Z

Guinness: /* _IsFileOlder */

__TOC__
[[category:Snippets]]

{{Snippet Credit Header}}

== _ConvertFileToUTF16 ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
_ConvertFileToUTF16(@ScriptDir & "\Example.xml")

Func _ConvertFileToUTF16($sFilePath)
Local $iEncoding = FileGetEncoding($sFilePath)
Local $hFileOpen = FileOpen($sFilePath, $iEncoding)
If $hFileOpen = -1 Then
Return SetError(1, 0, 0)
EndIf
Local $sData = FileRead($hFileOpen)
FileClose($hFileOpen)

$hFileOpen = FileOpen($sFilePath, 2 + 32)
If $hFileOpen = -1 Then
Return SetError(2, 0, 0)
EndIf
FileWrite($hFileOpen, $sData)
Return FileClose($hFileOpen)
EndFunc ;==>_ConvertFileToUTF16
</syntaxhighlight>

[[#top | ReturnToContents]]

== DropFiles ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
| Desc = Dropping multiple files onto a GUI
}}

<syntaxhighlight lang="autoit">
; Dropping multiple files onto a GUI

#include <APIConstants.au3>
#include <Array.au3>
#include <GUIConstantsEx.au3>
#include <WinAPIEx.au3>

Global $__aDropFiles

Example()

Func Example()
Local $hGUI = GUICreate('', 500, 500, -1, -1, -1, $WS_EX_ACCEPTFILES)

; Create a label that is transparent which will accept 'drop' events.
GUICtrlCreateLabel("", 0, 0, 500, 500)
GUICtrlSetBkColor(-1, $GUI_BKCOLOR_TRANSPARENT)
GUICtrlSetResizing(-1, $GUI_DOCKALL)
GUICtrlSetState(-1, $GUI_DROPACCEPTED)

GUIRegisterMsg($WM_DROPFILES, "WM_DROPFILES")
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop

Case $GUI_EVENT_DROPPED
If $__aDropFiles[0] > 0 Then
_ArrayDisplay($__aDropFiles)
EndIf

EndSwitch
WEnd
GUIDelete($hGUI)
EndFunc ;==>Example

Func WM_DROPFILES($hWnd, $iMsg, $iwParam, $ilParam)
#forceref $hWnd, $ilParam
Switch $iMsg
Case $WM_DROPFILES
Local $aReturn = _WinAPI_DragQueryFileEx($iwParam)
If IsArray($aReturn) Then
$__aDropFiles = $aReturn
Else
Local $aError[1] = [0]
$__aDropFiles = $aError
EndIf
EndSwitch
Return $GUI_RUNDEFMSG
EndFunc ;==>WM_DROPFILES
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ExitCheckTextChange ==

{{Snippet Header
| AuthorURL = 8007-negativenrg
| AuthorName = NegativeNrG
}}

<syntaxhighlight lang="autoit">
;Check(when Exit), if Text is not equal to $e_to Then, prompt the user to save or not save.
;_ExitCheckText Change $Edit Handle, $title of messagebox, $message of messagebox, $equal to(default = NULL).

Func _ExitCheckTextChange($E_hnd,$title,$message,$e_to = '')
Local $buffer, $choice, $filetosave, $handle1
$buffer = GUIctrlread($E_hnd)
If $buffer <> $e_to Then
$choice = Msgbox(4,$title,$message)
If $choice = 6 Then
$filetosave = FileSaveDialog('Choose File',@scriptdir,'(*.au3)')
$handle1 = FileOpen($filetosave,2)
FileWrite($handle1,$buffer)
Exit
Elseif $choice <> 6 Then
Exit
EndIf
Else
Exit
EndIf
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileDeleteEx ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Ref: http://msdn.microsoft.com/en-us/library/windows/desktop/aa365240(v=vs.85).aspx

#include <APIFilesConstants.au3>
#include <WinAPIFiles.au3>

ConsoleWrite(_FileDeleteEx("C:\Example.dat") & @CRLF)

Func _FileDeleteEx($sFilePath)
Return FileDelete($sFilePath) = 1 ? 1 : Int(_WinAPI_MoveFileEx(FileGetShortName($sFilePath), "", $MOVE_FILE_DELAY_UNTIL_REBOOT))
EndFunc ;==>_FileDeleteEx
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileCheck ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

; Check if the file was modified less than 24 hours ago.
ConsoleWrite( _FileCheck(@ScriptFullPath, 24) & @CRLF)

Func _FileCheck($sFilePath, $iHours = 24)
Local $aTime
If FileExists($sFilePath) = 0 Then
Return SetError(1, 0, 0)
EndIf
$aTime = FileGetTime($sFilePath, 0, 0)
Return Number(_DateDiff("h", $aTime[0] & "/" & $aTime[1] & "/" & $aTime[2] & " " & $aTime[3] & ":" & $aTime[4] & ":" & $aTime[5], @YEAR & "/" & @MON & "/" & @MDAY & " " & @HOUR & ":" & @MIN & ":" & @SEC) < $iHours)
EndFunc ;==>_FileCheck
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileCreateEx ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
_FileCreateEx(@ScriptDir & '\ExampleFile.txt', 42)

; Create a blank file with a certain size in bytes.
Func _FileCreateEx($sFilePath, $iBytes = 0)
Return RunWait(@ComSpec & ' /c fsutil file createnew "' & $sFilePath & '" ' & Int($iBytes), @WorkingDir, @SW_HIDE)
EndFunc ;==>_FileCreateEx
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileID ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

FileClose(FileOpen(@ScriptDir & '\ExampleFile.txt', 2))
ConsoleWrite(_FileID(@ScriptDir & '\ExampleFile.txt') & @CRLF)
FileDelete(@ScriptDir & '\ExampleFile.txt')

; Rerieve the file id of a filepath.
Func _FileID($sFilePath)
Local $iPID = Run(@ComSpec & ' /c fsutil file queryfileid "' & $sFilePath & '"', @SystemDir, @SW_HIDE, $STDOUT_CHILD + $STDERR_CHILD), $sReturn = ''
While 1
$sReturn &= StdoutRead($iPID)
If @error Then
ExitLoop
EndIf
WEnd
Return StringStripWS(StringRegExpReplace($sReturn, 'File\sID\sis\s(.*?)', '$1'), 8)
EndFunc ;==>_FileID
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileExistsWithQuotes ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_FileExistsWithQuotes('"' & @ScriptDir & '"') & @CRLF)
ConsoleWrite(_FileExistsWithQuotes("'" & @ScriptDir & "'") & @CRLF)
ConsoleWrite(_FileExistsWithQuotes(@ScriptDir) & @CRLF)

; Version: 1.00. AutoIt: V3.3.8.1
; Check a filepath ecists even if the path contains quotation marks.
Func _FileExistsWithQuotes($sFilePath)
Return FileExists(StringRegExpReplace($sFilePath, '^("|'')*([^"'']+)("|'')*$', '\2'))
EndFunc ;==>_FileExistsWithQuotes
</syntaxhighlight>

[[#top | ReturnToContents]]

== FileLineCount ==

{{Snippet Header
| AuthorURL = 71214-mkish
| AuthorName = MKISH
| Desc = Checks the number of lines in a file (useful for larger files as well)
}}

<syntaxhighlight lang="autoit">
; Author - MKISH

; Checks the number of lines in a file (useful for larger files as well)

#include <WinAPI.au3>

Local $FILE = "G:\WIN7\sources\boot.wim"
Local $COUNT = 0
Local $start = default
Local $res, $fLen, $err

While 1
$res = _HexSearch($FILE, StringToBinary("" & @crlf), $start)
$start = $res + 2
$COUNT = $COUNT + 1
If $res = -1 then exitloop
Wend

msgbox(64, "", "Lines count: " & $COUNT)

; _HexSearch function (originally written by Zinthose, modified by MKISH)
Func _HexSearch($FilePath, $BinaryValue, $StartOffset = Default)
Local $Buffer, $ptr, $hFile, $Result, $Read, $SearchValue, $Pos, $BufferSize = 2048
If $StartOffset = Default Then $StartOffset = 0
If Not FileExists($FilePath) Then Return SetError(1, @error, 0)
$fLen = FileGetSize($FilePath)
If $StartOffset > $fLen Then Return SetError(2, @error, 0)
If Not IsBinary($BinaryValue) Then Return SetError(3, @error, 0)
If Not IsNumber($StartOffset) Then Return SetError(4, @error, 0)
$SearchValue = BinaryToString($BinaryValue)
$Buffer = DllStructCreate("byte[" & $BufferSize & "]")
$ptr = DllStructGetPtr($Buffer)
$hFile = _WinAPI_CreateFile($FilePath, 2, 2, 1)
If $hFile = 0 Then Return SetError(5, @error, 0)
$Result = _WinAPI_SetFilePointer($hFile, $StartOffset)
$err = @error
If $Result = 0xFFFFFFFF Then
_WinAPI_CloseHandle($hFile)
Return SetError(5, $err, 0)
EndIf
$Pos = $StartOffset
While True
$Read = 0
$Result = _WinAPI_ReadFile($hFile, $ptr, $BufferSize, $Read)
$err = @error
If Not $Result Then
_WinAPI_CloseHandle($hFile)
Return SetError(6, $err, 0)
EndIf
$Result = DllStructGetData($Buffer, 1)
$Result = BinaryToString($Result)
$Result = StringInStr($Result, $SearchValue)
If $Result > 0 Then ExitLoop
If $Read < $BufferSize Then
_WinAPI_CloseHandle($hFile)
Return -1
EndIf
$Pos += $Read

WEnd
_WinAPI_CloseHandle($hFile)
If Not $Result Then Return SetError(7, @error, 0)
$Result = $Pos + $Result - 1
Return $Result
EndFunc; ==> _HexSearch
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileOpenDialog ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Local $sFilePath = _FileOpenDialog("", "", "Images (*.jpg;*.bmp)|Videos (*.avi;*.mpg)", Random(1, @DesktopWidth, 1), Random(1, @DesktopHeight, 1), 1 + 4, "")

ConsoleWrite('File = ' & $sFilePath & ', @error = ' & @error & @CRLF)

; #FUNCTION# ====================================================================================================================
; Name ..........: _FileOpenDialog
; Description ...: Initiates a Open File Dialog with the option to set the position of the GUI.
; Syntax ........: _FileOpenDialog($sTitle, $sIntitialDirectory, $sFilter[, $iLeft = -1[, $iTop = -1[, $iOptions = 0[,
; $sDefaultName = ""]]]])
; Parameters ....: $sTitle - Title text of the Dialog GUI.
; $sIntitialDirectory - Initial directory selected in the GUI file tree.
; $sFilter - File type single filter such as "All (*.*)" or "Text files (*.txt)".
; $iLeft - [optional] The left side of the dialog box. By default (-1), the window is centered.
; $iTop - [optional] The top of the dialog box. Default (-1) is centered
; $iOptions - [optional] Dialog Options: To use more than one option, add the required values together. See FileOpenDialog. Default is 0.
; $sDefaultName - [optional] Suggested file name for the user to open. Default is blank ("").
; Return values .: Success: Returns the full path of the file(s) chosen. Results for multiple selections are "Directory|file1|file2|..."
; Failure: Sets @error to non-zero.
; Author ........: guinness
; Remarks........: This doesn't change the working directory of the script like FileOpenDialog does.
; Example .......: Yes
; ===============================================================================================================================
Func _FileOpenDialog($sTitle, $sIntitialDirectory, $sFilter, $iLeft = -1, $iTop = -1, $iOptions = 0, $sDefaultName = "")
Local $hGUI = GUICreate('', -1, -1, $iLeft, $iTop), $sWorkingDir = @WorkingDir
Local $sFilePath = FileOpenDialog($sTitle, $sIntitialDirectory, $sFilter, $iOptions, $sDefaultName, $hGUI)
Local $iError = @error
FileChangeDir($sWorkingDir)
Return SetError($iError, GUIDelete($hGUI), $sFilePath)
EndFunc ;==>_FileOpenDialog()
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileRename ==

{{Snippet Header
| AuthorURL = 52374-johnone
| AuthorName = JohnOne
}}

<syntaxhighlight lang="autoit">
;### Rename a file ###
;$sFile = Full path to file
;$sRename = New Filename
;$iOverWrite = 0 or 1

;Success returns 1
;failure, returns 0 and sets @error
; 1 if FileMove fails,
; 2 if $sFile does not exist
;@extended
; 0 if the new file does not already exist / existed
; 1 if the new file already exists / existed

;#### Example ####
$File = @ScriptDir & '\filetorename.txt'
FileWrite($File, 'Test')
_FileRename($File, 'newname.txt')
If @error Then MsgBox(0, "Error", @error)

Func _FileRename($sFile, $sRename, $iOverWrite = 0)
Local Const $FILENOTEXIST = 2
If Not FileExists($sFile) Then Return SetError($FILENOTEXIST, 0, 0)
Local $_StringLen = StringLen($sFile)
Local $_StringInStr = StringInStr($sFile, "\", 0, -1, $_StringLen)
Local $_Count = $_StringLen - $_StringInStr
Local $_Dir = StringLeft($sFile, $_StringInStr)
Local $_NewFile = $_Dir & $sRename
Local $_NewFileExists = FileExists($_NewFile)
Local $_FileMove = FileMove($sFile, $_NewFile, $iOverWrite)
Return SetError(Not $_FileMove, $_NewFileExists, $_FileMove)
EndFunc ;==>_FileRename
</syntaxhighlight>

== _FileRename Alternative ==

<syntaxhighlight lang="autoit">

;FileRename(PathFile, RenameFile)
;JohnOne

FileRename(@ScriptDir & "\rename.txt", @ScriptDir & "\renamed.txt")

Func FileRename($FileName, $ReName)

Local $SHFILEOPSTRUCT, $SourceStruct, $DestStruct
Local Const $FO_RENAME = 0x0004
Local Const $FOF_SILENT = 0x0004
Local Const $FOF_NOCONFIRMATION = 0x0010
Local Const $FOF_NOERRORUI = 0x0400
Local Const $FOF_NOCONFIRMMKDIR = 0x0200
Local Const $NULL = 0

$SourceStruct = _StringToStruct($FileName)
$DestStruct = _StringToStruct($ReName)

$SHFILEOPSTRUCT = DllStructCreate("hwnd hWnd;uint wFunc;ptr pFrom;ptr pTo;int fFlags;int fAnyOperationsAborted;ptr hNameMappings;ptr lpszProgressTitle")

DllStructSetData($SHFILEOPSTRUCT, "hWnd", $NULL)
DllStructSetData($SHFILEOPSTRUCT, "wFunc", $FO_RENAME)
DllStructSetData($SHFILEOPSTRUCT, "pFrom", DllStructGetPtr($SourceStruct))
DllStructSetData($SHFILEOPSTRUCT, "pTo", DllStructGetPtr($DestStruct))
DllStructSetData($SHFILEOPSTRUCT, "fFlags", BitOR($FOF_SILENT, $FOF_NOCONFIRMATION, $FOF_NOERRORUI, $FOF_NOCONFIRMMKDIR))
DllStructSetData($SHFILEOPSTRUCT, "fAnyOperationsAborted", $NULL)
DllStructSetData($SHFILEOPSTRUCT, "hNameMappings", $NULL)
DllStructSetData($SHFILEOPSTRUCT, "lpszProgressTitle", $NULL)

$acall = DllCall("shell32.dll", "int", "SHFileOperation", "ptr", DllStructGetPtr($SHFILEOPSTRUCT))
If @error Then
Return SetError(@error, @extended, 0)
EndIf
Return 1
EndFunc ;==>FileRename

Func _StringToStruct($string)

Local $iLen = StringLen($string)
Local $Struct = DllStructCreate("char[" & String($iLen + 2) & "]")
DllStructSetData($Struct, 1, $string)
DllStructSetData($Struct, 1, 0, $iLen + 1)
DllStructSetData($Struct, 1, 0, $iLen + 2)

Return $Struct
EndFunc ;==>_StringToStruct

</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetFolderDepth ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Autoit 3.3.5.4 and Below
ConsoleWrite(_GetFolderDepth(@ScriptDir & '') & @CRLF)
ConsoleWrite(_GetFolderDepth(@ScriptDir) & @CRLF)
ConsoleWrite(_GetFolderDepth(@ScriptFullPath) & @CRLF)

; Get the folder depth of a filepath.
Func _GetFolderDepth($sFilePath)
If StringInStr($sFilePath, '.', 2, -1) Then
$sFilePath = StringLeft($sFilePath, StringInStr($sFilePath, "", 2, -1) - 1)
EndIf
Local $aArray = StringSplit(StringRegExpReplace($sFilePath, '[/]+z', ''), '')
Return $aArray[0] - 1
EndFunc ;==>_GetFolderDepth
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetFolderDepth ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Autoit 3.3.5.4 and Above
ConsoleWrite(_GetFolderDepth(@ScriptDir & '') & @CRLF)
ConsoleWrite(_GetFolderDepth(@ScriptDir) & @CRLF)
ConsoleWrite(_GetFolderDepth(@ScriptFullPath) & @CRLF)

; Get the folder depth of a filepath. Works with V3.3.5.4+
Func _GetFolderDepth($sFilePath)
If StringInStr($sFilePath, '.', 2, -1) Then
$sFilePath = StringLeft($sFilePath, StringInStr($sFilePath, "", 2, -1) - 1)
EndIf
Return StringSplit(StringRegExpReplace($sFilePath, '[/]+z', ''), '')[0] - 1
EndFunc ;==>_GetFolderDepth
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsDir ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite("IsDir: Using a file - " & IsDir(@ScriptFullPath) & @CRLF) ; Return 0
ConsoleWrite("IsDir: Using a directory - " & IsDir(@ScriptDir) & @CRLF) ; Return 1

Func IsDir($sFilePath)
Return Int(FileExists($sFilePath) And StringInStr(FileGetAttrib($sFilePath), 'D', Default, 1) > 0)
EndFunc ;==>IsDir
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite('IsFile: Using a file - ' & IsFile(@ScriptFullPath) & @CRLF) ; Return 1
ConsoleWrite('IsFile: Using a directory - ' & IsFile(@ScriptDir) & @CRLF) ; Return 0

Func IsFile($sFilePath)
Return Int(FileExists($sFilePath) And StringInStr(FileGetAttrib($sFilePath), 'D', Default, 1) = 0)
EndFunc ;==>IsFilee
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsFileDiff ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_IsFileDiff(@ScriptFullPath, @ScriptFullPath) & @CRLF) ; This will return False as the files are exactly the same.
ConsoleWrite(_IsFileDiff(@ScriptFullPath, @AutoItExe) & @CRLF) ; This will return True as the files are different.

; Check if a file is different.
Func _IsFileDiff($sFilePath_1, $sFilePath_2)
Return RunWait(@ComSpec & ' /c FC /B /W "' & $sFilePath_1 & '" "' & $sFilePath_2 & '"', @WorkingDir, @SW_HIDE) > 0
EndFunc ;==>_IsFileDiff
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsFileOlder ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <Date.au3> ; Required for _DateDiff()
#include <MsgBoxConstants.au3>
#include <MsgBoxConstants.au3>

; Check if the current script is older than 10 days.
If _IsFileOlder(@ScriptFullPath, 10) Then
MsgBox($MB_SYSTEMMODAL, '', 'File is older than 10 days.')
Else
MsgBox($MB_SYSTEMMODAL, '', 'File isn''t older than 10 days.')
EndIf

; Is a file older than a certain number of days.
Func _IsFileOlder($sFilePath, $iDays)
Local $aArray = FileGetTime($sFilePath, $FT_CREATED)
Return _DateDiff('D', $aArray[0] & '/' & $aArray[1] & '/' & $aArray[2] & ' ' & $aArray[3] & ':' & $aArray[4] & ':' & $aArray[5], @YEAR & '/' & @MON & '/' & @MDAY & ' ' & @HOUR & ':' & @MIN & ':' & @SEC) >= $iDays
EndFunc ;==>_IsFileOlder
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsFileSame ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_IsFileSame(@ScriptFullPath, @ScriptFullPath) & @CRLF) ; This will return True as the files are exactly the same.
ConsoleWrite(_IsFileSame(@ScriptFullPath, @AutoItExe) & @CRLF) ; This will return False as the files are different.

; Check if a file is the same.
Func _IsFileSame($sFilePath_1, $sFilePath_2)
Return RunWait(@ComSpec & ' /c FC /B /W "' & $sFilePath_1 & '" "' & $sFilePath_2 & '"', @WorkingDir, @SW_HIDE) = 0
EndFunc ;==>_IsFileSame
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IniReadFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

__INIFileFill(@ScriptDir & '\Example.ini') ; Create an INI file with random data.

Local $aArray = _IniReadFile(@ScriptDir & '\Example.ini')
FileDelete(@ScriptDir & '\Example.ini')
_ArrayDisplay($aArray)

Func _IniReadFile($sFilePath)
Local $aReturn[1][3] = [[0, 3]], $aSectionArray, $aSectionNameArray, $iCount = 0
$aSectionNameArray = IniReadSectionNames($sFilePath)
If @error Then
Return SetError(1, 0, $aReturn)
EndIf
For $A = 1 To $aSectionNameArray[0]
$aSectionArray = IniReadSection($sFilePath, $aSectionNameArray[$A])
If @error Then
ContinueLoop
EndIf
For $B = 1 To $aSectionArray[0][0]
$aReturn[0][0] += 1
$iCount += 1
If $aReturn[0][0] <= $iCount + 1 Then
ReDim $aReturn[$aReturn[0][0] * 2][$aReturn[0][1]]
EndIf
$aReturn[$iCount][0] = $aSectionArray[$B][0]
$aReturn[$iCount][1] = $aSectionArray[$B][1]
$aReturn[$iCount][2] = $aSectionNameArray[$A]
Next
Next
ReDim $aReturn[$aReturn[0][0] + 1][$aReturn[0][1]] ; Remove empty entries.
Return $aReturn
EndFunc ;==>_IniReadFile

Func __INIFileFill($sFilePath)
Local $sData = '', $sHeader = ''

For $i = 1 To Random(1, 5, 1)
$sHeader = _RandomText(Random(5, 25, 1))
$sData = ""
For $j = 1 To Random(1, 25, 1)
$sData &= _RandomText(Random(5, 25, 1)) & '=' & _RandomText(Random(5, 25, 1)) & @LF
Next
IniWriteSection($sFilePath, $sHeader, $sData)
Next
EndFunc ;==>__FillINIFile

Func _RandomText($iLength = 10)
Local $sData = '', $sRandom = ''
For $i = 1 To $iLength
$sRandom = Random(55, 116, 1)
$sData &= Chr($sRandom + 6 * ($sRandom > 90) - 7 * ($sRandom < 65))
Next
Return $sData
EndFunc ;==>_RandomText
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IniReadInit ==

{{Snippet Header
| AuthorURL = 9370-mlowery
| AuthorName = mlowery
}}

<syntaxhighlight lang="autoit">
;===============================================================================
; Description: Reads values from INI or creates INI with initial values.
; Intended to ensure all available INI settings are exposed
; and editable.
; Parameters are identical to IniRead()
; Parameter(s): $filename = filename of INI
; $section = section name of INI
; $key = key name in section
; $default = default value (written to INI if not exists)
; Requirement(s): None
; Return Value(s): Returns value from INI (or default if not defined)
; Note(s): Chr(127) used to detect non-existing value since won't normally exist in a text file
;===============================================================================
Func _IniReadInit($filename, $section, $key, $default)
Local $value = IniRead($filename, $section, $key, Chr(127))
If $value = Chr(127) Then
IniWrite($filename, $section, $key, $default)
$value = $default
EndIf
Return $value
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsValidFileType ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(@ScriptFullPath & " >> " & _IsValidFileType(@ScriptFullPath, "bat;cmd;au3") & @CRLF)
ConsoleWrite(@AutoItExe & " >> " & _IsValidFileType(@AutoItExe, "bat;cmd;au3") & @CRLF)

; Check if a filepath matches an extension filetype. Based on the idea by guinness - http://www.autoitscript.com/forum/topic/123674-isvalidfiletype/
Func _IsValidFileType($sFilePath, $sList = "bat;cmd;exe") ; By AZJIO - http://www.autoitscript.com/forum/topic/...filetype/page__view__findpost_
Local $iDot = StringInStr($sFilePath, ".", 0, -1)
Return $iDot And StringInStr(';' & $sList & ';', ';' & StringTrimLeft($sFilePath, $iDot) & ';') > 0
EndFunc ;==>_IsValidFileType
</syntaxhighlight>

<syntaxhighlight lang="autoit">
; Example 2

#include <WinAPIEx.au3>

ConsoleWrite(@ScriptFullPath & " >> " & _IsValidFileType(@ScriptFullPath, "bat;cmd;au3") & @CRLF)
ConsoleWrite(@AutoItExe & " >> " & _IsValidFileType(@AutoItExe, "bat;cmd;au3") & @CRLF)

; Check if a filepath matches an extension filetype. Based on the idea by guinness - http://www.autoitscript.com/forum/topic/123674-isvalidfiletype/
Func _IsValidFileType($sFilePath, $sList = "bat;cmd;exe", $iOpFast = 1) ; By Yashied.
If StringStripWS($sList, 8) = "" Then
$sList = "*"
EndIf
Return _WinAPI_PathMatchSpec($sFilePath, StringReplace(';' & $sList, ';', ';*.', 0, $iOpFast * 2))
EndFunc ;==>_IsValidFileType
</syntaxhighlight>

[[#top | ReturnToContents]]

== File Open/Save/Folder Dialog Box ==

{{Snippet Header
| AuthorURL = 2709-mhz
| AuthorName = MHz
| AuthorURL2 = 4997-odklizec
| AuthorName2 = odklizec
| AuthorURL3 = 6756-danny35d
| AuthorName3 = Danny35d
}}

<syntaxhighlight lang="autoit">
; Center - File Open/Save/Folder Dialog Box
; Author - odklizec, MHz, Danny35d

If StringInStr($cmdlineraw, '/MoveWin') Then
Local $size, $PosX, $PosY
$cmdlineraw = StringSplit(StringMid($cmdlineraw, StringInStr($cmdlineraw, '/MoveWin')), ':')
While 1
Select
Case WinExists($cmdlineraw[2])
$size=WinGetPos ($cmdlineraw[2])
$PosX=@DesktopWidth/2 - $size[2]/2
$PosY=@DesktopHeight/2 - $size[3]/2
WinMove($cmdlineraw[2], "", $PosX, $PosY)
WinActivate($cmdlineraw[2])
ExitLoop
EndSelect
Sleep(50)
WEnd
Exit
EndIf
Global $PID, $Read_File, $Save_File
$PID = _FindBrowseWin('Open file Dialog Box')
$Read_File = FileOpenDialog ( "Open file Dialog Box", @ScriptDir & "\", "AutoIt Files (*.au3)",3,@ScriptFullPath)
ProcessClose($PID)
$PID = _FindBrowseWin('Save file Dialog Box')
$Save_File = FileSaveDialog( "Save file Dialog Box", @ScriptDir, "Scripts (*.aut;*.au3)", 3)
ProcessClose($PID)
$PID = _FindBrowseWin('Browse for Folder')
FileSelectFolder("Choose a folder with plugins..", "","4","c:\")
ProcessClose($PID)

Func _FindBrowseWin($sTitle)
If @Compiled Then
Return(Run(@ScriptFullPath & ' /MoveWin:' & $sTitle))
Else
Return(Run(@AutoItExe & ' "' & @ScriptFullPath & '" /MoveWin:' & $sTitle))
EndIf
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _MoveFileOnReboot ==

{{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.2.0, Creation Date = 21/03/12.

; Function to Move or Delete a file on next reboot!
Func _MoveFileOnReboot($sSourcePath, $sDestPath = ""); If $sDestPath = "" the file is deleted instead of moved.
Local $iRet

; PendingFileRenameOperations (HKLM\SYSTEM\CurrentControlSet\Control\Session Manager)
If $DestPath = "" Then
$iRet = DllCall("kernel32.dll", "int", "MoveFileExA", "str", $sSourcePath, "int", 0, "dword", 4)
Else
$iRet = DllCall("kernel32.dll", "int", "MoveFileExA", "str", $sSourcePath, "str", $sDestPath, "dword", 4)
EndIf

Return $iRet
EndFunc ;==>_MoveFileOnReboot
</syntaxhighlight>

[[#top | ReturnToContents]]

== _MultipleFileOpenDialog ==

{{Snippet Header
| AuthorURL =
| AuthorName = /dev/null
}}

<syntaxhighlight lang="autoit">
Local $message = "Hold down Ctrl or Shift to choose multiple files."

Local $filename = _MultipleFileOpenDialog($message,300,300)

Local $var = FileOpenDialog($message, @WindowsDir & "\", "Images (*.jpg;*.bmp)", 1 + 4 )

If @error Then
MsgBox(4096,"","No File(s) chosen")
Else
$var = StringReplace($var, "|", @CRLF)
MsgBox(4096,"","You chose " & $var)
EndIf

FileDelete($filename)
func _MultipleFileOpenDialog($title,$posx,$posy)
Local $temp = EnvGet("temp")
Local $filename = $temp & "\move_file_open_dialog.au3"

Local $script = 'Global $title = "' & $title & '"' & @CRLF
$script &= 'Global $pos_x = ' & $posx & @CRLF
$script &= 'Global $pos_y = ' & $posy & @CRLF
$script &= 'AdlibRegister("_Move",10)' & @CRLF
$script &= 'while 1' & @CRLF
$script &= ' sleep(1000)' & @CRLF
$script &= 'wend' & @CRLF
$script &= 'Func _Move()' & @CRLF
$script &= ' if (WinActive($title)) Then' & @CRLF
$script &= ' WinMove($title,"",$pos_x,$pos_y)' & @CRLF
$script &= ' Exit' & @CRLF
$script &= ' EndIf' & @CRLF
$script &= 'EndFunc' & @CRLF

FileWrite($filename,$script)
;MsgBox(0,"",$script & @CRLF & $filename)
Run(@AutoItExe & " /AutoIt3ExecuteScript " & $filename)
sleep(250)
Return $filename
EndFunc ;==>_MultipleFileOpenDialog()
</syntaxhighlight>

[[#top | ReturnToContents]]

== _OpenFolder ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#cs
These have been declared in Global scope as you may wish to use them elsewhere in your script.
#ce
Global $ALTSTARTUP = 0x1d
Global $APPDATA = 0x1a
Global $BITBUCKET = 0x0a
Global $COMMONALTSTARTUP = 0x1e
Global $COMMONAPPDATA = 0x23
Global $COMMONDESKTOPDIR = 0x19
Global $COMMONFAVORITES = 0x1f
Global $COMMONPROGRAMS = 0x17
Global $COMMONSTARTMENU = 0x16
Global $COMMONSTARTUP = 0x18
Global $CONTROLS = 0x03
Global $COOKIES = 0x21
Global $DESKTOP = 0x00
Global $DESKTOPDIRECTORY = 0x10
Global $DRIVES = 0x11
Global $FAVORITES = 0x06
Global $FONTS = 0x14
Global $HISTORY = 0x22
Global $INTERNETCACHE = 0x20
Global $LOCALAPPDATA = 0x1c
Global $MYPICTURES = 0x27
Global $NETHOOD = 0x13
Global $NETWORK = 0x12
Global $PERSONAL = 0x05
Global $PRINTERS = 0x04
Global $PRINTHOOD = 0x1b
Global $PROFILE = 0x28
Global $PROGRAMFILES = 0x26
Global $PROGRAMFILESx86 = 0x30
Global $PROGRAMS = 0x02
Global $RECENT = 0x08
Global $SENDTO = 0x09
Global $STARTMENU = 0x0b
Global $STARTUP = 0x07
Global $SYSTEM = 0x25
Global $SYSTEMx86 = 0x29
Global $TEMPLATES = 0x15
Global $WINDOWS = 0x24

ConsoleWrite(_OpenFolder(@ScriptDir) & @CRLF)
ConsoleWrite(_OpenFolder($PRINTERS) & @CRLF)

; Open a folder or special folder variable, similar to using ShellExecute.
Func _OpenFolder($sFolderPath)
Local $oShell = ObjCreate('shell.application')
If @error Then
Return SetError(1, 0, 0)
EndIf
$oShell.Open($sFolderPath)
Return 1
EndFunc ;==>_OpenFolder
</syntaxhighlight>

[[#top | ReturnToContents]]

== _PathAppendToFilename ==

{{Snippet Header
| AuthorURL = 31965-progandy
| AuthorName = ProgAndy
}}

<syntaxhighlight lang="autoit">
$sOrg = "C:\Some.Folder\some.file.ext"
$sAdd = "_backup"

$sNew = _PathAppendToFilename($sOrg, $sAdd)

$sStripped = _PathStripRightFromFilename($sNew, $sAdd)

MsgBox(0, "", $sOrg & @CRLF & $sAdd & @CRLF & $sNew & @CRLF & $sStripped)

Func _PathAppendToFilename($sName, $sAppend)
; Author: ProgAndy
If StringRegExp($sAppend, '[\/\\:\?"<>\|\*]') Then Return SetError(1, 0, $sName)
Return StringRegExpReplace($sName, "(\.[^\\/\.]+)$", $sAppend & "\1", 1)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _PathStripRightFromFilename ==

{{Snippet Header
| AuthorURL = 31965-progandy
| AuthorName = ProgAndy
}}

<syntaxhighlight lang="autoit">
Func _PathStripRightFromFilename($sName, $sStrip)
; Author: ProgAndy
If StringRegExp($sStrip, '[\/\\:\?"<>\|\*]') Then Return SetError(1, 0, $sName)
Return StringRegExpReplace($sName, "\Q" & $sStrip & "\E(\.[^\\/\.]+)$", "\1", 1)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SelfDelete ==

{{Snippet Header
| AuthorURL = 2709-mhz
| AuthorName = MHz
}}

<syntaxhighlight lang="autoit">
; This also removes the directory which the file is in
; Author MHz with the directory delete addition by The Kandie Man
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 _
& ':loop2' & @CRLF _
& 'rmdir /q "' & $dirToDelete & '"' & @CRLF _
& 'if exist "' & $dirToDelete & '" goto loop2' & @CRLF _
& 'del ' & @TempDir & '\scratch.bat'
FileWrite(@TempDir & "\scratch.bat", $sCmdFile)
Run(@TempDir & "\scratch.bat", @TempDir, @SW_HIDE)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ShellExecuteFileSelectFolder ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_ShellExecuteFileSelectFolder('Select a Folder', @HomeDrive) & @CRLF)

; Shell Execute a selected folder.
Func _ShellExecuteFileSelectFolder($sText, $sRoot, $iFlag = 0, $sInitialDir = '', $hWnd = '')
Local $sFolder = FileSelectFolder($sText, $sRoot, $iFlag, $sInitialDir, $hWnd)
If @error Then
Return SetError(@error, @extended, '')
EndIf
ShellExecute($sFolder)
Return $sFolder
EndFunc ;==>_ShellExecuteFileSelectFolder
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SuiCide ==

{{Snippet Header
| AuthorURL = 28010-larrydalooza
| AuthorName = LarryDalooza
}}

<syntaxhighlight lang="autoit">
; IMPORTANT MAKE A COPY OF SCRIPT BEFORE DELETION
; Deletes the running script

Func SuiCide()
Local $sFilePath = @TempDir & '\SuiCide.bat'
FileDelete($sFilePath)
FileWrite($sFilePath, 'loop:' & @CRLF & 'del "' & @ScriptFullPath & '"' & @CRLF & _
'ping -n 1 -w 250 zxywqxz_q' & @CRLF & 'if exist "' & @ScriptFullPath & _
'" goto loop' & @CRLF & 'del SuiCide.bat' & @CRLF)
Exit Run($sFilePath, @TempDir, @SW_HIDE)
EndFunc ;==>SuiCide
</syntaxhighlight>

[[#top | ReturnToContents]]

== _UniqueFilename ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">

ConsoleWrite(_UniqueFilename(@ScriptDir, '.au3') & @CRLF)

Func _UniqueFilename($sFilePath, $sExtension)
Local $iRandom = 0, $sUnqiueFileName = ''

$sExtension = '.' & StringRegExpReplace($sExtension, '\A[\.]+', '')
$sFilePath = StringRegExpReplace($sFilePath, '[\\/]+\z', '') & '\'
While 1
$iRandom = Random(55, 116, 1)
$sUnqiueFileName &= Chr($iRandom + 6 * ($iRandom > 90) - 7 * ($iRandom < 65))
If FileExists($sFilePath & $sUnqiueFileName & $sExtension) = 0 And StringLen($sUnqiueFileName) > 7 Then
ExitLoop
EndIf
WEnd
Return $sFilePath & $sUnqiueFileName & $sExtension
EndFunc ;==>_UniqueFilename
</syntaxhighlight>

[[#top | ReturnToContents]]

== Windows - Copy With Progress ==

{{Snippet Header
| AuthorURL = 19-jos
| AuthorName = Jos
}}

<syntaxhighlight lang="autoit">
; Windows - Copy With Progress

;~ 4 Do not display a progress dialog box.
;~ 8 Give the file being operated on a new name in a move, copy, or rename operation if a file with the target name already exists.
;~ 16 Respond with "Yes to All" for any dialog box that is displayed.
;~ 64 Preserve undo information, if possible.
;~ 128 Perform the operation on files only if a wildcard file name (*.*) is specified.
;~ 256 Display a progress dialog box but do not show the file names.
;~ 512 Do not confirm the creation of a new directory if the operation requires one to be created.
;~ 1024 Do not display a user interface if an error occurs.
;~ 2048 Version 4.71. Do not copy the security attributes of the file.
;~ 4096 Only operate in the local directory. Don't operate recursively into subdirectories.
;~ 8192 Version 5.0. Do not copy connected files as a group. Only copy the specified files.

_FileCopy("C:\Installed Apps\Patches\WindowsXP-KB835935-SP2-ENU.exe","C:\temp")

; to copy a directory the destination directory must exist

Func _FileCopy($fromFile,$tofile)
Local $FOF_RESPOND_YES = 16
Local $FOF_SIMPLEPROGRESS = 256
$winShell = ObjCreate("shell.application")
$winShell.namespace($tofile).CopyHere($fromFile,$FOF_RESPOND_YES)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

Snippets ( Files & Folders )

2014-05-12T19:34:08Z

Guinness: /* _IsFile */

__TOC__
[[category:Snippets]]

{{Snippet Credit Header}}

== _ConvertFileToUTF16 ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
_ConvertFileToUTF16(@ScriptDir & "\Example.xml")

Func _ConvertFileToUTF16($sFilePath)
Local $iEncoding = FileGetEncoding($sFilePath)
Local $hFileOpen = FileOpen($sFilePath, $iEncoding)
If $hFileOpen = -1 Then
Return SetError(1, 0, 0)
EndIf
Local $sData = FileRead($hFileOpen)
FileClose($hFileOpen)

$hFileOpen = FileOpen($sFilePath, 2 + 32)
If $hFileOpen = -1 Then
Return SetError(2, 0, 0)
EndIf
FileWrite($hFileOpen, $sData)
Return FileClose($hFileOpen)
EndFunc ;==>_ConvertFileToUTF16
</syntaxhighlight>

[[#top | ReturnToContents]]

== DropFiles ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
| Desc = Dropping multiple files onto a GUI
}}

<syntaxhighlight lang="autoit">
; Dropping multiple files onto a GUI

#include <APIConstants.au3>
#include <Array.au3>
#include <GUIConstantsEx.au3>
#include <WinAPIEx.au3>

Global $__aDropFiles

Example()

Func Example()
Local $hGUI = GUICreate('', 500, 500, -1, -1, -1, $WS_EX_ACCEPTFILES)

; Create a label that is transparent which will accept 'drop' events.
GUICtrlCreateLabel("", 0, 0, 500, 500)
GUICtrlSetBkColor(-1, $GUI_BKCOLOR_TRANSPARENT)
GUICtrlSetResizing(-1, $GUI_DOCKALL)
GUICtrlSetState(-1, $GUI_DROPACCEPTED)

GUIRegisterMsg($WM_DROPFILES, "WM_DROPFILES")
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop

Case $GUI_EVENT_DROPPED
If $__aDropFiles[0] > 0 Then
_ArrayDisplay($__aDropFiles)
EndIf

EndSwitch
WEnd
GUIDelete($hGUI)
EndFunc ;==>Example

Func WM_DROPFILES($hWnd, $iMsg, $iwParam, $ilParam)
#forceref $hWnd, $ilParam
Switch $iMsg
Case $WM_DROPFILES
Local $aReturn = _WinAPI_DragQueryFileEx($iwParam)
If IsArray($aReturn) Then
$__aDropFiles = $aReturn
Else
Local $aError[1] = [0]
$__aDropFiles = $aError
EndIf
EndSwitch
Return $GUI_RUNDEFMSG
EndFunc ;==>WM_DROPFILES
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ExitCheckTextChange ==

{{Snippet Header
| AuthorURL = 8007-negativenrg
| AuthorName = NegativeNrG
}}

<syntaxhighlight lang="autoit">
;Check(when Exit), if Text is not equal to $e_to Then, prompt the user to save or not save.
;_ExitCheckText Change $Edit Handle, $title of messagebox, $message of messagebox, $equal to(default = NULL).

Func _ExitCheckTextChange($E_hnd,$title,$message,$e_to = '')
Local $buffer, $choice, $filetosave, $handle1
$buffer = GUIctrlread($E_hnd)
If $buffer <> $e_to Then
$choice = Msgbox(4,$title,$message)
If $choice = 6 Then
$filetosave = FileSaveDialog('Choose File',@scriptdir,'(*.au3)')
$handle1 = FileOpen($filetosave,2)
FileWrite($handle1,$buffer)
Exit
Elseif $choice <> 6 Then
Exit
EndIf
Else
Exit
EndIf
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileDeleteEx ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Ref: http://msdn.microsoft.com/en-us/library/windows/desktop/aa365240(v=vs.85).aspx

#include <APIFilesConstants.au3>
#include <WinAPIFiles.au3>

ConsoleWrite(_FileDeleteEx("C:\Example.dat") & @CRLF)

Func _FileDeleteEx($sFilePath)
Return FileDelete($sFilePath) = 1 ? 1 : Int(_WinAPI_MoveFileEx(FileGetShortName($sFilePath), "", $MOVE_FILE_DELAY_UNTIL_REBOOT))
EndFunc ;==>_FileDeleteEx
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileCheck ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

; Check if the file was modified less than 24 hours ago.
ConsoleWrite( _FileCheck(@ScriptFullPath, 24) & @CRLF)

Func _FileCheck($sFilePath, $iHours = 24)
Local $aTime
If FileExists($sFilePath) = 0 Then
Return SetError(1, 0, 0)
EndIf
$aTime = FileGetTime($sFilePath, 0, 0)
Return Number(_DateDiff("h", $aTime[0] & "/" & $aTime[1] & "/" & $aTime[2] & " " & $aTime[3] & ":" & $aTime[4] & ":" & $aTime[5], @YEAR & "/" & @MON & "/" & @MDAY & " " & @HOUR & ":" & @MIN & ":" & @SEC) < $iHours)
EndFunc ;==>_FileCheck
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileCreateEx ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
_FileCreateEx(@ScriptDir & '\ExampleFile.txt', 42)

; Create a blank file with a certain size in bytes.
Func _FileCreateEx($sFilePath, $iBytes = 0)
Return RunWait(@ComSpec & ' /c fsutil file createnew "' & $sFilePath & '" ' & Int($iBytes), @WorkingDir, @SW_HIDE)
EndFunc ;==>_FileCreateEx
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileID ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

FileClose(FileOpen(@ScriptDir & '\ExampleFile.txt', 2))
ConsoleWrite(_FileID(@ScriptDir & '\ExampleFile.txt') & @CRLF)
FileDelete(@ScriptDir & '\ExampleFile.txt')

; Rerieve the file id of a filepath.
Func _FileID($sFilePath)
Local $iPID = Run(@ComSpec & ' /c fsutil file queryfileid "' & $sFilePath & '"', @SystemDir, @SW_HIDE, $STDOUT_CHILD + $STDERR_CHILD), $sReturn = ''
While 1
$sReturn &= StdoutRead($iPID)
If @error Then
ExitLoop
EndIf
WEnd
Return StringStripWS(StringRegExpReplace($sReturn, 'File\sID\sis\s(.*?)', '$1'), 8)
EndFunc ;==>_FileID
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileExistsWithQuotes ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_FileExistsWithQuotes('"' & @ScriptDir & '"') & @CRLF)
ConsoleWrite(_FileExistsWithQuotes("'" & @ScriptDir & "'") & @CRLF)
ConsoleWrite(_FileExistsWithQuotes(@ScriptDir) & @CRLF)

; Version: 1.00. AutoIt: V3.3.8.1
; Check a filepath ecists even if the path contains quotation marks.
Func _FileExistsWithQuotes($sFilePath)
Return FileExists(StringRegExpReplace($sFilePath, '^("|'')*([^"'']+)("|'')*$', '\2'))
EndFunc ;==>_FileExistsWithQuotes
</syntaxhighlight>

[[#top | ReturnToContents]]

== FileLineCount ==

{{Snippet Header
| AuthorURL = 71214-mkish
| AuthorName = MKISH
| Desc = Checks the number of lines in a file (useful for larger files as well)
}}

<syntaxhighlight lang="autoit">
; Author - MKISH

; Checks the number of lines in a file (useful for larger files as well)

#include <WinAPI.au3>

Local $FILE = "G:\WIN7\sources\boot.wim"
Local $COUNT = 0
Local $start = default
Local $res, $fLen, $err

While 1
$res = _HexSearch($FILE, StringToBinary("" & @crlf), $start)
$start = $res + 2
$COUNT = $COUNT + 1
If $res = -1 then exitloop
Wend

msgbox(64, "", "Lines count: " & $COUNT)

; _HexSearch function (originally written by Zinthose, modified by MKISH)
Func _HexSearch($FilePath, $BinaryValue, $StartOffset = Default)
Local $Buffer, $ptr, $hFile, $Result, $Read, $SearchValue, $Pos, $BufferSize = 2048
If $StartOffset = Default Then $StartOffset = 0
If Not FileExists($FilePath) Then Return SetError(1, @error, 0)
$fLen = FileGetSize($FilePath)
If $StartOffset > $fLen Then Return SetError(2, @error, 0)
If Not IsBinary($BinaryValue) Then Return SetError(3, @error, 0)
If Not IsNumber($StartOffset) Then Return SetError(4, @error, 0)
$SearchValue = BinaryToString($BinaryValue)
$Buffer = DllStructCreate("byte[" & $BufferSize & "]")
$ptr = DllStructGetPtr($Buffer)
$hFile = _WinAPI_CreateFile($FilePath, 2, 2, 1)
If $hFile = 0 Then Return SetError(5, @error, 0)
$Result = _WinAPI_SetFilePointer($hFile, $StartOffset)
$err = @error
If $Result = 0xFFFFFFFF Then
_WinAPI_CloseHandle($hFile)
Return SetError(5, $err, 0)
EndIf
$Pos = $StartOffset
While True
$Read = 0
$Result = _WinAPI_ReadFile($hFile, $ptr, $BufferSize, $Read)
$err = @error
If Not $Result Then
_WinAPI_CloseHandle($hFile)
Return SetError(6, $err, 0)
EndIf
$Result = DllStructGetData($Buffer, 1)
$Result = BinaryToString($Result)
$Result = StringInStr($Result, $SearchValue)
If $Result > 0 Then ExitLoop
If $Read < $BufferSize Then
_WinAPI_CloseHandle($hFile)
Return -1
EndIf
$Pos += $Read

WEnd
_WinAPI_CloseHandle($hFile)
If Not $Result Then Return SetError(7, @error, 0)
$Result = $Pos + $Result - 1
Return $Result
EndFunc; ==> _HexSearch
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileOpenDialog ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Local $sFilePath = _FileOpenDialog("", "", "Images (*.jpg;*.bmp)|Videos (*.avi;*.mpg)", Random(1, @DesktopWidth, 1), Random(1, @DesktopHeight, 1), 1 + 4, "")

ConsoleWrite('File = ' & $sFilePath & ', @error = ' & @error & @CRLF)

; #FUNCTION# ====================================================================================================================
; Name ..........: _FileOpenDialog
; Description ...: Initiates a Open File Dialog with the option to set the position of the GUI.
; Syntax ........: _FileOpenDialog($sTitle, $sIntitialDirectory, $sFilter[, $iLeft = -1[, $iTop = -1[, $iOptions = 0[,
; $sDefaultName = ""]]]])
; Parameters ....: $sTitle - Title text of the Dialog GUI.
; $sIntitialDirectory - Initial directory selected in the GUI file tree.
; $sFilter - File type single filter such as "All (*.*)" or "Text files (*.txt)".
; $iLeft - [optional] The left side of the dialog box. By default (-1), the window is centered.
; $iTop - [optional] The top of the dialog box. Default (-1) is centered
; $iOptions - [optional] Dialog Options: To use more than one option, add the required values together. See FileOpenDialog. Default is 0.
; $sDefaultName - [optional] Suggested file name for the user to open. Default is blank ("").
; Return values .: Success: Returns the full path of the file(s) chosen. Results for multiple selections are "Directory|file1|file2|..."
; Failure: Sets @error to non-zero.
; Author ........: guinness
; Remarks........: This doesn't change the working directory of the script like FileOpenDialog does.
; Example .......: Yes
; ===============================================================================================================================
Func _FileOpenDialog($sTitle, $sIntitialDirectory, $sFilter, $iLeft = -1, $iTop = -1, $iOptions = 0, $sDefaultName = "")
Local $hGUI = GUICreate('', -1, -1, $iLeft, $iTop), $sWorkingDir = @WorkingDir
Local $sFilePath = FileOpenDialog($sTitle, $sIntitialDirectory, $sFilter, $iOptions, $sDefaultName, $hGUI)
Local $iError = @error
FileChangeDir($sWorkingDir)
Return SetError($iError, GUIDelete($hGUI), $sFilePath)
EndFunc ;==>_FileOpenDialog()
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileRename ==

{{Snippet Header
| AuthorURL = 52374-johnone
| AuthorName = JohnOne
}}

<syntaxhighlight lang="autoit">
;### Rename a file ###
;$sFile = Full path to file
;$sRename = New Filename
;$iOverWrite = 0 or 1

;Success returns 1
;failure, returns 0 and sets @error
; 1 if FileMove fails,
; 2 if $sFile does not exist
;@extended
; 0 if the new file does not already exist / existed
; 1 if the new file already exists / existed

;#### Example ####
$File = @ScriptDir & '\filetorename.txt'
FileWrite($File, 'Test')
_FileRename($File, 'newname.txt')
If @error Then MsgBox(0, "Error", @error)

Func _FileRename($sFile, $sRename, $iOverWrite = 0)
Local Const $FILENOTEXIST = 2
If Not FileExists($sFile) Then Return SetError($FILENOTEXIST, 0, 0)
Local $_StringLen = StringLen($sFile)
Local $_StringInStr = StringInStr($sFile, "\", 0, -1, $_StringLen)
Local $_Count = $_StringLen - $_StringInStr
Local $_Dir = StringLeft($sFile, $_StringInStr)
Local $_NewFile = $_Dir & $sRename
Local $_NewFileExists = FileExists($_NewFile)
Local $_FileMove = FileMove($sFile, $_NewFile, $iOverWrite)
Return SetError(Not $_FileMove, $_NewFileExists, $_FileMove)
EndFunc ;==>_FileRename
</syntaxhighlight>

== _FileRename Alternative ==

<syntaxhighlight lang="autoit">

;FileRename(PathFile, RenameFile)
;JohnOne

FileRename(@ScriptDir & "\rename.txt", @ScriptDir & "\renamed.txt")

Func FileRename($FileName, $ReName)

Local $SHFILEOPSTRUCT, $SourceStruct, $DestStruct
Local Const $FO_RENAME = 0x0004
Local Const $FOF_SILENT = 0x0004
Local Const $FOF_NOCONFIRMATION = 0x0010
Local Const $FOF_NOERRORUI = 0x0400
Local Const $FOF_NOCONFIRMMKDIR = 0x0200
Local Const $NULL = 0

$SourceStruct = _StringToStruct($FileName)
$DestStruct = _StringToStruct($ReName)

$SHFILEOPSTRUCT = DllStructCreate("hwnd hWnd;uint wFunc;ptr pFrom;ptr pTo;int fFlags;int fAnyOperationsAborted;ptr hNameMappings;ptr lpszProgressTitle")

DllStructSetData($SHFILEOPSTRUCT, "hWnd", $NULL)
DllStructSetData($SHFILEOPSTRUCT, "wFunc", $FO_RENAME)
DllStructSetData($SHFILEOPSTRUCT, "pFrom", DllStructGetPtr($SourceStruct))
DllStructSetData($SHFILEOPSTRUCT, "pTo", DllStructGetPtr($DestStruct))
DllStructSetData($SHFILEOPSTRUCT, "fFlags", BitOR($FOF_SILENT, $FOF_NOCONFIRMATION, $FOF_NOERRORUI, $FOF_NOCONFIRMMKDIR))
DllStructSetData($SHFILEOPSTRUCT, "fAnyOperationsAborted", $NULL)
DllStructSetData($SHFILEOPSTRUCT, "hNameMappings", $NULL)
DllStructSetData($SHFILEOPSTRUCT, "lpszProgressTitle", $NULL)

$acall = DllCall("shell32.dll", "int", "SHFileOperation", "ptr", DllStructGetPtr($SHFILEOPSTRUCT))
If @error Then
Return SetError(@error, @extended, 0)
EndIf
Return 1
EndFunc ;==>FileRename

Func _StringToStruct($string)

Local $iLen = StringLen($string)
Local $Struct = DllStructCreate("char[" & String($iLen + 2) & "]")
DllStructSetData($Struct, 1, $string)
DllStructSetData($Struct, 1, 0, $iLen + 1)
DllStructSetData($Struct, 1, 0, $iLen + 2)

Return $Struct
EndFunc ;==>_StringToStruct

</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetFolderDepth ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Autoit 3.3.5.4 and Below
ConsoleWrite(_GetFolderDepth(@ScriptDir & '') & @CRLF)
ConsoleWrite(_GetFolderDepth(@ScriptDir) & @CRLF)
ConsoleWrite(_GetFolderDepth(@ScriptFullPath) & @CRLF)

; Get the folder depth of a filepath.
Func _GetFolderDepth($sFilePath)
If StringInStr($sFilePath, '.', 2, -1) Then
$sFilePath = StringLeft($sFilePath, StringInStr($sFilePath, "", 2, -1) - 1)
EndIf
Local $aArray = StringSplit(StringRegExpReplace($sFilePath, '[/]+z', ''), '')
Return $aArray[0] - 1
EndFunc ;==>_GetFolderDepth
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetFolderDepth ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Autoit 3.3.5.4 and Above
ConsoleWrite(_GetFolderDepth(@ScriptDir & '') & @CRLF)
ConsoleWrite(_GetFolderDepth(@ScriptDir) & @CRLF)
ConsoleWrite(_GetFolderDepth(@ScriptFullPath) & @CRLF)

; Get the folder depth of a filepath. Works with V3.3.5.4+
Func _GetFolderDepth($sFilePath)
If StringInStr($sFilePath, '.', 2, -1) Then
$sFilePath = StringLeft($sFilePath, StringInStr($sFilePath, "", 2, -1) - 1)
EndIf
Return StringSplit(StringRegExpReplace($sFilePath, '[/]+z', ''), '')[0] - 1
EndFunc ;==>_GetFolderDepth
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsDir ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite("IsDir: Using a file - " & IsDir(@ScriptFullPath) & @CRLF) ; Return 0
ConsoleWrite("IsDir: Using a directory - " & IsDir(@ScriptDir) & @CRLF) ; Return 1

Func IsDir($sFilePath)
Return Int(FileExists($sFilePath) And StringInStr(FileGetAttrib($sFilePath), 'D', Default, 1) > 0)
EndFunc ;==>IsDir
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite('IsFile: Using a file - ' & IsFile(@ScriptFullPath) & @CRLF) ; Return 1
ConsoleWrite('IsFile: Using a directory - ' & IsFile(@ScriptDir) & @CRLF) ; Return 0

Func IsFile($sFilePath)
Return Int(FileExists($sFilePath) And StringInStr(FileGetAttrib($sFilePath), 'D', Default, 1) = 0)
EndFunc ;==>IsFilee
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsFileDiff ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_IsFileDiff(@ScriptFullPath, @ScriptFullPath) & @CRLF) ; This will return False as the files are exactly the same.
ConsoleWrite(_IsFileDiff(@ScriptFullPath, @AutoItExe) & @CRLF) ; This will return True as the files are different.

; Check if a file is different.
Func _IsFileDiff($sFilePath_1, $sFilePath_2)
Return RunWait(@ComSpec & ' /c FC /B /W "' & $sFilePath_1 & '" "' & $sFilePath_2 & '"', @WorkingDir, @SW_HIDE) > 0
EndFunc ;==>_IsFileDiff
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsFileOlder ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <Date.au3> ; Required for _DateDiff()

; Check if the current script is older than 10 days.
If _IsFileOlder(@ScriptFullPath, 10) Then
MsgBox(4096, '', 'File is older than 10 days.')
Else
MsgBox(4096, '', 'File isn''t older than 10 days.')
EndIf

; Is a file older than a certain number of days.
Func _IsFileOlder($sFilePath, $iDays)
Local $aArray = FileGetTime($sFilePath, 0)
Return _DateDiff('D', $aArray[0] & '/' & $aArray[1] & '/' & $aArray[2] & ' ' & $aArray[3] & ':' & $aArray[4] & ':' & $aArray[5], @YEAR & '/' & @MON & '/' & @MDAY & ' ' & @HOUR & ':' & @MIN & ':' & @SEC) >= $iDays
EndFunc ;==>_IsFileOlder
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsFileSame ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_IsFileSame(@ScriptFullPath, @ScriptFullPath) & @CRLF) ; This will return True as the files are exactly the same.
ConsoleWrite(_IsFileSame(@ScriptFullPath, @AutoItExe) & @CRLF) ; This will return False as the files are different.

; Check if a file is the same.
Func _IsFileSame($sFilePath_1, $sFilePath_2)
Return RunWait(@ComSpec & ' /c FC /B /W "' & $sFilePath_1 & '" "' & $sFilePath_2 & '"', @WorkingDir, @SW_HIDE) = 0
EndFunc ;==>_IsFileSame
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IniReadFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

__INIFileFill(@ScriptDir & '\Example.ini') ; Create an INI file with random data.

Local $aArray = _IniReadFile(@ScriptDir & '\Example.ini')
FileDelete(@ScriptDir & '\Example.ini')
_ArrayDisplay($aArray)

Func _IniReadFile($sFilePath)
Local $aReturn[1][3] = [[0, 3]], $aSectionArray, $aSectionNameArray, $iCount = 0
$aSectionNameArray = IniReadSectionNames($sFilePath)
If @error Then
Return SetError(1, 0, $aReturn)
EndIf
For $A = 1 To $aSectionNameArray[0]
$aSectionArray = IniReadSection($sFilePath, $aSectionNameArray[$A])
If @error Then
ContinueLoop
EndIf
For $B = 1 To $aSectionArray[0][0]
$aReturn[0][0] += 1
$iCount += 1
If $aReturn[0][0] <= $iCount + 1 Then
ReDim $aReturn[$aReturn[0][0] * 2][$aReturn[0][1]]
EndIf
$aReturn[$iCount][0] = $aSectionArray[$B][0]
$aReturn[$iCount][1] = $aSectionArray[$B][1]
$aReturn[$iCount][2] = $aSectionNameArray[$A]
Next
Next
ReDim $aReturn[$aReturn[0][0] + 1][$aReturn[0][1]] ; Remove empty entries.
Return $aReturn
EndFunc ;==>_IniReadFile

Func __INIFileFill($sFilePath)
Local $sData = '', $sHeader = ''

For $i = 1 To Random(1, 5, 1)
$sHeader = _RandomText(Random(5, 25, 1))
$sData = ""
For $j = 1 To Random(1, 25, 1)
$sData &= _RandomText(Random(5, 25, 1)) & '=' & _RandomText(Random(5, 25, 1)) & @LF
Next
IniWriteSection($sFilePath, $sHeader, $sData)
Next
EndFunc ;==>__FillINIFile

Func _RandomText($iLength = 10)
Local $sData = '', $sRandom = ''
For $i = 1 To $iLength
$sRandom = Random(55, 116, 1)
$sData &= Chr($sRandom + 6 * ($sRandom > 90) - 7 * ($sRandom < 65))
Next
Return $sData
EndFunc ;==>_RandomText
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IniReadInit ==

{{Snippet Header
| AuthorURL = 9370-mlowery
| AuthorName = mlowery
}}

<syntaxhighlight lang="autoit">
;===============================================================================
; Description: Reads values from INI or creates INI with initial values.
; Intended to ensure all available INI settings are exposed
; and editable.
; Parameters are identical to IniRead()
; Parameter(s): $filename = filename of INI
; $section = section name of INI
; $key = key name in section
; $default = default value (written to INI if not exists)
; Requirement(s): None
; Return Value(s): Returns value from INI (or default if not defined)
; Note(s): Chr(127) used to detect non-existing value since won't normally exist in a text file
;===============================================================================
Func _IniReadInit($filename, $section, $key, $default)
Local $value = IniRead($filename, $section, $key, Chr(127))
If $value = Chr(127) Then
IniWrite($filename, $section, $key, $default)
$value = $default
EndIf
Return $value
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsValidFileType ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(@ScriptFullPath & " >> " & _IsValidFileType(@ScriptFullPath, "bat;cmd;au3") & @CRLF)
ConsoleWrite(@AutoItExe & " >> " & _IsValidFileType(@AutoItExe, "bat;cmd;au3") & @CRLF)

; Check if a filepath matches an extension filetype. Based on the idea by guinness - http://www.autoitscript.com/forum/topic/123674-isvalidfiletype/
Func _IsValidFileType($sFilePath, $sList = "bat;cmd;exe") ; By AZJIO - http://www.autoitscript.com/forum/topic/...filetype/page__view__findpost_
Local $iDot = StringInStr($sFilePath, ".", 0, -1)
Return $iDot And StringInStr(';' & $sList & ';', ';' & StringTrimLeft($sFilePath, $iDot) & ';') > 0
EndFunc ;==>_IsValidFileType
</syntaxhighlight>

<syntaxhighlight lang="autoit">
; Example 2

#include <WinAPIEx.au3>

ConsoleWrite(@ScriptFullPath & " >> " & _IsValidFileType(@ScriptFullPath, "bat;cmd;au3") & @CRLF)
ConsoleWrite(@AutoItExe & " >> " & _IsValidFileType(@AutoItExe, "bat;cmd;au3") & @CRLF)

; Check if a filepath matches an extension filetype. Based on the idea by guinness - http://www.autoitscript.com/forum/topic/123674-isvalidfiletype/
Func _IsValidFileType($sFilePath, $sList = "bat;cmd;exe", $iOpFast = 1) ; By Yashied.
If StringStripWS($sList, 8) = "" Then
$sList = "*"
EndIf
Return _WinAPI_PathMatchSpec($sFilePath, StringReplace(';' & $sList, ';', ';*.', 0, $iOpFast * 2))
EndFunc ;==>_IsValidFileType
</syntaxhighlight>

[[#top | ReturnToContents]]

== File Open/Save/Folder Dialog Box ==

{{Snippet Header
| AuthorURL = 2709-mhz
| AuthorName = MHz
| AuthorURL2 = 4997-odklizec
| AuthorName2 = odklizec
| AuthorURL3 = 6756-danny35d
| AuthorName3 = Danny35d
}}

<syntaxhighlight lang="autoit">
; Center - File Open/Save/Folder Dialog Box
; Author - odklizec, MHz, Danny35d

If StringInStr($cmdlineraw, '/MoveWin') Then
Local $size, $PosX, $PosY
$cmdlineraw = StringSplit(StringMid($cmdlineraw, StringInStr($cmdlineraw, '/MoveWin')), ':')
While 1
Select
Case WinExists($cmdlineraw[2])
$size=WinGetPos ($cmdlineraw[2])
$PosX=@DesktopWidth/2 - $size[2]/2
$PosY=@DesktopHeight/2 - $size[3]/2
WinMove($cmdlineraw[2], "", $PosX, $PosY)
WinActivate($cmdlineraw[2])
ExitLoop
EndSelect
Sleep(50)
WEnd
Exit
EndIf
Global $PID, $Read_File, $Save_File
$PID = _FindBrowseWin('Open file Dialog Box')
$Read_File = FileOpenDialog ( "Open file Dialog Box", @ScriptDir & "\", "AutoIt Files (*.au3)",3,@ScriptFullPath)
ProcessClose($PID)
$PID = _FindBrowseWin('Save file Dialog Box')
$Save_File = FileSaveDialog( "Save file Dialog Box", @ScriptDir, "Scripts (*.aut;*.au3)", 3)
ProcessClose($PID)
$PID = _FindBrowseWin('Browse for Folder')
FileSelectFolder("Choose a folder with plugins..", "","4","c:\")
ProcessClose($PID)

Func _FindBrowseWin($sTitle)
If @Compiled Then
Return(Run(@ScriptFullPath & ' /MoveWin:' & $sTitle))
Else
Return(Run(@AutoItExe & ' "' & @ScriptFullPath & '" /MoveWin:' & $sTitle))
EndIf
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _MoveFileOnReboot ==

{{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.2.0, Creation Date = 21/03/12.

; Function to Move or Delete a file on next reboot!
Func _MoveFileOnReboot($sSourcePath, $sDestPath = ""); If $sDestPath = "" the file is deleted instead of moved.
Local $iRet

; PendingFileRenameOperations (HKLM\SYSTEM\CurrentControlSet\Control\Session Manager)
If $DestPath = "" Then
$iRet = DllCall("kernel32.dll", "int", "MoveFileExA", "str", $sSourcePath, "int", 0, "dword", 4)
Else
$iRet = DllCall("kernel32.dll", "int", "MoveFileExA", "str", $sSourcePath, "str", $sDestPath, "dword", 4)
EndIf

Return $iRet
EndFunc ;==>_MoveFileOnReboot
</syntaxhighlight>

[[#top | ReturnToContents]]

== _MultipleFileOpenDialog ==

{{Snippet Header
| AuthorURL =
| AuthorName = /dev/null
}}

<syntaxhighlight lang="autoit">
Local $message = "Hold down Ctrl or Shift to choose multiple files."

Local $filename = _MultipleFileOpenDialog($message,300,300)

Local $var = FileOpenDialog($message, @WindowsDir & "\", "Images (*.jpg;*.bmp)", 1 + 4 )

If @error Then
MsgBox(4096,"","No File(s) chosen")
Else
$var = StringReplace($var, "|", @CRLF)
MsgBox(4096,"","You chose " & $var)
EndIf

FileDelete($filename)
func _MultipleFileOpenDialog($title,$posx,$posy)
Local $temp = EnvGet("temp")
Local $filename = $temp & "\move_file_open_dialog.au3"

Local $script = 'Global $title = "' & $title & '"' & @CRLF
$script &= 'Global $pos_x = ' & $posx & @CRLF
$script &= 'Global $pos_y = ' & $posy & @CRLF
$script &= 'AdlibRegister("_Move",10)' & @CRLF
$script &= 'while 1' & @CRLF
$script &= ' sleep(1000)' & @CRLF
$script &= 'wend' & @CRLF
$script &= 'Func _Move()' & @CRLF
$script &= ' if (WinActive($title)) Then' & @CRLF
$script &= ' WinMove($title,"",$pos_x,$pos_y)' & @CRLF
$script &= ' Exit' & @CRLF
$script &= ' EndIf' & @CRLF
$script &= 'EndFunc' & @CRLF

FileWrite($filename,$script)
;MsgBox(0,"",$script & @CRLF & $filename)
Run(@AutoItExe & " /AutoIt3ExecuteScript " & $filename)
sleep(250)
Return $filename
EndFunc ;==>_MultipleFileOpenDialog()
</syntaxhighlight>

[[#top | ReturnToContents]]

== _OpenFolder ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#cs
These have been declared in Global scope as you may wish to use them elsewhere in your script.
#ce
Global $ALTSTARTUP = 0x1d
Global $APPDATA = 0x1a
Global $BITBUCKET = 0x0a
Global $COMMONALTSTARTUP = 0x1e
Global $COMMONAPPDATA = 0x23
Global $COMMONDESKTOPDIR = 0x19
Global $COMMONFAVORITES = 0x1f
Global $COMMONPROGRAMS = 0x17
Global $COMMONSTARTMENU = 0x16
Global $COMMONSTARTUP = 0x18
Global $CONTROLS = 0x03
Global $COOKIES = 0x21
Global $DESKTOP = 0x00
Global $DESKTOPDIRECTORY = 0x10
Global $DRIVES = 0x11
Global $FAVORITES = 0x06
Global $FONTS = 0x14
Global $HISTORY = 0x22
Global $INTERNETCACHE = 0x20
Global $LOCALAPPDATA = 0x1c
Global $MYPICTURES = 0x27
Global $NETHOOD = 0x13
Global $NETWORK = 0x12
Global $PERSONAL = 0x05
Global $PRINTERS = 0x04
Global $PRINTHOOD = 0x1b
Global $PROFILE = 0x28
Global $PROGRAMFILES = 0x26
Global $PROGRAMFILESx86 = 0x30
Global $PROGRAMS = 0x02
Global $RECENT = 0x08
Global $SENDTO = 0x09
Global $STARTMENU = 0x0b
Global $STARTUP = 0x07
Global $SYSTEM = 0x25
Global $SYSTEMx86 = 0x29
Global $TEMPLATES = 0x15
Global $WINDOWS = 0x24

ConsoleWrite(_OpenFolder(@ScriptDir) & @CRLF)
ConsoleWrite(_OpenFolder($PRINTERS) & @CRLF)

; Open a folder or special folder variable, similar to using ShellExecute.
Func _OpenFolder($sFolderPath)
Local $oShell = ObjCreate('shell.application')
If @error Then
Return SetError(1, 0, 0)
EndIf
$oShell.Open($sFolderPath)
Return 1
EndFunc ;==>_OpenFolder
</syntaxhighlight>

[[#top | ReturnToContents]]

== _PathAppendToFilename ==

{{Snippet Header
| AuthorURL = 31965-progandy
| AuthorName = ProgAndy
}}

<syntaxhighlight lang="autoit">
$sOrg = "C:\Some.Folder\some.file.ext"
$sAdd = "_backup"

$sNew = _PathAppendToFilename($sOrg, $sAdd)

$sStripped = _PathStripRightFromFilename($sNew, $sAdd)

MsgBox(0, "", $sOrg & @CRLF & $sAdd & @CRLF & $sNew & @CRLF & $sStripped)

Func _PathAppendToFilename($sName, $sAppend)
; Author: ProgAndy
If StringRegExp($sAppend, '[\/\\:\?"<>\|\*]') Then Return SetError(1, 0, $sName)
Return StringRegExpReplace($sName, "(\.[^\\/\.]+)$", $sAppend & "\1", 1)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _PathStripRightFromFilename ==

{{Snippet Header
| AuthorURL = 31965-progandy
| AuthorName = ProgAndy
}}

<syntaxhighlight lang="autoit">
Func _PathStripRightFromFilename($sName, $sStrip)
; Author: ProgAndy
If StringRegExp($sStrip, '[\/\\:\?"<>\|\*]') Then Return SetError(1, 0, $sName)
Return StringRegExpReplace($sName, "\Q" & $sStrip & "\E(\.[^\\/\.]+)$", "\1", 1)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SelfDelete ==

{{Snippet Header
| AuthorURL = 2709-mhz
| AuthorName = MHz
}}

<syntaxhighlight lang="autoit">
; This also removes the directory which the file is in
; Author MHz with the directory delete addition by The Kandie Man
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 _
& ':loop2' & @CRLF _
& 'rmdir /q "' & $dirToDelete & '"' & @CRLF _
& 'if exist "' & $dirToDelete & '" goto loop2' & @CRLF _
& 'del ' & @TempDir & '\scratch.bat'
FileWrite(@TempDir & "\scratch.bat", $sCmdFile)
Run(@TempDir & "\scratch.bat", @TempDir, @SW_HIDE)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ShellExecuteFileSelectFolder ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_ShellExecuteFileSelectFolder('Select a Folder', @HomeDrive) & @CRLF)

; Shell Execute a selected folder.
Func _ShellExecuteFileSelectFolder($sText, $sRoot, $iFlag = 0, $sInitialDir = '', $hWnd = '')
Local $sFolder = FileSelectFolder($sText, $sRoot, $iFlag, $sInitialDir, $hWnd)
If @error Then
Return SetError(@error, @extended, '')
EndIf
ShellExecute($sFolder)
Return $sFolder
EndFunc ;==>_ShellExecuteFileSelectFolder
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SuiCide ==

{{Snippet Header
| AuthorURL = 28010-larrydalooza
| AuthorName = LarryDalooza
}}

<syntaxhighlight lang="autoit">
; IMPORTANT MAKE A COPY OF SCRIPT BEFORE DELETION
; Deletes the running script

Func SuiCide()
Local $sFilePath = @TempDir & '\SuiCide.bat'
FileDelete($sFilePath)
FileWrite($sFilePath, 'loop:' & @CRLF & 'del "' & @ScriptFullPath & '"' & @CRLF & _
'ping -n 1 -w 250 zxywqxz_q' & @CRLF & 'if exist "' & @ScriptFullPath & _
'" goto loop' & @CRLF & 'del SuiCide.bat' & @CRLF)
Exit Run($sFilePath, @TempDir, @SW_HIDE)
EndFunc ;==>SuiCide
</syntaxhighlight>

[[#top | ReturnToContents]]

== _UniqueFilename ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">

ConsoleWrite(_UniqueFilename(@ScriptDir, '.au3') & @CRLF)

Func _UniqueFilename($sFilePath, $sExtension)
Local $iRandom = 0, $sUnqiueFileName = ''

$sExtension = '.' & StringRegExpReplace($sExtension, '\A[\.]+', '')
$sFilePath = StringRegExpReplace($sFilePath, '[\\/]+\z', '') & '\'
While 1
$iRandom = Random(55, 116, 1)
$sUnqiueFileName &= Chr($iRandom + 6 * ($iRandom > 90) - 7 * ($iRandom < 65))
If FileExists($sFilePath & $sUnqiueFileName & $sExtension) = 0 And StringLen($sUnqiueFileName) > 7 Then
ExitLoop
EndIf
WEnd
Return $sFilePath & $sUnqiueFileName & $sExtension
EndFunc ;==>_UniqueFilename
</syntaxhighlight>

[[#top | ReturnToContents]]

== Windows - Copy With Progress ==

{{Snippet Header
| AuthorURL = 19-jos
| AuthorName = Jos
}}

<syntaxhighlight lang="autoit">
; Windows - Copy With Progress

;~ 4 Do not display a progress dialog box.
;~ 8 Give the file being operated on a new name in a move, copy, or rename operation if a file with the target name already exists.
;~ 16 Respond with "Yes to All" for any dialog box that is displayed.
;~ 64 Preserve undo information, if possible.
;~ 128 Perform the operation on files only if a wildcard file name (*.*) is specified.
;~ 256 Display a progress dialog box but do not show the file names.
;~ 512 Do not confirm the creation of a new directory if the operation requires one to be created.
;~ 1024 Do not display a user interface if an error occurs.
;~ 2048 Version 4.71. Do not copy the security attributes of the file.
;~ 4096 Only operate in the local directory. Don't operate recursively into subdirectories.
;~ 8192 Version 5.0. Do not copy connected files as a group. Only copy the specified files.

_FileCopy("C:\Installed Apps\Patches\WindowsXP-KB835935-SP2-ENU.exe","C:\temp")

; to copy a directory the destination directory must exist

Func _FileCopy($fromFile,$tofile)
Local $FOF_RESPOND_YES = 16
Local $FOF_SIMPLEPROGRESS = 256
$winShell = ObjCreate("shell.application")
$winShell.namespace($tofile).CopyHere($fromFile,$FOF_RESPOND_YES)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

Snippets ( Files & Folders )

2014-05-12T19:33:33Z

Guinness: /* _IsDir */

__TOC__
[[category:Snippets]]

{{Snippet Credit Header}}

== _ConvertFileToUTF16 ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
_ConvertFileToUTF16(@ScriptDir & "\Example.xml")

Func _ConvertFileToUTF16($sFilePath)
Local $iEncoding = FileGetEncoding($sFilePath)
Local $hFileOpen = FileOpen($sFilePath, $iEncoding)
If $hFileOpen = -1 Then
Return SetError(1, 0, 0)
EndIf
Local $sData = FileRead($hFileOpen)
FileClose($hFileOpen)

$hFileOpen = FileOpen($sFilePath, 2 + 32)
If $hFileOpen = -1 Then
Return SetError(2, 0, 0)
EndIf
FileWrite($hFileOpen, $sData)
Return FileClose($hFileOpen)
EndFunc ;==>_ConvertFileToUTF16
</syntaxhighlight>

[[#top | ReturnToContents]]

== DropFiles ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
| Desc = Dropping multiple files onto a GUI
}}

<syntaxhighlight lang="autoit">
; Dropping multiple files onto a GUI

#include <APIConstants.au3>
#include <Array.au3>
#include <GUIConstantsEx.au3>
#include <WinAPIEx.au3>

Global $__aDropFiles

Example()

Func Example()
Local $hGUI = GUICreate('', 500, 500, -1, -1, -1, $WS_EX_ACCEPTFILES)

; Create a label that is transparent which will accept 'drop' events.
GUICtrlCreateLabel("", 0, 0, 500, 500)
GUICtrlSetBkColor(-1, $GUI_BKCOLOR_TRANSPARENT)
GUICtrlSetResizing(-1, $GUI_DOCKALL)
GUICtrlSetState(-1, $GUI_DROPACCEPTED)

GUIRegisterMsg($WM_DROPFILES, "WM_DROPFILES")
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop

Case $GUI_EVENT_DROPPED
If $__aDropFiles[0] > 0 Then
_ArrayDisplay($__aDropFiles)
EndIf

EndSwitch
WEnd
GUIDelete($hGUI)
EndFunc ;==>Example

Func WM_DROPFILES($hWnd, $iMsg, $iwParam, $ilParam)
#forceref $hWnd, $ilParam
Switch $iMsg
Case $WM_DROPFILES
Local $aReturn = _WinAPI_DragQueryFileEx($iwParam)
If IsArray($aReturn) Then
$__aDropFiles = $aReturn
Else
Local $aError[1] = [0]
$__aDropFiles = $aError
EndIf
EndSwitch
Return $GUI_RUNDEFMSG
EndFunc ;==>WM_DROPFILES
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ExitCheckTextChange ==

{{Snippet Header
| AuthorURL = 8007-negativenrg
| AuthorName = NegativeNrG
}}

<syntaxhighlight lang="autoit">
;Check(when Exit), if Text is not equal to $e_to Then, prompt the user to save or not save.
;_ExitCheckText Change $Edit Handle, $title of messagebox, $message of messagebox, $equal to(default = NULL).

Func _ExitCheckTextChange($E_hnd,$title,$message,$e_to = '')
Local $buffer, $choice, $filetosave, $handle1
$buffer = GUIctrlread($E_hnd)
If $buffer <> $e_to Then
$choice = Msgbox(4,$title,$message)
If $choice = 6 Then
$filetosave = FileSaveDialog('Choose File',@scriptdir,'(*.au3)')
$handle1 = FileOpen($filetosave,2)
FileWrite($handle1,$buffer)
Exit
Elseif $choice <> 6 Then
Exit
EndIf
Else
Exit
EndIf
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileDeleteEx ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Ref: http://msdn.microsoft.com/en-us/library/windows/desktop/aa365240(v=vs.85).aspx

#include <APIFilesConstants.au3>
#include <WinAPIFiles.au3>

ConsoleWrite(_FileDeleteEx("C:\Example.dat") & @CRLF)

Func _FileDeleteEx($sFilePath)
Return FileDelete($sFilePath) = 1 ? 1 : Int(_WinAPI_MoveFileEx(FileGetShortName($sFilePath), "", $MOVE_FILE_DELAY_UNTIL_REBOOT))
EndFunc ;==>_FileDeleteEx
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileCheck ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

; Check if the file was modified less than 24 hours ago.
ConsoleWrite( _FileCheck(@ScriptFullPath, 24) & @CRLF)

Func _FileCheck($sFilePath, $iHours = 24)
Local $aTime
If FileExists($sFilePath) = 0 Then
Return SetError(1, 0, 0)
EndIf
$aTime = FileGetTime($sFilePath, 0, 0)
Return Number(_DateDiff("h", $aTime[0] & "/" & $aTime[1] & "/" & $aTime[2] & " " & $aTime[3] & ":" & $aTime[4] & ":" & $aTime[5], @YEAR & "/" & @MON & "/" & @MDAY & " " & @HOUR & ":" & @MIN & ":" & @SEC) < $iHours)
EndFunc ;==>_FileCheck
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileCreateEx ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
_FileCreateEx(@ScriptDir & '\ExampleFile.txt', 42)

; Create a blank file with a certain size in bytes.
Func _FileCreateEx($sFilePath, $iBytes = 0)
Return RunWait(@ComSpec & ' /c fsutil file createnew "' & $sFilePath & '" ' & Int($iBytes), @WorkingDir, @SW_HIDE)
EndFunc ;==>_FileCreateEx
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileID ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

FileClose(FileOpen(@ScriptDir & '\ExampleFile.txt', 2))
ConsoleWrite(_FileID(@ScriptDir & '\ExampleFile.txt') & @CRLF)
FileDelete(@ScriptDir & '\ExampleFile.txt')

; Rerieve the file id of a filepath.
Func _FileID($sFilePath)
Local $iPID = Run(@ComSpec & ' /c fsutil file queryfileid "' & $sFilePath & '"', @SystemDir, @SW_HIDE, $STDOUT_CHILD + $STDERR_CHILD), $sReturn = ''
While 1
$sReturn &= StdoutRead($iPID)
If @error Then
ExitLoop
EndIf
WEnd
Return StringStripWS(StringRegExpReplace($sReturn, 'File\sID\sis\s(.*?)', '$1'), 8)
EndFunc ;==>_FileID
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileExistsWithQuotes ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_FileExistsWithQuotes('"' & @ScriptDir & '"') & @CRLF)
ConsoleWrite(_FileExistsWithQuotes("'" & @ScriptDir & "'") & @CRLF)
ConsoleWrite(_FileExistsWithQuotes(@ScriptDir) & @CRLF)

; Version: 1.00. AutoIt: V3.3.8.1
; Check a filepath ecists even if the path contains quotation marks.
Func _FileExistsWithQuotes($sFilePath)
Return FileExists(StringRegExpReplace($sFilePath, '^("|'')*([^"'']+)("|'')*$', '\2'))
EndFunc ;==>_FileExistsWithQuotes
</syntaxhighlight>

[[#top | ReturnToContents]]

== FileLineCount ==

{{Snippet Header
| AuthorURL = 71214-mkish
| AuthorName = MKISH
| Desc = Checks the number of lines in a file (useful for larger files as well)
}}

<syntaxhighlight lang="autoit">
; Author - MKISH

; Checks the number of lines in a file (useful for larger files as well)

#include <WinAPI.au3>

Local $FILE = "G:\WIN7\sources\boot.wim"
Local $COUNT = 0
Local $start = default
Local $res, $fLen, $err

While 1
$res = _HexSearch($FILE, StringToBinary("" & @crlf), $start)
$start = $res + 2
$COUNT = $COUNT + 1
If $res = -1 then exitloop
Wend

msgbox(64, "", "Lines count: " & $COUNT)

; _HexSearch function (originally written by Zinthose, modified by MKISH)
Func _HexSearch($FilePath, $BinaryValue, $StartOffset = Default)
Local $Buffer, $ptr, $hFile, $Result, $Read, $SearchValue, $Pos, $BufferSize = 2048
If $StartOffset = Default Then $StartOffset = 0
If Not FileExists($FilePath) Then Return SetError(1, @error, 0)
$fLen = FileGetSize($FilePath)
If $StartOffset > $fLen Then Return SetError(2, @error, 0)
If Not IsBinary($BinaryValue) Then Return SetError(3, @error, 0)
If Not IsNumber($StartOffset) Then Return SetError(4, @error, 0)
$SearchValue = BinaryToString($BinaryValue)
$Buffer = DllStructCreate("byte[" & $BufferSize & "]")
$ptr = DllStructGetPtr($Buffer)
$hFile = _WinAPI_CreateFile($FilePath, 2, 2, 1)
If $hFile = 0 Then Return SetError(5, @error, 0)
$Result = _WinAPI_SetFilePointer($hFile, $StartOffset)
$err = @error
If $Result = 0xFFFFFFFF Then
_WinAPI_CloseHandle($hFile)
Return SetError(5, $err, 0)
EndIf
$Pos = $StartOffset
While True
$Read = 0
$Result = _WinAPI_ReadFile($hFile, $ptr, $BufferSize, $Read)
$err = @error
If Not $Result Then
_WinAPI_CloseHandle($hFile)
Return SetError(6, $err, 0)
EndIf
$Result = DllStructGetData($Buffer, 1)
$Result = BinaryToString($Result)
$Result = StringInStr($Result, $SearchValue)
If $Result > 0 Then ExitLoop
If $Read < $BufferSize Then
_WinAPI_CloseHandle($hFile)
Return -1
EndIf
$Pos += $Read

WEnd
_WinAPI_CloseHandle($hFile)
If Not $Result Then Return SetError(7, @error, 0)
$Result = $Pos + $Result - 1
Return $Result
EndFunc; ==> _HexSearch
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileOpenDialog ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Local $sFilePath = _FileOpenDialog("", "", "Images (*.jpg;*.bmp)|Videos (*.avi;*.mpg)", Random(1, @DesktopWidth, 1), Random(1, @DesktopHeight, 1), 1 + 4, "")

ConsoleWrite('File = ' & $sFilePath & ', @error = ' & @error & @CRLF)

; #FUNCTION# ====================================================================================================================
; Name ..........: _FileOpenDialog
; Description ...: Initiates a Open File Dialog with the option to set the position of the GUI.
; Syntax ........: _FileOpenDialog($sTitle, $sIntitialDirectory, $sFilter[, $iLeft = -1[, $iTop = -1[, $iOptions = 0[,
; $sDefaultName = ""]]]])
; Parameters ....: $sTitle - Title text of the Dialog GUI.
; $sIntitialDirectory - Initial directory selected in the GUI file tree.
; $sFilter - File type single filter such as "All (*.*)" or "Text files (*.txt)".
; $iLeft - [optional] The left side of the dialog box. By default (-1), the window is centered.
; $iTop - [optional] The top of the dialog box. Default (-1) is centered
; $iOptions - [optional] Dialog Options: To use more than one option, add the required values together. See FileOpenDialog. Default is 0.
; $sDefaultName - [optional] Suggested file name for the user to open. Default is blank ("").
; Return values .: Success: Returns the full path of the file(s) chosen. Results for multiple selections are "Directory|file1|file2|..."
; Failure: Sets @error to non-zero.
; Author ........: guinness
; Remarks........: This doesn't change the working directory of the script like FileOpenDialog does.
; Example .......: Yes
; ===============================================================================================================================
Func _FileOpenDialog($sTitle, $sIntitialDirectory, $sFilter, $iLeft = -1, $iTop = -1, $iOptions = 0, $sDefaultName = "")
Local $hGUI = GUICreate('', -1, -1, $iLeft, $iTop), $sWorkingDir = @WorkingDir
Local $sFilePath = FileOpenDialog($sTitle, $sIntitialDirectory, $sFilter, $iOptions, $sDefaultName, $hGUI)
Local $iError = @error
FileChangeDir($sWorkingDir)
Return SetError($iError, GUIDelete($hGUI), $sFilePath)
EndFunc ;==>_FileOpenDialog()
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileRename ==

{{Snippet Header
| AuthorURL = 52374-johnone
| AuthorName = JohnOne
}}

<syntaxhighlight lang="autoit">
;### Rename a file ###
;$sFile = Full path to file
;$sRename = New Filename
;$iOverWrite = 0 or 1

;Success returns 1
;failure, returns 0 and sets @error
; 1 if FileMove fails,
; 2 if $sFile does not exist
;@extended
; 0 if the new file does not already exist / existed
; 1 if the new file already exists / existed

;#### Example ####
$File = @ScriptDir & '\filetorename.txt'
FileWrite($File, 'Test')
_FileRename($File, 'newname.txt')
If @error Then MsgBox(0, "Error", @error)

Func _FileRename($sFile, $sRename, $iOverWrite = 0)
Local Const $FILENOTEXIST = 2
If Not FileExists($sFile) Then Return SetError($FILENOTEXIST, 0, 0)
Local $_StringLen = StringLen($sFile)
Local $_StringInStr = StringInStr($sFile, "\", 0, -1, $_StringLen)
Local $_Count = $_StringLen - $_StringInStr
Local $_Dir = StringLeft($sFile, $_StringInStr)
Local $_NewFile = $_Dir & $sRename
Local $_NewFileExists = FileExists($_NewFile)
Local $_FileMove = FileMove($sFile, $_NewFile, $iOverWrite)
Return SetError(Not $_FileMove, $_NewFileExists, $_FileMove)
EndFunc ;==>_FileRename
</syntaxhighlight>

== _FileRename Alternative ==

<syntaxhighlight lang="autoit">

;FileRename(PathFile, RenameFile)
;JohnOne

FileRename(@ScriptDir & "\rename.txt", @ScriptDir & "\renamed.txt")

Func FileRename($FileName, $ReName)

Local $SHFILEOPSTRUCT, $SourceStruct, $DestStruct
Local Const $FO_RENAME = 0x0004
Local Const $FOF_SILENT = 0x0004
Local Const $FOF_NOCONFIRMATION = 0x0010
Local Const $FOF_NOERRORUI = 0x0400
Local Const $FOF_NOCONFIRMMKDIR = 0x0200
Local Const $NULL = 0

$SourceStruct = _StringToStruct($FileName)
$DestStruct = _StringToStruct($ReName)

$SHFILEOPSTRUCT = DllStructCreate("hwnd hWnd;uint wFunc;ptr pFrom;ptr pTo;int fFlags;int fAnyOperationsAborted;ptr hNameMappings;ptr lpszProgressTitle")

DllStructSetData($SHFILEOPSTRUCT, "hWnd", $NULL)
DllStructSetData($SHFILEOPSTRUCT, "wFunc", $FO_RENAME)
DllStructSetData($SHFILEOPSTRUCT, "pFrom", DllStructGetPtr($SourceStruct))
DllStructSetData($SHFILEOPSTRUCT, "pTo", DllStructGetPtr($DestStruct))
DllStructSetData($SHFILEOPSTRUCT, "fFlags", BitOR($FOF_SILENT, $FOF_NOCONFIRMATION, $FOF_NOERRORUI, $FOF_NOCONFIRMMKDIR))
DllStructSetData($SHFILEOPSTRUCT, "fAnyOperationsAborted", $NULL)
DllStructSetData($SHFILEOPSTRUCT, "hNameMappings", $NULL)
DllStructSetData($SHFILEOPSTRUCT, "lpszProgressTitle", $NULL)

$acall = DllCall("shell32.dll", "int", "SHFileOperation", "ptr", DllStructGetPtr($SHFILEOPSTRUCT))
If @error Then
Return SetError(@error, @extended, 0)
EndIf
Return 1
EndFunc ;==>FileRename

Func _StringToStruct($string)

Local $iLen = StringLen($string)
Local $Struct = DllStructCreate("char[" & String($iLen + 2) & "]")
DllStructSetData($Struct, 1, $string)
DllStructSetData($Struct, 1, 0, $iLen + 1)
DllStructSetData($Struct, 1, 0, $iLen + 2)

Return $Struct
EndFunc ;==>_StringToStruct

</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetFolderDepth ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Autoit 3.3.5.4 and Below
ConsoleWrite(_GetFolderDepth(@ScriptDir & '') & @CRLF)
ConsoleWrite(_GetFolderDepth(@ScriptDir) & @CRLF)
ConsoleWrite(_GetFolderDepth(@ScriptFullPath) & @CRLF)

; Get the folder depth of a filepath.
Func _GetFolderDepth($sFilePath)
If StringInStr($sFilePath, '.', 2, -1) Then
$sFilePath = StringLeft($sFilePath, StringInStr($sFilePath, "", 2, -1) - 1)
EndIf
Local $aArray = StringSplit(StringRegExpReplace($sFilePath, '[/]+z', ''), '')
Return $aArray[0] - 1
EndFunc ;==>_GetFolderDepth
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetFolderDepth ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Autoit 3.3.5.4 and Above
ConsoleWrite(_GetFolderDepth(@ScriptDir & '') & @CRLF)
ConsoleWrite(_GetFolderDepth(@ScriptDir) & @CRLF)
ConsoleWrite(_GetFolderDepth(@ScriptFullPath) & @CRLF)

; Get the folder depth of a filepath. Works with V3.3.5.4+
Func _GetFolderDepth($sFilePath)
If StringInStr($sFilePath, '.', 2, -1) Then
$sFilePath = StringLeft($sFilePath, StringInStr($sFilePath, "", 2, -1) - 1)
EndIf
Return StringSplit(StringRegExpReplace($sFilePath, '[/]+z', ''), '')[0] - 1
EndFunc ;==>_GetFolderDepth
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsDir ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite("IsDir: Using a file - " & IsDir(@ScriptFullPath) & @CRLF) ; Return 0
ConsoleWrite("IsDir: Using a directory - " & IsDir(@ScriptDir) & @CRLF) ; Return 1

Func IsDir($sFilePath)
Return Int(FileExists($sFilePath) And StringInStr(FileGetAttrib($sFilePath), 'D', Default, 1) > 0)
EndFunc ;==>IsDir
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Func IsFile($sFilePath)
Return Number(FileExists($sFilePath) And StringInStr(FileGetAttrib($sFilePath), "D", 2, 1) = 0)
EndFunc ;==>IsFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsFileDiff ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_IsFileDiff(@ScriptFullPath, @ScriptFullPath) & @CRLF) ; This will return False as the files are exactly the same.
ConsoleWrite(_IsFileDiff(@ScriptFullPath, @AutoItExe) & @CRLF) ; This will return True as the files are different.

; Check if a file is different.
Func _IsFileDiff($sFilePath_1, $sFilePath_2)
Return RunWait(@ComSpec & ' /c FC /B /W "' & $sFilePath_1 & '" "' & $sFilePath_2 & '"', @WorkingDir, @SW_HIDE) > 0
EndFunc ;==>_IsFileDiff
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsFileOlder ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <Date.au3> ; Required for _DateDiff()

; Check if the current script is older than 10 days.
If _IsFileOlder(@ScriptFullPath, 10) Then
MsgBox(4096, '', 'File is older than 10 days.')
Else
MsgBox(4096, '', 'File isn''t older than 10 days.')
EndIf

; Is a file older than a certain number of days.
Func _IsFileOlder($sFilePath, $iDays)
Local $aArray = FileGetTime($sFilePath, 0)
Return _DateDiff('D', $aArray[0] & '/' & $aArray[1] & '/' & $aArray[2] & ' ' & $aArray[3] & ':' & $aArray[4] & ':' & $aArray[5], @YEAR & '/' & @MON & '/' & @MDAY & ' ' & @HOUR & ':' & @MIN & ':' & @SEC) >= $iDays
EndFunc ;==>_IsFileOlder
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsFileSame ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_IsFileSame(@ScriptFullPath, @ScriptFullPath) & @CRLF) ; This will return True as the files are exactly the same.
ConsoleWrite(_IsFileSame(@ScriptFullPath, @AutoItExe) & @CRLF) ; This will return False as the files are different.

; Check if a file is the same.
Func _IsFileSame($sFilePath_1, $sFilePath_2)
Return RunWait(@ComSpec & ' /c FC /B /W "' & $sFilePath_1 & '" "' & $sFilePath_2 & '"', @WorkingDir, @SW_HIDE) = 0
EndFunc ;==>_IsFileSame
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IniReadFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

__INIFileFill(@ScriptDir & '\Example.ini') ; Create an INI file with random data.

Local $aArray = _IniReadFile(@ScriptDir & '\Example.ini')
FileDelete(@ScriptDir & '\Example.ini')
_ArrayDisplay($aArray)

Func _IniReadFile($sFilePath)
Local $aReturn[1][3] = [[0, 3]], $aSectionArray, $aSectionNameArray, $iCount = 0
$aSectionNameArray = IniReadSectionNames($sFilePath)
If @error Then
Return SetError(1, 0, $aReturn)
EndIf
For $A = 1 To $aSectionNameArray[0]
$aSectionArray = IniReadSection($sFilePath, $aSectionNameArray[$A])
If @error Then
ContinueLoop
EndIf
For $B = 1 To $aSectionArray[0][0]
$aReturn[0][0] += 1
$iCount += 1
If $aReturn[0][0] <= $iCount + 1 Then
ReDim $aReturn[$aReturn[0][0] * 2][$aReturn[0][1]]
EndIf
$aReturn[$iCount][0] = $aSectionArray[$B][0]
$aReturn[$iCount][1] = $aSectionArray[$B][1]
$aReturn[$iCount][2] = $aSectionNameArray[$A]
Next
Next
ReDim $aReturn[$aReturn[0][0] + 1][$aReturn[0][1]] ; Remove empty entries.
Return $aReturn
EndFunc ;==>_IniReadFile

Func __INIFileFill($sFilePath)
Local $sData = '', $sHeader = ''

For $i = 1 To Random(1, 5, 1)
$sHeader = _RandomText(Random(5, 25, 1))
$sData = ""
For $j = 1 To Random(1, 25, 1)
$sData &= _RandomText(Random(5, 25, 1)) & '=' & _RandomText(Random(5, 25, 1)) & @LF
Next
IniWriteSection($sFilePath, $sHeader, $sData)
Next
EndFunc ;==>__FillINIFile

Func _RandomText($iLength = 10)
Local $sData = '', $sRandom = ''
For $i = 1 To $iLength
$sRandom = Random(55, 116, 1)
$sData &= Chr($sRandom + 6 * ($sRandom > 90) - 7 * ($sRandom < 65))
Next
Return $sData
EndFunc ;==>_RandomText
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IniReadInit ==

{{Snippet Header
| AuthorURL = 9370-mlowery
| AuthorName = mlowery
}}

<syntaxhighlight lang="autoit">
;===============================================================================
; Description: Reads values from INI or creates INI with initial values.
; Intended to ensure all available INI settings are exposed
; and editable.
; Parameters are identical to IniRead()
; Parameter(s): $filename = filename of INI
; $section = section name of INI
; $key = key name in section
; $default = default value (written to INI if not exists)
; Requirement(s): None
; Return Value(s): Returns value from INI (or default if not defined)
; Note(s): Chr(127) used to detect non-existing value since won't normally exist in a text file
;===============================================================================
Func _IniReadInit($filename, $section, $key, $default)
Local $value = IniRead($filename, $section, $key, Chr(127))
If $value = Chr(127) Then
IniWrite($filename, $section, $key, $default)
$value = $default
EndIf
Return $value
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsValidFileType ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(@ScriptFullPath & " >> " & _IsValidFileType(@ScriptFullPath, "bat;cmd;au3") & @CRLF)
ConsoleWrite(@AutoItExe & " >> " & _IsValidFileType(@AutoItExe, "bat;cmd;au3") & @CRLF)

; Check if a filepath matches an extension filetype. Based on the idea by guinness - http://www.autoitscript.com/forum/topic/123674-isvalidfiletype/
Func _IsValidFileType($sFilePath, $sList = "bat;cmd;exe") ; By AZJIO - http://www.autoitscript.com/forum/topic/...filetype/page__view__findpost_
Local $iDot = StringInStr($sFilePath, ".", 0, -1)
Return $iDot And StringInStr(';' & $sList & ';', ';' & StringTrimLeft($sFilePath, $iDot) & ';') > 0
EndFunc ;==>_IsValidFileType
</syntaxhighlight>

<syntaxhighlight lang="autoit">
; Example 2

#include <WinAPIEx.au3>

ConsoleWrite(@ScriptFullPath & " >> " & _IsValidFileType(@ScriptFullPath, "bat;cmd;au3") & @CRLF)
ConsoleWrite(@AutoItExe & " >> " & _IsValidFileType(@AutoItExe, "bat;cmd;au3") & @CRLF)

; Check if a filepath matches an extension filetype. Based on the idea by guinness - http://www.autoitscript.com/forum/topic/123674-isvalidfiletype/
Func _IsValidFileType($sFilePath, $sList = "bat;cmd;exe", $iOpFast = 1) ; By Yashied.
If StringStripWS($sList, 8) = "" Then
$sList = "*"
EndIf
Return _WinAPI_PathMatchSpec($sFilePath, StringReplace(';' & $sList, ';', ';*.', 0, $iOpFast * 2))
EndFunc ;==>_IsValidFileType
</syntaxhighlight>

[[#top | ReturnToContents]]

== File Open/Save/Folder Dialog Box ==

{{Snippet Header
| AuthorURL = 2709-mhz
| AuthorName = MHz
| AuthorURL2 = 4997-odklizec
| AuthorName2 = odklizec
| AuthorURL3 = 6756-danny35d
| AuthorName3 = Danny35d
}}

<syntaxhighlight lang="autoit">
; Center - File Open/Save/Folder Dialog Box
; Author - odklizec, MHz, Danny35d

If StringInStr($cmdlineraw, '/MoveWin') Then
Local $size, $PosX, $PosY
$cmdlineraw = StringSplit(StringMid($cmdlineraw, StringInStr($cmdlineraw, '/MoveWin')), ':')
While 1
Select
Case WinExists($cmdlineraw[2])
$size=WinGetPos ($cmdlineraw[2])
$PosX=@DesktopWidth/2 - $size[2]/2
$PosY=@DesktopHeight/2 - $size[3]/2
WinMove($cmdlineraw[2], "", $PosX, $PosY)
WinActivate($cmdlineraw[2])
ExitLoop
EndSelect
Sleep(50)
WEnd
Exit
EndIf
Global $PID, $Read_File, $Save_File
$PID = _FindBrowseWin('Open file Dialog Box')
$Read_File = FileOpenDialog ( "Open file Dialog Box", @ScriptDir & "\", "AutoIt Files (*.au3)",3,@ScriptFullPath)
ProcessClose($PID)
$PID = _FindBrowseWin('Save file Dialog Box')
$Save_File = FileSaveDialog( "Save file Dialog Box", @ScriptDir, "Scripts (*.aut;*.au3)", 3)
ProcessClose($PID)
$PID = _FindBrowseWin('Browse for Folder')
FileSelectFolder("Choose a folder with plugins..", "","4","c:\")
ProcessClose($PID)

Func _FindBrowseWin($sTitle)
If @Compiled Then
Return(Run(@ScriptFullPath & ' /MoveWin:' & $sTitle))
Else
Return(Run(@AutoItExe & ' "' & @ScriptFullPath & '" /MoveWin:' & $sTitle))
EndIf
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _MoveFileOnReboot ==

{{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.2.0, Creation Date = 21/03/12.

; Function to Move or Delete a file on next reboot!
Func _MoveFileOnReboot($sSourcePath, $sDestPath = ""); If $sDestPath = "" the file is deleted instead of moved.
Local $iRet

; PendingFileRenameOperations (HKLM\SYSTEM\CurrentControlSet\Control\Session Manager)
If $DestPath = "" Then
$iRet = DllCall("kernel32.dll", "int", "MoveFileExA", "str", $sSourcePath, "int", 0, "dword", 4)
Else
$iRet = DllCall("kernel32.dll", "int", "MoveFileExA", "str", $sSourcePath, "str", $sDestPath, "dword", 4)
EndIf

Return $iRet
EndFunc ;==>_MoveFileOnReboot
</syntaxhighlight>

[[#top | ReturnToContents]]

== _MultipleFileOpenDialog ==

{{Snippet Header
| AuthorURL =
| AuthorName = /dev/null
}}

<syntaxhighlight lang="autoit">
Local $message = "Hold down Ctrl or Shift to choose multiple files."

Local $filename = _MultipleFileOpenDialog($message,300,300)

Local $var = FileOpenDialog($message, @WindowsDir & "\", "Images (*.jpg;*.bmp)", 1 + 4 )

If @error Then
MsgBox(4096,"","No File(s) chosen")
Else
$var = StringReplace($var, "|", @CRLF)
MsgBox(4096,"","You chose " & $var)
EndIf

FileDelete($filename)
func _MultipleFileOpenDialog($title,$posx,$posy)
Local $temp = EnvGet("temp")
Local $filename = $temp & "\move_file_open_dialog.au3"

Local $script = 'Global $title = "' & $title & '"' & @CRLF
$script &= 'Global $pos_x = ' & $posx & @CRLF
$script &= 'Global $pos_y = ' & $posy & @CRLF
$script &= 'AdlibRegister("_Move",10)' & @CRLF
$script &= 'while 1' & @CRLF
$script &= ' sleep(1000)' & @CRLF
$script &= 'wend' & @CRLF
$script &= 'Func _Move()' & @CRLF
$script &= ' if (WinActive($title)) Then' & @CRLF
$script &= ' WinMove($title,"",$pos_x,$pos_y)' & @CRLF
$script &= ' Exit' & @CRLF
$script &= ' EndIf' & @CRLF
$script &= 'EndFunc' & @CRLF

FileWrite($filename,$script)
;MsgBox(0,"",$script & @CRLF & $filename)
Run(@AutoItExe & " /AutoIt3ExecuteScript " & $filename)
sleep(250)
Return $filename
EndFunc ;==>_MultipleFileOpenDialog()
</syntaxhighlight>

[[#top | ReturnToContents]]

== _OpenFolder ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#cs
These have been declared in Global scope as you may wish to use them elsewhere in your script.
#ce
Global $ALTSTARTUP = 0x1d
Global $APPDATA = 0x1a
Global $BITBUCKET = 0x0a
Global $COMMONALTSTARTUP = 0x1e
Global $COMMONAPPDATA = 0x23
Global $COMMONDESKTOPDIR = 0x19
Global $COMMONFAVORITES = 0x1f
Global $COMMONPROGRAMS = 0x17
Global $COMMONSTARTMENU = 0x16
Global $COMMONSTARTUP = 0x18
Global $CONTROLS = 0x03
Global $COOKIES = 0x21
Global $DESKTOP = 0x00
Global $DESKTOPDIRECTORY = 0x10
Global $DRIVES = 0x11
Global $FAVORITES = 0x06
Global $FONTS = 0x14
Global $HISTORY = 0x22
Global $INTERNETCACHE = 0x20
Global $LOCALAPPDATA = 0x1c
Global $MYPICTURES = 0x27
Global $NETHOOD = 0x13
Global $NETWORK = 0x12
Global $PERSONAL = 0x05
Global $PRINTERS = 0x04
Global $PRINTHOOD = 0x1b
Global $PROFILE = 0x28
Global $PROGRAMFILES = 0x26
Global $PROGRAMFILESx86 = 0x30
Global $PROGRAMS = 0x02
Global $RECENT = 0x08
Global $SENDTO = 0x09
Global $STARTMENU = 0x0b
Global $STARTUP = 0x07
Global $SYSTEM = 0x25
Global $SYSTEMx86 = 0x29
Global $TEMPLATES = 0x15
Global $WINDOWS = 0x24

ConsoleWrite(_OpenFolder(@ScriptDir) & @CRLF)
ConsoleWrite(_OpenFolder($PRINTERS) & @CRLF)

; Open a folder or special folder variable, similar to using ShellExecute.
Func _OpenFolder($sFolderPath)
Local $oShell = ObjCreate('shell.application')
If @error Then
Return SetError(1, 0, 0)
EndIf
$oShell.Open($sFolderPath)
Return 1
EndFunc ;==>_OpenFolder
</syntaxhighlight>

[[#top | ReturnToContents]]

== _PathAppendToFilename ==

{{Snippet Header
| AuthorURL = 31965-progandy
| AuthorName = ProgAndy
}}

<syntaxhighlight lang="autoit">
$sOrg = "C:\Some.Folder\some.file.ext"
$sAdd = "_backup"

$sNew = _PathAppendToFilename($sOrg, $sAdd)

$sStripped = _PathStripRightFromFilename($sNew, $sAdd)

MsgBox(0, "", $sOrg & @CRLF & $sAdd & @CRLF & $sNew & @CRLF & $sStripped)

Func _PathAppendToFilename($sName, $sAppend)
; Author: ProgAndy
If StringRegExp($sAppend, '[\/\\:\?"<>\|\*]') Then Return SetError(1, 0, $sName)
Return StringRegExpReplace($sName, "(\.[^\\/\.]+)$", $sAppend & "\1", 1)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _PathStripRightFromFilename ==

{{Snippet Header
| AuthorURL = 31965-progandy
| AuthorName = ProgAndy
}}

<syntaxhighlight lang="autoit">
Func _PathStripRightFromFilename($sName, $sStrip)
; Author: ProgAndy
If StringRegExp($sStrip, '[\/\\:\?"<>\|\*]') Then Return SetError(1, 0, $sName)
Return StringRegExpReplace($sName, "\Q" & $sStrip & "\E(\.[^\\/\.]+)$", "\1", 1)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SelfDelete ==

{{Snippet Header
| AuthorURL = 2709-mhz
| AuthorName = MHz
}}

<syntaxhighlight lang="autoit">
; This also removes the directory which the file is in
; Author MHz with the directory delete addition by The Kandie Man
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 _
& ':loop2' & @CRLF _
& 'rmdir /q "' & $dirToDelete & '"' & @CRLF _
& 'if exist "' & $dirToDelete & '" goto loop2' & @CRLF _
& 'del ' & @TempDir & '\scratch.bat'
FileWrite(@TempDir & "\scratch.bat", $sCmdFile)
Run(@TempDir & "\scratch.bat", @TempDir, @SW_HIDE)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ShellExecuteFileSelectFolder ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_ShellExecuteFileSelectFolder('Select a Folder', @HomeDrive) & @CRLF)

; Shell Execute a selected folder.
Func _ShellExecuteFileSelectFolder($sText, $sRoot, $iFlag = 0, $sInitialDir = '', $hWnd = '')
Local $sFolder = FileSelectFolder($sText, $sRoot, $iFlag, $sInitialDir, $hWnd)
If @error Then
Return SetError(@error, @extended, '')
EndIf
ShellExecute($sFolder)
Return $sFolder
EndFunc ;==>_ShellExecuteFileSelectFolder
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SuiCide ==

{{Snippet Header
| AuthorURL = 28010-larrydalooza
| AuthorName = LarryDalooza
}}

<syntaxhighlight lang="autoit">
; IMPORTANT MAKE A COPY OF SCRIPT BEFORE DELETION
; Deletes the running script

Func SuiCide()
Local $sFilePath = @TempDir & '\SuiCide.bat'
FileDelete($sFilePath)
FileWrite($sFilePath, 'loop:' & @CRLF & 'del "' & @ScriptFullPath & '"' & @CRLF & _
'ping -n 1 -w 250 zxywqxz_q' & @CRLF & 'if exist "' & @ScriptFullPath & _
'" goto loop' & @CRLF & 'del SuiCide.bat' & @CRLF)
Exit Run($sFilePath, @TempDir, @SW_HIDE)
EndFunc ;==>SuiCide
</syntaxhighlight>

[[#top | ReturnToContents]]

== _UniqueFilename ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">

ConsoleWrite(_UniqueFilename(@ScriptDir, '.au3') & @CRLF)

Func _UniqueFilename($sFilePath, $sExtension)
Local $iRandom = 0, $sUnqiueFileName = ''

$sExtension = '.' & StringRegExpReplace($sExtension, '\A[\.]+', '')
$sFilePath = StringRegExpReplace($sFilePath, '[\\/]+\z', '') & '\'
While 1
$iRandom = Random(55, 116, 1)
$sUnqiueFileName &= Chr($iRandom + 6 * ($iRandom > 90) - 7 * ($iRandom < 65))
If FileExists($sFilePath & $sUnqiueFileName & $sExtension) = 0 And StringLen($sUnqiueFileName) > 7 Then
ExitLoop
EndIf
WEnd
Return $sFilePath & $sUnqiueFileName & $sExtension
EndFunc ;==>_UniqueFilename
</syntaxhighlight>

[[#top | ReturnToContents]]

== Windows - Copy With Progress ==

{{Snippet Header
| AuthorURL = 19-jos
| AuthorName = Jos
}}

<syntaxhighlight lang="autoit">
; Windows - Copy With Progress

;~ 4 Do not display a progress dialog box.
;~ 8 Give the file being operated on a new name in a move, copy, or rename operation if a file with the target name already exists.
;~ 16 Respond with "Yes to All" for any dialog box that is displayed.
;~ 64 Preserve undo information, if possible.
;~ 128 Perform the operation on files only if a wildcard file name (*.*) is specified.
;~ 256 Display a progress dialog box but do not show the file names.
;~ 512 Do not confirm the creation of a new directory if the operation requires one to be created.
;~ 1024 Do not display a user interface if an error occurs.
;~ 2048 Version 4.71. Do not copy the security attributes of the file.
;~ 4096 Only operate in the local directory. Don't operate recursively into subdirectories.
;~ 8192 Version 5.0. Do not copy connected files as a group. Only copy the specified files.

_FileCopy("C:\Installed Apps\Patches\WindowsXP-KB835935-SP2-ENU.exe","C:\temp")

; to copy a directory the destination directory must exist

Func _FileCopy($fromFile,$tofile)
Local $FOF_RESPOND_YES = 16
Local $FOF_SIMPLEPROGRESS = 256
$winShell = ObjCreate("shell.application")
$winShell.namespace($tofile).CopyHere($fromFile,$FOF_RESPOND_YES)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

Snippets ( Files & Folders )

2014-05-12T19:24:45Z

Guinness: /* _FileDeleteEx */

__TOC__
[[category:Snippets]]

{{Snippet Credit Header}}

== _ConvertFileToUTF16 ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
_ConvertFileToUTF16(@ScriptDir & "\Example.xml")

Func _ConvertFileToUTF16($sFilePath)
Local $iEncoding = FileGetEncoding($sFilePath)
Local $hFileOpen = FileOpen($sFilePath, $iEncoding)
If $hFileOpen = -1 Then
Return SetError(1, 0, 0)
EndIf
Local $sData = FileRead($hFileOpen)
FileClose($hFileOpen)

$hFileOpen = FileOpen($sFilePath, 2 + 32)
If $hFileOpen = -1 Then
Return SetError(2, 0, 0)
EndIf
FileWrite($hFileOpen, $sData)
Return FileClose($hFileOpen)
EndFunc ;==>_ConvertFileToUTF16
</syntaxhighlight>

[[#top | ReturnToContents]]

== DropFiles ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
| Desc = Dropping multiple files onto a GUI
}}

<syntaxhighlight lang="autoit">
; Dropping multiple files onto a GUI

#include <APIConstants.au3>
#include <Array.au3>
#include <GUIConstantsEx.au3>
#include <WinAPIEx.au3>

Global $__aDropFiles

Example()

Func Example()
Local $hGUI = GUICreate('', 500, 500, -1, -1, -1, $WS_EX_ACCEPTFILES)

; Create a label that is transparent which will accept 'drop' events.
GUICtrlCreateLabel("", 0, 0, 500, 500)
GUICtrlSetBkColor(-1, $GUI_BKCOLOR_TRANSPARENT)
GUICtrlSetResizing(-1, $GUI_DOCKALL)
GUICtrlSetState(-1, $GUI_DROPACCEPTED)

GUIRegisterMsg($WM_DROPFILES, "WM_DROPFILES")
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop

Case $GUI_EVENT_DROPPED
If $__aDropFiles[0] > 0 Then
_ArrayDisplay($__aDropFiles)
EndIf

EndSwitch
WEnd
GUIDelete($hGUI)
EndFunc ;==>Example

Func WM_DROPFILES($hWnd, $iMsg, $iwParam, $ilParam)
#forceref $hWnd, $ilParam
Switch $iMsg
Case $WM_DROPFILES
Local $aReturn = _WinAPI_DragQueryFileEx($iwParam)
If IsArray($aReturn) Then
$__aDropFiles = $aReturn
Else
Local $aError[1] = [0]
$__aDropFiles = $aError
EndIf
EndSwitch
Return $GUI_RUNDEFMSG
EndFunc ;==>WM_DROPFILES
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ExitCheckTextChange ==

{{Snippet Header
| AuthorURL = 8007-negativenrg
| AuthorName = NegativeNrG
}}

<syntaxhighlight lang="autoit">
;Check(when Exit), if Text is not equal to $e_to Then, prompt the user to save or not save.
;_ExitCheckText Change $Edit Handle, $title of messagebox, $message of messagebox, $equal to(default = NULL).

Func _ExitCheckTextChange($E_hnd,$title,$message,$e_to = '')
Local $buffer, $choice, $filetosave, $handle1
$buffer = GUIctrlread($E_hnd)
If $buffer <> $e_to Then
$choice = Msgbox(4,$title,$message)
If $choice = 6 Then
$filetosave = FileSaveDialog('Choose File',@scriptdir,'(*.au3)')
$handle1 = FileOpen($filetosave,2)
FileWrite($handle1,$buffer)
Exit
Elseif $choice <> 6 Then
Exit
EndIf
Else
Exit
EndIf
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileDeleteEx ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Ref: http://msdn.microsoft.com/en-us/library/windows/desktop/aa365240(v=vs.85).aspx

#include <APIFilesConstants.au3>
#include <WinAPIFiles.au3>

ConsoleWrite(_FileDeleteEx("C:\Example.dat") & @CRLF)

Func _FileDeleteEx($sFilePath)
Return FileDelete($sFilePath) = 1 ? 1 : Int(_WinAPI_MoveFileEx(FileGetShortName($sFilePath), "", $MOVE_FILE_DELAY_UNTIL_REBOOT))
EndFunc ;==>_FileDeleteEx
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileCheck ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

; Check if the file was modified less than 24 hours ago.
ConsoleWrite( _FileCheck(@ScriptFullPath, 24) & @CRLF)

Func _FileCheck($sFilePath, $iHours = 24)
Local $aTime
If FileExists($sFilePath) = 0 Then
Return SetError(1, 0, 0)
EndIf
$aTime = FileGetTime($sFilePath, 0, 0)
Return Number(_DateDiff("h", $aTime[0] & "/" & $aTime[1] & "/" & $aTime[2] & " " & $aTime[3] & ":" & $aTime[4] & ":" & $aTime[5], @YEAR & "/" & @MON & "/" & @MDAY & " " & @HOUR & ":" & @MIN & ":" & @SEC) < $iHours)
EndFunc ;==>_FileCheck
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileCreateEx ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
_FileCreateEx(@ScriptDir & '\ExampleFile.txt', 42)

; Create a blank file with a certain size in bytes.
Func _FileCreateEx($sFilePath, $iBytes = 0)
Return RunWait(@ComSpec & ' /c fsutil file createnew "' & $sFilePath & '" ' & Int($iBytes), @WorkingDir, @SW_HIDE)
EndFunc ;==>_FileCreateEx
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileID ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

FileClose(FileOpen(@ScriptDir & '\ExampleFile.txt', 2))
ConsoleWrite(_FileID(@ScriptDir & '\ExampleFile.txt') & @CRLF)
FileDelete(@ScriptDir & '\ExampleFile.txt')

; Rerieve the file id of a filepath.
Func _FileID($sFilePath)
Local $iPID = Run(@ComSpec & ' /c fsutil file queryfileid "' & $sFilePath & '"', @SystemDir, @SW_HIDE, $STDOUT_CHILD + $STDERR_CHILD), $sReturn = ''
While 1
$sReturn &= StdoutRead($iPID)
If @error Then
ExitLoop
EndIf
WEnd
Return StringStripWS(StringRegExpReplace($sReturn, 'File\sID\sis\s(.*?)', '$1'), 8)
EndFunc ;==>_FileID
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileExistsWithQuotes ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_FileExistsWithQuotes('"' & @ScriptDir & '"') & @CRLF)
ConsoleWrite(_FileExistsWithQuotes("'" & @ScriptDir & "'") & @CRLF)
ConsoleWrite(_FileExistsWithQuotes(@ScriptDir) & @CRLF)

; Version: 1.00. AutoIt: V3.3.8.1
; Check a filepath ecists even if the path contains quotation marks.
Func _FileExistsWithQuotes($sFilePath)
Return FileExists(StringRegExpReplace($sFilePath, '^("|'')*([^"'']+)("|'')*$', '\2'))
EndFunc ;==>_FileExistsWithQuotes
</syntaxhighlight>

[[#top | ReturnToContents]]

== FileLineCount ==

{{Snippet Header
| AuthorURL = 71214-mkish
| AuthorName = MKISH
| Desc = Checks the number of lines in a file (useful for larger files as well)
}}

<syntaxhighlight lang="autoit">
; Author - MKISH

; Checks the number of lines in a file (useful for larger files as well)

#include <WinAPI.au3>

Local $FILE = "G:\WIN7\sources\boot.wim"
Local $COUNT = 0
Local $start = default
Local $res, $fLen, $err

While 1
$res = _HexSearch($FILE, StringToBinary("" & @crlf), $start)
$start = $res + 2
$COUNT = $COUNT + 1
If $res = -1 then exitloop
Wend

msgbox(64, "", "Lines count: " & $COUNT)

; _HexSearch function (originally written by Zinthose, modified by MKISH)
Func _HexSearch($FilePath, $BinaryValue, $StartOffset = Default)
Local $Buffer, $ptr, $hFile, $Result, $Read, $SearchValue, $Pos, $BufferSize = 2048
If $StartOffset = Default Then $StartOffset = 0
If Not FileExists($FilePath) Then Return SetError(1, @error, 0)
$fLen = FileGetSize($FilePath)
If $StartOffset > $fLen Then Return SetError(2, @error, 0)
If Not IsBinary($BinaryValue) Then Return SetError(3, @error, 0)
If Not IsNumber($StartOffset) Then Return SetError(4, @error, 0)
$SearchValue = BinaryToString($BinaryValue)
$Buffer = DllStructCreate("byte[" & $BufferSize & "]")
$ptr = DllStructGetPtr($Buffer)
$hFile = _WinAPI_CreateFile($FilePath, 2, 2, 1)
If $hFile = 0 Then Return SetError(5, @error, 0)
$Result = _WinAPI_SetFilePointer($hFile, $StartOffset)
$err = @error
If $Result = 0xFFFFFFFF Then
_WinAPI_CloseHandle($hFile)
Return SetError(5, $err, 0)
EndIf
$Pos = $StartOffset
While True
$Read = 0
$Result = _WinAPI_ReadFile($hFile, $ptr, $BufferSize, $Read)
$err = @error
If Not $Result Then
_WinAPI_CloseHandle($hFile)
Return SetError(6, $err, 0)
EndIf
$Result = DllStructGetData($Buffer, 1)
$Result = BinaryToString($Result)
$Result = StringInStr($Result, $SearchValue)
If $Result > 0 Then ExitLoop
If $Read < $BufferSize Then
_WinAPI_CloseHandle($hFile)
Return -1
EndIf
$Pos += $Read

WEnd
_WinAPI_CloseHandle($hFile)
If Not $Result Then Return SetError(7, @error, 0)
$Result = $Pos + $Result - 1
Return $Result
EndFunc; ==> _HexSearch
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileOpenDialog ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Local $sFilePath = _FileOpenDialog("", "", "Images (*.jpg;*.bmp)|Videos (*.avi;*.mpg)", Random(1, @DesktopWidth, 1), Random(1, @DesktopHeight, 1), 1 + 4, "")

ConsoleWrite('File = ' & $sFilePath & ', @error = ' & @error & @CRLF)

; #FUNCTION# ====================================================================================================================
; Name ..........: _FileOpenDialog
; Description ...: Initiates a Open File Dialog with the option to set the position of the GUI.
; Syntax ........: _FileOpenDialog($sTitle, $sIntitialDirectory, $sFilter[, $iLeft = -1[, $iTop = -1[, $iOptions = 0[,
; $sDefaultName = ""]]]])
; Parameters ....: $sTitle - Title text of the Dialog GUI.
; $sIntitialDirectory - Initial directory selected in the GUI file tree.
; $sFilter - File type single filter such as "All (*.*)" or "Text files (*.txt)".
; $iLeft - [optional] The left side of the dialog box. By default (-1), the window is centered.
; $iTop - [optional] The top of the dialog box. Default (-1) is centered
; $iOptions - [optional] Dialog Options: To use more than one option, add the required values together. See FileOpenDialog. Default is 0.
; $sDefaultName - [optional] Suggested file name for the user to open. Default is blank ("").
; Return values .: Success: Returns the full path of the file(s) chosen. Results for multiple selections are "Directory|file1|file2|..."
; Failure: Sets @error to non-zero.
; Author ........: guinness
; Remarks........: This doesn't change the working directory of the script like FileOpenDialog does.
; Example .......: Yes
; ===============================================================================================================================
Func _FileOpenDialog($sTitle, $sIntitialDirectory, $sFilter, $iLeft = -1, $iTop = -1, $iOptions = 0, $sDefaultName = "")
Local $hGUI = GUICreate('', -1, -1, $iLeft, $iTop), $sWorkingDir = @WorkingDir
Local $sFilePath = FileOpenDialog($sTitle, $sIntitialDirectory, $sFilter, $iOptions, $sDefaultName, $hGUI)
Local $iError = @error
FileChangeDir($sWorkingDir)
Return SetError($iError, GUIDelete($hGUI), $sFilePath)
EndFunc ;==>_FileOpenDialog()
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileRename ==

{{Snippet Header
| AuthorURL = 52374-johnone
| AuthorName = JohnOne
}}

<syntaxhighlight lang="autoit">
;### Rename a file ###
;$sFile = Full path to file
;$sRename = New Filename
;$iOverWrite = 0 or 1

;Success returns 1
;failure, returns 0 and sets @error
; 1 if FileMove fails,
; 2 if $sFile does not exist
;@extended
; 0 if the new file does not already exist / existed
; 1 if the new file already exists / existed

;#### Example ####
$File = @ScriptDir & '\filetorename.txt'
FileWrite($File, 'Test')
_FileRename($File, 'newname.txt')
If @error Then MsgBox(0, "Error", @error)

Func _FileRename($sFile, $sRename, $iOverWrite = 0)
Local Const $FILENOTEXIST = 2
If Not FileExists($sFile) Then Return SetError($FILENOTEXIST, 0, 0)
Local $_StringLen = StringLen($sFile)
Local $_StringInStr = StringInStr($sFile, "\", 0, -1, $_StringLen)
Local $_Count = $_StringLen - $_StringInStr
Local $_Dir = StringLeft($sFile, $_StringInStr)
Local $_NewFile = $_Dir & $sRename
Local $_NewFileExists = FileExists($_NewFile)
Local $_FileMove = FileMove($sFile, $_NewFile, $iOverWrite)
Return SetError(Not $_FileMove, $_NewFileExists, $_FileMove)
EndFunc ;==>_FileRename
</syntaxhighlight>

== _FileRename Alternative ==

<syntaxhighlight lang="autoit">

;FileRename(PathFile, RenameFile)
;JohnOne

FileRename(@ScriptDir & "\rename.txt", @ScriptDir & "\renamed.txt")

Func FileRename($FileName, $ReName)

Local $SHFILEOPSTRUCT, $SourceStruct, $DestStruct
Local Const $FO_RENAME = 0x0004
Local Const $FOF_SILENT = 0x0004
Local Const $FOF_NOCONFIRMATION = 0x0010
Local Const $FOF_NOERRORUI = 0x0400
Local Const $FOF_NOCONFIRMMKDIR = 0x0200
Local Const $NULL = 0

$SourceStruct = _StringToStruct($FileName)
$DestStruct = _StringToStruct($ReName)

$SHFILEOPSTRUCT = DllStructCreate("hwnd hWnd;uint wFunc;ptr pFrom;ptr pTo;int fFlags;int fAnyOperationsAborted;ptr hNameMappings;ptr lpszProgressTitle")

DllStructSetData($SHFILEOPSTRUCT, "hWnd", $NULL)
DllStructSetData($SHFILEOPSTRUCT, "wFunc", $FO_RENAME)
DllStructSetData($SHFILEOPSTRUCT, "pFrom", DllStructGetPtr($SourceStruct))
DllStructSetData($SHFILEOPSTRUCT, "pTo", DllStructGetPtr($DestStruct))
DllStructSetData($SHFILEOPSTRUCT, "fFlags", BitOR($FOF_SILENT, $FOF_NOCONFIRMATION, $FOF_NOERRORUI, $FOF_NOCONFIRMMKDIR))
DllStructSetData($SHFILEOPSTRUCT, "fAnyOperationsAborted", $NULL)
DllStructSetData($SHFILEOPSTRUCT, "hNameMappings", $NULL)
DllStructSetData($SHFILEOPSTRUCT, "lpszProgressTitle", $NULL)

$acall = DllCall("shell32.dll", "int", "SHFileOperation", "ptr", DllStructGetPtr($SHFILEOPSTRUCT))
If @error Then
Return SetError(@error, @extended, 0)
EndIf
Return 1
EndFunc ;==>FileRename

Func _StringToStruct($string)

Local $iLen = StringLen($string)
Local $Struct = DllStructCreate("char[" & String($iLen + 2) & "]")
DllStructSetData($Struct, 1, $string)
DllStructSetData($Struct, 1, 0, $iLen + 1)
DllStructSetData($Struct, 1, 0, $iLen + 2)

Return $Struct
EndFunc ;==>_StringToStruct

</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetFolderDepth ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Autoit 3.3.5.4 and Below
ConsoleWrite(_GetFolderDepth(@ScriptDir & '') & @CRLF)
ConsoleWrite(_GetFolderDepth(@ScriptDir) & @CRLF)
ConsoleWrite(_GetFolderDepth(@ScriptFullPath) & @CRLF)

; Get the folder depth of a filepath.
Func _GetFolderDepth($sFilePath)
If StringInStr($sFilePath, '.', 2, -1) Then
$sFilePath = StringLeft($sFilePath, StringInStr($sFilePath, "", 2, -1) - 1)
EndIf
Local $aArray = StringSplit(StringRegExpReplace($sFilePath, '[/]+z', ''), '')
Return $aArray[0] - 1
EndFunc ;==>_GetFolderDepth
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetFolderDepth ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Autoit 3.3.5.4 and Above
ConsoleWrite(_GetFolderDepth(@ScriptDir & '') & @CRLF)
ConsoleWrite(_GetFolderDepth(@ScriptDir) & @CRLF)
ConsoleWrite(_GetFolderDepth(@ScriptFullPath) & @CRLF)

; Get the folder depth of a filepath. Works with V3.3.5.4+
Func _GetFolderDepth($sFilePath)
If StringInStr($sFilePath, '.', 2, -1) Then
$sFilePath = StringLeft($sFilePath, StringInStr($sFilePath, "", 2, -1) - 1)
EndIf
Return StringSplit(StringRegExpReplace($sFilePath, '[/]+z', ''), '')[0] - 1
EndFunc ;==>_GetFolderDepth
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsDir ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite("IsDir: Using a file - " & IsDir(@ScriptFullPath) & @CRLF) ; Return 0
ConsoleWrite("IsFile: Using a file - " & IsFile(@ScriptFullPath) & @CRLF) ; Return 1
ConsoleWrite("IsDir: Using a directory - " & IsDir(@ScriptDir) & @CRLF) ; Return 1
ConsoleWrite("IsFile: Using a directory - " & IsFile(@ScriptDir) & @CRLF) ; Return 0

Func IsDir($sFilePath)
Return Number(FileExists($sFilePath) And StringInStr(FileGetAttrib($sFilePath), "D", 2, 1) > 0)
EndFunc ;==>IsDir
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Func IsFile($sFilePath)
Return Number(FileExists($sFilePath) And StringInStr(FileGetAttrib($sFilePath), "D", 2, 1) = 0)
EndFunc ;==>IsFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsFileDiff ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_IsFileDiff(@ScriptFullPath, @ScriptFullPath) & @CRLF) ; This will return False as the files are exactly the same.
ConsoleWrite(_IsFileDiff(@ScriptFullPath, @AutoItExe) & @CRLF) ; This will return True as the files are different.

; Check if a file is different.
Func _IsFileDiff($sFilePath_1, $sFilePath_2)
Return RunWait(@ComSpec & ' /c FC /B /W "' & $sFilePath_1 & '" "' & $sFilePath_2 & '"', @WorkingDir, @SW_HIDE) > 0
EndFunc ;==>_IsFileDiff
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsFileOlder ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <Date.au3> ; Required for _DateDiff()

; Check if the current script is older than 10 days.
If _IsFileOlder(@ScriptFullPath, 10) Then
MsgBox(4096, '', 'File is older than 10 days.')
Else
MsgBox(4096, '', 'File isn''t older than 10 days.')
EndIf

; Is a file older than a certain number of days.
Func _IsFileOlder($sFilePath, $iDays)
Local $aArray = FileGetTime($sFilePath, 0)
Return _DateDiff('D', $aArray[0] & '/' & $aArray[1] & '/' & $aArray[2] & ' ' & $aArray[3] & ':' & $aArray[4] & ':' & $aArray[5], @YEAR & '/' & @MON & '/' & @MDAY & ' ' & @HOUR & ':' & @MIN & ':' & @SEC) >= $iDays
EndFunc ;==>_IsFileOlder
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsFileSame ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_IsFileSame(@ScriptFullPath, @ScriptFullPath) & @CRLF) ; This will return True as the files are exactly the same.
ConsoleWrite(_IsFileSame(@ScriptFullPath, @AutoItExe) & @CRLF) ; This will return False as the files are different.

; Check if a file is the same.
Func _IsFileSame($sFilePath_1, $sFilePath_2)
Return RunWait(@ComSpec & ' /c FC /B /W "' & $sFilePath_1 & '" "' & $sFilePath_2 & '"', @WorkingDir, @SW_HIDE) = 0
EndFunc ;==>_IsFileSame
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IniReadFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

__INIFileFill(@ScriptDir & '\Example.ini') ; Create an INI file with random data.

Local $aArray = _IniReadFile(@ScriptDir & '\Example.ini')
FileDelete(@ScriptDir & '\Example.ini')
_ArrayDisplay($aArray)

Func _IniReadFile($sFilePath)
Local $aReturn[1][3] = [[0, 3]], $aSectionArray, $aSectionNameArray, $iCount = 0
$aSectionNameArray = IniReadSectionNames($sFilePath)
If @error Then
Return SetError(1, 0, $aReturn)
EndIf
For $A = 1 To $aSectionNameArray[0]
$aSectionArray = IniReadSection($sFilePath, $aSectionNameArray[$A])
If @error Then
ContinueLoop
EndIf
For $B = 1 To $aSectionArray[0][0]
$aReturn[0][0] += 1
$iCount += 1
If $aReturn[0][0] <= $iCount + 1 Then
ReDim $aReturn[$aReturn[0][0] * 2][$aReturn[0][1]]
EndIf
$aReturn[$iCount][0] = $aSectionArray[$B][0]
$aReturn[$iCount][1] = $aSectionArray[$B][1]
$aReturn[$iCount][2] = $aSectionNameArray[$A]
Next
Next
ReDim $aReturn[$aReturn[0][0] + 1][$aReturn[0][1]] ; Remove empty entries.
Return $aReturn
EndFunc ;==>_IniReadFile

Func __INIFileFill($sFilePath)
Local $sData = '', $sHeader = ''

For $i = 1 To Random(1, 5, 1)
$sHeader = _RandomText(Random(5, 25, 1))
$sData = ""
For $j = 1 To Random(1, 25, 1)
$sData &= _RandomText(Random(5, 25, 1)) & '=' & _RandomText(Random(5, 25, 1)) & @LF
Next
IniWriteSection($sFilePath, $sHeader, $sData)
Next
EndFunc ;==>__FillINIFile

Func _RandomText($iLength = 10)
Local $sData = '', $sRandom = ''
For $i = 1 To $iLength
$sRandom = Random(55, 116, 1)
$sData &= Chr($sRandom + 6 * ($sRandom > 90) - 7 * ($sRandom < 65))
Next
Return $sData
EndFunc ;==>_RandomText
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IniReadInit ==

{{Snippet Header
| AuthorURL = 9370-mlowery
| AuthorName = mlowery
}}

<syntaxhighlight lang="autoit">
;===============================================================================
; Description: Reads values from INI or creates INI with initial values.
; Intended to ensure all available INI settings are exposed
; and editable.
; Parameters are identical to IniRead()
; Parameter(s): $filename = filename of INI
; $section = section name of INI
; $key = key name in section
; $default = default value (written to INI if not exists)
; Requirement(s): None
; Return Value(s): Returns value from INI (or default if not defined)
; Note(s): Chr(127) used to detect non-existing value since won't normally exist in a text file
;===============================================================================
Func _IniReadInit($filename, $section, $key, $default)
Local $value = IniRead($filename, $section, $key, Chr(127))
If $value = Chr(127) Then
IniWrite($filename, $section, $key, $default)
$value = $default
EndIf
Return $value
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsValidFileType ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(@ScriptFullPath & " >> " & _IsValidFileType(@ScriptFullPath, "bat;cmd;au3") & @CRLF)
ConsoleWrite(@AutoItExe & " >> " & _IsValidFileType(@AutoItExe, "bat;cmd;au3") & @CRLF)

; Check if a filepath matches an extension filetype. Based on the idea by guinness - http://www.autoitscript.com/forum/topic/123674-isvalidfiletype/
Func _IsValidFileType($sFilePath, $sList = "bat;cmd;exe") ; By AZJIO - http://www.autoitscript.com/forum/topic/...filetype/page__view__findpost_
Local $iDot = StringInStr($sFilePath, ".", 0, -1)
Return $iDot And StringInStr(';' & $sList & ';', ';' & StringTrimLeft($sFilePath, $iDot) & ';') > 0
EndFunc ;==>_IsValidFileType
</syntaxhighlight>

<syntaxhighlight lang="autoit">
; Example 2

#include <WinAPIEx.au3>

ConsoleWrite(@ScriptFullPath & " >> " & _IsValidFileType(@ScriptFullPath, "bat;cmd;au3") & @CRLF)
ConsoleWrite(@AutoItExe & " >> " & _IsValidFileType(@AutoItExe, "bat;cmd;au3") & @CRLF)

; Check if a filepath matches an extension filetype. Based on the idea by guinness - http://www.autoitscript.com/forum/topic/123674-isvalidfiletype/
Func _IsValidFileType($sFilePath, $sList = "bat;cmd;exe", $iOpFast = 1) ; By Yashied.
If StringStripWS($sList, 8) = "" Then
$sList = "*"
EndIf
Return _WinAPI_PathMatchSpec($sFilePath, StringReplace(';' & $sList, ';', ';*.', 0, $iOpFast * 2))
EndFunc ;==>_IsValidFileType
</syntaxhighlight>

[[#top | ReturnToContents]]

== File Open/Save/Folder Dialog Box ==

{{Snippet Header
| AuthorURL = 2709-mhz
| AuthorName = MHz
| AuthorURL2 = 4997-odklizec
| AuthorName2 = odklizec
| AuthorURL3 = 6756-danny35d
| AuthorName3 = Danny35d
}}

<syntaxhighlight lang="autoit">
; Center - File Open/Save/Folder Dialog Box
; Author - odklizec, MHz, Danny35d

If StringInStr($cmdlineraw, '/MoveWin') Then
Local $size, $PosX, $PosY
$cmdlineraw = StringSplit(StringMid($cmdlineraw, StringInStr($cmdlineraw, '/MoveWin')), ':')
While 1
Select
Case WinExists($cmdlineraw[2])
$size=WinGetPos ($cmdlineraw[2])
$PosX=@DesktopWidth/2 - $size[2]/2
$PosY=@DesktopHeight/2 - $size[3]/2
WinMove($cmdlineraw[2], "", $PosX, $PosY)
WinActivate($cmdlineraw[2])
ExitLoop
EndSelect
Sleep(50)
WEnd
Exit
EndIf
Global $PID, $Read_File, $Save_File
$PID = _FindBrowseWin('Open file Dialog Box')
$Read_File = FileOpenDialog ( "Open file Dialog Box", @ScriptDir & "\", "AutoIt Files (*.au3)",3,@ScriptFullPath)
ProcessClose($PID)
$PID = _FindBrowseWin('Save file Dialog Box')
$Save_File = FileSaveDialog( "Save file Dialog Box", @ScriptDir, "Scripts (*.aut;*.au3)", 3)
ProcessClose($PID)
$PID = _FindBrowseWin('Browse for Folder')
FileSelectFolder("Choose a folder with plugins..", "","4","c:\")
ProcessClose($PID)

Func _FindBrowseWin($sTitle)
If @Compiled Then
Return(Run(@ScriptFullPath & ' /MoveWin:' & $sTitle))
Else
Return(Run(@AutoItExe & ' "' & @ScriptFullPath & '" /MoveWin:' & $sTitle))
EndIf
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _MoveFileOnReboot ==

{{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.2.0, Creation Date = 21/03/12.

; Function to Move or Delete a file on next reboot!
Func _MoveFileOnReboot($sSourcePath, $sDestPath = ""); If $sDestPath = "" the file is deleted instead of moved.
Local $iRet

; PendingFileRenameOperations (HKLM\SYSTEM\CurrentControlSet\Control\Session Manager)
If $DestPath = "" Then
$iRet = DllCall("kernel32.dll", "int", "MoveFileExA", "str", $sSourcePath, "int", 0, "dword", 4)
Else
$iRet = DllCall("kernel32.dll", "int", "MoveFileExA", "str", $sSourcePath, "str", $sDestPath, "dword", 4)
EndIf

Return $iRet
EndFunc ;==>_MoveFileOnReboot
</syntaxhighlight>

[[#top | ReturnToContents]]

== _MultipleFileOpenDialog ==

{{Snippet Header
| AuthorURL =
| AuthorName = /dev/null
}}

<syntaxhighlight lang="autoit">
Local $message = "Hold down Ctrl or Shift to choose multiple files."

Local $filename = _MultipleFileOpenDialog($message,300,300)

Local $var = FileOpenDialog($message, @WindowsDir & "\", "Images (*.jpg;*.bmp)", 1 + 4 )

If @error Then
MsgBox(4096,"","No File(s) chosen")
Else
$var = StringReplace($var, "|", @CRLF)
MsgBox(4096,"","You chose " & $var)
EndIf

FileDelete($filename)
func _MultipleFileOpenDialog($title,$posx,$posy)
Local $temp = EnvGet("temp")
Local $filename = $temp & "\move_file_open_dialog.au3"

Local $script = 'Global $title = "' & $title & '"' & @CRLF
$script &= 'Global $pos_x = ' & $posx & @CRLF
$script &= 'Global $pos_y = ' & $posy & @CRLF
$script &= 'AdlibRegister("_Move",10)' & @CRLF
$script &= 'while 1' & @CRLF
$script &= ' sleep(1000)' & @CRLF
$script &= 'wend' & @CRLF
$script &= 'Func _Move()' & @CRLF
$script &= ' if (WinActive($title)) Then' & @CRLF
$script &= ' WinMove($title,"",$pos_x,$pos_y)' & @CRLF
$script &= ' Exit' & @CRLF
$script &= ' EndIf' & @CRLF
$script &= 'EndFunc' & @CRLF

FileWrite($filename,$script)
;MsgBox(0,"",$script & @CRLF & $filename)
Run(@AutoItExe & " /AutoIt3ExecuteScript " & $filename)
sleep(250)
Return $filename
EndFunc ;==>_MultipleFileOpenDialog()
</syntaxhighlight>

[[#top | ReturnToContents]]

== _OpenFolder ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#cs
These have been declared in Global scope as you may wish to use them elsewhere in your script.
#ce
Global $ALTSTARTUP = 0x1d
Global $APPDATA = 0x1a
Global $BITBUCKET = 0x0a
Global $COMMONALTSTARTUP = 0x1e
Global $COMMONAPPDATA = 0x23
Global $COMMONDESKTOPDIR = 0x19
Global $COMMONFAVORITES = 0x1f
Global $COMMONPROGRAMS = 0x17
Global $COMMONSTARTMENU = 0x16
Global $COMMONSTARTUP = 0x18
Global $CONTROLS = 0x03
Global $COOKIES = 0x21
Global $DESKTOP = 0x00
Global $DESKTOPDIRECTORY = 0x10
Global $DRIVES = 0x11
Global $FAVORITES = 0x06
Global $FONTS = 0x14
Global $HISTORY = 0x22
Global $INTERNETCACHE = 0x20
Global $LOCALAPPDATA = 0x1c
Global $MYPICTURES = 0x27
Global $NETHOOD = 0x13
Global $NETWORK = 0x12
Global $PERSONAL = 0x05
Global $PRINTERS = 0x04
Global $PRINTHOOD = 0x1b
Global $PROFILE = 0x28
Global $PROGRAMFILES = 0x26
Global $PROGRAMFILESx86 = 0x30
Global $PROGRAMS = 0x02
Global $RECENT = 0x08
Global $SENDTO = 0x09
Global $STARTMENU = 0x0b
Global $STARTUP = 0x07
Global $SYSTEM = 0x25
Global $SYSTEMx86 = 0x29
Global $TEMPLATES = 0x15
Global $WINDOWS = 0x24

ConsoleWrite(_OpenFolder(@ScriptDir) & @CRLF)
ConsoleWrite(_OpenFolder($PRINTERS) & @CRLF)

; Open a folder or special folder variable, similar to using ShellExecute.
Func _OpenFolder($sFolderPath)
Local $oShell = ObjCreate('shell.application')
If @error Then
Return SetError(1, 0, 0)
EndIf
$oShell.Open($sFolderPath)
Return 1
EndFunc ;==>_OpenFolder
</syntaxhighlight>

[[#top | ReturnToContents]]

== _PathAppendToFilename ==

{{Snippet Header
| AuthorURL = 31965-progandy
| AuthorName = ProgAndy
}}

<syntaxhighlight lang="autoit">
$sOrg = "C:\Some.Folder\some.file.ext"
$sAdd = "_backup"

$sNew = _PathAppendToFilename($sOrg, $sAdd)

$sStripped = _PathStripRightFromFilename($sNew, $sAdd)

MsgBox(0, "", $sOrg & @CRLF & $sAdd & @CRLF & $sNew & @CRLF & $sStripped)

Func _PathAppendToFilename($sName, $sAppend)
; Author: ProgAndy
If StringRegExp($sAppend, '[\/\\:\?"<>\|\*]') Then Return SetError(1, 0, $sName)
Return StringRegExpReplace($sName, "(\.[^\\/\.]+)$", $sAppend & "\1", 1)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _PathStripRightFromFilename ==

{{Snippet Header
| AuthorURL = 31965-progandy
| AuthorName = ProgAndy
}}

<syntaxhighlight lang="autoit">
Func _PathStripRightFromFilename($sName, $sStrip)
; Author: ProgAndy
If StringRegExp($sStrip, '[\/\\:\?"<>\|\*]') Then Return SetError(1, 0, $sName)
Return StringRegExpReplace($sName, "\Q" & $sStrip & "\E(\.[^\\/\.]+)$", "\1", 1)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SelfDelete ==

{{Snippet Header
| AuthorURL = 2709-mhz
| AuthorName = MHz
}}

<syntaxhighlight lang="autoit">
; This also removes the directory which the file is in
; Author MHz with the directory delete addition by The Kandie Man
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 _
& ':loop2' & @CRLF _
& 'rmdir /q "' & $dirToDelete & '"' & @CRLF _
& 'if exist "' & $dirToDelete & '" goto loop2' & @CRLF _
& 'del ' & @TempDir & '\scratch.bat'
FileWrite(@TempDir & "\scratch.bat", $sCmdFile)
Run(@TempDir & "\scratch.bat", @TempDir, @SW_HIDE)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ShellExecuteFileSelectFolder ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_ShellExecuteFileSelectFolder('Select a Folder', @HomeDrive) & @CRLF)

; Shell Execute a selected folder.
Func _ShellExecuteFileSelectFolder($sText, $sRoot, $iFlag = 0, $sInitialDir = '', $hWnd = '')
Local $sFolder = FileSelectFolder($sText, $sRoot, $iFlag, $sInitialDir, $hWnd)
If @error Then
Return SetError(@error, @extended, '')
EndIf
ShellExecute($sFolder)
Return $sFolder
EndFunc ;==>_ShellExecuteFileSelectFolder
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SuiCide ==

{{Snippet Header
| AuthorURL = 28010-larrydalooza
| AuthorName = LarryDalooza
}}

<syntaxhighlight lang="autoit">
; IMPORTANT MAKE A COPY OF SCRIPT BEFORE DELETION
; Deletes the running script

Func SuiCide()
Local $sFilePath = @TempDir & '\SuiCide.bat'
FileDelete($sFilePath)
FileWrite($sFilePath, 'loop:' & @CRLF & 'del "' & @ScriptFullPath & '"' & @CRLF & _
'ping -n 1 -w 250 zxywqxz_q' & @CRLF & 'if exist "' & @ScriptFullPath & _
'" goto loop' & @CRLF & 'del SuiCide.bat' & @CRLF)
Exit Run($sFilePath, @TempDir, @SW_HIDE)
EndFunc ;==>SuiCide
</syntaxhighlight>

[[#top | ReturnToContents]]

== _UniqueFilename ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">

ConsoleWrite(_UniqueFilename(@ScriptDir, '.au3') & @CRLF)

Func _UniqueFilename($sFilePath, $sExtension)
Local $iRandom = 0, $sUnqiueFileName = ''

$sExtension = '.' & StringRegExpReplace($sExtension, '\A[\.]+', '')
$sFilePath = StringRegExpReplace($sFilePath, '[\\/]+\z', '') & '\'
While 1
$iRandom = Random(55, 116, 1)
$sUnqiueFileName &= Chr($iRandom + 6 * ($iRandom > 90) - 7 * ($iRandom < 65))
If FileExists($sFilePath & $sUnqiueFileName & $sExtension) = 0 And StringLen($sUnqiueFileName) > 7 Then
ExitLoop
EndIf
WEnd
Return $sFilePath & $sUnqiueFileName & $sExtension
EndFunc ;==>_UniqueFilename
</syntaxhighlight>

[[#top | ReturnToContents]]

== Windows - Copy With Progress ==

{{Snippet Header
| AuthorURL = 19-jos
| AuthorName = Jos
}}

<syntaxhighlight lang="autoit">
; Windows - Copy With Progress

;~ 4 Do not display a progress dialog box.
;~ 8 Give the file being operated on a new name in a move, copy, or rename operation if a file with the target name already exists.
;~ 16 Respond with "Yes to All" for any dialog box that is displayed.
;~ 64 Preserve undo information, if possible.
;~ 128 Perform the operation on files only if a wildcard file name (*.*) is specified.
;~ 256 Display a progress dialog box but do not show the file names.
;~ 512 Do not confirm the creation of a new directory if the operation requires one to be created.
;~ 1024 Do not display a user interface if an error occurs.
;~ 2048 Version 4.71. Do not copy the security attributes of the file.
;~ 4096 Only operate in the local directory. Don't operate recursively into subdirectories.
;~ 8192 Version 5.0. Do not copy connected files as a group. Only copy the specified files.

_FileCopy("C:\Installed Apps\Patches\WindowsXP-KB835935-SP2-ENU.exe","C:\temp")

; to copy a directory the destination directory must exist

Func _FileCopy($fromFile,$tofile)
Local $FOF_RESPOND_YES = 16
Local $FOF_SIMPLEPROGRESS = 256
$winShell = ObjCreate("shell.application")
$winShell.namespace($tofile).CopyHere($fromFile,$FOF_RESPOND_YES)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

Snippets ( Files & Folders )

2014-05-12T19:21:05Z

Guinness: /* DropFiles */

__TOC__
[[category:Snippets]]

{{Snippet Credit Header}}

== _ConvertFileToUTF16 ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
_ConvertFileToUTF16(@ScriptDir & "\Example.xml")

Func _ConvertFileToUTF16($sFilePath)
Local $iEncoding = FileGetEncoding($sFilePath)
Local $hFileOpen = FileOpen($sFilePath, $iEncoding)
If $hFileOpen = -1 Then
Return SetError(1, 0, 0)
EndIf
Local $sData = FileRead($hFileOpen)
FileClose($hFileOpen)

$hFileOpen = FileOpen($sFilePath, 2 + 32)
If $hFileOpen = -1 Then
Return SetError(2, 0, 0)
EndIf
FileWrite($hFileOpen, $sData)
Return FileClose($hFileOpen)
EndFunc ;==>_ConvertFileToUTF16
</syntaxhighlight>

[[#top | ReturnToContents]]

== DropFiles ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
| Desc = Dropping multiple files onto a GUI
}}

<syntaxhighlight lang="autoit">
; Dropping multiple files onto a GUI

#include <APIConstants.au3>
#include <Array.au3>
#include <GUIConstantsEx.au3>
#include <WinAPIEx.au3>

Global $__aDropFiles

Example()

Func Example()
Local $hGUI = GUICreate('', 500, 500, -1, -1, -1, $WS_EX_ACCEPTFILES)

; Create a label that is transparent which will accept 'drop' events.
GUICtrlCreateLabel("", 0, 0, 500, 500)
GUICtrlSetBkColor(-1, $GUI_BKCOLOR_TRANSPARENT)
GUICtrlSetResizing(-1, $GUI_DOCKALL)
GUICtrlSetState(-1, $GUI_DROPACCEPTED)

GUIRegisterMsg($WM_DROPFILES, "WM_DROPFILES")
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop

Case $GUI_EVENT_DROPPED
If $__aDropFiles[0] > 0 Then
_ArrayDisplay($__aDropFiles)
EndIf

EndSwitch
WEnd
GUIDelete($hGUI)
EndFunc ;==>Example

Func WM_DROPFILES($hWnd, $iMsg, $iwParam, $ilParam)
#forceref $hWnd, $ilParam
Switch $iMsg
Case $WM_DROPFILES
Local $aReturn = _WinAPI_DragQueryFileEx($iwParam)
If IsArray($aReturn) Then
$__aDropFiles = $aReturn
Else
Local $aError[1] = [0]
$__aDropFiles = $aError
EndIf
EndSwitch
Return $GUI_RUNDEFMSG
EndFunc ;==>WM_DROPFILES
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ExitCheckTextChange ==

{{Snippet Header
| AuthorURL = 8007-negativenrg
| AuthorName = NegativeNrG
}}

<syntaxhighlight lang="autoit">
;Check(when Exit), if Text is not equal to $e_to Then, prompt the user to save or not save.
;_ExitCheckText Change $Edit Handle, $title of messagebox, $message of messagebox, $equal to(default = NULL).

Func _ExitCheckTextChange($E_hnd,$title,$message,$e_to = '')
Local $buffer, $choice, $filetosave, $handle1
$buffer = GUIctrlread($E_hnd)
If $buffer <> $e_to Then
$choice = Msgbox(4,$title,$message)
If $choice = 6 Then
$filetosave = FileSaveDialog('Choose File',@scriptdir,'(*.au3)')
$handle1 = FileOpen($filetosave,2)
FileWrite($handle1,$buffer)
Exit
Elseif $choice <> 6 Then
Exit
EndIf
Else
Exit
EndIf
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileDeleteEx ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Ref: http://msdn.microsoft.com/en-us/library/windows/desktop/aa365240(v=vs.85).aspx

#include <APIConstants.au3> ; Included with WinAPIEx.au3
#include <WinAPIEx.au3> ; Download From http://www.autoitscript.com/forum/topic/98712-winapiex-udf/ by Yashied.

ConsoleWrite(_FileDeleteEx("C:\Example.dat") & @LF)

Func _FileDeleteEx($sFilePath)
Local $iReturn = FileDelete($sFilePath)
If $iReturn Then
Return $iReturn
EndIf
Return _WinAPI_MoveFileEx(FileGetShortName($sFilePath), "", $MOVE_FILE_DELAY_UNTIL_REBOOT)
EndFunc ;==>_FileDeleteEx
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileCheck ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

; Check if the file was modified less than 24 hours ago.
ConsoleWrite( _FileCheck(@ScriptFullPath, 24) & @CRLF)

Func _FileCheck($sFilePath, $iHours = 24)
Local $aTime
If FileExists($sFilePath) = 0 Then
Return SetError(1, 0, 0)
EndIf
$aTime = FileGetTime($sFilePath, 0, 0)
Return Number(_DateDiff("h", $aTime[0] & "/" & $aTime[1] & "/" & $aTime[2] & " " & $aTime[3] & ":" & $aTime[4] & ":" & $aTime[5], @YEAR & "/" & @MON & "/" & @MDAY & " " & @HOUR & ":" & @MIN & ":" & @SEC) < $iHours)
EndFunc ;==>_FileCheck
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileCreateEx ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
_FileCreateEx(@ScriptDir & '\ExampleFile.txt', 42)

; Create a blank file with a certain size in bytes.
Func _FileCreateEx($sFilePath, $iBytes = 0)
Return RunWait(@ComSpec & ' /c fsutil file createnew "' & $sFilePath & '" ' & Int($iBytes), @WorkingDir, @SW_HIDE)
EndFunc ;==>_FileCreateEx
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileID ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

FileClose(FileOpen(@ScriptDir & '\ExampleFile.txt', 2))
ConsoleWrite(_FileID(@ScriptDir & '\ExampleFile.txt') & @CRLF)
FileDelete(@ScriptDir & '\ExampleFile.txt')

; Rerieve the file id of a filepath.
Func _FileID($sFilePath)
Local $iPID = Run(@ComSpec & ' /c fsutil file queryfileid "' & $sFilePath & '"', @SystemDir, @SW_HIDE, $STDOUT_CHILD + $STDERR_CHILD), $sReturn = ''
While 1
$sReturn &= StdoutRead($iPID)
If @error Then
ExitLoop
EndIf
WEnd
Return StringStripWS(StringRegExpReplace($sReturn, 'File\sID\sis\s(.*?)', '$1'), 8)
EndFunc ;==>_FileID
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileExistsWithQuotes ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_FileExistsWithQuotes('"' & @ScriptDir & '"') & @CRLF)
ConsoleWrite(_FileExistsWithQuotes("'" & @ScriptDir & "'") & @CRLF)
ConsoleWrite(_FileExistsWithQuotes(@ScriptDir) & @CRLF)

; Version: 1.00. AutoIt: V3.3.8.1
; Check a filepath ecists even if the path contains quotation marks.
Func _FileExistsWithQuotes($sFilePath)
Return FileExists(StringRegExpReplace($sFilePath, '^("|'')*([^"'']+)("|'')*$', '\2'))
EndFunc ;==>_FileExistsWithQuotes
</syntaxhighlight>

[[#top | ReturnToContents]]

== FileLineCount ==

{{Snippet Header
| AuthorURL = 71214-mkish
| AuthorName = MKISH
| Desc = Checks the number of lines in a file (useful for larger files as well)
}}

<syntaxhighlight lang="autoit">
; Author - MKISH

; Checks the number of lines in a file (useful for larger files as well)

#include <WinAPI.au3>

Local $FILE = "G:\WIN7\sources\boot.wim"
Local $COUNT = 0
Local $start = default
Local $res, $fLen, $err

While 1
$res = _HexSearch($FILE, StringToBinary("" & @crlf), $start)
$start = $res + 2
$COUNT = $COUNT + 1
If $res = -1 then exitloop
Wend

msgbox(64, "", "Lines count: " & $COUNT)

; _HexSearch function (originally written by Zinthose, modified by MKISH)
Func _HexSearch($FilePath, $BinaryValue, $StartOffset = Default)
Local $Buffer, $ptr, $hFile, $Result, $Read, $SearchValue, $Pos, $BufferSize = 2048
If $StartOffset = Default Then $StartOffset = 0
If Not FileExists($FilePath) Then Return SetError(1, @error, 0)
$fLen = FileGetSize($FilePath)
If $StartOffset > $fLen Then Return SetError(2, @error, 0)
If Not IsBinary($BinaryValue) Then Return SetError(3, @error, 0)
If Not IsNumber($StartOffset) Then Return SetError(4, @error, 0)
$SearchValue = BinaryToString($BinaryValue)
$Buffer = DllStructCreate("byte[" & $BufferSize & "]")
$ptr = DllStructGetPtr($Buffer)
$hFile = _WinAPI_CreateFile($FilePath, 2, 2, 1)
If $hFile = 0 Then Return SetError(5, @error, 0)
$Result = _WinAPI_SetFilePointer($hFile, $StartOffset)
$err = @error
If $Result = 0xFFFFFFFF Then
_WinAPI_CloseHandle($hFile)
Return SetError(5, $err, 0)
EndIf
$Pos = $StartOffset
While True
$Read = 0
$Result = _WinAPI_ReadFile($hFile, $ptr, $BufferSize, $Read)
$err = @error
If Not $Result Then
_WinAPI_CloseHandle($hFile)
Return SetError(6, $err, 0)
EndIf
$Result = DllStructGetData($Buffer, 1)
$Result = BinaryToString($Result)
$Result = StringInStr($Result, $SearchValue)
If $Result > 0 Then ExitLoop
If $Read < $BufferSize Then
_WinAPI_CloseHandle($hFile)
Return -1
EndIf
$Pos += $Read

WEnd
_WinAPI_CloseHandle($hFile)
If Not $Result Then Return SetError(7, @error, 0)
$Result = $Pos + $Result - 1
Return $Result
EndFunc; ==> _HexSearch
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileOpenDialog ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Local $sFilePath = _FileOpenDialog("", "", "Images (*.jpg;*.bmp)|Videos (*.avi;*.mpg)", Random(1, @DesktopWidth, 1), Random(1, @DesktopHeight, 1), 1 + 4, "")

ConsoleWrite('File = ' & $sFilePath & ', @error = ' & @error & @CRLF)

; #FUNCTION# ====================================================================================================================
; Name ..........: _FileOpenDialog
; Description ...: Initiates a Open File Dialog with the option to set the position of the GUI.
; Syntax ........: _FileOpenDialog($sTitle, $sIntitialDirectory, $sFilter[, $iLeft = -1[, $iTop = -1[, $iOptions = 0[,
; $sDefaultName = ""]]]])
; Parameters ....: $sTitle - Title text of the Dialog GUI.
; $sIntitialDirectory - Initial directory selected in the GUI file tree.
; $sFilter - File type single filter such as "All (*.*)" or "Text files (*.txt)".
; $iLeft - [optional] The left side of the dialog box. By default (-1), the window is centered.
; $iTop - [optional] The top of the dialog box. Default (-1) is centered
; $iOptions - [optional] Dialog Options: To use more than one option, add the required values together. See FileOpenDialog. Default is 0.
; $sDefaultName - [optional] Suggested file name for the user to open. Default is blank ("").
; Return values .: Success: Returns the full path of the file(s) chosen. Results for multiple selections are "Directory|file1|file2|..."
; Failure: Sets @error to non-zero.
; Author ........: guinness
; Remarks........: This doesn't change the working directory of the script like FileOpenDialog does.
; Example .......: Yes
; ===============================================================================================================================
Func _FileOpenDialog($sTitle, $sIntitialDirectory, $sFilter, $iLeft = -1, $iTop = -1, $iOptions = 0, $sDefaultName = "")
Local $hGUI = GUICreate('', -1, -1, $iLeft, $iTop), $sWorkingDir = @WorkingDir
Local $sFilePath = FileOpenDialog($sTitle, $sIntitialDirectory, $sFilter, $iOptions, $sDefaultName, $hGUI)
Local $iError = @error
FileChangeDir($sWorkingDir)
Return SetError($iError, GUIDelete($hGUI), $sFilePath)
EndFunc ;==>_FileOpenDialog()
</syntaxhighlight>

[[#top | ReturnToContents]]

== _FileRename ==

{{Snippet Header
| AuthorURL = 52374-johnone
| AuthorName = JohnOne
}}

<syntaxhighlight lang="autoit">
;### Rename a file ###
;$sFile = Full path to file
;$sRename = New Filename
;$iOverWrite = 0 or 1

;Success returns 1
;failure, returns 0 and sets @error
; 1 if FileMove fails,
; 2 if $sFile does not exist
;@extended
; 0 if the new file does not already exist / existed
; 1 if the new file already exists / existed

;#### Example ####
$File = @ScriptDir & '\filetorename.txt'
FileWrite($File, 'Test')
_FileRename($File, 'newname.txt')
If @error Then MsgBox(0, "Error", @error)

Func _FileRename($sFile, $sRename, $iOverWrite = 0)
Local Const $FILENOTEXIST = 2
If Not FileExists($sFile) Then Return SetError($FILENOTEXIST, 0, 0)
Local $_StringLen = StringLen($sFile)
Local $_StringInStr = StringInStr($sFile, "\", 0, -1, $_StringLen)
Local $_Count = $_StringLen - $_StringInStr
Local $_Dir = StringLeft($sFile, $_StringInStr)
Local $_NewFile = $_Dir & $sRename
Local $_NewFileExists = FileExists($_NewFile)
Local $_FileMove = FileMove($sFile, $_NewFile, $iOverWrite)
Return SetError(Not $_FileMove, $_NewFileExists, $_FileMove)
EndFunc ;==>_FileRename
</syntaxhighlight>

== _FileRename Alternative ==

<syntaxhighlight lang="autoit">

;FileRename(PathFile, RenameFile)
;JohnOne

FileRename(@ScriptDir & "\rename.txt", @ScriptDir & "\renamed.txt")

Func FileRename($FileName, $ReName)

Local $SHFILEOPSTRUCT, $SourceStruct, $DestStruct
Local Const $FO_RENAME = 0x0004
Local Const $FOF_SILENT = 0x0004
Local Const $FOF_NOCONFIRMATION = 0x0010
Local Const $FOF_NOERRORUI = 0x0400
Local Const $FOF_NOCONFIRMMKDIR = 0x0200
Local Const $NULL = 0

$SourceStruct = _StringToStruct($FileName)
$DestStruct = _StringToStruct($ReName)

$SHFILEOPSTRUCT = DllStructCreate("hwnd hWnd;uint wFunc;ptr pFrom;ptr pTo;int fFlags;int fAnyOperationsAborted;ptr hNameMappings;ptr lpszProgressTitle")

DllStructSetData($SHFILEOPSTRUCT, "hWnd", $NULL)
DllStructSetData($SHFILEOPSTRUCT, "wFunc", $FO_RENAME)
DllStructSetData($SHFILEOPSTRUCT, "pFrom", DllStructGetPtr($SourceStruct))
DllStructSetData($SHFILEOPSTRUCT, "pTo", DllStructGetPtr($DestStruct))
DllStructSetData($SHFILEOPSTRUCT, "fFlags", BitOR($FOF_SILENT, $FOF_NOCONFIRMATION, $FOF_NOERRORUI, $FOF_NOCONFIRMMKDIR))
DllStructSetData($SHFILEOPSTRUCT, "fAnyOperationsAborted", $NULL)
DllStructSetData($SHFILEOPSTRUCT, "hNameMappings", $NULL)
DllStructSetData($SHFILEOPSTRUCT, "lpszProgressTitle", $NULL)

$acall = DllCall("shell32.dll", "int", "SHFileOperation", "ptr", DllStructGetPtr($SHFILEOPSTRUCT))
If @error Then
Return SetError(@error, @extended, 0)
EndIf
Return 1
EndFunc ;==>FileRename

Func _StringToStruct($string)

Local $iLen = StringLen($string)
Local $Struct = DllStructCreate("char[" & String($iLen + 2) & "]")
DllStructSetData($Struct, 1, $string)
DllStructSetData($Struct, 1, 0, $iLen + 1)
DllStructSetData($Struct, 1, 0, $iLen + 2)

Return $Struct
EndFunc ;==>_StringToStruct

</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetFolderDepth ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Autoit 3.3.5.4 and Below
ConsoleWrite(_GetFolderDepth(@ScriptDir & '') & @CRLF)
ConsoleWrite(_GetFolderDepth(@ScriptDir) & @CRLF)
ConsoleWrite(_GetFolderDepth(@ScriptFullPath) & @CRLF)

; Get the folder depth of a filepath.
Func _GetFolderDepth($sFilePath)
If StringInStr($sFilePath, '.', 2, -1) Then
$sFilePath = StringLeft($sFilePath, StringInStr($sFilePath, "", 2, -1) - 1)
EndIf
Local $aArray = StringSplit(StringRegExpReplace($sFilePath, '[/]+z', ''), '')
Return $aArray[0] - 1
EndFunc ;==>_GetFolderDepth
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GetFolderDepth ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Autoit 3.3.5.4 and Above
ConsoleWrite(_GetFolderDepth(@ScriptDir & '') & @CRLF)
ConsoleWrite(_GetFolderDepth(@ScriptDir) & @CRLF)
ConsoleWrite(_GetFolderDepth(@ScriptFullPath) & @CRLF)

; Get the folder depth of a filepath. Works with V3.3.5.4+
Func _GetFolderDepth($sFilePath)
If StringInStr($sFilePath, '.', 2, -1) Then
$sFilePath = StringLeft($sFilePath, StringInStr($sFilePath, "", 2, -1) - 1)
EndIf
Return StringSplit(StringRegExpReplace($sFilePath, '[/]+z', ''), '')[0] - 1
EndFunc ;==>_GetFolderDepth
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsDir ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite("IsDir: Using a file - " & IsDir(@ScriptFullPath) & @CRLF) ; Return 0
ConsoleWrite("IsFile: Using a file - " & IsFile(@ScriptFullPath) & @CRLF) ; Return 1
ConsoleWrite("IsDir: Using a directory - " & IsDir(@ScriptDir) & @CRLF) ; Return 1
ConsoleWrite("IsFile: Using a directory - " & IsFile(@ScriptDir) & @CRLF) ; Return 0

Func IsDir($sFilePath)
Return Number(FileExists($sFilePath) And StringInStr(FileGetAttrib($sFilePath), "D", 2, 1) > 0)
EndFunc ;==>IsDir
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Func IsFile($sFilePath)
Return Number(FileExists($sFilePath) And StringInStr(FileGetAttrib($sFilePath), "D", 2, 1) = 0)
EndFunc ;==>IsFile
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsFileDiff ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_IsFileDiff(@ScriptFullPath, @ScriptFullPath) & @CRLF) ; This will return False as the files are exactly the same.
ConsoleWrite(_IsFileDiff(@ScriptFullPath, @AutoItExe) & @CRLF) ; This will return True as the files are different.

; Check if a file is different.
Func _IsFileDiff($sFilePath_1, $sFilePath_2)
Return RunWait(@ComSpec & ' /c FC /B /W "' & $sFilePath_1 & '" "' & $sFilePath_2 & '"', @WorkingDir, @SW_HIDE) > 0
EndFunc ;==>_IsFileDiff
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsFileOlder ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <Date.au3> ; Required for _DateDiff()

; Check if the current script is older than 10 days.
If _IsFileOlder(@ScriptFullPath, 10) Then
MsgBox(4096, '', 'File is older than 10 days.')
Else
MsgBox(4096, '', 'File isn''t older than 10 days.')
EndIf

; Is a file older than a certain number of days.
Func _IsFileOlder($sFilePath, $iDays)
Local $aArray = FileGetTime($sFilePath, 0)
Return _DateDiff('D', $aArray[0] & '/' & $aArray[1] & '/' & $aArray[2] & ' ' & $aArray[3] & ':' & $aArray[4] & ':' & $aArray[5], @YEAR & '/' & @MON & '/' & @MDAY & ' ' & @HOUR & ':' & @MIN & ':' & @SEC) >= $iDays
EndFunc ;==>_IsFileOlder
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsFileSame ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_IsFileSame(@ScriptFullPath, @ScriptFullPath) & @CRLF) ; This will return True as the files are exactly the same.
ConsoleWrite(_IsFileSame(@ScriptFullPath, @AutoItExe) & @CRLF) ; This will return False as the files are different.

; Check if a file is the same.
Func _IsFileSame($sFilePath_1, $sFilePath_2)
Return RunWait(@ComSpec & ' /c FC /B /W "' & $sFilePath_1 & '" "' & $sFilePath_2 & '"', @WorkingDir, @SW_HIDE) = 0
EndFunc ;==>_IsFileSame
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IniReadFile ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

__INIFileFill(@ScriptDir & '\Example.ini') ; Create an INI file with random data.

Local $aArray = _IniReadFile(@ScriptDir & '\Example.ini')
FileDelete(@ScriptDir & '\Example.ini')
_ArrayDisplay($aArray)

Func _IniReadFile($sFilePath)
Local $aReturn[1][3] = [[0, 3]], $aSectionArray, $aSectionNameArray, $iCount = 0
$aSectionNameArray = IniReadSectionNames($sFilePath)
If @error Then
Return SetError(1, 0, $aReturn)
EndIf
For $A = 1 To $aSectionNameArray[0]
$aSectionArray = IniReadSection($sFilePath, $aSectionNameArray[$A])
If @error Then
ContinueLoop
EndIf
For $B = 1 To $aSectionArray[0][0]
$aReturn[0][0] += 1
$iCount += 1
If $aReturn[0][0] <= $iCount + 1 Then
ReDim $aReturn[$aReturn[0][0] * 2][$aReturn[0][1]]
EndIf
$aReturn[$iCount][0] = $aSectionArray[$B][0]
$aReturn[$iCount][1] = $aSectionArray[$B][1]
$aReturn[$iCount][2] = $aSectionNameArray[$A]
Next
Next
ReDim $aReturn[$aReturn[0][0] + 1][$aReturn[0][1]] ; Remove empty entries.
Return $aReturn
EndFunc ;==>_IniReadFile

Func __INIFileFill($sFilePath)
Local $sData = '', $sHeader = ''

For $i = 1 To Random(1, 5, 1)
$sHeader = _RandomText(Random(5, 25, 1))
$sData = ""
For $j = 1 To Random(1, 25, 1)
$sData &= _RandomText(Random(5, 25, 1)) & '=' & _RandomText(Random(5, 25, 1)) & @LF
Next
IniWriteSection($sFilePath, $sHeader, $sData)
Next
EndFunc ;==>__FillINIFile

Func _RandomText($iLength = 10)
Local $sData = '', $sRandom = ''
For $i = 1 To $iLength
$sRandom = Random(55, 116, 1)
$sData &= Chr($sRandom + 6 * ($sRandom > 90) - 7 * ($sRandom < 65))
Next
Return $sData
EndFunc ;==>_RandomText
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IniReadInit ==

{{Snippet Header
| AuthorURL = 9370-mlowery
| AuthorName = mlowery
}}

<syntaxhighlight lang="autoit">
;===============================================================================
; Description: Reads values from INI or creates INI with initial values.
; Intended to ensure all available INI settings are exposed
; and editable.
; Parameters are identical to IniRead()
; Parameter(s): $filename = filename of INI
; $section = section name of INI
; $key = key name in section
; $default = default value (written to INI if not exists)
; Requirement(s): None
; Return Value(s): Returns value from INI (or default if not defined)
; Note(s): Chr(127) used to detect non-existing value since won't normally exist in a text file
;===============================================================================
Func _IniReadInit($filename, $section, $key, $default)
Local $value = IniRead($filename, $section, $key, Chr(127))
If $value = Chr(127) Then
IniWrite($filename, $section, $key, $default)
$value = $default
EndIf
Return $value
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsValidFileType ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(@ScriptFullPath & " >> " & _IsValidFileType(@ScriptFullPath, "bat;cmd;au3") & @CRLF)
ConsoleWrite(@AutoItExe & " >> " & _IsValidFileType(@AutoItExe, "bat;cmd;au3") & @CRLF)

; Check if a filepath matches an extension filetype. Based on the idea by guinness - http://www.autoitscript.com/forum/topic/123674-isvalidfiletype/
Func _IsValidFileType($sFilePath, $sList = "bat;cmd;exe") ; By AZJIO - http://www.autoitscript.com/forum/topic/...filetype/page__view__findpost_
Local $iDot = StringInStr($sFilePath, ".", 0, -1)
Return $iDot And StringInStr(';' & $sList & ';', ';' & StringTrimLeft($sFilePath, $iDot) & ';') > 0
EndFunc ;==>_IsValidFileType
</syntaxhighlight>

<syntaxhighlight lang="autoit">
; Example 2

#include <WinAPIEx.au3>

ConsoleWrite(@ScriptFullPath & " >> " & _IsValidFileType(@ScriptFullPath, "bat;cmd;au3") & @CRLF)
ConsoleWrite(@AutoItExe & " >> " & _IsValidFileType(@AutoItExe, "bat;cmd;au3") & @CRLF)

; Check if a filepath matches an extension filetype. Based on the idea by guinness - http://www.autoitscript.com/forum/topic/123674-isvalidfiletype/
Func _IsValidFileType($sFilePath, $sList = "bat;cmd;exe", $iOpFast = 1) ; By Yashied.
If StringStripWS($sList, 8) = "" Then
$sList = "*"
EndIf
Return _WinAPI_PathMatchSpec($sFilePath, StringReplace(';' & $sList, ';', ';*.', 0, $iOpFast * 2))
EndFunc ;==>_IsValidFileType
</syntaxhighlight>

[[#top | ReturnToContents]]

== File Open/Save/Folder Dialog Box ==

{{Snippet Header
| AuthorURL = 2709-mhz
| AuthorName = MHz
| AuthorURL2 = 4997-odklizec
| AuthorName2 = odklizec
| AuthorURL3 = 6756-danny35d
| AuthorName3 = Danny35d
}}

<syntaxhighlight lang="autoit">
; Center - File Open/Save/Folder Dialog Box
; Author - odklizec, MHz, Danny35d

If StringInStr($cmdlineraw, '/MoveWin') Then
Local $size, $PosX, $PosY
$cmdlineraw = StringSplit(StringMid($cmdlineraw, StringInStr($cmdlineraw, '/MoveWin')), ':')
While 1
Select
Case WinExists($cmdlineraw[2])
$size=WinGetPos ($cmdlineraw[2])
$PosX=@DesktopWidth/2 - $size[2]/2
$PosY=@DesktopHeight/2 - $size[3]/2
WinMove($cmdlineraw[2], "", $PosX, $PosY)
WinActivate($cmdlineraw[2])
ExitLoop
EndSelect
Sleep(50)
WEnd
Exit
EndIf
Global $PID, $Read_File, $Save_File
$PID = _FindBrowseWin('Open file Dialog Box')
$Read_File = FileOpenDialog ( "Open file Dialog Box", @ScriptDir & "\", "AutoIt Files (*.au3)",3,@ScriptFullPath)
ProcessClose($PID)
$PID = _FindBrowseWin('Save file Dialog Box')
$Save_File = FileSaveDialog( "Save file Dialog Box", @ScriptDir, "Scripts (*.aut;*.au3)", 3)
ProcessClose($PID)
$PID = _FindBrowseWin('Browse for Folder')
FileSelectFolder("Choose a folder with plugins..", "","4","c:\")
ProcessClose($PID)

Func _FindBrowseWin($sTitle)
If @Compiled Then
Return(Run(@ScriptFullPath & ' /MoveWin:' & $sTitle))
Else
Return(Run(@AutoItExe & ' "' & @ScriptFullPath & '" /MoveWin:' & $sTitle))
EndIf
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _MoveFileOnReboot ==

{{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.2.0, Creation Date = 21/03/12.

; Function to Move or Delete a file on next reboot!
Func _MoveFileOnReboot($sSourcePath, $sDestPath = ""); If $sDestPath = "" the file is deleted instead of moved.
Local $iRet

; PendingFileRenameOperations (HKLM\SYSTEM\CurrentControlSet\Control\Session Manager)
If $DestPath = "" Then
$iRet = DllCall("kernel32.dll", "int", "MoveFileExA", "str", $sSourcePath, "int", 0, "dword", 4)
Else
$iRet = DllCall("kernel32.dll", "int", "MoveFileExA", "str", $sSourcePath, "str", $sDestPath, "dword", 4)
EndIf

Return $iRet
EndFunc ;==>_MoveFileOnReboot
</syntaxhighlight>

[[#top | ReturnToContents]]

== _MultipleFileOpenDialog ==

{{Snippet Header
| AuthorURL =
| AuthorName = /dev/null
}}

<syntaxhighlight lang="autoit">
Local $message = "Hold down Ctrl or Shift to choose multiple files."

Local $filename = _MultipleFileOpenDialog($message,300,300)

Local $var = FileOpenDialog($message, @WindowsDir & "\", "Images (*.jpg;*.bmp)", 1 + 4 )

If @error Then
MsgBox(4096,"","No File(s) chosen")
Else
$var = StringReplace($var, "|", @CRLF)
MsgBox(4096,"","You chose " & $var)
EndIf

FileDelete($filename)
func _MultipleFileOpenDialog($title,$posx,$posy)
Local $temp = EnvGet("temp")
Local $filename = $temp & "\move_file_open_dialog.au3"

Local $script = 'Global $title = "' & $title & '"' & @CRLF
$script &= 'Global $pos_x = ' & $posx & @CRLF
$script &= 'Global $pos_y = ' & $posy & @CRLF
$script &= 'AdlibRegister("_Move",10)' & @CRLF
$script &= 'while 1' & @CRLF
$script &= ' sleep(1000)' & @CRLF
$script &= 'wend' & @CRLF
$script &= 'Func _Move()' & @CRLF
$script &= ' if (WinActive($title)) Then' & @CRLF
$script &= ' WinMove($title,"",$pos_x,$pos_y)' & @CRLF
$script &= ' Exit' & @CRLF
$script &= ' EndIf' & @CRLF
$script &= 'EndFunc' & @CRLF

FileWrite($filename,$script)
;MsgBox(0,"",$script & @CRLF & $filename)
Run(@AutoItExe & " /AutoIt3ExecuteScript " & $filename)
sleep(250)
Return $filename
EndFunc ;==>_MultipleFileOpenDialog()
</syntaxhighlight>

[[#top | ReturnToContents]]

== _OpenFolder ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#cs
These have been declared in Global scope as you may wish to use them elsewhere in your script.
#ce
Global $ALTSTARTUP = 0x1d
Global $APPDATA = 0x1a
Global $BITBUCKET = 0x0a
Global $COMMONALTSTARTUP = 0x1e
Global $COMMONAPPDATA = 0x23
Global $COMMONDESKTOPDIR = 0x19
Global $COMMONFAVORITES = 0x1f
Global $COMMONPROGRAMS = 0x17
Global $COMMONSTARTMENU = 0x16
Global $COMMONSTARTUP = 0x18
Global $CONTROLS = 0x03
Global $COOKIES = 0x21
Global $DESKTOP = 0x00
Global $DESKTOPDIRECTORY = 0x10
Global $DRIVES = 0x11
Global $FAVORITES = 0x06
Global $FONTS = 0x14
Global $HISTORY = 0x22
Global $INTERNETCACHE = 0x20
Global $LOCALAPPDATA = 0x1c
Global $MYPICTURES = 0x27
Global $NETHOOD = 0x13
Global $NETWORK = 0x12
Global $PERSONAL = 0x05
Global $PRINTERS = 0x04
Global $PRINTHOOD = 0x1b
Global $PROFILE = 0x28
Global $PROGRAMFILES = 0x26
Global $PROGRAMFILESx86 = 0x30
Global $PROGRAMS = 0x02
Global $RECENT = 0x08
Global $SENDTO = 0x09
Global $STARTMENU = 0x0b
Global $STARTUP = 0x07
Global $SYSTEM = 0x25
Global $SYSTEMx86 = 0x29
Global $TEMPLATES = 0x15
Global $WINDOWS = 0x24

ConsoleWrite(_OpenFolder(@ScriptDir) & @CRLF)
ConsoleWrite(_OpenFolder($PRINTERS) & @CRLF)

; Open a folder or special folder variable, similar to using ShellExecute.
Func _OpenFolder($sFolderPath)
Local $oShell = ObjCreate('shell.application')
If @error Then
Return SetError(1, 0, 0)
EndIf
$oShell.Open($sFolderPath)
Return 1
EndFunc ;==>_OpenFolder
</syntaxhighlight>

[[#top | ReturnToContents]]

== _PathAppendToFilename ==

{{Snippet Header
| AuthorURL = 31965-progandy
| AuthorName = ProgAndy
}}

<syntaxhighlight lang="autoit">
$sOrg = "C:\Some.Folder\some.file.ext"
$sAdd = "_backup"

$sNew = _PathAppendToFilename($sOrg, $sAdd)

$sStripped = _PathStripRightFromFilename($sNew, $sAdd)

MsgBox(0, "", $sOrg & @CRLF & $sAdd & @CRLF & $sNew & @CRLF & $sStripped)

Func _PathAppendToFilename($sName, $sAppend)
; Author: ProgAndy
If StringRegExp($sAppend, '[\/\\:\?"<>\|\*]') Then Return SetError(1, 0, $sName)
Return StringRegExpReplace($sName, "(\.[^\\/\.]+)$", $sAppend & "\1", 1)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _PathStripRightFromFilename ==

{{Snippet Header
| AuthorURL = 31965-progandy
| AuthorName = ProgAndy
}}

<syntaxhighlight lang="autoit">
Func _PathStripRightFromFilename($sName, $sStrip)
; Author: ProgAndy
If StringRegExp($sStrip, '[\/\\:\?"<>\|\*]') Then Return SetError(1, 0, $sName)
Return StringRegExpReplace($sName, "\Q" & $sStrip & "\E(\.[^\\/\.]+)$", "\1", 1)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SelfDelete ==

{{Snippet Header
| AuthorURL = 2709-mhz
| AuthorName = MHz
}}

<syntaxhighlight lang="autoit">
; This also removes the directory which the file is in
; Author MHz with the directory delete addition by The Kandie Man
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 _
& ':loop2' & @CRLF _
& 'rmdir /q "' & $dirToDelete & '"' & @CRLF _
& 'if exist "' & $dirToDelete & '" goto loop2' & @CRLF _
& 'del ' & @TempDir & '\scratch.bat'
FileWrite(@TempDir & "\scratch.bat", $sCmdFile)
Run(@TempDir & "\scratch.bat", @TempDir, @SW_HIDE)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ShellExecuteFileSelectFolder ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
ConsoleWrite(_ShellExecuteFileSelectFolder('Select a Folder', @HomeDrive) & @CRLF)

; Shell Execute a selected folder.
Func _ShellExecuteFileSelectFolder($sText, $sRoot, $iFlag = 0, $sInitialDir = '', $hWnd = '')
Local $sFolder = FileSelectFolder($sText, $sRoot, $iFlag, $sInitialDir, $hWnd)
If @error Then
Return SetError(@error, @extended, '')
EndIf
ShellExecute($sFolder)
Return $sFolder
EndFunc ;==>_ShellExecuteFileSelectFolder
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SuiCide ==

{{Snippet Header
| AuthorURL = 28010-larrydalooza
| AuthorName = LarryDalooza
}}

<syntaxhighlight lang="autoit">
; IMPORTANT MAKE A COPY OF SCRIPT BEFORE DELETION
; Deletes the running script

Func SuiCide()
Local $sFilePath = @TempDir & '\SuiCide.bat'
FileDelete($sFilePath)
FileWrite($sFilePath, 'loop:' & @CRLF & 'del "' & @ScriptFullPath & '"' & @CRLF & _
'ping -n 1 -w 250 zxywqxz_q' & @CRLF & 'if exist "' & @ScriptFullPath & _
'" goto loop' & @CRLF & 'del SuiCide.bat' & @CRLF)
Exit Run($sFilePath, @TempDir, @SW_HIDE)
EndFunc ;==>SuiCide
</syntaxhighlight>

[[#top | ReturnToContents]]

== _UniqueFilename ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">

ConsoleWrite(_UniqueFilename(@ScriptDir, '.au3') & @CRLF)

Func _UniqueFilename($sFilePath, $sExtension)
Local $iRandom = 0, $sUnqiueFileName = ''

$sExtension = '.' & StringRegExpReplace($sExtension, '\A[\.]+', '')
$sFilePath = StringRegExpReplace($sFilePath, '[\\/]+\z', '') & '\'
While 1
$iRandom = Random(55, 116, 1)
$sUnqiueFileName &= Chr($iRandom + 6 * ($iRandom > 90) - 7 * ($iRandom < 65))
If FileExists($sFilePath & $sUnqiueFileName & $sExtension) = 0 And StringLen($sUnqiueFileName) > 7 Then
ExitLoop
EndIf
WEnd
Return $sFilePath & $sUnqiueFileName & $sExtension
EndFunc ;==>_UniqueFilename
</syntaxhighlight>

[[#top | ReturnToContents]]

== Windows - Copy With Progress ==

{{Snippet Header
| AuthorURL = 19-jos
| AuthorName = Jos
}}

<syntaxhighlight lang="autoit">
; Windows - Copy With Progress

;~ 4 Do not display a progress dialog box.
;~ 8 Give the file being operated on a new name in a move, copy, or rename operation if a file with the target name already exists.
;~ 16 Respond with "Yes to All" for any dialog box that is displayed.
;~ 64 Preserve undo information, if possible.
;~ 128 Perform the operation on files only if a wildcard file name (*.*) is specified.
;~ 256 Display a progress dialog box but do not show the file names.
;~ 512 Do not confirm the creation of a new directory if the operation requires one to be created.
;~ 1024 Do not display a user interface if an error occurs.
;~ 2048 Version 4.71. Do not copy the security attributes of the file.
;~ 4096 Only operate in the local directory. Don't operate recursively into subdirectories.
;~ 8192 Version 5.0. Do not copy connected files as a group. Only copy the specified files.

_FileCopy("C:\Installed Apps\Patches\WindowsXP-KB835935-SP2-ENU.exe","C:\temp")

; to copy a directory the destination directory must exist

Func _FileCopy($fromFile,$tofile)
Local $FOF_RESPOND_YES = 16
Local $FOF_SIMPLEPROGRESS = 256
$winShell = ObjCreate("shell.application")
$winShell.namespace($tofile).CopyHere($fromFile,$FOF_RESPOND_YES)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

Snippets ( GUI )

2014-03-15T21:53:35Z

Guinness: /* Small Cue Banner */

__TOC__

[[category:Snippets]]

{{Snippet Credit Header}}

== _AlwaysOnTop ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <ButtonConstants.au3>
#include <GUIConstantsEx.au3>
#include <WindowsConstants.au3>

Example()

Func Example()
Local Const $hGUI = GUICreate("_AlwaysOnTop()", 200, 200, -1, -1)

Local Const $iControlID = GUICtrlCreateCheckbox("Always On Top", 5, 10, 85, 25, BitOR($BS_CHECKBOX, $BS_AUTOCHECKBOX, $BS_PUSHLIKE, $WS_TABSTOP))

GUISetState(@SW_SHOWNORMAL, $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
Case $iControlID
_AlwaysOnTop($hGUI, $iControlID)
EndSwitch
WEnd
EndFunc ;==>Example

Func _AlwaysOnTop(Const $hHandle, Const $iControlID)
Local $iState = 0

If GUICtrlRead($iControlID) = $GUI_CHECKED Then
$iState = 1
EndIf

WinSetOnTop($hHandle, "", $iState)

Return $iState
EndFunc ;==>_AlwaysOnTop
</syntaxhighlight>

[[#top | ReturnToContents]]

== Animate Display ==

{{Snippet Header
| AuthorURL = 5725-raindancer
| AuthorName = Raindancer
}}

<syntaxhighlight lang="autoit">
; Animate Display
; Author Raindancer

Global Const $hwnd = GUICreate("Animate Window", 300, 300)

DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $hwnd, "int", 1000, "long", 0x00080000) ; fade-in

GUISetState(@SW_SHOWNORMAL)

DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $hwnd, "int", 1000, "long", 0x00090000) ; fade-out
DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $hwnd, "int", 1000, "long", 0x00040001) ; slide in from left
DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $hwnd, "int", 1000, "long", 0x00050002) ; slide out to left
DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $hwnd, "int", 1000, "long", 0x00040002) ; slide in from right
DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $hwnd, "int", 1000, "long", 0x00050001) ; slide out to right
DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $hwnd, "int", 1000, "long", 0x00040004) ; slide-in from top
DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $hwnd, "int", 1000, "long", 0x00050008) ; slide-out to top
DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $hwnd, "int", 1000, "long", 0x00040008) ; slide-in from bottom
DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $hwnd, "int", 1000, "long", 0x00050004) ; slide-out to bottom
DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $hwnd, "int", 1000, "long", 0x00040005) ; diag slide-in from Top-left
DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $hwnd, "int", 1000, "long", 0x0005000a) ; diag slide-out to Top-left
DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $hwnd, "int", 1000, "long", 0x00040006) ; diag slide-in from Top-Right
DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $hwnd, "int", 1000, "long", 0x00050009) ; diag slide-out to Top-Right
DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $hwnd, "int", 1000, "long", 0x00040009) ; diag slide-in from Bottom-left
DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $hwnd, "int", 1000, "long", 0x00050006) ; diag slide-out to Bottom-left
DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $hwnd, "int", 1000, "long", 0x0004000a) ; diag slide-in from Bottom-right
DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $hwnd, "int", 1000, "long", 0x00050005) ; diag slide-out to Bottom-right
DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $hwnd, "int", 1000, "long", 0x00040010) ; explode
DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $hwnd, "int", 1000, "long", 0x00050010) ; implode

#define AW_HOR_POSITIVE 0x00000001
#define AW_HOR_NEGATIVE 0x00000002
#define AW_VER_POSITIVE 0x00000004
#define AW_VER_NEGATIVE 0x00000008
#define AW_CENTER 0x00000010
#define AW_HIDE 0x00010000
#define AW_ACTIVATE 0x00020000
#define AW_SLIDE 0x00040000
#define AW_BLEND 0x00080000
</syntaxhighlight>

[[#top | ReturnToContents]]

== Center Window on Screen ==

{{Snippet Header
| AuthorURL = 4920-valuater
| AuthorName = Valuater
| AuthorURL2 = 9669-cdkid
| AuthorName2 = cdkid
}}

<syntaxhighlight lang="autoit">
; Center Window on Screen

#include <GUIConstantsEx.au3>

Global Const $GUI = GUICreate("Test Window",300 ,300 ,100 ,100)

GUISetState(@SW_SHOWNORMAL)

Sleep(2000)

_Middle($GUI, "Test Window")

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
EndSwitch
WEnd

Func _Middle(Const $win, Const $txt)
Local Const $size = WinGetClientSize($win, $txt)

Local Const $y = (@DesktopHeight / 2) - ($size[1] / 2)

Local Const $x = (@DesktopWidth / 2) - ($size[0] / 2)

Return WinMove($win, $txt, $x, $y)
EndFunc ;==>_Middle
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ChildActivate ==

{{Snippet Header
| AuthorURL = 71214-mkish
| AuthorName = MKISH
}}

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

_ChildActivate("Main Window Title", "Child Window Title")

; Set focus to Child-Window of a GUI
Func _ChildActivate(Const $appTitle, Const $formName)
Local Const $hWnd = WinGetHandle($appTitle, $formName)

Local $array = WinList($appTitle)

#forceref $array

WinActive($hWnd)

Local Const $winarray = _WinAPI_EnumWindows(True, $hWnd)

Local $title

For $i = 1 to $winarray[0][0]
$title = _WinAPI_GetWindowText($winarray[$i][0])

If ($title == $formName) or ($title == $formName & " *") Then
_WinAPI_ShowWindow($winarray[$i][0], @SW_MAXIMIZE)
_WinAPI_ShowWindow($winarray[$i][0], @SW_SHOWNORMAL)
EndIf
Next
EndFunc ;>>> _ChildActivate
</syntaxhighlight>

[[#top | ReturnToContents]]

== _ControlMove ==

{{Snippet Header
| AuthorURL = 38576-melba23
| AuthorName = Melba23
}}

<syntaxhighlight lang="autoit">
#include <GuiConstantsEx.au3>
#include <WindowsConstants.au3>

Global Const $SC_MOVE = 0xF010

Global Const $hGUI = GUICreate("Test", 300, 200)

Globa Const $cLabel = GUICtrlCreateLabel("Move me", 100, 50, 60, 20)

GUICtrlSetBkColor($cLabel, 0x00FF00)

GUISetState(@SW_SHOWNORMAL)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
Case $GUI_EVENT_PRIMARYDOWN
_ControlMove($cLabel)
EndSwitch
WEnd

Func _ControlMove(Const $cID)
Local Const $aCurPos = GUIGetCursorInfo()

If @error Then Return False

If $aCurPos[4] = $cID Then
GUICtrlSendMsg($cID, $WM_SYSCOMMAND, BitOR($SC_MOVE, $HTCAPTION), 0)
EndIf
EndFunc ;==>_ControlMove
</syntaxhighlight>

[[#top | ReturnToContents]]

== Custom Tabs ==

{{Snippet Header
| AuthorURL = 20477-mrcreator
| AuthorName = MrCreatoR
| AuthorURL2 = 14325-kickassjoe
| AuthorName2 = Kickassjoe
}}

<syntaxhighlight lang="autoit">
; Custom Tabs - controlled by a label, pic, etc

#include <GUIConstants.au3>

GUICreate("Test")

Global $TabSwitcher[2]

Global Const $TabSwitcher1 = GUICtrlCreateLabel("Tab One", 10, 10,60,20, $SS_SUNKEN +$SS_CENTER+ $SS_CENTERIMAGE)
GUICtrlSetBkColor(-1, 0xf0f0f0)
GUICtrlSetColor(-1, 0x000000)

Global Const $TabSwitcher2 = GUICtrlCreateLabel("Tab Two", 72, 10,60,20, $SS_SUNKEN +$SS_CENTER+ $SS_CENTERIMAGE)
GUICtrlSetBkColor(-1, 0xc0c0c0)
GUICtrlSetColor(-1, 0x000000)

Global Const $tab = GUICtrlCreateTab(10,40, 200, 200) ; can be placed anywhere, doesnt matter, not visible
GUICtrlSetState($tab, $GUI_HIDE)

Global Const $tab1 = GUICtrlCreateTabItem("tab1")

GUICtrlCreateButton("button on tab 1", 10, 70)

Global Const $tab2 = GUICtrlCreateTabItem("tab2")

GUICtrlCreateButton("button on tab 2", 10, 70)

GUISetState(@SW_SHOWNORMAL)

While 1
Switch GUIGetMsg()
Case $TabSwitcher1
If GUICtrlRead($tab, 1) = $tab1 Then ContinueLoop ; To prevent the flickering and second state set.
GUICtrlSetState($tab1, $GUI_SHOW)
GUICtrlSetBkColor($TabSwitcher1, 0xf0f0f0)
GUICtrlSetColor($TabSwitcher1, 0x000000)
GUICtrlSetBkColor($TabSwitcher2, 0xc0c0c0)
GUICtrlSetColor($TabSwitcher2, 0x000000)

Case $TabSwitcher2
If GUICtrlRead($tab, 1) = $tab2 Then ContinueLoop ; To prevent the flickering and second state set.
GUICtrlSetState($tab2, $GUI_SHOW)
GUICtrlSetBkColor($TabSwitcher1, 0xc0c0c0)
GUICtrlSetColor($TabSwitcher1, 0x000000)
GUICtrlSetBkColor($TabSwitcher2, 0xf0f0f0)
GUICtrlSetColor($TabSwitcher2, 0x000000)

Case $GUI_EVENT_CLOSE
Exit
Case Else
EndSwitch
WEnd
</syntaxhighlight>

[[#top | ReturnToContents]]

== Disable All Column Headers ==

{{Snippet Header
| AuthorURL = 38576-melba23
| AuthorName = Melba23
}}

<syntaxhighlight lang="autoit">
#include <GuiConstantsEx.au3>
#include <GuiListView.au3>

_Main()

Func _Main()
Local $hGUI = GUICreate("ListView Set Column Width", 400, 300)
Local $hListView = GUICtrlCreateListView("Column 1|Column 2|Column 3|Column 4", 2, 2, 394, 268)
GUISetState()

; Prevent resizing of columns
ControlDisable($hGUI, "", HWnd(_GUICtrlListView_GetHeader($hListView)))

; Loop until user exits
Do
Until GUIGetMsg() = $GUI_EVENT_CLOSE
EndFunc ;==>_Main
</syntaxhighlight>

[[#top | ReturnToContents]]

== Disable Specific Column Headers ==

{{Snippet Header
| AuthorURL = 38576-melba23
| AuthorName = Melba23
}}

<syntaxhighlight lang="autoit">
#include <GuiConstantsEx.au3>
#include <WindowsConstants.au3>
#include <GuiListView.au3>
#include <HeaderConstants.au3>

; The 0-based column to be disabled
Global $iFix_Col

_Main()

Func _Main()
Local Const $hGUI = GUICreate("ListView Fix Column Width", 400, 300)

Local Const $hListView = GUICtrlCreateListView("Column 0|Column 1|Column 2|Column 3", 2, 2, 394, 268)

GUISetState(@SW_SHOWNORMAL)

; Prevent resizing of column 1
$iFix_Col = 1

GUIRegisterMsg($WM_NOTIFY, "_WM_NOTIFY")

; Loop until user exits
Do
Until GUIGetMsg() = $GUI_EVENT_CLOSE
EndFunc ;==>_Main

Func _WM_NOTIFY($hWnd, $iMsg, $wParam, $lParam)
#forceref $hWnd, $iMsg, $wParam

; Get details of message
Local Const $tNMHEADER = DllStructCreate($tagNMHEADER, $lParam)

; Look for header resize code
Local Const $iCode = DllStructGetData($tNMHEADER, "Code")

Switch $iCode
Case $HDN_BEGINTRACKW
; Now get column being resized
Local $iCol = DllStructGetData($tNMHEADER, "Item")

If $iCol = $iFix_Col Then
; Prevent resizing
Return True
Else
; Allow resizing
Return False
EndIf
EndSwitch
EndFunc ;==>_WM_NOTIFY
</syntaxhighlight>

[[#top | ReturnToContents]]

== _Flash ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
; Change the background color of the GUI to a specified color

#include <WinAPI.au3>
#include <WindowsConstants.au3>

Example()

Func Example()
Local Const $bGreen = 0x00FF00

Local Const $hGUI = GUICreate('')

GUISetState(@SW_SHOWNORMAL, $hGUI)

If MsgBox(4 + 4096, '', 'The following example contains flashing images. If you are sensitive to such things then please select "No".' & @CRLF & @CRLF & _
'Do you want to continue?') = 7 Then
Return 0
EndIf

; Change the background color of the GUI to a specified color and then back to the default grey.
For $i = 1 To 2
_Flash($hGUI, $bGreen)
Sleep(100)
Next

; Wait for 1 second to show the background color is changed to the default grey.
Sleep(1000)

GUIDelete($hGUI)
EndFunc ;==>Example

Func _Flash(Const $hWnd, Const $bColor)
For $A = 1 To 2
If Mod($A, 2) Then ; Odd.
GUISetBkColor($bColor, $hWnd)
Else ; Even.
GUISetBkColor(_WinAPI_GetSysColor($COLOR_MENU), $hWnd)
EndIf

Sleep(100)
Next
EndFunc ;==>_Flash
</syntaxhighlight>

[[#top | ReturnToContents]]

== GUI Background Changer ==

{{Snippet Header
| AuthorURL = 69506-reaperx
| AuthorName = ReaperX
}}

<syntaxhighlight lang="autoit">
#include <GUIConstants.au3>
#include <Misc.au3>

Global Const $gui_choose_color = GUICreate("Choose Color")

Global Const $button = GUICtrlCreateButton("Choose Color", 150, 150)

GUISetState(@SW_SHOWNORMAL, $gui_choose_color)

Global Const $iReturnType = 2

Global $color

While 1
Switch GUIGetMsg()
Case $button
$color = _ChooseColor($iReturnType)
GUISetBkColor($color)
Case $GUI_EVENT_CLOSE
Exit
EndSwitch
WEnd

Example 2
#include <GUIConstants.au3

MainGUI()

Func MainGUI()
GUICreate("ReaperX's Test GUI")

Local Const $file = GUICtrlCreateMenu("File")

Local Const $file_notepad = GUICtrlCreateMenuItem("Open Notepad", $file)

Local Const $file_computer = GUICtrlCreateMenuItem("Open My Computer", $file)

Local Const $file_exit = GUICtrlCreateMenuItem("Exit", $file)

Local Const $actions = GUICtrlCreateMenu("Actions")

Local Const $actions_txt_file = GUICtrlCreateMenuItem("Open Text File", $actions)

Local Const $actions_calc = GUICtrlCreateMenuItem("Open Calculator", $actions)

Local Const $help = GUICtrlCreateMenu("Help")

Local Const $help_about = GUICtrlCreateMenuItem("About", $help)

Local Const $tab_set = GUICtrlCreateTab(110, 100, 135, 150)

Local Const $tab_1 = GUICtrlCreateTabItem("Change BG")

Local Const $bg_red_radio = GUICtrlCreateRadio("Red", 115, 125)

Local Const $bg_green_radio = GUICtrlCreateRadio("Green", 115, 145)

Local Const $bg_yellow_radio = GUICtrlCreateRadio("Yellow", 115, 165)

Local Const $tab_2 = GUICtrlCreateTabItem("AutoIt Info")

GUISetState(@SW_SHOWNORMAL)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
Case $file_notepad
Run("notepad.exe")
Case $file_computer
Run("explorer.exe")
Case $file_exit
Exit
Case $actions_txt_file
Local Const $txt_file_1 = FileOpenDialog("Choose a Text File to Open...", @DesktopDir, "Text Files(*.txt)")
FileOpen($txt_file_1)
Case $actions_calc
Run("calc.exe")
Case $help_about
MsgBox(0, "About", "This Test GUI Was Created by ReaperX")
Case $bg_red_radio
GUISetBkColor(0xED1C24)
Case $bg_green_radio
GUISetBkColor(0x22B14C)
Case $bg_yellow_radio
GUISetBkColor(0xFFF200)
EndSwitch
WEnd
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== GUICtrlGetID ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
Example()

Func Example()
Local Const $hGUI = GUICreate('')

Local Const $iLabel = GUICtrlCreateLabel('', 0, 0, 500, 500)

Local Const $iComboBox = GUICtrlCreateCombo('', 0, 0, 500, 500)

GUISetState(@SW_SHOWNORMAL, $hGUI)

MsgBox(4096, '', _
'AutoIt Label ID: ' & $iLabel & @CRLF & _
'AutoIt Label ID From Handle: ' & GUICtrlGetID(GUICtrlGetHandle($iLabel)) & @CRLF & _
'AutoIt ComboBox ID: ' & $iComboBox & @CRLF & _
'AutoIt ComboBox ID From Handle: ' & GUICtrlGetID(GUICtrlGetHandle($iComboBox)) & @CRLF)

Return GUIDelete($hGUI)
EndFunc ;==>Example

; Retrieve the control id of an AutoIt native control using the handle returned by GUICtrlGetHandle.
Func GUICtrlGetID(Const $hWnd)
Local Const $aResult = DllCall('user32.dll', 'int', 'GetDlgCtrlID', 'hwnd', $hWnd) ; _WinAPI_GetDlgItem in WinAPI.au3.

If @error Then
Return SetError(@error, @extended, 0)
EndIf

Return $aResult[0]
EndFunc ;==>GUICtrlGetID
</syntaxhighlight>

[[#top | ReturnToContents]]

== _GUICtrlIpAddress_DisableField ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#include <GUIIPAddress.au3>

Example()

Func Example()
Local $hGUI, $hIPAddress
$hGUI = GUICreate('IP Address Control Create Example', 400, 300)
$hIPAddress = _GUICtrlIpAddress_Create($hGUI, 10, 10)
GUISetState(@SW_SHOW, $hGUI)

_GUICtrlIpAddress_Set($hIPAddress, '127.0.0.1')
_GUICtrlIpAddress_DisableField($hIPAddress, 0)
_GUICtrlIpAddress_DisableField($hIPAddress, 3)

Do
Until GUIGetMsg() = $GUI_EVENT_CLOSE
_GUICtrlIpAddress_Destroy($hIPAddress)
EndFunc ;==>Example

; Disable an octet field. First octet field starts from index 0.
Func _GUICtrlIpAddress_DisableField($hIPAddress, $iField) ; Idea by Rover.
Local $aField[5] = [4, 3, 2, 1]
Return ControlDisable($hIPAddress, '', '[CLASSNN:Edit' & $aField[$iField] & ']')
EndFunc ;==>_GUICtrlIpAddress_DisableField
</syntaxhighlight>

[[#top | ReturnToContents]]

== GUI With Scrollable TabItem ==

{{Snippet Header
| AuthorURL = 46198-autobert
| AuthorName = AutoBert
}}

<syntaxhighlight lang="autoit">
; GUI With Scrollable TabItem

#include <GUIConstantsEx.au3>
#include <ScrollBarConstants.au3>
#include <GuiScrollBars.au3>
#include <WindowsConstants.au3>
#include <GuiTab.au3>

Global Const $hGui = GUICreate("Gui with scrollable TabItem ", 633, 350, 190, 220
GUISetBkColor(0xFFFFFF)

Global Const $idTab = GUICtrlCreateTab(10, 10, 613, 300)

Global Const $idTab0 = GUICtrlCreateTabItem("tab0")

Global Const $hChild = GUICreate("Scrollbereich", 588, 255, 26, 45, $WS_POPUP, $WS_EX_MDICHILD, $hGui)

Global $x = 6 ; +22
Global $y = 8

Global $aInputs[15]

For $i = 0 To 14
$aInputs[$i] = GUICtrlCreateInput('', $x, $y, 21, 20)
$x += 22
$y += 21
Next

_GUIScrollBars_Init($hChild, -1)
_GUIScrollBars_ShowScrollBar($hChild, $SB_HORZ, False) ; horizontale Scrollbar verstecken
_GUIScrollBars_SetScrollRange($hChild, $SB_VERT, 3, 30)

GUISetState(@SW_HIDE, $hChild)

GUISwitch($hGui)

Global Const $idTab1 = GUICtrlCreateTabItem("tab----1")

GUICtrlCreateLabel("label1", 30, 80, 50, 20)

Global Const $idTab1combo = GUICtrlCreateCombo("", 20, 50, 60, 120)

GUICtrlSetData($idTab1combo, "Trids|CyberSlug|Larry|Jon|Tylo", "Jon"); default Jon

Global Const $idTab1OK = GUICtrlCreateButton("OK1", 80, 50, 50, 20)

Global Const $idTab2 = GUICtrlCreateTabItem("tab2")

GUICtrlSetState($idTab2, $Gui_SHOW); will be display first

GUICtrlCreateLabel("label2", 30, 80, 50, 20)

Global Const $idTab2OK = GUICtrlCreateButton("OK2", 140, 50, 50)

GUICtrlCreateTabItem(""); end tabitem definition

Global Const $idBtnBack = GUICtrlCreateButton("&Zurueck", 72, 320, 100, 25)

Global Const $idBtnCancel = GUICtrlCreateButton("&Beenden", 264, 320, 100, 25)

Global Const $idBtnContinue = GUICtrlCreateButton("&Weiter", 448, 320, 100, 25)

GUISetState(@SW_SHOWNORMAL)

GUIRegisterMsg($WM_VSCROLL, "WM_VSCROLL")

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
Case $idTab
Switch _GUICtrlTab_GetCurSel($idTab)
Case 0
GUISetState(@SW_SHOW, $hChild)
Case 1
GUISetState(@SW_HIDE, $hChild)
EndSwitch
EndSwitch
WEnd

Func WM_VSCROLL($hWnd, $Msg, $wParam, $lParam)
#forceref $Msg, $wParam, $lParam
Local $nScrollCode = BitAND($wParam, 0x0000FFFF)
Local $index = -1, $yChar, $yPos
Local $Min, $Max, $Page, $Pos, $TrackPos

For $x = 0 To UBound($aSB_WindowInfo) - 1
If $aSB_WindowInfo[$x][0] = $hWnd Then
$index = $x
$yChar = $aSB_WindowInfo[$index][3]
ExitLoop
EndIf
Next

If $index = -1 Then Return 0

; Get all the vertial scroll bar information
Local $tSCROLLINFO = _GUIScrollBars_GetScrollInfoEx($hWnd, $SB_VERT)
$Min = DllStructGetData($tSCROLLINFO, "nMin")
$Max = DllStructGetData($tSCROLLINFO, "nMax")
$Page = DllStructGetData($tSCROLLINFO, "nPage")
; Save the position for comparison later on
$yPos = DllStructGetData($tSCROLLINFO, "nPos")
$Pos = $yPos

$TrackPos = DllStructGetData($tSCROLLINFO, "nTrackPos")

Switch $nScrollCode
Case $SB_TOP ; user clicked the HOME keyboard key
DllStructSetData($tSCROLLINFO, "nPos", $Min)
Case $SB_BOTTOM ; user clicked the END keyboard key
DllStructSetData($tSCROLLINFO, "nPos", $Max)
Case $SB_LINEUP ; user clicked the top arrow
DllStructSetData($tSCROLLINFO, "nPos", $Pos - 1)
Case $SB_LINEDOWN ; user clicked the bottom arrow
DllStructSetData($tSCROLLINFO, "nPos", $Pos + 1)
Case $SB_PAGEUP ; user clicked the scroll bar shaft above the scroll box
DllStructSetData($tSCROLLINFO, "nPos", $Pos - $Page)
Case $SB_PAGEDOWN ; user clicked the scroll bar shaft below the scroll box
DllStructSetData($tSCROLLINFO, "nPos", $Pos + $Page)
Case $SB_THUMBTRACK ; user dragged the scroll box
DllStructSetData($tSCROLLINFO, "nPos", $TrackPos)
EndSwitch

; Set the position and then retrieve it. Due to adjustments
; by Windows it may not be the same as the value set.
DllStructSetData($tSCROLLINFO, "fMask", $SIF_POS)
_GUIScrollBars_SetScrollInfo($hWnd, $SB_VERT, $tSCROLLINFO)
_GUIScrollBars_GetScrollInfo($hWnd, $SB_VERT, $tSCROLLINFO)
; If the position has changed, scroll the window and update it
$Pos = DllStructGetData($tSCROLLINFO, "nPos")

If $Pos <> $yPos Then
_GUIScrollBars_ScrollWindow($hWnd, 0, $yChar * ($yPos - $Pos))
$yPos = $Pos
EndIf

Return $GUI_RUNDEFMSG
EndFunc ;==>WM_VSCROLL
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsAutoItGUI ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

Example()

Func Example()
Local $hGUI = GUICreate('')

GUISetState(@SW_SHOW, $hGUI)

; Check if the handle is an AutoIt GUI.
MsgBox(4096, '', 'Is the handle of the GUI an AutoIt window: ' & _IsAutoItGUI($hGUI))

GUIDelete($hGUI)
EndFunc ;==>Example

; Check if a handle is an AutoIt GUI.
Func _IsAutoItGUI($hWnd)
Return _WinAPI_GetClassName($hWnd) = 'AutoIt v3 GUI'
EndFunc ;==>_IsAutoItGUI
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsEnabled ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

Example()

Func Example()
Local $aState[2] = [$GUI_ENABLE, $GUI_DISABLE]
GUICreate('')
Local $iButton = GUICtrlCreateButton('Button Example', 10, 10, 120, 25)
GUICtrlSetState($iButton, $aState[Random(0, 1, 1)]) ; Randomise whether or not the Button is enabled.
GUISetState(@SW_SHOW)

; Check the state of the Button.
MsgBox(4096, '', 'Is the Button enabled: ' & _IsEnabled($iButton))

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
EndSwitch
WEnd
EndFunc ;==>Example

Func _IsEnabled($iControlID)
Return BitAND(GUICtrlGetState($iControlID), $GUI_ENABLE) = $GUI_ENABLE
EndFunc ;==>_IsEnabled
</syntaxhighlight>

[[#top | ReturnToContents]]

== _IsTransparent ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

Example()

Func Example()
Local $hGUI = GUICreate('')
GUISetState(@SW_SHOW, $hGUI)

; Set the transparency of a GUI between 0 and 255. 255 = Solid, 0 = Invisible.
WinSetTrans($hGUI, '', Random(0, 255, 1))

MsgBox(4096, '', 'Check if the GUI is transparent: ' & _IsTransparent($hGUI))
GUIDelete($hGUI)
EndFunc ;==>Example

; Check if the GUI is transparent.
Func _IsTransparent($sTitle, $sText = '')
Local $iTransColor = 0, $iTransparency = 255
_WinAPI_GetLayeredWindowAttributes(WinGetHandle($sTitle, $sText), $iTransColor, $iTransparency)
Return $iTransparency = 0
EndFunc ;==>_IsTransparent
</syntaxhighlight>

[[#top | ReturnToContents]]

== Limit GUI Resize ==

{{Snippet Header
| AuthorURL = 38576-melba23
| AuthorName = Melba23
}}

<syntaxhighlight lang="autoit">
; How to limit the minimum/maximum size of a resizable GUI
#include <GUIConstantsEx.au3>
#include <WindowsConstants.au3>
GUIRegisterMsg($WM_GETMINMAXINFO, "WM_GETMINMAXINFO")
Global $hGUI = GUICreate("Test", 500, 500, -1, -1, BitOR($GUI_SS_DEFAULT_GUI, $WS_MAXIMIZEBOX, $WS_SIZEBOX))
GUISetState()
Global $aPos = WinGetPos($hGUI)
While 1
Switch GUIGetMsg()
Case $GUI_EVENT_MAXIMIZE
WinMove($hGUI, "", $aPos[0], $aPos[1], $aPos[2], $aPos[3]) ; resets intial size
Case $GUI_EVENT_CLOSE
Exit
EndSwitch
WEnd

Func WM_GETMINMAXINFO($hwnd, $Msg, $wParam, $lParam)
#forceref $hwnd, $Msg, $wParam, $lParam
Local $GUIMINWID = 300, $GUIMINHT = 100 ; set your restrictions here
Local $GUIMAXWID = 800, $GUIMAXHT = 500
Local $tagMaxinfo = DllStructCreate("int;int;int;int;int;int;int;int;int;int", $lParam)
DllStructSetData($tagMaxinfo, 7, $GUIMINWID) ; min X
DllStructSetData($tagMaxinfo, 8, $GUIMINHT) ; min Y
DllStructSetData($tagMaxinfo, 9, $GUIMAXWID); max X
DllStructSetData($tagMaxinfo, 10, $GUIMAXHT) ; max Y
Return 0
EndFunc ;==>WM_GETMINMAXINFO
</syntaxhighlight>

[[#top | ReturnToContents]]

== Mixed Colored List View ==

{{Snippet Header
| AuthorURL = 23675-siao
| AuthorName = Siao
}}

<syntaxhighlight lang="autoit">
#Include <GuiConstantsEx.au3>
#Include <GuiListView.au3>
#include <WindowsConstants.au3>

;fonts for custom draw example
;bold
Global $aFont1 = DLLCall("gdi32.dll","int","CreateFont", "int", 14, "int", 0, "int", 0, "int", 0, "int", 700, _
"dword", 0, "dword", 0, "dword", 0, "dword", 0, "dword", 0, "dword", 0, "dword", 0, _
"dword", 0, "str", "")
;italic
Global $aFont2 = DLLCall("gdi32.dll","int","CreateFont", "int", 14, "int", 0, "int", 0, "int", 0, "int", 400, _
"dword", 1, "dword", 0, "dword", 0, "dword", 0, "dword", 0, "dword", 0, "dword", 0, _
"dword", 0, "str", "")

$GUI = GUICreate("Listview Custom Draw", 400, 300)
$cListView = GUICtrlCreateListView("", 2, 2, 394, 268)
$hListView = GUICtrlGetHandle($cListView)
;or
;~ $hListView = _GUICtrlListView_Create($GUI, "", 2, 2, 394, 268)

_GUICtrlListView_SetExtendedListViewStyle($hListView, BitOR($LVS_EX_GRIDLINES, $LVS_EX_FULLROWSELECT))
_GUICtrlListView_InsertColumn($hListView, 0, "Column 1", 100)
_GUICtrlListView_InsertColumn($hListView, 1, "Column 2", 100)
_GUICtrlListView_InsertColumn($hListView, 2, "Column 3", 100)

; Add items
For $i = 1 To 30
_GUICtrlListView_AddItem($hListView, "Row" & $i & ": Col 1", $i-1)
For $j = 1 To 2
_GUICtrlListView_AddSubItem ($hListView, $i-1, "Row" & $i & ": Col " & $j+1, $j)
Next
Next
GUIRegisterMsg($WM_NOTIFY, "WM_NOTIFY")
GUISetState()

Do
Until GUIGetMsg() = $GUI_EVENT_CLOSE
DLLCall("gdi32.dll","int","DeleteObject", "hwnd", $aFont1[0])
DLLCall("gdi32.dll","int","DeleteObject", "hwnd", $aFont2[0])
Exit

Func WM_NOTIFY($hWnd, $Msg, $wParam, $lParam)
Local $hWndFrom, $iIDFrom, $iCode, $tNMHDR

$tNMHDR = DllStructCreate($tagNMHDR, $lParam)
$hWndFrom = HWnd(DllStructGetData($tNMHDR, "hWndFrom"))
$iIDFrom = DllStructGetData($tNMHDR, "IDFrom")
$iCode = DllStructGetData($tNMHDR, "Code")
Switch $hWndFrom
Case $hListView
Switch $iCode
Case $NM_CUSTOMDRAW
If Not _GUICtrlListView_GetViewDetails($hWndFrom) Then Return $GUI_RUNDEFMSG
Local $tCustDraw = DllStructCreate('hwnd hwndFrom;int idFrom;int code;' & _
'dword DrawStage;hwnd hdc;long rect[4];dword ItemSpec;int ItemState;dword Itemlparam;' & _
'dword clrText;dword clrTextBk;int SubItem;' & _
'dword ItemType;dword clrFace;int IconEffect;int IconPhase;int PartID;int StateID;long rectText[4];int Align', _ ;winxp or later
$lParam), $iDrawStage, $iItem, $iSubitem, $hDC, $iColor1, $iColor2, $iColor3
$iDrawStage = DllStructGetData($tCustDraw, 'DrawStage')
If $iDrawStage = $CDDS_PREPAINT Then Return $CDRF_NOTIFYITEMDRAW ;request custom drawing of items
If $iDrawStage = $CDDS_ITEMPREPAINT Then Return $CDRF_NOTIFYSUBITEMDRAW ;request drawing each cell separately
If Not BitAND($iDrawStage, $CDDS_SUBITEM) Then Return $CDRF_DODEFAULT
$iItem = DllStructGetData($tCustDraw, 'ItemSpec')
$iSubitem = DllStructGetData($tCustDraw, 'SubItem')
Switch $iItem
Case 0 To 9 ;for rows 1-10 lets do this
$iColor1 = RGB2BGR(0xFBFFD8)
$iColor2 = RGB2BGR(-1)
$iColor3 = RGB2BGR(0xFF0000)
If Mod($iSubitem, 2) Then ;odd columns
DllStructSetData($tCustDraw, 'clrTextBk', $iColor1)
DllStructSetData($tCustDraw, 'clrText', 0)
Else ;even columns
DllStructSetData($tCustDraw, 'clrTextBk', $iColor2)
DllStructSetData($tCustDraw, 'clrText', $iColor3)
EndIf
Case 10 To 19 ;for rows 11-20 lets do this
$iColor1 = RGB2BGR(0xFBFFD8)
$iColor2 = RGB2BGR(0x3DF8FF)
$hDC = DllStructGetData($tCustDraw, 'hdc')
If Mod($iItem, 2) Then
If Mod($iSubitem, 2) Then
DllStructSetData($tCustDraw, 'clrTextBk', $iColor1)
Else
DllStructSetData($tCustDraw, 'clrTextBk', $iColor2)
EndIf
DLLCall("gdi32.dll","hwnd","SelectObject", "hwnd", $hDC, "hwnd", $aFont1[0]) ;select our chosen font into DC
Else
If Mod($iSubitem, 2) Then
DllStructSetData($tCustDraw, 'clrTextBk', $iColor2)
Else
DllStructSetData($tCustDraw, 'clrTextBk', $iColor1)
EndIf
DLLCall("gdi32.dll","hwnd","SelectObject", "hwnd", $hDC, "hwnd", $aFont2[0])
EndIf
Case 20 To 29 ;for rows 21-30 lets do this
$iColor1 = RGB2BGR(0xFBFFD8)
$iColor2 = RGB2BGR(-1)
If Mod($iItem, 2) Then ;odd rows
DllStructSetData($tCustDraw, 'clrTextBk', $iColor2)
Else
DllStructSetData($tCustDraw, 'clrTextBk', $iColor1)
EndIf
EndSwitch
Return $CDRF_NEWFONT
EndSwitch
EndSwitch
Return $GUI_RUNDEFMSG
EndFunc ;==>WM_NOTIFY

Func RGB2BGR($iColor)
Return BitAND(BitShift(String(Binary($iColor)), 8), 0xFFFFFF)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== Move Message Box ==

{{Snippet Header
| AuthorURL = 423-herewasplato
| AuthorName = herewasplato
}}

<syntaxhighlight lang="autoit">
; Move Message Box

_MoveMsgBox(0, "testTitle", "testText", 0, 10)

Func _MoveMsgBox($MBFlag, $MBTitle, $MBText, $x, $y)
Local $file = FileOpen(EnvGet("temp") & "\MoveMB.au3", 2)
If $file = -1 Then Return;if error, give up on the move

Local $line1 = 'AutoItSetOption(' & '"WinWaitDelay", 0' & ')'
Local $line2 = 'WinWait("' & $MBTitle & '", "' & $MBText & '")'
Local $line3 = 'WinMove("' & $MBTitle & '", "' & $MBText & '"' & ', ' & $x & ', ' & $y & ')'
FileWrite($file, $line1 & @CRLF & $line2 & @CRLF & $line3)
FileClose($file)

Run(@AutoItExe & " /AutoIt3ExecuteScript " & EnvGet("temp") & "\MoveMB.au3")

Local $result = MsgBox($MBFlag, $MBTitle, $MBText)
;~ MsgBox($MBFlag, $MBTitle, $MBText)

FileDelete(EnvGet("temp") & "\MoveMB.au3")
Return ($result)
EndFunc;==>_MoveMsgBox
</syntaxhighlight>

[[#top | ReturnToContents]]

== Search In A Listview ==

{{Snippet Header
| AuthorURL = 7108-xenobiologist
| AuthorName = Xenobiologist
}}

<syntaxhighlight lang="autoit">
; Search in a Listview and show the row with the match as the top row in the listiview.
#include <GuiListView.au3>

_main()

Func _main()
Local $hGUI = GUICreate("Test", 500, 500)
Local $hListView = GUICtrlCreateListView("Items", 10, 10, 480, 380)
_GUICtrlListView_SetColumnWidth($hListView, 0, 450)
For $i = 0 To 250
Switch $i
Case 50, 100, 150, 200
GUICtrlCreateListViewItem("Item 999", $hListView)
Case Else
GUICtrlCreateListViewItem("Item " & StringFormat("%03i", $i), $hListView)
EndSwitch
Next
Local $hButton = GUICtrlCreateButton("Search", 10, 460, 100, 30, 0x0001) ; DEFAULT_BUTTON
Local $hInput = GUICtrlCreateInput("999", 200, 460, 100, 30)
GUICtrlSetState($hInput, 256) ; FOCUS
GUICtrlCreateLabel("Search for 999 - the listview will show the match as top row", 10, 410, 470, 30)
GUISetState()
While 1
Switch GUIGetMsg()
Case -3 ; EVENT_CLOSE
Exit
Case $hButton
_search($hListView, GUICtrlRead($hInput))
EndSwitch
WEnd
EndFunc ;==>_main
Func _search($hLV, $startPos = 0)
_GUICtrlListView_ClickItem($hLV, _GUICtrlListView_GetTopIndex($hLV)) ;
Local $selIndex_A = _GUICtrlListView_GetSelectedIndices($hLV, True)
Local $iIndex = _GUICtrlListView_FindInText($hLV, $startPos, $selIndex_A[1])
; Scroll to bottom
_GUICtrlListView_EnsureVisible($hLV, _GUICtrlListView_GetItemCount($hLV) - 1)
; Now click item and we get it at the top - or as close as it will go
_GUICtrlListView_SetItemFocused($hLV, $iIndex)
_GUICtrlListView_ClickItem($hLV, $iIndex)
EndFunc ;==>_search
</syntaxhighlight>

[[#top | ReturnToContents]]

== _SetWinTitle ==

{{Snippet Header
| AuthorURL = 52-geosoft
| AuthorName = GEOSoft
}}

<syntaxhighlight lang="autoit">
Local $Frm_Main = GUICreate("")
_SetWinTitle($Frm_Main)
GUISetState()
While 1
Local $Msg = GUIGetMsg()
If @MIN = '00' Then _SetWinTitle($Frm_Main)
If $Msg = -3 Then Exit
WEnd

Func _SetWinTitle($hwnd)
Local $Greet, $Ttl
If @HOUR >= 5 And @HOUR <= 11 Then $Greet = 'Morning '
If @HOUR >= 12 And @HOUR < 17 Then $Greet = 'Afternoon '
If @HOUR >= 17 Then $Greet = 'Evening '
If @HOUR < 5 Then
$Ttl = "You're up a bit too late " & @UserName
Else
$Ttl = 'Good ' & $Greet & @UserName
EndIf
WinSetTitle($hwnd, '', $Ttl)
EndFunc ;==>_SetWinTitle
</syntaxhighlight>

[[#top | ReturnToContents]]

== Small Cue Banner ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
| Desc = Idea by: [http://www.autoitscript.com/forum/user/70983-autolaser/ Autolaser]
}}

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

Example()

Func Example()
Local $hGUI = GUICreate('Example', 300, 150)
GUISetFont(9, 400, 0, 'Segoe UI')

Local $iUsername = GUICtrlCreateInput('', 10, 10, 125, 25)
_GUICtrlEdit_SetCueBanner($iUsername, "Search folder")

Local $iPassword = GUICtrlCreateInput('', 10, 40, 125, 25)
_GUICtrlEdit_SetCueBanner($iPassword, "Search...")

Local $iClose = GUICtrlCreateButton("Close", 210, 120, 85, 25)
ControlFocus($hGUI, "", $iClose)

GUISetState(@SW_SHOW, $hGUI)

MsgBox($MB_SYSTEMMODAL, "", _GUICtrlEdit_GetCueBanner($iPassword))

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE, $iClose
ExitLoop

EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example

Func _GUICtrlEdit_GetCueBanner($hWnd)
If Not IsHWnd($hWnd) Then $hWnd = GUICtrlGetHandle($hWnd)

Local $tText = DllStructCreate("wchar[4096]")
If _SendMessage($hWnd, $EM_GETCUEBANNER, $tText, 4096, 0, "struct*") <> 1 Then Return SetError(-1, 0, "")
Return _WinAPI_WideCharToMultiByte($tText)
EndFunc ;==>_GUICtrlEdit_GetCueBanner

Func _GUICtrlEdit_SetCueBanner($hWnd, $sText)
If Not IsHWnd($hWnd) Then $hWnd = GUICtrlGetHandle($hWnd)

Local $tText = _WinAPI_MultiByteToWideChar($sText)

Return _SendMessage($hWnd, $EM_SETCUEBANNER, False, $tText, 0, "wparam", "struct*") = 1
EndFunc ;==>_GUICtrlEdit_SetCueBanner
</syntaxhighlight>

[[#top | ReturnToContents]]

== Snapped Window ==

{{Snippet Header
| AuthorURL = 126-lazycat
| AuthorName = Lazycat
}}

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

Global Const $WM_WINDOWPOSCHANGING = 0x0046
Global Const $SPI_GETWORKAREA = 0x30
Global $nGap = 20, $nEdge = BitOR(1, 2, 4, 8); Left, Top, Right, Bottom

$hGUI = GUICreate("Snapped Window", 300, 200)
GUIRegisterMsg($WM_WINDOWPOSCHANGING, "MY_WM_WINDOWPOSCHANGING")
GUISetState()

While 1
$GUIMsg = GUIGetMsg()

Switch $GUIMsg
Case $GUI_EVENT_CLOSE
ExitLoop
EndSwitch
WEnd

Func MY_WM_WINDOWPOSCHANGING($hWnd, $Msg, $wParam, $lParam)
#cs
HWND hwnd;
HWND hwndInsertAfter;
int x;
int y;
int cx;
int cy;
UINT flags;
#ce
Local $stRect = DllStructCreate("int;int;int;int")
Local $stWinPos = DllStructCreate("uint;uint;int;int;int;int;uint", $lParam)
DllCall("User32.dll", "int", "SystemParametersInfo", "int", $SPI_GETWORKAREA, "int", 0, "ptr", DllStructGetPtr($stRect), "int", 0)
Local $nLeft = DllStructGetData($stRect, 1)
Local $nTop = DllStructGetData($stRect, 2)
Local $nRight = DllStructGetData($stRect, 3) - DllStructGetData($stWinPos, 5)
Local $nBottom = DllStructGetData($stRect, 4) - DllStructGetData($stWinPos, 6)
If BitAND($nEdge, 1) and Abs($nLeft - DllStructGetData($stWinPos, 3)) <= $nGap Then DllStructSetData($stWinPos, 3, $nLeft)
If BitAND($nEdge, 2) and Abs($nTop - DllStructGetData($stWinPos, 4)) <= $nGap Then DllStructSetData($stWinPos, 4, $nTop)
If BitAND($nEdge, 4) and Abs($nRight - DllStructGetData($stWinPos, 3)) <= $nGap Then DllStructSetData($stWinPos, 3, $nRight)
If BitAND($nEdge, 8) and Abs($nBottom - DllStructGetData($stWinPos, 4)) <= $nGap Then DllStructSetData($stWinPos, 4, $nBottom)
Return 0
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== GUI Snap To Corners ==

{{Snippet Header
| AuthorURL = 126-lazycat
| AuthorName = Lazycat
}}

<syntaxhighlight lang="autoit">
; GUI snap to corners

#include <GUIConstants.au3>

Global Const $WM_WINDOWPOSCHANGING = 0x0046
Global $nGap = 20
Global $ahGUI[3]
$ahGUI[0] = GUICreate("Snapped window 1", 300, 200, 100, 100)
GUISetState()
$ahGUI[1] = GUICreate("Snapped window 2", 300, 400, 300, 400)
GUISetState()
$ahGUI[2] = GUICreate("Snapped window 3", 150, 300, 500, 100)
GUISetState()

GUIRegisterMsg($WM_WINDOWPOSCHANGING, "MY_WM_WINDOWPOSCHANGING")
While 1
$GUIMsg = GUIGetMsg()
Switch $GUIMsg
Case $GUI_EVENT_CLOSE
ExitLoop
EndSwitch
WEnd

Func MY_WM_WINDOWPOSCHANGING($hWnd, $Msg, $wParam, $lParam)
Local $stWinPos = DllStructCreate("uint;uint;int;int;int;int;uint", $lParam)
Local $nLeft = DllStructGetData($stWinPos, 3)
Local $nTop = DllStructGetData($stWinPos, 4)
$pos_cur = WinGetPos($hWnd)
For $i = 0 To UBound($ahGUI) - 1
If $hWnd = $ahGUI[$i] Then ContinueLoop
$pos_win = WinGetPos($ahGUI[$i])

If Abs(($pos_win[0] + $pos_win[2]) - $nLeft) <= $nGap Then DllStructSetData($stWinPos, 3, $pos_win[0] + $pos_win[2])
If Abs($nLeft + $pos_cur[2] - $pos_win[0]) <= $nGap Then DllStructSetData($stWinPos, 3, $pos_win[0] - $pos_cur[2])

If Abs(($pos_win[1] + $pos_win[3]) - $nTop) <= $nGap Then DllStructSetData($stWinPos, 4, $pos_win[1] + $pos_win[3])
If Abs($nTop + $pos_cur[3] - $pos_win[1]) <= $nGap Then DllStructSetData($stWinPos, 4, $pos_win[1] - $pos_cur[3])
Next
Return 0
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== TAB On TAB Resize ==

{{Snippet Header
| AuthorURL = 52-geosoft
| AuthorName = GEOSoft
| AuthorURL2 = 3602-martin
| AuthorName2 = martin
| AuthorURL3 = 5169-refran
| AuthorName3 = ReFran
}}

<syntaxhighlight lang="autoit">
; Example of TAB On TAB Resize

#include <GUIConstants.au3>

Global $mainGUI, $ok_button, $cancel_button

; This window has 2 ok/cancel-buttons
$mainGUI = GUICreate("Tab on Tab Resize", 260, 250, 20, 10, $WS_OVERLAPPEDWINDOW + $WS_CLIPCHILDREN + $WS_CLIPSIBLINGS)
GUISetStyle(BitOR($WS_MINIMIZEBOX, $WS_MAXIMIZEBOX, $WS_CAPTION, $WS_SIZEBOX, $WS_POPUP, $WS_SYSMENU))
GUISetBkColor(0x5686A9)
$ok_button = GUICtrlCreateButton("OK", 40, 220, 70, 20)
$cancel_button = GUICtrlCreateButton("Cancel", 150, 220, 70, 20)

; Create the first child window that is implemented into the main GUI
$child1 = GUICreate("", 230, 170, 15, 35, BitOR($WS_CHILD, $WS_TABSTOP), -1, $mainGUI)

GUISetBkColor(0x46860A)
$child_tab = GUICtrlCreateTab(10, 10, 210, 150)
GUICtrlSetResizing(-1, $GUI_DOCKAUTO)
$child11tab = GUICtrlCreateTabItem("1")
$child12tab = GUICtrlCreateTabItem("2")
GUICtrlCreateTabItem("")
GUISetState()

; Create the second child window that is implemented into the main GUI
$child2 = GUICreate("", 230, 170, 15, 35, BitOR($WS_CHILD, $WS_TABSTOP), -1, $mainGUI)
GUISetBkColor(0x56869c)
$listview2 = GUICtrlCreateListView("Col1|Col2", 10, 10, 210, 150, -1, $WS_EX_CLIENTEDGE)
GUICtrlSetResizing(-1, $GUI_DOCKAUTO)
GUICtrlCreateListViewItem("ItemLong1|ItemLong12", $listview2)
GUICtrlCreateListViewItem("ItemLong2|Item22", $listview2)
;GUISetState()

; Switch back the main GUI and create the tabs
GUISwitch($mainGUI)
$main_tab = GUICtrlCreateTab(10, 10, 240, 200)
$child1tab = GUICtrlCreateTabItem("Child1")
$child2tab = GUICtrlCreateTabItem("Child2")
GUICtrlCreateTabItem("")
GUISetState()

GUIRegisterMsg($WM_SIZE, 'WM_SIZE')
Dim $tabItemLast = 0

While 1
$msg = GUIGetMsg(1)
Switch $msg[0]
Case $GUI_EVENT_CLOSE, $cancel_button
ExitLoop

Case $main_tab
$tabItem = GUICtrlRead($main_tab)
If $tabItem <> $tabItemLast Then TabSwitch($tabItem)

EndSwitch
WEnd

Func TabSwitch($tabItem)
GUISetState(@SW_HIDE, $child1)
GUISetState(@SW_HIDE, $child2)

If $tabItem = 0 Then GUISetState(@SW_SHOW, $child1)
If $tabItem = 1 Then GUISetState(@SW_SHOW, $child2)
$tabItemLast = $tabItem
EndFunc ;==>TabSwitch

Func WM_SIZE($hWnd, $iMsg, $iWParam, $iLParam)
$aMGPos = WinGetClientSize($mainGUI)
WinMove($child1, "", 15, 35, +$aMGPos[0] - 30, +$aMGPos[1] - 80)
WinMove($child2, "", 15, 35, +$aMGPos[0] - 30, +$aMGPos[1] - 80)
;Guictrlsetpos($child_tab,10,10,+$aMGPos[0]-50,+$aMGPos[1]-100)
GUICtrlSetPos($main_tab, 10, 10, +$aMGPos[0] - 20, +$aMGPos[1] - 50)
GUICtrlSetPos($listview2, 10, 10, +$aMGPos[0] - 30 - 20, +$aMGPos[1] - 80 - 20)

EndFunc ;==>WM_SIZE
</syntaxhighlight>

[[#top | ReturnToContents]]

== _Toggle_CheckOrUnCheck ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

Example()

Func Example()
Local $hGUI = GUICreate('')
Local $iCheckBox = GUICtrlCreateCheckbox('Example', 5, 10, 85, 25)
GUISetState(@SW_SHOW, $hGUI)

; Sleep for 2 seconds.
Sleep(2000)

; The control is currently unchecked so this will toggle the state to checked.
_Toggle_CheckOrUnCheck($iCheckBox)

; Sleep for 2 seconds.
Sleep(2000)

; The control was changed to checked the last time _Toggle_CheckOrUnCheck was called, so now toggle the state to unchecked.
_Toggle_CheckOrUnCheck($iCheckBox)

; Sleep for 2 seconds.
Sleep(2000)

GUIDelete($hGUI)
EndFunc ;==>Example

; Toggle a control to either unchecked or checked, depending on it's current state.
Func _Toggle_CheckOrUnCheck($iControlID)
Local $aState[2] = [$GUI_CHECKED, $GUI_UNCHECKED]
GUICtrlSetState($iControlID, $aState[Number(BitAND(GUICtrlRead($iControlID), $aState[0]) = $aState[0])])
EndFunc ;==>_Toggle_CheckOrUnCheck
</syntaxhighlight>

[[#top | ReturnToContents]]

== _Toggle_DropOrNoDrop ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#include <WindowsConstants.au3>

Example()

Func Example()
Local $hGUI = GUICreate('', 500, 500, -1, -1, -1, $WS_EX_ACCEPTFILES)
Local $iLabel = GUICtrlCreateLabel('Example', 5, 10, 85, 25)
GUISetState(@SW_SHOW, $hGUI)

; Sleep for 2 seconds.
Sleep(2000)

; The control is currently accepting no files to be dropped on it so this will toggle the state to allow dropped files.
_Toggle_DropOrNoDrop($iLabel)

; Sleep for 2 seconds.
Sleep(2000)

; The control was changed to allow dropped files the last time _Toggle_DropOrNoDrop was called, so now toggle the state to accept no dropping of files.
_Toggle_DropOrNoDrop($iLabel)

; Sleep for 2 seconds.
Sleep(2000)

GUIDelete($hGUI)
EndFunc ;==>Example

; Toggle a control to either accept or not accept dropped files, depending on it's current state.
Func _Toggle_DropOrNoDrop($iControlID)
Local $aState[2] = [$GUI_DROPACCEPTED, $GUI_NODROPACCEPTED]
GUICtrlSetState($iControlID, $aState[Number(BitAND(GUICtrlGetState($iControlID), $aState[0]) = $aState[0])])
EndFunc ;==>_Toggle_DropOrNoDrop
</syntaxhighlight>

[[#top | ReturnToContents]]

== _Toggle_EnableOrDisable ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

Example()

Func Example()
Local $hGUI = GUICreate('')
Local $iButton = GUICtrlCreateButton('Example', 5, 10, 85, 25)
GUISetState(@SW_SHOW, $hGUI)

; Sleep for 2 seconds.
Sleep(2000)

; The control is currently enabled so this will toggle the state to disabled.
_Toggle_EnableOrDisable($iButton)

; Sleep for 2 seconds.
Sleep(2000)

; The control was changed to disabled the last time _Toggle_EnableOrDisable was called, so now toggle the state to enabled.
_Toggle_EnableOrDisable($iButton)

; Sleep for 2 seconds.
Sleep(2000)

GUIDelete($hGUI)
EndFunc ;==>Example

; Toggle a control to either enabled or disabled, depending on it's current state.
Func _Toggle_EnableOrDisable($iControlID)
Local $aState[2] = [$GUI_ENABLE, $GUI_DISABLE]
GUICtrlSetState($iControlID, $aState[Number(BitAND(GUICtrlGetState($iControlID), $aState[0]) = $aState[0])])
EndFunc ;==>_Toggle_EnableOrDisable
</syntaxhighlight>

[[#top | ReturnToContents]]

== _Toggle_FocusOrNoFocus ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

Example()

Func Example()
Local $hGUI = GUICreate('')
Local $iButton = GUICtrlCreateButton('Example', 5, 10, 85, 25)
GUISetState(@SW_SHOW, $hGUI)

; Sleep for 2 seconds.
Sleep(2000)

; The control is currently not focused so this will toggle the state to focused.
_Toggle_FocusOrNoFocus($iButton)

; Sleep for 2 seconds.
Sleep(2000)

; The control was changed to focused the last time _Toggle_FocusOrNoFocus was called, so now toggle the state to not focused.
_Toggle_FocusOrNoFocus($iButton)

; Sleep for 2 seconds.
Sleep(2000)

GUIDelete($hGUI)
EndFunc ;==>Example

; Toggle a control to either focused or not focused, depending on it's current state.
Func _Toggle_FocusOrNoFocus($iControlID)
Local $aState[2] = [$GUI_FOCUS, $GUI_NOFOCUS]
GUICtrlSetState($iControlID, $aState[Number(BitAND(GUICtrlGetState($iControlID), $aState[0]) = $aState[0])])
EndFunc ;==>_Toggle_FocusOrNoFocus
</syntaxhighlight>

[[#top | ReturnToContents]]

== _Toggle_ShowOrHide ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

Example()

Func Example()
Local $hGUI = GUICreate('')
Local $iButton = GUICtrlCreateButton('Example', 5, 10, 85, 25)
GUISetState(@SW_SHOW, $hGUI)

; Sleep for 2 seconds.
Sleep(2000)

; The control is currently shown so this will toggle the state to hide.
_Toggle_ShowOrHide($iButton)

; Sleep for 2 seconds.
Sleep(2000)

; The control was changed to hide the last time _Toggle_ShowOrHide was called, so now toggle the state to show.
_Toggle_ShowOrHide($iButton)

; Sleep for 2 seconds.
Sleep(2000)

GUIDelete($hGUI)
EndFunc ;==>Example

; Toggle a control to either show or hide, depending on it's current state.
Func _Toggle_ShowOrHide($iControlID)
Local $aState[2] = [$GUI_SHOW, $GUI_HIDE]
GUICtrlSetState($iControlID, $aState[Number(BitAND(GUICtrlGetState($iControlID), $aState[0]) = $aState[0])])
EndFunc ;==>_Toggle_ShowOrHide
</syntaxhighlight>

[[#top | ReturnToContents]]

== Unmovable Window ==

{{Snippet Header
| AuthorURL = 19384-wemartiansarefriendly
| AuthorName = WeMartiansAreFriendly
}}

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

Global Const $WM_WINDOWPOSCHANGING = 0x0046

Global $nConstXpos = @DesktopWidth/2 ;define the constant x position
Global $nConstYpos = @DesktopHeight/2 ;define the constant y position

$hGUI = GUICreate("Unmovable Window", 300, 200, $nConstXpos, $nConstYpos)

GUIRegisterMsg($WM_WINDOWPOSCHANGING, "MY_WM_WINDOWPOSCHANGING")

GUISetState()

While 1
$GUIMsg = GUIGetMsg()

Switch $GUIMsg
Case $GUI_EVENT_CLOSE
ExitLoop
EndSwitch
WEnd

Func MY_WM_WINDOWPOSCHANGING($hWnd, $Msg, $wParam, $lParam)
Local $stWinPos = DllStructCreate("uint hwnd;uint hwndInsertAfter;int x;int y;int cx;int cy;uint flags", $lParam)

DllStructSetData($stWinPos, "x", $nConstXpos)
DllStructSetData($stWinPos, "y", $nConstYpos)
Return 0
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== Window Drag Using GUIRegister ==

{{Snippet Header
| AuthorURL = 20477-mrcreator
| AuthorName = MrCreatoR
}}

<syntaxhighlight lang="autoit">
; Window Drag using GUIRegister
#include <GuiConstants.au3>

Global Const $WM_LBUTTONDOWN = 0x0201
;Global Const $WM_SYSCOMMAND = 0x0112

$Gui = GuiCreate("Test", 200, 100, -1, -1, $WS_POPUP, $WS_EX_DLGMODALFRAME)
GuiRegisterMsg($WM_LBUTTONDOWN, "_WinMove")

GUISetState()

While 1
$Msg = GUIGetMsg()
Switch $Msg
Case -3
Exit
EndSwitch
WEnd

Func _WinMove($HWnd, $Command, $wParam, $lParam)
If BitAND(WinGetState($HWnd), 32) Then Return $GUI_RUNDEFMSG
DllCall("user32.dll", "long", "SendMessage", "hwnd", $HWnd, "int", $WM_SYSCOMMAND, "int", 0xF009, "int", 0)
EndFunc
</syntaxhighlight>

[[#top | ReturnToContents]]

== WinGetTrans ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

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

Example()

Func Example()
Local $hGUI = GUICreate('')
GUISetState(@SW_SHOW, $hGUI)

; Set the transparency of a GUI between 0 and 255. 255 = Solid, 0 = Invisible.
WinSetTrans($hGUI, '', 100)

MsgBox(4096, '', 'The transparency of the GUI is: ' & WinGetTrans($hGUI) & ', this should be 100.')
GUIDelete($hGUI)
EndFunc ;==>Example

; Find the transparency of a GUI.
Func WinGetTrans($sTitle, $sText = '') ; By Valik - http://www.autoitscript.com/forum/topic/...gettrans/page__view__findpost_
Local $iTransColor = 0, $iTransparency = 255
_WinAPI_GetLayeredWindowAttributes(WinGetHandle($sTitle, $sText), $iTransColor, $iTransparency)
Return $iTransparency
EndFunc ;==>WinGetTrans
</syntaxhighlight>

[[#top | ReturnToContents]]

== _WorkingArea ==

{{Snippet Header
| AuthorURL = 35302-guinness
| AuthorName = guinness
}}

<syntaxhighlight lang="autoit">
#include <APIConstants.au3>
#include <GUIConstantsEx.au3>
#include <WinAPI.au3>

Example()

Func Example()
; Set the working area of the Desktop, in this case 120px to the left and retaining the same height and width.
Local $aWorkingArea = _WorkingArea(150, Default, Default, Default)

; Create the GUI.
Local $hGUI = GUICreate('', 150, $aWorkingArea[1], $aWorkingArea[2], $aWorkingArea[3], $WS_POPUP)
Local $iClose = GUICtrlCreateButton('Close', 5, 5, 150 - 10, 25)
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE, $iClose
ExitLoop

EndSwitch
WEnd

; Delete the GUI.
GUIDelete($hGUI)

; Reset the working area to the previous values.
_WorkingArea()
EndFunc ;==>Example

Func _WorkingArea($iLeft = Default, $iTop = Default, $iWidth = Default, $iHeight = Default)
Local Static $tWorkArea = 0
If IsDllStruct($tWorkArea) Then
_WinAPI_SystemParametersInfo($SPI_SETWORKAREA, 0, DllStructGetPtr($tWorkArea), $SPIF_SENDCHANGE)
$tWorkArea = 0
Else
$tWorkArea = DllStructCreate($tagRECT)
_WinAPI_SystemParametersInfo($SPI_GETWORKAREA, 0, DllStructGetPtr($tWorkArea))

Local $tCurrentArea = DllStructCreate($tagRECT)
Local $aArray[4] = [$iLeft, $iTop, $iWidth, $iHeight]
For $i = 0 To 3
If $aArray[$i] = Default Or $aArray[$i] < 0 Then
$aArray[$i] = DllStructGetData($tWorkArea, $i + 1)
EndIf
DllStructSetData($tCurrentArea, $i + 1, $aArray[$i])
$aArray[$i] = DllStructGetData($tWorkArea, $i + 1)
Next
_WinAPI_SystemParametersInfo($SPI_SETWORKAREA, 0, DllStructGetPtr($tCurrentArea), $SPIF_SENDCHANGE)
$aArray[2] -= $aArray[0]
$aArray[3] -= $aArray[1]
Local $aReturn[4] = [$aArray[2], $aArray[3], $aArray[0], $aArray[1]]
Return $aReturn
EndIf
EndFunc ;==>_WorkingArea
</syntaxhighlight>

[[#top | ReturnToContents]]

Helpfile-Changes

2014-01-20T16:51:21Z

Guinness:

This page is for keeping track of changes currently in the process of being made to the AutoIt3 helpfile and UDFs by the MVPs.

For reporting issues please refer to the [http://www.autoitscript.com/forum/topic/146560-report-help-file-issues-here/ Help File Issues] thread. Thanks.

== Doc changes ==
* Magic number removal (Mat)
** Document existing constants (in progress)
** Create new constants where required (making a list)

* [http://www.autoitscript.com/forum/topic/146560-report-help-file-issues-here/page__st__120#entry1048490 AZJIO post #135]
** RegRead type table (Mat), in progress [http://msdn.microsoft.com/en-us/library/windows/desktop/bb773476(v=vs.85).aspx - from guinness]

* General Example improvements
** Make sure no permanent changes are made to system.
** Update examples to make use of new AutoIt features where appropriate.
** Re-write GUI examples
** Sort include statements in examples and remove duplicates. If duplicates are found then take advantage of multiple examples. (guinness)
** Remove unused functions.

== UDF changes ==

* Fixed buffer sizes (as per [http://www.autoitscript.com/forum/topic/147486-ticket-1336/ thread] and ticket 1336)

Best coding practices

2013-08-15T18:22:38Z

Guinness:

Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.

__TOC__

== Variable Naming ==
The Hungarian notation is adopted however it's simplified and regroup all the types of numbers in one type.

{| class="wikitable"
|-
! prefix !! covering type !! initialization
|-
| i || Numbers (any type) || $i = 0
|-
| a || Arrays || $a = 0 or $a[0]
|-
| s || Strings (chars included) || $s = ""
|-
| f || Booleans || $f = False or $f = True
|-
| b || Binaries || $b = ""
|-
| h || Handles (and GUI handles) || $h = 0
|-
| k (not decided) || Keywords || Null (not decided)
|-
| fu (not decided) || Functions || Null (not decided)
|-
| p || Pointers || $p = 0
|-
| tag || Structures definition || $tag = "" (should directly be filled)
|-
| t || Structures || $t = 0
|-
| o || Objects || $o = 0
|}

The variables are named following this schema :
{| class="wikitable"
|-
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| i || f || MyFlag
|}

Example :
<syntaxhighlight lang="autoit">
; Assign a Local variable the number 5.
Local $iSomeVar = 5

; Assign a Local variable the number 1.
Local $ifMyFlag = 1

; Assign a Local variable an array of numbers.
Local $aiArray = 0

; Re-declare the array to size and fill it.
Local $aiArray[3] = [0, 0.25, 3 / 4]
</syntaxhighlight>

Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.

Example :
<syntaxhighlight lang="autoit">
;good
Local $iSomeVar1 = 0, $iSomeVar2 = 5
Local $aiArray = 0

;bad
Local $iSomeVar1, $aiArray = 0
Local $iSomeVar2 = 5
</syntaxhighlight>
You can still categorize your variables and declare for example the $iSomeVar2 on another line.

== Scopes of variables ==
To make the transition, the variables are also named according to their scope.
{| class="wikitable"
|-
! Global UDF variable !! Global variable !! Local variable
|-
| $__iSomeVar || $_iSomeVar || $iSomeVar
|}
Remark: With this method, you will avoid non wanted re-assignments.

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

; Assign a Global variable the number 0.
Global $iSomeVar1 = 0
; Assign a Global variable the number 5.
Global $_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 $_iSomeVar2.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)
EndFunc
</syntaxhighlight>

More coming soon :)

Best coding practices

2013-08-15T12:32:47Z

Guinness:

Outlined in this section, is a detailed explanation of what are to be considered the best coding practices within AutoIt.

Best coding practices

2013-08-15T12:30:13Z

Guinness: Created page with "Best coding practices."

Best coding practices.