Initial commit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 22:46:43 +01:00
commit 1c273fc881
5 changed files with 740 additions and 0 deletions
@@ -0,0 +1,58 @@
+# trackscreen
+
+Use a laptop touchscreen as a real multitouch **touchpad**. Toggle between
+modes with a **five-finger tap**.
+
+* **Touchscreen mode** (the default): nothing changes. trackscreen only reads
+  the touchscreen passively, so the desktop keeps native multitouch.
+* **Trackpad mode**: trackscreen grabs the touchscreen and re-emits its touches
+  through a virtual touchpad ("Trackscreen Virtual Touchpad"). libinput handles
+  it like any other touchpad, so you get relative pointer motion with
+  acceleration, tap-to-click (1/2/3 fingers = left/right/middle), tap-and-drag,
+  two-finger scrolling, pinch zoom, and 3/4-finger swipes. Configure these in
+  your desktop's normal touchpad settings (KDE: System Settings -> Touchpad).
+
+The grab exists only in trackpad mode. The kernel releases it if trackscreen
+exits or crashes, so the touchscreen can't get stuck. A pen or stylus is a
+separate device and is never affected.
+
+## Requirements
+
+Linux with libinput (Wayland or X11), Python 3 and `python-evdev`.
+
+## Install
+
+    ./install.sh            # udev rule (sudo) + systemd user service, starts it now
+
+The udev rule gives the logged-in user access to touchscreens and `/dev/uinput`.
+You can join the `input` group instead, but that also exposes every keyboard.
+
+To run it by hand instead: `./trackscreen.py --debug`
+
+## Toggling
+
+* Five-finger tap: fingers down and up within 0.6 s, without moving.
+  Tuning: `--toggle-fingers N` (0 disables it), `--tap-time`, `--tap-move`.
+* `trackscreen.py --toggle`, or `pkill -USR1 -f trackscreen.py`. Bind either
+  to a keyboard shortcut if you like.
+
+A desktop notification shows the new mode (disable with `--no-notify`).
+
+## Other laptops / tuning
+
+* `--list-devices` shows the auto-detected touchscreen; `--device` picks one by
+  path or name.
+* Physical size comes from the kernel or from udev (`ID_INPUT_WIDTH_MM`), so
+  pointer speed is consistent across machines. Override with `--size 307x187`.
+* If the built-in display is rotated, use `--rotate 90|180|270`. A
+  `LIBINPUT_CALIBRATION_MATRIX` set in udev is applied automatically
+  (`--matrix` overrides it).
+* `--speed 1.5` scales pointer and gesture speed on top of the desktop settings.
+* `--start-mode trackpad` starts in trackpad mode.
+
+## Caveats
+
+* In touchscreen mode the five-finger tap also reaches the desktop as five
+  touches. It is usually harmless, but it can tap whatever is under your fingers.
+* If "disable touchpad when a mouse is connected" is on, it also applies to
+  the virtual touchpad.