QML is a multi-paradigm language that enables defining objects in terms of their attributes and how they relate and respond to changes in other objects. In contrast to purely imperative code, where you express changes in properties and behavior through a series of statements that are processed step-by-step, QML's declarative syntax integrates attribute and behavioral changes directly into the definitions of individual objects. These property definitions can also include imperative code when you need complex custom application behavior.

The QML engine loads the source code through QML documents, which are standalone documents of QML code. Use these QML documents to define QML object types that you can reuse throughout an application.

Import statements

A QML document may have one or more imports at the top of the file.

The generic form of the various imports are as follows:

• import <ModuleIdentifier> [as <Qualifier>]

Examples:

import QtQuick
import QtQuick.Controls
import QtQuick as CoreItems

For in-depth information about QML imports, see import statements.

Object declarations

Syntactically, a block of QML code defines a tree of QML objects. You can define objects using object declarations that describe the type of object as well as its properties. Each object declaration may also include its child object declaration as a nested entity.

An object declaration begins with the name of its object type, followed by a set of curly braces. You declare all the properties and child objects within these braces.

Here is a simple object declaration:

Rectangle {
    width: 100
    height: 100
    color: "red"
}

This declares a Rectangle type object and its properties. The Rectangle type is provided by the QtQuick QML module, and the properties defined in this case are the values of the rectangle's width, height, and color. You can also include other properties, refer to the Rectangle QML type documentation for more information.

The object of Rectangle type is instantiated if it's part of a QML document, which imports the QtQuick QML module (to make the Rectangle type available). That is, complement the earlier source code with an import statement as shown in the following example:

import QtQuick

Rectangle {
    width: 100
    height: 100
    color: "red"
}

When a Qt for MCUs application loads the .qml document, a Rectangle object is created with the given properties:

Alternatively, you can also define a small number of object properties on a single line, as shown in the following example:

Rectangle { width: 100; height: 100; color: "red" }

The Rectangle object that you defined earlier is obviously very simple, as it defines a few properties only. To create more useful objects, consider defining objects with many other properties as described in QML object attributes. Additionally, you can also define child objects, as shown in the following section.

Child objects

Any object declaration can include nested object declarations defining its child objects. This means an object declaration implicitly defines an object tree that may include any number of child objects.

For example, the following Rectangle object declaration includes a Gradient object declaration, which in turn contains two GradientStop declarations:

import QtQuick

Rectangle {
    width: 100
    height: 100

    gradient: Gradient {
        GradientStop { position: 0.0; color: "yellow" }
        GradientStop { position: 1.0; color: "green" }
    }
}

This earlier code defines an object tree with a Rectangle object at the root that has a Gradient child object, which in turn has two GradientStop children.

The parent-child relationship that you see in the earlier example is an important concept in the context of a QML object tree. A similar concept is also available in the context of a visual scene, which is represented by the Item QML type. The Item type is the base type for most QML types, as most QML objects are intended to be visually rendered. For example, Rectangle and Text are both Item-based types, which means you can declare a Text object as a visual child of a Rectangle object:

import QtQuick

Rectangle {
    width: 200
    height: 200
    color: "red"

    Text {
        anchors.centerIn: parent
        text: "Hello, QML!"
    }
}

In this earlier example, you see that the Text object refers to its visual parent using the parent value, and not the parent in the object tree. Although in this case, the Rectangle object is the parent of the Text object, in both the context of the QML object tree as well as the visual scene.

However, you can change the visual parent of an object, but you cannot change the parent of an object in the context of the object tree.

Refer to visual parent for more information on the visual parenting concept with the Item type.

Comments

The syntax for commenting in QML is similar to that of JavaScript. The following example illustrates both the single line and multiline comments available in QML:

Text {
text: "Hello world!"    //a basic greeting
/*
    We want this text to stand out from the rest so
    we give it a large size and different font.
*/
font.family: "Helvetica"
font.pointSize: 24
}

The QML engine ignores the comments when processing QML code. The comments are useful for explaining what a section of code is doing, either for reference or for describing the implementation to others.

You can also use comments to prevent the execution of code, which is sometimes useful to diagnose problems.

Text {
    text: "Hello world!"
    //opacity: 0.5
}

In the earlier example, the Text object's opacity will not change as the line, opacity: 0.5, is a single line comment.