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
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights. These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
**
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qmldocuments.html
\title QML Documents
A QML document is a block of QML source code. QML documents generally correspond to files
stored on a disk or network resource, but can also be constructed directly from text data.
Here is a simple QML document:
\code
import Qt 4.6
Rectangle {
width: 240; height: 320;
resources: [
Component {
id: contactDelegate
Text {
text: modelData.firstName + " " + modelData.lastName
}
}
]
ListView {
anchors.fill: parent
model: contactModel
delegate: contactDelegate
}
}
\endcode
QML documents are always encoded in UTF-8 format.
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 \l {Modules}. That is,
QML is a \e versioned language.
Syntactically a QML document is self contained; QML does \e not have a preprocessor that
modifies the document prior to presentation to the QML runtime. \c import 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 \c Rectangle and \c ListView - including those made within an
\l {JavaScript Block} or \l {Property Binding}s, are \e resolved based exclusively on the
import statements. QML does not import any modules by default, so at least one \c import
statement must be present or no elements will be available!
A QML document defines a single, top-level \l {QmlComponent}{QML component}. 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 \e instances of the component.
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 that is
instantiated four times, each with a different value for its \c text property.
\table
\row
\o
\raw HTML
<table><tr><td>
\endraw
\code
import Qt 4.6
BorderImage {
property alias text: textElement.text
width: 100; height: 30; source: "images/toolbutton.sci"
Text {
id: textElement
anchors.centerIn: parent
font.pointSize: 20
style: Text.Raised
color: "white"
}
}
\endcode
\raw HTML
</td> <td>
\endraw
\image anatomy-component.png
\raw HTML
</td> </tr> </table>
\endraw
\endtable
In addition to the top-level component that all QML documents define, documents may also
include additional \e inline components. Inline components are declared using the
\l Component 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 \c import 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 \l ListView element uses the
\c delegate 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.
Like other \l {QML Elements}, the \l Component element is an object and must be assigned to a
property. \l Component objects may also have an object id. In the first example on this page,
the inline component is added to the \l Rectangle's \c resources list, and then
\l {Property Binding} is used to assign the \l Component to the \l ListView's \c delegate
property. While using property binding allows the \l Component object to be shared (for example,
if the QML document contained multiple \l ListView's with the same delegate), in this case the
\l Component could have been assigned directly to the \l ListView's \c delegate. The QML
language even contains a syntactic optimization when assigning directly to a component property
for this case where it will automatically insert the \l Component tag.
These final two examples are behaviorally identical to the original document.
\table
\row
\o
\code
import Qt 4.6
Rectangle {
width: 240; height: 320;
ListView {
anchors.fill: parent
model: contactModel
delegate: Component {
Text {
text: modelData.firstName + " " + modelData.lastName
}
}
}
}
\endcode
\o
\code
import Qt 4.6
Rectangle {
width: 240; height: 320;
ListView {
anchors.fill: parent
model: contactModel
delegate: Text {
text: modelData.firstName + " " + modelData.lastName
}
}
}
\endcode
\endtable
\sa QmlComponent
*/
|
