Delegate

From Xojo Documentation

Revision as of 21:03, 17 January 2019 by PLefebvre (talk | contribs) (See Also)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Data Type


A Delegate data type is an object representing a specific method.

Notes

A Delegate data type is an object representing a specific method. It is a function pointer with a method signature.

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 run-time 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.

Methods
Invoke
Constructors

Delegate.Constructor(p As Ptr)


Usage

For use in XojoScript code:

Delegate Sub name [(parameterList)]
or
Delegate Function name ([parameterList]) As type

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.
type Optional. The data type of the value returned by the function.

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.

fa-info-circle-32.png
While delegates are objects, you cannot create a subclass of a delegate 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:

Dim pp As Ptr = AnOSFunctionThatReturnsAFunctionPointer()
Dim 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.

Dim 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 Delegate.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.Append 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

You should also provide a method to Unregister a Delegate to remove it from the array.


See Also

Dim, Static, Declare statements; -, +, *, /, <, <=, =, >=, >, <> VarType functions; AddHandler, Boolean, Byte, CFStringRef, Color, CString, Currency, Delegate, Double, Int16, Int32, Int64, Int8, Integer, OSType, PString, Ptr, Short, Single, String, UInt16, UInt32, UInt64, UInt8, Variant, WindowPtr, WString data types. IsNumeric, Mod, Str, Val, Vartype, functions.