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 */
  82 class wxTextValidator : public wxValidator
  83 {
  84 public:
  85     /**
  86         Default constructor.
  87     */
  88     wxTextValidator(const wxTextValidator& validator);
  89
  90     /**
  91         Constructor taking a style and optional pointer to a wxString variable.
  92
  93         @param style
  94             One or more of the ::wxTextValidatorStyle styles. See SetStyle().
  95         @param valPtr
  96             A pointer to a wxString variable that contains the value. This
  97             variable should have a lifetime equal to or longer than the
  98             validator lifetime (which is usually determined by the lifetime of
  99             the window).
 100     */
 101     wxTextValidator(long style = wxFILTER_NONE, wxString* valPtr = NULL);
 102
 103     /**
 104         Clones the text validator using the copy constructor.
 105     */
 106     virtual wxObject* Clone() const;
 107
 108     /**
 109         Returns a reference to the exclude list (the list of invalid values).
 110     */
 111     wxArrayString& GetExcludes();
 112
 113     /**
 114         Returns a reference to the include list (the list of valid values).
 115     */
 116     wxArrayString& GetIncludes();
 117
 118     /**
 119         Returns the validator style.
 120
 121         @see HasFlag()
 122     */
 123     long GetStyle() const;
 124
 125     /**
 126         Returns @true if the given @a style bit is set in the current style.
 127     */
 128     bool HasFlag(wxTextValidatorStyle style) const;
 129
 130     /**
 131         Receives character input from the window and filters it according to
 132         the current validator style.
 133     */
 134     void OnChar(wxKeyEvent& event);
 135
 136     /**
 137         Sets the exclude list (invalid values for the user input).
 138     */
 139     void SetExcludes(const wxArrayString& stringList);
 140
 141     /**
 142         Breaks the given @a chars strings in single characters and sets the
 143         internal wxArrayString used to store the "excluded" characters
 144         (see SetExcludes()).
 145
 146         This function is mostly useful when @c wxFILTER_EXCLUDE_CHAR_LIST was used.
 147     */
 148     void SetCharExcludes(const wxString& chars);
 149
 150     /**
 151         Sets the include list (valid values for the user input).
 152     */
 153     void SetIncludes(const wxArrayString& stringList);
 154
 155     /**
 156         Breaks the given @a chars strings in single characters and sets the
 157         internal wxArrayString used to store the "included" characters
 158         (see SetIncludes()).
 159
 160         This function is mostly useful when @c wxFILTER_INCLUDE_CHAR_LIST was used.
 161     */
 162     void SetCharIncludes(const wxString& chars);
 163
 164     /**
 165         Sets the validator style which must be a combination of one or more
 166         of the ::wxTextValidatorStyle values.
 167
 168         Note that not all possible combinations make sense!
 169         Also note that the order in which the checks are performed is important,
 170         in case you specify more than a single style.
 171         wxTextValidator will perform the checks in the same definition order
 172         used in the ::wxTextValidatorStyle enumeration.
 173     */
 174     void SetStyle(long style);
 175
 176     /**
 177         Transfers the value in the text control to the string.
 178     */
 179     virtual bool TransferFromWindow();
 180
 181     /**
 182         Transfers the string value to the text control.
 183     */
 184     virtual bool TransferToWindow();
 185
 186     /**
 187         Validates the window contents against the include or exclude lists,
 188         depending on the validator style.
 189     */
 190     virtual bool Validate(wxWindow* parent);
 191
 192 protected:
 193
 194     /**
 195         Returns @true if all the characters of the given @a val string
 196         are present in the include list (set by SetIncludes() or SetCharIncludes()).
 197     */
 198     bool ContainsOnlyIncludedCharacters(const wxString& val) const;
 199
 200     /**
 201         Returns true if at least one character of the given @a val string
 202         is present in the exclude list (set by SetExcludes() or SetCharExcludes()).
 203     */
 204     bool ContainsExcludedCharacters(const wxString& val) const;
 205
 206     /**
 207         Returns the error message if the contents of @a val are invalid
 208         or the empty string if @a val is valid.
 209     */
 210     virtual wxString IsValid(const wxString& val) const;
 211 };
 212