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
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- addressbook.qdoc -->
<title>Qt 4.8: Part 5 - Adding a Find Function</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="content">
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
</div>
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li><a href="all-examples.html">Examples</a></li>
<li>Part 5 - Adding a Find Function</li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#defining-the-finddialog-class">Defining the FindDialog Class</a></li>
<li class="level1"><a href="#implementing-the-finddialog-class">Implementing the FindDialog Class</a></li>
<li class="level1"><a href="#defining-the-addressbook-class">Defining the AddressBook Class</a></li>
<li class="level1"><a href="#implementing-the-addressbook-class">Implementing the AddressBook Class</a></li>
</ul>
</div>
<h1 class="title">Part 5 - Adding a Find Function</h1>
<span class="subtitle"></span>
<!-- $$$tutorials/addressbook/part5-description -->
<div class="descr"> <a name="details"></a>
<p>Files:</p>
<ul>
<li><a href="tutorials-addressbook-part5-addressbook-cpp.html">tutorials/addressbook/part5/addressbook.cpp</a></li>
<li><a href="tutorials-addressbook-part5-addressbook-h.html">tutorials/addressbook/part5/addressbook.h</a></li>
<li><a href="tutorials-addressbook-part5-finddialog-cpp.html">tutorials/addressbook/part5/finddialog.cpp</a></li>
<li><a href="tutorials-addressbook-part5-finddialog-h.html">tutorials/addressbook/part5/finddialog.h</a></li>
<li><a href="tutorials-addressbook-part5-main-cpp.html">tutorials/addressbook/part5/main.cpp</a></li>
<li><a href="tutorials-addressbook-part5-part5-pro.html">tutorials/addressbook/part5/part5.pro</a></li>
</ul>
<p>Here we look at ways to locate contacts and addresses in the address book.</p>
<p class="centerAlign"><img src="images/addressbook-tutorial-part5-screenshot.png" alt="" /></p><p>As we add contacts to our address book, it becomes tedious to navigate the list with the <i>Next</i> and <i>Previous</i> buttons. A <i>Find</i> function would be more efficient. The screenshot above shows the <i>Find</i> button and its position on the panel of buttons.</p>
<p>When the user clicks on the <i>Find</i> button, it is useful to display a dialog that prompts for a contact's name. Qt provides <a href="qdialog.html">QDialog</a>, which we subclass here to implement a <tt>FindDialog</tt> class.</p>
<a name="defining-the-finddialog-class"></a>
<h2>Defining the FindDialog Class</h2>
<p class="centerAlign"><img src="images/addressbook-tutorial-part5-finddialog.png" alt="" /></p><p>In order to subclass <a href="qdialog.html">QDialog</a>, we first include the header for <a href="qdialog.html">QDialog</a> in the <tt>finddialog.h</tt> file. Also, we use forward declaration to declare <a href="qlineedit.html">QLineEdit</a> and <a href="qpushbutton.html">QPushButton</a> since we will be using those widgets in our dialog class.</p>
<p>As in our <tt>AddressBook</tt> class, the <tt>FindDialog</tt> class includes the <a href="qobject.html#Q_OBJECT">Q_OBJECT</a> macro and its constructor is defined to accept a parent <a href="qwidget.html">QWidget</a>, even though the dialog will be opened as a separate window.</p>
<pre class="cpp"> <span class="preprocessor">#include <QDialog></span>
<span class="keyword">class</span> <span class="type"><a href="qlineedit.html">QLineEdit</a></span>;
<span class="keyword">class</span> <span class="type"><a href="qpushbutton.html">QPushButton</a></span>;
<span class="keyword">class</span> FindDialog : <span class="keyword">public</span> <span class="type"><a href="qdialog.html">QDialog</a></span>
{
Q_OBJECT
<span class="keyword">public</span>:
FindDialog(<span class="type"><a href="qwidget.html">QWidget</a></span> <span class="operator">*</span>parent <span class="operator">=</span> <span class="number">0</span>);
<span class="type"><a href="qstring.html">QString</a></span> getFindText();
<span class="keyword">public</span> <span class="keyword">slots</span>:
<span class="type">void</span> findClicked();
<span class="keyword">private</span>:
<span class="type"><a href="qpushbutton.html">QPushButton</a></span> <span class="operator">*</span>findButton;
<span class="type"><a href="qlineedit.html">QLineEdit</a></span> <span class="operator">*</span>lineEdit;
<span class="type"><a href="qstring.html">QString</a></span> findText;
};</pre>
<p>We define a public function, <tt>getFindText()</tt>, to be used by classes that instantiate <tt>FindDialog</tt>. This function allows these classes to obtain the search string entered by the user. A public slot, <tt>findClicked()</tt>, is also defined to handle the search string when the user clicks the <b>Find</b> button.</p>
<p>Lastly, we define the private variables, <tt>findButton</tt>, <tt>lineEdit</tt> and <tt>findText</tt>, corresponding to the <b>Find</b> button, the line edit into which the user types the search string, and an internal string used to store the search string for later use.</p>
<a name="implementing-the-finddialog-class"></a>
<h2>Implementing the FindDialog Class</h2>
<p>Within the constructor of <tt>FindDialog</tt>, we set up the private variables, <tt>lineEdit</tt>, <tt>findButton</tt> and <tt>findText</tt>. We use a <a href="qhboxlayout.html">QHBoxLayout</a> to position the widgets.</p>
<pre class="cpp"> FindDialog<span class="operator">::</span>FindDialog(<span class="type"><a href="qwidget.html">QWidget</a></span> <span class="operator">*</span>parent)
: <span class="type"><a href="qdialog.html">QDialog</a></span>(parent)
{
<span class="type"><a href="qlabel.html">QLabel</a></span> <span class="operator">*</span>findLabel <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qlabel.html">QLabel</a></span>(tr(<span class="string">"Enter the name of a contact:"</span>));
lineEdit <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qlineedit.html">QLineEdit</a></span>;
findButton <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qpushbutton.html">QPushButton</a></span>(tr(<span class="string">"&Find"</span>));
findText <span class="operator">=</span> <span class="string">""</span>;
<span class="type"><a href="qhboxlayout.html">QHBoxLayout</a></span> <span class="operator">*</span>layout <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qhboxlayout.html">QHBoxLayout</a></span>;
layout<span class="operator">-</span><span class="operator">></span>addWidget(findLabel);
layout<span class="operator">-</span><span class="operator">></span>addWidget(lineEdit);
layout<span class="operator">-</span><span class="operator">></span>addWidget(findButton);
setLayout(layout);
setWindowTitle(tr(<span class="string">"Find a Contact"</span>));
connect(findButton<span class="operator">,</span> SIGNAL(clicked())<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> SLOT(findClicked()));
connect(findButton<span class="operator">,</span> SIGNAL(clicked())<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> SLOT(accept()));
}</pre>
<p>We set the layout and window title, as well as connect the signals to their respective slots. Notice that <tt>findButton</tt>'s <a href="qabstractbutton.html#clicked">clicked()</a> signal is connected to to <tt>findClicked()</tt> and <a href="qdialog.html#accept">accept()</a>. The <a href="qdialog.html#accept">accept()</a> slot provided by <a href="qdialog.html">QDialog</a> hides the dialog and sets the result code to <a href="qdialog.html#DialogCode-enum">Accepted</a>. We use this function to help <tt>AddressBook</tt>'s <tt>findContact()</tt> function know when the <tt>FindDialog</tt> object has been closed. We will explain this logic in further detail when discussing the <tt>findContact()</tt> function.</p>
<p class="centerAlign"><img src="images/addressbook-tutorial-part5-signals-and-slots.png" alt="" /></p><p>In <tt>findClicked()</tt>, we validate <tt>lineEdit</tt> to ensure that the user did not click the <b>Find</b> button without entering a contact's name. Then, we set <tt>findText</tt> to the search string, extracted from <tt>lineEdit</tt>. After that, we clear the contents of <tt>lineEdit</tt> and hide the dialog.</p>
<pre class="cpp"> <span class="type">void</span> FindDialog<span class="operator">::</span>findClicked()
{
<span class="type"><a href="qstring.html">QString</a></span> text <span class="operator">=</span> lineEdit<span class="operator">-</span><span class="operator">></span>text();
<span class="keyword">if</span> (text<span class="operator">.</span>isEmpty()) {
<span class="type"><a href="qmessagebox.html">QMessageBox</a></span><span class="operator">::</span>information(<span class="keyword">this</span><span class="operator">,</span> tr(<span class="string">"Empty Field"</span>)<span class="operator">,</span>
tr(<span class="string">"Please enter a name."</span>));
<span class="keyword">return</span>;
} <span class="keyword">else</span> {
findText <span class="operator">=</span> text;
lineEdit<span class="operator">-</span><span class="operator">></span>clear();
hide();
}
}</pre>
<p>The <tt>findText</tt> variable has a public getter function, <tt>getFindText()</tt>, associated with it. Since we only ever set <tt>findText</tt> directly in both the constructor and in the <tt>findClicked()</tt> function, we do not create a setter function to accompany <tt>getFindText()</tt>. Because <tt>getFindText()</tt> is public, classes instantiating and using <tt>FindDialog</tt> can always access the search string that the user has entered and accepted.</p>
<pre class="cpp"> <span class="type"><a href="qstring.html">QString</a></span> FindDialog<span class="operator">::</span>getFindText()
{
<span class="keyword">return</span> findText;
}</pre>
<a name="defining-the-addressbook-class"></a>
<h2>Defining the AddressBook Class</h2>
<p>To ensure we can use <tt>FindDialog</tt> from within our <tt>AddressBook</tt> class, we include <tt>finddialog.h</tt> in the <tt>addressbook.h</tt> file.</p>
<pre class="cpp"> <span class="preprocessor">#include "finddialog.h"</span></pre>
<p>So far, all our address book features have a <a href="qpushbutton.html">QPushButton</a> and a corresponding slot. Similarly, for the <b>Find</b> feature we have <tt>findButton</tt> and <tt>findContact()</tt>.</p>
<p>The <tt>findButton</tt> is declared as a private variable and the <tt>findContact()</tt> function is declared as a public slot.</p>
<pre class="cpp"> <span class="type">void</span> findContact();
...
<span class="type"><a href="qpushbutton.html">QPushButton</a></span> <span class="operator">*</span>findButton;</pre>
<p>Lastly, we declare the private variable, <tt>dialog</tt>, which we will use to refer to an instance of <tt>FindDialog</tt>.</p>
<pre class="cpp"> FindDialog <span class="operator">*</span>dialog;</pre>
<p>Once we have instantiated a dialog, we will want to use it more than once; using a private variable allows us to refer to it from more than one place in the class.</p>
<a name="implementing-the-addressbook-class"></a>
<h2>Implementing the AddressBook Class</h2>
<p>Within the <tt>AddressBook</tt> class's constructor, we instantiate our private objects, <tt>findButton</tt> and <tt>findDialog</tt>:</p>
<pre class="cpp"> findButton <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qpushbutton.html">QPushButton</a></span>(tr(<span class="string">"&Find"</span>));
findButton<span class="operator">-</span><span class="operator">></span>setEnabled(<span class="keyword">false</span>);
...
dialog <span class="operator">=</span> <span class="keyword">new</span> FindDialog;</pre>
<p>Next, we connect the <tt>findButton</tt>'s <a href="qabstractbutton.html#clicked">clicked()</a> signal to <tt>findContact()</tt>.</p>
<pre class="cpp"> connect(findButton<span class="operator">,</span> SIGNAL(clicked())<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> SLOT(findContact()));</pre>
<p>Now all that is left is the code for our <tt>findContact()</tt> function:</p>
<pre class="cpp"> <span class="type">void</span> AddressBook<span class="operator">::</span>findContact()
{
dialog<span class="operator">-</span><span class="operator">></span>show();
<span class="keyword">if</span> (dialog<span class="operator">-</span><span class="operator">></span>exec() <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="qdialog.html">QDialog</a></span><span class="operator">::</span>Accepted) {
<span class="type"><a href="qstring.html">QString</a></span> contactName <span class="operator">=</span> dialog<span class="operator">-</span><span class="operator">></span>getFindText();
<span class="keyword">if</span> (contacts<span class="operator">.</span>contains(contactName)) {
nameLine<span class="operator">-</span><span class="operator">></span>setText(contactName);
addressText<span class="operator">-</span><span class="operator">></span>setText(contacts<span class="operator">.</span>value(contactName));
} <span class="keyword">else</span> {
<span class="type"><a href="qmessagebox.html">QMessageBox</a></span><span class="operator">::</span>information(<span class="keyword">this</span><span class="operator">,</span> tr(<span class="string">"Contact Not Found"</span>)<span class="operator">,</span>
tr(<span class="string">"Sorry, \"%1\" is not in your address book."</span>)<span class="operator">.</span>arg(contactName));
<span class="keyword">return</span>;
}
}
updateInterface(NavigationMode);
}</pre>
<p>We start out by displaying the <tt>FindDialog</tt> instance, <tt>dialog</tt>. This is when the user enters a contact name to look up. Once the user clicks the dialog's <tt>findButton</tt>, the dialog is hidden and the result code is set to <a href="qdialog.html#DialogCode-enum">QDialog::Accepted</a>. This ensures that our <tt>if</tt> statement is always true.</p>
<p>We then proceed to extract the search string, which in this case is <tt>contactName</tt>, using <tt>FindDialog</tt>'s <tt>getFindText()</tt> function. If the contact exists in our address book, we display it immediately. Otherwise, we display the <a href="qmessagebox.html">QMessageBox</a> shown below to indicate that their search failed.</p>
<p class="centerAlign"><img src="images/addressbook-tutorial-part5-notfound.png" alt="" /></p></div>
<!-- @@@tutorials/addressbook/part5 -->
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2012 Nokia Corporation and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Nokia, Qt and their respective logos are trademarks of Nokia Corporation
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
</body>
</html>
|
