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