source: trunk/doc/src/examples/customcompleter.qdoc

Last change on this file 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: 7.4 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/customcompleter
30 \title Custom Completer Example
31
32 The Custom Completer example shows how to provide string-completion
33 facilities for an input widget based on data provided by a model. The
34 completer pops up suggestions for possible words based on the first three
35 characters input by the user and the user's choice of word is inserted
36 into the \c TextEdit using QTextCursor.
37
38 \image customcompleter-example.png
39
40 \section1 Setting Up The Resource File
41
42 The Custom Completer example requires a resource file, \e wordlist.txt,
43 that has a list of words to help QCompleter complete words. This file
44 contains the following:
45
46 \quotefile examples/tools/customcompleter/customcompleter.qrc
47
48 \section1 TextEdit Class Definition
49
50 The \c TextEdit class is a subclass of QTextEdit with a custom
51 \c insertCompletion() slot and it reimplements the
52 \l{QAbstractScrollArea::keyPressEvent()}{keyPressEvent()} and the
53 \l{QWidget::focusInEvent()}{focusInEvent()} functions. \c TextEdit also
54 contains a private function \c textUnderCursor() and a private instance
55 of QCompleter, \c c.
56
57 \snippet examples/tools/customcompleter/textedit.h 0
58
59 \section1 TextEdit Class Implementation
60
61 The constructor for \c TextEdit constructs a \c TextEdit with a parent and
62 initializes \c c. The instructions to use the completer is displayed on
63 the \c TextEdit object, using the
64 \l{QTextEdit::setPlainText()}{setPlainText()} function.
65
66 \snippet examples/tools/customcompleter/textedit.cpp 0
67
68 In addition, \c TextEdit also includes a default destructor:
69
70 \snippet examples/tools/customcompleter/textedit.cpp 1
71
72 The \c setCompleter() function accepts a \a completer and sets it up.
73 We use \c{if (c)} to check if \c c has been initialized. If it has been
74 initialized, the QObject::disconnect() function is invoked to disconnect
75 the signal from the slot. This is to ensure that no previous completer
76 object is still connected to the slot.
77
78 \snippet examples/tools/customcompleter/textedit.cpp 2
79
80 We then instantiate \c c with \a completer and set it as \c{TextEdit}'s
81 widget. The completion mode and case sensitivity are also set and then
82 we connect the \l{QCompleter::activated()}{activated()} signal to the
83 \c insertCompletion() slot.
84
85 The \c completer() function is a getter function that returns \c c.
86
87 \snippet examples/tools/customcompleter/textedit.cpp 3
88
89 The completer pops up the options available, based on the contents of
90 \e wordlist.txt, but the text cursor is responsible for filling in the
91 missing characters, according to the user's choice of word.
92
93 Suppose the user inputs "ACT" and accepts the completer's suggestion of
94 "ACTUAL". The \c completion string is then sent to \c insertCompletion()
95 by the completer's \l{QCompleter::activated()}{activated()} signal.
96
97 The \c insertCompletion() function is responsible for completing the word
98 using a QTextCursor object, \c tc. It validates to ensure that the
99 completer's widget is \c TextEdit before using \c tc to insert the extra
100 characters to complete the word.
101
102 \snippet examples/tools/customcompleter/textedit.cpp 4
103
104 The figure below illustrates this process:
105
106 \image customcompleter-insertcompletion.png
107
108 \c{completion.length()} = 6
109
110 \c{c->completionPrefix().length()}=3
111
112 The difference between these two values is \c extra, which is 3. This
113 means that the last three characters from the right, "U", "A", and "L",
114 will be inserted by \c tc.
115
116 The \c textUnderCursor() function uses a QTextCursor, \c tc, to select a
117 word under the cursor and return it.
118
119 \snippet examples/tools/customcompleter/textedit.cpp 5
120
121 The \c TextEdit class reimplements \l{QWidget::focusInEvent()}
122 {focusInEvent()} function, which is an event handler used to receive
123 keyboard focus events for the widget.
124
125 \snippet examples/tools/customcompleter/textedit.cpp 6
126
127 The \l{QAbstractScrollArea::keyPressEvent()}{keyPressEvent()} is
128 reimplemented to ignore key events like Qt::Key_Enter, Qt::Key_Return,
129 Qt::Key_Escape, Qt::Key_Tab, and Qt::Key_Backtab so the completer can
130 handle them.
131
132 If there is an active completer, we cannot process the shortcut, Ctrl+E.
133
134 \snippet examples/tools/customcompleter/textedit.cpp 7
135
136 We also handle other modifiers and shortcuts for which we do not want the
137 completer to respond to.
138
139 \snippet examples/tools/customcompleter/textedit.cpp 8
140
141 Finally, we pop up the completer.
142
143 \section1 MainWindow Class Definition
144
145 The \c MainWindow class is a subclass of QMainWindow and implements a
146 private slot, \c about(). This class also has two private functions,
147 \c createMenu() and \c modelFromFile() as well as private instances of
148 QCompleter and \c TextEdit.
149
150 \snippet examples/tools/customcompleter/mainwindow.h 0
151
152 \section1 MainWindow Class Implementation
153
154 The constructor constructs a \c MainWindow with a parent and initializes
155 the \c completer. It also instantiates a \c TextEdit and sets its
156 completer. A QStringListModel, obtained from \c modelFromFile(), is used
157 to populate the \c completer. The \c{MainWindow}'s central widget is set
158 to \c TextEdit and its size is set to 500 x 300.
159
160 \snippet examples/tools/customcompleter/mainwindow.cpp 0
161
162 The \c createMenu() function creates the necessary QAction objects needed
163 for the "File" and "Help" menu and their \l{QAction::triggered()}
164 {triggered()} signals are connected to the \c quit(), \c about(), and
165 \c aboutQt() slots respectively.
166
167 \snippet examples/tools/customcompleter/mainwindow.cpp 1
168
169 The \c modelFromFile() function accepts a \a fileName and attempts to
170 extract the contents of this file into a QStringListModel. We display the
171 Qt::WaitCursor when we are populating the QStringList, \c words, and