Function Notes

Functions in AutoIt are first class objects. Among other things, that means you can assign a function to a variable, pass it around as an argument or return from another function.
Aside from certain specific scope-regarding declaration rules (being that the names of the built-in functions are reserved and of UDFs' can be overwritten only locally), the names of functions do not have special status in the language.

#include <MsgBoxConstants.au3>

Local $vFunc = MsgBox

$vFunc($MB_OK, "Hi there!", "Lovely day today.")

 

Many functions contain optional parameters that can be omitted. If you wish to specify an optional parameter, however, all preceding parameters must be specified!
For example, consider Run ( "filename", ["workingdir" [, flag]] ). If you wish to specify the flag, you must specify a workingdir.

Many Win___ functions contain an optional parameter "text". This parameter is intended to help differentiate between windows that have identical titles.


Some functions indicate success/failure as a return value, others indicate it by setting the @error flag. Some do both....
@error = 0 ;is always success
Return = varies, but is typically non-zero for success to allow easy to read code...

If SomeUserFunc() Then ;...function worked.
If Not SomeUserFunc() Then ;...function failed.

Local $sFileRead = FileReadLine("C:\someFile.txt")
If @error = -1 Then ; End-of-file was reached.

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

@error is always set to 0 when entering in a function.

When the documentation states that the return value = none, AutoIt always returns a value to avoid errors. 1 is usually the value returned, but you should not depend on this return value.

When an optional parameter needs to be defined and is preceded by one or more optional parameters, the default value must be given for that parameter. Generally speaking functions should accept the Default keyword when you wish to use the default parameter. See the corresponding optional parameter description for more details.