Mapping the Mouse Buttons onto the
Keyboard in XFree86

By Fred Maciel

Japanese language version


This page teaches how to map the mouse buttons on the keyboard on XFree86. This is useful, for instance, to make the keyboard more comfortable by making good use of the otherwise useless Windows and Menu keys.


I enjoy very much the mousepad in laptops: they allow me to move the mouse cursor without the need to move my arms between the keyboard and a mouse. However, in my laptop the mouse buttons are too far from the keyboard (as you can see in this photograph), which requires me to move my hand to an uncomfortable position to use them.

On the other hand, since my laptop is a Japanese model, its keyboard has five extra keys, three of them located at both sides of the space bar. So comes the idea: can't I map the mouse buttons onto these keys in a way that mimics the buttons (so that pressing and releasing a key would give the same result as pressing and releasing the button mapped onto it)?

On Windows I used Keylay, a keyboard remapping program, to do the mapping above. Now I can use the mouse buttons without moving the arms, and with less force since the key is softer than the button (these should also reduce the risk of cumulative trauma disorders). Also, I get a middle mouse button. Finally, the reduced vibration from not pressing the button might even extend the lifetime of the hard disk (which is located under the buttons).

Mapping the mouse button on Windows was easy, but doing the same in XFree86 was difficult. X has a feature called "Mousekeys" which allows one to map the mouse buttons and movement onto the keyboard, however Mousekeys is difficult to configure due to lack of documentation and bugs. In this page I explain the basics of Mousekeys and how to configure it. I will focus on the mouse buttons; more information on other features can be found on the links section below.

The Mousekeys Feature

As expected of X keyboard mappings, there are symbols (keysyms) that can be mapped to the keys. The main ones for the mouse buttons are:

Mousekeys has also a control that turns on and off the feature as a whole, and a timeout (the latter is useful when a user leaves a shared terminal forgetting to turn Mousekeys off).


First of all, you have to find the keycodes of the keys you want to map the buttons to. You can do this by using the xev application. I will use the keycodes of my Japanese keyboard (131, 129 and 120) in the examples below (the keycodes of the left and right windows keys and menu key are probably 115, 116 and 117, but check them with xev anyway).

Mousekeys is a feature on the X Keyboard Extension (Xkb), so be sure that Xkb is enabled in XF86Config file (the default is enabled).

Then you have to set the symbols on the keyboard. On .xinitrc, I read the symbols with xmodmap from a file that contains the lines below. This maps the keys to the buttons; shift-key combinations lock/unlock the buttons.

keycode 131 = Pointer_Button1
keycode 129 = Pointer_Button2
keycode 120 = Pointer_Button3

The mapping above will only work after Mousekeys is turned on. The on/off control is mapped by default to Shift-Numlock, which is useful for testing. To turn this feature on automatically you can use the xkbset or Freeware AccessX programs. I happen to be using xkbset, so my .xinitrc has the following lines:

# turn mousekeys on and expiry (timeout) off
xkbset m
xkbset exp =m

Please notice that, since I am turning the whole Mousekeys on, the default key bindings for Mousekeys (movement and buttons mapped to the keypad) will also be turned on.


In XFree86 up to and including 4.0.2, auto-repeat on keys mapped to buttons will always work, even when explicitly turned off on these keys. This is not a problem for clicking, but makes dragging impossible. This bug has been corrected in 4.0.3. If you are using XFree 4.0.2 or earlier, you can set the Pointer_Drag keysyms to shift-key combinations as shown below, which allows you to drag (but makes shift-click in menus awkward).

keycode 131 = Pointer_Button1 Pointer_Drag1
keycode 129 = Pointer_Button2 Pointer_Drag2
keycode 120 = Pointer_Button3 Pointer_Drag3

In Gnome 2.2 it is possible to turn on Mousekeys through the "Accessibility settings", however this turns on Slowkeys also (see here for more information). By the way, the KDE Control Center also has Mousekeys settings, but I haven't tested them.


More information on Mousekeys can be found in "The X Keyboard Extension: Library Specification" document. The XFree86 Mousekeys symbols are in the /usr/X11R6/lib/X11/xkb/compat/mousekeys file.

Stephen Montgomery-Smith's pages explain AccessX, the set of accessibility features in Xkb to which Mousekeys belongs. He created xkbset, a program to manage the XKB features, like MouseKeys, AccessX, StickyKeys, etc. He has also a Mousekeys bugfix which should work for 3.3.6 and 4.0.x.

Dan Linder's pages also explain AccessX, contain Freeware AccessX (a utility to display and set the AccessX features), and another Mousekeys bugfix.

Here is another page on How to Make Your Windows Keys Useful.


Many thanks to Stephen Montgomery-Smith for correcting the auto-repeat bugs in XFree86. Thanks also to Dan Linder and Ivan Pascal for answering my questions.


All comments and criticism on the contents above are welcome, please contact me.