src/qml/doc/src/syntax/propertybinding.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qtqml-syntax-propertybinding.html
  30 \title Property Binding
  31 \brief binding object properties
  32
  33 To make the fullest use of QML and its built-in support for implementing dynamic object behavioral changes, most QML objects will use \e {property binding}. This is a core feature of QML that allows objects to automatically update their properties in response to changing attributes in other objects or the occurence of some external event.
  34
  35 When an object's property is assigned a value, it can either be assigned a static value, or \e bound to a JavaScript expression. In the first case, the property's value will not change unless a new value is assigned to the property. In the latter case, a \e {property binding} is created and the property's value is automatically updated by the QML engine whenever the value of the evaluated expression changes.
  36
  37
  38 \section1 Overview
  39
  40 To create a property binding, a property is assigned an expression that evaluates to the desired value. At its simplest, an expression may simply be a reference to another object's property. Take the following example, where the blue \l Rectangle's \c height is bound to the height of its parent:
  41
  42 \qml
  43 Rectangle {
  44     width: 200; height: 200
  45
  46     Rectangle {
  47         width: 100; height: parent.height
  48         color: "blue"
  49     }
  50 }
  51 \endqml
  52
  53 Whenever the \c height of the parent item changes, the \c height of the blue rectangle will update to be of the same value.
  54
  55 Furthermore, a binding can contain any valid JavaScript expression or
  56 statement, as QML uses a standards compliant JavaScript engine.  Below are
  57 valid bindings that could be substituted for the \c height binding from the
  58 above example:
  59
  60 \code
  61 height: parent.height / 2
  62
  63 height: Math.min(parent.width, parent.height)
  64
  65 height: parent.height > 100 ? parent.height : parent.height/2
  66
  67 height: {
  68     if (parent.height > 100)
  69         return parent.height
  70     else
  71         return parent.height / 2
  72 }
  73
  74 height: someMethodThatReturnsHeight()
  75 \endcode
  76
  77 ###TODO have .gif here that demonstrates the changes?
  78
  79 Whenever the value of \c parent.height changes, the QML engine will re-evaluate the above expression and assign the blue rectangle's \c width property with the appropriate updated value.
  80
  81 Bindings can access object properties, call methods and use built-in JavaScript objects such as \c Date and \c Math. Here is an example with various valid bindings:
  82
  83 \qml
  84 Column {
  85     width: 200
  86     height: 200
  87
  88     Rectangle {
  89         width: Math.max(bottomRect.width, parent.width/2)
  90         height: (parent.height / 3) + 10
  91         color: "yellow"
  92
  93         TextInput {
  94             id: myTextInput
  95             text: "Hello QML!"
  96         }
  97     }
  98
  99     Rectangle {
 100         id: bottomRect
 101         width: 100
 102         height: 50
 103         color: myTextInput.text.length <= 10 ? "red" : "blue"
 104     }
 105 }
 106 \endqml
 107
 108 ###TODO have .gif here that demonstrates the changes?
 109
 110 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.
 111
 112
 113 \keyword qml-javascript-assignment
 114 \section1 Creating Property Bindings from JavaScript
 115
 116 Once a property has been bound to an expression, the property is set to be automatically updated as necessary. However, be aware that if the property is later assigned a static value from a JavaScript statement, this will remove the binding.
 117
 118 For example, the \c height of the \l Rectangle below is initially bound to be twice its \c width. However, when the space key is pressed, the \c height value is changed to be three times its \c width. At this point, the \c height is assigned the currently evaluated result of \c width*3 and \e {the height will no longer be automatically updated whenever the width changes}. The assignment of the static value removes the binding.
 119
 120 \qml
 121 import QtQuick 2.0
 122
 123 Rectangle {
 124     width: 100
 125     height: width * 2
 126
 127     focus: true
 128     Keys.onSpacePressed: {
 129         height = width * 3
 130     }
 131 }
 132 \endqml
 133
 134 If the intention is to remove the binding, then this is not a problem. However if the intention is to create a new binding of \c width*3 then the property must be assigned a Qt.binding() value instead. This is done by passing a function to Qt.binding() that returns the desired result:
 135
 136 \qml
 137 import QtQuick 2.0
 138
 139 Rectangle {
 140     width: 100
 141     height: width * 2
 142
 143     focus: true
 144     Keys.onSpacePressed: {
 145         height = Qt.binding(function() { return width * 3 })
 146     }
 147 }
 148 \endqml
 149
 150 Now when the space key is pressed, a new binding of \c width*3 is assigned, instead of simply removing the initial binding.
 151
 152
 153 \section2 Using \c this with Property Binding
 154
 155 When creating a property binding from JavaScript, QML allows the use of the \c
 156 this keyword to refer to the object to which the property binding will be
 157 assigned. This allows one to explicitly refer to a property within an object
 158 when there may be ambiguity about the exact property that should be used for the
 159 binding.
 160
 161 For example, the \c Component.onCompleted handler below is defined within the
 162 scope of the \l Item, and references to \c width within this scope would refer
 163 to the \l Item's width, rather than that of the \l Rectangle. To bind the \l
 164 Rectangle's \c height to its own \c width, the function passed to Qt.binding()
 165 needs to explicitly refer to \c this.width rather than just \c width.
 166
 167 \qml
 168 Item {
 169     width: 500
 170     height: 500
 171
 172     Rectangle {
 173         id: rect
 174         width: 100
 175         color: "yellow"
 176     }
 177
 178     Component.onCompleted: {
 179         rect.height = Qt.binding(function() { return this.width * 2 })
 180         console.log("rect.height = " + rect.height) // prints 200, not 1000
 181     }
 182 }
 183 \endqml
 184
 185 In this case, the function could also have referred to \c rect.width rather than
 186 \c this.width.
 187
 188 Note that the value of \c this is not defined outside of its use in property binding.
 189 See \l {QML JavaScript Restrictions} for details.
 190
 191
 192 */
 193