- Qt 6.9
- Qt Quick
- Best Practices for QML and Qt Quick
- QML Coding Conventions
- Qt 6.9.3 Reference Documentation

Best Practices for QML and Qt Quick ◦ Scalability

# QML Coding Conventions

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

## QML object declarations

Throughout our documentation and examples, QML object attributes are always structured in the following order:

- id
- property declarations
- signal declarations
- JavaScript functions
- object properties
- child objects

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                                                   // try to group related properties together
         y: 20
         height: 150
         width: {                                                // large bindings
             if (photoImage.width > 200) {
                 photoImage.width;
             } else {
                 200;
             }
         }

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

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

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

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

## Grouped properties

If using multiple properties from a group of properties, consider using group notation instead of dot notation if it improves 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
     }

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

## Unqualified access

In order to improve readability and performance always reference properties of parent components by their id explicitly:

     Item {
         id: root

         property int rectangleWidth: 50

         Rectangle {
             width: root.rectangleWidth
         }
     }

## Required properties

When requiring data defined outside the component, make this explicit by using Required Properties. Required properties must be set or else the creation of the component will fail. These are preferable to unqualified lookups because they are more performant and allow for both users and tooling to reason about an external property's type. Additionally they remove assumptions that a component otherwise has to make about the environment in which it is created.

## Signal handlers

When handling parameters in signal handlers use functions which name them explicitly:

     MouseArea {
         onClicked: event => { console.log(`${event.x},${event.y}`); }
     }

## JavaScript code

For better readability and maintainability, we generally declare each property on a separate line, even for simple expressions.

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

For script expressions spanning multiple lines, we use a block format:

     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 : Item) : double
     {
         var w = object.width / 3;
         // ...
         // more javascript code
         // ...
         console.debug(w);
         return w;
     }

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

Also note that is recommended to add type annotations to your function in order to more easily reason about and refactor your application since both parameter and return types are immediately visible from the function signature.

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

If the code is longer than one line and hence within a block, we use semicolons to indicate the end of each statement:

     MouseArea {
         anchors.fill: parent
         onClicked: event => {
             var scenePos = mapToItem(null, event.x, event.y);
             console.log("MouseArea was clicked at scene pos " + scenePos);
         }
     }