AutoIt Wiki - User contributions [en]

Arrays

2015-11-23T08:56:34Z

Melba23:

An '''array''' is a [[Data_Structures|data structure]] which stores elements (variables) aligned in a computer's memory. Arrays are referenced by an [[identifier]] (variable name) and an index specifying a desired element. The array concept seems complex but the concept can be easily grasped. Why are arrays so important? The array is a fundamental data structure found in most programming languages.

This tutorial targets people who are beginners. To understand how arrays work, it is imperative to try out and modify the provided samples. Make sure that each concept is understood before the next concept is attempted. This tutorial assumes the use of the SciTE editor. There is a minimal version of SciTE included in the latest stable release of AutoIt (version 3.2.0.1 and above).

== Declaring Arrays in AutoIt ==

An array is declared in the same manner as a variable in AutoIt. The difference is that for an array, extra information on how many elements are to be included in the array must be specified. This information is provided by adding brackets after the identifier and a number indicating how many elements the array will possess.

<syntaxhighlight lang='autoit'>
Global $arr[4] ; Will make space for 4 elements.
Local $arr[1] ; Will make space for 1 element.
Dim $arr[3] ; Will make space for 3 elements. Note: Avoid using Dim. Use Global or Local instead.
</syntaxhighlight>

In AutoIt, a variable may be converted to an array by either using the {{Help File|ReDim}} keyword or assigning a function which returns an array to the variable.

For example, the function {{Help File|StringSplit}} returns an array which will be assigned to $arr.

<syntaxhighlight lang='autoit'>
Local $arr = StringSplit("This is my string. I want to split it in sentences.", '.')
</syntaxhighlight>

Now to make really certain we have an array from {{Help File|StringSplit}}, we should check it with the {{Help File|IsArray}} built-in function.

<syntaxhighlight lang='autoit'>
If IsArray($arr) Then
; Do work on the array
EndIf
</syntaxhighlight>

== Assigning Data to Array Elements ==

When we declare the array we make some room in memory for future data. We want to assign some data to the items in the array. Now here is the catch. The array always starts at index zero. So, the first element in the array will be accessed by zero, the second element in the array is accessed at by one and so on.

<syntaxhighlight lang='autoit'>
Local $arr[3] ; Make room for three elements
;Assign some data
$arr[0] = "Element 1"
$arr[1] = "Element 2"
$arr[2] = "Element 3"
</syntaxhighlight>

You can also assign all the data in one smack like this:

<syntaxhighlight lang='autoit'>
Local $arr[3] = ["element 1", "element 2", "element 3"]
</syntaxhighlight>

This zero-based indexing is quite common in most computer languages, but it can be a source of headaches to beginners until it becomes second nature to them. For example, every time you want to loop through a range of elements and the range includes the last element, you have to subtract one from the number of items your array is holding, to get the index of the last item. I.E., An array with three elements has a last index of two.

So if you don't take zero-based indexing into consideration in your code, you may ask for something outside the memory area set aside for the array. When you do, you get an error message (<font color="red">Array variable has incorrect number of subscripts or subscript dimension range exceeded</font>) and your script will cease execution.

== Accessing Data in Arrays ==

Let's walk all elements in the previous sample:

<syntaxhighlight lang='autoit'>
Local $arr[3] = ["element 1", "element 2", "element 3"]

For $i = 0 to 3 - 1 ; We have an array with three elements but the last index is two.
ConsoleWrite($arr[$i] & @LF)
Next
</syntaxhighlight>

=== Determine Array Size With UBound ===

The "3 - 1" construct used in the last sample looked strange. It is not a good idea to hard-code size like that. So lets improve our sample a little.

<syntaxhighlight lang='autoit'>
Local $iMax = 3

Local $arr[$iMax] = ["Element 1", "Element 2", "Element 3"]

For $i = 0 to $iMax - 1
ConsoleWrite($arr[$i] & @LF)
Next
</syntaxhighlight>

Now that's a bit cleaner. It's also a lot easier to increase or decrease the size of the array. <br>
But say you don't know the size of the array upfront because it may come in a variable size when created dynamically.

<syntaxhighlight lang='autoit'>
Local $iMax

Local $data = "Element 1|Element 2|Element 3"

; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")

If IsArray($arr) Then
$iMax = UBound($arr); get array size

ConsoleWrite("Items in the array: " & $iMax & @LF)

For $i = 0 to $iMax - 1; subtract 1 from size to prevent an out of bounds error
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</syntaxhighlight>

When you run the above code you will see that $iMax is four and not three as you might have expected. The reason for this is that the developer of the {{Help File|StringSplit}} function thought it was a good idea to use the first item (item zero) to keep a count of valid items in the array. This makes sense in many situations as you now have an array containing data with an index starting at one. So our sample code can now be rewritten like this.

<syntaxhighlight lang='autoit'>
Local $iMax

Local $data = "Element 1|Element 2|Element 3"

; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")

If IsArray($arr) Then
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</syntaxhighlight>

There is another good reason for keeping the count in $arr[0]. When you start to use arrays extensively, you will encounter situations where you have to create an array without knowing how many of the elements you will use. Resizing the array is a relatively expensive operation (in CPU cycles) in most languages.

Now consider our example if our initial array has reserved space for ten items but we end up only using three. In this case iterating the array using {{Help File|UBound}} will force us to check for empty elements. While iterating with $arr[0] needs no other change than maintaining the correct count in $arr[0].

<syntaxhighlight lang='autoit'>
Local $iMax=10

;NOTE: We have added the count in the first element

Local $arr[$iMax] = [3, "Element 1", "Element 2", "Element 3"]

;NOTE: We use the count in $arr[0] to indicate the last item and we start from index=1
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
</syntaxhighlight>

== Changing Array Sizes With ReDim ==

As arrays are critical to algorithm implementations, and in AutoIt even more so as there is no other means of grouping data, we have to understand how to let it grow and shrink. This is where the keyword {{Help File|ReDim}} comes into the picture.

Let's make an example. We want our array to hold data lines but we don't know how many items we need. We make a guess, in this case five. Now, we use that array to hold data we get from a loop with a random number of iterations. If the array is too small it should automatically be increased. Before we dump the array to output, we should adjust it to the exact size it is supposed to be.

<syntaxhighlight lang="autoit">
Local Const $iMax = 5

; NOTE: We have added the count in the first element
Local $arr[$iMax] = [0] ; Initiate the array and place a counter in the first element.

; Generate a random number between 0 and 20
Local Const $iRandom = Random(0, 20, 1)

For $i = 1 to $iRandom
; Check that the array is big enough
If UBound($arr) = $i Then
; Resize the array when $i is equal to the element count in the array to prevent subscript error
ReDim $arr[$arr[0] + $iMax]
EndIf

$arr[$i] = "Item " & $i ; safely add data to new index element

$arr[0] = $i ; update the index count for future reference
Next

; Adjust the array size. This time it is probably downward to the size of
; $arr[0] + 1 (remember the first item is $arr[0])
ReDim $arr[$arr[0] + 1]

; Now dump the results
For $i = 1 to $arr[0]
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next

; Visually check that the values are sound
ConsoleWrite("Ubound($arr):=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & ", $iRandom:=" & $iRandom & @LF)
</syntaxhighlight>

Note how the array now has first been adjusted to a multiple of $iMax and in the last part adjusted down to a size matching the data items.

== Passing Arrays to Functions ==

There is no special syntax required to pass an array as a function argument unlike a low level language such as C.
The following example demonstrates:

<syntaxhighlight lang="AutoIt">
Local Const $myArray[5] = [1, 2, 3, 4, 5]

displayArray($myArray)

Func displayArray(Const $array)
Local Const $arrayLength = UBound($array)

For $i = 0 To $arrayLength - 1
MsgBox($MB_OK, "displayArray", $array[$i])
Next
EndFunc
</syntaxhighlight>

You can not declare the variable to hold the array in the function declaration as an array. So, users could pass on a variable. So you have to check that the variable holds an array before you do array specific operations on it.
The following code example will cause an error:

<syntaxhighlight lang="AutoIt">
Local Const $myArray[5] = [1, 2, 3, 4, 5]

displayArray($myArray)

Func displayArray(Const $array[5])
Local Const $arrayLength = UBound($array)

For $i = 0 To $arrayLength - 1
MsgBox($MB_OK, "displayArray", $array[$i])
Next
EndFunc
</syntaxhighlight>

During the tutorial you have probably noticed that there is a lot of code that is equal in each sample. I'm especially thinking about the code we have used to output the array content. Let's make life easier and create a debug function.

<syntaxhighlight lang="autoit">
Func dbgArray(ByRef $arr, $msg="")
If $msg <> "" Then
ConsoleWrite("*** " & $msg & " ***" & @LF)
EndIf

For $i = 0 to UBound($arr) - 1
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next

ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & @LF)
EndFunc
</syntaxhighlight>

And let's make a little function to fill our arrays with something. Note how the ArrayFiller makes sure it works on an array.

<syntaxhighlight lang="autoit">
Func ArrayFiller(ByRef $arr)
If IsArray($arr) Then
ReDim $arr[3] ; Notice we might discard content in this operation
Else
Local $foo[3]
$arr = $foo
EndIf

;Fill the array
$arr[0] = 2
$arr[1] = "Fill 1"
$arr[2] = "Fill 2"
EndFunc
</syntaxhighlight>

And finally some code using the new functions
<syntaxhighlight lang="autoit">
Local $arr1[1]
ArrayFiller($arr1)
dbgArray($arr1)
</syntaxhighlight>

This code is a test on what happens when we pass a regular variable.
<syntaxhighlight lang="autoit">
Local $arr2
ArrayFiller($arr2)
dbgArray($arr2)
</syntaxhighlight>

== Returning Arrays From Functions ==

As you could observe, in the previous samples, an array will be passed back and forth with the ByRef keyword infront of the variable holding the array in the function declaration.

We could also have used the Return keyword in a function.
Lets re-work the ArrayFiller function to do this rather than using a variable ByRef.

<syntaxhighlight lang="autoit">
Func ArrayFiller2()
Local $arr = [3, "Fill 1", "Fill 2"]
Return $arr
EndFunc
</syntaxhighlight>

And now we can use the function like this

<syntaxhighlight lang="autoit">
Local $foo = ArrayFiller2()
dbgArray($foo)
</syntaxhighlight>

== Comparing Arrays ==

'''You can not compare complete arrays:'''<br/>
<syntaxhighlight lang="autoit">
Local $Array1[3] = [1, 2, 3]
Local $Array2[3] = [1, 2, 3]
Local $Array3[4] = [1, 2, 3, 4]

If $Array1 == $Array2 Then ConsoleWrite("1.) $Array1 is equal to $Array2! which might be correct in some sense." & @LF); while they contain the same data, the comparison does not work.

If $Array1 == $Array3 Then ConsoleWrite("2.) $Array1 is equal to $Array3! which is incorrect." & @LF); even though they're different in size, it's incorrectly determined that they're equal.
</syntaxhighlight>

I have the impression that such comparisons compare the memory address of the arrays instead of the array elements values. And the addresses are always different for different arrays. You have to instead, compare all elements one after the other. It might be a good idea to first compare array sizes if that can vary for both the compared arrays!

== Multi Dimensional Arrays ==

Now what is a good explanation of a multi-dimensional array?
It could be a table where you access one item in the table at a time.

<syntaxhighlight lang="autoit">
Local $arr[3][3] = [[1, 2, 3], [2, 3, 4], [3, 4, 5]]

For $i = 0 to UBound( $arr, 1) - 1
For $j = 0 to UBound($arr, 2) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "]:=" & $arr[$i][$j] & @LF)
Next

ConsoleWrite(@LF)
Next
</syntaxhighlight>

You can add a number of dimensions not to exceed sixty-four as stated in the help file section [http://www.autoitscript.com/autoit3/docs/appendix/LimitsDefaults.htm AutoIt3 limits/Defaults].

Here is a four dimensional example. You tell me how that initializer is for readability.

<syntaxhighlight lang="autoit">
; NOTE: The following is supposed to be all on one line
; but we use the "_" character to split it into multiple lines for readability

Local $arr[3][3][3][3] = _
[ _
[ _
[[1, 2, 3], [2, 3, 4], [3, 4, 5]], _
[[1, 2, 3], [2, 3, 4], [3, 4, 5]], _
[[1, 2, 3], [2, 3, 4], [3, 4, 5]] _
], _
[ _
[[1, 2, 3], [2, 3, 4], [3, 4, 5]], _
[[1, 2, 3], [2, 3, 4], [3, 4, 5]], _
[[1, 2, 3], [2, 3, 4], [3, 4, 5]] _
], _
[ _
[[1, 2, 3], [2, 3, 4], [3, 4, 5]], _
[[1, 2, 3], [2, 3, 4], [3, 4, 5]], _
[[1, 2, 3], [2, 3, 4], [3, 4, 5]] _
] _
]

For $i = 0 To UBound($arr, 1) - 1
For $j = 0 To UBound($arr, 2) - 1
For $k = 0 To UBound($arr, 3) - 1
For $l = 0 To UBound($arr, 4) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "][" & $k & "][" & $l & "]:=" & $arr[$i][$j][$k][$l] & @LF)
Next
Next
Next
Next

ConsoleWrite(@LF)
</syntaxhighlight>

== Arrays in Arrays ==

You may save an array in an array element (item). Remember that there may be issues if you pass an array containing arrays into a function and the embedded array is changed inside that function. So, as a general rule, try not to embed arrays within arrays unless you absolutely need to and are prepared to do rigorous testing to make sure your code will always work as expected.

You can access the elements of these embedded arrays directly (note the additional () required):

<syntaxhighlight lang="autoit">
Local $aContainerArray[2]
Local $aInternalArray_0[2] = ["Internal-0-0","Internal-0-1"]
Local $aInternalArray_1[2] = ["Internal-1-0","Internal-1-1"]
$aContainerArray[0] = $aInternalArray_0
$aContainerArray[1] = $aInternalArray_1

ConsoleWrite("1 element of InternalArray_0: " & ($aContainerArray[0])[1] & @CRLF)
ConsoleWrite("0 element of InternalArray_1: " & ($aContainerArray[1])[0] & @CRLF)
</syntaxhighlight>

== More Information ==

AutoIt features a large list of [http://www.autoitscript.com/autoit3/docs/libfunctions.htm User Defined Functions (UDF)], among which is a module supplying extra array functions. You can find a reference on those functions in AutoIt's Help file as the last main chapter named [http://www.autoitscript.com/autoit3/docs/libfunctions.htm User Defined Functions Reference].

[[Category:Tutorials]]

User Defined Functions

2015-05-19T15:42:28Z

Melba23:

This page is a listing of libraries of '''user defined functions''' (UDF). These libraries have been written to allow easy integration into your own scripts and are a very valuable resource for any programmer.
This list is probably not complete, but constantly supplemented.
If you do not find a solution here, ask a new question on the [http://www.autoitscript.com/forum/forum/2-general-help-and-support/ forum].

== Automation ==
* [http://www.autoitscript.com/forum/index.php?showtopic=106163 Active Directory (by water)] - Extensive library to control and manipulate the Windows active directory. Link to the [[Active_Directory_UDF_-_General|documentation]] pages.
* [http://www.autoitscript.com/forum/index.php?showtopic=150231 GTK+ (by prazetto)] - GTK+ Framework | Widgets.
* [http://www.autoitscript.com/forum/index.php?showtopic=153520 IUIAutomation MS framework (by junkew)] - IUIAutomation MS framework to automate chrome, FF, IE etc.
* [http://www.autoitscript.com/forum/index.php?showtopic=87956 Java (by seangriffin)] - Creates an access bridge between your application and a Java application. Allowing you to automate some Java applications.
* [http://www.autoitscript.com/forum/index.php?showtopic=86574 SAP (by seangriffin)] - SAP business management automation.
* [http://www.autoitscript.com/forum/index.php?showtopic=149540 SAPWizard (by ozmike)] - SAPWizard UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=80201 Service (by arcker)] - Build your own service with AutoIt code.
* [http://www.autoitscript.com/forum/index.php?showtopic=91018 WiFi (by MattyD)] - Low level control over your wireless LAN.

===Browsers===
* [http://www.autoitscript.com/forum/index.php?showtopic=154439 Chrome (by seangriffin)] - The same as above for Google Chrome. Automate the most common tasks in Chrome with the Chrome UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=95595 Firefox (by Stilgar)] - A little less support for automation than IE, but still very good.
* [http://www.autoitscript.com/forum/index.php?showtopic=166542 HTMLDocumentEvents (by SmOke_N)] - Track IE document events.
* [http://www.autoitscript.com/forum/index.php?showtopic=166304 IEJS (by SmOke_N)] - IEJS - IE Javascript options, an IE.au3 personal extension.
* Internet Explorer (by DaleHohm et al.) - Everything about Internet explorer can be automated with the IE library supplied with a standard AutoIt install.
* [http://www.autoitscript.com/forum/index.php?showtopic=149203 NavInfo (by Nessie)] - With this UDF you can check if a specified browser/software is installed and which version is being used.
* [http://www.autoitscript.com/forum/index.php?showtopic=61090 Opera (by MrCreatoR,)] - The same as above for Opera. Automate the most common tasks in Opera with the Opera UDF.

===Microsoft Office Automation===
* [http://www.autoitscript.com/forum/index.php?showtopic=32144 Microsoft Office Access (by randallc)] - Automate Microsoft Access.
* Microsoft Office Excel (by water et al.) - This UDF is included in AutoIt. Link to the [[Excel_UDF|documentation]] pages.
* [http://www.autoitscript.com/forum/index.php?showtopic=135312 Microsoft Office Excel Charts (by water, GreenCan)] - Creating charts using Microsoft Excel.
* [http://www.autoitscript.com/forum/index.php?showtopic=126305 Microsoft Office Outlook (by water )] - Automate Microsoft Outlook. Link to the [[OutlookEX_UDF_-_General|documentation]] pages.
* [http://www.autoitscript.com/forum/index.php?showtopic=50254 Microsoft PowerPoint (by Toady)] - Automate Microsoft PowerPoint.
* Microsoft Office Word (by water et al.) - This UDF is included in AutoIt. Link to the [[Word_UDF|documentation]] pages.

===OpenOffice Automation===
* [http://www.autoitscript.com/forum/index.php?showtopic=151530 OOo/LibO Calc (by GMK)] - OpenOfficeCalc UDF.

== Hardware ==
* [[CommAPI]] - Serial and parallel communication (COM port, RS-232, LPT port) - without installing DLL's (using Windows API calls).
* [http://www.autoitscript.com/forum/index.php?showtopic=77731 Device Management (by ... )] - Device Management API.
* [http://www.autoitscript.com/forum/index.php?showtopic=97487 DirectShow (by ... )] - DirectShow UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=164700 DirectSound (by ... )] - DirectSound UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=164701 Direct2D (by ... )] - Direct2D UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=138989 FritzBox (by ... )] - _FB_Tools - manage your FritzBox from Autoit.
* [http://www.autoitscript.com/forum/index.php?showtopic=121084 I/O Port Functions (by ... )] - This is a simple I/O (Input/Output) UDF for interacting with ports. (I/O Port Functions - x64 Parallel Port IO, Keyboard, etc + Restore PC Speaker Beep).
* [http://www.autoitscript.com/forum/index.php?showtopic=154350 Monitor Configuration (by ... )] - Monitor Configuration UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=155469 Mouse (by ... )] - AutoIt powered mouse events.
* [http://www.autoitscript.com/forum/index.php?showtopic=147325 MouseTrapEvent (by ... )] - MouseTrapEvent UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=149083 NetInfo (by ... )] - UDF for test internet download speed and upload speed.
* [http://www.autoitscript.com/forum/index.php?showtopic=155539 Network configuration (by ... )] - Network configuration UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=20121 Screen Resolution (by ... )] - Screen Resolution Changing UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=128546 Serial Port/COM (by ... )] - Serial Port /COM Port UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=27755 SMARTDRIVE (by ... )] - SMART drive Analysis.
* [http://www.autoitscript.com/forum/index.php?showtopic=15864 SPI Hardware Interface (by ... )] - This script is made to comunicate with the MAX335 chip using the SPI protocol via the LPT(printer) port.
* [http://www.autoitscript.com/forum/index.php?showtopic=68866 Webcam (by LIMITER)] - Webcam UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=70857 Webcam (by ludocus)] - Webcam UDF.

== Information gathering ==
* [http://www.autoitscript.com/forum/index.php?showtopic=29404 Computer information (by JSThePatriot)] - A general purpose library to get various details about a Windows machine.
* [http://www.autoitscript.com/forum/index.php?showtopic=54039 WinPcap (by JRSmile)] - Wrapper for the windows packet capture library WinPcap.
* [http://opensource.grisambre.net/pcapau3/ WinPcap (by Nicolas Ricquemaque)] - A library to access the main functionalities offered by the WinPcap driver.

== Databases and web connections ==
* [http://www.autoitscript.com/forum/index.php?showtopic=105875 ADODB (by spudw2k)] - ADODB Example.
* [http://www.autoitscript.com/forum/index.php?showtopic=145142 DBF (by funkey)] - dBase database read and write with DLL.
* [http://www.autoitscript.com/forum/index.php?showtopic=116072 EzMySql (by ... )] - EzMySql - Use MySql Databases with autoit.
* [http://www.autoitscript.com/forum/topic/94920-solved-passing-parameters-using-dllcall-to-a-c-dll/#entry684751 FireBird (by ... )] - FireBird, Interbase dll udf.
* [http://stackoverflow.com/questions/21991475/autoit-firebird-sql-combo-return-data-as-csv-instead-of-xml FireBird (by ... )] - Additional link to FireBird UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=127101 MS SQL (by ... )] - MSSQL.au3.
* [http://www.autoitscript.com/forum/index.php?showtopic=51952 MS SQL (by ... )] - _SQL.au3. ADODB Connection.
* [http://www.autoitscript.com/forum/index.php?showtopic=20814 MySQL (by ... )] - MySQL relational database management system UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=85617 MySQL (by ... )] - MySQL UDFs (without ODBC).
* [http://www.autoitscript.com/forum/index.php?showtopic=17099 SQLite (by ... )] - SQLite is a library that implements a self-contained, embeddable, zero-configuration SQL database engine.
* [http://www.autoitscript.com/forum/index.php?showtopic=19848 XML DOM Wrapper (by ... )] - Supports CRUD operations on XML. Including XSL and XPath.

== Internet protocol suite ==
* [http://www.autoitscript.com/forum/index.php?showtopic=137456 cURL (by ... )] - cURL UDF - a UDF for transferring data with URL syntax.
* [http://www.autoitscript.com/forum/index.php?showtopic=40243 IMAP (by ... )] - IMAP.
* [http://www.autoitscript.com/forum/index.php?showtopic=108422 IMAP4 (by ... )] - IMAP4 UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=43515 IRC (by ... )] - A lightweight library for communicating with IRC servers.
* [http://www.autoitscript.com/forum/index.php?showtopic=159285 IRC (by ... )] IRC UDF - Updated Version of Chips' IRC UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=104150 JSON (by ... )] - RFC4627 compliant JSON encode/decode.
* [http://www.autoitscript.com/forum/index.php?showtopic=148114 JSON (by ... )] - JSMN - A Non-Strict JSON UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=156794 JSON (by ... )] - Bridge to Native Windows JSON plus OO extension for AutoIt.
* [http://www.autoitscript.com/forum/index.php?showtopic=22838 POP3 (by ... )] - POP3 library for retrieving email messages. Not compatible with Gmail because it uses SSL.
* [http://www.autoitscript.com/forum/index.php?showtopic=167339 _POP3_Ex (by ... )] POP3 UDF According to the 1939 RFC, modified version with Quoted Printable decoder.
* [http://www.autoitscript.com/forum/index.php?showtopic=64051 POP3 SSL (by ... )] - A POP3 library that's compatible with Gmail. It uses an external executable that must be supplied with your script.
* [http://www.autoitscript.com/forum/index.php?showtopic=154530 Prowl (by ... )] - Prowl UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=138095 SFTP (by ... )] - UDF to support SFTP protocol using PSFTP.
* [http://www.autoitscript.com/forum/index.php?showtopic=23860 SMTP (by ... )] - Smtp Mailer That Supports Html And Attachments.
* [http://www.autoitscript.com/forum/index.php?showtopic=81687 SNMP (by ... )] - SNMP_UDF for SNMPv1 and SNMPv2c.
* [http://www.autoitscript.com/forum/index.php?showtopic=70759 SNMP - MIB protocol (by ... )] (Reading toner status from SNMP device with WMI).
* [http://www.autoitscript.com/forum/index.php?showtopic=166579 SSH (by ... )] - This UDF allows to use the SSH protocol very easily in your code.
* [http://www.autoitscript.com/forum/index.php?showtopic=57022 UPnP Protocol (by ... )] - UPnP : Read and Control your devices in side out.
* [http://www.autoitscript.com/forum/index.php?showtopic=84133 WinHTTP (by ... )] - Enables scripts to access the HTTP protocol for creating GET and POST requests and submitting them with conforming standards, cookies not supported.
* [http://www.autoitscript.com/forum/index.php?showtopic=77503 WinInet (by ... )] - Enables scripts to access standard Internet protocols, such as FTP, Gopher and HTTP. Also supports creating GET and POST requests and submitting them with conforming standards, cookies supported.
* [http://www.autoitscript.com/forum/index.php?showtopic=169774 TCPServer (by ... )] - multi client, event-based, able to bind console app to socket.

== Data compression ==
* [http://www.autoitscript.com/forum/index.php?showtopic=85094 7z, zip, gzip, bzip2, tar (by ... )] - More extensive library than the one above. Uses a external DLL that must be provided with the script.
* [http://www.autoitscript.com/forum/index.php?showtopic=87441 LZMA (by trancexx )] - LZMA (Native Windows).
* [http://www.autoitscript.com/forum/index.php?showtopic=112273 LZMA Compression (by ... )] - LZMA Compression UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=166634 MessagePack (by ... )] - MessagePack is an efficient binary serialization format. It lets you exchange data among multiple languages like JSON. But it's faster and smaller.
* [http://www.autoitscript.com/forum/index.php?showtopic=138838 Package (by ... )] - Package UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=129529 pZip (by ... )] - PureZIP_L library UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=76176 UnRAR (by ... )] - UnRAR.au3.
* [http://www.autoitscript.com/forum/index.php?showtopic=44524 Zip plugin (by ... )] - Zip plugin.
* [http://www.autoitscript.com/forum/index.php?showtopic=73425 ZIP (by ... )] - ZIP.au3 UDF in pure AutoIt.
* [http://www.autoitscript.com/forum/index.php?showtopic=116565 zip (by ... )] - Create ZIP files and unpack ZIP files.
* [http://www.autoitscript.com/forum/index.php?showtopic=135565 ZIP (by ... )] - ZIP STRUCTS UDF (from scratch).
* [http://www.autoitscript.com/forum/index.php?showtopic=128962 zLib (by ... )] - zLib (Deflate/Inflate/GZIP) UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=17727 XZip (by eltorro)] - another UDF for "XStandard XZIP Component".
* [http://www.autoitscript.com/forum/index.php?showtopic=161847 XZip (by mLipok)] - UDF for "XStandard XZIP Component".

== Encryption and hash ==
* [http://www.autoitscript.com/forum/index.php?showtopic=78745 AES Rijndael (by ... )] - Very fast AES UDF. Support ECB/CBC/CFB/OFB block cipher mode.
* [http://www.autoitscript.com/forum/index.php?showtopic=76976 MD5,SHA1,CRC32,RC4,BASE64,XXTEA (by ... )] - Several encryption and hash functions.
* [http://www.autoitscript.com/forum/index.php?showtopic=107784 TrueCrypt (by ... )] - TrueCrypt UDFs.

== Media ==
* [http://www.autoitscript.com/forum/index.php?showtopic=95357 FreeImage library (by ... )] - Various operations on images, such as rotate, resize, flip.
* [http://www.autoitscript.com/forum/index.php?showtopic=127263 HtmlHelp (by ... )] - HtmlHelp UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=50608 OCR (by ... )] - Real OCR in AU3 - MODI with MS Office 2003.
* [http://www.autoitscript.com/forum/index.php?showtopic=89542 OCR (by ... )] - Tesseract (Screen OCR) UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=51054 Printer controller (by ... )] - Print text in any font, size and colour at any position on the page, draw lines, curves, elipses, pies in any colour, and print images.
* [http://www.autoitscript.com/forum/index.php?showtopic=73993 Printing (by ... )] - Printing from AutoIt.
* [http://www.autoitscript.com/forum/index.php?showtopic=161831 RTF_Printer (by ... )] - RTF_Printer.au3 - Printing RichEdit in the background.
* [http://www.autoitscript.com/forum/index.php?showtopic=94834 Simple DirectMedia Layer (by ... )] - Adds support for joysticks, CDs, 2D graphics, timers. See [http://www.libsdl.org/ SDL website] for more information.
===Sound===
* [http://www.autoitscript.com/forum/index.php?showtopic=83481 BASS Function Library (by ... )] - Sound and Music via wrappers for Bass, BassEnc, Bass FX, BassSFX, BassAsio and BassCd DLLs.
* [http://www.autoitscript.com/forum/index.php?showtopic=37072 MIDI (by ... )] - MIDI UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=114742 SAPIListBox (by ... )] - SAPIListBox (Speech Recognition) UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=100439 TTS (by ... )] - Text-to-Speech UDF.

===Graphics and image===
* [http://www.autoitscript.com/forum/index.php?showtopic=27362 Bitmap Library (by ... )] - Bitmap Library.
* [http://www.autoitscript.com/forum/index.php?showtopic=70506 IrrLicht (by ... )] - A 3D graphics engine suitable for creating games.
* [http://www.autoitscript.com/forum/index.php?showtopic=113881 au3Irrlicht2 (by ... )] - Another UDF bringing Irrlicht and au3 together. Historically some kind of a follower of the UDF above, technically with a complete different approach.
* [http://www.autoitscript.com/forum/index.php?showtopic=13096 ImageGetInfo (by ... )] - This is an UDF for reading info from JPEG, TIFF, BMP, PNG and GIF - size, color depth, resolution.
* [http://www.autoitscript.com/forum/index.php?showtopic=151011 OpenGL (by ... )] - OpenGL without external libraries etc. For JPEG files UDF also retreive various Exif information.
* [http://www.autoitscript.com/forum/index.php?showtopic=148129 OpenGL (2.0) (by ... )] - new set of UDFs for OpenGL + AutoIt.

===Players===
* [http://www.autoitscript.com/forum/index.php?showtopic=114143 VLC (by ... )] - VLC (Media Player) UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=91316 VLC Media Player (by ... )] - VLC Media Player.
* [http://www.autoitscript.com/forum/index.php?showtopic=27352 WMP (by ... )] - Windows Media Player UDF.

== GUI Additions ==
* [http://www.autoitscript.com/forum/index.php?showtopic=32494 XSkin (by ... )] - A large library that allows skinning of your GUI and to apply custom skins.
* [http://www.autoitscript.com/forum/index.php?showtopic=132864 Uskin (by ... )] - A library that allows a user to skin their application GUI using the Windows ''.MSstyles'' files.
* [http://www.autoitscript.com/forum/index.php?showtopic=20967 Modern tray menu (by ... )] - Allows the creation of modern, fancy GUI and tray menus with icons and colors.
* [http://www.autoitscript.com/forum/index.php?showtopic=71811 SetOnEvent (by ... )] - Provides an easy way for an event to call functions with parameters.
* [http://www.autoitscript.com/forum/index.php?showtopic=119505 GUIFrame (by Melba23 & Kip)] - Divide a GUI into adjustable frames.
* [http://www.autoitscript.com/forum/index.php?showtopic=113723 Easy Scrollbars (by Melba23)] - Easily create scrollable sections in your GUI.
* [http://www.autoitscript.com/forum/index.php?showtopic=105582 GUICtrlOnChangeRegister (by ... )] - Call a function when an edits content is changed.
* [http://www.autoitscript.com/forum/index.php?showtopic=96258 ContextHelp.au3 (by ... )] - Management of context help ([http://www.autoitscript.com/forum/index.php?showtopic=72152-contexthelp/ original]).
* [http://www.autoitscript.com/forum/index.php?showtopic=145149 GUIExtender (by Melba23)] - Expand and contract sections of your GUI ([http://www.autoitscript.com/forum/index.php?showtopic=117909 original]).
* [http://www.autoitscript.com/forum/index.php?showtopic=109096 ExtMsgBox (by Melba23)] - A very customisable replacement for MsgBox.
* [http://www.autoitscript.com/forum/index.php?showtopic=108445 Toast (by Melba23)] - Small message GUIs which pop out of the Systray.
* [http://www.autoitscript.com/forum/index.php?showtopic=144207 GUI Panel (by ... )] - Manage child GUIs as panel ctrls.
* [http://www.autoitscript.com/forum/index.php?showtopic=161750 Pie chart (by ... )] - Pie chart.
* [http://www.autoitscript.com/forum/index.php?showtopic=97241 3D Pie chart (by ... )] - 3D Pie chart.

=== Controls ===
* [http://www.autoitscript.com/forum/index.php?showtopic=79412 Graph control (by ... )] - Easily create and show bar chart and line charts.
* [http://www.autoitscript.com/forum/index.php?showtopic=105682 GUICtrlCreateFinder (by ... )] - Allows you to create a window finder control like the one seen in AutoIt Window Info.
* [http://www.autoitscript.com/forum/index.php?showtopic=111438 GUIPager (by ... )] - Create and control native pager controls.
* [http://www.autoitscript.com/forum/index.php?showtopic=90598 Hotkey input control (by ... )] - Hotkeys Input Control UDF Library (Non-native).
* [http://www.autoitscript.com/forum/index.php?showtopic=107965 GUIHotkey (by ... )] - UDF for using native hotkey controls.
* [http://www.autoitscript.com/forum/index.php?showtopic=143711 Marquees (by Melba23)] - Make tickertape info bars.
* [http://www.autoitscript.com/forum/index.php?showtopic=96464 Colorpicker (by ... )] - Create a button for the user to select a color.
* [http://www.autoitscript.com/forum/index.php?showtopic=126958 Syslink (by ... )] - Provides a convenient way to embed hypertext links in a window.
* [http://www.autoitscript.com/forum/index.php?showtopic=74649 Progressbar with GDIplus (by ... )] - You even can use full textured images.
* [http://www.autoitscript.com/forum/index.php?showtopic=105814 Table (by ... )] - Table UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=20967 GUI/Tray Menu (by Holger, LarsJ, AZJIO)] - GUI/Tray Menu with icons and colors.
* [http://www.autoitscript.com/forum/index.php?showtopic=128242 Ribbon (by ... )] - UDF for Windows Ribbon framework.
* [http://www.autoitscript.com/forum/index.php?showtopic=166594 GUITreeViewEx (by Melba23)] - Check/clear parent and child checkboxes in a TreeView.
* [http://www.autoitscript.com/forum/index.php?showtopic=146406 Calendar (by ... )] - Calendar UDF.

== Maths ==
* [http://www.autoitscript.com/forum/index.php?showtopic=83091 Primes (by ... )] - Many functions dealing with prime number generation and calculations.
* [http://www.autoitscript.com/forum/index.php?showtopic=83529 Big number (by ... )] - Make calculations with extremely large numbers that AutoIt normally is not able to support.
* [http://www.autoitscript.com/forum/index.php?showtopic=81189 Number base conversion (by ... )] - From, to and between positive bases less than 63 (decimals supported).
* [http://www.autoitscript.com/forum/index.php?showtopic=106551 Decimal To fraction (by ... )] - Converts any decimal number to a fraction. Example: 1.2 to 6/5.
* [http://www.autoitscript.com/forum/index.php?showtopic=82722 Trigonometry math functions (by ... )] - _ATan2(), _Cosh(), _Frexp(), _Hypot(), _Ldexp(), _Logb(), _Sinh(), _Tanh().
* [http://www.autoitscript.com/forum/index.php?showtopic=108803 Polynomials (by ... )] - Functions for using polynomials.
* [http://www.autoitscript.com/forum/index.php?showtopic=117156 NumToWord (by ... )] - Convert numerals to a human readable string.
* [http://www.autoitscript.com/forum/index.php?showtopic=98160 Root function (by ... )] - Working out real roots of numbers.
* [http://www.autoitscript.com/forum/index.php?showtopic=102686 Advanced rounding (by ... )] - Support for different measures of accuracy and 8 ways to resolve tie breaks.
* [http://www.autoitscript.com/forum/index.php?showtopic=94770 Roman Numerals (by Mat)] - Integer to roman numerals.
* [http://www.autoitscript.com/forum/topic/123398-snippet-dump/page-3#entry1005157 Roman Numerals (by czardas)] - Roman Numerals.
* [http://www.autoitscript.com/forum/topic/94770-integer-to-roman-numerals/#entry1043544 Roman Numerals (by AZJIO)] - Roman Numerals.

* [http://www.autoitscript.com/forum/index.php?showtopic=163899 StringAPL (by ... )] - inline APL interpreter.

== Misc ==
* [http://www.autoitscript.com/forum/index.php?showtopic=90492 Hotkey.au3 (by ... )] - Management of Hotkeys UDF, with several advantages over HotkeySet().
* [http://www.autoitscript.com/forum/index.php?showtopic=97826 Animated tray icons (by ... )] - Make animated tray icons easily.
* [http://www.autoitscript.com/forum/index.php?showtopic=101733 NoFocusLines (by Melba23)] - Remove the dotted focus lines from buttons, sliders, radios and checkboxes which spoil the look of your GUI.
* [http://www.autoitscript.com/forum/index.php?showtopic=114034 StringSize (by Melba23)] - Automatically size controls to fit the text you want to put in them.
* [http://www.autoitscript.com/forum/index.php?showtopic=162033 Spell Checker (by ... )] - Spell Checker UDF - Hunspell.
* [http://www.autoitscript.com/forum/index.php?showtopic=125251 TVExplorer (by ... )] - TVExplorer UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=162366 BinaryCall (by ... )] - BinaryCall UDF - Write Subroutines In C, Call In AutoIt.
* [http://www.autoitscript.com/forum/index.php?showtopic=161628 LFN (by ... )] - LFN UDF - overcome MAX_PATH limit of 256 chars.
* [http://www.autoitscript.com/forum/index.php?showtopic=81267 Clipboard History/Sotrage (by ... )] - UDF to save and restore the entire clipboard contents.
* [http://www.autoitscript.com/forum/index.php?showtopic=51103 Resources (by ... )] - Resources UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=162499 ResourcesEx (by ... )] - ResourcesEx UDF (up to date with the current AutoIt language syntax v3.3.12.0).
* [http://www.autoitscript.com/forum/index.php?showtopic=149176 NotifyIcon (by ... )] - NotifyIcon UDF (formerly TrayIconEx) - Create, delete and manage self notify icons.
* [http://www.autoitscript.com/forum/index.php?showtopic=131037 Binary (by ... )] - Binary UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=99106 _DLLStructDisplay (by ... )] - Show Struct in ListView.
* [http://www.autoitscript.com/forum/index.php?showtopic=55994 DDEML (by ... )] - With DDEML UDF one can use an AutoIt script as a DDE client or server.
* [http://www.autoitscript.com/forum/index.php?showtopic=157689 _FileGetMimeType (by ... )] - _FileGetMimeType UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=157241 FindMimeFromData (by ... )] - FindMimeFromData using urlmon.dll.
* [http://www.autoitscript.com/forum/index.php?showtopic=63318 PixelGetColor (by ... )] - Get or Read Pixel from Memory UDF.
* [http://www.autoitscript.com/forum/topic/117033-file-locking-with-cooperative-semaphores File locking with cooperative semaphores (by ... )] - Simple file locking without a server.
* [http://www.autoitscript.com/forum/index.php?showtopic=142977 SQLite Array Functions (by ... )] - SQLite Array Functions - a faster method for unique arrays and sorting methods.
* [http://www.autoitscript.com/forum/index.php?showtopic=164444 Synology filestation (by ... )] - UDF for users of Synology NAS server.
* [http://www.autoitscript.com/forum/index.php?showtopic=163577 Atom Table (by ... )] - Basically, a bunch of strings can be stored locally (at program level) or globally (at O/S level) with unique numerical identifiers. This UDF lets you add, find, delete, and query these atoms.
* [http://www.autoitscript.com/forum/index.php?showtopic=121833 Copy (by ... )] - This small library allows simple and reliable way to copy or move files and directories without suspending your script. Moreover, you can get the current state (number of copied bytes, system error code, and other status information) while copying.
* [http://www.autoitscript.com/forum/index.php?showtopic=86672 AutoIt Inline Assembly (by ... )] -
* [http://www.autoitscript.com/forum/index.php?showtopic=111613 FASM (by ... )] - The Embedded Flat Assembler (FASM) UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=77463 MemoryDll (by ... )] - Embed DLLs in script and call functions from memory.
* [http://www.autoitscript.com/forum/index.php?showtopic=167024 RDC (by ... )] - ReadDirectoryChanges Wrapper.
* [http://www.autoitscript.com/forum/index.php?showtopic=170087 barcode-generators (by willichan )] - Creates a Code128A/B/C or Creates a Code39 or Code39Extended optimized barcode from supplied data.
* [http://www.autoitscript.com/forum/index.php?showtopic=169610 CmdLine (by Jefrey )] - Collection of functions to parse command line arguments.

== PDF ==
* [http://www.autoitscript.com/forum/index.php?showtopic=42776 PDFCreator (by ... )] - Automation of PDFCreator allows you to create and manipulate PDF files.
* [http://www.autoitscript.com/forum/index.php?showtopic=160875 Debenu Quick PDF Library (by ... )] - A collection of functions for Debenu Quick PDF Library.
* [http://www.autoitscript.com/forum/index.php?showtopic=118827 MPDF (by ... )] - Create PDF from your application.
* [http://www.autoitscript.com/forum/index.php?showtopic=164469 Debenu PDF Viewer SDK (by ... )] - A collection of functions to display PDF files in your applications using Debenu PDF Viewer SDK.
* [http://www.autoitscript.com/forum/index.php?showtopic=75832 FoxIt Reader (by ... )] - PDF Reader in AU3.
* [http://www.autoitscript.com/forum/index.php?showtopic=32261 _StringToPDF (by ... )] - Write a string to a PDF file and specify font size, type etc.

== Windows ==
* [http://www.autoitscript.com/forum/index.php?showtopic=145158 Firewall (by ... )] - Windows Firewall UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=158377 UAC (by ... )] - User Account Control (UAC) UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=50880 ACL (by ... )] - Set ACL on windows Objects.
* [http://www.autoitscript.com/forum/index.php?showtopic=124508 Startup (by ... )] - Create Startup entries in the Startup Folder or Registry.
* [http://www.autoitscript.com/forum/index.php?showtopic=74118 Local account (by ... )] - Local account UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=81880 Windows Services (by ... )] - Windows Services UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=111018 ITaskBarList (by ... )] - ITaskBarList UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=113560 FileSystemMonitor (by ... )] - FileSystemMonitor UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=161193 Magnifier Functions (by ... )] - Magnifier Functions - Windows Vista+ Magnifier Manipulation.
* [http://www.autoitscript.com/forum/index.php?showtopic=163178 WRMF (by ... )] - WRMF - Windows Registry Monitor Call Function.
* [http://www.autoitscript.com/forum/index.php?showtopic=75250 Registry (by ... )] - Windows Registry UDFs.
* [http://www.autoitscript.com/forum/index.php?showtopic=50551 Registry (by ... )] - RegWriteAllUsers / RegDeleteAllUsers.
* [http://www.autoitscript.com/forum/index.php?showtopic=134628 System restore (by ... )] - System restore UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=83355 Task Scheduler (by ... )] - Task Scheduler UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=135994 Taskplanner/Taskscheduler COM (by ... )] - an UDF for using the Windows Taskplaner / Task Scheduler
* [http://www.autoitscript.com/forum/index.php?showtopic=28436 Windows Events (by ... )] - Create your own Windows events.
* [http://www.autoitscript.com/forum/index.php?showtopic=161193 Magnifier Functions (by ... )] - This UDF exposes most of the useful Magnifier API functions available since Windows Vista.
* [http://www.autoitscript.com/forum/index.php?showtopic=127075 WIMGAPI (by ... )] - A UDF for manipulating Windows Image Files (.wim) without ImageX.exe.

== Security ==
* [http://www.autoitscript.com/forum/index.php?showtopic=150819 VirusTotal (by ... )] - VirusTotal API 2.0 UDF.

== Social Media and other Website API ==
* [http://www.autoitscript.com/forum/index.php?showtopic=116600 Twitter (by ... )] - Twitter UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=70675 iTunes (by ... )] - iTunes UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=101802 iTunes (by ... )] - another iTunes UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=149247 Yahoo Weather (by ... )] - YWeather UDF - Yahoo Weather API.
* [http://www.autoitscript.com/forum/index.php?showtopic=115437 Google Maps (by ... )] - Google Maps UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=150473 Google API (by ... )] - JSON queries for Google API.
* [http://www.autoitscript.com/forum/index.php?showtopic=131343 PasteBin (by ... )] - PasteBin (powered by PasteBin).
* [http://www.autoitscript.com/forum/index.php?showtopic=150838 PasteBin (by ... )] - Pastebin UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=114801 eBay (by ... )] - eBay UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=141340 Gmail (by ... )] - Remote Gmail (UDF).
* [http://www.autoitscript.com/forum/index.php?showtopic=150985 No-IP (by ... )] - With this UDF you can simply update your no-ip hostname(s) and retrive the ip address of an no-ip address.
* [http://www.autoitscript.com/forum/index.php?showtopic=112775 Youtube Uploader (by ... )] - AYTU - AutoIt Youtube Uploader.
* [http://www.autoitscript.com/forum/index.php?showtopic=98504 Google Functions (by ... )] - Google Functions.
* [http://www.autoitscript.com/forum/files/file/290-dropbox-authenticator/ Dropbox authenticator (by ... )] - Dropbox authenticator.
* [http://www.autoitscript.com/forum/index.php?showtopic=166547 TVmaze.com API (by ... )] - TVmaze.com API UDF (TV-Series).
* [http://www.autoitscript.com/forum/index.php?showtopic=113234 Teamspeak 3 (by ... )] - Teamspeak 3 UDF.
* [http://www.autoitscript.com/forum/index.php?showtopic=166205 TeamViewer API (by ... )] - UDF for TeamViewer API - a modest beginning.
* [http://www.autoitscript.com/forum/index.php?showtopic=158106 Easypost (by ... )] - Print USPS Postage Labels.
* [http://www.autoitscript.com/forum/index.php?showtopic=121767 Skype (by ... )] - Skype4COM provides an ActiveX interface to the Skype API.
* [http://www.autoitscript.com/forum/index.php?showtopic=169333 CrowdinAPI (by ... )] - This is UDF for connect with [https://crowdin.com/page/api crowdin.net website API] a couple of function, which allows you to create projects in Crowdin, add and update files, download translations or integrate localization with your development process.

== Android ==
* [http://www.autoitscript.com/forum/index.php?showtopic=160936 Android (by ... )] - Android UDF.

[[Category:UDF]]

Moving and Resizing PopUp GUIs

2015-04-18T11:40:31Z

Melba23:

[[Category:Tutorials]]
=Introduction=

Many Autoit coders would like to use the ''$WS_POPUP'' style for a GUI but do not when they find that they can no longer move or resize the GUI because it has no title bar or borders to grab. Here are four ways to move a ''$WS_POPUP'' GUI with the mouse as well as a way to resize it.

Note: I have garnered these methods from various places on the forum and I am afraid I do not remember all the original authors of the code in this tutorial. If you see your uncredited code here, please add your own credit line.

=Moving a $WS_POPUP GUI=

The four methods have, as you would expect, advantages and diadvantages. Some are easier to use than others - some have side-effects on the GUI, others do not. Try them all and then decide which is best for your particular script. For all examples, the green area shows where dragging is possible and the red area (if there is one) where it is not; clicking the button will bring up a message box; and pressing "''Escape''" always exits the script.

==Method 1: $GUI_WS_EX_PARENTDRAG==

This method uses a label on the GUI to act as a drag anchor. It is easy to set up, but as the label must be active, you can run into overlap problems with other controls - just try clicking on the top half of the button or see what happens when you try to drag the GUI when the button does not fire. If you disable the label, you will see that the button works normally but you can no longer drag the GUI. So although this is the simplest method, it is the least satisfactory - although it can be useful in certain cases.
<syntaxhighlight lang="autoit">
#include <GuiconstantsEx.au3>
#include <WindowsConstants.au3>

HotKeySet("{ESC}", "On_Exit")

$hGUI = GUICreate("X", 100, 100, -1, -1, $WS_POPUP)
GUISetBkColor(0xFF0000, $hGUI)
$hLabel = GUICtrlCreateLabel("", 0, 0, 100, 50, -1, $GUI_WS_EX_PARENTDRAG)
GUICtrlSetBkColor(-1, 0x00FF00)
;GUICtrlSetState(-1, $GUI_DISABLE)
$hButton = GUICtrlCreateButton("Test", 10, 35, 80, 30)
GUISetState()

While 1
Switch GUIGetMsg()
Case $hButton
On_Button()
EndSwitch
WEnd

Func On_Button()
MsgBox(0, "Hi", "Button Pressed")
EndFunc ;==>On_Button

Func On_Exit()
Exit
EndFunc ;==>On_Exit
</syntaxhighlight>

==Method 2: Sending the $SC_DRAGMOVE message==

Here we send a message when the primary mouse button is pressed to tell Windows to drag the GUI with the mouse. Note that the button works without problem.
<syntaxhighlight lang="autoit">
; Original code - martin
#include <GuiconstantsEx.au3>
#include <WindowsConstants.au3>
#include <SendMessage.au3>

Global Const $SC_DRAGMOVE = 0xF012

HotKeySet("{ESC}", "On_Exit")

$hGUI = GUICreate("X", 100, 100, -1, -1, $WS_POPUP)
GUISetBkColor(0x00FF00, $hGUI)
$hButton = GUICtrlCreateButton("Test", 10, 35, 80, 30)
GUISetState()

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_PRIMARYDOWN
_SendMessage($hGUI, $WM_SYSCOMMAND, $SC_DRAGMOVE, 0)
Case $hButton
On_Button()
EndSwitch
WEnd

Func On_Button()
MsgBox(0, "Hi", "Button Pressed")
EndFunc ;==>On_Button

Func On_Exit()
Exit
EndFunc ;==>On_Exit
</syntaxhighlight>

==Method 3: Sending the ''$WM_NCLBUTTONDOWN'' message==

In this example, we also detect when the primary mouse button is down. We then fool Windows into believing that the cursor is not in the client area of the GUI but is actually in the title bar - Windows reacts as we hoped by dragging the GUI. Again the button works without problem as Windows realises it is a control.
<syntaxhighlight lang="autoit">
#include <GuiconstantsEx.au3>
#include <WindowsConstants.au3>
#include <SendMessage.au3>

HotKeySet("{ESC}", "On_Exit")

$hGUI = GUICreate("X", 100, 100, -1, -1, $WS_POPUP)
GUISetBkColor(0x00FF00, $hGUI)
$hButton = GUICtrlCreateButton("Test", 10, 35, 80, 30)
GUISetState()

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_PRIMARYDOWN
On_Drag()
Case $hButton
On_Button()
EndSwitch
WEnd

Func On_Drag()
Local $aCurInfo = GUIGetCursorInfo($hGUI)
If $aCurInfo[4] = 0 Then ; Mouse not over a control
DllCall("user32.dll", "int", "ReleaseCapture")
_SendMessage($hGUI, $WM_NCLBUTTONDOWN, $HTCAPTION, 0)
EndIf
EndFunc ;==>On_Drag

Func On_Exit()
Exit
EndFunc ;==>On_Exit

Func On_Button()
MsgBox(0, "Hi", "Button Pressed")
EndFunc ;==>On_Button
</syntaxhighlight>
''Note'': The remainder of this tutorial assumes knowledge of the ''GUIRegisterMsg'' command. If you are not clear on the use of this command, please read the [[Tutorial GUIRegisterMsg|GUIRegisterMsg]] tutorial before continuing.

==Method 4: Handling the $WM_NCHITTEST message==

This final method intercepts the ''$WM_NCHITTEST'' message, which basically tells Windows what part of the GUI is under the mouse when a button is pressed. If the mouse is over the title bar, then Windows will drag the GUI. In this script we tell Windows that the top half of the GUI is a title bar and so would Windows please drag as normal. The coloured label is just there to differentiate between the 2 areas and has been disabled so as not to interfere with the button - which works normally as Windows realises it is a control and not part of the GUI.
<syntaxhighlight lang="autoit">
#include <GuiconstantsEx.au3>
#include <WindowsConstants.au3>
#include <SendMessage.au3>

HotKeySet("{ESC}", "On_Exit")

$hGUI = GUICreate("X", 100, 100, -1, -1, $WS_POPUP)
GUISetBkColor(0x00FF00, $hGUI)
GUICtrlCreateLabel("", 0, 50, 100, 50)
GUICtrlSetBkColor(-1, 0xFF0000)
GUICtrlSetState(-1, $GUI_DISABLE)
$hButton = GUICtrlCreateButton("Test", 10, 35, 80, 30)
GUISetState()

GUIRegisterMsg($WM_NCHITTEST, "_MY_NCHITTEST")

While 1
Switch GUIGetMsg()
Case $hButton
On_Button()
EndSwitch
WEnd

; Original code - Prog@ndy
Func _MY_NCHITTEST($hWnd, $uMsg, $wParam, $lParam)
Switch $hWnd
Case $hGUI
Local $aPos = WinGetPos($hWnd) ; Check if mouse is over top 50 pixels
If Abs(BitAND(BitShift($lParam, 16), 0xFFFF) - $aPos[1]) < 50 Then Return $HTCAPTION
EndSwitch
Return $GUI_RUNDEFMSG
EndFunc ;==>_MY_NCHITTEST

Func On_Button()
MsgBox(0, "Hi", "Button Pressed")
EndFunc ;==>On_Button

Func On_Exit()
Exit
EndFunc ;==>On_Exit
</syntaxhighlight>

=Resizing a $WS_POPUP GUI=

To resize a GUI without borders, we have to fool Windows into thinking that the borders actually exist. We do this by telling Windows to change the cursor to the "''resize''" type if the mouse is placed over the margin of the GUI. Then when primary mouse button is pressed, we check if the cursor has been changed and, if it has, tell Windows to resize the GUI.

The various message handlers interact as follows:

When we receive a ''$WM_MOUSEMOVE'' message, we check if the mouse is over a border by calling the ''_Check_Border'' function, which returns a code to indicate which cursor type is required, and then using that return to set the correct cursor type within the '' _SetCursor'' function.

Then if a ''$WM_LBUTTONDOWN'' message is received we again check the ''_Check_Border'' function and, if we are over a border, tell Windows to resize the GUI as the mouse is dragged.
<syntaxhighlight lang="autoit">
; Original code - martin
#include <GuiConstantsEx.au3>
#include <Windowsconstants.au3>
#include <SendMessage.au3>

HotKeySet("{ESC}", "On_Exit")

; Set distance from edge of window where resizing is possible
Global Const $iMargin = 4

; Create GUI
$hGUI = GUICreate("Y", 100, 100, -1, -1, $WS_POPUP)
GUISetBkColor(0xFF0000)
GUISetState()

; Register message handlers
GUIRegisterMsg($WM_LBUTTONDOWN, "_WM_LBUTTONDOWN") ; For resize
GUIRegisterMsg($WM_MOUSEMOVE, "_SetCursor") ; For cursor type change

While 1
Sleep(10)
WEnd

; Check cursor type and resize/drag window as required
Func _WM_LBUTTONDOWN($hWnd, $iMsg, $wParam, $lParam)
Local $iCursorType = _GetBorder()
If $iCursorType > 0 Then ; Cursor is set to resizing style
$iResizeType = 0xF000 + $iCursorType
_SendMessage($hGUI, $WM_SYSCOMMAND, $iResizeType, 0)
EndIf
EndFunc ;==>WM_LBUTTONDOWN

; Set cursor to correct resizing form if mouse is over a border
Func _SetCursor()
Local $iCursorID
Switch _GetBorder()
Case 0
$iCursorID = 2
Case 1, 2
$iCursorID = 13
Case 3, 6
$iCursorID = 11
Case 5, 7
$iCursorID = 10
Case 4, 8
$iCursorID = 12
EndSwitch
GUISetCursor($iCursorID, 1)
EndFunc ;==>SetCursor

; Determines if mouse cursor over a border
Func _GetBorder()
Local $aCurInfo = GUIGetCursorInfo()
Local $aWinPos = WinGetPos($hGUI)
Local $iSide = 0
Local $iTopBot = 0
If $aCurInfo[0] < $iMargin Then $iSide = 1
If $aCurInfo[0] > $aWinPos[2] - $iMargin Then $iSide = 2
If $aCurInfo[1] < $iMargin Then $iTopBot = 3
If $aCurInfo[1] > $aWinPos[3] - $iMargin Then $iTopBot = 6
Return $iSide + $iTopBot
EndFunc ;==>_GetBorder

Func On_Exit()
Exit
EndFunc
</syntaxhighlight>

=Moving and resizing a $WS_POPUP GUI=

Of the three serious methods for dragging a ''$WS_POPUP'' GUI, only two can be combined with the resize code. The ''$WM_NCHITTEST'' message version is unsuitable as it prevents the detection of the simulated borders. The other 2 methods both use the ''$GUI_EVENT_PRIMARYDOWN'' message within the ''GUIGetMsg'' loop to detect the primary mouse button being pressed, but we could also use the ''$WM_LBUTTONDOWN'' message we use when resizing the GUI to do the same thing. All we need to do is to check the cursor position and so the required cursor type: if it is greater than 0 we have a resize cursor - if it is 0 then we have a normal cursor and should drag the whole GUI.

As an ''added bonus'' because you have been kind enough to read until there, the following examples also show how to set the maximum and minimum size of a resizable GUI via the ''$WM_GETMINMAXINFO'' message. We simply make sure we set our own limits every time Windows checks to see when it should stop resizing.

So here are the 2 scripts - first using the ''$SC_DRAGMOVE'' message
<syntaxhighlight lang="autoit">
#include <GuiConstantsEx.au3>
#include <Windowsconstants.au3>
#include <SendMessage.au3>

Global Const $SC_DRAGMOVE = 0xF012

HotKeySet("{ESC}", "On_Exit")

; Set distance from edge of window where resizing is possible
Global Const $iMargin = 4
; Set max and min GUI sizes
Global Const $iGUIMinX = 50, $iGUIMinY = 50, $iGUIMaxX = 300, $iGUIMaxY = 300

; Create GUI
$hGUI = GUICreate("Y", 100, 100, -1, -1, $WS_POPUP)
GUISetBkColor(0x00FF00)
GUISetState()

; Register message handlers
GUIRegisterMsg($WM_MOUSEMOVE, "_SetCursor") ; For cursor type change
GUIRegisterMsg($WM_LBUTTONDOWN, "_WM_LBUTTONDOWN") ; For resize/drag
GUIRegisterMsg($WM_GETMINMAXINFO, "_WM_GETMINMAXINFO") ; For GUI size limits

While 1
Sleep(10)
WEnd

; Set cursor to correct resizing form if mouse is over a border
Func _SetCursor()
Local $iCursorID
Switch _Check_Border()
Case 0
$iCursorID = 2
Case 1, 2
$iCursorID = 13
Case 3, 6
$iCursorID = 11
Case 5, 7
$iCursorID = 10
Case 4, 8
$iCursorID = 12
EndSwitch
GUISetCursor($iCursorID, 1)
EndFunc ;==>SetCursor

; Check cursor type and resize/drag window as required
Func _WM_LBUTTONDOWN($hWnd, $iMsg, $wParam, $lParam)
Local $iCursorType = _Check_Border()
If $iCursorType > 0 Then ; Cursor is set to resizing style so send appropriate resize message
$iResizeType = 0xF000 + $iCursorType
_SendMessage($hGUI, $WM_SYSCOMMAND, $iResizeType, 0)
Else
Local $aCurInfo = GUIGetCursorInfo($hGUI)
If $aCurInfo[4] = 0 Then ; Mouse not over a control
_SendMessage($hGUI, $WM_SYSCOMMAND, $SC_DRAGMOVE, 0)
EndIf
EndIf
EndFunc ;==>WM_LBUTTONDOWN

; Determines if mouse cursor over a border
Func _Check_Border()
Local $aCurInfo = GUIGetCursorInfo()
If @error Then Return -1
Local $aWinPos = WinGetPos($hGUI)
Local $iSide = 0
Local $iTopBot = 0
If $aCurInfo[0] < $iMargin Then $iSide = 1
If $aCurInfo[0] > $aWinPos[2] - $iMargin Then $iSide = 2
If $aCurInfo[1] < $iMargin Then $iTopBot = 3
If $aCurInfo[1] > $aWinPos[3] - $iMargin Then $iTopBot = 6
Return $iSide + $iTopBot
EndFunc ;==>_Check_Border

; Set min and max GUI sizes
Func _WM_GETMINMAXINFO($hWnd, $iMsg, $wParam, $lParam)
$tMinMaxInfo = DllStructCreate("int;int;int;int;int;int;int;int;int;int", $lParam)
DllStructSetData($tMinMaxInfo, 7, $iGUIMinX)
DllStructSetData($tMinMaxInfo, 8, $iGUIMinY)
DllStructSetData($tMinMaxInfo, 9, $iGUIMaxX)
DllStructSetData($tMinMaxInfo, 10, $iGUIMaxY)
Return 0
EndFunc ;==>_WM_GETMINMAXINFO

Func On_Exit()
Exit
EndFunc
</syntaxhighlight>
And now using the ''$WM_NCLBUTTONDOWN'' message
<syntaxhighlight lang="autoit">
#include <GuiConstantsEx.au3>
#include <Windowsconstants.au3>
#include <SendMessage.au3>

HotKeySet("{ESC}", "On_Exit")

; Set distance from edge of window where resizing is possible
Global Const $iMargin = 4
; Set max and min GUI sizes
Global Const $iGUIMinX = 50, $iGUIMinY = 50, $iGUIMaxX = 300, $iGUIMaxY = 300

; Create GUI
$hGUI = GUICreate("Y", 100, 100, -1, -1, $WS_POPUP)
GUISetBkColor(0x00FF00)
GUISetState()

; Register message handlers
GUIRegisterMsg($WM_LBUTTONDOWN, "_WM_LBUTTONDOWN") ; For resize/drag
GUIRegisterMsg($WM_MOUSEMOVE, "_SetCursor") ; For cursor type change
GUIRegisterMsg($WM_GETMINMAXINFO, "_WM_GETMINMAXINFO") ; For GUI size limits

While 1
Sleep(10)
WEnd

; Check cursor type and resize/drag window as required
Func _WM_LBUTTONDOWN($hWnd, $iMsg, $wParam, $lParam)
Local $iCursorType = _GetBorder()
If $iCursorType > 0 Then ; Cursor is set to resizing style
$iResizeType = 0xF000 + $iCursorType
_SendMessage($hGUI, $WM_SYSCOMMAND, $iResizeType, 0)
Else
Local $aCurInfo = GUIGetCursorInfo($hGUI)
If $aCurInfo[4] = 0 Then ; Mouse not over a control
DllCall("user32.dll", "int", "ReleaseCapture")
_SendMessage($hGUI, $WM_NCLBUTTONDOWN, $HTCAPTION, 0)
EndIf
EndIf
EndFunc ;==>WM_LBUTTONDOWN

; Set cursor to correct resizing form if mouse is over a border
Func _SetCursor()
Local $iCursorID
Switch _GetBorder()
Case 0
$iCursorID = 2
Case 1, 2
$iCursorID = 13
Case 3, 6
$iCursorID = 11
Case 5, 7
$iCursorID = 10
Case 4, 8
$iCursorID = 12
EndSwitch
GUISetCursor($iCursorID, 1)
EndFunc ;==>SetCursor

; Determines if mouse cursor over a border
Func _GetBorder()
Local $aCurInfo = GUIGetCursorInfo()
If @error Then Return -1
Local $aWinPos = WinGetPos($hGUI)
Local $iSide = 0
Local $iTopBot = 0
If $aCurInfo[0] < $iMargin Then $iSide = 1
If $aCurInfo[0] > $aWinPos[2] - $iMargin Then $iSide = 2
If $aCurInfo[1] < $iMargin Then $iTopBot = 3
If $aCurInfo[1] > $aWinPos[3] - $iMargin Then $iTopBot = 6
Return $iSide + $iTopBot
EndFunc ;==>_GetBorder

; Set min and max GUI sizes
Func _WM_GETMINMAXINFO($hWnd, $iMsg, $wParam, $lParam)
$tMinMaxInfo = DllStructCreate("int;int;int;int;int;int;int;int;int;int", $lParam)
DllStructSetData($tMinMaxInfo, 7, $iGUIMinX)
DllStructSetData($tMinMaxInfo, 8, $iGUIMinY)
DllStructSetData($tMinMaxInfo, 9, $iGUIMaxX)
DllStructSetData($tMinMaxInfo, 10, $iGUIMaxY)
Return 0
EndFunc ;==>_WM_GETMINMAXINFO

Func On_Exit()
Exit
EndFunc
</syntaxhighlight>

=Summary=

Although it seems impossible to move and resize ''$WS_POPUP'' style GUIs because they lack the usual title bar and borders, you can se that it is not that difficult to do it. All we do is mimic what Windows does to a normal GUI.

Adding UDFs to AutoIt and SciTE

2015-02-24T09:59:14Z

Melba23:

[[Category:SciTE]][[Category:UDF]]
The ability to download UDFs created by other users is one of the major advantages of AutoIt, but are you one of the many coders who just add these UDFs to the existing "''Include''" folder which contains the standard UDFS distributed with AutoIt? If so then there is much better way to do it - one which will prevent you from losing all of these additional UDFs when you upgrade. Just use a user-defined folder to store all your UDFs - AutoIt makes this very easy to do.

=Creating a Personal Include Folder=

Begin by creating a new folder to hold the additional UDFs - it is recommended that you do '''NOT''' put this folder in the AutoIt install folder (or it will get overwritten when you upgrade). Then tell AutoIt about this folder.

- If you have ''SciTE4AutoIt3'' you can use '''SciTEConfig''' - look for the ''User Include Dir'' input about 2/3 way down the dialog.

- If not (and why not? You can download it from here[http://www.autoitscript.com/site/autoit-script-editor/downloads/]) you need to modify the registry directly as explained on the "''Include''" page of the Help file:
<syntaxhighlight lang="autoit">
There is a special registry value that can be created at "HKEY_CURRENT_USER\Software\AutoIt v3\AutoIt" called "Include".
It should be a REG_SZ (string) value.
</syntaxhighlight>
'''CYA Note''': Normal precautions are advised if modifying the registry.

You now have a folder to store modified, downloaded or personal UDFs which are available to use with no need to specify the path and which will not be
lost on upgrade.

=Adding CallTips and AutoComplete=

But to make coding with these UDFs even easier you can also add '''CallTips''' and '''AutoComplete''' for them.

As you might expect, the full ''SciTE4AutoIt3'' package makes it easy - have you downloaded and installed it yet? If you have then just open '''SciTEConfig''' on the '''Other Tools''' tab and press '''Run User Call Tip Manager'''. Then you just need to select the UDF file to add and everything is done for you automatically. Full instructions on using the ''User Call Tip Manager'' are found in the ''SciTE4AutoIt3'' Help file under ''<Extra Utilities>''.

But if you want to do it manually (which is '''not''' recommended):

'''Calltips''' first. These are stored in ''<Your_User_Profile>\au3.user.calltips.api''. If you are doing this for the first time then this file will not exist and you will have to create it. Then add a line like this to the file for each function you wish to have a calltip:
<syntaxhighlight lang="autoit">
_Function($param1, $param2, $param3) Explanation of function (Requires: #Include UDF.au3)
</syntaxhighlight>
Of course you need to change the ''Function, $param'' and ''UDF'' words to the correct values for the UDF function you want to include.

Now '''AutoComplete'''. Again a special file is used ''<Your_User_Profile>\au3.userudfs.properties'' - again you will have to create it initially - which should read as follows:
<syntaxhighlight lang="autoit">
au3.keywords.user.udfs=_function1 _function2 _function3 _function4 \
_function5 _function6 _function7
</syntaxhighlight>
Note that the entries are all in lowercase and all lines other than the first begin with a ''@TAB'' character.

Then save all files, close and restart SciTE. You will have '''AutoComplete''' when you start typing the UDF function name in a script and a syntax '''CallTip''' as you enter the parameters. These files are not overwritten when you update SciTE so all your hard work to set this up should be a once-only event.

One final thing. If you want the "''Tools - Open Include''" menu item in SciTE to work on the files within this new folder you need to add the following lines to your "''SciTEUser.properties''" file - you open it by using the <''Options - Open User Options File''> menu item:
<syntaxhighlight lang="autoit">
openpath.$(au3)=$(autoit3dir)\include;Your_Folder_Path
openpath.beta.$(au3)=$(autoit3dir)\beta\include;Your_Folder_Path
</syntaxhighlight>
Now you are all set - your personal include files are as accessible as the standard set.

Variables - using Global, Local, Static and ByRef

2013-11-05T08:38:03Z

Melba23:

[[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 <Constants.au3> ; only required for MsgBox constants

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

; Read the variables
MsgBox($MB_ICONINFORMATION + $MB_TOPMOST, "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_ICONINFORMATION + $MB_TOPMOST, "Reading", "Back In The Main Script" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 2 = " & $Var_2)

Func _Function()
; Read the variables
MsgBox($MB_ICONINFORMATION + $MB_TOPMOST, "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
</syntaxhighlight>
Here is a simple example showing how ''Local'' variables are only visible ''inside'' their own function:
<syntaxhighlight lang="autoit">
#include <Constants.au3> ; only required for MsgBox constants

Global $Var_1 = "Variable 1"

; Read the variable
MsgBox($MB_ICONINFORMATION + $MB_TOPMOST, "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_ICONINFORMATION + $MB_TOPMOST, "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_ICONINFORMATION + $MB_TOPMOST, "Reading", "In The Function" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 3 = " & $Var_3)
EndFunc
</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 <Constants.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_ICONINFORMATION + $MB_TOPMOST, "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_ICONINFORMATION + $MB_TOPMOST, "Reading", "In Function One" & @CRLF & @CRLF & "Variable = " & $sString)

EndFunc

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_ICONINFORMATION + $MB_TOPMOST, "Reading", "In Function Two" & @CRLF & @CRLF & "Variable = " & $sString)

EndFunc
</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 <Constants.au3> ; only required for MsgBox constants

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

; Read it
MsgBox($MB_ICONINFORMATION + $MB_TOPMOST, "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_ICONINFORMATION + $MB_TOPMOST, "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_ICONINFORMATION + $MB_TOPMOST, "Reading", "In Function One" & @CRLF & @CRLF & "Variable = " & $sString)

EndFunc
</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 $fFoo_First_Pass = True

; Check the flag
If $fFoo_First_Pass Then
; Immediately clear the flag to prevent running on subsequent passes
$fFoo_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

Func _Function_2()
; Use the same variable name
Local Static $vVar = 0
$vVar += 100
ConsoleWrite("In Function_2: " & $vVar & @CRLF)
EndFunc
</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 <Constants.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_ICONINFORMATION + $MB_TOPMOST, "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_ICONINFORMATION + $MB_TOPMOST, "Read", "Second read in Func A:" & @CRLF & "Var A1 = " & $iVar_A1 & @CRLF & "Var A2 = " & $iVar_A2)

EndFunc

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_ICONINFORMATION + $MB_TOPMOST, "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_ICONINFORMATION + $MB_TOPMOST, "Read", "Second read in Func B:" & @CRLF & "Var B1 = " & $iVar_B1 & @CRLF & "Var B2 = " & $iVar_B2)

; Now return to the other function

EndFunc
</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 <Constants.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_ICONINFORMATION + $MB_TOPMOST, "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_ICONINFORMATION + $MB_TOPMOST, "Read", "Second read in Func A:" & @CRLF & "Var A1 = " & $iVar_A1 & @CRLF & "Var A2 = " & $iVar_A2)

EndFunc

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_ICONINFORMATION + $MB_TOPMOST, "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_ICONINFORMATION + $MB_TOPMOST, "Read", "Second read in Func B:" & @CRLF & "Var B1 = " & $iVar_B1 & @CRLF & "Var B2 = " & $iVar_B2)

; Now return to the other function

EndFunc
</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">
Global $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
</syntaxhighlight>

''ByRef'' is a very powerful tool - 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

2013-11-04T18:07:28Z

Melba23:

[[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">
Global $Var_1 = "Variable 1"
Global $Var_2 = "Variable 2"

; Read the variables
MsgBox(0x40040, "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(0x40040, "Reading", "Back In The Main Script" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 2 = " & $Var_2)

Func _Function()
; Read the variables
MsgBox(0x40040, "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
</syntaxhighlight>
Here is a simple example showing how ''Local'' variables are only visible ''inside'' their own function:
<syntaxhighlight lang="autoit">
Global $Var_1 = "Variable 1"

; Read the variable
MsgBox(0x40040, "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(0x40040, "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(0x40040, "Reading", "In The Function" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 3 = " & $Var_3)
EndFunc
</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">
Function_1()

Func Function_1()

; Declare the variable in this function
Local $sString = "Variable in Function One"
; Read the value
MsgBox(0x40040, "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(0x40040, "Reading", "In Function One" & @CRLF & @CRLF & "Variable = " & $sString)

EndFunc

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(0x40040, "Reading", "In Function Two" & @CRLF & @CRLF & "Variable = " & $sString)

EndFunc
</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">
; Declare the variable as Global
Global $sString = "Global Variable in the Main Script"

; Read it
MsgBox(0x40040, "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(0x40040, "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(0x40040, "Reading", "In Function One" & @CRLF & @CRLF & "Variable = " & $sString)

EndFunc
</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">
Func Foo()
; Set the value only on the first entry into the function
Local Static $iFooCount = -1
; Increase the value each time we enter the function
$iFooCount += 1
; Now look at value in the variable
If $iFooCount Then
; Not the first pass because value > 0
Else
; First pass because value = 0
EndIf
EndFunc
</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

Func _Function_2()
; Use the same variable name
Local Static $vVar = 0
$vVar += 100
ConsoleWrite("In Function_2: " & $vVar & @CRLF)
EndFunc
</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">
Func_A()

Func Func_A()

; Declare variables
Local $iVar_A1 = 10
Local $iVar_A2 = 20
; And read them
MsgBox(0x40040, "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(0x40040, "Read", "Second read in Func A:" & @CRLF & "Var A1 = " & $iVar_A1 & @CRLF & "Var A2 = " & $iVar_A2)

EndFunc

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(0x40040, "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(0x40040, "Read", "Second read in Func B:" & @CRLF & "Var B1 = " & $iVar_B1 & @CRLF & "Var B2 = " & $iVar_B2)

; Now return to the other function

EndFunc
</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">
Func_A()

Func Func_A()

; Declare variables
Local $iVar_A1 = 10
Local $iVar_A2 = 20

; And read them
MsgBox(0x40040, "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(0x40040, "Read", "Second read in Func A:" & @CRLF & "Var A1 = " & $iVar_A1 & @CRLF & "Var A2 = " & $iVar_A2)

EndFunc

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(0x40040, "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(0x40040, "Read", "Second read in Func B:" & @CRLF & "Var B1 = " & $iVar_B1 & @CRLF & "Var B2 = " & $iVar_B2)

; Now return to the other function

EndFunc
</syntaxhighlight>

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

Adding UDFs to AutoIt and SciTE

2013-09-07T14:35:18Z

Melba23:

[[Category:SciTE]][[Category:UDF]]
The ability to download UDFs created by other users is one of the major advantages of AutoIt, but are you one of the many coders who just add these UDFs to the existing "''Include''" folder which contains the standard UDFS distributed with AutoIt? If so then there is much better way to do it - one which will prevent you from losing all of these additional UDFs when you upgrade. Just use a user-defined folder to store all your UDFs - AutoIt makes this very easy to do.

Begin by creating a new folder to hold the additional UDFs - it is recommended that you do '''NOT''' put this folder in the AutoIt install folder (or it will get overwritten when you upgrade). Then tell AutoIt about this folder.

- If you have ''SciTE4AutoIt3'' you can use '''SciTEConfig''' - look for the ''User Include Dir'' input about 2/3 way down the dialog.

- If not (and why not? You can download it from here[http://www.autoitscript.com/site/autoit-script-editor/downloads/]) you need to modify the registry directly as explained on the "''Include''" page of the Help file:
<syntaxhighlight lang="autoit">
There is a special registry value that can be created at "HKEY_CURRENT_USER\Software\AutoIt v3\AutoIt" called "Include".
It should be a REG_SZ (string) value.
</syntaxhighlight>
'''CYA Note''': Normal precautions are advised if modifying the registry.

You now have a folder to store modified, downloaded or personal UDFs which are available to use with no need to specify the path and which will not be lost on upgrade. But to make coding with these UDFs even easier you can also add '''CallTips''' and '''AutoComplete''' for them.

As you might expect, the full ''SciTE4AutoIt3'' package makes it easy - have you downloaded and installed it yet? If you have then just open '''SciTEConfig''' on the '''Other Tools''' tab and press '''Run User Call Tip Manager'''. Then you just need to select the UDF file to add and everything is done for you automatically.

But if you want to do it manually (which is '''not''' recommended):

'''Calltips''' first. These are stored in ''<Your_User_Profile>\au3.user.calltips.api''. If you are doing this for the first time then this file will not exist and you will have to create it. Then add a line like this to the file for each function you wish to have a calltip:
<syntaxhighlight lang="autoit">
_Function($param1, $param2, $param3) Explanation of function (Requires: #Include UDF.au3)
</syntaxhighlight>
Of course you need to change the ''Function, $param'' and ''UDF'' words to the correct values for the UDF function you want to include.

Now '''AutoComplete'''. Again a special file is used ''<Your_User_Profile>\au3.userudfs.properties'' - again you will have to create it initially - which should read as follows:
<syntaxhighlight lang="autoit">
au3.keywords.user.udfs=_function1 _function2 _function3 _function4 \
_function5 _function6 _function7
</syntaxhighlight>
Note that the entries are all in lowercase and all lines other than the first begin with a ''@TAB'' character.

Then save all files, close and restart SciTE. You will have '''AutoComplete''' when you start typing the UDF function name in a script and a syntax '''CallTip''' as you enter the parameters. These files are not overwritten when you update SciTE so all your hard work to set this up should be a once-only event.

One final thing. If you want the "''Tools - Open Include''" menu item in SciTE to work on the files within this new folder you need to add the following lines to your "''SciTEUser.properties''" file - you open it by using the <''Options - Open User Options File''> menu item:
<syntaxhighlight lang="autoit">
openpath.$(au3)=$(autoit3dir)\include;Your_Folder_Path
openpath.beta.$(au3)=$(autoit3dir)\beta\include;Your_Folder_Path
</syntaxhighlight>
Now you are all set - your personal include files are as accessible as the standard set.

Variables - using Global, Local, Static and ByRef

2013-09-03T16:29:37Z

Melba23: Created page with "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 variable..."

[[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 three possible scopes: ''Global, Local'' and ''Static''.

- A '''Global''' variable is visible throughout your script - any part of teh 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.

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

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/Local/Static'' to explicitly set the scope you require. 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">
Global $Var_1 = "Variable 1"
Global $Var_2 = "Variable 2"

; Read the variables
MsgBox(0x40040, "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(0x40040, "Reading", "Back In The Main Script" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 2 = " & $Var_2)

Func _Function()
; Read the variables
MsgBox(0x40040, "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
</syntaxhighlight>
Here is a simple example showing how ''Local'' variables are only visible ''inside'' their own function:
<syntaxhighlight lang="autoit">
Global $Var_1 = "Variable 1"

; Read the variable
MsgBox(0x40040, "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(0x40040, "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(0x40040, "Reading", "In The Function" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 3 = " & $Var_3)
EndFunc
</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">
Function_1()

Func Function_1()

; Declare the variable in this function
Local $sString = "Variable in Function One"
; Read the value
MsgBox(0x40040, "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(0x40040, "Reading", "In Function One" & @CRLF & @CRLF & "Variable = " & $sString)

EndFunc

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(0x40040, "Reading", "In Function Two" & @CRLF & @CRLF & "Variable = " & $sString)

EndFunc
</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">
; Declare the variable as Global
Global $sString = "Global Variable in the Main Script"

; Read it
MsgBox(0x40040, "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(0x40040, "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(0x40040, "Reading", "In Function One" & @CRLF & @CRLF & "Variable = " & $sString)

EndFunc
</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">
Func Foo()
; Set the value only on the first entry into the function
Static $iFooCount = -1
; Increase the value each time we enter the function
$iFooCount += 1
; Now look at value in the variable
If $iFooCount Then
; Not the first pass because value > 0
Else
; First pass because value = 0
EndIf
EndFunc
</syntaxhighlight>
As with ''Local'' variables, 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
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

Func _Function_2()
; Use the same variable name
Static $vVar = 0
$vVar += 100
ConsoleWrite("In Function_2: " & $vVar & @CRLF)
EndFunc
</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 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">
Func_A()

Func Func_A()

; Declare variables
Local $iVar_A1 = 10
Local $iVar_A2 = 20
; And read them
MsgBox(0x40040, "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(0x40040, "Read", "Second read in Func A:" & @CRLF & "Var A1 = " & $iVar_A1 & @CRLF & "Var A2 = " & $iVar_A2)

EndFunc

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(0x40040, "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(0x40040, "Read", "Second read in Func B:" & @CRLF & "Var B1 = " & $iVar_B1 & @CRLF & "Var B2 = " & $iVar_B2)

; Now return to the other function

EndFunc
</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">
Func_A()

Func Func_A()

; Declare variables
Local $iVar_A1 = 10
Local $iVar_A2 = 20

; And read them
MsgBox(0x40040, "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(0x40040, "Read", "Second read in Func A:" & @CRLF & "Var A1 = " & $iVar_A1 & @CRLF & "Var A2 = " & $iVar_A2)

EndFunc

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(0x40040, "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(0x40040, "Read", "Second read in Func B:" & @CRLF & "Var B1 = " & $iVar_B1 & @CRLF & "Var B2 = " & $iVar_B2)

; Now return to the other function

EndFunc
</syntaxhighlight>

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

Tutorials

2013-09-03T16:22:55Z

Melba23:

[[Category:Tutorials]]
There are many tutorials available for AutoIt. This page is an overview of a few known tutorials. More tutorials can possibly be found and will be added to this page in time.

= AutoIt beginner =
These tutorials describe simple tasks and AutoIt syntax.

* [[Tutorial_Core_Language|Language tutorial]] ''( cheat sheet )''
* [http://www.autoitscript.com/forum/index.php?showtopic=21048 Welcome to AutoIt 1-2-3]
* [http://www.autoitscript.com/forum/index.php?showtopic=84960 Learning to script with AutoIt v3]

==Autoit-1-2-3==

By Valuater, this tutorial is one of the most popular. Some key features are:
* Over 19 Interactive GUI's
* Over 50 Step-by-Step Scripts
* Verbal Instructions
* Complete with Demonstrations and Answers
* Exe Format for New People

This is the second page you will see when running AutoIt 1-2-3. It gives important links to necessary downloads and allows you to run demos that are supplied with the program.
[[image:Autoit-1-2-3.jpg|center]]

You can download AutoIt 1-2-3 from [http://www.autoitscript.com/forum/index.php?act=attach&type=post&id=10824 here], or check out the [http://www.autoitscript.com/forum/index.php?showtopic=21048&hl=tutorials Forum page].

==Learning to script with AutoIt V3==

This tutorial has example AU3 files contained in the text, printable exercise question/answer sheet and more. Originally by lxP and updated by BrettF, this is a great starting point for those who have never scripted before. For people who may have done other languages, this will also be a good back to basics tutorial.

[http://www.autoitscript.com/forum/index.php?showtopic=84960 Download now].

= Video =
These are almost 20 AutoIt video tutorials by 403forbidden. You can view all the tutorials at the link below. They start at a beginner level and work up from there.
* [http://www.youtube.com/watch?v=BLU60CD-Poo AutoIt Video Tutorials - Part 1]

Set of tutorials by [http://www.autoitscript.com/forum/user/64654-morthawt/ Morthawt]
* [http://www.youtube.com/playlist?list=PLNpExbvcyUkOJvgxtCPcKsuMTk9XwoWum&feature=view_all Easy Autoit Scripting Video Tutorials]

= More complicated AutoIt commands and concepts =
*[[Arrays]]
*[[Tutorial GUIRegisterMsg|GUIRegisterMsg]]
*[[Interrupting a running function]]
*[[Variables - using Global, Local, Static and ByRef]]
*[[Managing Multiple GUIs|Managing multiple GUIs]]
*[[Setting Styles|Setting styles]]
*[[Moving and Resizing PopUp GUIs|Moving and resizing pop up GUIs]]
*[[Modal MsgBox Styles|Modal MsgBox styles]]
*[[Tabs]]
*[[Recursion]]

= Tips to make your coding easier =
*[[Adding UDFs to AutoIt and SciTE]]
*[[Adding utilities to the SciTE Tools menu]]
*[http://www.autoitscript.com/forum/topic/131833-scite-jump-navigate-between-functions-and-regions-in-an-autoit-script/ Use tools like SciTE Jump]

= Books =
[http://www.oreilly.com/catalog/9780596515126/ AutoIt v3: Your Quick Guide (Andy Flesner, O'Reilly)]

This guide teaches you the foundations of the AutoIt v3 language. You will learn about variables and includes, graphical user interfaces, user-defined functions, and conditional and loop statements. You will then apply what you have learned in examples related to the system administration field.

Tabs

2013-05-27T10:26:24Z

Melba23:

=Tabs And How To Deal With Them=

Tabs are a valuable tool when you need to fit a lot of controls into a small GUI. But inexperienced users often have problems with them - particularly in making sure that controls only appear on the correct tab. This tutorial should help. Before going further, it is important to understand the differences between controls created using the built-in AutoIt commands (''GUICtrlCreate*'') and those created with the UDFs. The built-in commands produce controls which are managed internally by AutoIt - they return '''ControlID'''s. The UDF commands create controls that are not in Autoit's internal management structure and need to be managed by the code - they normally return '''handles''' (the special unique identifier for all Windows components).

=Tabs Created With Native AutoIt Functions=

Any tabs created by the built-in AutoIt commands ''GUICtrlCreateTab/TabItem'' will automatically take care of displaying any built-in controls created at the same time within the tab creation structure. Here is an example:
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

$hGUI = GUICreate("Built-In Tab Example", 500, 500)

$hTab = GUICtrlCreateTab(10, 10, 480, 480)
; Create tabitems
For $i = 0 To 2
GUICtrlCreateTabItem("Tab " & $i)
GUICtrlCreateButton("Button " & $i, 20 + ($i * 100), 40 + ($i * 50), 80, 30)
Next
; Close Tab definiton
GUICtrlCreateTabItem("")

GUISetState()

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
EndSwitch
WEnd
</syntaxhighlight>
As you can see, the controls for each tab are created just after the TabItem on which they are to appear and before the next TabItem. Do not forget to close the Tab definition - many tab problems are caused by omitting this vital line.

What happens if we add some UDF created controls to these tabs?
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#Include <GuiButton.au3>

$hGUI = GUICreate("Built-In Tab Example", 500, 500)

$hTab = GUICtrlCreateTab(10, 10, 480, 480)
; Create tabitems
For $i = 0 To 2
GUICtrlCreateTabItem("Tab " & $i)
GUICtrlCreateButton("Built-In " & $i, 20 + ($i * 100), 40 + ($i * 50), 80, 30)
_GUICtrlButton_Create($hGUI, "UDF " & $i, 20 + ($i * 100), 80 + ($i * 50),80, 30)
Next
; Close Tab definiton
GUICtrlCreateTabItem("")

GUISetState()

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
EndSwitch
WEnd
</syntaxhighlight>
As you can see, the UDF created controls appear on every tab. Remember this is because they are not part of the internal AutoIt control management structure, so AutoIt does not know how to handle them. It is up to you to manage them by seeing which tab is active and hiding/showing these controls as required:
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#Include <GuiButton.au3>

Global $hButtons[3]

$hGUI = GUICreate("Built-In Tab Example", 500, 500)

$hTab = GUICtrlCreateTab(10, 10, 480, 480)
; Create tabitems
For $i = 0 To 2
GUICtrlCreateTabItem("Tab " & $i)
GUICtrlCreateButton("Built-In " & $i, 20 + ($i * 100), 40 + ($i * 50), 80, 30)
; Add a label to the first tab
If $i = 0 Then GUICtrlCreateLabel("See how 'laggy' the UDF buttons are when selecting this tab because of using WinSetState", 20, 200, 150, 60)
Next

GUICtrlCreateTabItem("")

; Create UDF controls
For $i = 0 To 2
$hButtons[$i] = _GUICtrlButton_Create($hGUI, "UDF " & $i, 20 + ($i * 100), 80 + ($i * 50),80, 30)
Next

; Hide the controls so only the one on the first tab is visible
WinSetState($hButtons[1], "", @SW_HIDE)
WinSetState($hButtons[2], "", @SW_HIDE)

GUISetState()

; This is the current active tab
$iLastTab = 0

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
Case $hTab
; Check which Tab is active
$iCurrTab = GUICtrlRead($hTab)
; If the Tab has changed
If $iCurrTab <> $iLastTab Then
; Show/Hide controls as required
Switch $iCurrTab
Case 0
; Note lag when WinSetState is used
WinSetState($hButtons[1], "", @SW_HIDE)
WinSetState($hButtons[2], "", @SW_HIDE)
WinSetState($hButtons[0], "", @SW_SHOW)
Case 1
; No lag when using ControlHide/Show
ControlHide($hGUI, "", $hButtons[0])
ControlHide($hGUI, "", $hButtons[2])
ControlShow($hGUI, "", $hButtons[1])
Case 2
; Nor when using this DLL
DllCall("User32.dll", "bool", "ShowWindowAsync", "hwnd", $hButtons[0], "int", @SW_HIDE)
DllCall("User32.dll", "bool", "ShowWindowAsync", "hwnd", $hButtons[1], "int", @SW_HIDE)
DllCall("User32.dll", "bool", "ShowWindowAsync", "hwnd", $hButtons[2], "int", @SW_SHOW)

EndSwitch
; Store the value for future comparisons
$iLastTab = $iCurrTab
EndIf
EndSwitch
WEnd
</syntaxhighlight>
Note the lag in hiding/showing the UDF created controls if you use ''WinSetState'' - I would recommend using ''ControlShow/Hide'' which gives an instantaneous response. Also how you do not need to create the UDF controls within the tab creation structure - as you have to look after them, there is no requirement to do so.

=Tabs Created With UDFs=

Now let us look at Tabs created with the ''GUITab'' UDF. In this case you need to manage all of the controls on the tabs yourself, even if they are created using the built-in commands:
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#Include <GuiButton.au3>
#include <GuiTab.au3>

Global $hBuiltIn_Buttons[3]
Global $hUDF_Buttons[3]

$hGUI = GUICreate("Built-In Tab Example", 500, 500)

$hTab = _GUICtrlTab_Create($hGUI, 10, 10, 480, 480)
GUISetState()

; Add tabs
_GUICtrlTab_InsertItem($hTab, 0, "Tab 0")
_GUICtrlTab_InsertItem($hTab, 1, "Tab 1")
_GUICtrlTab_InsertItem($hTab, 2, "Tab 2")

; Create the Built-in and UDF buttons
For $i = 0 To 2
$hBuiltIn_Buttons[$i] = GUICtrlCreateButton("Button " & $i, 20 + ($i * 100), 40 + ($i * 50), 80, 30)
$hUDF_Buttons[$i] = _GUICtrlButton_Create($hGUI, "UDF " & $i, 20 + ($i * 100), 80 + ($i * 50),80, 30)
Next

; Hide the controls so only the one on the first tab is visible
GUICtrlSetState($hBuiltIn_Buttons[1], $GUI_HIDE)
GUICtrlSetState($hBuiltIn_Buttons[2], $GUI_HIDE)
ControlHide($hGUI, "", $hUDF_Buttons[1])
ControlHide($hGUI, "", $hUDF_Buttons[2])

GUISetState()

; This is the current active tab
$iLastTab = 0

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
EndSwitch

; Check which Tab is active
$iCurrTab = _GUICtrlTab_GetCurFocus($hTab)
; If the Tab has changed
If $iCurrTab <> $iLastTab Then
; Store the value for future comparisons
$iLastTab = $iCurrTab
; Show/Hide controls as required
Switch $iCurrTab
Case 0
GUICtrlSetState($hBuiltIn_Buttons[1], $GUI_HIDE)
GUICtrlSetState($hBuiltIn_Buttons[2], $GUI_HIDE)
GUICtrlSetState($hBuiltIn_Buttons[0], $GUI_SHOW)
ControlHide($hGUI, "", $hUDF_Buttons[1])
ControlHide($hGUI, "", $hUDF_Buttons[2])
ControlShow($hGUI, "", $hUDF_Buttons[0])
Case 1
GUICtrlSetState($hBuiltIn_Buttons[0], $GUI_HIDE)
GUICtrlSetState($hBuiltIn_Buttons[2], $GUI_HIDE)
GUICtrlSetState($hBuiltIn_Buttons[1], $GUI_SHOW)
ControlHide($hGUI, "", $hUDF_Buttons[0])
ControlHide($hGUI, "", $hUDF_Buttons[2])
ControlShow($hGUI, "", $hUDF_Buttons[1])
Case 2
GUICtrlSetState($hBuiltIn_Buttons[0], $GUI_HIDE)
GUICtrlSetState($hBuiltIn_Buttons[1], $GUI_HIDE)
GUICtrlSetState($hBuiltIn_Buttons[2], $GUI_SHOW)
ControlHide($hGUI, "", $hUDF_Buttons[0])
ControlHide($hGUI, "", $hUDF_Buttons[1])
ControlShow($hGUI, "", $hUDF_Buttons[2])
EndSwitch
EndIf
WEnd
</syntaxhighlight>
A lot of work but a very satisfactory result. Note the need to use different commands to hide/show the built-in and UDF created controls to avoid "lag" on the latter as was shown in the earlier example.

So, a couple of lessons to draw from this:

- 1. When using tabs, try and use built-in commands if at all possible. If you do, AutoIt looks after the showing/hiding problem for you as long as you create the controls ''within'' the tab creation structure. See the next section for how to add controls to tabs after their creation.

- 2. If you must use UDF created controls for any reason, you have to manage hiding/showing all controls yourself.

=Adding Controls To Tabs After Creation=

If you need to add built-in controls to a tab after the tabs have already been created, then you ''must'' use ''GUISwitch'' with the ''tabitemID'' parameter to select the correct tab before you create the control or you will find that it is visible on all tabs.

Here is an example to show how to do it:
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

$hGUI = GUICreate("Test", 500, 500)

$cTab = GUICtrlCreateTab(10, 10, 480, 350)
$cTab_0 = GUICtrlCreateTabItem("Tab 0")
$cTab_1 = GUICtrlCreateTabItem("Tab 1")
GUICtrlCreateTabItem("")

$cButton = GUICtrlCreateButton("Add controls", 10, 450, 80, 30)

GUISetState()

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
Case $cButton
; Correct
GUISwitch($hGUI, $cTab_0)
GUICtrlCreateLabel("Only on Tab 0", 40, 40, 200, 20)
GUICtrlSetBkColor(-1, 0xCCFFCC)
GUICtrlCreateTabItem("")
GUISwitch($hGUI)
; Incorrect
GUICtrlCreateLabel("OnTab 0 AND Tab 1", 40, 100, 200, 20)
GUICtrlSetBkColor(-1, 0xFFCCCC)
EndSwitch
WEnd
</syntaxhighlight>
Do not forget to reclose the tab definition after adding the new controls.

=Multiple Tabs In A GUI=

Unfortunately, only one built-in tab control can be created per GUI - you cannot have several tabs on a single GUI. But there is a way around this - just create child GUIs which can each hold a tab:
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#include <WindowsConstants.au3>

$hGUI = GUICreate("Test", 500, 500)

GUISetState()

; Create child GUIs to hold tabs
$hTab_Win0 = GUICreate("", 400, 200, 50, 20, $WS_POPUP, $WS_EX_MDICHILD, $hGUI)
$hTab_0 = GUICtrlCreateTab(10, 10, 380, 180)
$hTab_00 = GUICtrlCreateTabitem("00")
GUICtrlCreateButton("00", 160, 90, 80, 30)
$hTab_01 = GUICtrlCreateTabitem("01")
GUICtrlCreateButton("01", 160, 90, 80, 30)

GUICtrlCreateTabitem ("")
GUISetState()

$hTab_Win1 = GUICreate("", 400, 200, 50, 250, $WS_POPUP, $WS_EX_MDICHILD, $hGUI)
$hTab_1 = GUICtrlCreateTab(10, 10, 380, 180)
$hTab_10 = GUICtrlCreateTabitem("10")
GUICtrlCreateButton("10", 160, 90, 80, 30)
$hTab_11 = GUICtrlCreateTabitem("11")
GUICtrlCreateButton("11", 160, 90, 80, 30)
GUICtrlCreateTabitem ("")
GUISetState()

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
EndSwitch
WEnd
</syntaxhighlight>
Easy when you know how!

=Summary=

Tabs are useful controls, but can be difficult to master. After this tutorial you should be well on your way!

Interrupting a running function

2013-02-10T11:05:03Z

Melba23:

[[Category:Tutorials]]
This is a common question and this tutorial explains how to do it within the limitations of Autoit.

AutoIt queues function calls in both ''OnEvent'' and ''MessageLoop'' modes. This means that it waits until a function is finished and the code is back in your idle ''While...WEnd'' loop before running the next.

Here are 2 short scripts in both modes to show this in action. Start ''Function 1'' by pressing its button and then immediately try to run ''Function 2'' by pressing its button a couple of times. You will see from the console output that ''Function 2'' will only run '''AFTER''' ''Function 1'' has terminated - and then it will run as many times as you pressed the button.

We start with ''MessageLoop'' mode:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

$hGUI = GUICreate("Test", 500, 500)

$hButton_1 = GUICtrlCreateButton("Func One", 10, 10, 80, 30)
$hButton_2 = GUICtrlCreateButton("Func Two", 10, 50, 80, 30)

GUISetState()

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
Case $hButton_1
_Func_1()
Case $hButton_2
_Func_2()
EndSwitch
WEnd

Func _Func_1()
For $i = 1 To 20
ConsoleWrite("-Func 1 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 1 Ended" & @CRLF)
EndFunc

Func _Func_2()
For $i = 1 To 3
ConsoleWrite("+Func 2 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 2 Ended" & @CRLF)
EndFunc
</syntaxhighlight>
-----------------------------------
And now in ''OnEvent'' mode:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

Opt("GUIOnEventMode", 1)

$hGUI = GUICreate("Test", 500, 500)
GUISetOnEvent($GUI_EVENT_CLOSE, "_Exit")

$hButton_1 = GUICtrlCreateButton("Func One", 10, 10, 80, 30)
GUICtrlSetOnEvent($hButton_1, "_Func_1")
$hButton_2 = GUICtrlCreateButton("Func Two", 10, 50, 80, 30)
GUICtrlSetOnEvent($hButton_2, "_Func_2")

GUISetState()

While 1
Sleep(10)
WEnd

Func _Func_1()
For $i = 1 To 20
ConsoleWrite("-Func 1 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 1 Ended" & @CRLF)
EndFunc

Func _Func_2()
For $i = 1 To 3
ConsoleWrite("+Func 2 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 2 Ended" & @CRLF)
EndFunc

Func _Exit()
Exit
EndFunc
</syntaxhighlight>
-----------------------------------
So is it impossible to interrupt a running function? Of course not or this tutorial would serve no purpose - but there are limitations on the type of function which can be interrupted.

If you are in ''OnEvent'' mode then there is an easy way to interrupt a running function, as long as the function is started within the main code and not by an ''OnEvent'' call. This script shows how to do it by using a flag and checking if it is set - in this way the function is started by the main script and can be interrupted.
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

; Declare a flag
Global $fRunOne = False

Opt("GUIOnEventMode", 1)

$hGUI = GUICreate("Test", 500, 500)
GUISetOnEvent($GUI_EVENT_CLOSE, "_Exit")

$hButton_1 = GUICtrlCreateButton("Func One", 10, 10, 80, 30)
GUICtrlSetOnEvent($hButton_1, "_Func_1")
$hButton_2 = GUICtrlCreateButton("Func Two", 10, 50, 80, 30)
GUICtrlSetOnEvent($hButton_2, "_Func_2")

GUISetState()

While 1
Sleep(10)
; Check if the flag has been set by the OnEvent function
If $fRunOne Then
; Now start the "real" function from within the main code
_Func_1_Run()
EndIf
WEnd

Func _Func_1()
; Set the flag within the OnEvent function
$fRunOne = True
EndFunc ;==>_Func_1

Func _Func_1_Run()
For $i = 1 To 20
ConsoleWrite("-Func 1 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 1 Ended" & @CRLF)
Global $fRunOne = False
EndFunc ;==>_Func_1_Run

Func _Func_2()
For $i = 1 To 3
ConsoleWrite("+Func 2 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 2 Ended" & @CRLF)
EndFunc ;==>_Func_2

Func _Exit()
Exit
EndFunc ;==>_Exit
</syntaxhighlight>
-----------------------------------
However, this method does not work in ''MessageLoop'' mode, nor when you want to interrupt a function which was started by an ''OnEvent'' call in ''OnEvent'' mode. In these cases the function you want to interrupt must have regular checks of a flag which we set when we want to interrupt. If the function does not have a suitable loop where such a check is easy to make, you might not be able to interrupt it.

Let us now look at the 2 ways an AutoIt script can break into a suitable function: a '''HotKey''' and a '''Windows message handler'''. The first is easier to code, but cannot be linked to a control on your GUI; the latter is a little more complicated to code, but can be linked to a control.

How do they work?

Let us start with the ''HotKey''. From the AutoIt Help file: ''A hotkey-press *typically* interrupts the active AutoIt function/statement and runs its user function until it completes or is interrupted''. So a ''HotKey'' press is designed to interrupt your running function - just what we need. But the running function will resume after the ''HotKey'' function terminates - so, as explained above, we use the ''HotKey'' function to set a flag which is looked for by our running function. Remember that this flag must be declared as a ''Global'' variable because it needs to be seen by both functions.

Now many coders do not like using ''HotKey''s because they remain active while a script is running and can interfere with other apps. One way to get around this is to use ''Accelerator'' keys - these look very much like ''HotKey''s to the user, but are only active in the script in which they are declared. Although ''Accelerator'' keys look like ''HotKey''s, they are tied to GUI controls and you must use the ''message handler'' method explained below if you want to use them to interrupt a running function.

The ''Windows message handler'' method is a little more complicated and if you are not used to working with them, you might want to read the [[GUIRegisterMsg]] tutorial first.

What we do here is intercept the message that your GUI control sends when it is activated - the same message that AutoIt queues to run the required code once the running function terminates. We use our own message to get a sneak preview of this queuing and use it to set a similar flag to that described above. If our running function sees the flag, it terminates and AutoIt then runs the function waiting in the queue - simple really!

Here are scripts using both methods to show how ''HotKey''s, ''Accelerator'' keys and GUI controls can interrupt a running function. Just as before, start ''Function_1'' by pressing its button - but now you can interrupt it at will!

First in ''MessageLoop'' mode:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#include <WindowsConstants.au3>

; Set a HotKey
HotKeySet("x", "_Interrupt")

; Declare a flag
$fInterrupt = 0

$hGUI = GUICreate("Test", 500, 500)

$hButton_1 = GUICtrlCreateButton("Func One", 10, 10, 80, 30)
$hButton_2 = GUICtrlCreateButton("Func Two", 10, 50, 80, 30)

; Create a dummy control for the Accelerator to action when pressed
$hAccelInterupt = GUICtrlCreateDummy()
; Set an Accelerator key to action the dummy control
Dim $AccelKeys[1][2]=[ ["z", $hAccelInterupt] ]
GUISetAccelerators($AccelKeys)

GUISetState()

; Intercept Windows command messages with out own handler
GUIRegisterMsg($WM_COMMAND, "_WM_COMMAND")

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
Case $hButton_1
_Func_1()
Case $hButton_2
_Func_2()
EndSwitch
WEnd

Func _Func_1()
; Make sure the flag is cleared
$fInterrupt = 0
For $i = 1 To 20
ConsoleWrite("-Func 1 Running" & @CRLF)
; Look for the flag
If $fInterrupt <> 0 Then
; The flag was set
Switch $fInterrupt
Case 1
ConsoleWrite("!Func 1 interrrupted by Func 2" & @CRLF)
Case 2
ConsoleWrite("!Func 1 interrrupted by HotKey" & @CRLF)
Case 3
ConsoleWrite("!Func 1 interrrupted by Accelerator" & @CRLF)
EndSwitch
Return
EndIf
Sleep(100)
Next
ConsoleWrite(">Func 1 Ended" & @CRLF)
EndFunc

Func _Func_2()
For $i = 1 To 3
ConsoleWrite("+Func 2 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 2 Ended" & @CRLF)
EndFunc

Func _Interrupt()
; The HotKey was pressed so set the flag
$fInterrupt = 2
EndFunc

Func _WM_COMMAND($hWnd, $Msg, $wParam, $lParam)
; The Func 2 button was pressed so set the flag
If BitAND($wParam, 0x0000FFFF) = $hButton_2 Then $fInterrupt = 1
; The dummy control was actioned by the Accelerator key so set the flag
If BitAND($wParam, 0x0000FFFF) = $hAccelInterupt Then $fInterrupt = 3
Return $GUI_RUNDEFMSG
EndFunc ;==>_WM_COMMAND
</syntaxhighlight>
-----------------------------------
And now in ''OnEvent'' mode:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#include <WindowsConstants.au3>

; Set a HotKey
HotKeySet("x", "_Interrupt_HotKey")

; Declare a flag
$fInterrupt = 0

Opt("GUIOnEventMode", 1)

$hGUI = GUICreate("Test", 500, 500)
GUISetOnEvent($GUI_EVENT_CLOSE, "_Exit")

$hButton_1 = GUICtrlCreateButton("Func One", 10, 10, 80, 30)
GUICtrlSetOnEvent($hButton_1, "_Func_1")
$hButton_2 = GUICtrlCreateButton("Func Two", 10, 50, 80, 30)
GUICtrlSetOnEvent($hButton_2, "_Func_2")

; Create a dummy control for the Accelerator to action
$hAccelInterupt = GUICtrlCreateDummy()
GUICtrlSetOnEvent($hAccelInterupt, "_Interrupt_Accel")
; Set an Accelerator key to action the dummy control
Dim $AccelKeys[1][2]=[ ["z", $hAccelInterupt] ]
GUISetAccelerators($AccelKeys)

GUISetState()

; Intercept Windows command messages with out own handler
GUIRegisterMsg($WM_COMMAND, "_WM_COMMAND")

While 1
Sleep(10)
WEnd

Func _Func_1()
; Make sure the flag is cleared
$fInterrupt = 0
For $i = 1 To 20
ConsoleWrite("-Func 1 Running" & @CRLF)
; Look for the flag
If $fInterrupt <> 0 Then
; The flag was set
Switch $fInterrupt
Case 1
ConsoleWrite("!Func 1 interrrupted by Func 2" & @CRLF)
Case 2
ConsoleWrite("!Func 1 interrrupted by HotKey" & @CRLF)
Case 3
ConsoleWrite("!Func 1 interrrupted by Accelerator" & @CRLF)
EndSwitch
Return
EndIf
Sleep(100)
Next
ConsoleWrite(">Func 1 Ended" & @CRLF)
EndFunc

Func _Func_2()
For $i = 1 To 3
ConsoleWrite("+Func 2 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 2 Ended" & @CRLF)
EndFunc

Func _Exit()
Exit
EndFunc

Func _Interrupt_HotKey()
; The HotKey was pressed so set the flag
$fInterrupt = 2
EndFunc

Func _Interrupt_Accel()
; This is an empty function for the dummy control linked to the Accelerator key
EndFunc

Func _WM_COMMAND($hWnd, $Msg, $wParam, $lParam)
; The Func 2 button was pressed so set the flag
If BitAND($wParam, 0x0000FFFF) = $hButton_2 Then $fInterrupt = 1
; The dummy control was actioned by the Accelerator key so set the flag
If BitAND($wParam, 0x0000FFFF) = $hAccelInterupt Then $fInterrupt = 3
Return $GUI_RUNDEFMSG
EndFunc ;==>_WM_COMMAND
</syntaxhighlight>
-----------------------------------
But what if you want to have a longish ''Sleep'' or some other function which waits for a fair time inside the running function? If you add a ''Sleep(5000)'' to ''Func_1'' in the above examples, you will see that you have to wait until the function returns from the ''Sleep'' before the interrupt is actioned, which is not what we want:
----------------------------------
<syntaxhighlight lang="autoit">
Func _Func_1()
; Make sure the flag is cleared
$fInterrupt = 0
For $i = 1 To 20
ConsoleWrite("-Func 1 Running" & @CRLF)
; Add a long Sleep ; <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
Sleep(5000)
; Look for the flag
If $fInterrupt <> 0 Then
; The flag was set
Switch $fInterrupt
Case 1
ConsoleWrite("!Func 1 interrrupted by Func 2" & @CRLF)
Case 2
ConsoleWrite("!Func 1 interrrupted by HotKey" & @CRLF)
Case 3
ConsoleWrite("!Func 1 interrrupted by Accelerator" & @CRLF)
EndSwitch
Return
EndIf
Sleep(100)
Next
ConsoleWrite(">Func 1 Ended" & @CRLF)
EndFunc ;==>_Func_1

</syntaxhighlight>
-----------------------------------

The answer is to put the blocking function inside a wrapper function which does check for the interrupt flag at regular intervals. Replace the Sleep line with a call to the wrapper function and add the wrapper function to the script:

-----------------------------------
<syntaxhighlight lang="autoit">
; Use a wrapper function in place of the blocking function
Func _Func_1()
; Make sure the flag is cleared
$fInterrupt = 0
For $i = 1 To 20
ConsoleWrite("-Func 1 Running" & @CRLF)
; Run a modified Sleep function which checks for the interrupt
If _Interrupt_Sleep(5000) Then ; <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
; The flag was set
Switch $fInterrupt
Case 1
ConsoleWrite("!Func 1 interrrupted by Func 2" & @CRLF)
Case 2
ConsoleWrite("!Func 1 interrrupted by HotKey" & @CRLF)
Case 3
ConsoleWrite("!Func 1 interrrupted by Accelerator" & @CRLF)
EndSwitch
Return
EndIf
Sleep(100)
Next
ConsoleWrite(">Func 1 Ended" & @CRLF)
EndFunc ;==>_Func_1

; And here is the wrapper function itself
Func _Interrupt_Sleep($iDelay)
; Get a timestamp
Local $iBegin = TimerInit()
; And run a tight loop
Do
; Use a minimum Sleep (could also be a WinWaitActive with a short timeout)
Sleep(10)
; Look for the interrrupt
If $fInterrupt Then
; And return True immediately if set
Return True
EndIf
Until TimerDiff($iBegin) > $iDelay
; Return False if timed out and no interrupt was set
Return False
EndFunc ;==>_Interrupt_Sleep

</syntaxhighlight>
-----------------------------------
So there are the ways available in AutoIt to interrupt a running function. Remember that you must be in ''OnEvent'' mode and start the function from the main code - or have a function which checks internally whether it ought to allow an interruption. You may need to use a wrapper function if you want to use a blocking function such as ''Sleep'' or ''WinWaitActive''. In all other cases you are are not going to be able to interrupt your function.

Interrupting a running function

2013-02-07T10:43:00Z

Melba23:

[[Category:Tutorials]]
This is a common question and this tutorial explains how to do it within the limitations of Autoit.

AutoIt queues function calls in both ''OnEvent'' and ''MessageLoop'' modes. This means that it waits until a function is finished and the code is back in your idle ''While...WEnd'' loop before running the next.

Here are 2 short scripts in both modes to show this in action. Start ''Function 1'' by pressing its button and then immediately try to run ''Function 2'' by pressing its button a couple of times. You will see from the console output that ''Function 2'' will only run '''AFTER''' ''Function 1'' has terminated - and then it will run as many times as you pressed the button.

We start with ''MessageLoop'' mode:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

$hGUI = GUICreate("Test", 500, 500)

$hButton_1 = GUICtrlCreateButton("Func One", 10, 10, 80, 30)
$hButton_2 = GUICtrlCreateButton("Func Two", 10, 50, 80, 30)

GUISetState()

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
Case $hButton_1
_Func_1()
Case $hButton_2
_Func_2()
EndSwitch
WEnd

Func _Func_1()
For $i = 1 To 20
ConsoleWrite("-Func 1 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 1 Ended" & @CRLF)
EndFunc

Func _Func_2()
For $i = 1 To 3
ConsoleWrite("+Func 2 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 2 Ended" & @CRLF)
EndFunc
</syntaxhighlight>
-----------------------------------
And now in ''OnEvent'' mode:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

Opt("GUIOnEventMode", 1)

$hGUI = GUICreate("Test", 500, 500)
GUISetOnEvent($GUI_EVENT_CLOSE, "_Exit")

$hButton_1 = GUICtrlCreateButton("Func One", 10, 10, 80, 30)
GUICtrlSetOnEvent($hButton_1, "_Func_1")
$hButton_2 = GUICtrlCreateButton("Func Two", 10, 50, 80, 30)
GUICtrlSetOnEvent($hButton_2, "_Func_2")

GUISetState()

While 1
Sleep(10)
WEnd

Func _Func_1()
For $i = 1 To 20
ConsoleWrite("-Func 1 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 1 Ended" & @CRLF)
EndFunc

Func _Func_2()
For $i = 1 To 3
ConsoleWrite("+Func 2 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 2 Ended" & @CRLF)
EndFunc

Func _Exit()
Exit
EndFunc
</syntaxhighlight>
-----------------------------------
So is it impossible to interrupt a running function? Of course not or this tutorial would serve no purpose - but there are limitations on the type of function which can be interrupted.

If you are in ''OnEvent'' mode then there is an easy way to interrupt a running function, as long as the function is started within the main code and not by an ''OnEvent'' call. This script shows how to do it by using a flag and checking if it is set - in this way the function is started by the main script and can be interrupted.
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

; Declare a flag
Global $fRunOne = False

Opt("GUIOnEventMode", 1)

$hGUI = GUICreate("Test", 500, 500)
GUISetOnEvent($GUI_EVENT_CLOSE, "_Exit")

$hButton_1 = GUICtrlCreateButton("Func One", 10, 10, 80, 30)
GUICtrlSetOnEvent($hButton_1, "_Func_1")
$hButton_2 = GUICtrlCreateButton("Func Two", 10, 50, 80, 30)
GUICtrlSetOnEvent($hButton_2, "_Func_2")

GUISetState()

While 1
Sleep(10)
; Check if the flag has been set by the OnEvent function
If $fRunOne Then
; Now start the "real" function from within the main code
_Func_1_Run()
EndIf
WEnd

Func _Func_1()
; Set the flag within the OnEvent function
$fRunOne = True
EndFunc ;==>_Func_1

Func _Func_1_Run()
For $i = 1 To 20
ConsoleWrite("-Func 1 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 1 Ended" & @CRLF)
Global $fRunOne = False
EndFunc ;==>_Func_1_Run

Func _Func_2()
For $i = 1 To 3
ConsoleWrite("+Func 2 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 2 Ended" & @CRLF)
EndFunc ;==>_Func_2

Func _Exit()
Exit
EndFunc ;==>_Exit
</syntaxhighlight>
-----------------------------------
However, this method does not work in ''MessageLoop'' mode, not when you want to interrupt a function which was started by an ''OnEvent'' call in ''OnEvent'' mode. In these cases the function you want to interrupt must have regular checks of a flag which we set when we want to interrupt. If the function does not have a suitable loop where such a check is easy to make, you might not be able to interrupt it.

Let us now look at the 2 ways an AutoIt script can break into a suitable function: a '''HotKey''' and a '''Windows message handler'''. The first is easier to code, but cannot be linked to a control on your GUI; the latter is a little more complicated to code, but can be linked to a control.

How do they work?

Let us start with the ''HotKey''. From the AutoIt Help file: ''A hotkey-press *typically* interrupts the active AutoIt function/statement and runs its user function until it completes or is interrupted''. So a ''HotKey'' press is designed to interrupt your running function - just what we need. But the running function will resume after the ''HotKey'' function terminates - so, as explained above, we use the ''HotKey'' function to set a flag which is looked for by our running function. Remember that this flag must be declared as a ''Global'' variable because it needs to be seen by both functions.

Now many coders do not like using ''HotKey''s because they remain active while a script is running and can interfere with other apps. One way to get around this is to use ''Accelerator'' keys - these look very much like ''HotKey''s to the user, but are only active in the script in which they are declared. Although ''Accelerator'' keys look like ''HotKey''s, they are tied to GUI controls and you must use the ''message handler'' method explained below if you want to use them to interrupt a running function.

The ''Windows message handler'' method is a little more complicated and if you are not used to working with them, you might want to read the [[GUIRegisterMsg]] tutorial first.

What we do here is intercept the message that your GUI control sends when it is activated - the same message that AutoIt queues to run the required code once the running function terminates. We use our own message to get a sneak preview of this queuing and use it to set a similar flag to that described above. If our running function sees the flag, it terminates and AutoIt then runs the function waiting in the queue - simple really!

Here are scripts using both methods to show how ''HotKey''s, ''Accelerator'' keys and GUI controls can interrupt a running function. Just as before, start ''Function_1'' by pressing its button - but now you can interrupt it at will!

First in ''MessageLoop'' mode:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#include <WindowsConstants.au3>

; Set a HotKey
HotKeySet("x", "_Interrupt")

; Declare a flag
$fInterrupt = 0

$hGUI = GUICreate("Test", 500, 500)

$hButton_1 = GUICtrlCreateButton("Func One", 10, 10, 80, 30)
$hButton_2 = GUICtrlCreateButton("Func Two", 10, 50, 80, 30)

; Create a dummy control for the Accelerator to action when pressed
$hAccelInterupt = GUICtrlCreateDummy()
; Set an Accelerator key to action the dummy control
Dim $AccelKeys[1][2]=[ ["z", $hAccelInterupt] ]
GUISetAccelerators($AccelKeys)

GUISetState()

; Intercept Windows command messages with out own handler
GUIRegisterMsg($WM_COMMAND, "_WM_COMMAND")

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
Case $hButton_1
_Func_1()
Case $hButton_2
_Func_2()
EndSwitch
WEnd

Func _Func_1()
; Make sure the flag is cleared
$fInterrupt = 0
For $i = 1 To 20
ConsoleWrite("-Func 1 Running" & @CRLF)
; Look for the flag
If $fInterrupt <> 0 Then
; The flag was set
Switch $fInterrupt
Case 1
ConsoleWrite("!Func 1 interrrupted by Func 2" & @CRLF)
Case 2
ConsoleWrite("!Func 1 interrrupted by HotKey" & @CRLF)
Case 3
ConsoleWrite("!Func 1 interrrupted by Accelerator" & @CRLF)
EndSwitch
Return
EndIf
Sleep(100)
Next
ConsoleWrite(">Func 1 Ended" & @CRLF)
EndFunc

Func _Func_2()
For $i = 1 To 3
ConsoleWrite("+Func 2 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 2 Ended" & @CRLF)
EndFunc

Func _Interrupt()
; The HotKey was pressed so set the flag
$fInterrupt = 2
EndFunc

Func _WM_COMMAND($hWnd, $Msg, $wParam, $lParam)
; The Func 2 button was pressed so set the flag
If BitAND($wParam, 0x0000FFFF) = $hButton_2 Then $fInterrupt = 1
; The dummy control was actioned by the Accelerator key so set the flag
If BitAND($wParam, 0x0000FFFF) = $hAccelInterupt Then $fInterrupt = 3
Return $GUI_RUNDEFMSG
EndFunc ;==>_WM_COMMAND
</syntaxhighlight>
-----------------------------------
And now in ''OnEvent'' mode:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#include <WindowsConstants.au3>

; Set a HotKey
HotKeySet("x", "_Interrupt_HotKey")

; Declare a flag
$fInterrupt = 0

Opt("GUIOnEventMode", 1)

$hGUI = GUICreate("Test", 500, 500)
GUISetOnEvent($GUI_EVENT_CLOSE, "_Exit")

$hButton_1 = GUICtrlCreateButton("Func One", 10, 10, 80, 30)
GUICtrlSetOnEvent($hButton_1, "_Func_1")
$hButton_2 = GUICtrlCreateButton("Func Two", 10, 50, 80, 30)
GUICtrlSetOnEvent($hButton_2, "_Func_2")

; Create a dummy control for the Accelerator to action
$hAccelInterupt = GUICtrlCreateDummy()
GUICtrlSetOnEvent($hAccelInterupt, "_Interrupt_Accel")
; Set an Accelerator key to action the dummy control
Dim $AccelKeys[1][2]=[ ["z", $hAccelInterupt] ]
GUISetAccelerators($AccelKeys)

GUISetState()

; Intercept Windows command messages with out own handler
GUIRegisterMsg($WM_COMMAND, "_WM_COMMAND")

While 1
Sleep(10)
WEnd

Func _Func_1()
; Make sure the flag is cleared
$fInterrupt = 0
For $i = 1 To 20
ConsoleWrite("-Func 1 Running" & @CRLF)
; Look for the flag
If $fInterrupt <> 0 Then
; The flag was set
Switch $fInterrupt
Case 1
ConsoleWrite("!Func 1 interrrupted by Func 2" & @CRLF)
Case 2
ConsoleWrite("!Func 1 interrrupted by HotKey" & @CRLF)
Case 3
ConsoleWrite("!Func 1 interrrupted by Accelerator" & @CRLF)
EndSwitch
Return
EndIf
Sleep(100)
Next
ConsoleWrite(">Func 1 Ended" & @CRLF)
EndFunc

Func _Func_2()
For $i = 1 To 3
ConsoleWrite("+Func 2 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 2 Ended" & @CRLF)
EndFunc

Func _Exit()
Exit
EndFunc

Func _Interrupt_HotKey()
; The HotKey was pressed so set the flag
$fInterrupt = 2
EndFunc

Func _Interrupt_Accel()
; This is an empty function for the dummy control linked to the Accelerator key
EndFunc

Func _WM_COMMAND($hWnd, $Msg, $wParam, $lParam)
; The Func 2 button was pressed so set the flag
If BitAND($wParam, 0x0000FFFF) = $hButton_2 Then $fInterrupt = 1
; The dummy control was actioned by the Accelerator key so set the flag
If BitAND($wParam, 0x0000FFFF) = $hAccelInterupt Then $fInterrupt = 3
Return $GUI_RUNDEFMSG
EndFunc ;==>_WM_COMMAND
</syntaxhighlight>
-----------------------------------
But what if you want to have a longish ''Sleep'' or some other function which waits for a fair time inside the running function? If you add a ''Sleep(5000)'' to ''Func_1'' in the above examples, you will see that you have to wait until the function returns from the ''Sleep'' before the interrupt is actioned, which is not what we want:
----------------------------------
<syntaxhighlight lang="autoit">
Func _Func_1()
; Make sure the flag is cleared
$fInterrupt = 0
For $i = 1 To 20
ConsoleWrite("-Func 1 Running" & @CRLF)
; Add a long Sleep ; <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
Sleep(5000)
; Look for the flag
If $fInterrupt <> 0 Then
; The flag was set
Switch $fInterrupt
Case 1
ConsoleWrite("!Func 1 interrrupted by Func 2" & @CRLF)
Case 2
ConsoleWrite("!Func 1 interrrupted by HotKey" & @CRLF)
Case 3
ConsoleWrite("!Func 1 interrrupted by Accelerator" & @CRLF)
EndSwitch
Return
EndIf
Sleep(100)
Next
ConsoleWrite(">Func 1 Ended" & @CRLF)
EndFunc ;==>_Func_1

</syntaxhighlight>
-----------------------------------

The answer is to put the blocking function inside a wrapper function which does check for the interrupt flag at regular intervals. Replace the Sleep line with a call to the wrapper function and add the wrapper function to the script:

-----------------------------------
<syntaxhighlight lang="autoit">
; Use a wrapper function in place of the blocking function
Func _Func_1()
; Make sure the flag is cleared
$fInterrupt = 0
For $i = 1 To 20
ConsoleWrite("-Func 1 Running" & @CRLF)
; Run a modified Sleep function which checks for the interrupt
If _Interrupt_Sleep(5000) Then ; <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
; The flag was set
Switch $fInterrupt
Case 1
ConsoleWrite("!Func 1 interrrupted by Func 2" & @CRLF)
Case 2
ConsoleWrite("!Func 1 interrrupted by HotKey" & @CRLF)
Case 3
ConsoleWrite("!Func 1 interrrupted by Accelerator" & @CRLF)
EndSwitch
Return
EndIf
Sleep(100)
Next
ConsoleWrite(">Func 1 Ended" & @CRLF)
EndFunc ;==>_Func_1

; And here is the wrapper function itself
Func _Interrupt_Sleep($iDelay)
; Get a timestamp
Local $iBegin = TimerInit()
; And run a tight loop
Do
; Use a minimum Sleep (could also be a WinWaitActive with a short timeout)
Sleep(10)
; Look for the interrrupt
If $fInterrupt Then
; And return True immediately if set
Return True
EndIf
Until TimerDiff($iBegin) > $iDelay
; Return False if timed out and no interrupt was set
Return False
EndFunc ;==>_Interrupt_Sleep

</syntaxhighlight>
-----------------------------------
So there are the ways available in AutoIt to interrupt a running function. Remember that you must be in ''OnEvent'' mode and start the function from the main code - or have a function which checks internally whether it ought to allow an interruption. You may need to use a wrapper function if you want to use a blocking function such as ''Sleep'' or ''WinWaitActive''. In all other cases you are are not going to be able to interrupt your function.

Adding UDFs to AutoIt and SciTE

2012-11-03T09:51:29Z

Melba23:

The ability to download UDFs created by other users is one of the major advantages of AutoIt, but are you one of the many coders who just add these UDFs to the existing "''Include''" folder which contains the standard UDFS distributed with AutoIt? If so then there is much better way to do it - one which will prevent you from losing all of these additional UDFs when you upgrade. Just use a user-defined folder to store all your UDFs - AutoIt makes this very easy to do.

Begin by creating a new folder to hold the additional UDFs - it is recommended that you do '''NOT''' put this folder in the AutoIt install folder (or it will get overwritten when you upgrade). Then tell AutoIt about this folder.

- If you have ''SciTE4AutoIt3'' you can use '''SciTEConfig''' - look for the ''User Include Dir'' input about 2/3 way down the dialog.

- If not (and why not? You can download it from here[http://www.autoitscript.com/site/autoit-script-editor/downloads/]) you need to modify the registry directly as explained on the "''Include''" page of the Help file:
<syntaxhighlight lang="autoit">
There is a special registry value that can be created at "HKEY_CURRENT_USER\Software\AutoIt v3\AutoIt" called "Include".
It should be a REG_SZ (string) value.
</syntaxhighlight>
'''CYA Note''': Normal precautions are advised if modifying the registry.

You now have a folder to store modified, downloaded or personal UDFs which are available to use with no need to specify the path and which will not be lost on upgrade. But to make coding with these UDFs even easier you can also add '''CallTips''' and '''AutoComplete''' for them.

As you might expect, the full ''SciTE4AutoIt3'' package makes it easy - have you downloaded and installed it yet? If you have then just open '''SciTEConfig''' on the '''Other Tools''' tab and press '''Run User Call Tip Manager'''. Then you just need to select the UDF file to add and everything is done for you automatically.

But if you want to do it manually:

'''Calltips''' first. These are stored in ''C:\Program Files\AutoIt3\SciTE\api\au3.user.calltips.api''. If you are doing this for the first time then this file will not exist and you will have to create it. Then add a line like this to the file for each function you wish to have a calltip:
<syntaxhighlight lang="autoit">
_Function($param1, $param2, $param3) Explanation of function (Requires: #Include UDF.au3)
</syntaxhighlight>
Of course you need to change the ''Function, $param'' and ''UDF'' words to the correct values for the UDF function you want to include.

Now '''AutoComplete'''. Again a special file is used ''C:\Program Files\AutoIt3\SciTE\Properties\au3.userudfs.properties'' - again you will have to create it initially - which should read as follows:
<syntaxhighlight lang="autoit">
au3.keywords.user.udfs=_function1 _function2 _function3 _function4 \
_function5 _function6 _function7
</syntaxhighlight>
Note that the entries are all in lowercase and all lines other than the first begin with a ''@TAB'' character.

You may have adjust the path if you have installed SciTE elsewhere than the recommended option.

Then save all files, close and restart SciTE. You will have '''AutoComplete''' when you start typing the UDF function name in a script and a syntax '''CallTip''' as you enter the parameters. These files are not overwritten when you update SciTE so all your hard work to set this up should be a once-only event.

One final thing. If you want the "''Tools - Open Include''" menu item in SciTE to work on the files within this new folder you need to add the following lines to your "''SciTEUser.properties''" file - you open it by using the <''Options - Open User Options File''> menu item:
<syntaxhighlight lang="autoit">
openpath.$(au3)=$(autoit3dir)\include;Your_Folder_Path
openpath.beta.$(au3)=$(autoit3dir)\beta\include;Your_Folder_Path
</syntaxhighlight>
Now you are all set - your personal include files are as accessible as the standard set.

Recursion

2012-04-28T15:38:49Z

Melba23:

Recursion is a topic which many find difficult to grasp and even more difficult to realise. However, as I hope this tutorial will show, it is not that daunting and can prove very useful. However, you do need to take great care when using recursion, including tidying up after yourself, as otherwise you can crash your system very quickly.

[[What is recursion?]]

Let us start by explaining what is meant by recursion. Basically it means a function calling itself while the original function is still running. You might wonder why you would ever want to do this - perhaps the simplest example is searching through a folder structure where you need to look in each of the subfolders you find at each level. Another example would be my ''GUIFrames'' UDF where I use recursion to resize the frames inside a resized GUI, even if the frames are inside other frames - each resized element uses the same function to resize the elements within it. Without recursion this would be almost impossible to do.

[[Why is recursion difficult to use?]]

So now we know what recursion is, why is it tricky to use? The following is a very simplistic explanation, but it will suffice to illustrate the problem. Like any other application, AutoIt maintains an area of memory known as the ''stack'' where it stores temporary data. When you call a function, AutoIt puts a fair amout of data onto the ''stack'' so that it can reload it when the function returns and so knows where it was, what it was doing and what the various variable values were. If you call other functions from within the running function, the amount of data in the ''stack'' increases each time and if you do it enough times you can get a "''stack overflow''" error which usually spells disaster! Of course, most scripts do not nest functions to any great depth and the ''stack'' is comfortably large enough to cope as the data is removed once the function returns. But recursion, where a function keeps calling itself, can lead to a very rapid increase in the amount of ''stack'' space required and so a rapid crash. AutoIt actually prevents the crash by limiting the recursion level - it will not allow you to store too many datasets (i.e. call too many functions without ever getting back to the main idle loop) on the ''stack''. It is extremely unlikely that you would ever get anywhere close to this limit unless you get into a recursive loop with a function calling itself.

[[Some simple examples - bad and good!]]

So what does a recursive loop look like? Here is a very simple example which on first glance looks as if it will just print an ever-increasing value in the console. But try running it - it will not work as you might think, but it will not harm your machine:
-----------------------------------
<syntaxhighlight lang="autoit">
_AddOne(0)

Func _AddOne($i)

ConsoleWrite("In: " & $i & @CRLF)

$i += 1

_AddOne($i)

ConsoleWrite("Out: " & $i & @CRLF)

EndFunc
</syntaxhighlight>
-----------------------------------
I get to 3898 and then see:

''M:\Program\Au3 Scripts\Recursion Demo.au3 (13) : ==> Recursion level has been exceeded - AutoIt will quit to prevent stack overflow.:''

As you see, you get the "''In''" values printed, but as you immediately call the function again you never get to see the "''Out''" values as you never actually reach that point in the function - you are in an infinite recursive loop and only AutoIt's built-in limit prevents a crash as the ''stack'' approaches overflow.

But adding a single limit line to prevent the infinite loop will show how recursion can work without this problem:
-----------------------------------
<syntaxhighlight lang="autoit">
_AddOne(0)

Func _AddOne($i)

ConsoleWrite("In: " & $i & @CRLF)

$i += 1

If $i = 100 Then Return ; This is where we break the infinite recursive loop <<<<<<<<<<<<<<<<<<<<<<<<<<

_AddOne($i)

ConsoleWrite("Out: " & $i & @CRLF)

EndFunc
</syntaxhighlight>
-----------------------------------
Here you can see that the "''In''" values are printed as before until the limit is reached and the final function returns. This triggers all the other functions that had been called to continue to run and you get the "''Out''" values printed. Note that they are in the reverse order as AutoIt pulls the data back from the ''stack'' and resets each function to the state it was in before the recursive call.

[[A practical use of recursion]]

I hope the above has made it clear what recursion is and why you must make sure that you do not enter an infinite recursive loop. Let us now look at a practical application of recursion - searching a folder tree.

The problem is simple - we need to search an initial folder - and any subfolders that we find within that folder - and any subfolders within those subfolders - and any subfolder within those subfolders...... You can see why recursion might be useful here! This is a very simple script to list the files in the "''Extras''" folder of your AutoIt install:
-----------------------------------
<syntaxhighlight lang="autoit">
ListFiles_Recursive(@ProgramFilesDir & "\AutoIt3\Extras")

Func ListFiles_Recursive($sSourceFolder)

Local $sFile

; Force a trailing \
If StringRight($sSourceFolder, 1) <> "\" Then $sSourceFolder &= "\"

; Start the search
Local $hSearch = FileFindFirstFile($sSourceFolder & "*.*")
; If no files found then return
If $hSearch = -1 Then Return ; This is where we break the recursive loop <<<<<<<<<<<<<<<<<<<<<<<<<<

; Now run through the contents of the folder
While 1
; Get next match
$sFile = FileFindNextFile($hSearch)
; If no more files then close search handle and return
If @error Then ExitLoop ; This is where we break the recursive loop <<<<<<<<<<<<<<<<<<<<<<<<<<

; Check if a folder
If @extended Then
; If so then call the function recursively
ListFiles_Recursive($sSourceFolder & $sFile)
Else
; If a file than write path and name
ConsoleWrite("Found: " & $sSourceFolder & $sFile & @CRLF)
EndIf
WEnd

; Close search handle
FileClose($hSearch)

EndFunc ;==>ListFiles_Recursive
</syntaxhighlight>
-----------------------------------
The 2 <<<<<<<<<<< lines are the limiters to prevent infinite recursion. The first returns when the ''FileFindFirstFile'' does not find any files in a folder, the second when ''FileFindNextFile'' finds no more files in a folder. Take careful note of the difference in the action the 2 limiters take - the first returns instantly, the second exits the loop to make sure that the ''$hSearch'' handle is closed before returning. This is a good example of the "''tidying up''" I mentioned right at the beginning - there are only a limited number of handles available and leaving one open each time you call a recursive function is a good recipe for a catastophe later on.

I hope this short introduction to recursion has clarified what it is and why you need to take such care when using it. However, I would advise you '''not''' to use recursion unless there is absolutely no alternative. Unless you take extreme care, it is simply too easy to mess up the limiters and end up in an infinite recursive loop.

[[A way of avoiding of recursion]]

So what can you do when recursion seems the obvious and best solution? One possibility is to look at iteration, where you call a function several times but return from it each time and then restart it with another set of parameters. Here is a very similar file listing script to the example above using an iterative technique. Each time a subfolder is found its path is added to an array and the internal loop continues until all them have been searched:
-----------------------------------
<syntaxhighlight lang="autoit">
ListFiles_Iterative(@ProgramFilesDir & "\AutoIt3\Extras")

Func ListFiles_Iterative($sSourceFolder)

Local $sFile

; Force a trailing \
If StringRight($sSourceFolder, 1) <> "\" Then $sSourceFolder &= "\"
; Create an array to hold the folders to be searched
Local $aFolderList[10] = [1, $sSourceFolder]

; Search within listed folders until all have been searched
While $aFolderList[0] > 0

; Get path of folder to search
Local $sSearchPath = $aFolderList[$aFolderList[0]]
; Remove folder from list
$aFolderList[0] -= 1

; Start the search
Local $hSearch = FileFindFirstFile($sSearchPath & "*.*")
; If failure then return
If $hSearch = -1 Then Return

; Now run through the contents of the folder
While 1
; Get next match
$sFile = FileFindNextFile($hSearch)
; If no more files then close search handle and return
If @error Then ExitLoop
; If a folder then add to array to be searched
If @extended Then

; #######################################

; Increase folder count
$aFolderList[0] += 1
; Double array size if too small (fewer ReDim needed)
If UBound($aFolderList) <= $aFolderList[0] Then ReDim $aFolderList[UBound($aFolderList) * 2]
; Add folder
$aFolderList[$aFolderList[0]] = $sSearchPath & $sFile & "\"

; #######################################

Else
; If a file than write path and name
ConsoleWrite("Found: " & $sSearchPath & $sFile & @CRLF)
EndIf
WEnd

; Close search handle
FileClose($hSearch)

WEnd

EndFunc ;==>ListFiles_Iterative
</syntaxhighlight>
-----------------------------------
As you can see, you get the same files listed - and no recursion used at all!

[[A little added extra]]

If you have been good enough to read this far, you might like to look carefully at the code between the ######## lines in the example above where the subfolders found are added to the ''$aFolderList'' array. The code uses a clever trick to speed up the script. ''ReDim'' is among the slowest of the AutoIt functions, so you want to limit its use as much as possible. If we were to increase the array size by just the one element each time we added a folder, we would slow down the function enormously - it makes little difference here but imagine if you were scanning an entire drive. Instead of adding a single additional element we double the array in size if it is already full to make sure we get plenty of extra space. You will need to have a count variable available to do this - so why not in the [0] element as is the case for many AutoIt arrays? Just remember that if you want to use the array subsequently (unlike here where it is discarded) you will need one final ''ReDim'' to get rid of any unused elements left over after the last increase in size.

Tabs

2012-04-28T15:37:55Z

Melba23:

[[Tabs and how to deal with them]]

Tabs are a valuable tool when you need to fit a lot of controls into a small GUI. But inexperienced users often have problems with them - particularly in making sure that controls only appear on the correct tab. This tutorial should help.

Before going further, it is important to understand the differences between controls created using the built-in AutoIt commands (''GUICtrlCreate*'') and those created with the UDFs. The built-in commands produce controls which are managed internally by AutoIt - they return '''ControlID'''s. The UDF commands create controls that are not in Autoit's internal management structure and need to be managed by the code - they normally return '''handles''' (the special unique identifier for all Windows components).

'''Tabs'''

Any tabs created by the built-in AutoIt commands ''GUICtrlCreateTab/TabItem'' will automatically take care of displaying any built-in controls created at the same time within the tab creation structure. Here is an example:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

$hGUI = GUICreate("Built-In Tab Example", 500, 500)

$hTab = GUICtrlCreateTab(10, 10, 480, 480)
; Create tabitems
For $i = 0 To 2
GUICtrlCreateTabItem("Tab " & $i)
GUICtrlCreateButton("Button " & $i, 20 + ($i * 100), 40 + ($i * 50), 80, 30)
Next
; Close Tab definiton
GUICtrlCreateTabItem("")

GUISetState()

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
EndSwitch
WEnd
</syntaxhighlight>
-----------------------------------
As you can see, the controls for each tab are created just after the TabItem on which they are to appear and before the next TabItem. Do not forget to close the Tab definition - many tab problems are caused by omitting this vital line.

What happens if we add some UDF created controls to these tabs?
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#Include <GuiButton.au3>

$hGUI = GUICreate("Built-In Tab Example", 500, 500)

$hTab = GUICtrlCreateTab(10, 10, 480, 480)
; Create tabitems
For $i = 0 To 2
GUICtrlCreateTabItem("Tab " & $i)
GUICtrlCreateButton("Built-In " & $i, 20 + ($i * 100), 40 + ($i * 50), 80, 30)
_GUICtrlButton_Create($hGUI, "UDF " & $i, 20 + ($i * 100), 80 + ($i * 50),80, 30)
Next
; Close Tab definiton
GUICtrlCreateTabItem("")

GUISetState()

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
EndSwitch
WEnd
</syntaxhighlight>
-----------------------------------
As you can see, the UDF created controls appear on every tab. Remember this is because they are not part of the internal AutoIt control management structure, so AutoIt does not know how to handle them. It is up to you to manage them by seeing which tab is active and hiding/showing these controls as required:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#Include <GuiButton.au3>

Global $hButtons[3]

$hGUI = GUICreate("Built-In Tab Example", 500, 500)

$hTab = GUICtrlCreateTab(10, 10, 480, 480)
; Create tabitems
For $i = 0 To 2
GUICtrlCreateTabItem("Tab " & $i)
GUICtrlCreateButton("Built-In " & $i, 20 + ($i * 100), 40 + ($i * 50), 80, 30)
; Add a label to the first tab
If $i = 0 Then GUICtrlCreateLabel("See how 'laggy' the UDF buttons are when selecting this tab because of using WinSetState", 20, 200, 150, 60)
Next

GUICtrlCreateTabItem("")

; Create UDF controls
For $i = 0 To 2
$hButtons[$i] = _GUICtrlButton_Create($hGUI, "UDF " & $i, 20 + ($i * 100), 80 + ($i * 50),80, 30)
Next

; Hide the controls so only the one on the first tab is visible
WinSetState($hButtons[1], "", @SW_HIDE)
WinSetState($hButtons[2], "", @SW_HIDE)

GUISetState()

; This is the current active tab
$iLastTab = 0

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
Case $hTab
; Check which Tab is active
$iCurrTab = GUICtrlRead($hTab)
; If the Tab has changed
If $iCurrTab <> $iLastTab Then
; Show/Hide controls as required
Switch $iCurrTab
Case 0
; Note lag when WinSetState is used
WinSetState($hButtons[1], "", @SW_HIDE)
WinSetState($hButtons[2], "", @SW_HIDE)
WinSetState($hButtons[0], "", @SW_SHOW)
Case 1
; No lag when using ControlHide/Show
ControlHide($hGUI, "", $hButtons[0])
ControlHide($hGUI, "", $hButtons[2])
ControlShow($hGUI, "", $hButtons[1])
Case 2
; Nor when using this DLL
DllCall("User32.dll", "bool", "ShowWindowAsync", "hwnd", $hButtons[0], "int", @SW_HIDE)
DllCall("User32.dll", "bool", "ShowWindowAsync", "hwnd", $hButtons[1], "int", @SW_HIDE)
DllCall("User32.dll", "bool", "ShowWindowAsync", "hwnd", $hButtons[2], "int", @SW_SHOW)

EndSwitch
; Store the value for future comparisons
$iLastTab = $iCurrTab
EndIf
EndSwitch
WEnd
</syntaxhighlight>
-----------------------------------
Note the lag in hiding/showing the UDF created controls if you use ''WinSetState'' - I would recommend using ''ControlShow/Hide'' which gives an instantaneous response. Also how you do not need to create the UDF controls within the tab creation structure - as you have to look after them, there is no requirement to do so.

Now let us look at Tabs created with the ''GUITab'' UDF. In this case you need to manage all of the controls on the tabs yourself, even if they are created using the built-in commands:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#Include <GuiButton.au3>
#include <GuiTab.au3>

Global $hBuiltIn_Buttons[3]
Global $hUDF_Buttons[3]

$hGUI = GUICreate("Built-In Tab Example", 500, 500)

$hTab = _GUICtrlTab_Create($hGUI, 10, 10, 480, 480)
GUISetState()

; Add tabs
_GUICtrlTab_InsertItem($hTab, 0, "Tab 0")
_GUICtrlTab_InsertItem($hTab, 1, "Tab 1")
_GUICtrlTab_InsertItem($hTab, 2, "Tab 2")

; Create the Built-in and UDF buttons
For $i = 0 To 2
$hBuiltIn_Buttons[$i] = GUICtrlCreateButton("Button " & $i, 20 + ($i * 100), 40 + ($i * 50), 80, 30)
$hUDF_Buttons[$i] = _GUICtrlButton_Create($hGUI, "UDF " & $i, 20 + ($i * 100), 80 + ($i * 50),80, 30)
Next

; Hide the controls so only the one on the first tab is visible
GUICtrlSetState($hBuiltIn_Buttons[1], $GUI_HIDE)
GUICtrlSetState($hBuiltIn_Buttons[2], $GUI_HIDE)
ControlHide($hGUI, "", $hUDF_Buttons[1])
ControlHide($hGUI, "", $hUDF_Buttons[2])

GUISetState()

; This is the current active tab
$iLastTab = 0

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
EndSwitch

; Check which Tab is active
$iCurrTab = _GUICtrlTab_GetCurFocus($hTab)
; If the Tab has changed
If $iCurrTab <> $iLastTab Then
; Store the value for future comparisons
$iLastTab = $iCurrTab
; Show/Hide controls as required
Switch $iCurrTab
Case 0
GUICtrlSetState($hBuiltIn_Buttons[1], $GUI_HIDE)
GUICtrlSetState($hBuiltIn_Buttons[2], $GUI_HIDE)
GUICtrlSetState($hBuiltIn_Buttons[0], $GUI_SHOW)
ControlHide($hGUI, "", $hUDF_Buttons[1])
ControlHide($hGUI, "", $hUDF_Buttons[2])
ControlShow($hGUI, "", $hUDF_Buttons[0])
Case 1
GUICtrlSetState($hBuiltIn_Buttons[0], $GUI_HIDE)
GUICtrlSetState($hBuiltIn_Buttons[2], $GUI_HIDE)
GUICtrlSetState($hBuiltIn_Buttons[1], $GUI_SHOW)
ControlHide($hGUI, "", $hUDF_Buttons[0])
ControlHide($hGUI, "", $hUDF_Buttons[2])
ControlShow($hGUI, "", $hUDF_Buttons[1])
Case 2
GUICtrlSetState($hBuiltIn_Buttons[0], $GUI_HIDE)
GUICtrlSetState($hBuiltIn_Buttons[1], $GUI_HIDE)
GUICtrlSetState($hBuiltIn_Buttons[2], $GUI_SHOW)
ControlHide($hGUI, "", $hUDF_Buttons[0])
ControlHide($hGUI, "", $hUDF_Buttons[1])
ControlShow($hGUI, "", $hUDF_Buttons[2])
EndSwitch
EndIf
WEnd
</syntaxhighlight>
-----------------------------------
A lot of work but a very satisfactory result. Note the need to use different commands to hide/show the built-in and UDF created controls to avoid "lag" on the latter as was shown in the earlier example.

So, a couple of lessons to draw from this:

- 1. When using tabs, try and use built-in commands if at all possible. If you do, AutoIt looks after the showing/hiding problem for you as long as you create the controls WITHIN the tab creation structure. If you need to add controls after having ended the tab structure definiton, then you '''must''' use ''GUISwitch'' with the ''tabitemID'' parameter to select the correct tab before you create the control or you will find that it is visible on all tabs.

- 2. If you must use UDF created controls for any reason, you have to manage hiding/showing all controls yourself.

'''Multiple tabs in a GUI'''

Unfortunately, only one built-in tab control can be created per GUI - you cannot have several tabs on a single GUI. But there is a way around this - just create child GUIs which can each hold a tab:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#include <WindowsConstants.au3>

$hGUI = GUICreate("Test", 500, 500)

GUISetState()

; Create child GUIs to hold tabs
$hTab_Win0 = GUICreate("", 400, 200, 50, 20, $WS_POPUP, $WS_EX_MDICHILD, $hGUI)
$hTab_0 = GUICtrlCreateTab(10, 10, 380, 180)
$hTab_00 = GUICtrlCreateTabitem("00")
GUICtrlCreateButton("00", 160, 90, 80, 30)
$hTab_01 = GUICtrlCreateTabitem("01")
GUICtrlCreateButton("01", 160, 90, 80, 30)

GUICtrlCreateTabitem ("")
GUISetState()

$hTab_Win1 = GUICreate("", 400, 200, 50, 250, $WS_POPUP, $WS_EX_MDICHILD, $hGUI)
$hTab_1 = GUICtrlCreateTab(10, 10, 380, 180)
$hTab_10 = GUICtrlCreateTabitem("10")
GUICtrlCreateButton("10", 160, 90, 80, 30)
$hTab_11 = GUICtrlCreateTabitem("11")
GUICtrlCreateButton("11", 160, 90, 80, 30)
GUICtrlCreateTabitem ("")
GUISetState()

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
EndSwitch
WEnd
</syntaxhighlight>
-----------------------------------
Easy when you know how!

Tabs are useful controls, but can be difficult to master. After this tutorial you should be well on your way!

Modal MsgBox Styles

2012-04-28T15:36:45Z

Melba23:

''MsgBox'' is a blocking function - your script pauses until a button on the ''MsgBox'' is pressed - at which point the function terminates with a return value which you can use in a decision structure of some kind. Your main GUI appears unresponsive until the ''MsgBox'' is cleared.

However, things are not quite that simple, as the ''MsgBox'' can be set as '''Application, System''' or '''Task Modal'''. Although the values needed to set these styles are given in the Helpfile, it does not actually explain the difference between them.

'''Application''': This is the default setting. In this case your GUI will react to mouse clicks and will even retake focus from the ''MsgBox'', but will not act on the clicks until the ''MsgBox'' is cleared. Try closing the main GUI while the ''MsgBox'' is displayed - it will not close unless you clear the ''Msgbox'' first:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

$hGUI = GUICreate("Test", 500, 500)
GUISetState()

MsgBox(0, "Blocking", "Press me to continue")

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
EndSwitch
WEnd
</syntaxhighlight>
-----------------------------------
'''System Modal''': Now the ''MsgBox'' remains in view even if the main GUI regains focus although the main GUI appears inactive the GUI. However if the main GUI is closed this will again occur as soon as the ''MsgBox'' is cleared.
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

$hGUI = GUICreate("Test", 500, 500)
GUISetState()

MsgBox(4096, "Blocking", "Press me to continue")

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
EndSwitch
WEnd
</syntaxhighlight>
-----------------------------------
'''Task Modal''': Now we get to the real deal - you cannot action anything on the main GUI until the ''MsgBox'' is cleared. So you cannot close the main GUI - or do anything else with it at all!
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

$hGUI = GUICreate("Test", 500, 500)
GUISetState()

MsgBox(8192, "Blocking", "Press me to continue")

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
EndSwitch
WEnd
</syntaxhighlight>
-----------------------------------
Now all you have to do is choose which type best suits your needs!

[[An added extra]]

Another way to prevent the GUI from being actioned while the ''MsgBox'' is present is to set the "''parent''" parameter like this:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

$hGUI = GUICreate("Test", 500, 500)

GUISetState()

MsgBox(0, "", "", 0, $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
EndSwitch
WEnd
</syntaxhighlight>
-----------------------------------

Setting Styles

2012-04-28T15:34:13Z

Melba23:

Setting styles and extended styles in an integral part of coding in AutoIt - but it is very easy to get something other than the result you wanted if you do not take care when specifying them!

Note: Although the text and examples in this tutorial deal with styles, everything here is also applicable to extended styles.

[[Multiple styles]]

Most styles are set at the bit level - they require specific bits within the total style value to be set in order for the specific style to be activated. This is why you should always use ''BitOR'' rather than simple addition when setting multiple styles to make sure you do not inadvertantly set/unset bits you do not mean to! Let us look a why this might happen - but if you do not understand binary maths, you might want to go and read about that first!

Let us imagine we want to set 2 styles which have the values 17 and 33 (these values have been chosen just for illustration and are not valid styles). Expressing the 2 styles in binary gives us:
<syntaxhighlight lang="autoit">
Style_1 = 17 = 00010001
Style_2 = 33 = 00100001
</syntaxhighlight>
Now let us see what happens when we try and combine the 2 styles:

Using ''BitOR'' (which sets bits if either or both bits are set) we get:
<syntaxhighlight lang="autoit">
BitOR(Style_1, Style_2) = 00110001
</syntaxhighlight>
However, if we use ''simple addition'', we get:
<syntaxhighlight lang="autoit">
17 + 33 = 50 = 00110010
</syntaxhighlight>
Windows uses a form of ''BitAND'' to check for styles which means that it looks for specific bits within the larger number. So if Windows is checking for Style 1, it looks for bits 4 and 8. In the ''BitOr'' result, these bits are set - and Windows will apply the style. The same is true for Style 2 - this time bits 3 and 8 are set in both the style and the combined result.

However, if we try the same tests against the result obtained by simple addition, we see that in neither case does Windows find the correct bits set. So Windows will apply neither style to our control - and will probably apply some other completely different styles instead.

So, always use ''BitOR'' to set multiple styles. Remember that you can combine several styles within a single ''BitOr''.

[[Adding and removing styles]]

Most AutoIt controls have default styles - look in the <''Appendix - GUI Control Styles''> section of the Help file to see what they are. For example, a List control is created with the ''$LBS_SORT, $WS_BORDER'', and ''$WS_VSCROLL'' styles set automatically. As you can see from the <''List Styles''> section of the above Help file page, these have been conveniently combined as the ''$GUI_SS_DEFAULT_LIST'' style and similar values are available for all the ususal controls. However, there is no need to specify any of these default styles in the initial ''GUICtrlCreate*'' statement as they are automatically included as previously mentioned. Where users often have difficulty is when they want to add further styles to a control. Whenever you specify a particular style (or multiple styles using ''BitOR'' as explained above) you '''overwrite''' the existing style value and set '''ONLY''' the value you have just specified.

Here is an example of this overwriting using ListViews.

- The first default ListView is automatically created with the ''$LVS_SHOWSELALWAYS'' and ''$LVS_SINGLESEL'' styles.

- If we want to sort the items, we need to set the ''$LVS_SORTASCENDING/DESCENDING'' style. So we do this for the second ListView - but as we only specify the ''$LVS_SORTASCENDING'' style we '''overwrite''' the default styles.

- The final ListView shows how to add the ''$LVS_SORTASCENDING'' style correctly by using the ''BitOR'' operator on the default setting '''AND''' the new style.

If you play with the ListViews, you will see that although the middle ListView is indeed sorted, it now permits multiple selections and does not show the selected items when it does not have focus - because it no longer has the ''$LVS_SINGLESEL'' and ''$LVS_SHOWSELALWAYS '' styles. The bottom ListView is sorted and has retained the default styles - which is want we wanted.
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#include <ListviewConstants.au3>

$hGUI = GUICreate("Test", 500, 600)

$hLV_Default = GUICtrlCreateListView("Header", 10, 10, 480, 180)
GUICtrlSetBkColor(-1, 0xC4C4C4)
$hLV_Sorted = GUICtrlCreateListView("Header", 10, 200, 480, 180, $LVS_SORTASCENDING)
GUICtrlSetBkColor(-1, 0xC4C4C4)
$hLV_Default_Sorted = GUICtrlCreateListView("Header", 10, 400, 480, 180, BitOr($GUI_SS_DEFAULT_LISTVIEW, $LVS_SORTASCENDING))
GUICtrlSetBkColor(-1, 0xC4C4C4)

For $i = 1 To 8
$iItem = Random(0, 9, 1)
GUICtrlCreateListViewItem($iItem, $hLV_Default)
GUICtrlCreateListViewItem($iItem, $hLV_Sorted)
GUICtrlCreateListViewItem($iItem, $hLV_Default_Sorted)
Next

GUISetState()

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
EndSwitch
WEnd
</syntaxhighlight>
-----------------------------------
Things can get a little more complicated if we created the control with a non-standard style set and want to change it. How do we find out what styles are currently set? You may have noticed that there is no ''GUIGtrl'''Get'''Style'' to match the ''GUICtrl'''Set'''Style'' command.

As it is you who are setting the styles in your own script, a good tip is to keep the current value in a variable which you can then easily modify. But we can also get the current style values by calling the Windows API directly:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <Constants.au3> ; Do not forget these include files!
#include <WinAPI.au3>

$iStyle = _WinAPI_GetWindowLong(GUICtrlGetHandle($iControlID), $GWL_STYLE)
$iExStyle = _WinAPI_GetWindowLong(GUICtrlGetHandle($iControlID), $GWL_EXSTYLE)
</syntaxhighlight>
-----------------------------------
Once you have the current value then you can easily add or subtract other styles from it.

Adding a new style is simple - we just use ''BitOR'' as we have already seen:
-----------------------------------
<syntaxhighlight lang="autoit">
GUICtrlSetStyle($iControlID, BitOR($iOldStyleValue, $iNewStyle))
</syntaxhighlight>
-----------------------------------
Subtracting a style can be done in 2 ways - although one is much easier to use:
-----------------------------------
<syntaxhighlight lang="autoit">
GUICtrlSetStyle($iControlID, BitXOR($iOldStyleValue, $iStyleToRemove))

GUICtrlSetStyle($iControlID, BitAnd($iOldStyleValue, BitNOT($iStyleToRemove)))
</syntaxhighlight>
-----------------------------------
You can see that we are using ''Bit*'' operators again. Explaining exactly how they affect the values we give as parameters is beyond the scope of this tutorial, but they all operate in a similar manner to the ''BitOR/BitAND'' case we looked at when combining styles earlier.

Finally, here is a script which shows these various operators and API calls in action. You can see that the Edit control style value changes between 0x50331'''0'''C4 and 0x50331'''8'''C4 depending on whether the ''$ES_READONLY'' syle is included - and you can check that the style is applied/removed by attempting to change the Edit content.
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#include <EditConstants.au3>
#include <Constants.au3>
#include <WinAPI.au3>

$iCount = 1
$sBut_Add = "Press to add ReadOnly style"
$sBut_Sub = "Press to remove ReadOnly style"
$sEdit_Text = "You can edit me if you wish"
$sRead_Text = "But you can only read me"

$hGUI = GUICreate("Test", 500, 160)

$hEdit = GUICtrlCreateEdit($sEdit_Text, 10, 10, 480, 100)
$hEdit_Handle = GUICtrlGetHandle(-1)

$hButton = GUICtrlCreateButton($sBut_Add, 150, 120, 200, 30)

GUISetState()

; Read default values
$iStyle = _WinAPI_GetWindowLong($hEdit_Handle, $GWL_STYLE)
MsgBox(0, "Initial Style", "Style = " & "Ox" & Hex($iStyle, 8))

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
Case $hButton
Switch $iCount
Case 1
; Use BitOR to ADD style
GUICtrlSetStyle($hEdit, BitOr($iStyle, $ES_READONLY))
$iStyle = _WinAPI_GetWindowLong($hEdit_Handle, $GWL_STYLE)
$iCount += 1
MsgBox(0, "ReadOnly Added", "Style = " & "Ox" & Hex($iStyle, 8))
GUICtrlSetData($hButton, $sBut_Sub)
GUICtrlSetData($hEdit, $sRead_Text)
Case 2
; Read the current style
$iStyle = _WinAPI_GetWindowLong($hEdit_Handle, $GWL_STYLE)
; Use BitXOR to SUBTRACT style
GUICtrlSetStyle($hEdit, BitXOR($iStyle, $ES_READONLY))
; Read the new style
$iStyle = _WinAPI_GetWindowLong($hEdit_Handle, $GWL_STYLE)
$iCount += 1
MsgBox(0, "ReadOnly Removed", "Style = " & "Ox" & Hex($iStyle, 8))
GUICtrlSetData($hButton, $sBut_Add)
GUICtrlSetData($hEdit, $sEdit_Text)
Case 3
; Read the current style
$iStyle = _WinAPI_GetWindowLong($hEdit_Handle, $GWL_STYLE)
; Use BitOR to ADD style
GUICtrlSetStyle($hEdit, BitOr($iStyle, $ES_READONLY))
; Read the new style
$iStyle = _WinAPI_GetWindowLong($hEdit_Handle, $GWL_STYLE)
$iCount += 1
GUICtrlSetData($hButton, "")
MsgBox(0, "ReadOnly Added", "Style = " & "Ox" & Hex($iStyle, 8))
GUICtrlSetData($hButton, $sBut_Sub)
GUICtrlSetData($hEdit, $sRead_Text)
Case 4
; Read the current style
$iStyle = _WinAPI_GetWindowLong($hEdit_Handle, $GWL_STYLE)
; Use BitAnd and BitNOT to SUBTRACT style
GUICtrlSetStyle($hEdit, BitAnd($iStyle, BitNOT($ES_READONLY)))
; Read the new style
$iStyle = _WinAPI_GetWindowLong($hEdit_Handle, $GWL_STYLE)
$iCount += 1
MsgBox(0, "ReadOnly Removed", "Style = " & "Ox" & Hex($iStyle, 8))
GUICtrlSetData($hButton, "Exit")
GUICtrlSetData($hEdit, $sEdit_Text)
Case 5
Exit
EndSwitch
EndSwitch
WEnd
</syntaxhighlight>
-----------------------------------
[[Summary]]

Setting styles is not difficult, but does require you to combine multiple styles correctly using ''BitOR''. And if you want to add or subtract styles for an existing control you need to remember to take the existing styles into account or you will not end up with the final result you wanted.

Managing Multiple GUIs

2012-04-28T15:31:51Z

Melba23:

Having several GUIs on the screen at the same time is fairly common - but structuring your code to deal with this can seem quite daunting. However, as I hope this tutorial will demonstrate, it is nowhere near as difficult as it first appears.

[[MessageLoop Mode]]

Let us start with ''MessageLoop'' mode as this is where most new coders run into difficulties with multiple GUIS. This example script illustrates the problem - it exits when the '''[X]''' is clicked on either GUI:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

Global $hButton3 = 9999

gui1()

Func gui1()

$hGUI1 = GUICreate("Gui 1", 200, 200, 100, 100)
$hButton1 = GUICtrlCreateButton("Msgbox 1", 10, 10, 80, 30)
$hButton2 = GUICtrlCreateButton("Show Gui 2", 10, 60, 80, 30)
GUISetState()

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
Case $hButton1
MsgBox("", "MsgBox 1", "Test from Gui 1")
Case $hButton2
GUICtrlSetState($hButton2, $GUI_DISABLE)
gui2()
Case $hButton3
MsgBox("", "MsgBox 2", "Test from Gui 2")
EndSwitch
WEnd

EndFunc ;==>gui1

Func gui2()

$hGUI2 = GUICreate("Gui 2", 200, 200, 350, 350)
$hButton3 = GUICtrlCreateButton("MsgBox 2", 10, 10, 80, 30)
GUISetState()

EndFunc ;==>gui2
</syntaxhighlight>
-----------------------------------
The script exits because it has a single ''GUIGetMsg'' loop and the ''$GUI_EVENT_CLOSE'' message is received when either '''[X]''' is clicked - we have no way of telling the messages from the 2 GUIs apart.

The simplest solution is to disable the first GUI while the second is displayed:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

gui1()

Func gui1()

$hGUI1 = GUICreate("Gui 1", 200, 200, 100, 100)
$hButton1 = GUICtrlCreateButton("Msgbox 1", 10, 10, 80, 30)
$hButton2 = GUICtrlCreateButton("Show Gui 2", 10, 60, 80, 30)
GUISetState()

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
Case $hButton1
MsgBox("", "MsgBox 1", "Test from Gui 1")
Case $hButton2
; Disable the first GUI
GUISetState(@SW_DISABLE, $hGUI1)
gui2()
; Re-enable the first GUI
GUISetState(@SW_ENABLE, $hGUI1)
EndSwitch
WEnd

EndFunc ;==>gui1

Func gui2()

$hGUI2 = GUICreate("Gui 2", 200, 200, 350, 350)
$hButton3 = GUICtrlCreateButton("MsgBox 2", 10, 10, 80, 30)
GUISetState()

While 1
; We can only get messages from the second GUI
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
GUIDelete($hGUI2)
ExitLoop
Case $hButton3
MsgBox("", "MsgBox 2", "Test from Gui 2")
EndSwitch
WEnd

EndFunc ;==>gui2
</syntaxhighlight>
-----------------------------------
This may well be all you need, but it does mean that we cannot action any of the controls on the first GUI until we close the second. And importantly we remain blocked in the ''While...WEnd'' loop within the ''gui2'' function - go and read the "''Interrupting a running function''" tutorial to see why this is less than ideal.

So how can we deal with multiple GUIs visible at the same time? Fortunately AutoIt offers us a simple way to differentiate between GUIs in ''MessageLoop'' mode. Normally we use code like this in our idle loop to detect the messages sent by our GUI and its controls:
-----------------------------------
<syntaxhighlight lang="autoit">
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
; Code
Case $hButton1
; Code
EndSwitch
</syntaxhighlight>
-----------------------------------
But when dealing with multiple GUIs, we need to use the "''advanced''" parameter when we call ''GUIGetMsg''. As explained in the Help file, the function then returns an array instead of a single value. This array includes information on what exactly triggered the message, just what we need to distinguish the message that was sent (element['''0'''] of the array) and which GUI sent it (element['''1''']). We can then amend our simple Switch statement above to read like this:
-----------------------------------
<syntaxhighlight lang="autoit">
$aMsg = GUIGetMsg(1) ; Use advanced parameter to get an array returned
Switch $aMsg[1] ; First check which GUI sent the message
Case $hGUI1
Switch $aMsg[0] ; Now check for the messages sent from $hGUI1
Case $GUI_EVENT_CLOSE
; Code
Case $hControl
; Code
EndSwitch
Case $hGUI2
Switch $aMsg[0] ; Now check for the messages sent from $hGUI2
Case $GUI_EVENT_CLOSE
; Code
Case $hButton3
; Code
EndSwitch
EndSwitch
</syntaxhighlight>
-----------------------------------
Although this looks complicated, if you take a moment to study it and you will quickly realise it is simply 2 ''Switch'' structures within an outer ''Switch''. You have already dealt with a single ''Switch'' structure for a single GUI - all you are doing here is determining which ''Switch'' structure you want to use. And that depends on the GUI which sent the message, which is why we need the outer ''Switch'' structure as a wrapper.

So here an example of how to manage 2 GUIs simultaneously using the "''advanced''" parameter with ''GUIGetMsg'':
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

Global $hGUI2 = 9999, $hButton3 = 9999 ; Predeclare the variables with dummy values to prevent firing the Case statements

gui1()

Func gui1()

$hGUI1 = GUICreate("Gui 1", 200, 200, 100, 100)
$hButton1 = GUICtrlCreateButton("Msgbox 1", 10, 10, 80, 30)
$hButton2 = GUICtrlCreateButton("Show Gui 2", 10, 60, 80, 30)
GUISetState()

While 1
$aMsg = GUIGetMsg(1) ; Use advanced parameter to get array
Switch $aMsg[1] ; check which GUI sent the message
Case $hGUI1
Switch $aMsg[0] ; Now check for the messages for $hGUI1
Case $GUI_EVENT_CLOSE ; If we get the CLOSE message from this GUI - we exit <<<<<<<<<<<<<<<
ExitLoop
Case $hButton1
MsgBox("", "MsgBox 1", "Test from Gui 1")
Case $hButton2
GUICtrlSetState($hButton2, $GUI_DISABLE)
gui2()
EndSwitch
Case $hGUI2
Switch $aMsg[0] ; Now check for the messages for $hGUI2
Case $GUI_EVENT_CLOSE ; If we get the CLOSE message from this GUI - we just delete the GUI <<<<<<<<<<<<<<<
GUIDelete($hGUI2)
GUICtrlSetState($hButton2, $GUI_ENABLE)
Case $hButton3
MsgBox("", "MsgBox", "Test from Gui 2")
EndSwitch
EndSwitch
WEnd

EndFunc ;==>gui1

Func gui2()

$hGUI2 = GUICreate("Gui 2", 200, 200, 350, 350)
$hButton3 = GUICtrlCreateButton("MsgBox 2", 10, 10, 80, 30)
GUISetState()

EndFunc ;==>gui2
</syntaxhighlight>
-----------------------------------
As you can see, we have a single ''While...WEnd'' loop which distinguishes between the 2 GUIs, both GUIs and their controls remain active and we stay in the main idle loop while we wait (you did read that other tutorial I hope!).

[[OnEvent Mode]]

Coders using ''OnEvent'' mode do not usually find the same problem with multiple GUIs as they can code separate functions for each ''$GUI_EVENT_CLOSE'' as shown here:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

Opt("GUIOnEventMode", 1)

Global $hGUI2, $hButton2 ; Predeclare these variables

gui1()

Func gui1()

$hGUI1 = GUICreate("Gui 1", 200, 200, 100, 100)
GUISetOnEvent($GUI_EVENT_CLOSE, "On_Close_Main") ; Run this function when the main GUI [X] is clicked
$hButton1 = GUICtrlCreateButton("Msgbox 1", 10, 10, 80, 30)
GUICtrlSetOnEvent(-1, "On_Button1")
$hButton2 = GUICtrlCreateButton("Show Gui 2", 10, 60, 80, 30)
GUICtrlSetOnEvent(-1, "On_Button2")
GUISetState()

While 1
Sleep(10)
WEnd

EndFunc ;==>gui1

Func gui2()

$hGUI2 = GUICreate("Gui 2", 200, 200, 350, 350)
GUISetOnEvent($GUI_EVENT_CLOSE, "On_Close_Secondary") ; Run this function when the secondary GUI [X] is clicked
$hButton3 = GUICtrlCreateButton("MsgBox 2", 10, 10, 80, 30)
GUICtrlSetOnEvent(-1, "On_Button3")
GUISetState()

EndFunc ;==>gui2

Func On_Close_Main()

Exit

EndFunc

Func On_Close_Secondary()

GUIDelete($hGUI2)
GUICtrlSetState($hButton2, $GUI_ENABLE)

EndFunc

Func On_Button1()

MsgBox("", "MsgBox 1", "Test from Gui 1")

EndFunc

Func On_Button2()

GUICtrlSetState($hButton2, $GUI_DISABLE)
gui2()

EndFunc

Func On_Button3()

MsgBox("", "MsgBox 2", "Test from Gui 2")

EndFunc
</syntaxhighlight>
-----------------------------------
But did you realise that you can also use what some people think of as a hybrid mode - using common ''OnEvent'' functions and then determining the specific GUI or control which called the function within the function? As an added bonus, this approach may, depending on the circumstances, let you send parameters to the functions you call - something that you normally cannot do in ''OnEvent'' mode.
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

Opt("GUIOnEventMode", 1)

Global $hGUI1, $hGUI2 = 9999, $hButton1, $hButton2, $hButton3 = 9999 ; Predeclare the variables with dummy values to prevent firing the Case statements

gui1()

Func gui1()

$hGUI1 = GUICreate("Gui 1", 200, 200, 100, 100)
GUISetOnEvent($GUI_EVENT_CLOSE, "On_Close") ; Call a common GUI close function
$hButton1 = GUICtrlCreateButton("Msgbox 1", 10, 10, 80, 30)
GUICtrlSetOnEvent(-1, "On_Button") ; Call a common button function
$hButton2 = GUICtrlCreateButton("Show Gui 2", 10, 60, 80, 30)
GUICtrlSetOnEvent(-1, "On_Button") ; Call a common button function
GUISetState()

While 1
Sleep(10)
WEnd

EndFunc ;==>gui1

Func gui2()

$hGUI2 = GUICreate("Gui 2", 200, 200, 350, 350)
GUISetOnEvent($GUI_EVENT_CLOSE, "On_Close") ; Call a common GUI close function
$hButton3 = GUICtrlCreateButton("MsgBox 2", 10, 10, 80, 30)
GUICtrlSetOnEvent(-1, "On_Button") ; Call a common button function
GUISetState()

EndFunc ;==>gui2

Func On_Close()

Switch @GUI_WINHANDLE ; See which GUI sent the CLOSE message
Case $hGUI1
Exit ; If it was this GUI - we exit <<<<<<<<<<<<<<<
Case $hGUI2
GUIDelete($hGUI2) ; If it was this GUI - we just delete the GUI <<<<<<<<<<<<<<<
GUICtrlSetState($hButton2, $GUI_ENABLE)
EndSwitch

EndFunc

Func On_Button()

Switch @GUI_CTRLID ; See which button sent the message
Case $hButton1
MessageBox(1) ; We can call a function with parameters here <<<<<<<<<<<<<<<<<<<
Case $hButton2
GUICtrlSetState($hButton2, $GUI_DISABLE)
gui2()
Case $hButton3
MessageBox(2) ; We can call a function with parameters here <<<<<<<<<<<<<<<<<<<
EndSwitch

EndFunc

Func MessageBox($iIndex)

MsgBox("", "MsgBox " & $iIndex, "Test from Gui " & $iIndex)

EndFunc
</syntaxhighlight>
-----------------------------------
So you see that managing multiple GUIS is not as difficult as you might think. One of these methods is bound to suit your script, but do not try and mix them - only one method per script please!

Tutorial GUIRegisterMsg

2012-04-28T15:28:25Z

Melba23:

Here is a short tutorial on ''GUIRegisterMsg'' - one of the more mysterious functions within AutoIt for newcomers. Purists might quibble over details here, but it is good enough for hobbyists like me!

Windows works by sending messages to everything on the system, so that everything knows what is going on. By messages, I mean things like the ''$GUI_EVENT_CLOSE'' we look for when we exit a GUI - but the possible range is much, much wider; change of focus, change of state, mouseclicks, mousemoves, key presses, etc, etc, etc.

''GUIRegisterMsg'' allows us to intercept certain of these messages as they are sent by the GUIs we have created, so we can see who sent what. So when you see a ''GUIRegisterMsg($WM_COMMAND, "MY_WM_COMMAND")'' line in a script, this translates as "''Whenever a WM_COMMAND message is sent by my GUI, please intercept it and pass it through the MY_WM_COMMAND function in this script''". The actual message title is denoted by the constant ''$WM_COMMAND'' which is stored in ''WindowsConstant.au3'' include file. Of course, you can use other message types as well (such as ''$WM_NOTIFY'') - and call your function whatever you wish!

The function that you use ''GUIRegisterMsg'' to call '''MUST''' have these 4 parameters - ''$hWnd, $iMsg, $wParam, $lParam'' - because that is what Windows uses itself to pass the messages around. In the majority of cases, these parameters relate to the following:

*''$hWnd'' - the GUI which sent the message
*''$iMsg'' - the code for the message sent
*''$wParam, $iParam'' - details of what exactly the message is about. This varies according to the message and details can be found in MSDN but often these parameters will hold the identity of control that has been used and the exact version of the message that has been sent.

Let us look at some examples:
-----------------------------------
<syntaxhighlight lang="autoit">
GUIRegisterMsg($WM_COMMAND, "MY_WM_COMMAND")
;
Func MY_WM_COMMAND($hWnd, $iMsg, $wParam, $lParam)
;
Local $iIDFrom = BitAND($wParam, 0xFFFF) ; LoWord - this gives the control which sent the message
Local $iCode = BitShift($wParam, 16) ; HiWord - this gives the message that was sent
If $iCode = $EN_CHANGE Then ; If we have the correct message
Switch $iIDFrom ; See if it comes from one of the inputs
Case $hInput1
; Do something
Case $hInput2
; Do something else
EndSwitch
EndIf
;
EndFunc ;==>MY_WM_COMMAND
</syntaxhighlight>
-----------------------------------
Here we are looking to see if the contents of two Input controls have been altered. We first intercept the ''$WM_COMMAND'' messages from our GUI using ''GUIRegisterMsg''. We can ignore the GUI and the main message in this case - ''$WM_COMMAND'' is a huge set and as we are interested in the control we need not worry about the GUI - if we correctly identify the control, it can only come from our GUI! But in other cases, this is vital information, as you can imagine.

To see if an Input has been altered, we need to look for the ''$EN_CHANGE'' submessage and as you can see we need to investigate the contents of ''$wParam'' to determine this - and then determine the identity of the Input control which is also obtained from'' $wParam'' (MSDN is the bible here). The ''Bit*'' operators allow us to extract these values:
-----------------------------------
<syntaxhighlight lang="autoit">
Local $iIDFrom = BitAND($wParam, 0xFFFF) ; LoWord - this gives the ControlID of the control which sent the message
Local $iCode = BitShift($wParam, 16) ; HiWord - this gives the submessage that was sent
</syntaxhighlight>
-----------------------------------
We now know which control sent the message and what the sub-message was - so we check if it matches what we are looking for and if it does then we do whatever we need to do:

Another example:
-----------------------------------
<syntaxhighlight lang="autoit">
GUIRegisterMsg($WM_NOTIFY, "MY_WM_NOTIFY")
;
Func MY_WM_NOTIFY($hWnd, $iMsg, $wParam, $lParam)
;
Local $tNMHDR = DllStructCreate("int;int;int", $lParam)
If @error Then Return
If DllStructGetData($tNMHDR, 1) = $hLV_Handle Then ; Is it our ListView
If DllStructGetData($tNMHDR, 3) = $NM_DBLCLK Then $fDblClk = True ; Was it a double click
EndIf
$tNMHDR = 0 ; This not strictly necessary but does not hurt!
;
Return $GUI_RUNDEFMSG ; This tells AutoIt to process the message itself
;
EndFunc ;==>MY_WM_NOTIFY
</syntaxhighlight>
-----------------------------------
This time we are trapping the ''$WM_NOTIFY'' message which lets us know about events like mouse clicks. In particular we are looking for a double click on a ListView within our GUI. As above we use ''GUIRegisterMsg'' to intercept the message. Again we can ignore the GUI and main message and just look for the control and submessage. In this case we need to do a bit more work on the ''$lParam'' parameter which is actually a ''Struct''. However, AutoIt again makes it easy to obtain the handle of the control and the actual submessage - if these are the correct ones, we set a flag to ''True''. Why, well keep reading and you will find out!

When we have finished dealing with the message we have intercepted, it gets passed along the chain of all the other message handlers so all the other applications in the system can see if they are interested too. But in some cases you might actually want to stop the message going further - I wrote a UDF to prevent the system adding the dotted lines around the control when it has focus and passing the message on was exactly what I was trying to prevent! So in the UDF I added a ''Return'' line to the function to stop it dead - just as here. Returning the ''$GUI_RUNDEFMSG'' constant tells AutoIt to run its own internal message handler.

Now, what about the use of a flag in the second example? Well, if you read the Help file for ''GUIRegisterMsg'' you will see the following:

"''Warning: blocking of running user functions which execute Windows messages with commands such as "Msgbox()" can lead to unexpected behavior, the return to the system should be as fast as possible !!!''"

Basically, if you spend too long in your message handling function, the rest of the system gets behind and becomes unstable. So you should get out of it as quickly as you can - and certainly never create anything that waits for user input.

There are 2 ways we can still run something long and complicated but still leave the handler quickly: either set a flag or action a dummy control. If we set a flag inside the handler, we can then look for it within our idle loop and run our blocking code from here without affecting the handler at all. If we action a dummy control then we do not even have to look for the flag! Here is an example of both methods to show you how to apply them.
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#include<WindowsConstants.au3>

; Whichever method we use, we need to declare the dummy control or the flag as a Global variable
Global $hLeftClick, $fRightClick = False

GUICreate("Click me!")

; Create a dummy control for the handler to action
$hLeftClick = GUICtrlCreateDummy()

GUISetState()

; Register our messages
GUIRegisterMsg($WM_LBUTTONUP, "_WM_LBUTTONUP")
GUIRegisterMsg($WM_RBUTTONUP, "_WM_RBUTTONUP")

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ExitLoop
Case $hLeftClick
; Our dummy control was actioned so run the required code
MsgBox(0, "Click", "LEFT CLICK!")
EndSwitch

; Look for the flag
If $fRightClick = True Then
; Run the code
MsgBox(0, "Click", "RIGHT CLICK!")
; Do not forget to reset the flag!
$fRightClick = False
EndIf

WEnd

Func _WM_LBUTTONUP($hWnd, $iMsg, $wParam, $lParam)
; Action the dummy control
GUICtrlSendToDummy($hLeftClick)
EndFunc

Func _WM_RBUTTONUP($hWnd, $iMsg, $wParam, $lParam)
; Set the flag
$fRightClick = True
EndFunc
</syntaxhighlight>
-----------------------------------
I hope this short tutorial has made ''GUIRegisterMsg'' a little less complicated. Now I suggest you go and look at the many examples on the forum to see how they work and how each differs slightly depending on exactly the author is trying to do.

Interrupting a running function

2012-04-28T15:27:07Z

Melba23:

This is a common question and this tutorial explains how to do it within the limitations of Autoit.

AutoIt queues function calls in both ''OnEvent'' and ''MessageLoop'' modes. This means that it waits until a function is finished and the code is back in your idle ''While...WEnd'' loop before running the next.

Here are 2 short scripts in both modes to show this in action. Start ''Function 1'' by pressing its button and then immediately try to run ''Function 2'' by pressing its button a couple of times. You will see from the console output that ''Function 2'' will only run '''AFTER''' ''Function 1'' has terminated - and then it will run as many times as you pressed the button.

We start with ''MessageLoop'' mode:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

$hGUI = GUICreate("Test", 500, 500)

$hButton_1 = GUICtrlCreateButton("Func One", 10, 10, 80, 30)
$hButton_2 = GUICtrlCreateButton("Func Two", 10, 50, 80, 30)

GUISetState()

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
Case $hButton_1
_Func_1()
Case $hButton_2
_Func_2()
EndSwitch
WEnd

Func _Func_1()
For $i = 1 To 20
ConsoleWrite("-Func 1 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 1 Ended" & @CRLF)
EndFunc

Func _Func_2()
For $i = 1 To 3
ConsoleWrite("+Func 2 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 2 Ended" & @CRLF)
EndFunc
</syntaxhighlight>
-----------------------------------
And now in ''OnEvent'' mode:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

Opt("GUIOnEventMode", 1)

$hGUI = GUICreate("Test", 500, 500)
GUISetOnEvent($GUI_EVENT_CLOSE, "_Exit")

$hButton_1 = GUICtrlCreateButton("Func One", 10, 10, 80, 30)
GUICtrlSetOnEvent($hButton_1, "_Func_1")
$hButton_2 = GUICtrlCreateButton("Func Two", 10, 50, 80, 30)
GUICtrlSetOnEvent($hButton_2, "_Func_2")

GUISetState()

While 1
Sleep(10)
WEnd

Func _Func_1()
For $i = 1 To 20
ConsoleWrite("-Func 1 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 1 Ended" & @CRLF)
EndFunc

Func _Func_2()
For $i = 1 To 3
ConsoleWrite("+Func 2 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 2 Ended" & @CRLF)
EndFunc

Func _Exit()
Exit
EndFunc
</syntaxhighlight>
-----------------------------------
So is it impossible to interrupt a running function? Of course not or this tutorial would serve no purpose - but there are limitations on the type of function which can be interrupted.

If you are in ''OnEvent'' mode then there is an easy way to interrupt a running function, as long as the function is started within the main code and not by an ''OnEvent'' call. This script shows how to do it by using a flag and checking if it is set - in this way the function is started by the main script and can be interrupted.
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

; Declare a flag
Global $fRunOne = False

Opt("GUIOnEventMode", 1)

$hGUI = GUICreate("Test", 500, 500)
GUISetOnEvent($GUI_EVENT_CLOSE, "_Exit")

$hButton_1 = GUICtrlCreateButton("Func One", 10, 10, 80, 30)
GUICtrlSetOnEvent($hButton_1, "_Func_1")
$hButton_2 = GUICtrlCreateButton("Func Two", 10, 50, 80, 30)
GUICtrlSetOnEvent($hButton_2, "_Func_2")

GUISetState()

While 1
Sleep(10)
; Check if the flag has been set by the OnEvent function
If $fRunOne Then
; Now start the "real" function from within the main code
_Func_1_Run()
EndIf
WEnd

Func _Func_1()
; Set the flag within the OnEvent function
$fRunOne = True
EndFunc ;==>_Func_1

Func _Func_1_Run()
For $i = 1 To 20
ConsoleWrite("-Func 1 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 1 Ended" & @CRLF)
Global $fRunOne = False
EndFunc ;==>_Func_1_Run

Func _Func_2()
For $i = 1 To 3
ConsoleWrite("+Func 2 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 2 Ended" & @CRLF)
EndFunc ;==>_Func_2

Func _Exit()
Exit
EndFunc ;==>_Exit
</syntaxhighlight>
-----------------------------------
However, this method does not work in ''MessageLoop'' mode, not when you want to interrupt a function which was started by an ''OnEvent'' call in ''OnEvent'' mode. In these cases the function you want to interrupt must have regular checks of a flag which we set when we want to interrupt. If the function does not have a suitable loop where such a check is easy to make, you might not be able to interrupt it.

Let us now look at the 2 ways an AutoIt script can break into a suitable function: a '''HotKey''' and a '''Windows message handler'''. The first is easier to code, but cannot be linked to a control on your GUI; the latter is a little more complicated to code, but can be linked to a control.

How do they work?

Let us start with the ''HotKey''. From the AutoIt Help file: ''A hotkey-press *typically* interrupts the active AutoIt function/statement and runs its user function until it completes or is interrupted''. So a ''HotKey'' press is designed to interrupt your running function - just what we need. But the running function will resume after the ''HotKey'' function terminates - so, as explained above, we use the ''HotKey'' function to set a flag which is looked for by our running function. Remember that this flag must be declared as a ''Global'' variable because it needs to be seen by both functions.

Now many coders do not like using ''HotKey''s because they remain active while a script is running and can interfere with other apps. One way to get around this is to use ''Accelerator'' keys - these look very much like ''HotKey''s to the user, but are only active in the script in which they are declared. Although ''Accelerator'' keys look like ''HotKey''s, they are tied to GUI controls and you must use the ''message handler'' method explained below if you want to use them to interrupt a running function.

The ''Windows message handler'' method is a little more complicated and if you are not used to working with them, you might want to read the [[GUIRegisterMsg]] tutorial first.

What we do here is intercept the message that your GUI control sends when it is activated - the same message that AutoIt queues to run the required code once the running function terminates. We use our own message to get a sneak preview of this queuing and use it to set a similar flag to that described above. If our running function sees the flag, it terminates and AutoIt then runs the function waiting in the queue - simple really!

Here are scripts using both methods to show how ''HotKey''s, ''Accelerator'' keys and GUI controls can interrupt a running function. Just as before, start ''Function_1'' by pressing its button - but now you can interrupt it at will!

First in ''MessageLoop'' mode:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#include <WindowsConstants.au3>

; Set a HotKey
HotKeySet("x", "_Interrupt")

; Declare a flag
$fInterrupt = 0

$hGUI = GUICreate("Test", 500, 500)

$hButton_1 = GUICtrlCreateButton("Func One", 10, 10, 80, 30)
$hButton_2 = GUICtrlCreateButton("Func Two", 10, 50, 80, 30)

; Create a dummy control for the Accelerator to action when pressed
$hAccelInterupt = GUICtrlCreateDummy()
; Set an Accelerator key to action the dummy control
Dim $AccelKeys[1][2]=[ ["z", $hAccelInterupt] ]
GUISetAccelerators($AccelKeys)

GUISetState()

; Intercept Windows command messages with out own handler
GUIRegisterMsg($WM_COMMAND, "_WM_COMMAND")

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
Case $hButton_1
_Func_1()
Case $hButton_2
_Func_2()
EndSwitch
WEnd

Func _Func_1()
; Make sure the flag is cleared
$fInterrupt = 0
For $i = 1 To 20
ConsoleWrite("-Func 1 Running" & @CRLF)
; Look for the flag
If $fInterrupt <> 0 Then
; The flag was set
Switch $fInterrupt
Case 1
ConsoleWrite("!Func 1 interrrupted by Func 2" & @CRLF)
Case 2
ConsoleWrite("!Func 1 interrrupted by HotKey" & @CRLF)
Case 3
ConsoleWrite("!Func 1 interrrupted by Accelerator" & @CRLF)
EndSwitch
Return
EndIf
Sleep(100)
Next
ConsoleWrite(">Func 1 Ended" & @CRLF)
EndFunc

Func _Func_2()
For $i = 1 To 3
ConsoleWrite("+Func 2 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 2 Ended" & @CRLF)
EndFunc

Func _Interrupt()
; The HotKey was pressed so set the flag
$fInterrupt = 2
EndFunc

Func _WM_COMMAND($hWnd, $Msg, $wParam, $lParam)
; The Func 2 button was pressed so set the flag
If BitAND($wParam, 0x0000FFFF) = $hButton_2 Then $fInterrupt = 1
; The dummy control was actioned by the Accelerator key so set the flag
If BitAND($wParam, 0x0000FFFF) = $hAccelInterupt Then $fInterrupt = 3
Return $GUI_RUNDEFMSG
EndFunc ;==>_WM_COMMAND
</syntaxhighlight>
-----------------------------------
And now in ''OnEvent'' mode:
-----------------------------------
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>
#include <WindowsConstants.au3>

; Set a HotKey
HotKeySet("x", "_Interrupt_HotKey")

; Declare a flag
$fInterrupt = 0

Opt("GUIOnEventMode", 1)

$hGUI = GUICreate("Test", 500, 500)
GUISetOnEvent($GUI_EVENT_CLOSE, "_Exit")

$hButton_1 = GUICtrlCreateButton("Func One", 10, 10, 80, 30)
GUICtrlSetOnEvent($hButton_1, "_Func_1")
$hButton_2 = GUICtrlCreateButton("Func Two", 10, 50, 80, 30)
GUICtrlSetOnEvent($hButton_2, "_Func_2")

; Create a dummy control for the Accelerator to action
$hAccelInterupt = GUICtrlCreateDummy()
GUICtrlSetOnEvent($hAccelInterupt, "_Interrupt_Accel")
; Set an Accelerator key to action the dummy control
Dim $AccelKeys[1][2]=[ ["z", $hAccelInterupt] ]
GUISetAccelerators($AccelKeys)

GUISetState()

; Intercept Windows command messages with out own handler
GUIRegisterMsg($WM_COMMAND, "_WM_COMMAND")

While 1
Sleep(10)
WEnd

Func _Func_1()
; Make sure the flag is cleared
$fInterrupt = 0
For $i = 1 To 20
ConsoleWrite("-Func 1 Running" & @CRLF)
; Look for the flag
If $fInterrupt <> 0 Then
; The flag was set
Switch $fInterrupt
Case 1
ConsoleWrite("!Func 1 interrrupted by Func 2" & @CRLF)
Case 2
ConsoleWrite("!Func 1 interrrupted by HotKey" & @CRLF)
Case 3
ConsoleWrite("!Func 1 interrrupted by Accelerator" & @CRLF)
EndSwitch
Return
EndIf
Sleep(100)
Next
ConsoleWrite(">Func 1 Ended" & @CRLF)
EndFunc

Func _Func_2()
For $i = 1 To 3
ConsoleWrite("+Func 2 Running" & @CRLF)
Sleep(100)
Next
ConsoleWrite(">Func 2 Ended" & @CRLF)
EndFunc

Func _Exit()
Exit
EndFunc

Func _Interrupt_HotKey()
; The HotKey was pressed so set the flag
$fInterrupt = 2
EndFunc

Func _Interrupt_Accel()
; This is an empty function for the dummy control linked to the Accelerator key
EndFunc

Func _WM_COMMAND($hWnd, $Msg, $wParam, $lParam)
; The Func 2 button was pressed so set the flag
If BitAND($wParam, 0x0000FFFF) = $hButton_2 Then $fInterrupt = 1
; The dummy control was actioned by the Accelerator key so set the flag
If BitAND($wParam, 0x0000FFFF) = $hAccelInterupt Then $fInterrupt = 3
Return $GUI_RUNDEFMSG
EndFunc ;==>_WM_COMMAND
</syntaxhighlight>
-----------------------------------
So there are the ways available in AutoIt to interrupt a running function. Remember that you must be in ''OnEvent'' mode and start the function from the main code - or have a function which checks internally whether it ought to allow an interruption. In all other cases you are are not going to be able to interrupt your function.