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