From 141794f13fc943742ac9cf33d5d4d16b7c96e754 Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Fri, 6 Feb 2009 17:00:47 +0000 Subject: [PATCH] mention wxwindow::SetExtraStyle( wxWS_EX_VALIDATE_RECURSIVELY ) in the validator overview; cosmetic changes in the rest of the validator git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@58688 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/overviews/validator.h | 54 +++++++++++++++++------------- interface/wx/window.h | 15 +++++---- 2 files changed, 38 insertions(+), 31 deletions(-) diff --git a/docs/doxygen/overviews/validator.h b/docs/doxygen/overviews/validator.h index d95f67fdf7..5791ca6193 100644 --- a/docs/doxygen/overviews/validator.h +++ b/docs/doxygen/overviews/validator.h @@ -12,6 +12,16 @@ Classes: wxValidator, wxTextValidator, wxGenericValidator +@li @ref overview_validator_intro +@li @ref overview_validator_anatomy +@li @ref overview_validator_dialogs + + +
+ + +@section overview_validator_intro Example + 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 @@ -23,22 +33,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. - -@li @ref overview_validator_example -@li @ref overview_validator_anatomy -@li @ref overview_validator_dialogs - - -
- - -@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 @@ -53,12 +52,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 @@ -86,10 +89,13 @@ 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_eventhandling_processing). +For an example implementation, see the @c valtext.h and @c valtext.cpp files in the wxWidgets library. +wxwindow::SetExtraStyle( wxWS_EX_VALIDATE_RECURSIVELY ) + @section overview_validator_dialogs How Validators Interact with Dialogs @@ -99,10 +105,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 @@ -113,9 +119,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 diff --git a/interface/wx/window.h b/interface/wx/window.h index d2fe5d73a4..82f484cb5b 100644 --- a/interface/wx/window.h +++ b/interface/wx/window.h @@ -151,16 +151,17 @@ enum wxWindowVariant @beginExtraStyleTable @style{wxWS_EX_VALIDATE_RECURSIVELY} - By default, Validate/TransferDataTo/FromWindow() only work on - direct children of the window (compatible behaviour). Set this flag - to make them recursively descend into all subwindows. + By default, wxWindow::Validate(), wxWindow::TransferDataTo() and + wxWindow::TransferDataFromWindow() only work on + direct children of the window (compatible behaviour). + Set this flag to make them recursively descend into all subwindows. @style{wxWS_EX_BLOCK_EVENTS} wxCommandEvents and the objects of the derived classes are forwarded to the parent window and so on recursively by default. Using this flag for the given window allows to block this propagation at this window, i.e. prevent the events from being propagated further upwards. Dialogs have this flag on by default - for the reasons explained in the @ref overview_eventhandling "Event Handling Overview". + for the reasons explained in the @ref overview_eventhandling. @style{wxWS_EX_TRANSIENT} Don't use this window as an implicit parent for the other windows: this must be used with transient windows as otherwise there is the @@ -169,16 +170,16 @@ enum wxWindowVariant @style{wxWS_EX_CONTEXTHELP} Under Windows, puts a query button on the caption. When pressed, Windows will go into a context-sensitive help mode and wxWidgets - will send a wxEVT_HELP event if the user clicked on an application window. + will send a @c wxEVT_HELP event if the user clicked on an application window. This style cannot be used (because of the underlying native behaviour) together with @c wxMAXIMIZE_BOX or @c wxMINIMIZE_BOX, so these two styles are automatically turned off if this one is used. @style{wxWS_EX_PROCESS_IDLE} This window should always process idle events, even if the mode set - by wxIdleEvent::SetMode is wxIDLE_PROCESS_SPECIFIED. + by wxIdleEvent::SetMode is @c wxIDLE_PROCESS_SPECIFIED. @style{wxWS_EX_PROCESS_UI_UPDATES} This window should always process UI update events, even if the - mode set by wxUpdateUIEvent::SetMode is wxUPDATE_UI_PROCESS_SPECIFIED. + mode set by wxUpdateUIEvent::SetMode is @c wxUPDATE_UI_PROCESS_SPECIFIED. @endExtraStyleTable @library{wxcore} -- 2.47.2