Quickshell

https://quickshell.org/docs/v0.2.0
Admin
Quickshell is a QML-based shell and application launcher for Wayland compositors, offering extensive...
Tokens:31,864
Snippets:184
Trust Score:7.1
Update:1 year ago
Show doc for...
Tokens:
Raw
### Guix Installation Command for Quickshell

Source: https://quickshell.org/docs/v0.2.0/guide/install-setup

Command to install the release version of Quickshell from the standard Guix repository using `guix install`. The git version requires adding the repository as a channel or using `guix shell -f quickshell.scm`.

```bash
guix install quickshell
```

--------------------------------

### AUR Installation Commands for Quickshell

Source: https://quickshell.org/docs/v0.2.0/guide/install-setup

Commands to install Quickshell from the Arch User Repository (AUR). The `quickshell` package installs the latest release, while `quickshell-git` tracks the master branch. Be aware that AUR packages may break upon Qt updates.

```bash
yay -S quickshell
# or
yay -S quickshell-git
```

--------------------------------

### Neovim Configuration for QML Language Server

Source: https://quickshell.org/docs/v0.2.0/guide/install-setup

Neovim Lua configuration snippet to set up the `qmlls` language server using the `nvim-lspconfig` plugin. This provides language support features for QML files within Neovim.

```lua
require("lspconfig").qmlls.setup {}
```

--------------------------------

### Fedora COPR Installation Commands for Quickshell

Source: https://quickshell.org/docs/v0.2.0/guide/install-setup

Commands to enable the Quickshell COPR repository and install either the latest release (`quickshell`) or the git version (`quickshell-git`) on Fedora systems using DNF.

```bash
sudo dnf copr enable errornointernet/quickshell

sudo dnf install quickshell
# or
sudo dnf install quickshell-git
```

--------------------------------

### Nix Flake Configuration for Quickshell

Source: https://quickshell.org/docs/v0.2.0/guide/install-setup

This Nix flake configuration allows you to pin Quickshell to a specific Git repository or mirror and ensures that the Nixpkgs dependency follows the main Nixpkgs input. This is crucial for avoiding system dependency mismatches.

```nix
{
  inputs = {
    nixpkgs.url = "nixpkgs/nixos-unstable";

    quickshell = {
      # add ?ref=<tag> to track a tag
      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";
    };
  };
}
```

--------------------------------

### Emacs Configuration for QML Language Server

Source: https://quickshell.org/docs/v0.2.0/guide/install-setup

Emacs Lisp configuration for integrating the QML language server (`qmlls`) using `lsp-mode` and `qml-ts-mode`. This setup enables features like code completion and diagnostics for QML files.

```emacs-lisp
(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"))
                    :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))))
```

--------------------------------

### Guix Channel Configuration for Quickshell Git Version

Source: https://quickshell.org/docs/v0.2.0/guide/install-setup

Configuration to add the Quickshell Git repository as a channel in Guix. This allows tracking the master branch directly from the source repository. Note that the package definition is within the repository, requiring specific usage with `guix shell` if used directly.

```scheme
(channel
  (name quickshell)
  (url "https://git.outfoxxed.me/outfoxxed/quickshell")
  (branch "master"))
```

--------------------------------

### QML Document Structure and Syntax Example

Source: https://quickshell.org/docs/v0.2.0/guide/qml-language

Demonstrates the fundamental structure of a QML document, including import statements, object instantiation, property declarations and bindings, signal declarations and handlers, and function definitions. This snippet is key for understanding QML syntax.

```QML
// 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
  }

  // Inline component
  component MyComponent: Object {
    // ...
  }
}
```

--------------------------------

### QML Lambda Callback Example

Source: https://quickshell.org/docs/v0.2.0/guide/qml-language

An advanced example of using QML lambdas as callbacks within a click counter mechanism. It demonstrates passing a lambda function to another function to handle UI updates dynamically.

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

--------------------------------

### Asynchronous PopupWindow Loading with LazyLoader in QML

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell/LazyLoader

This example demonstrates how to use LazyLoader to asynchronously load a PopupWindow in Quickshell. The popup is prepared in the background, allowing the main panel to display first. Accessing the popup's item before it's loaded will block the UI thread. This setup is useful for components that are not immediately visible or required.

```QML
import QtQuick
import QtQuick.Controls
import Quickshell

ShellRoot {
  PanelWindow {
    id: window
    height: 50

    anchors {
      bottom: true
      left: true
      right: true
    }

    LazyLoader {
      id: popupLoader

      // start loading immediately
      loading: true

      // this window will be loaded in the background during spare
      // frame time unless active is set to true, where it will be
      // loaded in the foreground
      PopupWindow {
        // position the popup above the button
        parentWindow: window
        relativeX: window.width / 2 - width / 2
        relativeY: -height

        // some heavy component here

        width: 200
        height: 200
      }
    }

    Button {
      anchors.centerIn: parent
      text: "show popup"

      // accessing popupLoader.item will force the loader to
      // finish loading on the UI thread if it isn't finished yet.
      onClicked: popupLoader.item.visible = !popupLoader.item.visible
    }
  }
}
```

--------------------------------

### Configure Quickshell SocketServer

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell.Io/SocketServer

This example demonstrates how to configure a Quickshell SocketServer. It specifies the server's active state, the path for the socket file, and a custom handler for managing connections and parsing messages. The handler includes logic for logging connection status changes and received messages.

```Quik
SocketServer {
  active: true
  path: "/path/too/socket.sock"
  handler: Socket {
    onConnectedChanged: {
      console.log(connected ? "new connection!" : "connection dropped!")
    }
    parser: SplitParser {
      onRead: message => console.log(`read message from socket: ${message}`)
    }
  }
}
```

--------------------------------

### Container Item with Anchors - QML

Source: https://quickshell.org/docs/v0.2.0/guide/size-position

This QML example demonstrates how to reduce boilerplate code for creating container items with margins by utilizing QtQuick Anchors. Anchors provide a shorthand for common position and size bindings, making the code more concise. This version achieves the same layout behavior as the manual position and size setting examples.

```qml
Item {
  property real margin: 5

  implicitWidth: child.implicitWidth + margin * 2
  implicitHeight: child.implicitHeight + margin * 2

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

--------------------------------

### Hyprland Global Shortcut Binding Example

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell.Hyprland/GlobalShortcut

Example of how to bind a global shortcut within Hyprland using the GlobalShortcut object. This format specifies modifiers, key, action, and application-specific details. The protocol does not allow duplicate appid + name pairs, and conflicts can lead to client crashes.

```plaintext
bind = <modifiers>, <key>, global, <appid>:<name>

```

--------------------------------

### Displaying System Time with SystemClock and Qt.formatDateTime

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell/SystemClock

This example demonstrates how to use the SystemClock object to display the current system time formatted as a string. It initializes SystemClock with second precision and uses Qt.formatDateTime to present the date and time in a user-defined format.

```javascript
SystemClock {
  id: clock
  precision: SystemClock.Seconds
}

Text {
  text: Qt.formatDateTime(clock.date, "hh:mm:ss - yyyy-MM-dd")
}
```

--------------------------------

### QML Attached Object: Component.onCompleted

Source: https://quickshell.org/docs/v0.2.0/guide/qml-language

Demonstrates the use of the `Component.onCompleted` attached object to execute code once an object is initialized. This is a common pattern for performing setup tasks or initializations for QML elements.

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

--------------------------------

### Example: WrapperWidget using Default Property

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell.Widgets/WrapperManager

Demonstrates how to use the default property of a WrapperWidget to specify its visual child item, such as a Text or Scope component.

```javascript
WrapperWidget { // a widget that uses WrapperManager
  // Putting the item inline uses the default property of WrapperWidget.
  Text { text: "Hello" }

  // Scope does not extend Item, so it can be placed in the
  // default property without issue.
  Scope {}
}
```

--------------------------------

### Example: Implementing Custom Wrapper Types

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell.Widgets/WrapperManager

Shows how to create a custom wrapper component using WrapperManager. This involves aliasing the WrapperManager's 'child' property to allow consumers to set the visual child.

```javascript
Item { // your wrapper component
  WrapperManager { id: wrapperManager }

  // Allows consumers of your wrapper component to use the child property.
  property alias child: wrapperManager.child

  // The rest of your component logic. You can use
  // `wrapperManager.child` or `this.child` to refer to the selected child.
}
```

--------------------------------

### QtObject: Reusing Window on Every Screen

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell/Quickshell

Demonstrates how to configure Quickshell to create a window instance on each connected screen. This setup dynamically adapts to screen additions or removals, ensuring a window is always present on every active screen. It utilizes the `Quickshell.screens` property to iterate through available screens.

```qml
ShellRoot {
  Variants {
    // see Variants for details
    variants: Quickshell.screens
    PanelWindow {
      property var modelData
      screen: modelData
    }
  }
}
```

--------------------------------

### Execute Process with Context in Quickshell

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell.Io/Process

Launches a process with specified arguments or a context object. It can manage command, environment, and working directory. Arguments must be in a list, and shell scripts require explicit invocation of a shell. This is equivalent to setting process properties and then starting the process.

```javascript
exec(context: {
  command?: string[];
  environment?: { [key: string]: string };
  clearEnvironment?: boolean;
  workingDirectory?: string;
} | string[]): void;
```

--------------------------------

### Get Cache/Data/State Paths with Quickshell API

Source: https://quickshell.org/docs/v0.2.0/guide/faq

Demonstrates how to obtain file paths for Quickshell's cache, data, and state directories using the Quickshell API. These paths are useful for storing application-specific data.

```javascript
Quickshell.cachePath()
Quickshell.dataPath()
Quickshell.statePath()
```

--------------------------------

### Registering IPC Handlers for a Qt Rectangle

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell.Io/IpcHandler

This example demonstrates how to define an IpcHandler for a Qt Rectangle, exposing functions to set and get its color, angle, and radius. It illustrates the syntax for defining handler functions with specific argument and return types.

```qml
FloatingWindow {
  Rectangle {
    id: rect
    anchors.centerIn: parent
    width: 100
    height: 100
    color: "red"
  }

  IpcHandler {
    target: "rect"

    function setColor(color: color): void { rect.color = color; }
    function getColor(): color { return rect.color; }
    function setAngle(angle: real): void { rect.rotation = angle; }
    function getAngle(): real { return rect.rotation; }
    function setRadius(radius: int): void { rect.radius = radius; }
    function getRadius(): int { return rect.radius; }
  }
}
```

--------------------------------

### Example: WrapperWidget using Child Property

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell.Widgets/WrapperManager

Illustrates the use of the 'child' property in WrapperWidget to explicitly define which of its Item-based children should be the visual child, resolving ambiguity when multiple children are present.

```javascript
WrapperWidget {
  Text {
    id: text
    text: "Hello"
  }

  Text {
    id: otherText
    text: "Other Text"
  }

  // Both text and otherText extend Item, so one must be specified.
  child: text
}
```

--------------------------------

### Control Process Running State

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell.Io/Process

Demonstrates how to control the running state of a process. Setting `running` to true starts the process, while setting it to false sends a SIGTERM signal. The `onRunningChanged` signal can be used to restart a process if it stops.

```qml
Process {
  running: true
  onRunningChanged: if (!running) running = true
}
```

--------------------------------

### ColorQuantizer Example Usage

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell/ColorQuantizer

Demonstrates how to use the ColorQuantizer QtObject to perform color quantization on an image. It shows setting the source image, recursion depth, and rescaling size for processing. The resulting prevalent colors can be accessed via the 'colors' property.

```JavaScript
ColorQuantizer {
  id: colorQuantizer
  source: Qt.resolvedUrl("./yourImage.png")
  depth: 3 // Will produce 8 colors (2³)
  rescaleSize: 64 // Rescale to 64x64 for faster processing
}
```

--------------------------------

### QML Lambda Syntax for Function Assignment

Source: https://quickshell.org/docs/v0.2.0/guide/qml-language

Illustrates the concise syntax of QML lambdas for assigning functions to properties, simplifying inline function definitions. Examples show both single-expression and multi-line lambda bodies.

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

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

--------------------------------

### HyprlandFocusGrab Example - QML

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell.Hyprland/HyprlandFocusGrab

Demonstrates how to use HyprlandFocusGrab to manage focus for a FloatingWindow. The button's text dynamically updates based on the grab's active state, and clicking it toggles the focus grab.

```qml
import Quickshell
import Quickshell.Hyprland
import QtQuick.Controls

ShellRoot {
  FloatingWindow {
    id: window

    Button {
      anchors.centerIn: parent
      text: grab.active ? "Remove exclusive focus" : "Take exclusive focus"
      onClicked: grab.active = !grab.active
    }

    HyprlandFocusGrab {
      id: grab
      windows: [ window ]
    }
  }
}
```

--------------------------------

### Inspecting and Invoking IPC Handlers via CLI

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell.Io/IpcHandler

This section shows command-line examples for inspecting registered IPC handlers using `qs ipc show` and invoking them using `qs ipc call`. It demonstrates how to call functions like `setColor`, `setAngle`, `setRadius`, and retrieve values using `getColor`, `getAngle`, and `getRadius`.

```shell
$ qs ipc show
target rect
  function setColor(color: color): void
  function getColor(): color
  function setAngle(angle: real): void
  function getAngle(): real
  function setRadius(radius: int): void
  function getRadius(): int
```

```shell
$ qs ipc call rect setColor orange
$ qs ipc call rect setAngle 40.5
$ qs ipc call rect setRadius 30
$ qs ipc call rect getColor
#ffffa500
$ qs ipc call rect getAngle
40.5
$ qs ipc call rect getRadius
30
```

--------------------------------

### Update Panel Content at Interval using Timer (QML)

Source: https://quickshell.org/docs/v0.2.0/guide/introduction

Extends the previous example by introducing a `Timer` to periodically rerun a process and update the displayed content. This allows for dynamic updates, such as a clock that shows the current time.

```qml
import Quickshell
import Quickshell.Io
import QtQuick

PanelWindow {
  anchors {
    top: true
    left: true
    right: true
  }

  implicitHeight: 30

  Text {
    id: clock
    anchors.centerIn: parent

    Process {
      // give the process object an id so we can talk
      // about it from the timer
      id: dateProc

      command: ["date"]
      running: true

      stdout: StdioCollector {
        onStreamFinished: clock.text = this.text
      }
    }

    // use a timer to rerun the process at an interval
    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
    }
  }
}
```

--------------------------------

### System Clock Integration in QML

Source: https://context7.com/context7/quickshell_v0_2_0/llms.txt

This QML code demonstrates how to integrate the SystemClock component to get the current date and time. It uses a Singleton to make the time property accessible globally and formats it into a readable string. The precision is set to Seconds.

```qml
import Quickshell
import QtQuick

Singleton {
  id: root
  property string time: Qt.formatDateTime(clock.date, "hh:mm:ss - yyyy-MM-dd")

  SystemClock {
    id: clock
    precision: SystemClock.Seconds
  }
}
```

--------------------------------

### Automatic QML Property Binding Example

Source: https://quickshell.org/docs/v0.2.0/guide/qml-language

Demonstrates an automatic reactive binding where a Button's text updates when the 'clicks' property changes. This binding is created implicitly by referencing the 'clicks' property within the Button.text definition.

```QML
Item {
  property int clicks: 0

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

--------------------------------

### QML FileView with JsonAdapter Example

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell.Io/JsonAdapter

This QML snippet demonstrates the usage of JsonAdapter within a FileView. It shows how to define properties, handle file changes, and update the adapter. The adapter synchronizes QML properties with a JSON file, emitting signals on changes.

```qml
FileView {
  path: "/path/to/file"

  // when changes are made on disk, reload the file's content
  watchChanges: true
  onFileChanged: reload()

  // when changes are made to properties in the adapter, save them
  onAdapterUpdated: writeAdapter()

  JsonAdapter {
    property string myStringProperty: "default value"
    onMyStringPropertyChanged: {
      console.log("myStringProperty was changed via qml or on disk")
    }

    property list<string> stringList: [ "default", "value" ]

    property JsonObject subObject: JsonObject {
      property string subObjectProperty: "default value"
      onSubObjectPropertyChanged: console.log("same as above")
    }

    // works the same way as subObject
    property var inlineJson: { "a": "b" }
  }
}
```

--------------------------------

### Reusable Singleton Component for Time in QML

Source: https://context7.com/context7/quickshell_v0_2_0/llms.txt

This QML snippet defines a reusable Singleton component named 'Time' that exposes a formatted current time string. It leverages the SystemClock component. The example also shows how to use this singleton in other QML files.

```qml
// Time.qml
pragma Singleton

import Quickshell
import QtQuick

Singleton {
  id: root
  readonly property string time: Qt.formatDateTime(clock.date, "ddd MMM d hh:mm:ss AP t yyyy")

  SystemClock {
    id: clock
    precision: SystemClock.Seconds
  }
}

// Usage in any file:
// Text { text: Time.time }
```

--------------------------------

### Optimize Resource Usage with Scope for Monitor Bars

Source: https://quickshell.org/docs/v0.2.0/guide/introduction

This code refactors the previous example by moving the Process and Timer outside the Variants delegate using a Scope. This prevents new Process and Timer instances for each monitor bar, improving efficiency.

```qml
import Quickshell
import Quickshell.Io
import QtQuick

Scope {
  Variants {
    model: Quickshell.screens

    delegate: Component {
      PanelWindow {
        required property var modelData
        screen: modelData

        anchors {
          top: true
          left: true
          right: true
        }

        implicitHeight: 30

        Text {
          id: clock
          anchors.centerIn: parent
        }
      }
    }
  }

  Process {
    id: dateProc
    command: ["date"]
    running: true

    stdout: StdioCollector {
      onStreamFinished: clock.text = this.text
    }
  }

  Timer {
    interval: 1000
    running: true
    repeat: true
    onTriggered: dateProc.running = true
  }
}
```

--------------------------------

### Implement Persistent Data Storage for Application Settings

Source: https://context7.com/context7/quickshell_v0_2_0/llms.txt

This QML snippet shows how to use Quickshell's PersistentProperties to store application settings like launch count and last user. Data is saved to a JSON file specified by Quickshell.dataPath(). The Component.onCompleted handler increments the launch count and updates the last user upon application start.

```qml
import Quickshell
import QtQuick

Scope {
  PersistentProperties {
    id: persist
    path: Quickshell.dataPath("settings.json")

    property int launchCount: 0
    property string lastUser: ""
  }

  Component.onCompleted: {
    persist.launchCount++
    persist.lastUser = Quickshell.env("USER")
    console.log(`Launched ${persist.launchCount} times by ${persist.lastUser}`)
  }
}
```

--------------------------------

### PersistentProperties State Management in Quickshell

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell/PersistentProperties

This snippet demonstrates how to use PersistentProperties to maintain the state of UI elements across reloads. The `expanderOpen` boolean property is saved and restored, ensuring an expandable panel retains its open or closed state. This is useful for features like keeping popups open or preserving styling configurations.

```Quickshell
PersistentProperties {
  id: persist
  reloadableId: "persistedStates"

  property bool expanderOpen: false
}

Button {
  id: expanderButton
  anchors.centerIn: parent
  text: "toggle expander"
  onClicked: persist.expanderOpen = !persist.expanderOpen
}

Rectangle {
  anchors.top: expanderButton.bottom
  anchors.left: expanderButton.left
  anchors.right: expanderButton.right
  height: 100

  color: "lightblue"
  visible: persist.expanderOpen
}
```

--------------------------------

### Anchor PopupWindow to Parent Window

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell/PopupWindow

This example shows two ways to set the anchor for a PopupWindow to a parent window. The first method uses the shorthand `anchor.window: parentwindow`. The second method uses a block to define the `anchor` properties, including the `window` it should be anchored to. This is crucial for positioning the popup correctly.

```unknown
PopupWindow {
  anchor.window: parentwindow
  // or
  anchor {
    window: parentwindow
  }
}
```

--------------------------------

### QML Inlined Text Binding Expression

Source: https://quickshell.org/docs/v0.2.0/guide/qml-language

Illustrates an even more compact way to bind a Text element's content by inlining the logic directly into the `text` property. This example uses a block to declare a local variable and return the formatted string, showcasing flexibility in defining bindings.

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

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

--------------------------------

### Create Basic Panel Window with Text (QML)

Source: https://quickshell.org/docs/v0.2.0/guide/introduction

Demonstrates how to create a simple panel window using Quickshell and display 'hello world' text. It utilizes `PanelWindow` for the bar and `Text` for displaying content, anchoring the text to the center.

```qml
import Quickshell // for PanelWindow
import QtQuick // for Text

PanelWindow {
  anchors {
    top: true
    left: true
    right: true
  }

  implicitHeight: 30

  Text {
    // center the bar in its parent component (the window)
    anchors.centerIn: parent

    text: "hello world"
  }
}
```

--------------------------------

### Greetd Singleton

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell.Services.Greetd/Greetd

Provides access to a running greetd instance for user authentication and session launching.

```APIDOC
## Greetd Singleton

This object provides access to a running greetd instance if present. With it you can authenticate a user and launch a session.
See the greetd wiki for instructions on how to set up a graphical greeter.

### Properties

  * **available** (bool, readonly) - If the greetd socket is available.
  * **state** (GreetdState, readonly) - The current state of the greetd connection.
  * **user** (string, readonly) - The currently authenticating user.

### Functions

  * **cancelSession()** : void
    Cancel the active greetd session.

  * **createSession(user)** : void
    * **user** (string) - Create a greetd session for the given user.

  * **launch(command, environment, quit)** : void
    * **command** (list) - The command to launch.
    * **environment** (list) - The environment variables for the session.
    * **quit** (bool) - If true, quickshell will exit after launching the session.
    Launches the session, exiting quickshell if `quit` is true. The `state` must be `GreetdState.ReadyToLaunch` to call this function.
    The `launched` signal can be used to perform an action after greetd has acknowledged the desired session.
    WARNING: Note that greetd expects the greeter to terminate as soon as possible after setting a target session, and waiting too long may lead to unexpected behavior such as the greeter restarting. Performing animations and such should be done _before_ calling launch.

  * **respond(response)** : void
    * **response** (string) - The response to the authentication message.
    May only be called in response to an `authMessage()` with `responseRequired` set to true.

### Signals

  * **readyToLaunch()**
    Authentication has finished successfully and greetd can now launch a session.

  * **authFailure(message)**
    * **message** (string) - The error message indicating authentication failure.
    Authentication has failed and the session has terminated. Usually this is something like a timeout or a failed password entry.

  * **error(error)**
    * **error** (string) - The error message from greetd.
    Greetd has encountered an error.

  * **authMessage(message, error, responseRequired, echoResponse)**
    * **message** (string) - The text of the authentication message.
    * **error** (bool) - If the message should be displayed as an error.
    * **responseRequired** (bool) - If a response via `respond()` is required for this message.
    * **echoResponse** (bool) - If the response should be displayed in clear text to the user.
    An authentication message has been sent by greetd.
    Note that `error` and `responseRequired` are mutually exclusive. Errors are sent through `authMessage` when they are recoverable, such as a fingerprint scanner not being able to read a finger correctly, while definite failures such as a bad password are sent through `authFailure`.

  * **launched()**
    Greetd has acknowledged the launch request and the greeter should quit as soon as possible. This signal is sent right before quickshell exits automatically if the launch was not specifically requested not to exit. You usually don’t need to use this signal.
```

--------------------------------

### Run a Process with Stdout Collection

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell.Io/Process

Demonstrates how to define and run a process using the QtObject, including capturing and logging its standard output. It requires the Quickshell.Io import.

```qml
Process {
  running: true
  command: [ "some-command", "arg" ]
  stdout: StdioCollector {
    onStreamFinished: console.log(`line read: ${this.text}`)
  }
}
```

--------------------------------

### Example: RetainableLock Usage in Quickshell

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell/RetainableLock

This example demonstrates how to use RetainableLock to keep a retainable object alive as long as the lock exists. It takes a Retainable object as input and a boolean to control the locked state.

```QML
RetainableLock {
  object: aRetainableObject
  locked: true
}
```

--------------------------------

### Pipewire QtObject Properties

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell.Services.Pipewire/Pipewire

This section details the properties available on the Pipewire QtObject singleton, allowing you to query and control audio devices and system state.

```APIDOC
## Pipewire QtObject

### Description
This singleton contains links to all pipewire objects and provides access to various system properties.

### Properties

#### `preferredDefaultAudioSource`
- **Type**: PwNode
- **Description**: The preferred default audio source (input) or `null`. This is a hint to pipewire specifying the desired default source.

#### `defaultAudioSink`
- **Type**: PwNode
- **Readonly**: true
- **Description**: The default audio sink (output) currently in use by pipewire.

#### `preferredDefaultAudioSink`
- **Type**: PwNode
- **Description**: The preferred default audio sink (output) or `null`. This is a hint to pipewire specifying the desired default sink.

#### `links`
- **Type**: ObjectModel <PwLink>
- **Readonly**: true
- **Description**: All links present in pipewire. Links connect pipewire nodes.

#### `linkGroups`
- **Type**: ObjectModel <PwLinkGroup>
- **Readonly**: true
- **Description**: All link groups present in pipewire. This is a deduplicated list of `links`.

#### `defaultAudioSource`
- **Type**: PwNode
- **Readonly**: true
- **Description**: The default audio source (input) currently in use by pipewire.

#### `nodes`
- **Type**: ObjectModel <PwNode>
- **Readonly**: true
- **Description**: All nodes present in pipewire. This list contains every node on the system. Filtering by `isStream`, `isSink`, and `audio` properties is recommended.

#### `ready`
- **Type**: bool
- **Readonly**: true
- **Description**: Indicates whether quickshell has completed its initial sync with the pipewire server. If true, system state is fully synchronized.
```

--------------------------------

### JSON Document Generated by JsonAdapter Example

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell.Io/JsonAdapter

This JSON represents the data structure that would be generated or read by the QML JsonAdapter example. It shows how QML properties map to JSON keys and values, including nested objects and arrays.

```json
{
   "myStringProperty": "default value",
   "stringList": [
     "default",
     "value"
   ],
   "subObject": {
     "subObjectProperty": "default value"
   },
   "inlineJson": {
     "a": "b"
   }
}
```

--------------------------------

### Load Environment Variables and Application Icons

Source: https://context7.com/context7/quickshell_v0_2_0/llms.txt

This QML code demonstrates how to load environment variables like HOME and USER using Quickshell.env(). It also shows how to dynamically load application icons using Quickshell.iconPath(), providing fallback icon names for missing icons.

```qml
import Quickshell
import QtQuick

Column {
  Text {
    text: `Home: ${Quickshell.env("HOME")}`
  }

  Text {
    text: `User: ${Quickshell.env("USER")}`
  }

  Image {
    width: 32
    height: 32
    source: Quickshell.iconPath("firefox")
  }

  Image {
    width: 32
    height: 32
    source: Quickshell.iconPath("missing-icon", "application-x-executable")
  }
}
```

--------------------------------

### File Data Operations

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell.Io/FileView

Provides methods to get and set file data in various formats.

```APIDOC
## GET /websites/quickshell_v0_2_0/data

### Description
Retrieves the data of the specified file as an ArrayBuffer. Behavior is influenced by `blockAllReads` and `blockLoading` flags.

### Method
GET

### Endpoint
/websites/quickshell_v0_2_0/data

### Parameters
#### Query Parameters
- **blockAllReads** (boolean) - Optional - If true, all changes to the path will block the program when this function is called.
- **blockLoading** (boolean) - Optional - If true, reading this property before the file has loaded will block. Changing path or calling reload() will return old data until load completes.

### Response
#### Success Response (200)
- **data** (ArrayBuffer) - The data content of the file.

#### Response Example
```json
{
  "data": "binary data..."
}
```

## POST /websites/quickshell_v0_2_0/setData

### Description
Sets the content of the specified file with the provided data. `atomicWrites` and `blockWrites` affect behavior. Emits `saved()` or `saveFailed()` on completion.

### Method
POST

### Endpoint
/websites/quickshell_v0_2_0/setData

### Parameters
#### Request Body
- **data** (ArrayBuffer) - Required - The data to set for the file.

### Request Example
```json
{
  "data": "binary data..."
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
{
  "status": "success"
}
```

## GET /websites/quickshell_v0_2_0/text

### Description
Retrieves the data of the specified file as text. Behavior is influenced by `blockAllReads` and `blockLoading` flags.

### Method
GET

### Endpoint
/websites/quickshell_v0_2_0/text

### Parameters
#### Query Parameters
- **blockAllReads** (boolean) - Optional - If true, all changes to the path will block the program when this function is called.
- **blockLoading** (boolean) - Optional - If true, reading this property before the file has loaded will block. Changing path or calling reload() will return old data until load completes.

### Response
#### Success Response (200)
- **text** (string) - The text content of the file.

#### Response Example
```json
{
  "text": "file content as string"
}
```

## POST /websites/quickshell_v0_2_0/setText

### Description
Sets the content of the specified file with the provided text. `atomicWrites` and `blockWrites` affect behavior. Emits `saved()` or `saveFailed()` on completion.

### Method
POST

### Endpoint
/websites/quickshell_v0_2_0/setText

### Parameters
#### Request Body
- **text** (string) - Required - The text content to set for the file.

### Request Example
```json
{
  "text": "new file content"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### SystemTrayItem Functions

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell.Services.SystemTray/SystemTrayItem

This section details the functions available for interacting with a SystemTrayItem, such as activating it or displaying its menu.

```APIDOC
## SystemTrayItem Functions

### Description
Functions to perform actions on a system tray item.

### Functions

*   **activate()** : void
    Primary activation action, generally triggered via a left click.

*   **display(parentWindow, relativeX, relativeY)** : void
    Displays a platform menu at the given location relative to the parent window.
    *   **parentWindow** (QtObject) - The parent window for the menu.
    *   **relativeX** (int) - The X coordinate relative to the parent window.
    *   **relativeY** (int) - The Y coordinate relative to the parent window.

*   **scroll(delta, horizontal)** : void
    Scroll action, such as changing volume on a mixer.
    *   **delta** (int) - The scroll amount.
    *   **horizontal** (bool) - Indicates if the scroll is horizontal.

*   **secondaryActivate()** : void
    Secondary activation action, generally triggered via a middle click.
```

--------------------------------

### Item Positioning and Geometry Functions

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell/QsWindow

Provides functions to get an item's position and rectangle relative to the window.

```APIDOC
## GET /websites/quickshell_v0_2_0/functions/itemPosition

### Description
Returns the given Item’s position relative to the window. Does not update reactively.
Equivalent to calling `window.contentItem.mapFromItem(item, 0, 0)`

### Method
GET

### Endpoint
`/websites/quickshell_v0_2_0/functions/itemPosition`

### Parameters
#### Query Parameters
- **item** (Item) - Required - The item to get the position of.

### Response
#### Success Response (200)
- **point** (point) - The item's position relative to the window.

### Response Example
```json
{
  "position": {"x": 10, "y": 20}
}
```

## GET /websites/quickshell_v0_2_0/functions/itemRect

### Description
Returns the given Item’s geometry relative to the window. Does not update reactively.
Equivalent to calling `window.contentItem.mapFromItem(item, 0, 0, 0, 0)`

### Method
GET

### Endpoint
`/websites/quickshell_v0_2_0/functions/itemRect`

### Parameters
#### Query Parameters
- **item** (Item) - Required - The item to get the rectangle of.

### Response
#### Success Response (200)
- **rect** (rect) - The item's geometry relative to the window.

### Response Example
```json
{
  "rect": {"x": 10, "y": 20, "width": 100, "height": 50}
}
```
```

--------------------------------

### QtObject: Path Construction Helpers

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell/Quickshell

Provides utility functions to construct full paths based on predefined Quickshell directories (cache, data, state, shell configuration). These functions simplify the process of locating and referencing files and directories associated with the shell's operation.

```javascript
Quickshell.cachePath("relative/path")
```

```javascript
Quickshell.dataPath("relative/path")
```

```javascript
Quickshell.statePath("relative/path")
```

```javascript
Quickshell.shellPath("relative/path")
```

--------------------------------

### Load and Bind Component with BoundComponent

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell/BoundComponent

Demonstrates using BoundComponent to load a QML component ('MyComponent.qml') and set initial properties. It also shows how to bind to signals emitted by the loaded component, updating properties reactively. This is useful for managing component initialization and dependencies.

```qml
BoundComponent {
  source: "MyComponent.qml"

  // this is the same as assigning to `color` on MyComponent if loaded normally.
  property color color: "red";

  // this will be triggered when the `clicked` signal from the MouseArea is sent.
  function onClicked() {
    color = "blue";
  }
}
```

--------------------------------

### Hyprland Properties API

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell.Hyprland/Hyprland

Access read-only properties of the Hyprland module to get information about the current Hyprland session, such as focused monitor, active toplevel, and lists of monitors, workspaces, and toplevels.

```APIDOC
## Hyprland Properties

### Description
Provides read-only access to various Hyprland session properties.

### Properties
- **focusedMonitor** (HyprlandMonitor) - The currently focused Hyprland monitor. May be null.
- **eventSocketPath** (string) - Path to the event socket (.socket2.sock).
- **focusedWorkspace** (HyprlandWorkspace) - The currently focused Hyprland workspace. May be null.
- **monitors** (ObjectModel<HyprlandMonitor>) - All Hyprland monitors.
- **requestSocketPath** (string) - Path to the request socket (.socket.sock).
- **activeToplevel** (Toplevel) - Currently active toplevel (might be null).
- **toplevels** (ObjectModel<Toplevel>) - All Hyprland toplevels.
- **workspaces** (ObjectModel<HyprlandWorkspace>) - All Hyprland workspaces, sorted by id. Named workspaces have a negative id and appear before unnamed workspaces.
```

--------------------------------

### Removing QML Binding by Reassignment

Source: https://quickshell.org/docs/v0.2.0/guide/qml-language

Demonstrates how to remove a QML binding by assigning a new, non-binding value to the property. In this example, the text property of boundText is unbound from theButton.pressed after the button is clicked.

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

--------------------------------

### Quickshell Properties

Source: https://quickshell.org/docs/v0.2.0/types/Quickshell/Quickshell

Exposes various properties related to Quickshell's configuration, state, and environment.

```APIDOC
## Quickshell Properties

### Description
Provides access to Quickshell's configuration and runtime information.

### Properties
- **dataDir** (string, readonly) - The per-shell data directory.
- **stateDir** (string, readonly) - The per-shell state directory.
- **watchFiles** (bool) - If true, the configuration reloads on file changes.
- **processId** (int, readonly) - Quickshell's process ID.
- **clipboardText** (string) - The system clipboard content.
- **screens** (list<ShellScreen>, readonly) - A list of all currently connected screens.
- **workingDirectory** (string) - Quickshell's working directory.
- **shellDir** (string, readonly) - The full path to the root directory of your shell.
- **cacheDir** (string, readonly) - The per-shell cache directory.

### Deprecated Properties
- **shellRoot** (string, readonly) - Deprecated: Renamed to shellDir for consistency.
- **configDir** (string, readonly) - Deprecated: Renamed to shellDir for clarity.
```

--------------------------------

### Run Process and Display Output in Panel (QML)

Source: https://quickshell.org/docs/v0.2.0/guide/introduction

Shows how to run an external command (e.g., 'date') within a Quickshell panel and display its output. It uses `Process` to execute the command and `StdioCollector` to capture and display the standard output in a `Text` element.

```qml
import Quickshell
import Quickshell.Io // for Process
import QtQuick

PanelWindow {
  anchors {
    top: true
    left: true
    right: true
  }

  implicitHeight: 30

  Text {
    // give the text an ID we can refer to elsewhere in the file
    id: clock

    anchors.centerIn: parent

    // create a process management object
    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 StdioCollector
      // Use StdioCollector to retrieve the text the process sends
      // to stdout.
      stdout: StdioCollector {
        // Listen for the streamFinished signal, which is sent
        // when the process closes stdout or exits.
        onStreamFinished: clock.text = this.text // `this` can be omitted
      }
    }
  }
}
```
Tokens:
Raw