i3/docs
Michael Stapelberg bf3cd41b5d Use libxkbcommon for translating keysyms, support all XKB groups.
fixes #1835

This commit improves the translation of keysyms to keycodes by loading
keymaps using libxkbcommon-x11 and using libxkbcommon for figuring out
the keymap, depending on each keybinding’s modifiers. This way, the
upper layers of complex layouts are now usable with i3’s bindsym
directive, such as de_neo’s layer 3 and higher.

Furthermore, the commit generalizes the handling of different XKB
groups. We formerly had support only for two separate groups, the
default group 1, and group 2. While Mode_switch is only one way to
switch to group 2, we called the binding option Mode_switch. With this
commit, the new names Group1, Group2 (an alias for Mode_switch), Group3
and Group4 are introduced for configuring bindings. This is only useful
for advanced keyboard layouts, such as people loading two keyboard
layouts and switching between them (us, ru seems to be a popular
combination).

When grabbing keys, one can only specify the modifier mask, but not an
XKB state mask (or value), so we still dynamically unbind and re-bind
keys whenever the XKB group changes.

The commit was manually tested using the following i3 config:

    bindsym Group4+n nop heya from group 4
    bindsym Group3+n nop heya from group 3
    bindsym Group2+n nop heya from group 2
    bindsym n nop heya
    bindsym shift+N nop explicit shift binding
    bindsym shift+r nop implicit shift binding
    bindcode Group2+38 nop fallback overwritten in group 2 only
    bindcode 38 nop fallback

…with the following layout:

    setxkbmap -layout "us,ua,ru,de" -variant ",winkeys,,neo" \
      -option "grp:shift_caps_toggle,grp_led:scroll" \
      -model pc104 -rules evdev

By default (xkb group 1, us layout), pressing “n” will result in the
“heya” message appearing. Pressing “a” will result in the “fallback”
message appearing. “j” is not triggered.

By pressing Shift+CapsLock you switch to the next group (xkb group 2, ua
layout). Pressing “a” will result in the “fallback overwritten in group
2 only” message, pressing “n” will still result in “heya”. “j” is not
triggered.

In the next group (xkb group 3, ru layout), pressing “a” will result in
the “fallback” message again, pressing “n” will result in “heya”,
“j” is not triggered.

In the last group (xkb group 4, de_neo layout), pressing “a” will still
result in “fallback”, pressing “n” will result in “heya”, pressing “j”
will result in “heya from group 4”.

Pressing shift+n results in “explicit shift binding”, pressing shift+r
results in “implicit shift binding”. This ensures that keysym
translation falls back to looking at non-shift keys (“r” can be used
instead of ”R”) and that the order of keybindings doesn’t play a role
(“bindsym n” does not override “bindsym shift+n”, even though it’s
specified earlier in the config).

The fallback behavior ensures use-cases such as ticket #1775 are still
covered.

Only binding keys when the X server is in the corresponding XKB group
ensures use-cases such as ticket #585 are still covered.
2015-08-26 09:56:42 +02:00
..
GPN-2009-06-27 s/i3.zekjur.net/i3wm.org/g 2011-08-28 17:44:42 +02:00
NoName-2009-03-12 docs/NoName-2009-03-12: add missing screenshot 2014-01-26 16:39:09 +01:00
slides-2012-01-25 Add presentation slides from 2012-01-25 2012-01-25 21:16:21 +00:00
slides-2012-03-16 add slides from 2012-03-16 (German) 2012-06-10 18:17:02 +02:00
asciidoc-git.conf Update copyright notices and get rid of ranges 2015-04-20 17:50:21 -04:00
bigpicture.png Some more work on the how to hack documentation 2009-04-30 17:27:58 +02:00
bigpicture.xcf Some more work on the how to hack documentation 2009-04-30 17:27:58 +02:00
debugging docs/debugging: make it clearer that you need to reload i3 2015-08-24 20:50:18 +02:00
docs.mk add docs/layout-saving 2014-04-23 19:49:50 +02:00
hacking-howto hacking-howto: re-word branches info 2015-08-10 17:31:28 +02:00
i3-pod2html pod2html: remove "(testsuite)" from title, it’s also for i3-dmenu-desktop 2012-12-24 15:27:09 +01:00
i3-sync-working.dia Add docs/testsuite 2011-09-24 20:10:01 +01:00
i3-sync-working.png Add docs/testsuite 2011-09-24 20:10:01 +01:00
i3-sync.dia Add docs/testsuite 2011-09-24 20:10:01 +01:00
i3-sync.png Add docs/testsuite 2011-09-24 20:10:01 +01:00
i3bar-protocol i3bar: don't parse markup on statusline by default 2015-03-27 19:00:32 -04:00
ipc Use libxkbcommon for translating keysyms, support all XKB groups. 2015-08-26 09:56:42 +02:00
keyboard-layer1.png docs/userguide: update keyboard-layer images, remove incomplete warning 2011-07-31 23:53:26 +02:00
keyboard-layer1.svg docs/userguide: update keyboard-layer images, remove incomplete warning 2011-07-31 23:53:26 +02:00
keyboard-layer2.png docs/userguide: update keyboard-layer images, remove incomplete warning 2011-07-31 23:53:26 +02:00
keyboard-layer2.svg Include graphic of the default keyboard layout in user’s guide 2010-03-07 21:12:59 +01:00
layout-saving Added a troubleshooting section to the restoring layout docs and described solution for vertically split containers 2015-03-21 20:41:40 +01:00
layout-saving-1.png add missing docs/layout-saving-1.png 2014-04-26 12:46:25 +02:00
logo-30.png replace the refcard with an HTML version (by SardemFF7) 2012-04-12 16:04:29 +02:00
Makefile Add stub Makefiles to allow subdir make calls 2012-07-22 19:57:48 +02:00
modes.png Update userguide 2009-10-23 19:53:36 +02:00
multi-monitor docs/multi-monitor: nVidia ≥ 302.17 works just fine (Thanks HedgeMage) 2013-04-06 22:49:14 +02:00
refcard_style.css add missing docs/refcard_style.css to git 2012-04-13 13:38:06 +02:00
refcard.html update refcard (Thanks Moritz Bandemer) 2012-06-03 17:17:11 +02:00
single_terminal.png userguide: Document most features 2009-06-01 14:59:25 +02:00
snapping.png userguide: Document most features 2009-06-01 14:59:25 +02:00
testsuite Document test coverage reporting for testcases 2015-04-01 18:19:18 -04:00
tree-layout1.png docs: add tree-*.png (for tree-migrating) 2011-01-29 18:31:09 +01:00
tree-layout2.png docs: add tree-*.png (for tree-migrating) 2011-01-29 18:31:09 +01:00
tree-shot1.png docs: add tree-*.png (for tree-migrating) 2011-01-29 18:31:09 +01:00
tree-shot2.png docs: add tree-*.png (for tree-migrating) 2011-01-29 18:31:09 +01:00
tree-shot3.png docs: add tree-*.png (for tree-migrating) 2011-01-29 18:31:09 +01:00
tree-shot4.png docs: add tree-*.png (for tree-migrating) 2011-01-29 18:31:09 +01:00
two_columns.png userguide: Document most features 2009-06-01 14:59:25 +02:00
two_terminals.png userguide: Document most features 2009-06-01 14:59:25 +02:00
userguide Use libxkbcommon for translating keysyms, support all XKB groups. 2015-08-26 09:56:42 +02:00
wsbar docs/wsbar: update (we have i3bar now, i3-wsbar is just an example) 2013-04-07 10:24:38 +02:00
wsbar.dia Add documentation for external workspace bars 2011-01-29 15:19:11 +01:00
wsbar.png Add documentation for external workspace bars 2011-01-29 15:19:11 +01:00