Doc: Add qml application tutorial

- Add the necessary source files based
  on the video tutorial in QtStudios

Change-Id: Icdb16db8ff41c449e7657b9e2142d61ceddc1478
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>

10 files changed, 319 insertions, 0 deletions

diff --git a/sources/pyside2/doc/tutorials/index.rst b/sources/pyside2/doc/tutorials/index.rst
index 5b1eb9fe3..e394c4d24 100644
--- a/sources/pyside2/doc/tutorials/index.rst
+++ b/sources/pyside2/doc/tutorials/index.rst
@@ -28,3 +28,5 @@ Tutorials
     basictutorial/uifiles.rst
     qmltutorial/index.rst
     qmladvancedtutorial/index.rst
+    datavisualize/index.rst
+    qmlapp/qmlapplication.rst
diff --git a/sources/pyside2/doc/tutorials/qmlapp/logo.png b/sources/pyside2/doc/tutorials/qmlapp/logo.png
new file mode 100644
index 000000000..30c621c9c
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmlapp/logo.png
diff --git a/sources/pyside2/doc/tutorials/qmlapp/main.py b/sources/pyside2/doc/tutorials/qmlapp/main.py
new file mode 100644
index 000000000..54edf0e37
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmlapp/main.py
@@ -0,0 +1,82 @@
+#############################################################################
+##
+## 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$
+##
+#############################################################################
+
+#!/usr/bin/env python
+# -*- conding: utf-8 -*-
+
+import os, sys, urllib.request, json
+import PySide2.QtQml
+from PySide2.QtQuick import QQuickView
+from PySide2.QtCore import QStringListModel, Qt, QUrl
+from PySide2.QtGui import QGuiApplication
+
+if __name__ == '__main__':
+
+    #get our data
+    url = "http://country.io/names.json"
+    response = urllib.request.urlopen(url)
+    data = json.loads(response.read().decode('utf-8'))
+
+    #Format and sort the data
+    data_list = list(data.values())
+    data_list.sort()
+
+    #Set up the application window
+    app = QGuiApplication(sys.argv)
+    view = QQuickView()
+    view.setResizeMode(QQuickView.SizeRootObjectToView)
+
+    #Expose the list to the Qml code
+    my_model = QStringListModel()
+    my_model.setStringList(data_list)
+    view.rootContext().setContextProperty("myModel",my_model)
+
+    #Load the QML file
+    qml_file = os.path.join(os.path.dirname(__file__),"view.qml")
+    view.setSource(QUrl.fromLocalFile(os.path.abspath(qml_file)))
+
+    #Show the window
+    if view.status() == QQuickView.Error:
+        sys.exit(-1)
+    view.show()
+
+    #execute and cleanup
+    app.exec_()
+    del view
diff --git a/sources/pyside2/doc/tutorials/qmlapp/newpyproject.png b/sources/pyside2/doc/tutorials/qmlapp/newpyproject.png
new file mode 100644
index 000000000..93968a52d
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmlapp/newpyproject.png
diff --git a/sources/pyside2/doc/tutorials/qmlapp/projectsmode.png b/sources/pyside2/doc/tutorials/qmlapp/projectsmode.png
new file mode 100644
index 000000000..c66d88723
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmlapp/projectsmode.png
diff --git a/sources/pyside2/doc/tutorials/qmlapp/pyprojname.png b/sources/pyside2/doc/tutorials/qmlapp/pyprojname.png
new file mode 100644
index 000000000..98328074d
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmlapp/pyprojname.png
diff --git a/sources/pyside2/doc/tutorials/qmlapp/pyprojxplor.png b/sources/pyside2/doc/tutorials/qmlapp/pyprojxplor.png
new file mode 100644
index 000000000..e01e2ebeb
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmlapp/pyprojxplor.png
diff --git a/sources/pyside2/doc/tutorials/qmlapp/qmlapplication.png b/sources/pyside2/doc/tutorials/qmlapp/qmlapplication.png
new file mode 100644
index 000000000..ec0ad3dea
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmlapp/qmlapplication.png
diff --git a/sources/pyside2/doc/tutorials/qmlapp/qmlapplication.rst b/sources/pyside2/doc/tutorials/qmlapp/qmlapplication.rst
new file mode 100644
index 000000000..78bae94a8
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmlapp/qmlapplication.rst
@@ -0,0 +1,133 @@
+#########################
+QML Application Tutorial
+#########################
+
+This tutorial provides a quick walk-through of a python application
+that loads 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'll also learn how to provide data from Python
+as a QML context property, which is then consumed by the ListView
+defined in the QML file.
+
+Before you begin, install the following prerequisites:
+
+* The `PySide2 <https://pypi.org/project/PySide2/>`_ Python packages.
+* Qt Creator v4.9 beta1 or later from
+  `http://download.qt.io
+  <http://download.qt.io/snapshots/qtcreator/4.9/4.9.0-beta1/>`_.
+
+
+The following step-by-step instructions guide you through application
+development process using Qt Creator:
+
+#. Open Qt Creator and select **File > New File or Project..** menu item
+   to open following dialog:
+
+   .. image:: newpyproject.png
+
+#. Select **Qt for Python - Empty** from the list of application templates
+   and select **Choose**.
+
+   .. image:: pyprojname.png
+
+#. Give a **Name** to your project, choose its location in the
+   filesystem, and select **Finish** to create an empty ``main.py``
+   and ``main.pyproject``.
+
+   .. image:: pyprojxplor.png
+
+   This should create a ``main.py`` and ```main.pyproject`` files
+   for the project.
+
+#. Download :download:`view.qml<view.qml>` and :download:`logo.png <logo.png>`
+   and move them to your project folder.
+
+#. Double-click on ``main.pyproject`` to open it in edit mode, and append
+   ``view.qml`` and ``logo.png`` to the **files** list. This is how your
+   project file should look after this change:
+
+   .. code::
+
+    {
+        "files": ["main.py", "view.qml", "logo.png"]
+    }
+
+#. Now that you have the necessary bits for the application, import the
+   Python modules in your ``main.py``, and download country data and
+   format it:
+
+   .. literalinclude:: main.py
+      :linenos:
+      :lines: 40-60
+      :emphasize-lines: 12-20
+
+#. Now, set up the application window using
+   :ref:`PySide2.QtGui.QGuiApplication<qguiapplication>`, which manages the application-wide
+   settings.
+
+   .. literalinclude:: main.py
+      :linenos:
+      :lines: 40-65
+      :emphasize-lines: 23-25
+
+   .. note:: Setting the resize policy is important if you want the
+      root item to resize itself to fit the window or vice-a-versa.
+      Otherwise, the root item will retain its original size on
+      resizing the window.
+
+#. You can now expose the ``data_list`` variable as a QML context
+   property, which will be consumed by the QML ListView item in ``view.qml``.
+
+   .. literalinclude:: main.py
+      :linenos:
+      :lines: 40-70
+      :emphasize-lines: 27-30
+
+#. Load the ``view.qml`` to the ``QQuickView`` and call ``show()`` to
+   display the application window.
+
+   .. literalinclude:: main.py
+      :linenos:
+      :lines: 40-79
+      :emphasize-lines: 33-39
+
+#. Finally, execute the application to start the event loop and clean up.
+
+   .. literalinclude:: main.py
+      :linenos:
+      :lines: 40-
+      :emphasize-lines: 41-43
+
+#. Your application is ready to be run now. Select **Projects** mode to
+   choose the Python version to run it.
+
+   .. image:: projectsmode.png
+
+Run the application by using the ``CTRL+R`` keyboard shortcut to see if it
+looks like this:
+
+.. image:: qmlapplication.png
+
+You could also watch the following video tutorial for guidance to develop
+this application:
+
+.. raw:: html
+
+    <div style="position: relative; padding-bottom: 56.25%; height: 0;
+    overflow: hidden; max-width: 100%; height: auto;">
+        <iframe src="https://www.youtube.com/embed/JxfiUx60Mbg" frameborder="0"
+        allowfullscreen style="position: absolute; top: 0; left: 0;
+        width: 100%; height: 100%;">
+        </iframe>
+    </div>
+
+********************
+Related information
+********************
+
+* `QML Reference <https://doc.qt.io/qt-5/qmlreference.html>`_
+* :doc:`../qmltutorial/index`
+* :doc:`../qmladvancedtutorial/index`
diff --git a/sources/pyside2/doc/tutorials/qmlapp/view.qml b/sources/pyside2/doc/tutorials/qmlapp/view.qml
new file mode 100644
index 000000000..c75052b29
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmlapp/view.qml
@@ -0,0 +1,102 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the examples of Qt for Python.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** BSD License Usage
+** Alternatively, 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.12
+import QtQuick.Controls 2.12
+
+Page {
+    width: 640
+    height: 480
+
+    header: Label {
+        color: "#15af15"
+        text: qsTr("Where do people use Qt?")
+        font.pointSize: 17
+        font.bold: true
+        font.family: "Arial"
+        renderType: Text.NativeRendering
+        horizontalAlignment: Text.AlignHCenter
+        padding: 10
+    }
+    Rectangle {
+        id: root
+        width: parent.width
+        height: parent.height
+
+        Image {
+            id: image
+            fillMode: Image.PreserveAspectFit
+            anchors.centerIn: root
+            source: "./logo.png"
+            opacity: 0.5
+
+        }
+
+        ListView {
+            id: view
+            anchors.fill: root
+            anchors.margins: 25
+            model: myModel
+            delegate: Text {
+                anchors.leftMargin: 50
+                font.pointSize: 15
+                horizontalAlignment: Text.AlignHCenter
+                text: display
+            }
+        }
+    }
+    NumberAnimation {
+        id: anim
+        running: true
+        target: view
+        property: "contentY"
+        duration: 500
+    }
+}