Editing Xmodmap (section)

==Writing a xmodmap configuration file==
There are a few notable ways (TODO: add sources) to enumerate the keycodes for use with xmodmap. Considering xmodmap is part of X11, it is ideal to use X11 related programs to harvest the keycodes for binding. In this case the simplest answer would be '''xev''' tool. The '''xev''' tool allows one to not only harvest keycodes and how the machine would translate the keycode as (or even show the current binding for that key) but it also allows one to track mouse pointers for instance and how they are referenced within the X11 environment. Inevitably there is a catch when using '''xev''' tool notably with the fact that the Event Tester window has to be active within the X11 environment.

Not all keyboards will emit the same keycode for a specific key whilst at the same time not all keyboards have unique functions such as gaming keyboards having "macro" keys or multimedia keyboard having all the audio related keys. Therefore again it is best to keep in mind when switching between keyboards or when writing up a comprehensive xmodmap it is vital for one to try and test as much keys as possible on the said keyboard.

Here is a sample output of '''xev''' running with its Event Tester window active and with the letter '''a''' pressed from the keyboard:

 KeyPress event, serial 40, synthetic NO, window 0x3800001,
    root 0x1e1, subw 0x0, time 852024727, (122,40), root:(122,833),
    state 0x10, keycode 38 (keysym 0x61, a), same_screen YES,
    XLookupString gives 1 bytes: (61) "a"
    XmbLookupString gives 1 bytes: (61) "a"
    XFilterEvent returns: False

From this output, the only information needed when writing up a custom xmodmap file is the keycode mentioned. In this particular case, the keycode for the key '''a''' shows that it is keycode 38. Again bear in mind that not all keyboards may share the same keycode for all the keys.

As well as the keycode being mentioned here, xev also shows various other information. Extra information such as keysym, XLookupString and XmbLookupString shows that when the keycode 38 is being trapped by the machine - the machine interprets the keycode as the letter '''a'''.

Another way to enumerate keycodes apart from using '''xev''' is to use the '''xinput''' tool. Specifically under '''xinput''' there is a command that also shows keycodes being trapped by machine. However '''xinput''' also repeats the output of the said key on the same console as it is telling the keycode being pressed and released. Though one good benefit is that the '''xinput''' tool does not have Event Tester window unlike '''xev''' and hence does not require that window to be active in order to capture keycodes. The exact command for '''xinput''' to show the keycodes here is:

 xinput test <device name>

One will need to replace the field '''<device name>''' with either the corresponding actual device number without the paranthesis or the name of the device in quotes and without paranthesis. In order to do that one will need to enumerate the list of devices along with the device number. Which can simply be done via:

 xinput

Here is a sample output of xinput showing the list of input devices (anything that has a button which not only includes keyboards, mice, joysticks, etc but also power button for instance on the actual machine):

 ⎡ Virtual core pointer                          id=2    [master pointer  (3)]
 ⎜   ↳ Virtual core XTEST pointer                id=4    [slave  pointer  (2)]
 ⎜   ↳ Logitech USB-PS/2 Optical Mouse           id=8    [slave  pointer  (2)]
 ⎣ Virtual core keyboard                         id=3    [master keyboard (2)]
     ↳ Virtual core XTEST keyboard               id=5    [slave  keyboard (3)]
     ↳ Power Button                              id=6    [slave  keyboard (3)]
     ↳ Power Button                              id=7    [slave  keyboard (3)]
     ↳ PFU Limited  HHKB Professional JP         id=10   [slave  keyboard (3)]
     ↳ AT Translated Set 2 keyboard              id=9    [slave  keyboard (3)]

As previously mentioned this is only a sample output, not everyone's setup will be exact same.

For the '''<device name>''' that one needs to use win conjunction with '''xinput test''' command and the example to base one (in this case the PFU Limited  HHKB Professional JP is used) one could either start harvesting keycodes via either:

 xinput test 10

or:

 xinput test "PFU Limited  HHKB Professional JP"

Sample output of xinput with the letter '''a''' pressed and then released would show as this:

 key release 36 
 key press   38 
 akey release 38 

Notice in this case how the very first line shows a completely different key code compared to the latter two lines. This is to show that the Enter key was released after the command was executed therefore the Enter key would have been caught by the machine and its keycode being shown. Along with the Enter keycode in this example is being shown, so too can one see on the last line of the output that there is an erroneous character proceeeding the word '''key'''. Again this is most likely due to an '''echo''' event from the keyboard or the program. The erroneous character does not necessarily have to be the letter '''a''' it can be whatever other characters one presses on the keyboard to harvest the keycode from. For instance the output can show '''bkey release 39'''. Regardless of the output the only relevant matter is the number that it is being outputted which is required for xmodmap.

To write xmodmap entry for the keycode 38 in this case one would need to write it as:

 keycode  38 = a A

For simplicity sake only two groups ('''a''' and '''A''') are shown. Notice how there is an extra space in between the last character '''e''' and the number '''3'''. This is needed when writing xmodmap configuration file but only for keycode. The same case does not apply when writing modifiers.

Ideally it is best to dump a copy of the current xmodmap layout and then make minor changes as required. To do this one needs to dump the keymap table as well as their modifier separately into the same ASCII text file:

 xmodmap -pke >> my.xmodmap

This command dumps the output of xmodmap's current keymap table as a form of expressions suitable for xmodmap to read and apply.

 xmodmap -pm >> my.xmodmap

This command dumps the output xmodmap's current modifier map. The output is not exactly suitable for use with xmodmap as it lacks the '''add''' command (needed for appending keys to the modifier) as well as the redundant blank fields for modifiers that does not have any keys mapped to it.

Nonetheless the output is sufficient for either backing up one's current xmodmap setup and/or to base one's own custom xmodmap configuration file off.

For the list of allowed syntaxes in a xmodmap configuration file one should refer to:

 xmodmap -grammar

TODO (include links to further reading)

[[Category:Utilities]]