Subject Class Reference

Base class for objects to send notification when their data changes. More...

#include <Subject.h>

Inheritance diagram for Subject:

List of all members.

Public Member Functions
virtual bool	attach (const std::string &signal, const Slot &slot)=0
virtual bool	detach (const std::string &signal, const Slot &slot)=0
virtual bool	signalsEnabled () const =0
Static Public Member Functions
static const std::string &	signalDeleted ()
static const std::string &	signalModified ()
Protected Member Functions
virtual	~Subject ()

---

Detailed Description

Base class for objects to send notification when their data changes.

Generalized interface for objects that can notify observers when changes have been made. It provides a uniform means for letting other objects register an interest in the contents of this object's contents.

Each Subject has signals that it will emit under certain circumstances. When a signal is emitted, all slots attached to that signal on the Subject will be called. For example:

  pSubject->attach(SIGNAL_NAME(Subject, Modified), Slot(pObj, &Obj::mySlot));

This will cause pObj->mySlot(*pSubject, "Subject::Modified", v) to be called whenever pSubject emits SIGNAL_NAME(Subject, Modified).

Whenever a signal other than Subject::Modified or Subject::Deleted is emitted, Subject::Modified will also be emitted. This means that all slots attached to Subject::signalModified on a Subject of type MyClass will be called when that MyClass object emits SIGNAL_NAME(MyClass, MySignal).

Signals for a particular instance of a Subject can be supressed by using either the SignalBlocker or SignalEnabler classes.

The notification of slots is done in two passes. First, all slots attached to the specific signal are notified in FIFO order (First In == first attached, and First Out == first notified). Then, assuming the specific signal is not Subject::Deleted or Subject::Modified, all slots attached to Subject::Modified are notified in FIFO order.

See also:

TypeAwareObject, Slot, SafeSlot, AutoSlot, Signal, SignalBlocker, SignalEnabler

Definition at line 96 of file Subject.h.

---

Constructor & Destructor Documentation

virtual Subject::~Subject

(

)

[protected, virtual]

This should not be deleted directly.

It should be deleted according to the instructions provided for the relevant subclass.

Definition at line 175 of file Subject.h.

---

Member Function Documentation

static const std::string& Subject::signalDeleted

(

)

[static]

Emitted when a Subject is deleted.

This will always be emitted, it CANNOT be blocked using SignalBlocker or SignalEnabler.

Definition at line 103 of file Subject.h.

static const std::string& Subject::signalModified

(

)

[static]

Emitted when a Subject is modified.

Anytime a signal other than deleted or modified is notified, signalModified will be notified as well.

Definition at line 108 of file Subject.h.

virtual bool Subject::attach	(	const std::string &	signal,
		const Slot &	slot
	)			[pure virtual]

Allow another object to register an interest in specific changes on this Subject.

Parameters:

	signal	The name of the signal to attach to. If signal is empty, the Slot will be called on all signals from this Subject.
	slot	An object that contains the object and method to call when the specified signal is notified. This can be a Slot, SafeSlot or AutoSlot.

Returns:

true if the Slot was valid and was not already attached to the signal on the subject and false otherwise.

Subject Notifications:

This method will call Observer::attached on the object in the slot, if the object inherits Observer.

virtual bool Subject::detach	(	const std::string &	signal,
		const Slot &	slot
	)			[pure virtual]

Allow a Slot to be deregistered from a signal on this Subject.

Parameters:

	signal	The name of the signal the Slot is attached to. If signal is empty, the specified Slot will be detached from all signals on this Subject.
	slot	The Slot to detach from the specified signal. If the Slot is empty, all slots will be detached from the specified signal. If the slot was originally attached as a SafeSlot or AutoSlot, it needs to be detached as same type.

Returns:

true if the Slot was attached to the specified signal on the subject.

Subject Notifications:

This method will call Observer::detached on the object in the slot, if the object inherits Observer.

virtual bool Subject::signalsEnabled

(

)

const [pure virtual]

Indicates whether the Subject's notification mechanism is enabled or not.

If signals are disabled, then only SIGNAL_NAME(Subject, Deleted) will be emitted when requested, all other signals will be suppressed.

To disable signals, either the SignalBlocker or SignalEnabler classes must be used.

Warning:

Disabling signals can be very dangerous as it hides details from any attached slots which may depend on being notified to function properly.

See also:

SignalBlocker, SignalEnabler

Returns:

true if the Subject's notification is enabled, or false otherwise.