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.