source: src/documentation/howtos/action.dox@ b5f548

/*
 * Project: MoleCuilder
 * Description: creates and alters molecular systems
 * Copyright (C)  2010 University of Bonn. All rights reserved.
 * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
 */

/**
 * \file action.dox
 *
 * Created on: Oct 31, 2011
 *    Author: heber
 */

/**
 * \page howto-action Action Howto
 *
 * \section howto-action-introduction Introduction
 *
 * 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.
 *
 * \subsection howto-action-usage How to use an action
 *
 * 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).
 * \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.
 *
 * 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.
 *
 * \section howto-action-add Building your own actions
 *
 * 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.
 *
 * \subsection howto-action-add-notes Specific notes on the macros
 *
 * 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)
 *
 * \subsection howto-action-add-undo Interfacing your Action with the Undo mechanism
 *
 * 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().
 *
 * \section howto-action-implementation Outline of the implementation of Actions
 *
 * To sum up the actions necessary to build actions here is a brief outline of things methioned
 * in the last paragraphs:
 *
 * \subsection howto-action-implementation-notes Specific notes on the macros
 *
 *  \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.
 *
 * \subsection howto-action-implementation-perform-x Implementing performX() methods
 *
 *  \li performCall():
 *   -# first line should be calling of getParametersfromValueStorage().
 *   -# Access your parameters by the structure params.### (where ### stands for the reference/
 *         variable name chosen in the tupel).
 *   -# do whatever is needed to make the action work
 *   -# if the action was abborted return Action::failure
 *   -# if the action needs to save a state return a custom state object
 *   -# otherwise return Action::success
 *  \li performUndo():
 *   -# typecast the ActionState pointer to a Pointer to YourActionState if necessary
 *   -# undo the action using the extra information and the Action's parameters in the state
 *   -# produce a new state that can be used for redoing and return it
 *  \li performRedo():
 *   -# take the ActionState produced by performUndo and typecast it to a pointer to YourActionState if necessary
 *   -# redo the undone action using the extra information and the Action's parameters in the state
 *   -# produce a new state that can be used by performUndo() and return it
 *
 * \section howto-action-advanced Advanced techniques
 *
 * \subsection howto-action-advanced-predefined Predefined Actions
 *
 * 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.
 *
 * \subsection howto-action-advanced-sequences Sequences of Actions and MakroActions
 *
 * \paragraph howto-action-advanced-sequences-add Building sequences of Actions
 *
 * 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.
 *
 * \paragraph howto-action-advanced-sequences-build-larger Building larger Actions from simple ones
 *
 * 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:
 *  -# 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.
 *  -# none of the Actions inside the MakroAction should be registered with the registry, since the
 *        registry also assumes sole ownership of the actions.
 *  -# 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
 *
 * \section howto-action-special Special kinds of Actions
 *
 * 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.
 *
 * \subsection howto-action-special-process Processes
 *
 * 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.
 *
 * \subsection howto-action-special-calculation Calculations
 *
 * 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.
 *
 *
 * \date 2011-10-31
 */