1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
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.
|