VCF::EventHandlerInstance< SOURCE, EVENT > Class Template Reference

The EventHandlerInstance class is used to provide a typesafe wrapper around a specific class's member function pointer. More...

#include <vcf/FoundationKit/EventHandler.h>

Inheritance diagram for VCF::EventHandlerInstance< SOURCE, EVENT >:

List of all members.


Public Types
typedef void(SOURCE::*	OnEventHandlerMethod )(EVENT *e)
Public Member Functions
	EventHandlerInstance (SOURCE *source, OnEventHandlerMethod handlerMethod, const String &handlerName="")
virtual	~EventHandlerInstance ()
virtual void	invoke (Event *e)
	Called during the events dispatch cycle.
virtual Object *	getSource ()
	Returns the source that the event handler is attached to.
Protected Attributes
SOURCE *	source_
OnEventHandlerMethod	handlerMethod_

Detailed Description

template<class SOURCE, class EVENT>
class VCF::EventHandlerInstance< SOURCE, EVENT >

The EventHandlerInstance class is used to provide a typesafe wrapper around a specific class's member function pointer.

In addition, when the instance is created, if the source passed in is derived from VCF::ObjectWithEvents, then the handler will be maintained in a list by the source, and destroyed when the source is destroyed, freeing the creator of the handler from worrying about memory leaks.

The SOURCE template parameter specified the source class that the event handler method is a member of. The EVENT template parameter is the event class type. The event class type must derive (directly or indirectly) from VCF::Event, and it must be the same event type that is specified in the event handler signature. The basic event handler signature is:

void someMethod( EVENT* event );

For example

class Foo : public Object {
public:
  void onSomeEvent( Event* e );
};

int main()
{
  Foo f;
  EventHandler* ev = new EventHandlerInstance<Foo,Event>(&f,&Foo::onSomeEvent);
  return 0;
}

In the case above we simply created a new event handler instance that wrap's the Foo::onSomeEvent() method. If we wanted to specify a different type:

class Foo : public Object {
public:
  void onSomeEvent( MouseEvent* e );
};

int main()
{
  Foo f;
  EventHandler* ev = new EventHandlerInstance<Foo,MouseEvent>(&f,&Foo::onSomeEvent);
  return 0;
}

We can do so by changing the method signature of onSomeEvent() from taking a VCF::Event isntance to VCF::MouseEvent instance. The code above will have a memory leak, since we are allocating a new EventHandler isntance but not deleting it. If we would like to have the event handlers managed for us, then one solution is use the ObjectWithEvents class, for example:

class Foo : public ObjectWithEvents {
public:
  void onSomeEvent( MouseEvent* e );
};

int main()
{
  Foo f;
  EventHandler* ev = new EventHandlerInstance<Foo,MouseEvent>(&f,&Foo::onSomeEvent, "Foo::onSomeEvent");
  return 0;
}

Now when the EventHandlerInstance instance is create it will be added to the Foo "source" instance and assigned a name of "Foo::onSomeEvent" (the name can be whatever you want, but be aware that if you come up with duplicate names you'll see memory leaks). This event can then be retrieved at a later time via:

EventHandler* ev = f.getEventHandler( "Foo::onSomeEvent" );

When the Foo instance is destroyed it will automatically destroy all of it's event handlers in it's list.

See also:: Event
ObjectWithEvents

Member Typedef Documentation

template<class SOURCE, class EVENT>

typedef void(SOURCE::* VCF::EventHandlerInstance< SOURCE, EVENT >::OnEventHandlerMethod)(EVENT *e)

Constructor & Destructor Documentation

template<class SOURCE, class EVENT>

VCF::EventHandlerInstance< SOURCE, EVENT >::EventHandlerInstance ( SOURCE * source,

OnEventHandlerMethod handlerMethod,

const String & handlerName = ""

) [inline]

Parameters:

SOURCE the source instance. This is the instance that the event handler method will be invoked on.

OnEventHandlerMethod the mehthod pointer that this event handler will call when the invoke() method is triggered.

String the name of the event handler. This is optional. If no name is specified (the default), then the event handler will not be added to the source instance. If the a name is specified and the source instance derives from ObjectWithEvents, then the event handler instance will be added to the source with the name passed in destroyed when the source is destroyed. Note that any text may be used for the name, but if an event handler already exists on the source with that same name, then a memory leak will occur. If instead the same handler will be added twice with two different names we may have a memory access exception, as the framework will try to delete twice the same object.

template<class SOURCE, class EVENT>

virtual VCF::EventHandlerInstance< SOURCE, EVENT >::~EventHandlerInstance ( ) [inline, virtual]

Member Function Documentation

template<class SOURCE, class EVENT>

virtual Object* VCF::EventHandlerInstance< SOURCE, EVENT >::getSource ( ) [inline, virtual]

Returns the source that the event handler is attached to.
Some event handler implementations may not return a source for public use, or may not use one at all, so this method may return NULL. An example of not using a source would be the StaticEventHandlerInstance which is used to wrap static functions. The default implementation returns a NULL object source.
Reimplemented from VCF::EventHandler.

template<class SOURCE, class EVENT>

virtual void VCF::EventHandlerInstance< SOURCE, EVENT >::invoke ( Event * e ) [inline, virtual]

Called during the events dispatch cycle.
The implementation will end up calling the appropriate call back method.
Implements VCF::EventHandler.

Member Data Documentation

template<class SOURCE, class EVENT>

OnEventHandlerMethod VCF::EventHandlerInstance< SOURCE, EVENT >::handlerMethod_ [protected]

template<class SOURCE, class EVENT>

SOURCE* VCF::EventHandlerInstance< SOURCE, EVENT >::source_ [protected]

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

vcf/FoundationKit/EventHandler.h

VCF::EventHandlerInstance< SOURCE, EVENT > Class Template Reference

Public Types

Public Member Functions