VCF::CallBack

VCF::CallBack Class Reference

Base class for a function callback. More...

#include <vcf/FoundationKit/Delegates.h>

Inheritance diagram for VCF::CallBack:


Public Types
typedef std::vector< CallBack * >	Vector
Public Member Functions
	CallBack ()
	CallBack (const String &str)
	CallBack (Object *source, const String &str)
void	free ()
	Deletes the instance of the callback.
String	getName () const
	The name of the callback.
virtual Object *	getSource ()
	A callback may, or may not, have a source.
void	addToSource (Object *source)
	Add the callback to a source.
Protected Types
typedef std::vector< Delegate * >	DelegatesArray
Protected Member Functions
void	addDelegate (Delegate *val)
void	removeDelegate (Delegate *val)
virtual	~CallBack ()
Protected Attributes
String	name
DelegatesArray *	delegates_
Friends
class	Delegate
class	ObjectWithCallbacks

Detailed Description

Base class for a function callback.

This class is used to wrap a C++ function pointer, either a static function, or a C++ class member function. The class can have an optional name that may be used to reference it for later use. A callback is attached to delegate. Calling the invoke function on a delegate causes the delegate to pass this along and call an invoke function on all of the callbacks registered with it.

Note that some of the documentation here will introduce methods that are not directly declared on the Delegate base class, but instead are declared and implemented in derived classes. This specifically the case for the invoke(), beginInvoke(), and endInvoke() methods. However their usage is identical, the only difference is in the return type (if any) and the number of function arguments that they take.

A callback may be associated with multiple Delegates. Because of this the callback stores a list of delegates that it is registered with. When the callback is deleted, it will remove it self from any delegates that it is still registered with at that point.

If a callback has a source, then the source will clean up the instance of the CallBack and you don't have to worry about freeing the memory instance. If the callback does not have a source, then it is up to the programmer to delete it.

You cannot call the delete operator directly on a CallBack instance. Instead use the CallBack::free() member function to delete an instance.

Classes that derive from CallBack are classed into 2 main categories, functions that return some type, and functions that have a void return type (they return nothing). The naming convention used is that a procedure refers to a function with a void return type, and a function is used to refer to something that does return something, e.g.

void someFunction( int t );

Note that this is the same as

void* someFunction( int t );

Now we do have an actual return type ( a void pointer ).

Therefore all callback classes that wrap a procedure will be named ProcedureX where X indicates the number of arguments the procedure takes. So

void foobar()

is represented by the class Procedure and

void foobar2( const String, int, bool )

is represented by the class Procedure3.

A callback class that wraps a function is named FunctionX where X is the number arguments that the function takes. For example:

int foobar(char*)

is represented by the class Function1.

Within these two groups there is a further distinction between static functions and functions that are C++ member functions that require a "this" pointer. Consider the following:

int someFunc( int );

class MyClass {
public:
  void doit();
  static void dontDoIt();
};

Both someFunc and MyClass::dontDoIt are considered static functions. However MyClass::doit is a member function, and requires special treatment according to the rules of C++ function binding.

To handle C++ member functions we also derive classes from the various ProcedureX and FunctionX classes. These are named ClassProcedureX and ClassFunctionX where X defines the number of arguments the member function takes. So the following

class MyClass {
public:
  void doit( int, bool );
  static void dontDoIt();
};

uses the callback class ClassProcedure2 wrap MyClass::doit.

Member Typedef Documentation

typedef std::vector<Delegate*> VCF::CallBack::DelegatesArray [protected]

typedef std::vector<CallBack*> VCF::CallBack::Vector

Constructor & Destructor Documentation

VCF::CallBack::CallBack ( ) [inline]

VCF::CallBack::CallBack ( const String & str ) [inline]

VCF::CallBack::CallBack ( Object * source,

const String & str

) [inline]

virtual VCF::CallBack::~CallBack ( ) [inline, protected, virtual]

Member Function Documentation

void VCF::CallBack::addDelegate ( Delegate * val ) [inline, protected]

void VCF::CallBack::addToSource ( Object * source )

Add the callback to a source.
If the Object instance is derived from ObjectWithCallbacks, then the ObjectWithCallbacks::addCallback will get called for you. Otherwise nothing happens. This method will get called automatically for you by the framework.
See also:
ObjectWithCallbacks

void VCF::CallBack::free ( )

Deletes the instance of the callback.
You must use this method to delete a callback, i.e.
CallBack* cb = //some callback... //delete the callback //(a) Right way: cb->free(); //(b) wrong way delete cb
Note that not only is the second technique (b) not allowed but you will get a compile error as the destructor is marked as protected.

String VCF::CallBack::getName ( ) const [inline]

The name of the callback.
It can be anything you want, although the convention is the fully qualified C++ function name (like "SomeClass::someFunction" ). The name is optional and it may be an empty string.

virtual Object* VCF::CallBack::getSource ( ) [inline, virtual]

A callback may, or may not, have a source.
In addition, it's possible that the source is *not* an Object based type. For this reason this function is made virtual so that derived classes can properly implement it and return a valid source point if possible.
Returns:
Object the object that "owns" the callback and will delete it when the object is deleted. This means that the callback;s lifetime is that of it's owning object unless it's explicitly removed from the object and deleted.

Reimplemented in VCF::ClassProcedure1< P1, ClassType >, VCF::ClassProcedure< ClassType >, VCF::ClassProcedure2< P1, P2, ClassType >, VCF::ClassProcedure3< P1, P2, P3, ClassType >, VCF::ClassProcedure4< P1, P2, P3, P4, ClassType >, VCF::ClassProcedure5< P1, P2, P3, P4, P5, ClassType >, VCF::ClassProcedure6< P1, P2, P3, P4, P5, P6, ClassType >, VCF::ClassProcedure7< P1, P2, P3, P4, P5, P6, P7, ClassType >, and VCF::ClassProcedure8< P1, P2, P3, P4, P5, P6, P7, P8, ClassType >.

void VCF::CallBack::removeDelegate ( Delegate * val ) [inline, protected]

Friends And Related Function Documentation

friend class Delegate [friend]

friend class ObjectWithCallbacks [friend]

Member Data Documentation

DelegatesArray* VCF::CallBack::delegates_ [protected]

String VCF::CallBack::name [protected]

The documentation for this class was generated from the following file:

vcf/FoundationKit/Delegates.h

VCF::CallBack Class Reference

Public Types

Public Member Functions

Protected Types

Protected Member Functions