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
|
/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example tools/customcompleter
\title Custom Completer Example
\brief The Custom Completer example shows how to provide string-completion
facilities for an input widget based on data provided by a model.
The completer pops up suggestions for possible words based on the first three
characters input by the user and the user's choice of word is inserted
into the \c TextEdit using QTextCursor.
\image customcompleter-example.png
\section1 Setting Up The Resource File
The Custom Completer example requires a resource file, \e wordlist.txt,
that has a list of words to help QCompleter complete words. This file
contains the following:
\quotefile examples/tools/customcompleter/customcompleter.qrc
\section1 TextEdit Class Definition
The \c TextEdit class is a subclass of QTextEdit with a custom
\c insertCompletion() slot and it reimplements the
\l{QAbstractScrollArea::keyPressEvent()}{keyPressEvent()} and the
\l{QWidget::focusInEvent()}{focusInEvent()} functions. \c TextEdit also
contains a private function \c textUnderCursor() and a private instance
of QCompleter, \c c.
\snippet examples/tools/customcompleter/textedit.h 0
\section1 TextEdit Class Implementation
The constructor for \c TextEdit constructs a \c TextEdit with a parent and
initializes \c c. The instructions to use the completer is displayed on
the \c TextEdit object, using the
\l{QTextEdit::setPlainText()}{setPlainText()} function.
\snippet examples/tools/customcompleter/textedit.cpp 0
In addition, \c TextEdit also includes a default destructor:
\snippet examples/tools/customcompleter/textedit.cpp 1
The \c setCompleter() function accepts a \a completer and sets it up.
We use \c{if (c)} to check if \c c has been initialized. If it has been
initialized, the QObject::disconnect() function is invoked to disconnect
the signal from the slot. This is to ensure that no previous completer
object is still connected to the slot.
\snippet examples/tools/customcompleter/textedit.cpp 2
We then instantiate \c c with \a completer and set it as \c{TextEdit}'s
widget. The completion mode and case sensitivity are also set and then
we connect the \l{QCompleter::activated()}{activated()} signal to the
\c insertCompletion() slot.
The \c completer() function is a getter function that returns \c c.
\snippet examples/tools/customcompleter/textedit.cpp 3
The completer pops up the options available, based on the contents of
\e wordlist.txt, but the text cursor is responsible for filling in the
missing characters, according to the user's choice of word.
Suppose the user inputs "ACT" and accepts the completer's suggestion of
"ACTUAL". The \c completion string is then sent to \c insertCompletion()
by the completer's \l{QCompleter::activated()}{activated()} signal.
The \c insertCompletion() function is responsible for completing the word
using a QTextCursor object, \c tc. It validates to ensure that the
completer's widget is \c TextEdit before using \c tc to insert the extra
characters to complete the word.
\snippet examples/tools/customcompleter/textedit.cpp 4
The figure below illustrates this process:
\image customcompleter-insertcompletion.png
\c{completion.length()} = 6
\c{c->completionPrefix().length()}=3
The difference between these two values is \c extra, which is 3. This
means that the last three characters from the right, "U", "A", and "L",
will be inserted by \c tc.
The \c textUnderCursor() function uses a QTextCursor, \c tc, to select a
word under the cursor and return it.
\snippet examples/tools/customcompleter/textedit.cpp 5
The \c TextEdit class reimplements \l{QWidget::focusInEvent()}
{focusInEvent()} function, which is an event handler used to receive
keyboard focus events for the widget.
\snippet examples/tools/customcompleter/textedit.cpp 6
The \l{QAbstractScrollArea::keyPressEvent()}{keyPressEvent()} is
reimplemented to ignore key events like Qt::Key_Enter, Qt::Key_Return,
Qt::Key_Escape, Qt::Key_Tab, and Qt::Key_Backtab so the completer can
handle them.
If there is an active completer, we cannot process the shortcut, Ctrl+E.
\snippet examples/tools/customcompleter/textedit.cpp 7
We also handle other modifiers and shortcuts for which we do not want the
completer to respond to.
\snippet examples/tools/customcompleter/textedit.cpp 8
Finally, we pop up the completer.
\section1 MainWindow Class Definition
The \c MainWindow class is a subclass of QMainWindow and implements a
private slot, \c about(). This class also has two private functions,
\c createMenu() and \c modelFromFile() as well as private instances of
QCompleter and \c TextEdit.
\snippet examples/tools/customcompleter/mainwindow.h 0
\section1 MainWindow Class Implementation
The constructor constructs a \c MainWindow with a parent and initializes
the \c completer. It also instantiates a \c TextEdit and sets its
completer. A QStringListModel, obtained from \c modelFromFile(), is used
to populate the \c completer. The \c{MainWindow}'s central widget is set
to \c TextEdit and its size is set to 500 x 300.
\snippet examples/tools/customcompleter/mainwindow.cpp 0
The \c createMenu() function creates the necessary QAction objects needed
for the "File" and "Help" menu and their \l{QAction::triggered()}
{triggered()} signals are connected to the \c quit(), \c about(), and
\c aboutQt() slots respectively.
\snippet examples/tools/customcompleter/mainwindow.cpp 1
The \c modelFromFile() function accepts a \a fileName and attempts to
extract the contents of this file into a QStringListModel. We display the
Qt::WaitCursor when we are populating the QStringList, \c words, and
restore the mouse cursor when we are done.
\snippet examples/tools/customcompleter/mainwindow.cpp 2
The \c about() function provides a brief description about the Custom
Completer example.
\snippet examples/tools/customcompleter/mainwindow.cpp 3
\section1 \c main() Function
The \c main() function instantiates \c MainWindow and invokes the
\l{QWidget::show()}{show()} function.
\snippet examples/tools/customcompleter/main.cpp 0
*/
|
