/* * 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 * */