ExecuteIfBound

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 safely serialized to disk. Additionally, delegates may define "payload" data which will 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

• Up to eight function parameters

• 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.

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 table at the bottom of this documentation comment for the macro names to use for each function signature type.

DELEGATES EXAMPLE

Suppose you have a class with a method that you'd like to be able to call from anywhere:

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'.

Here's an example of how you'd use this 'FStringDelegate' in a class:

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?

Note 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:

/**