KWWidgets
vtkKWWizardStep.h
Go to the documentation of this file.
00001 /*=========================================================================
00002 
00003   Module:    $RCSfile: vtkKWWizardStep.h,v $
00004 
00005   Copyright (c) Kitware, Inc.
00006   All rights reserved.
00007   See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
00008 
00009      This software is distributed WITHOUT ANY WARRANTY; without even
00010      the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
00011      PURPOSE.  See the above copyright notice for more information.
00012 
00013 =========================================================================*/
00014 // .NAME vtkKWWizardStep - a wizard step.
00015 // .SECTION Description
00016 // This class is the basis for a wizard step. A wizard step is a 
00017 // placeholder for various states, transitions and inputs that are used
00018 // in a typical wizard workflow. Such steps can be added to instances of
00019 // the vtkKWWizardWorkflow class (subclass of vtkKWStateMachine). 
00020 // A wizard workflow can be manipulated from a user interface through either
00021 // the vtkKWWizardWidget or vtkKWWizardDialog classes.
00022 // .SECTION Thanks
00023 // This work is part of the National Alliance for Medical Image
00024 // Computing (NAMIC), funded by the National Institutes of Health
00025 // through the NIH Roadmap for Medical Research, Grant U54 EB005149.
00026 // Information on the National Centers for Biomedical Computing
00027 // can be obtained from http://nihroadmap.nih.gov/bioinformatics.
00028 // .SECTION See Also
00029 // vtkKWWizardWorkflow vtkKWStateMachine vtkKWWizardWidget vtkKWWizardDialog
00030 
00031 #ifndef __vtkKWWizardStep_h
00032 #define __vtkKWWizardStep_h
00033 
00034 #include "vtkKWObject.h"
00035 
00036 class vtkKWStateMachineState;
00037 class vtkKWStateMachineInput;
00038 class vtkKWStateMachineTransition;
00039 
00040 //BTX
00041 class KWWidgets_EXPORT vtkKWWizardStepCleanup
00042 {
00043 public:
00044   vtkKWWizardStepCleanup() {};
00045   ~vtkKWWizardStepCleanup();
00046 };
00047 //ETX
00048 
00049 class KWWidgets_EXPORT vtkKWWizardStep : public vtkKWObject
00050 {
00051 public:
00052   static vtkKWWizardStep* New();
00053   vtkTypeRevisionMacro(vtkKWWizardStep, vtkKWObject);
00054   void PrintSelf(ostream& os, vtkIndent indent);
00055 
00056   // Description:
00057   // Get id.
00058   vtkGetMacro(Id, vtkIdType);
00059 
00060   // Description:
00061   // Set/Get simple name.
00062   vtkGetStringMacro(Name);
00063   vtkSetStringMacro(Name);
00064 
00065   // Description:
00066   // Set/Get short description.
00067   vtkGetStringMacro(Description);
00068   vtkSetStringMacro(Description);
00069 
00070   // Description:
00071   // Show the user interface associated to that step. Wizard developpers can
00072   // either reimplement the ShowUserInterface method in a vtkKWWizardStep 
00073   // subclass (*do* call the superclass' ShowUserInterface first), or create a 
00074   // vtkKWWizardStep instance and set the ShowUserInterfaceCommand to point to
00075   // a callback of their choice.
00076   // Either ways, these methods will be invoked automatically when the state
00077   // machine enters the step's InteractionState state. 
00078   // The 'object' argument is the object that will have the method called on
00079   // it. The 'method' argument is the name of the method to be called and any
00080   // arguments in string form. If the object is NULL, the method is still
00081   // evaluated as a simple command. 
00082   virtual void ShowUserInterface();
00083   virtual void SetShowUserInterfaceCommand(
00084     vtkObject *object, const char *method);
00085   virtual void InvokeShowUserInterfaceCommand();
00086   virtual int HasShowUserInterfaceCommand();
00087 
00088   // Description:
00089   // Events.
00090   //BTX
00091   enum
00092   {
00093     ShowUserInterfaceEvent = 10000,
00094     HideUserInterfaceEvent,
00095     ValidateEvent
00096   };
00097   //ETX
00098 
00099 
00100   // Description:
00101   // Hide the user interface associated to that step. Wizard developpers can
00102   // either reimplement the HideUserInterface method in a vtkKWWizardStep 
00103   // subclass (*do* call the superclass' HideUserInterface first), or create a 
00104   // vtkKWWizardStep instance and set the HideUserInterfaceCommand to point to
00105   // a callback of their choice.
00106   // Either ways, these methods will be invoked automatically by transitions 
00107   // that move the state machine from one step to another step, such as the
00108   // ones created by the vtkKWWizardWorkflow::AddNextStep(), 
00109   // vtkKWWizardWorkflow::CreateNextTransition() or 
00110   // vtkKWWizardWorkflow::CreateBackTransition() methods.
00111   // While this method/callback can be used to release resources that were
00112   // allocated specifically for a step's UI, calling the
00113   // vtkKWWizardWidget::ClearPage() method will do the trick most of the time 
00114   // when the wizard workflow is working in conjunction with a 
00115   // vtkKWWizardWidget.
00116   // The 'object' argument is the object that will have the method called on
00117   // it. The 'method' argument is the name of the method to be called and any
00118   // arguments in string form. If the object is NULL, the method is still
00119   // evaluated as a simple command. 
00120   virtual void HideUserInterface();
00121   virtual void SetHideUserInterfaceCommand(
00122     vtkObject *object, const char *method);
00123   virtual void InvokeHideUserInterfaceCommand();
00124   virtual int HasHideUserInterfaceCommand();
00125 
00126   // Description:
00127   // Validate the user interface associated to that step. Wizard developpers
00128   // can either reimplement the Validate method in a 
00129   // vtkKWWizardStep subclass (*do* call the superclass' Validate
00130   // first), or create a vtkKWWizardStep instance and set the
00131   // ValidateCommand to point to a callback of their choice.
00132   // Either ways, these important methods are called when the 
00133   // ValidationTransition transition is triggered by the ValidationInput input,
00134   // effectively moving the state machine from the InteractionState state to
00135   // the ValidationState state.
00136   // It is the responsibility of this method/callback to push inputs that will
00137   // move the state machine to the next step (using the 
00138   // ValidationSucceededInput input for example), or back to the 
00139   // InteractionState on error (using the ValidationFailedInput input and the
00140   // ValidationFailedTransition transition). User-defined inputs can be
00141   // pushed as well if the step has potentially multiple "valid" next steps.
00142   // Pushing the ValidationSucceededInput input will trigger transitions
00143   // such as the one created by the vtkKWWizardWorkflow::AddNextStep() or 
00144   // vtkKWWizardWorkflow::CreateNextTransition() methods.
00145   // The 'object' argument is the object that will have the method called on
00146   // it. The 'method' argument is the name of the method to be called and any
00147   // arguments in string form. If the object is NULL, the method is still
00148   // evaluated as a simple command. 
00149   virtual void Validate();
00150   virtual void SetValidateCommand(vtkObject *object, const char *method);
00151   virtual void InvokeValidateCommand();
00152   virtual int HasValidateCommand();
00153 
00154   // Description:
00155   // Check if one can go directly to this step, given the model associated
00156   // to the wizard workflow. Wizard developpers can either reimplement the
00157   // CanGoToSelf method in a vtkKWWizardStep subclass (*do* check if
00158   // the CanGoToSelfCommand is set though, and invoke it in priority), or
00159   // create a vtkKWWizardStep instance and
00160   // set the CanGoToSelfCommand to point to a callback of their choice.
00161   // Either ways, these methods can be used when there is a need to know
00162   // if one can go directly to this step, effectively bypassing all others
00163   // steps: this should be used *very* carefully, and is provided to
00164   // implement features such as the "Finish" button in a wizard widget.
00165   // This method/command should return 1 if the step can be reached, 0 
00166   // otherwise.
00167   // The 'object' argument is the object that will have the method called on
00168   // it. The 'method' argument is the name of the method to be called and any
00169   // arguments in string form. If the object is NULL, the method is still
00170   // evaluated as a simple command. 
00171   virtual int CanGoToSelf();
00172   virtual void SetCanGoToSelfCommand(vtkObject *object, const char *method);
00173   virtual int InvokeCanGoToSelfCommand();
00174   virtual int HasCanGoToSelfCommand();
00175 
00176   // Description:
00177   // Get the step's interaction state. This state is used to
00178   // display the user interface pertaining to this step, then wait for more
00179   // user inputs. Note that this class listens to the InteractionState's 
00180   // vtkKWStateMachineState::EnterEvent event; as this event is triggered, the 
00181   // ShowUserInterface() method is automatically called (hence the 
00182   // InvokeShowUserInterfaceCommand() as well).
00183   // Access to this state is given for advanced customization. In the vast
00184   // majority of wizards, it should be ignored; the ShowUserInterface method
00185   // or callback is however the key component to define for this state to work
00186   // as expected.
00187   virtual vtkKWStateMachineState* GetInteractionState();
00188 
00189   // Description:
00190   // Get the step's validation state. This state is used to validate the user
00191   // interface pertaining to this step (as displayed by the InteractionState
00192   // state), then branch to the next step's InteractionState state on success,
00193   // or back to the current step's InteractionState state on error. The state
00194   // acts as a hub:  the validation itself is performed by the 
00195   // ValidateCommand callback (or Validate method for the corresponding
00196   // step) attached to the ValidationTransition 
00197   // transition that sits between the InteractionState state and the 
00198   // ValidationState state.
00199   // Access to this state is given for advanced customization. In the vast
00200   // majority of wizards, it should be ignored; the ValidateCommand (or
00201   // the Validate method) is however the key component to define for this
00202   // state to work as expected.
00203   virtual vtkKWStateMachineState* GetValidationState();
00204 
00205   // Description:
00206   // Get the step's validation transition. This transition is used to validate
00207   // the user interface pertaining to this step (as displayed by the 
00208   // InteractionState state), then branch to the next step's InteractionState
00209   // state on success, or back to the current step's InteractionState state
00210   // on error. More specifically:
00211   //   - its originating state is the InteractionState state, 
00212   //   - its destination state is the ValidationState state, 
00213   //   - it is triggered by the ValidationInput input. 
00214   // Note that this class listens to the ValidationTransition's 
00215   // vtkKWStateMachineTransition::EndEvent event; as this even is triggered, 
00216   // the Validate() method is automatically called (hence the
00217   // InvokeValidateCommand() method as well).
00218   // Wizard developpers reimplement the Validate method or can set 
00219   // ValidateCommand to point to a method of their choice to validate the
00220   // step's UI; it will be invoked automatically when the state machine
00221   // triggers the ValidationTransition transition. 
00222   // The wizard workflow (or wizard widget) will typically push a 
00223   // ValidationInput input on the queue to request a step to be validated
00224   // and move to the next step. If the state machine is at an InteractionState
00225   // state, the corresponding step's ValidationTransition transition will be
00226   // triggered, the state machine will move to the ValidationState state and
00227   // validation will occur through the ValidateCommand callback or Validate
00228   // method. This method/callback will push inputs that in turn will move the
00229   // state machine to the next step (using the ValidationSucceededInput input
00230   // for example), or back to the InteractionState on error (using the
00231   // ValidationFailedInput input and the ValidationFailedTransition 
00232   // transition).
00233   // Access to this transition is given for advanced customization. In the vast
00234   // majority of wizards, it should be ignored; the ValidateCommand (or
00235   // Validate method) is however the key component to define for this
00236   // transition to work as expected, since it is where the
00237   // ValidationSucceededInput, ValidationFailedInput and user-defined inputs
00238   // should be pushed.
00239   virtual vtkKWStateMachineTransition* GetValidationTransition();
00240 
00241   // Description:
00242   // Get the step's validation input. This singleton input is used to trigger
00243   // the ValidationTransition transition and move the state machine from the 
00244   // InteractionState state to the ValidationState state.
00245   // Access to this input is given for advanced customization. In the vast
00246   // majority of wizards, it should be ignored; the wizard workflow (or
00247   // wizard widget) will typically push a ValidationInput input on the queue
00248   // to request a step to be validated and move to the next step. If the state
00249   // machine is at an InteractionState state, the corresponding step's 
00250   // ValidationTransition transition will be triggered, the state machine will
00251   // move to the ValidationState state and validation will occur through the
00252   // ValidateCommand callback (or Validate method).
00253   static vtkKWStateMachineInput* GetValidationInput();
00254 
00255   // Description:
00256   // Get the step's validation successful input. This singleton input is used 
00257   // in the ValidateCommand callback and in conjunction with the 
00258   // workflow class (vtkKWWizardWorkflow) to trigger a transition from the
00259   // step's ValidationState state to the next step's InteractionState state. 
00260   // It is, as far as the workflow is concerned, the input that moves
00261   // the state machine from one step to the other. The corresponding 
00262   // transition can be created automatically by the
00263   // vtkKWWizardWorkflow::AddNextStep() or 
00264   // vtkKWWizardWorkflow::CreateNextTransition() methods.
00265   // The ValidateCommand callback (or Validate method) is the key component
00266   // where this input is used.
00267   static vtkKWStateMachineInput* GetValidationSucceededInput();
00268 
00269   // Description:
00270   // Get the step's validation failed input. This singleton input is used 
00271   // in the ValidateCommand callback (or Validate method) and in conjunction
00272   // with the workflow class (vtkKWWizardWorkflow) to trigger the
00273   // ValidationFailedTransition transition from the step's ValidationState
00274   // state back to the step's InteractionState state. 
00275   // The ValidateCommand callback (or Validate method) is the key component
00276   // where this input is used.
00277   static vtkKWStateMachineInput* GetValidationFailedInput();
00278 
00279   // Description:
00280   // Get the step's validation failed transition. This transition is used 
00281   // to bring the state machine from the ValidationState state back to the
00282   // InteractionState state, when validation of the user interface pertaining 
00283   // to this step failed (as displayed by the InteractionState state).
00284   // More specifically:
00285   //   - its originating state is the ValidationState state, 
00286   //   - its destination state is the InteractionState state, 
00287   //   - it is triggered by the ValidationFailedInput input. 
00288   // Important: it is up to the wizard developpers to push the
00289   // ValidationFailedInput input on the state machine queue *from* the 
00290   // ValidateCommand callback (or Validate method) for the state machine to
00291   // trigger that transition and go back to the InteractionState state.
00292   // Access to this transition is given for advanced customization. In the vast
00293   // majority of wizards, it should be ignored; the ValidateCommand callback
00294   // (or Validate method) is the key component to define for this transition
00295   // to work as expected, since it is where the ValidationFailedInput input 
00296   // should be pushed.
00297   virtual vtkKWStateMachineTransition* GetValidationFailedTransition();
00298 
00299   // Description:
00300   // Get the step's go to self input. This input is used to trigger
00301   // transition that are meant to move the state machine directly to this step,
00302   // effectively bypassing all others steps: this should be used very 
00303   // carefully, and is provided only to implement features such as the
00304   // "Finish" button in a wizard widget.
00305   // Access to this input is given for advanced customization. In the vast
00306   // majority of wizards, it should be ignored; it is used by the
00307   // vtkKWWizardWorkflow::CreateGoToTransition() method to implement
00308   // transitions to specific steps directly (the "Finish" step, for example).
00309   virtual vtkKWStateMachineInput* GetGoToSelfInput();
00310 
00311   // Description:
00312   // Get the step's go back to self input. This input is used to trigger
00313   // transitions that are meant to move the state machine back to the 
00314   // previous step (if any): this should be used very carefully, and is 
00315   // provided only to implement features such as the "Back" or "Finish" button
00316   // in a wizard widget.
00317   // Access to this input is given for advanced customization. In the vast
00318   // majority of wizards, it should be ignored; it is used by the
00319   // vtkKWWizardWorkflow::CreateBackTransition() method to implement
00320   // transitions back to specific steps directly.
00321   virtual vtkKWStateMachineInput* GetGoBackToSelfInput();
00322 
00323   // Description:
00324   // Add all the default observers needed by that object, or remove
00325   // all the observers that were added through AddCallbackCommandObserver.
00326   // Subclasses can override these methods to add/remove their own default
00327   // observers, but should call the superclass too.
00328   virtual void RemoveCallbackCommandObservers();
00329 
00330 protected:
00331   vtkKWWizardStep();
00332   ~vtkKWWizardStep();
00333 
00334   vtkIdType Id;
00335   char *Name;
00336   char *Description;
00337 
00338   char *ShowUserInterfaceCommand;
00339   char *HideUserInterfaceCommand;
00340   char *ValidateCommand;
00341   char *CanGoToSelfCommand;
00342 
00343   // Description:
00344   // Processes the events that are passed through CallbackCommand (or others).
00345   // Subclasses can oberride this method to process their own events, but
00346   // should call the superclass too.
00347   virtual void ProcessCallbackCommandEvents(
00348     vtkObject *caller, unsigned long event, void *calldata);
00349   
00350 private:
00351 
00352   vtkKWStateMachineState *InteractionState;
00353   vtkKWStateMachineState *ValidationState;
00354 
00355   vtkKWStateMachineTransition *ValidationTransition;
00356   vtkKWStateMachineTransition *ValidationFailedTransition;
00357 
00358   vtkKWStateMachineInput *GoToSelfInput;
00359   vtkKWStateMachineInput *GoBackToSelfInput;
00360 
00361   static vtkIdType IdCounter;
00362 
00363   static vtkKWStateMachineInput *ValidationInput;
00364   static vtkKWStateMachineInput *ValidationSucceededInput;
00365   static vtkKWStateMachineInput *ValidationFailedInput;
00366 
00367   //BTX
00368   // Used to delete our singletons.
00369   static vtkKWWizardStepCleanup Cleanup;
00370   friend class vtkKWWizardStepCleanup;
00371   //ETX
00372 
00373   static void SetValidationInput(vtkKWStateMachineInput*);
00374   static void SetValidationSucceededInput(vtkKWStateMachineInput*);
00375   static void SetValidationFailedInput(vtkKWStateMachineInput*);
00376 
00377   vtkKWWizardStep(const vtkKWWizardStep&); // Not implemented
00378   void operator=(const vtkKWWizardStep&); // Not implemented
00379 };
00380 
00381 #endif