Quickshell

https://quickshell.org/docs/v0.3.0
Admin
Quickshell is a declarative desktop shell framework written in QML that enables developers to create...
Tokens:70,352
Snippets:916
Trust Score:7.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Quickshell on Guix

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

Install Quickshell from the standard Guix repository using the `guix install` command.

```bash
guix install quickshell
```

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

### Install Quickshell on Gentoo using GURU overlay

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

Add the GURU overlay to your Gentoo system and install Quickshell from the `gui-apps/quickshell` package.

```bash
# Add GURU overlay
emerge eselect-repository
eselect repository enable guru
emerge --sync guru

emerge gui-apps/quickshell
```

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

### Install Quickshell on Debian

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

Install Quickshell from the Debian unstable or testing repositories using apt.

```bash
sudo apt install quickshell
```

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

### Example Usage

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

An example demonstrating how to set up an IpcHandler to control and retrieve properties of a Rectangle, including defining functions and signals.

```APIDOC
#### Example
The following example creates ipc functions to control and retrieve the appearance of a Rectangle.
```
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;
      this.radiusChanged(radius);
    }

    function getRadius(): int { return rect.radius; }
		signal radiusChanged(newRadius: int);
  }
}
```
```

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

### Command Line Interface (CLI) Examples

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

Examples of using the `qs ipc` command-line tool to show registered targets, call functions, and retrieve property values.

```APIDOC
The list of registered targets can be inspected using `qs ipc show`.
```
$ 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
  signal radiusChanged(newRadius: int)
```

and then invoked using `qs ipc call`.
```
$ 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
```
```

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

### Install Quickshell on Fedora

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

Install the release version of Quickshell on Fedora using the dnf package manager.

```bash
sudo dnf install quickshell
```

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

### I3IpcListener Example

Source: https://quickshell.org/docs/v0.3.0/types/Quickshell.I3/I3IpcListener

This example demonstrates how to create an I3IpcListener, subscribe to 'input' events, and handle incoming IPC events by calling a function with the event data.

```javascript
I3IpcListener {
  subscriptions: ["input"]
  onIpcEvent: function (event) {
    handleInputEvent(event.data)
  }
}
```

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

### QML Import Examples

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

Provides concrete examples of different QML import statements, including module imports, versioned imports, and aliased imports.

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

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

### Install Quickshell on Arch Linux

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

Install the release version of Quickshell from the Arch Linux package repository using pacman.

```bash
pacman -S quickshell
```

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

### Install Quickshell on Ubuntu using DankLinux PPA

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

Add the DankLinux PPA to your Ubuntu system and install either the latest release (`quickshell`) or the master branch (`quickshell-git`) version of Quickshell.

```bash
# Add DankLinux PPA
sudo add-apt-repository ppa:avengemedia/danklinux
sudo apt update

sudo apt install quickshell
# OR
sudo apt install quickshell-git
```

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

### Implicit QML Import Example

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

Shows how QML automatically imports types from neighboring files if their names start with an uppercase letter.

```qml
root
+|-MyButton.qml
+|-shell.qml
```

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

### Create a Basic Panel Window

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

Use PanelWindow to create a simple bar or widget. This example displays 'hello world' in the center of the panel.

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

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

### SocketServer Configuration Example

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

Demonstrates the basic structure of a SocketServer configuration, including its active state, socket path, and handler component.

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

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

### Install Quickshell-git on Arch Linux (AUR)

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

Install the development version of Quickshell from the AUR using an AUR helper like yay. Be aware that AUR packages may break with Qt updates.

```bash
yay -S quickshell-git
```

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

### ColorQuantizer Example

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

Demonstrates how to initialize and configure the ColorQuantizer with a source image, quantization depth, and rescaling size. Ensure the 'source' property points to a valid image file.

```javascript
import Quickshell

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

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

### ColorQuantizer Usage Example

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

Demonstrates how to instantiate and configure the ColorQuantizer to process an image and retrieve its dominant colors.

```APIDOC
## ColorQuantizer

### Description
A color quantization utility used for getting prevalent colors in an image, by averaging out the image’s color data recursively.

### Properties
* **rescaleSize** (real) - The size to rescale the image to. If 0, no scaling is performed. Recommended for faster processing.
* **depth** (real) - Maximum depth for color quantization. Each level of depth represents another binary split of the color space. The number of colors produced is 2^depth.
* **source** (unknown) - Path to the image for color quantization.
* **imageRect** (rect) - The rectangle to crop the source image to. Can be set to `undefined` to reset.

### Readonly Properties
* **colors** (list<color>) - Access the colors resulting from the color quantization. The amount of colors is determined by the `depth` property (2^depth).

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

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

### QML Document Structure Example

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

Illustrates the basic structure of a QML document, including imports, object declarations, properties, bindings, signals, and functions.

```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 {
    // ...
  }
}
```

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

### Neovim Configuration for QML Language Server

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

Set up the qmlls language server in Neovim using nvim-lspconfig. Ensure tree-sitter highlighting is installed for QML.

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

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

### QML Lambda Callback Example

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

This example demonstrates an overcomplicated click counter using a lambda callback passed to a function, updating a label with the click count.

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

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

### Container Item with Anchors

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

This example demonstrates reducing boilerplate code by using QtQuick Anchors to achieve common position and size bindings. It is equivalent to the first example but uses anchors for positioning and sizing.

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

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

### Basic WlSessionLock with a Button

Source: https://quickshell.org/docs/v0.3.0/types/Quickshell.Wayland/WlSessionLock

This example demonstrates creating a WlSessionLock with a button that unlocks the session when clicked. Ensure WlSessionLock is imported.

```javascript
WlSessionLock {
  id: lock

  WlSessionLockSurface {
    Button {
      text: "unlock me"
      onClicked: lock.locked = false
    }
  }
}

// ...
lock.locked = true
```

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

### Enable Fedora COPR and Install Quickshell

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

Enable the errornointernet/quickshell COPR repository on Fedora to install either the latest release (`quickshell`) or the master branch (`quickshell-git`) versions.

```bash
sudo dnf copr enable errornointernet/quickshell

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

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

### QML Property Binding Examples

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

Demonstrates various ways to bind properties in QML, including simple expressions, complex calculations, and multi-line expressions with or without explicit return statements.

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

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

### Hyprland Global Shortcut Binding

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

Example of how to bind a global shortcut in Hyprland's configuration file. This maps a key combination to trigger a specific application ID and shortcut name.

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

```

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

### Basic RetainableLock Usage

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

This example demonstrates how to use RetainableLock to keep a retainable object alive as long as the lock exists. Ensure the 'Quickshell' module is imported.

```javascript
import Quickshell

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

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

### Quickshell Scope Example

Source: https://quickshell.org/docs/v0.3.0/types/Quickshell/Scope

Demonstrates the structure of a Quickshell Scope within Variants. All elements defined inside this Scope will inherit its reload behavior.

```javascript
ShellRoot {
  Variants {
    variants: ...

    Scope {
      // everything in here behaves the same as if it was defined
      // directly in `Variants` reload-wise.
    }
  }
}
```

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

### Example: Using Default Property

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

Demonstrates how to set the visual child using the default property of a WrapperWidget. This is suitable when the child is the primary item within the widget.

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

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

### Update Process Output at an Interval

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

Use a Timer to repeatedly trigger a Process, ensuring dynamic content updates. This example creates a clock that updates every second.

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

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

### Monitor Track Position with Timer

Source: https://quickshell.org/docs/v0.3.0/types/Quickshell.Services.Mpris/MprisPlayer

This example demonstrates how to monitor track position using a Timer, ensuring updates at a specified interval (e.g., every second). It's suitable for scenarios where smooth, frame-by-frame updates are not critical. The timer only runs when the playback state is 'Playing'.

```javascript
Timer {
  // only emit the signal when the position is actually changing.
  running: player.playbackState == MprisPlaybackState.Playing
  // Make sure the position updates at least once per second.
  interval: 1000
  repeat: true
  // emit the positionChanged signal every second.
  onTriggered: player.positionChanged()
}
```

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

### Nested Regions Example

Source: https://quickshell.org/docs/v0.3.0/types/Quickshell/Region

Demonstrates how to create a square region with a cutout in the middle using nested Region objects. The inner region uses 'Intersection.Subtract' to create the cutout.

```Quickshell
Region {
  width: 100; height: 100;

  Region {
    x: 50; y: 50;
    width: 50; height: 50;
    intersection: Intersection.Subtract
  }
}
```

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

### HyprlandFocusGrab Example

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

Demonstrates how to use HyprlandFocusGrab to take and remove exclusive focus from a window. The button's text dynamically updates to reflect the grab's active state.

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

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

### Example: Implementing Custom Wrapper Type

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

Illustrates how to create a custom wrapper component using WrapperManager. It involves creating a WrapperManager instance and aliasing its 'child' property.

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

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

### QML Property Access Scope Examples

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

Illustrates property access rules in QML, showing how to access properties of the current object, the root object, and other objects using their `id` or `parent` properties. It also points out illegal access attempts.

```qml
Item {
  property string rootDefinition

  Item {
    id: mid
    property string midDefinition

    Text {
      property string innerDefinition

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

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

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

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

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

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

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

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

### IpcHandler Example for Rectangle Control

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

This example demonstrates how to create an IpcHandler to control and retrieve properties of a Rectangle object. It defines functions to set and get the color, rotation angle, and radius, and also includes a signal for radius changes.

```javascript
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;
      this.radiusChanged(radius);
    }

    function getRadius(): int { return rect.radius; }
		signal radiusChanged(newRadius: int);
  }
}
```

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

### Initialize SystemClock and Format Time

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

Demonstrates how to initialize SystemClock with second precision and format the current date and time using Qt.formatDateTime. Clock updates are guaranteed within 50ms of system clock changes.

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

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

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

### Launch Session

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

Launches the greetd session, exiting quickshell. This function requires the greetd state to be `ReadyToLaunch`.

```APIDOC
## launch

### Description
Launch the session, exiting quickshell. Must be `GreetdState.ReadyToLaunch` to call this function.

### Method
`launch(command: list, environment: list, quit: bool)`

### Parameters
#### Path Parameters
- **command** (list) - Required - The command to launch.
- **environment** (list) - Required - The environment variables for the command.
- **quit** (bool) - Required - If true, quickshell will exit after launching the session.
```

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

### QML Module Import Syntax

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

Demonstrates various ways to import QML modules, including versioned modules, relative paths, Quickshell modules, and JavaScript files.

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

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

```qml
import qs.<path> [as <Namespace>]
```

```qml
import "<filename>" as <Namespace>
```

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

### PamContext Functions

Source: https://quickshell.org/docs/v0.3.0/types/Quickshell.Services.Pam/PamContext

Provides functions to control the authentication flow, such as starting, aborting, and responding to authentication prompts.

```APIDOC
## PamContext Functions

### `abort()` : void
Abort a running authentication session.

### `respond(response: string)` : void
Respond to pam. May not be called unless `responseRequired` is true.

### `start()` : bool
Start an authentication session. Returns if the session was started successfully.
```

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

### Get Environment Variable

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

Retrieve the string value of an environment variable. Returns null if the variable is not set.

```javascript
Quickshell.env("VARIABLE_NAME");
```

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

### Switching to QApplication for QtWidgets Support

Source: https://quickshell.org/docs/v0.3.0/guide/advanced

Use the UseQApplication pragma to switch Quickshell's default QGuiApplication to a QApplication. This enables the use of QtWidgets controls and styles like qqc2-desktop-style.

```qml
//@ pragma UseQApplication
```

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

### Start Detached Process

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

Launches a process that runs independently of Quickshell. The subprocess will not be tracked or automatically killed by Quickshell.

```javascript
process.startDetached();
```

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

### Reusing a Window on Every Screen

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

This snippet demonstrates how to create an instance of a window on each connected screen. The window will be created or destroyed as screens are added or removed.

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

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

### Run a Process and Display Output

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

Utilize the Process object to execute commands and StdioCollector to capture their output. The Text element updates when the process finishes.

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

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

### Configuring Process Environment

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

Sets up the environment for a process, clearing existing variables and adding new ones. Note that the returned object must be wrapped in parentheses.

```javascript
clearEnvironment: true
environment: ({
  ADDED: "value",
  PASSED_FROM_SYSTEM: null,
})
```

```javascript
environment: ({
  ADDED: "value",
  REMOVED: null,
  "i'm different": "value",
})
```

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

### Hyprland Properties

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

Access read-only properties of the Hyprland QtObject to get information about monitors, toplevels, workspaces, and Hyprland's configuration.

```APIDOC
## Hyprland Properties

### `monitors`
- Type: ObjectModel <HyprlandMonitor>
- Description: All hyprland monitors.

### `activeToplevel`
- Type: HyprlandToplevel
- Description: Currently active toplevel (might be null)

### `toplevels`
- Type: ObjectModel <HyprlandToplevel>
- Description: All hyprland toplevels

### `workspaces`
- Type: ObjectModel <HyprlandWorkspace>
- Description: All hyprland workspaces, sorted by id. Named workspaces have a negative id, and will appear before unnamed workspaces.

### `eventSocketPath`
- Type: string
- Description: Path to the event socket (.socket2.sock)

### `focusedMonitor`
- Type: HyprlandMonitor
- Description: The currently focused hyprland monitor. May be null.

### `focusedWorkspace`
- Type: HyprlandWorkspace
- Description: The currently focused hyprland workspace. May be null.

### `requestSocketPath`
- Type: string
- Description: Path to the request socket (.socket.sock)

### `usingLua`
- Type: bool
- Description: True if Hyprland is running in lua mode. Dispatcher syntax changes when using lua. This property will be false until the Hyprland module is initialized.
```

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

### Executing a Desktop Entry

Source: https://quickshell.org/docs/v0.3.0/types/Quickshell/DesktopEntry

Demonstrates how to execute an application defined by a DesktopEntry object. This is equivalent to calling Quickshell.execDetached with the appropriate parameters.

```javascript
Quickshell.execDetached({
  command: desktopEntry.command,
  workingDirectory: desktopEntry.workingDirectory,
});
```

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

### Construct Config Path

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

Create a path within the Quickshell configuration directory. Use this for accessing or storing configuration files.

```javascript
Quickshell.shellPath("my-config.ini");
```

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

### Generated JSON from JsonAdapter

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

This JSON structure represents the data managed by the JsonAdapter example, showing how QML properties map to JSON keys and values.

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

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

### Version and Theme Checking Functions

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

Functions to check Quickshell and Qt versions, and the availability of theme icons.

```APIDOC
## hasQtVersion (major, minor)

### Description
Check if Qt’s version is at least `major.minor`.

### Parameters
#### Path Parameters
- **major** (int) - Required - The major version number.
- **minor** (int) - Required - The minor version number.

## hasThemeIcon (icon)

### Description
Check if specified icon has an available icon in your icon theme.

### Parameters
#### Path Parameters
- **icon** (string) - Required - The name of the icon to check.

## hasVersion (major, minor, features)

### Description
Check if Quickshell’s version is at least `major.minor` and the listed unreleased features are available.

### Parameters
#### Path Parameters
- **major** (int) - Required - The major version number.
- **minor** (int) - Required - The minor version number.
- **features** (list) - Optional - A list of unreleased features to check for.

## hasVersion (major, minor)

### Description
Check if Quickshell’s version is at least `major.minor`.

### Parameters
#### Path Parameters
- **major** (int) - Required - The major version number.
- **minor** (int) - Required - The minor version number.
```

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

### IpcHandler Properties

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

Expose properties of an IpcHandler for remote reading using `qs ipc prop get`. Properties must be of an IPC compatible type.

```APIDOC
#### Properties

Properties of an IpcHanlder can be read using `qs ipc prop get` as long as they are of an IPC compatible type. See the table above for compatible types.
## Properties [?]
  * target  : string
The target this handler should be accessible from. Required and must be unique. May be changed at runtime.
  * enabled  : bool
If the handler should be able to receive calls. Defaults to true.
```

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

### Get System Icon Path

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

Retrieve the path for a system icon. Icons are typically loaded from the current theme, ensuring consistency with other Qt applications.

```javascript
Quickshell.iconPath("icon-name");
```

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

### Create a Centered Panel with a Popup

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

This snippet demonstrates how to create a panel window and position a popup window centered over it. The popup is configured to be visible and takes up a specific area.

```Quickshell
PanelWindow {
  id: toplevel

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

  PopupWindow {
    anchor.window: toplevel
    anchor.rect.x: parentWindow.width / 2 - width / 2
    anchor.rect.y: parentWindow.height
    width: 500
    height: 500
    visible: true
  }
}
```

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

### Emacs Configuration for QML Language Server

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

Configure Emacs to use the qml-ts-mode and qmlls language server. Ensure lsp-mode is installed and qmlls is available in your PATH.

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

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

### Manual Binding with Qt.binding in QML

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

Illustrates creating a manual binding at runtime using `Qt.binding`. This is useful for dynamically attaching bindings based on events or conditions.

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

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

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

### Handle CheckBox State Changes

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

Use the `on<PropertyName>Changed` signal handler to react to property changes. This example demonstrates handling the `checkStateChanged` signal of a CheckBox.

```QML
ColumnLayout {
  CheckBox {
    text: "check me"

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

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

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

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

### Defining Data, State, and Cache Directories

Source: https://quickshell.org/docs/v0.3.0/guide/advanced

Use DataDir, StateDir, and CacheDir pragmas to define custom directories for Quickshell's data, state, and cache. The path can include $BASE/, which resolves to the XDG base directory.

```qml
//@ pragma DataDir <dir>
```

```qml
//@ pragma StateDir <dir>
```

```qml
//@ pragma CacheDir <dir>
```

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

### Create a PanelWindow Attached to the Bottom of the Screen

Source: https://quickshell.org/docs/v0.3.0/types/Quickshell/PanelWindow

This snippet demonstrates how to create a PanelWindow that spans the bottom of the screen and displays text. Ensure Quickshell is imported.

```Quickshell
PanelWindow {
  anchors {
    left: true
    bottom: true
    right: true
  }

  Text {
    anchors.centerIn: parent
    text: "Hello!"
  }
}
```

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

### Using JsonAdapter with FileView

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

Demonstrates how to configure FileView with JsonAdapter to manage JSON data. It includes settings for watching file changes and writing adapter updates back to the file. Property changes trigger console logs.

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

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

### Example: Using Explicit Child Property

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

Shows how to specify the visual child using the 'child' property when a widget has multiple Item-based children. This is necessary to resolve ambiguity.

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

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

### Pipewire Service Overview

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

Provides an overview of the Pipewire service singleton, its properties, and their descriptions.

```APIDOC
## Pipewire Service

singleton
`import Quickshell.Services.Pipewire`
Contains links to all pipewire objects.

### Properties

* **ready** : bool readonly
  This property is true if quickshell has completed its initial sync with the pipewire server. If true, nodes, links and sync/source preferences will be in a good state. You can use the pipewire object before it is ready, but some nodes/links may be missing, and preference metadata may be null.

* **links** : ObjectModel <PwLink> readonly
  All links present in pipewire. Links connect pipewire nodes to each other, and can be used to determine their relationship. If you already have a node you want to check for connections to, use PwNodeLinkTracker instead of filtering this list. Multiple links may exist between the same nodes. See for a deduplicated list containing only one entry per link between nodes.

* **linkGroups** : ObjectModel <PwLinkGroup> readonly
  All link groups present in pipewire. The same as but deduplicated. If you already have a node you want to check for connections to, use PwNodeLinkTracker instead of filtering this list.

* **defaultAudioSink** : PwNode readonly
  The default audio sink (output) or `null`. This is the default sink currently in use by pipewire, and the one applications are currently using. To set the default sink, use . When the default sink changes, this property may breifly become null. This depends on your hardware.

* **nodes** : ObjectModel <PwNode> readonly
  All nodes present in pipewire. This list contains every node on the system. To find a useful subset, filtering with the following properties may be helpful: * - if the node is an application or hardware device. * - if the node is a sink or source. * - if non null the node is an audio node.

* **preferredDefaultAudioSource** : PwNode
  The preferred default audio source (input) or `null`. This is a hint to pipewire telling it which source should be the default when possible. may differ when it is not possible for pipewire to pick this node. See for the current default source, regardless of preference.

* **defaultAudioSource** : PwNode readonly
  The default audio source (input) or `null`. This is the default source currently in use by pipewire, and the one applications are currently using. To set the default source, use . When the default source changes, this property may breifly become null. This depends on your hardware.

* **preferredDefaultAudioSink** : PwNode
  The preferred default audio sink (output) or `null`. This is a hint to pipewire telling it which sink should be the default when possible. may differ when it is not possible for pipewire to pick this node. See for the current default sink, regardless of preference.
```

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

### Display System Time with Quickshell

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

This snippet demonstrates how to use the SystemClock integration to display formatted system time. The `precision` property can be set to `SystemClock.Minutes` to conserve battery if seconds are not needed.

```qml
pragma Singleton

import Quickshell
import QtQuick

Singleton {
  id: root
  // an expression can be broken across multiple lines using {}
  readonly property string time: {
    // The passed format string matches the default output of
    // the `date` command.
    Qt.formatDateTime(clock.date, "ddd MMM d hh:mm:ss AP t yyyy")
  }

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

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

### Nix Flake Configuration for Quickshell

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

Configure Quickshell using a Nix flake, specifying inputs and ensuring system dependency compatibility. The `follows` attribute is crucial for matching Nixpkgs versions.

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

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

### Get Icon Path with Existence Check

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

Retrieve the path for a system icon, returning an empty string if the icon does not exist. This is useful for preventing missing icon errors.

```javascript
Quickshell.iconPath("icon-name", true);
```

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

### Get Icon Path with Fallback

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

Retrieve the path for a system icon, providing a fallback icon path if the primary icon cannot be loaded. This ensures a valid icon is always available.

```javascript
Quickshell.iconPath("icon-name", "fallback-icon-name");
```
Tokens:
Raw