Changeset 2efa90

Timestamp:

Apr 8, 2010, 2:00:11 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:

a295d1

Parents:

f9352d

Message:

Added detailed documentation for the Action class

Location:

src

Files:

• Actions/Action.cpp (modified) (1 diff)
• Actions/Action.hpp (modified) (2 diffs)
• Actions/ActionHistory.cpp (modified) (2 diffs)
• Actions/ActionSequence.cpp (modified) (1 diff)
• Actions/ActionSequence.hpp (modified) (2 diffs)
• Actions/MakroAction.cpp (modified) (1 diff)
• Actions/Process.cpp (modified) (1 diff)
• Actions/Process.hpp (modified) (1 diff)
• unittests/ActionSequenceTest.cpp (modified) (5 diffs)

src/Actions/Action.cpp

@@ -34 +34 @@
 
 void Action::call(){
+  if(!isActive()){
+    return;
+  }
   // forward to private virtual
   state_ptr state = performCall();

src/Actions/Action.hpp

@@ -18 +18 @@
 
 /**
+ * @file
+ * <H1> Action Howto </H1>
+ *
+ * <H2> Introduction </H2>
+ *
+ * Actions are used in object oriented design as a replacement for callback functions.
+ * In most ways Actions can be used in the same way that callbacks were used in non
+ * OO-Systems, but can contain support for several extra mechanism such as undo/redo
+ * or progress indicators.
+ *
+ * The main purpose of an action class is to contain small procedures, that can be repeatedly
+ * called. These procedures can also be stored, passed around, so that the execution of an
+ * action can happen quite far away from the place of creation. For a detailed description of
+ * the Action pattern see GOF:1996.
+ *
+ * <H3> How to use an action </H3>
+ *
+ * The process of using an action is as easy as calling the call() method of the action. The
+ * action will then do whatever it is supposed to do. If it is an action that can be undone, it
+ * will also register itself in the history to make itself available for undo. To undo the last
+ * action, you can either use the undoLast() method inside the ActionHistory class or call the
+ * UndoAction also provided by the ActionHistory. If an action was undone it will be available for
+ * redo, using the redoLast() method of the ActionHistory or the RedoAction also provided by this
+ * class. To check whether undo/redo is available at any moment you can use the hasUndo() or
+ * hasRedo() method respectively.
+ *
+ * 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
+ * UndoAction will set itself to inactive, when there is no action at that time that can be undone.
+ * Using call() on an inactive Action results in a no-op. You can query the state of an action using
+ * the isActive() method.
+ *
+ * The undo capabilities of actions come in three types as signaled by two boolean flags (one
+ * combination of these flags is left empty as can be seen later).
+ * <ul>
+ * <li/> The first flag indicates if the undo mechanism for this action should be considered at all, i.e.
+ *   if the state of the application changes in a way that needs to be reverted. Actions that should
+ *   consider the undo mechanism are for example adding a molecule, moving atoms, changing
+ *   the name of a molecule etc. Changing the View-Area on the other hand should be an action that
+ *   does not consider the undo mechanism. This flag can be queried using the shouldUndo() method.
+ *
+ * <li/> The second flag indicates whether the changes can be undo for this action. If this flag is true
+ *   the action will be made available for undo using the ActionHistory class and the actions of this
+ *   class. If this flag is false while the shoudlUndo() flag is true this means that this action
+ *   changes the state of the application changes in a way that cannot be undone, but might cause
+ *   the undo of previous actions to fail. In this case the whole History is cleared, as to keep
+ *   the state of the application intact by avoiding dangerous undos. This flag can be queried
+ *   using the canUndo() method.
+ *</ul>
+ *
+ * Each action has a name, that can be used to identify it throughout the run of the application.
+ * This name can be retrieved using the getName() method. Most actions also register themselves with
+ * a global structure, called the ActionRegistry. Actions that register themselves need to have a
+ * unique name for the whole application. If the name is known these actions can be retrieved from
+ * the registry by their name and then be used as normal.
+ *
+ * <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. You should also indicate whether the action supports undo by implementing
+ * the shouldUndo() and canUndo() methods to return the appropriate flags.
+ *
+ * The constructor of your derived class also needs to call the Base constructor, passing it the
+ * name of the Action and a flag indicating whether this action should be made available in the
+ * registry. WARNING: Do not use the virtual getName() method of the derived action to provide the
+ * constructor with the name, even if you overloaded this method to return a constant. Doing this
+ * will most likely not do what you think it does (see: http://www.parashift.com/c++-faq-lite/strange-inheritance.html#faq-23.5
+ * if you want to know why this wont work)
+ *
+ * <H3> Interfacing your Action with the Undo mechanism </H3>
+ *
+ * The performX() methods need to comply to a simple standard to allow for undo and redo. The first
+ * convention in this standard concerns the return type. All methods that handle calling, undoing
+ * or redoing return an object of Action::state_ptr. This is a smart pointer to a State object, that
+ * can be used to store state information that is needed by your action for later redo. A rename
+ * Action for example would need to store which object has been renamed and what the old name was.
+ * A move Action on the other hand would need to store the object that has been moved as well as the
+ * old position. If your Action does not need to store any kind of information for redo you can
+ * simply return Action::success and skip the rest of this paragraph. If your action has been
+ * abborted you can return Action::failure, which indicates to the history mechanism that this
+ * action should not be stored.
+ *
+ * If your Action needs any kind of information to undo its execution, you need to store this
+ * information in the state that is returned by the performCall() method. Since no assumptions
+ * can be made on the type or amount of information the ActionState base class is left empty.
+ * To use this class you need to derive a YourActionState class from the ActionState base class
+ * adding your data fields and accessor functions. Upon undo the ActionState object produced
+ * by the corresponding performCall() is then passed to the performUndo() method which should
+ * typecast the ActionState to the appropriate sub class, undo all the changes and produce
+ * a State object that can be used to redo the action if neccessary. This new state object is
+ * then used if the redo mechanism is invoked and passed to the performRedo() function, which
+ * again produces a State that can be used for performUndo().
+ *
+ * <H3> Outline of the implementation of Actions </H3>
+ *
+ * To sum up the actions necessary to build actions here is a brief outline of things methioned
+ * in the last paragraphs:
+ *
+ * <H4> Basics </H4>
+ *
+ * <ul>
+ *  <li/> derive YourAction from Action
+ *  <li/> pass name and flag for registry to the base constructor
+ *  <li/> implement performCall(), performUndo(), performRedo()
+ *  <li/> implement the functions that return the flags for the undo mechanism
+ *  <li/> Derive YourActionState from ActionState as necessary
+ * </ul>
+ *
+ * <H4> Implementing performX() methods </H4>
+ *
+ * <ul>
+ *  <li/> performCall():
+ *  <ul>
+ *   <li/> do whatever is needed to make the action work
+ *   <li/> if the action was abborted return Action::failure
+ *   <li/> if the action needs to save a state return a custom state object
+ *   <li/> otherwise return Action::success
+ *  </ul>
+ *  <li/> performUndo():
+ *  <ul>
+ *   <li/> typecast the ActionState pointer to a Pointer to YourActionState if necessary
+ *   <li/> undo the action using the information from the state
+ *   <li/> produce a new state that can be used for redoing and return it
+ *  </ul>
+ *  <li/> performRedo():
+ *  <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/> produce a new state that can be used by performUndo() and return it
+ *  </ul>
+ * </ul>
+ *
+ * <H2> Advanced techniques </H2>
+ *
+ * <H3> Predefined Actions </H3>
+ *
+ * To make construction of actions easy there are some predefined actions. Namely these are
+ * the MethodAction and the ErrorAction.
+ *
+ * The method action can be used to turn any function with empty arguments and return type void
+ * into an action (also works for functors with those types). Simply pass the constructor for the
+ * MethodAction a name to use for this action, the function to call inside the performCall()
+ * method and a flag indicating if this action should be made retrievable inside the registry
+ * (default is true). MethodActions always report themselves as changing the state of the
+ * application but cannot be undone. i.e. calling MethodActions will always cause the ActionHistory
+ * to be cleared.
+ *
+ * ErrorActions can be used to produce a short message using the Log() << Verbose() mechanism of
+ * the molecuilder. Simply pass the constructor a name for the action, the message to show upon
+ * calling this action and the flag for the registry (default is again true). Error action
+ * report that they do not change the state of the application and are therefore not considered
+ * for undo.
+ *
+ * <H3> Sequences of Actions and MakroActions </H3>
+ *
+ * <H4> Building sequences of Actions </H4>
+ *
+ * Actions can be chained to sequences using the ActionSequence class. Once an ActionSequence is
+ * constructed it will be initially empty. Any Actions can then be added to the sequence using the
+ * addAction() method of the ActionSequence class. The last added action can be removed using the
+ * removeLastAction() method. If the construction of the sequence is done, you can use the
+ * callAll() method. Each action called this way will register itself with the History to allow
+ * seperate undo of all actions in the sequence.
+ *
+ * <H4> Building larger Actions from simple ones </H4>
+ *
+ * Using the pre-defined class MakroAction it is possible to construct bigger actions from a sequence
+ * of smaller ones. For this you first have to build a sequence of the actions using the ActionSequence
+ * as described above. Then you can construct a MakroAction passing it a name, the sequence to use
+ * and as usual a flag for the registry. You can then simply call the complete action-sequence through
+ * this makro action using the normal interface. Other than with the direct use of the action sequence
+ * only the complete MakroAction is registered inside the history, i.e. the complete sequence can be
+ * undone at once. Also there are a few caveats you have to take care of when using the MakroAction:
+ * <ul>
+ *  <li/> All Actions as well as the sequence should exclusively belong to the MakroAction. This
+ *        especially means, that the destruction of these objects should be handled by the MakroAction.
+ *  <li/> none of the Actions inside the MakroAction should be registered with the registry, since the
+ *        registry also assumes sole ownership of the actions.
+ *  <li/> Do not remove or add actions from the sequence once the MakroAction has been constructed, since this
+ *        might brake important assumptions for the undo/redo mechanism
+ * </ul>
+ */
+
+/**
  * Base class for all actions.
  *
  * Actions describe something that has to be done.
  * Actions can be passed around, stored, performed and undone (Command-Pattern).
- *
- * TODO: Add queues of actions that have been performed to allow easy implementation of multiple-step undo
  */
 class Action
 {
 friend class ActionSequence;
+friend class ActionHistory;
 public:
 
@@ -38 +222 @@
   // actuall action is passed on to a private virtual
   void call();
+
+  virtual bool canUndo()=0;
+  virtual bool shouldUndo()=0;
+
+  virtual bool isActive();
+
+  virtual const std::string getName();
+
+protected:
   state_ptr undo(state_ptr);
   state_ptr redo(state_ptr);
 
-  virtual bool canUndo()=0;
-  virtual bool shouldUndo()=0;
-
-  virtual bool isActive();
-
-  virtual const std::string getName();
-
-protected:
   static state_ptr success;
   static state_ptr failure;

src/Actions/ActionHistory.cpp

@@ -45 +45 @@
 
 void ActionHistory::addElement(Action* action,Action::state_ptr state){
-  cout << "Adding action to end of history" << endl;
   yrotsih.clear();
   history.push_back(HistoryElement(action,state));
@@ -51 +50 @@
 
 void ActionHistory::clear(){
-  cout << "History cleared" << endl;
   history.clear();
   yrotsih.clear();

src/Actions/ActionSequence.cpp

@@ -36 +36 @@
 }
 
-ActionSequence::stateSet ActionSequence::callAll(){
+// this method is used outside the ActionModule
+// Each action registers itself with the history
+void ActionSequence::callAll(){
+  for(actionSet::iterator it=actions.begin(); it!=actions.end(); it++){
+    // we want to have a global bookkeeping for all actions in the sequence, so
+    // we bypass the normal call
+    (*it)->call();
+  }
+}
+
+// This method is used internally when MakroActions are constructed.
+// In this case only the makro Action should be registered and
+// handle the states
+ActionSequence::stateSet ActionSequence::callAll(bool){
   stateSet states;
   for(actionSet::iterator it=actions.begin(); it!=actions.end(); it++){

src/Actions/ActionSequence.hpp

@@ -18 +18 @@
 class ActionSequence
 {
+  friend class MakroAction;
 public:
   typedef std::deque<Action*> actionSet;
@@ -28 +29 @@
   Action* removeLastAction();
 
-  stateSet callAll();
-  stateSet undoAll(stateSet);
-  stateSet redoAll(stateSet);
+  void callAll();
 
   bool canUndo();
   bool shouldUndo();
 
+protected:
+  stateSet callAll(bool); // Dummy parameter to allow overloading
+  stateSet undoAll(stateSet);
+  stateSet redoAll(stateSet);
 private:
   actionSet actions;

src/Actions/MakroAction.cpp

@@ -44 +44 @@
 
 Action::state_ptr MakroAction::performCall(){
-  ActionSequence::stateSet states = actions->callAll();
+  ActionSequence::stateSet states = actions->callAll(true);
   return Action::state_ptr(new MakroActionState(states));
 }

src/Actions/Process.cpp

@@ -25 +25 @@
 
 
-bool Process::isActive(){
+bool Process::isRunning(){
   return active;
 }

src/Actions/Process.hpp

@@ -43 +43 @@
   virtual ~Process();
 
-  bool  isActive();
+  bool  isRunning();
   bool  doesStart();
   bool  doesStop();

src/unittests/ActionSequenceTest.cpp

@@ -13 +13 @@
 #include "Actions/Action.hpp"
 #include "Actions/ActionSequence.hpp"
+#include "Actions/MakroAction.hpp"
+#include "Actions/ActionHistory.hpp"
+#include "Actions/ActionRegistry.hpp"
 
 #ifdef HAVE_TESTRUNNER
@@ -22 +25 @@
 // Registers the fixture into the 'registry'
 CPPUNIT_TEST_SUITE_REGISTRATION( ActionSequenceTest );
-
-void setUp();
-void tearDown();
-
-void canUndoTest();
 
 /* some neccessary stubs for tests */
@@ -110 +108 @@
 
 void ActionSequenceTest::setUp(){
+  ActionHistory::init();
   // create some necessary stubs used in this test
   positive1 = new canUndoActionStub();
@@ -134 +133 @@
   delete shouldNotCall2;
 
+  ActionHistory::purgeInstance();
+  ActionRegistry::purgeInstance();
 }
 
@@ -209 +210 @@
 void ActionSequenceTest::doesUndoTest(){
   ActionSequence *sequence = new ActionSequence();
-  sequence->addAction(shouldNotCall1);
-  sequence->addAction(shouldNotCall2);
-  sequence->addAction(shouldCall1);
-  sequence->addAction(shouldCall2);
-
-  ActionSequence::stateSet states = sequence->callAll();
-
-  sequence->removeLastAction();
-  sequence->removeLastAction();
-
-  sequence->undoAll(states);
-
-  CPPUNIT_ASSERT_EQUAL(true,shouldCall1->wasCalled());
-  CPPUNIT_ASSERT_EQUAL(true,shouldCall2->wasCalled());
-  CPPUNIT_ASSERT_EQUAL(false,shouldNotCall1->wasCalled());
-  CPPUNIT_ASSERT_EQUAL(false,shouldNotCall2->wasCalled());
-
-  delete sequence;
-}
-
-
+  wasCalledActionStub *wasCalled1 = new wasCalledActionStub();
+  wasCalledActionStub *wasCalled2 = new wasCalledActionStub();
+  sequence->addAction(wasCalled1);
+  sequence->addAction(wasCalled2);
+
+  MakroAction act("Test MakroAction",sequence,false);
+
+  act.call();
+
+  CPPUNIT_ASSERT_EQUAL(true,wasCalled1->wasCalled());
+  CPPUNIT_ASSERT_EQUAL(true,wasCalled1->wasCalled());
+
+  ActionHistory::getInstance().undoLast();
+
+  CPPUNIT_ASSERT_EQUAL(false,wasCalled1->wasCalled());
+  CPPUNIT_ASSERT_EQUAL(false,wasCalled1->wasCalled());
+
+}
+
+