QML Value Types
QML supports built-in and custom value types.
A value type is one that is conceptually passed by value rather than by reference, such as an int
or a string
. This contrasts with QML Object Types. Object types are passed by reference. If you assign an instance of an object type to two different properties, both properties carry the same value. Modifying the object is reflected in both properties. If you assign an instance of a value type to two different properties, the properties carry separate values. If you modify one of them, the other one stays the same. Value types are only conceptually passed by value since it must still be possible to interact with them as if they were JavaScript objects. To facilitate this, in reality they are passed as Value Type References when you access them from JavaScript code.
Unlike an object type, a value type cannot be used to declare QML objects: it is not possible, for example, to declare an int{}
object or a size{}
object.
Value types can be used to refer to:
- A single value (e.g. int refers to a single number)
- A value that contains properties and methods (e.g. size refers to a value with
width
andheight
properties) - The generic type var. It can hold values of any other type but is itself a value type.
When a variable or property holds a value type and it is assigned to another variable or property, then a copy of the value is made.
Available Value Types
Some value types are supported by the engine by default and do not require an import statement to be used, while others do require the client to import the module which provides them. All of the value types listed below may be used as a property
type in a QML document, with the following exceptions:
void
, which marks the absence of a valuelist
must be used in conjunction with an object or value type as elementenumeration
cannot be used directly as the enumeration must be defined by a registered QML object type
Built-in Value Types Provided By The QML Language
The built-in value types supported natively in the QML language are listed below:
Binary true/false value | |
Date value | |
Number with a decimal point, stored in double precision | |
Named enumeration value | |
Whole number, e.g. 0, 10, or -20 | |
List of QML objects | |
Number with a decimal point | |
A free form text string | |
Resource locator | |
Generic property type | |
Generic property type | |
Empty value type |
Value Types Provided By QML Modules
QML modules may extend the QML language with more value types.
For instance, the value types provided by the QtQml
module are:
Value with x and y attributes | |
Value with x, y, width and height attributes | |
Value with width and height attributes |
The value types provided by the QtQuick
module are:
ARGB color value | |
Font value with the properties of QFont. The font type refers to a font value with the properties of QFont | |
A matrix4x4 type is a 4-row and 4-column matrix | |
A quaternion type has scalar, x, y, and z attributes | |
A vector2d type has x and y attributes | |
Value with x, y, and z attributes | |
A vector4d type has x, y, z and w attributes |
The Qt global object provides useful functions for manipulating values of value types for the Qt Qml and Qt Quick modules.
Other Qt modules will document their value types on their respective module pages.
You may define your own value types as described in Defining QML Types from C++. In order to use types provided by a particular QML module, clients must import that module in their QML documents.
Property Change Behavior for Value Types
Some value types have properties: for example, the font type has pixelSize
, family
and bold
properties. Unlike properties of object types, properties of value types do not provide their own property change signals. It is only possible to create a property change signal handler for the value type property itself:
Text { // invalid! onFont.pixelSizeChanged: doSomething() // also invalid! font { onPixelSizeChanged: doSomething() } // but this is ok onFontChanged: doSomething() }
Be aware, however, that a property change signal for a value type is emitted whenever any of its attributes have changed, as well as when the property itself changes. Take the following code, for example:
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 }
In contrast, properties of an 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.
See also The QML Type System.
© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.