From f8156ce853b1a74fb0bd6db4c5734a42933daee2 Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Mon, 14 Sep 2026 19:21:36 +0200 Subject: docs(desktop): document the kdeconnect module Records that the phone-to-PC clipboard is the daemon's plugin and not the indicator's, so removing the indicator does not break it, and that polling stops when the drawer closes. --- desktop/README.md | 15 ++++++------ desktop/modules/kdeconnect/README.md | 45 ++++++++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+), 7 deletions(-) create mode 100644 desktop/modules/kdeconnect/README.md diff --git a/desktop/README.md b/desktop/README.md index f440512..f0345eb 100644 --- a/desktop/README.md +++ b/desktop/README.md @@ -26,13 +26,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/kdeconnect/ devices, battery, pairing, ping, clipboard, share, mount 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, network and bluetooth 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, bluetooth and kdeconnect each carry their own README. +Appearance is a tile onto the separate appearance shell, whose README covers the +picker it opens. ## Writing a module @@ -58,8 +59,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, network and -bluetooth each add a service and a page on top of that same shape. +picker on click, no always-active service. Sound, mail, vm, network, bluetooth +and kdeconnect each add a service and a page on top of that same shape. Module files live under `desktop/modules//` and reference root types (`Module`, `Page`, `Button`, `Theme`), so each needs `import "../.."`. A plain @@ -72,7 +73,7 @@ directory import does not reach the parent. The moved `TransportButton.qml` and 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, network and bluetooth are -`alwaysActive: true`; vm is false. +`alwaysActive: true`; vm and kdeconnect are false. Sound's OSD has to answer a volume keypress with no drawer open, which is the whole point of it, so its PipeWire service is instantiated eagerly and runs for @@ -103,7 +104,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, Bluetooth, Mail, Appearance, Machines. +Sound, Network, Bluetooth, KDE Connect, Mail, Appearance, Machines. ## Hyprland and waybar diff --git a/desktop/modules/kdeconnect/README.md b/desktop/modules/kdeconnect/README.md new file mode 100644 index 0000000..b92cb2d --- /dev/null +++ b/desktop/modules/kdeconnect/README.md @@ -0,0 +1,45 @@ +# kdeconnect + +KDE Connect devices in the drawer, replacing the `kdeconnect-indicator` tray +icon. Status, battery, pairing, ping, clipboard send, file share, refresh and +filesystem mount. + +The tile names the reachable device and its battery when the battery plugin +reports one, a count when several are reachable, `Offline` when paired devices +exist but none is reachable, and `No devices` otherwise. + +The page lists paired devices, then any discovered unpaired ones, with a +refresh control at the top and an incoming-pairing banner. A reachable row +offers Ring, Clipboard, Share and Mount; a paired row offers Unpair; an +unpaired reachable one offers Pair. + +## The daemon does the clipboard + +Quickshell 0.3.1 has no generic D-Bus module, only `Quickshell.DBusMenu`, so +nothing here binds to `org.kde.kdeconnect`. State is read by `qdbus6` and +actions run through `kdeconnect-cli`, with `qdbus6` for pair accept and reject, +which the CLI does not expose. + +The phone-to-PC clipboard is not this module's. `kdeconnectd` loads the +clipboard plugin and writes the system clipboard itself (through +`KSystemClipboard`), and the indicator was never part of that path, so removing +the indicator does not break it. If it fails on Hyprland it is the compositor +refusing `set_selection` from a daemon with no keyboard focus, which no code +here can fix. + +## Service lifetime + +`alwaysActive: false`. There is no push to listen to, so the state is polled +every 5s while the drawer is open. The tile is created when the drawer panel +loads and destroyed when it unloads, and it is the tile that turns polling on +and off, so nothing polls while the drawer is closed. A consequence: an +incoming pairing request that arrives while the drawer is closed is not noticed +until it is opened, though the daemon keeps the request. + +## Not built + +SMS, notification forwarding, remote input, media control, presenter mode, +find-this-device and remote commands. The daemon supports them and the +indicator surfaced some; this module does not. Pairing failure comes from the +`kdeconnect-cli` exit code, not the `pairingFailed` signal, since there is no +D-Bus module to subscribe with. -- cgit v1.2.3