Function

C++ DELEGATES

This system allows you to call member functions on C++ objects in a generic, yet type-safe way. Using delegates, you can dynamically bind to a member function of an arbitrary object, then call functions on the object, even if the caller doesn't know the object's type.

The system predefines various combinations of generic function signatures with which you can declare a delegate type from, filling in the type names for return value and parameters with whichever types you need.

Both single-cast and multi-cast delegates are supported, as well as "dynamic" delegates which can be serialized to disk and accessed from blueprints. Additionally, delegates may define "payload" data which will be stored and passed directly to bound functions.

DELEGATE FEATURES

Currently we support delegate signatures using any combination of the following:

• Functions returning a value

• Up to four "payload" variables

• Multiple function parameters depending on macro/template declaration

• Functions declared as 'const'

Multi-cast delegates are also supported, using the 'DECLARE_MULTICAST_DELEGATE...' macros. Multi-cast delegates allow you to attach multiple function delegates, then execute them all at once by calling a single "Broadcast()" function. Multi-cast delegate signatures are not allowed to use a return value.

Unlike other types, dynamic delegates are integrated into the UObject reflection system and can be bound to blueprint-implemented functions or serialized to disk. You can also bind native functions, but the native functions need to be declared with UFUNCTION markup. You do not need to use UFUNCTION for functions bound to other types of delegates.

You can assign "payload data" to your delegates! These are arbitrary variables that will be passed directly to any bound function when it is invoked. This is really useful as it allows you to store parameters within the delegate it self at bind-time. All delegate types (except for "dynamic") supports payload variables automatically!

When binding to a delegate, you can pass payload data along. This example passes two custom variables, a bool and an int32 to a delegate. Then when the delegate is invoked, these parameters will be passed to your bound function. The extra variable arguments must always be accepted after the delegate type parameter arguments. MyDelegate.BindStatic( &MyFunction, true, 20 );

Remember to look at the signature table at the bottom of this documentation comment for the macro names to use for each function signature type, and the binding table to see options and concerns for binding.

DELEGATES EXAMPLE

To call the WriteToLog function, we'll need to create a delegate type for that function's signature. To do this, you will first declare the delegate using one of the macros below. For example, here is a simple delegate type: DECLARE_DELEGATE_OneParam( FStringDelegate, FString );

This creates a delegate type called 'FStringDelegate' that takes a single parameter of type 'FString'.

This allows your class to hold a pointer to a method in an arbitrary class. The only thing the class really knows about this delegate is it's function signature.

Now, to assign the delegate, simply create an instance of your delegate class, passing along the class that owns the method as a template parameter. You'll also pass the instance of your object and the actual function address of the method. So, here we'll create an instance of our 'FLogWriter' class, then create a delegate for the 'WriteToLog' method of that object instance: FSharedRef< FLogWriter > LogWriter( new FLogWriter() );

WriteToLogDelegate.BindSP( LogWriter, &FLogWriter::WriteToLog );

You've just dynamically bound a delegate to a method of a class! Pretty simple, right?

that the 'SP' part of 'BindSP' stands for 'shared pointer', because we're binding to an object that's owned by a shared pointer. There are versions for different object types, such as BindRaw() and BindUObject(). You can bind to global function pointers with BindStatic(). Now, your 'WriteToLog' method can be called by FMyClass without it even knowing anything about the 'FLogWriter' class! To call a your delegate, just use the 'Execute()' method: WriteToLogDelegate.Execute( TEXT( "Delegates are spiffy!" ) );

If you call Execute() before binding a function to the delegate, an assertion will be triggered. In many cases, you'll instead want to do this: WriteToLogDelegate.ExecuteIfBound( TEXT( "Only executes if a function was bound!" ) );

That's pretty much all there is to it!! You can read below for a bit more information.

MORE INFORMATION

The delegate system understands certain types of objects, and additional features are enabled when using these objects. If you bind a delegate to a member of a UObject or shared pointer class, the delegate system can keep a weak reference to the object, so that if the object gets destroyed out from underneath the delegate, you'll be able to handle these cases by calling IsBound() or ExecuteIfBound() functions.

the special binding syntax for the various types of supported objects. It's perfectly safe to copy delegate objects. Delegates can be passed around by value but this is generally not recommended since they do have to allocate memory on the heap. Pass them by reference when possible!

Delegate signature declarations can exist at global scope, within a namespace or even within a class declaration (but not function bodies.)

FUNCTION SIGNATURES

Use this table to find the declaration macro to use to declare your delegate. The full list is defined in DelegateCombinations.h

Function signature | Declaration macro

void Function() | DECLARE_DELEGATE( DelegateName ) /**Simple delegate used by various utilities such as timers

Declares a delegate with return value that can only bind to one native function at a time