wl-kbptr
— short for Wayland Keyboard Pointer — is a utility to help move the mouse pointer with the keyboard.
See Supported compositors section for compatibility.
To enable to select a target and click, it has four different modes:
floating
— which uses arbitrary areas either given by the user or detected,tile
— which uses a grid to select areas,bisect
— which enables to bisect an area,split
— which enables to successively split an area,- and
click
— which triggers a click in the middle of an area.
These are set with the modes
configuration field and can be chained, e.g. wl-kbptr -o modes=tile,bisect
.
Note that if you make a mistake — e.g. select the wrong area — you can always go back on step by pressing the Backspace
key. This even works between modes.
floating.webm
The floating
mode uses arbitrary selection areas that can be passed by the user through the standard input. Each input line represents an area defined with the wxh+x+y
format.
The areas can also be automatically detected with mode_floating.source
configuration set to detect
, e.g. wl-kbptr -o modes=floating,click -o mode_floating.source=detect
.
This requires the wl-kbptr
binary to be built with the opencv
feature and the compositor to support the wlr-screencopy-unstable-v1
protocol — see the supported compositors section and build instructions for details. Whilst it doesn't noticeably change the size of the program itself, OpenCV is a 100 MB+ dependency which is not ideal if you want a very small system which is why this is an optional feature.
Most distributions will package the program with the option enabled. If not, they will usually provide two packages. You can check if the binary you have has been built with it with wl-kbptr --version
— it should print opencv
if supported.
tile.webm
The tile
mode displays a grid. To select an area, simply type the label associated with the tile you want to select.
bisect.webm
The bisect
mode enables to bisect a given area. At any point the cursor can be moved at the location marked by the red marker by pressing Enter
or Space
.
A left, right and middle click can be made by pressing the g
, h
and b
keys respectively on a QWERTY keyboard layout. Note that other layout will use the same keys positions, e.g. i
, d
, and x
with a Dvorak keyboard layout.
split.webm
The split
mode enables to successively split an area with the arrow keys.
Just like the bisect
mode, a left, right and middle click can be made by pressing the g
, h
and b
keys respectively on a QWERTY keyboard layout.
The click
mode simply triggers a click in the middle of the selection area.
For wl-kbptr
to work, it requires the following protocols:
wlr-layer-shell-unstable-v1
for the program to display on top,wlr-virtual-pointer-unstable-v1
to control the mouse pointer,- and
wlr-screencopy-unstable-v1
(optional) to capture the screen for target detection in thefloating
mode.
Here are the compositors with which it has been tested:
Compositor | Notes | |
---|---|---|
Sway | ✅ | - |
Hyprland | ✅ | - |
niri | ✅ | - |
dwl | ✅ | - |
labwc | ✅ | - |
KWin | ❗ | The compositor doesn't support the wlr-virtual-pointer-unstable-v1 and wlr-screencopy-unstable-v1 protocols. It can still work with the --print-only option and the mouse pointer can then be moved with ydotool or similar. |
Mutter | ❌ | The compositor doesn't support any of the required protocols. |
If you are using Arch Linux, you can install the wl-kbptr
AUR package.
You can build and install the package with:
curl 'https://aur.archlinux.org/cgit/aur.git/tree/PKGBUILD?h=wl-kbptr' -o PKGBUILD
makepkg -si
If you are using NixOS, you can install the wl-kbptr
package. Nix can also be used to install wl-kbptr
on other distributions.
If you are using Chimera Linux, you can install the wl-kbptr
package which is available in the contrib repository.
apk add chimera-repo-contrib
apk add wl-kbptr
As of now there is no official package through dnf. So you will need to install the dependencies and then run the steps described in the From sources section.
sudo dnf install -y \
meson \
wayland-protocols-devel \
gcc \
libwayland-client \
cmake \
wayland-devel \
libxkbcommon-devel \
cairo-devel
You can build from sources with:
meson setup build --buildtype=release
meson compile -C build
If you want to build the target detection feature (see floating mode), you need to enable the opencv
feature:
meson setup build --buildtype=release -Dopencv=enabled
meson compile -C build
Then install with:
meson install -C build
mode Mouse {
bindsym a mode default, exec 'wl-kbptr-sway-active-win; swaymsg mode Mouse'
bindsym Shift+a mode default, exec 'wl-kbptr; swaymsg mode Mouse'
# Mouse move
bindsym h seat seat0 cursor move -15 0
bindsym j seat seat0 cursor move 0 15
bindsym k seat seat0 cursor move 0 -15
bindsym l seat seat0 cursor move 15 0
# Left button
bindsym s seat seat0 cursor press button1
bindsym --release s seat seat0 cursor release button1
# Middle button
bindsym d seat seat0 cursor press button2
bindsym --release d seat seat0 cursor release button2
# Right button
bindsym f seat seat0 cursor press button3
bindsym --release f seat seat0 cursor release button3
bindsym Escape mode default
}
bindsym $mod+g exec wl-kbptr-sway-active-win -o modes=floating','click -o mode_floating.source=detect
bindsym $mod+Shift+g mode Mouse
# Cursor submap (similar to the Mouse mode in Sway)
submap=cursor
# Jump cursor to a position
bind=,a,exec,hyprctl dispatch submap reset && wl-kbptr && hyprctl dispatch submap cursor
# Cursor movement
binde=,j,exec,wlrctl pointer move 0 10
binde=,k,exec,wlrctl pointer move 0 -10
binde=,l,exec,wlrctl pointer move 10 0
binde=,h,exec,wlrctl pointer move -10 0
# Left button
bind=,s,exec,wlrctl pointer click left
# Middle button
bind=,d,exec,wlrctl pointer click middle
# Right button
bind=,f,exec,wlrctl pointer click right
# Scroll up and down
binde=,e,exec,wlrctl pointer scroll 10 0
binde=,r,exec,wlrctl pointer scroll -10 0
# Scroll left and right
binde=,t,exec,wlrctl pointer scroll 0 -10
binde=,g,exec,wlrctl pointer scroll 0 10
# Exit cursor submap
# If you do not use cursor timeout or cursor:hide_on_key_press, you can delete its respective calls.
bind=,escape,exec,hyprctl keyword cursor:inactive_timeout 3; hyprctl keyword cursor:hide_on_key_press true; hyprctl dispatch submap reset
submap = reset
# Entrypoint
# If you do not use cursor timeout or cursor:hide_on_key_press, you can delete its respective calls.
bind=$mainMod,g,exec,hyprctl keyword cursor:inactive_timeout 0; hyprctl keyword cursor:hide_on_key_press false; hyprctl dispatch submap cursor
wl-kbptr
can be configured with a configuration file. See config.example
for an example and run wl-kbptr --help-config
for help.
xkbcommon
cairo
wayland
wayland-protocols
- With the
opencv
feature enabled: