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 

        ...

    }

}

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:

• Base events: events sent by data graph nodes about their base properties (e.g. their selection flag).
• Document events: events sent by documents and folders.
• Structural events: events sent by structural models and structural nodes.
• Visual events: events sent by visual models.
• Dynamical events: events sent by dynamical models.
• Interaction events: events sent by interaction models.
• Property events: events sent by property models.
• Simulator events: events sent by simulators.
• State updater events: events sent by state updaters.
• Controller events: events sent by controllers.

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.