ButtonMapping - Positional parameters
In an X configuration file mouse buttons can be mapped using a ButtonMapping option:
Section "InputClass"
# ...
Option "ButtonMapping" "1 9 3 4 5 6 7 8 2"
# ...
EndSection
Changing the order of the numbers changes the behaviour of the mouse buttons. Yet I cannot find any documentation that describes how the behaviour is assigned. What little documentation there is, I helped write.
For example, if the button mapping was written thus:
Option "ButtonMapping" "a b c d e f g h i"
We would document these positions as:
- a - Left click
- b - Middle
- c - Right click
- d - Scroll forward
- e - Scroll backward
- f - Forward
- g - Backward
- h - Horizontal scroll
- i - Vertical scroll
My question then: what do the positional values of a through i actually represent and how are they mapped to mouse buttons?
Update
Running xmodmap -pp shows:
$ xmodmap -pp
There are 10 pointer buttons defined.
Physical Button
Button Code
1 1
2 2
3 3
4 4
5 5
6 6
7 7
8 8
9 9
10 10
This is not useful as it contains no information a human can use about the physical attributes of the mouse (i.e., showing two columns of numbers is useless without button names, such as "left button"). So while technically this might answer the question of "how are they mapped", the question remains unanswered in any practical sense.
I think you should look at it this way:
1 2 3 4 5 6 7 8 9 <--position-- physical keys
Option "ButtonMapping" "1 9 3 4 5 6 7 8 2" <--function-- logical keys
-
The position that indicates the key id as reported by mouse (through driver). So it's up to the manufacturer how to order them, however most stick to common order.
Mouses still using the old protocols like PS2, it doesn't have a way store or tell info about available buttons and their functions. So X server can't tell you the id of each physical button, only by trying them using a tool like
xevthat shows the X events:xev -event mouseOr
evtestthat shows the raw events:sudo evtest The logical key are the ones actually mapped some where else for extra functions. At this level, X looks at them as: button1, button2, button3, button4,...,button24 and it does not know their function.
Official reference examples:
7. Configuration Examples
This section shows some example InputDevice section for popular mice.
All the examples assume that the mouse is connected to the PS/2 mouse
port, and the OS supports the PS/2 mouse initialization. It is also
assumed that /dev/mouse is a link to the PS/2 mouse port.
Logitech MouseMan+ has 4 buttons and a wheel. The following example
makes the wheel movement available as the button 5 and 6.
Section "InputDevice"
Identifier "MouseMan+"
Driver "mouse"
Option "Device" "/dev/mouse"
Option "Protocol" "MouseManPlusPS/2"
Option "Buttons" "6"
Option "ZAxisMapping" "5 6"
EndSection
You can change button number assignment using the xmodmap command
AFTER you start the X server with the above configuration. You may
not like to use the wheel as the button 2 and rather want the side
button (button 4) act like the button 2. You may also want to map the
wheel movement to the button 4 and 5. This can be done by the
following command:
xmodmap -e "pointer = 1 6 3 2 4 5"
After this command is run, the correspondence between the buttons and
button numbers will be as shown in the following table.
Physical Buttons Reported as:
------------------------------------
1 Left Button Button 1
2 Wheel Button Button 6
3 Right Button Button 3
4 Side Button Button 2
5 Wheel Negative Move Button 4
6 Wheel Positive Move Button 5
Starting in the Xorg 6.9 release, you can also achieve this in your
configuration file by adding this to the "InputDevice" section in
xorg.conf:
Option "ButtonMapping" "1 6 3 2 4 5"
For the MS IntelliMouse Explorer which as a wheel and 5 buttons, you
may have the following InputDevice section.
Section "InputDevice"
Identifier "IntelliMouse Explorer"
Driver "mouse"
Option "Device" "/dev/mouse"
Option "Protocol" "ExplorerPS/2"
Option "Buttons" "7"
Option "ZAxisMapping" "6 7"
EndSection
The IntelliMouse Explorer has 5 buttons, thus, you should give "7" to
the Buttons option if you want to map the wheel movement to buttons (6
and 7). With this configuration, the correspondence between the
buttons and button numbers will be as follows:
Physical Buttons Reported as:
------------------------------------
1 Left Button Button 1
2 Wheel Button Button 2
3 Right Button Button 3
4 Side Button 1 Button 4
5 Side Button 2 Button 5
6 Wheel Negative Move Button 6
7 Wheel Positive Move Button 7
You can change button number assignment using xmodmap AFTER you
started the X server with the above configuration.
xmodmap -e "pointer = 1 2 3 4 7 5 6"
The above command will moves the side button 2 to the button 7 and
make the wheel movement reported as the button 5 and 6. See the table
below.
Physical Buttons Reported as:
------------------------------------
1 Left Button Button 1
2 Wheel Button Button 2
3 Right Button Button 3
4 Side Button 1 Button 4
5 Side Button 2 Button 7
6 Wheel Negative Move Button 5
7 Wheel Positive Move Button 6
For the A4 Tech WinEasy mouse which has two wheels and 3 buttons, you
may have the following InputDevice section.
Section "InputDevice"
Identifier "WinEasy"
Driver "mouse"
Option "Device" "/dev/mouse"
Option "Protocol" "IMPS/2"
Option "Buttons" "7"
Option "ZAxisMapping" "4 5 6 7"
EndSection
The movement of the first wheel is mapped to the button 4 and 5. The
second wheel's movement will be reported as the buttons 6 and 7.
The Kensington Expert mouse is really a trackball. It has 4 buttons
arranged in a rectangle around the ball.
Source: ftp://ftp.x.org/pub/current/doc/mouse.txt