| 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 | |