Changeset 10fa1d for src/Actions

Timestamp:

Aug 28, 2010, 12:57:56 AM (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:

c66537

Parents:

966e12

git-author:

Frederik Heber <heber@…> (08/26/10 21:36:28)

git-committer:

Frederik Heber <heber@…> (08/28/10 00:57:56)

Message:

DOCU: Updated Action Howto to contain the new macro framework.

File:

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

src/Actions/Action.hpp

@@ -87 +87 @@
  * <H2> Building your own actions </H2>
  *
- * 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. 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.
+ * Building actions is easy. Each specific ...Action is derived from the base class Action.
+ * In order to create all the reoccuring stuff, macros have been created which you can simply
+ * include and then don't need to worry about it.
+ * There are three major virtual functions: performCall(), performUndo(), performRedo() which
+ * you have to write, to equip your action with some actual capabilities.
+ * Each Action definition and implementation consists of of three files:
+ * -# cpp: contains performX() which you have to write, also some boilerplate functions which are
+ *         constructed automatically when including your def and "Actions/action_impl_pre.hpp"
+ * -# hpp: boilerplate definitions created simply by including your def and
+ *         "Actions/action_impl_header.hpp"
+ * -# def: macro definitions of all your parameters and additional variables needed for the state,
+ *         also name and category and token of your action.
+ *
+ * Best thing to do is look at one of the already present triples and you should soon understand
+ * what you have to add:
+ * -# pick the right category, i.e. the right folder in src/Actions
+ * -# pick the right name
+ * -# decide which parameters your actions need and what the type, the variable name and the token
+ *    to reference it from the command-line should be. Check whether already present and fitting
+ *    tokens exists, e.g. "position" as token for a Vector representing a position.
+ * -# consider which additional information you need to undo your action
+ * -# don't forget to include your .def file followed by "action_impl_pre.hpp" in .cpp or
+ *    "action_impl_header.hpp" in the .hpp
+ * -# continue to write the functionality of your action in performCall(), undo and redo in performUndo()
+ *    and performRedo().
+ * -# You should indicate whether the action supports undo by implementing the shouldUndo() and
+ *    canUndo() methods to return the appropriate flags.
+ *
+ * <H3> Specific notes on the macros </H3>
+ *
+ * The following functions are created by the macros, i.e. you don't need to worry about it:
+ *
+ * Any user interaction should be placed into the dialog returned by fillDialog().
  *
  * Also, create the global function to allow for easy calling of your function internally (i.e.
@@ -135 +163 @@
  *
  * <ul>
- *  <li/> derive YourAction from Action
- *  <li/> pass name and flag for registry to the base constructor
- *  <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
+ *  <li/> create parameter tupels (type, token, reference), put into def. Access them later in
+ *        the performX() via the structure params.###.
+ *  <li/> think of name, category and token for your action, put into def
+ *  <li/> create additional state variables tupels (type, reference) for storing extra information
+ *        that you need for undo/redo in the ActionState. You can always access the parameters
+ *        of your Action by state.params.### (i.e. they are copied to the state by default).
+ *  <li/> implement performCall(), first line should be calling of getParametersfromValueStorage().
+ *  <li/> performUndo(), performRedo()
+ *  <li/> implement the functions that return the flags for the undo mechanism, i.e. true/false.
  * </ul>
  *
@@ -146 +177 @@
  *
  * <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/> first line should be calling of getParametersfromValueStorage().
+ *   <li/> Access your parameters by the structure params.### (where ### stands for the reference/
+ *         variable name chosen in the tupel).
  *   <li/> do whatever is needed to make the action work
  *   <li/> if the action was abborted return Action::failure
@@ -165 +190 @@
  *  <ul>
  *   <li/> typecast the ActionState pointer to a Pointer to YourActionState if necessary
- *   <li/> undo the action using the information from the state
+ *   <li/> undo the action using the extra information and the Action's parameters in the state
  *   <li/> produce a new state that can be used for redoing and return it
  *  </ul>
@@ -171 +196 @@
  *  <ul>
  *   <li/> take the ActionState produced by performUndo and typecast it to a pointer to YourActionState if necessary
- *   <li/> redo the undone action using the information from the state
+ *   <li/> redo the undone action using the extra information and the Action's parameters in the state
  *   <li/> produce a new state that can be used by performUndo() and return it
  *  </ul>