Overview
Examples
Screenshots
Comparisons
Applications
Download
Documentation
Tutorials
UppHub
Status & Roadmap
FAQ
Authors & License
Forums
Funding U++
Search on this site











SourceForge.net Logo

SourceForge.net Logo

GitHub Logo

Discord Logo

Callbacks

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 CallbackTypec)

Copy constructor.

c

Source callback.

 


 

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

cb

Target callback.

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<argumentsb)

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.

b

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<argumentscallback1(Object *object, void (M::*method)(P1, ...), T1 arg1, ...)

 

template <class Object, class M, class P1, ..., class T1, ...>

CallbackType<argumentscallback1(Object *object, void (M::*method)(P1, ...) const, T1 arg1, ...)

 

template <class Object, class M, class P1, ..., class T1, ...>

CallbackType<argumentspteback1(Object *object, void (M::*method)(P1, ...), T1 arg1, ...)

 

template <class Object, class M, class P1, ..., class T1, ...>

CallbackType<argumentspteback1(Object *object, void (M::*method)(P1, ...) const, T1 arg1, ...)

 

template <class P1, ..., class T1, ...>

CallbackType<argumentscallback1(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

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

m

Name of method.

 


 

THISBACK1(x, arg)

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

m

Name of method.

arg

Additional parameter.

 


 

THISBACK2(m, a, b)

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

m

Name of method.

a

First additional parameter.

b

Second additional parameter.

 


 

PTEBACK(x)

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

m

Name of method.

 


 

PTEBACK1(x, arg)

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

m

Name of method.

arg

Additional parameter.

 


 

PTEBACK2(m, a, b)

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

m

Name of method.

a

First additional parameter.

b

Second additional parameter.

 

 

 

 

EventArgTarget

 

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.

 

 

Public Member List

 

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.

value

Value.

Return value

Callback.

 

 

Do you want to contribute?