Doc: Add QML Integration tutorial

Since the qmlapp tutorial already explain many things
related to QML and PySide2 interaction, I made this shorter
highlighting only a few things.

Task-number: PYSIDE-841
Change-Id: I4a4618605a1868cf3632cf0efbafcfc4566b4257
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>

8 files changed, 423 insertions, 0 deletions

diff --git a/sources/pyside2/doc/tutorials/index.rst b/sources/pyside2/doc/tutorials/index.rst
index d0c47b9f2..af7e88873 100644
--- a/sources/pyside2/doc/tutorials/index.rst
+++ b/sources/pyside2/doc/tutorials/index.rst
@@ -28,3 +28,4 @@ Tutorials
     basictutorial/uifiles.rst
     datavisualize/index.rst
     qmlapp/qmlapplication.rst
+    qmlintegration/qmlintegration.rst
diff --git a/sources/pyside2/doc/tutorials/qmlintegration/main.py b/sources/pyside2/doc/tutorials/qmlintegration/main.py
new file mode 100644
index 000000000..3451c65b5
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmlintegration/main.py
@@ -0,0 +1,113 @@
+#############################################################################
+##
+## Copyright (C) 2019 The Qt Company Ltd.
+## Contact: http://www.qt.io/licensing/
+##
+## This file is part of the Qt for Python examples of the Qt Toolkit.
+##
+## $QT_BEGIN_LICENSE:BSD$
+## You may use this file under the terms of the BSD license as follows:
+##
+## "Redistribution and use in source and binary forms, with or without
+## modification, are permitted provided that the following conditions are
+## met:
+##   * Redistributions of source code must retain the above copyright
+##     notice, this list of conditions and the following disclaimer.
+##   * Redistributions in binary form must reproduce the above copyright
+##     notice, this list of conditions and the following disclaimer in
+##     the documentation and/or other materials provided with the
+##     distribution.
+##   * Neither the name of The Qt Company Ltd nor the names of its
+##     contributors may be used to endorse or promote products derived
+##     from this software without specific prior written permission.
+##
+##
+## THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+## "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+## LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+## A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+## OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+## DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+## THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+## (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+## OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+##
+## $QT_END_LICENSE$
+##
+#############################################################################
+
+import sys
+from os.path import abspath, dirname, join
+
+from PySide2.QtCore import QObject, Slot
+from PySide2.QtGui import QGuiApplication
+from PySide2.QtQml import QQmlApplicationEngine
+
+from style_rc import *
+
+
+class Bridge(QObject):
+
+    @Slot(str, result=str)
+    def getColor(self, color_name):
+        if color_name.lower() == "red":
+            return "#ef9a9a"
+        elif color_name.lower() == "green":
+            return "#a5d6a7"
+        elif color_name.lower() == "blue":
+            return "#90caf9"
+        else:
+            return "white"
+
+    @Slot(float, result=int)
+    def getSize(self, s):
+        size = int(s * 42) # Maximum font size
+        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)
+    engine = QQmlApplicationEngine()
+
+    # Instance of the Python object
+    bridge = Bridge()
+
+    # Expose the Python object to QML
+    context = engine.rootContext()
+    context.setContextProperty("con", bridge)
+
+    # Get the path of the current directory, and then add the name
+    # of the QML file, to load it.
+    qmlFile = join(dirname(__file__), 'view.qml')
+    engine.load(abspath(qmlFile))
+
+    if not engine.rootObjects():
+        sys.exit(-1)
+
+    sys.exit(app.exec_())
diff --git a/sources/pyside2/doc/tutorials/qmlintegration/qmlintegration.rst b/sources/pyside2/doc/tutorials/qmlintegration/qmlintegration.rst
new file mode 100644
index 000000000..36a12381d
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmlintegration/qmlintegration.rst
@@ -0,0 +1,111 @@
+########################
+QML Integration Tutorial
+########################
+
+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 through a context
+property.  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
+`PySide2 <https://pypi.org/project/PySide2/>`_ Python packages.
+
+The following step-by-step process will guide you through the key elements of the QML based
+application and PySide2 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: 98-108
+      :emphasize-lines: 103,107
+
+   Notice that we specify the name of the context property, **con**,
+   and also we explicitly load our QML file.
+
+#. Define the `Bridge` class, containing all the logic for the context property:
+
+   .. literalinclude:: main.py
+      :linenos:
+      :lines: 51-91
+
+#. Now, go back to the QML file and connect the signals to the slots defined in the `Bridge` class:
+
+   .. literalinclude:: view.qml
+      :linenos:
+      :lines: 85-93
+      :emphasize-lines: 89-91
+
+   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 context 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: 79-84
+      :emphasize-lines: 82,84
+
+   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: 64-70
+
+#. 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, `pyside2-rcc style.qrc > style_rc.py`
+      And finally import it from your `main.py` script.
+
+   .. literalinclude:: main.py
+      :linenos:
+      :lines: 41-48
+      :emphasize-lines: 48
+
+      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 `main.py <main.py>`_
+to try this example.
diff --git a/sources/pyside2/doc/tutorials/qmlintegration/qtquickcontrols2.conf b/sources/pyside2/doc/tutorials/qmlintegration/qtquickcontrols2.conf
new file mode 100644
index 000000000..850646021
--- /dev/null
+++ b/sources/pyside2/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/pyside2/doc/tutorials/qmlintegration/style.qrc b/sources/pyside2/doc/tutorials/qmlintegration/style.qrc
new file mode 100644
index 000000000..e313f5ed6
--- /dev/null
+++ b/sources/pyside2/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/pyside2/doc/tutorials/qmlintegration/textproperties_default.png b/sources/pyside2/doc/tutorials/qmlintegration/textproperties_default.png
new file mode 100644
index 000000000..cfeac9368
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmlintegration/textproperties_default.png
diff --git a/sources/pyside2/doc/tutorials/qmlintegration/textproperties_material.png b/sources/pyside2/doc/tutorials/qmlintegration/textproperties_material.png
new file mode 100644
index 000000000..47866c10e
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmlintegration/textproperties_material.png
diff --git a/sources/pyside2/doc/tutorials/qmlintegration/view.qml b/sources/pyside2/doc/tutorials/qmlintegration/view.qml
new file mode 100644
index 000000000..97968d691
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmlintegration/view.qml
@@ -0,0 +1,183 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the Qt for Python examples of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+
+import QtQuick 2.0
+import QtQuick.Layouts 1.12
+import QtQuick.Controls 2.12
+import QtQuick.Window 2.12
+import QtQuick.Controls.Material 2.12
+
+ApplicationWindow {
+    id: page
+    width: 800
+    height: 400
+    visible: true
+
+    GridLayout {
+        id: grid
+        columns: 2
+        rows: 3
+
+        ColumnLayout {
+            spacing: 2
+            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
+                text: "Italic"
+                onToggled: {
+                    leftlabel.font.italic = con.getItalic(italic.text)
+                    leftlabel.font.bold = con.getBold(italic.text)
+                    leftlabel.font.underline = con.getUnderline(italic.text)
+
+                }
+            }
+            RadioButton {
+                id: bold
+                text: "Bold"
+                onToggled: {
+                    leftlabel.font.italic = con.getItalic(bold.text)
+                    leftlabel.font.bold = con.getBold(bold.text)
+                    leftlabel.font.underline = con.getUnderline(bold.text)
+                }
+            }
+            RadioButton {
+                id: underline
+                text: "Underline"
+                onToggled: {
+                    leftlabel.font.italic = con.getItalic(underline.text)
+                    leftlabel.font.bold = con.getBold(underline.text)
+                    leftlabel.font.underline = con.getUnderline(underline.text)
+                }
+            }
+            RadioButton {
+                id: noneradio
+                text: "None"
+                checked: true
+                onToggled: {
+                    leftlabel.font.italic = con.getItalic(noneradio.text)
+                    leftlabel.font.bold = con.getBold(noneradio.text)
+                    leftlabel.font.underline = con.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 = con.getColor(red.text)
+                    }
+                }
+                Button {
+                    id: green
+                    text: "Green"
+                    highlighted: true
+                    Material.accent: Material.Green
+                    onClicked: {
+                        leftlabel.color = con.getColor(green.text)
+                    }
+                }
+                Button {
+                    id: blue
+                    text: "Blue"
+                    highlighted: true
+                    Material.accent: Material.Blue
+                    onClicked: {
+                        leftlabel.color = con.getColor(blue.text)
+                    }
+                }
+                Button {
+                    id: nonebutton
+                    text: "None"
+                    highlighted: true
+                    Material.accent: Material.BlueGrey
+                    onClicked: {
+                        leftlabel.color = con.getColor(nonebutton.text)
+                    }
+                }
+            }
+            RowLayout {
+                Layout.fillWidth: true
+                Layout.alignment: Qt.AlignVCenter | Qt.AlignHCenter
+                Text {
+                    id: rightlabel
+                    color: "white"
+                    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 = con.getSize(value)
+                    }
+                }
+            }
+        }
+    }
+}