### Install Quickshell on Guix

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

Install the release version of Quickshell from the standard Guix repository using guix install.

```bash
guix install quickshell
```

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

### Install Quickshell on Fedora

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

Install the release version of Quickshell from the Fedora Rawhide repository using dnf.

```bash
sudo dnf install quickshell
```

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

### Install Quickshell on Ubuntu

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

Add the DankLinux PPA and install either the latest release or development version of Quickshell on Ubuntu using apt.

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

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

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

### PopupWindow Usage Example

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

This example demonstrates how to create a panel window and a popup window centered over it.

```APIDOC
## PopupWindow: QsWindow

`import Quickshell`

Pupup window that can display in a position relative to a floating or panel window.

### Description

A component for creating popup windows that can be positioned relative to other windows or elements.

### Example

The following snippet creates a panel with a popup centered over it.

```javascript
PanelWindow {
  id: toplevel

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

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

### Properties

*   **relativeY** (int) - Deprecated in favor of `anchor.rect.y`. The Y position of the popup relative to the parent window.
*   **visible** (bool) - If the window is shown or hidden. Defaults to false. The popup will not be shown until `anchor` is valid, regardless of this property.
*   **relativeX** (int) - Deprecated in favor of `anchor.rect.x`. The X position of the popup relative to the parent window.
*   **anchor** (PopupAnchor readonly) - The popup’s anchor / positioner relative to another item or window. The popup will not be shown until it has a valid anchor relative to a window and `visible` is true. You can set properties of the anchor like so:
    ```javascript
    PopupWindow {
      anchor.window: parentwindow
      // or
      anchor {
        window: parentwindow
      }
    }
    ```
*   **screen** (ShellScreen readonly) - The screen that the window currently occupies. This may be modified to move the window to the given screen.
*   **parentWindow** (QtObject) - Deprecated in favor of `anchor.window`. The parent window of this popup. Changing this property reparents the popup.
```

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

### QML Import Examples

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

Provides concrete examples of various QML import statements, including module imports with versions and namespaces, and JavaScript file imports.

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

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

### Install Quickshell on Arch Linux

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

Install the release version of Quickshell from the official Arch Linux repositories using pacman.

```bash
pacman -S quickshell
```

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

### SocketServer Configuration

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

Configuration example for setting up a SocketServer with a custom handler and parser.

```APIDOC
## SocketServer Configuration Example

### Description
This example demonstrates how to configure a `SocketServer` component, specifying its active state, the path for the socket file, and a custom `handler` for managing connections.

### Component Structure
```
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}`)
    }
  }
}
```

### Properties
- **active** (bool): If the socket server is currently active. Defaults to `false`. Setting this to `false` will destroy all active connections and delete the socket file on disk. If `path` is empty, setting this property will have no effect.
- **path** (string): The path to create the socket server at. Setting this property while the server is active will have no effect.
- **handler** (Component): Connection handler component. Must create a `Socket`. The created socket should not set `onConnectedChanged` or `onRead` as they will be set by the socket server. Setting `connected` to `false` on the created socket after connection will close and delete it.
```

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

### QSWindow Mask Example

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

Example demonstrating how to use the `mask` property with different intersection modes.

```APIDOC
### Mask Example 1: Basic Region
```
ShellWindow {
  // The mask region is set to `rect`, meaning only `rect` is clickable.
  // All other clicks pass through the window to ones behind it.
  mask: Region { item: rect }

  Rectangle {
    id: rect

    anchors.centerIn: parent
    width: 100
    height: 100
  }
}
```

### Mask Example 2: Inverted Region (Xor Intersection)
```
ShellWindow {
  // The mask region is set to `rect`, but the intersection mode is set to `Xor`.
  // This inverts the mask causing all clicks inside `rect` to be passed to the window
  // behind this one.
  mask: Region { item: rect; intersection: Intersection.Xor }

  Rectangle {
    id: rect

    anchors.centerIn: parent
    width: 100
    height: 100
  }
}
```

**Note**: If the provided region’s intersection mode is `Combine` (the default), then the region will be used as is. Otherwise, it will be applied on top of the window region.
```

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

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

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

Install the development version of Quickshell from the AUR using an AUR helper like yay. Note that this version may break when Qt is updated.

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

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

### Setup qmlls in Neovim

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

This Lua snippet configures the qmlls language server for Neovim using the nvim-lspconfig plugin. Ensure nvim-lspconfig is installed and the qmljs tree-sitter grammar is available.

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

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

### Create a Basic PanelWindow

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

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

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

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

  implicitHeight: 30

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

    text: "hello world"
  }
}
```

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

### Implicit QML Import Example

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

Illustrates how QML automatically imports types from neighboring files if their names start with an uppercase letter, simplifying type usage.

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

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

### Enable Fedora COPR and Install Quickshell

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

Enable the errornointernet/quickshell COPR repository to install either the latest release or development version of Quickshell on Fedora.

```bash
sudo dnf copr enable errornointernet/quickshell

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

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

### Start and Monitor a Process

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

Defines a process with a command and configures stdout to log each line read. Use this to execute commands and capture their output.

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

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

### QML Document Structure Example

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

Illustrates the basic structure of a QML document, including imports, root object definition, property declarations, bindings, signal handlers, functions, and inline components.

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

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

### Asynchronous PopupWindow Loading with LazyLoader

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

This example demonstrates how to use LazyLoader to asynchronously load a PopupWindow. The popup is prepared in the background during spare frame time, allowing the main UI to remain responsive. Accessing the popup's item before it's fully loaded will block the UI thread.

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

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

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

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

### Container Item with Anchors

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

This example demonstrates how to use QtQuick Anchors to achieve the same result as the previous examples, reducing boilerplate code. It sets the child Rectangle to fill the parent and adds margins to all anchored sides.

```javascript
Item {
  property real margin: 5

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

  Rectangle {
    id: child

    // "Fill" the space occupied by the parent, setting width
    anchors.fill: parent
    // Add a margin to all anchored sides.
    anchors.margins: parent.margin

    implicitWidth: 50
    implicitHeight: 50
  }
}
```

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

### Bind Global Shortcut in Hyprland

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

Example of how to bind a global shortcut within Hyprland's configuration. This format is used to associate a key combination with a specific application and action.

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

```

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

### Update Process Output with a Timer

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

Use a Timer to periodically rerun a process, updating its output at a set interval. This example creates a live clock.

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

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

### Start Process Detached

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

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

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

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

### Property Access Scopes Example

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

Illustrates legal and illegal property access based on scope, showing how to access properties of the current object, root object, or objects by their `id` or `parent`.

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

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

### QML Object Definition

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

Shows the basic syntax for defining a QML object, which is an instance of a type from an imported module. Object names must start with an uppercase letter.

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

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

### HyprlandFocusGrab Example

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

Demonstrates how to use HyprlandFocusGrab to take and release exclusive input focus for a FloatingWindow. The button's text updates to reflect the grab's active state.

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

ShellRoot {
  FloatingWindow {
    id: window

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

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

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

### QML Reactive Function Example

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

Demonstrates a QML function that returns a string based on a property's value. Changes to the property automatically re-evaluate the function and update dependent UI elements.

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

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

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

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

### Run a Process and Display Output

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

Use Process and StdioCollector to run a command and display its output. The text updates when the process finishes.

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

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

  implicitHeight: 30

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

    anchors.centerIn: parent

    // create a process management object
    Process {
      // the command it will run, every argument is its own string
      command: ["date"]

      // run the command immediately
      running: true

      // process the stdout stream using a StdioCollector
      // Use StdioCollector to retrieve the text the process sends
      // to stdout.
      stdout: StdioCollector {
        // Listen for the streamFinished signal, which is sent
        // when the process closes stdout or exits.
        onStreamFinished: clock.text = this.text // `this` can be omitted
      }
    }
  }
}
```

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

### Nested Region Example

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

An example demonstrating how to create a complex region with a cutout using nested Region objects and the `intersection` property.

```APIDOC
### Nested Region Example

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

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

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

### Quickshell Module Import Syntax

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

Demonstrates the specific syntax for importing Quickshell modules, allowing access to shell root and nested folders via dotted paths.

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

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

### QML Lambda Callback Example

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

An example of using a lambda function as a callback within another QML function. This lambda updates a text element based on a counter passed to it.

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

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

### Define a Basic Quickshell Application

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

This is a complete Quickshell application in a single file. It includes UI elements, process execution, and a timer for updates.

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

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

### Nested Region Example

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

This example demonstrates how to create a complex region by nesting one region inside another, resulting in a square with a cutout. The `intersection` property is used to define how the inner region modifies the outer one.

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

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

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

### Execute Desktop Entry

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

This code demonstrates how to execute a desktop entry using the `execute()` function, which is equivalent to calling `Quickshell.execDetached()` with specific parameters.

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

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

### Create Panel Windows for Each Monitor with Variants

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

Use Variants to create instances of PanelWindow for each screen detected by Quickshell.screens. Each window displays the current time, updating 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
        }
      }
    }
  }
}
```

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

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

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

### Process Configuration and Execution

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

This section covers the configuration and execution of processes using the Process object in Quickshell.

```APIDOC
## Process Configuration and Execution

### Description
This section details the configuration and execution of processes using the `Process` object in Quickshell. It covers setting commands, managing environment variables, controlling process execution, and handling standard input/output streams.

### Properties

#### `command` (list<string>)
- **Description**: The command to execute. Each argument is its own string. This does not run the command in a shell. To execute shell scripts, use `["sh", "script.sh"]` or `["sh", "-c", "<your command>"]`.
- **Example**:
```
command: [ "some-command", "arg" ]
```

#### `running` (bool)
- **Description**: Controls whether the process is currently running. Setting to `true` starts the process if `command` is set. Setting to `false` sends `SIGTERM`. Defaults to `false`.
- **Example**:
```
Process {
  running: true
  onRunningChanged: if (!running) running = true
}
```

#### `environment` (unknown)
- **Description**: The environment for the executed process. This is a JSON object. Environment variables can be added by setting them to a string and removed by setting them to `null`.
- **Example**:
```
environment: ({
  ADDED: "value",
  REMOVED: null,
  "i'm different": "value",
})
```

#### `clearEnvironment` (bool)
- **Description**: If the process's environment should be cleared prior to applying the `environment` object. Defaults to `false`. If `true`, only the variables listed in `environment` will be visible to the process.
- **Example**:
```
clearEnvironment: true
environment: ({
  ADDED: "value",
  PASSED_FROM_SYSTEM: null,
})
```

#### `stdout` (DataStreamParser)
- **Description**: The parser for stdout. If `null`, the stdout channel will be closed, and no further data will be read.

#### `stderr` (DataStreamParser)
- **Description**: The parser for stderr. If `null`, the stderr channel will be closed, and no further data will be read.

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

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

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

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

### Notes
- Changing properties like `environment`, `command`, `workingDirectory`, `clearEnvironment`, `running`, and `stdinEnabled` after a process has started will affect the *next* started process, not the currently running one. The new value will be returned if the property is changed after starting a process.
- Use `startDetached()` to prevent the process from being killed if Quickshell is killed or reloaded.
```

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

### Get state path

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

Constructs a path within the per-shell state directory. Equivalent to `${Quickshell.stateDir}/${path}`.

```javascript
statePath (path) : string
path: string
```

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

### Get shell path

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

Constructs a path within the shell configuration directory. Equivalent to `${Quickshell.configDir}/${path}`.

```javascript
shellPath (path) : string
path: string
```

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

### Get data path

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

Constructs a path within the per-shell data directory. Equivalent to `${Quickshell.dataDir}/${path}`.

```javascript
dataPath (path) : string
path: string
```

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

### QML Using Connections Object for Signal Handling

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

Illustrates using a `Connections` object to handle signals, particularly useful for connecting to signals of Singleton objects or when implicit handlers are inconvenient.

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

  Connections {
    target: myButton

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

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

### Import Quickshell

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

Import the Quickshell library to use its functionalities.

```javascript
import Quickshell
```

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

### Get cache path

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

Constructs a path within the per-shell cache directory. Equivalent to `${Quickshell.cacheDir}/${path}`.

```javascript
cachePath (path) : string
path: string
```

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

### 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()`.
```

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

### UPowerDeviceType Enum

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

The UPowerDeviceType enum defines various device types. The `toString` function can be used to get a string representation of these types.

```APIDOC
## UPowerDeviceType Enum

### Description
An enumeration representing different types of devices managed by UPower.

### Import
`import Quickshell.Services.UPower`

### Functions
#### toString
- **Signature**: `toString(type: UPowerDeviceType): string`
- **Description**: Converts a UPowerDeviceType enum value to its string representation.

### Variants
- **Pen**
- **MediaPlayer**
- **Pda**
- **Keyboard**
- **Touchpad**
- **Printer**
- **Ups**
- **Tablet**
- **Modem**
- **BluetoothGeneric**
- **OtherAudio**
- **Headphones**
- **GamingInput**
- **Phone**
- **Wearable**
- **Network**
- **Video**
- **Mouse**
- **Computer**
- **Camera**
- **RemoteControl**
- **LinePower**
- **Headset**
- **Unknown**
- **Battery**
- **Scanner**
- **Speakers**
- **Toy**
- **Monitor**
```

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

### Reusing a window on every screen

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

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

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

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

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

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

### Load Component with Properties and Signals

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

Demonstrates using BoundComponent to load 'MyComponent.qml', setting its 'color' property, and defining an 'onClicked' signal handler.

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

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

### QML Connecting to a Signal with .connect()

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

Demonstrates how to connect a custom function to a signal using the `.connect()` method. The function is invoked when the signal is emitted.

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

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

### Removing Bindings by Reassignment in QML

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

To remove a binding, assign a new, non-binding value to the property. This example breaks the binding on 'boundText.text' after the button is clicked.

```QML
Item {
  Text {
    id: boundText
    text: `button is pressed: ${theButton.pressed}`
  }

  Button {
    id: theButton
    text: "break the binding"
    onClicked: boundText.text = `button was pressed at the time the binding was broken: ${pressed}`
  }
}
```

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

### Using a Custom QML Type (AnotherComponent.qml)

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

Demonstrates how to instantiate and use the custom `MyText` QML type. It shows how to set required properties, override inherited properties like `color`, and highlights that internal IDs like `textObj` are not accessible from outside.

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

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

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

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

### Get environment variable

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

Retrieves the string value of an environment variable. Returns null if the variable is not set. Usage: `Quickshell.env("VARIABLE_NAME")`.

```javascript
Quickshell.env (variable) : variant
variable: string
```

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

### Initialize ColorQuantizer

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

Instantiate ColorQuantizer with source image, depth, and rescale size. The depth determines the number of colors (2^depth), and rescaleSize optimizes processing time.

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

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

### Configure qml-ts-mode with lsp-mode in Emacs

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

This Emacs Lisp code configures the qml-ts-mode to work with lsp-mode, setting up the QML language server connection. Ensure qml-ts-mode and lsp-mode are installed.

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

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

### Initialize SystemClock with Seconds Precision

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

Instantiate SystemClock and set its precision to Seconds. This snippet also shows how to display the formatted date and time using Text and Qt.formatDateTime.

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

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

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

### Format System Time with SystemClock

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

Utilize the SystemClock library to get a Date object and format it using Qt.formatDateTime. The precision can be set to 'Minutes' to conserve battery if 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
  }
}
```

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

### Using ScriptModel with Quickshell ObjectModels

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

Demonstrates how to use ScriptModel with unique values from Quickshell's DesktopEntries.applications.values, suitable for dynamic filtering.

```javascript
ScriptModel {
  values: DesktopEntries.applications.values.filter(...)
}
```

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

### Set Anchor Properties for QsMenuAnchor

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

Demonstrates how to set properties of the anchor for a QsMenuAnchor. This is subject to change and not a guarantee of future behavior.

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

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

### Execute a Process with Arguments

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

Launches a process with specified arguments, stopping any currently running process. Arguments must be separate values. Use `["sh", "-c", <your command>]` to execute commands with the system shell.

```javascript
process.running = false;
process.command = ...
process.environment = ...
process.clearEnvironment = ...
process.workingDirectory = ...
process.running = true;
```

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

### Handle CheckBox State Changes

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

Use the `on<PropertyName>Changed` signal handler to react to property changes. This example listens for changes in `checkState` and updates a label's text accordingly.

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

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

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

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

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

### Configure Quickshell Git Channel in Guix

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

Add the Quickshell source repository as a channel in Guix to use the git version. Note that the package definition is in the source repo, requiring cloning for direct use.

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

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

### Implement Custom Wrapper Type

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

Provides an example of creating a custom wrapper component by embedding a WrapperManager and aliasing its 'child' property. This allows consumers to use the 'child' property on your custom component.

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

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

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

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

### Creating Manual Bindings with Qt.binding in QML

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

The Qt.binding function allows you to create bindings dynamically within functions or signal handlers. This example binds text to a button's pressed state.

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