Qt Reference Documentation

- Qt 4.8
- ALL VERSIONS

- A
- A
- A
- Print

# QML Syntax

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.

JavaScript is used as a scripting language in QML, so you may want to learn a bit more about it (Javascript Guide) before diving deeper into QML.

## 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
         }
     }

Objects are specified by their type, followed by a pair of braces. Object types always begin with a capital letter. In the above example, there are two objects, a Rectangle, and an Image. Between the braces, we can specify information about the object, such as its properties.

Properties are specified as `propertyname: value`. In the above example, we can see the Image 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 `Qt` module, which contains all of the standard QML Elements. Without this import statement, the Rectangle and Image elements would not be available.

## Expressions

In addition to assigning values to properties, you can also assign expressions written in JavaScript.

     Rotation {
         angle: 360 * 3
     }

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 the expression has been assigned to is automatically updated to that value.

     Item {
         Text {
             id: text1
             text: "Hello World"
         }
         Text {
             id: text2
             text: text1.text
         }
     }

In the example above, the `text2` object will display the same text as `text1`. If `text1` is changed, `text2` is automatically changed to the same value.

Note that to refer to other objects, we use their id values. (See below for more information on the id property.)

## QML 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.