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