]>
Commit | Line | Data |
---|---|---|
15b6757b FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: validator | |
3 | // Purpose: topic overview | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /*! | |
36c9828f | 10 | |
15b6757b | 11 | @page validator_overview wxValidator overview |
36c9828f FM |
12 | |
13 | Classes: #wxValidator, #wxTextValidator, | |
15b6757b FM |
14 | #wxGenericValidator |
15 | The aim of the validator concept is to make dialogs very much easier to write. | |
16 | A validator is an object that can be plugged into a control (such as a wxTextCtrl), and | |
17 | mediates between C++ data and the control, transferring the data in either direction | |
18 | and validating it. It also is able to intercept events generated | |
19 | by the control, providing filtering behaviour without the need to derive a new control class. | |
20 | You can use a stock validator, such as #wxTextValidator (which does text | |
36c9828f | 21 | control data transfer, validation and filtering) and |
15b6757b FM |
22 | #wxGenericValidator (which does data transfer for a range of controls); |
23 | or you can write your own. | |
24 | @b Example | |
25 | Here is an example of wxTextValidator usage. | |
36c9828f | 26 | |
15b6757b FM |
27 | @code |
28 | wxTextCtrl *txt1 = new wxTextCtrl(this, -1, wxT(""), | |
29 | wxPoint(10, 10), wxSize(100, 80), 0, | |
30 | wxTextValidator(wxFILTER_ALPHA, _data.m_string)); | |
31 | @endcode | |
36c9828f | 32 | |
15b6757b | 33 | In this example, the text validator object provides the following functionality: |
36c9828f FM |
34 | |
35 | ||
15b6757b FM |
36 | It transfers the value of g_data.m_string (a wxString variable) to the wxTextCtrl when |
37 | the dialog is initialised. | |
38 | It transfers the wxTextCtrl data back to this variable when the dialog is dismissed. | |
39 | It filters input characters so that only alphabetic characters are allowed. | |
36c9828f FM |
40 | |
41 | ||
15b6757b FM |
42 | The validation and filtering of input is accomplished in two ways. When a character is input, |
43 | wxTextValidator checks the character against the allowed filter flag (wxFILTER_ALPHA in this case). If | |
44 | the character is inappropriate, it is vetoed (does not appear) and a warning beep sounds. | |
45 | The second type of validation is performed when the dialog is about to be dismissed, so if | |
46 | the default string contained invalid characters already, a dialog box is shown giving the | |
47 | error, and the dialog is not dismissed. | |
48 | @b Anatomy of a validator | |
49 | A programmer creating a new validator class should provide the following functionality. | |
50 | A validator constructor is responsible for allowing the programmer to specify the kind | |
51 | of validation required, and perhaps a pointer to a C++ variable that is used for storing the | |
52 | data for the control. If such a variable address is not supplied by the user, then | |
53 | the validator should store the data internally. | |
54 | The wxValidator::Validate member function should return | |
55 | @true if the data in the control (not the C++ variable) is valid. It should also show | |
56 | an appropriate message if data was not valid. | |
57 | The wxValidator::TransferToWindow member function should | |
58 | transfer the data from the validator or associated C++ variable to the control. | |
59 | The wxValidator::TransferFromWindow member function should | |
60 | transfer the data from the control to the validator or associated C++ variable. | |
61 | There should be a copy constructor, and a wxValidator::Clone function | |
62 | which returns a copy of the validator object. This is important because validators | |
63 | are passed by reference to window constructors, and must therefore be cloned internally. | |
64 | You can optionally define event handlers for the validator, to implement filtering. These handlers | |
65 | will capture events before the control itself does. | |
66 | For an example implementation, see the valtext.h and valtext.cpp files in the wxWidgets library. | |
67 | @b How validators interact with dialogs | |
68 | For validators to work correctly, validator functions must be called at the right times during | |
69 | dialog initialisation and dismissal. | |
70 | When a wxDialog::Show is called (for a modeless dialog) | |
71 | or wxDialog::ShowModal is called (for a modal dialog), | |
72 | the function wxWindow::InitDialog is automatically called. | |
73 | This in turn sends an initialisation event to the dialog. The default handler for | |
74 | the wxEVT_INIT_DIALOG event is defined in the wxWindow class to simply call | |
75 | the function wxWindow::TransferDataToWindow. This | |
76 | function finds all the validators in the window's children and calls the TransferToWindow | |
77 | function for each. Thus, data is transferred from C++ variables to the dialog | |
78 | just as the dialog is being shown. | |
36c9828f | 79 | |
15b6757b FM |
80 | If you are using a window or panel instead of a dialog, you will need to |
81 | call wxWindow::InitDialog explicitly before showing the | |
82 | window. | |
36c9828f | 83 | |
15b6757b FM |
84 | When the user clicks on a button, for example the OK button, the application should |
85 | first call wxWindow::Validate, which returns @false if | |
86 | any of the child window validators failed to validate the window data. The button handler | |
87 | should return immediately if validation failed. Secondly, the application should | |
88 | call wxWindow::TransferDataFromWindow and | |
89 | return if this failed. It is then safe to end the dialog by calling EndModal (if modal) | |
90 | or Show (if modeless). | |
91 | In fact, wxDialog contains a default command event handler for the wxID_OK button. It goes like | |
92 | this: | |
36c9828f | 93 | |
15b6757b FM |
94 | @code |
95 | void wxDialog::OnOK(wxCommandEvent& event) | |
96 | { | |
97 | if ( Validate() && TransferDataFromWindow() ) | |
98 | { | |
99 | if ( IsModal() ) | |
100 | EndModal(wxID_OK); | |
101 | else | |
102 | { | |
103 | SetReturnCode(wxID_OK); | |
104 | this-Show(@false); | |
105 | } | |
106 | } | |
107 | } | |
108 | @endcode | |
36c9828f | 109 | |
15b6757b FM |
110 | So if using validators and a normal OK button, you may not even need to write any |
111 | code for handling dialog dismissal. | |
112 | If you load your dialog from a resource file, you will need to iterate through the controls | |
113 | setting validators, since validators can't be specified in a dialog resource. | |
36c9828f | 114 | |
15b6757b | 115 | */ |
36c9828f FM |
116 | |
117 |