Changeset 91b18cd for molecuilder/src/Actions

Timestamp:

Apr 8, 2010, 2:28:21 PM (15 years ago)

Author:

Tillmann Crueger <crueger@…>

Children:

298621

Parents:

abd4a1

Message:

More documentation for Action class added

File:

• molecuilder/src/Actions/Action.hpp (modified) (2 diffs)

molecuilder/src/Actions/Action.hpp

@@ -181 +181 @@
  * removeLastAction() method. If the construction of the sequence is done, you can use the
  * callAll() method. Each action called this way will register itself with the History to allow
- * seperate undo of all actions in the sequence.
+ * separate undo of all actions in the sequence.
  *
  * <H4> Building larger Actions from simple ones </H4>
@@ -200 +200 @@
  *        might brake important assumptions for the undo/redo mechanism
  * </ul>
+ *
+ * <H3> Special kinds of Actions </H3>
+ *
+ * To make the usage of Actions more versatile there are two special kinds of actions defined,
+ * that contain special mechanisms. These are defined inside the class Process, for actions that
+ * take some time and indicate their own progress, and in the class Calculations for actions that
+ * have a retrievable result.
+ *
+ * <H4> Processes </H4>
+ *
+ * Processes are Actions that might take some time and therefore contain special mechanisms
+ * to indicate their progress to the user. If you want to implement a process you can follow the
+ * guidelines for implementing actions. In addition to the normal Action constructor parameters,
+ * you also need to define the number of steps the process takes to finish (use 0 if that number is
+ * not known upon construction). At the beginning of your process you then simply call start() to
+ * indicate that the process is taking up its work. You might also want to set the number of steps it
+ * needs to finish, if it has changed since the last invocation/construction. You can use the
+ * setMaxSteps() method for this. Then after each finished step of calulation simply call step(),
+ * to let the indicators know that it should update itself. If the number of steps is not known
+ * at the time of calculation, you should make sure the maxSteps field is set to 0, either through
+ * the constructor or by using setMaxSteps(0). Indicators are required to handle both processes that
+ * know the number of steps needed as well as processes that cannot predict when they will be finished.
+ * Once your calculation is done call stop() to let every indicator know that the process is done with
+ * the work and to let the user know.
+ *
+ * Indicators that want to know about processes need to implement the Observer class with all the
+ * methods defined there. They can then globally sign on to all processes using the static
+ * Process::AddObserver() method and remove themselves using the Process::RemoveObserver()
+ * methods. When a process starts it will take care that the notification for this process
+ * is invoked at the right time. Indicators should not try to observe a single process, but rather
+ * be ready to observe the status of any kind of process using the methods described here.
+ *
+ * <H4> Calculations </H4>
+ *
+ * Calculations are special Actions that also return a result when called. Calculations are
+ * always derived from Process, so that the progress of a calculation can be shown. Also
+ * Calculations should not contain side-effects and not consider the undo mechanism.
+ * When a Calculation is called using the Action mechanism this will cause it to calculate
+ * the result and make it available using the getResult() method. Another way to have a Calculation
+ * produce a result is by using the function-call operator. When this operator is used, the Calculation
+ * will try to return a previously calculated and cached result and only do any actuall calculations
+ * when no such result is available. You can delete the cached result using the reset() method.
  */