DataType
Delegate
Description
A Delegate data type is an object representing a specific method.
Usage
For use in XojoScript code:
Delegate Sub name (parameterList)
or
Delegate Function name (parameterList) As DataType
Part |
Description |
---|---|
name |
Required. The name of the delegate. |
parameterList |
Optional: List of values representing parameters that are passed to the method when it is called. Multiple parameters are separated by commas. |
DataType |
Optional. The data type of the value returned by the function. |
Important
Only Global delegates defined in a Module are currently supported with Android.
Methods
Name |
Parameters |
Returns |
Shared |
---|---|---|---|
p As Ptr |
|||
[parameter1 As Type, parameterN As Type] |
Type |
Method descriptions
Delegate.Constructor
Constructor(p As Ptr)
Note
Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.
The Delegate type's constructor takes a single Ptr, which is assumed to be correct for the Delegate type.
Important
This Constructor is not supported for Android.
Assume there is a Delegate declared as SimpleProc:
Var pp As Ptr = AnOSFunctionThatReturnsAFunctionPointer()
Var sp As New SimpleProc(pp)
sp.Invoke()
Delegate.Invoke
Invoke([parameter1 As Type, parameterN As Type]) As Type
Call the method pointed by the Delegate. You must pass the same parameters as the method's ones and, if the method returns a value, you must use the return value as well.
If you defined a Delegate as:
Delegate Sub myDelegateMethod(x As Integer, y As Integer, s As String)
then you must use Invoke with the same parameters' type, as in:
Var d As myDelegateMethod
' <— Set d as your code requires
d.Invoke(1, 10, "An example string") ' Values are indicative
By contrast, if the Delegate is set to return a value as in:
Delegate Function myDelegateMethod(x As Integer, y As Integer, s As String ) As Boolean
then you must use the value returned by Invoke, as in:
Var d As myDelegateMethod
Var b As Boolean
' <— Set d as your code requires
b = d.Invoke(1, 10, "An example string") ' Values are indicative
Notes
A Delegate is a function pointer with a method signature. It has a single method, “Invoke” whose parameters and return value match the Delegate's parameters and return type. The Invoke method calls the method the Delegate instance represents.
Note
While delegates are objects, you cannot create a subclass of a Delegate type.
Delegates decouple interface from implementation in a similar way to events or interfaces. This decoupling allows you to treat a method implementation as a variable that is changeable based on runtime conditions. They represent methods that are callable without knowledge of the target object. You can change the function the Delegate points to on the fly.
A Delegate can be declared in either a module or a class. You use the Project > Add > Delegate menu command or the (optional) Add Delegate button in the Code Editor to create a Delegate entry.
A Delegate must have a name and can have optional parameters and a return type.
Creating a delegate value
Once you have added the Delegate as described above, create a variable or property of your Delegate type. For example, if you named your Delegate MyDelegate, you would declare a variable or property with myProp As MyDelegate.
There are two ways to create values that can be stored in delegates:
Usually, AddressOf (and WeakAddressOf) are used, taking an existing method and returning a function pointer in form of a Delegate.
The other way is to specify a function pointer address of type Ptr, passing it to a Delegate constructor. Assuming that there's a Delegate declared as Sub SimpleProc(), this could work as follows:
Var pp As Ptr = AnOSFunctionThatReturnsAFunctionPointer()
Var sp As New SimpleProc(pp)
sp.Invoke()
Sample code
Suppose you've added a Delegate named MethodCaller with no parameters or return type, and there is a checkbox MethodCheck that will determine which method to use.
Var callMethod As MethodCaller
If MethodCheck.Value Then
callMethod = AddressOf TestMethod
Else
callMethod = AddressOf AnotherMethod
End If
callMethod.Invoke
If you've defined your Delegate with parameters and a return type, the code might look like this instead:
someValue = callMethod.Invoke(param1, param2)
See the Invoke method for more examples.
A Delegate is a good way to allow one object to send the same message to various other objects. You can define a Register method that takes the Delegate as a parameter and adds it to an array of your Delegate type.
Sub Register (d As MessageDelegate)
MessageDelegateArray.Add(d)
End Sub
When you need to send a message, you can call each Delegate in the array in a loop.
Sub SendMessage (msg As String)
For Each d As MessageDelegate In MessageDelegateArray
If d <> Nil Then
d.Invoke(msg)
End If
Next d
End Sub
Compatibility
All project types on all supported operating systems.
See also
Var, Static, Declare statements; -, +, *, /, <, <=, =, >=, >, <> VarType functions; AddHandler, Boolean, Byte, CFStringRef, Color, CString, Currency, Double, Int16, Int32, Int64, Int8, Integer, OSType, PString, Ptr, Int16, Single, String, UInt16, UInt32, UInt64, UInt8, Variant, DesktopWindow.Handle, WString data types. IsNumeric, Mod, Str, Val, Vartype, functions.