Note: Wayland does use xkb, but many xTools have stopped working properly (xdotool for example)
Note: This is a non-exhaustive tutorial. It is most useful for an individual looking to create a new eight level layout and understanding the syntax.
Note: A quick and dirty solution is provided. It includes a spreadsheet which automatically generates the code you need.
Understanding XKB Directory
cd /usr/share/X11/xkb/ && ls
- types - How produced keys are changed by Active Modifiers. (Shift, Control, Alt~)
Important if you want to customize the Modifier Keys.
- geometry - Used to draw keyboard graphics.
Important if you are designing a non standard piece of keyboard hardware.
- rules - Fetching the appropriate configuration for your current setup.
You will need to define this
- keycodes - The interpreter of the keycodes for keyboard hardware.
Example: Macintosh Keyboards understand the spacebar as 57
. We write it however as <SPCE>
- symbols- Which Values are assigned to what Keycodes.
This is where we will define our custom layout.
- compat - Short for Compatability.
Internal behaviour of Modifiers (Shift, Control, Alt...)
Workflow
keycodes > symbols > compat
I only touch symbols
: See below for the Quick and Dirty solution.
Symbol Maps
/symbols/us Any file in this directory follows the same structure.
partial alphanumeric_keys
xkb_symbols "basic" {
name[Group1]= "US/ASCII";
key <TLDE> { [ quoteleft, asciitilde ] };
key <AE01> { [ 1, exclam ] };
modifier_map Shift { Shift_L, Shift_R };
};
partial - Not a complete keyboard map
alphanumeric_keys Section of the keyboard being mapped. Multiple can be used
Note: If no *_keys
are specified, a complete keyboard is assumed.
"basic" - The name of the symbol map
name[Group1]= "US/ASCII"; Gives a unique name to this keyboard group.
modifier_map For editing modifier keys. (ctrl, shift, alt~)
Shift { Shift_L, Shift_R }; Not ordinarily neccessary. It maps both shifts to the shift modifier, aka level 2.
key <TLDE> The Tilde Key - Usually top left key right above Tab
key <AE01> Illustration - Composed of Three Parts, AE01
A = alphanumeric key block.
KP = Keypad
FK = Function Key
E = Row on Keyboard.
Space Key = A row
Shift Key = B row
Caps Lock = C row
Tab Key = D row
01 = Position of the key on the row.
AE01 = 1
AB02 = X
AC05 = G
[ + ] - In C Languages; Square brackets denotes a list, by which items are split by ,. The Length of the list determines the amount of levels. For example:
key<AE01> { [ Level 1 , Level 2 , Level 3 , Level 4 , Level 5 ] }
Typically, the Levels denote the following keypress with:
- No Modifier Keys
- Shift
- Alt Gr
- Shift + Alt Gr
- Custom - Unlikely to see anything beyond level 4.
In short, if you wanted to map a key to shift + altgr, your list would have to be at least four items long.
WARNING - Common Errors
Either of these lines will cause a critical error, and will leave you without a usable keyboard:
key<AE01> { [ Backspace ] }
key<AE02> { [ a, b, , C ] }
Backspace
should be BackSpace
: Pay extra careful attention to spelling.
- An empty entry should be
VoidSymbol
.
Best Safety Measure!
Backup your file that you are editting:
sudo /bin/cp /usr/share/X11/xkb/symbols/us /usr/share/X11/xkb/symbols/usBACKUP
Make a script that you can run without root password
Something like:
#!/bin/bash
sudo /bin/cp -rf /usr/share/X11/xkb/symbols/usBACKUP /usr/share/X11/xkb/symbols/us
If anything goes wrong, use your mouse to run that line of code (contained in the bash script which you gave sudoers permission to. Remember to chmod +x
to allow running as an executable.)
Backup strategies to recover a broken system
- WARNING: Keyboard & On-Screen keyboard will cease to work with the slightest error.
- Mouse will work. Typing can be done by highlighting characters, and pasting them in using middle click. In Bash, you can
return
(Pressing Enter) by pasting a linebreak.
- Keyboard will work in recovery mode in root shell. (Accessed from bash)
- You can always use a live environment to fix files.
Quick and Dirty solution
- Go here
- File > Make a Copy
- Mapper Sheet is where you define your layout.
- Single Character entries are translated into code understood by the program.
(!
becomes U0021
). Unicode supported!
- Strings are not translated and are treated as is. MAKE SURE THERE ARE NO SPELLING or CASE errors!.
- Empty Squares are automatically filled with
VoidSymbol
.
- XKB-Sort Sheet contains key groups, for example:
key <AE01> { [U0021, U0021, U0021, U0021, U0021, U0021, U0021, U0021] };
key <AE02> { [U005B, U005B, U005B, U005B, U005B, U005B, U005B, U005B] };
key <AE03> { [U005D, U005D, U005D, U005D, U005D, U005D, U005D, U005D] };
key <AE04> { [U0022, U0022, U0022, U0022, U0022, U0022, U0022, U0022] };
key <AE05> { [U002A, U002A, U002A, U002A, U002A, U002A, U002A, U002A] };
key <AE06> { [U007B, U007B, U007B, U007B, U007B, U007B, U007B, U007B] };
key <AE07> { [U007D, U007D, U007D, U007D, U007D, U007D, U007D, U007D] };
key <AE08> { [U002F, U002F, U002F, U002F, U002F, U002F, U002F, U002F] };
key <AE09> { [U0027, U0027, U0037, U0027, U0027, U0027, U0027, U0027] };
key <AE10> { [U0029, U0029, U0038, U0029, U0029, U0029, U0029, U0029] };
key <AE11> { [U0028, U0028, U0039, U0028, U0028, U0028, U0028, U0028] };
key <AE12> { [U005C, U005C, U005C, U005C, U005C, U005C, U005C, U005C] };
Changes this on all 8 levels:
1234567890-= // Physical Keys
![]"*{}/')(\ // Changed to these characters
- XKB Tab also has lines. Every other tab can be ignored (its code).
sudo vim /usr/share/X11/xkb/symbols/us
- Replace a layouts contents. Choose one you wont use. For example: I changed the colemak entry leaving the structure intact, and replaced the keys.
Lines of interest:
key.type[group1]="EIGHT_LEVEL"; // Enables 8 levels
modifier_map Control { <LFSH>, <RTSH> }; // Maps ctrl`s to shift keys.
key { [Control_R, Control_R, Control_R, Control_R, Control_R, Control_R, Control_R, Control_R] };
key { [Control_L, Control_L, Control_L, Control_L, Control_L, Control_L, Control_L, Control_L] };
include "level3(lalt_switch)" // Hold Left Alt for Level 3
include "level5(ralt_switch)" // Hold Right Alt for Level 5