Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

More doxygen topic overview cleanup.

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52244 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
2008-03-02 10:48:31 +00:00
parent 2cd3cc948e
commit 3863c5ebd9
7 changed files with 1048 additions and 1063 deletions
Download Patch File Download Diff File Expand all files Collapse all files

241
docs/doxygen/overviews/validator.h
View File

@@ -1,5 +1,5 @@
/////////////////////////////////////////////////////////////////////////////
// Name: validator
// Name: validator.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
@@ -8,125 +8,130 @@
/*!
@page overview_validator wxValidator overview
@page overview_validator wxValidator Overview
Classes: #wxValidator, #wxTextValidator,
#wxGenericValidator
Classes: wxValidator, wxTextValidator, wxGenericValidator
The aim of the validator concept is to make dialogs very much easier to write.
A validator is an object that can be plugged into a control (such as a wxTextCtrl), and
mediates between C++ data and the control, transferring the data in either direction
and validating it. It also is able to intercept events generated
by the control, providing filtering behaviour without the need to derive a new control class.
The aim of the validator concept is to make dialogs very much easier to write.
A validator is an object that can be plugged into a control (such as a
wxTextCtrl), and mediates between C++ data and the control, transferring the
data in either direction and validating it. It also is able to intercept events
generated by the control, providing filtering behaviour without the need to
derive a new control class.
You can use a stock validator, such as #wxTextValidator (which does text
control data transfer, validation and filtering) and
#wxGenericValidator (which does data transfer for a range of controls);
or you can write your own.
@section example Example
Here is an example of wxTextValidator usage.
@code
wxTextCtrl *txt1 = new wxTextCtrl(this, -1, wxT(""),
wxPoint(10, 10), wxSize(100, 80), 0,
wxTextValidator(wxFILTER_ALPHA, _data.m_string));
@endcode
In this example, the text validator object provides the following functionality:
@li It transfers the value of g_data.m_string (a wxString variable) to the wxTextCtrl when
the dialog is initialised.
@li It transfers the wxTextCtrl data back to this variable when the dialog is dismissed.
@li It filters input characters so that only alphabetic characters are allowed.
The validation and filtering of input is accomplished in two ways. When a character is input,
wxTextValidator checks the character against the allowed filter flag (wxFILTER_ALPHA in this case). If
the character is inappropriate, it is vetoed (does not appear) and a warning beep sounds.
The second type of validation is performed when the dialog is about to be dismissed, so if
the default string contained invalid characters already, a dialog box is shown giving the
error, and the dialog is not dismissed.
@section anatomy Anatomy of a validator
A programmer creating a new validator class should provide the following functionality.
A validator constructor is responsible for allowing the programmer to specify the kind
of validation required, and perhaps a pointer to a C++ variable that is used for storing the
data for the control. If such a variable address is not supplied by the user, then
the validator should store the data internally.
The wxValidator::Validate member function should return
@true if the data in the control (not the C++ variable) is valid. It should also show
an appropriate message if data was not valid.
The wxValidator::TransferToWindow member function should
transfer the data from the validator or associated C++ variable to the control.
The wxValidator::TransferFromWindow member function should
transfer the data from the control to the validator or associated C++ variable.
There should be a copy constructor, and a wxValidator::Clone function
which returns a copy of the validator object. This is important because validators
are passed by reference to window constructors, and must therefore be cloned internally.
You can optionally define event handlers for the validator, to implement filtering. These handlers
will capture events before the control itself does.
For an example implementation, see the valtext.h and valtext.cpp files in the wxWidgets library.
@section dialogs How validators interact with dialogs
For validators to work correctly, validator functions must be called at the right times during
dialog initialisation and dismissal.
When a wxDialog::Show is called (for a modeless dialog)
or wxDialog::ShowModal is called (for a modal dialog),
the function wxWindow::InitDialog is automatically called.
This in turn sends an initialisation event to the dialog. The default handler for
the wxEVT_INIT_DIALOG event is defined in the wxWindow class to simply call
the function wxWindow::TransferDataToWindow. This
function finds all the validators in the window's children and calls the TransferToWindow
function for each. Thus, data is transferred from C++ variables to the dialog
just as the dialog is being shown.
@note If you are using a window or panel instead of a dialog, you will need to
call wxWindow::InitDialog explicitly before showing the
window.
When the user clicks on a button, for example the OK button, the application should
first call wxWindow::Validate, which returns @false if
any of the child window validators failed to validate the window data. The button handler
should return immediately if validation failed. Secondly, the application should
call wxWindow::TransferDataFromWindow and
return if this failed. It is then safe to end the dialog by calling EndModal (if modal)
or Show (if modeless).
In fact, wxDialog contains a default command event handler for the wxID_OK button. It goes like
this:
@code
void wxDialog::OnOK(wxCommandEvent& event)
{
if ( Validate() && TransferDataFromWindow() )
{
if ( IsModal() )
EndModal(wxID_OK);
else
{
SetReturnCode(wxID_OK);
this-Show(@false);
}
}
}
@endcode
So if using validators and a normal OK button, you may not even need to write any
code for handling dialog dismissal.
If you load your dialog from a resource file, you will need to iterate through the controls
setting validators, since validators can't be specified in a dialog resource.
*/
You can use a stock validator, such as wxTextValidator (which does text control
data transfer, validation and filtering) and wxGenericValidator (which does
data transfer for a range of controls); or you can write your own.
@section overview_validator_example Example
Here is an example of wxTextValidator usage.
@code
wxTextCtrl *txt1 = new wxTextCtrl(
this, -1, wxT(""), wxPoint(10, 10), wxSize(100, 80), 0,
wxTextValidator(wxFILTER_ALPHA, &g_data.m_string));
@endcode
In this example, the text validator object provides the following
functionality:
@li It transfers the value of g_data.m_string (a wxString variable) to the
wxTextCtrl when the dialog is initialised.
@li It transfers the wxTextCtrl data back to this variable when the dialog is
dismissed.
@li It filters input characters so that only alphabetic characters are allowed.
The validation and filtering of input is accomplished in two ways. When a
character is input, wxTextValidator checks the character against the allowed
filter flag (wxFILTER_ALPHA in this case). If the character is inappropriate,
it is vetoed (does not appear) and a warning beep sounds. The second type of
validation is performed when the dialog is about to be dismissed, so if the
default string contained invalid characters already, a dialog box is shown
giving the error, and the dialog is not dismissed.
@section overview_validator_anatomy Anatomy of a Validator
A programmer creating a new validator class should provide the following
functionality.
A validator constructor is responsible for allowing the programmer to specify
the kind of validation required, and perhaps a pointer to a C++ variable that
is used for storing the data for the control. If such a variable address is not
supplied by the user, then the validator should store the data internally.
The wxValidator::Validate member function should return @true if the data in
the control (not the C++ variable) is valid. It should also show an appropriate
message if data was not valid.
The wxValidator::TransferToWindow member function should transfer the data from
the validator or associated C++ variable to the control.
The wxValidator::TransferFromWindow member function should transfer the data
from the control to the validator or associated C++ variable.
There should be a copy constructor, and a wxValidator::Clone function which
returns a copy of the validator object. This is important because validators
are passed by reference to window constructors, and must therefore be cloned
internally.
You can optionally define event handlers for the validator, to implement
filtering. These handlers will capture events before the control itself does.
For an example implementation, see the valtext.h and valtext.cpp files in the
wxWidgets library.
@section overview_validator_dialogs How Validators Interact with Dialogs
For validators to work correctly, validator functions must be called at the
right times during dialog initialisation and dismissal.
When a wxDialog::Show is called (for a modeless dialog) or wxDialog::ShowModal
is called (for a modal dialog), the function wxWindow::InitDialog is
automatically called. This in turn sends an initialisation event to the dialog.
The default handler for the wxEVT_INIT_DIALOG event is defined in the wxWindow
class to simply call the function wxWindow::TransferDataToWindow. This function
finds all the validators in the window's children and calls the
TransferToWindow function for each. Thus, data is transferred from C++
variables to the dialog just as the dialog is being shown.
@note If you are using a window or panel instead of a dialog, you will need to
call wxWindow::InitDialog explicitly before showing the window.
When the user clicks on a button, for example the OK button, the application
should first call wxWindow::Validate, which returns @false if any of the child
window validators failed to validate the window data. The button handler should
return immediately if validation failed. Secondly, the application should call
wxWindow::TransferDataFromWindow and return if this failed. It is then safe to
end the dialog by calling EndModal (if modal) or Show (if modeless).
In fact, wxDialog contains a default command event handler for the wxID_OK
button. It goes like this:
@code
void wxDialog::OnOK(wxCommandEvent& event)
{
if ( Validate() && TransferDataFromWindow() )
{
if ( IsModal() )
EndModal(wxID_OK);
else
{
SetReturnCode(wxID_OK);
this->Show(false);
}
}
}
@endcode
So if using validators and a normal OK button, you may not even need to write
any code for handling dialog dismissal.
If you load your dialog from a resource file, you will need to iterate through
the controls setting validators, since validators can't be specified in a
dialog resource.
*/