ButtonMapping - Positional parameters

Question

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.

Answer 1

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 xev that shows the X events:

  xev -event mouse
  

  Or evtest that 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