1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>wxWidgets: wxValidator Overview</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="page_container">
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0" style="width: 100%;">
<tbody>
<tr>
<td id="projectlogo">
<a href="http://www.wxwidgets.org/" target="_new">
<img alt="wxWidgets" src="logo.png"/>
</a>
</td>
<td style="padding-left: 0.5em; text-align: right;">
<span id="projectnumber">Version: 3.0.2</span>
</td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.8.2 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Categories</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">Documentation</a></li><li class="navelem"><a class="el" href="page_topics.html">Programming Guides</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title"><a class="el" href="classwx_validator.html" title="wxValidator is the base class for a family of validator classes that mediate between a class of contr...">wxValidator</a> Overview </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#overview_validator_anatomy">Anatomy of a Validator</a></li>
<li class="level1"><a href="#overview_validator_dialogs">How Validators Interact with Dialogs</a></li>
</ul>
</div>
<div class="textblock"><p>The aim of the validator concept is to make dialogs very much easier to write.</p>
<p>A validator is an object that can be plugged into a control (such as a <a class="el" href="classwx_text_ctrl.html" title="A text control allows text to be displayed and edited.">wxTextCtrl</a>), 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.</p>
<p>You can use a stock validator, such as <a class="el" href="classwx_text_validator.html" title="wxTextValidator validates text controls, providing a variety of filtering behaviours.">wxTextValidator</a> (which does text control data transfer, validation and filtering) and <a class="el" href="classwx_generic_validator.html" title="wxGenericValidator performs data transfer (but not validation or filtering) for many type of controls...">wxGenericValidator</a> (which does data transfer for a range of controls); or you can write your own.</p>
<p>Here is an example of <a class="el" href="classwx_text_validator.html" title="wxTextValidator validates text controls, providing a variety of filtering behaviours.">wxTextValidator</a> usage.</p>
<div class="fragment"><div class="line"><a class="code" href="classwx_text_ctrl.html" title="A text control allows text to be displayed and edited.">wxTextCtrl</a> *txt1 = <span class="keyword">new</span> <a class="code" href="classwx_text_ctrl.html" title="A text control allows text to be displayed and edited.">wxTextCtrl</a>(</div>
<div class="line"> <span class="keyword">this</span>, -1, <a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">""</span>), <a class="code" href="gdicmn_8h.html#af5a90c753eaf3d3e3e5068a19ec3c1d0" title="Global instance of a wxPoint initialized with values (-1,-1).">wxDefaultPosition</a>, <a class="code" href="gdicmn_8h.html#a33a012cdb075e9f78c93f63bec2dc27b" title="Global instance of a wxSize object initialized to (-1,-1).">wxDefaultSize</a>, 0,</div>
<div class="line"> <a class="code" href="classwx_text_validator.html" title="wxTextValidator validates text controls, providing a variety of filtering behaviours.">wxTextValidator</a>(<a class="code" href="valtext_8h.html#aa02d29254d60e0c81f17696c9cecbd07ab7fa483928635f2e066229fe0bceec93" title="Non-alpha characters are filtered out.">wxFILTER_ALPHA</a>, &g_data.m_string));</div>
</div><!-- fragment --><p>In this example, the text validator object provides the following functionality:</p>
<ul>
<li>It transfers the value of g_data.m_string (a <a class="el" href="classwx_string.html" title="String class for passing textual data to or receiving it from wxWidgets.">wxString</a> variable) to the <a class="el" href="classwx_text_ctrl.html" title="A text control allows text to be displayed and edited.">wxTextCtrl</a> when the dialog is initialised. </li>
<li>It transfers the <a class="el" href="classwx_text_ctrl.html" title="A text control allows text to be displayed and edited.">wxTextCtrl</a> data back to this variable when the dialog is dismissed. </li>
<li>It filters input characters so that only alphabetic characters are allowed.</li>
</ul>
<p>The validation and filtering of input is accomplished in two ways. When a character is input, <a class="el" href="classwx_text_validator.html" title="wxTextValidator validates text controls, providing a variety of filtering behaviours.">wxTextValidator</a> checks the character against the allowed filter flag (<code>wxFILTER_ALPHA</code> 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.</p>
<p>Note that any <a class="el" href="classwx_window.html" title="wxWindow is the base class for all windows and represents any visible object on screen.">wxWindow</a> may have a validator; using the <code>wxWS_EX_VALIDATE_RECURSIVELY</code> style (see <a class="el" href="classwx_window.html" title="wxWindow is the base class for all windows and represents any visible object on screen.">wxWindow</a> extended styles) you can also implement recursive validation.</p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="classwx_validator.html" title="wxValidator is the base class for a family of validator classes that mediate between a class of contr...">wxValidator</a>, <a class="el" href="classwx_text_validator.html" title="wxTextValidator validates text controls, providing a variety of filtering behaviours.">wxTextValidator</a>, <a class="el" href="classwx_generic_validator.html" title="wxGenericValidator performs data transfer (but not validation or filtering) for many type of controls...">wxGenericValidator</a>, <a class="el" href="classwx_integer_validator.html" title="Validator for text entries used for integer entry.">wxIntegerValidator</a>, <a class="el" href="classwx_floating_point_validator.html" title="Validator for text entries used for floating point numbers entry.">wxFloatingPointValidator</a></dd></dl>
<h1><a class="anchor" id="overview_validator_anatomy"></a>
Anatomy of a Validator</h1>
<p>A programmer creating a new validator class should provide the following functionality.</p>
<p>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.</p>
<p>The <a class="el" href="classwx_validator.html#abe48368bac7f540f0c20b1436e5c71af" title="This overridable function is called when the value in the associated window must be validated...">wxValidator::Validate</a> member function should return <span class="literal">true</span> if the data in the control (not the C++ variable) is valid. It should also show an appropriate message if data was not valid.</p>
<p>The <a class="el" href="classwx_validator.html#aa09f9ae3bace5de7a8e577206b75aeae" title="This overridable function is called when the value associated with the validator must be transferred ...">wxValidator::TransferToWindow</a> member function should transfer the data from the validator or associated C++ variable to the control.</p>
<p>The <a class="el" href="classwx_validator.html#acffa9472b2f741ab29dbfad3b80934da" title="This overridable function is called when the value in the window must be transferred to the validator...">wxValidator::TransferFromWindow</a> member function should transfer the data from the control to the validator or associated C++ variable.</p>
<p>There should be a copy constructor, and a <a class="el" href="classwx_validator.html#a25a4e0250afe9451059fd7a967c4883f" title="All validator classes must implement the Clone() function, which returns an identical copy of itself...">wxValidator::Clone</a> 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.</p>
<p>You can optionally define event handlers for the validator, to implement filtering. These handlers will capture events before the control itself does (see <a class="el" href="overview_events.html#overview_events_processing">How Events are Processed</a>). For an example implementation, see the <code><a class="el" href="valtext_8h.html">valtext.h</a></code> and <code>valtext.cpp</code> files in the wxWidgets library.</p>
<h1><a class="anchor" id="overview_validator_dialogs"></a>
How Validators Interact with Dialogs</h1>
<p>For validators to work correctly, validator functions must be called at the right times during dialog initialisation and dismissal.</p>
<p>When a <a class="el" href="classwx_dialog.html#ae8e5fa98d473b812b8d1c2f163b65c67" title="Hides or shows the dialog.">wxDialog::Show</a> is called (for a modeless dialog) or <a class="el" href="classwx_dialog.html#a6e078c3d0653f75ad3c34a37c0b54637" title="Shows an application-modal dialog.">wxDialog::ShowModal</a> is called (for a modal dialog), the function <a class="el" href="classwx_window.html#aa90a260c0a835a133043460b7d0024a8" title="Sends an wxEVT_INIT_DIALOG event, whose handler usually transfers data to the dialog via validators...">wxWindow::InitDialog</a> is automatically called. This in turn sends an initialisation event to the dialog. The default handler for the <code>wxEVT_INIT_DIALOG</code> event is defined in the <a class="el" href="classwx_window.html" title="wxWindow is the base class for all windows and represents any visible object on screen.">wxWindow</a> class to simply call the function <a class="el" href="classwx_window.html#a88cc65e424a129d9b0057756cdb67ec9" title="Transfers values to child controls from data areas specified by their validators.">wxWindow::TransferDataToWindow</a>. This function finds all the validators in the window's children and calls the <a class="el" href="classwx_validator.html#aa09f9ae3bace5de7a8e577206b75aeae" title="This overridable function is called when the value associated with the validator must be transferred ...">wxValidator::TransferToWindow</a> function for each. Thus, data is transferred from C++ variables to the dialog just as the dialog is being shown.</p>
<dl class="section note"><dt>Note</dt><dd>If you are using a window or panel instead of a dialog, you will need to call <a class="el" href="classwx_window.html#aa90a260c0a835a133043460b7d0024a8" title="Sends an wxEVT_INIT_DIALOG event, whose handler usually transfers data to the dialog via validators...">wxWindow::InitDialog</a> explicitly before showing the window.</dd></dl>
<p>When the user clicks on a button, for example the OK button, the application should first call <a class="el" href="classwx_window.html#ac87f253253a0c5eb498871c83afa40fd" title="Validates the current values of the child controls using their validators.">wxWindow::Validate</a>, which returns <span class="literal">false</span> 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 <a class="el" href="classwx_window.html#ab8e51f36e7d8790b361c8d8c6f37b1ad" title="Transfers values from child controls to data areas specified by their validators.">wxWindow::TransferDataFromWindow</a> and return if this failed. It is then safe to end the dialog by calling <a class="el" href="classwx_dialog.html#a89b6085b05b63e98001311fafcfb21f0" title="Ends a modal dialog, passing a value to be returned from the ShowModal() invocation.">wxDialog::EndModal</a> (if modal) or <a class="el" href="classwx_dialog.html#ae8e5fa98d473b812b8d1c2f163b65c67" title="Hides or shows the dialog.">wxDialog::Show</a> (if modeless).</p>
<p>In fact, <a class="el" href="classwx_dialog.html" title="A dialog box is a window with a title bar and sometimes a system menu, which can be moved around the ...">wxDialog</a> contains a default command event handler for the <code>wxID_OK</code> button. It goes like this:</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> wxDialog::OnOK(<a class="code" href="classwx_command_event.html" title="This event class contains information about command events, which originate from a variety of simple ...">wxCommandEvent</a>& event)</div>
<div class="line">{</div>
<div class="line"> <span class="keywordflow">if</span> ( <a class="code" href="classwx_window.html#ac87f253253a0c5eb498871c83afa40fd" title="Validates the current values of the child controls using their validators.">Validate</a>() && <a class="code" href="classwx_window.html#ab8e51f36e7d8790b361c8d8c6f37b1ad" title="Transfers values from child controls to data areas specified by their validators.">TransferDataFromWindow</a>() )</div>
<div class="line"> {</div>
<div class="line"> <span class="keywordflow">if</span> ( <a class="code" href="classwx_dialog.html#a2c135c1ae94d87a64ab6b6390fa8ce1e" title="Returns true if the dialog box is modal, false otherwise.">IsModal</a>() )</div>
<div class="line"> <a class="code" href="classwx_dialog.html#a89b6085b05b63e98001311fafcfb21f0" title="Ends a modal dialog, passing a value to be returned from the ShowModal() invocation.">EndModal</a>(<a class="code" href="defs_8h.html#ac66d0a09761e7d86b2ac0b2e0c6a8cbbaeeb1bdf97306d7f0fdffb62c8af3d02f" title="Standard button and menu IDs.">wxID_OK</a>);</div>
<div class="line"> <span class="keywordflow">else</span></div>
<div class="line"> {</div>
<div class="line"> <a class="code" href="classwx_dialog.html#a0d04ed85ac5cd271a61514d446340673" title="Sets the return code for this window.">SetReturnCode</a>(<a class="code" href="defs_8h.html#ac66d0a09761e7d86b2ac0b2e0c6a8cbbaeeb1bdf97306d7f0fdffb62c8af3d02f" title="Standard button and menu IDs.">wxID_OK</a>);</div>
<div class="line"> this-><a class="code" href="classwx_dialog.html#ae8e5fa98d473b812b8d1c2f163b65c67" title="Hides or shows the dialog.">Show</a>(<span class="keyword">false</span>);</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line">}</div>
</div><!-- fragment --><p>So if using validators and a normal OK button, you may not even need to write any code for handling dialog dismissal.</p>
<p>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. </p>
</div></div><!-- contents -->
<address class="footer">
<small>
Generated on Thu Nov 27 2014 13:46:42 for wxWidgets by <a href="http://www.doxygen.org/index.html" target="_new">Doxygen</a> 1.8.2
</small>
</address>
<script src="wxwidgets.js" type="text/javascript"></script>
</div><!-- #page_container -->
</body>
</html>
|
