/****************************************************************************
**
** Copyright (C) 2007-2008 Trolltech ASA. All rights reserved.
**
** This file is part of the documentation of the Qt Toolkit.
**
** This file may be used under the terms of the GNU General Public
** License versions 2.0 or 3.0 as published by the Free Software
** Foundation and appearing in the files LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file.  Alternatively you may (at
** your option) use any later version of the GNU General Public
** License if such license has been publicly approved by Trolltech ASA
** (or its successors, if any) and the KDE Free Qt Foundation. In
** addition, as a special exception, Trolltech gives you certain
** additional rights. These rights are described in the Trolltech GPL
** Exception version 1.2, which can be found at
** http://www.trolltech.com/products/qt/gplexception/ and in the file
** GPL_EXCEPTION.txt in this package.
**
** Please review the following information to ensure GNU General
** Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/. If
** you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at sales@trolltech.com.
**
** In addition, as a special exception, Trolltech, as the sole
** copyright holder for Qt Designer, grants users of the Qt/Eclipse
** Integration plug-in the right for the Qt/Eclipse Integration to
** link to functionality provided by Qt Designer and its related
** libraries.
**
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE. Trolltech reserves all rights not expressly
** granted herein.
**
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
**
****************************************************************************/

/*!
    \example uitools/textfinder
    \title Text Finder Example

    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.qdoc 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_find_Button_clicked()} is a slot named according to the
    \l{AutomaticConnections} {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 \e{input.txt} into
    QTextEdit to displays its contents. The \c{TextFinder}'s layout and
    window title is set and \c isFirstTime is set to true.

    \snippet examples/uitools/textfinder/textfinder.cpp 3

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