variant QML Basic Type | Qt QML 5.9

Qt 5.9 | Qt QML | QML Types | variant QML Basic Type

Qt 5.9.3 Reference Documentation

# variant QML Basic Type

a generic property type.

The `variant` type is a generic property type. It is obsolete and exists only to support old applications; new applications should use var type properties instead.

A variant type property can hold any of the basic type values:

      Item {
          property variant aNumber: 100
          property variant aString: "Hello world!"
          property variant aBool: false
      }

When integrating with C++, note that any QVariant value passed into QML from C++ is automatically converted into a `variant` value, and vice-versa.

## Using Scarce Resources with the variant Type

A `variant` type property can also hold an image or pixmap. A `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 `variant` property from within JavaScript. They may also explicitly preserve the scarce resource by calling the "preserve" method on the `variant` property from within JavaScript.

## Storing Arrays and Objects

The `variant` type can also hold:

- An array of basic type values
- A map of key-value pairs with basic-type values

For example, below is an `items` array and an `attributes` map. Their contents can be examined using JavaScript `for` loops. Individual array values are accessible by index, and individual map values are accessible by key:

      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])
          }
      }

While this is a convenient way to store array and map-type values, you must be aware that the `items` and `attributes` properties above are not QML objects (and certainly not JavaScript object either) and the key-value pairs in `attributes` are not QML properties. Rather, the `items` property holds an array of values, and `attributes` holds a set of key-value pairs. Since they are stored as a set of values, instead of as an object, their contents cannot be modified individually:

      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'!
          }
      }

Since it is not possible to individually add or remove items from a list or object stored in a `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 `items` and `attributes` are not QML objects, changing their individual values do not trigger property change notifications. If the above example had `onNumberChanged` or `onAnimalChanged` signal handlers, they would not have been called. If, however, the `items` or `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 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.

See also QML Basic Types.