KWWidgets
debian/tmp/usr/include/KWWidgets/vtkKWWizardWorkflow.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: $RCSfile: vtkKWWizardWorkflow.h,v $
4 
5  Copyright (c) Kitware, Inc.
6  All rights reserved.
7  See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
8 
9  This software is distributed WITHOUT ANY WARRANTY; without even
10  the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
11  PURPOSE. See the above copyright notice for more information.
12 
13 =========================================================================*/
14 // .NAME vtkKWWizardWorkflow - a wizard workflow engine.
15 // .SECTION Description
16 // This class is the basis for a wizard workflow engine, i.e. a state
17 // machine with a enhancements to support wizard steps (vtkKWWizardStep).
18 // .SECTION Thanks
19 // This work is part of the National Alliance for Medical Image
20 // Computing (NAMIC), funded by the National Institutes of Health
21 // through the NIH Roadmap for Medical Research, Grant U54 EB005149.
22 // Information on the National Centers for Biomedical Computing
23 // can be obtained from http://nihroadmap.nih.gov/bioinformatics.
24 // .SECTION See Also
25 // vtkKWWizardStep vtkKWStateMachine vtkKWStateMachineState
26 
27 #ifndef __vtkKWWizardWorkflow_h
28 #define __vtkKWWizardWorkflow_h
29 
30 #include "vtkKWStateMachine.h"
31 
32 class vtkKWWizardStep;
34 class vtkKWWizardWorkflowInternals;
35 
37 {
38 public:
39  static vtkKWWizardWorkflow* New();
40  vtkTypeRevisionMacro(vtkKWWizardWorkflow, vtkKWStateMachine);
41  void PrintSelf(ostream& os, vtkIndent indent);
42 
43  // Description:
44  // Add a step.
45  // Note that the step's components will be added automatically to the state
46  // machine (i.e. its InteractionState and ValidationState states as well as
47  // its ValidationTransition and ValidationFailedTransition transitions).
48  // A new cluster will be created for both InteractionState and
49  // ValidationState states.
50  // Return 1 on success, 0 otherwise.
51  virtual int AddStep(vtkKWWizardStep *step);
52  virtual int HasStep(vtkKWWizardStep *step);
53  virtual int GetNumberOfSteps();
54  virtual vtkKWWizardStep* GetNthStep(int rank);
55 
56  // Description:
57  // Add a next step, connecting it to the previous added step (if any).
58  // The convenience method will:
59  // - call AddStep(),
60  // - create a transition from the previously added step (if any) *to* this
61  // step, by calling the CreateNextTransition() method,
62  // - create a transition from this step *back* to the previously added step
63  // (if any), by calling the CreateBackTransition() method.
64  // Return 1 on success, 0 otherwise.
65  virtual int AddNextStep(vtkKWWizardStep *step);
66 
67  // Description:
68  // Create a transition from an originating step to a destination step.
69  // The destination step should semantically be a "next" step, i.e. from
70  // a workflow perspective, the destination step is meant to appear "after"
71  // the originating step.
72  // More specifically, this method creates a transition from the origin's
73  // ValidationState state to the destination's InteractionState, triggered
74  // by next_input. The transition's StartCommand callback is automatically
75  // set to invoke the originating step's HideUserInterface method (which
76  // calls the HideUserInterfaceCommand callback as well),
77  // effectively hiding the originating step's UI before the destination
78  // state is reached.
79  // This method is used by the AddNextStep() method to connect a newly added
80  // step to a previously added step (if any). The input used in that case is
81  // vtkKWWizardStep::ValidationSucceededInput, and is expected to be pushed
82  // by the previously added step's Validate method/callback.
83  virtual int CreateNextTransition(
84  vtkKWWizardStep *origin,
85  vtkKWStateMachineInput *next_input,
86  vtkKWWizardStep *destination);
87 
88  // Description:
89  // Create a transition *back* from a destination step to an originating step.
90  // The destination step should semantically be a "next" step, i.e. from
91  // a workflow perspective, the destination step is meant to appear "after"
92  // the originating step.
93  // More specifically, this method creates a transition from the
94  // destination's InteractionState state to the origin's InteractionState
95  // state, triggered by the origin step's GoBackToSelfInput input.
96  // The transition's StartCommand callback is automatically set to invoke
97  // the destination step's HideUserInterface method (which calls the
98  // HideUserInterfaceCommand callback as well),
99  // effectively hiding the destination step's UI before the origin state
100  // is reached back.
101  virtual int CreateBackTransition(
102  vtkKWWizardStep *origin,
103  vtkKWWizardStep *destination);
104 
105  // Description:
106  // Create a go-to transition from an originating step to a destination step.
107  // The destination step does NOT have to be a "next" step semantically, i.e.
108  // from a workflow perspective, the destination step can be meant to appear
109  // "after" or "before" the originating step. Such a transition is designed
110  // to reach a step directly, effectively bypassing all others steps: this
111  // should be used *very* carefully (as it bends the state machine principles
112  // to some extent), and is provided only to implement features such as the
113  // "Finish" button in a wizard widget.
114  // More specifically, this method creates 4 transitions:
115  // 1) A transition from the origin's InteractionState to an internal
116  // GoToState state acting as a hub, triggered by the destination step's
117  // GoToSelfInput input. The transition's EndCommand callback is
118  // automatically set to invoke the TryToGoToStepCallback callback,
119  // which is in turn responsible for checking if the destination step can
120  // be reached, by invoking its CanGoToSelf method/callback. On success,
121  // the destination step's UI is hidden by calling its
122  // HideUserInterface method, and its GoToSelfInput input is
123  // pushed again to trigger transition 2). On error, the origin step's
124  // GoBackToSelfInput input is pushed to trigger transition 3).
125  // 2) A transition from the internal GoToState hub state to the
126  // destination step's InteractionState state, triggered by the destination
127  // step's GoToSelfInput input that will be pushed by the
128  // TryToGoToStepCallback callback attached to transition 1). This will
129  // effectively lead the state machine to the destination state.
130  // 3) A transition from the internal GoToState hub state back to the
131  // origin step's InteractionState state, triggered by the origin
132  // step's GoBackToSelfInput input that will be pushed by the
133  // TryToGoToStepCallback callback attached to transition 1).
134  // 4) a transition from the destination's InteractionState state back to
135  // the origin's InteractionState state, triggered by the origin step's
136  // GoBackToSelfInput input (by calling the CreateBackTransition method).
137 
138  virtual int CreateGoToTransition(
139  vtkKWWizardStep *origin,
140  vtkKWWizardStep *destination);
141 
142  // Description:
143  // Create a go-to transition from all known steps added so far to a
144  // destination step. See the CreateGoToTransition() method for more details.
145  virtual int CreateGoToTransitions(vtkKWWizardStep *destination);
146 
147  // Description:
148  // Set/Get the initial step. This is a convenience method to set the
149  // vtkKWStateMachine::InitialState to a specific step's InteractionState
150  // state. Check vtkKWStateMachine for more details.
151  // Note that the initial state can not be reset.
152  // Note that setting the initial state is actually the same as entering
153  // it (i.e. the state's Enter() method will be called). In this case,
154  // this will trigger the step's ShowUserInterfaceCommand callback (by
155  // calling the step's ShowUserInterface method),
156  // effectively showing this step's UI. For that reason, this method should
157  // be the last method you call after setting up the whole workflow.
158  // Return 1 on success, 0 otherwise.
159  virtual vtkKWWizardStep* GetInitialStep();
160  virtual int SetInitialStep(vtkKWWizardStep*);
161 
162  // Description:
163  // Get the current step, i.e. the step vtkKWStateMachine::CurrentState
164  // belongs too.
165  virtual vtkKWWizardStep* GetCurrentStep();
166 
167  // Description:
168  // Set/Get the finish step (if not set, GetFinishStep() will return
169  // the last added step). This is not mandatory and is mainly used
170  // for user interface (vtkKWWizardWidget) or IO purposes.
171  // The finish step should semantically be the "last" step, i.e. from
172  // a workflow perspective, the finish step is meant to appear "after"
173  // all other steps, at the end.
174  virtual void SetFinishStep(vtkKWWizardStep*);
175  virtual vtkKWWizardStep* GetFinishStep();
176 
177  // Description:
178  // Create a go-to transition from all known steps added so far to the
179  // Finish step. See FinishStep and the CreateGoToTransitions() and
180  // CreateGoToTransition() methods for more details.
181  virtual int CreateGoToTransitionsToFinishStep();
182 
183  // Description:
184  // Get the step a state belongs to (if any)
185  virtual vtkKWWizardStep* GetStepFromState(vtkKWStateMachineState*);
186 
187  // Description:
188  // The wizard workflow tries its best to keep a step navigation stack, i.e.
189  // the path that lead to the current step. This is *not* a step history,
190  // as going "back" (by calling AttemptToGoToPreviousStep() for example) will
191  // actually remove steps from the stack.
192  virtual int GetNumberOfStepsInNavigationStack();
193  virtual vtkKWWizardStep* GetNthStepInNavigationStack(int rank);
194 
195  // Description:
196  // Attempt to navigate in the workflow by moving the next, previous, or
197  // finish step.
198  // The AttemptToGoToNextStep() method pushes a
199  // vtkKWWizardStep::ValidationInput input.
200  // The AttemptToGoToFinishStep() method pushes the FinishStep's
201  // GoToSelfInput input.
202  // The AttemptToGoToPreviousStep() method pushes the previous step's
203  // GoBackToSelfInput input (if any) and updates the navigation stack.
204  virtual void AttemptToGoToNextStep();
205  virtual void AttemptToGoToPreviousStep();
206  virtual void AttemptToGoToFinishStep();
207 
208  // Description:
209  // Specifies a command to associate with this workflow. This command is
210  // invoked when the navigation stack has changed, as a result of moving
211  // forward (or backward) to a new step.
212  // The 'object' argument is the object that will have the method called on
213  // it. The 'method' argument is the name of the method to be called and any
214  // arguments in string form. If the object is NULL, the method is still
215  // evaluated as a simple command.
216  virtual void SetNavigationStackedChangedCommand(
217  vtkObject *object, const char *method);
218  virtual void InvokeNavigationStackedChangedCommand();
219  virtual int HasNavigationStackedChangedCommand();
220 
221  // Description:
222  // Events. The NavigationStackedChangedCommand is invoked when the navigation
223  // stack has changed, as a result of moving forward (or backward) to a
224  // new step.
225  //BTX
226  enum
227  {
228  NavigationStackedChangedEvent = 10000
229  };
230  //ETX
231 
232  // Description:
233  // Callbacks.
234  virtual void TryToGoToStepCallback(
235  vtkKWWizardStep *origin, vtkKWWizardStep *destination);
236 
237  // Description:
238  // Specifies a command to associate with this state machine. This command is
239  // invoked when the state machine current state has changed.
240  // Override to allow the workflow engine to keep track of a navigation stack.
241  virtual void InvokeCurrentStateChangedCommand();
242 
243 protected:
246 
247  // Description:
248  // Remove step(s).
249  virtual void RemoveStep(vtkKWWizardStep *step);
250  virtual void RemoveAllSteps();
251 
252  // PIMPL Encapsulation for STL containers
253  //BTX
254  vtkKWWizardWorkflowInternals *Internals;
255  //ETX
256 
257  // Description:
258  // Get the goto state
260  virtual vtkKWStateMachineState* GetGoToState();
261 
263 
264  // Description:
265  // Push/pop a step to/from the navigation stack..
266  virtual void PushStepToNavigationStack(vtkKWWizardStep*);
267  virtual vtkKWWizardStep* PopStepFromNavigationStack();
268 
269 private:
270 
271  vtkKWWizardStep *FinishStep;
272 
273  vtkKWWizardWorkflow(const vtkKWWizardWorkflow&); // Not implemented
274  void operator=(const vtkKWWizardWorkflow&); // Not implemented
275 };
276 
277 #endif