QML Object Attributes

A property may be defined for a type in C++ by registering a Q_PROPERTY of a class which is then registered with the QML type system. Alternatively, a custom property of an object type may be defined in an object declaration in a QML document with the following syntax:

[default] [required] [readonly] property <propertyType> <propertyName>

In this way an object declaration may expose a particular value to outside objects or maintain some internal state more easily.

Property names must begin with a lower case letter and can only contain letters, numbers and underscores. JavaScript reserved words are not valid property names. The default, required, and readonly keywords are optional, and modify the semantics of the property being declared. See the upcoming sections on default properties, required properties and, read-only properties for more information about their respective meaning.

Declaring a custom property implicitly creates a value-change signal for that property, as well as an associated signal handler called on<PropertyName>Changed, where <PropertyName> is the name of the property, with the first letter capitalized.

For example, the following object declaration defines a new type which derives from the Rectangle base type. It has two new properties, with a signal handler implemented for one of those new properties:

Rectangle {
    property color previousColor
    property color nextColor
    onNextColorChanged: console.log("The next color will be: " + nextColor.toString())
}

Valid Types in Custom Property Definitions▲

Item {
    property int someNumber
    property string someString
    property url someUrl
}

property var someNumber: 1.5
property var someString: "abc"
property var someBool: true
property var someList: [1, 2, "three", "four"]
property var someObject: Rectangle { width: 100; height: 100; color: "red" }

property Item someItem
property Rectangle someRectangle

The value of a property of an object instance may be specified in two separate ways:

• a value assignment on initialization

• an imperative value assignment

In either case, the value may be either a static value or a binding expression value.

Value Assignment on Initialization▲

<propertyName> : <value>

[default] property <propertyType> <propertyName> : <value>

import QtQuick 2.0

Rectangle {
    color: "red"
    property color nextColor: "blue" // combined property declaration and initialization
}

Imperative Value Assignment▲

[<objectId>.]<propertyName> = value

import QtQuick 2.0

Rectangle {
    id: rect
    Component.onCompleted: {
        rect.color = "red"
    }
}

As previously noted, there are two kinds of values which may be assigned to a property: static values, and binding expression values. The latter are also known as property bindings.

Here is an example that shows both kinds of values being assigned to properties:

import QtQuick 2.0

Rectangle {
    // both of these are static value assignments on initialization
    width: 400
    height: 200

    Rectangle {
        // both of these are binding expression value assignments on initialization
        width: parent.width / 2
        height: parent.height
    }
}

Properties are type safe. A property can only be assigned a value that matches the property type.

For example, if a property is a real, and if you try to assign a string to it, you will get an error:

property int volume: "four"  // generates an error; the property's object will not be loaded

Likewise if a property is assigned a value of the wrong type during run time, the new value will not be assigned, and an error will be generated.

Some property types do not have a natural value representation, and for those property types the QML engine automatically performs string-to-typed-value conversion. So, for example, even though properties of the color type store colors and not strings, you are able to assign the string "red" to a color property, without an error being reported.

See QML Basic Types for a list of the types of properties that are supported by default. Additionally, any available QML object type may also be used as a property type.

Object List Property Attributes▲

[ <item 1>, <item 2>, ... ]

import QtQuick 2.0

Item {
    states: [
        State { name: "loading" },
        State { name: "running" },
        State { name: "stopped" }
    ]
}

import QtQuick 2.0

Item {
    states: State { name: "running" }
}

[default] property list<<objectType>> propertyName

[default] property list<<objectType>> propertyName: <value>

import QtQuick 2.0

Rectangle {
    // declaration without initialization
    property list<Rectangle> siblingRects

    // declaration with initialization
    property list<Rectangle> childRects: [
        Rectangle { color: "red" },
        Rectangle { color: "blue"}
    ]
}

Grouped Properties▲

Text {
    //dot notation
    font.pixelSize: 12
    font.b: true
}

Text {
    //group notation
    font { pixelSize: 12; b: true }
}

Property aliases are properties which hold a reference to another property. Unlike an ordinary property definition, which allocates a new, unique storage space for the property, a property alias connects the newly declared property (called the aliasing property) as a direct reference to an existing property (the aliased property).

A property alias declaration looks like an ordinary property definition, except that it requires the alias keyword instead of a property type, and the right-hand-side of the property declaration must be a valid alias reference:

[default] property alias <name>: <alias reference>

Unlike an ordinary property, an alias has the following restrictions:

• It can only refer to an object, or the property of an object, that is within the scope of the type within which the alias is declared.

• It cannot contain arbitrary JavaScript expressions

• It cannot refer to objects declared outside of the scope of its type.

• The alias reference is not optional, unlike the optional default value for an ordinary property; the alias reference must be provided when the alias is first declared.

• It cannot refer to attached properties.

• It cannot refer to properties inside a hierarchy with depth 3 or greater. The following code will not work:

   

  Sélectionnez

  property alias color: myItem.myRect.border.color
  
  Item {
      id: myItem
      property Rectangle myRect
  }

  However, aliases to properties that are up to two levels deep will work.

   

  Sélectionnez

  property alias color: rectangle.border.color
  
  Rectangle {
      id: rectangle
  }

For example, below is a Button type with a buttonText aliased property which is connected to the text object of the Text child: