clicker

clicker maps a keyboard key to a mouse button on Linux. By default, the = key sends a left click.

A Wayland compositor (the display server for Wayland) has no function to map a key to a mouse button. The X11 tools that did this (xbindkeys, xdotool) do not operate under Wayland.

clicker does the remap in the input layer of the kernel instead. It grabs the keyboard with EVIOCGRAB. A grab gives clicker the only access to the key events, thus the compositor does not receive them. clicker then sends the events again through two virtual uinput devices: a keyboard for all the other keys, and a pointer for the button. The display server receives an ordinary mouse click. clicker thus operates the same under Wayland, X11 and the console.

clicker maps press and release one to one. If you hold the key down, the button stays down, and you can drag.

Requirements

You must have Linux and root permission. A read of /dev/input and a write to /dev/uinput are privileged operations. You must also have Python 3 with python-evdev.

sudo dnf install python3-evdev      # Fedora
sudo apt install python3-evdev      # Debian, Ubuntu
sudo pacman -S python-evdev         # Arch

Usage

There is nothing to install and nothing to configure. Start the script:

sudo ./clicker.py

Press = to send a click. To stop clicker and give the key back, press Ctrl-C.

Options

--key KEY_EQUAL      the key to remap
--button BTN_LEFT    the button to send in place of the key
--device NAME        which keyboard to remap, if you have more than one
                     keyboard
--list               list the keyboards that clicker can remap

Names are Linux input codes from input-event-codes.h, for example KEY_CAPSLOCK, KEY_F13, BTN_RIGHT and BTN_MIDDLE. To send a middle click from the Caps Lock key:

sudo ./clicker.py --key KEY_CAPSLOCK --button BTN_MIDDLE

clicker remaps one keyboard at a time. If you have a laptop keyboard and an external keyboard, --list shows both of them and --device selects one. To remap both keyboards, start a second instance of clicker.

Operation as a service (optional)

The file clicker.service keeps the remap after a reboot. The unit starts /usr/local/bin/clicker, thus you must install the script at that path:

sudo install -m 755 clicker.py /usr/local/bin/clicker
sudo install -m 644 clicker.service /etc/systemd/system/
sudo systemctl daemon-reload

sudo systemctl start clicker      # start now
sudo systemctl stop clicker       # stop now
sudo systemctl enable clicker     # start at each boot
sudo systemctl disable clicker    # do not start at boot

The unit gives the key and the button on the command line. To change the mapping, edit ExecStart in /etc/systemd/system/clicker.service. Then start the service again:

sudo systemctl daemon-reload && sudo systemctl restart clicker

Caveats

Select a key that you do not type with. The remap occurs before the keymap, thus the key no longer makes characters. With the default mapping, Shift+= also sends a click and does not send +.

clicker holds a grab on the keyboard while it operates. If clicker stops and does not respond, the keyboard also does not respond. You must then stop the process with the mouse, or from a different machine with SSH. Ctrl-C is a keystroke, thus you cannot use it.

License

MIT