Undid accidental modification of wxTaskBarIcon in the last commit.

[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$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
-/*!
+/**
 
 @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
@@ -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.
 
-
-@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,
+    this, -1, wxT(""), wxDefaultPosition, wxDefaultSize, 0,
     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
-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.
 
+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
 
@@ -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
-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.
 
 
@@ -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.
-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
@@ -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
-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