Changeset 0430e3 for src/Actions/Action.hpp

Timestamp:

Jul 26, 2010, 6:42:57 PM (15 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:

677e13, d6e719

Parents:

e076cd

Message:

FIX: ActionCalls.hpp removed, ActionRegistry.hpp included instead

• also, extended documentation of Action (Action howto).

File:

• src/Actions/Action.hpp (modified) (4 diffs)

src/Actions/Action.hpp

@@ -45 +45 @@
  * hasRedo() method respectively.
  *
+ * Note that an Action always has two functions createDialog() and performCall(). The former
+ * returns a Dialog filled with query...() functions for all information that we need from the
+ * user. The latter must not contain any interaction but just uses these values (which are
+ * temporarily stored by class ValueStorage) to perform the Action.
+ *
+ * Furthermore, there is a global action function that makes the action callable with already
+ * present parameters (i.e. without user interaction and for internal use within the code only).
+ * This function is basically just a macro, that puts the parameters into the ValueStorage and
+ * calls Action::call(Action::NonInteractive).
+ *
  * Actions can be set to be active or inactive. If an action is set to inactive it is signaling, that
  * some condition necessary for this action to be executed is not currently met. For example the
@@ -79 +89 @@
  * Building actions is fairly easy. Simply derive from the abstract Action base class and implement
  * the virtual methods. The main code that needs to be executed upon call() should be implemented in
- * the performCall() method. You should also indicate whether the action supports undo by implementing
+ * the performCall() method. Any user interaction should be placed into the dialog returned by
+ * createDialog(). You should also indicate whether the action supports undo by implementing
  * the shouldUndo() and canUndo() methods to return the appropriate flags.
+ *
+ * Also, create the global function to allow for easy calling of your function internally (i.e.
+ * without user interaction). It should have the name of the Action class without the suffix Action.
  *
  * The constructor of your derived class also needs to call the Base constructor, passing it the
@@ -123 +137 @@
  *  <li/> derive YourAction from Action
  *  <li/> pass name and flag for registry to the base constructor
- *  <li/> implement performCall(), performUndo(), performRedo()
+ *  <li/> implement createDialog(), performCall(), performUndo(), performRedo()
+ *  <li/> implement the global function call/macro.
  *  <li/> implement the functions that return the flags for the undo mechanism
  *  <li/> Derive YourActionState from ActionState as necessary
@@ -131 +146 @@
  *
  * <ul>
+ *  <li/> createDialog():
+ *  <ul>
+ *   <li/> Call makeDialog() from the UIFactory.
+ *   <li/> Call any needed Dialog->Query...() for the values you need with specific keywords.
+ *   <li/> if the action needs to save a state return a custom state object
+ *   <li/> otherwise return Action::success
+ *  </ul>
  *  <li/> performCall():
  *  <ul>
+ *   <li/> obtain parameters you need by ValueStorage::getCurrentValue, matching
+ *         key words from createDialog().
  *   <li/> do whatever is needed to make the action work
  *   <li/> if the action was abborted return Action::failure