/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** 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 The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

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

    \brief Dynamically loading .ui files using QUiLoader.

    The TextFinder example shows how to load and setup a \c{.ui} file
    dynamically using the \l{QUiLoader} class that is part of the
    \l{Qt UI Tools} library.

    The program allows the user to look up a particular word within the
    contents of a text. The visual elements and layout of the user interface is
    loaded at runtime, from a the program resources.

    \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 the example are:
    \list
        \li \c{textfinder.ui} - the user interface file created in
            \l{Qt Designer}
        \li \c{input.txt} - a text file containing some text to be displayed in
            a QTextEdit
    \endlist

    \c 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 \c input.txt, a QLabel is used to display the text
    "Keyword", and a QPushButton is used for the \uicontrol Find button. Note
    that all the widgets have sensible \c{objectName}'s assigned. These are
    used in code to identify them.

    The screenshot below shows the preview obtained in \l{Qt Designer}.

    \image textfinder-example-userinterface.png

    In this example, we store both resources in the applicaton's executable by
    including the \c{textfinder.qrc} file. Alternatively, the files could also
    be loaded at runtime from the file system, or from an external binary
    resource \c{.rcc} file. For more information on resource files, see
    \l{The Qt Resource System}.

    The \c{textfinder.qrc} file lists all files that should be included as a
    resource:

    \quotefile textfinder/textfinder.qrc

    To generate a form at run-time, the example is linked against the
    \l{Qt Ui Tools} library. This is done in the \c{textfinder.pro} file:

    \snippet textfinder/textfinder.pro 0

    \section1 TextFinder Class Definition

    The \c TextFinder class contains the main user interface. It declares
    pointers to the QPushButton, QTextEdit and QLineEdit elements described
    above. The QLabel in the user interface is not declared here as we do
    not need to access it from code.

    \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 Loading the Resources

    We use QFile to load the data from the program resources at runtime. The
    code for this is in two method methods on top of \c{textfinder.cpp}:
    \c{loadUiFile} and \c{loadTextFile}.

    The \c{loadUiFile} function loads the user interface file previously
    created in \l{Qt Designer}. First, the content of the \c{textfinder.ui}
    file is loaded from the resource system. Then a QUiLoader instance is
    created, and the QUiLoader::load() function is called, with the first
    argument being the open file, and the second argument being the pointer of
    the widget that should be set as the parent. The created QWidget is
    returned.

    \snippet textfinder/textfinder.cpp 4

    In a similar vein, the \c loadTextFile function loads \c{input.txt} from
    the resources. Data is read using QTextStream into a QString with the
    QTextStream::readAll() function. We explicitly set the encoding to
    \e{UTF-8}, because QTextStream by default uses the current system locale.
    Finally, the loaded text is returned.

    \snippet textfinder/textfinder.cpp 5

    \section1 TextFinder Class Implementation

    The \c TextFinder class's constructor does not instantiate any child widgets
    directly. Instead, it calls the \c loadUiFile() function, and then uses
    QObject::findChild() to locate the created \l{QWidget}s by object name.

    \snippet textfinder/textfinder.cpp 0

    We then use QMetaObject::connectSlotsByName() to enable the automatic
    calling of the \c on_findButton_clicked() slot.

    \snippet textfinder/textfinder.cpp 2

    The \c loadTextFile function is called to get the text to be shown in the
    QTextEdit.

    \snippet textfinder/textfinder.cpp 3a

    The dynamically loaded user interface in \c formWidget is now properly set
    up. We now embed \c formWidget through a \c QVBoxLayout.

    \snippet textfinder/textfinder.cpp 3b

    At the end of the constructor we set a window title.

    \snippet textfinder/textfinder.cpp 3c

    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 ui_textEdit. If 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 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

    The \c main() function instantiates and shows \c TextFinder.

    \snippet textfinder/main.cpp 0

    There are various approaches to include forms into applications. Using
    QUILoader is just one of them. See \l{Using a Designer UI File in Your
    Application} for more information on the other approaches available.

    \sa {Calculator Builder Example}, {World Time Clock Builder Example}
    */