/usr/share/qt5/doc/qtqml/qtqml-syntax-propertybinding.html is in qtdeclarative5-doc-html 5.2.1-3ubuntu15.
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 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- propertybinding.qdoc -->
<title>Property Binding | QtQml 5.2</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<ul>
<li>Qt 5.2</li>
<li><a href="qtqml-index.html">Qt QML</a></li>
<li>Property Binding</li>
<li id="buildversion">
Qt 5.2.1 Reference Documentation</li>
</ul>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<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 <tt>this</tt> with Property Binding</a></li>
</ul>
</div>
<h1 class="title">Property Binding</h1>
<span class="subtitle"></span>
<!-- $$$qtqml-syntax-propertybinding.html-description -->
<div class="descr"> <a name="details"></a>
<p>To make the fullest use of QML and its built-in support for implementing dynamic object behavioral changes, most QML objects will use <i>property binding</i>. 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 occurrence of some external event.</p>
<p>When an object's property is assigned a value, it can either be assigned a static value, or <i>bound</i> 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 <i>property binding</i> is created and the property's value is automatically updated by the QML engine whenever the value of the evaluated expression changes.</p>
<a name="overview"></a>
<h2>Overview</h2>
<p>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 Rectangle's <tt>height</tt> 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">"blue"</span>
}
}</pre>
<p>Whenever the <tt>height</tt> of the parent item changes, the <tt>height</tt> of the blue rectangle will update to be of the same value.</p>
<p>Furthermore, a binding can contain any valid JavaScript expression or statement, as QML uses a standards compliant JavaScript engine. Below are valid bindings that could be substituted for the <tt>height</tt> binding from the above 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">></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">></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>Whenever the value of <tt>parent.height</tt> changes, the QML engine will re-evaluate the above expression and assign the blue rectangle's <tt>width</tt> property with the appropriate updated value.</p>
<p>Bindings can access object properties, call methods and use built-in JavaScript objects such as <tt>Date</tt> and <tt>Math</tt>. Here is an example with various valid bindings:</p>
<pre class="qml"><span class="type">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">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">"yellow"</span>
<span class="type">TextInput</span> {
<span class="name">id</span>: <span class="name">myTextInput</span>
<span class="name">text</span>: <span class="string">"Hello QML!"</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"><=</span> <span class="number">10</span> ? <span class="string">"red"</span> : <span class="string">"blue"</span>
}
}</pre>
<p>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.</p>
<a name="qml-javascript-assignment"></a><a name="creating-property-bindings-from-javascript"></a>
<h2>Creating Property Bindings from JavaScript</h2>
<p>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.</p>
<p>For example, the <tt>height</tt> of the Rectangle below is initially bound to be twice its <tt>width</tt>. However, when the space key is pressed, the <tt>height</tt> value is changed to be three times its <tt>width</tt>. At this point, the <tt>height</tt> is assigned the currently evaluated result of <tt>width*3</tt> and <i>the height will no longer be automatically updated whenever the width 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 remove the binding, then this is not a problem. However if the intention is to create a new binding of <tt>width*3</tt> then the property must be assigned a Qt.<a href="qml-qtqml-binding.html">binding</a>() value instead. This is done by passing a function to Qt.<a href="qml-qtqml-binding.html">binding</a>() that returns the desired result:</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 when the space key is pressed, a new binding of <tt>width*3</tt> is assigned, instead of simply removing the initial binding.</p>
<a name="using-keyword-this-keyword-with-property-binding"></a>
<h3>Using <tt>this</tt> with Property Binding</h3>
<p>When creating a property binding from JavaScript, QML allows the use of the <tt>this</tt> keyword to refer to the object to which the property binding will be assigned. This allows one to explicitly refer to a property within an object when there may be ambiguity about the exact property that should be used for the binding.</p>
<p>For example, the <tt>Component.onCompleted</tt> handler below is defined within the scope of the Item, and references to <tt>width</tt> within this scope would refer to the Item's width, rather than that of the Rectangle. To bind the Rectangle's <tt>height</tt> to its own <tt>width</tt>, the function passed to Qt.<a href="qml-qtqml-binding.html">binding</a>() needs to explicitly refer to <tt>this.width</tt> rather than just <tt>width</tt>.</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">"yellow"</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">"rect.height = "</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>In this case, the function could also have referred to <tt>rect.width</tt> rather than <tt>this.width</tt>.</p>
<p>Note that the value of <tt>this</tt> is not defined outside of its use in property binding. 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">©</acronym> 2013 Digia Plc and/or its
subsidiaries. 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> Digia, Qt and their respective logos are trademarks of Digia Plc in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
|