source: trunk/doc/src/examples/completer.qdoc@ 1168

Last change on this file since 1168 was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.

File size: 9.3 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:FDL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in a
14** written agreement between you and Nokia.
15**
16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
21**
22** If you have questions regarding the use of this file, please contact
23** Nokia at [email protected].
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \example tools/completer
30 \title Completer Example
31
32 The Completer example shows how to provide string-completion facilities
33 for an input widget based on data provided by a model.
34
35 \image completer-example.png
36
37 This example uses a custom item model, \c FileSystemModel, and a QCompleter object.
38 QCompleter is a class that provides completions based on an item model. The
39 type of model, the completion mode, and the case sensitivity can be
40 selected using combo boxes.
41
42 \section1 The Resource File
43
44 The Completer example requires a resource file in order to store the
45 \e{countries.txt} and \e{words.txt}. The resource file contains the
46 following code:
47
48 \quotefile examples/tools/completer/completer.qrc
49
50 \section1 FileSystemModel Class Definition
51
52 The \c FileSystemModel class is a subclass of QFileSystemModel, which provides a data
53 model for the local filesystem.
54
55 \snippet examples/tools/completer/fsmodel.h 0
56
57 This class only has a constructor and a \c data() function as it is only
58 created to enable \c data() to return the entire file path for the
59 display role, unlike \l{QFileSystemModel}'s \c data() function that only returns
60 the folder and not the drive label. This is further explained in
61 \c FileSystemModel's implementation.
62
63 \section1 FileSystemModel Class Implementation
64
65 The constructor for the \c FileSystemModel class is used to pass \a parent to
66 QFileSystemModel.
67
68 \snippet examples/tools/completer/fsmodel.cpp 0
69
70 As mentioned earlier, the \c data() function is reimplemented in order to
71 get it to return the entire file parth for the display role. For example,
72 with a QFileSystemModel, you will see "Program Files" in the view. However, with
73 \c FileSystemModel, you will see "C:\\Program Files".
74
75 \snippet examples/tools/completer/fsmodel.cpp 1
76
77 The screenshots below illustrate this difference:
78
79 \table
80 \row \o \inlineimage completer-example-qdirmodel.png
81 \o \inlineimage completer-example-dirmodel.png
82 \endtable
83
84 The Qt::EditRole, which QCompleter uses to look for matches, is left
85 unchanged.
86
87 \section1 MainWindow Class Definition
88
89 The \c MainWindow class is a subclass of QMainWindow and implements five
90 private slots - \c about(), \c changeCase(), \c changeMode(), \c changeModel(),
91 and \c changeMaxVisible().
92
93 \snippet examples/tools/completer/mainwindow.h 0
94
95 Within the \c MainWindow class, we have two private functions:
96 \c createMenu() and \c modelFromFile(). We also declare the private widgets
97 needed - three QComboBox objects, a QCheckBox, a QCompleter, a QLabel, and
98 a QLineEdit.
99
100 \snippet examples/tools/completer/mainwindow.h 1
101
102 \section1 MainWindow Class Implementation
103
104 The constructor of \c MainWindow constructs a \c MainWindow with a parent
105 widget and initializes the private members. The \c createMenu() function
106 is then invoked.
107
108 We set up three QComboBox objects, \c modelComb, \c modeCombo and
109 \c caseCombo. By default, the \c modelCombo is set to QFileSystemModel,
110 the \c modeCombo is set to "Filtered Popup" and the \c caseCombo is set
111 to "Case Insensitive".
112
113 \snippet examples/tools/completer/mainwindow.cpp 0
114
115 The \c maxVisibleSpinBox is created and determines the number of visible
116 item in the completer
117
118 The \c wrapCheckBox is then set up. This \c checkBox determines if the
119 \c{completer}'s \l{QCompleter::setWrapAround()}{setWrapAround()} property
120 is enabled or disabled.
121
122 \snippet examples/tools/completer/mainwindow.cpp 1
123
124 We instantiate \c contentsLabel and set its size policy to
125 \l{QSizePolicy::Fixed}{fixed}. The combo boxes' \l{QComboBox::activated()}
126 {activated()} signals are then connected to their respective slots.
127
128 \snippet examples/tools/completer/mainwindow.cpp 2
129
130 The \c lineEdit is set up and then we arrange all the widgets using a
131 QGridLayout. The \c changeModel() function is called, to initialize the
132 \c completer.
133
134 \snippet examples/tools/completer/mainwindow.cpp 3
135
136 The \c createMenu() function is used to instantiate the QAction objects
137 needed to fill the \c fileMenu and \c helpMenu. The actions'
138 \l{QAction::triggered()}{triggered()} signals are connected to their
139 respective slots.
140
141 \snippet examples/tools/completer/mainwindow.cpp 4
142
143 The \c modelFromFile() function accepts the \a fileName of a file and
144 processes it depending on its contents.
145
146 We first validate the \c file to ensure that it can be opened in
147 QFile::ReadOnly mode. If this is unsuccessful, the function returns an
148 empty QStringListModel.
149
150 \snippet examples/tools/completer/mainwindow.cpp 5
151
152 The mouse cursor is then overriden with Qt::WaitCursor before we fill
153 a QStringList object, \c words, with the contents of \c file. Once this
154 is done, we restore the mouse cursor.
155
156 \snippet examples/tools/completer/mainwindow.cpp 6
157
158 As mentioned earlier, the resources file contains two files -
159 \e{countries.txt} and \e{words.txt}. If the \c file read is \e{words.txt},
160 we return a QStringListModel with \c words as its QStringList and
161 \c completer as its parent.
162
163 \snippet examples/tools/completer/mainwindow.cpp 7
164
165 If the \c file read is \e{countries.txt}, then we require a
166 QStandardItemModel with \c words.count() rows, 2 columns, and \c completer
167 as its parent.
168
169 \snippet examples/tools/completer/mainwindow.cpp 8
170
171 A standard line in \e{countries.txt} is:
172 \quotation
173 Norway NO
174 \endquotation
175
176 Hence, to populate the QStandardItemModel object, \c m, we have to
177 split the country name and its symbol. Once this is done, we return
178 \c m.
179
180 \snippet examples/tools/completer/mainwindow.cpp 9
181
182 The \c changeMode() function sets the \c{completer}'s mode, depending on
183 the value of \c index.
184
185 \snippet examples/tools/completer/mainwindow.cpp 10
186
187 The \c changeModel() function changes the item model used based on the
188 model selected by the user.
189
190 A \c switch statement is used to change the item model based on the index
191 of \c modelCombo. If \c case is 0, we use an unsorted QFileSystemModel, providing
192 us with a file path excluding the drive label.
193
194 \snippet examples/tools/completer/mainwindow.cpp 11
195
196 Note that we create the model with \c completer as the parent as this
197 allows us to replace the model with a new model. The \c completer will
198 ensure that the old one is deleted the moment a new model is assigned
199 to it.
200
201 If \c case is 1, we use the \c DirModel we defined earlier, resulting in
202 full paths for the files.
203
204 \snippet examples/tools/completer/mainwindow.cpp 12
205
206 When \c case is 2, we attempt to complete names of countries. This requires
207 a QTreeView object, \c treeView. The country names are extracted from
208 \e{countries.txt} and set the popup used to display completions to
209 \c treeView.
210
211 \snippet examples/tools/completer/mainwindow.cpp 13
212
213 The screenshot below shows the Completer with the country list model.
214
215 \image completer-example-country.png
216
217 If \c case is 3, we attempt to complete words. This is done using a
218 QStringListModel that contains data extracted from \e{words.txt}. The
219 model is sorted \l{QCompleter::CaseInsensitivelySortedModel}
220 {case insensitively}.
221
222 The screenshot below shows the Completer with the word list model.
223
224 \image completer-example-word.png
225
226 Once the model type is selected, we call the \c changeMode() function and
227 the \c changeCase() function and set the wrap option accordingly. The
228 \c{wrapCheckBox}'s \l{QCheckBox::clicked()}{clicked()} signal is connected
229 to the \c{completer}'s \l{QCompleter::setWrapAround()}{setWrapAround()}
230 slot.
231
232 \snippet examples/tools/completer/mainwindow.cpp 14
233
234 The \c changeMaxVisible() update the maximum number of visible items in
235 the completer.
236
237 \snippet examples/tools/completer/mainwindow.cpp 15
238
239 The \c about() function provides a brief description about the example.
240
241 \snippet examples/tools/completer/mainwindow.cpp 16
242
243 \section1 \c main() Function
244
245 The \c main() function instantiates QApplication and \c MainWindow and
246 invokes the \l{QWidget::show()}{show()} function.
247
248 \snippet examples/tools/completer/main.cpp 0
249 */
Note: See TracBrowser for help on using the repository browser.