qt-creator/doc/qtcreator/src/python/creator-tutorial-python-application-qtquick.qdoc

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

/*!
    \page creator-tutorial-python-application-qt-quick.html
    \previouspage creator-tutorials.html
    \nextpage creator-how-tos.html

    \ingroup creator-tutorials

    \keyword {Creating a Qt for Python Application with Qt Quick}
    \title Tutorial: Qt Quick and Python

    \brief How to develop a Qt Quick application with Python.

    First, create a Qt for Python application project. Then, edit the boilerplate
    code to develop a small application that uses Qt Quick to display the text
    \e {Hello World} in several languages.

    \image qtcreator-new-qt-for-python-app-qt-quick-empty-project-ready.webp {A small Qt Quick application}

    For more examples of creating Qt for Python applications, see
    \l {https://doc.qt.io/qtforpython/tutorials/index.html}
    {Qt for Python Examples and Tutorials}.

    \section1 Create an empty project

    To create a Qt for Python application that has a main QML file:

    \list 1
        \li Go to \uicontrol File > \uicontrol {New Project}.
        \li Select \uicontrol {Application (Qt for Python)} >
            \uicontrol {Qt Quick Application - Empty} > \uicontrol Choose to
            open the \uicontrol {Project Location} dialog.
            \image qtcreator-new-qt-for-python-app-qt-quick-empty-project-location.webp {Project Location dialog}
        \li In \uicontrol {Name}, enter the project name. For example,
            \e {hello_world_quick}.
        \li In \uicontrol {Create in}, enter the path for the project files.
            For example, \c {C:\Examples}.
        \li Select \uicontrol{Next} (on Windows and Linux) or \uicontrol Continue
            (on \macos) to open the \uicontrol {Define Project Details} dialog.
            \image qtcreator-new-qt-for-python-app-project-details.webp {Define Project Details dialog}
        \li In \uicontrol {PySide version}, select the PySide version of
            the generated code.
        \li Select \uicontrol{Next} or \uicontrol Continue to open the
            \uicontrol {Kit Selection} dialog.
            \image qtcreator-new-project-qt-for-python-kit-selection.webp {Selecting a kit for a Python project}
        \li Select Python kits for building, deploying, and running the
            project. By default, this creates a virtual environment for the project inside
            the source directory. To use the global interpreter, select the build configuration
            with the same name as the Python of the kit in \uicontrol{Details}.
        \li Review the project settings, and select \uicontrol {Finish} (on
            Windows and Linux) or \uicontrol Done (on \macos) to create the
            project.
    \endlist

    The wizard generates the following files:

    \list
        \li \c {hello_world_quick.pyproject}, which lists the files in the Python
            project.
        \li \c {main.py}, which has some boilerplate code.
        \li \c {main.qml}, which imports Qt Quick controls.
        \li \c {reguirements.txt}, which stores the PySide version of the
            generated code. You can use this file to install the required PySide version
            using pip.
    \endlist

    \section1 Add Qt Quick imports

    The wizard adds the following imports to the \c {main.py} source file for
    access to QGuiApplication and QQmlApplicationEngine:

    \badcode
    import sys
    from pathlib import Path

    from PySide6.QtGui import QGuiApplication
    from PySide6.QtQml import QQmlApplicationEngine
    \endcode

    \section1 Add a main function

    The wizard also adds a main function, where it creates a QGuiApplication
    instance and passes system arguments to the QGuiApplication object:

    \badcode
    if __name__ == "__main__":
        app = QGuiApplication(sys.argv)
        ...
    \endcode

    \section1 Load the QML file

    The following lines in the main class create a QQmlApplicationEngine
    instance and load the generated QML file to the engine object:

    \badcode
        ...
        engine = QQmlApplicationEngine()
        qml_file = Path(__file__).resolve().parent / "main.qml"
        engine.load(qml_file)
        ...
    \endcode

    Finally, the wizard adds code that checks whether the file was successfully
    loaded. If loading the file fails, the application exits with an error code.
    If loading succeeds, the wizard calls the \c app.exec() method to enter the
    Qt main loop and start executing the Qt code:

    \badcode
    ...
    if not engine.rootObjects():
        sys.exit(-1)
    sys.exit(app.exec())
    ...
    \endcode

    \section1 Design the UI

    Open the \c {main.qml} file in the \uicontrol Edit mode to design a
    Qt Quick UI.

    \section2 Add imports

    Add imports for Qt Quick Controls and Layouts:

    \badcode
    import QtQuick
    import QtQuick.Window
    import QtQuick.Controls
    import QtQuick.Layouts
    \endcode

    \section2 Add properties and functions

    The wizard adds a main window:

    \badcode
    Window {
        width: 640
        height: 480
        visible: true
        title: qsTr("Hello World")
    }
    \endcode

    Add a property and function to randomly select the language of the displayed
    text:

    \badcode
        ...
        readonly property list<string> texts: ["Hallo Welt", "Hei maailma",
                                           "Hola Mundo", "Привет мир"]

    function setText() {
        var i = Math.round(Math.random() * 3)
        text.text = texts[i]
    }
    \endcode

    \section2 Add Qt Quick Controls

    Add \l {Text} and \l {Button} QML types within a \l {ColumnLayout} type to
    design the UI:

    \badcode
        ColumnLayout {
        anchors.fill:  parent

        Text {
            id: text
            text: "Hello World"
            Layout.alignment: Qt.AlignHCenter
        }
        Button {
            text: "Click me"
            Layout.alignment: Qt.AlignHCenter
            onClicked:  setText()
        }
    }
    \endcode

    You can also use \l{Qt Design Studio Manual}{\QDS} to design Qt Quick UIs.

    \section1 Run the application

    Select \inlineimage icons/run_small.png to run the application.

    \sa {Tutorial: Qt Widgets and Python},
    {Develop Qt for Python Applications}
*/