AutoIt Wiki - User contributions [en]

Talk:UDF-spec

2013-04-28T04:42:17Z

Mdiesel: /* Variable naming conventions */ new section

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

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

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

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

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

== Coding Practice ==

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

Useful links:

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

--[[User:Mdiesel|Mdiesel]] ([[User talk:Mdiesel|talk]]) 01:38, 7 January 2013 (UTC)

== Variable naming conventions ==

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

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

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

Talk:Helpfile-Changes

2013-02-14T12:54:48Z

Mdiesel:

This page is just to keep track of all the large, and part-completed projects on the helpfile and UDFs.

If you update an item on this page, there is a good chance the user concerned won't notice unless you pm them about it too.

Talk:Helpfile-Changes

2013-01-31T03:04:21Z

Mdiesel: Created page with " This page is just to keep track of all the large, and part-completed projects on the helpfile and UDFs."

This page is just to keep track of all the large, and part-completed projects on the helpfile and UDFs.

Helpfile-Changes

2013-01-31T00:57:02Z

Mdiesel: Created page with "This page is for keeping track of changes currently in the process of being made to the AutoIt3 helpfile and UDFs by the MVPs. == Doc changes == * Shutdown parameter 2 (Mat)..."

This page is for keeping track of changes currently in the process of being made to the AutoIt3 helpfile and UDFs by the MVPs.

== Doc changes ==

* Shutdown parameter 2 (Mat)
** Parameter meaning is too complex and not really usable. Suggested removing from docs completely.

* Magic number removal (Mat)
** Document existing constants (in progress)
** Create new constants where required (making a list)
** Replace magic numbers in existing examples (Mat working on script to automate)

* [http://www.autoitscript.com/forum/topic/146560-report-help-file-issues-here/page__st__120#entry1048490 AZJIO post #135]
** RegRead type table (Mat), in progress
** IniRead return type (done)
** _ArrayDisplay $sheader (done in txtLibFunctions, not in UDF header)
** _GUICtrlComboBox_ReplaceEditSel
** _GUICtrlComboBox_ShowDropDown
** _GUICtrlComboBox_AddString
** _GUICtrlComboBox_SetCueBanner

* General Example improvements
** Update examples to use multiple example functionality.
** Remove magic numbers!
** Make sure no permanent changes are made to system.
** Update examples to make use of new AutoIt features where appropriate.

== UDF changes ==

* Fixed buffer sizes (as per [http://www.autoitscript.com/forum/topic/147486-ticket-1336/ thread] and ticket 1336)
* [http://www.autoitscript.com/forum/topic/144746-winapiexau3-splitting-proposal/ WinAPIEx Splitting] (Jpm)

UDF-spec

2013-01-29T23:43:33Z

Mdiesel: /* Basic Requirements */

[[Category:UDF]]
{{WIP}}This page is still under construction.

----

A library is a collection of one or more User Defined Functions (UDFs). However, the term UDF is often used to describe the collection as a whole. If a UDF is to be considered for inclusion in the standard set distributed with AutoIt then it must meet all the criteria detailed here, but it's also good practice to always write in conformance with at least the majority of this document, as that is what will be expected by people reading your code later.

== Basic Requirements ==
Firstly, the code itself should meet the following basic requirements:

* Be tidied. Just hit <code>Ctrl+T</code> from SciTE or run Tidy manually. The only flag needed is <code>/sf</code>.
* Pass Au3Check with no errors using the strictest settings: <code>-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7</code>
* Support everything AutoIt supports. In some cases features may not be able to support everything, in which case this should be checked for and return errors appropriately. This applies to: windows OS versions (AutoIt has support for all OS' from windows 2000), unicode and ansi strings, 64 and 32 bit machines.
* Ideally it will be able to run cleanly when obfuscated. Although there will be some cases where this is not possible, please consider it when writing UDFs, and avoid the use of Execute and similar statements. If it does not, then document it as such.
* Not use any magic numbers. Ever. None. At all. No excuses.

== UDF Outline ==
The library itself has a header that details important information such as the minimum OS and AutoIt versions, and what system dlls are required. There is also a number of other sections that are required that list what is present in the UDF.

=== Includes ===
Since a UDF is designed to define functions, it should only be included once. As a result, the <code>#include-once</code> directive should be used. This is typically the first line of the UDF, followed by the includes used by the UDF. Include statements should use the double quoted form, as the library is expected to work in the same directory as libraries it depends on. Non standard libraries can be used if necessary, but this should be documented and linked to so users can download it as well. It goes without saying that a UDF based on non-standard UDFs cannot itself become a standard.

=== Index ===
The index follows the following template (taken from <code>WinAPI.au3</code>):

<syntaxhighlight lang="autoit">; #INDEX# =======================================================================================================================
; Title .........: Windows API
; AutoIt Version : 3.2
; Description ...: Windows API calls that have been translated to AutoIt functions.
; Author(s) .....: Paul Campbell (PaulIA), gafrost, Siao, Zedna, arcker, Prog@ndy, PsaltyDS, Raik, jpm
; Dll ...........: kernel32.dll, user32.dll, gdi32.dll, comdlg32.dll, shell32.dll, ole32.dll, winspool.drv
; ===============================================================================================================================</syntaxhighlight>

The only required element in the index header is <code>Title</code>. All others are ignored by the processor, but should be included for reference

The <code>Dll</code> field can remain empty in many cases where no dlls are called directly. This header must be defined.

=== Other Sections ===
Other sections, in order of appearance, are as follows.

==== Variables ====
All global variables needed to be declared in the UDF are defined in this section. They should follow the variable rules for globals. Individual variables do not need to be documented, as it is assumed they are for internal use only. Any globals designed to be accessible for the user should instead be wrapped by a function (or multiple functions if globals must be retrieved and set). The template for this section is:

<syntaxhighlight lang="autoit">; #VARIABLES# ===================================================================================================================
Global $__gvMyGlobal = 0
; ===============================================================================================================================</syntaxhighlight>

If no globals are needed then this section may be ommitted. Please consider the use of global variables carefully, and read through the section on global variables.

==== Constants ====
Any global constant values are defined in this section. This should be constants only designated for use within the library itself. Constants that may be needed by the user should be defined in a separate file, named <code>UDFConstants.au3</code> where <code>UDF</code> is the name of the parent file. For example <code>File.au3</code> uses constants defined in <code>FileConstants.au3</code>. The exception to that rule is control UDFs which miss out the prepended 'GUI' when naming constant files, so <code>GUIButton.au3</code> uses constants from <code>ButtonConstants.au3</code>. The template for this section is:

<syntaxhighlight lang="autoit">; #CONSTANTS# ===================================================================================================================
Global Const $__MYUDFCONSTANT_FOOBAR = 42
; ===============================================================================================================================</syntaxhighlight>

If no constants are needed in this section, either because none are used or because they are stored in a separate file, then it may be ommitted. Please read the section on global constants for specific info on naming and definition of constants.

==== Listing ====
This defines all functions and structures currently used functions in the library. It MUST be the second defined header item after [[#Index]]. It is a simple list with each function on a line where the functions and structures appear in the same order as they do in the code, which is alphabetical order and structures first. A simple way to generate this list is to create a small script that searches for function definitions and outputs them in the correct format, an example of which is [http://www.autoitscript.com/forum/topic/120820-function-name-lister/ here]. In addition there is a second section that lists functions and structures for internal use only, this does not need to appear if none are defined.

The template for these sections are:

<syntaxhighlight lang="autoit">; #CURRENT# =====================================================================================================================
;$tagSTRUCT
;_MyUDF_Function
; ===============================================================================================================================

; #INTERNAL_USE_ONLY# ===========================================================================================================
;$tagINTERNALSTRUCT
;__MyUDF_InternalFunction
; ===============================================================================================================================</syntaxhighlight>

This section still needs to be defined for files that only define constants. It should also be noted that there MUST NOT be a space between the <code>;</code> and the function/structure name.

==== Undocumented Listing ====
There is a final kind of listing that lists functions for which no documentation exists, or they have been deprecated and are only included for backwards compatibility. These are listed in a section with the header <code>NO_DOC_FUNCTION</code>. This is very rarely used, and is reserved only for functions that can be utilised by the user, or that would have been in the past, as opposed to those for internal use only.

Template:

<syntaxhighlight lang="autoit">; #NO_DOC_FUNCTION# =============================================================================================================
;_MyUDF_Function
; ===============================================================================================================================</syntaxhighlight>

==== Renamed Functions ====
Although it should not be the case in new UDFs, many of the older ones (particularly to do with controls) have had script breaking name changes to functions. These are documented in the UDF to ensure updating old scripts is as easy as possible. The basic format for this is:

<syntaxhighlight lang="autoit">; #NO_DOC_FUNCTION# =============================================================================================================
;_MyUDF_OldFunction ; --> _MyUDF_NewFunction
; ===============================================================================================================================</syntaxhighlight>

The space padding is optional. This section is ignored as far as the docs are concerned, and is usually omitted.

== Functions ==
=== Naming ===
Function names must start with an underscore, and the first word is the library name. There is then usually another underscore before the rest of the function name. The library name should be consistent across all the functions in the library, and can be shortened if a logical abbreviation is available (e.g. <code>Window</code> ==> <code>Win</code>). Each word should be capitalized, but no underscores are placed in the rest of the name, for example <code>_WinAPI_GetWindowLong</code>.

For control libraries, the first part of the function name is changed slightly. For example the UDF for listviews would use <code>_GUICtrlListview_*</code>. When a function wraps a dll call, then the second part should closely resemble the function name as it appears in other languages. This also applies to functions acting as a wrapper to <code>SendMessage</code>.

Functions are defined in alphabetical order by name, which is the same as using <code>Tidy</code> with the <code>/sf</code> flag set.

=== Parameters ===
Parameters should follow the variable naming scheme ([[#Naming_2|here]]). All parameters must be checked to ensure they are valid, and return unique and documented error codes if they are not. For functions involving a specific type of control, this includes checking the class name using <code>_WinAPI_IsClassName</code>.

Parameters that are optional or byref should be documented as such, and the effect these have explicitly stated. For example a byref parameter should detail exactly what the expected output is as well as the input.

=== Headers ===
All functions have a documentation header that describes the function. This uses the following template:

<syntaxhighlight lang="autoit">; #FUNCTION# ====================================================================================================================
; Name...........: _WinAPI_GetMousePos
; Description ...: Returns the current mouse position
; Syntax.........: _WinAPI_GetMousePos([$fToClient = False[, $hWnd = 0]])
; Parameters ....: $fToClient - If True, the coordinates will be converted to client coordinates
; $hWnd - Window handle used to convert coordinates if $fToClient is True
; Return values .: Success - $tagPOINT structure with current mouse position
; Failure - Zero
; Author ........: Paul Campbell (PaulIA)
; Modified.......:
; Remarks .......: This function takes into account the current MouseCoordMode setting when obtaining the mouse position. It
; will also convert screen to client coordinates based on the parameters passed.
; Related .......: $tagPOINT, _WinAPI_GetMousePosX, _WinAPI_GetMousePosY
; Link ..........:
; Example .......: Yes
; ===============================================================================================================================
Func _WinAPI_GetMousePos($fToClient = False, $hWnd = 0)</syntaxhighlight>

The header is 129 characters wide, and any text within it should be wrapped to that length. For example the <code>Remarks</code> in the above header has been extended to cover two lines. The exception to that rule is the <code>Syntax</code> line, which should not be wrapped. Some of the parameters in the header are optional, in which case they should remain, but be left empty (for example the <code>Link</code> and <code>Modified</code> lines in the above header). In others, they are needed, but can be empty or not used such as <code>Parameters</code> or <code>Return Values</code>. In this case the value should be 'None', as they will still be present in the documentation.

There are some flags that can be used within function headers:

* '''+''' in column 20 is the continuation flag for the previous line (used in Parameters, Return Values)
* '''|''' in column 20 is a new line in the right side of the table when the help file is generated (used in Parameters, Return Values)
* '''-''' in column 20 will create new row in the table, used for things like Defaults for a style (used in Parameters, Return Values)
* '''+''' in column 2 of Remarks is a blank line
Name
:Specifies the name of the function. This will be identical to how it appeas in the Func statement in the code itself.
Description
:Gives a short summary of what the function does. This should only be a single line, as it is only designed to give a short impression of what is happening. For the standard set of includes distributed with AutoIt3, this value is also used in the SciTE calltips.
Syntax
:Describes the syntax of the function call. This differs slightly from what appears in the code itself for optional parameters, which are enclosed in square brackets ("[ ]"). Since subsequent parameters must also be optional, and cannot be defined unless all the previous ones have been given, these brackets are nested in the form: Function([param1[, param2[,param3]]]). Note that the opening bracket appears before the comma seperator.
Parameters
:This is a list of the arguments accepted by the function. Each is listed, followed by a dash ("-") and a description of what it is. The dash can be padded for neatness, although the amount of padding depends on how long the parameter names are. If the parameter is optional then the meaning of the default value should be given, similarly if it's used to pass data back to the program in the form of byref then the changes made should also be detailed. For more information on parameters see Parameters.
Return values
:Details what is returned by the function. This often comes in the form of Success and Failure values, but this is not always the case. Any setting of the @error of @extended flags should be detailed, along with their meanings, in some cases it is enough to say that @error is set to non-zero in the event of an error, in most cases though a list of values for @error should be given.
Author
:This is the original writer of the function. It should contain the username, so that any queries about the code can be made through the forum, but you can give as much or little information as you feel appropriate.
Modified
:This is a list of modifications made. At it's most basic this is just a list of users who have made changes, but ideally it includes some information about what they did, in which cases it follows the same form as other multi-value lines, with the username and description of modifications seperated by a dash.
Remarks
:This is anything the user should know about a function in order to use it. For example exceptional cases and recommended ways to handle the function should all be detailed here, as well as additional info about possible reasons for failure and how to deal with them.
Related
:A comma seperated list of functions or structures related to the function.
Link
:A link to additional information about the function. For many system function wrappers, this will be <code>@@MsdnLink@@ FunctionName</code>, which represents that the user should search MSDN for the function.
Example
:A simple yes or no value specifying whether the function has an example. If this is no then your UDF is not ready to be released. The [[#Examples]] section has more information on the format and location of examples.

The easiest way to generate the header is to copy and paste the following blank template in:

<syntaxhighlight lang="autoit">; #FUNCTION# ====================================================================================================================
; Name...........:
; Description ...:
; Syntax.........:
; Parameters ....:
; Return values .:
; Author ........:
; Modified.......:
; Remarks .......:
; Related .......:
; Link ..........:
; Example .......:
; ===============================================================================================================================</syntaxhighlight>

There are also a number of plugins for SciTE that will generate a header and maybe fill in certain known values for you such as Name, Syntax and Parameters. The most complete one that conforms to these standards is [http://code.google.com/p/m-a-t/wiki/UDFHeaderGenerator here], but there are two others [http://www.autoitscript.com/forum/topic/28270-lua-script-for-udf-header/ here] and [http://www.autoitscript.com/forum/topic/28270-lua-script-for-udf-header/page__view__findpost__p__200823 here].

=== Internal use only ===
Functions can also be marked for use only within the library and not to be documented for use by the user. These are named according to the same rules as normal functions but begin with a double underscore ("__"). The header is exactly the same except with the first line replaced, to make the blank template:

<syntaxhighlight lang="autoit">; #INTERNAL_USE_ONLY# ===========================================================================================================
; Name...........:
; Description ...:
; Syntax.........:
; Parameters ....:
; Return values .:
; Author ........:
; Modified.......:
; Remarks .......:
; Related .......:
; Link ..........:
; Example .......:
; ===============================================================================================================================</syntaxhighlight>

== Structures ==
Structures are defined as global constants, and follow the naming pattern <code>$tagSTRUCTNAME</code>. The struct name should be as it appears on MSDN if it's used in the windows API, or follow a similar pattern if not. It should go without saying that they must work for both 32 and 64 bit machines, including resolving any alignment issues. Elements should also be named as they appear on MSDN if they are taken from there, which includes the hungarian notation prefix. Although many standard UDFs do not follow that rule, importantly <code>StructureConstants.au3</code>, the rule still stands.

=== Headers ===
Structures need a header similar to functions, but with some minor differences. The same rules apply in terms of wrapping and line length however. The header follow this standard template:

<syntaxhighlight lang="autoit">; #STRUCTURE# ===================================================================================================================
; Name...........: $tagPOINT
; Description ...: Defines the x and y coordinates of a point
; Fields ........: X - Specifies the x-coordinate of the point
; Y - Specifies the y-coordinate of the point
; Author ........: Paul Campbell (PaulIA)
; Remarks .......:
; Related .......:
; ===============================================================================================================================
Global Const $tagPOINT = "long X;long Y"</syntaxhighlight>

It is essentially a shortened header, with the only thing new is the Fields line, which effectively replaces the Parameters field in terms of usage. All the same rules apply as listed [[#Function Header Fields|here]].

The blank template is:

<syntaxhighlight lang="autoit">; #STRUCTURE# ===================================================================================================================
; Name...........:
; Description ...:
; Fields ........:
; Author ........:
; Remarks .......:
; Related .......:
; ===============================================================================================================================</syntaxhighlight>

Structures may also be marked for internal use only. In this case the header ramains the same, but the sections first line changes. The blank template is:

<syntaxhighlight lang="autoit">; #INTERNAL_USE_ONLY# ===========================================================================================================
; Name...........:
; Description ...:
; Fields ........:
; Author ........:
; Remarks .......:
; Related .......:
; ===============================================================================================================================</syntaxhighlight>

== Variables ==
For code readability, there are special rules dealing with variables, particularly naming. All variables should be declared at the beginning of their scope, which usually means at the start of the function in which they are used, but could mean the top of the UDF itself in the [[#Variables|Variables section]].

=== Naming ===
A variable's first letter signifies the expected type of the variable. This should be as follows:

* <code>$a<letter></code> - Array (the following letter describes the data type taken from the rest of the data types below, if it varies then <code>v</code> should be used. A counter as the first element is ignored, so the array returned by StringSplit (with default options) would actually be marked as $as despite the integer in the zeroeth element).
* <code>$d</code> - Binary data.
* <code>$h</code> - Handle, usually to a file or window. NB: AutoIt handled controls return IDs, and so use $id instead.
* <code>$id</code> - An AutoIt control Id.
* <code>$i</code> - Integer.
* <code>$b</code> - Boolean.
* <code>$f</code> - Floating point number.
* <code>$n</code> - general number with no preference for floating point or integer.
* <code>$s</code> - String.
* <code>$v</code> - Variant (unknown/variable type of data) .
* <code>$p</code> - Pointer. It is assumed that it points to a struct so no further letters are needed. The type of struct being pointed to should be inferrable from the variable name e.g. <code>$pWindowRect</code> can be assumed to be a pointer to a <code>$tagRECT</code> structure.
* <code>$t</code> - Structure returned from DllStructCreate.
* <code>$tag</code> - Struct definition string.Structure definitions should conform to the structure guidelines.

=== Globals ===
The use of globals in a UDF is generally frowned upon, and byref parameters and static variables should be used where possible instead. However, in cases where this is not possible and a global must be used they should be defined using the following naming pattern: <code>$__g<VARNAME>_<UDF></code> where <code><VARNAME></code> is the name as it would usually appear according to the variable naming rules above and <code><UDF></code> is the name of the library in which it appears. This ensures there will never be a conflict with user variables of other UDF globals. They should be declared at the top of the UDF in the Variables section.

Globals are always private. If they need to be accessed by the user then functions need to be written wrapping that operation and values should be checked. Notable exceptions are debug variables, which are designed for developer purposes and may be used by some users in extreme cases. These are named <code>$Debug_<UDF></code> although the <code><UDF></code> part is often shortened so <code>GUIEdit.au3</code> uses <code>$Debug_Ed</code>. It is not required that a UDF has debugging symbols, but they are allowed to remain in releases.

=== Constants ===
There are two types of constants, internal and public. Public constants are designed to be utilised by the user, and are referenced in functions that use them. They include styles and flags. Internal constants are designed for use only within the library, so that values used fairly often can be held in one place to allow for easy updating. Both kinds of constant are always typed in all upper case. Constants taken from the windows API should appear exactly as they are defined there, but internal constants follow the naming pattern: <code>$__<UDF>CONSTANT_<NAME></code>.

=== The <code>Dim</code> statement ===
Should not be used.

== Examples ==
All functions and structures that are made public to the user need to have a good quality example. This means that it should:

* Be simple. Ideally the only functions used are basic functions like ConsoleWrite and MsgBox and the function that the example is written for. Writing a single example that covers a wide range of functions is not nearly as easy to use as writing an example per function that clearly demonstrates its use.
* Be readable. Everything should be explained step by step in comments.
* Be correct. In addition to passing the same Au3Check flags as the UDF itself (<code>-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7</code>) it should always be written with best practice being the main consideration. This takes preference over the first point, just because code is shorter and looks easier doesn't mean it's right.
* Examples should represent all the functionality. If there is more than one way of using a function then include more than one example of how to use it.
* Not make any permanent changes to the users computer. For example, if demonstrating a File function, be sure to delete the file after it has been used. The same applies for any function that makes a change to the environment: the changes MUST be undone.

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

Examples are stored in script files called <code><FUNCTION>.au3</code>. The files should be kept in a folder called <code>Examples</code>. To remain correct all examples should be wrapped in functions, such that the only code executed in the global scope is calling the function. This is usually named <code>Example</code>.

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

Opt("MustDeclareVars", 1)

Example()

Func Example()
Local $idButton_1, $idButton_2, $iMsg, $hGUI

$hGUI = GUICreate("My GUI Button") ; Will create a dialog box that when displayed is centered

$idButton_1 = GUICtrlCreateButton("Run Notepad", 4, 4, 80, 30)
$idButton_2 = GUICtrlCreateButton("Button Test", 4, 38, 80, 30)

GUISetState() ; will display a dialog box with 2 button

; Run the GUI until the dialog is closed
While 1
$iMsg = GUIGetMsg()
Select
Case $iMsg = $GUI_EVENT_CLOSE
ExitLoop
Case $iMsg = $idButton_1
Run("Notepad.exe") ; Will Run/Open Notepad
Case $iMsg = $idButton_2
MsgBox($MB_SYSTEMMODAL, "Testing", "Button 2 was pressed") ; Will demonstrate Button 2 being pressed
EndSelect
WEnd
GUIDelete($hGUI)
EndFunc ;==>Example</syntaxhighlight>

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

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

<syntaxhighlight lang="autoit">#include-once

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

; #INDEX# =======================================================================================================================
; Title .........: MyUDF
; AutoIt Version : 3.3.6.1
; Language ......: English
; Description ...: An example UDF that does very little.
; ===============================================================================================================================

; #CURRENT# =====================================================================================================================
;$tagMYSTRUCT
;_MyUDF_Function
; ===============================================================================================================================

; #STRUCTURE# ===================================================================================================================
; Name...........: $tagMYSTRUCT
; Description ...: An example of a structure.
; Fields ........: hFoo - A handle to foo that does something.
; iBar - An integer that does something.
; Author ........: Matt Diesel (Mat)
; Remarks .......:
; Related .......: _MyUDF_Function
; ===============================================================================================================================
Global Const $tagMYSTRUCT = "ptr hFoo; int iBar"

; #FUNCTION# ====================================================================================================================
; Name...........: _MyUDF_Function
; Description ...: A function that does something.
; Syntax.........: _MyUDF_Function(ByRef $avAnArray, $iAnInt[, $hAHandle = 0[, $nSomeNumber = 42]])
; Parameters ....: $avAnArray - [byref] An array of anything. The value of anything is changed and passed out using this
; parameter. The array should only have one dimension
; $iAnInt - An integer that does very little.
; $hAHandle - [optional] A handle. Default is zero.
; $nSomeNumber - [optional] A number of some kind. Default is 42.
; Return values .: Success - A MYSTRUCT structure.
; Failure - Returns zero and sets the @error flag:
; |1 - The $avAnArray is invalid.
; Author ........: Matt Diesel (Mat)
; Modified.......:
; Remarks .......:
; Related .......: $tagMYSTRUCT
; Link ..........:
; Example .......: No
; ===============================================================================================================================
Func _MyUDF_Function(ByRef $avAnArray, $iAnInt, $hAHandle = 0, $nSomeNumber = 42)
; 1 - Error Checking for parameters.
If Not IsArray($avAnArray) Or UBound($avAnArray, 0) <> 1 Then Return SetError(1, 0, 0) ; The $avAnArray is invalid.

; 2 - Declaration of locals.
Local $tMS = DllStructCreate($tagMYSTRUCT)

; 3 - Function code
DllStructSetData($tMS, "hFoo", $hAHandle)
DllStructSetData($tMS, "iBar", $iAnInt * $nSomeNumber)

Return $tMS
EndFunc ;==>_MyUDF_Function</syntaxhighlight>

UDF-spec

2013-01-29T23:42:21Z

Mdiesel: /* Examples */

[[Category:UDF]]
{{WIP}}This page is still under construction.

----

A library is a collection of one or more User Defined Functions (UDFs). However, the term UDF is often used to describe the collection as a whole. If a UDF is to be considered for inclusion in the standard set distributed with AutoIt then it must meet all the criteria detailed here, but it's also good practice to always write in conformance with at least the majority of this document, as that is what will be expected by people reading your code later.

== Basic Requirements ==
Firstly, the code itself should meet the following basic requirements:

* Be tidied. Just hit <code>Ctrl+T</code> from SciTE or run Tidy manually. The only flag needed is <code>/sf</code>.
* Pass Au3Check with no errors using the strictest settings: <code>-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7</code>
* Support everything AutoIt supports. In some cases features may not be able to support everything, in which case this should be checked for and return errors appropriately. This applies to: windows OS versions (AutoIt has support for all OS' from windows 2000), unicode and ansi strings, 64 and 32 bit machines.
* Ideally it will be able to run cleanly when obfuscated. Although there will be some cases where this is not possible, please consider it when writing UDFs, and avoid the use of Execute and similar statements. If it does not, then document it as such.

== UDF Outline ==
The library itself has a header that details important information such as the minimum OS and AutoIt versions, and what system dlls are required. There is also a number of other sections that are required that list what is present in the UDF.

=== Includes ===
Since a UDF is designed to define functions, it should only be included once. As a result, the <code>#include-once</code> directive should be used. This is typically the first line of the UDF, followed by the includes used by the UDF. Include statements should use the double quoted form, as the library is expected to work in the same directory as libraries it depends on. Non standard libraries can be used if necessary, but this should be documented and linked to so users can download it as well. It goes without saying that a UDF based on non-standard UDFs cannot itself become a standard.

=== Index ===
The index follows the following template (taken from <code>WinAPI.au3</code>):

<syntaxhighlight lang="autoit">; #INDEX# =======================================================================================================================
; Title .........: Windows API
; AutoIt Version : 3.2
; Description ...: Windows API calls that have been translated to AutoIt functions.
; Author(s) .....: Paul Campbell (PaulIA), gafrost, Siao, Zedna, arcker, Prog@ndy, PsaltyDS, Raik, jpm
; Dll ...........: kernel32.dll, user32.dll, gdi32.dll, comdlg32.dll, shell32.dll, ole32.dll, winspool.drv
; ===============================================================================================================================</syntaxhighlight>

The only required element in the index header is <code>Title</code>. All others are ignored by the processor, but should be included for reference

The <code>Dll</code> field can remain empty in many cases where no dlls are called directly. This header must be defined.

=== Other Sections ===
Other sections, in order of appearance, are as follows.

==== Variables ====
All global variables needed to be declared in the UDF are defined in this section. They should follow the variable rules for globals. Individual variables do not need to be documented, as it is assumed they are for internal use only. Any globals designed to be accessible for the user should instead be wrapped by a function (or multiple functions if globals must be retrieved and set). The template for this section is:

<syntaxhighlight lang="autoit">; #VARIABLES# ===================================================================================================================
Global $__gvMyGlobal = 0
; ===============================================================================================================================</syntaxhighlight>

If no globals are needed then this section may be ommitted. Please consider the use of global variables carefully, and read through the section on global variables.

==== Constants ====
Any global constant values are defined in this section. This should be constants only designated for use within the library itself. Constants that may be needed by the user should be defined in a separate file, named <code>UDFConstants.au3</code> where <code>UDF</code> is the name of the parent file. For example <code>File.au3</code> uses constants defined in <code>FileConstants.au3</code>. The exception to that rule is control UDFs which miss out the prepended 'GUI' when naming constant files, so <code>GUIButton.au3</code> uses constants from <code>ButtonConstants.au3</code>. The template for this section is:

<syntaxhighlight lang="autoit">; #CONSTANTS# ===================================================================================================================
Global Const $__MYUDFCONSTANT_FOOBAR = 42
; ===============================================================================================================================</syntaxhighlight>

If no constants are needed in this section, either because none are used or because they are stored in a separate file, then it may be ommitted. Please read the section on global constants for specific info on naming and definition of constants.

==== Listing ====
This defines all functions and structures currently used functions in the library. It MUST be the second defined header item after [[#Index]]. It is a simple list with each function on a line where the functions and structures appear in the same order as they do in the code, which is alphabetical order and structures first. A simple way to generate this list is to create a small script that searches for function definitions and outputs them in the correct format, an example of which is [http://www.autoitscript.com/forum/topic/120820-function-name-lister/ here]. In addition there is a second section that lists functions and structures for internal use only, this does not need to appear if none are defined.

The template for these sections are:

<syntaxhighlight lang="autoit">; #CURRENT# =====================================================================================================================
;$tagSTRUCT
;_MyUDF_Function
; ===============================================================================================================================

; #INTERNAL_USE_ONLY# ===========================================================================================================
;$tagINTERNALSTRUCT
;__MyUDF_InternalFunction
; ===============================================================================================================================</syntaxhighlight>

This section still needs to be defined for files that only define constants. It should also be noted that there MUST NOT be a space between the <code>;</code> and the function/structure name.

==== Undocumented Listing ====
There is a final kind of listing that lists functions for which no documentation exists, or they have been deprecated and are only included for backwards compatibility. These are listed in a section with the header <code>NO_DOC_FUNCTION</code>. This is very rarely used, and is reserved only for functions that can be utilised by the user, or that would have been in the past, as opposed to those for internal use only.

Template:

<syntaxhighlight lang="autoit">; #NO_DOC_FUNCTION# =============================================================================================================
;_MyUDF_Function
; ===============================================================================================================================</syntaxhighlight>

==== Renamed Functions ====
Although it should not be the case in new UDFs, many of the older ones (particularly to do with controls) have had script breaking name changes to functions. These are documented in the UDF to ensure updating old scripts is as easy as possible. The basic format for this is:

<syntaxhighlight lang="autoit">; #NO_DOC_FUNCTION# =============================================================================================================
;_MyUDF_OldFunction ; --> _MyUDF_NewFunction
; ===============================================================================================================================</syntaxhighlight>

The space padding is optional. This section is ignored as far as the docs are concerned, and is usually omitted.

== Functions ==
=== Naming ===
Function names must start with an underscore, and the first word is the library name. There is then usually another underscore before the rest of the function name. The library name should be consistent across all the functions in the library, and can be shortened if a logical abbreviation is available (e.g. <code>Window</code> ==> <code>Win</code>). Each word should be capitalized, but no underscores are placed in the rest of the name, for example <code>_WinAPI_GetWindowLong</code>.

For control libraries, the first part of the function name is changed slightly. For example the UDF for listviews would use <code>_GUICtrlListview_*</code>. When a function wraps a dll call, then the second part should closely resemble the function name as it appears in other languages. This also applies to functions acting as a wrapper to <code>SendMessage</code>.

Functions are defined in alphabetical order by name, which is the same as using <code>Tidy</code> with the <code>/sf</code> flag set.

=== Parameters ===
Parameters should follow the variable naming scheme ([[#Naming_2|here]]). All parameters must be checked to ensure they are valid, and return unique and documented error codes if they are not. For functions involving a specific type of control, this includes checking the class name using <code>_WinAPI_IsClassName</code>.

Parameters that are optional or byref should be documented as such, and the effect these have explicitly stated. For example a byref parameter should detail exactly what the expected output is as well as the input.

=== Headers ===
All functions have a documentation header that describes the function. This uses the following template:

<syntaxhighlight lang="autoit">; #FUNCTION# ====================================================================================================================
; Name...........: _WinAPI_GetMousePos
; Description ...: Returns the current mouse position
; Syntax.........: _WinAPI_GetMousePos([$fToClient = False[, $hWnd = 0]])
; Parameters ....: $fToClient - If True, the coordinates will be converted to client coordinates
; $hWnd - Window handle used to convert coordinates if $fToClient is True
; Return values .: Success - $tagPOINT structure with current mouse position
; Failure - Zero
; Author ........: Paul Campbell (PaulIA)
; Modified.......:
; Remarks .......: This function takes into account the current MouseCoordMode setting when obtaining the mouse position. It
; will also convert screen to client coordinates based on the parameters passed.
; Related .......: $tagPOINT, _WinAPI_GetMousePosX, _WinAPI_GetMousePosY
; Link ..........:
; Example .......: Yes
; ===============================================================================================================================
Func _WinAPI_GetMousePos($fToClient = False, $hWnd = 0)</syntaxhighlight>

The header is 129 characters wide, and any text within it should be wrapped to that length. For example the <code>Remarks</code> in the above header has been extended to cover two lines. The exception to that rule is the <code>Syntax</code> line, which should not be wrapped. Some of the parameters in the header are optional, in which case they should remain, but be left empty (for example the <code>Link</code> and <code>Modified</code> lines in the above header). In others, they are needed, but can be empty or not used such as <code>Parameters</code> or <code>Return Values</code>. In this case the value should be 'None', as they will still be present in the documentation.

There are some flags that can be used within function headers:

* '''+''' in column 20 is the continuation flag for the previous line (used in Parameters, Return Values)
* '''|''' in column 20 is a new line in the right side of the table when the help file is generated (used in Parameters, Return Values)
* '''-''' in column 20 will create new row in the table, used for things like Defaults for a style (used in Parameters, Return Values)
* '''+''' in column 2 of Remarks is a blank line
Name
:Specifies the name of the function. This will be identical to how it appeas in the Func statement in the code itself.
Description
:Gives a short summary of what the function does. This should only be a single line, as it is only designed to give a short impression of what is happening. For the standard set of includes distributed with AutoIt3, this value is also used in the SciTE calltips.
Syntax
:Describes the syntax of the function call. This differs slightly from what appears in the code itself for optional parameters, which are enclosed in square brackets ("[ ]"). Since subsequent parameters must also be optional, and cannot be defined unless all the previous ones have been given, these brackets are nested in the form: Function([param1[, param2[,param3]]]). Note that the opening bracket appears before the comma seperator.
Parameters
:This is a list of the arguments accepted by the function. Each is listed, followed by a dash ("-") and a description of what it is. The dash can be padded for neatness, although the amount of padding depends on how long the parameter names are. If the parameter is optional then the meaning of the default value should be given, similarly if it's used to pass data back to the program in the form of byref then the changes made should also be detailed. For more information on parameters see Parameters.
Return values
:Details what is returned by the function. This often comes in the form of Success and Failure values, but this is not always the case. Any setting of the @error of @extended flags should be detailed, along with their meanings, in some cases it is enough to say that @error is set to non-zero in the event of an error, in most cases though a list of values for @error should be given.
Author
:This is the original writer of the function. It should contain the username, so that any queries about the code can be made through the forum, but you can give as much or little information as you feel appropriate.
Modified
:This is a list of modifications made. At it's most basic this is just a list of users who have made changes, but ideally it includes some information about what they did, in which cases it follows the same form as other multi-value lines, with the username and description of modifications seperated by a dash.
Remarks
:This is anything the user should know about a function in order to use it. For example exceptional cases and recommended ways to handle the function should all be detailed here, as well as additional info about possible reasons for failure and how to deal with them.
Related
:A comma seperated list of functions or structures related to the function.
Link
:A link to additional information about the function. For many system function wrappers, this will be <code>@@MsdnLink@@ FunctionName</code>, which represents that the user should search MSDN for the function.
Example
:A simple yes or no value specifying whether the function has an example. If this is no then your UDF is not ready to be released. The [[#Examples]] section has more information on the format and location of examples.

The easiest way to generate the header is to copy and paste the following blank template in:

<syntaxhighlight lang="autoit">; #FUNCTION# ====================================================================================================================
; Name...........:
; Description ...:
; Syntax.........:
; Parameters ....:
; Return values .:
; Author ........:
; Modified.......:
; Remarks .......:
; Related .......:
; Link ..........:
; Example .......:
; ===============================================================================================================================</syntaxhighlight>

There are also a number of plugins for SciTE that will generate a header and maybe fill in certain known values for you such as Name, Syntax and Parameters. The most complete one that conforms to these standards is [http://code.google.com/p/m-a-t/wiki/UDFHeaderGenerator here], but there are two others [http://www.autoitscript.com/forum/topic/28270-lua-script-for-udf-header/ here] and [http://www.autoitscript.com/forum/topic/28270-lua-script-for-udf-header/page__view__findpost__p__200823 here].

=== Internal use only ===
Functions can also be marked for use only within the library and not to be documented for use by the user. These are named according to the same rules as normal functions but begin with a double underscore ("__"). The header is exactly the same except with the first line replaced, to make the blank template:

<syntaxhighlight lang="autoit">; #INTERNAL_USE_ONLY# ===========================================================================================================
; Name...........:
; Description ...:
; Syntax.........:
; Parameters ....:
; Return values .:
; Author ........:
; Modified.......:
; Remarks .......:
; Related .......:
; Link ..........:
; Example .......:
; ===============================================================================================================================</syntaxhighlight>

== Structures ==
Structures are defined as global constants, and follow the naming pattern <code>$tagSTRUCTNAME</code>. The struct name should be as it appears on MSDN if it's used in the windows API, or follow a similar pattern if not. It should go without saying that they must work for both 32 and 64 bit machines, including resolving any alignment issues. Elements should also be named as they appear on MSDN if they are taken from there, which includes the hungarian notation prefix. Although many standard UDFs do not follow that rule, importantly <code>StructureConstants.au3</code>, the rule still stands.

=== Headers ===
Structures need a header similar to functions, but with some minor differences. The same rules apply in terms of wrapping and line length however. The header follow this standard template:

<syntaxhighlight lang="autoit">; #STRUCTURE# ===================================================================================================================
; Name...........: $tagPOINT
; Description ...: Defines the x and y coordinates of a point
; Fields ........: X - Specifies the x-coordinate of the point
; Y - Specifies the y-coordinate of the point
; Author ........: Paul Campbell (PaulIA)
; Remarks .......:
; Related .......:
; ===============================================================================================================================
Global Const $tagPOINT = "long X;long Y"</syntaxhighlight>

It is essentially a shortened header, with the only thing new is the Fields line, which effectively replaces the Parameters field in terms of usage. All the same rules apply as listed [[#Function Header Fields|here]].

The blank template is:

<syntaxhighlight lang="autoit">; #STRUCTURE# ===================================================================================================================
; Name...........:
; Description ...:
; Fields ........:
; Author ........:
; Remarks .......:
; Related .......:
; ===============================================================================================================================</syntaxhighlight>

Structures may also be marked for internal use only. In this case the header ramains the same, but the sections first line changes. The blank template is:

<syntaxhighlight lang="autoit">; #INTERNAL_USE_ONLY# ===========================================================================================================
; Name...........:
; Description ...:
; Fields ........:
; Author ........:
; Remarks .......:
; Related .......:
; ===============================================================================================================================</syntaxhighlight>

== Variables ==
For code readability, there are special rules dealing with variables, particularly naming. All variables should be declared at the beginning of their scope, which usually means at the start of the function in which they are used, but could mean the top of the UDF itself in the [[#Variables|Variables section]].

=== Naming ===
A variable's first letter signifies the expected type of the variable. This should be as follows:

* <code>$a<letter></code> - Array (the following letter describes the data type taken from the rest of the data types below, if it varies then <code>v</code> should be used. A counter as the first element is ignored, so the array returned by StringSplit (with default options) would actually be marked as $as despite the integer in the zeroeth element).
* <code>$d</code> - Binary data.
* <code>$h</code> - Handle, usually to a file or window. NB: AutoIt handled controls return IDs, and so use $id instead.
* <code>$id</code> - An AutoIt control Id.
* <code>$i</code> - Integer.
* <code>$b</code> - Boolean.
* <code>$f</code> - Floating point number.
* <code>$n</code> - general number with no preference for floating point or integer.
* <code>$s</code> - String.
* <code>$v</code> - Variant (unknown/variable type of data) .
* <code>$p</code> - Pointer. It is assumed that it points to a struct so no further letters are needed. The type of struct being pointed to should be inferrable from the variable name e.g. <code>$pWindowRect</code> can be assumed to be a pointer to a <code>$tagRECT</code> structure.
* <code>$t</code> - Structure returned from DllStructCreate.
* <code>$tag</code> - Struct definition string.Structure definitions should conform to the structure guidelines.

=== Globals ===
The use of globals in a UDF is generally frowned upon, and byref parameters and static variables should be used where possible instead. However, in cases where this is not possible and a global must be used they should be defined using the following naming pattern: <code>$__g<VARNAME>_<UDF></code> where <code><VARNAME></code> is the name as it would usually appear according to the variable naming rules above and <code><UDF></code> is the name of the library in which it appears. This ensures there will never be a conflict with user variables of other UDF globals. They should be declared at the top of the UDF in the Variables section.

Globals are always private. If they need to be accessed by the user then functions need to be written wrapping that operation and values should be checked. Notable exceptions are debug variables, which are designed for developer purposes and may be used by some users in extreme cases. These are named <code>$Debug_<UDF></code> although the <code><UDF></code> part is often shortened so <code>GUIEdit.au3</code> uses <code>$Debug_Ed</code>. It is not required that a UDF has debugging symbols, but they are allowed to remain in releases.

=== Constants ===
There are two types of constants, internal and public. Public constants are designed to be utilised by the user, and are referenced in functions that use them. They include styles and flags. Internal constants are designed for use only within the library, so that values used fairly often can be held in one place to allow for easy updating. Both kinds of constant are always typed in all upper case. Constants taken from the windows API should appear exactly as they are defined there, but internal constants follow the naming pattern: <code>$__<UDF>CONSTANT_<NAME></code>.

=== The <code>Dim</code> statement ===
Should not be used.

== Examples ==
All functions and structures that are made public to the user need to have a good quality example. This means that it should:

* Be simple. Ideally the only functions used are basic functions like ConsoleWrite and MsgBox and the function that the example is written for. Writing a single example that covers a wide range of functions is not nearly as easy to use as writing an example per function that clearly demonstrates its use.
* Be readable. Everything should be explained step by step in comments.
* Be correct. In addition to passing the same Au3Check flags as the UDF itself (<code>-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7</code>) it should always be written with best practice being the main consideration. This takes preference over the first point, just because code is shorter and looks easier doesn't mean it's right.
* Examples should represent all the functionality. If there is more than one way of using a function then include more than one example of how to use it.
* Not make any permanent changes to the users computer. For example, if demonstrating a File function, be sure to delete the file after it has been used. The same applies for any function that makes a change to the environment: the changes MUST be undone.

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

Examples are stored in script files called <code><FUNCTION>.au3</code>. The files should be kept in a folder called <code>Examples</code>. To remain correct all examples should be wrapped in functions, such that the only code executed in the global scope is calling the function. This is usually named <code>Example</code>.

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

Opt("MustDeclareVars", 1)

Example()

Func Example()
Local $idButton_1, $idButton_2, $iMsg, $hGUI

$hGUI = GUICreate("My GUI Button") ; Will create a dialog box that when displayed is centered

$idButton_1 = GUICtrlCreateButton("Run Notepad", 4, 4, 80, 30)
$idButton_2 = GUICtrlCreateButton("Button Test", 4, 38, 80, 30)

GUISetState() ; will display a dialog box with 2 button

; Run the GUI until the dialog is closed
While 1
$iMsg = GUIGetMsg()
Select
Case $iMsg = $GUI_EVENT_CLOSE
ExitLoop
Case $iMsg = $idButton_1
Run("Notepad.exe") ; Will Run/Open Notepad
Case $iMsg = $idButton_2
MsgBox($MB_SYSTEMMODAL, "Testing", "Button 2 was pressed") ; Will demonstrate Button 2 being pressed
EndSelect
WEnd
GUIDelete($hGUI)
EndFunc ;==>Example</syntaxhighlight>

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

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

<syntaxhighlight lang="autoit">#include-once

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

; #INDEX# =======================================================================================================================
; Title .........: MyUDF
; AutoIt Version : 3.3.6.1
; Language ......: English
; Description ...: An example UDF that does very little.
; ===============================================================================================================================

; #CURRENT# =====================================================================================================================
;$tagMYSTRUCT
;_MyUDF_Function
; ===============================================================================================================================

; #STRUCTURE# ===================================================================================================================
; Name...........: $tagMYSTRUCT
; Description ...: An example of a structure.
; Fields ........: hFoo - A handle to foo that does something.
; iBar - An integer that does something.
; Author ........: Matt Diesel (Mat)
; Remarks .......:
; Related .......: _MyUDF_Function
; ===============================================================================================================================
Global Const $tagMYSTRUCT = "ptr hFoo; int iBar"

; #FUNCTION# ====================================================================================================================
; Name...........: _MyUDF_Function
; Description ...: A function that does something.
; Syntax.........: _MyUDF_Function(ByRef $avAnArray, $iAnInt[, $hAHandle = 0[, $nSomeNumber = 42]])
; Parameters ....: $avAnArray - [byref] An array of anything. The value of anything is changed and passed out using this
; parameter. The array should only have one dimension
; $iAnInt - An integer that does very little.
; $hAHandle - [optional] A handle. Default is zero.
; $nSomeNumber - [optional] A number of some kind. Default is 42.
; Return values .: Success - A MYSTRUCT structure.
; Failure - Returns zero and sets the @error flag:
; |1 - The $avAnArray is invalid.
; Author ........: Matt Diesel (Mat)
; Modified.......:
; Remarks .......:
; Related .......: $tagMYSTRUCT
; Link ..........:
; Example .......: No
; ===============================================================================================================================
Func _MyUDF_Function(ByRef $avAnArray, $iAnInt, $hAHandle = 0, $nSomeNumber = 42)
; 1 - Error Checking for parameters.
If Not IsArray($avAnArray) Or UBound($avAnArray, 0) <> 1 Then Return SetError(1, 0, 0) ; The $avAnArray is invalid.

; 2 - Declaration of locals.
Local $tMS = DllStructCreate($tagMYSTRUCT)

; 3 - Function code
DllStructSetData($tMS, "hFoo", $hAHandle)
DllStructSetData($tMS, "iBar", $iAnInt * $nSomeNumber)

Return $tMS
EndFunc ;==>_MyUDF_Function</syntaxhighlight>

Talk:UDF-spec

2013-01-07T01:38:32Z

Mdiesel: /* Coding Practice */ new section

User:Mdiesel

2012-11-05T22:41:58Z

Mdiesel: Update contact info

AutoIt Forum profile: http://www.autoitscript.com/forum/index.php?showuser=46719

Website: http://ma.ttdiesel.co.uk/

AutoIt scripts page: http://code.google.com/p/m-a-t/

AutoIt projects list: http://code.google.com/p/m-a-t/wiki/WhatIveDone

email: M@ttDiesel.co.uk

UDF-spec

2012-09-24T18:33:22Z

Mdiesel: /* Undocumented Listing */ corrected typo

This page is still under construction.

----

A library is a collection of one or more User Defined Functions (UDFs). However, the term UDF is often used to describe the collection as a whole. If a UDF is to be considered for inclusion in the standard set distributed with AutoIt then it must meet all the criteria detailed here, but it's also good practice to always write in conformance with at least the majority of this document, as that is what will be expected by people reading your code later.

== Basic Requirements ==
Firstly, the code itself should meet the following basic requirements:

* Be tidied. Just hit <code>Ctrl+T</code> from SciTE or run Tidy manually. The only flag needed is <code>/sf</code>.
* Pass Au3Check with no errors using the strictest settings: <code>-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7</code>
* Support everything AutoIt supports. In some cases features may not be able to support everything, in which case this should be checked for and return errors appropriately. This applies to: windows OS versions (AutoIt has support for all OS' from windows 2000), unicode and ansi strings, 64 and 32 bit machines.
* Ideally it will be able to run cleanly when obfuscated. Although there will be some cases where this is not possible, please consider it when writing UDFs, and avoid the use of Execute and similar statements. If it does not, then document it as such.

== UDF Outline ==
The library itself has a header that details important information such as the minimum OS and AutoIt versions, and what system dlls are required. There is also a number of other sections that are required that list what is present in the UDF.

=== Includes ===
Since a UDF is designed to define functions, it should only be included once. As a result, the <code>#include-once</code> directive should be used. This is typically the first line of the UDF, followed by the includes used by the UDF. Include statements should use the double quoted form, as the library is expected to work in the same directory as libraries it depends on. Non standard libraries can be used if necessary, but this should be documented and linked to so users can download it as well. It goes without saying that a UDF based on non-standard UDFs cannot itself become a standard.

=== Index ===
The index follows the following template (taken from <code>WinAPI.au3</code>):

<syntaxhighlight lang="autoit">; #INDEX# =======================================================================================================================
; Title .........: Windows API
; AutoIt Version : 3.2
; Description ...: Windows API calls that have been translated to AutoIt functions.
; Author(s) .....: Paul Campbell (PaulIA), gafrost, Siao, Zedna, arcker, Prog@ndy, PsaltyDS, Raik, jpm
; Dll ...........: kernel32.dll, user32.dll, gdi32.dll, comdlg32.dll, shell32.dll, ole32.dll, winspool.drv
; ===============================================================================================================================</syntaxhighlight>

The only required element in the index header is <code>Title</code>. All others are ignored by the processor, but should be included for reference

The <code>Dll</code> field can remain empty in many cases where no dlls are called directly. This header must be defined.

=== Other Sections ===
Other sections, in order of appearance, are as follows.

==== Variables ====
All global variables needed to be declared in the UDF are defined in this section. They should follow the variable rules for globals. Individual variables do not need to be documented, as it is assumed they are for internal use only. Any globals designed to be accessible for the user should instead be wrapped by a function (or multiple functions if globals must be retrieved and set). The template for this section is:

<syntaxhighlight lang="autoit">; #VARIABLES# ===================================================================================================================
Global $__gvMyGlobal = 0
; ===============================================================================================================================</syntaxhighlight>

If no globals are needed then this section may be ommitted. Please consider the use of global variables carefully, and read through the section on global variables.

==== Constants ====
Any global constant values are defined in this section. This should be constants only designated for use within the library itself. Constants that may be needed by the user should be defined in a seperate file, named <code>UDFConstants.au3</code> where <code>UDF</code> is the name of the parent file. For example <code>File.au3</code> uses constants defined in <code>FileConstants.au3</code>. The exception to that rule is control UDFs which miss out the prepended 'GUI' when naming constant files, so <code>GUIButton.au3</code> uses constants from <code>ButtonConstants.au3</code>. The template for this section is:

<syntaxhighlight lang="autoit">; #CONSTANTS# ===================================================================================================================
Global Const $__MYUDFCONSTANT_FOOBAR = 42
; ===============================================================================================================================</syntaxhighlight>

If no constants are needed in this section, either because non are used or because they are stored in a seperate file, then it may be ommitted. Please read the section on global constants for specific info on naming and definition of constants.

==== Listing ====
This defines all functions and structures currently used functions in the library. It MUST be the second defined header item after [[#Index]]. It is a simple list with each function on a line where the functions and structures appear in the same order as they do in the code, which is alphabetical order and structures first. A simple way to generate this list is to create a small script that searches for function definitions and outputs them in the correct format, an example of which is [http://www.autoitscript.com/forum/topic/120820-function-name-lister/ here]. In addition there is a second section that lists functions and structures for internal use only, this does not need to appear if none are defined.

The template for these sections are:

<syntaxhighlight lang="autoit">; #CURRENT# =====================================================================================================================
;$tagSTRUCT
;_MyUDF_Function
; ===============================================================================================================================

; #INTERNAL_USE_ONLY# ===========================================================================================================
;$tagINTERNALSTRUCT
;__MyUDF_InternalFunction
; ===============================================================================================================================</syntaxhighlight>

This section still needs to be defined for files that only define constants. It should also be noted that there MUST NOT be a space between the <code>;</code> and the function/structure name.

==== Undocumented Listing ====
There is a final kind of listing that lists functions for which no documentation exists, or they have been deprecated and are only included for backwards compatibility. These are listed in a section with the header <code>NO_DOC_FUNCTION</code>. This is very rarely used, and is reserved only for functions that can be utilised by the user, or that would have been in the past, as opposed to those for internal use only.

Template:

<syntaxhighlight lang="autoit">; #NO_DOC_FUNCTION# =============================================================================================================
;_MyUDF_Function
; ===============================================================================================================================</syntaxhighlight>

==== Renamed Functions ====
Although it should not be the case in new UDFs, many of the older ones (particularly to do with controls) have had script breaking name changes to functions. These are documented in the UDF to ensure updating old scripts is as easy as possible. The basic format for this is:

<syntaxhighlight lang="autoit">; #NO_DOC_FUNCTION# =============================================================================================================
;_MyUDF_OldFunction ; --> _MyUDF_NewFunction
; ===============================================================================================================================</syntaxhighlight>

The space padding is optional. This section is ignored as far as the docs are concerned, and is usually omitted.

== Functions ==
=== Naming ===
Function names must start with an underscore, and the first word is the library name. There is then usually another underscore before the rest of the function name. The library name should be consistent across all the functions in the library, and can be shortened if a logical abbreviation is available (e.g. <code>Window</code> ==> <code>Win</code>). Each word should be capitalized, but no underscores are placed in the rest of the name, for example <code>_WinAPI_GetWindowLong</code>.

For control libraries, the first part of the function name is changed slightly. For example the UDF for listviews would use <code>_GUICtrlListview_*</code>. When a function wraps a dll call, then the second part should closely resemble the function name as it appears in other languages. This also applies to functions acting as a wrapper to <code>SendMessage</code>.

Functions are defined in alphabetical order by name, which is the same as using <code>Tidy</code> with the <code>/sf</code> flag set.

=== Parameters ===
Parameters should follow the variable naming scheme ([[#Naming_2|here]]). All parameters must be checked to ensure they are valid, and return unique and documented error codes if they are not. For functions involving a specific type of control, this includes checking the class name using <code>_WinAPI_IsClassName</code>.

Parameters that are optional or byref should be documented as such, and the effect these have explicitly stated. For example a byref parameter should detail exactly what the expected output is as well as the input.

=== Headers ===
All functions have a documentation header that describes the function. This uses the following template:

<syntaxhighlight lang="autoit">; #FUNCTION# ====================================================================================================================
; Name...........: _WinAPI_GetMousePos
; Description ...: Returns the current mouse position
; Syntax.........: _WinAPI_GetMousePos([$fToClient = False[, $hWnd = 0]])
; Parameters ....: $fToClient - If True, the coordinates will be converted to client coordinates
; $hWnd - Window handle used to convert coordinates if $fToClient is True
; Return values .: Success - $tagPOINT structure with current mouse position
; Failure - Zero
; Author ........: Paul Campbell (PaulIA)
; Modified.......:
; Remarks .......: This function takes into account the current MouseCoordMode setting when obtaining the mouse position. It
; will also convert screen to client coordinates based on the parameters passed.
; Related .......: $tagPOINT, _WinAPI_GetMousePosX, _WinAPI_GetMousePosY
; Link ..........:
; Example .......: Yes
; ===============================================================================================================================
Func _WinAPI_GetMousePos($fToClient = False, $hWnd = 0)</syntaxhighlight>

The header is 129 characters wide, and any text within it should be wrapped to that length. For example the <code>Remarks</code> in the above header has been extended to cover two lines. The exception to that rule is the <code>Syntax</code> line, which should not be wrapped. Some of the parameters in the header are optional, in which case they should remain, but be left empty (for example the <code>Link</code> and <code>Modified</code> lines in the above header). In others, they are needed, but can be empty or not used such as <code>Parameters</code> or <code>Return Values</code>. In this case the value should be 'None', as they will still be present in the documentation.

There are some flags that can be used within function headers:

* '''+''' in column 20 is the continuation flag for the previous line (used in Parameters, Return Values)
* '''|''' in column 20 is a new line in the right side of the table when the help file is generated (used in Parameters, Return Values)
* '''-''' in column 20 will create new row in the table, used for things like Defaults for a style (used in Parameters, Return Values)
* '''+''' in column 2 of Remarks is a blank line
Name
:Specifies the name of the function. This will be identical to how it appeas in the Func statement in the code itself.
Description
:Gives a short summary of what the function does. This should only be a single line, as it is only designed to give a short impression of what is happening. For the standard set of includes distributed with AutoIt3, this value is also used in the SciTE calltips.
Syntax
:Describes the syntax of the function call. This differs slightly from what appears in the code itself for optional parameters, which are enclosed in square brackets ("[ ]"). Since subsequent parameters must also be optional, and cannot be defined unless all the previous ones have been given, these brackets are nested in the form: Function([param1[, param2[,param3]]]). Note that the opening bracket appears before the comma seperator.
Parameters
:This is a list of the arguments accepted by the function. Each is listed, followed by a dash ("-") and a description of what it is. The dash can be padded for neatness, although the amount of padding depends on how long the parameter names are. If the parameter is optional then the meaning of the default value should be given, similarly if it's used to pass data back to the program in the form of byref then the changes made should also be detailed. For more information on parameters see Parameters.
Return values
:Details what is returned by the function. This often comes in the form of Success and Failure values, but this is not always the case. Any setting of the @error of @extended flags should be detailed, along with their meanings, in some cases it is enough to say that @error is set to non-zero in the event of an error, in most cases though a list of values for @error should be given.
Author
:This is the original writer of the function. It should contain the username, so that any queries about the code can be made through the forum, but you can give as much or little information as you feel appropriate.
Modified
:This is a list of modifications made. At it's most basic this is just a list of users who have made changes, but ideally it includes some information about what they did, in which cases it follows the same form as other multi-value lines, with the username and description of modifications seperated by a dash.
Remarks
:This is anything the user should know about a function in order to use it. For example exceptional cases and recommended ways to handle the function should all be detailed here, as well as additional info about possible reasons for failure and how to deal with them.
Related
:A comma seperated list of functions or structures related to the function.
Link
:A link to additional information about the function. For many system function wrappers, this will be <code>@@MsdnLink@@ FunctionName</code>, which represents that the user should search MSDN for the function.
Example
:A simple yes or no value specifying whether the function has an example. If this is no then your UDF is not ready to be released. The [[#Examples]] section has more information on the format and location of examples.

The easiest way to generate the header is to copy and paste the following blank template in:

<syntaxhighlight lang="autoit">; #FUNCTION# ====================================================================================================================
; Name...........:
; Description ...:
; Syntax.........:
; Parameters ....:
; Return values .:
; Author ........:
; Modified.......:
; Remarks .......:
; Related .......:
; Link ..........:
; Example .......:
; ===============================================================================================================================</syntaxhighlight>

There are also a number of plugins for SciTE that will generate a header and maybe fill in certain known values for you such as Name, Syntax and Parameters. The most complete one that conforms to these standards is [http://code.google.com/p/m-a-t/wiki/UDFHeaderGenerator here], but there are two others [http://www.autoitscript.com/forum/topic/28270-lua-script-for-udf-header/ here] and [http://www.autoitscript.com/forum/topic/28270-lua-script-for-udf-header/page__view__findpost__p__200823 here].

=== Internal use only ===
Functions can also be marked for use only within the library and not to be documented for use by the user. These are named according to the same rules as normal functions but begin with a double underscore ("__"). The header is exactly the same except with the first line replaced, to make the blank template:

<syntaxhighlight lang="autoit">; #INTERNAL_USE_ONLY# ===========================================================================================================
; Name...........:
; Description ...:
; Syntax.........:
; Parameters ....:
; Return values .:
; Author ........:
; Modified.......:
; Remarks .......:
; Related .......:
; Link ..........:
; Example .......:
; ===============================================================================================================================</syntaxhighlight>

== Structures ==
Structures are defined as global constants, and follow the naming pattern <code>$tagSTRUCTNAME</code>. The struct name should be as it appears on MSDN if it's used in the windows API, or follow a similar pattern if not. It should go without saying that they must work for both 32 and 64 bit machines, including resolving any alignment issues. Elements should also be named as they appear on MSDN if they are taken from there, which includes the hungarian notation prefix. Although many standard UDFs do not follow that rule, importantly <code>StructureConstants.au3</code>, the rule still stands.

=== Headers ===
Structures need a header similar to functions, but with some minor differences. The same rules apply in terms of wrapping and line length however. The header follow this standard template:

<syntaxhighlight lang="autoit">; #STRUCTURE# ===================================================================================================================
; Name...........: $tagPOINT
; Description ...: Defines the x and y coordinates of a point
; Fields ........: X - Specifies the x-coordinate of the point
; Y - Specifies the y-coordinate of the point
; Author ........: Paul Campbell (PaulIA)
; Remarks .......:
; Related .......:
; ===============================================================================================================================
Global Const $tagPOINT = "long X;long Y"</syntaxhighlight>

It is essentially a shortened header, with the only thing new is the Fields line, which effectively replaces the Parameters field in terms of usage. All the same rules apply as listed [[#Function Header Fields|here]].

The blank template is:

<syntaxhighlight lang="autoit">; #STRUCTURE# ===================================================================================================================
; Name...........:
; Description ...:
; Fields ........:
; Author ........:
; Remarks .......:
; Related .......:
; ===============================================================================================================================</syntaxhighlight>

Structures may also be marked for internal use only. In this case the header ramains the same, but the sections first line changes. The blank template is:

<syntaxhighlight lang="autoit">; #INTERNAL_USE_ONLY# ===========================================================================================================
; Name...........:
; Description ...:
; Fields ........:
; Author ........:
; Remarks .......:
; Related .......:
; ===============================================================================================================================</syntaxhighlight>

== Variables ==
For code readability, there are special rules dealing with variables, particularly naming. All variables should be declared at the beginning of their scope, which usually means at the start of the function in which they are used, but could mean the top of the UDF itself in the [[#Variables|Variables section]].

=== Naming ===
A variables first letter signifies the expected type of the variable. This should be as follows:

* <code>$a<letter></code> - Array (the following letter describes the data type taken from the rest of the data types below, if it varies then <code>v</code> should be used. A counter as the first element is ignored, so the array returned by StringSplit (with default options) would actually be marked as $as despite the integer in the zeroeth element).
* <code>$d</code> - Binary data.
* <code>$h</code> - Handle, usually to a file or window. NB: AutoIt handled controls return IDs, and so use $id instead.
* <code>$id</code> - An AutoIt control Id.
* <code>$i</code> - Integer.
* <code>$b</code> - Boolean.
* <code>$f</code> - Floating point number.
* <code>$n</code> - general number with no preference for floating point or integral.
* <code>$s</code> - String.
* <code>$v</code> - Variant (unknown/variable type of data) .
* <code>$p</code> - Pointer. It is assumed that it points to a struct so no further letters are needed. The type of struct being pointed to should be inferrable from the variable name e.g. <code>$pWindowRect</code> can be assumed to be a pointer to a <code>$tagRECT</code> structure.
* <code>$t</code> - Structure returned from DllStructCreate.
* <code>$tag</code> - Struct definition string.Structure definitions should conform to the structure guidelines.

=== Globals ===
The use of globals in a UDF is generally frowned upon, and byref parameters and static variables should be used where possible instead. However, in cases where this is not possible and a global must be used they should be defined using the following naming pattern: <code>$__g<VARNAME>_<UDF></code> where <code><VARNAME></code> is the name as it would usually appear according to the variable naming rules above and <code><UDF></code> is the name of the library in which it appears. This ensures there will never be a conflict with user variables of other UDF globals. They should be declared at the top of the UDF in the Variables section.

Globals are always private. If they need to be accessed by the user then functions need to be written wrapping that operation and values should be checked. Notable exceptions are debug variables, which are designed for developer purposes and may be used by some users in extreme cases. These are named <code>$Debug_<UDF></code> although the <code><UDF></code> part is often shortened so <code>GUIEdit.au3</code> uses <code>$Debug_Ed</code>. It is not required that a UDF has debugging symbols, but they are allowed to remain in releases.

=== Constants ===
There are two types of constants, internal and public. Public constants are designed to be utilised by the user, and are referenced in functions that use them. They include styles and flags. Internal constants are designed for use only within the library, so that values used fairly often can be held in one place to allow for easy updating. Both kinds of constant are always typed in all upper case. Constants taken from the windows API should appear exactly as they are defined there, but internal constants follow the naming pattern: <code>$__<UDF>CONSTANT_<NAME></code>.

=== The <code>Dim</code> statement ===
Should not be used.

== Examples ==
All functions and structures that are made public to the user need to have a good quality example. This means that it should:

* Be simple. Ideally the only functions used are basic functions like ConsoleWrite and MsgBox and the function that the example is written for. Writing a single example that covers a wide range of functions is not nearly as easy to use as writing an example per function that clearly demonstrates its use.
* Be readable. Everything should be explained step by step in comments.
* Be correct. In addition to passing the same Au3Check flags as the UDF itself (<code>-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7</code>) it should always be written with best practice being the main consideration. This takes preference over the first point, just because code is shorter and looks easier doesn't mean it's right.
* Examples should represent all the functionality. If there are more than one ways of using a function then include more than one example of how to use it.

Examples are stored in individual files called <code><FUNCTION>.au3</code>. The files should be kept in a folder called <code>Examples</code>. To remain correct all examples should be wrapped in functions, such that the only code executed in the global scope is calling the function. This is usually named <code>Example</code>, though where multiple examples exists they are named <code>Example1</code>, <code>Example2</code>, ..., <code>ExampleN</code>.

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

Opt("MustDeclareVars", 1)

Example()

Func Example()
Local $idButton_1, $idButton_2, $iMsg, $hGUI

$hGUI = GUICreate("My GUI Button") ; Will create a dialog box that when displayed is centered

$idButton_1 = GUICtrlCreateButton("Run Notepad", 4, 4, 80, 30)
$idButton_2 = GUICtrlCreateButton("Button Test", 4, 38, 80, 30)

GUISetState() ; will display a dialog box with 2 button

; Run the GUI until the dialog is closed
While 1
$iMsg = GUIGetMsg()
Select
Case $iMsg = $GUI_EVENT_CLOSE
ExitLoop
Case $iMsg = $idButton_1
Run("Notepad.exe") ; Will Run/Open Notepad
Case $iMsg = $idButton_2
MsgBox(0, "Testing", "Button 2 was pressed") ; Will demonstrate Button 2 being pressed
EndSelect
WEnd
GUIDelete($hGUI)
EndFunc ;==>Example</syntaxhighlight>

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

<syntaxhighlight lang="autoit">#include-once

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

; #INDEX# =======================================================================================================================
; Title .........: MyUDF
; AutoIt Version : 3.3.6.1
; Language ......: English
; Description ...: An example UDF that does very little.
; ===============================================================================================================================

; #CURRENT# =====================================================================================================================
;$tagMYSTRUCT
;_MyUDF_Function
; ===============================================================================================================================

; #STRUCTURE# ===================================================================================================================
; Name...........: $tagMYSTRUCT
; Description ...: An example of a structure.
; Fields ........: hFoo - A handle to foo that does something.
; iBar - An integer that does something.
; Author ........: Matt Diesel (Mat)
; Remarks .......:
; Related .......: _MyUDF_Function
; ===============================================================================================================================
Global Const $tagMYSTRUCT = "ptr hFoo; int iBar"

; #FUNCTION# ====================================================================================================================
; Name...........: _MyUDF_Function
; Description ...: A function that does something.
; Syntax.........: _MyUDF_Function(ByRef $avAnArray, $iAnInt[, $hAHandle = 0[, $nSomeNumber = 42]])
; Parameters ....: $avAnArray - [byref] An array of anything. The value of anything is changed and passed out using this
; parameter. The array should only have one dimension
; $iAnInt - An integer that does very little.
; $hAHandle - [optional] A handle. Default is zero.
; $nSomeNumber - [optional] A number of some kind. Default is 42.
; Return values .: Success - A MYSTRUCT structure.
; Failure - Returns zero and sets the @error flag:
; |1 - The $avAnArray is invalid.
; Author ........: Matt Diesel (Mat)
; Modified.......:
; Remarks .......:
; Related .......: $tagMYSTRUCT
; Link ..........:
; Example .......: No
; ===============================================================================================================================
Func _MyUDF_Function(ByRef $avAnArray, $iAnInt, $hAHandle = 0, $nSomeNumber = 42)
; 1 - Error Checking for parameters.
If Not IsArray($avAnArray) Or UBound($avAnArray, 0) <> 1 Then Return SetError(1, 0, 0) ; The $avAnArray is invalid.

; 2 - Declaration of locals.
Local $tMS = DllStructCreate($tagMYSTRUCT)

; 3 - Function code
DllStructSetData($tMS, "hFoo", $hAHandle)
DllStructSetData($tMS, "iBar", $iAnInt * $nSomeNumber)

Return $tMS
EndFunc ;==>_MyUDF_Function</syntaxhighlight>

Talk:UDF-spec

2012-09-24T18:30:41Z

Mdiesel:

Talk:User Defined Functions

2012-09-24T18:28:12Z

Mdiesel: Explained link removal and changes to wrappers thread

This page should really be a spin-off from: http://www.autoitscript.com/forum/index.php?showtopic=19370
[[User:Manadar|Manadar]] 13:12, 27 May 2009 (UTC)

== Migrated UDF List here ==

The old page can still be seen here: http://www.autoitscript.com/w/index.php?title=UDF_List&action=edit

== Changes to AutoIt wrappers ==

Currently the old wrappers forum thread by valuator is locked and is being migrated to the wiki (link?). I have just removed the outdated link for now.
--[[User:Mat|Mat]] 19:28, 24 September 2012 (BST)

User:Mdiesel

2011-11-16T15:21:33Z

Mdiesel:

AutoIt Forum profile: http://www.autoitscript.com/forum/index.php?showuser=46719

Website: http://matdiesel.co.uk/

AutoIt scripts page: http://code.google.com/p/m-a-t/

AutoIt projects list: http://code.google.com/p/m-a-t/wiki/WhatIveDone

email: Mat@Weirdness.com

File:Autoit-1-2-3.jpg

2009-05-27T13:41:39Z

Mdiesel: The AutoIt-1-2-3 getting started screen. Here it gives you links to important links, and also allows you to run the demo's that come with the program.

The AutoIt-1-2-3 getting started screen. Here it gives you links to important links, and also allows you to run the demo's that come with the program.

AutoIt Environment

2009-05-27T13:33:49Z

Mdiesel: /* Choosing a Text Editor */

== Install Directory Structure ==

The installation directory for AutoIt (usually located in ''\Program Files\AutoIt3\'') looks like this:

{| border="1" cellpadding="3" cellspacing="0" width="100%"
|+ «AutoIt v3 Install Directory Structure — As of v3.1.1.0»
! align="center" style="background:#666666; color:#FFFFFF" | Files / Directories
! align="center" style="background:#666666; color:#FFFFFF" | Description
|- valign="middle"
| AutoIt3.exe
| The AutoIt v3 Main Program (typically, the only file required to run scripts)
|- valign="middle"
| AU3Info.exe
| The AutoIt Active Window Info tool (was AU3_Spy.exe)
|- valign="middle"
| AutoIt.chm
| The AutoIt v3 Help file
|- valign="middle"
| PSAPI.DLL
| <tt>Process...()</tt> function Helper DLL (required for Windows® NT 4; Microsoft® redistributable file)
|-
|||
|- valign="middle"
! style="background:#EEEEEE;" | Aut2Exe \
| style="background:#EEEEEE;" | AutoIt Script Compiler Components
|- valign="middle"
| Aut2Exe \ Aut2Exe.exe
| The Script Compiler
|- valign="middle"
| Aut2Exe \ AutoItSC.bin
| Executable Stub included into compiled scripts
|- valign="middle"
| Aut2Exe \ upx.exe
| The UPX Compressor (for compressing compiled scripts)
|- valign="middle"
| Aut2Exe \ Icons \
| Icons for use in compiled scripts
|-
|||
|- valign="middle"
! style="background:#EEEEEE;" | AutoItX \
| style="background:#EEEEEE;" | AutoIt Extension Samples
|- valign="middle"
| AutoItX \ ActiveX \
| Include AutoIt in Windows® Script as an ActiveX® Component
|- valign="middle"
| AutoItX \ StandardDLL \
| Include AutoIt in any program as a Dynamic Link Library
|-
|||
|- valign="middle"
! style="background:#EEEEEE;" | Examples \
| style="background:#EEEEEE;" | Example AutoIt scripts
|- valign="middle"
| Examples \ GUI \
| Example GUI scripts
|- valign="middle"
| Examples \ Helpfile \
| Example scripts from the Help file
|-
|||
|- valign="middle"
! style="background:#EEEEEE;" | Extras \
| style="background:#EEEEEE;" | Third-party / Contributed files provided for convenience
|- valign="middle"
| Extras \ AutoUpdateIt \
| Check for and install updates to AutoIt
|- valign="middle"
| Extras \ Editors \
| Syntax highlighting files for popular code editors (with auto-install scripts)
|- valign="middle"
| Extras \ Exe2Aut \
| Compiled script decompilers (convert .exe back to .au3, if compiled with ''Allow_Decompile'')
|- valign="middle"
| Extras \ v2_to_v3_Converter \
| An AutoIt v2.64 to v3 script converter
|-
|||
|- valign="middle"
! style="background:#EEEEEE;" | Icons \
| style="background:#EEEEEE;" | Icons used for .au3 filetype icon in Explorer®
|-
|||
|- valign="middle"
! style="background:#EEEEEE;" | Include \
| style="background:#EEEEEE;" | Standard include files (pre-written user functions; see Library Functions in Help file)
|}

It should be stressed that to run AutoIt scripts, the only required file is '''AutoIt3.exe'''. If you compile a script into an executable then a user does not require AutoIt to be installed to run that compiled executable.

Exception: Under Windows® NT 4, the file '''PSAPI.DLL''' needs to be in the path or the AutoIt directory for the <tt>Process...()</tt> related functions to work.


:•  Updated to reflect the directory structure of AutoIt v3.1.1.0. 
:•  Duplicate listing of the '''Aut2Exe''' directory was removed.  I assume this was supposed to be '''AutoItX'''.


== Choosing a Text Editor ==

Since Autoit scripts are simple text files, you can use any text editor to author your scripts. Even the humble '''Notepad''' that comes with Windows!

However, there are substantial benefits to be had from more sophisticated text editors, including:
* Multi-document Interface (MDI) - which allows for editing several soure files simultaneously (useful when you start using AU3's #[[Compiler directives|include]], or want to copy between files.
* Project files - allowing you to identify a single shortcut when launching your text editor, which will instruct it to open a specific set of source files.
* Enhanced Search & Replace functionality.
* Source-code highlighting - based on the AU3 syntax.
* "Folding" - where portions of the file can be hidden from view to allow for easier editing.
* ClipBooks - some editors have a feature where you can store frequently used code snippets and copy them in at a click while coding.
* CHM interface - allowing quick and easy reference to the help file that comes with Autoit.
* Customisable tools - useful when you want to run a script ''from within'' the text editor.

These features and more are available in text editors that are free or shareware. There are regular debates on the forums about which editor is the best, but in the end it all boils down to a personal choice. The following editors are very popular amongst AutoIt users:

===Text Pad===
Text Pad is a shareware text editor from Helios Software Solutions. It is available for download at http://www.textpad.com. It is an excellent general purpose editor, and AutoIt comes with syntax files for Text Pad. You can also run scripts you are editing directly from inside TextPad. It is particularily good at editing many files at once, and is able to perform find and replace operations on many files at the same time.

Text Pad costs £16.50 British pounds, which is about €24.80 Euros or $30.10 USD. The evaluation version does not expire - it simply pops up reminder messages to register once in a while.

===SciTE===
The current editor used by the majority of AutoIt users is SciTe, the AutoIt development team has created a custom version of SciTe with full syntax highlighting that also integrates various third-party AutoIt tools (like syntax checking and script tidying). A "lite" version of the SciTE editor comes with the AutoIt installation package. The full AutoIt version of SciTe that comes with all to tools can be downloaded seperately at http://www.autoitscript.com/autoit3/scite/

===Crimson Editor===
[http://www.crimsoneditor.com/ Crimson Editor] is a free source code editor that supports syntax highlighting, customizable commands and pluggable extensions.

===Notepad ++===
[http://notepad-plus.sourceforge.net/ NotePad ++] is a free/open source source code editor. It supports syntax highlighting, macros, etc. It uses the powerful Scintilla editor component. Now includes Syntax Highlighting for AutoIt by default.

===jEdit===
[http://www.jedit.org/ jEdit] is an open source, Java based programmer's text editor. Some of its features include:

* Written in Java, so it runs on Mac OS X, OS/2, Unix, VMS and Windows.
* Built-in macro language; extensible plugin architecture. Dozens of macros and plugins available.
* Plugins can be downloaded and installed from within jEdit using the "plugin manager" feature.
* Auto indent, and syntax highlighting for more than 130 languages.
* Supports a large number of character encodings including UTF8 and Unicode.
* Folding for selectively hiding regions of text.
* Word wrap.
* Highly configurable and customizable.
* Every other feature, both basic and advanced, you would expect to find in a text editor. See the [http://www.jedit.org/index.php?page=features features] page for a full list.

===PSPad===
[http://www.pspad.com/en/ PSPad] is a freeware programmer's editor for Microsoft Windows operating systems, useful for people who:

* work with various programming environments
* like highlighted syntax in their source code
* need a small tool with simple controls and the capabilities of a mighty code editor
* are looking for a tool that handles plain text
* want to save time - PSPad offers rich text formating functions
* need tool what offer user extension capabilities
* want to save money and still have the functionality of professional products because PSPad is free for commercial and government purposes too