Qt QML File Format

Overview

QML (Qt Modeling Language) is a declarative language for designing user interfaces in Qt applications. Developed by Qt (originally by Trolltech, now by The Qt Company), QML provides a JSON-like syntax for creating dynamic, fluid user interfaces with rich animations, effects, and complex layouts. It bridges the gap between designers and developers by offering an intuitive markup language.

Technical Details

• MIME Type: text/x-qml
• File Extension: .qml
• Category: Code
• First Appeared: 2009 (Qt 4.7)
• Current Version: Qt 6.x
• Language Family: Declarative, JavaScript-based

Structure and Syntax

QML uses a hierarchical, declarative syntax similar to JSON with JavaScript expressions for dynamic behavior.

Basic QML Structure

import QtQuick 2.15
import QtQuick.Controls 2.15

ApplicationWindow {
    id: window
    width: 640
    height: 480
    visible: true
    title: "My QML Application"
    
    Rectangle {
        id: background
        anchors.fill: parent
        color: "#f0f0f0"
        
        Text {
            id: welcomeText
            text: "Hello, QML!"
            anchors.centerIn: parent
            font.pointSize: 24
            color: "#333333"
        }
    }
}

Properties and Bindings

import QtQuick 2.15

Rectangle {
    id: root
    width: 300
    height: 200
    
    // Property declarations
    property string title: "My Rectangle"
    property int cornerRadius: 10
    property color baseColor: "#4CAF50"
    
    // Property bindings
    color: mouseArea.pressed ? Qt.darker(baseColor) : baseColor
    radius: cornerRadius
    
    // Computed properties
    property real aspectRatio: width / height
    
    Text {
        id: titleText
        text: root.title
        anchors.centerIn: parent
        font.bold: true
        
        // Property binding with ternary operator
        color: parent.color === "#4CAF50" ? "white" : "black"
    }
    
    MouseArea {
        id: mouseArea
        anchors.fill: parent
        onClicked: {
            console.log("Rectangle clicked!")
            root.title = "Clicked!"
        }
    }
}

Layout and Positioning

import QtQuick 2.15
import QtQuick.Layouts 1.15

Rectangle {
    width: 400
    height: 300
    color: "#ffffff"
    
    // Column layout
    ColumnLayout {
        anchors.fill: parent
        anchors.margins: 20
        spacing: 10
        
        // Header
        Rectangle {
            Layout.fillWidth: true
            Layout.preferredHeight: 60
            color: "#2196F3"
            radius: 5
            
            Text {
                text: "Header"
                anchors.centerIn: parent
                color: "white"
                font.bold: true
                font.pointSize: 16
            }
        }
        
        // Content area with row layout
        RowLayout {
            Layout.fillWidth: true
            Layout.fillHeight: true
            spacing: 10
            
            // Sidebar
            Rectangle {
                Layout.preferredWidth: 120
                Layout.fillHeight: true
                color: "#E0E0E0"
                radius: 5
                
                Text {
                    text: "Sidebar"
                    anchors.centerIn: parent
                    font.pointSize: 12
                }
            }
            
            // Main content
            Rectangle {
                Layout.fillWidth: true
                Layout.fillHeight: true
                color: "#F5F5F5"
                radius: 5
                
                Text {
                    text: "Main Content"
                    anchors.centerIn: parent
                    font.pointSize: 14
                }
            }
        }
        
        // Footer
        Rectangle {
            Layout.fillWidth: true
            Layout.preferredHeight: 40
            color: "#757575"
            radius: 5
            
            Text {
                text: "Footer"
                anchors.centerIn: parent
                color: "white"
                font.pointSize: 12
            }
        }
    }
}

Animations and Transitions

Basic Animations

import QtQuick 2.15

Rectangle {
    id: animatedRect
    width: 100
    height: 100
    color: "#FF5722"
    radius: 10
    
    // Property animation
    PropertyAnimation {
        id: moveAnimation
        target: animatedRect
        property: "x"
        from: 0
        to: 200
        duration: 1000
        easing.type: Easing.InOutQuad
    }
    
    // Number animation with loops
    NumberAnimation {
        id: rotationAnimation
        target: animatedRect
        property: "rotation"
        from: 0
        to: 360
        duration: 2000
        loops: Animation.Infinite
        running: true
    }
    
    // Color animation
    ColorAnimation {
        id: colorAnimation
        target: animatedRect
        property: "color"
        from: "#FF5722"
        to: "#4CAF50"
        duration: 1500
    }
    
    MouseArea {
        anchors.fill: parent
        onClicked: {
            moveAnimation.start()
            colorAnimation.start()
        }
    }
}

State-based Animations

import QtQuick 2.15

Rectangle {
    id: stateRect
    width: 200
    height: 200
    color: "#2196F3"
    
    states: [
        State {
            name: "expanded"
            PropertyChanges {
                target: stateRect
                width: 300
                height: 300
                color: "#4CAF50"
                rotation: 45
            }
        },
        State {
            name: "collapsed"
            PropertyChanges {
                target: stateRect
                width: 100
                height: 100
                color: "#F44336"
                rotation: 0
            }
        }
    ]
    
    transitions: [
        Transition {
            from: "*"
            to: "*"
            ParallelAnimation {
                PropertyAnimation {
                    properties: "width,height,rotation"
                    duration: 500
                    easing.type: Easing.OutBounce
                }
                ColorAnimation {
                    duration: 300
                }
            }
        }
    ]
    
    MouseArea {
        anchors.fill: parent
        onClicked: {
            stateRect.state = stateRect.state === "expanded" ? "collapsed" : "expanded"
        }
    }
    
    Text {
        text: parent.state || "default"
        anchors.centerIn: parent
        color: "white"
        font.bold: true
    }
}

User Interface Controls

Interactive Components

import QtQuick 2.15
import QtQuick.Controls 2.15

ApplicationWindow {
    id: controlsWindow
    width: 400
    height: 600
    visible: true
    title: "QML Controls Demo"
    
    ScrollView {
        anchors.fill: parent
        
        Column {
            width: parent.width
            padding: 20
            spacing: 15
            
            // Text input
            TextField {
                id: nameField
                width: parent.width - 40
                placeholderText: "Enter your name"
                onTextChanged: outputText.text = "Hello, " + text + "!"
            }
            
            // Buttons
            Row {
                spacing: 10
                
                Button {
                    text: "Primary"
                    highlighted: true
                    onClicked: console.log("Primary button clicked")
                }
                
                Button {
                    text: "Secondary"
                    onClicked: console.log("Secondary button clicked")
                }
            }
            
            // Checkboxes and radio buttons
            Column {
                spacing: 5
                
                CheckBox {
                    text: "Enable notifications"
                    checked: true
                }
                
                RadioButton {
                    text: "Option A"
                    checked: true
                }
                
                RadioButton {
                    text: "Option B"
                }
            }
            
            // Slider
            Slider {
                id: volumeSlider
                width: parent.width - 40
                from: 0
                to: 100
                value: 50
                stepSize: 1
                
                Text {
                    text: "Volume: " + Math.round(parent.value)
                    anchors.bottom: parent.top
                    anchors.horizontalCenter: parent.horizontalCenter
                }
            }
            
            // Progress bar
            ProgressBar {
                width: parent.width - 40
                value: volumeSlider.value / 100
            }
            
            // Combo box
            ComboBox {
                width: parent.width - 40
                model: ["Option 1", "Option 2", "Option 3", "Option 4"]
                currentIndex: 0
            }
            
            // Output text
            Text {
                id: outputText
                width: parent.width - 40
                text: "Hello, World!"
                wrapMode: Text.WordWrap
                font.pointSize: 14
                color: "#333333"
            }
        }
    }
}

Custom Components

// CustomButton.qml
import QtQuick 2.15

Rectangle {
    id: customButton
    width: 120
    height: 40
    radius: 8
    
    // Public properties
    property string text: "Button"
    property color primaryColor: "#2196F3"
    property color hoverColor: "#1976D2"
    property color pressedColor: "#0D47A1"
    
    // Signals
    signal clicked()
    signal pressAndHold()
    
    // State management
    color: mouseArea.pressed ? pressedColor : 
           mouseArea.containsMouse ? hoverColor : primaryColor
    
    // Smooth color transitions
    Behavior on color {
        ColorAnimation { duration: 150 }
    }
    
    Text {
        text: customButton.text
        anchors.centerIn: parent
        color: "white"
        font.bold: true
        font.pointSize: 12
    }
    
    MouseArea {
        id: mouseArea
        anchors.fill: parent
        hoverEnabled: true
        onClicked: customButton.clicked()
        onPressAndHold: customButton.pressAndHold()
    }
    
    // Ripple effect
    Rectangle {
        id: ripple
        width: 0
        height: 0
        radius: width / 2
        color: "#FFFFFF"
        opacity: 0
        anchors.centerIn: parent
        
        ParallelAnimation {
            id: rippleAnimation
            PropertyAnimation {
                target: ripple
                properties: "width,height"
                to: Math.max(customButton.width, customButton.height) * 2
                duration: 300
            }
            SequentialAnimation {
                PropertyAnimation {
                    target: ripple
                    property: "opacity"
                    to: 0.3
                    duration: 100
                }
                PropertyAnimation {
                    target: ripple
                    property: "opacity"
                    to: 0
                    duration: 200
                }
            }
        }
        
        Connections {
            target: mouseArea
            function onClicked() {
                ripple.width = 0
                ripple.height = 0
                rippleAnimation.start()
            }
        }
    }
}

JavaScript Integration

JavaScript Functions and Logic

import QtQuick 2.15

Rectangle {
    width: 300
    height: 200
    
    // JavaScript functions
    function calculateArea(width, height) {
        return width * height
    }
    
    function formatDate(date) {
        return Qt.formatDateTime(date, "yyyy-MM-dd hh:mm:ss")
    }
    
    function validateEmail(email) {
        var emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
        return emailRegex.test(email)
    }
    
    // Property with JavaScript expression
    property var currentTime: new Date()
    property string formattedTime: formatDate(currentTime)
    property real area: calculateArea(width, height)
    
    Column {
        anchors.centerIn: parent
        spacing: 10
        
        Text {
            text: "Area: " + parent.parent.area + " pixels"
        }
        
        Text {
            text: "Time: " + parent.parent.formattedTime
        }
        
        Text {
            id: emailStatus
            text: "Email validation will appear here"
        }
    }
    
    // Timer for updating time
    Timer {
        interval: 1000
        running: true
        repeat: true
        onTriggered: {
            currentTime = new Date()
            formattedTime = formatDate(currentTime)
        }
    }
    
    // Example of JavaScript in event handlers
    MouseArea {
        anchors.fill: parent
        onClicked: {
            var testEmail = "[email protected]"
            var isValid = validateEmail(testEmail)
            emailStatus.text = testEmail + " is " + (isValid ? "valid" : "invalid")
            
            // Complex JavaScript logic
            for (var i = 0; i < 5; i++) {
                console.log("Iteration: " + i)
            }
        }
    }
}

Data Models and Lists

import QtQuick 2.15

Rectangle {
    width: 400
    height: 300
    
    // ListModel for data
    ListModel {
        id: contactsModel
        
        ListElement {
            name: "John Doe"
            email: "[email protected]"
            phone: "+1-555-0123"
        }
        ListElement {
            name: "Jane Smith"
            email: "[email protected]"
            phone: "+1-555-0456"
        }
        ListElement {
            name: "Bob Johnson"
            email: "[email protected]"
            phone: "+1-555-0789"
        }
    }
    
    ListView {
        id: contactsList
        anchors.fill: parent
        anchors.margins: 20
        model: contactsModel
        spacing: 10
        
        delegate: Rectangle {
            width: contactsList.width
            height: 80
            color: "#F5F5F5"
            radius: 8
            border.color: "#E0E0E0"
            border.width: 1
            
            Row {
                anchors.left: parent.left
                anchors.verticalCenter: parent.verticalCenter
                anchors.leftMargin: 15
                spacing: 15
                
                Rectangle {
                    width: 50
                    height: 50
                    radius: 25
                    color: "#2196F3"
                    
                    Text {
                        text: model.name.charAt(0)
                        anchors.centerIn: parent
                        color: "white"
                        font.bold: true
                        font.pointSize: 18
                    }
                }
                
                Column {
                    anchors.verticalCenter: parent.verticalCenter
                    spacing: 2
                    
                    Text {
                        text: model.name
                        font.bold: true
                        font.pointSize: 14
                    }
                    
                    Text {
                        text: model.email
                        color: "#666666"
                        font.pointSize: 12
                    }
                    
                    Text {
                        text: model.phone
                        color: "#666666"
                        font.pointSize: 12
                    }
                }
            }
            
            MouseArea {
                anchors.fill: parent
                onClicked: {
                    console.log("Selected contact:", model.name)
                }
            }
        }
    }
    
    // JavaScript functions for model manipulation
    function addContact(name, email, phone) {
        contactsModel.append({
            "name": name,
            "email": email,
            "phone": phone
        })
    }
    
    function removeContact(index) {
        contactsModel.remove(index)
    }
}

C++ Integration

Exposing C++ Classes to QML

// C++ Header (Person.h)
#include <QObject>
#include <QString>

class Person : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged)
    Q_PROPERTY(int age READ age WRITE setAge NOTIFY ageChanged)
    
public:
    explicit Person(QObject *parent = nullptr);
    
    QString name() const;
    void setName(const QString &name);
    
    int age() const;
    void setAge(int age);
    
    Q_INVOKABLE QString getFullInfo() const;
    Q_INVOKABLE bool isAdult() const;
    
signals:
    void nameChanged();
    void ageChanged();
    
private:
    QString m_name;
    int m_age;
};

// Register type in main.cpp
#include <QQmlApplicationEngine>
#include <QtQml>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);
    
    // Register C++ type with QML
    qmlRegisterType<Person>("com.example", 1, 0, "Person");
    
    QQmlApplicationEngine engine;
    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
    
    return app.exec();
}

// Using C++ class in QML
import QtQuick 2.15
import com.example 1.0

Rectangle {
    width: 300
    height: 200
    
    Person {
        id: person
        name: "John Doe"
        age: 30
        
        onNameChanged: console.log("Name changed to:", name)
        onAgeChanged: console.log("Age changed to:", age)
    }
    
    Column {
        anchors.centerIn: parent
        spacing: 10
        
        Text {
            text: "Name: " + person.name
        }
        
        Text {
            text: "Age: " + person.age
        }
        
        Text {
            text: "Info: " + person.getFullInfo()
        }
        
        Text {
            text: person.isAdult() ? "Adult" : "Minor"
        }
        
        MouseArea {
            width: 100
            height: 30
            Rectangle {
                anchors.fill: parent
                color: "#2196F3"
                Text {
                    text: "Update"
                    anchors.centerIn: parent
                    color: "white"
                }
            }
            onClicked: {
                person.age = person.age + 1
            }
        }
    }
}

Advanced Features

Shader Effects

import QtQuick 2.15
import QtGraphicalEffects 1.15

Rectangle {
    width: 400
    height: 300
    color: "#000000"
    
    Image {
        id: sourceImage
        source: "qrc:/images/photo.jpg"
        anchors.centerIn: parent
        width: 200
        height: 200
        visible: false
    }
    
    // Blur effect
    GaussianBlur {
        anchors.fill: sourceImage
        source: sourceImage
        radius: 8
        samples: 16
    }
    
    // Custom shader effect
    ShaderEffect {
        width: 200
        height: 200
        anchors.right: parent.right
        anchors.verticalCenter: parent.verticalCenter
        anchors.rightMargin: 50
        
        property real time: 0
        
        fragmentShader: "
            varying highp vec2 qt_TexCoord0;
            uniform highp float qt_Opacity;
            uniform highp float time;
            
            void main() {
                highp vec2 pos = qt_TexCoord0;
                highp float wave = sin(pos.x * 10.0 + time) * 0.1;
                pos.y += wave;
                
                highp vec3 color = vec3(
                    sin(time + pos.x * 3.0) * 0.5 + 0.5,
                    sin(time + pos.y * 3.0) * 0.5 + 0.5,
                    sin(time + (pos.x + pos.y) * 3.0) * 0.5 + 0.5
                );
                
                gl_FragColor = vec4(color, qt_Opacity);
            }
        "
        
        NumberAnimation on time {
            from: 0
            to: Math.PI * 2
            duration: 3000
            loops: Animation.Infinite
        }
    }
}

Particle Systems

import QtQuick 2.15
import QtQuick.Particles 2.15

Rectangle {
    width: 600
    height: 400
    color: "#000011"
    
    ParticleSystem {
        id: particleSystem
        anchors.fill: parent
        
        // Emitter
        Emitter {
            id: fireEmitter
            anchors.bottom: parent.bottom
            anchors.horizontalCenter: parent.horizontalCenter
            width: 20
            height: 20
            
            emitRate: 100
            lifeSpan: 3000
            lifeSpanVariation: 1000
            
            velocity: AngleDirection {
                angle: 270
                angleVariation: 30
                magnitude: 100
                magnitudeVariation: 50
            }
            
            acceleration: PointDirection {
                y: -50
            }
            
            size: 8
            sizeVariation: 4
        }
        
        // Particle appearance
        ImageParticle {
            groups: ["fire"]
            source: "qrc:/particles/fire.png"
            color: "#FFD700"
            colorVariation: 0.6
            alpha: 0.8
            alphaVariation: 0.2
        }
        
        // Particle physics
        Wander {
            groups: ["fire"]
            xVariance: 30
            pace: 50
        }
        
        // Age-based effects
        Age {
            groups: ["fire"]
            lifeLeft: 1000
            advancePosition: false
        }
    }
    
    MouseArea {
        anchors.fill: parent
        onClicked: {
            fireEmitter.burst(50, mouse.x, mouse.y)
        }
    }
}

Best Practices and Performance

Performance Optimization

// Use appropriate item types
Item {  // Lightweight container
    Rectangle {  // Only when visual appearance needed
        // content
    }
}

// Efficient property bindings
Rectangle {
    // Good: Direct binding
    width: parent.width * 0.5
    
    // Avoid: Complex expressions in bindings
    // width: someComplexFunction(parent.width, parent.height, otherProperty)
}

// Use Loader for conditional content
Loader {
    active: showAdvancedOptions
    sourceComponent: AdvancedPanel {
        // Complex component loaded only when needed
    }
}

// Optimize ListView performance
ListView {
    model: largeModel
    cacheBuffer: 100  // Cache items outside view
    
    delegate: Rectangle {
        // Keep delegates lightweight
        width: ListView.view.width
        height: 50
    }
}

Code Organization

// Use consistent naming conventions
Rectangle {
    id: mainContainer  // camelCase for IDs
    
    property string userName: ""     // camelCase for properties
    property int maxItems: 100
    
    signal itemSelected(int index)   // camelCase for signals
    
    function calculateTotal() {      // camelCase for functions
        // implementation
    }
}

Common Use Cases

Desktop Applications

• Rich desktop applications with native look and feel
• Data visualization and dashboard applications
• Media players and content creation tools
• Scientific and engineering applications

Mobile Applications

• Cross-platform mobile applications
• Touch-optimized user interfaces
• Material Design and iOS-style interfaces
• Real-time communication applications

Embedded Systems

• Automotive infotainment systems
• Industrial control panels
• IoT device interfaces
• Medical device user interfaces

Prototyping and Design

• UI/UX prototyping and mockups
• Interactive design demonstrations
• Animation and motion graphics
• Design system implementations

QML continues to be a powerful choice for creating modern, cross-platform applications with rich user interfaces, offering excellent performance and extensive customization capabilities.