diff options
author | Michael Brasser <michael.brasser@nokia.com> | 2011-04-13 11:39:58 +1000 |
---|---|---|
committer | Michael Brasser <michael.brasser@nokia.com> | 2011-06-02 11:59:50 +1000 |
commit | f97e25abe073bede66cc5683ae45baea3a528d44 (patch) | |
tree | c6f5899396fd0e00b123baa62ba33414fd42c92e | |
parent | 0c375ebc59e68121cff43d9dd65aec4593c34154 (diff) |
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" |