interface/wx/valnum.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/valnum.h
   3 // Purpose:     Documentation of numeric validator classes.
   4 // Author:      Vadim Zeitlin based on the submission of Fulvio Senore
   5 // Created:     2010-11-06
   6 // Copyright:   (c) 2010 wxWidgets team
   7 //              (c) 2011 Vadim Zeitlin <vadim@wxwidgets.org>
   8 // Licence:     wxWindows license
   9 /////////////////////////////////////////////////////////////////////////////
  10
  11 /**
  12     Bit masks used for numeric validator styles.
  13
  14     A combination of these flags can be used when creating wxIntegerValidator
  15     and wxFloatingPointValidator objects and with their SetStyle() methods.
  16
  17     @since 2.9.2
  18     @category{validator}
  19  */
  20 enum wxNumValidatorStyle
  21 {
  22     /**
  23         Indicates absence of any other flags.
  24
  25         This value corresponds to the default behaviour.
  26      */
  27     wxNUM_VAL_DEFAULT = 0,
  28
  29     /**
  30         Use thousands separators in the numbers.
  31
  32         When this style is used, numbers are formatted using the thousands
  33         separators after validating the user entry (if the current locale uses
  34         the thousands separators character).
  35      */
  36     wxNUM_VAL_THOUSANDS_SEPARATOR = 1,
  37
  38     /**
  39         Show a value of zero as an empty string.
  40
  41         With this style a value of zero in the associated variable is
  42         translated to an empty string and an empty value of the control is
  43         translated to a value of zero.
  44      */
  45     wxNUM_VAL_ZERO_AS_BLANK = 2,
  46
  47     /**
  48         Remove trailing zeroes from the fractional part of the number.
  49
  50         This style can only be used with wxFloatingPointValidator and indicates
  51         that trailing zeroes should be removed from the control text when it is
  52         validated. By default, as many zeroes as needed to satisfy the
  53         precision used when creating the validator will be appended.
  54
  55         For example, without this style a wxFloatingPointValidator with a
  56         precision 3 will show the value of 1.5 as "1.500" after validation.
  57         With this style, the value will be shown as just "1.5" (while a value
  58         of e.g. 1.567 will still be shown with all the three significant
  59         digits, of course).
  60      */
  61     wxNUM_VAL_NO_TRAILING_ZEROES
  62
  63 };
  64
  65 /**
  66     wxNumValidator is the common base class for numeric validator classes.
  67
  68     This class is never used directly, but only as a base class for
  69     wxIntegerValidator and wxFloatingPointValidator.
  70
  71     @tparam T
  72         Type of the values used with this validator.
  73
  74     @category{validator}
  75
  76     @since 2.9.2
  77  */
  78 template <typename T>
  79 class wxNumValidator : public wxValidator
  80 {
  81 public:
  82     /// Type of the values this validator is used with.
  83     typedef T ValueType;
  84
  85     /**
  86         Sets the minimal value accepted by the validator.
  87
  88         This value is inclusive, i.e. the value equal to @a min is accepted.
  89      */
  90     void SetMin(ValueType min);
  91
  92     /**
  93         Sets the maximal value accepted by the validator.
  94
  95         This value is inclusive, i.e. the value equal to @a max is accepted.
  96      */
  97     void SetMax(ValueType max);
  98
  99     /**
 100         Sets both minimal and maximal values accepted by the validator.
 101
 102         Calling this is equivalent to calling both SetMin() and SetMax().
 103      */
 104     void SetRange(ValueType min, ValueType max)
 105
 106
 107     /**
 108         Change the validator style.
 109
 110         Can be used to change the style of the validator after its creation.
 111         The @a style parameter must be a combination of the values from
 112         wxNumValidatorStyle enum.
 113      */
 114     void SetStyle(int style);
 115
 116
 117     /**
 118         Override base class method to format the control contents.
 119
 120         This method is called when the associated window is shown and it fills
 121         it with the contents of the associated variable, if any, formatted
 122         according to the validator style.
 123
 124         It does nothing if there is no associated variable.
 125      */
 126     virtual bool TransferToWindow();
 127
 128     /**
 129         Override base class method to validate the control contents.
 130
 131         This method is called to check the correctness of user input and fill
 132         the associated variable with the controls numeric value. It returns
 133         false if it is not a number in the configured range or if the control
 134         contents is empty for a validator without wxNUM_VAL_ZERO_AS_BLANK
 135         style.
 136
 137         It does nothing if there is no associated variable.
 138      */
 139     virtual bool TransferFromWindow();
 140 };
 141
 142 /**
 143     Validator for text entries used for integer entry.
 144
 145     This validator can be used with wxTextCtrl or wxComboBox (and potentially
 146     any other class implementing wxTextEntry interface) to check that only
 147     valid integer values can be entered into them.
 148
 149     This is a template class which can be instantiated for all the integer types
 150     (i.e. @c short, @c int, @c long and <code>long long</code> if available) as
 151     well as their unsigned versions.
 152
 153     By default this validator accepts any integer values in the range
 154     appropriate for its type, e.g. <code>INT_MIN..INT_MAX</code> for @c int or
 155     <code>0..USHRT_MAX</code> for <code>unsigned short</code>. This range can
 156     be restricted further by calling SetMin() and SetMax() or SetRange()
 157     methods inherited from the base class.
 158
 159     A simple example of using this class:
 160     @code
 161         class MyDialog : public wxDialog
 162         {
 163         public:
 164             MyDialog()
 165             {
 166                 ...
 167                 // Allow positive integers and display them with thousands
 168                 // separators.
 169                 wxIntegerValidator<unsigned long>
 170                     val(&m_value, wxNUM_VAL_THOUSANDS_SEPARATOR);
 171
 172                 // If the variable were of type "long" and not "unsigned long"
 173                 // we would have needed to call val.SetMin(0) but as it is,
 174                 // this is not needed.
 175
 176                 // Associate it with the text control:
 177                 new wxTextCtrl(this, ..., val);
 178             }
 179
 180         private:
 181             unsigned long m_value;
 182         };
 183     @endcode
 184     For more information, please see @ref overview_validator.
 185
 186     @library{wxcore}
 187     @category{validator}
 188
 189     @see @ref overview_validator, wxValidator, wxGenericValidator,
 190     wxTextValidator, wxMakeIntegerValidator()
 191
 192     @since 2.9.2
 193 */
 194 template <typename T>
 195 class wxIntegerValidator : public wxNumValidator<T>
 196 {
 197 public:
 198     /// Type of the values this validator is used with.
 199     typedef T ValueType;
 200
 201     /**
 202         Validator constructor.
 203
 204         @param value
 205             A pointer to the variable associated with the validator. If non
 206             @NULL, this variable should have a lifetime equal to or longer than
 207             the validator lifetime (which is usually determined by the lifetime
 208             of the window).
 209         @param style
 210             A combination of wxNumValidatorStyle enum values with the exception
 211             of wxNUM_VAL_NO_TRAILING_ZEROES which can't be used here.
 212     */
 213     wxIntegerValidator(ValueType *value = NULL, int style = wxNUM_VAL_DEFAULT);
 214 };
 215
 216 /**
 217     Creates a wxIntegerValidator object with automatic type deduction.
 218
 219     This function can be used to create wxIntegerValidator object without
 220     explicitly specifying its type, e.g. write just:
 221     @code
 222         new wxTextCtrl(..., wxMakeIntegerValidator(&m_var));
 223     @endcode
 224     instead of more verbose
 225     @code
 226         new wxTextCtrl(..., wxIntegerValidator<unsigned long>(&m_var));
 227     @endcode
 228
 229     @since 2.9.2
 230  */
 231 template <typename T>
 232 wxIntegerValidator<T>
 233 wxMakeIntegerValidator(T *value, int style = wxNUM_VAL_DEFAULT);
 234
 235 /**
 236     Validator for text entries used for floating point numbers entry.
 237
 238     This validator can be used with wxTextCtrl or wxComboBox (and potentially
 239     any other class implementing wxTextEntry interface) to check that only
 240     valid floating point values can be entered into them. Currently only fixed
 241     format is supported on input, i.e. scientific format with mantissa and
 242     exponent is not supported.
 243
 244     This template class can be instantiated for either @c float or @c double,
 245     <code>long double</code> values are not currently supported.
 246
 247     Similarly to wxIntegerValidator<>, the range for the accepted values is by
 248     default set appropriately for the type. Additionally, this validator allows
 249     to specify the maximum number of digits that can be entered after the
 250     decimal separator. By default this is also set appropriately for the type
 251     used, e.g. 6 for @c float and 15 for @c double on a typical IEEE-754-based
 252     implementation. As with the range, the precision can be restricted after
 253     the validator creation if necessary.
 254
 255     A simple example of using this class:
 256     @code
 257         class MyDialog : public wxDialog
 258         {
 259         public:
 260             MyDialog()
 261             {
 262                 ...
 263                 // Allow floating point numbers from 0 to 100 with 2 decimal
 264                 // digits only and handle empty string as 0 by default.
 265                 wxFloatingPointValidator<float>
 266                     val(2, &m_value, wxNUM_VAL_ZERO_AS_BLANK);
 267                 val.SetRange(0, 100);
 268
 269                 // Associate it with the text control:
 270                 new wxTextCtrl(this, ..., val);
 271             }
 272
 273         private:
 274             float m_value;
 275         };
 276     @endcode
 277
 278     For more information, please see @ref overview_validator.
 279
 280     @library{wxcore}
 281     @category{validator}
 282
 283     @see @ref overview_validator, wxValidator, wxGenericValidator,
 284     wxTextValidator, wxMakeIntegerValidator()
 285
 286     @since 2.9.2
 287 */
 288 template <typename T>
 289 class wxFloatingPointValidator : public wxNumValidator<T>
 290 {
 291 public:
 292     /// Type of the values this validator is used with.
 293     typedef T ValueType;
 294
 295     /**
 296         Validator constructor.
 297
 298         @param value
 299             A pointer to the variable associated with the validator. If non
 300             @NULL, this variable should have a lifetime equal to or longer than
 301             the validator lifetime (which is usually determined by the lifetime
 302             of the window).
 303         @param style
 304             A combination of wxNumValidatorStyle enum values.
 305         @param precision
 306             The number of decimal digits after the decimal separator to show
 307             and accept.
 308     */
 309     //@{
 310     wxFloatingPointValidator(ValueType *value = NULL,
 311                              int style = wxNUM_VAL_DEFAULT);
 312     wxFloatingPointValidator(int precision,
 313                              ValueType *value = NULL,
 314                              int style = wxNUM_VAL_DEFAULT);
 315     //@}
 316
 317
 318     /**
 319         Set precision.
 320
 321         Precision is the number of digits shown (and accepted on input)
 322         after the decimal point. By default this is set to the maximal
 323         precision supported by the type handled by the validator in its
 324         constructor.
 325      */
 326     void SetPrecision(unsigned precision);
 327 };
 328
 329 /**
 330     Creates a wxFloatingPointValidator object with automatic type deduction.
 331
 332     Similarly to wxMakeIntegerValidator(), this function allows to avoid
 333     explicitly specifying the validator type.
 334
 335     @since 2.9.2
 336  */
 337 //@{
 338 template <typename T>
 339 inline wxFloatingPointValidator<T>
 340 wxMakeFloatingPointValidator(T *value, int style = wxNUM_VAL_DEFAULT);
 341
 342 template <typename T>
 343 inline wxFloatingPointValidator<T>
 344 wxMakeFloatingPointValidator(int precision,
 345                              T *value, int style = wxNUM_VAL_DEFAULT);
 346 //@}