KWWidgets
debian/tmp/usr/include/KWWidgets/vtkKWThumbWheel.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: $RCSfile: vtkKWThumbWheel.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 vtkKWThumbWheel - a thumbwheel widget
15 // .SECTION Description
16 // A widget that repsentes a thumbwheel widget with options for
17 // a label string and a text entry box.
18 
19 #ifndef __vtkKWThumbWheel_h
20 #define __vtkKWThumbWheel_h
21 
22 #include "vtkKWCompositeWidget.h"
23 
24 class vtkKWLabel;
25 class vtkKWEntry;
26 class vtkKWPushButton;
27 class vtkKWTopLevel;
28 
30 {
31 public:
32  static vtkKWThumbWheel* New();
33  vtkTypeRevisionMacro(vtkKWThumbWheel,vtkKWCompositeWidget);
34  void PrintSelf(ostream& os, vtkIndent indent);
35 
36  // Description:
37  // Set/Get the value of the thumbwheel.
38  virtual void SetValue(double v);
39  vtkGetMacro(Value, double);
40 
41  // Description:
42  // Set/Get the minimum value. The current value will be clamped only if
43  // ClampMinimumValue is true.
44  vtkSetMacro(MinimumValue, double);
45  vtkGetMacro(MinimumValue, double);
46  vtkSetMacro(ClampMinimumValue, int);
47  vtkGetMacro(ClampMinimumValue, int);
48  vtkBooleanMacro(ClampMinimumValue, int);
49 
50  // Description:
51  // Set/Get the maximum value. The current value will be clamped only if
52  // ClampMaximumValue is true.
53  vtkSetMacro(MaximumValue, double);
54  vtkGetMacro(MaximumValue, double);
55  vtkSetMacro(ClampMaximumValue, int);
56  vtkGetMacro(ClampMaximumValue, int);
57  vtkBooleanMacro(ClampMaximumValue, int);
58 
59  // Description:
60  // Set the range.
61  virtual void SetRange(double min, double max)
62  { this->SetMinimumValue(min); this->SetMaximumValue(max); };
63  virtual void SetRange(const double *range)
64  { this->SetRange(range[0], range[1]); };
65 
66  // Description:
67  // Set/Get the resolution of the thumbwheel. Moving the thumbwheel will
68  // increase/decrease the value by an amount proportional to this resolution.
69  // If the Clamp option is set, then the value will always be an integer
70  // number of increments of Resolution offset from the MinimumValue; for
71  // example, if the MinimumValue is -0.5 and the MaximumValue is 1.0 and
72  // the Resolution is set to .75, then Value can only be -0.5, 0.25, or 1.0.
73  virtual void SetResolution(double r);
74  vtkGetMacro(Resolution, double);
75  vtkSetMacro(ClampResolution, int);
76  vtkGetMacro(ClampResolution, int);
77  vtkBooleanMacro(ClampResolution, int);
78 
79  // Description:
80  // Set the interaction modes (mode 0 is left button, 1 is middle,
81  // 2 is right).
82  // Note: set it before setting the balloon help string.
83  //BTX
84  enum
85  {
86  InteractionModeNone = 0,
89  InteractionModeToggleCenterIndicator
90  };
91  //ETX
92  virtual void SetInteractionMode(int mode, int v);
93  virtual int GetInteractionMode(int mode);
94  virtual void SetInteractionModeToNone(int mode)
95  { this->SetInteractionMode(
97  virtual void SetInteractionModeToLinear(int mode)
98  { this->SetInteractionMode(
100  virtual void SetInteractionModeToNonLinear(int mode)
101  { this->SetInteractionMode(
103  virtual void SetInteractionModeToToggleCenterIndicator(int mode)
104  { this->SetInteractionMode(
106  virtual char *GetInteractionModeAsString(int mode);
107 
108  // Description:
109  // Set/Get the % of the thumbwheel's current width that must be "travelled"
110  // by the mouse so that the value is increased/decreased by one resolution
111  // unit (Resolution ivar). Linear mode only.
112  // Example: if the threshold is 0.1, the current width is 100 pixels and
113  // the resolution is 2, then the mouse must be moved 10 pixels to "the right"
114  // to add 2 to the current value.
115  // If set to 0, a reasonable value will be picked computed from the
116  // whole range and the resolution.
117  vtkSetClampMacro(LinearThreshold, double, 0.0, 1.0);
118  vtkGetMacro(LinearThreshold, double);
119 
120  // Description:
121  // Set/Get the maximum multiplier in non-linear mode. This bounds the
122  // scaling factor applied to the resolution when the thumbwheel is reaching
123  // its maximum left or right position.
124  vtkSetMacro(NonLinearMaximumMultiplier, double);
125  vtkGetMacro(NonLinearMaximumMultiplier, double);
126 
127  // Description:
128  // Set/Get the width and height of the thumbwheel. Can't be smaller than 5x5.
129  virtual void SetThumbWheelWidth(int v);
130  vtkGetMacro(ThumbWheelWidth, int);
131  virtual void SetThumbWheelHeight(int v);
132  vtkGetMacro(ThumbWheelHeight, int);
133  virtual void SetThumbWheelSize(int w, int h)
134  { this->SetThumbWheelWidth(w); this->SetThumbWheelHeight(h); };
135  virtual void SetLength(int v) { this->SetThumbWheelWidth(v); };
136 
137  // Description:
138  // Enable/Disable automatic thumbwheel resizing. Turn it off if you want
139  // a specific thumbwheel size, otherwise it will resize when its parent
140  // widget expands. Note that the ThumbWheelWidth and ThumbWheelHeight ivars
141  // are updated accordingly automatically.
142  virtual void SetResizeThumbWheel(int flag);
143  vtkGetMacro(ResizeThumbWheel, int);
144  vtkBooleanMacro(ResizeThumbWheel, int);
145 
146  // Description:
147  // Display/Hide a thumbwheel position indicator when the user performs a
148  // motion. This is just a vertical colored bar following the mouse position.
149  // Set/Get the indicator color.
150  vtkSetMacro(DisplayThumbWheelPositionIndicator, int);
151  vtkGetMacro(DisplayThumbWheelPositionIndicator, int);
152  vtkBooleanMacro(DisplayThumbWheelPositionIndicator, int);
153  vtkSetVector3Macro(ThumbWheelPositionIndicatorColor, double);
154  vtkGetVectorMacro(ThumbWheelPositionIndicatorColor, double, 3);
155 
156  // Description:
157  // Display/Hide a centrer indicator so that the user can easily find the
158  // positive and negative part of the range.
159  virtual void SetDisplayThumbWheelCenterIndicator(int flag);
160  vtkGetMacro(DisplayThumbWheelCenterIndicator, int);
161  vtkBooleanMacro(DisplayThumbWheelCenterIndicator, int);
162  virtual void ToggleDisplayThumbWheelCenterIndicator();
163 
164  // Description:
165  // Set/Get the average size (in pixels) of the notches on the visible part
166  // of the thumbwheel. Can be a decimal value, since it's only used to compute
167  // the number of notches to display depending on the current thumbwheel size.
168  virtual void SetSizeOfNotches(double v);
169  vtkGetMacro(SizeOfNotches, double);
170 
171  // Description:
172  // Display/Hide an entry field (optional).
173  virtual void SetDisplayEntry(int flag);
174  vtkGetMacro(DisplayEntry, int);
175  vtkBooleanMacro(DisplayEntry, int);
176  vtkGetObjectMacro(Entry, vtkKWEntry);
177 
178  // Description:
179  // Display/Hide/Set a label (optional).
180  virtual void SetDisplayLabel(int flag);
181  vtkGetMacro(DisplayLabel, int);
182  vtkBooleanMacro(DisplayLabel, int);
183  virtual vtkKWLabel* GetLabel();
184 
185  // Description:
186  // Set/Get the position of the label and/or entry (on top, or on the side).
187  virtual void SetDisplayEntryAndLabelOnTop(int flag);
188  vtkGetMacro(DisplayEntryAndLabelOnTop, int);
189  vtkBooleanMacro(DisplayEntryAndLabelOnTop, int);
190 
191  // Description:
192  // Set/Get the popup mode.
193  // WARNING: this mode must be set *before* Create() is called.
194  vtkSetMacro(PopupMode, int);
195  vtkGetMacro(PopupMode, int);
196  vtkBooleanMacro(PopupMode, int);
197  vtkGetObjectMacro(PopupPushButton, vtkKWPushButton);
198 
199  // Description:
200  // Set/Get the entry expansion flag. This flag is only used if PopupMode
201  // is On. In that case, the default behaviour is to provide a widget as
202  // compact as possible, i.e. the Entry won't be expanded if the widget grows.
203  // Set ExpandEntry to On to override this behaviour.
204  virtual void SetExpandEntry(int flag);
205  vtkGetMacro(ExpandEntry, int);
206  vtkBooleanMacro(ExpandEntry, int);
207 
208  // Description:
209  // Specifies commands to associate with the widget.
210  // 'Command' is invoked when the widget value is changing (i.e. during
211  // user interaction).
212  // 'StartCommand' is invoked at the beginning of a user interaction with
213  // the widget (when a mouse button is pressed over the widget for example).
214  // 'EndCommand' is invoked at the end of the user interaction with the
215  // widget (when the mouse button is released for example).
216  // 'EntryCommand' is invoked when the widget value is changed using
217  // the text entry.
218  // The need for a 'Command', 'StartCommand' and 'EndCommand' can be
219  // explained as follows: 'EndCommand' can be used to be notified about any
220  // changes made to this widget *after* the corresponding user interaction has
221  // been performed (say, after releasing the mouse button that was dragging
222  // a slider, or after clicking on a checkbutton). 'Command' can be set
223  // *additionally* to be notified about the intermediate changes that
224  // occur *during* the corresponding user interaction (say, *while* dragging
225  // a slider). While setting 'EndCommand' is enough to be notified about
226  // any changes, setting 'Command' is an application-specific choice that
227  // is likely to depend on how fast you want (or can) answer to rapid changes
228  // occuring during a user interaction, if any. 'StartCommand' is rarely
229  // used but provides an opportunity for the application to modify its
230  // state and prepare itself for user-interaction; in that case, the
231  // 'EndCommand' is usually set in a symmetric fashion to set the application
232  // back to its previous state.
233  // The 'object' argument is the object that will have the method called on
234  // it. The 'method' argument is the name of the method to be called and any
235  // arguments in string form. If the object is NULL, the method is still
236  // evaluated as a simple command.
237  // The following parameters are also passed to the command:
238  // - the current value: int (if Resolution is integer); double otherwise
239  // Note: the 'int' signature is for convenience, so that the command can
240  // be set to a callback accepting 'int'. In doubt, implement the callback
241  // using a 'double' signature that will accept both 'int' and 'double'.
242  virtual void SetCommand(vtkObject *object, const char *method);
243  virtual void SetStartCommand(vtkObject *object, const char *method);
244  virtual void SetEndCommand(vtkObject *object, const char *method);
245  virtual void SetEntryCommand(vtkObject *object, const char *method);
246 
247  // Description:
248  // Events. The ThumbWheelValueChangingEvent is triggered when the widget
249  // value is changed (i.e., during user interaction on the widget's
250  // thumbhweel), the ThumbWheelValueStartChangingEvent is invoked at the
251  // beginning of an interaction with the widget, the
252  // ThumbWheelValueChangedEvent is invoked at the end of an interaction with
253  // the widget. They are similar in concept as the 'Command', 'StartCommand',
254  // and 'EndCommand' callbacks but can be used by multiple listeners/observers
255  // at a time.
256  // The following parameters are also passed as client data:
257  // - the current value: double
258  //BTX
259  enum
260  {
261  ThumbWheelValueChangingEvent = 10000,
263  ThumbWheelValueStartChangingEvent
264  };
265  //ETX
266 
267  // Description:
268  // Setting this string enables balloon help for this widget.
269  // Override to pass down to children for cleaner behavior.
270  virtual void SetBalloonHelpString(const char *str);
271 
272  // Description:
273  // Bind/Unbind all components so that values can be changed, but
274  // no command will be called.
275  void Bind();
276  void UnBind();
277 
278  // Description:
279  // Update the "enable" state of the object and its internal parts.
280  // Depending on different Ivars (this->Enabled, the application's
281  // Limited Edition Mode, etc.), the "enable" state of the object is updated
282  // and propagated to its internal parts/subwidgets. This will, for example,
283  // enable/disable parts of the widget UI, enable/disable the visibility
284  // of 3D widgets, etc.
285  virtual void UpdateEnableState();
286 
287  // Description:
288  // Callbacks. Internal, do not use.
289  virtual void ResizeThumbWheelCallback();
290  virtual void DisplayPopupCallback();
291  virtual void WithdrawPopupCallback();
292  virtual void EntryValueCallback(const char*);
293  virtual void StartLinearMotionCallback();
294  virtual void PerformLinearMotionCallback();
295  virtual void StartNonLinearMotionCallback();
296  virtual void PerformNonLinearMotionCallback();
297  virtual void StopMotionCallback();
298 
299 protected:
300  vtkKWThumbWheel();
301  ~vtkKWThumbWheel();
302 
303  // Description:
304  // Create the widget.
305  virtual void CreateWidget();
306 
307  double Value;
308  double MinimumValue;
310  double MaximumValue;
312  double Resolution;
316 
320  double ThumbWheelPositionIndicatorColor[3];
321 
330 
331  char *Command;
333  char *EndCommand;
335 
336  virtual void InvokeThumbWheelCommand(const char *command, double value);
337  virtual void InvokeCommand(double value);
338  virtual void InvokeStartCommand(double value);
339  virtual void InvokeEndCommand(double value);
340  virtual void InvokeEntryCommand(double value);
341 
343 
344  int InteractionModes[3];
345 
351 
352  void CreateEntry();
353  void CreateLabel();
354  void UpdateThumbWheelImage(double pos = -1.0);
355  void PackWidget();
356  double GetMousePositionInThumbWheel();
357 
358  //BTX
359 
360  int State;
362  {
364  InMotion
365  };
366 
368  {
369  public:
370  double Value;
374  };
375 
377  {
378  public:
379  double Value;
380  double Increment;
382  };
383  //ETX
384 
387 
389 
390  void RefreshValue();
391 
392 private:
393  vtkKWThumbWheel(const vtkKWThumbWheel&); // Not implemented
394  void operator=(const vtkKWThumbWheel&); // Not implemented
395 };
396 
397 #endif
398