BALL::VIEW::ConnectionObject Class Reference
[Widget connectivity and message queuing]

#include <BALL/VIEW/KERNEL/connectionObject.h>

Inheritance diagram for BALL::VIEW::ConnectionObject:


Public Member Functions
Constructors
	ConnectionObject ()
Destructors
virtual	~ConnectionObject ()
virtual void	clear ()
virtual void	destroy ()
Accessors: inspectors and mutators
void	registerConnectionObject (ConnectionObject &object)
void	unregisterConnectionObject (ConnectionObject &object)
bool	isConnectionObjectRegistered (const ConnectionObject &object)
ConnectionObject *	getParent () const
ConnectionObject *	getRoot ()
virtual void	onNotify (Message *message)
debuggers and diagnostics
virtual bool	isValid () const
virtual void	dump (std::ostream &s=std::cout, Size depth=0) const
Protected Member Functions
void	onNotify_ (Message *message)
Protected notification methods
void	notify_ (Message *message)
void	notify_ (Message &message)
Private Member Functions
void	setParent_ (ConnectionObject &object)
void	clearParent_ ()
Private Attributes
bool	processing_message_queue_
List< Message * >	message_queue_
ConnectionObject *	parent_
List< ConnectionObject * >	children_connection_objects_

Detailed Description

Base class for all widgets and dialogs that handles communication through message posting. There are methods that handle the registering process between the classes that should be connected as well as notifying methods that are responsible for posting messages. The registering process will be handled by the interface of every dialog and widget. In this process a tree will be created that connects all connectionObject objects. See ModularWidget for further information concerning widget and dialog interface definition. The widgets communicate with the help of the method notify_. With this method a message can be sent through the connectionObject tree. One connectionObject will be the root of this tree and therefore responsible for handling and sending all incoming messages. A Message will first be sent to the root of the connectionObject tree and then will travers its way down to every leaf excluding the one that had sent the original message. If an incoming message triggers a reply message (in the onNotify method) that new message will be stored in a message queue in the root of the tree and executed if the first message has traversed all leafs of the tree. Therefore a message should always be created with the new command and the flag deletable must be set to true. If a message if statically created in the onNotify method there is the possibility that the message is already destroyed when it should be processed.

Constructor & Destructor Documentation

BALL::VIEW::ConnectionObject::ConnectionObject ( )

Default Constructor. Initialize the message queue and resets all connection to zero.

virtual BALL::VIEW::ConnectionObject::~ConnectionObject ( ) [virtual]

Destructor. Calls destroy.

See also:: destroy

Member Function Documentation

virtual void BALL::VIEW::ConnectionObject::clear ( ) [virtual]

Explicit default initialization. Clears the message queue and deletes all deletable messages in it. Further all connections to the children and the parent will be cut.

Reimplemented in BALL::VIEW::MainControl, BALL::VIEW::ModularWidget, BALL::VIEW::ServerWidget, BALL::VIEW::GeometricControl, BALL::VIEW::PyWidget, and BALL::VIEW::Scene.

void BALL::VIEW::ConnectionObject::clearParent_ ( ) [private]

virtual void BALL::VIEW::ConnectionObject::destroy ( ) [virtual]

Explicit destructor. Calls clear

See also:: clear

Reimplemented in BALL::VIEW::ModularWidget.

virtual void BALL::VIEW::ConnectionObject::dump	(	std::ostream &	s = `std::cout`,
		Size	depth = `0`
	)			const `[virtual]`

Internal value dump. Dump the current state to the output ostream s with dumping depth depth.

Parameters:

	s	output stream where to output the state
	depth	the dumping depth

Reimplemented in BALL::VIEW::MainControl, BALL::VIEW::ModularWidget, BALL::VIEW::ServerWidget, BALL::VIEW::PyWidget, and BALL::VIEW::Scene.

ConnectionObject* BALL::VIEW::ConnectionObject::getParent ( ) const

Access the parent connectionObject of this connectionObject. If this connectionObject is root 0 will be returned.

Returns:: ConnectionObject* the pointer to the parent connectionObject, 0 if this is root.

ConnectionObject* BALL::VIEW::ConnectionObject::getRoot ( )

Access the root of this ConnectionObject. Returns the ConnectionObject that parent is 0.

bool BALL::VIEW::ConnectionObject::isConnectionObjectRegistered ( const ConnectionObject & object )

Test if connectionObject is registered.

Parameters:

object

the connectionObject to be tested

Returns:: bool true if object is a child of this connectionObject, false otherwise

See also:

registerConnectionObject

unregisterConnectionObject

virtual bool BALL::VIEW::ConnectionObject::isValid ( ) const [virtual]

Internal state and consistency self-validation. Initiate self-validation of the data structure consistencies of this connectionObject. If the internal data structure of this connectionObject is correct (self-validated) and consistent true is returned, false otherwise. Checks the tree structure if all connections (in both ways: up and down) are without error.

Returns:: bool true if the internal data structure of this connectionObject is correct (self-validated) and consistent, false otherwise

Reimplemented in BALL::VIEW::ServerWidget, BALL::VIEW::PyWidget, and BALL::VIEW::Scene.

void BALL::VIEW::ConnectionObject::notify_ ( Message & message ) [protected]

Notification method with reference. See notify_ for detailed information on the notification process. Only use this method if you are absolutely sure what you are doing!

Parameters:

message

a reference to a message that will be sent through the connectionObject tree.

See also:: Message

void BALL::VIEW::ConnectionObject::notify_ ( Message * message ) [protected]

Notification method with pointer. Call this method if a message should be sent through the connectionObject tree. If this method is not called inside the onNotify method the message will immediately begin traversing the tree and trigger reactions in the other connectionObjects. After all connectionObjects have reacted to this message the method will return. If this method is called inside the onNotify method the message will be stored in the message queue of the root connectionObject and the method will immediately return. This new message will be executed after the previously message is completely executed. An often made error is to statically create a message in an onNotify method. In that case the message queue of the root connectionObject stores a pointer to the statically created message for later processing but if the message is processed later the onNotify method that has created that message is already finished. Therefore the message is no longer available what leads to a segmentation fault. To prevent that error always create messages with the new command and uses this method for the notification. See Message For further information concerning messages.

Parameters:

message

a pointer to a message that will be sent through the connectionObject tree.

See also:: Message

Referenced by BALL::VIEW::DemoTutorialDialog::nextStepDemo_().

virtual void BALL::VIEW::ConnectionObject::onNotify ( Message * message ) [virtual]

Message handling method. This method handles messages sent to this connectionObject. If a certain message should be processed for this connectionObject this method must be overridden. With the help of the RTTI methods one can easily determine if an incoming message is relevant for this connectionObject. See Message for further information concerning messages.

Parameters:

message

a pointer to a message. Do not delete the message in this method.

Reimplemented in BALL::VIEW::DisplayProperties, BALL::VIEW::LabelDialog, BALL::VIEW::ModifyRepresentationDialog, BALL::VIEW::MolecularFileDialog, BALL::VIEW::MainControl, BALL::VIEW::DatasetControl, BALL::VIEW::DockingController, BALL::VIEW::EditableScene, BALL::VIEW::GenericControl, BALL::VIEW::GeometricControl, BALL::VIEW::HelpViewer, BALL::VIEW::MolecularControl, BALL::VIEW::MolecularStructure, BALL::VIEW::RegularData1DWidget, BALL::VIEW::RegularData2DWidget, BALL::VIEW::Scene, and BALL::VIEW::DemoTutorialDialog.

void BALL::VIEW::ConnectionObject::onNotify_ ( Message * message ) [protected]

void BALL::VIEW::ConnectionObject::registerConnectionObject ( ConnectionObject & object )

Register connectionObject. The connectionObject this will be the new parent of object connectionObject. Each connectionObject can only be inserted once to a parent.

Parameters:

object

the connectionObject that is the new child of this connectionObject

See also:

unregisterConnectionObject

isConnectionObjectRegistered

void BALL::VIEW::ConnectionObject::setParent_ ( ConnectionObject & object ) [private]

void BALL::VIEW::ConnectionObject::unregisterConnectionObject ( ConnectionObject & object )

Unregister connectionObject. The connectionObject this deletes the object connectionObject from its children list and the parent of object connectionObject will be set to 0.

Parameters:

object

the connectionObject that will be removed from this connectionObject

See also:

registerConnectionObject

isConnectionObjectRegistered