/****************************************************************************

**

** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the documentation of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \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{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 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 \c{input.txt} into

    QTextEdit to displays its contents.

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

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

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

    */