<?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" />
<!-- qdeclarativedocument.qdoc -->
<title>Qt 4.8: QML Documents</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 Documents</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="#documents-as-component-definitions">Documents as Component Definitions</a></li>
<li class="level1"><a href="#inline-components">Inline Components</a></li>
</ul>
</div>
<h1 class="title">QML Documents</h1>
<span class="subtitle"></span>
<!-- $$$qdeclarativedocuments.html-description -->
<div class="descr"> <a name="details"></a>
<p>A QML document is a block of QML source code. QML documents generally correspond to files stored on a disk or at a location on a network, but they can also be constructed directly from text data.</p>
<p>Here is a simple QML document:</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">240</span>; <span class="name">height</span>: <span class="number">320</span>;
<span class="name">resources</span>: [
<span class="type"><a href="qml-component.html">Component</a></span> {
<span class="name">id</span>: <span class="name">contactDelegate</span>
<span class="type"><a href="qml-text.html">Text</a></span> {
<span class="name">text</span>: <span class="name">modelData</span>.<span class="name">firstName</span> <span class="operator">+</span> <span class="string">" "</span> <span class="operator">+</span> <span class="name">modelData</span>.<span class="name">lastName</span>
}
}
]
<span class="type"><a href="qml-listview.html">ListView</a></span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">model</span>: <span class="name">contactModel</span>
<span class="name">delegate</span>: <span class="name">contactDelegate</span>
}
}</pre>
<p>QML documents are always encoded in UTF-8 format.</p>
<p>A QML document always begins with one or more import statements. To prevent elements introduced in later versions from affecting existing QML programs, the element types available within a document are controlled by the imported QML <a href="qdeclarativemodules.html">Modules</a>. That is, QML is a <i>versioned</i> language.</p>
<p>Syntactically a QML document is self contained; QML does <i>not</i> have a preprocessor that modifies the document prior to presentation to the QML runtime. <tt>import</tt> statements do not "include" code in the document, but instead instruct the QML runtime on how to resolve type references found in the document. Any type reference present in a QML document - such as <tt>Rectangle</tt> and <tt>ListView</tt> - including those made within an <a href="qdeclarativejavascript.html#inline-javascript">JavaScript block</a> or <a href="propertybinding.html">Property Binding</a>s, are <i>resolved</i> based exclusively on the import statements. QML does not import any modules by default, so at least one <tt>import</tt> statement must be present or no elements will be available!</p>
<p>Each <tt>id</tt> value in a QML document must be unique within that document. They do not need to be unique across different documents as id values are resolved according to the document scope.</p>
<a name="documents-as-component-definitions"></a>
<h2>Documents as Component Definitions</h2>
<p>A QML document defines a single, top-level <a href="qdeclarativecomponent.html">QML component</a>. A QML component is a template that is interpreted by the QML runtime to create an object with some predefined behaviour. As it is a template, a single QML component can be "run" multiple times to produce several objects, each of which are said to be <i>instances</i> of the component.</p>
<p>Once created, instances are not dependent on the component that created them, so they can operate on independent data. Here is an example of a simple "Button" component (defined in a <tt>Button.qml</tt> file) that is instantiated four times by <tt>application.qml</tt>. Each instance is created with a different value for its <tt>text</tt> property:</p>
<table class="generic">
<tr valign="top" class="odd"><td >Button.qml</td><td >application.qml</td></tr>
<tr valign="top" class="even"><td ><pre class="qml"> import QtQuick 1.0
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
property <span class="type">alias</span> <span class="name">text</span>: <span class="name">textItem</span>.<span class="name">text</span>
<span class="name">width</span>: <span class="number">100</span>; <span class="name">height</span>: <span class="number">30</span>
<span class="name">border</span>.width: <span class="number">1</span>
<span class="name">radius</span>: <span class="number">5</span>
<span class="name">smooth</span>: <span class="number">true</span>
<span class="name">gradient</span>: <span class="name">Gradient</span> {
<span class="type"><a href="qml-gradientstop.html">GradientStop</a></span> { <span class="name">position</span>: <span class="number">0.0</span>; <span class="name">color</span>: <span class="string">"darkGray"</span> }
<span class="type"><a href="qml-gradientstop.html">GradientStop</a></span> { <span class="name">position</span>: <span class="number">0.5</span>; <span class="name">color</span>: <span class="string">"black"</span> }
<span class="type"><a href="qml-gradientstop.html">GradientStop</a></span> { <span class="name">position</span>: <span class="number">1.0</span>; <span class="name">color</span>: <span class="string">"darkGray"</span> }
}
<span class="type"><a href="qml-text.html">Text</a></span> {
<span class="name">id</span>: <span class="name">textItem</span>
<span class="name">anchors</span>.centerIn: <span class="name">parent</span>
<span class="name">font</span>.pointSize: <span class="number">20</span>
<span class="name">color</span>: <span class="string">"white"</span>
}
}</pre>
</td><td ><pre class="qml"> import QtQuick 1.0
<span class="type"><a href="qml-column.html">Column</a></span> {
<span class="name">spacing</span>: <span class="number">10</span>
<span class="type">Button</span> { <span class="name">text</span>: <span class="string">"Apple"</span> }
<span class="type">Button</span> { <span class="name">text</span>: <span class="string">"Orange"</span> }
<span class="type">Button</span> { <span class="name">text</span>: <span class="string">"Pear"</span> }
<span class="type">Button</span> { <span class="name">text</span>: <span class="string">"Grape"</span> }
}</pre>
<p class="centerAlign"><img src="images/anatomy-component.png" alt="" /></p></td></tr>
</table>
<p>Any snippet of QML code can become a component, just by placing it in the file "<Name>.qml" where <Name> is the new element name, and begins with an <b>uppercase</b> letter. Note that the case of all characters in the <Name> are significant on some filesystems, notably UNIX filesystems. It is recommended that the case of the filename matches the case of the component name in QML exactly, regardless of the platform the QML will be deployed to.</p>
<p>These QML component files automatically become available as new QML element types to other QML components and applications in the same directory.</p>
<a name="inline-components"></a>
<h2>Inline Components</h2>
<p>In addition to the top-level component that all QML documents define, and any reusable components placed in separate files, documents may also include <i>inline</i> components. Inline components are declared using the <a href="qml-component.html">Component</a> element, as can be seen in the first example above. Inline components share all the characteristics of regular top-level components and use the same <tt>import</tt> list as their containing QML document. Components are one of the most basic building blocks in QML, and are frequently used as "factories" by other elements. For example, the <a href="qml-listview.html">ListView</a> element uses the <tt>delegate</tt> component as the template for instantiating list items - each list item is just a new instance of the component with the item specific data set appropriately.</p>
<p>Like other <a href="qdeclarativeelements.html">QML Elements</a>, the <a href="qml-component.html">Component</a> element is an object and must be assigned to a property. <a href="qml-component.html">Component</a> objects may also have an object id. In the first example on this page, the inline component is added to the <a href="qml-rectangle.html">Rectangle</a>'s <tt>resources</tt> list, and then <a href="propertybinding.html">Property Binding</a> is used to assign the <a href="qml-component.html">Component</a> to the <a href="qml-listview.html">ListView</a>'s <tt>delegate</tt> property. While using property binding allows the <a href="qml-component.html">Component</a> object to be shared (for example, if the QML document contained multiple <a href="qml-listview.html">ListView</a>'s with the same delegate), in this case the <a href="qml-component.html">Component</a> could have been assigned directly to the <a href="qml-listview.html">ListView</a>'s <tt>delegate</tt>. The QML language even contains a syntactic optimization when assigning directly to a component property for this case where it will automatically insert the <a href="qml-component.html">Component</a> tag.</p>
<p>These final two examples are behaviorally identical to the original document.</p>
<table class="generic">
<tr valign="top" class="odd"><td ><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">240</span>; <span class="name">height</span>: <span class="number">320</span>;
<span class="type"><a href="qml-listview.html">ListView</a></span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">model</span>: <span class="name">contactModel</span>
<span class="name">delegate</span>: <span class="name">Component</span> {
<span class="type"><a href="qml-text.html">Text</a></span> {
<span class="name">text</span>: <span class="name">modelData</span>.<span class="name">firstName</span> <span class="operator">+</span> <span class="string">" "</span> <span class="operator">+</span> <span class="name">modelData</span>.<span class="name">lastName</span>
}
}
}
}</pre>
</td><td ><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">240</span>; <span class="name">height</span>: <span class="number">320</span>;
<span class="type"><a href="qml-listview.html">ListView</a></span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">model</span>: <span class="name">contactModel</span>
<span class="name">delegate</span>: <span class="name">Text</span> {
<span class="name">text</span>: <span class="name">modelData</span>.<span class="name">firstName</span> <span class="operator">+</span> <span class="string">" "</span> <span class="operator">+</span> <span class="name">modelData</span>.<span class="name">lastName</span>
}
}
}</pre>
</td></tr>
</table>
</div>
<p><b>See also </b><a href="qdeclarativecomponent.html">QDeclarativeComponent</a>.</p>
<!-- @@@qdeclarativedocuments.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>
