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     */