Signals and slots

SAMSON has a signals and slots mechanism on which SAMSON Elements may rely to develop adaptive and incremental algorithms.



We use the following definitions:

  • A signal is an object that emits events
  • An event is an object that is emitted by a signal
  • A slot is a function that receives an event emitted by a signal


Assume an app implements an adaptive algorithm that needs to be notified when some atoms changes their positions. An atom is a structural node, and the position is a property of this structural node. A position change is thus a structural event, and the app will implement a slot that receives a structural event:

void SEMyElementApp::onStructuralEvent(SBStructuralEvent* event) {
// get the atom which sent the event
SBAtom* atom = static_cast<SBAtom*>(event->getNode());
// do something

and connect this slot to the structural signal of some atoms:

this, // the pointer to the app
SB_SLOT(&SEMyElementApp::onStructuralEvent) // the slot

Whenever an atom position changes, the slot will be called immediately. When the app does not need to be notified anymore, it can disconnect atoms:

this, // the pointer to the app
SB_SLOT(&SEMyElementApp::onStructuralEvent) // the slot

Types of events

SAMSON's data graph nodes may send ten types of events:

In general, events signal changes in attributes of event senders. For example, when the position of a structural particle is changed, the structural particle emits the structural event SBMStructuralModelEvent::ParticlePositionChanged.

The type of event associated to a property is determined by the class that defines the relevant property. For example, an atom is a structural node, so a change in its position is a structural event. Similarly, the list of structural models contained in a document or in a folder is a property of the document or the folder, so the events that signal changes in this list are document events: SBDDocumentEvent::StructuralModelAdded and SBDDocumentEvent::StructuralModelRemoved.

Note that a class has to be a reference target in order to be able to receive signals. As a result, slots are typically added to non-GUI classes (e.g. SBDApp instead of SBGApp), which (indirectly) derive from the SBCReferenceTarget class. Please refer to the chapter about references for more information.