// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page creator-writing-program.html
    \previouspage creator-tutorials.html
    \nextpage creator-how-tos.html
    \ingroup creator-tutorials

    \keyword {Creating a Qt Widget Based Application}
    \title Tutorial: Qt Widgets application

    \brief How to use the integrated \QD to create a Qt widget-based application
    for the desktop.

    This tutorial describes how to use \QC to create a small Qt application,
    Text Finder. It is a simplified version of the Qt UI Tools \l{Text Finder}
    example. You'll use \QD to construct the application user interface from
    Qt widgets and the code editor to write the application logic in C++.

    \image {qtcreator-textfinder-screenshot.png} {Text Finder example}

    \section1 Create the Text Finder project

    \list 1

        \li Go to \uicontrol File > \uicontrol {New Project} >
            \uicontrol {Application (Qt)} > \uicontrol {Qt Widgets Application}.

            \image {qtcreator-new-project-qt-widgets.webp} {New Project dialog}

        \li Select \uicontrol Choose to open the \uicontrol {Project Location}
            dialog.

            \image {qtcreator-new-project-location-qt-widgets.webp} {Project Location dialog}

        \li In \uicontrol{Name}, type \b {TextFinder}.

        \li In \uicontrol {Create in}, enter the path for the project files.
            For example, \c {C:\Qt\examples}.

        \li Select \uicontrol{Next} (on Windows and Linux) or
            \uicontrol Continue (on \macos) to open the
            \uicontrol {Define Build System} dialog.

            \image {qtcreator-new-project-build-system.webp} {Define Build System dialog}

        \li In \uicontrol {Build system}, select \l {CMake}
            {CMake} as the build system to use for building the project.

        \li Select \uicontrol Next or \uicontrol Continue to open the
            \uicontrol{Class Information} dialog.

            \image {qtcreator-new-project-class-info.webp} {Class Information dialog}

        \li In \uicontrol{Class name}, type \b {TextFinder} as the class
            name.

        \li In \uicontrol{Base class}, select \b {QWidget} as the base
            class type.

           \note \uicontrol{Header file}, \uicontrol{Source file} and \uicontrol{Form file}
           s are automatically updated to match the name of the class.

        \li Select \uicontrol Next or \uicontrol Continue to open the
            \uicontrol {Translation File} dialog.

            \image {qtcreator-new-project-translation-file.webp} {Translation File dialog}

        \li In \uicontrol Language, you can select a language that you
            plan to \l {Use Qt Linguist}{translate} the application to. This
            sets up localization support for the application. You can add other
            languages later by editing the project file.

        \li Select \uicontrol Next or \uicontrol Continue to open the
            \uicontrol {Kit Selection} dialog.

            \image {qtcreator-new-project-kit-selection.webp} {Kit Selection dialog}

        \li Select build and run \l{Kits}{kits} for your
            project.

        \li Select \uicontrol Next or \uicontrol Continue to open the
            \uicontrol {Project Management} dialog.

            \image {qtcreator-new-project-summary.webp} {Project Management dialog}

        \li Review the project settings, and select \uicontrol{Finish} (on Windows and
            Linux) or \uicontrol Done (on \macos) to create the project.

    \endlist

    \note The project opens in the \uicontrol Edit mode, which hides these
    instructions. To return to these instructions, open the \uicontrol Help mode.

    The TextFinder project now has the following files:

    \list

        \li \c main.cpp
        \li \c textfinder.h
        \li \c textfinder.cpp
        \li \c textfinder.ui
        \li \c CMakeLists.txt

    \endlist

    \image {qtcreator-textfinder-contents.png} {TextFinder project contents}

    The \c .h and \c .cpp files come with the necessary boiler plate code.

    If you selected CMake as the build system, \QC created a \c CMakeLists.txt
    project file for you.

    \section1 Fill in the missing pieces

    Begin by designing the user interface and then move on to filling
    in the missing code. Finally, add the find functionality.

    \section2 Design the user interface

    \image {qtcreator-textfinder-ui.png} {Text Finder UI}

    \list 1

        \li In the \uicontrol {Edit} mode, double-click the \c textfinder.ui file in the
            \uicontrol{Projects} view to launch the integrated \QD.

        \li Drag the following widgets to the form:

        \list

            \li \uicontrol{Label} (QLabel)
            \li \uicontrol{Line Edit} (QLineEdit)
            \li \uicontrol{Push Button} (QPushButton)

        \endlist

        \image {qtcreator-textfinder-ui-widgets.png} {Adding widgets to Text Finder UI}

        \note To easily locate the widgets, use the search box at the top of the
        \uicontrol {Widget Box}. For example, to find the \uicontrol Label widget,
        start typing the word \b label.

        \image {qtcreator-textfinder-filter.png} {Filter}

        \li Double-click the \uicontrol{Label} widget and enter the text
            \b{Keyword}.

        \li Double-click the \uicontrol{Push Button} widget and enter the text
            \b{Find}.

        \li In the \uicontrol Properties view, change the \uicontrol objectName to
            \b findButton.

            \image {qtcreator-textfinder-objectname.png} {Changing object names}

        \li Select \key {Ctrl+A} (or \key {Cmd+A}) to select the widgets and
            select \uicontrol{Lay out Horizontally} (or select \key {Ctrl+H} on Linux or
            Windows or \key {Ctrl+Shift+H} on \macos) to apply a horizontal
            layout (QHBoxLayout).

            \image {qtcreator-textfinder-ui-horizontal-layout.png} {Applying horizontal layout}

        \li Drag a \uicontrol{Text Edit} widget (QTextEdit) to the form.

        \li Select the screen area, and then select \uicontrol{Lay out Vertically}
            (or select \key {Ctrl+L}) to apply a vertical layout (QVBoxLayout).

            \image {qtcreator-textfinder-ui.png} {Text Finder UI}

            Applying the horizontal and vertical layouts ensures that the
            application UI scales to different screen sizes.

        \li To call a find function when users select the \uicontrol Find button, you
            use the Qt signals and slots mechanism. A signal is emitted when a
            particular event occurs and a slot is a function that is called in
            response to a particular signal. Qt widgets have predefined signals
            and slots that you can use directly from \QD. To add a slot for the
            find function:

            \list

                \li Right-click the \uicontrol Find button to open a context-menu.

                \li Select \uicontrol {Go to Slot} > \uicontrol {clicked()}, and
                    then select \uicontrol OK.

                    This adds a private slot, \c{on_findButton_clicked()}, to the
                    header file, \c textfinder.h and a private function,
                    \c{TextFinder::on_findButton_clicked()}, to the
                    source file, \c textfinder.cpp.

            \endlist

        \li Select \key {Ctrl+S} (or \key {Cmd+S}) to save your changes.

    \endlist

    For more information about designing forms with \QD, see the
    \l{\QD Manual}.

    \section2 Complete the header file

    The \c textfinder.h file already has the necessary #includes, a constructor,
    a destructor, and the \c{Ui} object. You need to add a private function,
    \c{loadTextFile()}, to read and display the contents of the input text file
    in the QTextEdit.

    \list 1

        \li In the \uicontrol{Projects} view in the \uicontrol {Edit view}, double-click the
            \c{textfinder.h} file to open it for editing.

        \li Add a private function to the \c{private} section, after the
            \c{Ui::TextFinder} pointer:

            \snippet textfinder/textfinder.h 0

    \endlist

    \section2 Complete the source file

    Now that the header file is complete, move on to the source file,
    \c textfinder.cpp.

    \list 1

        \li In the \uicontrol{Projects} view in the \uicontrol Edit view, double-click the
            \c textfinder.cpp file to open it for editing.

        \li Add code to load a text file using QFile, read it with QTextStream,
            and then display it on \c{textEdit} with
            \l{QTextEdit::setPlainText()}:

            \snippet textfinder/textfinder.cpp 0

        \li To use QFile and QTextStream, add the following #includes to
            \c textfinder.cpp:

            \snippet textfinder/textfinder.cpp 1

        \li For the \c{on_findButton_clicked()} slot, add code to extract the
            search string and use the \l{QTextEdit::find()} function
            to look for the search string within the text file:

            \snippet textfinder/textfinder.cpp 2

        \li Add a line to call \c{loadTextFile()} in the constructor:

            \snippet textfinder/textfinder.cpp 3

    \endlist

    The following line of code automatically calls the \c{on_findButton_clicked()}
    slot in the uic generated \c ui_textfinder.h file:

    \code
    QMetaObject::connectSlotsByName(TextFinder);
    \endcode

    \section2 Create a resource file

    You need a resource file (\c .qrc) within which you embed the input
    text file. The input file can be any \c .txt file with a paragraph of text.
    Create a text file called \c input.txt and store it in the textfinder
    folder.

    To add a resource file:

    \list 1

        \li Go to \uicontrol File > \uicontrol {New File} >
            \uicontrol Qt > \uicontrol {Qt Resource File} > \uicontrol Choose.

            \image {qtcreator-new-file-qrc.webp} {New File dialog}

            The \uicontrol {Choose the Location} dialog opens.

            \image {qtcreator-new-file-qrc1.webp} {Choose the Location dialog}

        \li In \uicontrol{Name}, enter \b{textfinder}.

        \li In \uicontrol{Path}, enter the path to the project,
            and select \uicontrol Next or \uicontrol Continue.

            The \uicontrol{Project Management} dialog opens.

            \image {qtcreator-new-file-qrc2.webp} {Project Management dialog}


        \li In \uicontrol{Add to project}, select \b{TextFinder}
            and select \uicontrol{Finish} or \uicontrol Done to open the file
            in the code editor.

        \li Select \uicontrol Add > \uicontrol {Add Prefix}.

        \li In \uicontrol{Prefix}, replace the default prefix with a slash
            (/).

        \li Select \uicontrol Add > \uicontrol {Add Files}, to locate and add
            \c input.txt.

            \image {qtcreator-add-resource.png} {Editing resource files}

    \endlist

    \section1 Add resources to the project file

    For the text file to appear when you run the application, you must specify
    the resource file as a source file in the \c CMakeLists.txt file that the
    wizard created for you:

    \quotefromfile textfinder/CMakeLists.txt
    \skipto set(PROJECT_SOURCES
    \printuntil )

    \section1 Build and run your application

    Now that you have all the necessary files, select
    \inlineimage {icons/run_small.png} {Run} (\uicontrol Run)
    to build and run your application.

*/
