<?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" />
<!-- qdeclarativeintro.qdoc -->
<title>Qt 4.8: Introduction to the QML Language</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>Introduction to the QML Language</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="#basic-qml-syntax">Basic QML Syntax</a></li>
<li class="level1"><a href="#comments">Comments</a></li>
<li class="level1"><a href="#object-identifiers">Object Identifiers</a></li>
<li class="level1"><a href="#expressions">Expressions</a></li>
<li class="level1"><a href="#properties">Properties</a></li>
<li class="level2"><a href="#basic-property-types">Basic Property Types</a></li>
<li class="level2"><a href="#property-change-notifications">Property Change Notifications</a></li>
<li class="level2"><a href="#list-properties">List properties</a></li>
<li class="level2"><a href="#default-properties">Default Properties</a></li>
<li class="level2"><a href="#grouped-properties">Grouped Properties</a></li>
<li class="level2"><a href="#attached-properties">Attached Properties</a></li>
<li class="level1"><a href="#signal-handlers">Signal Handlers</a></li>
</ul>
</div>
<h1 class="title">Introduction to the QML Language</h1>
<span class="subtitle"></span>
<!-- $$$qdeclarativeintroduction.html-description -->
<div class="descr"> <a name="details"></a>
<p>QML is a declarative language designed to describe the user interface of a program: both what it looks like, and how it behaves. In QML, a user interface is specified as a tree of objects with properties.</p>
<p>This introduction is meant for those with little or no programming experience. JavaScript is used as a scripting language in QML, so you may want to learn a bit more about it (see the <a href="https://developer.mozilla.org/en/JavaScript/Guide">Javascript Guide</a>) before diving deeper into QML. It's also helpful to have a basic understanding of other web technologies like HTML and CSS, but it's not required.</p>
<a name="basic-qml-syntax"></a>
<h2>Basic QML Syntax</h2>
<p>QML looks like this:</p>
<pre class="qml"> import QtQuick 1.0
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">width</span>: <span class="number">200</span>
<span class="name">height</span>: <span class="number">200</span>
<span class="name">color</span>: <span class="string">"blue"</span>
<span class="type"><a href="qml-image.html">Image</a></span> {
<span class="name">source</span>: <span class="string">"pics/logo.png"</span>
<span class="name">anchors</span>.centerIn: <span class="name">parent</span>
}
}</pre>
<p>Here we create two objects, a <a href="qml-rectangle.html">Rectangle</a> object and its child <a href="qml-image.html">Image</a> object. Objects are specified by their type, followed by a pair of braces in between which additional data can be defined for the object, such as its property values and any child objects.</p>
<p>Properties are specified with a <tt>property: value</tt> syntax. In the above example, we can see the <a href="qml-image.html">Image</a> object has a property named <tt>source</tt>, which has been assigned the value <tt>"pics/logo.png"</tt>. The property and its value are separated by a colon.</p>
<p>Properties can be specified one-per-line:</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">width</span>: <span class="number">100</span>
<span class="name">height</span>: <span class="number">100</span>
}</pre>
<p>or you can put multiple properties on a single line:</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> { <span class="name">width</span>: <span class="number">100</span>; <span class="name">height</span>: <span class="number">100</span> }</pre>
<p>When multiple property/value pairs are specified on a single line, they must be separated by a semicolon.</p>
<p>The <tt>import</tt> statement imports the <tt>QtQuick</tt> <a href="qdeclarativemodules.html#qml-modules">module</a>, which contains all of the standard <a href="qdeclarativeelements.html">QML Elements</a>. Without this import statement, the <a href="qml-rectangle.html">Rectangle</a> and <a href="qml-image.html">Image</a> elements would not be available.</p>
<a name="comments"></a>
<h2>Comments</h2>
<p>Commenting in QML is similar to JavaScript.</p>
<ul>
<li>Single line comments start with // and finish at the end of the line.</li>
<li>Multiline comments start with /* and finish with */</li>
</ul>
<pre class="qml"> <span class="type"><a href="qml-text.html">Text</a></span> {
<span class="name">text</span>: <span class="string">"Hello world!"</span> <span class="comment">//a basic greeting</span>
<span class="comment">/*
We want this text to stand out from the rest so
we give it a large size and different font.
*/</span>
<span class="name">font</span>.family: <span class="string">"Helvetica"</span>
<span class="name">font</span>.pointSize: <span class="number">24</span>
}</pre>
<p>Comments are ignored by the engine. They are useful for explaining what you are doing; for referring back to at a later date, or for others reading your QML files.</p>
<p>Comments can also be used to prevent the execution of code, which is sometimes useful for tracking down problems.</p>
<pre class="qml"> <span class="type"><a href="qml-text.html">Text</a></span> {
<span class="name">text</span>: <span class="string">"Hello world!"</span>
<span class="comment">//opacity: 0.5</span>
}</pre>
<p>In the above example, the <a href="qml-text.html">Text</a> object will have normal opacity, since the line opacity: 0.5 has been turned into a comment.</p>
<a name="object-identifiers"></a>
<h2>Object Identifiers</h2>
<p>Each object can be given a special <i>id</i> value that allows the object to be identified and referred to by other objects.</p>
<p>For example, below we have two <a href="qml-text.html">Text</a> objects. The first <a href="qml-text.html">Text</a> object has an <tt>id</tt> value of "text1". The second <a href="qml-text.html">Text</a> object can now set its own <tt>text</tt> property value to be the same as that of the first object, by referring to <tt>text1.text</tt>:</p>
<pre class="qml"> import QtQuick 1.0
<span class="type"><a href="qml-row.html">Row</a></span> {
<span class="type"><a href="qml-text.html">Text</a></span> {
<span class="name">id</span>: <span class="name">text1</span>
<span class="name">text</span>: <span class="string">"Hello World"</span>
}
<span class="type"><a href="qml-text.html">Text</a></span> { <span class="name">text</span>: <span class="name">text1</span>.<span class="name">text</span> }
}</pre>
<p>An object can be referred to by its <tt>id</tt> from anywhere within the <a href="qdeclarativedocuments.html">component</a> in which it is declared. Therefore, an <tt>id</tt> value must always be unique within a single component.</p>
<p>The <tt>id</tt> value is a special value for a QML object and should not be thought of as an ordinary object property; for example, it is not possible to access <tt>text1.id</tt> in the above example. Once an object is created, its <tt>id</tt> cannot be changed.</p>
<p>Note that an <tt>id</tt> must begin with a lower-case letter or an underscore, and cannot contain characters other than letters, numbers and underscores.</p>
<a name="expressions"></a>
<h2>Expressions</h2>
<p>JavaScript expressions can be used to assign property values. For example:</p>
<pre class="qml"> <span class="type"><a href="qml-item.html">Item</a></span> {
<span class="name">width</span>: <span class="number">100</span> <span class="operator">*</span> <span class="number">3</span>
<span class="name">height</span>: <span class="number">50</span> <span class="operator">+</span> <span class="number">22</span>
}</pre>
<p>These expressions can include references to other objects and properties, in which case a <a href="propertybinding.html">binding</a> is established: when the value of the expression changes, the property to which the expression is assigned is automatically updated to the new value. For example:</p>
<pre class="qml"> <span class="type"><a href="qml-item.html">Item</a></span> {
<span class="name">width</span>: <span class="number">300</span>
<span class="name">height</span>: <span class="number">300</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="operator">-</span> <span class="number">50</span>
<span class="name">height</span>: <span class="number">100</span>
<span class="name">color</span>: <span class="string">"yellow"</span>
}
}</pre>
<p>Here, the <a href="qml-rectangle.html">Rectangle</a> object's <tt>width</tt> property is set relative to the width of its parent. Whenever the parent's width changes, the width of the <a href="qml-rectangle.html">Rectangle</a> is automatically updated.</p>
<a name="properties"></a>
<h2>Properties</h2>
<a name="intro-properties"></a><a name="basic-property-types"></a>
<h3>Basic Property Types</h3>
<p>QML supports properties of many types (see <a href="qdeclarativebasictypes.html">QML Basic Types</a>). The basic types include <tt>int</tt>, <tt>real</tt>, <tt>bool</tt>, <tt>string</tt> and <tt>color</tt>.</p>
<pre class="qml"> <span class="type"><a href="qml-item.html">Item</a></span> {
<span class="name">x</span>: <span class="number">10.5</span> <span class="comment">// a 'real' property</span>
<span class="name">state</span>: <span class="string">"details"</span> <span class="comment">// a 'string' property</span>
<span class="name">focus</span>: <span class="number">true</span> <span class="comment">// a 'bool' property</span>
<span class="comment">// ...</span>
}</pre>
<p>QML properties are what is known as <i>type-safe</i>. That is, they only allow you to assign a value that matches the property type. For example, the <tt>x</tt> property of item is a real, and if you try to assign a string to it you will get an error.</p>
<pre class="cpp"> Item {
x: "hello" // illegal!
}</pre>
<p>Note that with the exception of <a href="propertybinding.html#attached-properties">Attached Properties</a>, properties always begin with a lowercase letter.</p>
<a name="property-change-notifications"></a>
<h3>Property Change Notifications</h3>
<p>When a property changes value, it can send a signal to notify others of this change.</p>
<p>To receive these signals, simply create a <i>signal handler</i> named with an <tt>on<Property>Changed</tt> syntax. For example, the <a href="qml-rectangle.html">Rectangle</a> element has <a href="qml-item.html#width-prop">width</a> and <a href="qml-rectangle.html#color-prop">color</a> properties. Below, we have a <a href="qml-rectangle.html">Rectangle</a> object that has defined two signal handlers, <tt>onWidthChanged</tt> and <tt>onColorChanged</tt>, which will automaticallly be called whenever these properties are modified:</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">width</span>: <span class="number">100</span>; <span class="name">height</span>: <span class="number">100</span>
<span class="name">onWidthChanged</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"Width has changed to:"</span>, <span class="name">width</span>)
<span class="name">onColorChanged</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"Color has changed to:"</span>, <span class="name">color</span>)
}</pre>
<p>Signal handlers are explained further <a href="#signal-handlers">below</a>.</p>
<a name="list-properties"></a>
<h3>List properties</h3>
<p>List properties look like this:</p>
<pre class="qml"> <span class="type"><a href="qml-item.html">Item</a></span> {
<span class="name">children</span>: [
<span class="type"><a href="qml-image.html">Image</a></span> {},
<span class="type"><a href="qml-text.html">Text</a></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 can omit the square brackets:</p>
<pre class="qml"> <span class="type"><a href="qml-image.html">Image</a></span> {
<span class="name">children</span>: <span class="name">Rectangle</span> {}
}</pre>
<p>Items in the list can be accessed by index. See the <a href="qml-list.html">list type</a> documentation for more details about list properties and their available operations.</p>
<a name="default-properties"></a>
<h3>Default Properties</h3>
<p>Each object type can specify one of its list or object properties as its default property. If a property has been declared as the default property, the property tag can be omitted.</p>
<p>For example this code:</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> {}
]
}</pre>
<p>can be simplified to:</p>
<pre class="qml"> <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>because <tt>changes</tt> is the default property of the <tt>State</tt> type.</p>
<a name="grouped-properties"></a>
<h3>Grouped Properties</h3>
<a name="dot-properties"></a><p>In some cases properties form a logical group and use a 'dot' or grouped notation to show this.</p>
<p>Grouped properties can be written like this:</p>
<pre class="qml"> <span class="type"><a href="qml-text.html">Text</a></span> {
<span class="name">font</span>.pixelSize: <span class="number">12</span>
<span class="name">font</span>.bold: <span class="number">true</span>
}</pre>
<p>or like this:</p>
<pre class="qml"> <span class="type"><a href="qml-text.html">Text</a></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="attached-properties"></a>
<h3>Attached Properties</h3>
<a name="attached-properties"></a><p>Some objects attach properties to another object. Attached Properties are of the form <i>Type.property</i> where <i>Type</i> is the type of the element that attaches <i>property</i>.</p>
<p>For example, the <a href="qml-listview.html">ListView</a> element attaches the <i>ListView.isCurrentItem</i> property to each delegate it creates:</p>
<pre class="qml"> <span class="type"><a href="qml-component.html">Component</a></span> {
<span class="name">id</span>: <span class="name">myDelegate</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>
}
}</pre>
<pre class="qml"> <span class="type"><a href="qml-listview.html">ListView</a></span> {
<span class="name">delegate</span>: <span class="name">myDelegate</span>
}</pre>
<p>Another example of attached properties is the <a href="qml-keys.html">Keys</a> element which attaches properties for handling key presses to any visual Item, for example:</p>
<pre class="qml"> <span class="type"><a href="qml-item.html">Item</a></span> {
<span class="name">focus</span>: <span class="number">true</span>
<span class="name">Keys</span>.onSelectPressed: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"Selected"</span>)
}</pre>
<a name="signal-handlers"></a>
<h2>Signal Handlers</h2>
<p>Signal handlers allow JavaScript code to be executed in response to an event. For example, the <a href="qml-mousearea.html">MouseArea</a> element has an <a href="qml-mousearea.html#onClicked-signal">onClicked</a> handler that can be used to respond to a mouse click. Below, we use this handler to print a message whenever the mouse is clicked:</p>
<pre class="qml"> <span class="type"><a href="qml-item.html">Item</a></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-mousearea.html">MouseArea</a></span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">onClicked</span>: {
<span class="name">console</span>.<span class="name">log</span>(<span class="string">"mouse button clicked"</span>)
}
}
}</pre>
<p>All signal handlers begin with <i>"on"</i>.</p>
<p>Some signal handlers include an optional parameter. For example the <a href="qml-mousearea.html">MouseArea</a> <a href="qml-mousearea.html#onPressed-signal">onPressed</a> signal handler has a <tt>mouse</tt> parameter that contains information about the mouse press. This parameter can be referred to in the JavaScript code, as below:</p>
<pre class="qml"> <span class="type"><a href="qml-mousearea.html">MouseArea</a></span> {
<span class="name">acceptedButtons</span>: <span class="name">Qt</span>.<span class="name">LeftButton</span> <span class="operator">|</span> <span class="name">Qt</span>.<span class="name">RightButton</span>
<span class="name">onPressed</span>: {
<span class="keyword">if</span> (<span class="name">mouse</span>.<span class="name">button</span> <span class="operator">==</span> <span class="name">Qt</span>.<span class="name">RightButton</span>)
<span class="name">console</span>.<span class="name">log</span>(<span class="string">"Right mouse button pressed"</span>)
}
}</pre>
</div>
<!-- @@@qdeclarativeintroduction.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>
