| 1 | /*
|
|---|
| 2 | * Project: MoleCuilder
|
|---|
| 3 | * Description: creates and alters molecular systems
|
|---|
| 4 | * Copyright (C) 2010 University of Bonn. All rights reserved.
|
|---|
| 5 | * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
|
|---|
| 6 | */
|
|---|
| 7 |
|
|---|
| 8 | /**
|
|---|
| 9 | * \file qt-gui.dox
|
|---|
| 10 | *
|
|---|
| 11 | * Created on: Jan 5, 2012
|
|---|
| 12 | * Author: heber
|
|---|
| 13 | */
|
|---|
| 14 |
|
|---|
| 15 | /**
|
|---|
| 16 | * \page qt-gui Qt GUI
|
|---|
| 17 | *
|
|---|
| 18 | * The Qt GUI is the most advanced interface and thus the most complex.
|
|---|
| 19 | *
|
|---|
| 20 | * In the following we want to explain some of the details that are involved.
|
|---|
| 21 | *
|
|---|
| 22 | * \section qt-gui-qt3d Qt3D and the way to get atoms and bonds displayed
|
|---|
| 23 | *
|
|---|
| 24 | * Atoms and Bonds have to displayed, the widget for this is GLWorldView. To
|
|---|
| 25 | * this class belongs GLWorldScene that contains lots of GLMoleculeObject's or
|
|---|
| 26 | * nodes in the speak of Qt3D. We have four derived class for these kind of
|
|---|
| 27 | * objects:
|
|---|
| 28 | * -# GLMoleculeObject_atom: for each atom,
|
|---|
| 29 | * -# GLMoleculeObject_bond: for each "side" of the bond (each represents half of
|
|---|
| 30 | * the bond that join in the middle between the two atoms),
|
|---|
| 31 | * -# GLMoleculeObject_molecule: for each molecule (shows a box is selected),
|
|---|
| 32 | * -# GLMoleculeObject_shape: shows the shapes in the ShapeRegistry.
|
|---|
| 33 | *
|
|---|
| 34 | * We can only add new nodes to the Qt3D scene at the level of GLWorldScene,
|
|---|
| 35 | * hence all insertion go through this instance to add new nodes. Destruction
|
|---|
| 36 | * may occur anywhere as the new nodes are parentized to the scene.
|
|---|
| 37 | *
|
|---|
| 38 | * \subsection qt-gui-qt3d-atoms How atom object are constructed/destroyed.
|
|---|
| 39 | *
|
|---|
| 40 | * Atoms are rendered as spheres, see createAtom(). GLWorldView gets notified
|
|---|
| 41 | * by the World about new and removed atoms via the Channel's World::AtomInserted
|
|---|
| 42 | * and World::AtomRemoved. It translates these into Qt signals with the correct
|
|---|
| 43 | * affected atom, by looking at
|
|---|
| 44 | * \code
|
|---|
| 45 | * const atom *_atom = World::getInstance().lastChanged<atom>();
|
|---|
| 46 | * \endcode
|
|---|
| 47 | * These signals call slots of GLWorldScene that has a map of all contained
|
|---|
| 48 | * GLMoleculeObject, one for either of the two kinds:
|
|---|
| 49 | * -# GLWorldScene::atomInserted(): create a new node and connect its signals
|
|---|
| 50 | * with us, add to map
|
|---|
| 51 | * -# GLWorldScene::atomRemoved(): disconnect, remove from map, destroy
|
|---|
| 52 | *
|
|---|
| 53 | * We do not need to destroy the node itself as it is connected via the Observer
|
|---|
| 54 | * mechanism to the associated atom
|
|---|
| 55 | *
|
|---|
| 56 | * \subsection qt-gui-qt3d-bonds How bond object are constructed/destroyed.
|
|---|
| 57 | *
|
|---|
| 58 | * Bonds are displayed as cylinders that elongate from one atom to the midpoint
|
|---|
| 59 | * of the bond (i.e. the spot in between the two atoms). That is we have always
|
|---|
| 60 | * two cylinders per bond. That's why we need to distinguish
|
|---|
| 61 | * GLMoleculeObject_bond::SideOfBond to get the right node.
|
|---|
| 62 | *
|
|---|
| 63 | * Bonds are not as easy as atoms: The World does not know about bonds being
|
|---|
| 64 | * created or destroyed, only the atoms themselves know about them.
|
|---|
| 65 | *
|
|---|
| 66 | * That's way the atom node object GLMoleculeObject_atom is an Observer of is
|
|---|
| 67 | * associated atom and listens to the Channel AtomObservable::BondsAdded. It then
|
|---|
| 68 | * translates this into a Qt signal that calls a slot GLWorldScene:BondInserted.
|
|---|
| 69 | *
|
|---|
| 70 | *
|
|---|
| 71 | * Bonds themselves are also Observables, as are atoms. Hence,
|
|---|
| 72 | * GLMoleculeObject_bond connect via the Observer mechanism to their associated
|
|---|
| 73 | * bond and are thus notified when they are destroyed.
|
|---|
| 74 | *
|
|---|
| 75 | * Additionally, we use GLWorldScene to do some bookkeeping about all bond nodes.
|
|---|
| 76 | * This is not strictly required but might in general be useful. Hence, signals
|
|---|
| 77 | * notify GLWorldScene also about GLWorldScene::bondRemoved that are emitted by
|
|---|
| 78 | * the node itself.
|
|---|
| 79 | *
|
|---|
| 80 | * \section QtElementList
|
|---|
| 81 | *
|
|---|
| 82 | * Lists for each element how often it occures in the world. Selecting an entry
|
|---|
| 83 | * calls SelectionAtomByElementAction to select all atoms of that particular
|
|---|
| 84 | * element.
|
|---|
| 85 | *
|
|---|
| 86 | * It observes the World and performs a complete refill on any message. To reduce
|
|---|
| 87 | * performance issues it marks the list as dirty and refills it the next time the
|
|---|
| 88 | * GUI is idle. This way many successive changes to the world only lead to a
|
|---|
| 89 | * single refill.
|
|---|
| 90 | *
|
|---|
| 91 | * \section QtMoleculeList
|
|---|
| 92 | *
|
|---|
| 93 | * Lists all the molecules currently in the world grouped by their formula.
|
|---|
| 94 | * Selecting an entry calls the SelectionMoleculeByIdAction.
|
|---|
| 95 | *
|
|---|
| 96 | * It observes the World the same way QtElementList does.
|
|---|
| 97 | *
|
|---|
| 98 | * \section QtShapeController
|
|---|
| 99 | *
|
|---|
| 100 | * This is the interface for the ShapeRegistry. It lists all the shapes in the
|
|---|
| 101 | * registry and lets the user select them. It also features buttons to call
|
|---|
| 102 | * actions creating and manipulating the selected shapes.
|
|---|
| 103 | *
|
|---|
| 104 | * As an Observer it handles the following messages from ShapeRegistry:
|
|---|
| 105 | * - ShapeRegistry::ShapeInserted
|
|---|
| 106 | * - ShapeRegistry::ShapeRemoved
|
|---|
| 107 | * - ShapeRegistry::SelectionChanged
|
|---|
| 108 | *
|
|---|
| 109 | * \section QtInfoBox
|
|---|
| 110 | *
|
|---|
| 111 | * Shows information about the atom and molecule the cursor is currently hovering
|
|---|
| 112 | * over inside the GLWorldView.
|
|---|
| 113 | *
|
|---|
| 114 | * GLWorldView emits hoverChanged signals (via QT's signal slot mechanism) which
|
|---|
| 115 | * the QtInfoBox receives. QtInfoBox then creates its info pages for the atom
|
|---|
| 116 | * being transmitted as the signal's parameter.
|
|---|
| 117 | *
|
|---|
| 118 | * The info pages are Observers for the atom/molecule. When recieving subjectKilled
|
|---|
| 119 | * they automatically clear the info box.
|
|---|
| 120 | *
|
|---|
| 121 | * \date 2013-02-22
|
|---|
| 122 | */
|
|---|
