OMK::ValuedEventListenerCallBack< CallerClass, PrmType > Class Template Reference

Valued event listener which calling a object's method to handle the event. More...

#include <OMKValuedEventListenerCallBack.h>

Inheritance diagram for OMK::ValuedEventListenerCallBack< CallerClass, PrmType >:

[legend]Collaboration diagram for OMK::ValuedEventListenerCallBack< CallerClass, PrmType >:


Public Types
typedef bool(CallerClass::*)	CallBackFct (ValuedEvent< PrmType > *event)
	Define type of the call back method.
Protected Member Functions
Inherited from EventListener
virtual bool	processEvent (Event *e)
	Process an event.
virtual void	registerEvents ()
	Member function used to register the event the eventListener has to react to.
Protected Attributes
Attributs
CallerClass *	_callerInstance
	Pointer to the associated simulated object, owner of the listener and the call back method.
CallBackFct	_callBackFct
	Pointer to the call back method of the associated simulated object.
EventIdentifier	_eventId
	Identifier of the listened event.

Detailed Description

template<class CallerClass, class PrmType>
class OMK::ValuedEventListenerCallBack< CallerClass, PrmType >

Valued event listener which calling a object's method to handle the event.

Author:: Benoît Chanclou

Date:: 2006/06/15

The aim of this class is to provide a simple handling of events. To process the event the simulated object wants to listen, it declares a listener and adds a method to process the event. See the code below for code sample.
If you want to handle unvalued events use EventListenerCallBack.

This listener is a template class, the parameters are:

CallerClass, it is the class of the call back method owner,
PrmType, it is the type of the value associated to the listened event and it must be a son of OMK::Type::Base or use OMK::TypeSimpleTypeT.

How to handle an event

The header of the simulated object declares:

a pointer to the event listener
the call back method

class MySimulatedObject : public SimulatedObject
{
  //...
protected:
  // The event listener
  ValuedEventListenerCallBack<MySimulatedObject, MyType>* _p_eventListener ;
  // The call back method which will be called
  bool myCallBackMethod( ValuedEvent<MyType>* e ) ;
  //...
};

The call back method returns a boolean see CallBackFct.

The listener is created in the init method of the simulated object. Because it is automatically registered it cannot be created in the constructor of the simulated object.

void MySimulatedObject::init() 
{
  //...
  _p_eventListener = new ValuedEventListenerCallBack<MySimulatedObject, MyType>( *this, myCallBackMethod, TheEventEmitter::s_eventId ) ;
  //...
}

The call back is a member method of the simulated object:

void MySimulatedObject::myCallBackMethod( ValuedEvent<MyType>* e ) 
{
  // To get the associated value
  MyType theValue = e->value ;
  //...To do
}

The call back method returns a boolean see CallBackFct.
It can be virtual and redefined in sons of the simulated object.

The registration and the cancel are handled by the simulated object. So, to receive or stop a signal the object must use registerForSignal (or registerForSignalBy for a specific sender) or cancelRegistrationForSignal (respectively cancelRegistrationForSignalBy).
The sender will use fireValuedSignal methods.
If the sender uses sendValuedEvent the listener receives automatically the event and calls the call back method.

See DECLARE_PRM_TYPE_EVENT_LISTENER.

Definition at line 100 of file OMKValuedEventListenerCallBack.h.

Member Typedef Documentation

template<class CallerClass, class PrmType>

typedef bool(CallerClass::*) OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::CallBackFct(ValuedEvent< PrmType > *event)

Define type of the call back method.

The call back is a member method of the simulated object, which is the owner of the listener. The prototype of the call back method is:

 void myCallBackMethod( ValuedEvent<PrmType>* e ) ;

Parameters:

[in] \b event the valued event to processed.

Returns:: a boolean which tells how to process: true : the kernel will stop to process the event with the others eventlistener and with the object, and it will destroy the event. false : the kernel will continue the process

Most of the time, there is only one listener for each event, and the return of the call back method is true, so the processEvent method of the simulated object is never called, everything is done in the call back method.

If you want to prevent the event from being seen by the other event listeners but want it seen by the object, call owner.processEvent and return true. Warning, if owner.processEvent returns false, you will have a problem because the event will be destroyed while the owner thinks it can still use it safely.

Definition at line 126 of file OMKValuedEventListenerCallBack.h.

Constructor & Destructor Documentation

template<class CallerClass, class PrmType>

OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::ValuedEventListenerCallBack	(	CallerClass &	owner,
		CallBackFct	callBackFct,
		const EventIdentifier &	eventId
	)			`[inline]`

Constructor.

Parameters:

`[in]`	owner	the simulated object owner of the listener (ex:`*this`).
`[in]`	callBackFct	the call back method.
`[in]`	eventId	identifier of the event to listen.

Use this constructor for a caller which is a simulated object.

Call the ancestor and store the call back method pointer.
Automatically register the event identifier.
The constructor must be called in the init method of the owner.

Definition at line 139 of file OMKValuedEventListenerCallBack.h.

References OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::_callBackFct, OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::_callerInstance, OMK::EventListener::_owner, OMK::SimulatedObject::addEventListener(), and OMASSERTM.

00142   : EventListener( owner ), _callerInstance( &owner ), _callBackFct( callBackFct ), _eventId( eventId )
00143   { 
00144     // The owner instance and the call back method must be set
00145     OMASSERTM( _callerInstance && _callBackFct, "Needs a valid instance and call back method of this instance" ); 
00146     _owner.addEventListener( *this ) ;     
00147   }

template<class CallerClass, class PrmType>

OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::ValuedEventListenerCallBack	(	SimulatedObject &	owner,
		CallerClass *	callerInstance,
		CallBackFct	callBackFct,
		const EventIdentifier &	eventId
	)			`[inline]`

Constructor.

Parameters:

`[in]`	owner	the simulated object owner of the listener (ex:`*this`).
`[in]`	callerInstance	the object which be called (ex:`*this`).
`[in]`	callBackFct	the call back method.
`[in]`	eventId	identifier of the event to listen.

Use this constructor for a caller which is not a simulated object but an object associated to a simulated object like an extension.

Call the ancestor and store the call back method pointer.
Automatically register the event identifier.
The constructor must be called in the init method of the owner.

Definition at line 160 of file OMKValuedEventListenerCallBack.h.

00163   : EventListener( owner ), _callerInstance( callerInstance ), _callBackFct( callBackFct ), _eventId( eventId )
00164   { 
00165     // The owner instance and the call back method must be set
00166     OMASSERTM( _callerInstance && _callBackFct, "Needs a valid instance and call back method of this instance" ); 
00167     _owner.addEventListener( *this ) ;     
00168   }

template<class CallerClass, class PrmType>

virtual OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::~ValuedEventListenerCallBack ( ) [inline, virtual]

Destructor.

Definition at line 170 of file OMKValuedEventListenerCallBack.h.

00170 {}

template<class CallerClass, class PrmType>

OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::ValuedEventListenerCallBack	(	CallerClass &	owner,
		CallBackFct	callBackFct,
		const EventIdentifier &	eventId
	)			`[inline]`

Constructor.

Parameters:

`[in]`	owner	the simulated object owner of the listener (ex:`*this`).
`[in]`	callBackFct	the call back method.
`[in]`	eventId	identifier of the event to listen.

Use this constructor for a caller which is a simulated object.

Call the ancestor and store the call back method pointer.
Automatically register the event identifier.
The constructor must be called in the init method of the owner.

Definition at line 139 of file OMKValuedEventListenerCallBack.h.

00142   : EventListener( owner ), _callerInstance( &owner ), _callBackFct( callBackFct ), _eventId( eventId )
00143   { 
00144     // The owner instance and the call back method must be set
00145     OMASSERTM( _callerInstance && _callBackFct, "Needs a valid instance and call back method of this instance" ); 
00146     _owner.addEventListener( *this ) ;     
00147   }

template<class CallerClass, class PrmType>

OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::ValuedEventListenerCallBack	(	SimulatedObject &	owner,
		CallerClass *	callerInstance,
		CallBackFct	callBackFct,
		const EventIdentifier &	eventId
	)			`[inline]`

Constructor.

Parameters:

`[in]`	owner	the simulated object owner of the listener (ex:`*this`).
`[in]`	callerInstance	the object which be called (ex:`*this`).
`[in]`	callBackFct	the call back method.
`[in]`	eventId	identifier of the event to listen.

Use this constructor for a caller which is not a simulated object but an object associated to a simulated object like an extension.

Call the ancestor and store the call back method pointer.
Automatically register the event identifier.
The constructor must be called in the init method of the owner.

Definition at line 160 of file OMKValuedEventListenerCallBack.h.

00163   : EventListener( owner ), _callerInstance( callerInstance ), _callBackFct( callBackFct ), _eventId( eventId )
00164   { 
00165     // The owner instance and the call back method must be set
00166     OMASSERTM( _callerInstance && _callBackFct, "Needs a valid instance and call back method of this instance" ); 
00167     _owner.addEventListener( *this ) ;     
00168   }

template<class CallerClass, class PrmType>

virtual OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::~ValuedEventListenerCallBack ( ) [inline, virtual]

Destructor.

Definition at line 170 of file OMKValuedEventListenerCallBack.h.

00170 {}

Member Function Documentation

template<class CallerClass, class PrmType>

virtual bool OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::processEvent ( Event * e ) [inline, protected, virtual]

Process an event.

Call the associated call back

Returns:: The call back return see CallBackFct.

Implements OMK::EventListener.

Definition at line 180 of file OMKValuedEventListenerCallBack.h.

References OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::_callBackFct, OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::_callerInstance, OMK::EventListener::_owner, OMK::debugMsg(), OMK::Event::eventId, OMK::Name::getCString(), OMERROR, and OMK::Event::sender.

00181   {
00182     ValuedEvent< PrmType > *valuedEvent = dynamic_cast< ValuedEvent< PrmType >* >( e ) ;
00183     if( valuedEvent )
00184     { // Ok => call the call back method
00185       return (_callerInstance->*_callBackFct)( valuedEvent ) ;
00186     }
00187     else
00188     { // Unable to cast => error message
00189       OMERROR( ":-( Error to processEvent() of " << debugMsg( &_owner ) << " with the event \"" 
00190                 << ( e ? e->eventId.getCString() : "unknow" ) << "\" send by \"" 
00191                 << ( e ? e->sender.getCString() : "unknow" ) << "\"" << std::endl
00192                 << ">>> Unable to cast the event (waits " << typeid( valuedEvent ).name() << " get " << typeid( e ).name() ) ;
00193       return false ; // Unable to process the event => don't stop the process, maybe something else could process it.
00194     }
00195   }

template<class CallerClass, class PrmType>

virtual void OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::registerEvents ( ) [inline, protected, virtual]

Member function used to register the event the eventListener has to react to.

Reimplemented from OMK::EventListener.

Definition at line 197 of file OMKValuedEventListenerCallBack.h.

References OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::_eventId, OMK::EventListener::_owner, and OMK::SimulatedObject::registerEventListenerForEvent().

00198   {
00199     _owner.registerEventListenerForEvent( *this, _eventId ) ;
00200   }

Member Data Documentation

template<class CallerClass, class PrmType>

CallerClass* OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::_callerInstance [protected]

Pointer to the associated simulated object, owner of the listener and the call back method.

Definition at line 208 of file OMKValuedEventListenerCallBack.h.

Referenced by OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::processEvent(), and OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::ValuedEventListenerCallBack().

template<class CallerClass, class PrmType>

CallBackFct OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::_callBackFct [protected]

Pointer to the call back method of the associated simulated object.

Definition at line 210 of file OMKValuedEventListenerCallBack.h.

Referenced by OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::processEvent(), and OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::ValuedEventListenerCallBack().

template<class CallerClass, class PrmType>

EventIdentifier OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::_eventId [protected]

Identifier of the listened event.

Definition at line 212 of file OMKValuedEventListenerCallBack.h.

Referenced by OMK::ValuedEventListenerCallBack< CallerClass, PrmType >::registerEvents().

Documentation generated on Mon Jun 9 11:46:01 2008
Generated with doxygen by Dimitri van Heesch , 1997-2007

OMK::ValuedEventListenerCallBack< CallerClass, PrmType > Class Template Reference

Public Types

Protected Member Functions

Protected Attributes

Detailed Description

template<class CallerClass, class PrmType> class OMK::ValuedEventListenerCallBack< CallerClass, PrmType >

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<class CallerClass, class PrmType>
class OMK::ValuedEventListenerCallBack< CallerClass, PrmType >