| 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. This
|
|---|
| 25 | * this class belongs GLWorldScene that contains lots of GLMoleculeObject's or
|
|---|
| 26 | * nodes in the speak of Qt3D. We have two derived class for these kind of
|
|---|
| 27 | * objects:
|
|---|
| 28 | * -# GLMoleculeObject_atom: for each atom,
|
|---|
| 29 | * -# GLMoleculeObject_bond: for each "side" of the bond.
|
|---|
| 30 | *
|
|---|
| 31 | * We can only add new nodes to the Qt3D scene at the level of GLWorldScene,
|
|---|
| 32 | * hence all insertion go through this instance to add new nodes. Destruction
|
|---|
| 33 | * may occur anywhere as the new nodes are parentized to the scene.
|
|---|
| 34 | *
|
|---|
| 35 | * \subsection qt-gui-qt3d-atoms How atom object are constructed/destroyed.
|
|---|
| 36 | *
|
|---|
| 37 | * Atoms are rendered as spheres, see createAtom(). GLWorldView gets notified
|
|---|
| 38 | * by the World about new and removed atoms via the Channel's World::AtomInserted
|
|---|
| 39 | * and World::AtomRemoved. It translates these into Qt signals with the correct
|
|---|
| 40 | * affected atom, by looking at
|
|---|
| 41 | * \code
|
|---|
| 42 | * const atom *_atom = World::getInstance().lastChanged<atom>();
|
|---|
| 43 | * \endcode
|
|---|
| 44 | * These signals call slots of GLWorldScene that has a map of all contained
|
|---|
| 45 | * GLMoleculeObject, one for either of the two kinds:
|
|---|
| 46 | * -# GLWorldScene::atomInserted(): create a new node and connect its signals
|
|---|
| 47 | * with us, add to map
|
|---|
| 48 | * -# GLWorldScene::atomRemoved(): disconnect, remove from map, destroy
|
|---|
| 49 | *
|
|---|
| 50 | * We do not need to destroy the node itself as it is connected via the Observer
|
|---|
| 51 | * mechanism to the associated atom
|
|---|
| 52 | *
|
|---|
| 53 | * \subsection qt-gui-qt3d-bonds How bond object are constructed/destroyed.
|
|---|
| 54 | *
|
|---|
| 55 | * Bonds are displayed as cylinders that elongate from one atom to the midpoint
|
|---|
| 56 | * of the bond (i.e. the spot in between the two atoms). That is we have always
|
|---|
| 57 | * two cylinders per bond. That's why we need to distinguish
|
|---|
| 58 | * GLMoleculeObject_bond::SideOfBond to get the right node.
|
|---|
| 59 | *
|
|---|
| 60 | * Bonds are not as easy as atoms: The World does not know about bonds being
|
|---|
| 61 | * created or destroyed, only the atoms themselves know about them.
|
|---|
| 62 | *
|
|---|
| 63 | * That's way the atom node object GLMoleculeObject_atom is an Observer of is
|
|---|
| 64 | * associated atom and listens to the Channel AtomObservable::BondsAdded. It then
|
|---|
| 65 | * translates this into a Qt signal that calls a slot GLWorldScene:BondInserted.
|
|---|
| 66 | *
|
|---|
| 67 | *
|
|---|
| 68 | * Bonds themselves are also Observables, as are atoms. Hence,
|
|---|
| 69 | * GLMoleculeObject_bond connect via the Observer mechanism to their associated
|
|---|
| 70 | * bond and are thus notified when they are destroyed.
|
|---|
| 71 | *
|
|---|
| 72 | * Additionally, we use GLWorldScene to do some bookkeeping about all bond nodes.
|
|---|
| 73 | * This is not strictly required but might in general be useful. Hence, signals
|
|---|
| 74 | * notify GLWorldScene also about GLWorldScene::BondRemoved that are emitted by
|
|---|
| 75 | * the node itself.
|
|---|
| 76 | *
|
|---|
| 77 | * \date 2012-01-05
|
|---|
| 78 | */
|
|---|
