QML Coding Conventions

This document contains the QML coding conventions that we follow in our documentation and examples and recommend that others follow.

This page assumes that you are already familiar with the QML language. If you need an introduction to the language, please read the QML introduction first.

QML Objects

Through our documentation and examples, QML objects are always structured in the following order:

id
property declarations
signal declarations
JavaScript functions
object properties
child objects
states
transitions

For better readability, we separate these different parts with an empty line.

For example, a hypothetical photo QML object would look like this:

 Rectangle {
     id: photo                                               // id on the first line makes it easy to find an object

     property bool thumbnail: false                          // property declarations
     property alias image: photoImage.source

     signal clicked                                          // signal declarations

     function doSomething(x)                                 // javascript functions
     {
         return x + photoImage.width
     }

     color: "gray"                                           // object properties
     x: 20; y: 20; height: 150                               // try to group related properties together
     width: {                                                // large bindings
         if(photoImage.width > 200){
             photoImage.width;
         }else{
             200;
         }
     }

     Rectangle {                                             // child objects
         id: border
         anchors.centerIn: parent; color: "white"

         Image { id: photoImage; anchors.centerIn: parent }
     }

     states: State {                                         // states
         name: "selected"
         PropertyChanges { target: border; color: "red" }
     }

     transitions: Transition {                               // transitions
         from: ""; to: "selected"
         ColorAnimation { target: border; duration: 200 }
     }
 }

Grouped Properties

If using multiple properties from a group of properties, we use the group notation rather than the dot notation to improve readability.

For example, this:

 Rectangle {
     anchors.left: parent.left; anchors.top: parent.top; anchors.right: parent.right; anchors.leftMargin: 20
 }

 Text {
     text: "hello"
     font.bold: true; font.italic: true; font.pixelSize: 20; font.capitalization: Font.AllUppercase
 }

can be written like this:

 Rectangle {
     anchors { left: parent.left; top: parent.top; right: parent.right; leftMargin: 20 }
 }

 Text {
     text: "hello"
     font { bold: true; italic: true; pixelSize: 20; capitalization: Font.AllUppercase }
 }

Private Properties

QML and JavaScript do not enforce private properties like C++. There is a need to hide these private properties, for example, when the properties are part of the implementation. To effectively gain private properties in a QML Item, the convention is to add a QtObject{} child to contain the properties. This shields them from being accessed outside the file in QML and JavaScript. As it involves the creation of another object, it is more expensive than just creating a property. To minimize the performance cost, try to group all private properties in one file into the same QtObject.

 Item {
     id: component
     width: 40; height: 50
     QtObject {
         id: d
         property real area: width * height * 0.5    //not meant for outside use
     }
 }

Lists

If a list contains only one element, we generally omit the square brackets.

For example, it is very common for a component to only have one state.

In this case, instead of:

 states: [
     State {
         name: "open"
         PropertyChanges { target: container; width: 200 }
     }
 ]

we will write this:

 states: State {
     name: "open"
     PropertyChanges { target: container; width: 200 }
 }

JavaScript Code

If the script is a single expression, we recommend writing it inline:

 Rectangle { color: "blue"; width: parent.width / 3 }

If the script is only a couple of lines long, we generally use a block:

 Rectangle {
     color: "blue"
     width: {
         var w = parent.width / 3
         console.debug(w)
         return w
     }
 }

If the script is more than a couple of lines long or can be used by different objects, we recommend creating a function and calling it like this:

 function calculateWidth(object)
 {
     var w = object.width / 3
     // ...
     // more javascript code
     // ...
     console.debug(w)
     return w
 }

 Rectangle { color: "blue"; width: calculateWidth(parent) }

For long scripts, we will put the functions in their own JavaScript file and import it like this:

 import "myscript.js" as Script

 Rectangle { color: "blue"; width: Script.calculateWidth(parent) }

Contents