API for reading xkb_mod_index_t to keysym mapping

[gatispaeglis]

The documentation could be improved for xkb_keymap_mod_get_name() to describe the historical meaning of Mod1-Mod5 names. For someone who has never worked with linux, using these APIs can be difficult (for example a student wanting to write a native application on Linux, without using Qt or GTK). Only very few people truly understand the internals of Virtual vs Real modifiers (the X11 legacy). For example with 'us' keymap we see that Shift + Alt = Meta:

# alt key on level 2 (e.g. when holding Shift) becomes Meta key
key <LALT>               {  [           Alt_L,          Meta_L ] };

xkb_state_mod_name_is_active(state, "Meta", XKB_STATE_MODS_EFFECTIVE) == false

but without deep understanding of XKB keymaps and X11 legacy, one would expect this to return 'true'; on my system Meta is mapped to "Mod1" (default on Ubuntu). X11 clients can get mod-to-keysym mapping from X server. The same info AFAICT is present in the keymap. XKB should prove API to extract / read this mapping.

The XKB spec also says "keysyms, when bound to modifiers, affect the rules [..]", but without this API we can't know which keysyms are bound to Mod1-Mod5.

[gatispaeglis]

Or perhaps a better solution would be that libxkbcommon remaps keys that are bound to Mod1-Mod5 to "virtual" names. A user of API should not care that Alt or Meta is bound to Mod1 or Mod3, they should be able to use:

xkb_state_mod_name_is_active(state, "Meta", XKB_STATE_MODS_EFFECTIVE)
xkb_state_mod_name_is_active(state, "Alt", XKB_STATE_MODS_EFFECTIVE)

[bluetech]

I agree, there is indeed some lore around these names. I'll try to find some time to consider this more carefully.

You may be interested in two things:

• The xkbcommon-names.h which is an attempt to sort-of do it statically.

• An unfinished PR #36 which aims to remove some cases where the distinction between real and virtual modifiers leaks. But it needs some work as far as I can remember.

[gatispaeglis]

The xkbcommon-names.h which is an attempt to sort-of do it statically.

That file has had only one small change after the initial commit in 2012. I always assumed that it is somewhat a temporary solution.

An unfinished PR #36

Sorry, I did not see it before creating this issue. I use github very seldom, now that tab looks like an obvious place to to check for whats baking :) I will add a comment on #36

[bam80]

Ping? We still don't have good solution for https://bugreports.qt.io/browse/QTBUG-62102 without it. I'm going to just hardcode things there, not sure how good it is.

[wismill]

There is another attempt with PR #353.

[wismill]

Yet another attempt with #512.