interface/wx/valtext.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        valtext.h
   3 // Purpose:     interface of wxTextValidator
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     Styles used by wxTextValidator.
  12
  13     Note that when you specify more styles in wxTextValidator the validation checks
  14     are performed in the order in which the styles of this enumeration are defined.
  15 */
  16 enum wxTextValidatorStyle
  17 {
  18     /// No filtering takes place.
  19     wxFILTER_NONE,
  20
  21     /// Empty strings are filtered out.
  22     /// If this style is not specified then empty strings are accepted
  23     /// only if they pass the other checks (if you use more than one wxTextValidatorStyle).
  24     wxFILTER_EMPTY,
  25
  26     /// Non-ASCII characters are filtered out. See wxString::IsAscii.
  27     wxFILTER_ASCII,
  28
  29     /// Non-alpha characters are filtered out.
  30     /// Uses the wxWidgets wrapper for the standard CRT function @c isalpha
  31     /// (which is locale-dependent) on all characters of the string.
  32     wxFILTER_ALPHA,
  33
  34     /// Non-alphanumeric characters are filtered out.
  35     /// Uses the wxWidgets wrapper for the standard CRT function @c isalnum
  36     /// (which is locale-dependent) on all characters of the string.
  37     wxFILTER_ALPHANUMERIC,
  38
  39     /// Non-numeric characters are filtered out.
  40     /// Uses the wxWidgets wrapper for the standard CRT function @c isdigit
  41     /// (which is locale-dependent) on all characters of the string.
  42     wxFILTER_DIGITS,
  43
  44     /// Non-numeric characters are filtered out.
  45     /// Works like @c wxFILTER_DIGITS but allows also decimal points,
  46     /// minus/plus signs and the 'e' or 'E' character to input exponents.
  47     /// Note that this is not the same behaviour of wxString::IsNumber().
  48     wxFILTER_NUMERIC,
  49
  50     /// Use an include list. The validator checks if the user input is on
  51     /// the list, complaining if not. See wxTextValidator::SetIncludes().
  52     wxFILTER_INCLUDE_LIST,
  53
  54     /// Use an include list. The validator checks if each input character is
  55     /// in the list (one character per list element), complaining if not.
  56     /// See wxTextValidator::SetCharIncludes().
  57     wxFILTER_INCLUDE_CHAR_LIST,
  58
  59     /// Use an exclude list. The validator checks if the user input is on
  60     /// the list, complaining if it is. See wxTextValidator::SetExcludes().
  61     wxFILTER_EXCLUDE_LIST,
  62
  63     /// Use an exclude list. The validator checks if each input character is
  64     /// in the list (one character per list element), complaining if it is.
  65     /// See wxTextValidator::SetCharExcludes().
  66     wxFILTER_EXCLUDE_CHAR_LIST
  67 };
  68
  69 /**
  70     @class wxTextValidator
  71
  72     wxTextValidator validates text controls, providing a variety of filtering
  73     behaviours.
  74
  75     For more information, please see @ref overview_validator.
  76
  77     @library{wxcore}
  78     @category{validator}
  79
  80     @see @ref overview_validator, wxValidator, wxGenericValidator,
  81         wxIntegerValidator, wxFloatingPointValidator
  82 */
  83 class wxTextValidator : public wxValidator
  84 {
  85 public:
  86     /**
  87         Default constructor.
  88     */
  89     wxTextValidator(const wxTextValidator& validator);
  90
  91     /**
  92         Constructor taking a style and optional pointer to a wxString variable.
  93
  94         @param style
  95             One or more of the ::wxTextValidatorStyle styles. See SetStyle().
  96         @param valPtr
  97             A pointer to a wxString variable that contains the value. This
  98             variable should have a lifetime equal to or longer than the
  99             validator lifetime (which is usually determined by the lifetime of
 100             the window).
 101     */
 102     wxTextValidator(long style = wxFILTER_NONE, wxString* valPtr = NULL);
 103
 104     /**
 105         Clones the text validator using the copy constructor.
 106     */
 107     virtual wxObject* Clone() const;
 108
 109     /**
 110         Returns a reference to the exclude list (the list of invalid values).
 111     */
 112     wxArrayString& GetExcludes();
 113
 114     /**
 115         Returns a reference to the include list (the list of valid values).
 116     */
 117     wxArrayString& GetIncludes();
 118
 119     /**
 120         Returns the validator style.
 121
 122         @see HasFlag()
 123     */
 124     long GetStyle() const;
 125
 126     /**
 127         Returns @true if the given @a style bit is set in the current style.
 128     */
 129     bool HasFlag(wxTextValidatorStyle style) const;
 130
 131     /**
 132         Receives character input from the window and filters it according to
 133         the current validator style.
 134     */
 135     void OnChar(wxKeyEvent& event);
 136
 137     /**
 138         Sets the exclude list (invalid values for the user input).
 139     */
 140     void SetExcludes(const wxArrayString& stringList);
 141
 142     /**
 143         Breaks the given @a chars strings in single characters and sets the
 144         internal wxArrayString used to store the "excluded" characters
 145         (see SetExcludes()).
 146
 147         This function is mostly useful when @c wxFILTER_EXCLUDE_CHAR_LIST was used.
 148     */
 149     void SetCharExcludes(const wxString& chars);
 150
 151     /**
 152         Sets the include list (valid values for the user input).
 153     */
 154     void SetIncludes(const wxArrayString& stringList);
 155
 156     /**
 157         Breaks the given @a chars strings in single characters and sets the
 158         internal wxArrayString used to store the "included" characters
 159         (see SetIncludes()).
 160
 161         This function is mostly useful when @c wxFILTER_INCLUDE_CHAR_LIST was used.
 162     */
 163     void SetCharIncludes(const wxString& chars);
 164
 165     /**
 166         Sets the validator style which must be a combination of one or more
 167         of the ::wxTextValidatorStyle values.
 168
 169         Note that not all possible combinations make sense!
 170         Also note that the order in which the checks are performed is important,
 171         in case you specify more than a single style.
 172         wxTextValidator will perform the checks in the same definition order
 173         used in the ::wxTextValidatorStyle enumeration.
 174     */
 175     void SetStyle(long style);
 176
 177     /**
 178         Transfers the value in the text control to the string.
 179     */
 180     virtual bool TransferFromWindow();
 181
 182     /**
 183         Transfers the string value to the text control.
 184     */
 185     virtual bool TransferToWindow();
 186
 187     /**
 188         Validates the window contents against the include or exclude lists,
 189         depending on the validator style.
 190     */
 191     virtual bool Validate(wxWindow* parent);
 192
 193 protected:
 194
 195     /**
 196         Returns @true if all the characters of the given @a val string
 197         are present in the include list (set by SetIncludes() or SetCharIncludes()).
 198     */
 199     bool ContainsOnlyIncludedCharacters(const wxString& val) const;
 200
 201     /**
 202         Returns true if at least one character of the given @a val string
 203         is present in the exclude list (set by SetExcludes() or SetCharExcludes()).
 204     */
 205     bool ContainsExcludedCharacters(const wxString& val) const;
 206
 207     /**
 208         Returns the error message if the contents of @a val are invalid
 209         or the empty string if @a val is valid.
 210     */
 211     virtual wxString IsValid(const wxString& val) const;
 212 };
 213