repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

skill: add quickshell examples and docs

4c542374da3802b5febe4e8e2cf898f768bec7a1

Review <review@example.invalid> ·

unsigned

Browse filesCompare with HEAD

Changed files (11)

skills/quickshell/examples/01-hello-bar/README.md

Added
new file mode 100644
1 +# 01 — hello bar
3 +Smallest valid Quickshell shell. One `PanelWindow` anchored to the top of the focused monitor, 30 px tall, dark translucent background, centered white text.
5 +**Run:** `qs -p examples/01-hello-bar/shell.qml`
7 +**What it teaches:** the minimal shell shape — one `PanelWindow`, three anchors, one child.
9 +**What to break and learn from:**
11 +- Remove `anchors.left` and `anchors.right` → bar shrinks to its content width.
12 +- Change `color: "transparent"` → surface format flips; you'll see the bar become transparent but the text rendering may look different.
13 +- Add `mask: Region {}` → bar still renders but doesn't accept clicks; useful when you only want to show a strip and let clicks pass through.
14 +- Run without a compositor: the panel fails to attach and quickshell exits. This is expected; the panel needs a Wayland compositor.

skills/quickshell/examples/01-hello-bar/shell.qml

Added
new file mode 100644
1 +// 01-hello-bar/shell.qml
2 +// Smallest valid Quickshell shell: one panel on the focused monitor, "hello world".
3 +// Run with: qs -p examples/01-hello-bar/shell.qml
5 +import QtQuick
6 +import Quickshell
8 +PanelWindow {
9 + anchors {
10 + top: true
11 + left: true
12 + right: true
13 + }
14 + implicitHeight: 30
15 + color: "#cc1e1e2e"
17 + Text {
18 + anchors.centerIn: parent
19 + text: "hello quickshell"
20 + color: "white"
21 + }

skills/quickshell/examples/02-per-monitor-bar/Bar.qml

Added
new file mode 100644
1 +// 02-per-monitor-bar/Bar.qml
2 +// The bar component. Implicitly importable from shell.qml (PascalCase, same dir).
4 +import QtQuick
5 +import Quickshell
7 +PanelWindow {
8 + id: bar
10 + // Anchored to top, full-width.
11 + anchors {
12 + top: true
13 + left: true
14 + right: true
15 + }
16 + implicitHeight: 32
17 + color: "#cc1e1e2e"
19 + // The screen is set by the Variants delegate.
20 + // (Required property is in shell.qml; this file just consumes it via `screen`.)
22 + Row {
23 + anchors.fill: parent
24 + anchors.leftMargin: 12
25 + anchors.rightMargin: 12
26 + spacing: 16
28 + // Left side: workspace label (just static here; see Hyprland example for live).
29 + Text {
30 + text: "Bar"
31 + color: "white"
32 + font.pointSize: 11
33 + anchors.verticalCenter: parent.verticalCenter
34 + }
36 + Item { Layout.fillWidth: true; width: 1 } // spacer, push right cluster right
38 + // Right side: a clock. Uses SystemClock for live updates.
39 + Text {
40 + text: SystemClock.date.toLocaleDateString(Qt.locale(), Locale.ShortFormat) + " " +
41 + SystemClock.time.toLocaleString(Qt.locale(), Locale.ShortFormat)
42 + color: "white"
43 + font.pointSize: 11
44 + anchors.verticalCenter: parent.verticalCenter
45 + }
46 + }

skills/quickshell/examples/02-per-monitor-bar/README.md

Added
new file mode 100644
1 +# 02 — per-monitor bar
3 +The canonical multi-monitor shape: `Variants` instantiates a `Bar` per screen in `Quickshell.screens`. The bar file is auto-imported from the shell.qml directory (PascalCase neighbor).
5 +**Run:** `qs -p examples/02-per-monitor-bar/shell.qml`
7 +**What it teaches:**
9 +- `Variants { model: ...; delegate: Component { ... } }` — per-item instantiation.
10 +- `required property var modelData` in the delegate (and consuming it via `screen: modelData`).
11 +- Multi-file shells: `Bar.qml` next to `shell.qml` is implicitly imported (no `import` needed).
12 +- `SystemClock` for live time without a `Timer`.
14 +**What to break and learn from:**
16 +- Remove `required property var modelData` → qmlls error; this is intentional, the safety net.
17 +- Delete the `screen:` assignment in `Bar.qml` → every bar appears on the same monitor (the focused one).
18 +- Set `anchors.bottom: true` instead of `top` → bar moves to the bottom.
19 +- Add `color: "transparent"` + `mask: Region {}` → bar is click-through.
21 +**Splitting further:** move the clock into `Clock.qml` and the workspace into `Workspace.qml`, then `import "."` and use them by name.

skills/quickshell/examples/02-per-monitor-bar/shell.qml

Added
new file mode 100644
1 +// 02-per-monitor-bar/shell.qml
2 +// Per-monitor bar: one bar per connected screen, via Variants + Quickshell.screens.
3 +// Run with: qs -p examples/02-per-monitor-bar/shell.qml
5 +import QtQuick
6 +import Quickshell
7 +import "."
9 +// Variants creates one delegate instance per item in `model`.
10 +// `modelData` is the per-iteration value; mark it `required` so qmlls catches misses.
11 +Variants {
12 + model: Quickshell.screens
13 + delegate: Component {
14 + Bar {
15 + required property var modelData
16 + screen: modelData
17 + }
18 + }

skills/quickshell/examples/03-clock/README.md

Added
new file mode 100644
1 +# 03 — overlay clock
3 +A `FloatingWindow` promoted to layer-shell `Overlay`, with a live clock.
5 +**Run:** `qs -p examples/03-clock/shell.qml`
7 +**What it teaches:**
9 +- `FloatingWindow` with `WlrLayershell.layer: WlrLayer.Overlay` — appears above fullscreen apps.
10 +- `WlrLayershell.keyboardFocus: WlrKeyboardFocus.None` — doesn't steal keybinds.
11 +- `WlrLayershell.namespace` — group name for compositor-side stacking.
12 +- `SystemClock.time` / `.date` — reactive; no `Timer` needed.
14 +**What to break and learn from:**
16 +- Remove the `WlrLayershell.*` block → the window gets normal decorations and can be moved by the WM.
17 +- Set `keyboardFocus: WlrKeyboardFocus.Exclusive` → all keystrokes go to this window. Useful for modals, harmful for clocks.
18 +- Use a `Timer { interval: 1000; running: true; repeat: true }` instead of `SystemClock` if you need a custom format string.
19 +- For a rounded-corner window: `color: "transparent"` and put a `Rectangle { anchors.fill: parent; radius: 12; color: "#dd1e1e2e" }` inside (QML `radius` is for `Rectangle`, not `Window`).

skills/quickshell/examples/03-clock/shell.qml

Added
new file mode 100644
1 +// 03-clock/shell.qml
2 +// A floating, always-on-top clock in a FloatingWindow using WlrLayer.Overlay.
3 +// Run with: qs -p examples/03-clock/shell.qml
5 +import QtQuick
6 +import Quickshell
7 +import Quickshell.Wayland
9 +FloatingWindow {
10 + width: 380
11 + height: 90
12 + color: "#dd1e1e2e"
13 + radius: 12 // not actually rounded; see below
15 + // Place at top-center of the focused monitor.
16 + anchors {
17 + top: true
18 + horizontalCenter: true
19 + }
20 + margins.top: 60
22 + // Float over fullscreen apps.
23 + WlrLayershell.layer: WlrLayer.Overlay
24 + WlrLayershell.keyboardFocus: WlrKeyboardFocus.None
25 + WlrLayershell.namespace: "qs-example-clock"
27 + Column {
28 + anchors.centerIn: parent
29 + spacing: 4
31 + // Big time, live.
32 + Text {
33 + text: SystemClock.time.toLocaleString(Qt.locale(), "HH:mm:ss")
34 + color: "white"
35 + font.pointSize: 28
36 + font.bold: true
37 + anchors.horizontalCenter: parent.horizontalCenter
38 + }
40 + // Date below.
41 + Text {
42 + text: SystemClock.date.toLocaleDateString(Qt.locale(), Locale.LongFormat)
43 + color: "#ccd0d0d0"
44 + font.pointSize: 12
45 + anchors.horizontalCenter: parent.horizontalCenter
46 + }
47 + }

skills/quickshell/references/getting-fresh-docs.md

Added
new file mode 100644
1 +# Getting Fresh Docs
3 +Quickshell changes every release. The skills' hardcoded details will drift. **Always pull the live docs when starting a new component.** This file is the lookup procedure.
5 +## Sources of truth
7 +| What | URL |
8 +| -------------------- | ---------------------------------------------------------------------------- |
9 +| Landing | https://quickshell.org/ |
10 +| About (changelog) | https://quickshell.org/changelog/ |
11 +| Guide (current) | https://quickshell.org/docs/<version>/guide/ |
12 +| Type index (current) | https://quickshell.org/docs/<version>/types/ |
13 +| Source | https://github.com/quickshell-mirror/quickshell (or git.outfoxxed.me mirror) |
14 +| Examples | https://github.com/quickshell-mirror/quickshell-examples |
15 +| Forum | https://matrix.to/#/#quickshell:outfoxxed.me (Matrix) and bridged Discord |
16 +| Lead dev blog | https://outfoxxed.me |
18 +## Step 1. Identify the version
20 +```sh
21 +qs --version
22 +```
24 +Read the output. Example: `Quickshell 0.3.0 (revision , distributed by Arch Linux)`. The major.minor determines which doc set to read.
26 +## Step 2. Walk the guide
28 +Open (in this order):
30 +1. **Introduction** — the worked example. Walk it once. Almost everything you'll write is a generalization of that example.
31 +2. **QML Language** — if you don't already know QML. Pay attention to reactive bindings, required/default properties, and the `import qs.*` module path.
32 +3. **Item Size and Position** — the implicit-size/actual-size rule. This is the single most common source of bugs.
33 +4. **Distributing Configurations** — only if you're packaging.
34 +5. **FAQ** — covers the common "how do I…" and "something is broken" cases.
36 +## Step 3. Look up types
38 +For any type the guide names, click through to the type page. The left sidebar is the type index. **Use the sidebar, not memory** — the index changes between versions.
40 +For each type you use, capture:
42 +- Required imports
43 +- Required vs optional properties
44 +- Signals (signal name → what triggers it)
45 +- Invokable methods (for IpcHandler exposure)
46 +- Related types in the same module
48 +## Step 4. Cross-check the example repo
50 +```sh
51 +git clone https://github.com/quickshell-mirror/quickshell-examples
52 +```
54 +Look at the example closest to what you're building. Each example is a self-contained dir with a `shell.qml`, supporting `*.qml`, and a `README.md` that says how to run it.
56 +When a doc page is unclear, the example repo is usually the clearest reference.
58 +## Step 5. Cross-check community configs
60 +Real user configs (often more idiomatic than the examples for advanced patterns):
62 +- `bgibson72/yahr-quickshell` — Arch + Hyprland
63 +- `end-4/dots-hyprland` — Hyprland rice
64 +- `caelestia-dots/shell` — Caelestia
65 +- `doannc2212/quickshell-config` — minimal bar/launcher/notifications
66 +- `bjarneo/quickshell` — Omarchy-themed
67 +- `flickowoa/zephyr` — Zephyr
68 +- `outfoxxed` personal config — git.outfoxxed.me
70 +These are reference, not templates — copy patterns, not whole files. Quickshell changes between releases and most configs are pinned to a version.
72 +## Step 6. When stuck
74 +- **API question:** check the type page first; if the page is thin, file an issue on GitHub.
75 +- **"Is there a way to…"**: check the FAQ. The FAQ is being actively expanded.
76 +- **Build/runtime issue:** Matrix/Discord. The dev (outfoxxed) is active.
77 +- **"Old config doesn't work"**: it's almost always a breaking-change in the latest version. Read the changelog (https://quickshell.org/changelog/) for the version you target.
79 +## When the skill content disagrees with the docs
81 +The skill is a snapshot. The docs are the truth. If a pattern in `references/` or `examples/` no longer matches the current docs:
83 +1. Run the example against the current `qs` and see what error it gives.
84 +2. Update the example to match the current API.
85 +3. Open an issue or update the wiki raw-sources with the new doc page.
86 +4. Update the skill.
88 +## Caching tips
90 +- The doc page is ~250 KB rendered. A `web_fetch` to one page is fine; a full site mirror is overkill.
91 +- For long-running projects, `git pull` the example repo and watch the diff between releases — that's where the deprecations show up first.
92 +- Mirror: `git clone https://git.outfoxxed.me/quickshell/quickshell` is the canonical; the GitHub mirror is the same.

skills/quickshell/references/resources.md

Added
new file mode 100644
1 +# Resources
3 +Paths, icons, env vars, and persistence.
5 +## Paths
7 +| Call | Returns |
8 +| ---------------------------------- | ------------------------------------------------------- |
9 +| `Qt.resolvedUrl("foo.png")` | Absolute file URL relative to the **current QML file**. |
10 +| `Quickshell.cachePath("sub/file")` | `$XDG_CACHE_HOME/quickshell/<shell-id>/sub/file` |
11 +| `Quickshell.dataPath("sub/file")` | `$XDG_DATA_HOME/quickshell/<shell-id>/sub/file` |
12 +| `Quickshell.statePath("sub/file")` | `$XDG_STATE_HOME/quickshell/<shell-id>/sub/file` |
13 +| `Quickshell.env("VAR")` | Environment variable lookup. |
15 +Use `cachePath` for downloaded/derived files (e.g. icon cache), `dataPath` for assets that follow the shell, `statePath` for user-modifiable state (window position, last-opened menu).
17 +## Icons
19 +```qml
20 +import Quickshell.Widgets
22 +IconImage {
23 + source: Quickshell.iconPath("audio-volume-high-symbolic")
24 + implicitSize: 24
26 +```
28 +`Quickshell.iconPath` resolves against the current freedesktop icon theme.
30 +Three overloads:
32 +| Call | On miss |
33 +| ------------------------------------------------------------------- | ------------------- |
34 +| `Quickshell.iconPath(name)` | purple/black square |
35 +| `Quickshell.iconPath(name, fallback)` | fallback name |
36 +| `Quickshell.iconPath(name, { fallback: "x" })` or empty-string form | empty string |
38 +If the purple square shows up at runtime, the icon name isn't in the active theme. Use `fallback` for graceful degradation.
40 +## Environment variables
42 +```qml
43 +Quickshell.env("HOME")
44 +Quickshell.env("HYPRLAND_INSTANCE_SIGNATURE")
45 +```
47 +Quickshell's own env vars:
49 +| Var | Purpose |
50 +| -------------------------- | -------------------------------------------- |
51 +| `QS_CONFIG_PATH` | Path to config to load (equivalent to `-p`). |
52 +| `QS_APP_ID` | Override the desktop application ID. |
53 +| `QS_DISABLE_FILE_WATCHER` | Disable live-reload watching. |
54 +| `QS_DISABLE_CRASH_HANDLER` | Disable the crash reporter. |
55 +| `QS_CRASHREPORT_URL` | Override the crash report URL. |
56 +| `QS_DROP_EXPENSIVE_FONTS` | Don't load fonts that may slow first paint. |
58 +## File watching
60 +`FileView` and `JsonAdapter` watch the file they load from. Edits to the file are reflected live (and trigger a reload if the change affects QML types). For non-QML files (text, json, csv), use `FileView` directly:
62 +```qml
63 +import Quickshell.Io
65 +FileView {
66 + id: file
67 + path: Qt.resolvedUrl("data.txt")
68 + onLoaded: console.log("contents:", file.text())
70 +```
72 +## Persistence (across reloads)
74 +`PersistentProperties` keeps properties across hot-reloads:
76 +```qml
77 +import Quickshell
79 +PersistentProperties {
80 + property string lastSelection: ""
81 + property int volumeStep: 5
83 +```
85 +Declare these inside the `Scope` or `ShellRoot`. They survive both QML reloads and `qs` restarts (the data is written to disk under `statePath`).
87 +## IPC (call into quickshell from outside)
89 +```qml
90 +import Quickshell.Io
92 +IpcHandler {
93 + target: "mybar"
94 + function show(): void { visible = true }
95 + function hide(): void { visible = false }
96 + function setText(s: string): void { label.text = s }
98 +```
100 +Trigger from outside:
102 +```sh
103 +qs -c mybar ipc call mybar show
104 +qs -c mybar ipc call mybar setText "hello"
105 +```
107 +Use this for: keybind triggers (`hyprctl dispatch exec qs -c mybar ipc call mybar toggle`), CLI control, scripts, and external automation.
109 +## IPC (incoming event listener)
111 +`v0.3.0+` — register a listener for an IPC signal:
113 +```qml
114 +// in shell.qml
115 +Connections {
116 + target: IpcHandler.ipcBus
117 + function onSignal(s: string) { /* ... */ }
119 +```
121 +Use this to receive events from other quickshell instances or external programs.
123 +## Cache invalidation
125 +If you change the icons on disk but `IconImage` doesn't pick them up, check the icon theme cache (`~/.cache/icon-cache.kcache` or similar). The fix is shell-agnostic: `qt5ct` or `kbuildsycoca6` to rebuild.
127 +## System theme color
129 +```qml
130 +import QtQuick
132 +Window {
133 + color: contentItem.palette.active.window // follows system theme
134 + Text {
135 + color: contentItem.palette.active.text // follows system theme
138 +```
140 +In Quickshell, the equivalent in `PanelWindow` is:
142 +```qml
143 +PanelWindow {
144 + color: contentItem.palette.active.window
146 +```
148 +Bind `palette.active.*` for full theme integration. For dark/light override, set `Material.theme: Material.Dark` (with `import QtQuick.Controls` and the Material style attached).

skills/quickshell/references/services.md

Added
new file mode 100644
1 +# Services
3 +How to use each bundled service. Live type docs are at `https://quickshell.org/docs/v0.3.0/types/Quickshell.Services.<Name>/`. This file gives the working shape and the gotchas. Re-fetch the live docs when you write a new component — service APIs change between releases.
5 +## Pipewire (audio)
7 +`import Quickshell.Services.Pipewire`
9 +```qml
10 +PwObjectTracker { objects: [ Pipewire.defaultAudioSink ] }
12 +Text {
13 + text: `vol: ${Math.floor((Pipewire.defaultAudioSink?.audio.volume ?? 0) * 100)}%`
16 +Slider {
17 + value: Pipewire.defaultAudioSink?.audio.volume ?? 0
18 + onValueChanged: Pipewire.defaultAudioSink.audio.volume = value
20 +```
22 +- `Pipewire.defaultAudioSink` / `defaultAudioSource` are the per-user defaults.
23 +- A node's `.audio` is `PwNodeAudio` with `volume` (0.0–1.0+ — pipewire allows overdrive), `muted`, `volumeSteps` (for step controls), and `peak`/`peakHistory` (with `PwNodePeakMonitor`).
24 +- To list every app's output: `Pipewire.nodes` filtered by type, or `PwNodeLinkTracker { node: defaultSink }` then `linkTracker.linkGroups`.
25 +- `PwNodeLinkTracker` is the source/sink router view — `linkGroups[i].source`, `linkGroups[i].target`, `linkGroups[i].link`.
27 +Common gotcha: writing the new volume via `node.audio.volume = X` is fine, but if the binding `value: node.audio.volume` is also live, QML will fight you. Use a `Slider` with `onValueChanged` (assignment only) and **don't** bind `value:` to a write target. The pattern is `value: bind_readonly, onValueChanged: write`.
29 +## Mpris (media players)
31 +`import Quickshell.Services.Mpris`
33 +```qml
34 +Repeater {
35 + model: Mpris.players
36 + delegate: Item {
37 + required property var modelData // a MprisPlayer
38 + Text { text: `${modelData.trackTitle} — ${modelData.trackArtist}` }
39 + }
41 +```
43 +- `Mpris.players` is a list, automatically updated as players come and go.
44 +- `MprisPlayer`: `identity`, `desktopEntry`, `isPlaying`, `playbackState`, `position`, `length`, `volume`, `loopState`, `shuffleState`, `trackTitle`, `trackArtist`, `trackAlbum`.
45 +- Methods (call them): `next()`, `previous()`, `play()`, `pause()`, `playPause()`, `stop()`, `setPosition(microseconds)`, `setVolume(double)`.
46 +- No tracker needed — `Mpris.players` is a service-singleton property.
48 +## Notifications
50 +`import Quickshell.Services.Notifications`
52 +```qml
53 +NotificationServer {
54 + id: server
55 + // settings here
58 +ListView {
59 + model: server.trackedNotifications
60 + delegate: Item { /* render Notification */ }
62 +```
64 +- Implement a `NotificationServer` to act as a notification daemon (replaces mako/dunst).
65 +- `Notification`: `summary`, `body`, `appName`, `icon`, `urgency`, `actions` (list of `NotificationAction`), `expireTimeout`, `image`.
66 +- `server.trackedNotifications` is the active list. For popups, `server.lastNotification` is a convenience.
67 +- To replace your existing notification daemon, stop mako/dunst and start your quickshell config — quickshell will register the DBus name.
69 +## System tray
71 +`import Quickshell.Services.SystemTray`
73 +```qml
74 +SystemTray {
75 + id: tray
76 + // settings
79 +Repeater {
80 + model: tray.items
81 + delegate: TrayButton { item: modelData }
83 +```
85 +- `SystemTrayItem`: `id`, `title`, `icon`, `tooltip`, `status`, `category`, `menu` (DBusMenuHandle), `activate()` (callable), `secondaryActivate()`.
86 +- `Status` enum: `Active`, `Passive`, `NeedsAttention`. Use to dim passive items.
87 +- The `menu` is a `DBusMenuHandle` (from `Quickshell.DBusMenu`) — bind `QsMenuOpener` to it to render the native menu.
89 +## UPower (battery / power)
91 +`import Quickshell.Services.UPower`
93 +```qml
94 +UPower { id: upower }
96 +Text {
97 + text: upower.displayDevice ? `${Math.floor((upower.displayDevice?.chargePercentage ?? 0) * 100)}%` : "—"
99 +```
101 +- `UPower.displayDevice` is the system battery (laptop).
102 +- `UPowerDevice`: `chargePercentage`, `chargeState`, `state` (`Discharging|Charging|FullyCharged|...`), `timeToFull`, `timeToEmpty`, `healthPercentage`, `capacity`, `energyRate`, `voltage`.
103 +- For desktops, `displayDevice` may be null — always check.
104 +- `PowerProfiles` (separate import? — yes: `Quickshell.Services.UPower.PowerProfiles`) for performance mode switching.
106 +## Bluetooth
108 +`import Quickshell.Services.Bluetooth`
110 +```qml
111 +BluetoothAdapter {
112 + id: adapter
113 + // selected adapter, defaults to the first
115 +```
117 +- `BluetoothAdapter.devices` is the paired-device list.
118 +- `BluetoothDevice`: `deviceName`, `address`, `connected`, `paired`, `trusted`, `batteryPercentage` (optional), `iconName`, `connect()`, `disconnect()`, `pair()`, `cancelPairing()`.
119 +- For the per-device battery, the device must expose it via BlueZ. Most modern devices do; some don't.
120 +- No tracker required at the adapter level; bind to `adapter.devices` and `device.connected` directly.
122 +## Networking
124 +`import Quickshell.Networking`
126 +```qml
127 +Networking { id: net }
129 +Text {
130 + text: net.primaryWifi?.ssid ?? "—"
132 +```
134 +- `Networking.devices` includes both wifi and wired.
135 +- `WifiDevice`, `WiredDevice` are the typed children.
136 +- `WifiDevice`: `ssid`, `signalStrength`, `state`, `networks` (list of `WifiNetwork`), `scan()`.
137 +- `Network.wifiEnabled` toggles wifi.
138 +- `NetworkConnectivity`, `NetworkBackendType`, `DeviceType` enums surface what backend (NetworkManager) reports.
140 +## Greetd (display manager)
142 +`import Quickshell.Services.Greetd`
144 +```qml
145 +Greetd {
146 + onPrompt: /* request username/password from UI */
147 + onInfo: /* show info message */
148 + onError: /* show error */
150 +```
152 +- A full greeter (DM) shell. Replace your existing DM's greeter to use quickshell.
153 +- Lifecycle: `createSession(username)` → `postAuthMessageResponse(password)` → `start(cockpitCmd)`.
154 +- See the official greeter example (`Quickshell-examples`) for a working implementation.
156 +## Pam (lockscreen auth)
158 +`import Quickshell.Services.Pam`
160 +```qml
161 +PamContext {
162 + id: pam
163 + config: "login"
164 + onCompleted: (result) => { if (result == PamResult.Success) unlock() }
165 + onResponseRequired: (prompt) => { passwordField.text = prompt; pam.respond(passwordField.text) }
166 + onError: (err) => { showError(err) }
168 +```
170 +- Use with `WlSessionLock` to build a full lockscreen.
171 +- `config` is the PAM service name (e.g. `"login"`, `"sudo"`, `"polkit-1"`).
172 +- Signals: `completed(PamResult)`, `responseRequired(String)`, `error(PamError)`.
173 +- `PamResult` enum: `Success`, `Failed`, `Error`, `MaxTries`, `AuthError`, `AuthUnavailable`, `UnknownUser`, `UnknownError`, `ConversationError`, ...
175 +## Polkit
177 +`import Quickshell.Services.Polkit`
179 +```qml
180 +PolkitAgent {
181 + id: polkit
182 + onQuestion: (auth) => { /* show password UI, call auth.response(pw) */ }
184 +```
186 +- Replaces polkit-gnome / polkit-kde-agent.
187 +- `AuthFlow`: `polkit.inFlightAuthentication` is the current flow (may be null).
188 +- Always run quickshell on session start so it can register the agent.
190 +## Notification DBusMenu
192 +`import Quickshell.DBusMenu`
194 +- For system tray items with sub-menus.
195 +- `DBusMenuHandle` is the menu; iterate `handle.items` to build a QML menu manually, or use `QsMenuOpener`.
196 +- `QsMenuOpener` will pop the native compositor menu (when supported by the WM) — preferred over building your own.
198 +## WlrLayershell (layer-shell control)
200 +`import Quickshell.Wayland`
202 +```qml
203 +PanelWindow {
204 + WlrLayershell.layer: WlrLayer.Overlay
205 + WlrLayershell.keyboardFocus: WlrKeyboardFocus.None
207 +```
209 +- `WlrLayer` enum: `Background | Bottom | Top | Overlay`. `Overlay` is above fullscreen windows.
210 +- `WlrKeyboardFocus` enum: `None | Exclusive`. `Exclusive` captures all keyboard (for lockscreen).
211 +- `WlrLayershell.namespace` (string) for stacked panels.
212 +- `WlrLayershell.anchors` and `WlrLayershell.margins` are the layer-shell-native versions; `PanelWindow`'s `anchors`/`margins` map onto them.

skills/quickshell/references/windowing.md

Added
new file mode 100644
1 +# Windowing
3 +How the three window types work, how to anchor them, how to manage input.
5 +## `PanelWindow`
7 +Anchored to a screen edge (top/bottom/left/right) or a corner. Reserves space so the WM doesn't place windows under it. The default choice for bars and side panels.
9 +```qml
10 +import Quickshell
12 +PanelWindow {
13 + screen: Quickshell.screens[0] // optional; defaults to focused monitor
14 + anchors {
15 + top: true
16 + left: true
17 + right: true
18 + // bottom: true
19 + }
20 + margins { top: 5; left: 5; right: 5 }
21 + implicitHeight: 30
22 + color: "#cc1e1e2e" // opaque/translucent — drives surface format
23 + mask: Region {} // click-through (empty region)
25 +```
27 +`anchors` are booleans: which edges to stick to. `margins` is a margin in each direction (0 = flush).
29 +### Anchored but not reserving space
31 +```qml
32 +PanelWindow {
33 + anchors { top: true; left: true }
34 + exclusiveZone: -1 // sit on top of the screen, don't reserve
35 + // or 0 = reserves its actual size; >0 = reserves that many pixels (overrides size)
37 +```
39 +- `exclusiveZone: -1` — show, but don't reserve. Useful for floating-style panels.
40 +- `exclusiveZone: 0` — reserve exactly the panel's size.
41 +- `exclusiveZone: N` — reserve `N` pixels regardless of panel size (manual override).
43 +### Click-through
45 +```qml
46 +PanelWindow {
47 + color: "transparent"
48 + mask: Region {} // empty input region = click-through
50 +```
52 +This is the **only** correct way to make a panel ignore clicks. `Item.visible: false` on the contents doesn't help; the panel itself is the input surface.
54 +## `FloatingWindow`
56 +A normal desktop window. Has decorations (unless you disable them), can be moved by the user, can be focused and clicked.
58 +```qml
59 +import Quickshell
61 +FloatingWindow {
62 + width: 600
63 + height: 400
64 + color: "#222"
65 + // no `anchors` — the WM controls position
66 + // optional: visibility, focus, modality
68 +```
70 +Use for: settings dialogs, command palettes that need their own decoration, app-like windows.
72 +### Disabling decorations / setting layer
74 +```qml
75 +import Quickshell.Wayland
77 +FloatingWindow {
78 + color: "transparent"
79 + WlrLayershell.layer: WlrLayer.Overlay
80 + WlrLayershell.keyboardFocus: WlrKeyboardFocus.None
82 +```
84 +Setting a `WlrLayer` makes it act like a panel even though it's a `FloatingWindow` — useful for fullscreen overlays that should appear over fullscreen apps (think volume OSD).
86 +## `PopupWindow`
88 +Anchored to a parent window. Auto-positions above/below/side of the parent based on `anchor.rect`. The right choice for menus, tooltips, popovers.
90 +```qml
91 +import Quickshell
93 +PopupWindow {
94 + anchor {
95 + window: someBar
96 + rect: someButton.itemRect // or { x, y, width, height } of the parent rect
97 + gravity: Edges.Bottom
98 + adjustment: PopupAdjustment.None
99 + }
100 + width: 200
101 + height: 100
102 + color: "#222"
104 +```
106 +- `anchor.gravity` — which direction the popup grows from the parent rect (`Edges.Top|Bottom|Left|Right`).
107 +- `PopupAdjustment` — `Flip` (auto-flip if off-screen), `Slide` (auto-slide), `None` (clip).
108 +- The popup is `WlrLayer.Overlay` by default, so it floats over panels.
110 +## `WlSessionLock` (lockscreen)
112 +```qml
113 +import Quickshell
114 +import Quickshell.Wayland
116 +ShellRoot {
117 + LockContext { id: ctx; onUnlocked: Qt.quit() }
119 + WlSessionLock {
120 + id: lock
121 + locked: true
123 + WlSessionLockSurface {
124 + // one per monitor you want locked
125 + LockSurface { anchors.fill: parent; context: ctx }
129 +```
131 +- `WlSessionLock` requests a session lock from the compositor. The compositor hides everything (taskbar, etc.) and dims the screen.
132 +- `WlSessionLockSurface` is one surface per monitor.
133 +- Pair with `PamContext` (or whatever auth) and call `lock.locked = false; Qt.quit()` to unlock.
134 +- The compositor will not unlock for you — you must set `locked: false` and the shell must exit (or the compositor will show a fallback lock).
136 +## `WlrLayershell` (advanced layering)
138 +For windows that need explicit layer control:
140 +```qml
141 +import Quickshell.Wayland
143 +PanelWindow {
144 + WlrLayershell {
145 + layer: WlrLayer.Overlay // above all fullscreen windows
146 + namespace: "my-osd" // groups panels together for ordering
147 + exclusiveZone: 0 // no reservation
150 +```
152 +- `Background` — below everything (wallpaper).
153 +- `Bottom` — desktop icons, above background.
154 +- `Top` — panels and widgets (default).
155 +- `Overlay` — fullscreen OSDs, popups.
157 +## Multi-monitor (the standard pattern)
159 +```qml
160 +import Quickshell
162 +Variants {
163 + model: Quickshell.screens
164 + delegate: Component {
165 + PanelWindow {
166 + required property var modelData
167 + screen: modelData
168 + anchors { top: true; left: true; right: true }
169 + implicitHeight: 30
170 + // ... bar contents
174 +```
176 +`Quickshell.screens` is the list of `ShellScreen` (name, width, height, scale, model, manufacturer, ...). `modelData` is one of them. Variants re-instantiates on connect/disconnect.
178 +If you want one bar but tracking the focused monitor (e.g. a centered OSD):
180 +```qml
181 +import Quickshell.Io
183 +ShellRoot {
184 + Socket {
185 + path: `/tmp/hypr/${Quickshell.env("HYPRLAND_INSTANCE_SIGNATURE")}/.socket2.sock`
186 + connected: true
187 + parser: SplitParser {
188 + onRead: msg => {
189 + const m = /focusedmon>>(.+),/.exec(msg)
190 + if (m) myPanel.screen = Quickshell.screens.find(s => s.name == m[1])
195 + PanelWindow { id: myPanel; ... }
197 +```
199 +## Z-order
201 +Layer-shell handles it. Within a layer, the compositor stacks by `namespace` (string) and creation order. Use distinct namespaces for distinct concepts (e.g. `"bar"`, `"osd-volume"`, `"notification"`).
203 +## Common mistakes
205 +- Mixing `anchors` (boolean edges) with `width`/`height` literal → conflict. Pick one.
206 +- Setting `color: "transparent"` then also using `border` → invisible under-rect (QTBUG-137166). Use `border.width: 0` to avoid.
207 +- Forgetting `mask: Region {}` on a click-through panel → the whole panel swallows clicks.
208 +- Setting `exclusiveZone: -1` on a top bar that should reserve space → windows appear under the bar.
209 +- Per-monitor `Variants` works; the `modelData` property must be `required` or qmlls won't track it.