QML Coding Conventions

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

 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
 }

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

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

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

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

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

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

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

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

 import "myscript.js" as Script

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