diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 190 |
1 files changed, 190 insertions, 0 deletions
@@ -0,0 +1,190 @@ +mouseboard +========== +Keyboard-driven virtual pointer for Wayland and Windows. Bring up a labelled +grid over the screen, type a label to jump to a cell, refine the spot by +bisection, then press one key to click. No mouse, no daemon. + + +What it does +------------ +Run `mouseboard` (bound to a hotkey) and a grid is drawn over every monitor: + +1. Grid Type the two-or-so letter label in a cell to jump there. +2. Refine The cell becomes the active region. Split it by quadrant with + u/i/j/k until the crosshair sits exactly where you want; the pointer + tracks the region centre live. Backspace undoes a split. +3. Click m left, , middle, . right, ; double, v drag. Esc cancels. + +Bisection gives unlimited precision in a few keystrokes, so the coarse grid can +stay coarse and the labels short. + + +Requirements +------------ +Linux: a wlroots-based compositor (sway, Hyprland, river, Wayfire, labwc, ...) +implementing `wlr-layer-shell` and `wlr-virtual-pointer`. GNOME and KDE are not +supported yet (see Portability). A shipped static binary needs nothing else. + +Windows: Windows 10 1703 or newer (per-monitor DPI v2). The shipped .exe is +static and needs nothing else. + + +Build and install +----------------- +The Wayland protocols are vendored under proto/, so a build needs only a +toolchain. The release build is static: provision its dependencies once, then +build and install. + + ./provision-static.sh # once per machine: static wayland/xkbcommon/ffi + # archives (pinned, checksummed) into musl-sysroot/ + make static # -> ./mouseboard, one static binary + sudo make install + +The result is self-contained, already stripped, and runs on any Linux. + +Besides a C compiler, make and pkg-config, provisioning needs meson, ninja, +bison, expat, curl and the Linux kernel headers - plus a musl toolchain on a +glibc distro (Debian, Arch). It builds its own wayland-scanner from source, so +the host's version does not matter. On musl-native distros (Alpine, Void-musl) +gcc is already musl and provision-static.sh uses it automatically; set CC only +to override the detected compiler. + +These commands install enough for both Linux builds: + + # Debian / Ubuntu + sudo apt install build-essential pkgconf libwayland-bin libwayland-dev \ + libxkbcommon-dev meson ninja-build bison curl musl-tools libexpat1-dev + + # Arch + sudo pacman -S --needed base-devel wayland libxkbcommon meson ninja bison \ + curl linux-api-headers musl expat + + # Alpine (musl-native: gcc is already musl, detected automatically) + sudo apk add build-base pkgconf wayland-dev libxkbcommon-dev meson samurai \ + bison curl linux-headers expat-dev + + # Void (use the musl flavour: gcc is already musl, detected automatically) + sudo xbps-install -S base-devel pkgconf wayland-devel libxkbcommon-devel \ + meson ninja bison curl expat-devel + + # Gentoo (gcc/make/pkg-config already in @system) + sudo emerge --ask dev-libs/wayland x11-libs/libxkbcommon dev-libs/expat \ + meson ninja sys-devel/bison net-misc/curl sys-kernel/linux-headers + + +Windows build +------------- +The .exe is cross-built from Linux with a mingw-w64 toolchain (native mingw on +Windows builds the same way). It links only gdi32/user32, so there are no other +libraries: + + # Debian / Ubuntu + sudo apt install gcc-mingw-w64-x86-64 make + + # Arch + sudo pacman -S --needed mingw-w64-gcc make + + # Fedora + sudo dnf install mingw64-gcc make + + make -f Makefile.win # -> mouseboard.exe + +Copy the result to the Windows machine and run it; there is nothing to install. + + +Developing (dynamic build) +-------------------------- +A plain `make` links against the system's shared libraries, so it needs no +provisioning - only wayland-scanner (it ships with the Wayland package) plus the +wayland-client, xkbcommon and Linux kernel development headers: + + make # dev build; produces ./mouseboard + make check # dependency-free core and state-machine tests + +If anything is missing it tells you exactly what to install. `make static` +cleans first (the modes use different compilers); run `make clean` when +switching back. + + +Usage +----- +Wayland does not let a client grab a global hotkey, so bind the command in your +compositor. One binding runs the whole flow; the final key decides the button. + +sway (~/.config/sway/config): + + bindsym $mod+g exec mouseboard + +Hyprland (~/.config/hypr/hyprland.conf): + + bind = SUPER, G, exec, mouseboard + +Windows: run mouseboard.exe directly, or bind it to a hotkey with a shortcut or +a tool such as AutoHotkey. It grabs the keyboard while the grid is up, so keys +do not leak to the focused window; Esc cancels. + +Try it without clicking anything; it prints the target and action instead: + + mouseboard --dry-run + + +Keys +---- +Defaults; all are configurable (see Configuration). + + label chars f j d k s l a g h r u e i w o q p t y v b c n x m z + refine u top-left i top-right j bottom-left k bottom-right + click m left , middle . right ; double v drag + Enter left click (once a cell is selected) + Backspace undo last split (or return to the grid) + Esc cancel + +Drag is two targets: press v over the start, then pick the end the same way +(grid, refine) and press any click key to release. + + +Configuration +------------- +Optional file at $XDG_CONFIG_HOME/mouseboard/config (default +~/.config/mouseboard/config; on Windows %APPDATA%\mouseboard\config). Lines are +`key = value`; lines starting with # are comments. Command-line flags override +the file. See config.example for every key with its default. Colours are +#RRGGBB or #RRGGBBAA. Two opacities (0..100): `opacity_bg` dims the desktop +(default 33; 100 is solid) and `opacity_fg` sets how strong the labels, grid +and crosshair are (default 65). + + +How to debug +------------ + mouseboard --dry-run print "x y action" instead of moving the pointer + mouseboard --selftest run offline checks of labels/bisection/config + WAYLAND_DEBUG=1 mouseboard --dry-run trace every protocol message + +If it exits with "compositor lacks ...", the compositor does not implement a +required wlroots protocol and is not supported. If labels do not appear, confirm +the binding actually launched mouseboard (run it from a terminal to see errors). + + +Portability +----------- +The core (grid, labels, bisection, rendering, config) talks only to the backend +interface in platform.h and never includes an OS header. A backend is one file +providing platform_init(), and exactly one is linked into the binary. + +The wlroots Wayland backend uses layer-shell for the overlay and virtual-pointer +for input. The Win32 backend draws a per-monitor layered overlay with +UpdateLayeredWindow, grabs the keyboard with a low-level hook, and clicks via +SendInput. It is a GUI-subsystem binary, so a hotkey launch shows no console; it +attaches to a parent console when run from a terminal, so --dry-run and --help +still print. + + +Credits +------- +mouseboard is released under the MIT licence; see LICENSE. It bundles +third-party files, each kept under its own terms: + +- font8x8_basic.h: 8x8 bitmap font by Daniel Hepper and Marcel Sondaar / IBM, + public domain. +- proto/*.xml: Wayland protocol descriptions from wayland-protocols and + wlr-protocols, MIT/Expat. Per-file provenance is in proto/SOURCES. |