| 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 values.dox
|
|---|
| 10 | *
|
|---|
| 11 | * Created on: Mar 16, 2012
|
|---|
| 12 | * Author: heber
|
|---|
| 13 | */
|
|---|
| 14 |
|
|---|
| 15 | /**
|
|---|
| 16 | * \page values Values from the user to the Action
|
|---|
| 17 | *
|
|---|
| 18 | * The way from a value to end up as a option value/parameter inside an
|
|---|
| 19 | * \link MoleCuilder::Action Action \endlink ist rather complex. Hence,
|
|---|
| 20 | * let us briefly sketch the complete path, ranging from the \link
|
|---|
| 21 | * userinterfaces User Interface \endlink to the Action.
|
|---|
| 22 | *
|
|---|
| 23 | * \section value-from-ui From the user interface ...
|
|---|
| 24 | *
|
|---|
| 25 | * The user may enter a value either in ...
|
|---|
| 26 | * -# a command line option, e.g. ...--position "0,1,2" ...
|
|---|
| 27 | * -# a text interface, e.g. "Which position:" "0,1,2"
|
|---|
| 28 | * -# a GUI dialog: Placing "0,1,2" in some text box or alike.
|
|---|
| 29 | *
|
|---|
| 30 | * This is handled by a class derived from a \ref Dialog::Query and all queries
|
|---|
| 31 | * of a specific Action are placed into a \ref Dialog. A \ref Dialog::Query
|
|---|
| 32 | * may e.g. be \ref TextDialog::VectorTextQuery. This class is derived from
|
|---|
| 33 | * \ref Dialog::VectorQuery which is derived from Query.
|
|---|
| 34 | *
|
|---|
| 35 | * The \ref Dialog::Query instance has a member Query::tmp which eventually
|
|---|
| 36 | * contains the value of a specific type (here Vector) from the user.
|
|---|
| 37 | * TextDialog::VectorTextQuery::handle() asks the user in some way for the value,
|
|---|
| 38 | * Dialog::VectorQuery::setResult() places Dialog::VectorQuery::tmp into the
|
|---|
| 39 | * \ref ValueStorage. This is done under a specific token which the Query
|
|---|
| 40 | * knows via its cstor: Query::title.
|
|---|
| 41 | *
|
|---|
| 42 | * ValueStorage does not take any value but only those it knows and more
|
|---|
| 43 | * specifically whose type it knows. I.e. for each option it has to know
|
|---|
| 44 | * a token and a name. These are contained in instances of \ref OptionTrait.
|
|---|
| 45 | * The list of these instances is contained in \ref ActionTrait which each
|
|---|
| 46 | * specialized \link MoleCuilder::Action Action \endlink gets on construction.
|
|---|
| 47 | * In Action's cstor these Trait's are registered with the \ref ActionRegistry
|
|---|
| 48 | * and the \ref OptionRegistry.
|
|---|
| 49 | *
|
|---|
| 50 | * And the OptionRegistry is then the place where \ref ValueStorage checks
|
|---|
| 51 | * whether token and type (the value) given to it are correct. This is required
|
|---|
| 52 | * to ensure that only a specific type is associated with each token. If another
|
|---|
| 53 | * type is needed simply think of a new token.
|
|---|
| 54 | *
|
|---|
| 55 | * \section value-from-action ... into the Action
|
|---|
| 56 | *
|
|---|
| 57 | * Now the value rests inside the ValueStorage as a string with a known type.
|
|---|
| 58 | * Every \link MoleCuilder::Action Action \endlink in its Action::performCall()
|
|---|
| 59 | * call Action::getParametersFromValueStorage() which fills an internal
|
|---|
| 60 | * Action::params structure (that is constructed as most of the other stuff
|
|---|
| 61 | * in an action via boost::preprocessor magic). This is then used by the
|
|---|
| 62 | * Action to know that the token "position" with value "0,1,2" which the user
|
|---|
| 63 | * supplied are meant to place a new atom at (0,1,2) (\ref AddAtomAction). It
|
|---|
| 64 | * takes the value from AtomAddAction::params::position (all these information
|
|---|
| 65 | * is stored in \ref AddAction.def).
|
|---|
| 66 | *
|
|---|
| 67 | *
|
|---|
| 68 | * \date 2012-03-16
|
|---|
| 69 | *
|
|---|
| 70 | */
|
|---|
