QML Language

Examples

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

Property bindings

Expressions are snippets of javascript code assigned to a property. The last line can serve as the return value. Alternatively, an explicit return statement can also be used for multi-line expressions.

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, while optional, can be included on any line of a single or multi-line expression, including the last line.

All property bindings are reactive. This means that whenever any property the expression depends on is updated, the expression is re-evaluated and the property is updated accordingly.

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.

Trying to assign to a property that does not exist is an error.

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 that 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";
  }
}

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.

In general, you should only access properties of the current object without an id. For all other objects, you should refer to them by id when accessing properties.

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

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

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

When the button is clicked, the button emits the Button.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 connections, and prior examples have used them.

When creating an object, there is a corresponding on<Signal> property implicitly defined for every signal present on its type, which can be set to a function. Do note that the first letter of the signal’s name is capitalized.

Below is the same example from Making Connections, but 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"
  }
}

Indirect signal handlers

Signal handlers should be preferred, but there are times where it is not possible or inconvenient to define one. In those cases, before resorting to .connecting the properties, a Connections object can be used to access them.

This is especially useful to connect to signals of a Singleton.

Item {
  Button {
    id: myButton
    text "click me"
  }

  Connections {
    target: myButton

    function onClicked() {
      // ...
    }
  }
}

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.

When it is not possible or inconvenient to directly define a signal handler, before resorting to .connecting the properties, a Connections object can be used to access them.

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 changes to the CheckBox.checkState property of the CheckBox 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 accessed 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.

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

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

Inline Components

Inline components work the same as any other type, but are created inside another QML file. These components only work within the file, and can reference IDs inside the file.

While inline components can be created anywhere inside a QML file, they are scoped to the file itself and cannot be nested.

Example of an inline component:

ColumnLayout {
  id: layout
  property real textPointSize: 10

  MyText { text: "Thing 1" }
  MyText { text: "Thing 2" }
  MyText { text: "Thing 3" }

  component MyText: Text {
    // applied to all MyText instances
    color: "red"
    // references an id outside of the component
    font.pointSize: layout.textPointSize
  }
}

Singletons

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

To make a type of a Singleton, put pragma Singleton at the top of the file. To ensure it behaves correctly with Quickshell, you should also make the Singleton the root item of your type.

pragma Singleton
import ...

Singleton {
  ...
}

Once a type is a Singleton, its members can be accessed by name from neighboring files.

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