7 files changed, 380 insertions, 0 deletions
diff --git a/sources/pyside6/doc/tutorials/qmlintegration/main.py b/sources/pyside6/doc/tutorials/qmlintegration/main.py
new file mode 100644
index 000000000..0a751d7d1
--- /dev/null
+++ b/sources/pyside6/doc/tutorials/qmlintegration/main.py
@@ -0,0 +1,77 @@
+# Copyright (C) 2022 The Qt Company Ltd.
+# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+import sys
+from pathlib import Path
+
+from PySide6.QtCore import QObject, Slot
+from PySide6.QtGui import QGuiApplication
+from PySide6.QtQml import QQmlApplicationEngine, QmlElement
+from PySide6.QtQuickControls2 import QQuickStyle
+
+import style_rc
+
+# To be used on the @QmlElement decorator
+# (QML_IMPORT_MINOR_VERSION is optional)
+QML_IMPORT_NAME = "io.qt.textproperties"
+QML_IMPORT_MAJOR_VERSION = 1
+
+
+@QmlElement
+class Bridge(QObject):
+
+    @Slot(str, result=str)
+    def getColor(self, s):
+        if s.lower() == "red":
+            return "#ef9a9a"
+        elif s.lower() == "green":
+            return "#a5d6a7"
+        elif s.lower() == "blue":
+            return "#90caf9"
+        else:
+            return "white"
+
+    @Slot(float, result=int)
+    def getSize(self, s):
+        size = int(s * 34)
+        if size <= 0:
+            return 1
+        else:
+            return size
+
+    @Slot(str, result=bool)
+    def getItalic(self, s):
+        if s.lower() == "italic":
+            return True
+        else:
+            return False
+
+    @Slot(str, result=bool)
+    def getBold(self, s):
+        if s.lower() == "bold":
+            return True
+        else:
+            return False
+
+    @Slot(str, result=bool)
+    def getUnderline(self, s):
+        if s.lower() == "underline":
+            return True
+        else:
+            return False
+
+
+if __name__ == '__main__':
+    app = QGuiApplication(sys.argv)
+    QQuickStyle.setStyle("Material")
+    engine = QQmlApplicationEngine()
+
+    # Get the path of the current directory, and then add the name
+    # of the QML file, to load it.
+    qml_file = Path(__file__).parent / 'view.qml'
+    engine.load(qml_file)
+
+    if not engine.rootObjects():
+        sys.exit(-1)
+
+    sys.exit(app.exec())
diff --git a/sources/pyside6/doc/tutorials/qmlintegration/qmlintegration.rst b/sources/pyside6/doc/tutorials/qmlintegration/qmlintegration.rst
new file mode 100644
index 000000000..ff6fe3e31
--- /dev/null
+++ b/sources/pyside6/doc/tutorials/qmlintegration/qmlintegration.rst
@@ -0,0 +1,128 @@
+Python-QML integration
+======================
+
+This tutorial provides a quick walk-through of a python application that loads, and interacts with
+a QML file. QML is a declarative language that lets you design UIs faster than a traditional
+language, such as C++. The QtQml and QtQuick modules provides the necessary infrastructure for
+QML-based UIs.
+
+In this tutorial, you will learn how to integrate Python with a QML application.
+This mechanism will help us to understand how to use Python as a backend for certain
+signals from the UI elements in the QML interface. Additionally, you will learn how to provide
+a modern look to your QML application using one of the features from Qt Quick Controls 2.
+
+The tutorial is based on an application that allow you to set many text properties, like increasing
+the font size, changing the color, changing the style, and so on. Before you begin, install the
+`PySide6 <https://pypi.org/project/PySide6/>`_ Python packages.
+
+The following step-by-step process will guide you through the key elements of the QML based
+application and PySide6 integration:
+
+#. First, let's start with the following QML-based UI:
+
+   .. image:: textproperties_default.png
+
+   The design is based on a `GridLayout`, containing two `ColumnLayout`.
+   Inside the UI you will find many `RadioButton`, `Button`, and a `Slider`.
+
+#. With the QML file in place, you can load it from Python:
+
+   .. literalinclude:: main.py
+      :linenos:
+      :lines: 63-76
+      :emphasize-lines: 4,9
+
+   Notice that we only need a :code:`QQmlApplicationEngine` to
+   :code:`load` the QML file.
+
+#. Define the ``Bridge`` class, containing all the logic for the element
+   that will be register in QML:
+
+   .. literalinclude:: main.py
+      :linenos:
+      :lines: 14-54
+      :emphasize-lines: 3,4,7
+
+   Notice that the registration happens thanks to the :code:`QmlElement`
+   decorator, that underneath uses the reference to the :code:`Bridge`
+   class and the variables :code:`QML_IMPORT_NAME` and
+   :code:`QML_IMPORT_MAJOR_VERSION`.
+
+#. Now, go back to the QML file and connect the signals to the slots defined in the ``Bridge`` class:
+
+   .. code:: js
+
+      Bridge {
+         id: bridge
+      }
+
+   Inside the :code:`ApplicationWindow` we declare a component
+   with the same name as the Python class, and provide an :code:`id:`.
+   This :code:`id` will help you to get a reference to the element
+   that was registered from Python.
+
+   .. literalinclude:: view.qml
+      :linenos:
+      :lines: 45-55
+      :emphasize-lines: 6-8
+
+   The properties *Italic*, *Bold*, and *Underline* are mutually
+   exclusive, this means only one can be active at any time.
+   To achieve this each time we select one of these options, we
+   check the three properties via the QML element property as you can
+   see in the above snippet.
+   Only one of the three will return *True*, while the other two
+   will return *False*, that is how we make sure only one is being
+   applied to the text.
+
+#. Each slot verifies if the selected option contains the text associated
+   to the property:
+
+   .. literalinclude:: main.py
+      :linenos:
+      :lines: 42-47
+      :emphasize-lines: 4,6
+
+   Returning *True* or *False* allows you to activate and deactivate
+   the properties of the QML UI elements.
+
+   It is also possible to return other values that are not *Boolean*,
+   like the slot in charge of returning the font size:
+
+   .. literalinclude:: main.py
+      :linenos:
+      :lines: 34-39
+
+#. Now, for changing the look of our application, you have two options:
+
+   1. Use the command line: execute the python file adding the option, ``--style``::
+
+       python main.py --style material
+
+   2. Use a ``qtquickcontrols2.conf`` file:
+
+      .. literalinclude:: qtquickcontrols2.conf
+         :linenos:
+
+      Then add it to your ``.qrc`` file:
+
+      .. literalinclude:: style.qrc
+         :linenos:
+
+      Generate the *rc* file running, ``pyside6-rcc style.qrc -o style_rc.py``
+      And finally import it from your ``main.py`` script.
+
+   .. literalinclude:: main.py
+      :linenos:
+      :lines: 4-12
+      :emphasize-lines: 9
+
+   You can read more about this configuration file
+   `here <https://doc.qt.io/qt-5/qtquickcontrols2-configuration.html>`_.
+
+   The final look of your application will be:
+
+   .. image:: textproperties_material.png
+
+You can :download:`view.qml <view.qml>` and
+:download:`main.py <main.py>` to try this example.
diff --git a/sources/pyside6/doc/tutorials/qmlintegration/qtquickcontrols2.conf b/sources/pyside6/doc/tutorials/qmlintegration/qtquickcontrols2.conf
new file mode 100644
index 000000000..850646021
--- /dev/null
+++ b/sources/pyside6/doc/tutorials/qmlintegration/qtquickcontrols2.conf
@@ -0,0 +1,10 @@
+[Controls]
+Style=Material
+
+[Universal]
+Theme=System
+Accent=Red
+
+[Material]
+Theme=Dark
+Accent=Red
diff --git a/sources/pyside6/doc/tutorials/qmlintegration/style.qrc b/sources/pyside6/doc/tutorials/qmlintegration/style.qrc
new file mode 100644
index 000000000..e313f5ed6
--- /dev/null
+++ b/sources/pyside6/doc/tutorials/qmlintegration/style.qrc
@@ -0,0 +1,5 @@
+<!DOCTYPE RCC><RCC version="1.0">
+<qresource prefix="/">
+    <file>qtquickcontrols2.conf</file>
+</qresource>
+</RCC>
diff --git a/sources/pyside6/doc/tutorials/qmlintegration/textproperties_default.png b/sources/pyside6/doc/tutorials/qmlintegration/textproperties_default.png
new file mode 100644
index 000000000..cfeac9368
--- /dev/null
+++ b/sources/pyside6/doc/tutorials/qmlintegration/textproperties_default.png
diff --git a/sources/pyside6/doc/tutorials/qmlintegration/textproperties_material.png b/sources/pyside6/doc/tutorials/qmlintegration/textproperties_material.png
new file mode 100644
index 000000000..47866c10e
--- /dev/null
+++ b/sources/pyside6/doc/tutorials/qmlintegration/textproperties_material.png
diff --git a/sources/pyside6/doc/tutorials/qmlintegration/view.qml b/sources/pyside6/doc/tutorials/qmlintegration/view.qml
new file mode 100644
index 000000000..635603fac
--- /dev/null
+++ b/sources/pyside6/doc/tutorials/qmlintegration/view.qml
@@ -0,0 +1,160 @@
+// Copyright (C) 2021 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+
+import QtQuick 2.0
+import QtQuick.Layouts 1.11
+import QtQuick.Controls 2.1
+import QtQuick.Window 2.1
+import QtQuick.Controls.Material 2.1
+
+import io.qt.textproperties 1.0
+
+ApplicationWindow {
+    id: page
+    width: 800
+    height: 400
+    visible: true
+    Material.theme: Material.Dark
+    Material.accent: Material.Red
+
+    Bridge {
+        id: bridge
+    }
+
+    GridLayout {
+        id: grid
+        columns: 2
+        rows: 3
+
+        ColumnLayout {
+            spacing: 2
+            Layout.columnSpan: 1
+            Layout.preferredWidth: 400
+
+            Text {
+                id: leftlabel
+                Layout.alignment: Qt.AlignHCenter
+                color: "white"
+                font.pointSize: 16
+                text: "Qt for Python"
+                Layout.preferredHeight: 100
+                Material.accent: Material.Green
+            }
+
+            RadioButton {
+                id: italic
+                Layout.alignment: Qt.AlignLeft
+                text: "Italic"
+                onToggled: {
+                    leftlabel.font.italic = bridge.getItalic(italic.text)
+                    leftlabel.font.bold = bridge.getBold(italic.text)
+                    leftlabel.font.underline = bridge.getUnderline(italic.text)
+
+                }
+            }
+            RadioButton {
+                id: bold
+                Layout.alignment: Qt.AlignLeft
+                text: "Bold"
+                onToggled: {
+                    leftlabel.font.italic = bridge.getItalic(bold.text)
+                    leftlabel.font.bold = bridge.getBold(bold.text)
+                    leftlabel.font.underline = bridge.getUnderline(bold.text)
+                }
+            }
+            RadioButton {
+                id: underline
+                Layout.alignment: Qt.AlignLeft
+                text: "Underline"
+                onToggled: {
+                    leftlabel.font.italic = bridge.getItalic(underline.text)
+                    leftlabel.font.bold = bridge.getBold(underline.text)
+                    leftlabel.font.underline = bridge.getUnderline(underline.text)
+                }
+            }
+            RadioButton {
+                id: noneradio
+                Layout.alignment: Qt.AlignLeft
+                text: "None"
+                checked: true
+                onToggled: {
+                    leftlabel.font.italic = bridge.getItalic(noneradio.text)
+                    leftlabel.font.bold = bridge.getBold(noneradio.text)
+                    leftlabel.font.underline = bridge.getUnderline(noneradio.text)
+                }
+            }
+        }
+
+        ColumnLayout {
+            id: rightcolumn
+            spacing: 2
+            Layout.columnSpan: 1
+            Layout.preferredWidth: 400
+            Layout.preferredHeight: 400
+            Layout.fillWidth: true
+
+            RowLayout {
+                Layout.alignment: Qt.AlignVCenter | Qt.AlignHCenter
+
+
+                Button {
+                    id: red
+                    text: "Red"
+                    highlighted: true
+                    Material.accent: Material.Red
+                    onClicked: {
+                        leftlabel.color = bridge.getColor(red.text)
+                    }
+                }
+                Button {
+                    id: green
+                    text: "Green"
+                    highlighted: true
+                    Material.accent: Material.Green
+                    onClicked: {
+                        leftlabel.color = bridge.getColor(green.text)
+                    }
+                }
+                Button {
+                    id: blue
+                    text: "Blue"
+                    highlighted: true
+                    Material.accent: Material.Blue
+                    onClicked: {
+                        leftlabel.color = bridge.getColor(blue.text)
+                    }
+                }
+                Button {
+                    id: nonebutton
+                    text: "None"
+                    highlighted: true
+                    Material.accent: Material.BlueGrey
+                    onClicked: {
+                        leftlabel.color = bridge.getColor(nonebutton.text)
+                    }
+                }
+            }
+            RowLayout {
+                Layout.fillWidth: true
+                Layout.alignment: Qt.AlignVCenter | Qt.AlignHCenter
+                Text {
+                    id: rightlabel
+                    color: "white"
+                    Layout.alignment: Qt.AlignLeft
+                    text: "Font size"
+                    Material.accent: Material.White
+                }
+                Slider {
+                    width: rightcolumn.width*0.6
+                    Layout.alignment: Qt.AlignRight
+                    id: slider
+                    value: 0.5
+                    onValueChanged: {
+                        leftlabel.font.pointSize = bridge.getSize(value)
+                    }
+                }
+            }
+        }
+    }
+}