12 files changed, 557 insertions, 0 deletions
diff --git a/sources/pyside2/doc/tutorials/qmltutorial/declarative-tutorial1.png b/sources/pyside2/doc/tutorials/qmltutorial/declarative-tutorial1.png
new file mode 100644
index 000000000..c9d3844cb
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmltutorial/declarative-tutorial1.png
diff --git a/sources/pyside2/doc/tutorials/qmltutorial/declarative-tutorial2.png b/sources/pyside2/doc/tutorials/qmltutorial/declarative-tutorial2.png
new file mode 100644
index 000000000..835484aa4
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmltutorial/declarative-tutorial2.png
diff --git a/sources/pyside2/doc/tutorials/qmltutorial/declarative-tutorial3_animation.gif b/sources/pyside2/doc/tutorials/qmltutorial/declarative-tutorial3_animation.gif
new file mode 100644
index 000000000..80b78dea9
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmltutorial/declarative-tutorial3_animation.gif
diff --git a/sources/pyside2/doc/tutorials/qmltutorial/helloworld.tar.bz2 b/sources/pyside2/doc/tutorials/qmltutorial/helloworld.tar.bz2
new file mode 100644
index 000000000..001a5258d
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmltutorial/helloworld.tar.bz2
diff --git a/sources/pyside2/doc/tutorials/qmltutorial/helloworld/Cell.qml b/sources/pyside2/doc/tutorials/qmltutorial/helloworld/Cell.qml
new file mode 100644
index 000000000..a561e34db
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmltutorial/helloworld/Cell.qml
@@ -0,0 +1,82 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the examples of PySide2.
+**
+** $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$
+**
+****************************************************************************/
+
+//![0]
+import QtQuick 1.0
+
+//![1]
+Item {
+    id: container
+//![4]
+    property alias cellColor: rectangle.color
+//![4]
+//![5]
+    signal clicked(color cellColor)
+//![5]
+
+    width: 40; height: 25
+//![1]
+
+//![2]
+    Rectangle {
+        id: rectangle
+        border.color: "white"
+        anchors.fill: parent
+    }
+//![2]
+
+//![3]
+    MouseArea {
+        anchors.fill: parent
+        onClicked: container.clicked(container.cellColor)
+    }
+//![3]
+}
+//![0]
diff --git a/sources/pyside2/doc/tutorials/qmltutorial/helloworld/tutorial1.qml b/sources/pyside2/doc/tutorials/qmltutorial/helloworld/tutorial1.qml
new file mode 100644
index 000000000..ef26bb1aa
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmltutorial/helloworld/tutorial1.qml
@@ -0,0 +1,73 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the examples of PySide2.
+**
+** $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$
+**
+****************************************************************************/
+
+//![0]
+//![3]
+import QtQuick 1.0
+//![3]
+
+//![1]
+Rectangle {
+    id: page
+    width: 500; height: 200
+    color: "lightgray"
+//![1]
+
+//![2]
+    Text {
+        id: helloText
+        text: "Hello world!"
+        y: 30
+        anchors.horizontalCenter: page.horizontalCenter
+        font.pointSize: 24; font.bold: true
+    }
+//![2]
+}
+//![0]
diff --git a/sources/pyside2/doc/tutorials/qmltutorial/helloworld/tutorial2.qml b/sources/pyside2/doc/tutorials/qmltutorial/helloworld/tutorial2.qml
new file mode 100644
index 000000000..f86da25b7
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmltutorial/helloworld/tutorial2.qml
@@ -0,0 +1,82 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the examples of PySide2.
+**
+** $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$
+**
+****************************************************************************/
+
+//![0]
+import QtQuick 1.0
+
+Rectangle {
+    id: page
+    width: 500; height: 200
+    color: "lightgray"
+
+    Text {
+        id: helloText
+        text: "Hello world!"
+        y: 30
+        anchors.horizontalCenter: page.horizontalCenter
+        font.pointSize: 24; font.bold: true
+    }
+
+    Grid {
+        id: colorPicker
+        x: 4; anchors.bottom: page.bottom; anchors.bottomMargin: 4
+        rows: 2; columns: 3; spacing: 3
+
+//![1]
+        Cell { cellColor: "red"; onClicked: helloText.color = cellColor }
+//![1]
+        Cell { cellColor: "green"; onClicked: helloText.color = cellColor }
+        Cell { cellColor: "blue"; onClicked: helloText.color = cellColor }
+        Cell { cellColor: "yellow"; onClicked: helloText.color = cellColor }
+        Cell { cellColor: "steelblue"; onClicked: helloText.color = cellColor }
+        Cell { cellColor: "black"; onClicked: helloText.color = cellColor }
+    }
+}
+//![0]
diff --git a/sources/pyside2/doc/tutorials/qmltutorial/helloworld/tutorial3.qml b/sources/pyside2/doc/tutorials/qmltutorial/helloworld/tutorial3.qml
new file mode 100644
index 000000000..7324c4df9
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmltutorial/helloworld/tutorial3.qml
@@ -0,0 +1,101 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the examples of PySide2.
+**
+** $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$
+**
+****************************************************************************/
+
+//![0]
+import QtQuick 1.0
+
+Rectangle {
+    id: page
+    width: 500; height: 200
+    color: "lightgray"
+
+    Text {
+        id: helloText
+        text: "Hello world!"
+        y: 30
+        anchors.horizontalCenter: page.horizontalCenter
+        font.pointSize: 24; font.bold: true
+
+//![1]
+        MouseArea { id: mouseArea; anchors.fill: parent }
+//![1]
+
+//![2]
+        states: State {
+            name: "down"; when: mouseArea.pressed == true
+            PropertyChanges { target: helloText; y: 160; rotation: 180; color: "red" }
+        }
+//![2]
+
+//![3]
+        transitions: Transition {
+            from: ""; to: "down"; reversible: true
+            ParallelAnimation {
+                NumberAnimation { properties: "y,rotation"; duration: 500; easing.type: Easing.InOutQuad }
+                ColorAnimation { duration: 500 }
+            }
+        }
+//![3]
+    }
+
+    Grid {
+        id: colorPicker
+        x: 4; anchors.bottom: page.bottom; anchors.bottomMargin: 4
+        rows: 2; columns: 3; spacing: 3
+
+        Cell { cellColor: "red"; onClicked: helloText.color = cellColor }
+        Cell { cellColor: "green"; onClicked: helloText.color = cellColor }
+        Cell { cellColor: "blue"; onClicked: helloText.color = cellColor }
+        Cell { cellColor: "yellow"; onClicked: helloText.color = cellColor }
+        Cell { cellColor: "steelblue"; onClicked: helloText.color = cellColor }
+        Cell { cellColor: "black"; onClicked: helloText.color = cellColor }
+    }
+}
+//![0]
diff --git a/sources/pyside2/doc/tutorials/qmltutorial/index.rst b/sources/pyside2/doc/tutorials/qmltutorial/index.rst
new file mode 100644
index 000000000..35cda3170
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmltutorial/index.rst
@@ -0,0 +1,25 @@
+
+.. _qmltutorial:
+
+QML Tutorial
+************
+
+This tutorial gives an introduction to QML, the mark up language for Qt Quick. It doesn't cover everything;
+the emphasis is on teaching the key principles, and features are introduced as needed.
+
+Through the different steps of this tutorial we will learn about QML basic types, we will create our own QML component
+with properties and signals, and we will create a simple animation with the help of states and transitions.
+
+Chapter one starts with a minimal "Hello world" program and the following chapters introduce new concepts.
+
+The tutorial's source code can be downloaded :download:`here<helloworld.tar.bz2>`.
+
+Tutorial chapters:
+
+.. toctree::
+    :maxdepth: 1
+
+    step1.rst
+    step2.rst
+    step3.rst
+
diff --git a/sources/pyside2/doc/tutorials/qmltutorial/step1.rst b/sources/pyside2/doc/tutorials/qmltutorial/step1.rst
new file mode 100644
index 000000000..02a1095bc
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmltutorial/step1.rst
@@ -0,0 +1,66 @@
+.. _qmlbasictypes:
+
+QML Tutorial 1 - Basic Types
+****************************
+
+This first program is a very simple "Hello world" example that introduces some basic QML concepts.
+The picture below is a screenshot of this program.
+
+.. figure:: declarative-tutorial1.png
+    :align: center
+
+Here is the QML code for the application:
+
+.. pysideinclude:: helloworld/tutorial1.qml
+    :snippet: 0
+
+Walkthrough
+===========
+
+Import
+------
+
+First, we need to import the types that we need for this example. Most QML files will import the built-in QML
+types (like Rectangle, Image, ...) that come with Qt, using:
+
+.. pysideinclude:: helloworld/tutorial1.qml
+    :snippet: 3
+
+Rectangle element
+-----------------
+
+.. pysideinclude:: helloworld/tutorial1.qml
+    :snippet: 1
+
+We declare a root element of type Rectangle. It is one of the basic building blocks you can use to create an application in QML.
+We give it an ``id`` to be able to refer to it later. In this case, we call it "page".
+We also set the ``width``, ``height`` and ``color`` properties.
+The Rectangle element contains many other properties (such as ``x`` and ``y``), but these are left at their default values.
+
+Text element
+------------
+
+.. pysideinclude code/tutorial1.qml
+    :snippet: 2
+
+We add a Text element as a child of the root Rectangle element that displays the text 'Hello world!'.
+
+The ``y`` property is used to position the text vertically at 30 pixels from the top of its parent.
+
+The ``anchors.horizontalCenter`` property refers to the horizontal center of an element.
+In this case, we specify that our text element should be horizontally centered in the *page* element.
+
+The ``font.pointSize`` and ``font.bold properties`` are related to fonts and use the dot notation.
+
+
+Viewing the example
+-------------------
+
+To view what you have created, run the QML Viewer tool (located in the ``bin directory`` of your Qt installation) with your filename as the first argument.
+For example, to run the provided completed Tutorial 1 example from the install location, you would type:
+
+::
+
+    bin/qmlviewer tutorial1.qml
+
+[Previous :ref:`qmltutorial`][Next :ref:`qmlcomponents`]
diff --git a/sources/pyside2/doc/tutorials/qmltutorial/step2.rst b/sources/pyside2/doc/tutorials/qmltutorial/step2.rst
new file mode 100644
index 000000000..4dacd00a9
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmltutorial/step2.rst
@@ -0,0 +1,81 @@
+.. _qmlcomponents:
+
+QML Tutorial 2 - QML Components
+*******************************
+
+This chapter adds a color picker to change the color of the text.
+
+.. figure:: declarative-tutorial2.png
+    :align: center
+
+Our color picker is made of six cells with different colors.
+To avoid writing the same code multiple times for each cell, we create a new ``Cell`` component.
+A component provides a way of defining a new type that we can re-use in other QML files.
+A QML component is like a black-box and interacts with the outside world through properties, signals and functions and is generally
+defined in its own QML file.
+The component's filename must always start with a capital letter.
+
+Here is the QML code for ``Cell.qml``:
+
+.. pysideinclude:: helloworld/Cell.qml
+    :snippet: 0
+
+Walkthrough
+===========
+
+The Cell Component
+------------------
+
+.. pysideinclude:: helloworld/Cell.qml
+    :snippet: 1
+
+The root element of our component is an Item with the ``id`` *container*.
+An Item is the most basic visual element in QML and is often used as a container for other elements.
+
+.. pysideinclude:: helloworld/Cell.qml
+    :snippet: 4
+
+We declare a ``cellColor`` property. This property is accessible from  *outside* our component, this allows us
+to instantiate the cells with different colors.
+This property is just an alias to an existing property - the color of the rectangle that compose the cell.
+
+.. pysideinclude:: helloworld/Cell.qml
+    :snippet: 5
+
+We want our component to also have a signal that we call *clicked* with a *cellColor* parameter of type *color*.
+We will use this signal to change the color of the text in the main QML file later.
+
+.. pysideinclude:: helloworld/Cell.qml
+    :snippet: 2
+
+Our cell component is basically a colored rectangle with the ``id`` *rectangle*.
+
+The ``anchors.fill`` property is a convenient way to set the size of an element.
+In this case the rectangle will have the same size as its parent.
+
+.. pysideinclude:: helloworld/Cell.qml
+    :snippet: 3
+
+In order to change the color of the text when clicking on a cell, we create a MouseArea element with
+the same size as its parent.
+
+A MouseArea defines a signal called *clicked*.
+When this signal is triggered we want to emit our own *clicked* signal with the color as parameter.
+
+The main QML file
+-----------------
+
+In our main QML file, we use our ``Cell`` component to create the color picker:
+
+.. pysideinclude:: helloworld/tutorial2.qml
+    :snippet: 0
+
+We create the color picker by putting 6 cells with different colors in a grid.
+
+.. pysideinclude:: helloworld/tutorial2.qml
+    :snippet: 1
+
+When the *clicked* signal of our cell is triggered, we want to set the color of the text to the *cellColor* passed as a parameter.
+We can react to any signal of our component through a property of the name *'onSignalName'*.
+
+[Previous :ref:`qmlbasictypes`][Next :ref:`qmlstatesandtransitions`]
diff --git a/sources/pyside2/doc/tutorials/qmltutorial/step3.rst b/sources/pyside2/doc/tutorials/qmltutorial/step3.rst
new file mode 100644
index 000000000..a72d1eac0
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/qmltutorial/step3.rst
@@ -0,0 +1,47 @@
+.. _qmlstatesandtransitions:
+
+QML Tutorial 3 - States and Transitions
+***************************************
+
+In this chapter, we make this example a little bit more dynamic by introducing states and transitions.
+
+We want our text to move to the bottom of the screen, rotate and become red when clicked.
+
+.. figure:: declarative-tutorial3_animation.gif
+    :align: center
+
+Here is the QML code:
+
+.. pysideinclude:: helloworld/tutorial3.qml
+    :snippet: 0
+
+Walkthrough
+===========
+
+.. pysideinclude:: helloworld/tutorial3.qml
+    :snippet: 2
+
+First, we create a new *down* state for our text element.
+This state will be activated when the MouseArea is pressed, and deactivated when it is released.
+
+The *down* state includes a set of property changes from our implicit *default state*
+(the items as they were initially defined in the QML).
+Specifically, we set the ``y`` property of the text to ``160``, the rotation to ``180`` and the ``color`` to red.
+
+.. pysideinclude:: helloworld/tutorial3.qml
+    :snippet: 3
+
+Because we don't want the text to appear at the bottom instantly but rather move smoothly,
+we add a transition between our two states.
+
+``from`` and ``to`` define the states between which the transition will run.
+In this case, we want a transition from the default state to our *down* state.
+
+Because we want the same transition to be run in reverse when changing back from the *down* state to the default state,
+we set ``reversible`` to ``true``.
+This is equivalent to writing the two transitions separately.
+
+The ParallelAnimation element makes sure that the two types of animations (number and color) start at the same time.
+We could also run them one after the other by using SequentialAnimation instead.
+
+[Previous :ref:`qmlcomponents`]