source: src/documentation/constructs/actions.dox@ 0f3042

Last change on this file since 0f3042 was eee1b7, checked in by Frederik Heber <heber@…>, 12 years ago

DOCU: Documentation on ShapeRegistry, QtUI changes, validators, and parameters.

  • Property mode set to 100644
File size: 3.2 KB
Line 
1/*
2 * Project: MoleCuilder
3 * Description: creates and alters molecular systems
4 * Copyright (C) 2010 University of Bonn. All rights reserved.
5 * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
6 */
7
8/**
9 * \file actions.dox
10 *
11 * Created on: Oct 28, 2011
12 * Author: heber
13 */
14
15/** \page actions Actions
16 *
17 * \link MoleCuilder::Action Actions \endlink are Command patterns
18 * (http://en.wikipedia.org/wiki/Command_pattern)
19 * to allow for undoing and redoing. Each specific Action derives from this
20 * class to implement a certain functionality. There is a lot of preprocessor
21 * magic implemented for making this as easy as possible. In effect you only
22 * have to create three files of which only one actually contains more than a
23 * few lines, namely the code of the Action itself.
24 * Each Action also derives a specific ActionState and ActionParameters for
25 * containing the undo/redo state information and the parameters steering what
26 * the Action does.
27 *
28 * Each Action has thus three types of functionality: do, undo, and redo.
29 *
30 * The ActionRegistry contains a prototype of each Action under its token
31 * such that an instance can be retrieved by knowing this token.
32 *
33 * Each Action can contain multiple \ref parameters in its specific ActionParameters
34 * structure that represent the options. Executing call() first fills a dialog
35 * with \ref queries, one for each option. The UI then tries to obtain the
36 * values from the user. Depending on the type of the UI in use that could mean
37 * parsing stored command line parameters or displaying a real dialog box with widgets.
38 *
39 * Also there is a regression test (\ref regression-test) for each Action to
40 * check that it always behaves the same no matter how much the code
41 * implementing actually has changed.
42 *
43 * \section actions-add To add a new action ...
44 *
45 * The following steps have to be done for adding a new action:
46 * -# Create three new files .cpp, .def, and .hpp
47 * -# Add the files to \b src/Actions/Makefile.am.
48 * -# Add the name of the Action to \b src/Actions/GlobalListOfActions.hpp
49 * such that the ActionRegistry knows about it and can instantiate a
50 * prototype.
51 *
52 * \section actions-undo-redo Undoing and Redoing actions ...
53 *
54 * The central points of Actions is that they can be undone and redone. This
55 * has to be implemented in two more functions beside the "do".
56 *
57 * Note that undoing means to get everything back to its original state and by whatever
58 * means seem appropriate, e.g. remvoing all just inserted atoms.
59 * To make this more elaborate it is usually very useful to store extra information
60 * in the Action's state such that undo and redo can be accomplished more quickly.
61 * E.g. if your Action creates some new atoms, store their info as \ref AtomicInfo.
62 * Then, undo can simply delete the newly created atoms and redo can quickly re-
63 * create them in the state they have been before.
64 *
65 * Have a look at \ref UndoRedoHelpers.hpp for some helper functions on this.
66 *
67 * \section actions-further Further information
68 *
69 * If you want know:
70 * -# how the code knows about the valid tokens for actions and options and how
71 * they are constructed, see \ref MoleCuilder::Action .
72 *
73 *
74 * \date 2013-02-07
75 *
76 */
Note: See TracBrowser for help on using the repository browser.