This file is indexed.

/usr/share/qt5/doc/qtqml/qtqml-syntax-propertybinding.html is in qtdeclarative5-doc-html 5.9.5-0ubuntu1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- propertybinding.qdoc -->
  <title>Property Binding | Qt QML 5.9</title>
  <link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
  <script type="text/javascript">
    document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
    // loading style sheet breaks anchors that were jumped to before
    // so force jumping to anchor again
    setTimeout(function() {
        var anchor = location.hash;
        // need to jump to different anchor first (e.g. none)
        location.hash = "#";
        setTimeout(function() {
            location.hash = anchor;
        }, 0);
    }, 0);
  </script>
</head>
<body>
<div class="header" id="qtdocheader">
  <div class="main">
    <div class="main-rounded">
      <div class="navigationbar">
        <table><tr>
<td >Qt 5.9</td><td ><a href="qtqml-index.html">Qt QML</a></td><td >Property Binding</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.5 Reference Documentation</td>
        </tr></table>
      </div>
    </div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#overview">Overview</a></li>
<li class="level1"><a href="#creating-property-bindings-from-javascript">Creating Property Bindings from JavaScript</a></li>
<li class="level2"><a href="#using-keyword-this-keyword-with-property-binding">Using <code>this</code> with Property Binding</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Property Binding</h1>
<span class="subtitle"></span>
<!-- $$$qtqml-syntax-propertybinding.html-description -->
<div class="descr"> <a name="details"></a>
<p>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 <i>property bindings</i>.</p>
<p>Property bindings are a core feature of QML that lets developers specify relationships between different object properties. When a property's <i>dependencies</i> change in value, the property is automatically updated according to the specified relationship.</p>
<p>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.</p>
<a name="overview"></a>
<h2 id="overview">Overview</h2>
<p>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 Rectangle's height is bound to the height of its parent:</p>
<pre class="qml">

  <span class="type">Rectangle</span> {
      <span class="name">width</span>: <span class="number">200</span>; <span class="name">height</span>: <span class="number">200</span>

      <span class="type">Rectangle</span> {
          <span class="name">width</span>: <span class="number">100</span>
          <span class="name">height</span>: <span class="name">parent</span>.<span class="name">height</span>
          <span class="name">color</span>: <span class="string">&quot;blue&quot;</span>
      }
  }

</pre>
<p>Whenever the height of the parent rectangle changes, the height of the blue rectangle automatically updates to be of the same value.</p>
<p>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 <code>Date</code> and <code>Math</code>. Below are other possible bindings for the previous example:</p>
<pre class="cpp">

  height: parent<span class="operator">.</span>height <span class="operator">/</span> <span class="number">2</span>

  height: Math<span class="operator">.</span>min(parent<span class="operator">.</span>width<span class="operator">,</span> parent<span class="operator">.</span>height)

  height: parent<span class="operator">.</span>height <span class="operator">&gt;</span> <span class="number">100</span> <span class="operator">?</span> parent<span class="operator">.</span>height : parent<span class="operator">.</span>height<span class="operator">/</span><span class="number">2</span>

  height: {
      <span class="keyword">if</span> (parent<span class="operator">.</span>height <span class="operator">&gt;</span> <span class="number">100</span>)
          <span class="keyword">return</span> parent<span class="operator">.</span>height
      <span class="keyword">else</span>
          <span class="keyword">return</span> parent<span class="operator">.</span>height <span class="operator">/</span> <span class="number">2</span>
  }

  height: someMethodThatReturnsHeight()

</pre>
<p>Below is a more complex example involving more objects and types:</p>
<pre class="qml">

  <span class="type">Column</span> {
      <span class="name">id</span>: <span class="name">column</span>
      <span class="name">width</span>: <span class="number">200</span>
      <span class="name">height</span>: <span class="number">200</span>

      <span class="type">Rectangle</span> {
          <span class="name">id</span>: <span class="name">topRect</span>
          <span class="name">width</span>: <span class="name">Math</span>.<span class="name">max</span>(<span class="name">bottomRect</span>.<span class="name">width</span>, <span class="name">parent</span>.<span class="name">width</span><span class="operator">/</span><span class="number">2</span>)
          <span class="name">height</span>: (<span class="name">parent</span>.<span class="name">height</span> <span class="operator">/</span> <span class="number">3</span>) <span class="operator">+</span> <span class="number">10</span>
          <span class="name">color</span>: <span class="string">&quot;yellow&quot;</span>

          <span class="type">TextInput</span> {
              <span class="name">id</span>: <span class="name">myTextInput</span>
              <span class="name">text</span>: <span class="string">&quot;Hello QML!&quot;</span>
          }
      }

      <span class="type">Rectangle</span> {
          <span class="name">id</span>: <span class="name">bottomRect</span>
          <span class="name">width</span>: <span class="number">100</span>
          <span class="name">height</span>: <span class="number">50</span>
          <span class="name">color</span>: <span class="name">myTextInput</span>.<span class="name">text</span>.<span class="name">length</span> <span class="operator">&lt;=</span> <span class="number">10</span> ? <span class="string">&quot;red&quot;</span> : <span class="string">&quot;blue&quot;</span>
      }
  }

</pre>
<p>In the previous example,</p>
<ul>
<li><code>topRect.width</code> depends on <code>bottomRect.width</code> and <code>column.width</code></li>
<li><code>topRect.height</code> depends on <code>column.height</code></li>
<li><code>bottomRect.color</code> depends on <code>myTextInput.text.length</code></li>
</ul>
<p>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.</p>
<a name="qml-javascript-assignment"></a><a name="creating-property-bindings-from-javascript"></a>
<h2 id="creating-property-bindings-from-javascript">Creating Property Bindings from JavaScript</h2>
<p>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.</p>
<p>For example, the Rectangle below initially ensures that its <code>height</code> is always twice its <code>width</code>. However, when the space key is pressed, the current value of <code>width*3</code> will be assigned to <code>height</code> as a <i>static</i> value. After that, <i>the <code>height</code> will remain fixed at this value, even if the <code>width</code> changes</i>. The assignment of the static value removes the binding.</p>
<pre class="qml">

  import QtQuick 2.0

  <span class="type">Rectangle</span> {
      <span class="name">width</span>: <span class="number">100</span>
      <span class="name">height</span>: <span class="name">width</span> <span class="operator">*</span> <span class="number">2</span>

      <span class="name">focus</span>: <span class="number">true</span>
      <span class="name">Keys</span>.onSpacePressed: {
          <span class="name">height</span> <span class="operator">=</span> <span class="name">width</span> <span class="operator">*</span> <span class="number">3</span>
      }
  }

</pre>
<p>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 <code>width</code> and <code>height</code>, then the new binding expression must be wrapped in the Qt.binding() function instead:</p>
<pre class="qml">

  import QtQuick 2.0

  <span class="type">Rectangle</span> {
      <span class="name">width</span>: <span class="number">100</span>
      <span class="name">height</span>: <span class="name">width</span> <span class="operator">*</span> <span class="number">2</span>

      <span class="name">focus</span>: <span class="number">true</span>
      <span class="name">Keys</span>.onSpacePressed: {
          <span class="name">height</span> <span class="operator">=</span> <span class="name">Qt</span>.<span class="name">binding</span>(<span class="keyword">function</span>() { <span class="keyword">return</span> <span class="name">width</span> <span class="operator">*</span> <span class="number">3</span> })
      }
  }

</pre>
<p>Now, after the space key is pressed, the rectangle's height will continue auto-updating to always be three times its width.</p>
<a name="using-keyword-this-keyword-with-property-binding"></a>
<h3 >Using <code>this</code> with Property Binding</h3>
<p>When creating a property binding from JavaScript, the <code>this</code> keyword can be used to refer to the object which receives the binding. This is helpful for resolving ambiguities with property names.</p>
<p>For example, the <code>Component.onCompleted</code> handler below is defined within the scope of the Item. In this scope, <code>width</code> refers to the Item's width, not the Rectangle's width. To bind the Rectangle's <code>height</code> to its own <code>width</code>, the binding expression must explicitly refer to <code>this.width</code> (or alternatively, <code>rect.width</code>):</p>
<pre class="qml">

  <span class="type">Item</span> {
      <span class="name">width</span>: <span class="number">500</span>
      <span class="name">height</span>: <span class="number">500</span>

      <span class="type">Rectangle</span> {
          <span class="name">id</span>: <span class="name">rect</span>
          <span class="name">width</span>: <span class="number">100</span>
          <span class="name">color</span>: <span class="string">&quot;yellow&quot;</span>
      }

      <span class="name">Component</span>.onCompleted: {
          <span class="name">rect</span>.<span class="name">height</span> <span class="operator">=</span> <span class="name">Qt</span>.<span class="name">binding</span>(<span class="keyword">function</span>() { <span class="keyword">return</span> this.<span class="name">width</span> <span class="operator">*</span> <span class="number">2</span> })
          <span class="name">console</span>.<span class="name">log</span>(<span class="string">&quot;rect.height = &quot;</span> <span class="operator">+</span> <span class="name">rect</span>.<span class="name">height</span>) <span class="comment">// prints 200, not 1000</span>
      }
  }

</pre>
<p><b>Note: </b>The value of <code>this</code> is not defined outside of property bindings. See <a href="qtqml-javascript-hostenvironment.html#javascript-environment-restrictions">JavaScript Environment Restrictions</a> for details.</p></div>
<!-- @@@qtqml-syntax-propertybinding.html -->
        </div>
       </div>
   </div>
   </div>
</div>
<div class="footer">
   <p>
   <acronym title="Copyright">&copy;</acronym> 2017 The Qt Company Ltd.
   Documentation contributions included herein are the copyrights of
   their respective owners.<br>    The documentation provided herein is licensed under the terms of the    <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation    License version 1.3</a> as published by the Free Software Foundation.<br>    Qt and respective logos are trademarks of The Qt Company Ltd.     in Finland and/or other countries worldwide. All other trademarks are property
   of their respective owners. </p>
</div>
</body>
</html>