1 /****************************************************************************
3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/legal
6 ** This file is part of the documentation of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and Digia. For licensing terms and
14 ** conditions see http://qt.digia.com/licensing. For further information
15 ** use the contact form at http://qt.digia.com/contact-us.
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file. Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
26 ****************************************************************************/
29 \example uitools/textfinder
30 \title Text Finder Example
32 \brief The Text Finder example demonstrates how to dynamically process forms
33 using the QtUiTools module. Dynamic form processing enables a form to
34 be processed at run-time only by changing the UI file for the project.
35 The program allows the user to look up a particular word within the
36 contents of a text file. This text file is included in the project's
37 resource and is loaded into the display at startup.
40 \row \li \inlineimage textfinder-example-find.png
41 \li \inlineimage textfinder-example-find2.png
44 \section1 Setting Up The Resource File
46 The resources required for Text Finder are:
48 \li \e{textfinder.ui} - the user interface file created in QtDesigner
49 \li \e{input.txt} - a text file containing some text to be displayed
53 \e{textfinder.ui} contains all the necessary QWidget objects for the
54 Text Finder. A QLineEdit is used for the user input, a QTextEdit is
55 used to display the contents of \e{input.txt}, a QLabel is used to
56 display the text "Keyword", and a QPushButton is used for the "Find"
57 button. The screenshot below shows the preview obtained in QtDesigner.
59 \image textfinder-example-userinterface.png
61 A \e{textfinder.qrc} file is used to store both the \e{textfinder.ui}
62 and \e{input.txt} in the application's executable. The file contains
65 \quotefile examples/uitools/textfinder/textfinder.qrc
67 For more information on resource files, see \l{The Qt Resource System}.
69 To generate a form at run-time, the example is linked against the
70 QtUiTools module library. This is done in the \c{textfinder.pro} file
71 that contains the following lines:
73 \snippet doc/src/snippets/code/doc_src_examples_textfinder.pro 0
75 \section1 TextFinder Class Definition
77 The \c TextFinder class is a subclass of QWidget and it hosts the
78 \l{QWidget}s we need to access in the user interface. The QLabel in the
79 user interface is not declared here as we do not need to access it.
81 \snippet examples/uitools/textfinder/textfinder.h 0
83 The slot \c{on_findButton_clicked()} is a slot named according to the
84 \l{Using a Designer UI File in Your Application#Automatic Connections}
85 {Automatic Connection} naming convention required
88 \section1 TextFinder Class Implementation
90 The \c TextFinder class's constructor calls the \c loadUiFile() function
91 and then uses \c qFindChild() to access the user interface's
94 \snippet examples/uitools/textfinder/textfinder.cpp 0
96 We then use QMetaObject's system to enable signal and slot connections.
98 \snippet examples/uitools/textfinder/textfinder.cpp 2
100 The loadTextFile() function is called to load \c{input.txt} into
101 QTextEdit to displays its contents.
103 \snippet examples/uitools/textfinder/textfinder.cpp 3a
105 The \c{TextFinder}'s layout is set with \l{QWidget::}{setLayout()}.
107 \snippet examples/uitools/textfinder/textfinder.cpp 3b
109 Finally, the window title is set to \e {Text Finder} and \c isFirstTime is
112 \c isFirstTime is used as a flag to indicate whether the search operation
113 has been performed more than once. This is further explained with the
114 \c{on_findButton_clicked()} function.
116 The \c{loadUiFile()} function is used to load the user interface file
117 previously created in QtDesigner. The QUiLoader class is instantiated
118 and its \c load() function is used to load the form into \c{formWidget}
119 that acts as a place holder for the user interface. The function then
120 returns \c{formWidget} to its caller.
122 \snippet examples/uitools/textfinder/textfinder.cpp 4
124 As mentioned earlier, the loadTextFile() function loads \e{input.txt}
125 into QTextEdit to display its contents. Data is read using QTextStream
126 into a QString object, \c line with the QTextStream::readAll() function.
127 The contents of \c line are then appended to \c{ui_textEdit}.
129 \snippet examples/uitools/textfinder/textfinder.cpp 5
131 The \c{on_findButton_clicked()} function is a slot that is connected to
132 \c{ui_findButton}'s \c clicked() signal. The \c searchString is extracted
133 from the \c ui_lineEdit and the \c document is extracted from \c textEdit.
134 In event there is an empty \c searchString, a QMessageBox is used,
135 requesting the user to enter a word. Otherwise, we traverse through the
136 words in \c ui_textEdit, and highlight all ocurrences of the
137 \c searchString . Two QTextCursor objects are used: One to traverse through
138 the words in \c line and another to keep track of the edit blocks.
140 \snippet examples/uitools/textfinder/textfinder.cpp 7
142 The \c isFirstTime flag is set to false the moment \c findButton is
143 clicked. This is necessary to undo the previous text highlight before
144 highlighting the user's next search string. Also, the \c found flag
145 is used to indicate if the \c searchString was found within the contents
146 of \c ui_textEdit. If it was not found, a QMessageBox is used
149 \snippet examples/uitools/textfinder/textfinder.cpp 9
151 \section1 \c main() Function
153 \snippet examples/uitools/textfinder/main.cpp 0
155 The \c main() function initialises the \e{textfinder.qrc} resource file
156 and instantiates as well as displays \c TextFinder.
158 \sa {Calculator Builder Example}, {World Time Clock Builder Example}