f958cf8623d635ba329775d5f93146d24e1c96e8
[profile/ivi/qtbase.git] / examples / tools / doc / textfinder.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/legal
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 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.
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. 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.
38
39     \table
40     \row \li \inlineimage textfinder-example-find.png
41          \li \inlineimage textfinder-example-find2.png
42     \endtable
43
44     \section1 Setting Up The Resource File
45
46     The resources required for Text Finder are:
47     \list
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
50                            in the QTextEdit
51     \endlist
52
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.
58
59     \image textfinder-example-userinterface.png
60
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 
63     the following code:
64
65     \quotefile examples/uitools/textfinder/textfinder.qrc
66
67     For more information on resource files, see \l{The Qt Resource System}.
68
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:
72
73     \snippet doc/src/snippets/code/doc_src_examples_textfinder.pro 0
74
75     \section1 TextFinder Class Definition
76
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.
80
81     \snippet examples/uitools/textfinder/textfinder.h 0
82
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
86     by \c uic.
87
88     \section1 TextFinder Class Implementation
89
90     The \c TextFinder class's constructor calls the \c loadUiFile() function
91     and then uses \c qFindChild() to access the user interface's
92     \l{QWidget}s.
93
94     \snippet examples/uitools/textfinder/textfinder.cpp 0
95
96     We then use QMetaObject's system to enable signal and slot connections.
97
98     \snippet examples/uitools/textfinder/textfinder.cpp 2
99
100     The loadTextFile() function is called to load \c{input.txt} into
101     QTextEdit to displays its contents.
102
103     \snippet examples/uitools/textfinder/textfinder.cpp 3a
104
105     The \c{TextFinder}'s layout is set with \l{QWidget::}{setLayout()}.
106
107     \snippet examples/uitools/textfinder/textfinder.cpp 3b
108
109     Finally, the window title is set to \e {Text Finder} and \c isFirstTime is
110     set to true.
111
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.
115
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.
121
122     \snippet examples/uitools/textfinder/textfinder.cpp 4
123
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}.
128
129     \snippet examples/uitools/textfinder/textfinder.cpp 5
130
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.
139
140     \snippet examples/uitools/textfinder/textfinder.cpp 7
141
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
147     to inform the user.
148
149     \snippet examples/uitools/textfinder/textfinder.cpp 9
150
151     \section1 \c main() Function
152
153     \snippet examples/uitools/textfinder/main.cpp 0
154
155     The \c main() function initialises the \e{textfinder.qrc} resource file
156     and instantiates as well as displays \c TextFinder.
157
158     \sa {Calculator Builder Example}, {World Time Clock Builder Example}
159     */