Qt Reference Documentation

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
         }
     }
 }

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 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.

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
 }
X

Thank you for giving your feedback.

Make sure it is related to this specific page. For more general bugs and requests, please use the Qt Bug Tracker.