xcb keyboard button masks meaning
Usually Mask1 is Alt or Meta, Mask2 is Num lock, Mask3 is AltGr, Mask4 is Win, and Mask5 is Scroll lock, but this varies between X implementations and/or keyboard models.
Source: my own computer running X11, and various bits and pieces of code lying around on the 'net. Not all of them are consistent, e.g. some say Mod1 is Alt and Mod4 is Meta.
X11 programs normally let users configure actions corresponding to Mask1 ... Mask5, and have them sort out which key sets which mask.
You can actually configure what those keys (or any keys) are mapped to, with a utility like xmodmap
. In the X Window System there are eight modifiers. The 8 modifiers are
shift
lock
control
mod1
mod2
mod3
mod4
mod5
To see what keys are currently mapped to these modifiers you can run xmodmap -pm
, which prints the modifier map. Eg. for me the output is
xmodmap: up to 4 keys per modifier, (keycodes in parentheses):
shift Shift_L (0x32), Shift_R (0x3e)
lock Caps_Lock (0x42)
control Control_L (0x25), Control_R (0x69)
mod1 Alt_L (0x40), Alt_R (0x6c), Meta_L (0xcd)
mod2 Num_Lock (0x4d)
mod3
mod4 Super_L (0x85), Super_R (0x86), Super_L (0xce), Hyper_L (0xcf)
mod5 ISO_Level3_Shift (0x5c), Mode_switch (0xcb)
So Alt
generates mod1
, for instance.
Now to change mod1
through mod5
with xmodmap
, open ~/.Xmodmap
and write something like:
clear mod1
clear mod2
clear mod3
clear mod4
clear mod5
add mod1 = Alt_L Alt_R Meta_L
add mod2 = Num_Lock
add mod3 = ISO_Level3_Shift
add mod4 = Super_L Super_R Super_L Hyper_L
add mod5 = ISO_Level5_Shift
Then run xmodmap ~/.Xmodmap
.
And as of now, for instance, ISO_Level3_Shift
is what gives you mod3
. How you can actually get a key from your keyboard to generate the keycode that corresponds to ISO_Level3_Shift
is another challenge.
Eg. to get keycode 100
to generate ISO_Level3_Shift
(which is now mod3
), add the following to your ~/.Xmodmap
file and run xmodmap ~/.Xmodmap
.
keycode 100 = ISO_Level3_Shift
You might hear that xmodmap
is deprecated, and that you should mess with XKB config files and stuff, but using XKB is much, much, much worse.
In the X protocol, the 8 modifiers (shift
, ..., mod1
, ..., mod5
) have a bitmask associated to them. This is the bitmask that XCB implements using a C enum, and its precise values are:
enum xcb_mod_mask_t{
XCB_MOD_MASK_SHIFT = 1<<0,
XCB_MOD_MASK_LOCK = 1<<1,
XCB_MOD_MASK_CONTROL = 1<<2,
XCB_MOD_MASK_1 = 1<<3,
XCB_MOD_MASK_2 = 1<<4,
XCB_MOD_MASK_3 = 1<<5,
XCB_MOD_MASK_4 = 1<<6,
XCB_MOD_MASK_5 = 1<<7,
XCB_MOD_MASK_ANY = 1<<15,
};
These values aren't XCB's choice, but they're prescribed by the X protocol specification and you can use them when talking to the X server through the X protocol. Eg. when the X server sends you an XCB_KEY_PRESS
event, this event is a 32-byte struct, and one of its fields is a bitmask where the bits are set according to the modifiers that were pressed during that key press event. Eg. if the 3rd bit is set, it means XCB_MOD_MASK_CONTROL
is set, meaning the Control
modifier was help down.