1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
<?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" />
<!-- tutorial.qdoc -->
<title>Qt 4.8: QML Tutorial 2 - QML Components</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="content">
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
</div>
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li>QML Tutorial 2 - QML Components</li>
</ul>
</div>
</div>
<div class="content mainContent">
<link rel="prev" href="qml-tutorial1.html" />
<link rel="next" href="qml-tutorial3.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="qml-tutorial1.html">QML Tutorial 1 - Basic Types</a>
<a class="nextPage" href="qml-tutorial3.html">QML Tutorial 3 - States and Transitions</a>
</p><p/>
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#walkthrough">Walkthrough</a></li>
<li class="level2"><a href="#the-cell-component">The Cell Component</a></li>
<li class="level2"><a href="#the-main-qml-file">The main QML file</a></li>
</ul>
</div>
<h1 class="title">QML Tutorial 2 - QML Components</h1>
<span class="subtitle"></span>
<!-- $$$qml-tutorial2.html-description -->
<div class="descr"> <a name="details"></a>
<p>This chapter adds a color picker to change the color of the text.</p>
<p class="centerAlign"><img src="images/declarative-tutorial2.png" alt="" /></p><p>Our color picker is made of six cells with different colors. To avoid writing the same code multiple times for each cell, we create a new <tt>Cell</tt> component. A component provides a way of defining a new type that we can re-use in other QML files. A QML component is like a black-box and interacts with the outside world through properties, signals and functions and is generally defined in its own QML file. (For more details, see <a href="qmlreusablecomponents.html#defining-new-components">Defining New Components</a>). The component's filename must always start with a capital letter.</p>
<p>Here is the QML code for <tt>Cell.qml</tt>:</p>
<pre class="qml"> import QtQuick 1.0
<span class="type"><a href="qml-item.html">Item</a></span> {
<span class="name">id</span>: <span class="name">container</span>
property <span class="type">alias</span> <span class="name">cellColor</span>: <span class="name">rectangle</span>.<span class="name">color</span>
signal <span class="type">clicked</span>(color cellColor)
<span class="name">width</span>: <span class="number">40</span>; <span class="name">height</span>: <span class="number">25</span>
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">rectangle</span>
<span class="name">border</span>.color: <span class="string">"white"</span>
<span class="name">anchors</span>.fill: <span class="name">parent</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">container</span>.<span class="name">clicked</span>(<span class="name">container</span>.<span class="name">cellColor</span>)
}
}</pre>
<a name="walkthrough"></a>
<h2>Walkthrough</h2>
<a name="the-cell-component"></a>
<h3>The Cell Component</h3>
<pre class="qml"> <span class="type"><a href="qml-item.html">Item</a></span> {
<span class="name">id</span>: <span class="name">container</span>
property <span class="type">alias</span> <span class="name">cellColor</span>: <span class="name">rectangle</span>.<span class="name">color</span>
signal <span class="type">clicked</span>(color cellColor)
<span class="name">width</span>: <span class="number">40</span>; <span class="name">height</span>: <span class="number">25</span></pre>
<p>The root element of our component is an <a href="qml-item.html">Item</a> with the <tt>id</tt> <i>container</i>. An <a href="qml-item.html">Item</a> is the most basic visual element in QML and is often used as a container for other elements.</p>
<pre class="qml"> property <span class="type">alias</span> <span class="name">cellColor</span>: <span class="name">rectangle</span>.<span class="name">color</span></pre>
<p>We declare a <tt>cellColor</tt> property. This property is accessible from <i>outside</i> our component, this allows us to instantiate the cells with different colors. This property is just an alias to an existing property - the color of the rectangle that compose the cell (see <a href="propertybinding.html">Property Binding</a>).</p>
<pre class="qml"> signal <span class="type">clicked</span>(color cellColor)</pre>
<p>We want our component to also have a signal that we call <i>clicked</i> with a <i>cellColor</i> parameter of type <i>color</i>. We will use this signal to change the color of the text in the main QML file later.</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">border</span>.color: <span class="string">"white"</span>
<span class="name">anchors</span>.fill: <span class="name">parent</span>
}</pre>
<p>Our cell component is basically a colored rectangle with the <tt>id</tt> <i>rectangle</i>.</p>
<p>The <tt>anchors.fill</tt> property is a convenient way to set the size of an element. In this case the rectangle will have the same size as its parent (see <a href="qml-anchor-layout.html#anchor-layout">Anchor-Based Layout</a>).</p>
<pre class="qml"> <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">container</span>.<span class="name">clicked</span>(<span class="name">container</span>.<span class="name">cellColor</span>)
}</pre>
<p>In order to change the color of the text when clicking on a cell, we create a <a href="qml-mousearea.html">MouseArea</a> element with the same size as its parent.</p>
<p>A <a href="qml-mousearea.html">MouseArea</a> defines a signal called <i>clicked</i>. When this signal is triggered we want to emit our own <i>clicked</i> signal with the color as parameter.</p>
<a name="the-main-qml-file"></a>
<h3>The main QML file</h3>
<p>In our main QML file, we use our <tt>Cell</tt> component to create the color picker:</p>
<pre class="qml"> import QtQuick 1.0
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">page</span>
<span class="name">width</span>: <span class="number">500</span>; <span class="name">height</span>: <span class="number">200</span>
<span class="name">color</span>: <span class="string">"lightgray"</span>
<span class="type"><a href="qml-text.html">Text</a></span> {
<span class="name">id</span>: <span class="name">helloText</span>
<span class="name">text</span>: <span class="string">"Hello world!"</span>
<span class="name">y</span>: <span class="number">30</span>
<span class="name">anchors</span>.horizontalCenter: <span class="name">page</span>.<span class="name">horizontalCenter</span>
<span class="name">font</span>.pointSize: <span class="number">24</span>; <span class="name">font</span>.bold: <span class="number">true</span>
}
<span class="type"><a href="qml-grid.html">Grid</a></span> {
<span class="name">id</span>: <span class="name">colorPicker</span>
<span class="name">x</span>: <span class="number">4</span>; <span class="name">anchors</span>.bottom: <span class="name">page</span>.<span class="name">bottom</span>; <span class="name">anchors</span>.bottomMargin: <span class="number">4</span>
<span class="name">rows</span>: <span class="number">2</span>; <span class="name">columns</span>: <span class="number">3</span>; <span class="name">spacing</span>: <span class="number">3</span>
<span class="type">Cell</span> { <span class="name">cellColor</span>: <span class="string">"red"</span>; <span class="name">onClicked</span>: <span class="name">helloText</span>.<span class="name">color</span> <span class="operator">=</span> <span class="name">cellColor</span> }
<span class="type">Cell</span> { <span class="name">cellColor</span>: <span class="string">"green"</span>; <span class="name">onClicked</span>: <span class="name">helloText</span>.<span class="name">color</span> <span class="operator">=</span> <span class="name">cellColor</span> }
<span class="type">Cell</span> { <span class="name">cellColor</span>: <span class="string">"blue"</span>; <span class="name">onClicked</span>: <span class="name">helloText</span>.<span class="name">color</span> <span class="operator">=</span> <span class="name">cellColor</span> }
<span class="type">Cell</span> { <span class="name">cellColor</span>: <span class="string">"yellow"</span>; <span class="name">onClicked</span>: <span class="name">helloText</span>.<span class="name">color</span> <span class="operator">=</span> <span class="name">cellColor</span> }
<span class="type">Cell</span> { <span class="name">cellColor</span>: <span class="string">"steelblue"</span>; <span class="name">onClicked</span>: <span class="name">helloText</span>.<span class="name">color</span> <span class="operator">=</span> <span class="name">cellColor</span> }
<span class="type">Cell</span> { <span class="name">cellColor</span>: <span class="string">"black"</span>; <span class="name">onClicked</span>: <span class="name">helloText</span>.<span class="name">color</span> <span class="operator">=</span> <span class="name">cellColor</span> }
}
}</pre>
<p>We create the color picker by putting 6 cells with different colors in a grid.</p>
<pre class="qml"> <span class="type">Cell</span> { <span class="name">cellColor</span>: <span class="string">"red"</span>; <span class="name">onClicked</span>: <span class="name">helloText</span>.<span class="name">color</span> <span class="operator">=</span> <span class="name">cellColor</span> }</pre>
<p>When the <i>clicked</i> signal of our cell is triggered, we want to set the color of the text to the <i>cellColor</i> passed as a parameter. We can react to any signal of our component through a property of the name <i>'onSignalName'</i> (see <a href="qdeclarativeintroduction.html#signal-handlers">Signal Handlers</a>).</p>
</div>
<!-- @@@qml-tutorial2.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="qml-tutorial1.html">QML Tutorial 1 - Basic Types</a>
<a class="nextPage" href="qml-tutorial3.html">QML Tutorial 3 - States and Transitions</a>
</p>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2012 Nokia Corporation 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>
Nokia, Qt and their respective logos are trademarks of Nokia Corporation
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>
</body>
</html>
|
