source: src/documentation/constructs/actions.dox@ 50d49d

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

/**
 * \file actions.dox
 *
 * Created on: Oct 28, 2011
 *    Author: heber
 */

/** \page actions Actions
 *
 *  \link MoleCuilder::Action Actions \endlink are Command patterns
 *  (http://en.wikipedia.org/wiki/Command_pattern)
 *  to allow for undoing and redoing. Each specific Action derives from this
 *  class to implement a certain functionality. There is a lot of preprocessor
 *  magic implemented for making this as easy as possible. In effect you only
 *  have to create three files of which only one actually contains more than a
 *  few lines, namely the code of the Action itself.
 *  Each Action also derives a specific ActionState and ActionParameters for
 *  containing the undo/redo state information and the parameters steering what
 *  the Action does.
 *
 *  Each Action has thus three types of functionality: do, undo, and redo. And
 *  each action has a unique \a token: a name without white space that is 
 *  descriptive.
 *
 *  The ActionRegistry contains a prototype of each Action under its token.
 *  If an Action is requested via its known token from the ActionQueue 
 *  (that contains the ActionRegistry), this prototype is cloned and added to the 
 *  queue. Action::clone() is a public function but only certain classes are
 *  allowed to directly add Action instances to the ActionQueue. Normally, an
 *  Action first has to be registered with the ActionRegistry and afterwards it
 *  may be added to the queue via its specific and unique token.
 *
 *  Each Action can contain multiple \ref parameters in its specific 
 *  ActionParameters structure that represent the options. Executing call() first 
 *  fills a dialog with \ref queries, one for each option. The UI then tries to 
 *  obtain the values from the user. Depending on the type of the UI in use that 
 *  could mean parsing stored command line parameters or displaying a real dialog 
 *  box with widgets.
 *
 *  Also there is a regression test (\ref regression-test) for each Action to
 *  check that it always behaves the same no matter how much the code
 *  implementing actually has changed. In most cases also for testing undo and
 *  redo.
 *
 * \section actions-add To add a new action ...
 *
 *  The following steps have to be done for adding a new action:
 *  -# Create three new files .cpp, .def, and .hpp
 *  -# Add the files to \b src/Actions/Makefile.am.
 *  -# Add the name of the Action to \b src/Actions/GlobalListOfActions.hpp
 *    such that the ActionRegistry knows about it and can instantiate a
 *    prototype.
 *
 *  Most of the magic that fills in the remaining gaps of the Action's
 *  declaration and definition is done by boost::preprocessor magic in the
 *  files Action_impl_pre.hpp and Action_impl_header.hpp. There is a pendant
 *  for MakroActions.
 *
 * \section actions-types Specific types of actions
 *
 *  There are some special types of Actions:
 *  -# Calculation: A process with a final result that can be requested
 *  -# MakroAction: A chain of other Actions to be executed various times
 *  -# MethodAction: An action that basically calls a certain bound method
 *  -# Process: An action that takes some time to complete and informs about
 *     how much work remains
 *
 * \section actions-types-add Add a specific types of action ...
 *
 *  Instantiating the MakroAction is simple, only two functions, prepare()
 *  and unprepare(), are required that fill und empty the chain of Actions
 *  from Actions from the ActionRegistry.
 *
 *  Adding a Process is much the same as adding a normal Action. There is a
 *  keyword BASECLASS in the associated \b .def file which should say Process
 *  and one needs to use Process::setCurrStep(int) to tell the Process and
 *  all listening Observers what the current stage of execution is. Also,
 *  initially a total number of steps must be stated via Process::setMaxSteps()
 *  When the job executes, this is initiated with Process::start() and when
 *  it stops, this is told via Process::stop().
 *
 *  A Calculation must be derived by hand and is not supported via the
 *  boost::preprocessor magic but behaves very similar to the Process itself
 *  with respect to informing about the current stage of execution. What's
 *  more is essentially the Calculation::doCalc() function that performs the
 *  actual calculation (must not changed the state of the World and hence
 *  there is not need for undo). The Calculation implementation takes care
 *  of the rest.
 *
 *  A MethodAction is simply implemented by filling an ActionTraits structure
 *  with the desired values and bind a method that should get executed.
 *  Instantating the MethodAction with these parameters and executing
 *  ActionRegistry()::registerAction() then allows for using it in the context
 *  of the ActionQueue.
 *
 * \section actions-undo-redo Undoing and Redoing actions ...
 *
 * The central points of Actions is that they can be undone and redone. This
 * has to be implemented in two more functions beside the "do" in performCall().
 *
 * Note that undoing means to get everything back to its original state and by whatever
 * means seem appropriate, e.g. remvoing all just inserted atoms.
 * To make this more elaborate it is usually very useful to store extra information
 * in the Action's state such that undo and redo can be accomplished more quickly.
 * E.g. if your Action creates some new atoms, store their info as \ref AtomicInfo.
 * Then, undo can simply delete the newly created atoms and redo can quickly re-
 * create them in the state they have been before. Types required for storage are
 * contained in the Action's state and are filled during performCall(). Undo and
 * redo both get access to this state and may use the information as described.
 *
 * Have a look at \ref UndoRedoHelpers.hpp for some helper functions on this.
 *
 * \section actions-further Further information
 *
 * If you want know:
 * -# how the code knows about the valid tokens for actions and options and how
 *    they are constructed, see \ref MoleCuilder::Action .
 *
 *
 *  \date 2015-08-03
 *
 */