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
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
|
/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see http://www.qt.io/terms-conditions. For further
** information use the contact form at http://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtqml-typesystem-basictypes.html
\title QML Basic Types
\brief Description of basic types provided by the Qt QML module
QML supports a number of basic types.
A \e{basic type} is one that refers to a simple value, such as an \c int
or a \c string. This contrasts with a \l{qtqml-typesystem-topic.html#qml-object-types}{QML Object Types},
which refers to an object with properties, signals, methods and so on. Unlike an object type,
a basic type cannot be used to declare QML objects: it is not possible, for example, to declare an
\c int{} object or a \c size{} object.
Basic types can be used to refer to:
\list
\li A single value (e.g. \l int refers to a single number, \l var can refer to a single list of items)
\li A value that contains a simple set of property-value pairs (e.g. \l size refers to a value with \c width and \c height attributes)
\endlist
\sa {qtqml-typesystem-topic.html}{The QML Type System}
\section1 Supported Basic Types
Some basic types are supported by the engine by default and do not require an
\l {Import Statements}{import statement} to be used, while others do require
the client to import the module which provides them.
All of the basic types listed below may be used as a \c property type in a QML
document, with the following exceptions:
\list
\li \c list must be used in conjunction with a QML object type
\li \c enumeration cannot be used directly as the enumeration must be defined by a registered QML object type
\endlist
\section2 Basic Types Provided By The QML Language
The basic types supported natively in the QML language are listed below:
\annotatedlist qmlbasictypes
\section2 Basic Types Provided By QML Modules
QML modules may extend the QML language with more basic types.
For example, the basic types provided by the \c QtQuick module are listed below:
\annotatedlist qtquickbasictypes
The \l{QtQml::Qt}{Qt} global object provides useful functions for manipulating values of basic types.
Currently only QML modules which are provided by Qt may provide their
own basic types, however this may change in future releases of Qt QML.
In order to use types provided by a particular QML module, clients
must import that module in their QML documents.
\section1 Property Change Behavior for Basic Types
Some basic types have properties: for example, the \l font type has
\c pixelSize, \c family and \c bold properties. Unlike properties of
\l{qtqml-typesystem-topic.html#qml-object-types}{object types}, properties of
basic types do not provide their own property change signals. It is only possible
to create a property change signal handler for the basic type property itself:
\code
Text {
// invalid!
onFont.pixelSizeChanged: doSomething()
// also invalid!
font {
onPixelSizeChanged: doSomething()
}
// but this is ok
onFontChanged: doSomething()
}
\endcode
Be aware, however, that a property change signal for a basic type is emitted
whenever \e any of its attributes have changed, as well as when the property itself
changes. Take the following code, for example:
\qml
Text {
onFontChanged: console.log("font changed")
Text { id: otherText }
focus: true
// changing any of the font attributes, or reassigning the property
// to a different font value, will invoke the onFontChanged handler
Keys.onDigit1Pressed: font.pixelSize += 1
Keys.onDigit2Pressed: font.b = !font.b
Keys.onDigit3Pressed: font = otherText.font
}
\endqml
In contrast, properties of an \l{qtqml-typesystem-topic.html#qml-object-types}{object type}
emit their own property change signals, and a property change signal handler for an object-type
property is only invoked when the property is reassigned to a different object value.
*/
/*!
\qmlbasictype int
\ingroup qmlbasictypes
\brief a whole number, e.g. 0, 10, or -20.
The \c int type refers to a whole number, e.g. 0, 10, or -20.
The possible \c int values range from around -2000000000 to around 2000000000,
although most types will only accept a reduced range (which they
mention in their documentation).
Example:
\qml
Item { width: 100; height: 200 }
\endqml
This basic type is provided by the QML language.
\sa {QML Basic Types}
*/
/*!
\qmlbasictype bool
\ingroup qmlbasictypes
\brief a binary true/false value.
The \c bool type refers to a binary true/false value.
Example:
\qml
Item {
focus: true
clip: false
}
\endqml
This basic type is provided by the QML language.
\sa {QML Basic Types}
*/
/*!
\qmlbasictype real
\ingroup qmlbasictypes
\brief a number with a decimal point.
The \c real type refers to a number with decimal point, e.g. 1.2 or -29.8.
Example:
\qml
Item { width: 100.45; height: 150.82 }
\endqml
\b{Note:} In QML all reals are stored in double precision, \l
{http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point}
format.
This basic type is provided by the QML language.
\sa {QML Basic Types}
*/
/*!
\qmlbasictype double
\ingroup qmlbasictypes
\brief a number with a decimal point, stored in double precision.
The \c double type refers to a number with a decimal point and is stored in double precision, \l
{http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point} format.
Example:
\qml
Item {
property double number: 32155.2355
}
\endqml
This basic type is provided by the QML language.
\sa {QML Basic Types}
*/
/*!
\qmlbasictype string
\ingroup qmlbasictypes
\brief a free form text string.
The \c string type refers to a free form text string in quotes, e.g. "Hello world!".
Example:
\qml
Text { text: "Hello world!" }
\endqml
Strings have a \c length attribute that holds the number of
characters in the string.
QML extends the JavaScript String type with a \l {String::arg}{arg()} function
to support value substitution.
When integrating with C++, note that any QString value
\l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
converted into a \c string value, and vice-versa.
This basic type is provided by the QML language.
\sa {QML Basic Types}
*/
/*!
\qmlbasictype url
\ingroup qmlbasictypes
\brief a resource locator.
The \c url type refers to a resource locator (like a file name, for example). It can be either
absolute, e.g. "http://qt-project.org", or relative, e.g. "pics/logo.png". A relative URL is
resolved relative to the URL of the containing component.
For example, the following assigns a valid URL to the \l {Image::source}
property, which is of type \c url:
\qml
Image { source: "pics/logo.png" }
\endqml
When integrating with C++, note that any QUrl value
\l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
converted into a \c url value, and vice-versa.
\section1 Using the url Type
When a relative URL is written to a \c url type property, it is converted
into a URL object, so \b {matching the URL value against the input string
value will fail}. Instead, convert the string to a URL using Qt.resolvedUrl()
for means of comparison, and use \c toString() to get the contents of the URL:
\qml
Image {
source: "pics/logo.png"
Component.onCompleted: {
// This prints 'false'. Although "pics/logo.png" was the input string,
// it's been converted from a string to a URL, so these two are not the same.
console.log(source == "pics/logo.png")
// This prints 'true' as Qt.resovledUrl() converts the string into a
// URL with the correctly resolved path
console.log(source == Qt.resolvedUrl("pics/logo.png"))
// This prints the absolute path, e.g. "file:///path/to/pics/logo.png"
console.log(source.toString())
}
}
\endqml
\note When referring to files stored with the \l{resources.html}{Qt Resource System}
from within QML, you should use "qrc:///" instead of ":/" as QML requires URL paths.
Relative URLs resolved from within that file will use the same protocol.
Additionally, URLs may contain encoded characters using the 'percent-encoding' scheme
specified by \l {http://tools.ietf.org/html/rfc3986}{RFC 3986}. These characters
will be preserved within properties of type \c url, to allow QML code to
construct precise URL values. An exception to this rule is the preemptive
decoding of directory-separator characters (\c '/') - these characters are decoded
to allow the URL to be correctly classified.
For example, a local file containing a '#' character, which would normally be
interpreted as the beginning of the URL 'fragment' element, can be accessed by
encoding the characters of the file name:
\qml
Image { source: encodeURIComponent("/tmp/test#1.png") }
\endqml
This basic type is provided by the QML language.
\sa {QML Basic Types}
*/
/*!
\qmlbasictype list
\ingroup qmlbasictypes
\brief a list of QML objects.
The \c list type refers to a list of QML objects.
A list value can be accessed in a similar way to a JavaScript array:
\list
\li Values are assigned using the \c[] square bracket syntax with comma-separated values
\li The \c length property provides the number of items in the list
\li Values in the list are accessed using the \c [index] syntax
\endlist
Values can be dynamically added to the list by using the \c push method,
as if it were a JavaScript Array
A \c list can only store QML objects, and cannot contain any
\l {QML Basic Types}{basic type} values. (To store basic types within a
list, use the \l var type instead.)
When integrating with C++, note that any QQmlListProperty value
\l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
converted into a \c list value, and vice-versa.
\section1 Using the list Type
For example, the \l Item type has a \l {Item::}{states} list-type property that
can be assigned to and used as follows:
\qml
import QtQuick 2.0
Item {
width: 100; height: 100
states: [
State { name: "activated" },
State { name: "deactivated" }
]
Component.onCompleted: {
console.log("Name of first state:", states[0].name)
for (var i = 0; i < states.length; i++)
console.log("state", i, states[i].name)
}
}
\endqml
The defined \l State objects will be added to the \c states list
in the order in which they are defined.
If the list only contains one object, the square brackets may be omitted:
\qml
import QtQuick 2.0
Item {
width: 100; height: 100
states: State { name: "activated" }
}
\endqml
Note that objects cannot be individually added to or removed from
the list once created; to modify the contents of a list, it must be
reassigned to a new list.
\note The \c list type is not recommended as a type for custom properties.
The \c var type should be used instead for this purpose as
lists stored by the \c var type can be manipulated with greater
flexibility from within QML.
This basic type is provided by the QML language.
\sa {QML Basic Types}
*/
/*!
\qmlbasictype var
\ingroup qmlbasictypes
\brief a generic property type.
The \c var type is a generic property type that can refer to any data type.
It is equivalent to a regular JavaScript variable.
For example, var properties can store numbers, strings, objects,
arrays and functions:
\qml
Item {
property var aNumber: 100
property var aBool: false
property var aString: "Hello world!"
property var anotherString: String("#FF008800")
property var aColor: Qt.rgba(0.2, 0.3, 0.4, 0.5)
property var aRect: Qt.rect(10, 10, 10, 10)
property var aPoint: Qt.point(10, 10)
property var aSize: Qt.size(10, 10)
property var aVector3d: Qt.vector3d(100, 100, 100)
property var anArray: [1, 2, 3, "four", "five", (function() { return "six"; })]
property var anObject: { "foo": 10, "bar": 20 }
property var aFunction: (function() { return "one"; })
}
\endqml
\section1 Change Notification Semantics
It is important to note that changes in regular properties of JavaScript
objects assigned to a var property will \b{not} trigger updates of bindings
that access them. The example below will display "The car has 4 wheels" as
the change to the wheels property will not cause the reevaluation of the
binding assigned to the "text" property:
\qml
Item {
property var car: new Object({wheels: 4})
Text {
text: "The car has " + car.wheels + " wheels";
}
Component.onCompleted: {
car.wheels = 6;
}
}
\endqml
If the onCompleted handler instead had \tt{"car = new Object({wheels: 6})"}
then the text would be updated to say "The car has 6 wheels", since the
car property itself would be changed, which causes a change notification
to be emitted.
\section1 Property Value Initialization Semantics
The QML syntax defines that curly braces on the right-hand-side of a
property value initialization assignment denote a binding assignment.
This can be confusing when initializing a \c var property, as empty curly
braces in JavaScript can denote either an expression block or an empty
object declaration. If you wish to initialize a \c var property to an
empty object value, you should wrap the curly braces in parentheses.
For example:
\qml
Item {
property var first: {} // nothing = undefined
property var second: {{}} // empty expression block = undefined
property var third: ({}) // empty object
}
\endqml
In the previous example, the \c first property is bound to an empty
expression, whose result is undefined. The \c second property is bound to
an expression which contains a single, empty expression block ("{}"), which
similarly has an undefined result. The \c third property is bound to an
expression which is evaluated as an empty object declaration, and thus the
property will be initialized with that empty object value.
Similarly, a colon in JavaScript can be either an object property value
assignment, or a code label. Thus, initializing a var property with an
object declaration can also require parentheses:
\qml
Item {
property var first: { example: 'true' } // example is interpreted as a label
property var second: ({ example: 'true' }) // example is interpreted as a property
property var third: { 'example': 'true' } // example is interpreted as a property
Component.onCompleted: {
console.log(first.example) // prints 'undefined', as "first" was assigned a string
console.log(second.example) // prints 'true'
console.log(third.example) // prints 'true'
}
}
\endqml
\sa {QML Basic Types}
*/
/*
TODO Qt 5.1: see explanation in expressions.qdoc
\section1 Using Scarce Resources with the var Type
A \c var type property can also hold an image or pixmap.
A \c var which contains a QPixmap or QImage is known as a
"scarce resource" and the declarative engine will attempt to
automatically release such resources after evaluation of any JavaScript
expression which requires one to be copied has completed.
Clients may explicitly release such a scarce resource by calling the
"destroy" method on the \c var property from within JavaScript. They
may also explicitly preserve the scarce resource by calling the
"preserve" method on the \c var property from within JavaScript.
This basic type is provided by the QML language.
*/
/*!
\obsolete
\qmlbasictype variant
\ingroup qmlbasictypes
\brief a generic property type.
The \c variant type is a generic property type. It is obsolete and exists only to
support old applications; new applications should use \l var type
properties instead.
A variant type property can hold any of the \l {QML Basic Types}{basic type}
values:
\qml
Item {
property variant aNumber: 100
property variant aString: "Hello world!"
property variant aBool: false
}
\endqml
When integrating with C++, note that any QVariant value
\l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
converted into a \c variant value, and vice-versa.
\section1 Using Scarce Resources with the variant Type
A \c variant type property can also hold an image or pixmap.
A \c variant which contains a QPixmap or QImage is known as a
"scarce resource" and the declarative engine will attempt to
automatically release such resources after evaluation of any JavaScript
expression which requires one to be copied has completed.
Clients may explicitly release such a scarce resource by calling the
"destroy" method on the \c variant property from within JavaScript. They
may also explicitly preserve the scarce resource by calling the
"preserve" method on the \c variant property from within JavaScript.
\section1 Storing Arrays and Objects
The \c variant type can also hold:
\list
\li An array of \l {QML Basic Types}{basic type} values
\li A map of key-value pairs with \l {QML Basic Types}{basic-type} values
\endlist
For example, below is an \c items array and an \c attributes map. Their
contents can be examined using JavaScript \c for loops. Individual array
values are accessible by index, and individual map values are accessible
by key:
\qml
Item {
property variant items: [1, 2, 3, "four", "five"]
property variant attributes: { 'color': 'red', 'width': 100 }
Component.onCompleted: {
for (var i = 0; i < items.length; i++)
console.log(items[i])
for (var prop in attributes)
console.log(prop, "=", attributes[prop])
}
}
\endqml
While this is a convenient way to store array and map-type values, you
must be aware that the \c items and \c attributes properties above are \e not
QML objects (and certainly not JavaScript object either) and the key-value
pairs in \c attributes are \e not QML properties. Rather, the \c items
property holds an array of values, and \c attributes holds a set of key-value
pairs. Since they are stored as a set of values, instead of as an object,
their contents \e cannot be modified individually:
\qml
Item {
property variant items: [1, 2, 3, "four", "five"]
property variant attributes: { 'color': 'red', 'width': 100 }
Component.onCompleted: {
items[0] = 10
console.log(items[0]) // This will still be '1'!
attributes.color = 'blue'
console.log(attributes.color) // This will still be 'red'!
}
}
\endqml
Since it is not possible to individually add or remove items from a list or
object stored in a \c variant, the only way to modify its contents is to
reassign a new value. However, this is not efficient, as it causes the value
to be serialized and deserialized.
Additionally, since \c items and \c attributes are not QML objects, changing
their individual values do not trigger property change notifications. If
the above example had \c onNumberChanged or \c onAnimalChanged signal
handlers, they would not have been called. If, however, the \c items or
\c attributes properties themselves were reassigned to different values, then
such handlers would be called.
JavaScript programmers should also note that when a JavaScript object is
copied to an array or map property, the \e contents of the object (that is,
its key-value properties) are copied, rather than the object itself. The
property does not hold a reference to the original JavaScript object, and
extra data such as the object's JavaScript prototype chain is also lost in
the process.
This basic type is provided by the QML language.
\sa {QML Basic Types}
*/
/*!
\qmlbasictype enumeration
\ingroup qmlbasictypes
\brief a named enumeration value.
The \c enumeration type refers to a named enumeration value.
Each named value can be referred to as \c {<Type>.<value>}. For
example, the \l Text type has an \c AlignRight enumeration value:
\qml
Text { horizontalAlignment: Text.AlignRight }
\endqml
(For backwards compatibility, the enumeration value may also be
specified as a string, e.g. "AlignRight". This form is not
recommended for new code.)
When integrating with C++, note that any \c enum value
\l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
converted into an \c enumeration value, and vice-versa.
This basic type is provided by the QML language. Some enumeration values
are provided by the QtQuick import.
\section1 Using the enumeration Type in QML
The \c enumeration type is a representation of a C++ \c enum type. It is
not possible to refer to the \c enumeration type in QML itself; instead, the
\l int or \l var types can be used when referring to \c enumeration values
from QML code.
For example:
\qml
import QtQuick 2.0
Item {
// refer to Text.AlignRight using an int type
property int enumValue: textItem.horizontalAlignment
signal valueEmitted(int someValue)
Text {
id: textItem
horizontalAlignment: Text.AlignRight
}
// emit valueEmitted() signal, which expects an int, with Text.AlignRight
Component.onCompleted: valueEmitted(Text.AlignRight)
}
\endqml
\sa {QML Basic Types}
*/
|