Doc: Correct error in doc Transition QML Type

- corrected reference to non-existing state
- added example with multiple states

Fixes: QTBUG-73982
Change-Id: I7c815cb706f1ad1b8035f136448b75dce8eb9bfe
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

3 files changed, 106 insertions, 49 deletions

diff --git a/src/quick/doc/images/declarative-qtlogo.png b/src/quick/doc/images/declarative-qtlogo.png
index 940d159ae4..b63f1384b1 100644
--- a/src/quick/doc/images/declarative-qtlogo.png
+++ b/src/quick/doc/images/declarative-qtlogo.png
diff --git a/src/quick/doc/snippets/qml/transitions-list.qml b/src/quick/doc/snippets/qml/transitions-list.qml
index 06b9e39cc8..972d3ee14e 100644
--- a/src/quick/doc/snippets/qml/transitions-list.qml
+++ b/src/quick/doc/snippets/qml/transitions-list.qml
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2017 The Qt Company Ltd.
+** Copyright (C) 2019 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -48,52 +48,105 @@
 **
 ****************************************************************************/
 
-import QtQuick 2.0
+import QtQuick 2.13
 
 Rectangle {
-  width: 150; height: 250
+    id: page
+    width: 640
+    height: 500
 
-  Rectangle {
-      id: stopLight
-      x: 25; y: 15; width: 100; height: 100
-  }
-  Rectangle {
-      id: goLight
-      x: 25; y: 135; width: 100; height: 100
-  }
+    Image {
+        id: userIcon
+        x: topLeftRect.x
+        y: topLeftRect.y
 
-  states: [
-    State {
-      name: "stop"
-      PropertyChanges { target: stopLight; color: "red" }
-      PropertyChanges { target: goLight; color: "black" }
-    },
-    State {
-      name: "go"
-      PropertyChanges { target: stopLight; color: "black" }
-      PropertyChanges { target: goLight; color: "green" }
+        source: "../../images/declarative-qtlogo.png"
     }
-  ]
 
-  state: "stop"
+    Rectangle {
+        id: topLeftRect
+        anchors { left: parent.left; top: parent.top; leftMargin: 10; topMargin: 20 }
+        width: 46; height: 54
+        color: "Transparent"; border.color: "Gray"; radius: 6
+        // Clicking here sets state to default state, returning image to initial position
+        TapHandler { onTapped: page.state = 'start' }
+    }
+
+    Rectangle {
+        id: middleRightRect
+        anchors { right: parent.right; verticalCenter: parent.verticalCenter; rightMargin: 20 }
+        width: 46; height: 54
+        color: "Transparent"; border.color: "Gray"; radius: 6
+        // Clicking in here sets the state to 'middleRight'
+        TapHandler { onTapped: page.state = 'middleRight' }
+    }
 
-  MouseArea {
-      anchors.fill: parent
-      onClicked: parent.state == "stop" ?
-                 parent.state = "go" : parent.state = "stop"
-  }
+    Rectangle {
+        id: bottomLeftRect
+        anchors { left: parent.left; bottom: parent.bottom; leftMargin: 10; bottomMargin: 20 }
+        width: 46; height: 54
+        color: "Transparent"; border.color: "Gray"; radius: 6
+        // Clicking in here sets the state to 'bottomLeft'
+        TapHandler { onTapped: page.state = 'bottomLeft' }
+    }
 
-  //! [list of transitions]
-  transitions: [
-    Transition {
-        from: "stop"; to: "go"
-        PropertyAnimation { target: stopLight
-                            properties: "color"; duration: 1000 }
-    },
-    Transition {
-        from: "go"; to: "stop"
-        PropertyAnimation { target: goLight
-                            properties: "color"; duration: 1000 }
-    } ]
-  //! [list of transitions]
+    states: [
+        State {
+            name: "start"
+            PropertyChanges {
+                target: userIcon
+                explicit: true
+                x: topLeftRect.x
+                y: topLeftRect.y
+            }
+        },
+        State {
+            name: "middleRight"
+            PropertyChanges {
+                target: userIcon
+                explicit: true
+                x: middleRightRect.x
+                y: middleRightRect.y
+            }
+        },
+        State {
+            name: "bottomLeft"
+            PropertyChanges {
+                target: userIcon
+                explicit: true
+                x: bottomLeftRect.x
+                y: bottomLeftRect.y
+            }
+        }
+    ]
+//! [list of transitions]
+    transitions: [
+        Transition {
+            from: "*"; to: "middleRight"
+            NumberAnimation {
+                properties: "x,y";
+                easing.type: Easing.InOutQuad;
+                duration: 2000;
+            }
+        },
+        Transition {
+            from: "*"; to: "bottomLeft";
+            NumberAnimation {
+                properties: "x,y";
+                easing.type: Easing.InOutQuad;
+                duration: 200;
+            }
+        },
+        //If any other rectangle is clicked, the icon will return
+        //to the start position at a slow speed and bounce.
+        Transition {
+            from: "*"; to: "*";
+            NumberAnimation {
+                easing.type: Easing.OutBounce;
+                properties: "x,y";
+                duration: 4000;
+            }
+        }
+    ]
+//! [list of transitions]
 }
diff --git a/src/quick/util/qquicktransition.cpp b/src/quick/util/qquicktransition.cpp
index c8699426f2..b973309212 100644
--- a/src/quick/util/qquicktransition.cpp
+++ b/src/quick/util/qquicktransition.cpp
@@ -82,13 +82,15 @@ QT_BEGIN_NAMESPACE
     values can be set to restrict the animations to only be applied when changing
     from one particular state to another.
 
-    To define multiple transitions, specify \l Item::transitions as a list:
+    To define multiple Transitions, specify \l Item::transitions as a list:
 
     \snippet qml/transitions-list.qml list of transitions
 
-    If multiple Transitions are specified, only a single (best-matching) Transition will be applied for any particular
-    state change. In the example above, when changing to \c state1, the first transition will be used, rather
-    than the more generic second transition.
+    If multiple Transitions are specified, only a single (best-matching)
+    Transition will be applied for any particular state change. In the
+    example above, if the Rectangle enters a state other than \c "middleRight"
+    or \c "bottomLeft", the third Transition will be carried out, meaning the
+    icon will be moved to the starting point.
 
     If a state change has a Transition that matches the same property as a
     \l Behavior, the Transition animation overrides the \l Behavior for that
@@ -298,10 +300,11 @@ QQuickTransitionInstance *QQuickTransition::prepare(QQuickStateOperation::Action
 
     \snippet qml/transition-from-to-modified.qml modified transition
 
-    The animation would only be applied when changing from the default state to
-    the "brighter" state (i.e. when the mouse is pressed, but not on release).
+    The animation would only be applied when changing from the default state
+    to the "brighter" state (i.e. when the mouse is pressed, but not on release).
 
-    Multiple \c to and \c from values can be set by using a comma-separated string.
+    Multiple \c to and \c from values can be set by using a comma-separated
+    string.
 
     \sa reversible
 */
@@ -323,7 +326,8 @@ void QQuickTransition::setFromState(const QString &f)
 
 /*!
     \qmlproperty bool QtQuick::Transition::reversible
-    This property holds whether the transition should be automatically reversed when the conditions that triggered this transition are reversed.
+    This property holds whether the transition should be automatically
+    reversed when the conditions that triggered this transition are reversed.
 
     The default value is false.