KWWidgets
vtkKWRange.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: $RCSfile: vtkKWRange.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 vtkKWRange - a range widget
15 // .SECTION Description
16 // A widget that represents a range within a bigger range.
17 // Note: As a subclass of vtkKWWidgetWithLabel, it inherits a label and methods
18 // to set its position and visibility. Note that the default label position
19 // implemented in this class is on the top of the range if the range
20 // direction is horizontal, on the left if is is vertical. Specific positions
21 // listed in vtkKWWidgetWithLabel are supported as well.
22 // .SECTION See Also
23 // vtkKWWidgetWithLabel
24 
25 #ifndef __vtkKWRange_h
26 #define __vtkKWRange_h
27 
28 #include "vtkKWWidgetWithLabel.h"
29 
30 class vtkKWCanvas;
31 class vtkKWEntry;
32 class vtkKWFrame;
33 class vtkKWPushButtonSet;
34 
36 {
37 public:
38  static vtkKWRange* New();
39  vtkTypeRevisionMacro(vtkKWRange,vtkKWWidgetWithLabel);
40  void PrintSelf(ostream& os, vtkIndent indent);
41 
42  // Description:
43  // Set/Get the whole range.
44  vtkGetVector2Macro(WholeRange, double);
45  virtual void SetWholeRange(double r0, double r1);
46  virtual void SetWholeRange(const double range[2])
47  { this->SetWholeRange(range[0], range[1]); };
48 
49  // Description:
50  // Set/Get the current (sub-)range.
51  vtkGetVector2Macro(Range, double);
52  virtual void SetRange(double r0, double r1);
53  virtual void SetRange(const double range[2])
54  { this->SetRange(range[0], range[1]); };
55 
56  // Description:
57  // Set/Get the current (sub-)range as relative positions in the whole range.
58  virtual void GetRelativeRange(double &r0, double &r1);
59  virtual void GetRelativeRange(double range[2])
60  { this->GetRelativeRange(range[0], range[1]); };
61  virtual void SetRelativeRange(double r0, double r1);
62  virtual void SetRelativeRange(const double range[2])
63  { this->SetRelativeRange(range[0], range[1]); };
64 
65  // Description:
66  // Set/Get the resolution of the slider.
67  // The whole range and sub range are not snapped to this resolution.
68  // Both ranges can be set to any floating point number.
69  // Think of the sliders and the resolution as a way to set the bounds of
70  // the sub range interactively using nice clean steps (power of 10 for
71  // example).
72  // The entries associated to the sub range can be used to set the bounds to
73  // anything within the whole range, despite the resolution, allowing the user
74  // to enter precise values that could not be reached given the resolution.
75  // Of course, given a whole range of 1 to 64, if the resolution is set to 3
76  // the slider will only snap to values ranging from 3 to 63 (within the
77  // whole range constraint), but the entries can be used to set accurate
78  // values out of the resolution (i.e., 1, 2... 64).
79  virtual void SetResolution(double r);
80  vtkGetMacro(Resolution, double);
81 
82  // Description:
83  // Adjust the resolution automatically (to a power of 10 in this implem)
84  virtual void SetAdjustResolution(int);
85  vtkBooleanMacro(AdjustResolution, int);
86  vtkGetMacro(AdjustResolution, int);
87 
88  // Description:
89  // Set/Get the orientation.
90  //BTX
91  enum
92  {
93  OrientationHorizontal = 0,
94  OrientationVertical = 1
95  };
96  //ETX
97  virtual void SetOrientation(int);
98  vtkGetMacro(Orientation, int);
99  virtual void SetOrientationToHorizontal()
100  { this->SetOrientation(vtkKWRange::OrientationHorizontal); };
101  virtual void SetOrientationToVertical()
102  { this->SetOrientation(vtkKWRange::OrientationVertical); };
103 
104  // Description:
105  // Set/Get the order of the sliders (inverted means that the first slider
106  // will be associated to Range[1], the last to Range[0])
107  virtual void SetInverted(int);
108  vtkBooleanMacro(Inverted, int);
109  vtkGetMacro(Inverted, int);
110 
111  // Description:
112  // Set/Get the desired narrow dimension of the widget. For horizontal widget
113  // this is the widget height, for vertical this is the width.
114  // In the current implementation, this controls the sliders narrow dim.
115  virtual void SetThickness(int);
116  vtkGetMacro(Thickness, int);
117 
118  // Description:
119  // Set/Get the desired narrow dimension of the internal widget as a fraction
120  // of the thickness of the widget (see Thickness).
121  // In the current implementation, this controls the range bar narrow dim.
122  virtual void SetInternalThickness(double);
123  vtkGetMacro(InternalThickness, double);
124 
125  // Description:
126  // Set/Get the long dimension of the widget. For horizontal widget
127  // this is the widget width, for vertical this is the height.
128  // Set it to zero (default) to ignore it and let the widget
129  // resize.
130  virtual void SetRequestedLength(int);
131  vtkGetMacro(RequestedLength, int);
132 
133  // Description:
134  // Set/Get the slider size.
135  virtual void SetSliderSize(int);
136  vtkGetMacro(SliderSize, int);
137 
138  // Description:
139  // Set/Get if a slider can push another slider when bumping into it
140  vtkSetMacro(SliderCanPush, int);
141  vtkBooleanMacro(SliderCanPush, int);
142  vtkGetMacro(SliderCanPush, int);
143 
144  // Description:
145  // Set/Get the (sub) range scale color.
146  // Defaults to -1, -1, -1: a shade of the widget background color will
147  // be used at runtime.
148  vtkGetVector3Macro(RangeColor, double);
149  virtual void SetRangeColor(double r, double g, double b);
150  virtual void SetRangeColor(double rgb[3])
151  { this->SetRangeColor(rgb[0], rgb[1], rgb[2]); };
152 
153  // Description:
154  // Set/Get the (sub) range scale interaction color. Used when interaction
155  // is performed using the sliders.
156  // IF set to -1, -1, -1: a shade of the widget background color will
157  // be used at runtime.
158  vtkGetVector3Macro(RangeInteractionColor, double);
159  virtual void SetRangeInteractionColor(double r, double g, double b);
160  virtual void SetRangeInteractionColor(double rgb[3])
161  { this->SetRangeInteractionColor(rgb[0], rgb[1], rgb[2]); };
162 
163  // Description:
164  // Set/Get the color of the first slider.
165  // Defaults to -1, -1, -1: a shade of the widget background color will
166  // be used at runtime.
167  vtkGetVector3Macro(Slider1Color, double);
168  virtual void SetSlider1Color(double r, double g, double b);
169  virtual void SetSlider1Color(double rgb[3])
170  { this->SetSlider1Color(rgb[0], rgb[1], rgb[2]); };
171 
172  // Description:
173  // Set/Get the (sub) slider scale interaction color. Used when interaction
174  // is performed using the sliders.
175  // IF set to -1, -1, -1: a shade of the widget background color will
176  // be used at runtime.
177  vtkGetVector3Macro(SliderInteractionColor, double);
178  virtual void SetSliderInteractionColor(double r, double g, double b);
179  virtual void SetSliderInteractionColor(double rgb[3])
180  { this->SetSliderInteractionColor(rgb[0], rgb[1], rgb[2]); };
181 
182  // Description:
183  // Set/Get the color of the second slider.
184  // Defaults to -1, -1, -1: a shade of the widget background color will
185  // be used at runtime.
186  vtkGetVector3Macro(Slider2Color, double);
187  virtual void SetSlider2Color(double r, double g, double b);
188  virtual void SetSlider2Color(double rgb[3])
189  { this->SetSlider2Color(rgb[0], rgb[1], rgb[2]); };
190 
191  // Description:
192  // Set/Get the entries visibility.
193  virtual void SetEntriesVisibility(int);
194  vtkBooleanMacro(EntriesVisibility, int);
195  vtkGetMacro(EntriesVisibility, int);
196 
197  // Description:
198  // Get the entries object.
199  virtual vtkKWEntry* GetEntry1()
200  { return this->Entries[0]; };
201  virtual vtkKWEntry* GetEntry2()
202  { return this->Entries[1]; };
203 
204  // Description:
205  // Set/Get the entries width (in chars).
206  virtual void SetEntriesWidth(int width);
207  vtkGetMacro(EntriesWidth, int);
208 
209  // Description:
210  // Set/Get the position of the entries (Default is top if the range
211  // direction is horizontal, left if it is vertical).
212  // Note that you can also set the label position using the superclass
213  // methods (vtkKWWidgetWithLabel).
214  //BTX
215  enum
216  {
217  EntryPositionDefault = 0,
218  EntryPositionTop,
219  EntryPositionBottom,
220  EntryPositionLeft,
221  EntryPositionRight
222  };
223  //ETX
224  virtual void SetEntry1Position(int);
225  vtkGetMacro(Entry1Position, int);
226  virtual void SetEntry1PositionToDefault()
227  { this->SetEntry1Position(vtkKWRange::EntryPositionDefault); };
228  virtual void SetEntry1PositionToTop()
229  { this->SetEntry1Position(vtkKWRange::EntryPositionTop); };
230  virtual void SetEntry1PositionToBottom()
231  { this->SetEntry1Position(vtkKWRange::EntryPositionBottom); };
232  virtual void SetEntry1PositionToLeft()
233  { this->SetEntry1Position(vtkKWRange::EntryPositionLeft); };
234  virtual void SetEntry1PositionToRight()
235  { this->SetEntry1Position(vtkKWRange::EntryPositionRight); };
236  virtual void SetEntry2Position(int);
237  vtkGetMacro(Entry2Position, int);
238  virtual void SetEntry2PositionToDefault()
239  { this->SetEntry2Position(vtkKWRange::EntryPositionDefault); };
240  virtual void SetEntry2PositionToTop()
241  { this->SetEntry2Position(vtkKWRange::EntryPositionTop); };
242  virtual void SetEntry2PositionToBottom()
243  { this->SetEntry2Position(vtkKWRange::EntryPositionBottom); };
244  virtual void SetEntry2PositionToLeft()
245  { this->SetEntry2Position(vtkKWRange::EntryPositionLeft); };
246  virtual void SetEntry2PositionToRight()
247  { this->SetEntry2Position(vtkKWRange::EntryPositionRight); };
248 
249  // Description:
250  // Specifies commands to associate with the widget.
251  // 'Command' is invoked when the widget value is changing (i.e. during
252  // user interaction).
253  // 'StartCommand' is invoked at the beginning of a user interaction with
254  // the widget (when a mouse button is pressed over the widget for example).
255  // 'EndCommand' is invoked at the end of the user interaction with the
256  // widget (when the mouse button is released for example).
257  // 'EntriesCommand' is invoked when the widget value is changed using
258  // the text entries.
259  // The need for a 'Command', 'StartCommand' and 'EndCommand' can be
260  // explained as follows: 'EndCommand' can be used to be notified about any
261  // changes made to this widget *after* the corresponding user interaction has
262  // been performed (say, after releasing the mouse button that was dragging
263  // a slider, or after clicking on a checkbutton). 'Command' can be set
264  // *additionally* to be notified about the intermediate changes that
265  // occur *during* the corresponding user interaction (say, *while* dragging
266  // a slider). While setting 'EndCommand' is enough to be notified about
267  // any changes, setting 'Command' is an application-specific choice that
268  // is likely to depend on how fast you want (or can) answer to rapid changes
269  // occuring during a user interaction, if any. 'StartCommand' is rarely
270  // used but provides an opportunity for the application to modify its
271  // state and prepare itself for user-interaction; in that case, the
272  // 'EndCommand' is usually set in a symmetric fashion to set the application
273  // back to its previous state.
274  // The 'object' argument is the object that will have the method called on
275  // it. The 'method' argument is the name of the method to be called and any
276  // arguments in string form. If the object is NULL, the method is still
277  // evaluated as a simple command.
278  // The following parameters are also passed to the command:
279  // - the current range: int, int (if Resolution is integer); double, double
280  // otherwise.
281  // Note: the 'int' signature is for convenience, so that the command can
282  // be set to a callback accepting 'int'. In doubt, implement the callback
283  // using a 'double' signature that will accept both 'int' and 'double'.
284  virtual void SetCommand(vtkObject *object, const char *method);
285  virtual void SetStartCommand(vtkObject *object, const char *method);
286  virtual void SetEndCommand(vtkObject *object, const char *method);
287  virtual void SetEntriesCommand(vtkObject *object, const char *method);
288 
289  // Description:
290  // Set/Get whether the above commands should be called or not.
291  // This allow you to disable the commands while you are setting the range
292  // value for example.
293  vtkSetMacro(DisableCommands, int);
294  vtkGetMacro(DisableCommands, int);
295  vtkBooleanMacro(DisableCommands, int);
296 
297  // Description:
298  // Events. The RangeValueChangingEvent is triggered when the widget value
299  // is changed (i.e., during user interaction on the widget's slider),
300  // the RangeValueStartChangingEvent is invoked at the beginning of an
301  // interaction with the widget, the RangeValueChangedEvent is invoked at the
302  // end of an interaction with the widget (or when the value is changed
303  // using the entries widget). They are similar in concept as
304  // the 'Command', 'StartCommand', 'EndCommand' and 'EntriesCommand' callbacks
305  // but can be used by multiple listeners/observers at a time.
306  // The following parameters are also passed as client data:
307  // - the current range: double, double.
308  //BTX
309  enum
310  {
311  RangeValueChangingEvent = 10000,
312  RangeValueChangedEvent,
313  RangeValueStartChangingEvent
314  };
315  //ETX
316 
317  // Description:
318  // If set to on, set the interaction to a symmetrical mode, where
319  // adjusting one slider adjust the other one symmetrically.
320  vtkBooleanMacro(SymmetricalInteraction, int);
321  vtkGetMacro(SymmetricalInteraction, int);
322  vtkSetMacro(SymmetricalInteraction, int);
323 
324  // Description:
325  // Set the string that enables balloon help for this widget.
326  // Override to pass down to children.
327  virtual void SetBalloonHelpString(const char *str);
328 
329  // Description:
330  // Access to the canvas
331  vtkGetObjectMacro(Canvas, vtkKWCanvas);
332 
333  // Description:
334  // Update the "enable" state of the object and its internal parts.
335  // Depending on different Ivars (this->Enabled, the application's
336  // Limited Edition Mode, etc.), the "enable" state of the object is updated
337  // and propagated to its internal parts/subwidgets. This will, for example,
338  // enable/disable parts of the widget UI, enable/disable the visibility
339  // of 3D widgets, etc.
340  virtual void UpdateEnableState();
341 
342  // Description:
343  // Turn on/off the automatic clamping of the end values when the
344  // user types a value beyond the range. Default is on.
345  vtkSetMacro(ClampRange, int);
346  vtkGetMacro(ClampRange, int);
347  vtkBooleanMacro(ClampRange, int);
348 
349  // Description:
350  // Callbacks. Internal, do not use.
351  //BTX
352  enum
353  {
354  SliderIndex0 = 0,
355  SliderIndex1 = 1
356  };
357  //ETX
358  virtual void ConfigureCallback();
359  virtual void MaximizeRangeCallback();
360  virtual void EnlargeRangeCallback();
361  virtual void ShrinkRangeCallback();
362  virtual void EntriesUpdateCallback(int i);
363  virtual void StartRangeInteractionCallback(int x, int y);
364  virtual void StartSliderInteractionCallback(int slider_idx, int x, int y);
365  virtual void EndInteractionCallback();
366  virtual void SliderMotionCallback(
367  int slider_idx, int x, int y, int shift, int ctrl);
368  virtual void RangeMotionCallback(int x, int y, int shift, int ctrl);
369 
370 protected:
371  vtkKWRange();
372  ~vtkKWRange();
373 
374  // Description:
375  // Create the widget.
376  virtual void CreateWidget();
377 
378  double WholeRange[2];
379  double Range[2];
380  double WholeRangeAdjusted[2];
381  double RangeAdjusted[2];
382  double Resolution;
383  int AdjustResolution;
384  int SymmetricalInteraction;
385  int Inverted;
386  int Thickness;
387  double InternalThickness;
388  int RequestedLength;
389  int Orientation;
390  int DisableCommands;
391  int SliderSize;
392  double RangeColor[3];
393  double RangeInteractionColor[3];
394  double Slider1Color[3];
395  double Slider2Color[3];
396  double SliderInteractionColor[3];
397  int EntriesVisibility;
398  int Entry1Position;
399  int Entry2Position;
400  int EntriesWidth;
401  int SliderCanPush;
402 
403  int ClampRange;
404 
405  char *Command;
406  char *StartCommand;
407  char *EndCommand;
408  char *EntriesCommand;
409 
410  virtual void InvokeRangeCommand(const char *command, double r0, double r1);
411  virtual void InvokeCommand(double r0, double r1);
412  virtual void InvokeStartCommand(double r0, double r1);
413  virtual void InvokeEndCommand(double r0, double r1);
414  virtual void InvokeEntriesCommand(double r0, double r1);
415 
416  vtkKWFrame *CanvasFrame;
417  vtkKWCanvas *Canvas;
418  vtkKWEntry *Entries[2];
419 
420  virtual void CreateEntries();
421  virtual void UpdateEntriesValue(double range[2]);
422  virtual void ConstrainResolution();
423 
424  // Description:
425  // Bind/Unbind all components.
426  virtual void Bind();
427  virtual void UnBind();
428 
429  // Description:
430  // Make sure all elements are constrained correctly
431  virtual void ConstrainRangeToResolution(
432  double range[2], double res, int adjust = 1);
433  virtual void ConstrainRangeToWholeRange(
434  double range[2], double whole_range[2], double *old_range_hint = 0);
435  virtual void ConstrainWholeRange();
436  virtual void ConstrainRange(double *old_range_hint = 0);
437  virtual void ConstrainRanges();
438 
439  // Description:
440  // Pack the widget
441  virtual void Pack();
442 
443  // Description:
444  // Get type of interaction
445  //BTX
446  enum
447  {
448  RangeInteraction,
449  Slider1Interaction,
450  Slider2Interaction
451  };
452 
453  // Description:
454  // Start Interactions with the input interaction type
455  // (RangeInteraction, Slider1Interaction, Slider2Interaction)
456  virtual void StartInteraction(int inter_type, int x, int y);
457 
458  // Description:
459  // Get element colors (and shades)
460  //BTX
461  enum
462  {
463  DarkShadowColor,
464  LightShadowColor,
465  BackgroundColor,
466  HighlightColor
467  };
468  //ETX
469  virtual void GetColorShade(
470  int type, double rgb[3], double &r, double &g, double &b);
471  virtual void GetWholeRangeColor(int type, double &r, double &g, double &b);
472  virtual void GetRangeColor(int type, double &r, double &g, double &b);
473  virtual void GetSliderColor(int slider_idx, int type, double &r, double &g, double &b);
474 
475  // Description:
476  // Redraw elements
477  virtual void RedrawCanvas();
478  virtual void RedrawWholeRange();
479  virtual void RedrawRange();
480  virtual void RedrawSliders();
481  virtual void RedrawSlider(int x, int slider_idx);
482  virtual void UpdateRangeColors();
483  virtual void UpdateSliderColors(int slider_idx);
484  virtual void UpdateColors();
485 
486  // Description:
487  // Look for a tag
488  virtual int HasTag(const char *tag, const char *suffix = 0);
489 
490  // Description:
491  // Get the current sliders center positions
492  virtual void GetSlidersPositions(int pos[2]);
493 
494 private:
495 
496  int InInteraction;
497  int StartInteractionPos;
498  double StartInteractionRange[2];
499 
500  vtkKWRange(const vtkKWRange&); // Not implemented
501  void operator=(const vtkKWRange&); // Not implemented
502 };
503 
504 #endif
505