source: src/documentation/constructs/actions.dox@ f84992

/*
 * 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 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 has thus three types of functionalty: do, undo, and redo.
 *
 *  The ActionRegistry contains a prototype of each Action under its token
 *  such that an instance can be retrieved by knowing this token.
 *
 *  Each Action obtains its options from a central ValueStorage such that
 *  they are independent of where the option originated from: a command line
 *  parameter, a value entered in a graphical dialog or given via the keyboard
 *  in a terminal. That's why each begins with a function call to
 *  getParametersfromValueStorage() to fill its internal Action::params
 *  structure.
 *
 *  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.
 *
 * \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.
 *
 * \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".
 *
 * Note that undoing means to get every back to its original state and by whatever
 * means seem appropriate, e.g. just remvoing all 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.
 *
 * 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 2012-04-05
 *
 */