Loading...
Searching...
No Matches
Signals and slots

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

Introduction

Definitions

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

Example

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) {
if (event->getType() == SBStructuralEvent::ParticlePositionChanged) {
// get the atom which sent the event
SBAtom* atom = static_cast<SBAtom*>(event->getNode());
// do something
...
}
}
This class describe a structural event.
Definition: SBMStructuralModelEvent.hpp:15
Type getType() const
Returns the structural model event type.
Definition: SBMStructuralModelEvent.cpp:20
This class describes an atom in a structural model.
Definition: SBMStructuralModelNodeAtom.hpp:34

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

atom->connectStructuralSignalToSlot(
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:

atom->disconnectStructuralSignalFromSlot(
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 an atom is changed, the atom emits the structural event SBMStructuralModelEvent::AtomPositionChanged.

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.