sleepyvani/qt-qml

QML and Qt Quick

QML vs Widgets: When to Choose QML

| Use QML when... | Use Widgets when... | |-----------------|---------------------| | Building modern, animated, fluid UIs | Building traditional desktop tools | | Targeting mobile or embedded | Heavy data tables and forms | | Designers are involved in the UI | Rich text editing required | | GPU-accelerated rendering needed | Complex platform widget integration | | Writing a new app from scratch | Extending an existing widget app |

For new Python/PySide6 desktop applications, QML offers better visual results with less code. For data-heavy enterprise tools, widgets remain the pragmatic choice.

Bootstrap and architecture — see references/qml-architecture.md

Official Best Practices (Qt Quick)

1. Type-safe property declarations — Always use explicit types, not var:

// WRONG — prevents static analysis, unclear errors
property var name

// CORRECT
property string name
property int count
property MyModel optionsModel

2. Prefer declarative bindings over imperative assignments:

// WRONG — imperative assignment overwrites bindings, breaks Qt Design Studio
Rectangle {
    Component.onCompleted: color = "red"
}

// CORRECT — declarative binding, evaluates once at load
Rectangle {
    color: "red"
}

3. Interaction signals over value-change signals:

// WRONG — valueChanged fires on clamping/rounding, causes event cascades
Slider { onValueChanged: model.update(value) }

// CORRECT — moved only fires on user interaction
Slider { onMoved: model.update(value) }

4. Don't anchor the immediate children of Layouts:

// WRONG — anchors on direct Layout children cause binding loops
RowLayout {
    Rectangle { anchors.fill: parent }
}

// CORRECT — use Layout attached properties
RowLayout {
    Rectangle {
        Layout.fillWidth: true
        Layout.preferredHeight: 40
    }
}

5. Don't customize native styles — Windows and macOS native styles ignore QSS. Base all custom styling on cross-platform styles: Basic, Fusion, Material, or Universal:

// In main() — must be set before QGuiApplication
QQuickStyle.setStyle("Material")

6. Make all user-visible strings translatable from the start:

Label { text: qsTr("Save File") }
Button { text: qsTr("Cancel") }

Exposing Python Objects to QML

Three methods: Required Properties (preferred), Context Property, Registered QML Type.

Key rule: @Slot is mandatory for any Python method callable from QML. Missing it causes TypeError at runtime.

Full patterns — see references/qml-pyside6.md

QML Signals and Connections

Full patterns — see references/qml-signals-properties.md

Common QtQuick.Controls Components

Full component reference — see references/qml-components.md