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
|
/****************************************************************************
**
** Copyright (C) 2012 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:FDL$
** GNU Free Documentation License
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example uitools/textfinder
\title Text Finder Example
\brief The Text Finder example demonstrates how to dynamically process forms
using the QtUiTools module.
Dynamic form processing enables a form to
be processed at run-time only by changing the UI file for the project.
The program allows the user to look up a particular word within the
contents of a text file. This text file is included in the project's
resource and is loaded into the display at startup.
\table
\row \o \inlineimage textfinder-example-find.png
\o \inlineimage textfinder-example-find2.png
\endtable
\section1 Setting Up The Resource File
The resources required for Text Finder are:
\list
\o \e{textfinder.ui} - the user interface file created in QtDesigner
\o \e{input.txt} - a text file containing some text to be displayed
in the QTextEdit
\endlist
\e{textfinder.ui} contains all the necessary QWidget objects for the
Text Finder. A QLineEdit is used for the user input, a QTextEdit is
used to display the contents of \e{input.txt}, a QLabel is used to
display the text "Keyword", and a QPushButton is used for the "Find"
button. The screenshot below shows the preview obtained in QtDesigner.
\image textfinder-example-userinterface.png
A \e{textfinder.qrc} file is used to store both the \e{textfinder.ui}
and \e{input.txt} in the application's executable. The file contains
the following code:
\quotefile examples/uitools/textfinder/textfinder.qrc
For more information on resource files, see \l{The Qt Resource System}.
To generate a form at run-time, the example is linked against the
QtUiTools module library. This is done in the \c{textfinder.pro} file
that contains the following lines:
\snippet doc/src/snippets/code/doc_src_examples_textfinder.pro 0
\section1 TextFinder Class Definition
The \c TextFinder class is a subclass of QWidget and it hosts the
\l{QWidget}s we need to access in the user interface. The QLabel in the
user interface is not declared here as we do not need to access it.
\snippet examples/uitools/textfinder/textfinder.h 0
The slot \c{on_findButton_clicked()} is a slot named according to the
\l{Using a Designer UI File in Your Application#Automatic Connections}
{Automatic Connection} naming convention required
by \c uic.
\section1 TextFinder Class Implementation
The \c TextFinder class's constructor calls the \c loadUiFile() function
and then uses \c qFindChild() to access the user interface's
\l{QWidget}s.
\snippet examples/uitools/textfinder/textfinder.cpp 0
We then use QMetaObject's system to enable signal and slot connections.
\snippet examples/uitools/textfinder/textfinder.cpp 2
The loadTextFile() function is called to load \c{input.txt} into
QTextEdit to displays its contents.
\snippet examples/uitools/textfinder/textfinder.cpp 3a
The \c{TextFinder}'s layout is set with \l{QWidget::}{setLayout()}.
\snippet examples/uitools/textfinder/textfinder.cpp 3b
Finally, the window title is set to \e {Text Finder} and \c isFirstTime is
set to true.
\c isFirstTime is used as a flag to indicate whether the search operation
has been performed more than once. This is further explained with the
\c{on_findButton_clicked()} function.
The \c{loadUiFile()} function is used to load the user interface file
previously created in QtDesigner. The QUiLoader class is instantiated
and its \c load() function is used to load the form into \c{formWidget}
that acts as a place holder for the user interface. The function then
returns \c{formWidget} to its caller.
\snippet examples/uitools/textfinder/textfinder.cpp 4
As mentioned earlier, the loadTextFile() function loads \e{input.txt}
into QTextEdit to display its contents. Data is read using QTextStream
into a QString object, \c line with the QTextStream::readAll() function.
The contents of \c line are then appended to \c{ui_textEdit}.
\snippet examples/uitools/textfinder/textfinder.cpp 5
The \c{on_findButton_clicked()} function is a slot that is connected to
\c{ui_findButton}'s \c clicked() signal. The \c searchString is extracted
from the \c ui_lineEdit and the \c document is extracted from \c textEdit.
In event there is an empty \c searchString, a QMessageBox is used,
requesting the user to enter a word. Otherwise, we traverse through the
words in \c ui_textEdit, and highlight all ocurrences of the
\c searchString . Two QTextCursor objects are used: One to traverse through
the words in \c line and another to keep track of the edit blocks.
\snippet examples/uitools/textfinder/textfinder.cpp 7
The \c isFirstTime flag is set to false the moment \c findButton is
clicked. This is necessary to undo the previous text highlight before
highlighting the user's next search string. Also, the \c found flag
is used to indicate if the \c searchString was found within the contents
of \c ui_textEdit. If it was not found, a QMessageBox is used
to inform the user.
\snippet examples/uitools/textfinder/textfinder.cpp 9
\section1 \c main() Function
\snippet examples/uitools/textfinder/main.cpp 0
The \c main() function initialises the \e{textfinder.qrc} resource file
and instantiates as well as displays \c TextFinder.
\sa{Calculator Builder Example}, {World Time Clock Builder Example}
*/
|
