Template Callbacks

ClanLib includes a complete signalling library – a signal library is a C++ template library that allow you to use type-safe C++ templates to setup function callbacks.

The library currently supports two different types of callback templates:

  • Signals and slots
  • Callbacks

Signals and Slots

A signal is an object that, when emitted, invokes one or more slot functions. This setup allows a one-way messaging system that informs a number of functions whenever a certain event occours. A simple example with one signal and two slot functions:

void slot_function1(int p1, int p2)
{
clan::Console::write_line("Slot 1: %1,%2", p1, p2);
}
void slot_function2(int p1, int p2)
{
clan::Console::write_line("Slot 2: %1,%2", p1, p2);
}
// Create signal and hook up slots:
clan::Slot slot1 = signal.connect(&slot_function1);
clan::Slot slot2 = signal.connect(&slot_function2);
// Emit signal:
signal.invoke(21, 42);

The 'v2' part of clan::Signal_v2 indicates that the slot functions returns void and take 2 parameters. The types of the parameters are then defined as int, int. When the clan::Slot handle object returned by clan::Signal_vX::connect is destroyed, the slot function is disconnected from the signal. If you plan to connect a lot of slots to signals, the clan::SlotContainer class may come in handy:

void slot_function1(int p1, int p2, clan::String p3);
void slot_function2(int p1, int p2, clan::String p3);
slots.connect(signal, &slot_function1);
slots.connect(signal, &slot_function2);
signal.invoke(21, 42, "text");

Just like with the clan::Thread::start and clan::string_format functions, the slot callback function can be placed in a class and have additional fixed parameters passed along:

class MyClass
{
public:
void slot_func(int p1, int p2, int user1);
};
MyClass my_class;
my_class.slots.connect(signal, &my_class, &MyClass:slot_func, 100);
my_class.slots.connect(signal, &my_class, &MyClass:slot_func, 200);
signal.invoke(21, 42);

Callbacks

The second type of callback template classes available is clan::Callback_X. It simply calls one callback function when invoked, just like a standard C style function pointer would do.

int callback_function(int p1, int p2)
{
return p1 + p2;
}
callback.set(&callback_function);
int result = callback.invoke(21, 42);

Callbacks are used in many ClanLib classes, like the func_expired callback in clan::Timer :

clan::Callback_v0 &func_expired();
class MyClass
{
clan::Timer timer;
....
}
void MyClass::on_timer_expired()
{
... do something when the timer expires ...
}
void MyClass::initialize_timer()
{
timer.func_expired().set(this, &MyClass::on_timer_expired);
}