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 licence
   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     When the validator displays integers with thousands separators, the
 160     character used for the separators (usually "." or ",") depends on the locale
 161     set with wxLocale (note that you shouldn't change locale with setlocale()
 162     as this can result in a mismatch between the thousands separator used by
 163     wxLocale and the one used by the run-time library).
 164
 165     A simple example of using this class:
 166     @code
 167         class MyDialog : public wxDialog
 168         {
 169         public:
 170             MyDialog()
 171             {
 172                 ...
 173                 // Allow positive integers and display them with thousands
 174                 // separators.
 175                 wxIntegerValidator<unsigned long>
 176                     val(&m_value, wxNUM_VAL_THOUSANDS_SEPARATOR);
 177
 178                 // If the variable were of type "long" and not "unsigned long"
 179                 // we would have needed to call val.SetMin(0) but as it is,
 180                 // this is not needed.
 181
 182                 // Associate it with the text control:
 183                 new wxTextCtrl(this, ..., val);
 184             }
 185
 186         private:
 187             unsigned long m_value;
 188         };
 189     @endcode
 190     For more information, please see @ref overview_validator.
 191
 192     @library{wxcore}
 193     @category{validator}
 194
 195     @see @ref overview_validator, wxValidator, wxGenericValidator,
 196     wxTextValidator, wxMakeIntegerValidator()
 197
 198     @since 2.9.2
 199 */
 200 template <typename T>
 201 class wxIntegerValidator : public wxNumValidator<T>
 202 {
 203 public:
 204     /// Type of the values this validator is used with.
 205     typedef T ValueType;
 206
 207     /**
 208         Validator constructor.
 209
 210         @param value
 211             A pointer to the variable associated with the validator. If non
 212             @NULL, this variable should have a lifetime equal to or longer than
 213             the validator lifetime (which is usually determined by the lifetime
 214             of the window).
 215         @param style
 216             A combination of wxNumValidatorStyle enum values with the exception
 217             of wxNUM_VAL_NO_TRAILING_ZEROES which can't be used here.
 218     */
 219     wxIntegerValidator(ValueType *value = NULL, int style = wxNUM_VAL_DEFAULT);
 220 };
 221
 222 /**
 223     Creates a wxIntegerValidator object with automatic type deduction.
 224
 225     This function can be used to create wxIntegerValidator object without
 226     explicitly specifying its type, e.g. write just:
 227     @code
 228         new wxTextCtrl(..., wxMakeIntegerValidator(&m_var));
 229     @endcode
 230     instead of more verbose
 231     @code
 232         new wxTextCtrl(..., wxIntegerValidator<unsigned long>(&m_var));
 233     @endcode
 234
 235     @since 2.9.2
 236  */
 237 template <typename T>
 238 wxIntegerValidator<T>
 239 wxMakeIntegerValidator(T *value, int style = wxNUM_VAL_DEFAULT);
 240
 241 /**
 242     Validator for text entries used for floating point numbers entry.
 243
 244     This validator can be used with wxTextCtrl or wxComboBox (and potentially
 245     any other class implementing wxTextEntry interface) to check that only
 246     valid floating point values can be entered into them. Currently only fixed
 247     format is supported on input, i.e. scientific format with mantissa and
 248     exponent is not supported.
 249
 250     This template class can be instantiated for either @c float or @c double,
 251     <code>long double</code> values are not currently supported.
 252
 253     Similarly to wxIntegerValidator<>, the range for the accepted values is by
 254     default set appropriately for the type. Additionally, this validator allows
 255     to specify the maximum number of digits that can be entered after the
 256     decimal separator. By default this is also set appropriately for the type
 257     used, e.g. 6 for @c float and 15 for @c double on a typical IEEE-754-based
 258     implementation. As with the range, the precision can be restricted after
 259     the validator creation if necessary.
 260
 261     When the validator displays numbers with decimal or thousands separators,
 262     the characters used for the separators (usually "." or ",") depend on the
 263     locale set with wxLocale (note that you shouldn't change locale with
 264     setlocale() as this can result in a mismatch between the separators used by
 265     wxLocale and the one used by the run-time library).
 266
 267     A simple example of using this class:
 268     @code
 269         class MyDialog : public wxDialog
 270         {
 271         public:
 272             MyDialog()
 273             {
 274                 ...
 275                 // Allow floating point numbers from 0 to 100 with 2 decimal
 276                 // digits only and handle empty string as 0 by default.
 277                 wxFloatingPointValidator<float>
 278                     val(2, &m_value, wxNUM_VAL_ZERO_AS_BLANK);
 279                 val.SetRange(0, 100);
 280
 281                 // Associate it with the text control:
 282                 new wxTextCtrl(this, ..., val);
 283             }
 284
 285         private:
 286             float m_value;
 287         };
 288     @endcode
 289
 290     For more information, please see @ref overview_validator.
 291
 292     @library{wxcore}
 293     @category{validator}
 294
 295     @see @ref overview_validator, wxValidator, wxGenericValidator,
 296     wxTextValidator, wxMakeIntegerValidator()
 297
 298     @since 2.9.2
 299 */
 300 template <typename T>
 301 class wxFloatingPointValidator : public wxNumValidator<T>
 302 {
 303 public:
 304     /// Type of the values this validator is used with.
 305     typedef T ValueType;
 306
 307     /**
 308         Validator constructor.
 309
 310         @param value
 311             A pointer to the variable associated with the validator. If non
 312             @NULL, this variable should have a lifetime equal to or longer than
 313             the validator lifetime (which is usually determined by the lifetime
 314             of the window).
 315         @param style
 316             A combination of wxNumValidatorStyle enum values.
 317         @param precision
 318             The number of decimal digits after the decimal separator to show
 319             and accept.
 320     */
 321     //@{
 322     wxFloatingPointValidator(ValueType *value = NULL,
 323                              int style = wxNUM_VAL_DEFAULT);
 324     wxFloatingPointValidator(int precision,
 325                              ValueType *value = NULL,
 326                              int style = wxNUM_VAL_DEFAULT);
 327     //@}
 328
 329
 330     /**
 331         Set precision.
 332
 333         Precision is the number of digits shown (and accepted on input)
 334         after the decimal point. By default this is set to the maximal
 335         precision supported by the type handled by the validator in its
 336         constructor.
 337      */
 338     void SetPrecision(unsigned precision);
 339 };
 340
 341 /**
 342     Creates a wxFloatingPointValidator object with automatic type deduction.
 343
 344     Similarly to wxMakeIntegerValidator(), this function allows to avoid
 345     explicitly specifying the validator type.
 346
 347     @since 2.9.2
 348  */
 349 //@{
 350 template <typename T>
 351 inline wxFloatingPointValidator<T>
 352 wxMakeFloatingPointValidator(T *value, int style = wxNUM_VAL_DEFAULT);
 353
 354 template <typename T>
 355 inline wxFloatingPointValidator<T>
 356 wxMakeFloatingPointValidator(int precision,
 357                              T *value, int style = wxNUM_VAL_DEFAULT);
 358 //@}