/*
 * 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. To
 * this class belongs GLWorldScene that contains lots of GLMoleculeObject's or
 * nodes in the speak of Qt3D. We have four derived class for these kind of
 * objects:
 * -# GLMoleculeObject_atom: for each atom,
 * -# GLMoleculeObject_bond: for each "side" of the bond (each represents half of
 *     the bond that join in the middle between the two atoms),
 * -# GLMoleculeObject_molecule: for each molecule (shows a box is selected),
 * -# GLMoleculeObject_shape: shows the shapes in the ShapeRegistry.
 *
 * 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.
 *
 * \section QtElementList
 *
 * Lists for each element how often it occures in the world. Selecting an entry
 * calls SelectionAtomByElementAction to select all atoms of that particular
 * element.
 *
 * It observes the World and performs a complete refill on any message. To reduce
 * performance issues it marks the list as dirty and refills it the next time the
 * GUI is idle. This way many successive changes to the world only lead to a
 * single refill.
 *
 * \section QtMoleculeList
 *
 * Lists all the molecules currently in the world grouped by their formula.
 * Selecting an entry calls the SelectionMoleculeByIdAction.
 *
 * It observes the World the same way QtElementList does.
 *
 * \section QtShapeController
 *
 * This is the interface for the ShapeRegistry. It lists all the shapes in the
 * registry and lets the user select them. It also features buttons to call
 * actions creating and manipulating the selected shapes.
 *
 * As an Observer it handles the following messages from ShapeRegistry:
 *  - ShapeRegistry::ShapeInserted
 *  - ShapeRegistry::ShapeRemoved
 *  - ShapeRegistry::SelectionChanged
 *
 * \section QtInfoBox
 *
 * Shows information about the atom and molecule the cursor is currently hovering
 * over inside the GLWorldView.
 *
 * GLWorldView emits hoverChanged signals (via QT's signal slot mechanism) which
 * the QtInfoBox receives. QtInfoBox then creates its info pages for the atom
 * being transmitted as the signal's parameter.
 *
 * The info pages are Observers for the atom/molecule. When recieving subjectKilled
 * they automatically clear the info box.
 *
 * \date 2013-02-22
 */