/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.  Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example textfinder
    \ingroup examples-qtuitools
    \title Text Finder Example

    \brief Dynamically processing forms using Qt UI Tools.

    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 \li \inlineimage textfinder-example-find.png
         \li \inlineimage textfinder-example-find2.png
    \endtable

    \section1 Setting Up The Resource File

    The resources required for Text Finder are:
    \list
        \li \e{textfinder.ui} - the user interface file created in QtDesigner
        \li \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 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 textfinder/doc_src_examples_textfinder.pro 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 textfinder/textfinder.h 0

    The slot \c{on_findButton_clicked()} is a slot named according to the
    \l{Using a Designer UI File in Your Application#Automatic Connections}
    {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 textfinder/textfinder.cpp 0

    We then use QMetaObject's system to enable signal and slot connections.

    \snippet textfinder/textfinder.cpp 2

    The loadTextFile() function is called to load \c{input.txt} into
    QTextEdit to displays its contents.

    \snippet textfinder/textfinder.cpp 3a

    The \c{TextFinder}'s layout is set with \l{QWidget::}{setLayout()}.

    \snippet textfinder/textfinder.cpp 3b

    Finally, the window title is set to \e {Text Finder} and \c isFirstTime is
    set to true.

    \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 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 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 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 textfinder/textfinder.cpp 9

    \section1 \c main() Function

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