summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorMichael Brasser <michael.brasser@nokia.com>2011-04-01 02:53:05 (GMT)
committerMichael Brasser <michael.brasser@nokia.com>2011-04-04 00:55:20 (GMT)
commit05f3920562e7a718492bed61a48c0058b65a0d5d (patch)
treedb16a81648ea8e6dd456f21ececf5d88ed627479 /doc
parent538a415b8296db36355609d6e84137b9354967a7 (diff)
downloadQt-05f3920562e7a718492bed61a48c0058b65a0d5d.zip
Qt-05f3920562e7a718492bed61a48c0058b65a0d5d.tar.gz
Qt-05f3920562e7a718492bed61a48c0058b65a0d5d.tar.bz2
Document using Behaviors with States.
Change-Id: I74f163cef8caa16cccb158061ec30ffb4e471fd1 Task-number: QTBUG-16856 Reviewed-by: Bea Lam
Diffstat (limited to 'doc')
-rw-r--r--doc/src/declarative/behaviors-and-states.qdoc206
1 files changed, 206 insertions, 0 deletions
diff --git a/doc/src/declarative/behaviors-and-states.qdoc b/doc/src/declarative/behaviors-and-states.qdoc
new file mode 100644
index 0000000..0815b39
--- /dev/null
+++ b/doc/src/declarative/behaviors-and-states.qdoc
@@ -0,0 +1,206 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qml-behaviors-and-states.html
+\title Using QML Behaviors with States
+
+\section1 Using Behaviors with States
+
+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.
+
+Here's an example that shows the problem:
+
+\qml
+import QtQuick 1.0
+
+Rectangle {
+ width: 400
+ height: 400
+
+ Rectangle {
+ id: coloredRect
+ width: 100
+ height: 100
+ anchors.centerIn: parent
+
+ color: "red"
+ Behavior on color {
+ ColorAnimation {}
+ }
+
+ MouseArea {
+ id: mouser
+ anchors.fill: parent
+ hoverEnabled: true
+ }
+
+ states: State {
+ name: "GreenState"
+ when: mouser.containsMouse
+
+ PropertyChanges {
+ target: coloredRect
+ color: "green"
+ }
+ }
+ }
+}
+\endqml
+
+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
+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.
+
+To state the problem more formally, using States and Behaviors together can cause unexpected behavior when:
+\list
+\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
+\o this Behavior can be interrupted to (re-)enter an explicitly defined state.
+\endlist
+
+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
+to red, and interrupt the animation to return to "GreenState", the base state will include the color in its intermediate, mid-animation form.
+
+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.
+
+1. Use a transition to animate the change, rather than a Behavior.
+
+\qml
+import QtQuick 1.0
+
+Rectangle {
+ width: 400
+ height: 400
+
+ Rectangle {
+ id: coloredRect
+ width: 100
+ height: 100
+ anchors.centerIn: parent
+
+ color: "red"
+
+ MouseArea {
+ id: mouser
+ anchors.fill: parent
+ hoverEnabled: true
+ }
+
+ states: State {
+ name: "GreenState"
+ when: mouser.containsMouse
+
+ PropertyChanges {
+ target: coloredRect
+ color: "green"
+ }
+ }
+
+ transitions: Transition {
+ ColorAnimation {}
+ }
+ }
+}
+\endqml
+
+2. Use a conditional binding to change the property value, rather than a state
+
+\qml
+import QtQuick 1.0
+
+Rectangle {
+ width: 400
+ height: 400
+
+ Rectangle {
+ id: coloredRect
+ width: 100
+ height: 100
+ anchors.centerIn: parent
+
+ color: mouser.containsMouse ? "green" : "red"
+ Behavior on color {
+ ColorAnimation {}
+ }
+
+ MouseArea {
+ id: mouser
+ anchors.fill: parent
+ hoverEnabled: true
+ }
+ }
+}
+\endqml
+
+3. Use only explicitly defined states, rather than an implicit base state
+
+\qml
+import QtQuick 1.0
+
+Rectangle {
+ width: 400
+ height: 400
+
+ Rectangle {
+ id: coloredRect
+ width: 100
+ height: 100
+ anchors.centerIn: parent
+
+ Behavior on color {
+ ColorAnimation {}
+ }
+
+ MouseArea {
+ id: mouser
+ anchors.fill: parent
+ hoverEnabled: true
+ }
+
+ states: [
+ State {
+ name: "GreenState"
+ when: mouser.containsMouse
+
+ PropertyChanges {
+ target: coloredRect
+ color: "green"
+ }
+ },
+ State {
+ name: "RedState"
+ when: !mouser.containsMouse
+
+ PropertyChanges {
+ target: coloredRect
+ color: "red"
+ }
+ }]
+ }
+}
+\endqml
+
+*/