Changeset 7ef5b9a

Timestamp:

Dec 14, 2012, 1:03:36 PM (12 years ago)

Author:

Frederik Heber <heber@…>

Branches:

Action_Thermostats, Add_AtomRandomPerturbation, Add_FitFragmentPartialChargesAction, Add_RotateAroundBondAction, Add_SelectAtomByNameAction, Added_ParseSaveFragmentResults, AddingActions_SaveParseParticleParameters, Adding_Graph_to_ChangeBondActions, Adding_MD_integration_tests, Adding_ParticleName_to_Atom, Adding_StructOpt_integration_tests, AtomFragments, Automaking_mpqc_open, AutomationFragmentation_failures, Candidate_v1.5.4, Candidate_v1.6.0, Candidate_v1.6.1, ChangeBugEmailaddress, ChangingTestPorts, ChemicalSpaceEvaluator, CombiningParticlePotentialParsing, Combining_Subpackages, Debian_Package_split, Debian_package_split_molecuildergui_only, Disabling_MemDebug, Docu_Python_wait, EmpiricalPotential_contain_HomologyGraph, EmpiricalPotential_contain_HomologyGraph_documentation, Enable_parallel_make_install, Enhance_userguide, Enhanced_StructuralOptimization, Enhanced_StructuralOptimization_continued, Example_ManyWaysToTranslateAtom, Exclude_Hydrogens_annealWithBondGraph, FitPartialCharges_GlobalError, Fix_BoundInBox_CenterInBox_MoleculeActions, Fix_ChargeSampling_PBC, Fix_ChronosMutex, Fix_FitPartialCharges, Fix_FitPotential_needs_atomicnumbers, Fix_ForceAnnealing, Fix_IndependentFragmentGrids, Fix_ParseParticles, Fix_ParseParticles_split_forward_backward_Actions, Fix_PopActions, Fix_QtFragmentList_sorted_selection, Fix_Restrictedkeyset_FragmentMolecule, Fix_StatusMsg, Fix_StepWorldTime_single_argument, Fix_Verbose_Codepatterns, Fix_fitting_potentials, Fixes, ForceAnnealing_goodresults, ForceAnnealing_oldresults, ForceAnnealing_tocheck, ForceAnnealing_with_BondGraph, ForceAnnealing_with_BondGraph_continued, ForceAnnealing_with_BondGraph_continued_betteresults, ForceAnnealing_with_BondGraph_contraction-expansion, FragmentAction_writes_AtomFragments, FragmentMolecule_checks_bonddegrees, GeometryObjects, Gui_Fixes, Gui_displays_atomic_force_velocity, ImplicitCharges, IndependentFragmentGrids, IndependentFragmentGrids_IndividualZeroInstances, IndependentFragmentGrids_IntegrationTest, IndependentFragmentGrids_Sole_NN_Calculation, JobMarket_RobustOnKillsSegFaults, JobMarket_StableWorkerPool, JobMarket_unresolvable_hostname_fix, MoreRobust_FragmentAutomation, ODR_violation_mpqc_open, PartialCharges_OrthogonalSummation, PdbParser_setsAtomName, PythonUI_with_named_parameters, QtGui_reactivate_TimeChanged_changes, Recreated_GuiChecks, Rewrite_FitPartialCharges, RotateToPrincipalAxisSystem_UndoRedo, SaturateAtoms_findBestMatching, SaturateAtoms_singleDegree, StoppableMakroAction, Subpackage_CodePatterns, Subpackage_JobMarket, Subpackage_LinearAlgebra, Subpackage_levmar, Subpackage_mpqc_open, Subpackage_vmg, Switchable_LogView, ThirdParty_MPQC_rebuilt_buildsystem, TrajectoryDependenant_MaxOrder, TremoloParser_IncreasedPrecision, TremoloParser_MultipleTimesteps, TremoloParser_setsAtomName, Ubuntu_1604_changes, stable

Children:

14de8e1

Parents:

6ffc0b

git-author:

Frederik Heber <heber@…> (03/16/12 12:29:01)

git-committer:

Frederik Heber <heber@…> (12/14/12 13:03:36)

Message:

DOCU: Extended documentation on how values from the user are eventually used by Actions.

• updated ValueStorage docu.

Location:

src

Files:

• UIElements/Dialog.hpp (modified) (3 diffs)
• documentation/constructs/actions.dox (modified) (2 diffs)

src/UIElements/Dialog.hpp

@@ -197 +197 @@
   //these queries can be handled by this dialog
 
-  //TODO: Find a way to reduce complexity...
-  //needs O(N*M) query classes, where N is the number of query types and M is the number of GUIs
-  //usual approach for reducing inheritance complexity (strategy pattern) does not work,
-  //due to lack of common code for query types as well as GUI-Types (all subtypes differ a lot)
-
   /** Base class for all queries.
    *
@@ -209 +204 @@
    * of the interface that the user is using.
    *
-   * A Query always contains a protected member variable of the specific type.
-   * For each type there is a derived class, e.g. for a boolean there is
-   * \ref BooleanQuery deriving from \ref Query. Each specific UI derives
-   * again from a specific Query, e.g. for the \link userinterfaces-textmenu
-   * textmenu \endlink we have \ref BooleanTextQuery that derives from
-   * \ref BooleanQuery. This derived class has to implement the Query::handle
-   * function that actually sets the protected member variable to something
-   * the user has entered. Also it implements Query::setResult that actually
-   * places the obtained value in the \ref ValueStorage.
+   * A Query just has title and description and serves as the general interface
+   * to queries. TQuery is a templatization of the Query containing a protected
+   * member variable of the specific type and also a Parameter<> reference of
+   * the type that actually belongs to the Action that triggered/created the
+   * Query. handle() is UI-specific and sets the (temporary) member variable. 
+   * However, isValid() in TQuery checks via the Parameter<> reference whether
+   * the variable is valid with the given Validators and setResult() finally
+   * set the Parameter with the temporary variable.
+   *
+   * For each type there is a derived class per \b UI, e.g. for the
+   * \link userinterfaces-textmenu textmenu \endlink we have 
+   * \ref BooleanTextQuery that derives from \ref TQuery<bool>. This derived
+   * class has to implement the Query::handle() function that actually sets
+   * the protected member variable to something the user has entered. 
+   *
+   * Thanks to the templated TQuery this is a as simple as it can get. The
+   * handle() has to be UI-specific, hence has to be implemented once for
+   * every present UI. But all other code can be used for either of them.
    *
    * \section query-howto How to add another query?
@@ -224 +228 @@
    *
    * Then, we do the following:
-   *  -# Add a class ValueQuery inside class Dialog, the class contains
-   *    -# constructor/destructor (latter virtual! because of derived class)
-   *    -# virtual bool handle() and virtual void setResult()
-   *    -# a protected member tmp of type Value (NOTE: herein the result is stored)
-   *    -# if temporaries for conversion are needed put them in here
-   *  -# add a function queryValue
-   *  -# now, for each of the GUIs we basically have to repeat the above, i.e.
-   *     add the class and the function that implement the virtual ones above.
-   *    -# QT: an extra class called ValueQtQueryPipe that actually handles
-   *       showing dialogs to obtain the value and placing it into the \a tmp
-   *       variable (via a given pointer to it as reference). handle() will
-   *       simply return true. This is needed because of a restriction of Qt4:
-   *       its meta-object-compiler does not like nested classes.
+   *  -# add a virtual function queryValue inside class Dialog.
+   *  -# now, for each of the GUIs we basically have to add a sub-class for the
+   *     respective Query inside the derived Dialog that implements handle().
+   *    -# QT: typically we use a onUpdate() function here attached the Qt
+   *       signals and handle then just does nothing.
    *    -# CommandLine: nothing special, handle() imports value from \a
    *       CommandLineParser and sets the tmp variable.

src/documentation/constructs/actions.dox

@@ -53 +53 @@
  * has to be implemented in two more functions beside the "do".
  *
- * Note that undoing means to get every back to its original state and by whatever
- * means seem appropriate, e.g. just remvoing all inserted atoms.
+ * Note that undoing means to get everything back to its original state and by
+ * whatever means seem appropriate, e.g. just remvoing all inserted atoms.
  * To make this more elaborate it is usually very useful to store extra information
  * in the Action's state such that undo and redo can be accomplished more quickly.
@@ -70 +70 @@
  *
  *
- *  \date 2012-04-05
+ *  \date 2012-12-04
  *
  */