diff options
Diffstat (limited to 'desktop')
| -rw-r--r-- | desktop/README.md | 14 | ||||
| -rw-r--r-- | desktop/modules/bluetooth/README.md | 38 |
2 files changed, 46 insertions, 6 deletions
diff --git a/desktop/README.md b/desktop/README.md index 7dc9612..5b890e0 100644 --- a/desktop/README.md +++ b/desktop/README.md @@ -25,12 +25,14 @@ the IPC layer rejects. The page-less grid entry is therefore the zero-argument modules/sound/ output and input volume, the OSD, the player modules/network/ wired and wifi, radio, scan, join, forget + modules/bluetooth/ adapter, scan, pair, connect, forget, trust modules/mail/ unread per account, threads, the watcher dot modules/vm/ libvirt state, live stats, snapshots modules/appearance/ a tile that opens the separate appearance shell -Sound, mail, vm and network each carry their own README. Appearance is a tile -onto the separate appearance shell, whose README covers the picker it opens. +Sound, mail, vm, network and bluetooth each carry their own README. Appearance +is a tile onto the separate appearance shell, whose README covers the picker +it opens. ## Writing a module @@ -56,8 +58,8 @@ fire-and-forget, so its click calls `activate()` and closes the drawer. `modules/appearance/AppearanceModule.qml` is the smallest complete example: a name, an icon, a label, and an `activate()` that launches the separate appearance shell. It has no page, and it owns only a `Process` that fires the -picker on click, no always-active service. Sound, mail, vm and network each add -a service and a page on top of that same shape. +picker on click, no always-active service. Sound, mail, vm, network and +bluetooth each add a service and a page on top of that same shape. Module files live under `desktop/modules/<name>/` and reference root types (`Module`, `Page`, `Button`, `Theme`), so each needs `import "../.."`. A plain @@ -69,7 +71,7 @@ directory import does not reach the parent. The moved `TransportButton.qml` and `alwaysActive` is declarative metadata: it documents whether a module's service is meant to run while the drawer is closed. The drawer does not read or enforce it. Each module implements its own service lifetime, and the property records -that choice rather than driving it. Sound, mail and network are +that choice rather than driving it. Sound, mail, network and bluetooth are `alwaysActive: true`; vm is false. Sound's OSD has to answer a volume keypress with no drawer open, which is the @@ -101,7 +103,7 @@ is an empty `Item` claiming the space, not a placeholder graphic, so the grid below it sits where it will sit once notifications arrive. The bottom is a fixed, never-scrolled `Flow` grid: three columns at 180px minimum, wrapping and adding rows up to a 3x3 ceiling for the modules that exist, in the order -Sound, Network, Mail, Appearance, Machines. +Sound, Network, Bluetooth, Mail, Appearance, Machines. ## Hyprland and waybar diff --git a/desktop/modules/bluetooth/README.md b/desktop/modules/bluetooth/README.md new file mode 100644 index 0000000..2de634a --- /dev/null +++ b/desktop/modules/bluetooth/README.md @@ -0,0 +1,38 @@ +# bluetooth + +The adapter, its devices, and pairing, in one module. + +The tile names the connected device, or a count when several, `No devices` +when the adapter is on and idle, `Off` when it is down. + +The page carries the adapter power switch, a visible toggle, a scan toggle, +then the connected devices, the paired ones, and anything found while +scanning. A paired device offers Connect, Trust and Forget; an unpaired one +offers Pair. + +## Pairing is the one shell-out + +Quickshell ships no BlueZ pairing agent and no generic D-Bus module, so a +device that requires a passkey or PIN confirmation has no way to prompt from +QML. `Pairing.qml` runs `bluetoothctl --timeout 20 pair <address>`, whose own +agent handles the prompt. + +Everything else is native `Quickshell.Bluetooth`. The cost is that +`bluetoothctl` is the ceiling: a device it cannot auto-confirm times out and +the error shows, rather than pairing. `Pairing.qml` carries a `ponytail:` +comment naming that and the upgrade path. + +## Not built + +Connecting and forgetting report no failure signal in the BlueZ binding; only +pairing does, through the `bluetoothctl` exit code. A connect that fails +shows only as the device staying unconnected. + +## Service lifetime + +`alwaysActive: true`, and truthfully: the BlueZ backend pushes, there is no +poll to gate, and there is no `Service.qml`. Referencing `Bluetooth` in +`BluetoothModule.qml` instantiates it at shell start. + +The adapter is null and the device list empty for about two seconds after +launch. Every access navigates safely; nothing caches the first paint. |