1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the documentation of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** GNU Free Documentation License
10 ** Alternatively, this file may be used under the terms of the GNU Free
11 ** Documentation License version 1.3 as published by the Free Software
12 ** Foundation and appearing in the file included in the packaging of
16 ** Alternatively, this file may be used in accordance with the terms
17 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
28 \page qtqml-typesystem-basictypes.html
29 \title QML Basic Types
30 \brief Description of basic types provided by the Qt QML module
32 QML supports a number of basic types.
34 A \e{basic type} is one that refers to a simple value, such as an \c int
35 or a \c string. This contrasts with a \l{qtqml-typesystem-topic.html#qml-object-types}{QML Object Types},
36 which refers to an object with properties, signals, methods and so on. Unlike an object type,
37 a basic type cannot be used to declare QML objects: it is not possible, for example, to declare an
38 \c int{} object or a \c size{} object.
40 Basic types can be used to refer to:
43 \li A single value (e.g. \l int refers to a single number, \l var can refer to a single list of items)
44 \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)
47 \sa {qtqml-typesystem-topic.html}{The QML Type System}
50 \section1 Supported Basic Types
52 Some basic types are supported by the engine by default and do not require an
53 \l {Import Statements}{import statement} to be used, while others do require
54 the client to import the module which provides them.
55 All of the basic types listed below may be used as a \c property type in a QML
56 document, with the following exceptions:
58 \li \c list must be used in conjunction with a QML object type
59 \li \c enumeration cannot be used directly as the enumeration must be defined by a registered QML object type
62 \section2 Basic Types Provided By The QML Language
64 The basic types supported natively in the QML language are listed below:
65 \annotatedlist qmlbasictypes
67 \section2 Basic Types Provided By QML Modules
69 QML modules may extend the QML language with more basic types.
70 For example, the basic types provided by the QtQuick module are listed below:
71 \annotatedlist qtquickbasictypes
73 Currently only QML modules which are provided by Qt may provide their
74 own basic types, however this may change in future releases of Qt QML.
75 In order to use types provided by a particular QML module, clients
76 must import that module in their QML documents.
78 \section1 Property Change Behavior for Basic Types
80 Some basic types have properties: for example, the \l font type has
81 \c pixelSize, \c family and \c b properties. Unlike properties of
82 \l{qtqml-typesystem-topic.html#qml-object-types}{object types}, properties of
83 basic types do not provide their own property change signals. It is only possible
84 to create a property change signal handler for the basic type property itself:
89 onFont.pixelSizeChanged: doSomething()
93 onPixelSizeChanged: doSomething()
97 onFontChanged: doSomething()
101 Be aware, however, that a property change signal for a basic type is emitted
102 whenever \e any of its attributes have changed, as well as when the property itself
103 changes. Take the following code, for example:
107 onFontChanged: console.log("font changed")
109 Text { id: otherText }
113 // changing any of the font attributes, or reassigning the property
114 // to a different font value, will invoke the onFontChanged handler
115 Keys.onDigit1Pressed: font.pixelSize += 1
116 Keys.onDigit2Pressed: font.b = !font.b
117 Keys.onDigit3Pressed: font = otherText.font
121 In contrast, properties of an \l{qtqml-typesystem-topic.html#qml-object-types}{object type}
122 emit their own property change signals, and a property change signal handler for an object-type
123 property is only invoked when the property is reassigned to a different object value.
129 \ingroup qmlbasictypes
130 \brief a whole number, e.g. 0, 10, or -20.
132 The \c int type refers to a whole number, e.g. 0, 10, or -20.
134 The possible \c int values range from around -2000000000 to around 2000000000,
135 although most elements will only accept a reduced range (which they
136 mention in their documentation).
140 Item { width: 100; height: 200 }
143 This basic type is provided by the QML language.
145 \sa {QML Basic Types}
150 \ingroup qmlbasictypes
151 \brief a binary true/false value.
153 The \c bool type refers to a binary true/false value.
163 This basic type is provided by the QML language.
165 \sa {QML Basic Types}
170 \ingroup qmlbasictypes
172 \brief a number with a decimal point.
174 The \c real type refers to a number with decimal point, e.g. 1.2 or -29.8.
178 Item { width: 100.45; height: 150.82 }
181 \b{Note:} In QML all reals are stored in double precision, \l
182 {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point}
185 This basic type is provided by the QML language.
187 \sa {QML Basic Types}
192 \ingroup qmlbasictypes
194 \brief a number with a decimal point, stored in double precision.
196 The \c double type refers to a number with a decimal point and is stored in double precision, \l
197 {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point} format.
202 property double number: 32155.2355
206 This basic type is provided by the QML language.
208 \sa {QML Basic Types}
213 \ingroup qmlbasictypes
214 \brief a free form text string.
216 The \c string type refers to a free form text string in quotes, e.g. "Hello world!".
220 Text { text: "Hello world!" }
223 Strings have a \c length attribute that holds the number of
224 characters in the string.
226 QML extends the JavaScript String type with a \l {String::arg}{arg()} function
227 to support value substitution.
229 When integrating with C++, note that any QString value
230 \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
231 converted into a \c string value, and vice-versa.
233 This basic type is provided by the QML language.
235 \sa {QML Basic Types}
240 \ingroup qmlbasictypes
241 \brief a resource locator.
243 The \c url type refers to a resource locator (like a file name, for example). It can be either
244 absolute, e.g. "http://qt.nokia.com", or relative, e.g. "pics/logo.png". A relative URL is
245 resolved relative to the URL of the containing component.
247 For example, the following assigns a valid URL to the \l {Image::source}
248 property, which is of type \c url:
251 Image { source: "pics/logo.png" }
254 When integrating with C++, note that any QUrl value
255 \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
256 converted into a \c url value, and vice-versa.
259 \section1 Using the url Type
261 When a relative URL is written to a \c url type property, it is converted
262 into a URL object, so \b {matching the URL value against the input string
263 value will fail}. Instead, convert the string to a URL using Qt.resolvedUrl()
264 for means of comparison, and use \c toString() to get the contents of the URL:
268 source: "pics/logo.png"
270 Component.onCompleted: {
271 // This prints 'false'. Although "pics/logo.png" was the input string,
272 // it's been converted from a string to a URL, so these two are not the same.
273 console.log(source == "pics/logo.png")
275 // This prints 'true' as Qt.resovledUrl() converts the string into a
276 // URL with the correctly resolved path
277 console.log(source == Qt.resolvedUrl("pics/logo.png"))
279 // This prints the absolute path, e.g. "file:///path/to/pics/logo.png"
280 console.log(source.toString())
285 \note When referring to files stored with the \l{resources.html}{Qt Resource System}
286 from within QML, you should use "qrc:///" instead of ":/" as QML requires URL paths.
287 Relative URLs resolved from within that file will use the same protocol.
289 Additionally, URLs may contain encoded characters using the 'percent-encoding' scheme
290 specified by \l {http://tools.ietf.org/html/rfc3986}{RFC 3986}. These characters
291 will be preserved within properties of type \c url, to allow QML code to
292 construct precise URL values. An exception to this rule is the preemptive
293 decoding of directory-separator characters (\c '/') - these characters are decoded
294 to allow the URL to be correctly classified.
296 For example, a local file containing a '#' character, which would normally be
297 interpreted as the beginning of the URL 'fragment' element, can be accessed by
298 encoding the characters of the file name:
301 Image { source: encodeURIComponent("/tmp/test#1.png") }
304 This basic type is provided by the QML language.
306 \sa {QML Basic Types}
312 \ingroup qmlbasictypes
313 \brief a list of QML objects.
315 The \c list type refers to a list of QML objects.
317 A list value can be accessed in a similar way to a JavaScript array:
320 \li Values are assigned using the \c[] square bracket syntax with comma-separated values
321 \li The \c length property provides the number of items in the list
322 \li Values in the list are accessed using the \c [index] syntax
325 A \c list can only store QML objects, and cannot contain any
326 \l {QML Basic Types}{basic type} values. (To store basic types within a
327 list, use the \l var type instead.)
329 When integrating with C++, note that any QQmlListProperty value
330 \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
331 converted into a \c list value, and vice-versa.
334 \section1 Using the list Type
336 For example, the \l Item type has a \l {Item::}{states} list-type property that
337 can be assigned to and used as follows:
343 width: 100; height: 100
346 State { name: "activated" },
347 State { name: "deactivated" }
350 Component.onCompleted: {
351 console.log("Name of first state:", states[0].name)
352 for (var i = 0; i < states.length; i++)
353 console.log("state", i, states[i].name)
358 The defined \l State objects will be added to the \c states list
359 in the order in which they are defined.
361 If the list only contains one object, the square brackets may be omitted:
367 width: 100; height: 100
368 states: State { name: "activated" }
372 Note that objects cannot be individually added to or removed from
373 the list once created; to modify the contents of a list, it must be
374 reassigned to a new list.
376 \note The \c list type is not recommended as a type for custom properties.
377 The \c var type should be used instead for this purpose as
378 lists stored by the \c var type can be manipulated with greater
379 flexibility from within QML.
381 This basic type is provided by the QML language.
383 \sa {QML Basic Types}
388 \ingroup qmlbasictypes
389 \brief a generic property type.
391 The \c var type is a generic property type that can refer to any data type.
393 It is equivalent to a regular JavaScript variable.
394 For example, var properties can store numbers, strings, objects,
395 arrays and functions:
399 property var aNumber: 100
400 property var aBool: false
401 property var aString: "Hello world!"
402 property var anotherString: String("#FF008800")
403 property var aColor: Qt.rgba(0.2, 0.3, 0.4, 0.5)
404 property var aRect: Qt.rect(10, 10, 10, 10)
405 property var aPoint: Qt.point(10, 10)
406 property var aSize: Qt.size(10, 10)
407 property var aVector3d: Qt.vector3d(100, 100, 100)
408 property var anArray: [1, 2, 3, "four", "five", (function() { return "six"; })]
409 property var anObject: { "foo": 10, "bar": 20 }
410 property var aFunction: (function() { return "one"; })
414 \section1 Change Notification Semantics
416 It is important to note that changes in regular properties of JavaScript
417 objects assigned to a var property will \b{not} trigger updates of bindings
418 that access them. The example below will display "The car has 4 wheels" as
419 the change to the wheels property will not cause the reevaluation of the
420 binding assigned to the "text" property:
424 property var car: new Object({wheels: 4})
427 text: "The car has " + car.wheels + " wheels";
430 Component.onCompleted: {
436 If the onCompleted handler instead had \tt{"car = new Object({wheels: 6})"}
437 then the text would be updated to say "The car has 6 wheels", since the
438 car property itself would be changed, which causes a change notification
441 \section1 Property Value Initialization Semantics
443 The QML syntax defines that curly braces on the right-hand-side of a
444 property value initialization assignment denote a binding assignment.
445 This can be confusing when initializing a \c var property, as empty curly
446 braces in JavaScript can denote either an expression block or an empty
447 object declaration. If you wish to initialize a \c var property to an
448 empty object value, you should wrap the curly braces in parentheses.
453 property var first: {} // nothing = undefined
454 property var second: {{}} // empty expression block = undefined
455 property var third: ({}) // empty object
459 In the previous example, the \c first property is bound to an empty
460 expression, whose result is undefined. The \c second property is bound to
461 an expression which contains a single, empty expression block ("{}"), which
462 similarly has an undefined result. The \c third property is bound to an
463 expression which is evaluated as an empty object declaration, and thus the
464 property will be initialized with that empty object value.
466 Similarly, a colon in JavaScript can be either an object property value
467 assignment, or a code label. Thus, initializing a var property with an
468 object declaration can also require parentheses:
472 property var first: { example: 'true' } // example is interpreted as a label
473 property var second: ({ example: 'true' }) // example is interpreted as a property
474 property var third: { 'example': 'true' } // example is interpreted as a property
475 Component.onCompleted: {
476 console.log(first.example) // prints 'undefined', as "first" was assigned a string
477 console.log(second.example) // prints 'true'
478 console.log(third.example) // prints 'true'
483 \section1 Using Scarce Resources with the var Type
485 A \c var type property can also hold an image or pixmap.
486 A \c var which contains a QPixmap or QImage is known as a
487 "scarce resource" and the declarative engine will attempt to
488 automatically release such resources after evaluation of any JavaScript
489 expression which requires one to be copied has completed.
491 Clients may explicitly release such a scarce resource by calling the
492 "destroy" method on the \c var property from within JavaScript. They
493 may also explicitly preserve the scarce resource by calling the
494 "preserve" method on the \c var property from within JavaScript.
495 For more information regarding the usage of a scarce resource, please
496 see \l{Scarce Resources in JavaScript}.
498 This basic type is provided by the QML language.
500 \sa {QML Basic Types}
506 \qmlbasictype variant
507 \ingroup qmlbasictypes
508 \brief a generic property type.
510 The \c variant type is a generic property type. It is obsolete and exists only to
511 support old applications; new applications should use \l var type
514 A variant type property can hold any of the \l {QML Basic Types}{basic type}
519 property variant aNumber: 100
520 property variant aString: "Hello world!"
521 property variant aBool: false
525 When integrating with C++, note that any QVariant value
526 \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
527 converted into a \c variant value, and vice-versa.
530 \section1 Using Scarce Resources with the variant Type
532 A \c variant type property can also hold an image or pixmap.
533 A \c variant which contains a QPixmap or QImage is known as a
534 "scarce resource" and the declarative engine will attempt to
535 automatically release such resources after evaluation of any JavaScript
536 expression which requires one to be copied has completed.
538 Clients may explicitly release such a scarce resource by calling the
539 "destroy" method on the \c variant property from within JavaScript. They
540 may also explicitly preserve the scarce resource by calling the
541 "preserve" method on the \c variant property from within JavaScript.
542 For more information regarding the usage of a scarce resource, please
543 see \l{Scarce Resources in JavaScript}.
545 \section1 Storing Arrays and Objects
547 The \c variant type can also hold:
550 \li An array of \l {QML Basic Types}{basic type} values
551 \li A map of key-value pairs with \l {QML Basic Types}{basic-type} values
554 For example, below is an \c items array and an \c attributes map. Their
555 contents can be examined using JavaScript \c for loops. Individual array
556 values are accessible by index, and individual map values are accessible
561 property variant items: [1, 2, 3, "four", "five"]
562 property variant attributes: { 'color': 'red', 'width': 100 }
564 Component.onCompleted: {
565 for (var i = 0; i < items.length; i++)
566 console.log(items[i])
568 for (var prop in attributes)
569 console.log(prop, "=", attributes[prop])
574 While this is a convenient way to store array and map-type values, you
575 must be aware that the \c items and \c attributes properties above are \e not
576 QML objects (and certainly not JavaScript object either) and the key-value
577 pairs in \c attributes are \e not QML properties. Rather, the \c items
578 property holds an array of values, and \c attributes holds a set of key-value
579 pairs. Since they are stored as a set of values, instead of as an object,
580 their contents \e cannot be modified individually:
584 property variant items: [1, 2, 3, "four", "five"]
585 property variant attributes: { 'color': 'red', 'width': 100 }
587 Component.onCompleted: {
589 console.log(items[0]) // This will still be '1'!
590 attributes.color = 'blue'
591 console.log(attributes.color) // This will still be 'red'!
596 Since it is not possible to individually add or remove items from a list or
597 object stored in a \c variant, the only way to modify its contents is to
598 reassign a new value. However, this is not efficent, as it causes the value
599 to be serialized and deserialized.
601 Additionally, since \c items and \c attributes are not QML objects, changing
602 their individual values do not trigger property change notifications. If
603 the above example had \c onNumberChanged or \c onAnimalChanged signal
604 handlers, they would not have been called. If, however, the \c items or
605 \c attributes properties themselves were reassigned to different values, then
606 such handlers would be called.
608 JavaScript programmers should also note that when a JavaScript object is
609 copied to an array or map property, the \e contents of the object (that is,
610 its key-value properties) are copied, rather than the object itself. The
611 property does not hold a reference to the original JavaScript object, and
612 extra data such as the object's JavaScript prototype chain is also lost in
615 This basic type is provided by the QML language.
617 \sa {QML Basic Types}
621 \qmlbasictype enumeration
622 \ingroup qmlbasictypes
623 \brief a named enumeration value.
625 The \c enumeration type refers to a named enumeration value.
627 Each named value can be referred to as \c {<Type>.<value>}. For
628 example, the \l Text type has an \c AlignRight enumeration value:
631 Text { horizontalAlignment: Text.AlignRight }
634 (For backwards compatibility, the enumeration value may also be
635 specified as a string, e.g. "AlignRight". This form is not
636 recommended for new code.)
638 When integrating with C++, note that any \c enum value
639 \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
640 converted into an \c enumeration value, and vice-versa.
642 This basic type is provided by the QML language. Some enumeration values
643 are provided by the QtQuick import.
645 \section1 Using the enumeration type in QML
647 The \c enumeration type is a representation of a C++ \c enum type. It is
648 not possible to refer to the \c enumeration type in QML itself; instead, the
649 \l int or \l var types can be used when referring to \c enumeration values
658 // refer to Text.AlignRight using an int type
659 property int enumValue: textItem.horizontalAlignment
661 signal valueEmitted(int someValue)
665 horizontalAlignment: Text.AlignRight
668 // emit valueEmitted() signal, which expects an int, with Text.AlignRight
669 Component.onCompleted: valueEmitted(Text.AlignRight)
673 \sa {QML Basic Types}