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
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
|
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights. These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example tools/completer
\title Completer Example
The Completer example shows how to provide string-completion facilities
for an input widget based on data provided by a model.
\image completer-example.png
This example uses a custom item model, \c DirModel, and a QCompleter object.
QCompleter is a class that provides completions based on an item model. The
type of model, the completion mode, and the case sensitivity can be
selected using combo boxes.
\section1 The Resource File
The Completer example requires a resource file in order to store the
\e{countries.txt} and \e{words.txt}. The resource file contains the
following code:
\quotefile examples/tools/completer/completer.qrc
\section1 DirModel Class Definition
The \c DirModel class is a subclass of QDirModel, which provides a data
model for the local filesystem.
\snippet examples/tools/completer/dirmodel.h 0
This class only has a constructor and a \c data() function as it is only
created to enable \c data() to return the entire file path for the
display role, unlike \l{QDirModel}'s \c data() function that only returns
the folder and not the drive label. This is further explained in
\c DirModel's implementation.
\section1 DirModel Class Implementation
The constructor for the \c DirModel class is used to pass \a parent to
QDirModel.
\snippet examples/tools/completer/dirmodel.cpp 0
As mentioned earlier, the \c data() function is reimplemented in order to
get it to return the entire file parth for the display role. For example,
with a QDirModel, you will see "Program Files" in the view. However, with
\c DirModel, you will see "C:\\Program Files".
\snippet examples/tools/completer/dirmodel.cpp 1
The screenshots below illustrate this difference:
\table
\row \o \inlineimage completer-example-qdirmodel.png
\o \inlineimage completer-example-dirmodel.png
\endtable
The Qt::EditRole, which QCompleter uses to look for matches, is left
unchanged.
\section1 MainWindow Class Definition
The \c MainWindow class is a subclass of QMainWindow and implements five
private slots - \c about(), \c changeCase(), \c changeMode(), \c changeModel(),
and \c changeMaxVisible().
\snippet examples/tools/completer/mainwindow.h 0
Within the \c MainWindow class, we have two private functions:
\c createMenu() and \c modelFromFile(). We also declare the private widgets
needed - three QComboBox objects, a QCheckBox, a QCompleter, a QLabel, and
a QLineEdit.
\snippet examples/tools/completer/mainwindow.h 1
\section1 MainWindow Class Implementation
The constructor of \c MainWindow constructs a \c MainWindow with a parent
widget and initializes the private members. The \c createMenu() function
is then invoked.
We set up three QComboBox objects, \c modelComb, \c modeCombo and
\c caseCombo. By default, the \c modelCombo is set to QDirModel,
the \c modeCombo is set to "Filtered Popup" and the \c caseCombo is set
to "Case Insensitive".
\snippet examples/tools/completer/mainwindow.cpp 0
The \c maxVisibleSpinBox is created and determines the number of visible
item in the completer
The \c wrapCheckBox is then set up. This \c checkBox determines if the
\c{completer}'s \l{QCompleter::setWrapAround()}{setWrapAround()} property
is enabled or disabled.
\snippet examples/tools/completer/mainwindow.cpp 1
We instantiate \c contentsLabel and set its size policy to
\l{QSizePolicy::Fixed}{fixed}. The combo boxes' \l{QComboBox::activated()}
{activated()} signals are then connected to their respective slots.
\snippet examples/tools/completer/mainwindow.cpp 2
The \c lineEdit is set up and then we arrange all the widgets using a
QGridLayout. The \c changeModel() function is called, to initialize the
\c completer.
\snippet examples/tools/completer/mainwindow.cpp 3
The \c createMenu() function is used to instantiate the QAction objects
needed to fill the \c fileMenu and \c helpMenu. The actions'
\l{QAction::triggered()}{triggered()} signals are connected to their
respective slots.
\snippet examples/tools/completer/mainwindow.cpp 4
The \c modelFromFile() function accepts the \a fileName of a file and
processes it depending on its contents.
We first validate the \c file to ensure that it can be opened in
QFile::ReadOnly mode. If this is unsuccessful, the function returns an
empty QStringListModel.
\snippet examples/tools/completer/mainwindow.cpp 5
The mouse cursor is then overriden with Qt::WaitCursor before we fill
a QStringList object, \c words, with the contents of \c file. Once this
is done, we restore the mouse cursor.
\snippet examples/tools/completer/mainwindow.cpp 6
As mentioned earlier, the resources file contains two files -
\e{countries.txt} and \e{words.txt}. If the \c file read is \e{words.txt},
we return a QStringListModel with \c words as its QStringList and
\c completer as its parent.
\snippet examples/tools/completer/mainwindow.cpp 7
If the \c file read is \e{countries.txt}, then we require a
QStandardItemModel with \c words.count() rows, 2 columns, and \c completer
as its parent.
\snippet examples/tools/completer/mainwindow.cpp 8
A standard line in \e{countries.txt} is:
\quotation
Norway NO
\endquotation
Hence, to populate the QStandardItemModel object, \c m, we have to
split the country name and its symbol. Once this is done, we return
\c m.
\snippet examples/tools/completer/mainwindow.cpp 9
The \c changeMode() function sets the \c{completer}'s mode, depending on
the value of \c index.
\snippet examples/tools/completer/mainwindow.cpp 10
The \c changeModel() function changes the item model used based on the
model selected by the user.
A \c switch statement is used to change the item model based on the index
of \c modelCombo. If \c case is 0, we use an unsorted QDirModel, providing
us with a file path excluding the drive label.
\snippet examples/tools/completer/mainwindow.cpp 11
Note that we create the model with \c completer as the parent as this
allows us to replace the model with a new model. The \c completer will
ensure that the old one is deleted the moment a new model is assigned
to it.
If \c case is 1, we use the \c DirModel we defined earlier, resulting in
full paths for the files.
\snippet examples/tools/completer/mainwindow.cpp 12
When \c case is 2, we attempt to complete names of countries. This requires
a QTreeView object, \c treeView. The country names are extracted from
\e{countries.txt} and set the popup used to display completions to
\c treeView.
\snippet examples/tools/completer/mainwindow.cpp 13
The screenshot below shows the Completer with the country list model.
\image completer-example-country.png
If \c case is 3, we attempt to complete words. This is done using a
QStringListModel that contains data extracted from \e{words.txt}. The
model is sorted \l{QCompleter::CaseInsensitivelySortedModel}
{case insensitively}.
The screenshot below shows the Completer with the word list model.
\image completer-example-word.png
Once the model type is selected, we call the \c changeMode() function and
the \c changeCase() function and set the wrap option accordingly. The
\c{wrapCheckBox}'s \l{QCheckBox::clicked()}{clicked()} signal is connected
to the \c{completer}'s \l{QCompleter::setWrapAround()}{setWrapAround()}
slot.
\snippet examples/tools/completer/mainwindow.cpp 14
The \c changeMaxVisible() update the maximum number of visible items in
the completer.
\snippet examples/tools/completer/mainwindow.cpp 15
The \c about() function provides a brief description about the example.
\snippet examples/tools/completer/mainwindow.cpp 16
\section1 \c main() Function
The \c main() function instantiates QApplication and \c MainWindow and
invokes the \l{QWidget::show()}{show()} function.
\snippet examples/tools/completer/main.cpp 0
*/
|
