Add docs and test for Binding changes.

Change-Id: I6bce140bf80c3e0defd7603aecfb7f658520f4d3
Reviewed-by: Martin Jones

3 files changed, 101 insertions, 0 deletions

diff --git a/src/declarative/util/qdeclarativebind.cpp b/src/declarative/util/qdeclarativebind.cpp
index 252dd6545b..6038aca8d5 100644
--- a/src/declarative/util/qdeclarativebind.cpp
+++ b/src/declarative/util/qdeclarativebind.cpp
@@ -82,6 +82,8 @@ public:
     \since 4.7
     \brief The Binding element allows arbitrary property bindings to be created.
 
+    \section1 Binding to an inaccessible property
+
     Sometimes it is necessary to bind to a property of an object that wasn't
     directly instantiated by QML - generally a property of a class exported
     to QML by C++. In these cases, regular property binding doesn't work. Binding
@@ -97,6 +99,44 @@ public:
     Whenever the text in the TextEdit is updated, the C++ property will be
     updated also.
 
+    \section1 "Single-branch" conditional binding
+
+    In some circumstances you may want to control the value of a property
+    only when a certain condition is true (and relinquish control in all
+    other cirumstances). This often isn't possible to accomplish with a direct
+    binding, as you need to supply values for all possible branches.
+
+    \qml
+    // warning: "Unable to assign [undefined] to double value"
+    value: if (mouse.pressed) mouse.mouseX
+    \endqml
+
+    The above example will produce a warning whenever we release the mouse, as the value
+    of the binding is undefined when the mouse isn't pressed. We can use the Binding
+    element to rewrite the above code and avoid the warning.
+
+    \qml
+    Binding on value {
+        when: mouse.pressed
+        value: mouse.mouseX
+    }
+    \endqml
+
+    The Binding element will also restore any previously set direct bindings on
+    the property. In that sense, it functions much like a simplified State.
+
+    \qml
+    // this is equivilant to the above Binding
+    State {
+        name: "pressed"
+        when: mouse.pressed
+        PropertyChanges {
+            target: obj
+            value: mouse.mouseX
+        }
+    }
+    \endqml
+
     If the binding target or binding property is changed, the bound value is
     immediately pushed onto the new target.
 
@@ -123,6 +163,9 @@ QDeclarativeBind::~QDeclarativeBind()
         value: name; when: list.ListView.isCurrentItem
     }
     \endcode
+
+    When the binding becomes inactive again, any direct bindings that were previously
+    set on the property will be restored.
 */
 bool QDeclarativeBind::when() const
 {
diff --git a/tests/auto/declarative/qdeclarativebinding/data/restoreBinding.qml b/tests/auto/declarative/qdeclarativebinding/data/restoreBinding.qml
new file mode 100644
index 0000000000..9491c0f1d3
--- /dev/null
+++ b/tests/auto/declarative/qdeclarativebinding/data/restoreBinding.qml
@@ -0,0 +1,26 @@
+import QtQuick 2.0
+
+Rectangle {
+    width: 400
+    height: 400
+
+    Rectangle {
+        id: myItem
+        objectName:  "myItem"
+        width: 100
+        height: 100
+        color: "green"
+        x: 100 - myItem.y
+
+        Binding on x {
+            when: myItem.y > 50
+            value: myItem.y
+        }
+
+        /*NumberAnimation on y {
+            loops: Animation.Infinite
+            to: 100
+            duration: 1000
+        }*/
+    }
+}
diff --git a/tests/auto/declarative/qdeclarativebinding/tst_qdeclarativebinding.cpp b/tests/auto/declarative/qdeclarativebinding/tst_qdeclarativebinding.cpp
index 6305cd33bc..127309e1e4 100644
--- a/tests/auto/declarative/qdeclarativebinding/tst_qdeclarativebinding.cpp
+++ b/tests/auto/declarative/qdeclarativebinding/tst_qdeclarativebinding.cpp
@@ -43,6 +43,7 @@
 #include <QtDeclarative/qdeclarativecomponent.h>
 #include <private/qdeclarativebind_p.h>
 #include <private/qdeclarativerectangle_p.h>
+#include <private/qsgrectangle_p.h>
 #include "../../../shared/util.h"
 
 #ifdef Q_OS_SYMBIAN
@@ -60,6 +61,7 @@ public:
 private slots:
     void binding();
     void whenAfterValue();
+    void restoreBinding();
 
 private:
     QDeclarativeEngine engine;
@@ -113,6 +115,36 @@ void tst_qdeclarativebinding::whenAfterValue()
     delete rect;
 }
 
+void tst_qdeclarativebinding::restoreBinding()
+{
+    QDeclarativeEngine engine;
+    QDeclarativeComponent c(&engine, QUrl::fromLocalFile(SRCDIR "/data/restoreBinding.qml"));
+    QSGRectangle *rect = qobject_cast<QSGRectangle*>(c.create());
+    QVERIFY(rect != 0);
+
+    QSGRectangle *myItem = qobject_cast<QSGRectangle*>(rect->findChild<QSGRectangle*>("myItem"));
+    QVERIFY(myItem != 0);
+
+    myItem->setY(25);
+    QCOMPARE(myItem->x(), qreal(100-25));
+
+    myItem->setY(13);
+    QCOMPARE(myItem->x(), qreal(100-13));
+
+    //Binding takes effect
+    myItem->setY(51);
+    QCOMPARE(myItem->x(), qreal(51));
+
+    myItem->setY(88);
+    QCOMPARE(myItem->x(), qreal(88));
+
+    //original binding restored
+    myItem->setY(49);
+    QCOMPARE(myItem->x(), qreal(100-49));
+
+    delete rect;
+}
+
 QTEST_MAIN(tst_qdeclarativebinding)
 
 #include "tst_qdeclarativebinding.moc"