00001 /*========================================================================= 00002 00003 Module: vtkKWEntry.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 vtkKWEntry - a single line text entry widget 00015 // .SECTION Description 00016 // A simple widget used for collecting keyboard input from the user. This 00017 // widget provides support for single line input. 00018 00019 #ifndef __vtkKWEntry_h 00020 #define __vtkKWEntry_h 00021 00022 #include "vtkKWCoreWidget.h" 00023 00024 class KWWidgets_EXPORT vtkKWEntry : public vtkKWCoreWidget 00025 { 00026 public: 00027 static vtkKWEntry* New(); 00028 vtkTypeRevisionMacro(vtkKWEntry,vtkKWCoreWidget); 00029 void PrintSelf(ostream& os, vtkIndent indent); 00030 00031 // Description: 00032 // Set/Get the value of the entry in a few different formats. 00033 // In the SetValue method with double, values are printed in printf's %f 00034 // or %e format, whichever is more compact for the given value and precision. 00035 // The %e format is used only when the exponent of the value is less than 00036 // -4 or greater than or equal to the precision argument (which can be 00037 // controlled using the second parameter of SetValue). Trailing zeros 00038 // are truncated, and the decimal point appears only if one or more digits 00039 // follow it. 00040 // Set/GetHexadecimalValueAsRGB provides a convenience way to enter/parse 00041 // a RGB triplet formatted in hexadecimal. Note that the values are 00042 // int, not double (i.e. 0 to 255 instead of VTK's normalized 0.0 to 1.0) 00043 // IMPORTANT: whenever possible, use any of the GetValueAs...() methods 00044 // GetHexadecimalValueAsRGB will set r,g,b to -1, -1, -1 if the hexadecimal 00045 // value could not be parsed. 00046 // to retrieve the value if it is meant to be a number. This is faster 00047 // than calling GetValue() and converting the resulting string to a number. 00048 virtual void SetValue(const char *); 00049 virtual const char* GetValue(); 00050 virtual void SetValueAsInt(int a); 00051 virtual int GetValueAsInt(); 00052 virtual void SetValueAsFormattedDouble(double f, int size); 00053 virtual void SetValueAsDouble(double f); 00054 virtual double GetValueAsDouble(); 00055 virtual void SetHexadecimalValueAsRGB(int r, int g, int b); 00056 virtual void GetHexadecimalValueAsRGB(int &r, int &g, int &b); 00057 00058 // Description: 00059 // The width is the number of charaters wide the entry box can fit. 00060 // To keep from changing behavior of the entry, the default 00061 // value is -1 wich means the width is not explicitly set and will default 00062 // to whatever value Tk is using (at this point, 20). Set it to 0 00063 // and the widget should pick a size just large enough to hold its text. 00064 virtual void SetWidth(int width); 00065 vtkGetMacro(Width, int); 00066 00067 // Description: 00068 // Set/Get readonly flag. This flags makes the entry read only. 00069 virtual void SetReadOnly(int); 00070 vtkBooleanMacro(ReadOnly, int); 00071 vtkGetMacro(ReadOnly, int); 00072 00073 // Description: 00074 // Set/Get password mode flag. If this flag is set, then the true contents 00075 // of the entry are not displayed in the window. Instead, each character in 00076 // the entry's value will be displayed as '*'. This is useful, for example, 00077 // if the entry is to be used to enter a password. If characters in the entry 00078 // are selected and copied elsewhere, the information copied will be what is 00079 // displayed, not the true contents of the entry. 00080 vtkBooleanMacro(PasswordMode, int); 00081 virtual void SetPasswordMode(int); 00082 virtual int GetPasswordMode(); 00083 00084 // Description: 00085 // Select all text in the entry 00086 virtual void SelectAll(); 00087 00088 // Description: 00089 // Set/Get if the entry's contents should be selected automatically 00090 // when the entry receives focus. Off by default, this variable can be 00091 // turned on to On to emulate the effect of the URL entry in a browser 00092 // window. 00093 vtkBooleanMacro(SelectAllOnFocusIn, int); 00094 virtual void SetSelectAllOnFocusIn(int); 00095 vtkGetMacro(SelectAllOnFocusIn, int); 00096 00097 // Description: 00098 // Restrict the value to a given type (integer, hexadecimal, double, or 00099 // no restriction). 00100 // Note: checks against RestrictValue are performed before ValidationCommand. 00101 //BTX 00102 enum 00103 { 00104 RestrictNone = 0, 00105 RestrictInteger, 00106 RestrictDouble, 00107 RestrictHexadecimal 00108 }; 00109 //ETX 00110 vtkGetMacro(RestrictValue, int); 00111 virtual void SetRestrictValue(int); 00112 virtual void SetRestrictValueToInteger(); 00113 virtual void SetRestrictValueToDouble(); 00114 virtual void SetRestrictValueToHexadecimal(); 00115 virtual void SetRestrictValueToNone(); 00116 00117 // Description: 00118 // Specifies a command to associate with this step. This command can 00119 // be used to validate the contents of the widget. 00120 // Note: checks against RestrictValue are performed before ValidationCommand. 00121 // The 'object' argument is the object that will have the method called on 00122 // it. The 'method' argument is the name of the method to be called and any 00123 // arguments in string form. If the object is NULL, the method is still 00124 // evaluated as a simple command. 00125 // This command should return 1 if the contents is valid, 0 otherwise. 00126 // The following parameters are also passed to the command: 00127 // - current value: const char* 00128 virtual void SetValidationCommand(vtkObject *object, const char *method); 00129 virtual int InvokeValidationCommand(const char *value); 00130 00131 // Description: 00132 // Set/Get the background color of the widget. 00133 virtual void GetBackgroundColor(double *r, double *g, double *b); 00134 virtual double* GetBackgroundColor(); 00135 virtual void SetBackgroundColor(double r, double g, double b); 00136 virtual void SetBackgroundColor(double rgb[3]) 00137 { this->SetBackgroundColor(rgb[0], rgb[1], rgb[2]); }; 00138 00139 // Description: 00140 // Set/Get the foreground color of the widget. 00141 virtual void GetForegroundColor(double *r, double *g, double *b); 00142 virtual double* GetForegroundColor(); 00143 virtual void SetForegroundColor(double r, double g, double b); 00144 virtual void SetForegroundColor(double rgb[3]) 00145 { this->SetForegroundColor(rgb[0], rgb[1], rgb[2]); }; 00146 00147 // Description: 00148 // Set/Get the background color of the widget when it is disabled. 00149 virtual void GetDisabledBackgroundColor(double *r, double *g, double *b); 00150 virtual double* GetDisabledBackgroundColor(); 00151 virtual void SetDisabledBackgroundColor(double r, double g, double b); 00152 virtual void SetDisabledBackgroundColor(double rgb[3]) 00153 { this->SetDisabledBackgroundColor(rgb[0], rgb[1], rgb[2]); }; 00154 00155 // Description: 00156 // Set/Get the foreground color of the widget when it is disabled. 00157 virtual void GetDisabledForegroundColor(double *r, double *g, double *b); 00158 virtual double* GetDisabledForegroundColor(); 00159 virtual void SetDisabledForegroundColor(double r, double g, double b); 00160 virtual void SetDisabledForegroundColor(double rgb[3]) 00161 { this->SetDisabledForegroundColor(rgb[0], rgb[1], rgb[2]); }; 00162 00163 // Description: 00164 // Set/Get the background color of the widget when it is read-only. 00165 virtual void GetReadOnlyBackgroundColor(double *r, double *g, double *b); 00166 virtual double* GetReadOnlyBackgroundColor(); 00167 virtual void SetReadOnlyBackgroundColor(double r, double g, double b); 00168 virtual void SetReadOnlyBackgroundColor(double rgb[3]) 00169 { this->SetReadOnlyBackgroundColor(rgb[0], rgb[1], rgb[2]); }; 00170 00171 // Description: 00172 // Set/Get the highlight thickness, a non-negative value indicating the 00173 // width of the highlight rectangle to draw around the outside of the 00174 // widget when it has the input focus. 00175 virtual void SetHighlightThickness(int); 00176 virtual int GetHighlightThickness(); 00177 00178 // Description: 00179 // Set/Get the border width, a non-negative value indicating the width of 00180 // the 3-D border to draw around the outside of the widget (if such a border 00181 // is being drawn; the Relief option typically determines this). 00182 virtual void SetBorderWidth(int); 00183 virtual int GetBorderWidth(); 00184 00185 // Description: 00186 // Set/Get the 3-D effect desired for the widget. 00187 // The value indicates how the interior of the widget should appear 00188 // relative to its exterior. 00189 // Valid constants can be found in vtkKWOptions::ReliefType. 00190 virtual void SetRelief(int); 00191 virtual int GetRelief(); 00192 virtual void SetReliefToRaised(); 00193 virtual void SetReliefToSunken(); 00194 virtual void SetReliefToFlat(); 00195 virtual void SetReliefToRidge(); 00196 virtual void SetReliefToSolid(); 00197 virtual void SetReliefToGroove(); 00198 00199 // Description: 00200 // Specifies the font to use when drawing text inside the widget. 00201 // You can use predefined font names (e.g. 'system'), or you can specify 00202 // a set of font attributes with a platform-independent name, for example, 00203 // 'times 12 bold'. In this example, the font is specified with a three 00204 // element list: the first element is the font family, the second is the 00205 // size, the third is a list of style parameters (normal, bold, roman, 00206 // italic, underline, overstrike). Example: 'times 12 {bold italic}'. 00207 // The Times, Courier and Helvetica font families are guaranteed to exist 00208 // and will be matched to the corresponding (closest) font on your system. 00209 // If you are familiar with the X font names specification, you can also 00210 // describe the font that way (say, '*times-medium-r-*-*-12*'). 00211 virtual void SetFont(const char *font); 00212 virtual const char* GetFont(); 00213 00214 // Description: 00215 // Specifies a command to associate with the widget. This command is 00216 // typically invoked when the return key is pressed, or the focus is lost, 00217 // as specified by the CommandTrigger variable. 00218 // The 'object' argument is the object that will have the method called on 00219 // it. The 'method' argument is the name of the method to be called and any 00220 // arguments in string form. If the object is NULL, the method is still 00221 // evaluated as a simple command. 00222 // The following parameters are also passed to the command: 00223 // - current value: const char* 00224 virtual void SetCommand(vtkObject *object, const char *method); 00225 virtual void InvokeCommand(const char *value); 00226 00227 // Description: 00228 // Specify when Command should be invoked. Default to losing focus and 00229 // return key. 00230 //BTX 00231 enum 00232 { 00233 TriggerOnFocusOut = 1, 00234 TriggerOnReturnKey = 2, 00235 TriggerOnAnyChange = 4 00236 }; 00237 //ETX 00238 vtkGetMacro(CommandTrigger, int); 00239 virtual void SetCommandTrigger(int); 00240 virtual void SetCommandTriggerToReturnKeyAndFocusOut(); 00241 virtual void SetCommandTriggerToAnyChange(); 00242 00243 // Description: 00244 // Events. The EntryValueChangedEvent is triggered when the widget value 00245 // is changed. It is similar in concept to the 'Command' callback but can be 00246 // used by multiple listeners/observers at a time. 00247 // Important: since there is no way to robustly find out when the user 00248 // is done inputing characters in the text entry, the EntryValueChangedEvent 00249 // event is also generated when <Return> is pressed, or the entry widget 00250 // is losing focus (i.e. the user clicked outside the text field). 00251 // The following parameters are also passed as client data: 00252 // - current value: const char* 00253 //BTX 00254 enum 00255 { 00256 EntryValueChangedEvent = 10000 00257 }; 00258 //ETX 00259 00260 // Description: 00261 // Update the "enable" state of the object and its internal parts. 00262 // Depending on different Ivars (this->Enabled, the application's 00263 // Limited Edition Mode, etc.), the "enable" state of the object is updated 00264 // and propagated to its internal parts/subwidgets. This will, for example, 00265 // enable/disable parts of the widget UI, enable/disable the visibility 00266 // of 3D widgets, etc. 00267 virtual void UpdateEnableState(); 00268 00269 // Description: 00270 // Callbacks. Internal, do not use. 00271 virtual void ValueCallback(); 00272 virtual int ValidationCallback(const char *value); 00273 virtual void TracedVariableChangedCallback( 00274 const char *, const char *, const char *); 00275 00276 protected: 00277 vtkKWEntry(); 00278 ~vtkKWEntry(); 00279 00280 // Description: 00281 // Create the widget. 00282 virtual void CreateWidget(); 00283 00284 int Width; 00285 int ReadOnly; 00286 int RestrictValue; 00287 int CommandTrigger; 00288 int SelectAllOnFocusIn; 00289 00290 char *Command; 00291 char *ValidationCommand; 00292 00293 // Description: 00294 // Configure. 00295 virtual void Configure(); 00296 virtual void ConfigureValidation(); 00297 virtual void ConfigureTraceCallback(int state); 00298 00299 private: 00300 00301 char *InternalValueString; 00302 vtkGetStringMacro(InternalValueString); 00303 vtkSetStringMacro(InternalValueString); 00304 00305 vtkKWEntry(const vtkKWEntry&); // Not implemented 00306 void operator=(const vtkKWEntry&); // Not Implemented 00307 }; 00308 00309 #endif