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.
7 +`import Quickshell.Services.Pipewire`
10 +PwObjectTracker { objects: [ Pipewire.defaultAudioSink ] }
13 + text: `vol: ${Math.floor((Pipewire.defaultAudioSink?.audio.volume ?? 0) * 100)}%`
17 + value: Pipewire.defaultAudioSink?.audio.volume ?? 0
18 + onValueChanged: Pipewire.defaultAudioSink.audio.volume = value
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`
35 + model: Mpris.players
37 + required property var modelData // a MprisPlayer
38 + Text { text: `${modelData.trackTitle} — ${modelData.trackArtist}` }
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.
50 +`import Quickshell.Services.Notifications`
59 + model: server.trackedNotifications
60 + delegate: Item { /* render Notification */ }
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.
71 +`import Quickshell.Services.SystemTray`
81 + delegate: TrayButton { item: modelData }
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`
94 +UPower { id: upower }
97 + text: upower.displayDevice ? `${Math.floor((upower.displayDevice?.chargePercentage ?? 0) * 100)}%` : "—"
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.
108 +`import Quickshell.Services.Bluetooth`
113 + // selected adapter, defaults to the first
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.
124 +`import Quickshell.Networking`
127 +Networking { id: net }
130 + text: net.primaryWifi?.ssid ?? "—"
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`
146 + onPrompt: /* request username/password from UI */
147 + onInfo: /* show info message */
148 + onError: /* show error */
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`
164 + onCompleted: (result) => { if (result == PamResult.Success) unlock() }
165 + onResponseRequired: (prompt) => { passwordField.text = prompt; pam.respond(passwordField.text) }
166 + onError: (err) => { showError(err) }
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`, ...
177 +`import Quickshell.Services.Polkit`
182 + onQuestion: (auth) => { /* show password UI, call auth.response(pw) */ }
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`
204 + WlrLayershell.layer: WlrLayer.Overlay
205 + WlrLayershell.keyboardFocus: WlrKeyboardFocus.None
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.