/*
 * Project: MoleCuilder
 * Description: creates and alters molecular systems
 * Copyright (C)  2010 University of Bonn. All rights reserved.
 * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
 */

/**
 * \file qt-gui.dox
 *
 * Created on: Jan 5, 2012
 *    Author: heber
 */

/**
 * \page qt-gui Qt GUI
 *
 * The Qt GUI is the most advanced interface and thus the most complex.
 *
 * In the following we want to explain some of the details that are involved.
 *
 * \section qt-gui-qt3d Qt3D and the way to get atoms and bonds displayed
 *
 * Atoms and Bonds have to displayed, the widget for this is GLWorldView. This
 * this class belongs GLWorldScene that contains lots of GLMoleculeObject's or
 * nodes in the speak of Qt3D. We have two derived class for these kind of
 * objects:
 * -# GLMoleculeObject_atom: for each atom,
 * -# GLMoleculeObject_bond: for each "side" of the bond.
 *
 * We can only add new nodes to the Qt3D scene at the level of GLWorldScene,
 * hence all insertion go through this instance to add new nodes. Destruction
 * may occur anywhere as the new nodes are parentized to the scene.
 *
 * \subsection qt-gui-qt3d-atoms How atom object are constructed/destroyed.
 *
 * Atoms are rendered as spheres, see createAtom(). GLWorldView gets notified
 * by the World about new and removed atoms via the Channel's World::AtomInserted
 * and World::AtomRemoved. It translates these into Qt signals with the correct
 * affected atom, by looking at
 * \code
 *   const atom *_atom = World::getInstance().lastChanged<atom>();
 * \endcode
 * These signals call slots of GLWorldScene that has a map of all contained
 * GLMoleculeObject, one for either of the two kinds:
 * -# GLWorldScene::atomInserted(): create a new node and connect its signals
 *  with us, add to map
 * -# GLWorldScene::atomRemoved(): disconnect, remove from map, destroy
 *
 * We do not need to destroy the node itself as it is connected via the Observer
 * mechanism to the associated atom
 *
 * \subsection qt-gui-qt3d-bonds How bond object are constructed/destroyed.
 *
 * Bonds are displayed as cylinders that elongate from one atom to the midpoint
 * of the bond (i.e. the spot in between the two atoms). That is we have always
 * two cylinders per bond. That's why we need to distinguish
 * GLMoleculeObject_bond::SideOfBond to get the right node.
 *
 * Bonds are not as easy as atoms: The World does not know about bonds being
 * created or destroyed, only the atoms themselves know about them.
 *
 * That's way the atom node object GLMoleculeObject_atom is an Observer of is
 * associated atom and listens to the Channel AtomObservable::BondsAdded. It then
 * translates this into a Qt signal that calls a slot GLWorldScene:BondInserted.
 *
 *
 * Bonds themselves are also Observables, as are atoms. Hence,
 * GLMoleculeObject_bond connect via the Observer mechanism to their associated
 * bond and are thus notified when they are destroyed.
 *
 * Additionally, we use GLWorldScene to do some bookkeeping about all bond nodes.
 * This is not strictly required but might in general be useful. Hence, signals
 * notify GLWorldScene also about GLWorldScene::BondRemoved that are emitted by
 * the node itself.
 *
 * \date 2012-01-05
 */