tlp::Observable Class Reference

Observable is the base class for the implementation of observable Object by Listener or Observer objects. More...

#include <Observable.h>

Inheritance diagram for tlp::Observable:

Collaboration diagram for tlp::Observable:

List of all members.

Public Member Functions

• void addObserver (Observable *const obs) const
• void addListener (Observable *const obs) const
• void removeObserver (Observable *const obs) const
• void removeListener (Observable *const obs) const
• unsigned int getSent () const

  return the number of sent nofication
  

• unsigned int getReceived () const

  return the number of received nofication
  

• unsigned int countListeners () const

  return the number of Listeners of that Object
  

• unsigned int countObservers () const

  return the number of Observers of that Object
  

Static Public Member Functions

• static void holdObservers ()

  start delay of events to all Observer
  

• static void unholdObservers ()

  Send queued event to all Observer.
  

• static void _DEPRECATED unholdObservers (bool)
• static unsigned int observersHoldCounter ()
• static Observable * getObject (tlp::node n)
• static bool isAlive (tlp::node n)

  Enables to test if the object represented by a node has been deleted. Outside a unhold/hold block or an update that function always return true.
  

• static const tlp::VectorGraph & getObservableGraph ()

  Return a reference on the Observable/Listener/Observer graph.
  

Protected Member Functions

• Observable ()
• Observable (const Observable &)
• virtual ~Observable ()
• Observable & operator= (const Observable &)
• void sendEvent (const Event &)

  Enable to send an event to all Observer/Listener.
  

• virtual void treatEvents (const std::vector< Event > &events)
• virtual void treatEvent (const Event &)
• void observableDeleted ()

  Enable to send Event::DELETE before the deletion of subclass internal objects.
  

• bool hasOnlookers () const

  Enable to know if there is at least one Observer/Listener connected.
  

• tlp::Iterator< Observable * > * getObservables () const

  use for old observer tulip compatibility
  

• virtual void _DEPRECATED update (std::set< Observable * >::iterator, std::set< Observable * >::iterator)

  use for old observer tulip compatibility
  

• virtual void _DEPRECATED observableDestroyed (Observable *)

  use for old observer tulip compatibility
  

• void _DEPRECATED notifyObservers ()

  use for old observer tulip compatibility
  

Friends

• class Event

---

Detailed Description

Observable is the base class for the implementation of observable Object by Listener or Observer objects.

Observable the base class of all objects that need to be Observed or listened. To notify its Onlooker an Observable have to call the notify function whenever it wants. The event will be send directly to all Listener and Observer (if not holded) The Event send by the Observable is a const reference, thus the observer is responsible of the creation and destruction of Event. Usually the Event is created on the stack in the block of code that call the notify function, thus there is no need to take care of it.

Observable provides a mechanism (hold/unhold) to delay the sending of events to Observer, the mechanism is global. Calling the hold function will stop the transmission of Event::MODIFICATION to all the Observer, there is no way to delay the sending of events only for one Observable. Nested call to hold/unhold are permitted.

The Event::DELETE event cannot be created by user, it is automatically send to all Observer/Listener at the destruction of an Observable. However, using the ObservableDeleted function it is possible to send the Event from the destructor of a specific Observable implementation. The update function of observer/Listener can the be called before the destruction of your internal objects. It enables the Observer/Listener, to to access to the internal data of your Observable before it disappear.

See also:

Listener

Observer

Event

---

Constructor & Destructor Documentation

tlp::Observable::Observable

(

)

[protected]

tlp::Observable::Observable

(

const Observable &

)

[protected]

virtual tlp::Observable::~Observable

(

)

[protected, virtual]

---

Member Function Documentation

void tlp::Observable::addListener

(

Observable *const

obs

)

const

void tlp::Observable::addObserver

(

Observable *const

obs

)

const

unsigned int tlp::Observable::countListeners

(

)

const

return the number of Listeners of that Object

unsigned int tlp::Observable::countObservers

(

)

const

return the number of Observers of that Object

static Observable* tlp::Observable::getObject

(

tlp::node

n

)

[static]

return a pointer on the object represented by that node

Warning:

If you call that function during an update, it is possible that the pointer do not point on an existing object, use the isAlive function before to test if your object still valid

static const tlp::VectorGraph& tlp::Observable::getObservableGraph

(

)

[static]

Return a reference on the Observable/Listener/Observer graph.

tlp::Iterator<Observable *>* tlp::Observable::getObservables

(

)

const [protected]

use for old observer tulip compatibility

unsigned int tlp::Observable::getReceived

(

)

const

return the number of received nofication

unsigned int tlp::Observable::getSent

(

)

const

return the number of sent nofication

bool tlp::Observable::hasOnlookers

(

)

const [protected]

Enable to know if there is at least one Observer/Listener connected.

it enables to prevent creation and sending of Event for nothing. Usually a notify code block in an Observable should look like that:

    if (hasOnlookers()) {
       notify(MyEvent(*this, param1, param2, ...));
    }
  ° 

static void tlp::Observable::holdObservers

(

)

[static]

start delay of events to all Observer

After a call to holdObservers, no more events are sent to Observer(execpt DELETE events), events are still transmit to listeners. It is possible to call several time the holdObservers function, in that case the observers are holded until all holdObservers calls are closed by unholdOBservers calls.

See also:

unholdObservers

Observer

static bool tlp::Observable::isAlive

(

tlp::node

n

)

[static]

Enables to test if the object represented by a node has been deleted. Outside a unhold/hold block or an update that function always return true.

void _DEPRECATED tlp::Observable::notifyObservers

(

)

[protected]

use for old observer tulip compatibility

void tlp::Observable::observableDeleted

(

)

[protected]

Enable to send Event::DELETE before the deletion of subclass internal objects.

The Observable mecahnism automatically send DELETE event to Listener/Observer when an Obseravble is deleted. However when that Event is send the subclass of Observable are already deleted, thus it is no more possible to access to their members. In case you want to allow to access to your Observable member variables/functions when Listner/Observer receive a DELETE events, you should call that function in your destructor.

Warning:

That function must be called only one time in the destructor of your object, in case of several inheritance be carefull not to call it in all the destructors implied in in the inheritance tree.

virtual void _DEPRECATED tlp::Observable::observableDestroyed

(

Observable *

)

[protected, virtual]

use for old observer tulip compatibility

static unsigned int tlp::Observable::observersHoldCounter

(

)

[inline, static]

Observable& tlp::Observable::operator=

(

const Observable &

)

[protected]

void tlp::Observable::removeListener

(

Observable *const

obs

)

const

void tlp::Observable::removeObserver

(

Observable *const

obs

)

const

void tlp::Observable::sendEvent

(

const Event &

)

[protected]

Enable to send an event to all Observer/Listener.

According to the type of the event that function has got different behaviour. event::DELETE : are sent directly to all Observers/Listeners, it is not possible to delay their processing.
event::MODIFICATION : sent to all Observer/Listener, it is possible to delay their processing (only for Observer)
event::INFORMATION : sent only to Listener, it is not possible to delay their processing.
event::INVALID : never sent use internally.

Note:

In any cases, Event are first sent to Listener and then to Observer

To prevent building of too many objects(Event) a notify code block in an Observable should look like that:

    if (hasOnlookers()) {
       notify(MyEvent(*this, param1, param2, ...));
    }
  ° 

virtual void tlp::Observable::treatEvent

(

const Event &

)

[protected, virtual]

virtual void tlp::Observable::treatEvents

(

const std::vector< Event > &

events

)

[protected, virtual]

that function should be virtual pure the current implementation is only here to insure compatibility with tulip 3.x x<6.

static void _DEPRECATED tlp::Observable::unholdObservers

(

bool

)

[inline, static]

static void tlp::Observable::unholdObservers

(

)

[static]

Send queued event to all Observer.

If the stack of Observable lock is empty (ie. number of calls to unhold equal to the number of calls to hold), send all queued events to observers.

Warning:

Calling that function when the hold stack is empty raises an ObservableException.

See also:

holdObservers

Observer

virtual void _DEPRECATED tlp::Observable::update	(	std::set< Observable * >::iterator	,
		std::set< Observable * >::iterator
	)		[protected, virtual]

use for old observer tulip compatibility

---

Friends And Related Function Documentation

friend class Event [friend]