Changeset 677e13 for src/Actions/Action.hpp

Timestamp:

Jul 28, 2010, 9:21:14 AM (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:

400170, a7b777c

Parents:

7067bd6 (diff), 0430e3 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.

Message:

Merge branch 'stable' into StructureRefactoring

Conflicts:

src/Makefile.am

File:

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

src/Actions/Action.hpp

@@ -16 +16 @@
 class ActionState;
 class ActionSequence;
+class Dialog;
 
 /**
@@ -44 +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
@@ -78 +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
@@ -122 +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
@@ -130 +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
@@ -256 +281 @@
 public:
 
+  enum QueryOptions {Interactive, NonInteractive};
+
   /**
    * This type is used to store pointers to ActionStates while allowing multiple ownership
@@ -278 +305 @@
    * If the call needs to undone you have to use the History, to avoid destroying
    * invariants used by the History.
-   */
-  void call();
+   *
+   * Note that this call can be Interactive (i.e. a dialog will ask the user for
+   * necessary information) and NonInteractive (i.e. the information will have to
+   * be present already within the ValueStorage class or else a MissingArgumentException
+   * is thrown)
+   */
+  void call(enum QueryOptions state = Interactive);
 
   /**
@@ -339 +371 @@
 private:
   /**
-   * This is called internally when the call is being done. Implement this method to do the actuall
+   * This creates the dialog requesting the information needed for this action from the user
+   * via means of the user interface.
+   */
+  virtual Dialog * createDialog()=0;
+
+  /**
+   * This is called internally when the call is being done. Implement this method to do the actual
    * work of the Action. Implement this in your Derived classes. Needs to return a state that can be
    * used to undo the action.