UDF Help!

[PlatinumHex]

I need some help with creating your own UDF.

Please explain to me how a UDF works and such.

I know the most common one is eg: MyFunc()

I seen people using UDF with extra usage in the brackets.

Now how do I do that? Please help me out, ok?

A step-step tutorial would be nice.

I know I'm the worst at searching, but I just could find any thing related to this.

Regards,

Thank you for reading anyway.

[Melba23]

PlatinumHex,

There is a difference between a Function and a UDF (= User Defined Function). The first is usually a section of code that you want to run more than once within your script - so to save yourself typing it out several times, you use a function call to use the same code several times. A UDF is a chunk of complete stand-alone code, usually containing many functions, which does something the basic built-in AutoIt commands cannot. Let us stick with functions for the moment. Are you sitting comfortably? Then here we go....

This is how a function works:

For $i = 2 To 5
    ; Display the square of the number in the loop variable
    _Show_Square()  ; <<<<<<<<<<< this is where we call the function
Next

Func _Show_Square()   ; <<<<<<<<<<<<<<<< this is where we define the function
   MsgBox(0, "Squared", $i^2)
EndFunc

That is obviously a trivial example, but it shows how to call and define a function.

You asked about the additional variables you sometimes see in the () - these are parameters, values that are passed to the function for it to work with. But before we get there, we need to discuss Global and Local variables. A definition:

Global variables are visible everywhere in the script

Local variables are only visible in the function where they are declared.

AutoIt tries to help you by assuming all variables in the main script are Global and any variables declared within a function are Local - but it is good programming practice to declare them explicitly yourself:

Global $Variable_1 = 2

_Function()

;MsgBox(0, "Variables", "I am Local: " & $Variable_2 & @CRLF & "I am Global: " & $Variable_1)

Func _Function()

    Local $Variable_2 = 4
    MsgBox(0, "Variables", "I am Local: " & $Variable_2 & @CRLF & "I am Global: " & $Variable_1)

EndFunc

$Variable_1 is Global and visible everywhere - so _Function can see it and use it. _Function can also see its own Local $Variable_2. But try uncommenting the MsgBox line - you will be told that $Variable_2 has not been declared - because it is Local, it does not exist outside of the function and is destroyed when the function ends.

Now imagine we have 2 functions, one of which calls the other. If the variables in the first function do not exist outside of that function, how can we pass a value to another function? The answer is to use parameters like this:

Global $Variable_1 = 2

_Function_A()

Func _Function_A()

    Local $Variable_2 = 4

    _Function_B($Variable_2)

EndFunc

Func _Function_B($Variable_3)

    MsgBox(0, "Parameter", $Variable_3)

EndFunc

You can see that _Function_A passed its Local $Variable_2 as a parameter to _Function_B, who was therefore able to see and use it.

Enough for now. Any questions?

M23

[kaotkbliss]

thanks Melba, that helped me understand function parameters which I could not understand from the help file

I do have 1 question about the Func _Function_B($Variable_3) line

is that just changing the name of $Variable_2 to $Variable_3?

Edited February 19, 2010 by kaotkbliss

[omikron48]

The value of $Variable_2 is passed into the _Function_B's $Variable_3.

[kaotkbliss]

Great! thanks for the clarification

[Melba23]

kaotkbliss,

is that just changing the name of $Variable_2 to $Variable_3?

Not really.

_Function_A passed its Local $Variable_2 as a parameter to _Function_B. $Variable_2 is still Local to _Function_A - if you try and use it in _Function_B you will get an "Undeclared variable" error. What _Function_B does is create a new Local variable, $Variable_3, which is given the same value as $Variable_2.

I was not intending to this far, but now we are here, it is time to introduce the ByRef keyword.

Normally parameters are passed as I explained above - that is the new variable takes the value of the parameter - this is known as passing By Value. But you can also pass a variable By Reference (or ByRef for short). In this case the second function can actually change the value of the original variable - a sort of limited Global if you like. Take a look at this:

Global $Variable_1 = 2

_Function_A()

Func _Function_A()

    Local $Variable_2 = 4
    Local $Variable_3 = 10

    MsgBox(0, "Start Function_A", "Variable_2: " & $Variable_2 & @CRLF & "Variable_3: " & $Variable_3)

    _Function_B($Variable_2, $Variable_3)

    MsgBox(0, "End Function_A", "Variable_2: " & $Variable_2 & @CRLF & "Variable_3: " & $Variable_3)

EndFunc

Func _Function_B($Variable_4, ByRef $Variable_5)

    MsgBox(0, "Start Function_B", "Variable_4: " & $Variable_4 & @CRLF & "Variable_5: " & $Variable_5)

    $Variable_4 = 40
    $Variable_5 = 100

    MsgBox(0, "End Function_B", "Variable_4: " & $Variable_4 & @CRLF & "Variable_5: " & $Variable_5)

EndFunc

We start with the 2 variables in _Function_A set to 4 & 10. We pass them to _Function_B, and you can see they are the same values. _Function_B plays with them and you can see that they have been changed. But when we go back to _Function_A, only the parameter passed ByRef has changed.

I hope that makes it clearer - or does it confuse even more?

M23

[kaotkbliss]

heh, nope understood. without byref the variable goes back to original value when passed on to another function. byref lets the variable save changes made in current function when passed to a new function

[Melba23]

kaotkbliss,

without byref the variable goes back to original value when passed on to another function. byref lets the variable save changes made in current function when passed to a new function

Hmmm...I would have put it this way:

Without ByRef, any changes are lost when the second function ends. ByRef keeps the changes made by the second function when you return to the first function.

M23

[kaotkbliss]

I thought that's what I said

at any rate, this will help a bunch!

[PlatinumHex]

Thanks a lot Melba23!

I'm definitely gonna save a copy of your tutorial to my HD.

Just another question,

How do you create an UDF with an optional parameter?

[omikron48]

That piece of information is in the help file under Func...EndFunc entry. There's a few rules to follow when incorporating optional parameters into your function. It's all there.

[JohnOne]

Thanks a lot Melba23!

I'm definitely gonna save a copy of your tutorial to my HD.

Just another question,

How do you create an UDF with an optional parameter?

_Function_A(2, 20)

_Function_A(2)

Func _Function_A($Variable_2, $Variable_3 = 10)

    MsgBox(0, "Function_A", "Variable_2: " & $Variable_2 & @CRLF & "Variable_3: " & $Variable_3)

EndFunc

[PlatinumHex]

Thanks you guys!