### Import examples

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

Examples of import statements.

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

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

### start()

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

Starts an authentication session. Returns whether the session was started successfully.

```APIDOC
## start()

### Description
Starts an authentication session. Returns whether the session was started successfully.

### Method
start

### Parameters
None

### Returns
bool - True if the session was started successfully, false otherwise.

```

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

### Install Quickshell on Gentoo with GURU overlay

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

Enables the GURU overlay and installs 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 Guix

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

Installs the release version of Quickshell from the standard Guix repository.

```bash
guix install quickshell
```

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

### Neovim: Setup qmlls with nvim-lspconfig

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

Add this snippet to your Neovim configuration to set up the qmlls language server. Requires nvim-lspconfig. Note that tree-sitter highlighting may work better than built-in highlighting; install the grammar with :TSInstall qmljs.

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

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

### Install Quickshell on Debian with apt

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

Installs the release version of Quickshell from Debian unstable/testing.

```bash
sudo apt install quickshell
```

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

### Install Quickshell on Fedora with dnf

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

Installs the release version of Quickshell from Fedora Rawhide.

```bash
sudo dnf install quickshell
```

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

### Install Quickshell on Ubuntu from PPA

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

Adds the avengemedia/danklinux PPA and installs either the release or development version. Use `quickshell` for the latest release or `quickshell-git` for the master branch.

```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-git on Arch with yay

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

Installs the development version of Quickshell from the AUR. May break when Qt is updated; reinstall if warned of breakage.

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

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

### Install Quickshell on Arch with pacman

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

Installs the release version of Quickshell from the Arch Linux repository.

```bash
pacman -S quickshell
```

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

### play()

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

Starts playback. Equivalent to setting playbackState to Playing.

```APIDOC
## play()

### Description
Starts playback. Equivalent to setting playbackState to Playing.

### Method
play

### Parameters
None

### Returns
void
```

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

### startSystemMove()

Source: https://quickshell.org/docs/v0.3.1/types/Quickshell/FloatingWindow

Starts a system move operation. Must be called during a pointer press/drag.

```APIDOC
## startSystemMove()

### Description
Starts a system move operation. Must be called during a pointer press/drag.

### Method
Function

### Signature
`startSystemMove() : bool`

### Parameters
None

### Return Value
- **bool** - Whether the operation was successfully started.
```

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

### startSystemResize(edges)

Source: https://quickshell.org/docs/v0.3.1/types/Quickshell/FloatingWindow

Starts a system resize operation. Must be called during a pointer press/drag.

```APIDOC
## startSystemResize(edges)

### Description
Starts a system resize operation. Must be called during a pointer press/drag.

### Method
Function

### Signature
`startSystemResize(edges) : bool`

### Parameters
- **edges** - The edges to resize from.
```

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

### Implicit imports example

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

The QML engine will automatically import any types in neighboring files with names that start with an uppercase letter.

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

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

### I3IpcListener example with subscriptions and onIpcEvent

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

Creates an I3IpcListener that subscribes to the 'input' event and handles it with the onIpcEvent callback, passing the event data to a handleInputEvent function.

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

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

### Execute DesktopEntry with Quickshell.execDetached

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

Shown in the execute() function documentation, this example demonstrates how to run a desktop entry by passing its command and workingDirectory to Quickshell.execDetached(). The execute() method is equivalent to this call, but currently ignores field codes.

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

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

### Move bar to separate file: shell.qml and Bar.qml

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

Initial refactoring step: shell.qml contains the root Scope with a Bar component, while Bar.qml defines the bar with a PanelWindow, a Process to get the date, and a Timer to update it. Any QML file starting with an uppercase letter can be referenced this way.

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

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

### JSON document produced by the JsonAdapter example

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

The JSON output generated from the JsonAdapter example above, showing the mapping of QML properties to JSON keys and values.

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

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

### Install Quickshell from Fedora COPR

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

Enables the errornointernet/quickshell COPR and installs either the release or development version. Use `quickshell` for the latest release or `quickshell-git` for the master branch.

```bash
sudo dnf copr enable errornointernet/quickshell

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

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

### Scope usage example

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

Shows how to use Scope inside a ShellRoot with Variants. Everything inside the Scope behaves the same as if defined directly in Variants for reload purposes.

```qml
ShellRoot {
  Variants {
    variants: ...

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

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

### ColorQuantizer Example

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

Example usage of ColorQuantizer to extract 8 colors from an image with depth 3 and rescale size 64.

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

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

### LazyLoader example: asynchronously load a PopupWindow

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

Creates a PopupWindow asynchronously as the bar loads, allowing the bar to show before the popup is ready. Accessing popupLoader.item forces synchronous loading if not finished. The PopupWindow is positioned relative to the parent window and toggled by a button.

```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 bar on each monitor with Variants

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

Uses Variants with Quickshell.screens as the model to create a PanelWindow for each screen. The screen is injected into the modelData property and used to set the window's screen. Includes a Process to get the date and a Timer to refresh it every second.

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

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

### read()

Source: https://quickshell.org/docs/v0.3.1/types/Quickshell.Networking/NMSettings

Gets the settings map describing this network configuration. This will never include secrets required for connection.

```APIDOC
## read()

### Description
Get the settings map describing this network configuration. This will never include any secrets required for connection to the network, as those are often protected.

### Method
Function

### Signature
`read() : unknown`

### Parameters
None

### Returns
unknown - The settings map describing the network configuration.
```

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

### Rerun a process at an interval with Timer

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

Extends the previous clock example by adding a Timer that triggers every 1000 milliseconds. The timer sets the Process's `running` property to true to rerun the `date` command, keeping the displayed time updated.

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

```

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

### Automatic reactive binding example

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

Shows how a property binding is automatically created when using another property in a definition. The button's text updates when the clicks property changes.

```qml
Item {
  property int clicks: 0

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

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

### Hyprland global shortcut binding

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

Example of binding a global shortcut in Hyprland configuration. The syntax is `bind = <modifiers>, <key>, global, <appid>:<name>`. This is required for the GlobalShortcut to work.

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

```

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

### Process

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

The Process type is used to start and manage external processes. It supports configuring the command, environment, working directory, and I/O streams.

```APIDOC
## Process

### Description
The Process type is used to start and manage external processes. It supports configuring the command, environment, working directory, and I/O streams.

### Properties

#### stdout
- **Type**: DataStreamParser
- **Description**: The parser for stdout. If the parser is null the process's stdout channel will be closed and no further data will be read, even if a new parser is attached.

#### clearEnvironment
- **Type**: bool
- **Description**: If the process's environment should be cleared prior to applying environment. Defaults to false. If true, all environment variables will be removed before the environment object is applied, meaning the variables listed will be the only ones visible to the process. This changes the behavior of `null` to pass in the system value of the variable if present instead of removing it.

#### processId
- **Type**: variant (readonly)
- **Description**: The process ID of the running process or `null` if running is false.

#### command
- **Type**: list<string>
- **Description**: The command to execute. Each argument is its own string. Does not run in a shell. Use `["sh", "-c", <command>]` to execute with the system shell.

#### running
- **Type**: bool
- **Description**: If the process is currently running. Defaults to false. Setting to true starts the process if command has at least one element. Setting to false sends SIGTERM. Use signal() with SIGKILL to kill immediately.

#### stderr
- **Type**: DataStreamParser
- **Description**: The parser for stderr. If null, the stderr channel is closed.

#### workingDirectory
- **Type**: string
- **Description**: The working directory of the process. Defaults to quickshell's working directory.

#### environment
- **Type**: unknown
- **Description**: Environment variables for the process. Set to a string to add, null to remove (unless clearEnvironment is true).

#### stdinEnabled
- **Type**: bool
- **Description**: If stdin is enabled. Defaults to false. If false, the stdin channel is closed and write() does nothing.

#### stdout
- **Type**: DataStreamParser
- **Description**: The parser for stdout. If null, the stdout channel is closed and no further data is read.

#### stderr
- **Type**: DataStreamParser
- **Description**: The parser for stderr. If null, the stderr channel is closed and no further data is read.

#### clearEnvironment
- **Type**: bool
- **Description**: If true, clears the environment before applying the environment object. Defaults to false.

#### processId
- **Type**: variant (readonly)
- **Description**: The process ID of the running process, or null if not running.

#### command
- **Type**: list<string>
- **Description**: The command to execute as a list of arguments. Does not run in a shell by default.

#### running
- **Type**: bool
- **Description**: Whether the process is currently running. Setting to true starts the process; setting to false sends SIGTERM.

#### stderr
- **Type**: DataStreamParser
- **Description**: The parser for stderr. If null, the stderr channel is closed.

#### workingDirectory
- **Type**: string
- **Description**: The working directory of the process. Defaults to quickshell's working directory.

#### environment
- **Type**: unknown
- **Description**: Environment variables for the process. Set to a string to add, null to remove (unless clearEnvironment is true).

#### stdinEnabled
- **Type**: bool
- **Description**: If stdin is enabled. Defaults to false. If false, the stdin channel is closed and write() does nothing.
```

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

### Container with margin using anchors

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

Equivalent to the first container example but uses QtQuick Anchors to reduce boilerplate. The child fills the parent with a margin on all sides, and the container's implicit size is still derived from the child's implicit size plus margins.

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

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

### JsonAdapter usage in FileView with QML properties

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

Shows how to define a JsonAdapter inside a FileView to expose JSON keys as QML properties. The example includes watchChanges and onFileChanged to reload on disk changes, and onAdapterUpdated to save via writeAdapter(). It demonstrates primitive, list, JsonObject, and var properties, with change handlers.

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

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

### Create a bottom-anchored PanelWindow with a Text label

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

Creates a white bar attached to the bottom of the screen using anchors. The Text element is centered within the panel and displays "Hello!". This example demonstrates the basic structure of a PanelWindow with anchor configuration.

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

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

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

### ProxyWindow with transparent background workaround

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

Recommended workaround for transparent colors on some systems: use a colored content item over a transparent window. The example shows a ProxyWindow containing a Rectangle with a semi-transparent white color and a placeholder for content.

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

    // your content here
  }
}
```

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

### launch(command, environment)

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

Launches the session with an environment, exiting quickshell. Must be in GreetdState.ReadyToLaunch to call this function.

```APIDOC
## launch(command, environment)

### Description
Launches the session with an environment, exiting quickshell. Must be in `GreetdState.ReadyToLaunch` to call this function.

### Method
Function

### Signature
`launch(command, environment) : void`

### Parameters
- **command** (list) - Required - The command to launch as a list of arguments.
- **environment** (list) - Required - The environment variables to set for the session.

### Returns
void
```

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

### BoundComponent with initial properties and signal handler

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

Shows a BoundComponent loading MyComponent.qml and setting its color property and attaching an onClicked handler. Requires the loaded component to have a color property and a clicked signal, as in the MouseArea example. The initial color is "red" and changes to "blue" when clicked. The comment notes property assignment is equivalent to assigning to color on the loaded component normally.

```qml
MouseArea {
  required property color color;
  width: 100
  height: 100

  Rectangle {
    anchors.fill: parent
    color: parent.color
  }
}
```

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

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

### launch(command, environment, quit)

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

Launches the session, exiting quickshell if quit is true. Must be in GreetdState.ReadyToLaunch to call this function.

```APIDOC
## launch(command, environment, quit)

### Description
Launches the session, exiting quickshell if `quit` is true. Must be in `GreetdState.ReadyToLaunch` to call this function.

### Method
Function

### Signature
`launch(command, environment, quit) : void`

### Parameters
- **command** (list) - Required - The command to launch as a list of arguments.
- **environment** (list) - Required - The environment variables to set for the session.
- **quit** (bool) - Required - Whether to exit quickshell after launching.

### Returns
void
```

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

### launch(command)

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

Launches the session, exiting quickshell. Must be in GreetdState.ReadyToLaunch to call this function.

```APIDOC
## launch(command)

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

### Method
Function

### Signature
`launch(command) : void`

### Parameters
- **command** (list) - Required - The command to launch as a list of arguments.

### Returns
void
```

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

### UseQApplication pragma

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

Switches from the default QGuiApplication to a QApplication, enabling QtWidgets controls.

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

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

### WlrLayershell Usage Examples

Source: https://quickshell.org/docs/v0.3.1/types/Quickshell.Wayland/WlrLayershell

Examples of using WlrLayershell as an attached object of PanelWindow, including static and dynamic property setting.

```APIDOC
## WlrLayershell Usage Examples

### Static Usage
```
PanelWindow {
  // When PanelWindow is backed with WlrLayershell this will work
  WlrLayershell.layer: WlrLayer.Bottom
}
```

### Dynamic Usage for Platform Compatibility
```
PanelWindow {
  Component.onCompleted: {
    if (this.WlrLayershell != null) {
      this.WlrLayershell.layer = WlrLayer.Bottom;
    }
  }
}
```
```

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

### Reusing a window on every screen

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

This code snippet demonstrates how to create a window instance on every screen using the Quickshell.screens property and the Variants component.

```APIDOC
## Reusing a window on every screen

### Description
This example creates an instance of your window once on every screen. As screens are added or removed your window will be created or destroyed on those screens.

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

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

### elapsedNs()

Source: https://quickshell.org/docs/v0.3.1/types/Quickshell/ElapsedTimer

Returns the number of nanoseconds since the timer was last started or restarted.

```APIDOC
## elapsedNs()

### Description
Returns the number of nanoseconds since the timer was last started or restarted.

### Method
elapsedNs

### Return Value
- **int** - Number of nanoseconds since the timer was last started or restarted.
```

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

### elapsedMs()

Source: https://quickshell.org/docs/v0.3.1/types/Quickshell/ElapsedTimer

Returns the number of milliseconds since the timer was last started or restarted.

```APIDOC
## elapsedMs()

### Description
Returns the number of milliseconds since the timer was last started or restarted.

### Method
elapsedMs

### Return Value
- **int** - Number of milliseconds since the timer was last started or restarted.
```

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

### restartNs()

Source: https://quickshell.org/docs/v0.3.1/types/Quickshell/ElapsedTimer

Restarts the timer, returning the number of nanoseconds since the timer was last started or restarted.

```APIDOC
## restartNs()

### Description
Restarts the timer, returning the number of nanoseconds since the timer was last started or restarted.

### Method
restartNs

### Return Value
- **int** - Number of nanoseconds since the timer was last started or restarted.
```

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

### restartMs()

Source: https://quickshell.org/docs/v0.3.1/types/Quickshell/ElapsedTimer

Restarts the timer, returning the number of milliseconds since the timer was last started or restarted.

```APIDOC
## restartMs()

### Description
Restarts the timer, returning the number of milliseconds since the timer was last started or restarted.

### Method
restartMs

### Return Value
- **int** - Number of milliseconds since the timer was last started or restarted.
```

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

### execute()

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

Runs the application described by the desktop entry. This is equivalent to calling Quickshell.execDetached() with the entry's command and working directory.

```APIDOC
## execute()

### Description
Run the application. Currently ignores field codes. This is equivalent to calling Quickshell.execDetached() with the command and working directory.

### Method
Function

### Signature
`execute() : void`

### Parameters
None

### Return Value
- **void** - No return value.

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

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

### elapsed()

Source: https://quickshell.org/docs/v0.3.1/types/Quickshell/ElapsedTimer

Returns the number of seconds since the timer was last started or restarted, with nanosecond precision.

```APIDOC
## elapsed()

### Description
Returns the number of seconds since the timer was last started or restarted, with nanosecond precision.

### Method
elapsed

### Return Value
- **real** - Number of seconds since the timer was last started or restarted, with nanosecond precision.
```

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

### Run a process with Process and StdioCollector

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

Creates a PanelWindow with a Text element that displays the output of the `date` command. The Process object runs the command immediately and uses a StdioCollector to capture stdout, updating the text when the stream 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
      }
    }
  }
}

```

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

### SocketServer with Socket handler and SplitParser

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

Creates a socket server that listens on the given path. The handler must create a Socket; the server sets connected and path properties, so the socket should not set them or the connection will be dropped. Setting active to false destroys connections and deletes the socket file.

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

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

### restart()

Source: https://quickshell.org/docs/v0.3.1/types/Quickshell/ElapsedTimer

Restarts the timer, returning the number of seconds since the timer was last started or restarted, with nanosecond precision.

```APIDOC
## restart()

### Description
Restarts the timer, returning the number of seconds since the timer was last started or restarted, with nanosecond precision.

### Method
restart

### Return Value
- **real** - Number of seconds since the timer was last started or restarted, with nanosecond precision.
```

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

### activate()

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

Activates the workspace. This is equivalent to running I3.dispatch(`workspace number ${workspace.number}`);

```APIDOC
## activate()

### Description
Activate the workspace. This is equivalent to running `I3.dispatch(`workspace number ${workspace.number}`);`

### Method
activate

### Parameters
None

### Return Value
void
```

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

### ColorQuantizer

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

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

```APIDOC
## ColorQuantizer: QtObject

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

### Import
`import Quickshell`

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

### Properties

#### depth (real)
Max depth for the color quantization. Each level of depth represents another binary split of the color space.

#### rescaleSize (real)
The size to rescale the image to. When rescaleSize is 0, no scaling is done. Results from color quantization don’t suffer much when rescaling; it’s recommended to rescale, otherwise the quantization process will take much longer.

#### source (unknown)
Path to the image you’d like to run the color quantization on.

#### imageRect (rect)
Rectangle that the source image is cropped to. Can be set to `undefined` to reset.

#### colors (list<color>) - readonly
Access the colors resulting from the color quantization performed. The amount of colors returned is determined by the property depth, specifically 2ⁿ where n is the depth.
```

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

### open() : void

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

Opens the given menu on this anchor. Requires that the anchor is valid.

```APIDOC
## open() : void

### Description
Open the given menu on this anchor. Requires that the anchor is valid.

### Method
open

### Parameters
None

### Returns
void
```

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

### PAM configuration file rule syntax

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

Shows the general syntax of a pam configuration file rule, where type, control flag, module path, and optional parameters are space-separated. Each line is a rule and runs in order.

```text
<type> <control_flag> <module_path> [options]

```

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

### Basic Process usage with stdout collector

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

Creates a Process that runs a command and collects stdout lines. The command is a list of strings, and the stdout parser is a StdioCollector that logs each line when the stream finishes.

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

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

### Use SystemClock for Time (Time.qml)

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

Replaces the Process-based time retrieval with the SystemClock support library. The precision can be set to Minutes to reduce work when seconds are not displayed.

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

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

### toString(conn)

Source: https://quickshell.org/docs/v0.3.1/types/Quickshell.Networking/NetworkConnectivity

Converts a NetworkConnectivity enum value to its string representation. This function is part of the NetworkConnectivity enum and can be used to get a human-readable string for a given connectivity state.

```APIDOC
## toString(conn)

### Description
Converts a NetworkConnectivity enum value to its string representation.

### Parameters
- **conn** (NetworkConnectivity) - Required - The NetworkConnectivity value to convert.

### Returns
- **string** - The string representation of the connectivity value.

```

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

### Setting environment variables

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

Shows how to set environment variables using a JavaScript object. Variables set to a string are added, and null removes them. The object must be wrapped in parentheses.

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

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

### Fingerprint-first with password fallback PAM configuration

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

First tries fingerprint authentication with pam_fprintd.so; if it succeeds, authentication passes. If it fails, falls back to password authentication with pam_unix.so, which is required to pass.

```text
auth sufficient pam_fprintd.so
auth required pam_unix.so

```

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

### Console error when clock is not defined

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

Shows the repeated ReferenceError that appears in the console every second when running the incorrect Scope example, because the clock reference is not defined in the Scope's context.

```text
WARN scene: **/shell.qml[36:-1]: ReferenceError: clock is not defined
WARN scene: **/shell.qml[36:-1]: ReferenceError: clock is not defined
WARN scene: **/shell.qml[36:-1]: ReferenceError: clock is not defined
WARN scene: **/shell.qml[36:-1]: ReferenceError: clock is not defined
WARN scene: **/shell.qml[36:-1]: ReferenceError: clock is not defined
```

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

### startDetached() : void

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

Launches an instance of the process detached from Quickshell. The subprocess will not be tracked, running will be false, and the subprocess will not be killed by Quickshell.

```APIDOC
## startDetached() : void

### Description
Launches an instance of the process detached from Quickshell. The subprocess will not be tracked, running will be false, and the subprocess will not be killed by Quickshell. This function is equivalent to Quickshell.execDetached().

### Parameters
None.

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

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

### Toggle exclusive focus with HyprlandFocusGrab

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

Example showing how to use HyprlandFocusGrab inside a FloatingWindow to toggle exclusive focus. The button toggles the active property, and the grab is configured with the window in its windows list.

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

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

### Setting clearEnvironment and environment

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

Shows how to clear the environment and set specific variables. When clearEnvironment is true, only the listed variables are visible to the process, and null passes the system value.

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

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

### Reactive function example with ColumnLayout and Button

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

Demonstrates a function that depends on a property (clicks) and is used in a Text element. When the button is clicked, clicks changes, triggering re-evaluation of the function and updating the text.

```qml
ColumnLayout {
  property int clicks: 0

  function makeClicksLabel(): string {
    return "the button has been clicked " + clicks + " times!";
  }

  Button {
    text: "click me"
    onClicked: clicks += 1
  }

  Text {
    text: makeClicksLabel()
  }
}
```

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

### execute()

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

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

```APIDOC
## execute()

### Description
Runs the application associated with the desktop action. Currently ignores field codes. This is equivalent to calling Quickshell.execDetached() with the command and working directory.

### Method
Function

### Signature
`execute() : void`

### Parameters
None

### Return Value
- **void** - No return value.

```

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

### MarginWrapperManager basic usage

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

Rewrites the earlier container example using MarginWrapperManager to handle size and position automatically, avoiding the childrenRect binding loop. The child Rectangle is automatically detected and sized.

```qml
Item {
  MarginWrapperManager { margin: 5 }

  // Automatically detected by MarginWrapperManager as the
  // primary child of the container and sized accordingly.
  Rectangle {
    implicitWidth: 50
    implicitHeight: 50
  }
}
```

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

### Property definition examples in QML

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

Shows normal, readonly, and bound property definitions. Defining a property with the same name as one provided by the current object will override the property of the type it is derived from in the current context.

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

  // readonly property
  readonly property string bar: "hi!"

  // bound property
  property var things: [ "foo", "bar" ]
}
```

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

### Create a simple PanelWindow bar

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

Creates a bar/panel on the currently focused monitor with a centered text. It reserves space for itself on the monitor. Uses PanelWindow from Quickshell and Text from QtQuick.

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

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

### Manual binding with Qt.binding

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

Shows how to create a binding at runtime using Qt.binding. The boundText's text property is bound to the button's pressed state when the button is first clicked.

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

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

### childrenRect binding loop example

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

Shows the common but incorrect pattern of using childrenRect to size a container. This creates a binding loop because childrenRect reflects actual geometry, not implicit geometry, causing an indirect self-dependency.

```qml
Item {
  implicitWidth: childrenRect.width
  implicitHeight: childrenRect.height

  Rectangle {
    anchors.fill: parent

    implicitWidth: 50
    implicitHeight: 50
  }
}
```

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

### raise()

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

Brings the media player to the front of the window stack. May only be called if canRaise is true.

```APIDOC
## raise()

### Description
Brings the media player to the front of the window stack. May only be called if canRaise is true.

### Method
raise

### Parameters
None

### Returns
void
```

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

### activate()

Source: https://quickshell.org/docs/v0.3.1/types/Quickshell.WindowManager/Windowset

Activates the windowset, making it the current workspace on a workspace based WM, or activating the tag on a tag based WM.

```APIDOC
## activate()

### Description
Activates the windowset, making it the current workspace on a workspace based WM, or activating the tag on a tag based WM.

### Method
activate

### Parameters
None

### Return Value
void

```

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

### Property access scopes in QML

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

Properties are in scope if defined for the current type or the root type in the current file. Access properties of other objects by id or via parent. The example shows legal and illegal property accesses.

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

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

### Object syntax

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

An object looks like this:

```qml
Name {
  id: foo
  // properties, functions, signals, etc...
}
```

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

### Define and use a custom QML type (MyText)

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

Create a reusable type in MyText.qml with a required `text` property and use it in AnotherComponent.qml. The example shows that `id` properties are not accessible outside the file, and that properties like `color` and `anchors` can be overridden.

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

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

### Reusing a window on every screen with Variants

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

Creates a PanelWindow instance on every screen, updating as screens are added or removed. Uses the Variants component with Quickshell.screens as the variants list.

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

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

### statePath(path)

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

Returns a path under the Quickshell state directory.

```APIDOC
## statePath(path)

### Description
Returns a path under the Quickshell state directory. Equivalent to `${Quickshell.stateDir}/${path}`.

### Parameters
- **path** (string) - Required - The path to append to the state directory.

### Returns
- **string** - The full state path.
```

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

### Environment pragma (Env, DefaultEnv)

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

Sets environment variables for Quickshell only; does not affect spawned processes.

```qml
//@ pragma Env VAR = VAL
//@ pragma DefaultEnv VAR = VAL
```

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

### Using ScriptModel to avoid delegate re-creation

Source: https://quickshell.org/docs/v0.3.1/types/Quickshell/ScriptModel

Shows two Repeater examples: the first uses a raw JavaScript expression as the model, causing all delegates to be re-created when filterText changes; the second wraps the expression in ScriptModel, which only adds and removes delegates as needed, enabling ListView animations.

```qml
// Will cause all delegates to be re-created every time filterText changes.
Repeater {
  model: myList.filter(entry => entry.name.startsWith(filterText))
  delegate: // ...
}

// Will add and remove delegates only when required.
Repeater {
  model: ScriptModel {
    values: myList.filter(entry => entry.name.startsWith(filterText))
  }

  delegate: // ...
}
```

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

### Activate i3 workspace with I3.dispatch

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

Activates a workspace by dispatching an i3/Sway command. This is what the workspace's activate() method runs internally.

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