<?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" />
<!-- scope.qdoc -->
<title>Qt 4.8: QML Scope</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>QML Scope</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">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#javascript-scope">JavaScript Scope</a></li>
<li class="level1"><a href="#element-names-and-imported-javascript-files">Element Names and Imported JavaScript Files</a></li>
<li class="level1"><a href="#binding-scope-object">Binding Scope Object</a></li>
<li class="level1"><a href="#component-scope">Component Scope</a></li>
<li class="level1"><a href="#component-instance-hierarchy">Component Instance Hierarchy</a></li>
<li class="level1"><a href="#javascript-global-object">JavaScript Global Object</a></li>
</ul>
</div>
<h1 class="title">QML Scope</h1>
<span class="subtitle"></span>
<!-- $$$qdeclarativescope.html-description -->
<div class="descr"> <a name="details"></a>
<p>QML property bindings, inline functions and imported JavaScript files all run in a JavaScript scope. Scope controls which variables an expression can access, and which variable takes precedence when two or more names conflict.</p>
<p>As JavaScript's built-in scope mechanism is very simple, QML enhances it to fit more naturally with the QML language extensions.</p>
<a name="javascript-scope"></a>
<h2>JavaScript Scope</h2>
<p>QML's scope extensions do not interfere with JavaScript's natural scoping. JavaScript programmers can reuse their existing knowledge when programming functions, property bindings or imported JavaScript files in QML.</p>
<p>In the following example, the <tt>addConstant()</tt> method will add 13 to the parameter passed just as the programmer would expect irrespective of the value of the QML object's <tt>a</tt> and <tt>b</tt> properties.</p>
<pre class="cpp"> <span class="type">QtObject</span> {
property <span class="type">int</span> a: <span class="number">3</span>
property <span class="type">int</span> b: <span class="number">9</span>
function addConstant(b) {
var a <span class="operator">=</span> <span class="number">13</span>;
<span class="keyword">return</span> b <span class="operator">+</span> a;
}
}</pre>
<p>That QML respects JavaScript's normal scoping rules even applies in bindings. This totally evil, abomination of a binding will assign 12 to the QML object's <tt>a</tt> property.</p>
<pre class="cpp"> <span class="type">QtObject</span> {
property <span class="type">int</span> a
a: { var a <span class="operator">=</span> <span class="number">12</span>; a; }
}</pre>
<p>Every JavaScript expression, function or file in QML has its own unique variable object. Local variables declared in one will never conflict with local variables declared in another.</p>
<a name="element-names-and-imported-javascript-files"></a>
<h2>Element Names and Imported JavaScript Files</h2>
<p><a href="qdeclarativedocuments.html">QML Document</a>s include import statements that define the element names and JavaScript files visible to the document. In addition to their use in the QML declaration itself, element names are used by JavaScript code when accessing <a href="propertybinding.html#attached-properties">Attached Properties</a> and enumeration values.</p>
<p>The effect of an import applies to every property binding, and JavaScript function in the QML document, even those in nested inline components. The following example shows a simple QML file that accesses some enumeration values and calls an imported JavaScript function.</p>
<pre class="cpp"> import <span class="type">QtQuick</span> <span class="number">1.0</span>
import <span class="string">"code.js"</span> as Code
ListView {
snapMode: ListView<span class="operator">.</span>SnapToItem
delegate: Component {
Text {
elide: Text<span class="operator">.</span>ElideMiddle
text: <span class="string">"A really, really long string that will require eliding."</span>
color: Code<span class="operator">.</span>defaultColor()
}
}
}</pre>
<a name="binding-scope-object"></a>
<h2>Binding Scope Object</h2>
<p>Property bindings are the most common use of JavaScript in QML. Property bindings associate the result of a JavaScript expression with a property of an object. The object to which the bound property belongs is known as the binding's scope object. In this QML simple declaration the <a href="qml-item.html">Item</a> object is the binding's scope object.</p>
<pre class="cpp"> Item {
anchors<span class="operator">.</span>left: parent<span class="operator">.</span>left
}</pre>
<p>Bindings have access to the scope object's properties without qualification. In the previous example, the binding accesses the <a href="qml-item.html">Item</a>'s <tt>parent</tt> property directly, without needing any form of object prefix. QML introduces a more structured, object-oriented approach to JavaScript, and consequently does not require the use of the JavaScript <tt>this</tt> property.</p>
<p>Care must be used when accessing <a href="propertybinding.html#attached-properties">Attached Properties</a> from bindings due to their interaction with the scope object. Conceptually attached properties exist on <i>all</i> objects, even if they only have an effect on a subset of those. Consequently unqualified attached property reads will always resolve to an attached property on the scope object, which is not always what the programmer intended.</p>
<p>For example, the <a href="qml-pathview.html">PathView</a> element attaches interpolated value properties to its delegates depending on their position in the path. As <a href="qml-pathview.html">PathView</a> only meaningfully attaches these properties to the root element in the delegate, any sub-element that accesses them must explicitly qualify the root object, as shown below.</p>
<pre class="cpp"> PathView {
delegate: Component {
Rectangle {
id: root
Image {
scale: root<span class="operator">.</span>PathView<span class="operator">.</span>scale
}
}
}
}</pre>
<p>If the <a href="qml-image.html">Image</a> element omitted the <tt>root</tt> prefix, it would inadvertently access the unset <tt>PathView.scale</tt> attached property on itself.</p>
<a name="component-scope"></a>
<h2>Component Scope</h2>
<p>Each QML component in a QML document defines a logical scope. Each document has at least one root component, but can also have other inline sub-components. The component scope is the union of the object ids within the component and the component's root element's properties.</p>
<pre class="cpp"> Item {
property string title
Text {
id: titleElement
text: <span class="string">"<b>"</span> <span class="operator">+</span> title <span class="operator">+</span> <span class="string">"</b>"</span>
font<span class="operator">.</span>pixelSize: <span class="number">22</span>
anchors<span class="operator">.</span>top: parent<span class="operator">.</span>top
}
Text {
text: titleElement<span class="operator">.</span>text
font<span class="operator">.</span>pixelSize: <span class="number">18</span>
anchors<span class="operator">.</span>bottom: parent<span class="operator">.</span>bottom
}
}</pre>
<p>The example above shows a simple QML component that displays a rich text title string at the top, and a smaller copy of the same text at the bottom. The first <tt>Text</tt> element directly accesses the component's <tt>title</tt> property when forming the text to display. That the root element's properties are directly accessible makes it trivial to distribute data throughout the component.</p>
<p>The second <tt>Text</tt> element uses an id to access the first's text directly. IDs are specified explicitly by the QML programmer so they always take precedence over other property names (except for those in the <a href="#javascript-scope">JavaScript Scope</a>). For example, in the unlikely event that the binding's <a href="#binding-scope-object">scope object</a> had a <tt>titleElement</tt> property in the previous example, the <tt>titleElement</tt> id would still take precedence.</p>
<a name="component-instance-hierarchy"></a>
<h2>Component Instance Hierarchy</h2>
<p>In QML, component instances connect their component scopes together to form a scope hierarchy. Component instances can directly access the component scopes of their ancestors.</p>
<p>The easiest way to demonstrate this is with inline sub-components whose component scopes are implicitly scoped as children of the outer component.</p>
<pre class="cpp"> Item {
property color defaultColor: <span class="string">"blue"</span>
ListView {
delegate: Component {
Rectangle {
color: defaultColor
}
}
}
}</pre>
<p>The component instance hierarchy allows instances of the delegate component to access the <tt>defaultColor</tt> property of the <tt>Item</tt> element. Of course, had the delegate component had a property called <tt>defaultColor</tt> that would have taken precedence.</p>
<p>The component instance scope hierarchy extends to out-of-line components, too. In the following example, the <tt>TitlePage.qml</tt> component creates two <tt>TitleText</tt> instances. Even though the <tt>TitleText</tt> element is in a separate file, it still has access to the <tt>title</tt> property when it is used from within the <tt>TitlePage</tt>. QML is a dynamically scoped language - depending on where it is used, the <tt>title</tt> property may resolve differently.</p>
<pre class="cpp"> <span class="comment">// TitlePage.qml</span>
import <span class="type">QtQuick</span> <span class="number">1.0</span>
Item {
property string title
TitleText {
size: <span class="number">22</span>
anchors<span class="operator">.</span>top: parent<span class="operator">.</span>top
}
TitleText {
size: <span class="number">18</span>
anchors<span class="operator">.</span>bottom: parent<span class="operator">.</span>bottom
}
}
<span class="comment">// TitleText.qml</span>
import <span class="type">QtQuick</span> <span class="number">1.0</span>
Text {
property <span class="type">int</span> size
text: <span class="string">"<b>"</span> <span class="operator">+</span> title <span class="operator">+</span> <span class="string">"</b>"</span>
font<span class="operator">.</span>pixelSize: size
}</pre>
<p>Dynamic scoping is very powerful, but it must be used cautiously to prevent the behavior of QML code from becoming difficult to predict. In general it should only be used in cases where the two components are already tightly coupled in another way. When building reusable components, it is preferable to use property interfaces, like this:</p>
<pre class="cpp"> <span class="comment">// TitlePage.qml</span>
import <span class="type">QtQuick</span> <span class="number">1.0</span>
Item {
id: root
property string title
TitleText {
title: root<span class="operator">.</span>title
size: <span class="number">22</span>
anchors<span class="operator">.</span>top: parent<span class="operator">.</span>top
}
TitleText {
title: root<span class="operator">.</span>title
size: <span class="number">18</span>
anchors<span class="operator">.</span>bottom: parent<span class="operator">.</span>bottom
}
}
<span class="comment">// TitleText.qml</span>
import <span class="type">QtQuick</span> <span class="number">1.0</span>
Text {
property string title
property <span class="type">int</span> size
text: <span class="string">"<b>"</span> <span class="operator">+</span> title <span class="operator">+</span> <span class="string">"</b>"</span>
font<span class="operator">.</span>pixelSize: size
}</pre>
<a name="javascript-global-object"></a>
<h2>JavaScript Global Object</h2>
<p>In addition to all the properties that a developer would normally expect on the JavaScript global object, QML adds some custom extensions to make UI or QML specific tasks a little easier. These extensions are described in the <a href="qdeclarativeglobalobject.html">QML Global Object</a> documentation.</p>
<p>QML disallows element, id and property names that conflict with the properties on the global object to prevent any confusion. Programmers can be confident that <tt>Math.min(10, 9)</tt> will always work as expected!</p>
</div>
<!-- @@@qdeclarativescope.html -->
</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>
