| Version: 3.2.5

wxValidator Overview

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.

Here is an example of wxTextValidator usage.

wxTextCtrl *txt1 = new wxTextCtrl(
this, -1, wxT(""), wxDefaultPosition, wxDefaultSize, 0,
wxTextValidator(wxFILTER_ALPHA, &g_data.m_string));
wxTextCtrl
A text control allows text to be displayed and edited.
Definition: textctrl.h:1436
wxTextValidator
wxTextValidator validates text controls, providing a variety of filtering behaviours.
Definition: valtext.h:105
wxDefaultSize
const wxSize wxDefaultSize
Global instance of a wxSize object initialized to (-1,-1).
Definition: gdicmn.h:1108
wxDefaultPosition
const wxPoint wxDefaultPosition
Global instance of a wxPoint initialized with values (-1,-1).
Definition: gdicmn.h:782
wxT
#define wxT(string)
This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...
Definition: chartype.h:32
wxFILTER_ALPHA
@ wxFILTER_ALPHA
Non-alpha characters are filtered out.
Definition: valtext.h:34

In this example, the text validator object provides the following functionality:

- It transfers the value of g_data.m_string (a wxString variable) to the wxTextCtrl when the dialog is initialised.
- It transfers the wxTextCtrl data back to this variable when the dialog is dismissed.
- 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 (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 and it will be used when transferring data to or from the parent window.

See also
  wxValidator, wxTextValidator, wxGenericValidator, wxIntegerValidator, wxFloatingPointValidator

# 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 (see How Events are Processed). For an example implementation, see the `valtext.h` and `valtext.cpp` files in the wxWidgets library.

# 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 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 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 wxDialog::EndModal (if modal) or wxDialog::Show (if modeless).

In fact, wxDialog contains a default command event handler for the `wxID_OK` button. It goes like this:

void wxDialog::OnOK(wxCommandEvent& event)
{
if ( Validate() && TransferDataFromWindow() )
{
if ( IsModal() )
EndModal(wxID_OK);
else
{
SetReturnCode(wxID_OK);
this->Show(false);
}
}
}
wxCommandEvent
This event class contains information about command events, which originate from a variety of simple ...
Definition: event.h:2042
wxDialog::SetReturnCode
void SetReturnCode(int retCode)
Sets the return code for this window.
wxDialog::Show
virtual bool Show(bool show=true)
Hides or shows the dialog.
wxDialog::EndModal
virtual void EndModal(int retCode)
Ends a modal dialog, passing a value to be returned from the ShowModal() invocation.
wxDialog::IsModal
virtual bool IsModal() const
Returns true if the dialog box is modal, false otherwise.
wxWindow::TransferDataFromWindow
virtual bool TransferDataFromWindow()
Transfers values from child controls to data areas specified by their validators.
wxWindow::Validate
virtual bool Validate()
Validates the current values of the child controls using their validators.
wxID_OK
@ wxID_OK
Standard button and menu IDs.
Definition: defs.h:664

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.