summaryrefslogtreecommitdiffstats
path: root/doc/src
diff options
context:
space:
mode:
authorQt Continuous Integration System <qt-info@nokia.com>2011-04-04 05:40:43 (GMT)
committerQt Continuous Integration System <qt-info@nokia.com>2011-04-04 05:40:43 (GMT)
commitd1a21551dc31937db4b62b2406ea3820dd8a8c0a (patch)
tree38949bd50cc2df96a56b702815b1838c9c2cae43 /doc/src
parent19fd8c6c4c7e1a739cae53fa51c6994643ef5be1 (diff)
parentfd1e840eba4567e67b55a00f7f761fc9815eaa47 (diff)
downloadQt-d1a21551dc31937db4b62b2406ea3820dd8a8c0a.zip
Qt-d1a21551dc31937db4b62b2406ea3820dd8a8c0a.tar.gz
Qt-d1a21551dc31937db4b62b2406ea3820dd8a8c0a.tar.bz2
Merge branch '4.7' of scm.dev.nokia.troll.no:qt/qt-qml into 4.7-integration
* '4.7' of scm.dev.nokia.troll.no:qt/qt-qml: Fix failing autotest XmlListModel should allow types other than application/xml Document using Behaviors with States.
Diffstat (limited to 'doc/src')
-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
+
+*/