The keyboard interfaces and protocols in X

[Peter Hutterer]

On Tue, Feb 15, 2022 at 05:42:39PM +0200, John Found wrote:
> On Tue, 15 Feb 2022 14:29:05 +0000
> Dave Howorth <xorg at howorth.org.uk> wrote:
> 
> > On Tue, 15 Feb 2022 15:21:07 +0200
> > John Found <johnfound at asm32.info> wrote:
> > 
> > > What is the meaning of the fields in the following structure, in the
> > > XkbGetMap reply:
> > > 
> > > KB_KEYSYMMAP     8+4n
> > > 4     LISTofCARD8    ktIndex      ; What is this?
> > > 1     CARD8          groupInfo    ; What is this?    
> > > 1     CARD8          width        ; Width of what?
> > > 2     n              nSyms        ; more or less clear
> > > 4n    LISTofKEYSYM          syms  ; clear as well.  
> > 
> > Oh, and assuming you found this in the XKB Protocol Specification then
> > the answers to your question are in the same document, I think. For
> > example groupInfo is explained on p32. Just search the document.
> 
> Please, could you explain it on this example:
> 
> 01  14  00  00  = ktIndex   - what this means?
> 02              = groupInfo - what info?
> 04              = width     - of what?
> 08  00          = 8 keysyms follow
> 34  00  00  00  = "4"
> 24  00  00  00  = "$"
> 00  00  00  00  = NULL
> 00  00  00  00  = NULL
> 34  00  00  00  = "4"
> 24  00  00  00  = "$"
> AC  20  00  00  = "€" (euro sign)
> AC  20  00  00  = "€" (euro sign)
> 
> What the constants 0x01, 0x14 (ktIndex), 0x02 (groupInfo) and 
> 0x04 (width) means?

From:
https://www.x.org/releases/X11R7.7/doc/kbproto/xkbproto.html#XKB_Protocol_Requests
"""
Key Symbol Map

The key symbol map for a key contains all of the information that a client
needs to process events generated by that key. Each key symbol mapping
reports:

    The number of groups of symbols bound to the key ( numGroups ).
    The treatment of out-of-range groups ( groupInfo ).
    The index of the key type to for each possible group ( kt_index[MaxKbdGroups] ).
    The width of the widest type associated with the key ( groupsWidth ).
    The two-dimensional (numGroups × groupsWidth) array of symbols bound to the key. 
"""

XKB is a huge spec and you will need to support virtually *all* of it to get
anywhere meaningful. Some terms that you don't know are specific terms used in
the protocol, e.g. if you do not know what group "width" is that means you do
not yet understand XKB well enough to implement a protocol parser.

And XKB is probably one of the most extensively documented protocols, both
originally and in terms of follow ups by people who had to wrap their brains
around it later.

Which is also why I said earlier: you can either become an XKB expert [1]
or use libxkbcommon. XKB isn't *hard*, it's just complicated and a lot to
implement.

Oh, and there's a PDF too https://www.x.org/docs/XKB/XKBproto.pdf in case you
want to inflict that on your ebook reader.

Cheers,
  Peter

[1] fwiw, the job market for those is rather small and you rarely get your
face on TV during a crisis