Introduction to the QML Language

QML is a declarative language designed to describe the user interface of a program: both what it looks like, and how it behaves. In QML, a user interface is specified as a tree of objects with properties.

This introduction is meant for those with little or no programming experience. JavaScript is used as a scripting language in QML, so you may want to learn a bit more about it (see the Javascript Guide) before diving deeper into QML. It's also helpful to have a basic understanding of other web technologies like HTML and CSS, but it's not required.

Basic QML Syntax

QML looks like this:

 import QtQuick 1.0

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

     Image {
         source: "pics/logo.png"
         anchors.centerIn: parent
     }
 }

Here we create two objects, a Rectangle object and its child Image object. Objects are specified by their type, followed by a pair of braces in between which additional data can be defined for the object, such as its property values and any child objects.

Properties are specified with a property: value syntax. In the above example, we can see the Image object has a property named source, which has been assigned the value "pics/logo.png". The property and its value are separated by a colon.

Properties can be specified one-per-line:

 Rectangle {
     width: 100
     height: 100
 }

or you can put multiple properties on a single line:

 Rectangle { width: 100; height: 100 }

When multiple property/value pairs are specified on a single line, they must be separated by a semicolon.

The import statement imports the QtQuick module, which contains all of the standard QML Elements. Without this import statement, the Rectangle and Image elements would not be available.

Comments

Commenting in QML is similar to JavaScript.

• Single line comments start with // and finish at the end of the line.
• Multiline comments start with /* and finish with */

 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
 }

Comments are ignored by the engine. They are useful for explaining what you are doing; for referring back to at a later date, or for others reading your QML files.

Comments can also be used to prevent the execution of code, which is sometimes useful for tracking down problems.

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

In the above example, the Text object will have normal opacity, since the line opacity: 0.5 has been turned into a comment.

Object Identifiers

Each object can be given a special id value that allows the object to be identified and referred to by other objects.

For example, below we have two Text objects. The first Text object has an id value of "text1". The second Text object can now set its own text property value to be the same as that of the first object, by referring to text1.text:

 import QtQuick 1.0

 Row {
     Text {
         id: text1
         text: "Hello World"
     }

     Text { text: text1.text }
 }

An object can be referred to by its id from anywhere within the component in which it is declared. Therefore, an id value must always be unique within a single component.

The id value is a special value for a QML object and should not be thought of as an ordinary object property; for example, it is not possible to access text1.id in the above example. Once an object is created, its id cannot be changed.

Note that an id must begin with a lower-case letter or an underscore, and cannot contain characters other than letters, numbers and underscores.

Expressions

JavaScript expressions can be used to assign property values. For example:

 Item {
     width: 100 * 3
     height: 50 + 22
 }

These expressions can include references to other objects and properties, in which case a binding is established: when the value of the expression changes, the property to which the expression is assigned is automatically updated to the new value. For example:

 Item {
     width: 300
     height: 300

     Rectangle {
         width: parent.width - 50
         height: 100
         color: "yellow"
     }
 }

Here, the Rectangle object's width property is set relative to the width of its parent. Whenever the parent's width changes, the width of the Rectangle is automatically updated.

Properties

Basic Property Types

QML supports properties of many types (see QML Basic Types). The basic types include int, real, bool, string and color.

 Item {
     x: 10.5             // a 'real' property
     state: "details"    // a 'string' property
     focus: true         // a 'bool' property
     // ...
 }

QML properties are what is known as type-safe. That is, they only allow you to assign a value that matches the property type. For example, the x property of item is a real, and if you try to assign a string to it you will get an error.

 Item {
     x: "hello"  // illegal!
 }

Note that with the exception of Attached Properties, properties always begin with a lowercase letter.

Property Change Notifications

When a property changes value, it can send a signal to notify others of this change.

To receive these signals, simply create a signal handler named with an on<Property>Changed syntax. For example, the Rectangle element has width and color properties. Below, we have a Rectangle object that has defined two signal handlers, onWidthChanged and onColorChanged, which will automaticallly be called whenever these properties are modified:

 Rectangle {
     width: 100; height: 100

     onWidthChanged: console.log("Width has changed to:", width)
     onColorChanged: console.log("Color has changed to:", color)
 }

Signal handlers are explained further below.

List properties

List properties look like this:

 Item {
     children: [
         Image {},
         Text {}
     ]
 }

The list is enclosed in square brackets, with a comma separating the list elements. In cases where you are only assigning a single item to a list, you can omit the square brackets:

 Image {
     children: Rectangle {}
 }

Items in the list can be accessed by index. See the list type documentation for more details about list properties and their available operations.

Default Properties

Each object type can specify one of its list or object properties as its default property. If a property has been declared as the default property, the property tag can be omitted.

For example this code:

 State {
     changes: [
         PropertyChanges {},
         PropertyChanges {}
     ]
 }

can be simplified to:

 State {
     PropertyChanges {}
     PropertyChanges {}
 }

because changes is the default property of the State type.

Grouped Properties

In some cases properties form a logical group and use a 'dot' or grouped notation to show this.

Grouped properties can be written like this:

 Text {
     font.pixelSize: 12
     font.bold: true
 }

or like this:

 Text {
     font { pixelSize: 12; bold: true }
 }

In the element documentation grouped properties are shown using the 'dot' notation.

Attached Properties

Some objects attach properties to another object. Attached Properties are of the form Type.property where Type is the type of the element that attaches property.

For example, the ListView element attaches the ListView.isCurrentItem property to each delegate it creates:

 Component {
     id: myDelegate
     Text {
         text: "Hello"
         color: ListView.isCurrentItem ? "red" : "blue"
     }
 }

 ListView {
     delegate: myDelegate
 }

Another example of attached properties is the Keys element which attaches properties for handling key presses to any visual Item, for example:

 Item {
     focus: true
     Keys.onSelectPressed: console.log("Selected")
 }

Signal Handlers

Signal handlers allow JavaScript code to be executed in response to an event. For example, the MouseArea element has an onClicked handler that can be used to respond to a mouse click. Below, we use this handler to print a message whenever the mouse is clicked:

 Item {
     width: 100; height: 100

     MouseArea {
         anchors.fill: parent
         onClicked: {
             console.log("mouse button clicked")
         }
     }
 }

All signal handlers begin with "on".

Some signal handlers include an optional parameter. For example the MouseArea onPressed signal handler has a mouse parameter that contains information about the mouse press. This parameter can be referred to in the JavaScript code, as below:

 MouseArea {
     acceptedButtons: Qt.LeftButton | Qt.RightButton
     onPressed: {
         if (mouse.button == Qt.RightButton)
             console.log("Right mouse button pressed")
     }
 }