]> git.saurik.com Git - wxWidgets.git/blame - docs/doxygen/overviews/validator.h
fixed wxListCtrl::RefreshItem(s) - it didn't update anything before
[wxWidgets.git] / docs / doxygen / overviews / validator.h
CommitLineData
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