source: src/Actions/Action.hpp@ 6253ed

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
Last change on this file since 6253ed was 5ca6b5, checked in by Michael Ankele <ankele@…>, 12 years ago

drop deprecated references to ValueStorage

  • Property mode set to 100644
File size: 9.7 KB
Line 
1/*
2 * Action.hpp
3 *
4 * Created on: Dec 8, 2009
5 * Author: crueger
6 */
7
8#ifndef ACTION_HPP_
9#define ACTION_HPP_
10
11// include config.h
12#ifdef HAVE_CONFIG_H
13#include <config.h>
14#endif
15
16#include <string>
17#include <boost/shared_ptr.hpp>
18
19#include <boost/preprocessor/list/adt.hpp>
20
21/** Used in .def files in paramdefaults define to set that no default value exists.
22 * We define NOPARAM_DEFAULT here, as it is used in .def files and needs to be present
23 * before these are included.
24 */
25#define NOPARAM_DEFAULT BOOST_PP_NIL
26
27// forward declaration
28
29namespace MoleCuilder {
30 class ActionState;
31 class ActionSequence;
32}
33class Dialog;
34
35#include "Actions/ActionTrait.hpp"
36
37
38namespace MoleCuilder {
39
40/** Actions are Command patterns to allow for undoing and redoing.
41 *
42 * Each specific Action derives from this class to implement a certain functionality.
43 *
44 * Actions describe something that has to be done.
45 * Actions can be passed around, stored, performed and undone (Command-Pattern:
46 * http://en.wikipedia.org/wiki/Command_pattern).
47 *
48 * Unique to each Action is its ActionTrait, i.e. the options it requires
49 * to perform a certain function. E.g. in order to execute a "add atom" Action
50 * we need to know a position and an element. These options have certain
51 * properties, see \ref OptionTrait and \ref ActionTrait wherein these are stored.
52 * Essentially, each option is stored as an \ref OptionTrait instance and
53 * contains the token, default value, a description, the type, ...
54 *
55 * ActionTrait itself is also an OptionTrait because the command token may actually
56 * coincide with an option-token. E.g. this allows "...--add-atom 3" to mean
57 * both execute the action under token "add-atom" and that the option "add-atom"
58 * (the new atom's \ref element number) should contain 3.
59 *
60 * \ref ActionTrait contains a map of all associated options. With this in the cstor
61 * we register not only the Action with the \ref ActionRegistry but also each of
62 * its \link options OptionTrait \endlink with the \ref OptionRegistry.
63 *
64 * The token of the option is unique, but two Action's may share the same token if:
65 * -# they have the same default value
66 * -# they have the same type
67 *
68 * This requirement is easy because if you need to store some option of another
69 * type, simply think of a new suitable name for it.
70 *
71 * The actual value, i.e. "3" in the "add-atom" example, is taken from the
72 * ValueStorage, see \ref Dialog for how this is possible.
73 *
74 * \note There is a unit test that checks on the consistency of all registered
75 * options, also in "--enable-debug"-mode assertions will check that an option
76 * has not been registered before under another type.
77 *
78 */
79class Action
80{
81friend class ActionSequence;
82friend class ActionHistory;
83public:
84
85 enum QueryOptions {Interactive, NonInteractive};
86
87 /**
88 * This type is used to store pointers to ActionStates while allowing multiple ownership
89 */
90 typedef boost::shared_ptr<ActionState> state_ptr;
91
92 /**
93 * Standard constructor of Action Base class
94 *
95 * All Actions need to have a name. The second flag indicates, whether the action should
96 * be registered with the ActionRegistry. If the Action is registered the name of the
97 * Action needs to be unique for all Actions that are registered.
98 *
99 * \note NO reference for \a _Traits as we do have to copy it, otherwise _Traits would have
100 * to be present throughout the program's run.
101 *
102 * \param Traits information class to this action
103 * \param _doRegister whether to register with ActionRegistry
104 */
105 Action(const ActionTrait &_Traits, bool _doRegister=true);
106 virtual ~Action();
107
108 /**
109 * This method is used to call an action. The basic operations for the Action
110 * are carried out and if necessary/possible the Action is added to the History
111 * to allow for undo of this action.
112 *
113 * If the call needs to undone you have to use the History, to avoid destroying
114 * invariants used by the History.
115 *
116 * Note that this call can be Interactive (i.e. a dialog will ask the user for
117 * necessary information) and NonInteractive (i.e. the information will have to
118 * be present already within the ValueStorage class or else a MissingArgumentException
119 * is thrown)
120 */
121 void call(enum QueryOptions state = Interactive);
122
123 /**
124 * This method provides a flag that indicates if an undo mechanism is implemented
125 * for this Action. If this is true, and this action was called last, you can
126 * use the History to undo this action.
127 */
128 virtual bool canUndo()=0;
129
130 /**
131 * This method provides a flag, that indicates if the Action changes the state of
132 * the application in a way that needs to be undone for the History to work.
133 *
134 * If this is false the Action will not be added to the History upon calling. However
135 * Actions called before this one will still be available for undo.
136 */
137 virtual bool shouldUndo()=0;
138
139 /**
140 * Indicates whether the Action can do it's work at the moment. If this
141 * is false calling the action will result in a no-op.
142 */
143 virtual bool isActive();
144
145 /**
146 * Returns the name of the Action.
147 */
148 const std::string getName() const;
149
150 /**
151 * returns a detailed help message.
152 */
153 const std::string help() const;
154
155 /**
156 * Traits resemble all necessary information that "surrounds" an action, such as
157 * its name (for ActionRegistry and as ref from string to instance and vice versa),
158 * which menu, which position, what parameters, their types, if it is itself a
159 * parameter and so on ...
160 *
161 * Note that is important that we do not use a reference here. We want to copy the
162 * information in the Action's constructor and have it contained herein. Hence, we
163 * also have our own copy constructor for ActionTrait. Information should be
164 * encapsulated in the Action, no more references to the outside than absolutely
165 * necessary.
166 */
167 const ActionTrait Traits;
168
169protected:
170 /** Removes the static entities Action::success and Action::failure.
171 * This is only to be called on the program's exit, i.e. in cleanUp(),
172 * as these static entities are used throughout all Actions.
173 */
174 static void removeStaticStateEntities();
175
176 /** Creates the static entities Action::success and Action::failure.
177 * This is only to be called by ActionHistory.
178 */
179 static void createStaticStateEntities();
180
181 /**
182 * This method is called by the History, when an undo is performed. It is
183 * provided with the corresponding state produced by the performCall or
184 * performRedo method and needs to provide a state that can be used for redo.
185 */
186 state_ptr undo(state_ptr);
187
188 /**
189 * This method is called by the History, when a redo is performed. It is
190 * provided with the corresponding state produced by the undo method and
191 * needs to produce a State that can then be used for another undo.
192 */
193 state_ptr redo(state_ptr);
194
195 /**
196 * This special state can be used to indicate that the Action was successful
197 * without providing a special state. Use this if your Action does not need
198 * a specialized state.
199 */
200 static state_ptr success;
201
202 /**
203 * This special state can be returned, to indicate that the action could not do it's
204 * work, was aborted by the user etc. If you return this state make sure to transactionize
205 * your Actions and unroll the complete transaction before this is returned.
206 */
207 static state_ptr failure;
208
209 /**
210 * This creates the dialog requesting the information needed for this action from the user
211 * via means of the user interface.
212 */
213 Dialog * createDialog();
214
215 /** Virtual function that starts the timer.
216 *
217 */
218 virtual void startTimer() const {};
219
220 /** Virtual function that ends the timer.
221 *
222 */
223 virtual void endTimer() const {};
224
225private:
226
227 /**
228 * This is called internally before the action is processed. This adds necessary queries
229 * to a given dialog to obtain parameters for the user for processing the action accordingly.
230 * The dialog will be given to the user before Action::performCall() is initiated, values
231 * are transfered via ValueStorage.
232 */
233 virtual Dialog * fillDialog(Dialog*)=0;
234
235 /**
236 * This is called internally when the call is being done. Implement this method to do the actual
237 * work of the Action. Implement this in your Derived classes. Needs to return a state that can be
238 * used to undo the action.
239 */
240 virtual state_ptr performCall()=0;
241
242 /**
243 * This is called internally when the undo process is chosen. This Method should use the state
244 * produced by the performCall method to return the state of the application to the state
245 * it had before the Action.
246 */
247 virtual state_ptr performUndo(state_ptr)=0;
248
249 /**
250 * This is called internally when the redo process is chosen. This method shoudl use the state
251 * produced by the performUndo method to return the application to the state it should have after
252 * the action.
253 *
254 * Often this method can be implement to re-use the performCall method. However if user interaction
255 * or further parameters are needed, those should be taken from the state and not query the user
256 * again.
257 */
258 virtual state_ptr performRedo(state_ptr)=0;
259};
260
261/**
262 * This class can be used by actions to save the state.
263 *
264 * It is implementing a memento pattern. The base class is completely empty,
265 * since no general state internals can be given. The Action performing
266 * the Undo should downcast to the appropriate type.
267 */
268class ActionState{
269public:
270 ActionState(){}
271 virtual ~ActionState(){}
272};
273
274/**
275 * This class can be used by actions to contain parameters.
276 *
277 * The base class is completely empty, since no general parameters can be given. The
278 * Action performing the function should construct its own parameter class derived
279 * from it.
280 */
281class ActionParameters{
282public:
283 ActionParameters(){}
284 virtual ~ActionParameters(){}
285};
286
287}
288
289#endif /* ACTION_HPP_ */
Note: See TracBrowser for help on using the repository browser.