Property Binding

Property binding is a declarative way of specifying the value of a property. Binding allows a property's value to be expressed as an JavaScript expression that defines the value relative to other property values or data accessible in the application. The property value is automatically kept up to date if the other properties or data values change.

Property bindings are created implicitly in QML whenever a property is assigned an JavaScript expression. The following QML uses two property bindings to connect the size of the rectangle to that of otherItem.

 Rectangle {
     width: otherItem.width
     height: otherItem.height
 }

QML extends a standards compliant JavaScript engine, so any valid JavaScript expression can be used as a property binding. Bindings can access object properties, make function calls and even use builtin JavaScript objects like Date and Math. Assigning a constant value to a property can even be thought of as a binding - afterall, a constant is a valid JavaScript expression! Here are some examples of more complex bindings:

 Rectangle {
     function calculateMyHeight() {
         return Math.max(otherItem.height, thirdItem.height);
     }

     anchors.centerIn: parent
     width: Math.min(otherItem.width, 10)
     height: calculateMyHeight()
     color: { if (width > 10) "blue"; else "red" }
 }

While syntactically bindings can be of arbitrary complexity, if a binding starts to become overly complex - such as involving multiple lines, or imperative loops - it may be better to refactor the component entirely, or at least factor the binding out into a separate function.

Changing Bindings

The PropertyChanges element can be used within a state change to modify the bindings on properties.

This example modifies the Rectangle's width property binding to be otherItem.height when in the "square" state. When it returns to its default state, width's original property binding will have been restored.

 Rectangle {
     id: rectangle
     width: otherItem.width
     height: otherItem.height

     states: State {
         name: "square"
         PropertyChanges {
             target: rectangle
             width: otherItem.height
         }
     }
 }

Effects of Property Assignment in JavaScript

Assigning a property value from JavaScript does not create a property binding. For example:

 Rectangle {

     Component.onCompleted: {
         width = otherItem.width;
     }
 }

Instead of creating a property binding, this simply sets the width of the Rectangle to the value of other.width at the time the JavaScript code is invoked. See 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 Rectangle in the example below will have a width of 13, regardless of the otherItem's width.

 Rectangle {
     width: otherItem.width

     Component.onCompleted: {
         width = 13;
     }
 }

There is no way to create a property binding directly from imperative JavaScript code, although it is possible to set up a Binding object (shown below).

Binding Element

The implicit binding syntax shown previously is easy to use and works perfectly for most uses of bindings. In some advanced cases, it is necessary to create bindings explicitly using the Binding element.

For example, to bind a property exposed from C++ (system.brightness) to a value coming from QML (slider.value), you could use the Binding element as follows:

 Binding {
     target: system
     property: "brightness"
     value: slider.value
 }