Loading...
Searching...
No Matches
BALL::VIEW::ConnectionObject Class Reference
Visualisation » Kernel » 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 notification methods

void | notify_ (Message *message)
void | notify_ (Message &message)
void | onNotify_ (Message *message)

## 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.

Definition at line 39 of file connectionObject.h.

## Constructor & Destructor Documentation

## ConnectionObject()

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

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

## ~ConnectionObject()

virtual BALL::VIEW::ConnectionObject::~ConnectionObject | ( |  | ) |

virtual

Destructor. Calls destroy.

See also
  destroy

## Member Function Documentation

## clear()

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::GeometricControl, BALL::VIEW::MainControl, BALL::VIEW::ModularWidget, BALL::VIEW::Scene, and BALL::VIEW::ServerWidget.

## destroy()

virtual void BALL::VIEW::ConnectionObject::destroy | ( |  | ) |

virtual

Explicit destructor. Calls clear

See also
  clear

Reimplemented in BALL::VIEW::ModularWidget.

## dump()

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::PyWidget, BALL::VIEW::Scene, and BALL::VIEW::ServerWidget.

## getParent()

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.

## getRoot()

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

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

## isConnectionObjectRegistered()

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

## isValid()

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::PyWidget, BALL::VIEW::Scene, and BALL::VIEW::ServerWidget.

## notify_() [1/2]

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

## notify_() [2/2]

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

## onNotify()

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::DatasetControl, BALL::VIEW::DisplayProperties, BALL::VIEW::DockingController, BALL::VIEW::GenericControl, BALL::VIEW::GeometricControl, BALL::VIEW::HelpViewer, BALL::VIEW::LabelDialog, BALL::VIEW::MainControl, BALL::VIEW::ModifyRepresentationDialog, BALL::VIEW::MolecularControl, BALL::VIEW::MolecularFileDialog, BALL::VIEW::MolecularStructure, BALL::VIEW::Scene, and BALL::VIEW::UndoManagerDialog.

## onNotify_()

void BALL::VIEW::ConnectionObject::onNotify_ | ( | Message * | message | ) |

protected

## registerConnectionObject()

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

## unregisterConnectionObject()

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