Update copyright headers
[qt:qt.git] / doc / src / examples / textfinder.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
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 The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
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.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \example uitools/textfinder
30     \title Text Finder Example
31
32     \brief The Text Finder example demonstrates how to dynamically process forms
33     using the QtUiTools module.
34     
35     Dynamic form processing enables a form to
36     be processed at run-time only by changing the UI file for the project.
37     The program allows the user to look up a particular word within the
38     contents of a text file. This text file is included in the project's
39     resource and is loaded into the display at startup.
40
41     \table
42     \row \o \inlineimage textfinder-example-find.png
43          \o \inlineimage textfinder-example-find2.png
44     \endtable
45
46     \section1 Setting Up The Resource File
47
48     The resources required for Text Finder are:
49     \list
50         \o \e{textfinder.ui} - the user interface file created in QtDesigner
51         \o \e{input.txt} - a text file containing some text to be displayed
52                            in the QTextEdit
53     \endlist
54
55     \e{textfinder.ui} contains all the necessary QWidget objects for the
56     Text Finder. A QLineEdit is used for the user input, a QTextEdit is
57     used to display the contents of \e{input.txt}, a QLabel is used to
58     display the text "Keyword", and a QPushButton is used for the "Find"
59     button. The screenshot below shows the preview obtained in QtDesigner.
60
61     \image textfinder-example-userinterface.png
62
63     A \e{textfinder.qrc} file is used to store both the \e{textfinder.ui}
64     and \e{input.txt} in the application's executable. The file contains 
65     the following code:
66
67     \quotefile examples/uitools/textfinder/textfinder.qrc
68
69     For more information on resource files, see \l{The Qt Resource System}.
70
71     To generate a form at run-time, the example is linked against the
72     QtUiTools module library. This is done in the \c{textfinder.pro} file
73     that contains the following lines:
74
75     \snippet doc/src/snippets/code/doc_src_examples_textfinder.pro 0
76
77     \section1 TextFinder Class Definition
78
79     The \c TextFinder class is a subclass of QWidget and it hosts the
80     \l{QWidget}s we need to access in the user interface. The QLabel in the
81     user interface is not declared here as we do not need to access it.
82
83     \snippet examples/uitools/textfinder/textfinder.h 0
84
85     The slot \c{on_findButton_clicked()} is a slot named according to the
86     \l{Using a Designer UI File in Your Application#Automatic Connections}
87     {Automatic Connection} naming convention required
88     by \c uic.
89
90     \section1 TextFinder Class Implementation
91
92     The \c TextFinder class's constructor calls the \c loadUiFile() function
93     and then uses \c qFindChild() to access the user interface's
94     \l{QWidget}s.
95
96     \snippet examples/uitools/textfinder/textfinder.cpp 0
97
98     We then use QMetaObject's system to enable signal and slot connections.
99
100     \snippet examples/uitools/textfinder/textfinder.cpp 2
101
102     The loadTextFile() function is called to load \c{input.txt} into
103     QTextEdit to displays its contents.
104
105     \snippet examples/uitools/textfinder/textfinder.cpp 3a
106
107     The \c{TextFinder}'s layout is set with \l{QWidget::}{setLayout()}.
108
109     \snippet examples/uitools/textfinder/textfinder.cpp 3b
110
111     Finally, the window title is set to \e {Text Finder} and \c isFirstTime is
112     set to true.
113
114     \c isFirstTime is used as a flag to indicate whether the search operation
115     has been performed more than once. This is further explained with the
116     \c{on_findButton_clicked()} function.
117
118     The \c{loadUiFile()} function is used to load the user interface file
119     previously created in QtDesigner. The QUiLoader class is instantiated
120     and its \c load() function is used to load the form into \c{formWidget}
121     that acts as a place holder for the user interface. The function then
122     returns \c{formWidget} to its caller.
123
124     \snippet examples/uitools/textfinder/textfinder.cpp 4
125
126     As mentioned earlier, the loadTextFile() function loads \e{input.txt}
127     into QTextEdit to display its contents. Data is read using QTextStream
128     into a QString object, \c line with the QTextStream::readAll() function.
129     The contents of \c line are then appended to \c{ui_textEdit}.
130
131     \snippet examples/uitools/textfinder/textfinder.cpp 5
132
133     The \c{on_findButton_clicked()} function is a slot that is connected to
134     \c{ui_findButton}'s \c clicked() signal. The \c searchString is extracted
135     from the \c ui_lineEdit and the \c document is extracted from \c textEdit.
136     In event there is an empty \c searchString, a QMessageBox is used,
137     requesting the user to enter a word. Otherwise, we traverse through the
138     words in \c ui_textEdit, and highlight all ocurrences of the
139     \c searchString . Two QTextCursor objects are used: One to traverse through
140     the words in \c line and another to keep track of the edit blocks.
141
142     \snippet examples/uitools/textfinder/textfinder.cpp 7
143
144     The \c isFirstTime flag is set to false the moment \c findButton is
145     clicked. This is necessary to undo the previous text highlight before
146     highlighting the user's next search string. Also, the \c found flag
147     is used to indicate if the \c searchString was found within the contents
148     of \c ui_textEdit. If it was not found, a QMessageBox is used
149     to inform the user.
150
151     \snippet examples/uitools/textfinder/textfinder.cpp 9
152
153     \section1 \c main() Function
154
155     \snippet examples/uitools/textfinder/main.cpp 0
156
157     The \c main() function initialises the \e{textfinder.qrc} resource file
158     and instantiates as well as displays \c TextFinder.
159
160     \sa{Calculator Builder Example}, {World Time Clock Builder Example}
161     */