KWWidgets
|
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