Changes in src/Actions/Action.hpp [8a34392:047878]

File:

• src/Actions/Action.hpp (modified) (8 diffs)

src/Actions/Action.hpp

@@ -16 +16 @@
 class ActionState;
 class ActionSequence;
+class Dialog;
 
 /**
@@ -44 +45 @@
  * 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
@@ -78 +89 @@
  * 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. You should also indicate whether the action supports undo by implementing
+ * 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
@@ -122 +137 @@
  *  <li/> derive YourAction from Action
  *  <li/> pass name and flag for registry to the base constructor
- *  <li/> implement performCall(), performUndo(), performRedo()
+ *  <li/> implement createDialog(), performCall(), performUndo(), performRedo()
+ *  <li/> implement the global function call/macro.
  *  <li/> implement the functions that return the flags for the undo mechanism
  *  <li/> Derive YourActionState from ActionState as necessary
@@ -130 +146 @@
  *
  * <ul>
+ *  <li/> createDialog():
+ *  <ul>
+ *   <li/> Call makeDialog() from the UIFactory.
+ *   <li/> Call any needed Dialog->Query...() for the values you need with specific keywords.
+ *   <li/> if the action needs to save a state return a custom state object
+ *   <li/> otherwise return Action::success
+ *  </ul>
  *  <li/> performCall():
  *  <ul>
+ *   <li/> obtain parameters you need by ValueStorage::getCurrentValue, matching
+ *         key words from createDialog().
  *   <li/> do whatever is needed to make the action work
  *   <li/> if the action was abborted return Action::failure
@@ -256 +281 @@
 public:
 
+  enum QueryOptions {Interactive, NonInteractive};
+
   /**
    * This type is used to store pointers to ActionStates while allowing multiple ownership
@@ -278 +305 @@
    * If the call needs to undone you have to use the History, to avoid destroying
    * invariants used by the History.
-   */
-  void call();
+   *
+   * 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);
 
   /**
@@ -337 +369 @@
   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:
-  /**
-   * This is called internally when the call is being done. Implement this method to do the actuall
+
+  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.