Overview

The Unreal Engine provides different ways to call functions.

• Delegates
  • Single-cast
  • Multi-cast

• Lambas
  • TFunction
  • TFunctionRef

Delegate

A delegate is a pointer to a C++ function.

A delegate is bound to a function with a certain signature.

• The signature of a function is determined by its parameters and return type.

• The name of the parameters are not part of the function's signature.

There are two kind of delegates: single-cast and multi-cast delegates.

Single-Cast Delegate

A single-cast delegate is bound to only one function.

To declare a single-cast delegate, use the following macros:

• DECLARE_DELEGATE – single-cast delegate.

• DECLARE_DELEGATE_<Num>Params – single-cast delegate with Num parameters.

• DECLARE_DELEGATE_RetVal_<Num>Params – single-cast delegate with a return value and Num parameters.

• DECLARE_DYNAMIC_DELEGATE – dynamic single-cast delegate.

DECLARE_DELEGATE(Delegate)
DECLARE_DELEGATE_OneParam(IntDelegate, int32)

Internally, a single-cast delegate is represented by TScriptDelegate.

Multi-Cast Delegate

A multi-cast delegate can be bound to multiple functions and execute them all at once.

Multi-cast delegate are not allowed to use a return value.

To declare a multi-cast delegate, use the following macros:

• DECLARE_MULTICAST_DELEGATE – multi-cast delegate.

• DECLARE_MULTICAST_DELEGATE_<Num>Params – multi-cast delegate with Num parameters.

• DECLARE_DYNAMIC_MULTICAST_DELEGATE – dynamic multi-cast delegate.

DECLARE_MULTICAST_DELEGATE(MultiDelegate)
DECLARE_MULTICAST_DELEGATE_OneParam(IntMultiDelegate, int32)

Internally, a single-cast delegate is represented by TMulticastScriptDelegate.

Binding

Single-Cast Delegate

1. To bind a function to a delegate, call BindUFunction.

   Delegate MyDelegate;
   MyDelegate.BindUFunction(this, FName("MyFunction"));
   
   IntDelegate MyIntDelegate;
   MyIntDelegate.BindUFunction(this, FName("MyIntFunction"));

2. To check if a delegate is safe to execute, call IsBound.

3. To call the function bound to the delegate, call Execute.

   Delegate.Execute();
   
   MyIntDelegate.Execute(42);

Multi-Cast Delegate

1. To bind functions to a delegate, call AddUFunction for each function.

   MultiDelegate MyMultiDelegate;
   MyMultiDelegate.AddUFunction(this, FName("MyFunction1"));
   MyMultiDelegate.AddUFunction(this, FName("MyFunction2"));
   
   IntMultiDelegate MyIntMultiDelegate;
   MyIntMultiDelegate.AddUFunction(this, FName("MyIntFunction1"));
   MyIntMultiDelegate.AddUFunction(this, FName("MyIntFunction2"));
   MyIntMultiDelegate.AddUFunction(this, FName("MyIntFunction3"));

2. To check if a delegate is safe to execute, call IsBound.

3. To call the functions bound to the delegate, call Broadcast.

   ⚠️

   The execution order of the functions is not defined.

   MultiDelegate.Broadcast();
   
   MyIntMultiDelegate.Broadcast(42);

TFunction

A TFunction represents a copy to something callable.

template <typename FuncType>
class TFunction

The FuncType template parameter represents a function type.

When declaring a TFunctionRef, the parameter names for FuncType are optional.

For example, a function taking a string and float and returning an int32.

TFunctionRef<int32 (const FString&, float)>
TFunctionRef<int32 (const FString& Name, float Scale)>

TFunction is similar to std::function.

• It takes a copy of whatever is bound to it.

• It can be returned from functions.

• It can be stored in variables.

TFunctionRef

A TFunctionRef represents a reference to something callable.

template <typename FuncType>
class TFunctionRef

TFunctionRef is different from TFunction and std::function.

• TFunctionRef does not have ownership of the lambda.

• If TFunctionRef is bound to a lambda and the lambda goes out of scope, it will become an invalid reference.

• It cannot be copied and does not have an operator bool.

However, TFunctionRef is more efficient than TFunction.

TFunctionRef is useful to parameterize a function with some caller-defined code without making it a template.