repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

skill: add quickshell reference

82f2dbd655809341b4990ec17eaad054888298ad

Review <review@example.invalid> ·

unsigned

Browse filesCompare with HEAD

Changed files (3)

skills/quickshell/SKILL.md

Added
new file mode 100644
1 +---
2 +name: quickshell
3 +description: Use when building Wayland desktop components with Quickshell (status bars, widgets, OSDs, lockscreens, Greetd login, Polkit agent, app launchers) on Hyprland/Sway/i3/Niri. Triggers on "quickshell", "qs shell", "qml bar", "qtquick panel", "make me a bar/widget/lockscreen with quickshell", "add a module to my quickshell config".
4 +---
6 +# Quickshell
8 +Toolkit for building desktop components in QML (QtQuick). Not a WM, not a DE — runs alongside your compositor and owns a few Wayland surfaces (panels, popups, OSDs, lockscreens, etc.). Hot-reloads on save.
10 +## Mental model
12 +```
13 +Quickshell process
14 +└── ShellRoot (or Scope)
15 + ├── Variants { model: Quickshell.screens; delegate: Component { PanelWindow {...} } }
16 + ├── FloatingWindow {...}
17 + ├── PopupWindow {...}
18 + └── Connections { target: SomeService; function onXxx() {...} }
19 +```
21 +- A **shell** is a `shell.qml` file inside a named config dir.
22 +- The **root** is `ShellRoot` (passive container) or `Scope` (container with shared state + services).
23 +- **Windows** are children of the root. Three kinds: `PanelWindow` (anchored to screen edge/corner, reserves space), `FloatingWindow` (free desktop window), `PopupWindow` (auto-positioned over a parent).
24 +- **Variants** instantiates a component per item in a model — the canonical pattern for one-bar-per-monitor.
25 +- **Reactive bindings** do the work. You don't write update logic; you write expressions whose dependencies re-evaluate.
27 +## File layout (user config)
29 +```
30 +$XDG_CONFIG_HOME/quickshell/<name>/ # usually ~/.config/quickshell/<name>/
31 +├── shell.qml # entry point; root must be ShellRoot or Scope
32 +├── .qmlls.ini # touch to enable LSP; managed by quickshell (gitignore)
33 +├── Bar.qml # implicitly importable from shell.qml (PascalCase)
34 +├── widgets/
35 +│ ├── Clock.qml # import via qs.widgets.Clock (qs.*, since v0.2.0)
36 +│ └── Volume.qml
37 +└── ...
38 +```
40 +- Multiple named configs live side by side; pick with `qs -c <name>`.
41 +- `qs -p /path/to/shell.qml` runs an arbitrary file.
42 +- A `shell.qml` directly inside `~/.config/quickshell/` shadows all named configs.
44 +## Minimal bar (one focused monitor)
46 +```qml
47 +import QtQuick
48 +import Quickshell
50 +PanelWindow {
51 + anchors { top: true; left: true; right: true }
52 + implicitHeight: 30
53 + Text { anchors.centerIn: parent; text: "hello" }
55 +```
57 +## Per-monitor bar (the canonical shape)
59 +```qml
60 +import QtQuick
61 +import Quickshell
63 +Variants {
64 + model: Quickshell.screens
65 + delegate: Component {
66 + PanelWindow {
67 + required property var modelData
68 + screen: modelData
69 + anchors { top: true; left: true; right: true }
70 + implicitHeight: 30
71 + Text { anchors.centerIn: parent; text: "bar" }
72 + }
73 + }
75 +```
77 +`Quickshell.screens` is the monitor list; each element is a `ShellScreen` with `name`, `width`, `height`, `scale`.
79 +## Sizing (the rule that breaks everyone once)
81 +> **Implicit size flows child → parent. Actual size flows parent → child.**
83 +- Children set `implicitWidth`/`implicitHeight` (what they want).
84 +- Containers/`PanelWindow` set `width`/`height` (what they get).
85 +- `childrenRect` is the wrong tool for containers (creates binding loop). Use anchors or `MarginWrapperManager`/`WrapperItem`.
86 +- An `Item` with no implicit size is 0×0 — invisible. Quickshell warns about this on first show.
88 +## Reactive bindings
90 +```qml
91 +Item {
92 + property int count: 0
93 + Timer { running: true; interval: 1000; repeat: true; onTriggered: count++ }
94 + width: 100 + count // re-evaluates every time count changes
96 +```
98 +`property <type> <name>: <expr>` declares a reactive property. Any binding to it (including inside other components) re-runs when dependencies change.
100 +## Imports
102 +```qml
103 +import QtQuick // Rectangle, Text, Item, Timer, etc.
104 +import QtQuick.Layouts // RowLayout, ColumnLayout, GridLayout
105 +import QtQuick.Controls // Button, Slider, Label (Material/Universal styling)
106 +import Quickshell // PanelWindow, FloatingWindow, PopupWindow, Scope, ShellRoot, Quickshell.* helpers
107 +import Quickshell.Io // Process, StdioCollector, SplitParser, Socket, FileView, IpcHandler
108 +import Quickshell.Wayland // Toplevel, ToplevelManager, WlSessionLock, WlrLayershell
109 +import Quickshell.Services.Pipewire // Pipewire, PwObjectTracker, PwNode, PwNodeLinkTracker
110 +import Quickshell.Services.Mpris // Mpris (media player)
111 +import Quickshell.Services.Notifications
112 +import Quickshell.Services.SystemTray
113 +import Quickshell.Services.UPower // battery
114 +import Quickshell.Services.Bluetooth
115 +import Quickshell.Services.Polkit
116 +import Quickshell.Widgets // IconImage, WrapperRectangle, MarginWrapperManager, ClippingWrapperRectangle
117 +import qs.widgets as W // your own modules, v0.2.0+; LSP-friendly
118 +import qs // the shell root dir
119 +```
121 +Neighbor `.qml` files starting with **uppercase** are implicitly importable from `shell.qml`. Use `qs.*` for subfolders — much better LSP coverage than relative path imports.
123 +## Running things
125 +```qml
126 +// One-shot command, capture all stdout as a string
127 +Process {
128 + command: ["date"]
129 + running: true
130 + stdout: StdioCollector { onStreamFinished: someText.text = this.text }
133 +// Long-running stream, line by line
134 +Process {
135 + command: ["some-listener"]
136 + running: true
137 + stdout: SplitParser {
138 + onRead: line => console.log("got:", line)
141 +```
143 +`StdioCollector` accumulates then fires `streamFinished`. `SplitParser` fires `onRead` per line. **One process, many widgets** — don't spawn one `Process` per widget (FAQ).
145 +## Binding to a service's state
147 +Most Quickshell services expose singletons with reactive state. To read a property, you must keep the service "looking" at the object or the binding dies:
149 +```qml
150 +import Quickshell.Services.Pipewire
152 +// Force Pipewire to keep tracking the default sink
153 +PwObjectTracker { objects: [ Pipewire.defaultAudioSink ] }
154 +Text { text: `vol: ${(Pipewire.defaultAudioSink?.audio.volume ?? 0) * 100 | 0}%` }
155 +```
157 +Same pattern for `Mpris.players`, `UPower.devices`, `Bluetooth.adapters`, etc. The tracker + `?.` optional chain is idiomatic.
159 +## Signals
161 +```qml
162 +// Property change handler (auto-generated signal)
163 +onVolumeChanged: console.log("vol =", volume)
165 +// Named signal
166 +signal clicked()
167 +onClicked: doThing()
169 +// Connections to a target's signals
170 +Connections {
171 + target: Pipewire.defaultAudioSink?.audio
172 + function onVolumeChanged() { ... }
175 +// One-shot at creation
176 +Component.onCompleted: console.log("ready")
177 +```
179 +## Conditional UI (memory-aware)
181 +```qml
182 +// Cheap, always in memory; just hides
183 +Item { visible: shouldShow; ... }
185 +// Frees memory when not active (rebuilds on toggle)
186 +LazyLoader { active: shouldShow; PanelWindow { ... } }
187 +```
189 +`LazyLoader` for non-Item roots (`PanelWindow` etc.); `Loader` for `Item`-derived trees. The `visible` toggle is fine for always-shown panels; `LazyLoader` is the answer for OSDs/drawers that appear and disappear.
191 +## Click-through
193 +```qml
194 +PanelWindow {
195 + color: "transparent"
196 + mask: Region {} // empty click region — clicks pass through
198 +```
200 +`Region` is the only correct way to make a window ignore input while still rendering. Use it for OSDs and decorative overlays.
202 +## Icons
204 +```qml
205 +import Quickshell.Widgets
206 +IconImage { source: Quickshell.iconPath("audio-volume-high-symbolic") }
207 +```
209 +`Quickshell.iconPath(name)` resolves a system icon theme name. Three overloads: missing icon → purple/black square, fallback, or empty string. Use the fallback/empty overload if the square bothers you.
211 +## Files / paths
213 +- `Qt.resolvedUrl("foo.png")` → path relative to the current QML file.
214 +- `Quickshell.cachePath("x")` / `.dataPath("x")` / `.statePath("x")` → XDG cache/data/state for this shell.
215 +- `Quickshell.env("VAR")` → env var lookup.
217 +## LSP
219 +```sh
220 +touch ~/.config/quickshell/<name>/.qmlls.ini
221 +```
223 +Quickshell will overwrite it with a managed config (gitignore it). qmlls gives completions for Quickshell types. **Without `.qmlls.ini`, all Quickshell symbols are unresolved in your editor.**
225 +## Versioning
227 +API breaks between minor versions. Use `Quickshell.hasVersion("0.3.0")` and the preprocessor (`pragma …`) to version-gate. Pin your distro's quickshell package; track master only if you want to live on the edge.
229 +## Cross-references
231 +- `references/types.md` — quick lookup table of every Quickshell type
232 +- `references/patterns.md` — reusable recipes (timers, process I/O, signals, monitor-per-instance, conditional load)
233 +- `references/services.md` — pipewire, mpris, notifications, system tray, upower, bluetooth, greetd, polkit
234 +- `references/windowing.md` — PanelWindow / FloatingWindow / PopupWindow / WlSessionLock
235 +- `references/resources.md` — icons, paths, env, system paths
236 +- `references/getting-fresh-docs.md` — how to read the current docs (don't memorize; look up)
237 +- `examples/` — minimal, runnable prototypes; copy/adapt
239 +## When NOT to use
241 +- You want a preconfigured desktop → use [Caelestia](https://github.com/caelestia-dots/shell) or [Illogical-Impulse](https://github.com/end-4/dots-hyprland) instead.
242 +- You want a one-line status bar → use Waybar. Quickshell is programming, not config.
243 +- You target Windows/macOS → Quickshell is Linux/BSD only.
244 +- You're on X11 with no wlroots compat → Hyprland/Sway/i3/Niri are the supported targets; X11 is best-effort.

skills/quickshell/references/patterns.md

Added
new file mode 100644
1 +# Patterns
3 +Reusable recipes. Each pattern solves a recurring shape of problem. Combine them.
5 +## P1. Per-monitor instantiation
7 +```qml
8 +import Quickshell
10 +Variants {
11 + model: Quickshell.screens
12 + delegate: Component {
13 + PanelWindow {
14 + required property var modelData
15 + screen: modelData
16 + // ... rest of bar
17 + }
18 + }
20 +```
22 +`modelData` is the per-iteration value. Always mark it `required` so qmlls catches missing bindings. `Quickshell.screens` is a `list<ShellScreen>` — each has `name`, `width`, `height`, `scale`. Variants survives monitor hot-plug: when a screen disconnects, its instance is destroyed; when it reconnects, a fresh one is created.
24 +## P2. Live-updating clock
26 +```qml
27 +Text {
28 + text: SystemClock.date
29 + // or: text: SystemClock formatted as you like
31 +```
33 +`SystemClock` exposes `date`, `time`, and locale-aware formatters. It updates reactively; no `Timer` needed. For fully custom formatting, bind a `Timer { interval: 1000; repeat: true; running: true }` and recompute.
35 +## P3. Run a shell command, capture output
37 +```qml
38 +import Quickshell.Io
40 +Process {
41 + id: proc
42 + command: ["wpctl", "get-volume", "@DEFAULT_AUDIO_SINK@"]
43 + running: true
44 + stdout: StdioCollector {
45 + onStreamFinished: lastOutput.text = this.text
46 + }
48 +```
50 +`StdioCollector` is a `Property`-like that becomes the full output string after the process closes stdout. **One process, many widgets** — don't spawn per widget (memory + startup cost).
52 +## P4. Long-running stream, regex match per line
54 +```qml
55 +import Quickshell.Io
57 +Process {
58 + command: ["some-streaming-tool"]
59 + running: true
60 + stdout: SplitParser {
61 + property var pattern: /focusedmon>>(.+),/
62 + onRead: msg => {
63 + const m = pattern.exec(msg)
64 + if (m) doStuff(m[1])
65 + }
66 + }
68 +```
70 +`SplitParser` splits on newlines by default; you can override with `split`. Each line fires `onRead(line)`. Use this for any event-stream consumer (Hyprland socket, log tailer, status feed).
72 +## P5. Bind a service object's state
74 +```qml
75 +import Quickshell.Services.Pipewire
77 +PwObjectTracker { objects: [ Pipewire.defaultAudioSink ] }
79 +Text {
80 + text: `vol: ${(Pipewire.defaultAudioSink?.audio.volume ?? 0) * 100 | 0}%`
82 +```
84 +`PwObjectTracker` is a sentinel — it does nothing visible, but its presence keeps the object alive in the service's internal model. Without it, the binding can drop to `null`. Pattern: every time you read a non-singleton service object, declare a tracker for it. Same for `Mpris.players`, `UPower.devices`, `Bluetooth.adapters`.
86 +The `?.` optional chain is the safe way to read state that might not be present yet (e.g. before the service has connected).
88 +## P6. React to a service signal
90 +```qml
91 +import Quickshell.Services.Pipewire
93 +Connections {
94 + target: Pipewire.defaultAudioSink?.audio
95 + function onVolumeChanged() { flashOsd() }
97 +```
99 +`Connections` is the idiomatic way to listen to a target's signals. The `target` must be live — wrap with `?.` and use the `target:` binding (not a static `target:` assignment) to make it reactive. The handler name follows `on<SignalName>` convention.
101 +## P7. Show a window only when a condition holds
103 +```qml
104 +// Cheap: always in memory, just hides
105 +Item { visible: showIt }
107 +// Frees memory: builds only when active
108 +LazyLoader { active: showIt; PanelWindow { ... } }
109 +```
111 +Use `LazyLoader` for windows and other non-`Item` roots. The OSD-on-volume-change pattern is exactly this:
113 +```qml
114 +LazyLoader {
115 + active: showOsd
116 + PanelWindow { /* the OSD UI */ }
118 +```
120 +The window is destroyed when `active` flips to false. Good for rare/expensive UI.
122 +## P8. Click-through overlay
124 +```qml
125 +PanelWindow {
126 + color: "transparent"
127 + mask: Region {} // empty = no input
129 +```
131 +The `Region` input mask is the only correct way to make a panel ignore clicks while still rendering. For a window that should be opaque to clicks, leave `mask` unset.
133 +## P9. System icon
135 +```qml
136 +import Quickshell.Widgets
138 +IconImage {
139 + source: Quickshell.iconPath("audio-volume-high-symbolic")
140 + implicitSize: 24
142 +```
144 +`Quickshell.iconPath` looks up the name in the current icon theme. Three variants: missing icon → purple/black square (default), fallback to a name, or empty string. If the purple square bugs you, use the empty-string overload and `source !== ""` to gate the `IconImage`.
146 +## P10. Custom file-bound properties (config-as-code)
148 +```qml
149 +import Quickshell.Io
151 +JsonAdapter {
152 + id: config
153 + path: Qt.resolvedUrl("config.json")
154 + // adapter is auto-generated; properties become QML properties
156 +```
158 +`JsonAdapter` reads a JSON file at startup and exposes its top-level keys as reactive QML properties. Edits to the file are picked up on next reload. Use this for user-tweakable config (theme, layout offsets, monitor list).
160 +## P11. Multi-file shell
162 +```
163 +~/.config/quickshell/mybar/
164 +├── shell.qml # entry, contains the Variants
165 +├── Bar.qml # the bar component (implicit import)
166 +├── Clock.qml # implicit import
167 +└── widgets/
168 + └── Volume.qml # import via: import qs.widgets as W
169 +```
171 +Inside `shell.qml`:
173 +```qml
174 +import qs.widgets as W
175 +import "."
177 +// or use the implicit Bar / Clock from this directory
178 +Variants {
179 + model: Quickshell.screens
180 + delegate: Bar { screen: modelData }
182 +```
184 +Rules:
186 +- `*.qml` next to `shell.qml` with PascalCase name → implicitly importable.
187 +- `widgets/*.qml` etc. → import with `import qs.widgets as W` (LSP-friendly, v0.2.0+).
188 +- `import "relative/path"` works but loses LSP coverage; prefer `qs.*`.
190 +## P12. Version-gate a feature
192 +```qml
193 +import Quickshell
194 +pragma ComponentBehavior: bound
196 +Loader {
197 + active: Quickshell.hasVersion("0.3.0")
198 + sourceComponent: someNewFeature
200 +```
202 +`Quickshell.hasVersion` is the API; the `#pragma`-style preprocessor (different syntax) lets you gate by version at parse time. Use these when you want the same shell.qml to work across quickshell releases.
204 +## P13. Reuse state across components
206 +Put the state in the `Scope` root:
208 +```qml
209 +Scope {
210 + id: root
211 + property string currentWallpaper: "/path/to/wp"
212 + property int volumeStep: 5
214 + Variants { model: Quickshell.screens; delegate: Component { Bar { ... } } }
215 + LazyLoader { active: showMixer; Mixer { ... } }
217 +```
219 +Components declared inside `Scope` can reach `root.foo` by id. If you find yourself passing the same property into 4+ components, hoist it to `Scope`.
221 +## P14. Custom re-usable component file
223 +```qml
224 +// MyButton.qml (PascalCase, placed in same dir as shell.qml or imported via qs.*)
225 +import QtQuick
226 +import QtQuick.Controls
228 +Button {
229 + property string iconName: ""
230 + property var onActivate: () => {}
231 + icon.name: iconName
232 + onClicked: onActivate()
234 +```
236 +Consume from `shell.qml` (auto-imported) or `import qs.widgets as W; W.MyButton { ... }`. Components are just `Item`-like root objects — anything that's a QML object can be a component.
238 +## P15. Hide the reload popup
240 +If you have your own reloader indicator, you can disable the built-in one (v0.3.0+):
242 +```qml
243 +import Quickshell
244 +ShellRoot {
245 + // The default reload popup is added automatically.
246 + // To replace it, add a ReloadPopup from your own module path.
247 + // (See official examples/reload-popup.)
249 +```
251 +The default reload popup shows on every file save. For noisier iteration, replace it with a smaller indicator or disable via `QuickshellSettings`.
253 +## P16. Process IPC (call into quickshell from outside)
255 +```qml
256 +import Quickshell.Io
258 +IpcHandler {
259 + target: "myShell" // becomes the IPC namespace
260 + function toggleBar(): void {
261 + showBar = !showBar
264 +```
266 +Call it from the shell:
268 +```sh
269 +qs -c mybar ipc call myShell toggleBar
270 +```
272 +Use this for keybind triggers, scripts, and external automation.

skills/quickshell/references/types.md

Added
new file mode 100644
1 +# Quickshell Types — Quick Reference
3 +The complete live index lives at **https://quickshell.org/docs/v0.3.0/types/**. This file is a curated shortlist of what you'll actually reach for. The doc index above is the source of truth — re-fetch when starting a new component; type names and modules shift between minor versions.
5 +## Core (root containers)
7 +| Type | Purpose |
8 +| ----------- | ----------------------------------------------------------------------------------------------------------------------- |
9 +| `ShellRoot` | Top-level container. Use when your shell is just a bag of windows. No shared state. |
10 +| `Scope` | Top-level container with shared state. Use when you have services, signals, or properties that several components need. |
12 +## Windows
14 +| Type | Use for |
15 +| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
16 +| `PanelWindow` | Bars, sidebars, drawers, status strips. Reserves space on the screen. Anchored. |
17 +| `FloatingWindow` | Free desktop windows (settings dialogs, popovers that need their own decorations). |
18 +| `PopupWindow` | Anchored to a parent window with `anchor.window`; auto-positions above/below/side. Good for menus and tooltips. |
19 +| `FloatingWindow` (with `WlrLayershell.layer: WlrLayer.Overlay`) | Fullscreen overlays (like the "Activate Linux" notification). |
21 +All windows share `QsWindow` base: `screen`, `anchors`, `mask`, `color`, `surfaceFormat`, `WlrLayershell.*` (when on wlroots).
23 +## Lifecycle & layout
25 +| Type | Purpose |
26 +| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
27 +| `Variants` | Instantiate a component per item in a model. The standard for per-monitor. |
28 +| `Loader` / `LazyLoader` | Conditionally build a tree. `Loader` for `Item`-derived; `LazyLoader` for non-`Item` (windows). |
29 +| `MarginWrapperManager`, `WrapperItem`, `WrapperRectangle` | Auto-margin containers — no `childrenRect` loops. |
30 +| `ClippingRectangle`, `ClippingWrapperRectangle` | Rounded-image / rounded-content helpers. |
31 +| `IconImage` | System-icon-theme aware `Image`. Use `Quickshell.iconPath()` for the source. |
33 +## Io
35 +| Type | Purpose |
36 +| -------------------------------- | -------------------------------------------------------------------------------------- |
37 +| `Process` | Run an external program. Streams stdio. |
38 +| `StdioCollector` | Read a process's full stdout as a string on completion. |
39 +| `SplitParser` | Stream stdout line-by-line (regex-friendly). |
40 +| `Socket` | Connect to a Unix/named socket. |
41 +| `SocketServer` | Listen on a socket. |
42 +| `FileView` | Reactive file reader (watches + reads). |
43 +| `JsonAdapter`, `JsonObject` | Bind a JSON file to QML properties. |
44 +| `IpcHandler` | Expose a callable function over Quickshell's IPC. `qs -c name ipc call …` triggers it. |
45 +| `DataStream`, `DataStreamParser` | Generic stream + parser. |
47 +## Services
49 +| Module | Singletons / types |
50 +| ----------------------------------- | ---------------------------------------------------------------------------------------------------------- |
51 +| `Quickshell.Services.Pipewire` | `Pipewire`, `PwObjectTracker`, `PwNodeLinkTracker`, `PwNode`, `PwLink`, `PwNodeAudio`, `PwNodePeakMonitor` |
52 +| `Quickshell.Services.Mpris` | `Mpris.players`, `MprisPlayer` |
53 +| `Quickshell.Services.Notifications` | `NotificationServer`, `Notification` |
54 +| `Quickshell.Services.SystemTray` | `SystemTray.items`, `SystemTrayItem` |
55 +| `Quickshell.Services.UPower` | `UPower`, `UPowerDevice`, `PowerProfiles` |
56 +| `Quickshell.Services.Bluetooth` | `Bluetooth`, `BluetoothAdapter`, `BluetoothDevice` |
57 +| `Quickshell.Networking` | `Networking`, `WifiDevice`, `WiredDevice` (NM-backed) |
58 +| `Quickshell.Services.Polkit` | `PolkitAgent`, `AuthFlow` |
59 +| `Quickshell.Services.Pam` | `PamContext` (lockscreen) |
60 +| `Quickshell.Services.Greetd` | `Greetd` (display manager) |
62 +## Wayland
64 +| Type | Use for |
65 +| ---------------------------------------- | ---------------------------------------------------- |
66 +| `Toplevel` / `ToplevelManager` | Track open windows. |
67 +| `WlSessionLock` / `WlSessionLockSurface` | Lockscreen. |
68 +| `BackgroundEffect` | Per-window blur / shader effect. |
69 +| `WlrLayershell` / `WlrLayer` | Layer-shell control (Background/Bottom/Top/Overlay). |
70 +| `IdleInhibitor` | Prevent compositor idle. |
71 +| `IdleMonitor` | React to user-idle / resume. |
72 +| `ShortcutInhibitor` | Block compositor keybinds while a window is focused. |
73 +| `ScreencopyView` | Capture a Wayland surface. |
74 +| `WlrKeyboardFocus` | Per-window keyboard focus (rare; advanced). |
76 +## WindowManager (workspaces)
78 +| Type | Use for |
79 +| ------------------------------------------ | ----------------------------------------------------------------------------- |
80 +| `WindowManager` | Workspaces: `workspaces`, `focusedWorkspace`, `toplevels`, `focusedToplevel`. |
81 +| `Windowset` | Active windowset (e.g. focused + immediate stack). |
82 +| `ScreenProjection` / `WindowsetProjection` | Map windows to screen-relative coords. |
84 +The `WindowManager` is the generic interface; prefer WM-specific modules (`Quickshell.Hyprland`, `Quickshell.I3`) for richer per-WM data.
86 +## WM-specific
88 +| Module | Highlights |
89 +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
90 +| `Quickshell.Hyprland` | `Hyprland.workspaces`, `Hyprland.focusedWorkspace`, `HyprlandToplevel`, `GlobalShortcut`, `HyprlandFocusGrab`, `HyprlandMonitor`. Lua-config supported. |
91 +| `Quickshell.I3` | `I3.workspaces`, `I3IpcListener`, `I3Monitor`. |
93 +## Misc
95 +| Type | Purpose |
96 +| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
97 +| `Singleton` | Make a QML type a single shared instance. |
98 +| `Reloadable` | Force a re-instantiation of a subtree on config reload. |
99 +| `Retainable` / `RetainableLock` | Manually manage object lifetime across reloads. |
100 +| `PersistentProperties` | Properties that survive reload. |
101 +| `SystemClock` | Reactive `date`/`time` strings. |
102 +| `ElapsedTimer` | Reactive timer with elapsed time. |
103 +| `EasingCurve` | Built-in easings. |
104 +| `ObjectModel` / `ScriptModel` | Reactive list models from QML/JS. |
105 +| `BoundComponent` | Bind a component to data with type-safe properties. |
106 +| `Region` | Input mask for windows. `Region {}` → click-through. |
107 +| `ExclusionMode` | Window exclusion mode (Auto/Ignore/Normal). |
108 +| `Edges` | Edge enum (Top/Right/Bottom/Left). |
109 +| `DesktopEntry` / `DesktopEntries` | Read `.desktop` files. |
110 +| `DesktopAction` | Reactive handle to a desktop action. |
111 +| `Quickshell` (singleton) | `Quickshell.screens`, `Quickshell.env()`, `Quickshell.iconPath()`, `Quickshell.hasVersion()`, `Quickshell.cachePath()`, `Quickshell.dataPath()`, `Quickshell.statePath()`. |
112 +| `ColorQuantizer` | Region color quantizer (screencopy-derived). |
114 +## "What's the URL again?"
116 +The official type index is at `https://quickshell.org/docs/v0.3.0/types/Quickshell/<TypeName>`. Use the left-sidebar type index to navigate. Sidebar contents change each release — re-map mentally, don't memorize paths.