debian/tmp/usr/include/KWWidgets/vtkKWWizardWorkflow.h

Go to the documentation of this file.
00001 /*=========================================================================
00002 
00003   Module:    $RCSfile: vtkKWWizardWorkflow.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 vtkKWWizardWorkflow - a wizard workflow engine.
00015 // .SECTION Description
00016 // This class is the basis for a wizard workflow engine, i.e. a state
00017 // machine with a enhancements to support wizard steps (vtkKWWizardStep).
00018 // .SECTION Thanks
00019 // This work is part of the National Alliance for Medical Image
00020 // Computing (NAMIC), funded by the National Institutes of Health
00021 // through the NIH Roadmap for Medical Research, Grant U54 EB005149.
00022 // Information on the National Centers for Biomedical Computing
00023 // can be obtained from http://nihroadmap.nih.gov/bioinformatics.
00024 // .SECTION See Also
00025 // vtkKWWizardStep vtkKWStateMachine vtkKWStateMachineState
00026 
00027 #ifndef __vtkKWWizardWorkflow_h
00028 #define __vtkKWWizardWorkflow_h
00029 
00030 #include "vtkKWStateMachine.h"
00031 
00032 class vtkKWWizardStep;
00033 class vtkKWStateMachineState;
00034 class vtkKWWizardWorkflowInternals;
00035 
00036 class KWWidgets_EXPORT vtkKWWizardWorkflow : public vtkKWStateMachine
00037 {
00038 public:
00039   static vtkKWWizardWorkflow* New();
00040   vtkTypeRevisionMacro(vtkKWWizardWorkflow, vtkKWStateMachine);
00041   void PrintSelf(ostream& os, vtkIndent indent);
00042 
00043   // Description:
00044   // Add a step.
00045   // Note that the step's components will be added automatically to the state
00046   // machine (i.e. its InteractionState and ValidationState states as well as
00047   // its ValidationTransition and ValidationFailedTransition transitions). 
00048   // A new cluster will be created for both InteractionState and 
00049   // ValidationState states.
00050   // Return 1 on success, 0 otherwise.
00051   virtual int AddStep(vtkKWWizardStep *step);
00052   virtual int HasStep(vtkKWWizardStep *step);
00053   virtual int GetNumberOfSteps();
00054   virtual vtkKWWizardStep* GetNthStep(int rank);
00055 
00056   // Description:
00057   // Add a next step, connecting it to the previous added step (if any).
00058   // The convenience method will:
00059   //  - call AddStep(), 
00060   //  - create a transition from the previously added step (if any) *to* this
00061   //    step, by calling the CreateNextTransition() method,
00062   //  - create a transition from this step *back* to the previously added step
00063   //    (if any), by calling the CreateBackTransition() method.
00064   // Return 1 on success, 0 otherwise.
00065   virtual int AddNextStep(vtkKWWizardStep *step);
00066 
00067   // Description:
00068   // Create a transition from an originating step to a destination step. 
00069   // The destination step should semantically be a "next" step, i.e. from
00070   // a workflow perspective, the destination step is meant to appear "after"
00071   // the originating step.
00072   // More specifically, this method creates a transition from the origin's
00073   // ValidationState state to the destination's InteractionState, triggered
00074   // by next_input. The transition's StartCommand callback is automatically
00075   // set to invoke the originating step's HideUserInterface method (which
00076   // calls the HideUserInterfaceCommand callback as well),
00077   // effectively hiding the originating step's UI before the destination
00078   // state is reached.
00079   // This method is used by the AddNextStep() method to connect a newly added
00080   // step to a previously added step (if any). The input used in that case is
00081   // vtkKWWizardStep::ValidationSucceededInput, and is expected to be pushed
00082   // by the previously added step's Validate method/callback.
00083   virtual int CreateNextTransition(
00084     vtkKWWizardStep *origin, 
00085     vtkKWStateMachineInput *next_input,
00086     vtkKWWizardStep *destination);
00087 
00088   // Description:
00089   // Create a transition *back* from a destination step to an originating step.
00090   // The destination step should semantically be a "next" step, i.e. from
00091   // a workflow perspective, the destination step is meant to appear "after"
00092   // the originating step.
00093   // More specifically, this method creates a transition from the 
00094   // destination's InteractionState state to the origin's InteractionState 
00095   // state, triggered by the origin step's GoBackToSelfInput input. 
00096   // The transition's StartCommand callback is automatically set to invoke
00097   // the destination step's HideUserInterface method (which calls the
00098   // HideUserInterfaceCommand callback as well),
00099   // effectively hiding the destination step's UI before the origin state
00100   // is reached back.
00101   virtual int CreateBackTransition(
00102     vtkKWWizardStep *origin, 
00103     vtkKWWizardStep *destination);
00104 
00105   // Description:
00106   // Create a go-to transition from an originating step to a destination step. 
00107   // The destination step does NOT have to be a "next" step semantically, i.e.
00108   // from a workflow perspective, the destination step can be meant to appear
00109   // "after" or "before" the originating step. Such a transition is designed
00110   // to reach a step directly, effectively bypassing all others steps: this
00111   // should be used *very* carefully (as it bends the state machine principles
00112   // to some extent), and is provided only to implement features such as the
00113   // "Finish" button in a wizard widget.
00114   // More specifically, this method creates 4 transitions:
00115   // 1) A transition from the origin's InteractionState to an internal 
00116   //    GoToState state acting as a hub, triggered by the destination step's 
00117   //    GoToSelfInput input. The transition's EndCommand callback is 
00118   //    automatically set to invoke the TryToGoToStepCallback callback, 
00119   //    which is in turn responsible for checking if the destination step can
00120   //    be reached, by invoking its CanGoToSelf method/callback. On success, 
00121   //    the destination step's UI is hidden by calling its 
00122   //    HideUserInterface method, and its GoToSelfInput input is 
00123   //    pushed again to trigger transition 2). On error, the origin step's
00124   //    GoBackToSelfInput input is pushed to trigger transition 3).
00125   // 2) A transition from the internal GoToState hub state to the
00126   //    destination step's InteractionState state, triggered by the destination
00127   //    step's GoToSelfInput input that will be pushed by the 
00128   //    TryToGoToStepCallback callback attached to transition 1). This will
00129   //    effectively lead the state machine to the destination state.
00130   // 3) A transition from the internal GoToState hub state back to the
00131   //    origin step's InteractionState state, triggered by the origin
00132   //    step's GoBackToSelfInput input that will be pushed by the 
00133   //    TryToGoToStepCallback callback attached to transition 1).
00134   // 4) a transition from the destination's InteractionState state back to
00135   //    the origin's InteractionState state, triggered by the origin step's
00136   //    GoBackToSelfInput input (by calling the CreateBackTransition method).
00137 
00138   virtual int CreateGoToTransition(
00139     vtkKWWizardStep *origin, 
00140     vtkKWWizardStep *destination);
00141 
00142   // Description:
00143   // Create a go-to transition from all known steps added so far to a 
00144   // destination step. See the CreateGoToTransition() method for more details.
00145   virtual int CreateGoToTransitions(vtkKWWizardStep *destination);
00146 
00147   // Description:
00148   // Set/Get the initial step. This is a convenience method to set the
00149   // vtkKWStateMachine::InitialState to a specific step's InteractionState
00150   // state. Check vtkKWStateMachine for more details.
00151   // Note that the initial state can not be reset.
00152   // Note that setting the initial state is actually the same as entering
00153   // it (i.e. the state's Enter() method will be called). In this case,
00154   // this will trigger the step's ShowUserInterfaceCommand callback (by
00155   // calling the step's ShowUserInterface method), 
00156   // effectively showing this step's UI. For that reason, this method should
00157   // be the last method you call after setting up the whole workflow.
00158   // Return 1 on success, 0 otherwise.
00159   virtual vtkKWWizardStep* GetInitialStep();
00160   virtual int SetInitialStep(vtkKWWizardStep*);
00161 
00162   // Description:
00163   // Get the current step, i.e. the step vtkKWStateMachine::CurrentState
00164   // belongs too.
00165   virtual vtkKWWizardStep* GetCurrentStep();
00166 
00167   // Description:
00168   // Set/Get the finish step (if not set, GetFinishStep() will return
00169   // the last added step). This is not mandatory and is mainly used
00170   // for user interface (vtkKWWizardWidget) or IO purposes.
00171   // The finish step should semantically be the "last" step, i.e. from
00172   // a workflow perspective, the finish step is meant to appear "after"
00173   // all other steps, at the end.
00174   virtual void SetFinishStep(vtkKWWizardStep*);
00175   virtual vtkKWWizardStep* GetFinishStep();
00176 
00177   // Description:
00178   // Create a go-to transition from all known steps added so far to the 
00179   // Finish step. See FinishStep and the CreateGoToTransitions() and 
00180   // CreateGoToTransition() methods for more details.
00181   virtual int CreateGoToTransitionsToFinishStep();
00182 
00183   // Description:
00184   // Get the step a state belongs to (if any)
00185   virtual vtkKWWizardStep* GetStepFromState(vtkKWStateMachineState*);
00186 
00187   // Description:
00188   // The wizard workflow tries its best to keep a step navigation stack, i.e.
00189   // the path that lead to the current step. This is *not* a step history,
00190   // as going "back" (by calling AttemptToGoToPreviousStep() for example) will
00191   // actually remove steps from the stack.
00192   virtual int GetNumberOfStepsInNavigationStack();
00193   virtual vtkKWWizardStep* GetNthStepInNavigationStack(int rank);
00194 
00195   // Description:
00196   // Attempt to navigate in the workflow by moving the next, previous, or
00197   // finish step.
00198   // The AttemptToGoToNextStep() method pushes a
00199   // vtkKWWizardStep::ValidationInput input. 
00200   // The AttemptToGoToFinishStep() method pushes the FinishStep's 
00201   // GoToSelfInput input.
00202   // The AttemptToGoToPreviousStep() method pushes the previous step's
00203   // GoBackToSelfInput input (if any) and updates the navigation stack.
00204   virtual void AttemptToGoToNextStep();
00205   virtual void AttemptToGoToPreviousStep();
00206   virtual void AttemptToGoToFinishStep();
00207 
00208   // Description:
00209   // Specifies a command to associate with this workflow. This command is 
00210   // invoked when the navigation stack has changed, as a result of moving
00211   // forward (or backward) to a new step.
00212   // The 'object' argument is the object that will have the method called on
00213   // it. The 'method' argument is the name of the method to be called and any
00214   // arguments in string form. If the object is NULL, the method is still
00215   // evaluated as a simple command. 
00216   virtual void SetNavigationStackedChangedCommand(
00217     vtkObject *object, const char *method);
00218   virtual void InvokeNavigationStackedChangedCommand();
00219   virtual int HasNavigationStackedChangedCommand();
00220 
00221   // Description:
00222   // Events. The NavigationStackedChangedCommand is invoked when the navigation
00223   // stack has changed, as a result of moving forward (or backward) to a 
00224   // new step.
00225   //BTX
00226   enum
00227   {
00228     NavigationStackedChangedEvent = 10000
00229   };
00230   //ETX
00231 
00232   // Description:
00233   // Callbacks.
00234   virtual void TryToGoToStepCallback(
00235     vtkKWWizardStep *origin, vtkKWWizardStep *destination);
00236 
00237   // Description:
00238   // Specifies a command to associate with this state machine. This command is 
00239   // invoked when the state machine current state has changed.
00240   // Override to allow the workflow engine to keep track of a navigation stack.
00241   virtual void InvokeCurrentStateChangedCommand();
00242 
00243 protected:
00244   vtkKWWizardWorkflow();
00245   ~vtkKWWizardWorkflow();
00246 
00247   // Description:
00248   // Remove step(s).
00249   virtual void RemoveStep(vtkKWWizardStep *step);
00250   virtual void RemoveAllSteps();
00251 
00252   // PIMPL Encapsulation for STL containers
00253   //BTX
00254   vtkKWWizardWorkflowInternals *Internals;
00255   //ETX
00256 
00257   // Description:
00258   // Get the goto state
00259   vtkKWStateMachineState *GoToState;
00260   virtual vtkKWStateMachineState* GetGoToState();
00261 
00262   char *NavigationStackedChangedCommand;
00263 
00264   // Description:
00265   // Push/pop a step to/from the navigation stack..
00266   virtual void PushStepToNavigationStack(vtkKWWizardStep*);
00267   virtual vtkKWWizardStep* PopStepFromNavigationStack();
00268 
00269 private:
00270 
00271   vtkKWWizardStep *FinishStep;
00272 
00273   vtkKWWizardWorkflow(const vtkKWWizardWorkflow&); // Not implemented
00274   void operator=(const vtkKWWizardWorkflow&); // Not implemented
00275 };
00276 
00277 #endif

Generated on Sat Dec 12 16:04:57 2009 for KWWidgets by  doxygen 1.6.1