]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: validate.h | |
e54c96f1 | 3 | // Purpose: interface of wxValidator |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
526954c5 | 6 | // Licence: wxWindows licence |
23324ae1 FM |
7 | ///////////////////////////////////////////////////////////////////////////// |
8 | ||
9 | /** | |
10 | @class wxValidator | |
7c913512 | 11 | |
fbec75d0 BP |
12 | wxValidator is the base class for a family of validator classes that |
13 | mediate between a class of control, and application data. | |
7c913512 | 14 | |
23324ae1 | 15 | A validator has three major roles: |
7c913512 | 16 | |
fbec75d0 BP |
17 | -# To transfer data from a C++ variable or own storage to and from a |
18 | control. | |
19 | -# To validate data in a control, and show an appropriate error message. | |
20 | -# To filter events (such as keystrokes), thereby changing the behaviour | |
21 | of the associated control. | |
7c913512 | 22 | |
23324ae1 | 23 | Validators can be plugged into controls dynamically. |
7c913512 | 24 | |
fbec75d0 | 25 | To specify a default, "null" validator, use ::wxDefaultValidator. |
7c913512 | 26 | |
d9faa1fe | 27 | For more information, please see @ref overview_validator. |
7c913512 | 28 | |
d9faa1fe | 29 | @beginWxPythonOnly |
fbec75d0 BP |
30 | If you wish to create a validator class in wxPython you should derive the |
31 | class from @c wxPyValidator in order to get Python-aware capabilities for | |
32 | the various virtual methods. | |
d9faa1fe | 33 | @endWxPythonOnly |
7c913512 | 34 | |
23324ae1 FM |
35 | @library{wxcore} |
36 | @category{validator} | |
7c913512 | 37 | |
d9faa1fe FM |
38 | @stdobjects |
39 | ::wxDefaultValidator | |
40 | ||
41 | @see @ref overview_validator, wxTextValidator, wxGenericValidator | |
23324ae1 FM |
42 | */ |
43 | class wxValidator : public wxEvtHandler | |
44 | { | |
45 | public: | |
46 | /** | |
47 | Constructor. | |
48 | */ | |
49 | wxValidator(); | |
50 | ||
51 | /** | |
52 | Destructor. | |
53 | */ | |
adaaa686 | 54 | virtual ~wxValidator(); |
23324ae1 FM |
55 | |
56 | /** | |
fbec75d0 BP |
57 | All validator classes must implement the Clone() function, which |
58 | returns an identical copy of itself. | |
d9faa1fe | 59 | |
fbec75d0 BP |
60 | This is because validators are passed to control constructors as |
61 | references which must be copied. Unlike objects such as pens and | |
62 | brushes, it does not make sense to have a reference counting scheme to | |
63 | do this cloning because all validators should have separate data. | |
d9faa1fe | 64 | |
d29a9a8a | 65 | @return This base function returns @NULL. |
23324ae1 | 66 | */ |
328f5751 | 67 | virtual wxObject* Clone() const; |
23324ae1 FM |
68 | |
69 | /** | |
70 | Returns the window associated with the validator. | |
71 | */ | |
328f5751 | 72 | wxWindow* GetWindow() const; |
23324ae1 FM |
73 | |
74 | /** | |
75 | This functions switches on or turns off the error sound produced by the | |
76 | validators if an invalid key is pressed. | |
c27181d1 VZ |
77 | |
78 | @since 2.9.1 | |
79 | ||
80 | @param suppress | |
81 | If @true, error sound is not played when a validator detects an | |
82 | error. If @false, error sound is enabled. | |
23324ae1 | 83 | */ |
c27181d1 | 84 | static void SuppressBellOnError(bool suppress = true); |
23324ae1 FM |
85 | |
86 | /** | |
87 | Associates a window with the validator. | |
180d62d8 FM |
88 | |
89 | This function is automatically called by wxWidgets when creating a wxWindow-derived | |
90 | class instance which takes a wxValidator reference. | |
91 | ||
92 | E.g. | |
93 | @code | |
94 | new wxTextCtrl(this, wxID_ANY, wxEmptyString, wxDefaultPosition, wxDefaultSize, 0, | |
95 | wxTextValidator(wxFILTER_ALPHA, &g_data.m_string)); | |
96 | @endcode | |
97 | will automatically link the wxTextValidator instance with the wxTextCtrl | |
98 | instance. | |
23324ae1 FM |
99 | */ |
100 | void SetWindow(wxWindow* window); | |
101 | ||
102 | /** | |
fbec75d0 BP |
103 | This overridable function is called when the value in the window must |
104 | be transferred to the validator. | |
d9faa1fe FM |
105 | |
106 | @return @false if there is a problem. | |
23324ae1 | 107 | */ |
d9faa1fe | 108 | virtual bool TransferFromWindow(); |
23324ae1 FM |
109 | |
110 | /** | |
111 | This overridable function is called when the value associated with the | |
d9faa1fe FM |
112 | validator must be transferred to the window. |
113 | ||
114 | @return @false if there is a problem. | |
23324ae1 FM |
115 | */ |
116 | virtual bool TransferToWindow(); | |
117 | ||
118 | /** | |
fbec75d0 BP |
119 | This overridable function is called when the value in the associated |
120 | window must be validated. | |
d9faa1fe | 121 | |
180d62d8 FM |
122 | @param parent |
123 | The parent of the window associated with the validator. | |
124 | ||
fbec75d0 BP |
125 | @return @false if the value in the window is not valid; you may pop up |
126 | an error dialog. | |
23324ae1 FM |
127 | */ |
128 | virtual bool Validate(wxWindow* parent); | |
129 | }; | |
e54c96f1 | 130 | |
d9faa1fe | 131 | /** |
fbec75d0 | 132 | An empty, "null" wxValidator instance. |
d9faa1fe | 133 | */ |
05b0355a | 134 | const wxValidator wxDefaultValidator; |
fbec75d0 | 135 |