How to customise keyboard mappings with Wayland

Question

I use Linux on a Macbook with a UK/GB keyboard and I customize the keymap to solve some problems Apple's weird keyboard layout causes. I use xmodmap to do this. I'd like to try Wayland, but xmodmap doesn't work in that. How can I achieve a similar result in Wayland? The .Xmodmap file I use contains the following:

keycode  12 = 3 numbersign 3 sterling sterling sterling threesuperior sterling
clear Control
clear Mod4
add Control = Control_L Super_R
add Mod4 = Super_L
keysym Caps_Lock = NoSymbol Caps_Lock

Line 1: On UK keyboards Shift-3 is £, so # usually has its own key near Return. But on the Mac # is obtained with Altgr-3. As a programmer I use # far more than £ so this line swaps them over. Selecting US layout also achieves this, but doing that in Linux also swaps some other commonly used keys, whereas in OS X those other keys are unaffected by US/UK.

Lines 2-5: Make the right Cmd key act as Right-Ctrl, because this keyboard has no physical right Ctrl key.

Line 6: Makes CapsLock only work if you press it with Shift. Not Mac-specific, this should be a standard option for all OSs and keyboards.

Answer 1

Unfortunately modifying the system XKB database in /usr/share/X11/xkb is the only way; from your other question it looks like you've gotten that part working.

The limitation is mostly due to the immaturity of Wayland and a design oversight in XKB.

• Tools like setxkbmap and xkbcomp provide an -I option to add a user-defined database to search (eg ~/.xkb or ~/.config/xkb, with files and subdirectories laid out like the system database). These tools interact with the X server, so they might be useful configuring the Xwayland compatibility layer for running X applications under Wayland. But they do not at present speak the Wayland protocols.

• Wayland protocols are still maturing. Currently it seems the input-method and text-input protocols are most relevant, and both are unstable. Neither mention anything about altering a defined keymap; these details are left to the compositor.

• GNOME and KDE both provide keyboard-handling settings daemons that should handle system XKB options, including changing on the fly. To the best of my knowledge, there's no way to tell either about user customizations. As far as I know, Weston and other compositors rely on config files or environment variables to set XKB options at startup, and provide no way to change them other than exiting and restarting.

• Even in XKB itself, this is not fully supported. Your custom symbols file can include other system symbols files. But at present there's no include functionality for XKB rules files, so even if you had a tool that would talk to the Wayland compositor and would look up your personal customizations, you'd have to manually include all the rules you want to use (ie copy rules/evdev* from the system XKB and modify it). libxkbcommon has an open issue on this topic and a related bug.

Answer 2

I've been using Interception Tools for Linux with success for this, and know of people producing other plugins for their custom mappings too. caps2esc is a first proof-of-concept plugin that I use everyday, and works both on X and Wayland. The tool is a bit lower level than usual mapping software, but quite flexible, and my plan for a next plugin is a generalized chording mapping tool.

Disclaimer: I'm the author.

Answer 3

The top answer in addition to https://unix.stackexchange.com/a/215062 is very helpful, but it is not necessary to edit the system xkb files.

https://xkbcommon.org/doc/current/md_doc_user_configuration.html helpfully says you can put the symbol file in $XDG_CONFIG_HOME/xkb/symbols/<name> and custom rules in $XDG_CONFIG_HOME/xkb/rules/evdev

I could then in sway easily load my custom symbol file.

So for a full example, where I added åäö to US dvorak:
$XDG_CONFIG_HOME/xkb/symbols/swedish_letters_on_dvorak

xkb_symbols "sweletters" {
    //å on alt+u (qwerty f)
    key <AC04> { [     u,   U, aring,       Aring           ]   };
    //ä on alt+e (qwerty d)
    key <AC03> { [     e,   E, adiaeresis,  Adiaeresis      ]   };
    //ö on alt+o (qwerty s)
    key <AC02> { [     o,   O, odiaeresis,  Odiaeresis      ]   };
    // make right alt altGr
    include "level3(ralt_switch)"
};

$XDG_CONFIG_HOME/xkb/rules/evdev

! option = symbols
  swedish_letters_on_dvorak:sweletters    = +swedish_letters_on_dvorak(sweletters)
! include %S/evdev

(and in my sway config)

input type:keyboard {
    xkb_layout "us"
    xkb_variant "dvorak"
    xkb_options "caps:escape,swedish_letters_on_dvorak:sweletters"
}

Answer 4

For those coming here in 2018 (Ubuntu 17.10), the most critical part of this can be accomplished using the GNOME Tweak Tool.

Gnome Tweak Tool > Keyboard & Mouse > Additional Layout Options > Ctrl is mapped to Win keys (and the usual Ctrl keys).

Answer 5

This answer has the same idea as quickotic's answer but just with a more detailed example:

Gnome Tweaks have a list of 20 or 30 keyboard tweaks you can do via xkb. Sometime you can find the tweak you're looking for by default. In my case, I wanted to swap printscreen key with Menu.

The only option to modify the printscr key available via xkb was to replace it with Win_R. Gunnar Hjalmarsson on this thread suggested to me that I modify xkb's modifications so that the printscr/win_r would do printscr/menu instead. We worked out a solution together and I'm going to retransmit it here:

In terminal, enter:

sudo su
nano /usr/share/X11/xkb/symbols/altwin

At the bottom of the file you will find:

// Win is mapped to the PrtSc key (and the usual Win key).
partial modifier_keys
xkb_symbols "prtsc_rwin" {
    replace key <PRSC> { [ Super_R, Super_R ] };
    modifier_map Mod4 { <PRSC>, <RWIN> };
};

Delete this section and replace it with this:

// Menu is mapped to the PrtSc key (and the usual Win key).
xkb_symbols "prtsc_rwin" {
     replace key <PRSC> { [ Menu, Menu ] };
     modifier_map Mod4 { <PRSC>, <MENU> };
};

To delete in nano, use backspace key (highlighting and deleting doesn't work). To paste, use shift-ctrl-v. To exit and save, press ctrl-x, select yes to overwrite and press enter.

Reboot. In Gnome/Ubuntu Go to gnome-tweak-tools In tweak tools go to Keyboard & Mouse section, press the Additional Layout Options button and expand Alt/Win key behavior. Selecting the option on the very bottom: Win is mapped to printscr (remember that we've modified just this behavior to swap print and Menu instead of print and Win). (I'm sure there is a way of turning on the modded xkb option in KDE but I don't use it, so I can't give you the exact procedure).

Answer 6

I've had joy doing this with udev. It is a little more tricky, but it is so low-level that it doesn't care what window manager, or desktop manager you are using...

Here is the detail:

~ ❯ cat /etc/udev/hwdb.d/63-capslock-to-esc.hwdb
### from https://github.com/gkovacs/udev-key-remapping
### Input device ID: bus 0x11 vendor 0x1 product 0x1 version 0xab41
### obtained from running `evtest /dev/input/event3`
### The below line is then created using the Input device ID data from above
### using evdev:input:b${bus}v${vendor}p${product} as a pattern
evdev:input:b0011v0001p0001*
  KEYBOARD_KEY_3a=esc # key marked caps lock -> esc
~ ❯ 

Credit to this github repo for the suggestion.

Answer 7

If you want to remap your keyboard keys or mouse buttons to certain keys, use "Input Remapper" by sezanzeb. It's VERY simple, it has a GUI, and it just WORKS. I just have set a certain shortcut to simulate a keyboard key, works well.