Callbacks

Callbacks can be described as a very generalized form of function pointers. Each Callback represents some kind of action (usually calling a certain function or a certain object method) that can be invoked at any time.

There are several basic callback types, depending on number of parameters passed and return value. In order to keep description of callbacks short, all these types are described in a single "parametrized" description, with parameters highlighted.

Callback types

[ template <parameters> ]

class CallbackType

Callback type. Callbacks are moveable types with fast deep copy (using reference counting).

explicit CallbackType(CallbackTypeAction<arguments> *newaction)

Constructs callback based from new action.

Creates an empty callback.

CallbackType(const CallbackType& c)

Copy constructor.

Destructor.

Empties the callback.

Only in Gate callbacks.

Clears Gate. After this method is invoked, the Gate performs no actions but returns true.

Only in Gate callbacks.

Clears Gate. After this method is invoked, the Gate performs no actions and returns false. This is the same as Clear.

Executes the callback with given set of arguments.

Same as the Execute method.

[ template <parameters> ]

struct CallbackTypeAction

This is the abstract base class for callback action implementations. Callback holds reference counted pointer to instance of class derived from this class.

Constructor. Assigns 1 to the reference count.

Virtual destructor.

Performs the action with specified set of arguments.

virtual bool IsValid() const

Atomic count

Member variable used as reference count.

Common functions creating callbacks

CallbackType<arguments> callback(OBJECT *object, void (METHOD::*method)(arguments))

Creates a callback that invokes the specified method of the specified object.

CallbackType<arguments> callback(const OBJECT *object, void (METHOD::*method)(arguments) const)

Constant variant of callback. The created Callback object invokes a constant method of the object.

CallbackType<arguments> pteback(OBJECT *object, void (METHOD::*method)(arguments))

Creates a Callback object which is similar to the one created by callback, but which can be safely invoked even after destruction of object (results in no operation).

CallbackType<arguments> callback(void (*fn)(arguments))

Creates a Callback object that invokes a non-member function.

[ template <parameters> ]

CallbackType<arguments> Proxy(CallbackType<arguments>& cb)

Creates a Callback object that invokes another Callback object. Useful for callback routing (e.g. when some parent Ctrl wants to reroute some of its child callbacks via its interface). Note that this function stores a reference to the target callback in the created callback - storing callbacks that are used as Proxy targets in Vector flavor of containers is not a good idea.

[ template <parameters> ]

CallbackType<arguments> callback(CallbackType<arguments>  cb1, CallbackType<arguments>  cb2)

Creates a Callback object that invokes two other callbacks. Note that this function stores a reference to the target callbacks in the created callback - storing callbacks that are used as targets here in Vector flavor of containers is not a good idea. For Gate callbacks, the result of this operation is the boolean value returned by cb2.

[ template <parameters> ]

CallbackType<arguments>& operator<<(CallbackType<arguments> & a, CallbackType<arguments> b)

Operator variant of the previous function. Allows chaining thus imitating callback insertion.

Special functions creating callbacks

Returns a no-parameter callback for a method expecting a single parameter. The parameter is supplied as arg and stored in the Callback.

Constant variant of the previous callback1 routine.

Returns a no-parameter callback for a method expecting a single parameter. Parameter is supplied as arg and stored in the Callback. The created Callback object can be safely invoked even after the object instance is destructed.

Returns a no-parameter callback for a non-member function expecting a single parameter. Parameter is supplied as arg and stored in the Callback.

Returns a single-parameter callback for a method expecting two parameters. Additional parameter is supplied as arg and stored in the Callback.

Constant variant of the previous callback.

Returns a single-parameter callback for a method expecting two parameters. Additional parameter is supplied as arg and stored in the Callback. The created Callback can be safely invoked even after the object instance is destructed.

Returns a single-parameter callback for a non-member function expecting two parameters. Additional parameter is supplied as arg and stored in the Callback.

template <class T, class P>

Callback callback1(Callback1<P> cb, T arg)

Combines a single-parameter callback and an argument into a no-parameter callback.

template <class T, class P1, class P>

Callback1<P1> callback1(Callback2<P1, P> cb, T arg)

Combines a double-parameter callback and an argument into a single parameter callback.

Returns a no-parameter callback for a method taking two parameters. Parameters are supplied as arg1 and arg2. They are stored in the created callback object.

Constant version of the previous callback.

Returns a no-parameter callback for a method taking two parameters. Parameter are supplied as arg1 and arg2. They are stored in the created callback. The created Callback can be safely invoked even after the object instance is destructed.

Returns a no-parameter callback for a non-member function taking two parameters. Parameter are supplied as arg1 and arg2. They are stored in the created callback.

template <class A, class B, class T1, class T2>

Callback callback2(Callback2<A, B> cb, T1 arg1, T2 arg2)

Combines a two-parameter callback and two arguments into a no-parameter callback.

Callback macros

Callback macros reduce verbosity of instance method callbacks. They expect CLASSNAME to be typedef-ed as the type of current class and return method callbacks bound to the this pointer.

Expands to callback(this, &CLASSNAME::x).

Expands to callback1(this, &CLASSNAME::x, arg).

Expands to callback2(this, &CLASSNAME::x, a, b).

Expands to pteback(this, &CLASSNAME::x).

Expands to pteback1(this, &CLASSNAME::x, arg).

Expands to pteback2(this, &CLASSNAME::x, a, b).

CallbackArgTarget

template <class T>

class CallbackArgTarget

This helper class is useful in a situation when a set of callbacks define some output value. Example is pop-up menu that provides selection of one character - in that case, CallbackArgTarget can be used instead of dedicated method to obtain result of user selection.

T    Type of output value. Must be able to be assigned Null.

Constructor. Assigns Null to the output value.

Returns a Callback that, when invoked, assigns value to the output value.