# Retained patterns

Verify every Quickshell type against the installed-version docs before using these patterns.
These examples show structure, not cross-version compatibility.

## Single panel root

A `PanelWindow` can be the entry file's root object.
It does not need a `ShellRoot` wrapper.

```qml
import QtQuick
import Quickshell

PanelWindow {
    anchors { top: true; left: true; right: true }
    implicitHeight: 30
    Text { anchors.centerIn: parent; text: "hello" }
}
```

## One panel per screen

A `Variants` object can also be the entry root.

```qml
import QtQuick
import Quickshell

Variants {
    model: Quickshell.screens
    delegate: Component {
        PanelWindow {
            required property var modelData
            screen: modelData
        }
    }
}
```

`required property var modelData` exposes the model item to the delegate.

## Reactive clock

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

Text {
    text: Qt.formatTime(clock.date, "HH:mm:ss")
}
```

The binding updates when `clock.date` changes.
A direct `new Date()` expression has no changing QML dependency.

## Process output

```qml
import Quickshell.Io

Process {
    command: ["some-program", "--argument"]
    running: true
    stdout: StdioCollector {
        onStreamFinished: output.text = this.text
    }
}
```

Pass command arguments as a list.
Do not invoke a shell unless shell syntax is explicitly required and trusted.

For line-oriented output, use `SplitParser` and its `onRead` signal after verifying the installed type page.

## Service-backed slider

Assuming the containing object declares
`readonly property var sinkAudio: Pipewire.defaultAudioSink ? Pipewire.defaultAudioSink.audio : null`:

```qml
Slider {
    value: sinkAudio ? sinkAudio.volume : 0
    onMoved: if (sinkAudio) sinkAudio.volume = value
}
```

The `value` binding keeps external service changes reactive.
`onMoved` limits writes to user movement instead of reacting to initialization or service-driven updates.

## Changing signal target

```qml
Connections {
    target: sinkAudio
    function onVolumeChanged() {
        showVolumeOsd()
    }
}
```

Bind `target` to the current service object because the object may appear, disappear, or be replaced.

## Conditional non-Item object

```qml
LazyLoader {
    active: shouldShow
    PanelWindow { /* content */ }
}
```

Use `LazyLoader` for a conditionally instantiated window.
Use ordinary `visible` when retaining the object is intentional.

## Click-through panel

```qml
PanelWindow {
    color: "transparent"
    mask: Region {}
}
```

An empty `Region` makes the window's input mask empty.
Confirm interaction in a nested compositor because static loading cannot prove click-through behavior.

## IPC callable

```qml
import Quickshell.Io

IpcHandler {
    target: "mybar"
    function toggle(): void {
        panel.visible = !panel.visible
    }
}
```

IPC function argument and return types must be explicit and supported by the installed version.
Inspect registered handlers with `qs ipc show`, then call the function with `qs ipc call mybar toggle`.

## Multi-file configuration

Neighboring PascalCase QML files can define local types.
For subdirectories, follow the installed guide's `qs.*` import rules.
Do not add compatibility imports or version gates unless the user explicitly requires multiple Quickshell versions.