KWWidgets
vtkKWSpinBox.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: vtkKWSpinBox.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 vtkKWSpinBox - SpinBox
15 // .SECTION Description
16 // A widget with up and down arrow controls and direct text editing.
17 // Typically used with integer fields that users increment by 1 (or
18 // decrement) by clicking on the arrows.
19 // .SECTION Thanks
20 // This work is part of the National Alliance for Medical Image
21 // Computing (NAMIC), funded by the National Institutes of Health
22 // through the NIH Roadmap for Medical Research, Grant U54 EB005149.
23 // Information on the National Centers for Biomedical Computing
24 // can be obtained from http://nihroadmap.nih.gov/bioinformatics.
25 
26 #ifndef __vtkKWSpinBox_h
27 #define __vtkKWSpinBox_h
28 
29 #include "vtkKWCoreWidget.h"
30 
31 class vtkKWMenu;
32 
34 {
35 public:
36  static vtkKWSpinBox* New();
37  vtkTypeRevisionMacro(vtkKWSpinBox,vtkKWCoreWidget);
38  void PrintSelf(ostream& os, vtkIndent indent);
39 
40  // Description:
41  // Set the range. Default to [0, 10]
42  virtual void SetRange(double from, double to);
43 
44  // Description:
45  // Set the increment value. Default to 1.
46  virtual void SetIncrement(double increment);
47  virtual double GetIncrement();
48 
49  // Description:
50  // Set/Get the current value.
51  virtual void SetValue(double value);
52  virtual double GetValue();
53 
54  // Description:
55  // Set/Get the string used to format the value.
56  // Specifies an alternate format to use when setting the string value when
57  // using the range. This must be a format specifier of the
58  // form %<pad>.<pad>f, as it will format a floating-point number.
59  virtual void SetValueFormat(const char *format);
60  virtual const char* GetValueFormat();
61 
62  // Description:
63  // Set/Get the wrap. If on, values at edges of range wrap around to the
64  // other side of the range when clicking on the up/down arrows.
65  virtual void SetWrap(int wrap);
66  virtual int GetWrap();
67  vtkBooleanMacro(Wrap, int);
68 
69  // Description:
70  // Restrict the value to a given type (integer, double, or no restriction).
71  // Note: checks against RestrictValue are performed before ValidationCommand.
72  //BTX
73  enum
74  {
75  RestrictNone = 0,
76  RestrictInteger,
77  RestrictDouble
78  };
79  //ETX
80  vtkGetMacro(RestrictValue, int);
81  virtual void SetRestrictValue(int);
82  virtual void SetRestrictValueToInteger();
83  virtual void SetRestrictValueToDouble();
84  virtual void SetRestrictValueToNone();
85 
86  // Description:
87  // Specifies a command to associate with this step. This command can
88  // be used to validate the contents of the widget.
89  // Note: checks against RestrictValue are performed before ValidationCommand.
90  // The 'object' argument is the object that will have the method called on
91  // it. The 'method' argument is the name of the method to be called and any
92  // arguments in string form. If the object is NULL, the method is still
93  // evaluated as a simple command.
94  // This command should return 1 if the contents is valid, 0 otherwise.
95  // The following parameters are also passed to the command:
96  // - current value: const char*
97  virtual void SetValidationCommand(vtkObject *object, const char *method);
98  virtual int InvokeValidationCommand(const char *value);
99 
100  // Description:
101  // Set/Get the width of the spinbox in number of characters.
102  virtual void SetWidth(int);
103  virtual int GetWidth();
104 
105  // Description:
106  // Set/Get the background color of the widget.
107  virtual void GetBackgroundColor(double *r, double *g, double *b);
108  virtual double* GetBackgroundColor();
109  virtual void SetBackgroundColor(double r, double g, double b);
110  virtual void SetBackgroundColor(double rgb[3])
111  { this->SetBackgroundColor(rgb[0], rgb[1], rgb[2]); };
112 
113  // Description:
114  // Set/Get the foreground color of the widget.
115  virtual void GetForegroundColor(double *r, double *g, double *b);
116  virtual double* GetForegroundColor();
117  virtual void SetForegroundColor(double r, double g, double b);
118  virtual void SetForegroundColor(double rgb[3])
119  { this->SetForegroundColor(rgb[0], rgb[1], rgb[2]); };
120 
121  // Description:
122  // Set/Get the background color of the widget when it is disabled.
123  virtual void GetDisabledBackgroundColor(double *r, double *g, double *b);
124  virtual double* GetDisabledBackgroundColor();
125  virtual void SetDisabledBackgroundColor(double r, double g, double b);
126  virtual void SetDisabledBackgroundColor(double rgb[3])
127  { this->SetDisabledBackgroundColor(rgb[0], rgb[1], rgb[2]); };
128 
129  // Description:
130  // Set/Get the foreground color of the widget when it is disabled.
131  virtual void GetDisabledForegroundColor(double *r, double *g, double *b);
132  virtual double* GetDisabledForegroundColor();
133  virtual void SetDisabledForegroundColor(double r, double g, double b);
134  virtual void SetDisabledForegroundColor(double rgb[3])
135  { this->SetDisabledForegroundColor(rgb[0], rgb[1], rgb[2]); };
136 
137  // Description:
138  // Set/Get the background color of the widget when it is read-only.
139  virtual void GetReadOnlyBackgroundColor(double *r, double *g, double *b);
140  virtual double* GetReadOnlyBackgroundColor();
141  virtual void SetReadOnlyBackgroundColor(double r, double g, double b);
142  virtual void SetReadOnlyBackgroundColor(double rgb[3])
143  { this->SetReadOnlyBackgroundColor(rgb[0], rgb[1], rgb[2]); };
144 
145  // Description:
146  // Set/Get the background color of the spin-buttons.
147  virtual void GetButtonBackgroundColor(double *r, double *g, double *b);
148  virtual double* GetButtonBackgroundColor();
149  virtual void SetButtonBackgroundColor(double r, double g, double b);
150  virtual void SetButtonBackgroundColor(double rgb[3])
151  { this->SetButtonBackgroundColor(rgb[0], rgb[1], rgb[2]); };
152 
153  // Description:
154  // Set/Get the highlight thickness, a non-negative value indicating the
155  // width of the highlight rectangle to draw around the outside of the
156  // widget when it has the input focus.
157  virtual void SetHighlightThickness(int);
158  virtual int GetHighlightThickness();
159 
160  // Description:
161  // Set/Get the active background color of the widget. An element
162  // (a widget or portion of a widget) is active if the mouse cursor is
163  // positioned over the element and pressing a mouse button will cause some
164  // action to occur.
165  virtual void GetActiveBackgroundColor(double *r, double *g, double *b);
166  virtual double* GetActiveBackgroundColor();
167  virtual void SetActiveBackgroundColor(double r, double g, double b);
168  virtual void SetActiveBackgroundColor(double rgb[3])
169  { this->SetActiveBackgroundColor(rgb[0], rgb[1], rgb[2]); };
170 
171  // Description:
172  // Set/Get the border width, a non-negative value indicating the width of
173  // the 3-D border to draw around the outside of the widget (if such a border
174  // is being drawn; the Relief option typically determines this).
175  virtual void SetBorderWidth(int);
176  virtual int GetBorderWidth();
177 
178  // Description:
179  // Set/Get the 3-D effect desired for the widget.
180  // The value indicates how the interior of the widget should appear
181  // relative to its exterior.
182  // Valid constants can be found in vtkKWOptions::ReliefType.
183  virtual void SetRelief(int);
184  virtual int GetRelief();
185  virtual void SetReliefToRaised();
186  virtual void SetReliefToSunken();
187  virtual void SetReliefToFlat();
188  virtual void SetReliefToRidge();
189  virtual void SetReliefToSolid();
190  virtual void SetReliefToGroove();
191 
192  // Description:
193  // Specifies the font to use when drawing text inside the widget.
194  // You can use predefined font names (e.g. 'system'), or you can specify
195  // a set of font attributes with a platform-independent name, for example,
196  // 'times 12 bold'. In this example, the font is specified with a three
197  // element list: the first element is the font family, the second is the
198  // size, the third is a list of style parameters (normal, bold, roman,
199  // italic, underline, overstrike). Example: 'times 12 {bold italic}'.
200  // The Times, Courier and Helvetica font families are guaranteed to exist
201  // and will be matched to the corresponding (closest) font on your system.
202  // If you are familiar with the X font names specification, you can also
203  // describe the font that way (say, '*times-medium-r-*-*-12*').
204  virtual void SetFont(const char *font);
205  virtual const char* GetFont();
206 
207  // Description:
208  // Specifies whether or not a selection in the widget should also be the X
209  // selection. If the selection is exported, then selecting in the widget
210  // deselects the current X selection, selecting outside the widget deselects
211  // any widget selection, and the widget will respond to selection retrieval
212  // requests when it has a selection.
213  virtual void SetExportSelection(int);
214  virtual int GetExportSelection();
215  vtkBooleanMacro(ExportSelection, int);
216 
217  // Description:
218  // Specifies a command to associate with the widget. This command is
219  // typically invoked when the return key is pressed, or the focus is lost,
220  // as specified by the CommandTrigger variable. It is also invoked when
221  // the spinbuttons are pressed.
222  // The 'object' argument is the object that will have the method called on
223  // it. The 'method' argument is the name of the method to be called and any
224  // arguments in string form. If the object is NULL, the method is still
225  // evaluated as a simple command.
226  // The following parameters are also passed to the command:
227  // - the current value: int (if Increment is integer); double otherwise
228  // Note: the 'int' signature is for convenience, so that the command can
229  // be set to a callback accepting 'int'. In doubt, implement the callback
230  // using a 'double' signature that will accept both 'int' and 'double'.
231  virtual void SetCommand(vtkObject *object, const char *method);
232  virtual void InvokeCommand(double value);
233 
234  // Description:
235  // Specify when Command should be invoked. Default to losing focus and
236  // return key.
237  //BTX
238  enum
239  {
240  TriggerOnFocusOut = 1,
241  TriggerOnReturnKey = 2,
242  TriggerOnAnyChange = 4
243  };
244  //ETX
245  vtkGetMacro(CommandTrigger, int);
246  virtual void SetCommandTrigger(int);
247  virtual void SetCommandTriggerToReturnKeyAndFocusOut();
248  virtual void SetCommandTriggerToAnyChange();
249 
250  // Description:
251  // Events. The SpinBoxValueChangedEvent is triggered when the widget value
252  // is changed. It is similar in concept to the 'Command' callback but can be
253  // used by multiple listeners/observers at a time.
254  // Important: since there is no way to robustly find out when the user
255  // is done inputing characters in the text entry part of the spinbox, the
256  // SpinBoxValueChangedEvent event is also generated when <Return> is pressed,
257  // or the spinbox widget is losing focus (i.e. the user clicked outside the
258  // text field).
259  // The following parameters are also passed as client data:
260  // - the current value: double
261  //BTX
262  enum
263  {
264  SpinBoxValueChangedEvent = 10000
265  };
266  //ETX
267 
268  // Description:
269  // Update the "enable" state of the object and its internal parts.
270  // Depending on different Ivars (this->Enabled, the application's
271  // Limited Edition Mode, etc.), the "enable" state of the object is updated
272  // and propagated to its internal parts/subwidgets. This will, for example,
273  // enable/disable parts of the widget UI, enable/disable the visibility
274  // of 3D widgets, etc.
275  virtual void UpdateEnableState();
276 
277  // Description:
278  // Callbacks. Internal, do not use.
279  virtual void ValueCallback();
280  virtual int ValidationCallback(const char *value);
281  virtual void TracedVariableChangedCallback(
282  const char *, const char *, const char *);
283  virtual void RightClickCallback(int x, int y);
284 
285 protected:
286  vtkKWSpinBox();
287  ~vtkKWSpinBox();
288 
289  // Description:
290  // Create the widget.
291  virtual void CreateWidget();
292 
293  int RestrictValue;
294  int CommandTrigger;
295 
296  char *Command;
297  char *ValidationCommand;
298 
299  vtkKWMenu *ContextMenu;
300 
301  // Description:
302  // Populate the context menu
303  virtual void PopulateContextMenu(vtkKWMenu*);
304 
305  // Description:
306  // Configure.
307  virtual void Configure();
308  virtual void ConfigureValidation();
309 
310 private:
311  vtkKWSpinBox(const vtkKWSpinBox&); // Not implemented
312  void operator=(const vtkKWSpinBox&); // Not implemented
313 };
314 
315 #endif