quickshell-docs/content/docs/configuration/qml-overview.md

+++ title = "QML Overview" +++

Quickshell is configured using the Qt Modeling Language, or QML. This page explains what you need to know about QML to start using quickshell.

See also: Qt Documentation: QML Tutorial

Structure

Below is a QML document showing most of the syntax. Keep it in mind as you read the detailed descriptions below.

Notes:

• Semicolons are permitted basically everywhere, and recommended in functions and expressions.
• While types can often be elided, we recommend you use them where possible to catch proplems early instead of running into them unexpectedly layer on.

// QML Import statement
import QtQuick 6.0

// Javascript import statement
import "myjs.js" as MyJs

// Root Object
Item {
  // Id assignment

  id: root
  // Property declaration
  property int myProp: 5;

  // Property binding
  width: 100

  // Property binding
  height: width

  // Multiline property binding
  prop: {
    // ...
    5
  }

  // Object assigned to a property
  objProp: Object {
    // ...
  }

  // Object assigned to the parent's default property
  AnotherObject {
    // ...
  }

  // Signal declaration
  signal foo(bar: int)

  // Signal handler
  onSignal: console.log("received signal!")

  // Property change signal handler
  onWidthChanged: console.log(`width is now ${width}!`)

  // Multiline signal handler
  onOtherSignal: {
    console.log("received other signal!");
    console.log(`5 * 2 is ${dub(5)}`);
    // ...
  }

  // Attached property signal handler
  Component.onCompleted: MyJs.myfunction()

  // Function
  function dub(x: int): int {
    return x * 2
  }
}

Imports

Explicit imports

Every QML File begins with a list of imports. Import statements tell the QML engine where to look for types you can create objects from.

A module import statement looks like this:

import <Module> [Major.Minor] [as <Namespace>]

• Module is the name of the module you want to import, such as QtQuick.
• Major.Minor is the version of the module you want to import.
• Namespace is an optional namespace to import types from the module under.

A subfolder import statement looks like this:

import "<directory>" [as <Namespace>]

• directory is the directory to import, relative to the current file.
• Namespace is an optional namespace to import types from the folder under.

A javascript import statement looks like this:

import "<filename>" as <Namespace>

• filename is the name of the javascript file to import.
• Namespace is the namespace functions and variables from the javascript file will be made available under.

Note: All Module and Namespace names must start with an uppercase letter. Attempting to use a lowercase namespace is an error.

Examples

import QtQuick
import QtQuick.Controls 6.0
import Quickshell as QS
import QtQuick.Layouts 6.0 as L
import "jsfile.js" as JsFile

{{% details title="When to use versions" closed="true" %}}

By default, when no module version is requested, the QML engine will pick the latest available version of the module. Requesting a specific version can help ensure you get a specific version of the module's types, and as a result your code dosen't break across Qt or quickshell updates.

While Qt's types usually don't majorly change across versions, quickshell's are much more likely to break. To put off dealing with the breakage we suggest specifying a version at least when importing quickshell modules.

{{% /details %}}

Qt Documentation: Import syntax

Implicit imports

The QML engine will automatically import any types in neighboring files with names that start with an uppercase letter.

root
|-MyButton.qml
|-shell.qml

In this example, MyButton will automatically be imported as a type usable from shell.qml or any other neighboring files.

Objects

Objects are instances of a type from an imported module. The name of an object must start with an uppercase letter. This will always distinguish an object from a property.

An object looks like this:

Name {
  id: foo
  // properties, functions, signals, etc...
}

Every object can contain properties, functions, and signals. You can find out what properties are available for a type by looking it up in the Type Reference.

Properties

Every object may have any number of property assignments (only one per specific property). Each assignment binds the named property to the given expression.

Property bindings

Expressions are snippets of javascript code assigned to a property. The last (or only) line can be the return value, or an explicit return statement (multiline expressions only) can be used.

Item {
  // simple expression
  property: 5

  // complex expression
  property: 5 * 20 + this.otherProperty

  // multiline expression
  property: {
    const foo = 5;
    const bar = 10;
    foo * bar
  }

  // multiline expression with return
  property: {
    // ...
    return 5;
  }
}

Semicolons are optional and allowed on any line of a single or multiline expression, including the last line.

All property bindings are reactive, which means when any property the expression depends on is updated, the expression is re-evaluated and the property is updated.

See: Reactive bindings

Note that it is an error to try to assign to a property that does not exist. (See: property definitions)

Property definitions

Properties can be defined inside of objects with the following syntax:

[required] [readonly] [default] property <type> <name>[: binding]

• required forces users of this type to assign this property. See Creating Types for details.
• readonly makes the property not assignable. Its binding will still be reactive.
• default makes the property the default property of this type.
• type is the type of the property. You can use var if you don't know or don't care but be aware that var will allow any value type.
• name is the name that the property is known as. It cannot start with an uppercase letter.
• binding is the property binding. See Property bindings for details.

Item {
  // normal property
  property int foo: 3

  // readonly property
  readonly property string bar: "hi!"

  // bound property
  property var things: [ "foo", "bar" ]
}

Defining a property with the same name as one provided by the current object will override the property of the type it is derived from in the current context.

The default property

Types can have a default property which must accept either an object or a list of objects.

The default property will allow you to assign a value to it without using the name of the property:

Item {
  // normal property
  foo: 3

  // this item is assigned to the outer object's default property
  Item {
  }
}

If the default property is a list, you can put multiple objects into it the same way as you would put a single object in:

Item {
  // normal property
  foo: 3

  // this item is assigned to the outer object's default property
  Item {
  }

  // this one is too
  Item {
  }
}

The id property

Every object has a special property called id that can be assigned to give the object a name it can be referred to throughout the current file. The id must be lowercase.

ColumnLayout {
  Text {
    id: text
    text: "Hello World!"
  }

  Button {
    text: "Make the text red";
    onClicked: text.color = "red";
  }
}

{{% details title="The id property compared to normal properties" closed="true" %}}

The id property isn't really a property, and dosen't do anything other than expose the object to the current file. It is only called a property because it uses very similar syntax to one, and is the only exception to standard property definition rules. The name id is always reserved for the id property.

{{% /details %}}

Property access scopes

Properties are "in scope" and usable in two cases.

1. They are defined for current type.
2. They are defined for the root type in the current file.

You can access the properties of any object by setting its id property, or make sure the property you are accessing is from the current object using this.

The parent property is also defined for all objects, but may not always point to what it looks like it should. Use the id property if parent does not do what you want.

Item {
  property string rootDefinition

  Item {
    id: mid
    property string midDefinition

    Text {
      property string innerDefinition

      // legal - innerDefinition is defined on the current object
      text: innerDefinition

      // legal - innerDefinition is accessed via `this` to refer to the current object
      text: this.innerDefinition

      // legal - width is defined for Text
      text: width

      // legal - rootDefinition is defined on the root object
      text: rootDefinition

      // illegal - midDefinition is not defined on the root or current object
      text: midDefinition

      // legal - midDefinition is accessed via `mid`'s id.
      text: mid.midDefinition

      // legal - midDefinition is accessed via `parent`
      text: parent.midDefinition
    }
  }
}

Qt Documentation: Scope and Naming Resolution

Functions

Functions in QML can be declared everywhere properties can, and follow the same scoping rules.

Function definition syntax:

function <name>(<paramname>[: <type>][, ...])[: returntype] {
  // multiline expression (note that `return` is required)
}

Functions can be invoked in expressions. Expression reactivity carries through functions, meaning if one of the properties a function depends on is re-evaluated, every expression depending on the function is also re-evaluated.

ColumnLayout {
  property int clicks: 0

  function makeClicksLabel(): string {
    return "the button has been clicked " + clicks + " times!";
  }

  Button {
    text: "click me"
    onClicked: clicks += 1
  }

  Text {
    text: makeClicksLabel()
  }
}

In this example, every time the button is clicked, the label's count increases by one, as clicks is changed, which triggers a re-evaluation of text through makeClicksLabel.

Lambdas

Functions can also be values, and you can assign them to properties or pass them to other functions (callbacks). There is a shorter way to write these functions, known as lambdas.

Lambda syntax:

<params> => <expression>

// params can take the following forms:
() => ... // 0 parameters
<name> => ... // 1 parameter
(<name>[, ...]) => ... // 1+ parameters

// the expression can be either a single or multiline expression.
... => <result>
... => {
  return <result>;
}

Assigning functions to properties:

Item {
  // using functions
  function dub(number: int): int { return number * 2; }
  property var operation: dub

  // using lambdas
  property var operation: number => number * 2
}

An overcomplicated click counter using a lambda callback:

ColumnLayout {
  property int clicks: 0

  function incrementAndCall(callback) {
    clicks += 1;
    callback(clicks);
  }

  Button {
    text: "click me"
    onClicked: incrementAndCall(clicks => {
        label.text = `the button was clicked ${clicks} time(s)!`;
    })
  }

  Text {
    id: label
    text: "the button has not been clicked"
  }
}

Signals

A signal is basically an event emitter you can connect to and receive updates from. They can be declared everywhere properties and functions can, and follow the same scoping rules.

Qt Documentation: Signal and Handler Event System

Signal definitions

A signal can be explicitly defined with the following syntax:

signal <name>(<paramname>: <type>[, ...])

Making connections

Signals all have a connect(<function>) method which invokes the given function or signal when the signal is emitted.

ColumnLayout {
  property int clicks: 0

  function updateText() {
    clicks += 1;
    label.text = `the button has been clicked ${clicks} times!`;
  }

  Button {
    id: button
    text: "click me"
  }

  Text {
    id: label
    text: "the button has not been clicked"
  }

  Component.onCompleted: {
    button.clicked.connect(updateText)
  }
}

Component.onCompleted will be addressed later in Attached Properties but for now just know that it runs immediately once the object is fully initialized.

When the button is clicked, the button emits the clicked signal which we connected to updateText. The signal then invokes updateText which updates the counter and the text on the label.

Signal handlers

Signal handlers are a more concise way to make a connections, and prior examples have used them.

When creating an object, for every signal present on its type there is a corrosponding on<Signal> property implicitly defined which can be set to a function. (Note that the first letter of the signal's name it capitalized.)

Below is the same example as in Making Connections, this time using the implicit signal handler property to handle button.clicked.

ColumnLayout {
  property int clicks: 0

  function updateText() {
    clicks += 1;
    label.text = `the button has been clicked ${clicks} times!`;
  }

  Button {
    text: "click me"
    onClicked: updateText()
  }

  Text {
    id: label
    text: "the button has not been clicked"
  }
}

Property change signals

Every property has an associated signal, which powers QML's reactive bindings. The signal is named <propertyname>Changed and works exactly the same as any other signal.

Whenever the property is re-evaluated, its change signal is emitted. This is used internally to update dependent properties, but can be directly used, usually with a signal handler.

ColumnLayout {
  CheckBox {
    text: "check me"

    onCheckStateChanged: {
      label.text = labelText(checkState == Qt.Checked);
    }
  }

  Text {
    id: label
    text: labelText(false)
  }

  function labelText(checked): string {
    return `the checkbox is checked: ${checked}`;
  }
}

In this example we listen for the checkState property of the CheckBox changing using its change signal, checkStateChanged with the signal handler onCheckStateChanged.

Since text is also a property we can do the same thing more concisely:

ColumnLayout {
  CheckBox {
    id: checkbox
    text: "check me"
  }

  Text {
    id: label
    text: labelText(checkbox.checkState == Qt.Checked)
  }

  function labelText(checked): string {
    return `the checkbox is checked: ${checked}`;
  }
}

And the function can also be inlined to an expression:

ColumnLayout {
  CheckBox {
    id: checkbox
    text: "check me"
  }

  Text {
    id: label
    text: {
      const checked = checkbox.checkState == Qt.Checked;
      return `the checkbox is checked: ${checked}`;
    }
  }
}

You can also remove the return statement if you wish.

Attached objects

Attached objects are additional objects that can be associated with an object as decided by internal library code. The documentation for a type will tell you if it can be used as an attached object and how.

Attached objects are acccessed in the form <Typename>.<member> and can have properties, functions and signals.

A good example is the Component type, which is attached to every object and often used to run code when an object initializes.

Text {
  Component.onCompleted: {
    text = "hello!"
  }
}

In this example, the text property is set inside the Component.onCompleted attached signal handler.

Creating types

Every QML file with an uppercase name is implicitly a type, and can be used from neighboring files or imported (See Imports.)

A type definition is just a normal object. All properties defined for the root object are visible to the consumer of the type. Objects identified by id properties are not visible outside the file.

// MyText.qml
Rectangle {
  required property string text

  color: "red"
  implicitWidth: textObj.implicitWidth
  implicitHeight: textObj.implicitHeight

  Text {
    id: textObj
    anchors.fill: parent
    text: parent.text
  }
}

// AnotherComponent.qml
Item {
  MyText {
    // The `text` property of `MyText` is required, so we must set it.
    text: "Hello World!"

    // `anchors` is a property of `Item` which `Rectangle` subclasses,
    // so it is available on MyText.
    anchors.centerIn: parent

    // `color` is a property of `Rectangle`. Even though MyText sets it
    // to "red", we can override it here.
    color: "blue"

    // `textObj` is has an `id` within MyText.qml but is not a property
    // so we cannot access it.
    textObj.color: "red" // illegal
  }
}

Singletons

QML Types can be easily made into a singleton, meaning there is only one instance of the type.

To make a type a singleton, put pragma Singleton at the top of the file.

pragma Singleton
import ...

Item { ... }

once a type is a singleton, its members can be accessed by name from neighboring files.

Concepts

Reactive bindings

This section assumes knowledge of: Properties, Signals, and Functions. See also the Qt documentation.

Reactivity is when a property is updated based on updates to another property. Every time one of the properties in a binding change, the binding is re-evaluated and the bound property takes the new result. Any bindings that depend on that property are then re-evaluated and so forth.

Bindings can be created in two different ways:

Automatic bindings

A reactive binding occurs automatically when you use one or more properties in the definition of another property. .

Item {
  property int clicks: 0

  Button {
    text: `clicks: ${clicks}`
    onClicked: clicks += 1
  }
}

In this example, the button's text property is re-evaluated every time the button is clicked, because the clicks property has changed.

Avoiding creation

To avoid creating a binding, do not use any other properties in the definition of a property.

You can use the Component.onCompleted signal to set a value using a property without creating a binding, as assignments to properties do not create binding.

Item {
  property string theProperty: "initial value"

  Text {
    // text: "Right now, theProperty is: " + theProperty
    Component.onCompleted: text = "At creation time, theProperty is: " + theProperty
  }
}

Manual bindings

Sometimes (not often) you need to create a binding inside of a function, signal, or expression. If you need to change or attach a binding at runtime, the Qt.binding function can be used to create one.

The Qt.binding function takes another function as an argument, and when assigned to a property, the property will use that function as its binding expression.

Item {
  Text {
    id: boundText
    text: "not bound to anything"
  }

  Button {
    text: "bind the above text"
    onClicked: {
      if (boundText.text == "not bound to anything") {
        text = "press me";
        boundText.text = Qt.binding(() => `button is pressed: ${this.pressed}`);
      }
    }
  }
}

In this example, boundText's text property is bound to the button's pressed state when the button is first clicked. When you press or unpress the button the text will be updated.

Removing bindings

To remove a binding, just assign a new value to the property without using Qt.binding.

Item {
  Text {
    id: boundText
    text: `button is pressed: ${theButton.pressed}`
  }

  Button {
    id: theButton
    text: "break the binding"
    onClicked: boundText.text = `button was pressed at the time the binding was broken: ${pressed}`
  }
}

When the button is first pressed, the text will be updated, but once onClicked fires the text will be unbound, and even though it contains a reference to the pressed property, it will not be updated further by the binding.

Lazy loading

Often not all of your interface needs to load immediately. By default the QML engine initializes every object in the scene before showing anything onscreen. For parts of the interface you don't need to load immediately, you should load them lazily to make your interface load faster.

The Loader type can help with this, by loading in external files or creating components at runtime. Check its documentation for more information.

Components

Another delayed loading mechanism is the Component type. This type can be used to create multiple instances of objects or lazily load them. It's used by types such as Repeater and Quickshell.Variants to create instances of a component at runtime.