1// Copyright (C) 2022 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
4\page qtqml-typesystem-valuetypes.html
6\brief Description of QML value types
8QML supports built-in and custom value types.
10A \e{value type} is one that is conceptually passed by value rather than by
11reference, such as an \c int or a \c string. This contrasts with
12\l{qtqml-typesystem-topic.html#qml-object-types}{QML Object Types}. Object types
13are passed by reference. If you assign an instance of an object type to two
14different properties, both properties carry the same value. Modifying the object
15is reflected in both properties. If you assign an instance of a value type to
16two different properties, the properties carry separate values. If you modify
17one of them, the other one stays the same. Value types are only conceptually
18passed by value since it must still be possible to interact with them as if they
19were JavaScript objects. To facilitate this, in reality they are passed as
20\l{QML Value Type and Sequence References}{Value Type References} when you access
21them from JavaScript code.
23Unlike an object type, a value type cannot be used to declare QML objects:
24it is not possible, for example, to declare an \c int{} object or a \c size{} object.
26Value types can be used to refer to:
29\li A single value (e.g. \l int refers to a single number)
30\li A value that contains properties and methods (e.g. \l size refers to a value with \c width and \c height properties)
31\li The generic type \l{var}. It can hold values of any other type but is itself a value type.
34When a variable or property holds a value type and it is assigned to another
35variable or property, then a copy of the value is made.
37\sa {qtqml-typesystem-topic.html}{The QML Type System}
40\section1 Available Value Types
42Some value types are supported by the engine by default and do not require an
43\l {Import Statements}{import statement} to be used, while others do require
44the client to import the module which provides them.
45All of the value types listed below may be used as a \c property type in a QML
46document, with the following exceptions:
48 \li \c void, which marks the absence of a value
49 \li \c list must be used in conjunction with an object or value type as element
50 \li \c enumeration cannot be used directly as the enumeration must be defined by a registered QML object type
53\section2 Built-in Value Types Provided By The QML Language
55The built-in value types supported natively in the \l{The QML Reference}{QML language} are listed below:
56\annotatedlist qmlvaluetypes
58\section2 Value Types Provided By QML Modules
60QML modules may extend the QML language with more value types.
62For instance, the value types provided by the \c QtQml module are:
63\annotatedlist qtqmlvaluetypes
65The value types provided by the \c QtQuick module are:
66\annotatedlist qtquickvaluetypes
68The \l{QtQml::Qt}{Qt} global object provides \l{globalqtobjecttypes}{useful functions} for manipulating values of value
69types for the \l{Qt Qml} and \l{Qt Quick} modules.
71Other Qt modules will document their value types on their respective module pages.
73You may define your own value types as described in
74\l{qtqml-cppintegration-definetypes.html}{Defining QML Types from C++}.
75In order to use types provided by a particular QML module, clients
76must import that module in their QML documents.
78\section1 Property Change Behavior for Value Types
80Some value types have properties: for example, the \l font type has
81\c pixelSize, \c family and \c bold properties. Unlike properties of
82\l{qtqml-typesystem-topic.html#qml-object-types}{object types}, properties of
83value types do not provide their own property change signals. It is only possible
84to create a property change signal handler for the value type property itself:
89 onFont.pixelSizeChanged: doSomething()
93 onPixelSizeChanged: doSomething()
97 onFontChanged: doSomething()
101Be aware, however, that a property change signal for a value type is emitted
102whenever \e any of its attributes have changed, as well as when the property itself
103changes. 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
121In contrast, properties of an \l{qtqml-typesystem-topic.html#qml-object-types}{object type}
122emit their own property change signals, and a property change signal handler for an object-type
123property is only invoked when the property is reassigned to a different object value.
129 \ingroup qmlvaluetypes
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 -2147483648 to 2147483647,
135 although most types will only accept a reduced range (which they
136 mention in their documentation).
140 NumberAnimation { loops: 5 }
143 This value type is provided by the QML language.
145 \sa {QML Value Types}
150 \ingroup qmlvaluetypes
151 \brief a binary true/false value.
153 The \c bool type refers to a binary true/false value.
155 Properties of type \c bool have \c false as their default value.
165 This value type is provided by the QML language.
167 \sa {QML Value Types}
172 \ingroup qmlvaluetypes
174 \brief a number with a decimal point.
176 The \c real type refers to a number with decimal point, e.g. 1.2 or -29.8.
180 Item { width: 100.45; height: 150.82 }
183 \note In QML all reals are stored in double precision, \l
184 {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point}
187 This value type is provided by the QML language.
189 \sa {QML Value Types}
194 \ingroup qmlvaluetypes
196 \brief a number with a decimal point, stored in double precision.
198 The \c double type refers to a number with a decimal point and is stored in double precision, \l
199 {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point} format. It's the same as \c real.
201 Properties of type \c double have \e {0.0} as their default value.
206 property double number: 32155.2355
210 This value type is provided by the QML language.
212 \sa {QML Value Types}
217 \ingroup qmlvaluetypes
218 \brief A free form text string.
220 The \c string type refers to a free form text string in quotes, for example
221 "Hello world!". The QML language provides this value type by default.
225 Text { text: "Hello world!" }
228 Properties of type \c string are empty by default.
230 Strings have a \c length attribute that holds the number of characters in
233 The string value type is backed by the C++ type QString. It extends the
234 JavaScript String primitive type in that it provides much of the same API,
235 plus some extra methods. For example, the QML string value type method
236 \c {arg()} supports value substitution:
239 var message = "There are %1 items"
241 console.log(message.arg(count))
244 The example above prints "There are 20 items".
246 The QML string value type supports most of the ECMAScript string features,
247 such as template (string) literals, string interpolation, multi-line
248 strings, and looping over strings.
250 In general, QML string supports most JavaScript String methods, including
251 checking for inclusion using \c string.includes(), \c string.startsWith(),
252 and \c string.endsWith(); repeating a string using \c string.repeats(), and
253 slicing and splitting using \c string.slice() and \c string.split().
255 For more information about which version of ECMAScript QML supports, see
256 \l {JavaScript Host Environment}
258 For more information about JavaScript String methods, see
259 \l {https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String}
260 {mdn JavaScript String}
262 When integrating with C++, note that any QString value
263 \l{qtqml-cppintegration-data.html}{passed into QML from C++} is
264 automatically converted into a \c string value, and vice-versa.
266 \sa {QML Value Types}, {ECMA-262}{ECMAScript Language Specification}
271 \ingroup qmlvaluetypes
272 \brief a resource locator.
274 The \c url type refers to a resource locator (like a file name, for example). It can be either
275 absolute, e.g. "http://qt-project.org", or relative, e.g. "pics/logo.png". A relative URL is
276 resolved relative to the URL of the containing component.
278 For example, the following assigns a valid URL to the \l {Image::source}
279 property, which is of type \c url:
282 Image { source: "pics/logo.png" }
285 When integrating with C++, note that any QUrl value
286 \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
287 converted into a \c url value, and vice-versa.
289 Alternatively you may convert your \c url to a \l{https://developer.mozilla.org/en-US/docs/Web/API/URL}{URL} object
290 in order to access and modify its components:
292 var urlObject = new URL(url);
295 \note In Qt 5, URLs were automatically resolved based on the current context
296 when assigning them to any \c url property. This made it impossible to
297 work with relative URLs and it created inconsistent behavior when reading
298 back a URL previously written to a property. Therefore, the behavior was
299 changed in Qt 6: URLs are not automatically resolved on assignment anymore.
300 The individual elements that use URLs have to resolve them themselves.
302 \note When referring to files stored with the \l{resources.html}{Qt Resource System}
303 from within QML, you should use "qrc:///" instead of ":/" as QML requires URL paths.
304 Relative URLs resolved from within that file will use the same protocol.
306 Additionally, URLs may contain encoded characters using the 'percent-encoding' scheme
307 specified by \l {https://datatracker.ietf.org/doc/html/rfc3986}{RFC 3986}. These characters
308 will be preserved within properties of type \c url, to allow QML code to
309 construct precise URL values.
311 For example, a local file containing a '#' character, which would normally be
312 interpreted as the beginning of the URL 'fragment' element, can be accessed by
313 encoding the characters of the file name:
316 Image { source: encodeURIComponent("/tmp/test#1.png") }
319 This value type is provided by the QML language.
321 \sa {QML Value Types}
327 \ingroup qmlvaluetypes
328 \brief a list of QML objects.
330 The \c list type refers to a list of QML objects or values.
332 Properties of type \c list are empty by default.
334 A \c list can store QML objects or \l{QML Value Types}{value type} values.
336 When integrating with C++, note that any QQmlListProperty value
337 \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
338 converted into a \c list value, and vice-versa.
340 Similarly any \c{QList<T>} of a registered value type \c{T} is automatically
341 converted into a \c list value, and vice-versa.
343 \section1 Using the list Type
345 For example, the \l Item type has a \l {Item::}{states} list-type property that
346 can be assigned to and used as follows:
352 width: 100; height: 100
355 State { name: "activated" },
356 State { name: "deactivated" }
359 Component.onCompleted: {
360 console.log("Name of first state:", states[0].name)
361 for (var i = 0; i < states.length; i++)
362 console.log("state", i, states[i].name)
367 The defined \l State objects will be added to the \c states list
368 in the order in which they are defined.
370 If the list only contains one object, the square brackets may be omitted:
376 width: 100; height: 100
377 states: State { name: "activated" }
381 You can also declare your own list properties in QML:
387 property list<int> intList: [1, 2, 3, 4]
388 property list<QtObject> objectList
392 Lists can be used much like JavaScript arrays. For example:
395 \li Values are assigned using the \c[] square bracket syntax with comma-separated values
396 \li The \c length property provides the number of items in the list
397 \li Values in the list are accessed using the \c [index] syntax
398 \li You can use \c{push()} to append entries
399 \li You can set the \c length property of the list to truncate or extend it.
402 However, you can \e{not} automatically extend the list by assigning to an
403 index currently out of range. Furthermore, if you insert \c null values
404 into a list of objects, those are converted to \c nullptr entries in
405 the underlying QQmlListProperty.
407 A list of value types is different from a JavaScript array in one further
408 important aspect: Growing it by setting its length does not produce undefined
409 entries, but rather default-constructed instances of the value type.
411 Similarly, growing a list of object types this way produces null entries,
412 rather than undefined entries.
414 This value type is provided by the QML language.
416 \sa {QML Value Types}
421 \ingroup qmlvaluetypes
422 \brief a generic property type.
424 The \c var type is a generic property type that can refer to any data type.
426 It is equivalent to a regular JavaScript variable.
427 For example, var properties can store numbers, strings, objects,
428 arrays and functions:
432 property var aNumber: 100
433 property var aBool: false
434 property var aString: "Hello world!"
435 property var anotherString: String("#FF008800")
436 property var aColor: Qt.rgba(0.2, 0.3, 0.4, 0.5)
437 property var aRect: Qt.rect(10, 10, 10, 10)
438 property var aPoint: Qt.point(10, 10)
439 property var aSize: Qt.size(10, 10)
440 property var aVector3d: Qt.vector3d(100, 100, 100)
441 property var anArray: [1, 2, 3, "four", "five", (function() { return "six"; })]
442 property var anObject: { "foo": 10, "bar": 20 }
443 property var aFunction: (function() { return "one"; })
447 \section1 Change Notification Semantics
449 It is important to note that changes in regular properties of JavaScript
450 objects assigned to a var property will \b{not} trigger updates of bindings
451 that access them. The example below will display "The car has 4 wheels" as
452 the change to the wheels property will not cause the reevaluation of the
453 binding assigned to the "text" property:
457 property var car: new Object({wheels: 4})
460 text: "The car has " + car.wheels + " wheels";
463 Component.onCompleted: {
469 If the onCompleted handler instead had \tt{"car = new Object({wheels: 6})"}
470 then the text would be updated to say "The car has 6 wheels", since the
471 car property itself would be changed, which causes a change notification
474 \section1 Property Value Initialization Semantics
476 The QML syntax defines that curly braces on the right-hand-side of a
477 property value initialization assignment denote a binding assignment.
478 This can be confusing when initializing a \c var property, as empty curly
479 braces in JavaScript can denote either an expression block or an empty
480 object declaration. If you wish to initialize a \c var property to an
481 empty object value, you should wrap the curly braces in parentheses.
483 Properties of type \c var are \c {undefined} by default.
488 property var first: {} // nothing = undefined
489 property var second: {{}} // empty expression block = undefined
490 property var third: ({}) // empty object
494 In the previous example, the \c first property is bound to an empty
495 expression, whose result is undefined. The \c second property is bound to
496 an expression which contains a single, empty expression block ("{}"), which
497 similarly has an undefined result. The \c third property is bound to an
498 expression which is evaluated as an empty object declaration, and thus the
499 property will be initialized with that empty object value.
501 Similarly, a colon in JavaScript can be either an object property value
502 assignment, or a code label. Thus, initializing a var property with an
503 object declaration can also require parentheses:
507 property var first: { example: 'true' } // example is interpreted as a label
508 property var second: ({ example: 'true' }) // example is interpreted as a property
509 property var third: { 'example': 'true' } // example is interpreted as a property
510 Component.onCompleted: {
511 console.log(first.example) // prints 'undefined', as "first" was assigned a string
512 console.log(second.example) // prints 'true'
513 console.log(third.example) // prints 'true'
518 \sa {QML Value Types}
522 \qmlvaluetype variant
523 \ingroup qmlvaluetypes
524 \brief a generic property type.
526 The \c variant type is the same as the \c var type. Use \c var instead.
528 \sa {QML Value Types}
533 \ingroup qmlvaluetypes
534 \brief The empty value type.
536 The \c void type is exclusively used to type-annotate JavaScript functions
537 returning \c undefined. For example:
540 function doThings() : void { console.log("hello") }
543 This is to help tooling analyze calls to such functions and compile them and
544 their callers to C++.
546 You cannot declare \c void properties in QML.
548 \sa {QML Value Types}
552 \qmlvaluetype enumeration
553 \ingroup qmlvaluetypes
554 \brief a named enumeration value.
556 The \c enumeration type refers to a named enumeration value.
558 Each named value can be referred to as \c {<Type>.<value>}. For
559 example, the \l Text type has an \c AlignRight enumeration value:
562 Text { horizontalAlignment: Text.AlignRight }
565 (For backwards compatibility, the enumeration value may also be
566 specified as a string, e.g. "AlignRight". This form is not
567 recommended for new code.)
569 When integrating with C++, note that any \c enum value
570 \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
571 converted into an \c enumeration value, and vice-versa.
573 This value type is provided by the QML language. Some enumeration values
574 are provided by the QtQuick import.
576 \section1 Using the enumeration Type in QML
578 The \c enumeration type is a representation of a C++ \c enum type. It is
579 not possible to refer to the \c enumeration type in QML itself; instead, the
580 \l int or \l var types can be used when referring to \c enumeration values
589 // refer to Text.AlignRight using an int type
590 property int enumValue: textItem.horizontalAlignment
592 signal valueEmitted(int someValue)
596 horizontalAlignment: Text.AlignRight
599 // emit valueEmitted() signal, which expects an int, with Text.AlignRight
600 Component.onCompleted: valueEmitted(Text.AlignRight)
604 \sa {QML Value Types}
605 \sa {qtqml-syntax-objectattributes.html#enumeration-attributes}{Enumeration Attributes}