OMK::EventListenerCallBack< CallerClass > Class Template Reference

Untyped event listener calling an object's method to handle the event. More...

#include <OMKEventListenerCallBack.h>

Inheritance diagram for OMK::EventListenerCallBack< CallerClass >:

[legend]Collaboration diagram for OMK::EventListenerCallBack< CallerClass >:

[legend]List of all members.

Public Types
typedef bool(CallerClass::*)	CallBackFct (Event *event)
	Define type of the callback method.
Protected Member Functions
Inherited from EventListener
virtual bool	processEvent (Event *event)
	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 callback method.
CallBackFct	_callBackFct
	Pointer to the callback method of the associated simulated object.
EventIdentifier	_eventId
	Identifier of the listened event.

---

Detailed Description

template<class CallerClass>
class OMK::EventListenerCallBack< CallerClass >

Untyped event listener calling an 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 valued events use OMKValuedEventListenerCallBack.

This listener is a template class, the parameter is:

• CallerClass, it is the class of the callback method and event listener owner it must be a son of SimulatedObject.

How to handle an event

The header of the simulated object declares:

• a pointer to the event listener
• the callback method

class MySimulatedObject : public SimulatedObject
{
  //...
protected:
  // The event listener
  EventListenerCallBack<MySimulatedObject>* _p_eventListener ;
  // The callback method which will be called
  bool myCallBackMethod( Event* e ) ;
  //...
};

The callback method returns a boolean. See CallBackFct.

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

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

The callback is a member method of the simulated object:

bool MySimulatedObject::myCallBackMethod( Event* e ) 
{
  //...To do
}

The callback 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 fireSignal or fireValuedSignal methods.
If the sender uses sendEvent or sendValuedEvent the listener receives automatically the event and calls the callback method.

Definition at line 92 of file OMKEventListenerCallBack.h.

---

Member Typedef Documentation

template<class CallerClass>

typedef bool(CallerClass::*) OMK::EventListenerCallBack< CallerClass >::CallBackFct(Event *event)

Define type of the callback method.

The callback is a member method of the simulated object which is the owner of the listener. The prototype of the callback method is:

 bool myCallBackMethod( Event* e ) ;

Parameters:

[in]

\b

event the 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 callback method is true, so the processEvent method of the simulated object is never called, everything is done in the callback 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 118 of file OMKEventListenerCallBack.h.

---

Constructor & Destructor Documentation

template<class CallerClass>

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

Constructor.

Parameters:

[in]	owner	the simulated object owner of the listener and of the callback (ex:*this).
[in]	callBackFct	the callback 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 callback method pointer.
Automatically register the event identifier.
The constructor must be called in the init method of the owner.

Definition at line 131 of file OMKEventListenerCallBack.h.

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

  : EventListener( owner ), _callerInstance( &owner ), _callBackFct( callBackFct ), _eventId( eventId )
  {
    // The owner instance and the callback method must be set
    OMASSERTM( _callerInstance && _callBackFct, "The owner instance and the callback method must be set" ); 
    _owner.addEventListener( *this ) ;     
  }

template<class CallerClass>

OMK::EventListenerCallBack< CallerClass >::EventListenerCallBack	(	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 for the callback.
[in]	callBackFct	the callback 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 callback method pointer.
Automatically register the event identifier.
The constructor must be called in the init method of the owner.

Definition at line 152 of file OMKEventListenerCallBack.h.

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

  : EventListener( owner ), _callerInstance( callerInstance ), _callBackFct( callBackFct ), _eventId( eventId )
  { 
    // The owner instance and the callback method must be set
    OMASSERTM( _callerInstance && _callBackFct, "The owner instance and the callback method must be set" ); 
    _owner.addEventListener( *this ) ;     
  }

template<class CallerClass>

virtual OMK::EventListenerCallBack< CallerClass >::~EventListenerCallBack

(

)

[inline, virtual]

Destructor.

Definition at line 162 of file OMKEventListenerCallBack.h.

{}

template<class CallerClass>

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

Constructor.

Parameters:

[in]	owner	the simulated object owner of the listener and of the callback (ex:*this).
[in]	callBackFct	the callback 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 callback method pointer.
Automatically register the event identifier.
The constructor must be called in the init method of the owner.

Definition at line 131 of file OMKEventListenerCallBack.h.

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

  : EventListener( owner ), _callerInstance( &owner ), _callBackFct( callBackFct ), _eventId( eventId )
  {
    // The owner instance and the callback method must be set
    OMASSERTM( _callerInstance && _callBackFct, "The owner instance and the callback method must be set" ); 
    _owner.addEventListener( *this ) ;     
  }

template<class CallerClass>

OMK::EventListenerCallBack< CallerClass >::EventListenerCallBack	(	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 for the callback.
[in]	callBackFct	the callback 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 callback method pointer.
Automatically register the event identifier.
The constructor must be called in the init method of the owner.

Definition at line 152 of file OMKEventListenerCallBack.h.

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

  : EventListener( owner ), _callerInstance( callerInstance ), _callBackFct( callBackFct ), _eventId( eventId )
  { 
    // The owner instance and the callback method must be set
    OMASSERTM( _callerInstance && _callBackFct, "The owner instance and the callback method must be set" ); 
    _owner.addEventListener( *this ) ;     
  }

template<class CallerClass>

virtual OMK::EventListenerCallBack< CallerClass >::~EventListenerCallBack

(

)

[inline, virtual]

Destructor.

Definition at line 162 of file OMKEventListenerCallBack.h.

{}

---

Member Function Documentation

template<class CallerClass>

virtual bool OMK::EventListenerCallBack< CallerClass >::processEvent

(

Event *

event

)

[inline, protected, virtual]

Process an event.

Call the associated callback

Returns:

The callback return see CallBackFct.

Implements OMK::EventListener.

Definition at line 172 of file OMKEventListenerCallBack.h.

References OMK::EventListenerCallBack< CallerClass >::_callBackFct, and OMK::EventListenerCallBack< CallerClass >::_callerInstance.

  {
    return (_callerInstance->*_callBackFct)( event ) ;
  }

template<class CallerClass>

virtual void OMK::EventListenerCallBack< CallerClass >::registerEvents

(

)

[inline, protected, virtual]

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

Reimplemented from OMK::EventListener.

Definition at line 177 of file OMKEventListenerCallBack.h.

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

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

---

Member Data Documentation

template<class CallerClass>

CallerClass* OMK::EventListenerCallBack< CallerClass >::_callerInstance [protected]

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

Definition at line 188 of file OMKEventListenerCallBack.h.

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

template<class CallerClass>

CallBackFct OMK::EventListenerCallBack< CallerClass >::_callBackFct [protected]

Pointer to the callback method of the associated simulated object.

Definition at line 190 of file OMKEventListenerCallBack.h.

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

template<class CallerClass>

EventIdentifier OMK::EventListenerCallBack< CallerClass >::_eventId [protected]

Identifier of the listened event.

Definition at line 192 of file OMKEventListenerCallBack.h.

Referenced by OMK::EventListenerCallBack< CallerClass >::registerEvents().

---