diff options
| -rw-r--r-- | doc/src/declarative/javascriptblocks.qdoc | 34 | ||||
| -rw-r--r-- | doc/src/declarative/propertybinding.qdoc | 33 |
2 files changed, 62 insertions, 5 deletions
diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc index 18da3d2..d290690 100644 --- a/doc/src/declarative/javascriptblocks.qdoc +++ b/doc/src/declarative/javascriptblocks.qdoc @@ -173,6 +173,40 @@ handler to execute at startup, they are run sequentially in an undefined order. Likewise, the \l {Component::onDestruction} attached property is triggered on component destruction. + +\section1 Property Assignment vs Property Binding + +When working with both QML and JavaScript, it is important to differentiate between +QML \l {Property Binding} and JavaScript value assignment. In QML, a property +binding is created using the \e {property: value} syntax: + +\code +Rectangle { + width: otherItem.width +} +\endcode + +The \c width of the above \l Rectangle is updated whenever \c otherItem.width changes. On the other +hand, take the following JavaScript code snippet, that runs when the \l Rectangle is created: + +\code +Rectangle { + + Component.onCompleted: { + width = otherItem.width; + } +} +\endcode + +The \c width of this \l Rectangle is \e assigned the value of \c otherItem.width using the +\e {property = value} syntax in JavaScript. Unlike the QML \e {property: value} syntax, this +does not invoke QML property binding; the \c rectangle.width property is set to the value +of \c otherItem.width at the time of the assignment and will not be updated if that value +changes. + +See \l {Property Binding} for more information. + + \section1 QML JavaScript Restrictions QML executes standard JavaScript code, with the following restrictions: diff --git a/doc/src/declarative/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc index 552b9e4..314bf67 100644 --- a/doc/src/declarative/propertybinding.qdoc +++ b/doc/src/declarative/propertybinding.qdoc @@ -94,10 +94,29 @@ Rectangle { } \endcode -Imperatively assigning a value directly to a property will also implicitly remove a binding -on a property. A property can only have one value at a time, and if code explicitly sets -this value the binding must be removed. The \l Rectangle in the example below will have -a width of 13, regardless of the otherItem's width. + +\section1 Effects of Property Assignment in JavaScript + +Assigning a property value from JavaScript does \e not create a property binding. +For example: + +\code +Rectangle { + + Component.onCompleted: { + width = otherItem.width; + } +} +\endcode + +Instead of creating a property binding, this simply sets the \c width of the \l Rectangle +to the value of \c other.width at the time the JavaScript code is invoked. See +\l {Property Assignment vs Property Binding} for more details. + +Also note that assigning a value to a property that is currently bound will remove the binding. +A property can only have one value at a time, and if any code explicitly sets +this value, the binding is removed. The \l Rectangle in the example below will have +a width of 13, regardless of the \c otherItem's width. \code Rectangle { @@ -109,7 +128,9 @@ Rectangle { } \endcode -There is no way to create a property binding directly from imperative JavaScript code. +There is no way to create a property binding directly from imperative JavaScript code, +although it is possible to set up a \l Binding object (shown below). + \section1 Binding Element @@ -126,5 +147,7 @@ Binding { value: slider.value } \endqml + + */ |