]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/valtext.h
Override default handling so that we can position windows off-screen like on other...
[wxWidgets.git] / 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 license
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_SIMPLE_NUMBER 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