Document behavior of conflicting when clauses.

Task-number: QTBUG-9371

3 files changed, 48 insertions, 4 deletions

diff --git a/src/declarative/util/qdeclarativestate.cpp b/src/declarative/util/qdeclarativestate.cpp
index 5e6c35e..e4c968e 100644
--- a/src/declarative/util/qdeclarativestate.cpp
+++ b/src/declarative/util/qdeclarativestate.cpp
@@ -121,14 +121,13 @@ QDeclarativeStateOperation::QDeclarativeStateOperation(QObjectPrivate &dd, QObje
 
 /*!
     \qmlclass State QDeclarativeState
-  \since 4.7
+    \since 4.7
     \brief The State element defines configurations of objects and properties.
 
     A state is specified as a set of batched changes from the default configuration.
 
-    Note that setting the state of an object from within another state of the same object is
-    inadvisible. Not only would this have the same effect as going directly to the second state
-    it may cause the program to crash.
+    \note setting the state of an object from within another state of the same object is
+    not allowed.
 
     \sa {qmlstates}{States}, {state-transitions}{Transitions}
 */
@@ -191,6 +190,17 @@ bool QDeclarativeState::isWhenKnown() const
 
     This should be set to an expression that evaluates to true when you want the state to
     be applied.
+
+    If multiple states in a group have \c when clauses that evaluate to true at the same time,
+    the first matching state will be applied. For example, in the following snippet
+    \c state1 will always be selected rather than \c state2 when sharedCondition becomes
+    \c true.
+    \qml
+    states: [
+        State { name: "state1"; when: sharedCondition },
+        State { name: "state2"; when: sharedCondition }
+    ]
+    \endqml
 */
 QDeclarativeBinding *QDeclarativeState::when() const
 {
diff --git a/tests/auto/declarative/qdeclarativestates/data/whenOrdering.qml b/tests/auto/declarative/qdeclarativestates/data/whenOrdering.qml
new file mode 100644
index 0000000..7369c63
--- /dev/null
+++ b/tests/auto/declarative/qdeclarativestates/data/whenOrdering.qml
@@ -0,0 +1,11 @@
+import Qt 4.6
+
+Rectangle {
+    property bool condition1: false
+    property bool condition2: false
+
+    states: [
+        State { name: "state1"; when: condition1 },
+        State { name: "state2"; when: condition2 }
+    ]
+}
diff --git a/tests/auto/declarative/qdeclarativestates/tst_qdeclarativestates.cpp b/tests/auto/declarative/qdeclarativestates/tst_qdeclarativestates.cpp
index e7c595a..f0b6759 100644
--- a/tests/auto/declarative/qdeclarativestates/tst_qdeclarativestates.cpp
+++ b/tests/auto/declarative/qdeclarativestates/tst_qdeclarativestates.cpp
@@ -108,6 +108,7 @@ private slots:
     void nonExistantProperty();
     void reset();
     void illegalObjectCreation();
+    void whenOrdering();
 };
 
 void tst_qdeclarativestates::initTestCase()
@@ -993,6 +994,28 @@ void tst_qdeclarativestates::illegalObjectCreation()
     QCOMPARE(error.description().toUtf8().constData(), "PropertyChanges does not support creating state-specific objects.");
 }
 
+void tst_qdeclarativestates::whenOrdering()
+{
+    QDeclarativeEngine engine;
+
+    QDeclarativeComponent c(&engine, SRCDIR "/data/whenOrdering.qml");
+    QDeclarativeRectangle *rect = qobject_cast<QDeclarativeRectangle*>(c.create());
+    QVERIFY(rect != 0);
+
+    QCOMPARE(rect->state(), QLatin1String(""));
+    rect->setProperty("condition2", true);
+    QCOMPARE(rect->state(), QLatin1String("state2"));
+    rect->setProperty("condition1", true);
+    QCOMPARE(rect->state(), QLatin1String("state1"));
+    rect->setProperty("condition2", false);
+    QCOMPARE(rect->state(), QLatin1String("state1"));
+    rect->setProperty("condition2", true);
+    QCOMPARE(rect->state(), QLatin1String("state1"));
+    rect->setProperty("condition1", false);
+    rect->setProperty("condition2", false);
+    QCOMPARE(rect->state(), QLatin1String(""));
+}
+
 QTEST_MAIN(tst_qdeclarativestates)
 
 #include "tst_qdeclarativestates.moc"