| 1 | /*
|
|---|
| 2 | * Project: MoleCuilder
|
|---|
| 3 | * Description: creates and alters molecular systems
|
|---|
| 4 | * Copyright (C) 2010 University of Bonn. All rights reserved.
|
|---|
| 5 | * Copyright (C) 2014 Frederik Heber. All rights reserved.
|
|---|
| 6 | * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
|
|---|
| 7 | */
|
|---|
| 8 |
|
|---|
| 9 | /**
|
|---|
| 10 | * \file actions.dox
|
|---|
| 11 | *
|
|---|
| 12 | * Created on: Oct 28, 2011
|
|---|
| 13 | * Author: heber
|
|---|
| 14 | */
|
|---|
| 15 |
|
|---|
| 16 | /** \page actions Actions
|
|---|
| 17 | *
|
|---|
| 18 | * \link MoleCuilder::Action Actions \endlink are Command patterns
|
|---|
| 19 | * (http://en.wikipedia.org/wiki/Command_pattern)
|
|---|
| 20 | * to allow for undoing and redoing. Each specific Action derives from this
|
|---|
| 21 | * class to implement a certain functionality. There is a lot of preprocessor
|
|---|
| 22 | * magic implemented for making this as easy as possible. In effect you only
|
|---|
| 23 | * have to create three files of which only one actually contains more than a
|
|---|
| 24 | * few lines, namely the code of the Action itself.
|
|---|
| 25 | * Each Action also derives a specific ActionState and ActionParameters for
|
|---|
| 26 | * containing the undo/redo state information and the parameters steering what
|
|---|
| 27 | * the Action does.
|
|---|
| 28 | *
|
|---|
| 29 | * Each Action has thus three types of functionality: do, undo, and redo. And
|
|---|
| 30 | * each action has a unique \a token: a name without white space that is
|
|---|
| 31 | * descriptive.
|
|---|
| 32 | *
|
|---|
| 33 | * The ActionRegistry contains a prototype of each Action under its token.
|
|---|
| 34 | * If an Action is requested via its known token from the ActionQueue
|
|---|
| 35 | * (that contains the ActionRegistry), this prototype is cloned and added to the
|
|---|
| 36 | * queue. Action::clone() is a public function but only certain classes are
|
|---|
| 37 | * allowed to directly add Action instances to the ActionQueue. Normally, an
|
|---|
| 38 | * Action first has to be registered with the ActionRegistry and afterwards it
|
|---|
| 39 | * may be added to the queue via its specific and unique token.
|
|---|
| 40 | *
|
|---|
| 41 | * Each Action can contain multiple \ref parameters in its specific
|
|---|
| 42 | * ActionParameters structure that represent the options. Executing call() first
|
|---|
| 43 | * fills a dialog with \ref queries, one for each option. The UI then tries to
|
|---|
| 44 | * obtain the values from the user. Depending on the type of the UI in use that
|
|---|
| 45 | * could mean parsing stored command line parameters or displaying a real dialog
|
|---|
| 46 | * box with widgets.
|
|---|
| 47 | *
|
|---|
| 48 | * Also there is a regression test (\ref regression-test) for each Action to
|
|---|
| 49 | * check that it always behaves the same no matter how much the code
|
|---|
| 50 | * implementing actually has changed. In most cases also for testing undo and
|
|---|
| 51 | * redo.
|
|---|
| 52 | *
|
|---|
| 53 | * \section actions-add To add a new action ...
|
|---|
| 54 | *
|
|---|
| 55 | * The following steps have to be done for adding a new action:
|
|---|
| 56 | * -# Create three new files .cpp, .def, and .hpp
|
|---|
| 57 | * -# Add the files to \b src/Actions/Makefile.am.
|
|---|
| 58 | * -# Add the name of the Action to \b src/Actions/GlobalListOfActions.hpp
|
|---|
| 59 | * such that the ActionRegistry knows about it and can instantiate a
|
|---|
| 60 | * prototype.
|
|---|
| 61 | *
|
|---|
| 62 | * Most of the magic that fills in the remaining gaps of the Action's
|
|---|
| 63 | * declaration and definition is done by boost::preprocessor magic in the
|
|---|
| 64 | * files Action_impl_pre.hpp and Action_impl_header.hpp. There is a pendant
|
|---|
| 65 | * for MakroActions.
|
|---|
| 66 | *
|
|---|
| 67 | * \section actions-types Specific types of actions
|
|---|
| 68 | *
|
|---|
| 69 | * There are some special types of Actions:
|
|---|
| 70 | * -# Calculation: A process with a final result that can be requested
|
|---|
| 71 | * -# MakroAction: A chain of other Actions to be executed various times
|
|---|
| 72 | * -# MethodAction: An action that basically calls a certain bound method
|
|---|
| 73 | * -# Process: An action that takes some time to complete and informs about
|
|---|
| 74 | * how much work remains
|
|---|
| 75 | *
|
|---|
| 76 | * \section actions-types-add Add a specific types of action ...
|
|---|
| 77 | *
|
|---|
| 78 | * Instantiating the MakroAction is simple, only two functions, prepare()
|
|---|
| 79 | * and unprepare(), are required that fill und empty the chain of Actions
|
|---|
| 80 | * from Actions from the ActionRegistry.
|
|---|
| 81 | *
|
|---|
| 82 | * Adding a Process is much the same as adding a normal Action. There is a
|
|---|
| 83 | * keyword BASECLASS in the associated \b .def file which should say Process
|
|---|
| 84 | * and one needs to use Process::setCurrStep(int) to tell the Process and
|
|---|
| 85 | * all listening Observers what the current stage of execution is. Also,
|
|---|
| 86 | * initially a total number of steps must be stated via Process::setMaxSteps()
|
|---|
| 87 | * When the job executes, this is initiated with Process::start() and when
|
|---|
| 88 | * it stops, this is told via Process::stop().
|
|---|
| 89 | *
|
|---|
| 90 | * A Calculation must be derived by hand and is not supported via the
|
|---|
| 91 | * boost::preprocessor magic but behaves very similar to the Process itself
|
|---|
| 92 | * with respect to informing about the current stage of execution. What's
|
|---|
| 93 | * more is essentially the Calculation::doCalc() function that performs the
|
|---|
| 94 | * actual calculation (must not changed the state of the World and hence
|
|---|
| 95 | * there is not need for undo). The Calculation implementation takes care
|
|---|
| 96 | * of the rest.
|
|---|
| 97 | *
|
|---|
| 98 | * A MethodAction is simply implemented by filling an ActionTraits structure
|
|---|
| 99 | * with the desired values and bind a method that should get executed.
|
|---|
| 100 | * Instantating the MethodAction with these parameters and executing
|
|---|
| 101 | * ActionRegistry()::registerAction() then allows for using it in the context
|
|---|
| 102 | * of the ActionQueue.
|
|---|
| 103 | *
|
|---|
| 104 | * \section actions-undo-redo Undoing and Redoing actions ...
|
|---|
| 105 | *
|
|---|
| 106 | * The central points of Actions is that they can be undone and redone. This
|
|---|
| 107 | * has to be implemented in two more functions beside the "do" in performCall().
|
|---|
| 108 | *
|
|---|
| 109 | * Note that undoing means to get everything back to its original state and by whatever
|
|---|
| 110 | * means seem appropriate, e.g. remvoing all just inserted atoms.
|
|---|
| 111 | * To make this more elaborate it is usually very useful to store extra information
|
|---|
| 112 | * in the Action's state such that undo and redo can be accomplished more quickly.
|
|---|
| 113 | * E.g. if your Action creates some new atoms, store their info as \ref AtomicInfo.
|
|---|
| 114 | * Then, undo can simply delete the newly created atoms and redo can quickly re-
|
|---|
| 115 | * create them in the state they have been before. Types required for storage are
|
|---|
| 116 | * contained in the Action's state and are filled during performCall(). Undo and
|
|---|
| 117 | * redo both get access to this state and may use the information as described.
|
|---|
| 118 | *
|
|---|
| 119 | * Have a look at \ref UndoRedoHelpers.hpp for some helper functions on this.
|
|---|
| 120 | *
|
|---|
| 121 | * \section actions-further Further information
|
|---|
| 122 | *
|
|---|
| 123 | * If you want know:
|
|---|
| 124 | * -# how the code knows about the valid tokens for actions and options and how
|
|---|
| 125 | * they are constructed, see \ref MoleCuilder::Action .
|
|---|
| 126 | *
|
|---|
| 127 | *
|
|---|
| 128 | * \date 2015-08-03
|
|---|
| 129 | *
|
|---|
| 130 | */
|
|---|
