Revision control
++ // Copyright (C) 2017 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example textfinder
++ \examplecategory {Desktop}
++ \meta tags {widgets,designer}
++ \ingroup examples-qtuitools
++ \title Text Finder
++
++ \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.webp} {TextFinder find button and input}
++ \li \inlineimage {textfinder-example-find2.webp} {TextFinder Highlighted results}
++ \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 Widgets 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 Widgets Designer}.
++
++ \image {doc/images/textfinder-example-userinterface.webp} {Screenshot of TestFinder UI}
++
++ 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 Qt Widgets 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 Widgets Designer}. First, the \c{textfinder.ui}
++ file is located and opened 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 locates and opens
++ \c{input.txt} from the resources. It then returns the file's content
++ using the QTextStream::readAll() function.
++
++ \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
++ \l QUiLoader is just one of them. See \l{Using a Qt Widgets Designer UI File in Your
++ Application} for more information on the other approaches available.
++
++ \sa {Calculator Builder}
++ */