repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

skill: add quickshell advanced examples

4e9487b91554cbc3b379a8cd2dbd12acfab87df5

Review <review@example.invalid> ·

unsigned

Browse filesCompare with HEAD

Changed files (7)

skills/quickshell/examples/04-pipewire-volume/Bar.qml

Added
new file mode 100644
1 +// 04-pipewire-volume/Bar.qml
2 +// A bar showing the default audio sink volume. Drag the slider to change it.
4 +import QtQuick
5 +import QtQuick.Layouts
6 +import Quickshell
7 +import Quickshell.Services.Pipewire
8 +import Quickshell.Widgets
10 +PanelWindow {
11 + anchors { top: true; left: true; right: true }
12 + implicitHeight: 36
13 + color: "#cc1e1e2e"
15 + // Keep the default sink tracked; without this, `defaultAudioSink?.audio`
16 + // can drop to null because pipewire may release the node.
17 + PwObjectTracker {
18 + objects: [ Pipewire.defaultAudioSink ]
19 + }
21 + RowLayout {
22 + anchors.fill: parent
23 + anchors.leftMargin: 12
24 + anchors.rightMargin: 12
25 + spacing: 12
27 + // Icon. `Quickshell.iconPath` resolves against the system icon theme.
28 + IconImage {
29 + implicitSize: 18
30 + source: Quickshell.iconPath(
31 + (Pipewire.defaultAudioSink?.audio.muted ?? false)
32 + ? "audio-volume-muted-symbolic"
33 + : "audio-volume-high-symbolic"
34 + )
35 + }
37 + // Mute toggle. The `Connections` watches the service for changes.
38 + Text {
39 + text: "Mute"
40 + color: "white"
41 + font.pointSize: 11
42 + MouseArea {
43 + anchors.fill: parent
44 + cursorShape: Qt.PointingHandCursor
45 + onClicked: Pipewire.defaultAudioSink.audio.muted = !Pipewire.defaultAudioSink.audio.muted
46 + }
47 + }
49 + Item { Layout.fillWidth: true; width: 1 } // spacer
51 + // The slider is read-only bound to volume, but writes on change.
52 + // We must NOT bind `value:` to the same property we assign to (binding fight).
53 + Slider {
54 + Layout.preferredWidth: 240
55 + from: 0
56 + to: 1.5
57 + value: Pipewire.defaultAudioSink?.audio.volume ?? 0
58 + onMoved: Pipewire.defaultAudioSink.audio.volume = value
59 + }
61 + Text {
62 + text: `${Math.floor((Pipewire.defaultAudioSink?.audio.volume ?? 0) * 100)}%`
63 + color: "white"
64 + font.pointSize: 11
65 + Layout.preferredWidth: 40
66 + }
67 + }

skills/quickshell/examples/04-pipewire-volume/README.md

Added
new file mode 100644
1 +# 04 — pipewire volume
3 +A bar that displays and controls the default audio sink's volume via Pipewire. The same shape generalizes to per-app volume, source/sink switching, mic mute, etc.
5 +**Run:** `qs -p examples/04-pipewire-volume/shell.qml`
7 +**What it teaches:**
9 +- `PwObjectTracker { objects: [ ... ] }` to keep a service object alive.
10 +- Reading reactive state with `?.` and `??` for safe defaults.
11 +- Writing to the same property is fine — but never also `bind` a Slider's `value:` to it (binding loop). Use `value: ...; onMoved: ... = value`.
12 +- `Quickshell.iconPath` for the volume/mute icon.
13 +- `MouseArea` over a `Text` for a clickable label.
15 +**What to break and learn from:**
17 +- Remove the `PwObjectTracker` → volume may show as 0% even when audio plays (object got collected).
18 +- Replace `onMoved` with `onValueChanged` → fires while the user drags (very chatty, but works).
19 +- Add `Connections { target: ...audio; function onVolumeChanged() { flash() } }` to react to OS-level volume changes (e.g. from a media key) — the OSD-on-volume-change pattern.
20 +- Read `Pipewire.defaultAudioSource` instead → mic volume instead of speaker.
22 +**Related:**
24 +- `references/services.md` for the full Pipewire API.
25 +- The `volume-osd/` example in the official examples repo for a LazyLoader + OSD variant.

skills/quickshell/examples/04-pipewire-volume/shell.qml

Added
new file mode 100644
1 +// 04-pipewire-volume/shell.qml
2 +// A bar with the default sink's volume — read+write via PwObjectTracker + Slider.
3 +// Run with: qs -p examples/04-pipewire-volume/shell.qml
5 +import QtQuick
6 +import QtQuick.Layouts
7 +import Quickshell
8 +import Quickshell.Services.Pipewire
9 +import "."
11 +Variants {
12 + model: Quickshell.screens
13 + delegate: Component {
14 + Bar {
15 + required property var modelData
16 + screen: modelData
17 + }
18 + }

skills/quickshell/examples/05-osd-volume/README.md

Added
new file mode 100644
1 +# 05 — OSD volume
3 +An on-screen-display volume bar that appears for one second when the default sink's volume changes (or it gets muted). The canonical OSD pattern.
5 +**Run:** `qs -p examples/05-osd-volume/shell.qml`
7 +**Test it:**
9 +```sh
10 +wpctl set-volume @DEFAULT_AUDIO_SINK@ 0.5
11 +wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle
12 +```
14 +You should see a pill-shaped OSD pop up at the bottom of the focused monitor for one second.
16 +**What it teaches:**
18 +- `Scope` as the root — used here to host shared state (`shouldShowOsd`) and a `Timer`.
19 +- `Connections { target: ...; function onXxx() { ... } }` to react to service signals.
20 +- `Timer { interval: 1000; onTriggered: ... }` to debounce/show-duration.
21 +- `LazyLoader { active: ... }` to create/destroy a window on demand (memory-aware).
22 +- `FloatingWindow` + `WlrLayershell.layer: WlrLayer.Overlay` to appear over fullscreen apps.
23 +- `mask: Region {}` for click-through.
24 +- `exclusiveZone: 0` so the OSD doesn't push windows around.
25 +- `screen.height / 5` for proportional placement.
27 +**What to break and learn from:**
29 +- Replace `LazyLoader` with `visible: false` → the OSD is always in memory; cheaper to build, but worse for big trees.
30 +- Remove `mask: Region {}` → the OSD swallows clicks until it disappears; you'll see the cursor change when you hover it.
31 +- Add a second `Connections` block on `Pipewire.defaultAudioSource?.audio` for mic-level OSD.
32 +- Swap `WlrLayer.Overlay` for `WlrLayer.Top` (default) → OSD is hidden behind fullscreen apps.
34 +**Why it didn't appear (debug checklist):**
36 +- Pipewire not running → no `defaultAudioSink`. The OSD never triggers. Check `wpctl status`.
37 +- No active audio stream → some pipewire nodes don't update volume if there's no stream.
38 +- LazyLoader only loads `active: true`; check `shouldShowOsd` is being set (`console.log` in the Connections handler).

skills/quickshell/examples/05-osd-volume/shell.qml

Added
new file mode 100644
1 +// 05-osd-volume/shell.qml
2 +// OSD volume: appears for 1s when the default sink's volume changes.
3 +// Demonstrates: Scope, PwObjectTracker, Connections, Timer, LazyLoader, Region, WlrLayer.Overlay.
4 +// Run with: qs -p examples/05-osd-volume/shell.qml
5 +// Try: `wpctl set-volume @DEFAULT_AUDIO_SINK@ 0.5` in another terminal to trigger.
7 +import QtQuick
8 +import QtQuick.Layouts
9 +import Quickshell
10 +import Quickshell.Services.Pipewire
11 +import Quickshell.Widgets
13 +Scope {
14 + id: root
16 + // Keep the default sink tracked. The Connections below needs it to be live.
17 + PwObjectTracker { objects: [ Pipewire.defaultAudioSink ] }
19 + // Show OSD for 1s after every volume change.
20 + Connections {
21 + target: Pipewire.defaultAudioSink?.audio
22 + function onVolumeChanged() {
23 + root.shouldShowOsd = true
24 + hideTimer.restart()
25 + }
26 + function onMutedChanged() {
27 + root.shouldShowOsd = true
28 + hideTimer.restart()
29 + }
30 + }
32 + property bool shouldShowOsd: false
34 + Timer {
35 + id: hideTimer
36 + interval: 1000
37 + onTriggered: root.shouldShowOsd = false
38 + }
40 + // LazyLoader: only exists when shouldShowOsd. Frees memory between events.
41 + LazyLoader {
42 + active: root.shouldShowOsd
44 + FloatingWindow {
45 + // The compositor picks the current focused monitor when no screen is set.
46 + anchors.bottom: true
47 + margins.bottom: screen.height / 5
48 + exclusiveZone: 0
50 + implicitWidth: 400
51 + implicitHeight: 60
52 + color: "transparent"
54 + // Empty region = click-through. Clicks pass to whatever's behind.
55 + mask: Region {}
57 + // Above fullscreen apps.
58 + WlrLayershell.layer: WlrLayer.Overlay
59 + WlrLayershell.keyboardFocus: WlrKeyboardFocus.None
60 + WlrLayershell.namespace: "qs-example-osd"
62 + Rectangle {
63 + anchors.fill: parent
64 + radius: height / 2
65 + color: "#aa000000"
67 + RowLayout {
68 + anchors {
69 + fill: parent
70 + leftMargin: 14
71 + rightMargin: 18
72 + }
73 + spacing: 12
75 + IconImage {
76 + implicitSize: 28
77 + source: Quickshell.iconPath(
78 + (Pipewire.defaultAudioSink?.audio.muted ?? false)
79 + ? "audio-volume-muted-symbolic"
80 + : "audio-volume-high-symbolic"
81 + )
82 + }
84 + Rectangle {
85 + Layout.fillWidth: true
86 + implicitHeight: 8
87 + radius: 4
88 + color: "#33ffffff"
90 + Rectangle {
91 + anchors {
92 + left: parent.left
93 + top: parent.top
94 + bottom: parent.bottom
95 + topMargin: 0
96 + bottomMargin: 0
97 + }
98 + implicitWidth: parent.width * Math.min(1, Pipewire.defaultAudioSink?.audio.volume ?? 0)
99 + radius: 4
100 + color: "white"
104 + Text {
105 + text: `${Math.floor((Pipewire.defaultAudioSink?.audio.volume ?? 0) * 100)}%`
106 + color: "white"
107 + font.pointSize: 13
108 + Layout.preferredWidth: 50

skills/quickshell/examples/06-ipc-control/README.md

Added
new file mode 100644
1 +# 06 — IPC control
3 +Expose quickshell functions to be called from outside (e.g. by a keybind daemon, a script, or another quickshell instance). The standard pattern for "open launcher", "toggle bar", "set bar text".
5 +**Run (in a terminal):**
7 +```sh
8 +qs -p examples/06-ipc-control/shell.qml
9 +```
11 +**From another terminal:**
13 +```sh
14 +# Show / hide / toggle the bar
15 +qs ipc call mybar show
16 +qs ipc call mybar hide
17 +qs ipc call mybar toggle
19 +# Pass an argument
20 +qs ipc call mybar setText "hello from outside"
21 +```
23 +The bar is hidden by default; call `show` to make it appear.
25 +**What it teaches:**
27 +- `IpcHandler { target: "mybar" }` registers an IPC namespace.
28 +- Functions declared inside `IpcHandler` are callable from outside via `qs ipc call <target> <fn> [args]`.
29 +- `Scope` as root to share state (`label`) between the handler and the visible widget.
30 +- `visible: false` initial state, controlled externally.
32 +**What to break and learn from:**
34 +- Forget the `target:` → IPC won't register. You'll get a "no such target" error from the outside `qs ipc` call.
35 +- Try `qs ipc call mybar setText` (no arg) → runtime error in the shell, the bar's text will go blank.
36 +- Add a `signal` to `IpcHandler` and listen from another quickshell instance via `Connections` — the v0.3.0 IPC signal listener feature.
38 +**Practical use:**
40 +- `hyprctl dispatch exec qs ipc call mybar toggle` in a Hyprland keybind.
41 +- `qs ipc call mybar focusWorkspace 3` from a script that wants to move the user to workspace 3.
42 +- `qs ipc call mybar notify "title" "body"` from a notification script that wants to use your quickshell notification daemon.
44 +**Note on `-c` vs `-p`:** IPC target names are global per shell ID, not per config name. If you run with `-p`, the shell ID is derived from the file path. Using a stable `-c <name>` makes the IPC target discoverable.

skills/quickshell/examples/06-ipc-control/shell.qml

Added
new file mode 100644
1 +// 06-ipc-control/shell.qml
2 +// IpcHandler: expose show/hide/toggle/text functions callable from outside the shell.
3 +// Run with: qs -p examples/06-ipc-control/shell.qml
4 +// Try:
5 +// qs -c ... ipc call mybar show
6 +// qs -c ... ipc call mybar hide
7 +// qs -c ... ipc call mybar toggle
8 +// qs -c ... ipc call mybar setText "hello from outside"
10 +import QtQuick
11 +import Quickshell
12 +import Quickshell.Io
14 +Scope {
15 + id: root
16 + property string label: "idle"
18 + IpcHandler {
19 + target: "mybar" // IPC namespace for qs ipc call
21 + function show(): void { bar.visible = true }
22 + function hide(): void { bar.visible = false }
23 + function toggle(): void { bar.visible = !bar.visible }
24 + function setText(s: string): void { root.label = s }
25 + }
27 + PanelWindow {
28 + id: bar
29 + visible: false
30 + anchors { top: true; left: true; right: true }
31 + implicitHeight: 40
32 + color: "#cc1e1e2e"
34 + Text {
35 + anchors.centerIn: parent
36 + text: root.label
37 + color: "white"
38 + }
39 + }