- Qt 6.10
- Qt Qml
- The QML Reference
- The QML Type System
- QML Value Type and Sequence References
- Qt 6.10.2 Reference Documentation

QML Namespaces ◦ QML Modules

# QML Value Type and Sequence References

QML Value Types and QML Sequence Types are necessarily passed by value. In contrast to QML Object Types they have no identity of themselves, but can only be accessed as properties of other objects or values, or as values returned from methods. Each such access implicitly creates a copy. Yet, in JavaScript everything is an object. There is no such concept as a value type in JavaScript. For example, if you execute `font.bold = true` in JavaScript, we expect the `bold` property of `font` to be set, no matter what `font` is. But consider the following code snippet:

     import QtQuick
     Text {
         onSomethingHappened: font.bold = true
     }

In this case we know that `font` is a value type. Accessing it creates a local copy by calling the getter of a Q_PROPERTY. We can then set the `bold` property on it, but that would usually only affect the copy, not the original Q_PROPERTY.

To overcome this problem, QML offers the concept of references. When you retrieve an instance of a value or sequence type from a property, the QML engine remembers the property along with the value itself. If the value is modified, it is written back to the property. This produces the illusion of an object with separate identity and makes the above case, along with many others, just work.

This can be rather expensive, though. If a sequence is exposed as a Q_PROPERTY, accessing any value in the sequence by index will cause the whole sequence data to be read from the property. From this sequence data, a single element is then retrieved. Similarly, modifying any value in the sequence causes the sequence data to be read. Then the modification is performed and the modified sequence is be written back to the property. A read operation can be relatively cheap if the type in question is implicitly shared. A modification always incurs at least one deep copy.

If you return an instance of a sequence or value type from a Q_INVOKABLE function you avoid such overhead. Return values are not attached to any property and won't be written back.

Sequences of object types are passed as QQmlListProperty by default. QQmlListProperty is not an actual container, but only a view, or reference, to some sequential storage. Therefore, QQmlListProperty is not affected by this effect. You can, however, register other sequence types for objects using QML_SEQUENTIAL_CONTAINER. Those will be affected.