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/modules/kdeconnect/README.md | 45 ++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 desktop/modules/kdeconnect/README.md (limited to 'desktop/modules/kdeconnect/README.md') 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