// 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-widgets.html
    \previouspage creator-tutorials.html
    \nextpage creator-how-tos.html

    \ingroup creator-tutorials

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

    \brief How to develop a Qt widget-based application with Python.

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

    \image {qtcreator-new-qt-for-python-app-widgets-ready.webp} {A small Qt Widgets application}

    For more examples of creating Qt for Python applications, see
    \l{Qt for Python Examples and Tutorials}.

    \section1 Create an empty window project

    To create a Qt for Python application that has the source file for a main
    class:

    \list 1
        \li Go to \uicontrol File > \uicontrol {New Project}.
        \li Select \uicontrol {Application (Qt for Python)} >
            \uicontrol {Empty Window} > \uicontrol Choose to open the
            \uicontrol {Project Location} dialog.
            \image {qtcreator-new-qt-for-python-app-widgets-project-location.webp} {Project Location dialog}
        \li In \uicontrol {Name}, enter the project name. For example,
            \e {hello_world}.
        \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 Class} dialog.
            \image {qtcreator-new-qt-for-python-app-widgets-define-class.webp} {Define Class dialog}
        \li In \uicontrol {Class name}, enter \b {MyWidget} as the class
            name.
        \li In \uicontrol {Base class}, select \b {QWidget} as the base class.
            \note The \uicontrol {Source file} field is automatically updated to
            match the name of the class.
        \li In \uicontrol {Project file}, enter a name for the project file.
        \li Select \uicontrol{Next} or \uicontrol Continue 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 Select \uicontrol{Next} or \uicontrol Continue.
        \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 {pyproject.toml}, which lists the files in the Python
            project and other configurations.
        \li \c {mywidget.py}, which has some boilerplate code for a class.
        \li \c {requirements.txt}, which stores the PySide version of the
            generated code. You can use this file to install the required PySide version
            using pip.
    \endlist

    \include creator-tutorial-python-application-qtquick.qdoc install-pyside6

    \section1 Add Qt Widgets imports

    The wizard adds the imports to the \c mywidget.py source file for access to
    the QApplication and the base class you selected in the Qt Widgets module,
    QWidget. In addition, you need to import \c random and QtCore for randomly
    selecting the language of the displayed text and QtWidgets for adding UI
    elements:

    \code [python]
    import sys
    import random
    from PySide6.QtWidgets import QApplication, QWidget
    from PySide6 import QtCore, QtWidgets
    \endcode

   \section1 Add a widgets-based UI

    The wizard adds a main class with the specified name that inherits from the
    specified base class:

    \code [python]
    class MyWidget(QWidget):
        def __init__(self, parent=None):
            super().__init__(parent)
            ...
    \endcode

    Add button, label, and layout widgets to create UI elements:

    \code [python]
        ...
        self.hello = ["Hallo Welt", "Hei maailma", "Hola Mundo", "Привет мир"]

        self.button = QtWidgets.QPushButton("Click me!")
        self.text = QtWidgets.QLabel("Hello World",
                                     alignment=QtCore.Qt.AlignCenter)

        self.layout = QtWidgets.QVBoxLayout(self)
        self.layout.addWidget(self.text)
        self.layout.addWidget(self.button)
        ...
    \endcode

    \section1 Add signals and slots

    Then, add a signal and a slot to implement the random function:

    \code [python]
        ...
        self.button.clicked.connect(self.magic)

    @QtCore.Slot()
    def magic(self):
        self.text.setText(random.choice(self.hello))
    \endcode

    \section1 Add a main function

    The wizard adds a main function, where it creates a QApplication instance. As
    Qt can receive arguments from the command line, you can pass any arguments to
    the QApplication object. Usually, you do not need to pass any arguments, and
    you can use the following approach:

    \code [python]
    if __name__ == "__main__":
        app = QApplication(sys.argv)
        ...
    \endcode

    \section1 Instantiate the MainWindow class

    The wizard instantiates the \c MainWindow class and shows it:

    \code [python]
        ...
        widget = MyWidget()
        widget.show()
        ...
    \endcode

    \section1 Execute the Qt code

    Finally, the wizard calls the \c app.exec() method to enter the Qt
    main loop and start executing the Qt code:

    \code [python]
        ...
        sys.exit(app.exec())
    \endcode

    \section1 Run the application

    Select \imagerunsmall (\uicontrol {Run})
    to run the application.

    \sa {Tutorial: Qt Quick and Python}, {Tutorial: Qt Widgets UI and Python},
    {Develop Qt for Python applications}
*/
