<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.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>Qt 4.8: Property Binding</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li>Property Binding</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<link rel="prev" href="qdeclarativebasictypes.html" />
<link rel="next" href="qml-positioners.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="qdeclarativebasictypes.html">Data Types</a>
<a class="nextPage" href="qml-positioners.html">Component Layouts</a>
</p><p/>
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#properties">Properties</a></li>
<li class="level1"><a href="#property-binding">Property Binding</a></li>
<li class="level1"><a href="#property-assignment-versus-property-binding">Property Assignment versus Property Binding</a></li>
<li class="level1"><a href="#types-of-properties">Types of Properties</a></li>
<li class="level2"><a href="#basic-property-types">Basic Property Types</a></li>
<li class="level2"><a href="#the-property">The <tt>id</tt> Property</a></li>
<li class="level2"><a href="#elements-and-objects-as-property-values">Elements and Objects as Property Values</a></li>
<li class="level2"><a href="#attached-properties">Attached Properties</a></li>
<li class="level2"><a href="#attached-signal-handlers">Attached Signal Handlers</a></li>
<li class="level2"><a href="#list-properties">List properties</a></li>
<li class="level2"><a href="#grouped-properties">Grouped Properties</a></li>
<li class="level2"><a href="#property-aliases">Property Aliases</a></li>
<li class="level3"><a href="#considerations-for-property-aliases">Considerations for property aliases</a></li>
<li class="level2"><a href="#default-properties">Default Properties</a></li>
<li class="level1"><a href="#using-the-binding-element">Using the Binding Element</a></li>
<li class="level1"><a href="#changing-property-values-in-states">Changing Property Values in States</a></li>
</ul>
</div>
<h1 class="title">Property Binding</h1>
<span class="subtitle"></span>
<!-- $$$propertybinding.html-description -->
<div class="descr"> <a name="details"></a>
<a name="properties"></a>
<h2>Properties</h2>
<p>QML components have <i>properties</i> that can be read and modified by other objects. In QML, properties serve many purposes but their main function is to bind to values. Values may be a <a href="qdeclarativebasictypes.html">basic type</a>, or other QML elements.</p>
<p>The syntax for properties is:</p>
<p><tt>[default] property <type> <name>[: defaultValue]</tt></p>
<p>Elements already possess useful properties but, to create custom properties, precede the property name with the keyword <tt>property</tt>.</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">width</span>: <span class="number">320</span>; <span class="name">height</span>: <span class="number">240</span>
<span class="name">color</span>: <span class="string">"lightblue"</span>
<span class="name">focus</span>: <span class="number">true</span>
property <span class="type">int</span> <span class="name">counter</span>
property <span class="type">real</span> <span class="name">area</span>: <span class="number">100.45</span>
}</pre>
<p>QML property rules coincide with many of JavaScript's property rules, for example, property names must begin with a lowercase letter. <a href="https://developer.mozilla.org/en/JavaScript/Reference/Reserved_Words">JavaScript reserved words</a> are not valid property names.</p>
<a name="property-binding"></a>
<h2>Property Binding</h2>
<p>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.</p>
<p>Property bindings are created in QML using the colon "<tt>:</tt>" before the value:</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">width</span>: <span class="name">parent</span>.<span class="name">width</span>
}</pre>
<p>The property binding causes the width of the <tt>Rectangle</tt> to update whenever the <tt>parent</tt>'s width changes.</p>
<p>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 built-in JavaScript objects such as <tt>Date</tt> and <tt>Math</tt>.</p>
<pre class="qml"> <span class="keyword">function</span> <span class="name">calculateArea</span>(<span class="name">width</span>, height) {
<span class="keyword">return</span> (<span class="name">width</span> <span class="operator">*</span> <span class="name">height</span>) <span class="operator">*</span> <span class="number">0.5</span>
}
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">width</span>: <span class="number">150</span>; <span class="name">height</span>: <span class="number">75</span>
property <span class="type">real</span> <span class="name">area</span>: <span class="name">calculateArea</span>(<span class="name">width</span>, <span class="name">height</span>)
property <span class="type">real</span> <span class="name">parentArea</span>: <span class="name">calculateArea</span>(<span class="name">parent</span>.<span class="name">width</span>,<span class="name">parent</span>.<span class="name">height</span>)
<span class="name">color</span>: { <span class="keyword">if</span> (<span class="name">area</span> <span class="operator">></span> <span class="name">parentArea</span>) <span class="string">"blue"</span>; else <span class="string">"red"</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="property-assignment-versus-property-binding"></a>
<h2>Property Assignment versus Property Binding</h2>
<p>When working with both QML and JavaScript, it is important to differentiate between QML property binding and JavaScript value assignment. In QML, a property binding is created using the colon "<tt>:</tt>".</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">width</span>: <span class="name">parent</span>.<span class="name">width</span>
}</pre>
<p>The property binding causes the width of the <tt>Rectangle</tt> to update whenever the <tt>parent</tt>'s width changes.</p>
<p>Assigning a property value (using the equals sign "<tt>=</tt>") does not create a property binding.</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">Component</span>.onCompleted: {
<span class="name">width</span> <span class="operator">=</span> <span class="number">150</span>
}
}</pre>
<p>Instead of creating a property binding, the assignment simply sets the <tt>Rectangle</tt> <tt>width</tt> value to a number when the <tt>Component.onCompleted</tt> code is invoked.</p>
<p>Assigning a value to a property that is already bound will remove the previous binding. A property can only have one value at a time (a list of property is one value), and if any code explicitly re-sets this value, the property binding is removed.</p>
<p>There is no way to create a property binding directly from imperative JavaScript code, although it is possible to use the <a href="#using-the-binding-element">Binding</a> element.</p>
<a name="types-of-properties"></a>
<h2>Types of Properties</h2>
<p>Properties may bind to different types, but they are <i>type-safe</i>. That is, properties only allow you to assign a value that matches the property type. For example, if a property is a real, and if you try to assign a string to it you will get an error.</p>
<pre class="cpp"> property real volume: "four" //generates an error</pre>
<p>Certain properties bind to more complex types such as other elements and objects.</p>
<a name="qml-basic-property-types"></a><a name="basic-property-types"></a>
<h3>Basic Property Types</h3>
<p>Basic types such as <a href="qml-int.html">int</a>, <a href="qml-real.html">real</a>, and other Qt structures may be bound to properties. For a list of types, visit the <a href="qdeclarativebasictypes.html">QML Basic Types</a> document.</p>
<a name="qml-id-property"></a><a name="the-property"></a>
<h3>The <tt>id</tt> Property</h3>
<p>Each QML object may be given a special unique property called an <tt>id</tt>. No other object within the same QML component (see <a href="qdeclarativedocuments.html">QML Documents</a>) can have the same <tt>id</tt> value. QML objects may then access an object using the <tt>id</tt> property.</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">container</span>
<span class="name">width</span>: <span class="number">100</span>; <span class="name">height</span>: <span class="number">100</span>
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">width</span>: <span class="name">parent</span>.<span class="name">width</span>; <span class="name">height</span>: <span class="name">parent</span>.<span class="name">height</span>
}
}
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">width</span>: <span class="name">container</span>.<span class="name">width</span>; <span class="name">height</span>: <span class="name">container</span>.<span class="name">height</span>
}</pre>
<p>A component may readily access its parent's properties by using the <tt>parent</tt> property.</p>
<p>Note that an <tt>id</tt> must begin with a lower-case letter or an underscore. The <tt>id</tt> cannot contain characters other than letters, numbers, underscores, and <a href="https://developer.mozilla.org/en/JavaScript/Reference/Reserved_Words">JavaScript reserved words</a>.</p>
<a name="elements-and-objects-as-property-values"></a>
<h3>Elements and Objects as Property Values</h3>
<p>Many properties bind to objects. For example, the <a href="qml-item.html">Item</a> element has a <tt>states</tt> property that can bind to <a href="qml-state.html">State</a> elements. This type of property binding allows elements to carry additional non-children elements. <tt>Item</tt>'s <tt>transitions</tt> property behaves in a similar way; it can bind to <a href="qml-transition.html">Transition</a> elements.</p>
<p>Care must be taken when referring to the parent of an object property binding. Elements and components that are bound to properties are not necessarily set as children of the properties' component.</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">parentrectangle</span>
<span class="name">gradient</span>:
<span class="name">Gradient</span> { <span class="comment">//not a child of parentrectangle</span>
<span class="comment">//generates a TypeError</span>
<span class="comment">//Component.onCompleted: console.log(parent.width)</span>
}
<span class="comment">//child of parentrectangle</span>
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {property <span class="type">string</span> <span class="name">name</span>: <span class="string">"childrectangle"</span>}
<span class="comment">//prints "childrectangle"</span>
<span class="name">Component</span>.onCompleted: <span class="name">console</span>.<span class="name">log</span>(<span class="name">children</span>[<span class="number">0</span>].<span class="name">name</span>)
}</pre>
<p>The code snippet has a <a href="qml-gradient.html">Gradient</a> element that attempts to print its parent's <tt>width</tt> value. However, the <tt>Gradient</tt> element is bound to the <tt>gradient</tt> property, not the <tt>children</tt> property of the <tt>Rectangle</tt>. As a result, the <tt>Gradient</tt> does not have the <tt>Rectangle</tt> as its parent. Printing the value of <tt>parent.width</tt> generates an error. Printing the <tt>Rectangle</tt> object's first child's <tt>name</tt> will print <tt>childrectangle</tt> because the second <tt>Rectangle</tt> is bound to the <tt>children</tt> property.</p>
<p>For more information about the <tt>children</tt> property, please read the <a href="#default-properties">Default Properties</a> section.</p>
<a name="attached-properties"></a><a name="attached-properties"></a>
<h3>Attached Properties</h3>
<p>Certain objects provide additional properties by <i>attaching</i> properties to other objects. For example, the <a href="qml-keys.html">Keys</a> element have properties that can <i>attach</i> to other QML objects to provide keyboard handling.</p>
<pre class="qml"> <span class="type"><a href="qml-component.html">Component</a></span> {
<span class="name">id</span>: <span class="name">listdelegate</span>
<span class="type"><a href="qml-text.html">Text</a></span> {
<span class="name">text</span>: <span class="string">"Hello"</span>
<span class="name">color</span>: <span class="name">ListView</span>.<span class="name">isCurrentItem</span> ? <span class="string">"red"</span> : <span class="string">"blue"</span>
}
}
<span class="type"><a href="qml-listview.html">ListView</a></span> {
<span class="name">delegate</span>: <span class="name">listdelegate</span>
}</pre>
<p>The element <a href="qml-listview.html">ListView</a> provides the delegate, <tt>listdelegate</tt>, the property <tt>isCurrentItem</tt> as an attached property. The <tt>ListView.isCurrentItem</tt> <i>attached property</i> provides highlight information to the delegate. Effectively, the <a href="qml-listview.html">ListView</a> element attaches the <tt>ListView.isCurrentItem</tt> property to each delegate it creates.</p>
<a name="attached-signalhandlers"></a><a name="attached-signal-handlers"></a>
<h3>Attached Signal Handlers</h3>
<p><i>Attached signal handlers</i> are similar to <a href="#attached-properties">attached properties</a> in that they attach to objects to provide additional functionality to objects. Two prominent elements, <a href="qml-component.html">Component</a> and <a href="qml-keys.html">Keys</a> element provide <a href="qmlevents.html">signal handlers</a> as attached signal handlers.</p>
<pre class="qml"> <span class="type"><a href="qml-item.html">Item</a></span> {
<span class="name">Keys</span>.onPressed: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"Key Press Detected"</span>)
<span class="name">Component</span>.onCompleted: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"Completed initialization"</span>)
}</pre>
<p>Read the <a href="qmlevents.html">QML Signal and Handler Event System</a> and the <a href="qdeclarativefocus.html">Keyboard Focus in QML</a> articles for more information.</p>
<a name="list-properties"></a>
<h3>List properties</h3>
<p>Some properties may accept a binding to a list property, where more than one component can bind to the property. List properties allow multiple <a href="qml-state.html">States</a>, <a href="qml-gradient.html">Gradients</a>, and other components to bind to a single property.</p>
<pre class="qml"> <span class="type"><a href="qml-item.html">Item</a></span> {
<span class="name">id</span>: <span class="name">multistate</span>
<span class="name">states</span>: [
<span class="type"><a href="qml-state.html">State</a></span> {<span class="name">name</span>: <span class="string">"FETCH"</span>},
<span class="type"><a href="qml-state.html">State</a></span> {<span class="name">name</span>: <span class="string">"DECODE"</span>},
<span class="type"><a href="qml-state.html">State</a></span> {<span class="name">name</span>: <span class="string">"EXECUTE"</span>}
]
}</pre>
<p>The list is enclosed in square brackets, with a comma separating the list elements. In cases where you are only assigning a single item to a list, you may omit the square brackets.</p>
<pre class="qml"> <span class="type"><a href="qml-item.html">Item</a></span> {
<span class="name">id</span>: <span class="name">monostate</span>
<span class="name">states</span>: <span class="name">State</span> {<span class="name">name</span>: <span class="string">"RUNNING"</span>}
}</pre>
<p>To access the list, use the <tt>index</tt> property.</p>
<pre class="qml"> <span class="name">Component</span>.onCompleted: <span class="name">console</span>.<span class="name">log</span> (<span class="name">multistate</span>.<span class="name">states</span>[<span class="number">0</span>].<span class="name">name</span>)</pre>
<p>The snippet code simply prints the name of the first state, <tt>FETCH</tt>.</p>
<p>See the <a href="qml-list.html">list type</a> documentation for more details about list properties and their available operations.</p>
<a name="qml-grouped-properties"></a><a name="grouped-properties"></a>
<h3>Grouped Properties</h3>
<p>In some cases properties form a logical group and use either the <i>dot</i> notation or <i>group</i> notation.</p>
<p>Grouped properties may be written both ways:</p>
<pre class="qml"> <span class="type"><a href="qml-text.html">Text</a></span> {
<span class="comment">//dot notation</span>
<span class="name">font</span>.pixelSize: <span class="number">12</span>
<span class="name">font</span>.bold: <span class="number">true</span>
}
<span class="type"><a href="qml-text.html">Text</a></span> {
<span class="comment">//group notation</span>
<span class="type">font</span> {<span class="name">pixelSize</span>: <span class="number">12</span>; <span class="name">bold</span>: <span class="number">true</span>}
}</pre>
<p>In the element documentation grouped properties are shown using the dot notation.</p>
<a name="property-aliases"></a>
<h3>Property Aliases</h3>
<p>Unlike a property definition, which allocates a new, unique storage space for the property, a property alias connects the newly declared property, called the <i>aliasing property</i> as a direct reference to an existing property, the <i>aliased property</i>. Read or write operations on the aliasing property results in a read or write operations on the aliased property, respectively.</p>
<p>A property alias declaration is similar to an ordinary property definition:</p>
<p><tt>[default] property alias <name>: <alias reference></tt></p>
<p>As the aliasing property has the same type as the aliased property, an explicit type is omitted, and the special <tt>alias</tt> keyword is before the property name. Instead of a default value, a property alias has a compulsory alias reference. Accessing the aliasing property is similar to accessing a regular property. In addition, the optional <tt>default</tt> keyword indicates that the aliasing property is a <a href="#default-properties">default property</a>.</p>
<pre class="qml"> property <span class="type">alias</span> <span class="name">buttonLabel</span>: <span class="name">label</span>.<span class="name">text</span>
<span class="type"><a href="qml-text.html">Text</a></span> {
<span class="name">id</span>: <span class="name">label</span>
<span class="name">text</span>: <span class="string">"empty label"</span>
}</pre>
<p>When importing the component as a <tt>Button</tt>, the <tt>buttonlabel</tt> is directly accessible through the <tt>label</tt> property.</p>
<pre class="qml"> <span class="type">Button</span> {
<span class="name">id</span>: <span class="name">textbutton</span>
<span class="name">buttonLabel</span>: <span class="string">"Click Me!"</span>
}</pre>
<p>In addition, the <tt>id</tt> property may also be aliased and referred outside the component.</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
property <span class="type">alias</span> <span class="name">buttonImage</span>: <span class="name">image</span>
<span class="type"><a href="qml-image.html">Image</a></span> {<span class="name">id</span>: <span class="name">image</span>}
}</pre>
<p>The <tt>imagebutton</tt> component has the ability to modify the child <a href="qml-image.html">Image</a> object and its properties.</p>
<pre class="qml"> <span class="type">Button</span> {
<span class="name">id</span>: <span class="name">imagebutton</span>
<span class="name">buttonImage</span>.source: <span class="string">"http://qt.nokia.com/logo.png"</span>
<span class="name">buttonLabel</span>: <span class="name">buttonImage</span>.<span class="name">source</span>
}</pre>
<p>Using aliases, properties may be exposed to the <a href="qmlbasicelements.html#qml-top-level-component">top level component</a>. Exposing properties to the top-level component allows components to have interfaces similar to Qt widgets.</p>
<a name="considerations-for-property-aliases"></a>
<h4>Considerations for property aliases</h4>
<p>Aliases are only activated once the component <a href="qml-component.html#onCompleted-signal">completes</a> its initialization. An error is generated when an uninitialized alias is referenced. Likewise, aliasing an aliasing property will also result in an error.</p>
<pre class="qml"> property <span class="type">alias</span> <span class="name">widgetLabel</span>: <span class="name">label</span>
<span class="comment">//will generate an error</span>
<span class="comment">//widgetLabel.text: "Initial text"</span>
<span class="comment">//will generate an error</span>
<span class="comment">//property alias widgetLabelText: widgetLabel.text</span>
<span class="name">Component</span>.onCompleted: <span class="name">widgetLabel</span>.<span class="name">text</span> <span class="operator">=</span> <span class="string">"Alias completed Initialization"</span></pre>
<p>When importing the component, however, aliasing properties appear as regular Qt properties and consequently can be used in alias references.</p>
<p>It is possible for an aliasing property to have the same name as an existing property, effectively overwriting the existing property. For example, the following component has a <tt>color</tt> alias property, named the same as the built-in <a href="qml-rectangle.html#color-prop">Rectangle::color</a> property:</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">coloredrectangle</span>
property <span class="type">alias</span> <span class="name">color</span>: <span class="name">bluerectangle</span>.<span class="name">color</span>
<span class="name">color</span>: <span class="string">"red"</span>
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">bluerectangle</span>
<span class="name">color</span>: <span class="string">"#1234ff"</span>
}
<span class="name">Component</span>.onCompleted: {
<span class="name">console</span>.<span class="name">log</span> (<span class="name">coloredrectangle</span>.<span class="name">color</span>) <span class="comment">//prints "#1234ff"</span>
<span class="name">setInternalColor</span>()
<span class="name">console</span>.<span class="name">log</span> (<span class="name">coloredrectangle</span>.<span class="name">color</span>) <span class="comment">//prints "#111111"</span>
<span class="name">coloredrectangle</span>.<span class="name">color</span> <span class="operator">=</span> <span class="string">"#884646"</span>
<span class="name">console</span>.<span class="name">log</span> (<span class="name">coloredrectangle</span>.<span class="name">color</span>) <span class="comment">//prints #884646</span>
}
<span class="comment">//internal function that has access to internal properties</span>
<span class="keyword">function</span> <span class="name">setInternalColor</span>() {
<span class="name">color</span> <span class="operator">=</span> <span class="string">"#111111"</span>
}
}</pre>
<p>Any object that use this component and refer to its <tt>color</tt> property will be referring to the alias rather than the ordinary <a href="qml-rectangle.html#color-prop">Rectangle::color</a> property. Internally, however, the <tt>coloredrectangle</tt> can correctly set its <tt>color</tt> property and refer to the actual defined property rather than the alias.</p>
<p>The <a href="declarative-ui-components-tabwidget.html">TabWidget</a> example uses aliases to reassign children to the <a href="qml-listview.html">ListView</a>, creating a tab effect.</p>
<a name="default-properties"></a><a name="default-properties"></a>
<h3>Default Properties</h3>
<p>When imported, QML components will bind declared children to their designated <i>default properties</i>. The optional <tt>default</tt> attribute specifies a property as the <i>default property</i>. For example, the State element's default property is its <a href="qml-state.html#changes-prop">changes</a> property. <a href="qml-propertychanges.html">PropertyChanges</a> elements may simply be placed as the <tt>State</tt>'s children and they will be bound to the <tt>changes</tt> property.</p>
<pre class="qml"> <span class="type"><a href="qml-state.html">State</a></span> {
<span class="name">changes</span>: [
<span class="type"><a href="qml-propertychanges.html">PropertyChanges</a></span> {},
<span class="type"><a href="qml-propertychanges.html">PropertyChanges</a></span> {}
]
}
<span class="type"><a href="qml-state.html">State</a></span> {
<span class="type"><a href="qml-propertychanges.html">PropertyChanges</a></span> {}
<span class="type"><a href="qml-propertychanges.html">PropertyChanges</a></span> {}
}</pre>
<p>Similarly, the <a href="qml-item.html">Item</a> element's default property is its <a href="qml-item.html#data-prop">data</a> property. The <tt>data</tt> property manages Item's <tt>children</tt> and <tt>resources</tt> properties. This way, different data types may be placed as direct children of the <tt>Item</tt>.</p>
<pre class="qml"> <span class="type"><a href="qml-item.html">Item</a></span> {
<span class="type"><a href="qml-text.html">Text</a></span> {}
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {}
<span class="type"><a href="qml-timer.html">Timer</a></span> {}
}
<span class="type"><a href="qml-item.html">Item</a></span> {
<span class="comment">//without default property</span>
<span class="name">children</span>: [
<span class="type"><a href="qml-text.html">Text</a></span> {},
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {}
]
<span class="name">resources</span>: [
<span class="type"><a href="qml-timer.html">Timer</a></span> {}
]
}</pre>
<p>Reassigning a default property is useful when a component is reused. For example, the <a href="declarative-ui-components-tabwidget.html">TabWidget</a> example uses the <tt>default</tt> attribute to reassign children to the <a href="qml-listview.html">ListView</a>, creating a tab effect.</p>
<a name="using-the-binding-element"></a>
<h2>Using the Binding Element</h2>
<p>In some advanced cases, it may be necessary to create bindings explicitly with the<a href="qml-binding.html">Binding</a> element.</p>
<p>For example, to bind a property exposed from C++ (<tt>system.brightness</tt>) to a value written in QML (<tt>slider.value</tt>), you could use the <a href="qml-binding.html">Binding</a> element as follows:</p>
<pre class="qml"> <span class="type"><a href="qml-binding.html">Binding</a></span> {
<span class="name">target</span>: <span class="name">system</span>
<span class="name">property</span>: <span class="string">"brightness"</span>
<span class="name">value</span>: <span class="name">slider</span>.<span class="name">value</span>
}</pre>
<a name="changing-property-values-in-states"></a>
<h2>Changing Property Values in States</h2>
<p>The <a href="qml-propertychanges.html">PropertyChanges</a> element is for setting property bindings within a <a href="qml-state.html">State</a> element to set a property binding.</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">rectangle</span>
<span class="name">states</span>: <span class="name">State</span> {
<span class="name">name</span>: <span class="string">"WARNING"</span>
<span class="type"><a href="qml-propertychanges.html">PropertyChanges</a></span> {
<span class="name">target</span>: <span class="name">rectangle</span>
<span class="name">color</span>: <span class="name">warning</span>.<span class="name">color</span>
}
}
}</pre>
<p>The rectangle's <tt>color</tt> property will bind to the <tt>warning</tt> component's <tt>color</tt> property when its <tt>state</tt> is set to the <tt>WARNING</tt> state.</p>
</div>
<!-- @@@propertybinding.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="qdeclarativebasictypes.html">Data Types</a>
<a class="nextPage" href="qml-positioners.html">Component Layouts</a>
</p>
</div>
</div>
</div>
<div class="ft">
<span></span>
</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.</p>
<br />
<p>
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.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
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. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
