docs/doxygen/overviews/validator.h

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