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 | */
|
---|