doc/src/declarative/behaviors-and-states.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qml-behaviors-and-states.html
  30 \title Using QML Behaviors with States
  31
  32 \section1 Using Behaviors with States
  33
  34 In some cases you may choose to use a Behavior to animate a property change caused by a state change. While this works well for some situations, in other situations it may lead to unexpected behavior.
  35
  36 Here's an example that shows the problem:
  37
  38 \qml
  39 import QtQuick 1.0
  40
  41 Rectangle {
  42     width: 400
  43     height: 400
  44
  45     Rectangle {
  46         id: coloredRect
  47         width: 100
  48         height: 100
  49         anchors.centerIn: parent
  50
  51         color: "red"
  52         Behavior on color {
  53             ColorAnimation {}
  54         }
  55
  56         MouseArea {
  57             id: mouser
  58             anchors.fill: parent
  59             hoverEnabled: true
  60         }
  61
  62         states: State {
  63             name: "GreenState"
  64             when: mouser.containsMouse
  65
  66             PropertyChanges {
  67                 target: coloredRect
  68                 color: "green"
  69             }
  70         }
  71     }
  72 }
  73 \endqml
  74
  75 Testing the example by quickly and repeatedly moving the mouse in to and out of the colored rectangle shows that the colored rectangle will settle into a green color over time, never returning to full red. This is not what we wanted! The
  76 problem occurs because we have used a Behavior to animate the change in color, and our state change is trigged by the mouse entering or exiting the MouseArea, which is easily interrupted.
  77
  78 To state the problem more formally, using States and Behaviors together can cause unexpected behavior when:
  79 \list
  80 \o a Behavior is used to animate a property change, specifically when moving from an explicitly defined state back to the implicit base state; and
  81 \o this Behavior can be interrupted to (re-)enter an explicitly defined state.
  82 \endlist
  83
  84 The problem occurs because of the way the base state is defined for QML: as the "snapshot" state of the application just prior to entering an explicitly defined state. In this case, if we are in the process of animating from green back
  85 to red, and interrupt the animation to return to "GreenState", the base state will include the color in its intermediate, mid-animation form.
  86
  87 While future versions of QML should be able to handle this situation more gracefully, there are currently several ways to rework your application to avoid this problem.
  88
  89 1. Use a transition to animate the change, rather than a Behavior.
  90
  91 \qml
  92 import QtQuick 1.0
  93
  94 Rectangle {
  95     width: 400
  96     height: 400
  97
  98     Rectangle {
  99         id: coloredRect
 100         width: 100
 101         height: 100
 102         anchors.centerIn: parent
 103
 104         color: "red"
 105
 106         MouseArea {
 107             id: mouser
 108             anchors.fill: parent
 109             hoverEnabled: true
 110         }
 111
 112         states: State {
 113             name: "GreenState"
 114             when: mouser.containsMouse
 115
 116             PropertyChanges {
 117                 target: coloredRect
 118                 color: "green"
 119             }
 120         }
 121
 122         transitions: Transition {
 123             ColorAnimation {}
 124         }
 125     }
 126 }
 127 \endqml
 128
 129 2. Use a conditional binding to change the property value, rather than a state
 130
 131 \qml
 132 import QtQuick 1.0
 133
 134 Rectangle {
 135     width: 400
 136     height: 400
 137
 138     Rectangle {
 139         id: coloredRect
 140         width: 100
 141         height: 100
 142         anchors.centerIn: parent
 143
 144         color: mouser.containsMouse ? "green" : "red"
 145         Behavior on color {
 146             ColorAnimation {}
 147         }
 148
 149         MouseArea {
 150             id: mouser
 151             anchors.fill: parent
 152             hoverEnabled: true
 153         }
 154     }
 155 }
 156 \endqml
 157
 158 3. Use only explicitly defined states, rather than an implicit base state
 159
 160 \qml
 161 import QtQuick 1.0
 162
 163 Rectangle {
 164     width: 400
 165     height: 400
 166
 167     Rectangle {
 168         id: coloredRect
 169         width: 100
 170         height: 100
 171         anchors.centerIn: parent
 172
 173         Behavior on color {
 174             ColorAnimation {}
 175         }
 176
 177         MouseArea {
 178             id: mouser
 179             anchors.fill: parent
 180             hoverEnabled: true
 181         }
 182
 183         states: [
 184         State {
 185             name: "GreenState"
 186             when: mouser.containsMouse
 187
 188             PropertyChanges {
 189                 target: coloredRect
 190                 color: "green"
 191             }
 192         },
 193         State {
 194             name: "RedState"
 195             when: !mouser.containsMouse
 196
 197             PropertyChanges {
 198                 target: coloredRect
 199                 color: "red"
 200             }
 201         }]
 202     }
 203 }
 204 \endqml
 205
 206 */