Quickshell

https://quickshell.org/docs/v0.2.1
Admin
Quickshell is a modular framework providing QML components and services for building custom desktop...
Tokens:46,415
Snippets:593
Trust Score:7.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Quickshell on Gentoo

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

Install Quickshell from the GURU overlay.

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

emerge gui-apps/quickshell
```

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

### Install Quickshell on Ubuntu

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

Install Quickshell using the DankLinux PPA.

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

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

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

### Install Quickshell on Guix

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

Install Quickshell using the Guix package manager.

```bash
guix install quickshell
```

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

### Install Quickshell on Debian

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

Install Quickshell from the unstable or testing repositories.

```bash
sudo apt install quickshell
```

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

### Define the main shell and bar components

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

Initial setup splitting the shell scope and the bar implementation into separate files.

```qml
// shell.qml
import Quickshell

Scope {
  Bar {}
}
```

```qml
// Bar.qml
import Quickshell
import Quickshell.Io
import QtQuick

Scope {
  id: root
  property string time

  Variants {
    model: Quickshell.screens

    PanelWindow {
      required property var modelData
      screen: modelData

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

      implicitHeight: 30

      Text {
        anchors.centerIn: parent
        text: root.time
      }
    }
  }

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

    stdout: StdioCollector {
      onStreamFinished: root.time = this.text
    }
  }

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

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

### Install Quickshell on Fedora

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

Install Quickshell via standard repositories or the COPR repository for development versions.

```bash
sudo dnf install quickshell
```

```bash
sudo dnf copr enable errornointernet/quickshell

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

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

### QML Document Structure

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

A comprehensive example demonstrating QML syntax including imports, object declarations, property 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 {
    // ...
  }
}
```

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

### Install Quickshell on Arch Linux

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

Install stable or development versions of Quickshell using pacman or an AUR helper.

```bash
pacman -S quickshell
```

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

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

### play()

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

Starts playback.

```APIDOC
## play()

### Description
Equivalent to setting the playback status to 'Playing'.
```

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

### Activate a workspace

Source: https://quickshell.org/docs/v0.2.1/types/Quickshell.I3/I3Workspace

Example of how to activate a specific workspace using the I3 dispatch function.

```JavaScript
I3.dispatch(`workspace number ${workspace.number}`);
```

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

### Use lambda callbacks

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

Example of passing a lambda as a callback to a function.

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

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

### Configure process environment with clearEnvironment

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

Example of clearing the environment and setting specific variables. Note that clearEnvironment: true changes the behavior of null values.

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

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

### SystemTray Singleton

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

Referencing the SystemTray singleton will make Quickshell start tracking system tray contents. These contents are updated as the tray changes and can be accessed via the 'items' property.

```APIDOC
## SystemTray: QtObject 
singleton
`import Quickshell.Services.SystemTray`

Referencing the SystemTray singleton will make quickshell start tracking system tray contents, which are updated as the tray changes, and can be accessed via the  property.

### Properties
  * items  : ObjectModel <SystemTrayItem> readonly
List of all system tray icons.
```

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

### Create a WlSessionLock with a Clickable Button

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

This example demonstrates how to create a session lock that can be unlocked by clicking a button. The lock is activated by setting `lock.locked` to true.

```javascript
WlSessionLock {
  id: lock

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

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

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

### Resolve Property Access Scopes

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

Examples of accessing properties based on current object, root object, or explicit id references.

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

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

### Execute a DesktopEntry

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

Demonstrates how to manually invoke a desktop entry using Quickshell.execDetached with the entry's command and working directory.

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

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

### RetainableLock Usage Example

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

This example demonstrates how to use the RetainableLock to keep a Retainable object alive for as long as the lock exists.

```APIDOC
## RetainableLock: QtObject

`import Quickshell`
A RetainableLock provides extra safety and ease of use for locking Retainable objects. A retainable object can be locked by multiple locks at once, and each lock re-exposes relevant properties of the retained objects.

### Example
The code below will keep a retainable object alive for as long as the RetainableLock exists.
```
RetainableLock {
  object: aRetainableObject
  locked: true
}
```

## Properties
  * locked  : bool
If the object should be locked.
  * retained  : bool readonly
If the object is currently in a retained state.
  * object  : QtObject
The object to lock. Must be Retainable.

## Signals
  * aboutToDestroy ()
Rebroadcast of the object’s .
  * dropped ()
Rebroadcast of the object’s .
```

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

### Define and run a process

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

Basic configuration for a Process object, including command definition and stdout collection.

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

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

### Run a process and display output

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

Uses a Process object to execute the 'date' command and a StdioCollector to capture and display the 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
      }
    }
  }
}
```

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

### Initialize a SocketServer

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

Configures a SocketServer with a specific path and a handler to manage incoming connections and message parsing.

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

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

### ToplevelManager Properties

Source: https://quickshell.org/docs/v0.2.1/types/Quickshell.Wayland/ToplevelManager

Access properties of the ToplevelManager to get information about active and all toplevel windows.

```APIDOC
## ToplevelManager Properties

### Description
Exposes a list of windows from other applications as Toplevels via the zwlr-foreign-toplevel-management-v1 wayland protocol.

### Properties

- **activeToplevel** (Toplevel) - readonly
  Active toplevel or null. If multiple are active, this will be the most recently activated one. Usually compositors will not report more than one toplevel as active at a time.

- **toplevels** (ObjectModel <Toplevel>) - readonly
  All toplevel windows exposed by the compositor.
```

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

### Configure Neovim for QML

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

Initializes the qmlls language server using nvim-lspconfig.

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

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

### startDetached()

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

Launches an instance of the process detached from Quickshell.

```APIDOC
## startDetached()

### Description
Launches an instance of the process detached from Quickshell. The subprocess will not be tracked and will not be killed by Quickshell.
```

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

### Initialize ColorQuantizer

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

Configure the ColorQuantizer with a source image, recursion depth, and rescale size to optimize processing speed.

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

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

### Generated JSON from JsonAdapter

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

This JSON structure represents the data managed by the JsonAdapter configuration shown in the example. It reflects the defined properties and their default values.

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

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

### Implement SystemClock Singleton

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

Uses the built-in SystemClock library to provide formatted time, with precision settings to optimize performance.

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

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

### Define IpcHandler Functions for a Rectangle

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

This example demonstrates how to create an IpcHandler for a Rectangle object, defining functions to control its color, rotation, and radius. Ensure argument and return types are explicitly specified for registration.

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

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

### Asynchronous PopupWindow Loading

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

Demonstrates using LazyLoader to load a PopupWindow in the background while the main panel remains responsive.

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

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

### Create a basic PanelWindow

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

Defines a panel window that reserves space on the monitor and displays centered text.

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

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

### Quickshell Settings

Source: https://quickshell.org/docs/v0.2.1/types/Quickshell/QuickshellSettings

Configuration options for Quickshell.

```APIDOC
## QuickshellSettings: QtObject

Accessor for some options under the Quickshell type.

### Properties

* **watchFiles** (bool) - Optional - If true then the configuration will be reloaded whenever any files change. Defaults to true.
* **workingDirectory** (string) - Optional - Quickshell’s working directory. Defaults to whereever quickshell was launched from.

### Signals

* **lastWindowClosed** ()
  Sent when the last window is closed. To make the application exit when the last window is closed run `Qt.quit()`.
```

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

### QML Import Syntax

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

Various import patterns for modules, relative paths, Quickshell-specific 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>
```

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

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

### raise()

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

Brings the media player window to the front.

```APIDOC
## raise()

### Description
Bring the media player to the front of the window stack. May only be called if supported.
```

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

### Invoke IPC Functions via Command Line

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

Demonstrates how to call registered IPC functions using the 'qs ipc call' command. Provide the target name, function name, and arguments as shown. The output reflects the return value of the called function.

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

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

### Greetd API Reference

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

Documentation for the Greetd singleton object methods and properties.

```APIDOC
## Greetd Service

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

### Functions
- **cancelSession()** - Cancel the active greetd session.
- **createSession(user: string)** - Create a greetd session for the given user.
- **launch(command: list)** - Launch the session, exiting quickshell. Must be GreetdState.ReadyToLaunch.
- **launch(command: list, environment: list)** - Launch the session with environment variables, exiting quickshell. Must be GreetdState.ReadyToLaunch.
- **launch(command: list, environment: list, quit: bool)** - Launch the session with environment variables and optional quit behavior. Must be GreetdState.ReadyToLaunch.
- **respond(response: string)** - Respond to an authentication message. Only valid if responseRequired is true.

### Signals
- **readyToLaunch()** - Authentication finished successfully.
- **authFailure(message: string)** - Authentication failed and session terminated.
- **authMessage(message: string, error: bool, responseRequired: bool, echoResponse: bool)** - Authentication message received from greetd.
- **error(error: string)** - Greetd encountered an error.
- **launched()** - Greetd acknowledged the launch request.
```

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

### Defining and Using Custom QML Types

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

Demonstrates creating a reusable component in one file and instantiating it in another, noting that IDs are private to the file.

```qml
// MyText.qml
Rectangle {
  required property string text

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

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

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

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

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

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

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

### Creating Inline Components

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

Shows how to define a component locally within a file, allowing it to reference IDs from the parent scope.

```qml
ColumnLayout {
  id: layout
  property real textPointSize: 10

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

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

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

### Integrate Singleton in Bar Layout

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

Shows how to use the ClockWidget within a PanelWindow without passing explicit time objects.

```qml
// Bar.qml
import Quickshell

Scope {
  // no more time object

  Variants {
    model: Quickshell.screens

    PanelWindow {
      required property var modelData
      screen: modelData

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

      implicitHeight: 30

      ClockWidget {
        anchors.centerIn: parent

        // no more time binding
      }
    }
  }
}
```

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

### Define Property Bindings

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

Demonstrates simple, complex, and multi-line JavaScript expressions assigned to properties.

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

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

### activate()

Source: https://quickshell.org/docs/v0.2.1/types/Quickshell.I3/I3Workspace

Activates the workspace, making it the currently focused workspace in i3/Sway.

```APIDOC
## activate()

### Description
Activates the workspace. This is equivalent to executing the command `workspace number [number]` via the I3 dispatcher.

### Signature
`void activate()`
```

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

### connect()

Source: https://quickshell.org/docs/v0.2.1/types/Quickshell.Bluetooth/BluetoothDevice

Attempts to establish a connection to the Bluetooth device.

```APIDOC
## connect()

### Description
Attempts to establish a connection to the Bluetooth device.
```

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

### Assign functions to properties

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

Demonstrates assigning both standard functions and lambdas to properties.

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

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

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

### Configure Emacs for QML

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

Uses use-package to integrate qml-ts-mode with lsp-mode, registering the qmlls server and setting up hooks for indentation and deferred LSP startup.

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

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

### Configure PopupWindow anchor

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

Demonstrates setting the anchor window property using direct assignment or block syntax.

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

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

### Implicit File Imports

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

Demonstration of how neighboring files are automatically imported as types.

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

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

### Implementing a Singleton Type

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

Illustrates the use of the pragma Singleton directive to ensure only one instance of a type exists.

```qml
pragma Singleton
import ...

Singleton {
  ...
}
```

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

### Define a Hyprland global shortcut

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

Use this syntax in your Hyprland configuration to bind a key to a Quickshell global shortcut.

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

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

### execute()

Source: https://quickshell.org/docs/v0.2.1/types/Quickshell/DesktopAction

Executes the application associated with the desktop action. This method is equivalent to calling Quickshell.execDetached() with the action's command and working directory.

```APIDOC
## execute()

### Description
Runs the application associated with the DesktopAction. Currently, this method ignores field codes.

### Signature
`execute() : void`
```

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

### pair()

Source: https://quickshell.org/docs/v0.2.1/types/Quickshell.Bluetooth/BluetoothDevice

Attempts to initiate the pairing process with the device.

```APIDOC
## pair()

### Description
Attempts to initiate the pairing process with the device.
```

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

### Create manual bindings with Qt.binding

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

Use the Qt.binding function to attach a binding expression to a property at runtime.

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

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

### Using WrapperManager with the default property

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

Demonstrates how to define a visual child using the default property of a WrapperWidget.

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

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

### Connect signals using the connect method

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

Use the connect method to link a signal to a function, demonstrated here with a button click.

```qml
ColumnLayout {
  property int clicks: 0

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

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

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

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

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

### Read a JSON file as text

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

Demonstrates loading a JSON file into a FileView and parsing it into a JavaScript object.

```qml
FileView {
  id: jsonFile
  path: Qt.resolvedUrl("./your.json")
  // Forces the file to be loaded by the time we call JSON.parse().
  // see blockLoading's property documentation for details.
  blockLoading: true
}

readonly property var jsonData: JSON.parse(jsonFile.text())
```

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

### Specify Quickshell Configuration Directory

Source: https://quickshell.org/docs/v0.2.1/guide/distribution

Use the `--config` or `-c` flag to specify a named configuration directory within `$XDG_CONFIG_HOME/quickshell` when distributing configurations as dotfiles.

```bash
qs -c <name>
```

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

### Use Default Properties

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

Illustrates assigning objects to a default property without explicitly naming the property.

```qml
Item {
  // normal property
  foo: 3

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

```qml
Item {
  // normal property
  foo: 3

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

  // this one is too
  Item {
  }
}
```

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

### Assign and Use IDs

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

Demonstrates using the id property to reference objects within the same file.

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

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

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

### next()

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

Plays the next song in the media player.

```APIDOC
## next()

### Description
Play the next song. May only be called if the player supports it.
```

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

### activate()

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

Activates the workspace, equivalent to dispatching a workspace command via the Hyprland IPC.

```APIDOC
## activate()

### Description
Activates the workspace. This is equivalent to running `HyprlandIpc.dispatch("workspace ${workspace.name}");`.

### Signature
`void activate()`
```

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

### Show Registered IPC Targets and Functions

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

Use 'qs ipc show' to list all registered IPC targets and their associated functions. This command helps in understanding the available IPC endpoints and their signatures.

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

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

### Configure QsMenuAnchor properties

Source: https://quickshell.org/docs/v0.2.1/types/Quickshell/QsMenuAnchor

Set the anchor window for the menu using either direct property assignment or a property group block.

```QML
QsMenuAnchor {
  anchor.window: parentwindow
  // or
  anchor {
    window: parentwindow
  }
}
```

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

### exec(context)

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

Launches a process with the specified arguments and configuration, stopping any currently running process.

```APIDOC
## exec(context)

### Description
Launches a process with the given arguments, stopping any currently running process. The context can be a list of command arguments or an object defining command, environment, and working directory settings.

### Parameters
- **context** (list|object) - Required - Either a list of command arguments or an object containing `command`, `environment`, `clearEnvironment`, and `workingDirectory`.
```

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

### Create monitor-aware windows with Variants

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

Uses the Variants type to instantiate a PanelWindow for every screen in the Quickshell.screens model. Each window receives its specific screen via the modelData property.

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

Variants {
  model: Quickshell.screens;

  delegate: Component {
    PanelWindow {
      // the screen from the screens list will be injected into this
      // property
      required 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

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

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

### Displaying System Time with SystemClock

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

Configures a SystemClock instance with second-level precision and displays the formatted date and time in a Text element.

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

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

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

### Set process environment variables

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

Define environment variables for the process. Wrap the object in parentheses to ensure correct parsing.

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

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

### Implementing a custom wrapper component

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

Illustrates how to create a custom wrapper by aliasing the child property of an internal WrapperManager.

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

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

### execDetached(context)

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

Launches a process detached from the Quickshell instance.

```APIDOC
## execDetached(context)
Launches a process detached from Quickshell. The context can be a list of arguments or an object containing `command`, `environment`, `clearEnvironment`, and `workingDirectory`.
```

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

### execute()

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

Executes the application defined by the desktop entry. This function ignores field codes and terminal requirements, effectively running the command in the specified working directory.

```APIDOC
## execute()

### Description
Runs the application associated with the desktop entry. This is a convenience method equivalent to calling Quickshell.execDetached with the entry's command and working directory.

### Returns
- **void** - No return value.
```

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

### Handle signals with a Connections object

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

Use a Connections object to handle signals when direct handlers are inconvenient, such as with Singletons.

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

  Connections {
    target: myButton

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

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

### Reusing a window on every screen

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

Uses the screens property to instantiate a window on every connected display, automatically handling creation and destruction as screens change.

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

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

### Implement BoundComponent

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

Usage of BoundComponent to load a source file, set initial properties, and define signal handlers.

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

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

### Handle signals with implicit signal handlers

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

Use the on<Signal> property as a concise alternative to explicit connections.

```qml
ColumnLayout {
  property int clicks: 0

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

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

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

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

### activate()

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

Triggers the primary activation action for the system tray item, typically mapped to a left-click event.

```APIDOC
## activate()

### Description
Performs the primary activation action for the system tray item.

### Signature
`void activate()`
```

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

### Displaying a menu item icon

Source: https://quickshell.org/docs/v0.2.1/types/Quickshell/QsMenuEntry

Use the icon property with an Image component, setting sourceSize to match the rendered dimensions for optimal quality.

```qml
Image {
  source: menuItem.icon
  // To get the best image quality, set the image source size to the same size
  // as the rendered image.
  sourceSize.width: width
  sourceSize.height: height
}
```

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

### DBusMenuItem Class Overview

Source: https://quickshell.org/docs/v0.2.1/types/Quickshell.DBusMenu/DBusMenuItem

Provides information about the DBusMenuItem class, its properties, functions, and signals.

```APIDOC
## DBusMenuItem: QsMenuEntry 

Menu item shared by an external program via the DBusMenu specification.

### Properties

* **menuHandle** (DBusMenuHandle) - readonly - Handle to the root of this menu.

### Functions

* **updateLayout** () : void
Refreshes the menu contents. Usually you shouldn’t need to call this manually but some applications providing menus do not update them correctly. Call this if menus don’t update their state.
The `layoutUpdated` signal will be sent when a response is received.

### Signals

* **layoutUpdated** ()
_No details provided_
```

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

### monitorFor(screen)

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

Retrieves the HyprlandMonitor object corresponding to a given Quickshell screen.

```APIDOC
## monitorFor(screen)

### Description
Get the HyprlandMonitor object that corresponds to a quickshell screen.

### Parameters
- **screen** (ShellScreen) - Required - The quickshell screen object.
```

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

### Configure background color with ProxyWindow

Source: https://quickshell.org/docs/v0.2.1/types/Quickshell.Wayland/WlSessionLockSurface

Use a ProxyWindow with a Rectangle to set a background color, which is recommended over setting the color property directly when using transparency.

```QML
ProxyWindow {
  Rectangle {
    anchors.fill: parent
    color: "#20ffffff"

    // your content here
  }
}
```

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

### Container Item with Anchors

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

Simplifies layout logic by using QtQuick anchors to handle margins and positioning instead of manual property bindings.

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

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

### Import I3 module

Source: https://quickshell.org/docs/v0.2.1/types/Quickshell.I3/I3Workspace

Required import to access I3 workspace functionality.

```QML
import Quickshell.I3
```

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

### DesktopEntries API

Source: https://quickshell.org/docs/v0.2.1/types/Quickshell/DesktopEntries

Provides access to desktop entry information, including properties and functions for lookup.

```APIDOC
## DesktopEntries API

### Description
Index of desktop entries according to the desktop entry specification. Primarily useful for looking up icons and metadata from an id, as there is currently no mechanism for usage based sorting of entries and other launcher niceties.

### Properties
#### applications (ObjectModel <DesktopEntry>)
- **Type**: ObjectModel <DesktopEntry>
- **Readonly**: true
- **Description**: All desktop entries of type Application that are not Hidden or NoDisplay.

### Functions
#### byId (id: string) : DesktopEntry
- **Description**: Look up a desktop entry by name. Includes NoDisplay entries. May return null. While this function requires an exact match, heuristicLookup() will correctly find an entry more often and is generally more useful.
- **Parameters**:
  - **id** (string) - Required - The exact name of the desktop entry to look up.
- **Returns**: DesktopEntry or null if not found.

#### heuristicLookup (name: string) : DesktopEntry
- **Description**: Look up a desktop entry by name using heuristics. Unlike byId(), if no exact matches are found this function will try to guess - potentially incorrectly. May return null.
- **Parameters**:
  - **name** (string) - Required - The name of the desktop entry to look up using heuristics.
- **Returns**: DesktopEntry or null if not found.

### Signals
#### applicationsChanged ()
- **Description**: Emitted when the list of applications changes.
```

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

### Access Singleton Properties in UI

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

Demonstrates accessing a property from a Singleton directly within a UI component.

```qml
// ClockWidget.qml
import QtQuick

Text {
  // we no longer need time as an input

  // directly access the time property from the Time singleton
  text: Time.time
}
```

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

### writeAdapter()

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

Writes the current content to the selected file.

```APIDOC
## writeAdapter()

### Description
Persists the current content to the associated file.
```

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

### Custom Container Item with Margins

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

Demonstrates a basic container that calculates implicit size based on a child and sets the child's actual size and position relative to the parent.

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

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

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

### Using JsonAdapter with FileView

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

Configure FileView to use JsonAdapter for managing JSON data. Set watchChanges to reload from disk and onAdapterUpdated to write changes back. Properties like strings, lists, and nested objects can be defined and observed.

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

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

### previous()

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

Plays the previous song or restarts the current one.

```APIDOC
## previous()

### Description
Play the previous song, or go back to the beginning of the current one. May only be called if supported.
```

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

### Reactive Property Binding in ObjectModel

Source: https://quickshell.org/docs/v0.2.1/types/Quickshell/ObjectModel

Demonstrates the difference between non-reactive and reactive property binding when accessing elements in an ObjectModel.

```qml
// will not update reactively
property var foo: model[3]
```

```qml
// will update reactively
property var foo: model.values[3]
```

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

### iconPath(icon, [check], [fallback])

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

Resolves a system icon path.

```APIDOC
## iconPath(icon: string) -> string
## iconPath(icon: string, check: bool) -> string
## iconPath(icon: string, fallback: string) -> string
Returns a string usable for an icon. Setting `check` to true returns an empty string if the icon is missing. Setting `fallback` provides an alternative icon if the primary one fails to load.
```
Tokens:
Raw