Furkan Uzumcu

• Started using QML in 2017
• ❤️ Open Source
• ❤️ [Split] Mechanical Keyboards
• Working at Autodesk
• Furkanzmc @ GitHub
• Furkanzmc @ Twitter
• Website: https://zmc.space

Yet another guideline?..

• Official Best Practices for QML and Qt Quick from Qt
• QML Best Practices Search

Guidelines are NOT…

• Unchangeable
• The absolute truth
• Be all end all

Guidelines are for…

• Making code easier to:
  • read
  • understand
  • maintain
• Making it easier to detect errors or pitfalls
• Low barrier knowledge for new comers
• Aid in tooling

How to Read QML Code

// CircleMouseArea.qml
Item {
    id: root

    property int radius

    signal clicked(MouseEvent mouse)

    implicitWidth: 50
    implicitHeight: 50

    Rectangle {
        width: parent.width / 2
        height: height
        radius: root.radius
    }

    MouseArea {
        // If mouse click is inside the circle, emits root.clicked(mouse)
    }
}

Code Order

• id
• Property declarations
• Signal declarations
• Property initializations
• Attached properties and signal handlers
• States
• Transitions
• Signal handlers
• Child objects
  • Visual Items
  • Qt provided non-visual items
  • Custom non-visual items
• QtObject for encapsulating private members[1]
• JavaScript functions

Full Example

// First Qt imports
import QtQuick 2.15
import QtQuick.Controls 2.15
// Then custom imports
import my.library 1.0

Item {
    id: root

    // ----- Property Declarations

    // Required properties should be at the top.
    required property int radius: 0

    property int radius: 0
    property color borderColor: "blue"

    // ----- Signal declarations

    signal clicked()
    signal doubleClicked()

    // ----- In this section, we group the size and position information together.

    x: 0
    y: 0
    z: 0
    width: 100
    height: 100
    anchors.top: parent.top // If a single assignment, dot notation can be used.
    // If the item is an image, sourceSize is also set here.
    // sourceSize: Qt.size(12, 12)

    // ----- Then comes the other properties. There's no predefined order to these.

    // Do not use empty lines to separate the assignments. Empty lines are reserved
    // for separating type declarations.
    enabled: true
    layer.enabled: true

    // ----- Then attached properties and attached signal handlers.

    Layout.fillWidth: true
    Drag.active: false
    Drag.onActiveChanged: { }

    // ----- States and transitions.

    states: [ State { } ]
    transitions: [ Transitions { } ]

    // ----- Signal handlers

    onWidthChanged: { } // Always use curly braces.
    // onCompleted and onDestruction signal handlers are always the last in
    // the order.
    Component.onCompleted: { }
    Component.onDestruction: { }

    // ----- Visual children.

    Rectangle {
        height: 50
        anchors: { // For multiple assignments, use group notation.
            top: parent.top
            left: parent.left
            right: parent.right
        }
        color: "red"
        layer.enabled: true
    }

    // ----- Qt provided non-visual children

    Timer { }

    // ----- Custom non-visual children

    MyCustomNonVisualType { }

    QtObject {
        id: privates

        property int diameter: 0
    }

    // ----- JavaScript functions

    function collapse() { }

    function setCollapsed(value: bool) { }
}

Declarative 2

Is this still declarative?

ListView {
    model: ContactModel { }
    delegate: Label {
        required property int index
        required property string name

        text: getText()

        function getText(): string {
            return index + ". " + name
        }
    }
}

void MyRectangle::setRadius(int r)
{
    m_radius = r;
    emit radiusChanged();
}

1. Context properties [Deprecated]
2. Global object
3. Singletons
4. Instantiated object

Context Properties Are Deprecated

Don’t use them.

QTBUG-73064

Item {
    id: root

    property int borderWidth

    Rectangle {
        // No no...
        border.width: borderWidth
    }
}

Singletons for API Access

Window {
    onClosing: (event) => {
        event.accepted = MySingletonClass.confirmExit()
    }

    Button {
        background: Rectangle {
            color: Theme.buttonBackground
        }
    }
}

Singletons for API Access (Continued)

• If you use singleton for data, don’t use it inside a component.

// Contacts.qml
Item {
    id: root

    ListView {
        model: MySingletonClass.contacts
        delegate: Text { /* ... */ }
    }
}

// Contacts.qml
Item {
    id: root

    property alias model: lv.model

    ListView {
        id: lv
        delegate: Text { /* ... */ }
    }
}

Prefer Instantiated Types Over Singletons For Data

// ColorsWindow.qml
Window {
    id: root

    Column {
        Repeater {
            model: Palette.selectedColors
            delegate: ColorViewer {
                required property color color
                required property string colorName

                selectedColor: color
                selectedColorName: colorName
            }
        }
    }
}

Prefer Instantiated Types Over Singletons For Data

See Issue #2 for related discussions.

// ColorsWindow.qml
Window {
    property alias model: rp.model

    Column {
        Repeater {
            id: rp
            model: PaletteColorsModel { } // Alternatively
            delegate: ColorViewer {
                required property color color
                required property string colorName

                selectedColor: color
                selectedColorName: colorName
            }
        }
    }
}

Watch Out for Object Ownership Rules

Two ownership types:

• C++
• QML
• Expose data with properties only

See example for using properties for data customization

See this article for a real life example of a related bug in an application.

Q_PROPERTY( QObject* colors READ colors )

QObject* colors(); // Ownership remains in C++.
Q_INVOKABLE QObject* myData(); // Ownership is transferred to QML.

Functions vs Signals

Function -> Changes Internal State

Imperative form -> doSomething()

Signal -> Announces Internal State Change

Passive form -> somethingChanged()

Avoid Using .connect() in QML

ApplicationWindow {
    id: root

    property list<QtObject> myObjects: [
        QtObject { signal somethingHappened() }, QtObject { signal somethingHappened() },
        QtObject { signal somethingHappened() }, QtObject { signal somethingHappened() },
        QtObject { signal somethingHappened() }, QtObject { signal somethingHappened() },
        QtObject { signal somethingHappened() }, QtObject { signal somethingHappened() }
    ]

    ListView {
        cacheBuffer: 1 // Low enough we can resize the window to destroy buttons.
        model: root.myObjects.length
        delegate: Button {
            text: "Button " + index
            onClicked: root.myObjects[index].somethingHappened()
            Component.onCompleted: root.myObjects[index].somethingHappened.connect(() => console.log(text))
            Component.onDestruction: console.log("Destroyed #", index)
        }
    }
}

Avoid Using .connect() in QML (Continued)

ApplicationWindow {
    id: root

    property list<QtObject> myObjects: [
        // ... Same model as previous code snippet
    ]

    ListView {
        cacheBuffer: 1 // Low enough we can resize the window to destroy buttons.
        model: root.myObjects.length
        delegate: Button {
            id: dlg
            text: "Button " + index
            onClicked: root.myObjects[index].somethingHappened()
            Component.onDestruction: console.log("Destroyed #", index)

            Connections {
                target: root.myObjects[index]

                function onSomethingHappened() {
                    console.log(dlg.text)
                }
            }
        }
    }
}

What is wrong here?

// ColorPicker.qml
Rectangle {
    id: root

    signal colorPicked(color pickedColor)

    ColorDialog {
        onColorChanged: {
            root.colorPicked(color)
        }
    }
}

// main.qml
Window {
    ColorPicker {
        onColorPicked: {
            color = pickedColor
            label.text = "Color Changed"
        }
    }
    Label { id: label }
}

// ColorPicker.qml
Rectangle {
    id: root

    signal colorPicked(color pickedColor)

    ColorDialog {
        onColorChanged: {
            root.color = color
            root.colorPicked(color)
        }
    }
}

// main.qml
Window {
    ColorPicker {
        onColorPicked: {
            label.text = "Color Changed"
        }
    }
    Label { id: label }
}

Don’t Define Top Level States

Item {
    component Rect: Rectangle {
        id: self

        readonly property alias pressed: ma.containsPress

        states: State {
            when: ma.containsMouse

            PropertyChanges { target: self; color: "red" }
        }

        MouseArea { id: ma; hoverEnabled: true }
    }

    Rect {
        id: rect
        states: State {
            when: rect.pressed

            PropertyChanges { target: rect; color: "yellow" }
        }
    }
}

One Size Does Not Fit All

• Implicit Size: Space occupied when no explicit size or anchors are set.
• Explicit Size: Space occupied when an external size is given, ie width/height or anchors are set.
• Content Size: Space occupied by the contents of a view.
• Padding: Space between the content item and the edge of a component.
• Margin: Space between two controls.
• Inset: Space between background and the edge of a component.

// Arrow function
root.value = Qt.binding(() => root.someOtherValue)
// The old way.
root.value = Qt.binding(function() { return root.someOtherValue })

// Variables
const value = 32;
let valueTwo = 42;
{
    // Valid assignment since we are in a different scope.
    const value = 32;
    let valueTwo = 42;
}
const value = 32;
value = 42; // ERROR!

Use arrow function syntax for signal handlers

MouseArea {
    // Good!
    onClicked: (mouse) => {

    }
    // Bad...
    onClicked: {

    }
}

What’s next?

• OUt with the old, in with the new
• More content for Qt 6
• An architecture section
• More contributions from others

QML Coding Guidelines on GitHub - https://github.com/Furkanzmc/QML-Coding-Guide