source: trunk/doc/src/examples/textfinder.qdoc@ 550

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Qt Software Information (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** 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.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at qt-sales@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}
    */