KWWidgets
vtkKWWizardStep.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: $RCSfile: vtkKWWizardStep.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 vtkKWWizardStep - a wizard step.
15 // .SECTION Description
16 // This class is the basis for a wizard step. A wizard step is a
17 // placeholder for various states, transitions and inputs that are used
18 // in a typical wizard workflow. Such steps can be added to instances of
19 // the vtkKWWizardWorkflow class (subclass of vtkKWStateMachine).
20 // A wizard workflow can be manipulated from a user interface through either
21 // the vtkKWWizardWidget or vtkKWWizardDialog classes.
22 // .SECTION Thanks
23 // This work is part of the National Alliance for Medical Image
24 // Computing (NAMIC), funded by the National Institutes of Health
25 // through the NIH Roadmap for Medical Research, Grant U54 EB005149.
26 // Information on the National Centers for Biomedical Computing
27 // can be obtained from http://nihroadmap.nih.gov/bioinformatics.
28 // .SECTION See Also
29 // vtkKWWizardWorkflow vtkKWStateMachine vtkKWWizardWidget vtkKWWizardDialog
30 
31 #ifndef __vtkKWWizardStep_h
32 #define __vtkKWWizardStep_h
33 
34 #include "vtkKWObject.h"
35 
39 
40 //BTX
42 {
43 public:
46 };
47 //ETX
48 
50 {
51 public:
52  static vtkKWWizardStep* New();
53  vtkTypeRevisionMacro(vtkKWWizardStep, vtkKWObject);
54  void PrintSelf(ostream& os, vtkIndent indent);
55 
56  // Description:
57  // Get id.
58  vtkGetMacro(Id, vtkIdType);
59 
60  // Description:
61  // Set/Get simple name.
62  vtkGetStringMacro(Name);
63  vtkSetStringMacro(Name);
64 
65  // Description:
66  // Set/Get short description.
67  vtkGetStringMacro(Description);
68  vtkSetStringMacro(Description);
69 
70  // Description:
71  // Show the user interface associated to that step. Wizard developpers can
72  // either reimplement the ShowUserInterface method in a vtkKWWizardStep
73  // subclass (*do* call the superclass' ShowUserInterface first), or create a
74  // vtkKWWizardStep instance and set the ShowUserInterfaceCommand to point to
75  // a callback of their choice.
76  // Either ways, these methods will be invoked automatically when the state
77  // machine enters the step's InteractionState state.
78  // The 'object' argument is the object that will have the method called on
79  // it. The 'method' argument is the name of the method to be called and any
80  // arguments in string form. If the object is NULL, the method is still
81  // evaluated as a simple command.
82  virtual void ShowUserInterface();
83  virtual void SetShowUserInterfaceCommand(
84  vtkObject *object, const char *method);
85  virtual void InvokeShowUserInterfaceCommand();
86  virtual int HasShowUserInterfaceCommand();
87 
88  // Description:
89  // Events.
90  //BTX
91  enum
92  {
93  ShowUserInterfaceEvent = 10000,
94  HideUserInterfaceEvent,
95  ValidateEvent
96  };
97  //ETX
98 
99 
100  // Description:
101  // Hide the user interface associated to that step. Wizard developpers can
102  // either reimplement the HideUserInterface method in a vtkKWWizardStep
103  // subclass (*do* call the superclass' HideUserInterface first), or create a
104  // vtkKWWizardStep instance and set the HideUserInterfaceCommand to point to
105  // a callback of their choice.
106  // Either ways, these methods will be invoked automatically by transitions
107  // that move the state machine from one step to another step, such as the
108  // ones created by the vtkKWWizardWorkflow::AddNextStep(),
109  // vtkKWWizardWorkflow::CreateNextTransition() or
110  // vtkKWWizardWorkflow::CreateBackTransition() methods.
111  // While this method/callback can be used to release resources that were
112  // allocated specifically for a step's UI, calling the
113  // vtkKWWizardWidget::ClearPage() method will do the trick most of the time
114  // when the wizard workflow is working in conjunction with a
115  // vtkKWWizardWidget.
116  // The 'object' argument is the object that will have the method called on
117  // it. The 'method' argument is the name of the method to be called and any
118  // arguments in string form. If the object is NULL, the method is still
119  // evaluated as a simple command.
120  virtual void HideUserInterface();
121  virtual void SetHideUserInterfaceCommand(
122  vtkObject *object, const char *method);
123  virtual void InvokeHideUserInterfaceCommand();
124  virtual int HasHideUserInterfaceCommand();
125 
126  // Description:
127  // Validate the user interface associated to that step. Wizard developpers
128  // can either reimplement the Validate method in a
129  // vtkKWWizardStep subclass (*do* call the superclass' Validate
130  // first), or create a vtkKWWizardStep instance and set the
131  // ValidateCommand to point to a callback of their choice.
132  // Either ways, these important methods are called when the
133  // ValidationTransition transition is triggered by the ValidationInput input,
134  // effectively moving the state machine from the InteractionState state to
135  // the ValidationState state.
136  // It is the responsibility of this method/callback to push inputs that will
137  // move the state machine to the next step (using the
138  // ValidationSucceededInput input for example), or back to the
139  // InteractionState on error (using the ValidationFailedInput input and the
140  // ValidationFailedTransition transition). User-defined inputs can be
141  // pushed as well if the step has potentially multiple "valid" next steps.
142  // Pushing the ValidationSucceededInput input will trigger transitions
143  // such as the one created by the vtkKWWizardWorkflow::AddNextStep() or
144  // vtkKWWizardWorkflow::CreateNextTransition() methods.
145  // The 'object' argument is the object that will have the method called on
146  // it. The 'method' argument is the name of the method to be called and any
147  // arguments in string form. If the object is NULL, the method is still
148  // evaluated as a simple command.
149  virtual void Validate();
150  virtual void SetValidateCommand(vtkObject *object, const char *method);
151  virtual void InvokeValidateCommand();
152  virtual int HasValidateCommand();
153 
154  // Description:
155  // Check if one can go directly to this step, given the model associated
156  // to the wizard workflow. Wizard developpers can either reimplement the
157  // CanGoToSelf method in a vtkKWWizardStep subclass (*do* check if
158  // the CanGoToSelfCommand is set though, and invoke it in priority), or
159  // create a vtkKWWizardStep instance and
160  // set the CanGoToSelfCommand to point to a callback of their choice.
161  // Either ways, these methods can be used when there is a need to know
162  // if one can go directly to this step, effectively bypassing all others
163  // steps: this should be used *very* carefully, and is provided to
164  // implement features such as the "Finish" button in a wizard widget.
165  // This method/command should return 1 if the step can be reached, 0
166  // otherwise.
167  // The 'object' argument is the object that will have the method called on
168  // it. The 'method' argument is the name of the method to be called and any
169  // arguments in string form. If the object is NULL, the method is still
170  // evaluated as a simple command.
171  virtual int CanGoToSelf();
172  virtual void SetCanGoToSelfCommand(vtkObject *object, const char *method);
173  virtual int InvokeCanGoToSelfCommand();
174  virtual int HasCanGoToSelfCommand();
175 
176  // Description:
177  // Get the step's interaction state. This state is used to
178  // display the user interface pertaining to this step, then wait for more
179  // user inputs. Note that this class listens to the InteractionState's
180  // vtkKWStateMachineState::EnterEvent event; as this event is triggered, the
181  // ShowUserInterface() method is automatically called (hence the
182  // InvokeShowUserInterfaceCommand() as well).
183  // Access to this state is given for advanced customization. In the vast
184  // majority of wizards, it should be ignored; the ShowUserInterface method
185  // or callback is however the key component to define for this state to work
186  // as expected.
187  virtual vtkKWStateMachineState* GetInteractionState();
188 
189  // Description:
190  // Get the step's validation state. This state is used to validate the user
191  // interface pertaining to this step (as displayed by the InteractionState
192  // state), then branch to the next step's InteractionState state on success,
193  // or back to the current step's InteractionState state on error. The state
194  // acts as a hub: the validation itself is performed by the
195  // ValidateCommand callback (or Validate method for the corresponding
196  // step) attached to the ValidationTransition
197  // transition that sits between the InteractionState state and the
198  // ValidationState state.
199  // Access to this state is given for advanced customization. In the vast
200  // majority of wizards, it should be ignored; the ValidateCommand (or
201  // the Validate method) is however the key component to define for this
202  // state to work as expected.
203  virtual vtkKWStateMachineState* GetValidationState();
204 
205  // Description:
206  // Get the step's validation transition. This transition is used to validate
207  // the user interface pertaining to this step (as displayed by the
208  // InteractionState state), then branch to the next step's InteractionState
209  // state on success, or back to the current step's InteractionState state
210  // on error. More specifically:
211  // - its originating state is the InteractionState state,
212  // - its destination state is the ValidationState state,
213  // - it is triggered by the ValidationInput input.
214  // Note that this class listens to the ValidationTransition's
215  // vtkKWStateMachineTransition::EndEvent event; as this even is triggered,
216  // the Validate() method is automatically called (hence the
217  // InvokeValidateCommand() method as well).
218  // Wizard developpers reimplement the Validate method or can set
219  // ValidateCommand to point to a method of their choice to validate the
220  // step's UI; it will be invoked automatically when the state machine
221  // triggers the ValidationTransition transition.
222  // The wizard workflow (or wizard widget) will typically push a
223  // ValidationInput input on the queue to request a step to be validated
224  // and move to the next step. If the state machine is at an InteractionState
225  // state, the corresponding step's ValidationTransition transition will be
226  // triggered, the state machine will move to the ValidationState state and
227  // validation will occur through the ValidateCommand callback or Validate
228  // method. This method/callback will push inputs that in turn will move the
229  // state machine to the next step (using the ValidationSucceededInput input
230  // for example), or back to the InteractionState on error (using the
231  // ValidationFailedInput input and the ValidationFailedTransition
232  // transition).
233  // Access to this transition is given for advanced customization. In the vast
234  // majority of wizards, it should be ignored; the ValidateCommand (or
235  // Validate method) is however the key component to define for this
236  // transition to work as expected, since it is where the
237  // ValidationSucceededInput, ValidationFailedInput and user-defined inputs
238  // should be pushed.
239  virtual vtkKWStateMachineTransition* GetValidationTransition();
240 
241  // Description:
242  // Get the step's validation input. This singleton input is used to trigger
243  // the ValidationTransition transition and move the state machine from the
244  // InteractionState state to the ValidationState state.
245  // Access to this input is given for advanced customization. In the vast
246  // majority of wizards, it should be ignored; the wizard workflow (or
247  // wizard widget) will typically push a ValidationInput input on the queue
248  // to request a step to be validated and move to the next step. If the state
249  // machine is at an InteractionState state, the corresponding step's
250  // ValidationTransition transition will be triggered, the state machine will
251  // move to the ValidationState state and validation will occur through the
252  // ValidateCommand callback (or Validate method).
253  static vtkKWStateMachineInput* GetValidationInput();
254 
255  // Description:
256  // Get the step's validation successful input. This singleton input is used
257  // in the ValidateCommand callback and in conjunction with the
258  // workflow class (vtkKWWizardWorkflow) to trigger a transition from the
259  // step's ValidationState state to the next step's InteractionState state.
260  // It is, as far as the workflow is concerned, the input that moves
261  // the state machine from one step to the other. The corresponding
262  // transition can be created automatically by the
263  // vtkKWWizardWorkflow::AddNextStep() or
264  // vtkKWWizardWorkflow::CreateNextTransition() methods.
265  // The ValidateCommand callback (or Validate method) is the key component
266  // where this input is used.
267  static vtkKWStateMachineInput* GetValidationSucceededInput();
268 
269  // Description:
270  // Get the step's validation failed input. This singleton input is used
271  // in the ValidateCommand callback (or Validate method) and in conjunction
272  // with the workflow class (vtkKWWizardWorkflow) to trigger the
273  // ValidationFailedTransition transition from the step's ValidationState
274  // state back to the step's InteractionState state.
275  // The ValidateCommand callback (or Validate method) is the key component
276  // where this input is used.
277  static vtkKWStateMachineInput* GetValidationFailedInput();
278 
279  // Description:
280  // Get the step's validation failed transition. This transition is used
281  // to bring the state machine from the ValidationState state back to the
282  // InteractionState state, when validation of the user interface pertaining
283  // to this step failed (as displayed by the InteractionState state).
284  // More specifically:
285  // - its originating state is the ValidationState state,
286  // - its destination state is the InteractionState state,
287  // - it is triggered by the ValidationFailedInput input.
288  // Important: it is up to the wizard developpers to push the
289  // ValidationFailedInput input on the state machine queue *from* the
290  // ValidateCommand callback (or Validate method) for the state machine to
291  // trigger that transition and go back to the InteractionState state.
292  // Access to this transition is given for advanced customization. In the vast
293  // majority of wizards, it should be ignored; the ValidateCommand callback
294  // (or Validate method) is the key component to define for this transition
295  // to work as expected, since it is where the ValidationFailedInput input
296  // should be pushed.
297  virtual vtkKWStateMachineTransition* GetValidationFailedTransition();
298 
299  // Description:
300  // Get the step's go to self input. This input is used to trigger
301  // transition that are meant to move the state machine directly to this step,
302  // effectively bypassing all others steps: this should be used very
303  // carefully, and is provided only to implement features such as the
304  // "Finish" button in a wizard widget.
305  // Access to this input is given for advanced customization. In the vast
306  // majority of wizards, it should be ignored; it is used by the
307  // vtkKWWizardWorkflow::CreateGoToTransition() method to implement
308  // transitions to specific steps directly (the "Finish" step, for example).
309  virtual vtkKWStateMachineInput* GetGoToSelfInput();
310 
311  // Description:
312  // Get the step's go back to self input. This input is used to trigger
313  // transitions that are meant to move the state machine back to the
314  // previous step (if any): this should be used very carefully, and is
315  // provided only to implement features such as the "Back" or "Finish" button
316  // in a wizard widget.
317  // Access to this input is given for advanced customization. In the vast
318  // majority of wizards, it should be ignored; it is used by the
319  // vtkKWWizardWorkflow::CreateBackTransition() method to implement
320  // transitions back to specific steps directly.
321  virtual vtkKWStateMachineInput* GetGoBackToSelfInput();
322 
323  // Description:
324  // Add all the default observers needed by that object, or remove
325  // all the observers that were added through AddCallbackCommandObserver.
326  // Subclasses can override these methods to add/remove their own default
327  // observers, but should call the superclass too.
328  virtual void RemoveCallbackCommandObservers();
329 
330 protected:
331  vtkKWWizardStep();
332  ~vtkKWWizardStep();
333 
334  vtkIdType Id;
335  char *Name;
336  char *Description;
337 
338  char *ShowUserInterfaceCommand;
339  char *HideUserInterfaceCommand;
340  char *ValidateCommand;
341  char *CanGoToSelfCommand;
342 
343  // Description:
344  // Processes the events that are passed through CallbackCommand (or others).
345  // Subclasses can oberride this method to process their own events, but
346  // should call the superclass too.
347  virtual void ProcessCallbackCommandEvents(
348  vtkObject *caller, unsigned long event, void *calldata);
349 
350 private:
351 
352  vtkKWStateMachineState *InteractionState;
353  vtkKWStateMachineState *ValidationState;
354 
355  vtkKWStateMachineTransition *ValidationTransition;
356  vtkKWStateMachineTransition *ValidationFailedTransition;
357 
358  vtkKWStateMachineInput *GoToSelfInput;
359  vtkKWStateMachineInput *GoBackToSelfInput;
360 
361  static vtkIdType IdCounter;
362 
363  static vtkKWStateMachineInput *ValidationInput;
364  static vtkKWStateMachineInput *ValidationSucceededInput;
365  static vtkKWStateMachineInput *ValidationFailedInput;
366 
367  //BTX
368  // Used to delete our singletons.
369  static vtkKWWizardStepCleanup Cleanup;
370  friend class vtkKWWizardStepCleanup;
371  //ETX
372 
373  static void SetValidationInput(vtkKWStateMachineInput*);
374  static void SetValidationSucceededInput(vtkKWStateMachineInput*);
375  static void SetValidationFailedInput(vtkKWStateMachineInput*);
376 
377  vtkKWWizardStep(const vtkKWWizardStep&); // Not implemented
378  void operator=(const vtkKWWizardStep&); // Not implemented
379 };
380 
381 #endif