<?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" />
<!-- qmlreusablecomponents.qdoc -->
<title>Qt 4.8: Importing Reusable Components</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>Importing Reusable Components</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="qmlevents.html" />
<link rel="next" href="qdeclarativestates.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="qmlevents.html">Signal and Handler Event System</a>
<a class="nextPage" href="qdeclarativestates.html">States</a>
</p><p/>
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#defining-new-components">Defining New Components</a></li>
<li class="level1"><a href="#loading-a-component">Loading a Component</a></li>
<li class="level2"><a href="#importing-a-component">Importing a Component</a></li>
<li class="level2"><a href="#loading-an-inline-component">Loading an Inline Component</a></li>
<li class="level1"><a href="#component-properties">Component Properties</a></li>
<li class="level1"><a href="#top-level-component">Top-Level Component</a></li>
</ul>
</div>
<h1 class="title">Importing Reusable Components</h1>
<span class="subtitle"></span>
<!-- $$$qmlreusablecomponents.html-description -->
<div class="descr"> <a name="details"></a>
<p>A <i>component</i> is an instantiable QML definition, typically contained in a <tt>.qml</tt> file. For instance, a Button <i>component</i> may be defined in <tt>Button.qml</tt>. The QML runtime may instantiate this Button component to create Button <i>objects</i>. Alternatively, a component may be defined inside a <a href="qml-component.html">Component</a> element.</p>
<p>Moreover, the Button definition may also contain other components. A Button component could use a Text element for its label and other components to implement its functions. Compounding components to form new components (and effectively new interfaces) is the emphasis in QML.</p>
<a name="qml-define-components"></a><a name="defining-new-components"></a>
<h2>Defining New Components</h2>
<p>Any snippet of QML code may become a component, by placing the code in a QML file (extension is <tt>.qml</tt>). A complete Button component that responds to user input may be in a Button.qml file.</p>
<pre class="qml"> <span class="comment">//contents of Button.qml</span>
import QtQuick 1.0
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">button</span>
<span class="name">width</span>: <span class="number">145</span>; <span class="name">height</span>: <span class="number">60</span>
<span class="name">color</span>: <span class="string">"blue"</span>
<span class="name">smooth</span>: <span class="number">true</span>; <span class="name">radius</span>: <span class="number">9</span>
property <span class="type">alias</span> <span class="name">text</span>: <span class="name">label</span>.<span class="name">text</span>
<span class="type">border</span> {<span class="name">color</span>: <span class="string">"#B9C5D0"</span>; <span class="name">width</span>: <span class="number">1</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">color</span>: <span class="string">"#CFF7FF"</span>; <span class="name">position</span>: <span class="number">0.0</span>}
<span class="type"><a href="qml-gradientstop.html">GradientStop</a></span> {<span class="name">color</span>: <span class="string">"#99C0E5"</span>; <span class="name">position</span>: <span class="number">0.57</span>}
<span class="type"><a href="qml-gradientstop.html">GradientStop</a></span> {<span class="name">color</span>: <span class="string">"#719FCB"</span>; <span class="name">position</span>: <span class="number">0.9</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">anchors</span>.centerIn: <span class="name">parent</span>
<span class="name">text</span>: <span class="string">"Click Me!"</span>
<span class="name">font</span>.pointSize: <span class="number">12</span>
<span class="name">color</span>: <span class="string">"blue"</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="name">text</span> <span class="operator">+</span> <span class="string">" clicked"</span>)
}
}</pre>
<p>Alternatively, a <a href="qml-component.html">Component</a> element may encapsulate a QML object to form a component.</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="type"><a href="qml-component.html">Component</a></span> {
<span class="name">id</span>: <span class="name">inlinecomponent</span>
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">display</span>
<span class="name">width</span>: <span class="number">50</span>; <span class="name">height</span>: <span class="number">50</span>
<span class="name">color</span>: <span class="string">"blue"</span>
}
}
}</pre>
<a name="qml-loading-components"></a><a name="loading-a-component"></a>
<h2>Loading a Component</h2>
<p>The initialization of inline components is different from loading a component from a <tt>.qml</tt> file.</p>
<a name="importing-a-component"></a>
<h3>Importing a Component</h3>
<p>A component defined in a <tt>.qml</tt> file is directly usable by declaring the name of the component. For example, a button defined in <tt>Button.qml</tt> is created by declaring a <tt>Button</tt>. The button is defined in the <a href="#qml-define-components">Defining New Components</a> section.</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">175</span>; <span class="name">height</span>: <span class="number">350</span>
<span class="name">color</span>: <span class="string">"lightgrey"</span>
<span class="type"><a href="qml-column.html">Column</a></span> {
<span class="name">anchors</span>.centerIn: <span class="name">parent</span>
<span class="name">spacing</span>: <span class="number">15</span>
<span class="type">Button</span> {}
<span class="type">Button</span> {<span class="name">text</span>: <span class="string">"Me Too!"</span>}
<span class="type">Button</span> {<span class="name">text</span>: <span class="string">"Me Three!"</span>}
}
}</pre>
<p>Note that the component name, <tt>Button</tt>, matches the QML filename, <tt>Button.qml</tt>. Also, the first character is in upper case. Matching the names allow components in the same directory to be in the direct import path of the application.</p>
<p>For flexibility, a <tt>qmldir</tt> file is for dictating which additional components, plugins, or directories should be imported. By using a <tt>qmldir</tt> file, component names do not need to match the filenames. The <tt>qmldir</tt> file should, however, be in an imported path.</p>
<pre class="cpp"> Button <span class="operator">.</span><span class="operator">/</span>Button<span class="operator">.</span>qml
FocusButton <span class="operator">.</span><span class="operator">/</span>focusbutton<span class="operator">.</span>qml</pre>
<a name="loading-an-inline-component"></a>
<h3>Loading an Inline Component</h3>
<p>A consequence of inline components is that initialization may be deferred or delayed. A component may be created during a <a href="qml-mousearea.html">MouseArea</a> event or by using a <a href="qml-loader.html">Loader</a> element. The component can create an object, which is addressable in a similar way as an <a href="propertybinding.html#qml-id-property">id property</a>. Thus, the created object may have its bindings set and read like a normal QML object.</p>
<pre class="qml"> <span class="type"><a href="qml-component.html">Component</a></span> {
<span class="name">id</span>: <span class="name">inlinecomponent</span>
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">display</span>
<span class="name">width</span>: <span class="number">50</span>; <span class="name">height</span>: <span class="number">50</span>
<span class="name">color</span>: <span class="string">"blue"</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">inlinecomponent</span>.<span class="name">createObject</span>(<span class="name">parent</span>)
var <span class="name">second</span> = <span class="name">inlinecomponent</span>.<span class="name">createObject</span>(<span class="name">parent</span>)
var <span class="name">third</span> = <span class="name">inlinecomponent</span>.<span class="name">createObject</span>(<span class="name">parent</span>)
<span class="name">third</span>.<span class="name">x</span> <span class="operator">=</span> <span class="name">second</span>.<span class="name">width</span> <span class="operator">+</span> <span class="number">10</span>
<span class="name">third</span>.<span class="name">color</span> <span class="operator">=</span> <span class="string">"red"</span>
}
}</pre>
<a name="qml-component-properties"></a><a name="component-properties"></a>
<h2>Component Properties</h2>
<p>Initializing a component, either from a .qml file or initializing an inline component, have several properties to facilitate component execution. Specifically, there are <a href="propertybinding.html#attached-properties">attached properties</a> and <a href="propertybinding.html#attached-signalhandlers">attached signal handlers</a> for setting properties during the lifetime of a component.</p>
<p>The <tt>Component.onCompleted</tt> attached signal handler is called when the component completes initialization. It is useful for executing any commands after component initialization. Similarly, the <tt>Component.onDestruction</tt> signal handler executes when the component finishes destruction.</p>
<a name="qml-top-level"></a><a name="top-level-component"></a>
<h2>Top-Level Component</h2>
<p>Choosing the <i>top-level</i> or the <i>root</i> object of components is an important design aspect because the top-level object dictates which properties are accessible outside the component. Some elements are not visual elements and will not have visual properties exposed outside the component. Likewise, some elements add functionality that are not available to visual elements.</p>
<p>Consider the Button component from the <a href="#qml-define-components">Defining New Components</a> section; it's top-level object is a <a href="qml-rectangle.html">Rectangle</a>. When imported, the Button component will possess the Rectangle's properties, methods, signals, and any custom properties.</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="comment">//...</span>
<span class="name">width</span>: <span class="number">145</span>; <span class="name">height</span>: <span class="number">60</span>
<span class="name">color</span>: <span class="string">"blue"</span>
<span class="name">smooth</span>: <span class="number">true</span>; <span class="name">radius</span>: <span class="number">9</span>
property <span class="type">alias</span> <span class="name">text</span>: <span class="name">label</span>.<span class="name">text</span>
<span class="comment">//...</span>
}</pre>
<p>The Button's <tt>text</tt> alias is accessible from outside the component as well as the Rectangle's visual properties and signals such as <tt>x</tt>, <tt>y</tt>, <tt>anchors</tt>, and <tt>states</tt>.</p>
<p>Alternatively, we may choose a <a href="qdeclarativefocus.html">FocusScope</a> as our top-level object. The <a href="qml-focusscope.html">FocusScope</a> element manage keyboard focus for its children which is beneficial for certain types of interfaces. However, since <tt>FocusScopes</tt> are not visual elements, the visual properties of its child need to be exposed.</p>
<pre class="qml"> <span class="comment">//contents of focusbutton.qml</span>
import QtQuick 1.0
<span class="type"><a href="qml-focusscope.html">FocusScope</a></span> {
<span class="comment">//FocusScope needs to bind to visual properties of the children</span>
property <span class="type">alias</span> <span class="name">color</span>: <span class="name">button</span>.<span class="name">color</span>
<span class="name">x</span>: <span class="name">button</span>.<span class="name">x</span>; <span class="name">y</span>: <span class="name">button</span>.<span class="name">y</span>
<span class="name">width</span>: <span class="name">button</span>.<span class="name">width</span>; <span class="name">height</span>: <span class="name">button</span>.<span class="name">height</span>
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">button</span>
<span class="name">width</span>: <span class="number">145</span>; <span class="name">height</span>: <span class="number">60</span>
<span class="name">color</span>: <span class="string">"blue"</span>
<span class="name">smooth</span>: <span class="number">true</span>; <span class="name">radius</span>: <span class="number">9</span>
property <span class="type">alias</span> <span class="name">text</span>: <span class="name">label</span>.<span class="name">text</span>
<span class="type">border</span> {<span class="name">color</span>: <span class="string">"#B9C5D0"</span>; <span class="name">width</span>: <span class="number">1</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">color</span>: <span class="string">"#CFF7FF"</span>; <span class="name">position</span>: <span class="number">0.0</span>}
<span class="type"><a href="qml-gradientstop.html">GradientStop</a></span> {<span class="name">color</span>: <span class="string">"#99C0E5"</span>; <span class="name">position</span>: <span class="number">0.57</span>}
<span class="type"><a href="qml-gradientstop.html">GradientStop</a></span> {<span class="name">color</span>: <span class="string">"#719FCB"</span>; <span class="name">position</span>: <span class="number">0.9</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">anchors</span>.centerIn: <span class="name">parent</span>
<span class="name">text</span>: <span class="string">"Click Me!"</span>
<span class="name">font</span>.pointSize: <span class="number">12</span>
<span class="name">color</span>: <span class="string">"blue"</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="name">text</span> <span class="operator">+</span> <span class="string">" clicked"</span>)
}
}
}</pre>
</div>
<!-- @@@qmlreusablecomponents.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="qmlevents.html">Signal and Handler Event System</a>
<a class="nextPage" href="qdeclarativestates.html">States</a>
</p>
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2015 The Qt Company Ltd.
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>
Qt and respective logos are trademarks of The Qt Company Ltd
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>
