KWWidgets
vtkKWThumbWheel.h
Go to the documentation of this file.
00001 /*=========================================================================
00002 
00003   Module:    $RCSfile: vtkKWThumbWheel.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 vtkKWThumbWheel - a thumbwheel widget
00015 // .SECTION Description
00016 // A widget that repsentes a thumbwheel widget with options for 
00017 // a label string and a text entry box.
00018 
00019 #ifndef __vtkKWThumbWheel_h
00020 #define __vtkKWThumbWheel_h
00021 
00022 #include "vtkKWCompositeWidget.h"
00023 
00024 class vtkKWLabel;
00025 class vtkKWEntry;
00026 class vtkKWPushButton;
00027 class vtkKWTopLevel;
00028 
00029 class KWWidgets_EXPORT vtkKWThumbWheel : public vtkKWCompositeWidget
00030 {
00031 public:
00032   static vtkKWThumbWheel* New();
00033   vtkTypeRevisionMacro(vtkKWThumbWheel,vtkKWCompositeWidget);
00034   void PrintSelf(ostream& os, vtkIndent indent);
00035 
00036   // Description:
00037   // Set/Get the value of the thumbwheel.
00038   virtual void SetValue(double v);
00039   vtkGetMacro(Value, double);
00040 
00041   // Description:
00042   // Set/Get the minimum value. The current value will be clamped only if
00043   // ClampMinimumValue is true.
00044   vtkSetMacro(MinimumValue, double);
00045   vtkGetMacro(MinimumValue, double);
00046   vtkSetMacro(ClampMinimumValue, int);
00047   vtkGetMacro(ClampMinimumValue, int);
00048   vtkBooleanMacro(ClampMinimumValue, int);  
00049 
00050   // Description:
00051   // Set/Get the maximum value. The current value will be clamped only if
00052   // ClampMaximumValue is true.
00053   vtkSetMacro(MaximumValue, double);
00054   vtkGetMacro(MaximumValue, double);
00055   vtkSetMacro(ClampMaximumValue, int);
00056   vtkGetMacro(ClampMaximumValue, int);
00057   vtkBooleanMacro(ClampMaximumValue, int);  
00058 
00059   // Description:
00060   // Set the range.
00061   virtual void SetRange(double min, double max)
00062     { this->SetMinimumValue(min); this->SetMaximumValue(max); };
00063   virtual void SetRange(const double *range) 
00064     { this->SetRange(range[0], range[1]); };
00065 
00066   // Description:
00067   // Set/Get the resolution of the thumbwheel. Moving the thumbwheel will
00068   // increase/decrease the value by an amount proportional to this resolution.
00069   // If the Clamp option is set, then the value will always be an integer 
00070   // number of increments of Resolution offset from the MinimumValue; for 
00071   // example, if the MinimumValue is -0.5 and the MaximumValue is 1.0 and 
00072   // the Resolution is set to .75, then Value can only be -0.5, 0.25, or 1.0.
00073   virtual void SetResolution(double r);
00074   vtkGetMacro(Resolution, double);
00075   vtkSetMacro(ClampResolution, int);
00076   vtkGetMacro(ClampResolution, int);
00077   vtkBooleanMacro(ClampResolution, int);  
00078   
00079   // Description:
00080   // Set the interaction modes (mode 0 is left button, 1 is middle, 
00081   // 2 is right). 
00082   // Note: set it before setting the balloon help string.
00083   //BTX
00084   enum
00085   {
00086     InteractionModeNone = 0,
00087     InteractionModeLinearMotion,
00088     InteractionModeNonLinearMotion,
00089     InteractionModeToggleCenterIndicator
00090   };
00091   //ETX
00092   virtual void SetInteractionMode(int mode, int v);
00093   virtual int GetInteractionMode(int mode);
00094   virtual void SetInteractionModeToNone(int mode) 
00095     { this->SetInteractionMode(
00096       mode, vtkKWThumbWheel::InteractionModeNone); };
00097   virtual void SetInteractionModeToLinear(int mode) 
00098     { this->SetInteractionMode(
00099       mode, vtkKWThumbWheel::InteractionModeLinearMotion); };
00100   virtual void SetInteractionModeToNonLinear(int mode) 
00101     { this->SetInteractionMode(
00102       mode, vtkKWThumbWheel::InteractionModeNonLinearMotion); };
00103   virtual void SetInteractionModeToToggleCenterIndicator(int mode) 
00104     { this->SetInteractionMode(
00105       mode, vtkKWThumbWheel::InteractionModeToggleCenterIndicator); };
00106   virtual char *GetInteractionModeAsString(int mode);
00107 
00108   // Description:
00109   // Set/Get the % of the thumbwheel's current width that must be "travelled"
00110   // by the mouse so that the value is increased/decreased by one resolution 
00111   // unit (Resolution ivar). Linear mode only.
00112   // Example: if the threshold is 0.1, the current width is 100 pixels and
00113   // the resolution is 2, then the mouse must be moved 10 pixels to "the right"
00114   // to add 2 to the current value.
00115   // If set to 0, a reasonable value will be picked computed from the
00116   // whole range and the resolution.
00117   vtkSetClampMacro(LinearThreshold, double, 0.0, 1.0);
00118   vtkGetMacro(LinearThreshold, double);
00119 
00120   // Description:
00121   // Set/Get the maximum multiplier in non-linear mode. This bounds the 
00122   // scaling factor applied to the resolution when the thumbwheel is reaching
00123   // its maximum left or right position.
00124   vtkSetMacro(NonLinearMaximumMultiplier, double);
00125   vtkGetMacro(NonLinearMaximumMultiplier, double);
00126 
00127   // Description:
00128   // Set/Get the width and height of the thumbwheel. Can't be smaller than 5x5.
00129   virtual void SetThumbWheelWidth(int v);
00130   vtkGetMacro(ThumbWheelWidth, int);
00131   virtual void SetThumbWheelHeight(int v);
00132   vtkGetMacro(ThumbWheelHeight, int);
00133   virtual void SetThumbWheelSize(int w, int h) 
00134     { this->SetThumbWheelWidth(w); this->SetThumbWheelHeight(h); };
00135   virtual void SetLength(int v) { this->SetThumbWheelWidth(v); };
00136 
00137   // Description:
00138   // Enable/Disable automatic thumbwheel resizing. Turn it off if you want
00139   // a specific thumbwheel size, otherwise it will resize when its parent
00140   // widget expands. Note that the ThumbWheelWidth and ThumbWheelHeight ivars
00141   // are  updated accordingly automatically.
00142   virtual void SetResizeThumbWheel(int flag);
00143   vtkGetMacro(ResizeThumbWheel, int);
00144   vtkBooleanMacro(ResizeThumbWheel, int);
00145 
00146   // Description:
00147   // Display/Hide a thumbwheel position indicator when the user performs a 
00148   // motion. This is just a vertical colored bar following the mouse position.
00149   // Set/Get the indicator color.
00150   vtkSetMacro(DisplayThumbWheelPositionIndicator, int);
00151   vtkGetMacro(DisplayThumbWheelPositionIndicator, int);
00152   vtkBooleanMacro(DisplayThumbWheelPositionIndicator, int);  
00153   vtkSetVector3Macro(ThumbWheelPositionIndicatorColor, double);
00154   vtkGetVectorMacro(ThumbWheelPositionIndicatorColor, double, 3);
00155 
00156   // Description:
00157   // Display/Hide a centrer indicator so that the user can easily find the
00158   // positive and negative part of the range.
00159   virtual void SetDisplayThumbWheelCenterIndicator(int flag);
00160   vtkGetMacro(DisplayThumbWheelCenterIndicator, int);
00161   vtkBooleanMacro(DisplayThumbWheelCenterIndicator, int);  
00162   virtual void ToggleDisplayThumbWheelCenterIndicator();
00163 
00164   // Description:
00165   // Set/Get the average size (in pixels) of the notches on the visible part
00166   // of the thumbwheel. Can be a decimal value, since it's only used to compute
00167   // the number of notches to display depending on the current thumbwheel size.
00168   virtual void SetSizeOfNotches(double v);
00169   vtkGetMacro(SizeOfNotches, double);
00170 
00171   // Description:
00172   // Display/Hide an entry field (optional).
00173   virtual void SetDisplayEntry(int flag);
00174   vtkGetMacro(DisplayEntry, int);
00175   vtkBooleanMacro(DisplayEntry, int);  
00176   vtkGetObjectMacro(Entry, vtkKWEntry);
00177 
00178   // Description:
00179   // Display/Hide/Set a label (optional).
00180   virtual void SetDisplayLabel(int flag);
00181   vtkGetMacro(DisplayLabel, int);
00182   vtkBooleanMacro(DisplayLabel, int);  
00183   virtual vtkKWLabel* GetLabel();
00184 
00185   // Description:
00186   // Set/Get the position of the label and/or entry (on top, or on the side).
00187   virtual void SetDisplayEntryAndLabelOnTop(int flag);
00188   vtkGetMacro(DisplayEntryAndLabelOnTop, int);
00189   vtkBooleanMacro(DisplayEntryAndLabelOnTop, int);  
00190 
00191   // Description:
00192   // Set/Get the popup mode.
00193   // WARNING: this mode must be set *before* Create() is called.
00194   vtkSetMacro(PopupMode, int);
00195   vtkGetMacro(PopupMode, int);
00196   vtkBooleanMacro(PopupMode, int);  
00197   vtkGetObjectMacro(PopupPushButton, vtkKWPushButton);
00198 
00199   // Description:
00200   // Set/Get the entry expansion flag. This flag is only used if PopupMode 
00201   // is On. In that case, the default behaviour is to provide a widget as 
00202   // compact as possible, i.e. the Entry won't be expanded if the widget grows.
00203   // Set ExpandEntry to On to override this behaviour.
00204   virtual void SetExpandEntry(int flag);
00205   vtkGetMacro(ExpandEntry, int);
00206   vtkBooleanMacro(ExpandEntry, int);  
00207 
00208   // Description:
00209   // Specifies commands to associate with the widget. 
00210   // 'Command' is invoked when the widget value is changing (i.e. during
00211   // user interaction).
00212   // 'StartCommand' is invoked at the beginning of a user interaction with
00213   // the widget (when a mouse button is pressed over the widget for example).
00214   // 'EndCommand' is invoked at the end of the user interaction with the 
00215   // widget (when the mouse button is released for example).
00216   // 'EntryCommand' is invoked when the widget value is changed using
00217   // the text entry.
00218   // The need for a 'Command', 'StartCommand' and 'EndCommand' can be
00219   // explained as follows: 'EndCommand' can be used to be notified about any
00220   // changes made to this widget *after* the corresponding user interaction has
00221   // been performed (say, after releasing the mouse button that was dragging
00222   // a slider, or after clicking on a checkbutton). 'Command' can be set
00223   // *additionally* to be notified about the intermediate changes that
00224   // occur *during* the corresponding user interaction (say, *while* dragging
00225   // a slider). While setting 'EndCommand' is enough to be notified about
00226   // any changes, setting 'Command' is an application-specific choice that
00227   // is likely to depend on how fast you want (or can) answer to rapid changes
00228   // occuring during a user interaction, if any. 'StartCommand' is rarely
00229   // used but provides an opportunity for the application to modify its
00230   // state and prepare itself for user-interaction; in that case, the
00231   // 'EndCommand' is usually set in a symmetric fashion to set the application
00232   // back to its previous state.
00233   // The 'object' argument is the object that will have the method called on
00234   // it. The 'method' argument is the name of the method to be called and any
00235   // arguments in string form. If the object is NULL, the method is still
00236   // evaluated as a simple command. 
00237   // The following parameters are also passed to the command:
00238   // - the current value: int (if Resolution is integer); double otherwise
00239   //   Note: the 'int' signature is for convenience, so that the command can
00240   //   be set to a callback accepting 'int'. In doubt, implement the callback
00241   //   using a 'double' signature that will accept both 'int' and 'double'.
00242   virtual void SetCommand(vtkObject *object, const char *method);
00243   virtual void SetStartCommand(vtkObject *object, const char *method);
00244   virtual void SetEndCommand(vtkObject *object, const char *method);
00245   virtual void SetEntryCommand(vtkObject *object, const char *method);
00246 
00247   // Description:
00248   // Events. The ThumbWheelValueChangingEvent is triggered when the widget 
00249   // value is changed (i.e., during user interaction on the widget's 
00250   // thumbhweel), the ThumbWheelValueStartChangingEvent is invoked at the 
00251   // beginning of an interaction with the widget, the 
00252   // ThumbWheelValueChangedEvent is invoked at the end of an interaction with
00253   // the widget. They are similar in concept as the 'Command', 'StartCommand', 
00254   // and 'EndCommand' callbacks but can be used by multiple listeners/observers
00255   // at a time.
00256   // The following parameters are also passed as client data:
00257   // - the current value: double
00258   //BTX
00259   enum
00260   {
00261     ThumbWheelValueChangingEvent = 10000,
00262     ThumbWheelValueChangedEvent,
00263     ThumbWheelValueStartChangingEvent
00264   };
00265   //ETX
00266 
00267   // Description:
00268   // Setting this string enables balloon help for this widget.
00269   // Override to pass down to children for cleaner behavior.
00270   virtual void SetBalloonHelpString(const char *str);
00271 
00272   // Description:
00273   // Bind/Unbind all components so that values can be changed, but
00274   // no command will be called.
00275   void Bind();
00276   void UnBind();
00277 
00278   // Description:
00279   // Update the "enable" state of the object and its internal parts.
00280   // Depending on different Ivars (this->Enabled, the application's 
00281   // Limited Edition Mode, etc.), the "enable" state of the object is updated
00282   // and propagated to its internal parts/subwidgets. This will, for example,
00283   // enable/disable parts of the widget UI, enable/disable the visibility
00284   // of 3D widgets, etc.
00285   virtual void UpdateEnableState();
00286 
00287   // Description:
00288   // Callbacks. Internal, do not use.
00289   virtual void ResizeThumbWheelCallback();
00290   virtual void DisplayPopupCallback();
00291   virtual void WithdrawPopupCallback();
00292   virtual void EntryValueCallback(const char*);
00293   virtual void StartLinearMotionCallback();
00294   virtual void PerformLinearMotionCallback();
00295   virtual void StartNonLinearMotionCallback();
00296   virtual void PerformNonLinearMotionCallback();
00297   virtual void StopMotionCallback();
00298 
00299 protected:
00300   vtkKWThumbWheel();
00301   ~vtkKWThumbWheel();
00302 
00303   // Description:
00304   // Create the widget.
00305   virtual void CreateWidget();
00306 
00307   double      Value;
00308   double      MinimumValue;
00309   int         ClampMinimumValue;
00310   double      MaximumValue;
00311   int         ClampMaximumValue;
00312   double      Resolution;
00313   int         ClampResolution;
00314   double      NonLinearMaximumMultiplier;
00315   double      LinearThreshold;
00316 
00317   int         ThumbWheelWidth;
00318   int         ThumbWheelHeight;
00319   double      SizeOfNotches;
00320   double      ThumbWheelPositionIndicatorColor[3];
00321 
00322   int         ResizeThumbWheel;
00323   int         DisplayLabel;
00324   int         DisplayEntry;
00325   int         DisplayEntryAndLabelOnTop;
00326   int         DisplayThumbWheelPositionIndicator;
00327   int         DisplayThumbWheelCenterIndicator;
00328   int         PopupMode;
00329   int         ExpandEntry;
00330 
00331   char        *Command;
00332   char        *StartCommand;
00333   char        *EndCommand;
00334   char        *EntryCommand;
00335 
00336   virtual void InvokeThumbWheelCommand(const char *command, double value);
00337   virtual void InvokeCommand(double value);
00338   virtual void InvokeStartCommand(double value);
00339   virtual void InvokeEndCommand(double value);
00340   virtual void InvokeEntryCommand(double value);
00341 
00342   double      ThumbWheelShift;
00343 
00344   int         InteractionModes[3];
00345 
00346   vtkKWLabel    *ThumbWheel;
00347   vtkKWEntry    *Entry;
00348   vtkKWLabel    *Label;
00349   vtkKWTopLevel *TopLevel;
00350   vtkKWPushButton *PopupPushButton;
00351 
00352   void CreateEntry();
00353   void CreateLabel();
00354   void UpdateThumbWheelImage(double pos = -1.0);
00355   void PackWidget();
00356   double GetMousePositionInThumbWheel();
00357 
00358   //BTX
00359 
00360   int State;
00361   enum WidgetState
00362   {
00363     Idle,
00364     InMotion
00365   };
00366   
00367   class LinearMotionState
00368   {
00369   public:
00370     double Value;
00371     double ThumbWheelShift;
00372     double MousePosition;
00373     int InPerform;
00374   };
00375 
00376   class NonLinearMotionState
00377   {
00378   public:
00379     double Value;
00380     double Increment;
00381     int InPerform;
00382   };
00383   //ETX
00384 
00385   LinearMotionState StartLinearMotionState;
00386   NonLinearMotionState StartNonLinearMotionState;
00387 
00388   int InInvokeCommand;
00389 
00390   void RefreshValue();
00391 
00392 private:
00393   vtkKWThumbWheel(const vtkKWThumbWheel&); // Not implemented
00394   void operator=(const vtkKWThumbWheel&); // Not implemented
00395 };
00396 
00397 #endif
00398