Binding Mouse Buttons in XOrg!

This is almost purely a selfish article as I am tired of having to find that obscure post on some random forum every time I install a new FreeBSD desktop.

Got one of them new fangled mice things with more buttons on it than Steve Job's can count? Keep getting annoyed when accidentally hitting them and your browser/window manager starts flipping the fuck out? You're not alone, even though Google Search Results would suggest otherwise.

There are a couple of little additional X applications you will probably need to install before we get started, so let's dive in:


The general way this works is that we use xbindkeys to capture any xinput that we specify in the rc file and then tell it to run the virtual keyboard (xvkbd) to execute a 'key' for us. Simple enough.

First of all lets see which xevent mouse button your mouse fires when you press it. Run xev, which will throw up a small x window called 'Event Tester' and spam your console/terminal with all kinds of rubbish. This rubbish tells you exactly what the xorg event system sees when you do something in that window. For example :

MotionNotify event, serial 34, synthetic NO, window 0x3200001,
	root 0x154, subw 0x0, time 98294418, (67,112), root:(944,542),
	state 0x10, is_hint 0, same_screen YES

ButtonPress event, serial 34, synthetic NO, window 0x3200001,
	root 0x154, subw 0x0, time 98294594, (67,112), root:(944,542),
	state 0x10, button 1, same_screen YES

ButtonRelease event, serial 34, synthetic NO, window 0x3200001,
	root 0x154, subw 0x0, time 98294722, (67,112), root:(944,542),
	state 0x110, button 1, same_screen YES

The above output tells us that the mouse has moved (MotionNotify) in the window, then mouse button 1 was pressed (ButtonPressed) and released (ButtonRelease). In the ButtonPress/Release events you can see there is, on the bottom line a field called 'button', this is the important bit for us.

When you press one of your extra mouse buttons, you should get a higher number, for example the Logitech MX518 side/thumb buttons should show as button 8 and button 9. If you do not get any events when you press these buttons, it's likely that XOrg has not detected all the buttons for you. You may need to edit your xorg.conf file (on FreeBSD this will be in /etc/X11/xorg.conf) and tell it to map some extra buttons for your mouse.

There will be a few sections marked "InputDevice", one of them should have an Identifier of something like "Mouse0".

Section "InputDevice" 
	# generated from default
	Identifier     "Mouse0"
	Driver         "mouse"
	Option         "Protocol" "auto" 
	Option         "Device" "/dev/sysmouse"
	Option         "Emulate3Buttons" "no" 
	Option         "ZAxisMapping" "4 5"

In here you'll need to add an extra option before the EndSection:

Option         "ButtonMapping" "1 2 3 4 5 6 7 8 9" 

Do that and restart your Xorg session, if that doesn't come back, you've done something wrong and well quite frankly I can't explain how to add an Option to an xorg.conf config any better than that, so you're on your own.

So.. great! now we have the button numbers we need for xbindkeys. In your home directory, create a file called .xbindkeysrc. Add the following :

"/usr/local/bin/xvkbd -xsendevent -text "\\[Page_Down]""
 m:0x0 + b:8
"/usr/local/bin/xvkbd -xsendevent -text "\\[Page_Up]""
 m:0x0 + b:9 

Fairly simple really, there are two 'binds' in this file. Two lines per command, the first line tells xbindkeys what to do. The second line tells it when to do it. In the first bind, we want to execute xvkdb with the options -xsendevent so that it fires an xevent to xorg and -text "\[Page_Down]" to tell it what key to send.

Then the second line in that bind tells xbindkeys which event to catch, in this case 'm:0x0' = mouse and 'b:8' = button 8 on that mouse.

Once you've conjublated that, save it and simply run xbindkeys from your console/terminal and everything should be golden. After that all you need to do is tell your xorg/window manager to run xbindkeys each time you start up.

If none of that makes sense, well congratulations for reading this far, when you are at your next big party you can boast that you know how to bind custom keys/xevents to your extra unconfigured mouse buttons your unix workstation's Xserver just before you sheepishly go and hide in the kitchen next to the fridge and get toasted on free beer.

Bucket of win, table 1! athankyouplease!


Is there a way to make it work in, for example, wine apps?

By Asmageddon |

Heavy Engine Console
Loading Page... /1106-Binding-Mouse-Buttons-in-XOrg