Index: src/documentation/constructs/qt-gui.dox
===================================================================
--- src/documentation/constructs/qt-gui.dox	(revision 52c5d4c7c4ecce1343353bae76e18959dd8d2d1a)
+++ src/documentation/constructs/qt-gui.dox	(revision 59f1bcc899a181c8225110eb43adbf27eb563d57)
@@ -59,7 +59,7 @@
  * there is a QTimer that only updates an object in regular intervals, or
  * because of asynchronous threads. Elsewhen, the slot callback for a
- * certain signal is called directly. For all of these cases we have to
+ * certain signal is called directly. All of these cases we have to
  * accommodate. This is especially problematic with the instantiation and
- * destruction of objects.
+ * destruction of objects that represent atoms and molecules in the World.
  *
  * A clarifying example: Imagine an atom is constructed, the AtomObserver
@@ -70,8 +70,9 @@
  *
  * The only possible way out is to duplicate information. This is the usual
- * way how to deal with environments with multiple threads. I.e. all the
+ * way how to proceed in environments with multiple threads. I.e. all the
  * information that the GUI representants of information inside the World
  * needs to be doubled such that when the original information is destroyed
- * the representant can still be accessed as long as needed.
+ * the representant can still be accessed as long as needed. Here, we use
+ * the ObservedValue construct of CodePatterns.
  *
  * \subsection qt-gui-general-observedvalue Observed Value
@@ -100,31 +101,111 @@
  * pieces of information that require more computing resources within the
  * updater. Also, the Cacheable's information can only be obtained as long
- * as the source of information is still alive.
- *
- * Both concepts can be used in threaded environments as mutexed are used to
+ * as the source of information is still alive. However, so far Cacheable's
+ * content is marked invalid when an update signal has been received and
+ * update itself only on request, which is no longer possible when the object
+ * to represent is gone.
+ *
+ * Both concepts can be used in threaded environments as mutexes are used to
  * protect read and write accesses.
  *
- * \subsection qt-gui-general-signalslot Observer/Observable and Signal/Slot
- *
- * In the following we refer to Observer/Observable as "O/O" and to Signal/Slot
- * as "S/S".
- *
- * One thing we need to do is to translate between update() or
- * recieveNotification() calls from an Observable and subsequent signal/slot
- * calls. The general idea is to use these ObservedValues as translation
- * points for small pieces of information and Cacheables for larger pieces.
- *
- * However, we need more of these translation points:
- * -# GLWorldView checks for
- *   -# World's MoleculeInserted
- *   -# World's SelectionChanged
- *   -# WorldTime's TimeChanged
- *   -# each molecule's AtomInserted and AtomRemoved
- *   -# AtomObservable's AtomChanged.
- *   -# ShapeRegistry's ShapedAdded, ShapeRemoved, and SelectionChanged
- * -# GLMoleculeObject_molecule checks for
- *   -# molecule's AtomInserted, AtomRemoved, AtomMoved, IndexChanged
- *   -# World's SelectionChanged
- *
+ * \subsection qt-gui-general-observedinstance The observed instance board
+ *
+ * The setup is then as follows: We have two distinct realms, the World (with
+ * atoms and molecules) on the one side and the QtGUI (with visual
+ * representations of atoms and molecules) on the other side.
+ *
+ * There is an interface between this world such that the destruction of an
+ * atom does not directly invalidate its visual representation. This interface
+ * between the two realms is contained in the class QtObservedInstanceBoard,
+ * which is a singleton and is similar to the World instance in the World realm
+ * for the QtGui realm.
+ *
+ * All properties, e.g. the position of an element, relevant to the QtGUI are
+ * duplicated as ObservedValues. Properties associated to the same instance in
+ * the World, e.g. the same atom, are combined into a QtObservedAtom instance,
+ * and similarly QtObservedMolecule for molecule. All of these observed
+ * instances are placed into ObservedValuesContainer which are contained in
+ * the interface QtObservedInstanceBoard.
+ *
+ * The sequence of events is then as follows (here exemplified with an atom):
+ * -# an atom is created (World::createAtom()), the World notifies about it
+ *    via its World::AtomInserted channel.
+ * -# QtObservedInstanceBoard is signOn()ed to this channel and instantiates
+ *    a new QtObservedAtom which is placed into its respective
+ *    ObservedValuesContainer.
+ * -# on instantiation of QtObservedAtom a vector of specific ObservedValues is
+ *    created, one for each property (position, element, bond count, ...).
+ *    Each signOn()s to the respective atom's channel. Also the QtObservedAtom
+ *    signOn()s to each of these channels as it converts these notifications
+ *    into Qt signals (and the updated value can be accessed via getters from
+ *    the QtObservedAtom instance). The QtObservedInstanceBoard is notified
+ *    of this with the instance being marked as connected.
+ * -# when the atom is destroyed (World::destroyAtom()), being an Observable
+ *    it will call subjectKilled() on all its channels. The
+ *    ObservedValue_wCallback announces this subjectKilled() via the callback
+ *    function which notifies QtObservedAtom. Once all subjectKilled(), for
+ *    each observed value and for QtObservedAtom itself, have been received,
+ *    the QtObservedInstanceBoard is notified by the instance now being
+ *    marked as disconnected and ready for erase.
+ * -# then the QtObservedInstanceBoard removes the instance from its
+ *    ObservedValuesContainer.
+ *
+ * Note however that the instance is a shared_ptr and will continue to exist
+ * and therefore its getters will still deliver the last piece of information
+ * before the atom was destroyed until all shared_ptrs are released. Hence,
+ * the QtGui may safely continue using the pointer.
+ *
+ * As new observed instances may come in immediately having the same id and
+ * as it is difficult to keep track who got its observed instance already
+ * and who not, a soft fail is required. I.e. of the QtObservedInstanceBoard
+ * returns an empty shared_ptr this means that the object -- despite any
+ * received (and probably delayed) signal -- has been destroyed and should
+ * not be displayed, updated by, ... whatsoever.
+ *
+ * \subsection qt-gui-general-signalslot Details on the slot connections
+ *
+ * Qt's event system does not guarantee that events are always processed in
+ * the order they are emitted. This is because connections can be defined
+ * as direct or queued (or both with auto). Direct connections will always
+ * be executed as direct function calls, i.e. immediately. Queued connections
+ * however are inserted into Qt's event queue and may even get processed by
+ * a different thread.
+ *
+ * We have to take care of this.
+ *
+ * Basically what we do in QtObservedInstanceBoard and the observed instances
+ * of type QtObservedAtom and QtObservedMolecule is that we translate between
+ * the Observer/Observable (O/O) system of CodePatterns with its callback
+ * functions and the event system of Qt with its Signal/Slot (S/S).
+ *
+ * That is in the recieveNotification() functions many "emit()"s can be found.
+ *
+ * Furthermore, signals are used in a specific way to ensure synchronicity.
+ * This is only a problem with the visual representation as we there find a
+ * a nested problem: First molecules, then atoms belonging to a certain
+ * molecule. This enforces a certain sequence of events and thus of signals.
+ *
+ * \subsubsection qt-gui-general-signalslot-glworldscene Details on GLWorldScene
+ *
+ * The central place for all events is the GLWorldScene instance. There
+ * signals from QtObservedInstanceBoard for insertion and removal of both atoms
+ * and molecules are caught. Insertion of molecules is dealt with directly,
+ * we sign on to the inserted&removed channels for its atoms, then we emit
+ * a queued signal to actually instantiate the GLMoleculeObject_molecule.
+ *
+ * Until its instantiation we store incoming signals in the
+ * GLWorldScene::MoleculeMissedStateMap, protected by a mutex to enforce atomic
+ * access. After it has been instantiated (and all stored signals have been
+ * processed), they are relayed onto the specific instance. However, we do not
+ * do this via emits but by directly using Qt's invokeMethod() which allows
+ * to trigger queued events. This way it is done in a likewise manner whether
+ * it has been a stored or live signal that was received.
+ *
+ * \subsubsection qt-gui-general-signalslot-other Details on other signals
+ *
+ * All other signals that only change the property of a visual representation,
+ * e.g. the element of an atom, is directly processed by, in this case, the
+ * GLMoleculeObject_atom connected to QtObservedAtom.
+. *
  * \section qt-gui-qt3d Qt3D and the way to get atoms and bonds displayed
  *
@@ -146,6 +227,6 @@
  * of an element-specific color at the atom's position. The atom relies
  * on its representants to be contain all required information but it
- * is also signOn() to the atom itself whose O/O are translated to S/S
- * for processing whenever desired.
+ * is also signOn() to the QtObservedAtom itself whose O/O are translated to
+ * S/S for processing whenever desired.
  *
  * Next comes the GLMoleculeObject_bond which displays a cylinder between
@@ -158,5 +239,5 @@
  *
  * Parallel to these are GLMoleculeObject_shape which display the surface
- * of a selected shape. A shape in general does not change after instantation,
+ * of a selected shape. A shape in general does not change after instantiation,
  * hence the shape lives with the information it gets on instantiation till
  * it dies.
@@ -168,5 +249,5 @@
  * molecules. The molecule also needs ObservedValues for its bounding box
  * (used to show when it's selected), the index, the selection status,
- * and the list of atom ids. As Cacheable we use the tesselation structure.
+ * and the list of atom ids.
  *
  * \section qt-gui-cases Sample cases
@@ -270,4 +351,4 @@
  * they automatically clear the info box.
  *
- * \date 2015-07-15
+ * \date 2016-01-08
  */
