quickshell/quickshell-web
3
1
Fork 0
Code Issues Projects Activity

refactor guide pages to use content collections

Browse source 
also configuration->guide
This commit is contained in:
outfoxxed 2025-05-13 20:56:31 -07:00
parent a449f976c7
commit b066a48976
Signed by: outfoxxed
GPG key ID: 4C88A185FB89301E
13 changed files with 68 additions and 83 deletions
Download patch file Download diff file Expand all files Collapse all files

153
src/pages/docs/configuration/getting-started.mdx
View file

@ -1,153 +0,0 @@
---
layout: "@layouts/ConfigLayout.astro"
title: "Getting Started"
---
# {frontmatter.title}
> [!NOTE]
> Quickshell is still in a somewhat early stage of development.
> There will be breaking changes before 1.0, however a migration guide will be provided.
## Installation
All packages currently track quickshell's master branch. This may change in the future.
### Nix
The Quickshell repo has an embedded flake.
You can use either `git+https://git.outfoxxed.me/outfoxxed/quickshell`
or `github:quickshell-mirror/quickshell`.
```nix
{
inputs = {
nixpkgs.url = "nixpkgs/nixos-unstable";
quickshell = {
url = "git+https://git.outfoxxed.me/outfoxxed/quickshell";
# THIS IS IMPORTANT
# Mismatched system dependencies will lead to crashes and other issues.
inputs.nixpkgs.follows = "nixpkgs";
};
};
}
```
The package is available as `quickshell.packages.<system>.default`, which you can add to
`environment.systemPackages` or `home.packages` if you use home-manager.
### Arch
Quickshell is available from the aur by [mcgoth] under
the [quickshell](https://aur.archlinux.org/packages/quickshell) package.
> [!WARNING]
> When using the AUR package, quickshell may break any time Qt is updated.
> The AUR gives us no way to actually fix this, but Quickshell will attempt to
> warn you if it detects a breakage when updating. If warned of a breakage,
> please reinstall the package
Install using the command below:
```sh
yay -S quickshell
```
(or your AUR helper of choice)
### Fedora
Quickshell is available from [errornointernet](https://github.com/errornointernet/)'s
Fedora COPR as [errornointernet/quickshell](https://copr.fedorainfracloud.org/coprs/errornointernet/quickshell).
Install using the command below:
```sh
sudo dnf copr enable errornointernet/quickshell
sudo dnf install quickshell
```
## Guix
Quickshell's source repository works as a channel. Add the following to your channel list:
```scheme
(channel
(name quickshell)
(url "https://git.outfoxxed.me/outfoxxed/quickshell")
(branch "master"))
```
Then, you can install the package via `guix install quickshell-git` or by adding `quickshell-git` to your system or home definition.
You can also clone the repository and use `guix shell -f quickshell.scm` to try out the package.
### Manual build
See [BUILD.md](https://git.outfoxxed.me/quickshell/quickshell/src/branch/master/BUILD.md)
for build instructions and configurations.
See [Installation](./installation) if Quickshell isn't installed yet.
## Editor configuration
### Emacs
Install the [yuja/tree-sitter-qml](https://github.com/yuja/tree-sitter-qmljs) tree-sitter grammar,
and the [xhcoding/qml-ts-mode](https://github.com/xhcoding/qml-ts-mode) mode.
Both are packaged for nix via [outfoxxed/nix-qml-support](https://git.outfoxxed.me/outfoxxed/nix-qml-support).
Either `lsp-mode` or `eglot` should be usable for LSP ([caveats below](#language-server)).
The author's personal emacs config uses `lsp-mode` and `qml-ts-mode` as follows:
```elisp
(use-package qml-ts-mode
:after lsp-mode
:config
(add-to-list 'lsp-language-id-configuration '(qml-ts-mode . "qml-ts"))
(lsp-register-client
(make-lsp-client :new-connection (lsp-stdio-connection '("qmlls", "-E"))
:activation-fn (lsp-activate-on "qml-ts")
:server-id 'qmlls))
(add-hook 'qml-ts-mode-hook (lambda ()
(setq-local electric-indent-chars '(?\n ?\( ?\) ?{ ?} ?\[ ?\] ?\; ?,))
(lsp-deferred))))
```
> [!NOTE]
> Qmlls versions prior to 6.8.2 do not require `-E`
### Neovim
Neovim has built-in syntax highlighting for QML, however tree-sitter highlighting
may work better than the built-in highlighting. You can install the grammar
using `:TSInstall qmljs`.
To use the language server ([caveats below](#language-server)),
install [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig)
and the following snippet:
```lua
require("lspconfig").qmlls.setup {
cmd = {"qmlls", "-E"}
}
```
> [!NOTE]
> Qmlls versions prior to 6.8.2 do not require `-E`
## Language Server
The QML language has an associated language server,
[qmlls](https://doc.qt.io/qt-6/qtqml-tooling-qmlls.html).
Please note that the language server, along with quickshell's support of it,
is in development.
We are aware of the following issues:
- Qmlls does not work well when a file is not correctly structured.
This means that completions and lints won't work unless braces are closed
correctly and such.
- Qmlls cannot handle quickshell's singletons. This means you won't see
completions, and usages of singleton members may show a warning.
We're still investigating this problem and how to fix it.
Keeping in mind the above caveats, qmlls should be able to guide you towards
more correct code should you chose to use it.
> [!NOTE]
> Nix users should note that qmlls will not be able to pick up qml modules
> that are not in `QML2_IMPORT_PATH`. The easiest way to ensure this is by setting
> `qt.enable` to `true` and installing the quickshell package globally.
# Next steps
Create your first configuration by reading the [Intro](/docs/configuration/intro).

18
src/pages/docs/configuration/index.mdx
View file

@ -1,18 +0,0 @@
---
layout: "@layouts/ConfigLayout.astro"
title: "Configuration"
description: "Configuring the shell"
---
# {frontmatter.title}
See [Getting Started](/docs/configuration/getting-started) for installation and editor configuration instructions.
You should start with the [Introduction](/docs/configuration/intro) which will guide you
through the basics of QML by creating a simple topbar with a clock.
From there you can read the [QML Overview](/docs/configuration/qml-overview) to get an overview of
the QML language, or jump right into the [Type Reference](/docs/types) to find
types you can use in your shell.
The [quickshell-examples](https://git.outfoxxed.me/quickshell/quickshell-examples) repo contains
fully working example configurations you can read and modify.

840
src/pages/docs/configuration/intro.mdx
View file

@ -1,840 +0,0 @@
---
layout: "@layouts/ConfigLayout.astro"
title: "Introduction"
---
import Collapsible from "@components/Collapsible.astro";
import MD_Title from "@components/MD_Title.tsx"
# {frontmatter.title}
> [!NOTE]
> This guide was created a long time ago, and is somewhat outdated.
> Take a look at @@Quickshell.SystemClock after going through.
This page will walk you through the process of creating a simple bar/panel, and
introduce you to all the basic concepts involved.
There are many links to the [QML Overview](/docs/configuration/qml-overview)
and [Type Reference](/docs/types) which you should follow if you don't
fully understand the concepts involved.
## <MD_Title titleVar={2} client:visible> Shell Files </MD_Title>
Every quickshell instance starts from a shell root file, conventionally named `shell.qml`.
The default path is `~/.config/quickshell/shell.qml`.
(where `~/.config` can be substituted with `$XDG_CONFIG_HOME` if present.)
Each shell file starts with the shell root object. Only one may exist per configuration.
```qml {filename="~/.config/quickshell/shell.qml"}
import Quickshell
@@Quickshell.ShellRoot {
// ...
}
```
The shell root is not a visual element but instead contains all of the visual
and non visual objects in your shell. You can have multiple different shells
with shared components and different shell roots.
<Collapsible title="Shell search paths and manifests">
Quickshell can be launched with configurations in locations other than the default one.
The `-p` or `--path` option will launch the shell root at the given path.
It will also accept folders with a `shell.qml` file in them.
It can also be specified via the `QS_CONFIG_PATH` environment variable.
The `-c` or `--config` option will launch a configuration from the current manifest,
or if no manifest is specified, a subfolder of quickshell's base path.
It can also be specified via the `QS_CONFIG_NAME` environment variable.
The base path defaults to `~/.config/quickshell`, but can be changed using
the `QS_BASE_PATH` environment variable.
The `-m` or `--manifest` option specifies the quickshell manifest to read configs
from. When used with `-c`, the config will be chosen by name from the manifest.
It can also be specified via the `QS_MANIFEST` environment variable.
The manifest path defaults to `~/.config/quickshell/manifest.conf` and is a list
of `name = path` pairs where path can be relative or absolute.
Lines starting with `#` are comments.
```properties
# ~/.config/quickshell/manifest.conf
myconf1 = myconf
myconf2 = ./myconf
myconf3 = myconf/shell.nix
myconf4 = ~/.config/quickshell/myconf
```
You can use `quickshell --current` to print the current values of any of these
options and what set them.
</Collapsible>
## <MD_Title titleVar={2}> Creating Windows </MD_Title>
Quickshell has two main window types available,
[PanelWindow](/docs/types/quickshell/panelwindow) for bars and widgets, and
[FloatingWindow](/docs/types/quickshell/floatingwindow) for standard desktop windows.
We'll start with an example:
```qml
import Quickshell // for ShellRoot and PanelWindow
import QtQuick // for Text
@@Quickshell.ShellRoot {
@@Quickshell.PanelWindow {
anchors {
top: true
left: true
right: true
}
implicitHeight: 30
@@QtQuick.Text {
// center the bar in its parent component (the window)
anchors.centerIn: parent
text: "hello world"
}
}
}
```
The above example creates a bar/panel on your currently focused monitor with
a centered piece of [text](https://doc.qt.io/qt-6/qml-qtquick-text.html). It will also reserve space for itself on your monitor.
More information about available properties is available in the [type reference](/docs/types/quickshell/panelwindow).
## <MD_Title titleVar={2}> Running a process </MD_Title>
Now that we have a piece of text, what if it did something useful?
To start with lets make a clock. To get the time we'll use the `date` command.
We can use a [Process](/docs/types/quickshell.io/process) object to run commands
and return their results.
We'll listen to the @@Quickshell.Io.DataStreamParser.read(s) signal emitted by
@@Quickshell.Io.SplitParser using a
[signal handler](/docs/configuration/qml-overview/#signal-handlers)
to update the text on the clock.
> [!note/Note]
> Quickshell live-reloads your code. You can leave it open and edit the
> original file. The panel will reload when you save it.
```qml
import Quickshell
import Quickshell.Io // for Process
import QtQuick
@@Quickshell.ShellRoot {
@@Quickshell.PanelWindow {
anchors {
top: true
left: true
right: true
}
implicitHeight: 30
@@QtQuick.Text {
// give the text an ID we can refer to elsewhere in the file
id: clock
anchors.centerIn: parent
// create a process management object
@@Quickshell.Io.Process {
// the command it will run, every argument is its own string
command: ["date"]
// run the command immediately
running: true
// process the stdout stream using a SplitParser
// which returns chunks of output after a delimiter
stdout: @@Quickshell.Io.SplitParser {
// listen for the read signal, which returns the data that was read
// from stdout, then write that data to the clock's text property
onRead: data => clock.text = data
}
}
}
}
}
```
## <MD_Title titleVar={2}> Running code at an interval </MD_Title>
With the above example, your bar should now display the time, but it isn't updating!
Let's use a @@QtQml.Timer to fix that.
```qml
import Quickshell
import Quickshell.Io
import QtQuick
@@Quickshell.ShellRoot {
@@Quickshell.PanelWindow {
anchors {
top: true
left: true
right: true
}
implicitHeight: 30
@@QtQuick.Text {
id: clock
anchors.centerIn: parent
@@Quickshell.Io.Process {
// give the process object an id so we can talk
// about it from the timer
id: dateProc
command: ["date"]
running: true
stdout: @@Quickshell.Io.SplitParser {
onRead: data => clock.text = data
}
}
// use a timer to rerun the process at an interval
@@QtQml.Timer {
// 1000 milliseconds is 1 second
interval: 1000
// start the timer immediately
running: true
// run the timer again when it ends
repeat: true
// when the timer is triggered, set the running property of the
// process to true, which reruns it if stopped.
onTriggered: dateProc.running = true
}
}
}
}
```
## <MD_Title titleVar={2}> Reusable components </MD_Title>
If you have multiple monitors you might have noticed that your bar
is only on one of them. If not, you'll still want to **follow this section
to make sure your bar doesn't disappear if your monitor disconnects**.
We can use a @@Quickshell.Variants object to create instances of _non widget items_.
(See @@QtQuick.Repeater for doing
something similar with visual items.)
The @@Quickshell.Variants type creates instances of a @@QtQml.Component based on
a data model you supply. (A component is a re-usable tree of objects.)
The most common use of @@Quickshell.Variants in a shell is to create instances of
a window (your bar) based on your monitor list (the data model).
@@Quickshell.Variants will inject the values in the data model into each new
component's `modelData` property, which means we can easily pass each screen
to its own component. (See @@Quickshell.QsWindow.screen.)
```qml
import Quickshell
import Quickshell.Io
import QtQuick
@@Quickshell.ShellRoot {
@@Quickshell.Variants {
model: Quickshell.screens;
delegate: @@QtQml.Component {
@@Quickshell.PanelWindow {
// the screen from the screens list will be injected into this
// property
property var modelData
// we can then set the window's screen to the injected property
screen: modelData
anchors {
top: true
left: true
right: true
}
implicitHeight: 30
@@QtQuick.Text {
id: clock
anchors.centerIn: parent
@@Quickshell.Io.Process {
id: dateProc
command: ["date"]
running: true
stdout: @@Quickshell.Io.SplitParser {
onRead: data => clock.text = data
}
}
@@QtQml.Timer {
interval: 1000
running: true
repeat: true
onTriggered: dateProc.running = true
}
}
}
}
}
}
```
<span class="small">
See also: [Property Bindings](/docs/configuration/qml-overview/#property-bindings),
[Array.map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map)
</span>
With this example, bars will be created and destroyed as you plug and unplug them,
due to the reactive nature of the
@@Quickshell.Quickshell.screens property.
(See: [Reactive Bindings](/docs/configuration/qml-overview/#reactive-bindings).)
Now there's an important problem you might have noticed: when the window
is created multiple times we also make a new Process and Timer. We can fix
this by moving the Process and Timer outside of the window.
> [!caution/Error]
> This code will not work correctly.
```qml
import Quickshell
import Quickshell.Io
import QtQuick
@@Quickshell.ShellRoot {
@@Quickshell.Variants {
model: Quickshell.screens
delegate: @@QtQml.Component {
@@Quickshell.PanelWindow {
property var modelData
screen: modelData
anchors {
top: true
left: true
right: true
}
implicitHeight: 30
@@QtQuick.Text {
id: clock
anchors.centerIn: parent
}
}
}
}
@@Quickshell.Io.Process {
id: dateProc
command: ["date"]
running: true
stdout: @@Quickshell.Io.SplitParser {
onRead: data => clock.text = data
}
}
@@QtQml.Timer {
interval: 1000
running: true
repeat: true
onTriggered: dateProc.running = true
}
}
```
However there is a problem with naively moving the Process and Timer
out of the component.
_What about the `clock` that the process references?_
If you run the above example you'll see something like this in the console every second:
```
file:///home/name/.config/quickshell/shell.qml:33: ReferenceError: clock is not defined
file:///home/name/.config/quickshell/shell.qml:33: ReferenceError: clock is not defined
file:///home/name/.config/quickshell/shell.qml:33: ReferenceError: clock is not defined
file:///home/name/.config/quickshell/shell.qml:33: ReferenceError: clock is not defined
file:///home/name/.config/quickshell/shell.qml:33: ReferenceError: clock is not defined
```
This is because the `clock` object, even though it has an ID, cannot be referenced
outside of its component. Remember, components can be created _any number of times_,
including zero, so `clock` may not exist or there may be more than one, meaning
there isn't an object to refer to from here.
We can fix it with a [Property Definition](/docs/configuration/qml-overview/#property-definitions).
We can define a property inside of the ShellRoot and reference it from the clock
text instead. Due to QML's [Reactive Bindings](/docs/configuration/qml-overview/#reactive-bindings),
the clock text will be updated when we update the property for every clock that
currently exists.
```qml
import Quickshell
import Quickshell.Io
import QtQuick
@@Quickshell.ShellRoot {
id: root
// add a property in the root
property string time;
@@Quickshell.Variants {
model: Quickshell.screens
delegate: @@QtQml.Component {
@@Quickshell.PanelWindow {
property var modelData
screen: modelData
anchors {
top: true
left: true
right: true
}
implicitHeight: 30
@@QtQuick.Text {
// remove the id as we don't need it anymore
anchors.centerIn: parent
// bind the text to the root's time property
text: root.time
}
}
}
}
@@Quickshell.Io.Process {
id: dateProc
command: ["date"]
running: true
stdout: @@Quickshell.Io.SplitParser {
// update the property instead of the clock directly
onRead: data => root.time = data
}
}
@@QtQml.Timer {
interval: 1000
running: true
repeat: true
onTriggered: dateProc.running = true
}
}
```
Now we've fixed the problem so there's nothing actually wrong with the
above code, but we can make it more concise:
1. `Component`s can be defined implicitly, meaning we can remove the
component wrapping the window and place the window directly into the
`delegate` property.
2. The @@Quickshell.Variants.delegate property is a
[Default Property](/docs/configuration/qml-overview/#the-default-property),
which means we can skip the `delegate:` part of the assignment.
We're already using the default property of @@Quickshell.ShellRoot to store our
Variants, Process, and Timer components among other things.
3. The ShellRoot doesn't actually need an `id` property to talk about
the time property, as it is the outermost object in the file which
has [special scoping rules](/docs/configuration/qml-overview/#property-access-scopes).
This is what our shell looks like with the above (optional) cleanup:
```qml
import Quickshell
import Quickshell.Io
import QtQuick
@@Quickshell.ShellRoot {
property string time;
@@Quickshell.Variants {
model: Quickshell.screens
@@Quickshell.PanelWindow {
property var modelData
screen: modelData
anchors {
top: true
left: true
right: true
}
implicitHeight: 30
@@QtQuick.Text {
anchors.centerIn: parent
// now just time instead of root.time
text: time
}
}
}
@@Quickshell.Io.Process {
id: dateProc
command: ["date"]
running: true
stdout: @@Quickshell.Io.SplitParser {
// now just time instead of root.time
onRead: data => time = data
}
}
@@QtQml.Timer {
interval: 1000
running: true
repeat: true
onTriggered: dateProc.running = true
}
}
```
## <MD_Title titleVar={2}> Multiple files </MD_Title>
In an example as small as this, it isn't a problem, but as the shell
grows it might be preferable to separate it into multiple files.
To start with, let's move the entire bar into a new file.
```qml {filename="shell.qml"}
import Quickshell
@@Quickshell.ShellRoot {
Bar {}
}
```
```qml {filename="Bar.qml"}
import Quickshell
import Quickshell.Io
import QtQuick
@@Quickshell.Scope {
property string time;
@@Quickshell.Variants {
model: Quickshell.screens
@@Quickshell.PanelWindow {
property var modelData
screen: modelData
anchors {
top: true
left: true
right: true
}
implicitHeight: 30
@@QtQuick.Text {
anchors.centerIn: parent
// now just time instead of root.time
text: time
}
}
}
@@Quickshell.Io.Process {
id: dateProc
command: ["date"]
running: true
stdout: @@Quickshell.Io.SplitParser {
// now just time instead of root.time
onRead: data => time = data
}
}
@@QtQml.Timer {
interval: 1000
running: true
repeat: true
onTriggered: dateProc.running = true
}
}
```
<span class="small">See also: [Scope](/docs/types/Quickshell/Scope/)</span>
Any qml file that starts with an uppercase letter can be referenced this way.
We can bring in other folders as well using
[import statements](/docs/configuration/qml-overview/#explicit-imports).
Now what about breaking out the clock? This is a bit more complex because
the clock component in the bar, as well as the process and timer that
make up the actual clock, need to be dealt with.
To start with, we can move the clock widget to a new file. For now it's just a
single @@QtQuick.Text object but the same concepts apply regardless of complexity.
```qml {filename="ClockWidget.qml"}
import QtQuick
@@QtQuick.Text {
// A property the creator of this type is required to set.
// Note that we could just set `text` instead, but don't because your
// clock probably will not be this simple.
required property string time
text: time
}
```
```qml {filename="Bar.qml"}
import Quickshell
import Quickshell.Io
import QtQuick
@@Quickshell.Scope {
id: root
property string time;
@@Quickshell.Variants {
model: Quickshell.screens
@@Quickshell.PanelWindow {
property var modelData
screen: modelData
anchors {
top: true
left: true
right: true
}
implicitHeight: 30
// the ClockWidget type we just created
ClockWidget {
anchors.centerIn: parent
// Warning: setting `time: time` will bind time to itself which is not what we want
time: root.time
}
}
}
@@Quickshell.Io.Process {
id: dateProc
command: ["date"]
running: true
stdout: @@Quickshell.Io.SplitParser {
onRead: data => time = data
}
}
@@QtQml.Timer {
interval: 1000
running: true
repeat: true
onTriggered: dateProc.running = true
}
}
```
While this example is larger than what we had before, we can now expand
on the clock widget without cluttering the bar file.
Let's deal with the clock's update logic now:
```qml {filename="Time.qml"}
import Quickshell
import Quickshell.Io
import QtQuick
@@Quickshell.Scope {
property string time;
@@Quickshell.Io.Process {
id: dateProc
command: ["date"]
running: true
stdout: @@Quickshell.Io.SplitParser {
onRead: data => time = data
}
}
@@QtQml.Timer {
interval: 1000
running: true
repeat: true
onTriggered: dateProc.running = true
}
}
```
```qml {filename="Bar.qml"}
import Quickshell
@@Quickshell.Scope {
// the Time type we just created
Time { id: timeSource }
@@Quickshell.Variants {
model: Quickshell.screens
@@Quickshell.PanelWindow {
property var modelData
screen: modelData
anchors {
top: true
left: true
right: true
}
implicitHeight: 30
ClockWidget {
anchors.centerIn: parent
// now using the time from timeSource
time: timeSource.time
}
}
}
}
```
## <MD_Title titleVar={2}> Singletons </MD_Title>
Now you might be thinking, why do we need the `Time` type in
our bar file, and the answer is we don't. We can make `Time`
a [Singleton](/docs/configuration/qml-overview/#singletons).
A singleton object has only one instance, and is accessible from
any scope.
```qml {filename="Time.qml"}
// with this line our type becomes a singleton
pragma Singleton
import Quickshell
import Quickshell.Io
import QtQuick
// your singletons should always have Singleton as the type
@@Quickshell.Singleton {
property string time
@@Quickshell.Io.Process {
id: dateProc
command: ["date"]
running: true
stdout: @@Quickshell.Io.SplitParser {
onRead: data => time = data
}
}
@@QtQml.Timer {
interval: 1000
running: true
repeat: true
onTriggered: dateProc.running = true
}
}
```
```qml {filename="ClockWidget.qml"}
import QtQuick
@@QtQuick.Text {
// we no longer need time as an input
// directly access the time property from the Time singleton
text: Time.time
}
```
```qml {filename="Bar.qml"}
import Quickshell
@@Quickshell.Scope {
// no more time object
@@Quickshell.Variants {
model: Quickshell.screens
@@Quickshell.PanelWindow {
property var modelData
screen: modelData
anchors {
top: true
left: true
right: true
}
implicitHeight: 30
ClockWidget {
anchors.centerIn: parent
// no more time binding
}
}
}
}
```
## <MD_Title titleVar={2}> JavaScript APIs </MD_Title>
In addition to calling external processes, a [limited set of javascript interfaces] is available.
We can use this to improve our clock by using the [Date API] instead of calling `date`.
[limited set of javascript interfaces]: https://doc.qt.io/qt-6/qtqml-javascript-functionlist.html
[Date API]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date
```qml {filename="Time.qml"}
pragma Singleton
import Quickshell
import Quickshell.Io
import QtQuick
@@Quickshell.Singleton {
property var date: new Date()
property string time: date.toLocaleString(Qt.locale())
@@QtQml.Timer {
interval: 1000
running: true
repeat: true
onTriggered: date = new Date()
}
}
```

224
src/pages/docs/configuration/positioning.mdx
View file

@ -1,224 +0,0 @@
---
layout: "@layouts/ConfigLayout.astro"
title: "Positioning"
---
import MD_Title from "@components/MD_Title.tsx"
# {frontmatter.title}
> [!TIP]
> Read the entire page, understanding this is critical to building a well designed shell.
@@QtQuick.Item has two sets of size properties, actual size (@@QtQuick.Item.width and @@QtQuick.Item.height)
and implicit / desired (@@QtQuick.Item.implicitWidth and @@QtQuick.Item.implicitHeight).
Container items, such as layouts and wrappers, use the implicit size of their children to determine
their own implicit size, and their actual size to detetermine the actual size of their children.
If managed by a container, an Item should not set its own size, and should instead allow
the container to determine it based on its implicit size.
Put simply, implicit size should flow from children to parents, while actual size should flow from
parent to children.
In addition to size, Items also have position properties (@@QtQuick.Item.x and @@QtQuick.Item.y).
Similarly to actual size, (actual) position should not be set directly if your item is managed
by a container, though there is no such thing as implicit position.
> [!WARNING]
> Many QtQuick Items have *zero size* by default (both implicit and actual).
>
> An invisible zero sized item (usually a custom container without implicit size set)
> is a common bug and often manifests as an item being laid out as if it took no space.
>
> Quickshell will attempt to detect zero sized items when a window is initially made visible
> and log a warning, but it cannot detect all cases. Please be aware these exist.
## Container Items
Below is an example container which adds a margin to a rectangle, and interacts properly
with other container types.
```qml
@@QtQuick.Item {
property real margin: 5
// Set the implicit size of the containing item to the size of
// the contained item, plus the margin on each side.
implicitWidth: child.implicitWidth + margin * 2
implicitHeight: child.implicitHeight + margin * 2
@@QtQuick.Rectangle {
id: child
// Set the size of the child item relative to the actual size
// of the parent item. If the parent item is constrained
// or stretched the child's position and size will be similarly
// constrained.
x: parent.margin
y: parent.margin
width: parent.width - parent.margin * 2
height: parent.height - parent.margin * 2
// The child's implicit / desired size, which will be respected
// by the container item as long as it is not constrained
// or stretched.
implicitWidth: 50
implicitHeight: 50
}
}
```
If we were to write this as a reusable component, we could use @@QtQml.Binding
to control the child item's actual size and position.
```qml
@@QtQuick.Item {
id: wrapper
property real margin: 5
required default property Item child
// Set the item's visual children list to just the passed item.
children: [child]
implicitWidth: child.implicitWidth + margin * 2
implicitHeight: child.implicitHeight + margin * 2
// Bind the child's position and size.
// Note that this syntax is exclusive to the Binding type.
@@QtQuick.Binding { wrapper.child.x: wrapper.margin }
@@QtQuick.Binding { wrapper.child.y: wrapper.margin }
@@QtQuick.Binding { wrapper.child.width: wrapper.width - wrapper.margin * 2 }
@@QtQuick.Binding { wrapper.child.height: wrapper.height - wrapper.margin * 2 }
}
```
Note: @@Quickshell.Widgets.WrapperItem is a builtin component that adds margins similarly to this.
### Reducing boilerplate with Anchors
We can reduce the amount of boilerplate we have to write using
[QtQuick Anchors](https://doc.qt.io/qt-6/qtquick-positioning-anchors.html).
Anchors exist as a shorthand way to achieve many common position and size bindings.
See the linked qt documentation for more details on how to use them.
The following example is equivalent to the one above, but uses anchors instead of setting
position and size directly. A similar change can be made to the `Binding` example.
```qml
@@QtQuick.Item {
property real margin: 5
implicitWidth: child.implicitWidth + margin * 2
implicitHeight: child.implicitHeight + margin * 2
@@QtQuick.Rectangle {
id: child
// "Fill" the space occupied by the parent, setting width
anchors.fill: parent
// Add a margin to all anchored sides.
anchors.margins: parent.margin
implicitWidth: 50
implicitHeight: 50
}
}
```
### childrenRect and binding loops
The most common mistake made when creating container items is trying to use @@QtQuick.Item.childrenRect
to determine the size of a child item, such as in the example below:
```qml
@@QtQuick.Item {
implicitWidth: childrenRect.width
implicitHeight: childrenRect.height
@@QtQuick.Rectangle {
anchors.fill: parent
implicitWidth: 50
implicitHeight: 50
}
}
```
While the snippet above might look like it should work, it is actually hiding a nasty bug.
As stated at the top of the page, an item's implicit size should be used to determine
its parent's implicit size, and the parent's actual size should be used to determine
the child's actual size. **`childrenRect` breaks this pattern.**
`childrenRect` encompasses the geometry of all child items, meaning their *actual* geometry,
not their *implicit* geometry. This results in the container item's size having an indirect
dependency on itself, in what is known as a *binding loop*.
If we were to try to figure out what implicitWidth is by hand, it would look something like this:
*container.implicitWidth = container.childrenRect.width = child.width = container.width (via anchor)
= container.implicitWidth = ... (repeats forever)*
which isn't a valid definition.
### MarginWrapper components
To solve the boilerplate problem that often leads users to `childrenRect`, Quickshell comes with
@@Quickshell.Widgets.MarginWrapperManager and a set of components based on it.
@@Quickshell.Widgets.MarginWrapperManager automatically handles the size and position relationship
between a container item and a single child item, skipping most of the boilerplate in the above
examples. See its linked documentation for more information on how to use it.
Rewriting the examples from the top of the page:
```qml
@@QtQuick.Item {
@@Quickshell.Widgets.MarginWrapperManager {
margin: 5
// By default, MarginWrapperManager centers the child
// instead of resizing it when encountering constraints.
resizeChild: true
}
// Automatically detected by MarginWrapperManager as the
// primary child of the container and sized accordingly.
@@QtQuick.Rectangle {
implicitWidth: 50
implicitHeight: 50
}
}
```
Or as a reusable component:
```qml
@@QtQuick.Item {
// A bidirectional binding to manager.margin,
// where the default value is set.
property alias margin: manager.margin
// MarginWrapperManager tries to automatically detect
// the primary child of the container, but exposing the
// child property allows us to both access the child
// externally and override it if automatic detection fails.
property alias child: manager.margin
// MarginWrapperManager automatically manages the implicit size
// of the container and actual size of the child.
@@Quickshell.Widgets.MarginWrapperManager {
id: manager
resizeChild: true
margin: 5 // the default value of margin
}
}
```
Quickshell bundles three of the most commonly used wrappers, which are implemented similarly
to the example above:
- @@Quickshell.Widgets.WrapperItem
- @@Quickshell.Widgets.WrapperRectangle
- @@Quickshell.Widgets.WrapperMouseArea
## Layouts
QtQuick comes with a set of layout types in the
[QtQuick.Layouts](https://doc.qt.io/qt-6/qtquicklayouts-overview.html) module.
Layouts, such as the Row, Column and Grid layout, are extremely useful for positioning
items adjacent to eachother. See the linked qt documentation for more details.
> [!NOTE]
> Layouts have a default spacing of 5 pixels between items, not zero.

886
src/pages/docs/configuration/qml-overview.mdx
View file

@ -1,886 +0,0 @@
---
layout: "@layouts/ConfigLayout.astro"
title: "QML Overview"
---
import MD_Title from "@components/MD_Title.tsx"
import Collapsible from "@components/Collapsible.astro";
# {frontmatter.title}
Quickshell is configured using the Qt Modeling Language, or QML.
This page explains what you need to know about QML to start using quickshell.
<span class="small">
See also: [Qt Documentation: QML
Tutorial](https://doc.qt.io/qt-6/qml-tutorial.html)
</span>
## <MD_Title titleVar={2}> Structure </MD_Title>
Below is a QML document showing most of the syntax.
Keep it in mind as you read the detailed descriptions below.
> [!note/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 problems early instead of running into them unexpectedly later on.
```qml
// QML Import statement
import QtQuick 6.0
// Javascript import statement
import "myjs.js" as MyJs
// Root Object
@@QtQuick.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
}
}
```
### <MD_Title titleVar={3}> Imports </MD_Title>
#### <MD_Title titleVar={4}> Manual imports </MD_Title>
Every QML File begins with a list of imports.
Import statements tell the QML engine where
to look for types you can create [objects](#objects) from.
A module import statement looks like this:
```qml
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:
```qml
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:
```qml
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.
##### <MD_Title titleVar={5}> Examples </MD_Title>
```qml
import QtQuick
import QtQuick.Controls 6.0
import Quickshell as QS
import QtQuick.Layouts 6.0 as L
import "jsfile.js" as JsFile
```
<Collapsible title="When no module version">
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 doesn'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.
</Collapsible>
<span class="small">
[Qt Documentation: Import
syntax](https://doc.qt.io/qt-6/qtqml-syntax-imports.html)
</span>
#### <MD_Title titleVar={4}> Implicit imports </MD_Title>
The QML engine will automatically import any [types](#creating-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.
### <MD_Title titleVar={3}> Objects </MD_Title>
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:
```qml
Name {
id: foo
// properties, functions, signals, etc...
}
```
Every object can contain [properties](#properties), [functions](#functions),
and [signals](#signals). You can find out what properties are available for a type
by looking it up in the [Type Reference](/docs/types/).
#### <MD_Title titleVar={4}> Properties </MD_Title>
Every object may have any number of property assignments (only one per specific property).
Each assignment binds the named property to the given expression.
##### <MD_Title titleVar={5}> Property bindings </MD_Title>
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.
```qml
@@QtQuick.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_](#reactive-bindings), which means when any property the expression depends
on is updated, the expression is re-evaluated and the property is updated.
<span class="small">See: [Reactive bindings](#reactive-bindings)</span>
Note that it is an error to try to assign to a property that does not exist.
(See: [property definitions](#property-definitions))
##### <MD_Title titleVar={5}> Property definitions </MD_Title>
Properties can be defined inside of objects with the following syntax:
```qml
[required] [readonly] [default] property <type> <name>[: binding]
```
- `required` forces users of this type to assign this property. See [Creating Types](#creating-types) for details.
- `readonly` makes the property not assignable. Its binding will still be [reactive](#reactive-bindings).
- `default` makes the property the [default 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](#property-bindings) for details.
```qml
@@QtQuick.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.
##### <MD_Title titleVar={5}> The default property </MD_Title>
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:
```qml
@@QtQuick.Item {
// normal property
foo: 3
// this item is assigned to the outer object's default property
@@QtQuick.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:
```qml
@@QtQuick.Item {
// normal property
foo: 3
// this item is assigned to the outer object's default property
@@QtQuick.Item {
}
// this one is too
@@QtQuick.Item {
}
}
```
##### <MD_Title titleVar={5}> The `id` property </MD_Title>
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.
```qml
@@QtQuick.Layouts.ColumnLayout {
@@QtQuick.Text {
id: text
text: "Hello World!"
}
@@QtQuick.Controls.Button {
text: "Make the text red";
onClicked: text.color = "red";
}
}
```
<Collapsible title="The `id` property compared to normal properties">
The `id` property isn't really a property, and doesn'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.
</Collapsible>
##### <MD_Title titleVar={5}> Property access scopes </MD_Title>
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](#the-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.
```qml
@@QtQuick.Item {
property string rootDefinition
@@QtQuick.Item {
id: mid
property string midDefinition
@@QtQuick.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
}
}
}
```
<span class="small">
[Qt Documentation: Scope and Naming
Resolution](https://doc.qt.io/qt-6/qtqml-documents-scope.html)
</span>
#### <MD_Title titleVar={4}> Functions </MD_Title>
Functions in QML can be declared everywhere [properties](#properties) can, and follow
the same [scoping rules](#property-access-scopes).
Function definition syntax:
```qml
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.
```qml
@@QtQuick.Layouts.ColumnLayout {
property int clicks: 0
function makeClicksLabel(): string {
return "the button has been clicked " + clicks + " times!";
}
@@QtQuick.Controls.Button {
text: "click me"
onClicked: clicks += 1
}
@@QtQuick.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`.
##### <MD_Title titleVar={5}> Lambdas </MD_Title>
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:
```qml
<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:
```qml
@@QtQuick.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:
```qml
@@QtQuick.Layouts.ColumnLayout {
property int clicks: 0
function incrementAndCall(callback) {
clicks += 1;
callback(clicks);
}
@@QtQuick.Controls.Button {
text: "click me"
onClicked: incrementAndCall(clicks => {
label.text = `the button was clicked ${clicks} time(s)!`;
})
}
@@QtQuick.Text {
id: label
text: "the button has not been clicked"
}
}
```
#### <MD_Title titleVar={4}> Signals </MD_Title>
A signal is basically an event emitter you can connect to and receive updates from.
They can be declared everywhere [properties](#properties) and [functions](#functions)
can, and follow the same [scoping rules](#property-access-scopes).
<span class="small">
[Qt Documentation: Signal and Handler Event
System](https://doc.qt.io/qt-6/qtqml-syntax-signals.html)
</span>
##### <MD_Title titleVar={5}> Signal definitions </MD_Title>
A signal can be explicitly defined with the following syntax:
```qml
signal <name>(<paramname>: <type>[, ...])
```
##### <MD_Title titleVar={5}> Making connections </MD_Title>
Signals all have a `connect(<function>)` method which invokes the given function
or signal when the signal is emitted.
```qml
@@QtQuick.Layouts.ColumnLayout {
property int clicks: 0
function updateText() {
clicks += 1;
label.text = `the button has been clicked ${clicks} times!`;
}
@@QtQuick.Controls.Button {
id: button
text: "click me"
}
@@QtQuick.Text {
id: label
text: "the button has not been clicked"
}
Component.onCompleted: {
button.clicked.connect(updateText)
}
}
```
<span class="small">
`Component.onCompleted` will be addressed later in [Attached
Properties](#attached-properties) but for now just know that it runs
immediately once the object is fully initialized.
</span>
When the button is clicked, the button emits the @@QtQuick.Controls.Button.clicked(s)
signal which we connected to `updateText`. The signal then invokes `updateText`
which updates the counter and the text on the label.
##### <MD_Title titleVar={5}> Signal handlers </MD_Title>
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 corresponding `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](#making-connections),
this time using the implicit signal handler property to handle @@QtQuick.Controls.Button.clicked(s).
```qml
@@QtQuick.Layouts.ColumnLayout {
property int clicks: 0
function updateText() {
clicks += 1;
label.text = `the button has been clicked ${clicks} times!`;
}
@@QtQuick.Controls.Button {
text: "click me"
onClicked: updateText()
}
@@QtQuick.Text {
id: label
text: "the button has not been clicked"
}
}
```
##### <MD_Title titleVar={5}> Indirect signal handlers </MD_Title>
When it is not possible or not convenient to directly define a signal handler, before resorting
to `.connect`ing the properties, a @@QtQml.Connections object can be used to access them.
This is especially useful to connect to signals of singletons.
```qml
@@QtQuick.Item {
@@QtQuick.Controls.Button {
id: myButton
text "click me"
}
@@QtQml.Connections {
target: myButton
function onClicked() {
// ...
}
}
}
```
##### <MD_Title titleVar={5}> Property change signals </MD_Title>
Every property has an associated signal, which powers QML's [reactive bindings](#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.
```qml
@@QtQuick.Layouts.ColumnLayout {
@@QtQuick.Controls.CheckBox {
text: "check me"
onCheckStateChanged: {
label.text = labelText(checkState == Qt.Checked);
}
}
@@QtQuick.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 @@QtQuick.Controls.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:
```qml
@@QtQuick.Layouts.ColumnLayout {
@@QtQuick.Controls.CheckBox {
id: checkbox
text: "check me"
}
@@QtQuick.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:
```qml
@@QtQuick.Layouts.ColumnLayout {
@@QtQuick.Controls.CheckBox {
id: checkbox
text: "check me"
}
@@QtQuick.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.
##### <MD_Title titleVar={5}> Attached objects </MD_Title>
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 @@QtQml.Component type,
which is attached to every object and often used to run code when an object initializes.
```qml
@@QtQuick.Text {
Component.onCompleted: {
text = "hello!"
}
}
```
In this example, the text property is set inside the `Component.onCompleted` attached signal handler.
#### <MD_Title titleVar={4}> Creating types </MD_Title>
Every QML file with an uppercase name is implicitly a type, and can be used from
neighboring files or imported (See [Imports](#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](#the-id-property)
are not visible outside the file.
```qml
// MyText.qml
@@QtQuick.Rectangle {
required property string text
color: "red"
implicitWidth: textObj.implicitWidth
implicitHeight: textObj.implicitHeight
@@QtQuick.Text {
id: textObj
anchors.fill: parent
text: parent.text
}
}
// AnotherComponent.qml
@@QtQuick.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
}
}
```
##### <MD_Title titleVar={5}> Singletons </MD_Title>
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.
To ensure it behaves correctly with quickshell you should also make
@@Quickshell.Singleton the root item of your type.
```qml
pragma Singleton
import ...
@@Quickshell.Singleton {
...
}
```
once a type is a singleton, its members can be accessed by name from neighboring
files.
## <MD_Title titleVar={2}> Concepts </MD_Title>
### <MD_Title titleVar={3}> Reactive bindings </MD_Title>
<span class="small">
This section assumes knowledge of: [Properties](#properties),
[Signals](#signals), and [Functions](#functions). See also the [Qt
documentation](https://doc.qt.io/qt-6/qtqml-syntax-propertybinding.html).
</span>
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:
##### <MD_Title titleVar={5}> Automatic bindings </MD_Title>
A reactive binding occurs automatically when you use one or more properties in the definition
of another property. .
```qml
@@QtQuick.Item {
property int clicks: 0
@@QtQuick.Controls.Button {
text: `clicks: ${clicks}`
onClicked: clicks += 1
}
}
```
In this example, the button's @@QtQuick.Controls.Button.text property is re-evaluated
every time the button is clicked, because the `clicks` property has changed.
###### <MD_Title titleVar={6}> Avoiding creation </MD_Title>
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.
```qml
@@QtQuick.Item {
property string theProperty: "initial value"
@@QtQuick.Text {
// text: "Right now, theProperty is: " + theProperty
Component.onCompleted: text = "At creation time, theProperty is: " + theProperty
}
}
```
##### <MD_Title titleVar={5}> Manual bindings </MD_Title>
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.
```qml
@@QtQuick.Item {
@@QtQuick.Text {
id: boundText
text: "not bound to anything"
}
@@QtQuick.Controls.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.
##### <MD_Title titleVar={5}> Removing bindings </MD_Title>
To remove a binding, just assign a new value to the property without using `Qt.binding`.
```qml
@@QtQuick.Item {
@@QtQuick.Text {
id: boundText
text: `button is pressed: ${theButton.pressed}`
}
@@QtQuick.Controls.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.
### <MD_Title titleVar={3}> Lazy loading </MD_Title>
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 be immediately visible, load them
asynchronously using a @@Quickshell.LazyLoader.
See its documentation for more information.
#### <MD_Title titleVar={4}> Components </MD_Title>
Another delayed loading mechanism is the @@QtQml.Component type.
This type can be used to create multiple instances of objects or lazily load them. It's used by types such
as @@QtQuick.Repeater and @@Quickshell.Variants to create instances of a component at runtime.

30
src/pages/docs/guide/[...id].astro Normal file
View file

@ -0,0 +1,30 @@
---
import DocsLayout from "@layouts/DocsLayout.astro";
import TOC from "@components/navigation/sidebars/TOC.astro";
import TOCIntersectionObserver from "@src/components/hooks/TOCIntersectionObserver.astro";
import { getCollection, render } from "astro:content";
export async function getStaticPaths() {
const guidePages = await getCollection("guide");
return guidePages.map(page => ({
params: { id: page.id == "index" ? "/" : page.id },
props: { page },
}));
}
const { page } = Astro.props;
const { Content, headings } = await render(page);
---
<DocsLayout title={page.data.title} description="" headings={headings}>
<div class="docs">
<div class="docs-content">
<hr>
<Content/>
</div>
<TOC mobile={false} headings={headings} data-pagefind-ignore/>
</div>
</DocsLayout>
<TOCIntersectionObserver/>

2
src/pages/docs/index.astro
View file

@ -4,7 +4,7 @@ import DocsLayout from "@layouts/DocsLayout.astro";
<DocsLayout title="Quickshell Docs" description="Quickshell Documentation">
<h2>Docs</h2>
<div class="root-nav">
<h3><a href="/docs/configuration">Configuration</a></h3>
<h3><a href="/docs/guide">Guide</a></h3>
<h3><a href="/docs/types">Type Definitions</a></h3>
</div>
</DocsLayout>