Discussion of this wiki can be found here

Mouse Customizations

One major unresolved issue for many users switching to Linux is the ability to set an arbitrary (usually the middle or thumb) button on a mouse to "double click" (typically double "left click"). This wiki explains a reasonable solution to the problem, including enough additional details that most people should be able to work out how to customize their mice. These instructions rely only on X and distro-independent tools for it, so should work with most or all Linux distros with only minor changes. Parts of these instructions are known to work in multiple versions/releases of Ubuntu and Debian.

Setting Forward And Back Buttons

If all you want to do is set your four or five button mouse to use the extra buttons as "forward" and "back" buttons, you may have success with performing only a single action: edit /etc/X11/xorg.conf in the mouse section, and add the following two lines:

Option "Buttons" "7"
Option "ButtonMapping" "1 2 3 6 7"

Make sure to backup the file first, and restart X to have the effect take place. Assuming you are one of the fortunate people who only wants these functions and whose mouse buttons map as the "standard" behavior, you'll be all set. If it does not work, or you want other functions, you'll need to follow the longer details below. (END SHORTCUT)

Install Programs

First, you need to install several programs. xbindkeys allows you to map any mouse (or keyboard) event to some program. xautomation is our gateway to setting up a "double click" event and mapping keyboard events to mouse buttons, and so it is not needed if you do not plan on using this.

NOTE: xvkbd seems to be the preferred tool in other threads instead of xautomation/xte, so if you wish you can use that instead of xautomation for all the same keyboard mapping tasks if you prefer that approach. xmacro is another tool that may work to replace xte for double click.

Open a terminal and type:

sudo apt-get install xautomation
sudo apt-get install xbindkeys

Getting Button Numbers

  • Now we need to determine the "button number" of each physical button on your mouse.


This will open a window. Move your mouse cursor over it, and you'll see a lot of output in your terminal; don't worry about the output that happens when you move the mouse. One at a time, single click each button inside the "event tester" window, and note the 3rd line of output from either (or both) of the "ButtonPress" or "ButtonRelease" notices that pop up. The center item is "button X." Make a note of the number that matches each physical button on your mouse. Also note if one or more buttons do not respond.

Scroll Wheel And Getting Buttons To Respond

First, get your scroll wheel working, if you have one. This will be approximate, but other guides available cover this in great depth if you need more help. Basically, the "scroll up" and "scroll down"are 2 more buttons on your mouse, so you will need to identify this as well using xev. Then type:

sudo cp /etc/X11/xorg.conf /etc/X11/xorg.conf.backup
sudo gedit /etc/X11/xorg.conf

It is essentially to have a backup of xorg.conf, as messing it up can damage your ability to work to load your window environment. Search for "mouse." It should look something like this (although you may have additional lines):

Section "InputDevice"
        Identifier      "Configured Mouse"
        Driver          "mouse"
        Option          "CorePointer"
        Option          "Device"                "/dev/input/mice"
        Option          "Protocol"              "ExplorerPS/2"
        Option          "ZAxisMapping"          "6 7"
        Option          "Emulate3Buttons"       "true"

The only two lines we are going to touch are the "Protocol" and "ZAxisMapping" lines. Only change the Protocol line if one or more buttons did not respond. If you have unresponding buttons, chances are that you are using the PS/2 or IMPS/2 protocols, which may not allow for as many buttons (or the configuration) that you have, in which case try the ExplorerPS/2 as shown above. If you are already set to that and can't get buttons to respond (or get multiple button events in response to a single click), you probably need to use the "evdev" driver, described near the bottom of this post.

ZAxisMapping refers to the scroll wheel. Basically, the simplest way to get the scroll wheel to work is to change the "6 7" above to match the two scroll button numbers from xev.

You will need to restart X (logout & press Ctrl + Alt + Backspace) to have these changes go into effect. If you changed the protocol, you will need to resume at the beginning (getting button numbers) as they will probably have changed. If your scroll wheel still does not work, try this in the terminal (the pointer should have as many numbers as from the -pp output, each only once):

xmodmap -pp
xmodmap -e "pointer = 1 2 3 4 5 X Y 6 7 ..."

This first outputs your current mapping of buttons. Basically, this means that the number shown (in the pointer) is the button # that triggers the events normally associated with the button position (i.e., here X & Y should be replaced with your 2 scroll buttons, to get them to trigger the 6 & 7 events). Note that if you use xmodmap, you will to auto-load this each time you start X (in Gnome, go to System -> Preferences -> Sessions -> Startup, and add the xmodmap command. Also note that xmodmap takes effect immediately; you do not need to restart.

You may also need to add a "buttons" option and try remapping in xorg.conf; see the other tutorials and this site for more details.

Rearranging buttons

As mentioned above, you can use xmodmap to rearrange buttons. This is useful if, as with a marble mouse, none of the buttons are set to be the "middle" button, which can be a problem in some programs. The middle button is button position 2. For example, a mouse may have 4 buttons, which are assigned numbers 1, 3, 8, and 9. In such a situation one would use this:

xmodmap -e "pointer = 3 8 1 4 5 6 7 2 9"

to assign button 8 to be the "middle button" (and assign position 8 to button 2, which does not exist). Note that this layout is for using it left-handed, so the right- & left-click buttons are swapped ("normally" the 1 is left-click and 3 is right-click). In this case, positions which are assigned numbers 2 & 4-7 do not have any function, since this mouse does not have any of those button numbers. Again, you must run xmodmap each time you login for this to work.

Setting up double click

It's taken a while to get here, but the unique point to this howto: setting an arbitrary button to be a "double click." To follow what we're going to do, understand that there is no such thing as a "double click" event. What we are actually going to do is assign a button to give 2 "left-click" events.

Installing xautomation provided us with several tools (use "man xautomation" if you're curious), but the key one is "xte." This allows us to send arbitray mouse (& keyboard) events to the kernel. We will also make use of xbindkeys to first trap the button event. First, create .xbindkeysrc, which xbindkeys uses for trapping events:

gedit ~/.xbindkeysrc

Now type:

"/usr/bin/xte 'mouseup Y' 'mouseclick 1' 'mouseclick 1' &"


"/usr/bin/xte 'mouseclick 1' 'mouseclick 1' &"
b:Y + Release

(The difference is whether you want the double click to to respond when you first click the mouse, or only when you release the button, respectively.) Replace "Y" in "b:Y" with the button number of the button you wish to assign to double-click. Save & close this file.

xbindkeys -n -v

This starts xbindkeys running in the foreground, which means it will tell you if there are problems with your file. If you click the button Y, you should see xbindkeys provide trapping feedback upon release, and see feedback as well from button 1. Press "Ctrl + C" to stop this interface, then (if everything is working):

xbindkeys &

which will load xbindkeys in the background, and you should be set. As with xmodmap (end of the Scroll Wheel section), you need to add xbindkeys to start when X loads for this to work long-term.

Additional Keys

Basically, adding any other function to your mouse is going to use xbindkeys via the .xbindkeysrc file, except the command line will look something like this:

"/usr/bin/xte 'keydown Alt_L' 'key Left' 'keyup Alt_L' &"

This example binds "Alt + Left Arrow" to button Z, which works as "back" in Firefox (and a variety of other applications). You can read many more examples of key combinations here using "man xte" or at the xbindkeys site: http://hocwp.free.fr/xbindkeys/xbindkeys.html . The examples there mostly show to how invoke programs, but you can still get the example keys and just substitute in the example above. Also at the site are scripts (and at least one example of how to use in their config files, possibly for invoking emacs two different ways) on mapping multiple events to a single button (e.g., if single click button Z, go back; if double-click, go forward).

For those wishing to set "scroll up" & "scroll down" buttons that repeat (i.e., advance multiple times instead of just once per click), it should be possible to set up a short script that loops the xte event & a short sleep event as long as the button is held down, and invoke that script in .xbindkeysrc, but this has not actually been tested. Also note that xbindkeys is a great way to get keyboard combinations working (e.g., that useless Windows key, the multimedia keys you may have, or other random combinations to load favorite programs).

Application specific settings

See this thread. Dealing with different settings for laptops when external mouse connected- see this thread for a start.

Evdev Driver

If you have multiple scroll wheels or buttons that are not recognized, you probably need to use the evdev driver. This is a little more complicated to set up. Much of this section is stolen from another mouse guide.

First you need to identify the name of your mouse (or its receiver, if wireless):

cat /proc/bus/input/devices

Which will yield output something like this (on my computer):

 N: Name="Macintosh mouse button emulation"
 P: Phys=
 S: Sysfs=/class/input/input0
 U: Uniq=
 H: Handlers=mouse0 event0 
 B: EV=7
 B: KEY=70000 0 0 0 0 0 0 0 0
 B: REL=3

 I: Bus=0010 Vendor=001f Product=0001 Version=0100
 N: Name="PC Speaker"
 P: Phys=isa0061/input0
 S: Sysfs=/class/input/input4
 U: Uniq=
 H: Handlers=kbd event4 
 B: EV=40001
 B: SND=6

 I: Bus=0003 Vendor=05a4 Product=9998 Version=0100
 N: Name="NOVATEK USB Keyboard"
 P: Phys=usb-0000:00:1f.2-1/input0
 S: Sysfs=/class/input/input58
 U: Uniq=
 H: Handlers=kbd event1 
 B: EV=120003
 B: KEY=10000 7 ff87207a c14057ff febeffdf ffefffff ffffffff fffffffe
 B: LED=7

 I: Bus=0003 Vendor=05a4 Product=9998 Version=0100
 N: Name="NOVATEK USB Keyboard"
 P: Phys=usb-0000:00:1f.2-1/input1
 S: Sysfs=/class/input/input59
 U: Uniq=
 H: Handlers=kbd event2 
 B: EV=3
 B: KEY=c000 100000 0 0 0

 I: Bus=0003 Vendor=046d Product=c408 Version=0110
 N: Name="Logitech USB Trackball"
 P: Phys=usb-0000:00:1f.4-1/input0
 S: Sysfs=/class/input/input60
 U: Uniq=
 H: Handlers=mouse1 event3 
 B: EV=7
 B: KEY=1f0000 0 0 0 0 0 0 0 0
 B: REL=3

 I: Bus=0019 Vendor=0000 Product=0002 Version=0000
 N: Name="Power Button (FF)"
 P: Phys=button_power/button/input0
 S: Sysfs=/class/input/input61
 U: Uniq=
 H: Handlers=kbd event5 
 B: EV=3
 B: KEY=100000 0 0 0

 I: Bus=0019 Vendor=0000 Product=0001 Version=0000
 N: Name="Power Button (CM)"
 P: Phys=PNP0C0C/button/input0
 S: Sysfs=/class/input/input62
 U: Uniq=
 H: Handlers=kbd event6 
 B: EV=3
 B: KEY=100000 0 0 0 ||

You are looking for the one that implies a mouse, or the manufacturer of your mouse (not the Macintosh mouse buttom emulation) and generally would refer to "mouse" in the "Handler" line of the section; in my cases, this is the 5th entry with the name "Logitech USB Trackball". Make a note of the name line, including all capitalization exactly.

Edit (after backing up!) your xorg.conf as described above, replacing the existing mouse section section (between the "Section..." and "End Section" lines) with this:

        Identifier      "Logitech Trackball"
        Driver          "evdev"
        Option          "Name"          "Logitech USB Trackball"

replacing Identifier to reflect what you wish to call your mouse, and the Option "Name" with the name of your mouse from the output desribed above.

Then replace the

InputDevice     "configured mouse"

near the bottom of xorg.conf with this (replacing your name as needed):

InputDevice     "Logitech Trackball" "CorePointer"

NOTE: If you using a laptop where your mouse will not always be connected, use "SendCoreEvents" instead of "CorePointer". Save & close xorg.conf and restart X, then resume the guide above (note that the ZAxisMapping trick won't work with evdev). Also note with the evdev driver that some buttons will report two events (e.g., the "tilt wheel" of Logitech mice). The first button, usually the higher number, is the "start/stop" signal for the event, while the second button, usually lower and repeating, is the button you usually want to modify to change a function. A way has not yet been found on those mice to change which button is triggered (e.g., the "cruise" buttons on the Logitech MX1000 trigger buttons 4 & 5, which are the same as the scroll wheel, so you can't change the cruise effect separately from an effect on the scroll wheel).

Originally posted The Ubuntu Forums (ubuntuforums.org)

MouseCustomizations (last edited 2012-07-18 11:06:19 by elfy)