2d/kickstart/KEYBOARD

   1 overview:
   2 ---------
   3 x11 -->
   4   - 2 xkb(s): the x11 one (dirty partial implementation of the specs) and the
   5     xkbcommon library one (cleaned up partial implementation of the specs)
   6   - xkb x11 protocol keycode = 1 byte = linux keycode + 8
   7   - most of xkb x11 protocol was actually _not_ implemented or is hardly
   8     working.
   9   - xinput2 x11 protocol keycode is 32 bits word = linux keycode + 8
  10   - resolving a keycode to a key symbol is done client side, the xkb protocol
  11     is only there to get the mapping from the server and broken events. it is
  12     done for you in libX11 xkb submodule or in xkbcommon-x11, or you can interpret
  13     the brain f*ck*ge of xkb mapping rules yourself, but know that even libX11 xkb
  14     submodule and xkbcommon-x11 do only a partial implementation of the specs (this
  15     is not documented, the xkbcommon guys did discover it while extracting the code
  16     to make it standalone).
  17   - x11 compose key support is client side, not server side, and is user
  18     locale dependent, often reduced to the name "xim" (x input method, which it
  19     is only partial):
  20       - client libX11 xkb submodule.
  21       - client xcb-xkb + xkbcommon-x11 (xkbcommon helper module for x11 support)
  22   - linux has packed most but not all of the real keyboard keycodes out
  23     there in 8 bits, the least significant byte of its 32 bits keycode.
  24
  25 wayland -->
  26   - xkbcommon lib keycode = 32 bits word = linux keycode + 8 (keep x11 offset
  27     in order to re-use the x11 keyboard data files)
  28   - xkbcommon is the only one, but simple one can be added easily.
  29
  30 text input:
  31   - for many "scripts" (see unicode definition) the compose key is often
  32     sufficient. but you need to dynamically load the libs on the client side in
  33     order to actually locate the configuration files properly.
  34   - unicode string rendering: currently no reasonable way to do it using open
  35     source (existing is ultimate c++ cr*p), except for simple scripts (use bear
  36     freetype2).
  37   - heavy duty input methods with graphic editor support for scripts which are
  38     "alien to keyboard input":
  39        - several libs. see wikipedia for a list (scm, xcb-im, m17n...)
  40        - those libs are tightly integrated with exiting gfx toolkits
  41          (gtk, clutter...)
  42        - pseudo interfaces for basic windowing system interaction, xim for x11
  43          and there is a similar wayland interface (not used as it seems).
  44 --------------------------------------------------------------------------------
  45 first, a quick note on usb hid (Human Interface Device): such a device is
  46 actually a bunch of "controls" which can be used as buttons, axis, etc.
  47 controls have no human interface semantics attached to them and usb hid
  48 standard is doing such a thing: attaching human interface semantics to such
  49 controls (not all usb hid devices are input devices). those semantics tries to
  50 fit many common use scenarios (keyboard, mouse...), it is a bit of a grab bag.
  51 that said, there is always some "generic" semantics for the devices which don't
  52 want to deal with too usage specific semantics, for instance an array of
  53 generic programable buttons/keys.
  54 --------------------------------------------------------------------------------
  55 the 2 main cases to use a keyboard:
  56  - as a joypad with a d-pad and many buttons
  57  - for text-input (the can of worms)
  58
  59 this can become *REALLY* nasty due to the i18n(InternationalizatioN) software
  60 plumbering needed for l10n(LocalizatioN) support: some language scripts are so
  61 alien to computer input, "it should not be supported". that's why a "simple
  62 global common language with a computer input friendly script" is kind of
  63 important.
  64
  65   currently, it is english.
  66
  67 (maybe in hundreds of years or a few milleniums, earthlings, if still around,
  68 will manage to design, without being a brain f*ckage, a better/more efficient
  69 common language with a computer input friendly script to be taught globally,
  70 that without the "need" of an authoritarian regime)
  71
  72 on linux based OS (except android, coze we avoid to deal with this mega kludge),
  73 the keycode types are:
  74 usb hid "keycodes" -> linux keycodes -> x11 keycodes -> user app
  75 usb hid "keycodes" -> linux keycodes -> wayland(~x11) keycodes -> user app
  76
  77 joypad only --------------------------------------------------------------------
  78 in an international context, the only basic physical keys are those which are
  79 layout independent: arrow keys, escape, enter, delete, backspace, tabulation,
  80 etc. only the basic key events are interesting, aka press and release with the
  81 kernel keycode (ofc with minimal latency). on linux, if x11 or wayland(android
  82 may have wayland support now) can give you the linux input devices which are in
  83 your "seat" (set of monitors+set of input devices), and if you have read access
  84 to the corresponding /dev files (could be the "server" only), you can
  85 yourself interpret the usb hid frames, which are 100% operating system
  86 independent.
  87
  88 the layout independent keys do have "standard" (~usb hid) kernel keycodes. you
  89 can present to the user some gfx symbols for them, gfx symbols which would be
  90 common to the whole planet. we can presume that in any l10n (english,
  91 japanese...) the roman numbers[0-9] are understood. then for the keycodes which
  92 are not layout independent, brutally display the keycode value with roman
  93 numbers. namely, whatever the l10n, in the keyboard input context, you will
  94 need gfx symbols only for layout independent keys and roman numbers.
  95
  96 if you are sure to have the gfx symbols for keyboard keys in a specific l10n
  97 your would query the operating system to discover the user keyboard layout. on
  98 linux, this is xkb, linux and wayland (wayland could use others, but xkb is the
  99 only one for now). a big fat warning, the xkb used in wayland is actually a
 100 "lean" xkb only partially compatible with the full brain damaged x11 xkb (which
 101 actually was never 100% implemented in xorg x11 server anyway). and you have
 102 the xkbcommon library to do all the work for you.
 103
 104 key bindings remapping: for menu navigation, the bindings of the layout
 105 independent keys should be frozen. new bindings should be added only on top of
 106 them only. in game, all key bindings should be able to be remapped.
 107
 108 x11 keycodes are not exactly kernel keycodes, they have an offest of 8:
 109   - core and xkb(x11) keycodes are limited to the value from 8 to 255 by their
 110     respective x11 protocol, aka it fits in 1 byte.
 111   - xinput2 use a 32 bits word for the kernel keycode, namely the full one.
 112
 113 wayland:
 114   - from libinput, direct 32 bits word kernel keycode. If you use xkb mapping,
 115     like for x11, you would need to offset them by 8.
 116
 117 linux evdev:
 118   - kernel keycodes, with semantics attached. You will need to manage device
 119     hotplug (don't use udev), device selection (which you have read access) by
 120     navigating in /sys (which will give you the /dev file). you'll know when
 121     to read from the device when the windowing system tells you the input
 122     focus is yours. does not work with multi-seat systems except if you can
 123     query the devices of the seat and map them to the right /dev/input/eventX.
 124
 125 linux hidraw:
 126   - you need to decode and interpret hid data on top of what evdev requires
 127     you to do. but this is 100% independent from any os.
 128 joypad only end-----------------------------------------------------------------
 129
 130
 131 text input ---------------------------------------------------------------------
 132 aka, the can of worms. once in text input mode, you must use an input method
 133 which is most of the time provided by the operating system (customized by the
 134 user). keep in mind that some input methods do not need a specific graphic user
 135 interface (compose key) but some do and can behave badly with exclusive
 136 fullscreen.
 137 the other way: you provide your own input method for each of the l10ns you
 138 support (the "compose key" is implemented client side, see below).
 139 in any case, you will need to render an utf-8 string in the l10ns you support.
 140 for basic scripts (english, french...), it will be fine most of the time, but
 141 for complex scripts, you cannot... or you will have to deal with some of the
 142 worst pieces of open source software ever (at the time of writing).
 143
 144 in x11, with libX11, you have the simple xim (X Input Method) which provides
 145 compose key/dead keys. on the xcb side, the compose key/dead keys would be
 146 provided with the combo xcb-xkb & xkcommon-x11 libraries.
 147
 148 in wayland, it seems there would be some specific interfaces to deal with a
 149 user customized operating system input method.
 150 text input end------------------------------------------------------------------
 151
 152 ********************************************************************************
 153 * excessive generalization and code factorization ends up more harmful than    *
 154 * orthogonalization and code duplication, and that happens often.              *
 155 ********************************************************************************