Merge in from trunk r67662 to r64801

[wxWidgets.git] / docs / doxygen / overviews / validator.h

diff --git a/docs/doxygen/overviews/validator.h b/docs/doxygen/overviews/validator.h
index 4d36ff2fe469b5feb2aca64734c81abbde5fc074..81010b915fadcadad11a1318edd06647c080273a 100644 (file)
--- a/docs/doxygen/overviews/validator.h
+++ b/docs/doxygen/overviews/validator.h
@@ -3,14 +3,25 @@
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /////////////////////////////////////////////////////////////////////////////
 

-/*!
+/**

 
 @page overview_validator wxValidator Overview
 
 
 @page overview_validator wxValidator Overview
 

-Classes: wxValidator, wxTextValidator, wxGenericValidator
+Classes: wxValidator, wxTextValidator, wxGenericValidator, wxIntegerValidator,
+wxFloatingPointValidator
+
+@li @ref overview_validator_intro
+@li @ref overview_validator_anatomy
+@li @ref overview_validator_dialogs
+
+
+<hr>
+
+
+@section overview_validator_intro Validator basic concepts

 
 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
 
 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


@@ -23,14 +34,11 @@ 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.
 
 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(
 Here is an example of wxTextValidator usage.
 
 @code
 wxTextCtrl *txt1 = new wxTextCtrl(

-    this, -1, wxT(""), wxPoint(10, 10), wxSize(100, 80), 0,
+    this, -1, wxT(""), wxDefaultPosition, wxDefaultSize, 0,

     wxTextValidator(wxFILTER_ALPHA, &g_data.m_string));
 @endcode
 
     wxTextValidator(wxFILTER_ALPHA, &g_data.m_string));
 @endcode
 


@@ -45,12 +53,16 @@ functionality:
 
 The validation and filtering of input is accomplished in two ways. When a
 character is input, wxTextValidator checks the character against the 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
+filter flag (@c wxFILTER_ALPHA in this case). If the character is inappropriate,
+it is vetoed (does not appear) and a warning beep sounds (unless
+wxValidator::SetBellOnError(false) has been called).
+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.
 
 giving the error, and the dialog is not dismissed.
 

+Note that any wxWindow may have a validator; using the @c wxWS_EX_VALIDATE_RECURSIVELY
+style (see wxWindow extended styles) you can also implement recursive validation.
+

 
 @section overview_validator_anatomy Anatomy of a Validator
 
 
 @section overview_validator_anatomy Anatomy of a Validator
 


@@ -78,8 +90,9 @@ are passed by reference to window constructors, and must therefore be cloned
 internally.
 
 You can optionally define event handlers for the validator, to implement
 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
+filtering. These handlers will capture events before the control itself does
+(see @ref overview_events_processing).
+For an example implementation, see the @c valtext.h and @c valtext.cpp files in the

 wxWidgets library.
 
 
 wxWidgets library.
 
 


@@ -91,10 +104,10 @@ 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.
 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++
+The default handler for the @c 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
+wxValidator::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
 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


@@ -105,9 +118,9 @@ 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
 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).
+end the dialog by calling wxDialog::EndModal (if modal) or wxDialog::Show (if modeless).

 
 

-In fact, wxDialog contains a default command event handler for the wxID_OK
+In fact, wxDialog contains a default command event handler for the @c wxID_OK

 button. It goes like this:
 
 @code
 button. It goes like this:
 
 @code