Contents
xmodconfig
xmodconfig is a graphical frontend for xmodmap. It allows you to configure
xmodmap files without using a texteditor or any additional application such as
xev to identify keycodes. xmodconfig simplifies configuring and managing your
keyboard-mapping as you can use only one application to do anything needed to
use xmodmap, including configuring xmodmap files, identifying keycodes, loading
and unloading specific xmodmap-files.
What's xmodmap anyway?
The xmodmap program is used to edit and display the keyboard modifier map and
keymap table that are used by client applications to convert event keycodes into
keysyms. It is usually run from the user's session startup script to configure
the keyboard according to personal tastes.
[section of xmodmap manual]
If you have a file named ~/.Xmodmap, it will be opened and presented at start. Otherwise, you will become presented your current Xmodmap. At your first start, a message saying that a backup has been created should appear. If something goes wrong while editing the Xmodmap using xmodconfig, restore this backup (see here at section Xmodmap Failure).
To change a key's mapping, go to Tools -> Find Key and press the desired key. The row containing the respective key will be selected or created, if need be. Start to change the keysym here. See Editing Xmodmap, if you are not sure which Level to choose for your keysym. You can enter letters from a-z and digits directly, e.g., type 'a' (without quote), to map a key to 'a'. It is slightly more difficult to map other characters, as you cannot, e.g., simply enter '~' into a cell. Its the simplest to go to Tools -> Find Hexcode and type the desired character there. Afterwards, paste this hexcode into the cell.
If you're done, you may test the map (Xmodmap -> Test). If everything works as expected, you can save and apply your Xmodmap. If no file name was specified before you applied or saved the Xmodmap, the file will be saved to ~/.Xmodmap.
xmodconfig will search for a xmodmap file in ~/.Xmodmap. You can change this at Settings->Preferences->Behaviour. If it exists, it will be opened and presented at start. Otherwise, your current xmodmap will be loaded and presented. You can change this one and save it (at best as ~/.Xmodmap), open a existing xmodmap file, or create a new (blank) one.
New Xmodmap, existing Xmodmap, current Xmodmap - What's the
difference?
New Xmodmap:
A blank table will be presented. You can map your keys by editing this table.
It's the simplest to use the 'Find Key' function and write the keysyms next
to
the keycode. If you apply your newly created xmodmap, it will work substituting.
Thus, if a keycode is already mapped to a keysym and you mapped it to another
keysym, the keysym you have chosen will be mapped to the key. Make sure to describe any keyboard level you want to use. If you want only one level to be changed, you have to set any Level nevertheless, otherwise, these levels will not be mapped to any keysym (using the key(-combination) does not have any effect). If a keycode
is already mapped and it is not described in your xmodmap, the old setting will
last.
This basically means that you do not have to map your complete keyboard. It is
sufficient to describe only the keys whose mappings shall be changed.
Existing Xmodmap
Open an existing Xmodmap if you have already created an Xmodmap once.
Current Xmodmap
This will load the complete keyboard mappings that are active at that moment.
Only use this option if you have not already created an Xmodmap file with
adjusted mappings.
Once the table is loaded, you can start editing it. See Editing Xmodmap for further
information.
One easy way to map a key to a specific character is to use the 'Find Hex' dialog. Just copy the character, e.g. from some Character Map of your Distribution, go to Tools->Find Hexcode and paste the character. The respective keycode is now in your clipboard. Go to the table and paste the hexcode. The proper character should be displayed as a Tooltip now.
Once the xmodmap has been edited, you may want to test the changes to be sure
anything works as expected. Go to Xmodmap->Test. If your file contains any
errors, you will be advised. In this case, any row of the table without errors will be applied, rows containing errors won't. Go to Xmodmap->Reset and correct the row containing errors. If no error will be displayed, you are able to test your
configuration by typing newly mapped keys. This can be undone by going to
Xmodmap->Reset. Please be advised that after a Xmodmap-Reset, the previously
opened file with the status it has been when it was saved will be set as your new xmodmap, not any default xmodmap file.
To avoid using any additional tool such as xev, you can find out the correct
keycode of a specific key simply by going to Tools->Find Key. Type the key you
want to map and the respective row will be selected. To use a keysym that
does not represent a letter contained in the latin alphabet or a digit (Arabic numerals, 0-9), you can either
use the keysym-definitions or its hexadecimal number. It is more convenient to use hexadecimal number. Do not forget to include the prefix x0. You can use the hexcode-converter at Tools->Find Hexcode. Just copy or write your character to the line edit and your hexadecimal number will be available at your clipboard. Copy this to the respective cell. You should now see a tooltip printing out the requested character. To use keysym-definitions, you have to enter the keys keysym at it is described at /usr/include/X11/keysymdef.h without XK_ prefix.
When you are done, choose "Apply" at the bottom right to apply your new xmodmap
or choose "OK" to apply the changes and close xmodconfig.
How to make changes permanent?
Keyboard mappings are applied by xmodmap using the command 'xmodmap .Xmodmap'
(or whatever your file name is). xmodconfig will do this for you automatically.
Depending on your distribution and window manager, these settings may get lost
once you reboot your system. Some distributions, e.g., Ubuntu, provide automatic
recognition of xmodmap files, asking you whether you want to load the file at reboot. If something similiar is not provided at your system, you have to
make sure that your Xmodmap file will be applied any time you log in at
X-Server. Various solutions are possible, once again, depending on your
distribution and window manager. One possibility is to paste the respective
command to your ~/.xinitrc BEFORE your Window Manager is started.
Here is an example of a ~/.xinitrc which applies xmodmap file ~/.Xmodmap before LXDE gets started:
#!/bin/sh
# ~/.xinitrc
# Executed by startx (run your window manager from here)
xmodmap .Xmodmap
# lxde with hal
exec ck-launch-session startlxde
You are presented 9 columns: One keycode and eight levels. Each keycode
represents one key. Each key possesses up to eight levels. At various keyboards, especially with US layout, only four levels are accessible:
- Level 1 can be reached by typing the key only
- Level 2 can be reached by typing additionally Shift
- Level 3 can be reached by typing additionally ISO_Level3_Shift (alt in most
cases)
- Level 4 can be reached by typing additionally Shift and
ISO_Level3_Shift (alt).
Some keyboards with a different keyboard layout provide more than four levels, e.g. by AltGr. You may adjust the appearance by setting a different value at the spinbox in the upper right.
In the upper left, you can enter Xmodmap directions. That's including any xmodmap expression that does not begin with "keycode". See the section "Expression Grammar" of the man page of xmodmap.
Open a file containing keyboard mappings of xmodmap. This file can either be
created directly by xmodmap: 'xmodmap -pke > .Xmodmap' or it can be created
using xmodconfig. Syntax is:
<keycode> = <keysym 1> [...] <keysym n>
n is maximum 8. e.g.:
keycode 53 = x X x X
Xmodmap files are usually stored at ~/.Xmodmap.
Xmodmaps can be saved at Xmodmap->Save. They will be saved automatically when you apply the Xmodmap. Standard file is ~/.Xmodmap. Files will be saved at this path if the file was not opened from any other path (including the current Xmodmap).
If you want to test specific key mappings, use these options. Your current
Xmodmap will be applied using "Test", your old Xmodmap can be set using "Reset".
This is achieved by creating a temporary file which will be deleted when using
Reset or closing xmodconfig.
Please note that any changes will not take effect immediately. You have to restart the application or change the contents of the table, i.e., load a new file.
Appearance
Change any preferences concerning the tables appearance here.
Behaviour
Setup anything concerning the way of processing xmodmaps here.
Files:
Your standard Xmodmap file. The xmodmap file can be loaded any time the program starts.
Missing Columns:
A "Missing Column" is any column that has been set invisible. This can be done by changing the spinbox' value at the upper right. Data contained in these invisible columns does not get lost, as you can see, as it appears again when increasing the spinbox' value. Choose "Leave Blank" if you do not want any data of these invisible columns to be written in any file. Choose "Leave their previous values" if you want to ignore the character of invisible columns and have data of any column being written in a file.
Tooltips:
Tooltips inform you about the meaning of keysyms. When having some cryptic keysyms or, especially, hex character indexes, it may be useful to be aware of the character it represents. In case some problems occur while the table becomes changed (loading a file, changing a cell etc.), disable this option.
Usage: xmodconfig [OPTION]
Options
--help displays this help message
--xml=[KEYSYMFILE] create new xml file using [KEYSYMFILE] as header file
--restore restore first backup
--xml is used to create a new xml file containing keysym names as recognized by xmodmap, the hexcodes and the comments included in the keysymfile. the keysymfile can usually be found at /usr/include/X11/keysymdef.h. The xml file being created is needed to use tooltips. It is included by xmodconfig usually, so there is no need to create a new one. In fact, this switch is only needed for developing issues.
--restore is used to restore the backup that was created at first launch. You have to declare the outputfile as [FILE]. Not existing files will not be overwritten, so make sure the declared file does not already exist.
General approach
xmodconfig is still beta, thus some feature may lead to difficulties. Please report bugs to Fabian.Muscariello91@googlemail.com and describe, how one can reproduce the bug. Most critical is, in my experience, the tooltips that change automatically once you change any item. If problems occur when changing items, disable this feature.
"Find Key" function does not work
If pressing specific keys does not have any effect, i.e., the dialog does not disappear and the respective keycode is not shown, it is most likely that this key is not associated with any keycode. This may be because some other program, e.g. xbindkeys, grabs these keys.
Another possibility, especially with multimedia-keys is that the keys scancode is not associated with any keycode. You can check this by pressing the key and view the output of '$ dmesg|tail -10'. Look for some output like this:
atkbd.c: Unknown key pressed (translated set 2, code 0xf1 on isa0060/serio0).
atkbd.c: Use 'setkeycodes e071 <keycode>' to make it known.
Follow the messages advice and associate the keys scancode with a keycode using setkeycodes.
If you do not get any output like this, you might want to check if xev gives you any output. If it does not, chances are small that you get this key working with linux. Some manufacturers, e.g. cherry, provide kernel patches for some of their products.
Xmodmap Failure
If something goes wrong and your Xmodmap cannot be applied after editing, you always have the possibility to restore the backup created at the first start. It is stored at '~/.config/xmodconfig/xmodmap.backup'. You can either copy and apply it by hand or use xmodconfigs commandline switch. Use a shell to run, e.g.:
xmodconfig --restore ~/.Xmodmap
to restore and apply your backup.
Error Messages
File could not be saved
If you receive any message involving this, you probably do not have sufficient rights at the chosen directory. Especially Default Maps cannot be changed directly. To use any of these maps and change it afterwards, you have to load it (Tools -> Create Default Map) and save it with a new file name. Any changes will take effect at your new file.