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.