repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

skill(qml,quickshell): strip quickshell from qml + license + source citations

5726553f4ebc1651f237eb95584a25448310bd3e

Review <review@example.invalid> ·

unsigned

Browse filesCompare with HEAD

Changed files (8)

skills/qml/README.md

Modified
1 1 # qml
3 -QML (Qt Modeling Language) — the declarative UI language for QtQuick. Pure QML: no Quickshell, no Qt-specific compositor types, no platform bindings beyond the standard library.
3 +QML (Qt Modeling Language) — the declarative UI language for QtQuick. Pure language: no compositor, windowing protocol, or desktop-integration types. Runs on any platform with Qt.
5 5 ## Layout
36 36 qmllint examples/01-hello/hello.qml
39 -This skill is **QtQuick/QML only**. For Quickshell-specific desktop components, see the `quickshell` skill.
39 +This skill is the pure QML language only.
41 41 ## Validation
43 43 - All 7 examples parse clean with `qmllint` (Qt 6 linter).
44 44 - All 7 examples run with `qml6` (QML runtime) — open a window, interactive.
45 -- No Quickshell imports in any example. Pure QML.
45 +- No compositor or platform-specific imports in any example. Pure standard-library QML.
47 47 To extend validation on your own machine: add a new QML file, drop it under `examples/`, and run `qmllint <file> && qml6 <file>` to verify it parses and runs.
56 56 ## See also
58 -- **`quickshell` skill** — Quickshell uses QML for configuration. For Quickshell-specific types (`PanelWindow`, `Quickshell.Io`, `Quickshell.Services.*`, `Scope`, `Variants`, `LazyLoader`, etc.), see the `quickshell` skill. The `qml` skill is referenced by the `quickshell` skill but contains zero Quickshell knowledge.
59 58 - Qt documentation: <https://doc.qt.io/qt-6/qml-tutorial.html>, <https://doc.qt.io/qt-6/qtqml-index.html>

skills/qml/SKILL.md

Modified
2 2 name: qml
3 -description: Use when writing or editing QML/QtQuick code — property bindings, components, signals, models, anchors, layouts, JavaScript integration. Triggers on "qml", "qtquick", "qt qml", "qml binding", "qml signal", "qml component", "qml layout", "qt property binding". Does NOT cover Quickshell-specific types (see the quickshell skill for that).
3 +description: Use when writing or editing QML/QtQuick code — property bindings, components, signals, models, anchors, layouts, JavaScript integration. Triggers on "qml", "qtquick", "qt qml", "qml binding", "qml signal", "qml component", "qml layout", "qt property binding", "qtquick bar", "qt panel". The pure language only — no compositor or desktop-integration types.
6 6 # QML
8 8 QML (Qt Modeling Language) is the declarative UI language for QtQuick. You build a tree of objects; properties propagate reactively. The language is small — the depth is in the standard library (`QtQuick`, `QtQuick.Controls`, `QtQuick.Layouts`, `QtQuick.Window`, …).
10 -This skill is **pure QML** — no Quickshell, no Qt-specific compositor types. For Quickshell desktop shells, layer-shell, or Wayland IPC, see the `quickshell` skill.
10 +This skill covers the pure QML language. It contains zero knowledge of any specific compositor, windowing protocol, or desktop-integration toolkit. For related skills, see the cross-reference list at the end of this file.
12 12 ## Mental model
253 253 - `references/signals.md` — signal declaration, handlers, Connections
254 254 - `references/javascript.md` — JS in QML, function calls, lambdas
255 255 - `references/common-pitfalls.md` — `childrenRect` loops, zero-size Items, binding fights
256 -- `examples/` — 7 minimal, runnable QML prototypes (no Quickshell, no Qt-specific compositor types)
256 +- `examples/` — 7 minimal, runnable QML prototypes (pure standard-library QML)
258 258 ## See also
260 -- **`quickshell` skill** — for using QML inside a Quickshell shell, layer-shell panels, IPC, and the Quickshell-specific types.
261 260 - Qt docs: <https://doc.qt.io/qt-6/qml-tutorial.html>, <https://doc.qt.io/qt-6/qtqml-index.html>

skills/qml/examples/01-hello/hello.qml

Modified
1 1 // 01-hello/hello.qml
2 2 // Smallest interactive QML: a rectangle that changes color on click.
3 -// Pure QML — no Quickshell, no Qt-specific compositor. Runs with: qml6 hello.qml
3 +// Pure standard-library QML — no compositor, no platform bindings. Run with: qml6 hello.qml
5 5 import QtQuick
6 6 import QtQuick.Window

skills/qml/references/common-pitfalls.md

Modified
33 -Or use a `Column`/`Row` for stacking, or `MarginWrapperManager` (Quickshell extension) for auto-margin.
33 +Or use a `Column`/`Row` for stacking, or `MarginWrapperManager` (a QtQuick extension from a downstream toolkit) for auto-margin.
35 35 ## 2. Zero-size items
289 289 ## 18. QML reloading state
291 -When you save a `.qml` file, QML hot-reloads. Some state is lost (component instances), some is preserved (`PersistentProperties` in Quickshell; `Settings` in Qt.labs.settings). Plan for state loss during development.
291 +When you save a `.qml` file, QML hot-reloads. Some state is lost (component instances), some is preserved (`Settings` in `Qt.labs.settings`; some toolkits provide their own persistence like `PersistentProperties`). Plan for state loss during development.
293 293 ## Quick debugging
296 296 - Use `Component.onCompleted: console.log(JSON.stringify(props))` to dump an object.
297 297 - Set `visible: true` on hidden components to see them.
298 298 - Use `Qt.application.debugging` or attach `qml --inspect` to debug interactively.
299 -- Check the runtime log (`log.log` in Quickshell; Qt prints to stderr) for binding loop warnings.
299 +- Check the runtime log (Qt prints binding-loop warnings to stderr; specific toolkits may have their own log files) for binding loop warnings.
301 301 ## See also

skills/qml/references/layouts.md

Modified
132 -Or use `MarginWrapperManager` (Quickshell extension) or `Column`/`Row` for auto-stacking.
132 +Or use `MarginWrapperManager` (a QtQuick extension from a downstream toolkit) or `Column`/`Row` for auto-stacking.
134 134 ## StackLayout
170 170 ## What to choose
172 -| Use case | Pick |
173 -| ----------------------------------- | --------------------------------------------------------------------- |
174 -| Single rectangle pinned to a corner | `anchors` |
175 -| 3 buttons in a row | `RowLayout` |
176 -| Form with labels + fields | `GridLayout { columns: 2 }` |
177 -| Tabbed views | `StackLayout` + `TabBar` |
178 -| Scrollable list | `ListView` (not a Layout) |
179 -| Auto-margin (no binding loops) | `MarginWrapperManager` (Quickshell extension, see `quickshell` skill) |
172 +| Use case | Pick |
173 +| ----------------------------------- | ---------------------------------------------------------------------- |
174 +| Single rectangle pinned to a corner | `anchors` |
175 +| 3 buttons in a row | `RowLayout` |
176 +| Form with labels + fields | `GridLayout { columns: 2 }` |
177 +| Tabbed views | `StackLayout` + `TabBar` |
178 +| Scrollable list | `ListView` (not a Layout) |
179 +| Auto-margin (no binding loops) | `MarginWrapperManager` (a QtQuick extension from a downstream toolkit) |

skills/quickshell/SKILL.md

Modified
2 2 name: quickshell
3 -description: Use when building Wayland desktop components in QML with the Quickshell toolkit — status bars, widgets, OSDs, lockscreens, Greetd greeter, Polkit agent, system tray, app launchers, notification daemons. Runs on Hyprland/Sway/i3/Niri (wlroots-based compositors) and X11 best-effort. Triggers on "quickshell", "qs shell", "quickshell config", "qs ipc", "qtquick bar", "qt panel", "build me a bar with quickshell", "make a quickshell widget", "add a module to my quickshell config". NOT for: configuring Hyprland itself (see `hypr` skill), configuring Niri (see `niri` skill), Ironbar configs (see `ironbar` skill), or general QML language questions (see `qml` skill).
3 +license: LGPL-3.0
4 +description: Use when building Wayland desktop components in QML with the Quickshell toolkit — status bars, widgets, OSDs, lockscreens, Greetd greeter, Polkit agent, system tray, app launchers, notification daemons. Runs on Hyprland/Sway/i3/Niri (wlroots-based compositors) and X11 best-effort. Triggers on "quickshell", "qs shell", "quickshell config", "qs ipc", "build me a bar with quickshell", "make a quickshell widget", "add a module to my quickshell config". This skill is not for configuring Hyprland itself (see `hypr` skill), Niri (see `niri` skill), Ironbar configs (see `ironbar` skill), or general QML language questions (see `qml` skill).
6 7 # Quickshell

skills/quickshell/examples/README.md

Modified
4 4 # quickshell examples
6 6 Each example in this directory is a **minimal, runnable** Quickshell shell. They were derived from the patterns documented in the [official Quickshell examples repo](https://git.outfoxxed.me/quickshell/quickshell-examples) and the [official Quickshell docs](https://quickshell.org/docs/v0.3.0/). They are written from scratch, not copies.
8 8 ## Examples
10 -| # | Name | What it shows | Source / inspiration | License |
11 -| - | ---- | ------------- | -------------------- | ------- |
12 -| 01 | `01-hello-bar/` | Smallest valid `PanelWindow` | Hand-written; the canonical "hello world" shape from `quickshell.org/docs/v0.3.0/guide/introduction/` | Same as the quickshell project: LGPL-3.0 (runtime) |
13 -| 02 | `02-per-monitor-bar/` | `Variants` + per-monitor, multi-file shell | `quickshell.org/docs/v0.3.0/guide/introduction/` "Reusable components" section + `caelestia-dots/shell` pattern | Same as the quickshell project: LGPL-3.0 |
14 -| 03 | `03-clock/` | `PanelWindow` + `SystemClock` + `Qt.formatTime/Date` | Hand-written; the SystemClock docs page | Same as the quickshell project: LGPL-3.0 |
15 -| 04 | `04-pipewire-volume/` | Pipewire binding + Slider | Adapted from `quickshell-examples/mixer/` (Pipewire + Repeater) and `quickshell-examples/volume-osd/` (Pipewire audio binding) | Same as the quickshell project: LGPL-3.0 |
16 -| 05 | `05-osd-volume/` | LazyLoader + Connections + Timer OSD | Mirrors `quickshell-examples/volume-osd/` shape directly (Scope + LazyLoader + PanelWindow + PwObjectTracker + Connections + Timer + Region) | Same as the quickshell project: LGPL-3.0 |
17 -| 06 | `06-ipc-control/` | `IpcHandler` for external control | `quickshell.org/docs/v0.3.0/guide/faq/` "Open/close windows with commands" section | Same as the quickshell project: LGPL-3.0 |
18 -| 07 | `07-composite-bar/` | All five services in one bar | Composite of patterns from `examples/02`, `04`, `quickshell-examples/activate_linux/` (Variants + namespace), `quickshell-examples/focus_following_panel/` (Hyprland API) | Same as the quickshell project: LGPL-3.0 |
19 -| 08 | `08-notification-daemon/` | `NotificationServer` + `Repeater` on `trackedNotifications` | `quickshell.org/docs/v0.3.0/types/Quickshell.Services.Notifications/NotificationServer` + replaces mako/dunst | Same as the quickshell project: LGPL-3.0 |
10 +| # | Name | What it shows | Source / inspiration | License |
11 +| -- | ------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
12 +| 01 | `01-hello-bar/` | Smallest valid `PanelWindow` | Hand-written; the canonical "hello world" shape from `quickshell.org/docs/v0.3.0/guide/introduction/` | Same as the quickshell project: LGPL-3.0 (runtime) |
13 +| 02 | `02-per-monitor-bar/` | `Variants` + per-monitor, multi-file shell | `quickshell.org/docs/v0.3.0/guide/introduction/` "Reusable components" section + `caelestia-dots/shell` pattern | Same as the quickshell project: LGPL-3.0 |
14 +| 03 | `03-clock/` | `PanelWindow` + `SystemClock` + `Qt.formatTime/Date` | Hand-written; the SystemClock docs page | Same as the quickshell project: LGPL-3.0 |
15 +| 04 | `04-pipewire-volume/` | Pipewire binding + Slider | Adapted from `quickshell-examples/mixer/` (Pipewire + Repeater) and `quickshell-examples/volume-osd/` (Pipewire audio binding) | Same as the quickshell project: LGPL-3.0 |
16 +| 05 | `05-osd-volume/` | LazyLoader + Connections + Timer OSD | Mirrors `quickshell-examples/volume-osd/` shape directly (Scope + LazyLoader + PanelWindow + PwObjectTracker + Connections + Timer + Region) | Same as the quickshell project: LGPL-3.0 |
17 +| 06 | `06-ipc-control/` | `IpcHandler` for external control | `quickshell.org/docs/v0.3.0/guide/faq/` "Open/close windows with commands" section | Same as the quickshell project: LGPL-3.0 |
18 +| 07 | `07-composite-bar/` | All five services in one bar | Composite of patterns from `examples/02`, `04`, `quickshell-examples/activate_linux/` (Variants + namespace), `quickshell-examples/focus_following_panel/` (Hyprland API) | Same as the quickshell project: LGPL-3.0 |
19 +| 08 | `08-notification-daemon/` | `NotificationServer` + `Repeater` on `trackedNotifications` | `quickshell.org/docs/v0.3.0/types/Quickshell.Services.Notifications/NotificationServer` + replaces mako/dunst | Same as the quickshell project: LGPL-3.0 |
21 21 ## Running an example

skills/quickshell/references/patterns.md

Modified
2 2 # Patterns
4 4 Reusable recipes. Each pattern solves a recurring shape of problem. Combine them.
6 +All patterns here are validated against Quickshell **v0.3.0**. When bumping versions, re-check each against the latest `quickshell.org/docs/<version>/guide/` (see `getting-fresh-docs.md`).
6 8 ## P1. Per-monitor instantiation
8 10 ```qml
22 24 `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.
26 +**Source:** [docs/v0.3.0/guide/introduction/ → Reusable components](https://quickshell.org/docs/v0.3.0/guide/introduction/#reusable-components) · [Variants type](https://quickshell.org/docs/v0.3.0/types/Quickshell/Variants) · [ShellScreen type](https://quickshell.org/docs/v0.3.0/types/Quickshell/ShellScreen)
24 28 ## P2. Live-updating clock
26 30 ```qml
33 37 `SystemClock` is **not** a singleton — you must instantiate it. `clock.date` is a reactive JS `Date`; format it with `Qt.formatTime` / `Qt.formatDate` / `Qt.formatDateTime`. Updates trigger within 50ms of the system clock changing.
39 +**Source:** [SystemClock type](https://quickshell.org/docs/v0.3.0/types/Quickshell/SystemClock) · [quickshell-mirror/quickshell `src/wayland/screencopy/systemclock.*` @ v0.3.0](https://github.com/quickshell-mirror/quickshell/blob/v0.3.0/src/wayland/screencopy/systemclock.cpp) (reference impl)
35 41 ## P3. Run a shell command, capture output
37 43 ```qml
50 56 `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).
58 +**Source:** [docs/v0.3.0/guide/introduction/ → Running a process](https://quickshell.org/docs/v0.3.0/guide/introduction/#running-a-process) · [Process type](https://quickshell.org/docs/v0.3.0/types/Quickshell.Io/Process) · [StdioCollector type](https://quickshell.org/docs/v0.3.0/types/Quickshell.Io/StdioCollector)
52 60 ## P4. Long-running stream, regex match per line
54 62 ```qml
70 78 `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).
80 +**Source:** [SplitParser type](https://quickshell.org/docs/v0.3.0/types/Quickshell.Io/SplitParser) · [quickshell-examples/focus_following_panel](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/focus_following_panel) (canonical example)
72 82 ## P5. Bind a service object's state
74 84 ```qml
86 96 The `?.` optional chain is the safe way to read state that might not be present yet (e.g. before the service has connected).
98 +**Source:** [docs/v0.3.0/guide/ → Not "one process per widget"](https://quickshell.org/docs/v0.3.0/guide/faq/#should-i-use-a-process-per-widget) (FAQ) · [Pipewire type](https://quickshell.org/docs/v0.3.0/types/Quickshell.Services.Pipewire/Pipewire) · [PwObjectTracker type](https://quickshell.org/docs/v0.3.0/types/Quickshell.Services.Pipewire/PwObjectTracker)
88 100 ## P6. React to a service signal
90 102 ```qml
99 111 `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.
113 +**Source:** [quickshell-examples/volume-osd](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/volume-osd) (canonical Connections + Pipewire example)
101 115 ## P7. Show a window only when a condition holds
103 117 ```qml
120 134 The window is destroyed when `active` flips to false. Good for rare/expensive UI.
136 +**Source:** [docs/v0.3.0/guide/faq/ → Reduce memory usage](https://quickshell.org/docs/v0.3.0/guide/faq/#reduce-memory-usage) · [LazyLoader type](https://quickshell.org/docs/v0.3.0/types/Quickshell/LazyLoader) · [quickshell-examples/volume-osd](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/volume-osd) (canonical example)
122 138 ## P8. Click-through overlay
124 140 ```qml
131 147 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.
149 +**Source:** [Region type](https://quickshell.org/docs/v0.3.0/types/Quickshell/Region) · [quickshell-examples/activate_linux](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/activate_linux) (`mask: Region {}` example) · [quickshell-examples/volume-osd](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/volume-osd) (OSD with click-through)
133 151 ## P9. System icon
135 153 ```qml
144 162 `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`.
164 +**Source:** [Quickshell.iconPath method](https://quickshell.org/docs/v0.3.0/types/Quickshell/Quickshell#iconPath) · [IconImage type](https://quickshell.org/docs/v0.3.0/types/Quickshell.Widgets/IconImage) · [docs/v0.3.0/guide/faq/ → Get rid of the purple/black icons](https://quickshell.org/docs/v0.3.0/guide/faq/#get-rid-of-the-purpleblack-icons)
146 166 ## P10. Custom file-bound properties (config-as-code)
148 168 ```qml
158 178 `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).
180 +**Source:** [JsonAdapter type](https://quickshell.org/docs/v0.3.0/types/Quickshell.Io/JsonAdapter)
160 182 ## P11. Multi-file shell
187 209 - `widgets/*.qml` etc. → import with `import qs.widgets as W` (LSP-friendly, v0.2.0+).
188 210 - `import "relative/path"` works but loses LSP coverage; prefer `qs.*`.
212 +**Source:** [docs/v0.3.0/guide/qml-language/ → Implicit imports](https://quickshell.org/docs/v0.3.0/guide/qml-language/#implicit-imports) · [docs/v0.3.0/guide/qml-language/ → Manual imports (qs.*)](https://quickshell.org/docs/v0.3.0/guide/qml-language/#manual-imports)
190 214 ## P12. Version-gate a feature
192 216 ```qml
202 226 `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.
228 +**Source:** [Quickshell.hasVersion method](https://quickshell.org/docs/v0.3.0/types/Quickshell/Quickshell#hasVersion) · [docs/v0.3.0/guide/advanced/ → If/Endif preprocessor](https://quickshell.org/docs/v0.3.0/guide/advanced/#ifendif)
204 230 ## P13. Reuse state across components
206 232 Put the state in the `Scope` root:
219 245 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`.
247 +**Source:** [Scope type](https://quickshell.org/docs/v0.3.0/types/Quickshell/Scope) · [quickshell-examples/volume-osd](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/volume-osd) (canonical Scope example)
221 249 ## P14. Custom re-usable component file
223 251 ```qml
236 264 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.
266 +**Source:** [docs/v0.3.0/guide/qml-language/ → Creating types](https://quickshell.org/docs/v0.3.0/guide/qml-language/#creating-types) · [quickshell-examples/wlogout](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/wlogout) (canonical multi-file component example)
238 268 ## P15. Hide the reload popup
240 270 If you have your own reloader indicator, you can disable the built-in one (v0.3.0+):
251 281 The default reload popup shows on every file save. For noisier iteration, replace it with a smaller indicator or disable via `QuickshellSettings`.
283 +**Source:** [quickshell-examples/reload-popup](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/reload-popup) · [quickshell.org/docs/v0.3.0/guide/advanced/ → Environment (QS_NO_RELOAD_POPUP)](https://quickshell.org/docs/v0.3.0/guide/advanced/#environment)
253 285 ## P16. Process IPC (call into quickshell from outside)
255 287 ```qml
272 304 Use this for keybind triggers, scripts, and external automation.
306 +**Source:** [IpcHandler type](https://quickshell.org/docs/v0.3.0/types/Quickshell.Io/IpcHandler) · [docs/v0.3.0/guide/faq/ → Open/close windows with commands](https://quickshell.org/docs/v0.3.0/guide/faq/#openclose-windows-with-commands) · [docs/v0.3.0/guide/advanced/ → IPC signal listener (v0.3.0+)](https://quickshell.org/docs/v0.3.0/guide/advanced/#environment)