KWWidgets
vtkKWEntry.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: vtkKWEntry.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 vtkKWEntry - a single line text entry widget
15 // .SECTION Description
16 // A simple widget used for collecting keyboard input from the user. This
17 // widget provides support for single line input.
18 
19 #ifndef __vtkKWEntry_h
20 #define __vtkKWEntry_h
21 
22 #include "vtkKWCoreWidget.h"
23 
25 {
26 public:
27  static vtkKWEntry* New();
28  vtkTypeRevisionMacro(vtkKWEntry,vtkKWCoreWidget);
29  void PrintSelf(ostream& os, vtkIndent indent);
30 
31  // Description:
32  // Set/Get the value of the entry in a few different formats.
33  // In the SetValue method with double, values are printed in printf's %f
34  // or %e format, whichever is more compact for the given value and precision.
35  // The %e format is used only when the exponent of the value is less than
36  // -4 or greater than or equal to the precision argument (which can be
37  // controlled using the second parameter of SetValue). Trailing zeros
38  // are truncated, and the decimal point appears only if one or more digits
39  // follow it.
40  // Set/GetHexadecimalValueAsRGB provides a convenience way to enter/parse
41  // a RGB triplet formatted in hexadecimal. Note that the values are
42  // int, not double (i.e. 0 to 255 instead of VTK's normalized 0.0 to 1.0)
43  // IMPORTANT: whenever possible, use any of the GetValueAs...() methods
44  // GetHexadecimalValueAsRGB will set r,g,b to -1, -1, -1 if the hexadecimal
45  // value could not be parsed.
46  // to retrieve the value if it is meant to be a number. This is faster
47  // than calling GetValue() and converting the resulting string to a number.
48  virtual void SetValue(const char *);
49  virtual const char* GetValue();
50  virtual void SetValueAsInt(int a);
51  virtual int GetValueAsInt();
52  virtual void SetValueAsFormattedDouble(double f, int size);
53  virtual void SetValueAsDouble(double f);
54  virtual double GetValueAsDouble();
55  virtual void SetHexadecimalValueAsRGB(int r, int g, int b);
56  virtual void GetHexadecimalValueAsRGB(int &r, int &g, int &b);
57 
58  // Description:
59  // The width is the number of charaters wide the entry box can fit.
60  // To keep from changing behavior of the entry, the default
61  // value is -1 wich means the width is not explicitly set and will default
62  // to whatever value Tk is using (at this point, 20). Set it to 0
63  // and the widget should pick a size just large enough to hold its text.
64  virtual void SetWidth(int width);
65  vtkGetMacro(Width, int);
66 
67  // Description:
68  // Set/Get readonly flag. This flags makes the entry read only.
69  virtual void SetReadOnly(int);
70  vtkBooleanMacro(ReadOnly, int);
71  vtkGetMacro(ReadOnly, int);
72 
73  // Description:
74  // Set/Get password mode flag. If this flag is set, then the true contents
75  // of the entry are not displayed in the window. Instead, each character in
76  // the entry's value will be displayed as '*'. This is useful, for example,
77  // if the entry is to be used to enter a password. If characters in the entry
78  // are selected and copied elsewhere, the information copied will be what is
79  // displayed, not the true contents of the entry.
80  vtkBooleanMacro(PasswordMode, int);
81  virtual void SetPasswordMode(int);
82  virtual int GetPasswordMode();
83 
84  // Description:
85  // Select all text in the entry
86  virtual void SelectAll();
87 
88  // Description:
89  // Set/Get if the entry's contents should be selected automatically
90  // when the entry receives focus. Off by default, this variable can be
91  // turned on to On to emulate the effect of the URL entry in a browser
92  // window.
93  vtkBooleanMacro(SelectAllOnFocusIn, int);
94  virtual void SetSelectAllOnFocusIn(int);
95  vtkGetMacro(SelectAllOnFocusIn, int);
96 
97  // Description:
98  // Restrict the value to a given type (integer, hexadecimal, double, or
99  // no restriction).
100  // Note: checks against RestrictValue are performed before ValidationCommand.
101  //BTX
102  enum
103  {
104  RestrictNone = 0,
105  RestrictInteger,
106  RestrictDouble,
107  RestrictHexadecimal
108  };
109  //ETX
110  vtkGetMacro(RestrictValue, int);
111  virtual void SetRestrictValue(int);
112  virtual void SetRestrictValueToInteger();
113  virtual void SetRestrictValueToDouble();
114  virtual void SetRestrictValueToHexadecimal();
115  virtual void SetRestrictValueToNone();
116 
117  // Description:
118  // Specifies a command to associate with this step. This command can
119  // be used to validate the contents of the widget.
120  // Note: checks against RestrictValue are performed before ValidationCommand.
121  // The 'object' argument is the object that will have the method called on
122  // it. The 'method' argument is the name of the method to be called and any
123  // arguments in string form. If the object is NULL, the method is still
124  // evaluated as a simple command.
125  // This command should return 1 if the contents is valid, 0 otherwise.
126  // The following parameters are also passed to the command:
127  // - current value: const char*
128  virtual void SetValidationCommand(vtkObject *object, const char *method);
129  virtual int InvokeValidationCommand(const char *value);
130 
131  // Description:
132  // Set/Get the background color of the widget.
133  virtual void GetBackgroundColor(double *r, double *g, double *b);
134  virtual double* GetBackgroundColor();
135  virtual void SetBackgroundColor(double r, double g, double b);
136  virtual void SetBackgroundColor(double rgb[3])
137  { this->SetBackgroundColor(rgb[0], rgb[1], rgb[2]); };
138 
139  // Description:
140  // Set/Get the foreground color of the widget.
141  virtual void GetForegroundColor(double *r, double *g, double *b);
142  virtual double* GetForegroundColor();
143  virtual void SetForegroundColor(double r, double g, double b);
144  virtual void SetForegroundColor(double rgb[3])
145  { this->SetForegroundColor(rgb[0], rgb[1], rgb[2]); };
146 
147  // Description:
148  // Set/Get the background color of the widget when it is disabled.
149  virtual void GetDisabledBackgroundColor(double *r, double *g, double *b);
150  virtual double* GetDisabledBackgroundColor();
151  virtual void SetDisabledBackgroundColor(double r, double g, double b);
152  virtual void SetDisabledBackgroundColor(double rgb[3])
153  { this->SetDisabledBackgroundColor(rgb[0], rgb[1], rgb[2]); };
154 
155  // Description:
156  // Set/Get the foreground color of the widget when it is disabled.
157  virtual void GetDisabledForegroundColor(double *r, double *g, double *b);
158  virtual double* GetDisabledForegroundColor();
159  virtual void SetDisabledForegroundColor(double r, double g, double b);
160  virtual void SetDisabledForegroundColor(double rgb[3])
161  { this->SetDisabledForegroundColor(rgb[0], rgb[1], rgb[2]); };
162 
163  // Description:
164  // Set/Get the background color of the widget when it is read-only.
165  virtual void GetReadOnlyBackgroundColor(double *r, double *g, double *b);
166  virtual double* GetReadOnlyBackgroundColor();
167  virtual void SetReadOnlyBackgroundColor(double r, double g, double b);
168  virtual void SetReadOnlyBackgroundColor(double rgb[3])
169  { this->SetReadOnlyBackgroundColor(rgb[0], rgb[1], rgb[2]); };
170 
171  // Description:
172  // Set/Get the highlight thickness, a non-negative value indicating the
173  // width of the highlight rectangle to draw around the outside of the
174  // widget when it has the input focus.
175  virtual void SetHighlightThickness(int);
176  virtual int GetHighlightThickness();
177 
178  // Description:
179  // Set/Get the border width, a non-negative value indicating the width of
180  // the 3-D border to draw around the outside of the widget (if such a border
181  // is being drawn; the Relief option typically determines this).
182  virtual void SetBorderWidth(int);
183  virtual int GetBorderWidth();
184 
185  // Description:
186  // Set/Get the 3-D effect desired for the widget.
187  // The value indicates how the interior of the widget should appear
188  // relative to its exterior.
189  // Valid constants can be found in vtkKWOptions::ReliefType.
190  virtual void SetRelief(int);
191  virtual int GetRelief();
192  virtual void SetReliefToRaised();
193  virtual void SetReliefToSunken();
194  virtual void SetReliefToFlat();
195  virtual void SetReliefToRidge();
196  virtual void SetReliefToSolid();
197  virtual void SetReliefToGroove();
198 
199  // Description:
200  // Specifies the font to use when drawing text inside the widget.
201  // You can use predefined font names (e.g. 'system'), or you can specify
202  // a set of font attributes with a platform-independent name, for example,
203  // 'times 12 bold'. In this example, the font is specified with a three
204  // element list: the first element is the font family, the second is the
205  // size, the third is a list of style parameters (normal, bold, roman,
206  // italic, underline, overstrike). Example: 'times 12 {bold italic}'.
207  // The Times, Courier and Helvetica font families are guaranteed to exist
208  // and will be matched to the corresponding (closest) font on your system.
209  // If you are familiar with the X font names specification, you can also
210  // describe the font that way (say, '*times-medium-r-*-*-12*').
211  virtual void SetFont(const char *font);
212  virtual const char* GetFont();
213 
214  // Description:
215  // Specifies a command to associate with the widget. This command is
216  // typically invoked when the return key is pressed, or the focus is lost,
217  // as specified by the CommandTrigger variable.
218  // The 'object' argument is the object that will have the method called on
219  // it. The 'method' argument is the name of the method to be called and any
220  // arguments in string form. If the object is NULL, the method is still
221  // evaluated as a simple command.
222  // The following parameters are also passed to the command:
223  // - current value: const char*
224  virtual void SetCommand(vtkObject *object, const char *method);
225  virtual void InvokeCommand(const char *value);
226 
227  // Description:
228  // Specify when Command should be invoked. Default to losing focus and
229  // return key.
230  //BTX
231  enum
232  {
233  TriggerOnFocusOut = 1,
234  TriggerOnReturnKey = 2,
235  TriggerOnAnyChange = 4
236  };
237  //ETX
238  vtkGetMacro(CommandTrigger, int);
239  virtual void SetCommandTrigger(int);
240  virtual void SetCommandTriggerToReturnKeyAndFocusOut();
241  virtual void SetCommandTriggerToAnyChange();
242 
243  // Description:
244  // Events. The EntryValueChangedEvent is triggered when the widget value
245  // is changed. It is similar in concept to the 'Command' callback but can be
246  // used by multiple listeners/observers at a time.
247  // Important: since there is no way to robustly find out when the user
248  // is done inputing characters in the text entry, the EntryValueChangedEvent
249  // event is also generated when <Return> is pressed, or the entry widget
250  // is losing focus (i.e. the user clicked outside the text field).
251  // The following parameters are also passed as client data:
252  // - current value: const char*
253  //BTX
254  enum
255  {
256  EntryValueChangedEvent = 10000
257  };
258  //ETX
259 
260  // Description:
261  // Update the "enable" state of the object and its internal parts.
262  // Depending on different Ivars (this->Enabled, the application's
263  // Limited Edition Mode, etc.), the "enable" state of the object is updated
264  // and propagated to its internal parts/subwidgets. This will, for example,
265  // enable/disable parts of the widget UI, enable/disable the visibility
266  // of 3D widgets, etc.
267  virtual void UpdateEnableState();
268 
269  // Description:
270  // Callbacks. Internal, do not use.
271  virtual void ValueCallback();
272  virtual int ValidationCallback(const char *value);
273  virtual void TracedVariableChangedCallback(
274  const char *, const char *, const char *);
275 
276 protected:
277  vtkKWEntry();
278  ~vtkKWEntry();
279 
280  // Description:
281  // Create the widget.
282  virtual void CreateWidget();
283 
284  int Width;
285  int ReadOnly;
286  int RestrictValue;
287  int CommandTrigger;
288  int SelectAllOnFocusIn;
289 
290  char *Command;
291  char *ValidationCommand;
292 
293  // Description:
294  // Configure.
295  virtual void Configure();
296  virtual void ConfigureValidation();
297  virtual void ConfigureTraceCallback(int state);
298 
299 private:
300 
301  char *InternalValueString;
302  vtkGetStringMacro(InternalValueString);
303  vtkSetStringMacro(InternalValueString);
304 
305  vtkKWEntry(const vtkKWEntry&); // Not implemented
306  void operator=(const vtkKWEntry&); // Not Implemented
307 };
308 
309 #endif