KWWidgets
vtkKWWizardWidget.h
Go to the documentation of this file.
00001 /*=========================================================================
00002 
00003   Module:    $RCSfile: vtkKWWizardWidget.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 vtkKWWizardWidget - a superclass for creating wizards UI.
00015 // .SECTION Description
00016 // This class is the basis for a wizard widget/dialog. It embeds a
00017 // wizard workflow (i.e. a state machine) and tie it to navigation buttons.
00018 // This widget can be inserted directly inside another user interface;
00019 // most of the time, however, people will use a vtkKWWizardDialog, which
00020 // is just an independent toplevel embedding a vtkKWWizardWidget.
00021 // .SECTION Thanks
00022 // This work is part of the National Alliance for Medical Image
00023 // Computing (NAMIC), funded by the National Institutes of Health
00024 // through the NIH Roadmap for Medical Research, Grant U54 EB005149.
00025 // Information on the National Centers for Biomedical Computing
00026 // can be obtained from http://nihroadmap.nih.gov/bioinformatics.
00027 // .SECTION See Also
00028 // vtkKWWizardDialog vtkKWWizardStep vtkKWWizardWorkflow
00029 
00030 #ifndef __vtkKWWizardWidget_h
00031 #define __vtkKWWizardWidget_h
00032 
00033 #include "vtkKWCompositeWidget.h"
00034 
00035 class vtkKWPushButton;
00036 class vtkKWLabel;
00037 class vtkKWLabelWithLabel;
00038 class vtkKWFrame;
00039 class vtkKWSeparator;
00040 class vtkKWWizardWorkflow;
00041 
00042 class KWWidgets_EXPORT vtkKWWizardWidget : public vtkKWCompositeWidget
00043 {
00044 public:
00045   static vtkKWWizardWidget* New();
00046   vtkTypeRevisionMacro(vtkKWWizardWidget,vtkKWCompositeWidget);
00047   void PrintSelf(ostream& os, vtkIndent indent);
00048 
00049   // Description:
00050   // Get the wizard workflow instance.
00051   vtkGetObjectMacro(WizardWorkflow, vtkKWWizardWorkflow);
00052 
00053   // Description:
00054   // Get the client area. This is where user content should be placed.
00055   // A wizard workflow is made of steps (vtkKWWizardStep). Each step
00056   // should set its vtkKWWizardStep::ShowUserInterfaceCommand callback to point
00057   // to a method that will display this step's UI (or reimplement
00058   // vtkKWWizardStep::ShowUserInterface). Within that method,
00059   // all widgets should be children of this ClientArea.
00060   vtkGetObjectMacro(ClientArea, vtkKWFrame);
00061 
00062   // Description:
00063   // Set the minimum client area height. No effect if called before Create(). 
00064   virtual void SetClientAreaMinimumHeight(int);
00065 
00066   // Description:
00067   // Refresh the interface.
00068   // This important method will refresh the state of the buttons, depending
00069   // on the current workflow navigation stack. If the workflow's FinishStep
00070   // step is defined, it will invoke its CanGoToSelf method/callback to check
00071   // if it can be reached directly, and enable the Finish button accordingly.
00072   // This method should be called each time modifying the UI of the current
00073   // step may have an impact on navigating the workflow. For example, updating
00074   // the value of a specific entry may forbid the user to move to the Finish
00075   // step directly. Check the entry's API for callbacks that can
00076   // be triggered with a small granularity (vtkKWEntry::Command,
00077   // vtkKWEntry::SetCommandTriggerToAnyChange, vtkKWScale::Command, etc.).
00078   virtual void Update();
00079 
00080   // Description:
00081   // Set the title text (usually a few words), located in the top area.
00082   // Note that this method is called automatically by Update() to display
00083   // the name of the WizardWorkflow's CurrentStep() step (see the
00084   // vtkKWWizardStep::GetName() method).
00085   virtual void SetTitle(const char *);
00086   virtual char* GetTitle();
00087 
00088   // Description:
00089   // Set the subtitle text (usually a short sentence or two), located in the 
00090   // top area below the title.
00091   // Note that this method is called automatically by Update() to display
00092   // the description of the WizardWorkflow's CurrentStep() step (see the
00093   // vtkKWWizardStep::GetDescription() method).
00094   virtual void SetSubTitle(const char *);
00095   virtual char* GetSubTitle();
00096 
00097   // Description:
00098   // Set/Get the background color of the title area.
00099   virtual void GetTitleAreaBackgroundColor(double *r, double *g, double *b);
00100   virtual double* GetTitleAreaBackgroundColor();
00101   virtual void SetTitleAreaBackgroundColor(double r, double g, double b);
00102   virtual void SetTitleAreaBackgroundColor(double rgb[3])
00103     { this->SetTitleAreaBackgroundColor(rgb[0], rgb[1], rgb[2]); };
00104   
00105   // Description:
00106   // Get the wizard icon, located in the top area right of the title.
00107   // This can be used to provide a better graphical identity to the wizard.
00108   vtkGetObjectMacro(TitleIconLabel, vtkKWLabel);
00109 
00110   // Description:
00111   // Set the pre-text, i.e. the contents of a convenience text section placed
00112   // just above the client area.
00113   virtual void SetPreText(const char *);
00114   virtual char* GetPreText();
00115 
00116   // Description:
00117   // Set the post-text, i.e. the contents of a convenience text section placed
00118   // just below the client area.
00119   virtual void SetPostText(const char *);
00120   virtual char* GetPostText();
00121 
00122   // Description:
00123   // Set the error text, i.e. the contents of a convenience text section
00124   // placed just below the client area. It is prefixed with an error icon.
00125   // This is typically used by a step's vtkKWWizardStep::Validate
00126   // method/callback to report an error when validating the UI failed.
00127   virtual void SetErrorText(const char *);
00128   virtual char* GetErrorText();
00129 
00130   // Description:
00131   // Unpack all children in the client-area and set all pre-/post-/title label
00132   // to empty strings.
00133   // This is typically used by a step's 
00134   // vtkKWWizardStep::HideUserInterfaceCommand callback (or the 
00135   // vtkKWWizardStep::HideUserInterface method) to hide the step's UI
00136   // or release resources that were allocated specifically for a step's UI.
00137   virtual void ClearPage();
00138   
00139   // Description:
00140   // Set/Get the visibility of the buttons.
00141   virtual void SetBackButtonVisibility(int);
00142   vtkGetMacro(BackButtonVisibility,int);
00143   vtkBooleanMacro(BackButtonVisibility,int);
00144   virtual void SetNextButtonVisibility(int);
00145   vtkGetMacro(NextButtonVisibility,int);
00146   vtkBooleanMacro(NextButtonVisibility,int);
00147   virtual void SetFinishButtonVisibility(int);
00148   vtkGetMacro(FinishButtonVisibility,int);
00149   vtkBooleanMacro(FinishButtonVisibility,int);
00150   virtual void SetCancelButtonVisibility(int);
00151   vtkGetMacro(CancelButtonVisibility,int);
00152   vtkBooleanMacro(CancelButtonVisibility,int);
00153   virtual void SetHelpButtonVisibility(int);
00154   vtkGetMacro(HelpButtonVisibility,int);
00155   vtkBooleanMacro(HelpButtonVisibility,int);
00156   virtual void SetOKButtonVisibility(int);
00157   vtkGetMacro(OKButtonVisibility,int);
00158   vtkBooleanMacro(OKButtonVisibility,int);
00159 
00160   // Description:
00161   // Get and customize some UI elements.
00162   vtkGetObjectMacro(CancelButton, vtkKWPushButton);
00163   vtkGetObjectMacro(OKButton, vtkKWPushButton);
00164   vtkGetObjectMacro(FinishButton, vtkKWPushButton);
00165   vtkGetObjectMacro(HelpButton, vtkKWPushButton);
00166   vtkGetObjectMacro(SeparatorBeforeButtons, vtkKWSeparator);
00167   vtkGetObjectMacro(SubTitleLabel, vtkKWLabel);
00168   vtkGetObjectMacro(TitleLabel, vtkKWLabel);
00169 
00170   // Description:
00171   // If supported, set the label position in regards to the rest of
00172   // the composite widget. Check the subclass for more information about
00173   // what the Default position is, and if specific positions are supported.
00174   //BTX
00175   enum
00176   {
00177     ButtonsPositionTop = 0,
00178     ButtonsPositionBottom
00179   };
00180   //ETX
00181   virtual void SetButtonsPosition(int);
00182   vtkGetMacro(ButtonsPosition, int);
00183   virtual void SetButtonsPositionToTop()
00184     { this->SetButtonsPosition(vtkKWWizardWidget::ButtonsPositionTop); };
00185   virtual void SetButtonsPositionToBottom()
00186     { this->SetButtonsPosition(vtkKWWizardWidget::ButtonsPositionBottom); };
00187   
00188   // Description:
00189   // Add all the default observers needed by that object, or remove
00190   // all the observers that were added through AddCallbackCommandObserver.
00191   // Subclasses can override these methods to add/remove their own default
00192   // observers, but should call the superclass too.
00193   virtual void AddCallbackCommandObservers();
00194   virtual void RemoveCallbackCommandObservers();
00195 
00196   // Description:
00197   // Update the "enable" state of the object and its internal parts.
00198   // Depending on different Ivars (this->Enabled, the application's 
00199   // Limited Edition Mode, etc.), the "enable" state of the object is updated
00200   // and propagated to its internal parts/subwidgets. This will, for example,
00201   // enable/disable parts of the widget UI, enable/disable the visibility
00202   // of 3D widgets, etc.
00203   virtual void UpdateEnableState();
00204 
00205 protected:
00206   vtkKWWizardWidget();
00207   ~vtkKWWizardWidget();
00208 
00209   // Description:
00210   // Create the widget
00211   virtual void CreateWidget();
00212 
00213   // Description:
00214   // Pack the buttons.
00215   virtual void PackButtons();
00216 
00217   int ButtonsPosition;
00218 
00219   int BackButtonVisibility;
00220   int NextButtonVisibility;
00221   int FinishButtonVisibility;
00222   int CancelButtonVisibility;
00223   int HelpButtonVisibility;
00224   int OKButtonVisibility;
00225 
00226   vtkKWWizardWorkflow *WizardWorkflow;
00227 
00228   vtkKWFrame          *TitleFrame;
00229   vtkKWLabel          *TitleLabel;
00230   vtkKWLabel          *SubTitleLabel;
00231   vtkKWLabel          *TitleIconLabel;
00232   
00233   vtkKWSeparator      *SeparatorAfterTitleArea;
00234 
00235   vtkKWFrame          *LayoutFrame;
00236   vtkKWLabel          *PreTextLabel;
00237   vtkKWFrame          *ClientArea;
00238   vtkKWLabel          *PostTextLabel;
00239   vtkKWLabelWithLabel *ErrorTextLabel;
00240 
00241   vtkKWSeparator      *SeparatorBeforeButtons;
00242 
00243   vtkKWFrame          *ButtonFrame;
00244   vtkKWPushButton     *BackButton;
00245   vtkKWPushButton     *NextButton;
00246   vtkKWPushButton     *FinishButton;
00247   vtkKWPushButton     *CancelButton;
00248   vtkKWPushButton     *HelpButton;
00249   vtkKWPushButton     *OKButton;
00250 
00251   // Description:
00252   // Processes the events that are passed through CallbackCommand (or others).
00253   // Subclasses can oberride this method to process their own events, but
00254   // should call the superclass too.
00255   virtual void ProcessCallbackCommandEvents(
00256     vtkObject *caller, unsigned long event, void *calldata);
00257   
00258 private:
00259   vtkKWWizardWidget(const vtkKWWizardWidget&); // Not implemented
00260   void operator=(const vtkKWWizardWidget&); // Not Implemented
00261 };
00262 
00263 #endif