Changeset 8a34392 for src/Actions

Timestamp:

Apr 15, 2010, 1:17:15 PM (15 years ago)

Author:

Tillmann Crueger <crueger@…>

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:

ccacba

Parents:

a295d1

Message:

Improved documentation for the Action pattern

File:

• src/Actions/Action.hpp (modified) (1 diff)

src/Actions/Action.hpp

@@ -256 +256 @@
 public:
 
+  /**
+   * This type is used to store pointers to ActionStates while allowing multiple ownership
+   */
   typedef boost::shared_ptr<ActionState> state_ptr;
 
+  /**
+   * Standard constructor of Action Base class
+   *
+   * All Actions need to have a name. The second flag indicates, whether the action should
+   * be registered with the ActionRegistry. If the Action is registered the name of the
+   * Action needs to be unique for all Actions that are registered.
+   */
   Action(std::string _name,bool _doRegister=true);
   virtual ~Action();
 
-  // this method only handles the infrastructure
-  // actuall action is passed on to a private virtual
+  /**
+   * This method is used to call an action. The basic operations for the Action
+   * are carried out and if necessary/possible the Action is added to the History
+   * to allow for undo of this action.
+   *
+   * If the call needs to undone you have to use the History, to avoid destroying
+   * invariants used by the History.
+   */
   void call();
 
+  /**
+   * This method provides a flag that indicates if an undo mechanism is implemented
+   * for this Action. If this is true, and this action was called last, you can
+   * use the History to undo this action.
+   */
   virtual bool canUndo()=0;
+
+  /**
+   * This method provides a flag, that indicates if the Action changes the state of
+   * the application in a way that needs to be undone for the History to work.
+   *
+   * If this is false the Action will not be added to the History upon calling. However
+   * Actions called before this one will still be available for undo.
+   */
   virtual bool shouldUndo()=0;
 
+  /**
+   * Indicates whether the Action can do it's work at the moment. If this
+   * is false calling the action will result in a no-op.
+   */
   virtual bool isActive();
 
+  /**
+   * Returns the name of the Action.
+   */
   virtual const std::string getName();
 
 protected:
+  /**
+   * This method is called by the History, when an undo is performed. It is
+   * provided with the corresponding state produced by the performCall or
+   * performRedo method and needs to provide a state that can be used for redo.
+   */
   state_ptr undo(state_ptr);
+
+  /**
+   * This method is called by the Histor, when a redo is performed. It is
+   * provided with the corresponding state produced by the undo method and
+   * needs to produce a State that can then be used for another undo.
+   */
   state_ptr redo(state_ptr);
 
+  /**
+   * This special state can be used to indicate that the Action was successfull
+   * without providing a special state. Use this if your Action does not need
+   * a speciallized state.
+   */
   static state_ptr success;
+
+  /**
+   * This special state can be returned, to indicate that the action could not do it's
+   * work, was abborted by the user etc. If you return this state make sure to transactionize
+   * your Actions and unroll the complete transaction before this is returned.
+   */
   static state_ptr failure;
 
 private:
+  /**
+   * This is called internally when the call is being done. Implement this method to do the actuall
+   * work of the Action. Implement this in your Derived classes. Needs to return a state that can be
+   * used to undo the action.
+   */
   virtual state_ptr performCall()=0;
+
+  /**
+   * This is called internally when the undo process is chosen. This Method should use the state
+   * produced by the performCall method to return the state of the application to the state
+   * it had before the Action.
+   */
   virtual state_ptr performUndo(state_ptr)=0;
+
+  /**
+   * This is called internally when the redo process is chosen. This method shoudl use the state
+   * produced by the performUndo method to return the application to the state it should have after
+   * the action.
+   *
+   * Often this method can be implement to re-use the performCall method. However if user interaction
+   * or further parameters are needed, those should be taken from the state and not query the user
+   * again.
+   */
   virtual state_ptr performRedo(state_ptr)=0;