directvnc-kbmapping(7)

📦 version 0.7.8, in debian bookworm, ubuntu jammy, ubuntu noble

💖 directvnc-kbmapping — the keyboard mapping file lore, explained 💖

okay bestie, sit down, grab a strawberry 🍓, because this is the Miscellaneous Information Manual page for directvnc-kbmapping(7) — aka the deep lore on the keyboard mapping file syntax for directvnc(1). it's giving "niche but essential", and honestly? we ate. 💅

✨ Xmodmap Keyboard Layout File Syntax ✨

so the general syntax of the xmodmap keyboard layout file is fully described over in the xmodmap(1x) manual page. but for the purposes of how keyboard switching is implemented in directvnc, only a subset of that syntax gets used, and here's the tea:

  • Comments — those lines that start with an exclamation mark — are recognized as such and ignored. 🫶
  • Expressions using keycode are recognized with up to four keysym values, used as described in the manual page mentioned above.
  • Other xmodmap expressions will be ignored. periodt.

so like, the following is a valid syntax of an xmodmap file that can be converted into a directvnc keyboard layout file:

         Key    Base     Shift          Mode               Mode+Shift

keycode  13     = 4      dollar         4                  quotedbl
keycode  14     = 5      percent        5                  colon
keycode  15     = 6      asciicircum    6                  comma
keycode  16     = 7      ampersand      7                  period
keycode  24     = q      Q              Cyrillic_shorti
Cyrillic_SHORTI
keycode  25     = w      W              Cyrillic_tse       Cyrillic_TSE
keycode  26     = e      E              Cyrillic_u         Cyrillic_U
keycode  27     = r      R              Cyrillic_ka        Cyrillic_KA

An example of a xmodmap file for Cyrillic input can be found ???? 👀 (yes, the original really leaves it at that — mystery main character energy)

🌸 Directvnc Keyboard Layout File Syntax 🌸

here's the situation. the xmodmap file uses character identifiers to identify the keysyms that keycodes get translated into. and that totally works in the original xmodmap program, because that program acts as a client to the X server it loads the keyboard layout into — xmodmap literally queries the X server to convert those symbolic keysym identifiers into numeric ones. cute for xmodmap!

but directvnc is not supposed to interact with the remote Xvnc server that way. 🙅 so instead, a derivative format is used, and this one contains hexadecimal codes for keysyms:

keycode 13 0x034 0x024 0x034 0x022
keycode 14 0x035 0x025 0x035 0x03a
keycode 15 0x036 0x05e 0x036 0x02c
keycode 16 0x037 0x026 0x037 0x02e
keycode 24 0x071 0x051 0x6ca 0x6ea
keycode 25 0x077 0x057 0x6c3 0x6e3
keycode 26 0x065 0x045 0x6d5 0x6f5
keycode 27 0x072 0x052 0x6cb 0x6eb
keycode 28 0x074 0x054 0x6c5 0x6e5
keycode 29 0x079 0x059 0x6ce 0x6ee
keycode 30 0x075 0x055 0x6c7 0x6e7

and ngl, the keycode keyword does not play any role at the moment — it's just preserved for future extensions, for when other xmodmap expressions may also be recognized. lowkey foreshadowing. 🦋

🧚 Conversion From One to Another 🧚

so, as noted above, directvnc does not query the remote Xvnc server for keysyms' numeric values. what it does have is the keysymdef.h include file, which contains all the necessary information. consider this lil snippet (a small portion of the keysymdef.h file):

#define XK_Q                   0x051
#define XK_q                   0x071
#define XK_Cyrillic_shorti     0x6ca
#define XK_Cyrillic_SHORTI     0x6ea

and now it becomes clear how to convert this:

keycode 24   = q   Q   Cyrillic_shorti   Cyrillic_SHORTI

into this:

keycode 24 0x071 0x051 0x6ca 0x6ea

iconic, honestly. 💫

the directvnc-xmapconv(1) utility reads an xmodmap syntax file from standard input, and writes the directvnc compatible syntax file to standard output. ✨

and inside? the script runs its standard input through the C preprocessor, including the keysymdef.h file, and prepending each keysym identifier with XK_. and get this — the directvnc keyboard layout file we mentioned earlier was produced exactly this way out of the xmodmap file for Cyrillic input. no cap. 🔥

👑 Key Modifiers Logic 👑

the directvnc keyboard layout switching module holds an internal table, and the contents of the keyboard layout file get read into it. the module intercepts all keyboard input obtained from DirectFB, and it uses the keyboard scan code plus 8 (also known as the MIN_KEYCODE constant) as the index into that table, to determine whether any mapping exists for a given keycode.

then, the mode-locking situation: the directvnc keyboard layout switching module uses the ScrollLock key as mode lock. so:

  • when its LED is on, the third or fourth keysym would be transmitted (depending on the Shift and CapsLock status) 💡
  • when the Scroll lock LED is off, the first or the second keysym would be transmitted 🌑

The Alt or AltGr keys are not used to control keyboard mode. nope, not them.

For letters, Shift and CapsLock are XORed. For numbers, CapsLock does not apply. (math girlies rise 🎀)

and if Ctrl is pressed, or there was no keyboard layout file specified, or the keyboard layout file does not contain any mapping for a given keycode — directvnc performs its default translation of keyboard code into a keysym, using its hardcoded ISO-8859-1 translation table. fallback queen behavior, fr fr. 💜

🌈 SEE ALSO 🌈

💌 AUTHOR 💌

Dimitry Golubovsky, Loris Boillet

okay that's the whole page bestie, you're officially fluent in directvnc keyboard mapping 💅🦋

and a lil sign-off for the record books: this was the directvnc-kbmapping(7) page, dated Jul 30, 2011. mwah, go forth and map those keys. 🎀✨

📦 where this page comes from