/* * Action.h * * Created on: Dec 8, 2009 * Author: crueger */ #ifndef ACTION_H_ #define ACTION_H_ #include #include // forward declaration class ActionState; class ActionSequence; class Dialog; /** * @file *

Action Howto

* *

Introduction

* * Actions are used in object oriented design as a replacement for callback functions. * In most ways Actions can be used in the same way that callbacks were used in non * OO-Systems, but can contain support for several extra mechanism such as undo/redo * or progress indicators. * * The main purpose of an action class is to contain small procedures, that can be repeatedly * called. These procedures can also be stored, passed around, so that the execution of an * action can happen quite far away from the place of creation. For a detailed description of * the Action pattern see GOF:1996. * *

How to use an action

* * The process of using an action is as easy as calling the call() method of the action. The * action will then do whatever it is supposed to do. If it is an action that can be undone, it * will also register itself in the history to make itself available for undo. To undo the last * action, you can either use the undoLast() method inside the ActionHistory class or call the * UndoAction also provided by the ActionHistory. If an action was undone it will be available for * redo, using the redoLast() method of the ActionHistory or the RedoAction also provided by this * class. To check whether undo/redo is available at any moment you can use the hasUndo() or * hasRedo() method respectively. * * Note that an Action always has two functions createDialog() and performCall(). The former * returns a Dialog filled with query...() functions for all information that we need from the * user. The latter must not contain any interaction but just uses these values (which are * temporarily stored by class ValueStorage) to perform the Action. * * Furthermore, there is a global action function that makes the action callable with already * present parameters (i.e. without user interaction and for internal use within the code only). * This function is basically just a macro, that puts the parameters into the ValueStorage and * calls Action::call(Action::NonInteractive). * * Actions can be set to be active or inactive. If an action is set to inactive it is signaling, that * some condition necessary for this action to be executed is not currently met. For example the * UndoAction will set itself to inactive, when there is no action at that time that can be undone. * Using call() on an inactive Action results in a no-op. You can query the state of an action using * the isActive() method. * * The undo capabilities of actions come in three types as signaled by two boolean flags (one * combination of these flags is left empty as can be seen later). * * * Each action has a name, that can be used to identify it throughout the run of the application. * This name can be retrieved using the getName() method. Most actions also register themselves with * a global structure, called the ActionRegistry. Actions that register themselves need to have a * unique name for the whole application. If the name is known these actions can be retrieved from * the registry by their name and then be used as normal. * *

Building your own actions

* * Building actions is fairly easy. Simply derive from the abstract Action base class and implement * the virtual methods. The main code that needs to be executed upon call() should be implemented in * the performCall() method. Any user interaction should be placed into the dialog returned by * createDialog(). You should also indicate whether the action supports undo by implementing * the shouldUndo() and canUndo() methods to return the appropriate flags. * * Also, create the global function to allow for easy calling of your function internally (i.e. * without user interaction). It should have the name of the Action class without the suffix Action. * * The constructor of your derived class also needs to call the Base constructor, passing it the * name of the Action and a flag indicating whether this action should be made available in the * registry. WARNING: Do not use the virtual getName() method of the derived action to provide the * constructor with the name, even if you overloaded this method to return a constant. Doing this * will most likely not do what you think it does (see: http://www.parashift.com/c++-faq-lite/strange-inheritance.html#faq-23.5 * if you want to know why this wont work) * *

Interfacing your Action with the Undo mechanism

* * The performX() methods need to comply to a simple standard to allow for undo and redo. The first * convention in this standard concerns the return type. All methods that handle calling, undoing * or redoing return an object of Action::state_ptr. This is a smart pointer to a State object, that * can be used to store state information that is needed by your action for later redo. A rename * Action for example would need to store which object has been renamed and what the old name was. * A move Action on the other hand would need to store the object that has been moved as well as the * old position. If your Action does not need to store any kind of information for redo you can * simply return Action::success and skip the rest of this paragraph. If your action has been * abborted you can return Action::failure, which indicates to the history mechanism that this * action should not be stored. * * If your Action needs any kind of information to undo its execution, you need to store this * information in the state that is returned by the performCall() method. Since no assumptions * can be made on the type or amount of information the ActionState base class is left empty. * To use this class you need to derive a YourActionState class from the ActionState base class * adding your data fields and accessor functions. Upon undo the ActionState object produced * by the corresponding performCall() is then passed to the performUndo() method which should * typecast the ActionState to the appropriate sub class, undo all the changes and produce * a State object that can be used to redo the action if neccessary. This new state object is * then used if the redo mechanism is invoked and passed to the performRedo() function, which * again produces a State that can be used for performUndo(). * *

Outline of the implementation of Actions

* * To sum up the actions necessary to build actions here is a brief outline of things methioned * in the last paragraphs: * *

Basics

* * * *

Implementing performX() methods

* * * *

Advanced techniques

* *

Predefined Actions

* * To make construction of actions easy there are some predefined actions. Namely these are * the MethodAction and the ErrorAction. * * The method action can be used to turn any function with empty arguments and return type void * into an action (also works for functors with those types). Simply pass the constructor for the * MethodAction a name to use for this action, the function to call inside the performCall() * method and a flag indicating if this action should be made retrievable inside the registry * (default is true). MethodActions always report themselves as changing the state of the * application but cannot be undone. i.e. calling MethodActions will always cause the ActionHistory * to be cleared. * * ErrorActions can be used to produce a short message using the Log() << Verbose() mechanism of * the molecuilder. Simply pass the constructor a name for the action, the message to show upon * calling this action and the flag for the registry (default is again true). Error action * report that they do not change the state of the application and are therefore not considered * for undo. * *

Sequences of Actions and MakroActions

* *

Building sequences of Actions

* * Actions can be chained to sequences using the ActionSequence class. Once an ActionSequence is * constructed it will be initially empty. Any Actions can then be added to the sequence using the * addAction() method of the ActionSequence class. The last added action can be removed using the * 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 * separate undo of all actions in the sequence. * *

Building larger Actions from simple ones

* * Using the pre-defined class MakroAction it is possible to construct bigger actions from a sequence * of smaller ones. For this you first have to build a sequence of the actions using the ActionSequence * as described above. Then you can construct a MakroAction passing it a name, the sequence to use * and as usual a flag for the registry. You can then simply call the complete action-sequence through * this makro action using the normal interface. Other than with the direct use of the action sequence * only the complete MakroAction is registered inside the history, i.e. the complete sequence can be * undone at once. Also there are a few caveats you have to take care of when using the MakroAction: * * *

Special kinds of Actions

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

Processes

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

Calculations

* * 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. */ /** * Base class for all actions. * * Actions describe something that has to be done. * Actions can be passed around, stored, performed and undone (Command-Pattern). */ class Action { friend class ActionSequence; friend class ActionHistory; public: enum QueryOptions {Interactive, NonInteractive}; /** * This type is used to store pointers to ActionStates while allowing multiple ownership */ typedef boost::shared_ptr state_ptr; /** * Standard constructor of Action Base class * * All Actions need to have a name. The second flag indicates, whether the action should * be registered with the ActionRegistry. If the Action is registered the name of the * Action needs to be unique for all Actions that are registered. */ Action(std::string _name,bool _doRegister=true); virtual ~Action(); /** * This method is used to call an action. The basic operations for the Action * are carried out and if necessary/possible the Action is added to the History * to allow for undo of this action. * * If the call needs to undone you have to use the History, to avoid destroying * invariants used by the History. * * Note that this call can be Interactive (i.e. a dialog will ask the user for * necessary information) and NonInteractive (i.e. the information will have to * be present already within the ValueStorage class or else a MissingArgumentException * is thrown) */ void call(enum QueryOptions state = Interactive); /** * This method provides a flag that indicates if an undo mechanism is implemented * for this Action. If this is true, and this action was called last, you can * use the History to undo this action. */ virtual bool canUndo()=0; /** * This method provides a flag, that indicates if the Action changes the state of * the application in a way that needs to be undone for the History to work. * * If this is false the Action will not be added to the History upon calling. However * Actions called before this one will still be available for undo. */ virtual bool shouldUndo()=0; /** * Indicates whether the Action can do it's work at the moment. If this * is false calling the action will result in a no-op. */ virtual bool isActive(); /** * Returns the name of the Action. */ virtual const std::string getName(); protected: /** * This method is called by the History, when an undo is performed. It is * provided with the corresponding state produced by the performCall or * performRedo method and needs to provide a state that can be used for redo. */ state_ptr undo(state_ptr); /** * This method is called by the Histor, when a redo is performed. It is * provided with the corresponding state produced by the undo method and * needs to produce a State that can then be used for another undo. */ state_ptr redo(state_ptr); /** * This special state can be used to indicate that the Action was successfull * without providing a special state. Use this if your Action does not need * a speciallized state. */ static state_ptr success; /** * This special state can be returned, to indicate that the action could not do it's * work, was abborted by the user etc. If you return this state make sure to transactionize * your Actions and unroll the complete transaction before this is returned. */ static state_ptr failure; /** * This creates the dialog requesting the information needed for this action from the user * via means of the user interface. */ Dialog * createDialog(); private: virtual Dialog * fillDialog(Dialog*)=0; /** * This is called internally when the call is being done. Implement this method to do the actual * work of the Action. Implement this in your Derived classes. Needs to return a state that can be * used to undo the action. */ virtual state_ptr performCall()=0; /** * This is called internally when the undo process is chosen. This Method should use the state * produced by the performCall method to return the state of the application to the state * it had before the Action. */ virtual state_ptr performUndo(state_ptr)=0; /** * This is called internally when the redo process is chosen. This method shoudl use the state * produced by the performUndo method to return the application to the state it should have after * the action. * * Often this method can be implement to re-use the performCall method. However if user interaction * or further parameters are needed, those should be taken from the state and not query the user * again. */ virtual state_ptr performRedo(state_ptr)=0; std::string name; }; /** * This class can be used by actions to save the state. * * It is implementing a memento pattern. The base class is completely empty, * since no general state internals can be given. The Action performing * the Undo should downcast to the apropriate type. */ class ActionState{ public: ActionState(){} virtual ~ActionState(){} }; #endif /* ACTION_H_ */