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:

Grid Type the two-or-so letter label in a cell to jump there.
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.
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.