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

/*!
    \page qtquick-app-tutorial.html
    \previouspage creator-tutorials.html
    \nextpage creator-how-tos.html
    \ingroup creator-tutorials

    \keyword {Creating a Qt Quick Application}
    \title Tutorial: Qt Quick application

    \brief How to use the project wizard to create a Qt Quick Application, and
    run it on a device.

    This tutorial illustrates basic concepts of
    \l{Getting started with Qt Quick applications}{Qt Quick}. With the Qt Quick
    module, you can build fluid animated user interfaces in QML and connect them
    to back-end C++ libraries.

    The Qt Quick module provides all the basic types necessary for creating user
    interfaces with QML. It provides a visual canvas and includes types for
    creating and animating visual components, receiving user input, and so on.
    For more information about the UI choices you have, see \l{User Interfaces}.

    This tutorial describes the example application that the
    \uicontrol {New Project} wizard generates. It imports QML types from the
    \l{Qt Quick}, \l{Qt Quick Controls}, and \l{Qt Quick Layouts} modules. It
    also creates a main C++ source file for building and running the application
    using the CMake build configuration system.

    You will use the \l{Editing code}{Edit} mode to inspect the QML and the C++
    code and the CMake build configuration of the project. You will then run the
    application on an Android or iOS device.

    \image {qtquick-tutorial.webp} {Qt Quick Application created with the new project wizard}

    For more examples, see \l{Qt Quick Examples and Tutorials}.

    \section1 Set up the development environment

    To build the application for and run it on a mobile device, you must
    set up the development environment for the device platform and configure a
    connection between \QC and the mobile device.

    To develop for Android devices, you must install \l{Qt for Android}
    and set up the development environment, as instructed in
    \l{Developing for Android}.

    To develop for iOS devices, you must install \l{Qt for iOS}. You also need
    to install Xcode and use it to configure a device. For this, you need an
    Apple developer account and iOS Developer Program certificate that you
    receive from Apple. For more information, see \l{Developing for iOS}.

    \include qtquick-tutorial-create-empty-project.qdocinc qtquick empty application

    \QC generates a component file, \c Main.qml, and opens it in the
    \uicontrol Edit mode.

    \section1 Preview the application

    The main view of the application shows two rectangles with background color,
    text, and a button. Selecting the button toggles the application between
    light and dark mode.

    \list
        \li To preview the application, select
            \inlineimage {icons/live-preview.png} {Live Preview} on the top
            toolbar.
        \li To run the application on the desktop, select \imagerunsmall.
    \endlist

    \section1 Inspect the QML code

    Open \c Main.qml to inspect the generated QML code.

    \section2 QML imports

    The file has import statements for the Qt modules that contain the QML
    types used in the application:

    \code [text]
    import QtQuick
    import QtQuick.Layouts
    import QtQuick.Controls.Basics
    \endcode

    \section2 Main window

    The file contains an instance of the \l{ApplicationWindow} QML type, which
    creates a main window. The window properties set an initial and minimum size,
    as well as a window title. Also, they determine that the window is visible on
    the screen.

    \code [text]
    ApplicationWindow {
        id: window
        width: 640
        height: 480
        minimumWidth: 200
        minimumHeight: 250
        visible: true
        title: qsTr("Hello World")

        property bool lightMode: Application.styleHints.colorScheme === Qt.Light
        property color reallyDark: "#1f1f1f"
        property color dark: "#262626"
        property color reallyLight: "#e7e7e7"
        property color light: "#e0e0e0"
    \endcode

    The custom properties set the application colors in the light and dark modes.

    \section2 Layout

    The window contains an instance of the \l {GridLayout} QML type from the
    Qt Quick Layouts module, which positions two instances of the \l {Rectangle}
    type in a grid. The grid properties set the column width and the spacing
    between rows and columns, as well as bind the grid size to the window size.

    \code [text]
        GridLayout {
            id: grid
            columns: width < 400 ? 1 : 2
            rowSpacing: 0
            columnSpacing: 0
            anchors.fill: parent
    \endcode

    If the column width becomes less than 400 pixels in the running application,
    the rectangles are positioned in one column.

    \image {qtquick-tutorial-column-width.webp} {The application running in a narrow window}

    \section2 Basic QML types

    Each instance of the Rectangle type has properties that set the type ID and
    the color. The rectangle color is bound to the window color in the current
    mode. The \l {Layout} properties make the rectagle fit the grid cell.

    \code [text]
            Rectangle {
                id: rectangle1
                color: window.lightMode ? window.reallyLight : window.reallyDark
                Layout.fillHeight: true
                Layout.fillWidth: true
    \endcode

    Both rectangles contain a \l{ColumnLayout}, which position instances
    of the \l [QML] {Label} and \l [QML] {Button} types from the
    Qt Quick Controls module.

    \code [text]
                ColumnLayout {
                    anchors.fill: parent
                    Layout.alignment: Qt.AlignHCenter | Qt.AlignTop
    \endcode

    The Layout properties align the column at the top center of the rectangle,
    and set top and bottom margins for the layout to position the text and the
    button.

    \section3 Change the properties

    When you preview the application, you can change the values of the properties
    in the code and see the changes immediately.

    Experiment by changing the colors, margins, and alignment.

    \section2 Qt Quick Controls

    The Qt Quick Controls module provides a set of controls for building complete
    user interfaces in Qt Quick. The application contains instaces of Label and
    Button controls.

    \section3 Label

    The \l [QML] {Label} properties set the heading text, as well as its color
    and its size in pixels. Also, they center the label text horizontally and
    vertically within the element's width and height, as well as adjust the font
    size to fit the text within the label when the column width changes.

    The Layout properties make the label fit the grid cell with 16 pixel margins.

    \code [text]
                    Label {
                        id: text1
                        color: window.lightMode ? window.dark : window.light
                        font.pixelSize: 120
                        fontSizeMode: Text.Fit
                        text: qsTr("Hello World")
                        Layout.fillWidth: true
                        Layout.fillHeight: true
                        Layout.margins: 16
                        horizontalAlignment: Text.AlignHCenter
                        verticalAlignment: Text.AlignVCenter
                    }
    \endcode

    \section3 Button

    The \l [QtQuickControls] {Button} \c text property sets the button icon and
    text depending on the window mode.

    The Layout properties align the button at the bottom center of the rectangle,
    and set the bottom margin for the layout to position the button.

    \code [text]
                    Button {
                        id: button1
                        text: window.lightMode ? qsTr("\u263D  Dark mode")
                                               : qsTr("\u263C  Light mode")

                            Layout.bottomMargin: 16
                            Layout.alignment: Qt.AlignHCenter | Qt.AlignBottom
                        ...
                    }
    \endcode

    The \l [QML] {Text} properties bind the button text, as well as its color and
    font to the window mode.

    \code [text]
                        ...
                        contentItem: Text {
                            text: button1.text
                            color: window.lightMode ? window.light : window.dark
                            font: button1.font
                            horizontalAlignment: Text.AlignHCenter
                            verticalAlignment: Text.AlignVCenter
                        }
    \endcode

    The \c {background} item holds an instance of the Rectangle type. The
    rectangle properties make the button corners round and set the button
    background color according to the window mode.

    \code [text]
                        ...
                        background: Rectangle {
                            implicitWidth: 120
                            implicitHeight: 36
                            radius: 8
                            color: window.lightMode ? window.dark : window.light
                        }
                        ...
                    }
    \endcode

    \section2 Change the styling

    The example application uses the Basic styling for Qt Quick Controls.
    It is a simple and light-weight all-round style that offers the maximum
    performance.

    There are several other styles that you can choose based on your target
    platform, such as iOS, \macos, or Material for Android. To experiment
    with different styles, add a style name to \c {import QtQuick.Controls}.
    For example: \c {import QtQuick.Controls.Material}.

    Since Qt 6.12, you can import \c {QtQuick.Controls.Native}, which imports
    the default style for the target platform.

    For more information about the available styles, see
    \l {Styling Qt Quick Controls}.

    \section2 Signals and signal handlers

    The \c onClicked signal handler of the Button type reacts to button clicks.
    In the example application, selecting the button toggles the light and dark
    mode.

    \code [text]
                    Button {
                        id: button1
                        text: window.lightMode ? qsTr("\u263D  Dark mode")
                                               : qsTr("\u263C  Light mode")
                        Layout.bottomMargin: 16
                        Layout.alignment: Qt.AlignHCenter | Qt.AlignBottom

                        contentItem: Text {
                            text: button1.text
                            color: window.lightMode ? window.light : window.dark
                            font: button1.font
                            horizontalAlignment: Text.AlignHCenter
                            verticalAlignment: Text.AlignVCenter
                        }

                        background: Rectangle {
                            implicitWidth: 120
                            implicitHeight: 36
                            radius: 8
                            color: window.lightMode ? window.dark : window.light
                        }

                        onClicked: window.lightMode = !window.lightMode
                    }
                }
            }
        }
    \endcode

    \section1 Inspect the C++ source code

    Open the \c main.cpp file to inspect the generated C++ code. It declares the
    application, \c app, and the application engine, \c engine. The engine loads
    the main QML file when you run the application.

    \code
    #include <QGuiApplication>
    #include <QQmlApplicationEngine>

    int main(int argc, char *argv[])
    {
        QGuiApplication app(argc, argv);

        QQmlApplicationEngine engine;
        QObject::connect(
            &engine,
            &QQmlApplicationEngine::objectCreationFailed,
            &app,
            []() { QCoreApplication::exit(-1); },
            Qt::QueuedConnection);
        engine.loadFromModule("HelloWorld", "Main");

        return QGuiApplication::exec();
    }
    \endcode

    \section1 Inspect the CMake configuration file

    The wizard generates a \c {CMakeLists.txt} configuration file for building
    the application.

    The \c RESOURCES section lists the source files for the application. If you
    add source files to the project, \QC automatically adds them to the section.

    For more information, see \l {Build with CMake}.

    \section1 Run the application on a device

    You can now deploy the application to a device and run it there:

    \list 1
        \li Enable \e{USB Debugging} on the Android device or \e{developer mode}
            on the iOS device.
        \li Connect the device to the development PC.
        \li Go to \uicontrol Projects, and activate the appropriate kit for the
            project.
        \li Go to \preferences > \uicontrol Kits > \uicontrol Kits, and select
            the device from the list in \uicontrol {Run device},
            \uicontrol {Device}.
        \li To run the application on the device, select \key {Ctrl+R}.
    \endlist

    \sa {Activate kits for a project}, {Deploy applications to Android},
    {Build with CMake}{How to: Build with CMake},
    {Design Qt Quick UIs}{How to: Design Qt Quick UIs},
    {Qt Quick UI design}, {Designing Qt Quick UIs},
    {Getting Started programming with Qt Quick: An Alarm Application}

*/
