Changeset 750cff for src/Actions

Timestamp:

Oct 31, 2011, 5:13:52 PM (13 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:

5982c5

Parents:

19bc74

Message:

HUGE: Update on documenation.

• a general skeleton of the documentation is now in place with all the major components of MoleCuilder explained to some extent.
• some information has been transfered from TRAC (e.g. install procecure) into this doxygen documentation where it is general and not specific to the situation at our institute.

File:

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

src/Actions/Action.hpp

@@ -31 +31 @@
 #include "Actions/ActionTraits.hpp"
 
-/**
- * @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.
- *
- * 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
- * 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 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.
- * 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
- * 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/> 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>
- *
- * <H4> Implementing performX() methods </H4>
- *
- * <ul>
- *  <li/> performCall():
- *  <ul>
- *   <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
- *   <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 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>
- *  <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 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>
- * </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
- * separate 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>
- *
- * <H3> Special kinds of Actions </H3>
- *
- * To make the usage of Actions more versatile there are two special kinds of actions defined,
- * that contain special mechanisms. These are defined inside the class Process, for actions that
- * take some time and indicate their own progress, and in the class Calculations for actions that
- * have a retrievable result.
- *
- * <H4> Processes </H4>
- *
- * Processes are Actions that might take some time and therefore contain special mechanisms
- * to indicate their progress to the user. If you want to implement a process you can follow the
- * guidelines for implementing actions. In addition to the normal Action constructor parameters,
- * you also need to define the number of steps the process takes to finish (use 0 if that number is
- * not known upon construction). At the beginning of your process you then simply call start() to
- * indicate that the process is taking up its work. You might also want to set the number of steps it
- * needs to finish, if it has changed since the last invocation/construction. You can use the
- * setMaxSteps() method for this. Then after each finished step of calulation simply call step(),
- * to let the indicators know that it should update itself. If the number of steps is not known
- * at the time of calculation, you should make sure the maxSteps field is set to 0, either through
- * the constructor or by using setMaxSteps(0). Indicators are required to handle both processes that
- * know the number of steps needed as well as processes that cannot predict when they will be finished.
- * Once your calculation is done call stop() to let every indicator know that the process is done with
- * the work and to let the user know.
- *
- * Indicators that want to know about processes need to implement the Observer class with all the
- * methods defined there. They can then globally sign on to all processes using the static
- * Process::AddObserver() method and remove themselves using the Process::RemoveObserver()
- * methods. When a process starts it will take care that the notification for this process
- * is invoked at the right time. Indicators should not try to observe a single process, but rather
- * be ready to observe the status of any kind of process using the methods described here.
- *
- * <H4> Calculations </H4>
- *
- * Calculations are special Actions that also return a result when called. Calculations are
- * always derived from Process, so that the progress of a calculation can be shown. Also
- * Calculations should not contain side-effects and not consider the undo mechanism.
- * When a Calculation is called using the Action mechanism this will cause it to calculate
- * the result and make it available using the getResult() method. Another way to have a Calculation
- * produce a result is by using the function-call operator. When this operator is used, the Calculation
- * will try to return a previously calculated and cached result and only do any actuall calculations
- * when no such result is available. You can delete the cached result using the reset() method.
- */