propertybinding.qdoc

Go to the documentation of this file.

// Copyright (C) 2017 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
\page qtqml-syntax-propertybinding.html
\meta {keywords} {qmltopic}
\title Property Binding
\brief binding object properties
 
An object's property can be assigned a static value which stays constant until it
is explicitly assigned a new value. However, to make the fullest use of QML and its
built-in support for dynamic object behaviors, most QML objects use \e {property bindings}.
 
Property bindings are a core feature of QML that lets developers specify relationships
between different object properties. When a property's \e dependencies change in
value, the property is automatically updated according to the specified relationship.
 
Behind the scenes, the QML engine monitors the property's dependencies (that is,
the variables in the binding expression). When a change is detected, the QML engine
re-evaluates the binding expression and applies the new result to the property.
 
\section1 Overview
 
To create a property binding, a property is assigned a JavaScript expression that
evaluates to the desired value. At its simplest, a binding may be a reference to
another property. Take the following example, where the blue \l Rectangle's height
is bound to the height of its parent:
 
\qml
Rectangle {
    width: 200; height: 200
 
    Rectangle {
        width: 100
        height: parent.height
        color: "blue"
    }
}
\endqml
 
Whenever the height of the parent rectangle changes, the height of the blue
rectangle automatically updates to be of the same value.
 
A binding can contain any valid JavaScript expression or statement, as QML uses
a standards compliant JavaScript engine.  Bindings can access object properties,
call methods and use built-in JavaScript objects such as \c Date and \c Math.
Below are other possible bindings for the previous example:
 
\code
height: parent.height / 2
 
height: Math.min(parent.width, parent.height)
 
height: parent.height > 100 ? parent.height : parent.height/2
 
height: {
    if (parent.height > 100)
        return parent.height
    else
        return parent.height / 2
}
 
height: someMethodThatReturnsHeight()
\endcode
 
Below is a more complex example involving more objects and types:
 
\qml
Column {
    id: column
    width: 200
    height: 200
 
    Rectangle {
        id: topRect
        width: Math.max(bottomRect.width, parent.width/2)
        height: (parent.height / 3) + 10
        color: "yellow"
 
        TextInput {
            id: myTextInput
            text: "Hello QML!"
        }
    }
 
    Rectangle {
        id: bottomRect
        width: 100
        height: 50
        color: myTextInput.text.length <= 10 ? "red" : "blue"
    }
}
\endqml
 
In the previous example,
\list
\li \c topRect.width depends on \c bottomRect.width and \c column.width
\li \c topRect.height depends on \c column.height
\li \c bottomRect.color depends on \c myTextInput.text.length
\endlist
 
In addition, any properties referenced within a JavaScript function that is
itself used as a binding will be re-evaluated. For example, in the snippet
below, whenever the \c enabled property of the \c Rectangle changes, the
bindings for the \c x and \c y properties will be re-evaluated:
 
\snippet qml/function-call-binding.qml rectangle
 
Syntactically, bindings are allowed to be of arbitrary complexity. However, if
a binding is overly complex - such as involving multiple lines, or imperative
loops - it could indicate that the binding is being used for more than describing
property relationships. Complex bindings can reduce code performance, readability,
and maintainability. It may be a good idea to redesign components that have
complex bindings, or at least factor the binding out into a separate function.
As a general rule, users should not rely on the evaluation order of bindings.
 
\sa {Positioning with Anchors}
 
 
\target qml-javascript-assignment
\section1 Creating Property Bindings from JavaScript
 
A property with a binding is automatically updated as necessary. However, if the
property is later assigned a static value from a JavaScript statement, the binding
will be removed.
 
For example, the \l Rectangle below initially ensures that its \c height is always
twice its \c width. However, when the space key is pressed, the current value
of \c {width*3} will be assigned to \c height as a \e static value.  After that,
\e {the \c height will remain fixed at this value, even if the \c width changes}.
The assignment of the static value removes the binding.
 
\qml
import QtQuick 2.0
 
Rectangle {
    width: 100
    height: width * 2
 
    focus: true
    Keys.onSpacePressed: {
        height = width * 3
    }
}
\endqml
 
If the intention is to give the rectangle a fixed height and stop automatic
updates, then this is not a problem. However, if the intention is to establish
a new relationship between \c width and \c height, then the new binding
expression must be wrapped in the Qt.binding() function instead:
 
\qml
import QtQuick 2.0
 
Rectangle {
    width: 100
    height: width * 2
 
    focus: true
    Keys.onSpacePressed: {
        height = Qt.binding(function() { return width * 3 })
    }
}
\endqml
 
Now, after the space key is pressed, the rectangle's height will continue
auto-updating to always be three times its width.
 
\section3 Debugging overwriting of bindings
 
A common cause of bugs in QML applications is accidentally overwriting bindings
with static values from JavaScript statements. To help developers track down
problems of this kind, the QML engine is able to emit messages whenever a
binding is lost due to imperative assignments.
 
In order to generate such messages, you need to enable the informational output
for the \c{qt.qml.binding.removal} logging category, for instance by calling:
 
\code
QLoggingCategory::setFilterRules(QStringLiteral("qt.qml.binding.removal.info=true"));
\endcode
 
Please refer to the QLoggingCategory documentation for more information about
enabling output from logging categories.
 
Note that is perfectly reasonable in some circumstances to overwrite bindings.
Any message generated by the QML engine should be treated as a diagnostic aid,
and not necessarily as evidence of a problem without further investigation.
 
\section2 Using \c this with Property Binding
 
When creating a property binding from JavaScript, the \c this keyword can be used
to refer to the object which receives the binding. This is helpful for resolving
ambiguities with property names.
 
For example, the \c Component.onCompleted handler below is defined within the
scope of the \l Item. In this scope, \c width refers to the \l Item's width, not
the \l Rectangle's width. To bind the \l Rectangle's \c height to its own \c width,
the binding expression must explicitly refer to \c this.width (or alternatively,
\c{rect.width}):
 
\qml
Item {
    width: 500
    height: 500
 
    Rectangle {
        id: rect
        width: 100
        color: "yellow"
    }
 
    Component.onCompleted: {
        rect.height = Qt.binding(function() { return this.width * 2 })
        console.log("rect.height = " + rect.height) // prints 200, not 1000
    }
}
\endqml
 
\note The value of \c this is not defined outside of property bindings.
See \l {JavaScript Environment Restrictions} for details.
*/