AutoIt: UDFs

Was bedeutet UDF?

UDF ist die Abkürzung von User Defined Functions (=Von Benutzern erstellte Funktionen).

Andere Benutzer von AutoIt bzw. Sie selber können eigene Funktionen erstellen und können diese anderen Leuten zur Verfügung stellen. Genaueres zum Definieren von Funktionen finden Sie unter AutoIt: Funktionen.

Was ist zu beachten?

Name der Funktion

Der Name sollte an keine andere Funktion bereits vergeben sein. Außerdem sollte er mit einem Unterstrich (_) beginnen, der symbolisiert, dass es sich um eine UDF handelt. Der Name sollte richtig gewählt sein, d.h. das erste Wort sollte die Kategorie beschreiben, so heißt die UDF zum Erstellen eines Internet Explorer-Fenster _IE_Create oder zum Stellen der Computer Uhr _SetTime. Die Wörter sollten am Anfang auch groß geschrieben werden.

Die Namen der Variablen

Grundsätzlich sollten nur diese Variablen benutzt werden:

$a[Zeichen]: Ein Array wobei das zweite Zeichen den Datentyp der darin enthaltenen Werte beschreibt.
$b: Binäre Daten
$h: Datei oder Fensterhandle
$i: Integer
$f: bool'scher Wert, also true oder false
$n: Float
$s: String
$v: Variante (Unbekannter Datentype)
$o: (COM) Objekte
$p: Pointer
$st: DLLStruct

Innerhalb des Namens beginnen dann alle Wörter mit einem Großbuchstaben.

Alternativ können auch eindeutige Variablennamen verwendet werden, die normalerweise nicht benutzt werden würden. Z.B.:

;richtig wäre z.B.
$sSourceWebsiteWikipedia
;für den Source-Code von einer Wikipedia-Seite
;falsch wäre z.B.
$sSource
;das ist einfach zu uneindeutig

Kommentare

Dazu hier beispielhaft ein Codeschnipsel aus Array.au3 mit einer Funktion:

; #INDEX# =======================================================================================================================
; Title .........: Array
; AutoIt Version : 3.2.10++
; Language ......: English
; Description ...: This module contains various functions for manipulating arrays.
; ===============================================================================================================================

; #NO_DOC_FUNCTION# =============================================================================================================
; Not documented - function(s) no longer needed, will be worked out of the file at a later date
; ===============================================================================================================================
;_ArrayCreate
; ===============================================================================================================================

; #CURRENT# =====================================================================================================================
;_ArrayAdd
;_ArrayBinarySearch
;_ArrayCombinations
;_ArrayConcatenate
;_ArrayDelete
;_ArrayDisplay
;_ArrayFindAll
;_ArrayInsert
;_ArrayMax
;_ArrayMaxIndex
;_ArrayMin
;_ArrayMinIndex
;_ArrayPermute
;_ArrayPop
;_ArrayPush
;_ArrayReverse
;_ArraySearch
;_ArraySort
;_ArraySwap
;_ArrayToClip
;_ArrayToString
;_ArrayTrim
;_ArrayUnique
; ===============================================================================================================================

; #INTERNAL_USE_ONLY#============================================================================================================
;__ArrayQuickSort1D
;__ArrayQuickSort2D
;_Array_ExeterInternal
;_Array_Combinations
;_Array_GetNext($iN, $iR, ByRef $iLeft, $iTotal, ByRef $aIdx)
; ===============================================================================================================================

; #FUNCTION# ====================================================================================================================
; Name...........: _ArrayAdd
; Description ...: Adds a specified value at the end of an existing array.
; Syntax.........: _ArrayAdd(ByRef $avArray, $vValue)
; Parameters ....: $avArray - Array to modify
;                  $vValue  - Value to add
; Return values .: Success - Index of last added item
;                  Failure - -1, sets @error
;                  |1 - $avArray is not an array
;                  |2 - $avArray is not a 1 dimensional array
; Author ........: Jos van der Zande <jdeb at autoitscript dot com>
; Modified.......: Ultima - code cleanup
; Remarks .......:
; Related .......: _ArrayConcatenate, _ArrayDelete, _ArrayInsert, _ArrayPop, _ArrayPush
; Link ..........;
; Example .......; Yes
; ===============================================================================================================================
Func _ArrayAdd(ByRef $avArray, $vValue)
	If Not IsArray($avArray) Then Return SetError(1, 0, -1)
	If UBound($avArray, 0) <> 1 Then Return SetError(2, 0, -1)

	Local $iUBound = UBound($avArray)
	ReDim $avArray[$iUBound + 1]
	$avArray[$iUBound] = $vValue
	Return $iUBound
EndFunc   ;==>_ArrayAdd

Dieser Schnipsel ist zwar sehr lang, und es sind alles zwar nur Kommentare, aber gerade diese sind wichtig. Der Schnipsel wird jetzt in einzelne Teile zerlegt:

#INDEX#

Als erstes wird ein sog. Index angelegt:

; #INDEX# =======================================================================================================================
; Title .........: Array
; AutoIt Version : 3.2.10++
; Language ......: English
; Description ...: This module contains various functions for manipulating arrays.
; ===============================================================================================================================

Ausdruck	Nutzen
"#INDEX#"	Zur Kennzeichnung des Indexes
====...	Trennlinie
Title	Der Titel der Datei
AutoIt Version	Die Version, die benutzt wurde, um das Skript zu kompilieren (bei der Beta einfach "(Beta)" anfügen.
Language	Die Sprache der Kommentare etc.
Description	Eine kurze Beschreibung des Inhaltes.
====...	Trennlinie

#CURRENT#

Die Funktionen, die enthalten sind, werden hier aufgelistet. Beispiel:

; #CURRENT# =====================================================================================================================
;_ArrayAdd
;_ArrayBinarySearch
;_ArrayCombinations
;_ArrayConcatenate
;_ArrayDelete
;_ArrayDisplay
;_ArrayFindAll
;_ArrayInsert
;_ArrayMax
;_ArrayMaxIndex
;_ArrayMin
;_ArrayMinIndex
;_ArrayPermute
;_ArrayPop
;_ArrayPush
;_ArrayReverse
;_ArraySearch
;_ArraySort
;_ArraySwap
;_ArrayToClip
;_ArrayToString
;_ArrayTrim
;_ArrayUnique
; ===============================================================================================================================

#FUNCTION#

Dieser Teil bezieht sich auf die unmittelbar folgende Funktion.

; #FUNCTION# ====================================================================================================================
; Name...........: _ArrayAdd
; Description ...: Adds a specified value at the end of an existing array.
; Syntax.........: _ArrayAdd(ByRef $avArray, $vValue)
; Parameters ....: $avArray - Array to modify
;                  $vValue  - Value to add
; Return values .: Success - Index of last added item
;                  Failure - -1, sets @error
;                  |1 - $avArray is not an array
;                  |2 - $avArray is not a 1 dimensional array
; Author ........: Jos van der Zande <jdeb at autoitscript dot com>
; Modified.......: Ultima - code cleanup
; Remarks .......:
; Related .......: _ArrayConcatenate, _ArrayDelete, _ArrayInsert, _ArrayPop, _ArrayPush
; Link ..........;
; Example .......; Yes
; ===============================================================================================================================

Wieder eine Tabelle mit den einzelnen Funktionen der Ausdrücke:

Ausdruck	Funktion
"#FUNCTION#"	Definieren des Funktionen-Bereichs
===...	Trennlinie
Name	Name der Funktion
Description	Eine kurze Beschreibung der Funktion
Syntax	Der Syntax der Funktion
Parameters	Die Parameter, die verwendet werden (s.o.)
Return values	Was zurückgegeben wird (s.u.)
Author	Autor der Funktion
Modified	Status
Remarks	Bemerkungen
Related	verwandte Funktionen
Link	Ein Link
Example	(Yes/No): Ob ein Skript-Beispiel vorhanden ist.

Alle Ausdrücke nach Modified beziehen sich auf die Hilfe.

Rückgabewerte

Rückgabewerte (Return values) sind die Werte, die von der Funktion nach dem Ausführen zurückgeliefert werden. Sie sollten immer überprüft werden. Auch sollte im Falle eines Fehlers immer @error gesetzt werden. Die Rückgabewerte werden auch in #FUNCTION# festgehalten. In unserem Beispiel:

; Return values .: Success - Index of last added item
;                  Failure - -1, sets @error
;                  |1 - $avArray is not an array
;                  |2 - $avArray is not a 1 dimensional array

Hinter Success steht, was bei einem Erfolg geschieht (hier: der Index des zuletzt hinzugefügten Items wird zurückgegeben). Hinter Failure steht, was passiert, wenn ein Fehler auftritt. (Es wird hier -1 zurückgegeben und @error wird gesetzt. @error = 1 bedeutet, das angegeben Array ist gar kein Array, @error = 2 bedeutet das Array ist mehrdimensional.

Aufgaben

Schreiben Sie eine UDF, die das aktuelle Datum aus dem Internet zurückgibt (Bei einem Fehler soll @error gesetzt werden).
Schauen Sie sich mehrere UDFs im Include-Ordner an.
Schreiben Sie ein Skript, das sich auf einer beliebigen Internetseite mit Hilfe von IE.au3 einloggt.

Siehe auch

AutoIt: @error
AutoIt: Funktionsreferenz
AutoIt: Kommentare
AutoIt: Definitionen
AutoIt: Includings
AutoIt: Fehlersuche

< Zurück

Zur Hauptseite

Weiter >