Callbacks are now deprecated. Use Function/Event/Gate instead!
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.
If you are happy enough to be able to use C++11, you can also assign C++ lambda to Callback using operator << (see bellow).
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.
Generally, callbacks are now defined for up to 5 parameters of target (function, method, another callback).
Callback types:
CallbackType
|
parameters
|
arguments
|
return_type
|
Callback
|
none
|
none
|
void
|
Callback1
|
class P1
|
P1
|
void
|
Callback2
|
class P1, class P2
|
P1, P2
|
void
|
Callback3
|
class P1, class P2, class P3
|
P1, P2, P3
|
void
|
Callback4
|
class P1, class P2, class P3, class P4
|
P1, P2, P3, P4
|
void
|
Callback5
|
class P1, ... , class P5
|
P1, ... , P5
|
void
|
Gate
|
none
|
none
|
bool
|
Gate1
|
class P1
|
P1
|
bool
|
Gate2
|
class P1, class P2
|
P1, P2
|
bool
|
Gate3
|
class P1, class P2, class P3
|
P1, P2, P3
|
bool
|
Gate4
|
class P1, class P2, class P3, class P4
|
P1, P2, P3, P4
|
bool
|
Gate5
|
class P1, ... , class P5
|
P1, ... , P5
|
bool
|
|
[ 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.
|
newaction |
Action. Must be created using new operator. Callback takes over its ownership. |
CallbackType()
Creates an empty callback.
CallbackType(const CallbackType& c)
Copy constructor.
~CallbackType()
Destructor.
void Clear()
Empties the callback.
void ClearTrue()
Only in Gate callbacks.
Clears Gate. After this method is invoked, the Gate performs no actions but returns true.
void ClearFalse()
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.
operator bool() const
|
Return value |
True if the callback is valid. Invoking a valid callback invokes an action. |
return_type Execute(arguments) const
Executes the callback with given set of arguments.
return_type operator()(arguments) const
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.
CallbackTypeAction()
Constructor. Assigns 1 to the reference count.
~CallbackTypeAction()
Virtual destructor.
virtual return_type Execute(arguments) = 0
Performs the action with specified set of arguments.
virtual bool IsValid() const
|
Return value |
true if the Action is valid. Default implementation returns true. |
Atomic count
Member variable used as reference count.
Common Callback/Gate functions
|
|
template <class OBJECT, class METHOD, parameters>
CallbackType<arguments> callback(OBJECT *object, void (METHOD::*method)(arguments))
Creates a callback that invokes the specified method of the specified object.
|
object |
Pointer to the object. |
|
method |
Pointer to the method. |
|
Return value |
Created callback. |
template <class OBJECT, class METHOD, parameters>
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.
|
object |
Pointer to the object. |
|
method |
Pointer to the constant method to invoke. |
|
Return value |
Created callback. |
[ template <parameters> ]
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).
|
object |
Pointer to the object. Must be an ancestor of the Pte class. |
|
method |
Pointer to the method. |
|
Return value |
Created callback. |
[ template <parameters> ]
CallbackType<arguments> callback(void (*fn)(arguments))
Creates a Callback object that invokes a non-member function.
|
fn |
Pointer to the function. |
|
Return value |
Created callback. |
[ 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.
|
Return value |
Created callback. |
[ 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.
|
cb1 |
First target callback. |
|
cb2 |
Second target callback. |
|
Return value |
Created callback. |
[ template <parameters> ]
CallbackType<arguments>& operator<<(CallbackType<arguments> & a, CallbackType<arguments> b)
Operator variant of the previous function. Allows chaining thus imitating callback insertion.
|
a |
First callback. Its value is replaced by a callback that calls both the first and the second callback. |
|
Return value |
Reference to the first callback. |
[ template <parameters> ]
CallbackType<arguments>& operator<<(CallbackType<arguments> & a, C++11Lambda b)
Variant of merging callbacks that can be used for C++11 lambdas.
Storing arguments in callback
|
|
It is possible to store some arguments that are passed to target (function or method) as parameters when creating. If simultaneously passing other parameters in callback call, those passed on call represent beginning arguments and those defined in callback creation fill the rest of arguments.
Again, all this is defined for up to 5 target parameters:
template <class Object, class M, class P1, ..., class T1, ...>
CallbackType<arguments> callback1(Object *object, void (M::*method)(P1, ...), T1 arg1, ...)
template <class Object, class M, class P1, ..., class T1, ...>
CallbackType<arguments> callback1(Object *object, void (M::*method)(P1, ...) const, T1 arg1, ...)
template <class Object, class M, class P1, ..., class T1, ...>
CallbackType<arguments> pteback1(Object *object, void (M::*method)(P1, ...), T1 arg1, ...)
template <class Object, class M, class P1, ..., class T1, ...>
CallbackType<arguments> pteback1(Object *object, void (M::*method)(P1, ...) const, T1 arg1, ...)
template <class P1, ..., class T1, ...>
CallbackType<arguments> callback1(void (*fn)(P1, ...), T1 arg, ...)
P1 (P2, P3 ...) are arguments passed on method invocation, T1 (T2, T3 ...) are parameters stored in Callback object.
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.
THISBACK(x)
Expands to callback(this, &CLASSNAME::m).
THISBACK1(x, arg)
Expands to callback1(this, &CLASSNAME::m, arg).
|
arg |
Additional parameter. |
THISBACK2(m, a, b)
Expands to callback2(this, &CLASSNAME::m, a, b).
|
a |
First additional parameter. |
|
b |
Second additional parameter. |
PTEBACK(x)
Expands to pteback(this, &CLASSNAME::m).
PTEBACK1(x, arg)
Expands to pteback1(this, &CLASSNAME::m, arg).
|
arg |
Additional parameter. |
PTEBACK2(m, a, b)
Expands to pteback2(this, &CLASSNAME::m, a, b).
|
a |
First additional parameter. |
|
b |
Second additional parameter. |
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. |
CallbackArgTarget()
Assigns Null to the output value.
operator const T&() const
|
Return value |
The result. If no CallbackArgTarget was invoked, returns Null. |
bool IsNullInstance() const
|
Return value |
True if there is not Null in output value. |
Callback operator[](const T& value)
Returns a Callback that, when invoked, assigns value to the output value.
|