liblx provides utility routines to help applications deal with keyboard
mapping state, including the conventions for determining which mapping
entry to use for a given event.  These routines associate keyboard
mapping state with an LX_CONN using a connection-private index (see
private-data for more on connection-private indices).

There are four functions involved: lx_kbmap_setup, lx_kbmap_update,
lx_kbmap_keysym, and lx_kbmap_string.  lx_kbmap_setup must be called
before any of the others are called for a given LX_CONN; otherwise, the
others produce undefined behaviour.  When the LX_OP returned by
lx_kbmap_setup completes, this subsystem is ready to process
keystrokes.  (It is actually valid to call the other functions as soon
as lx_kbmap_setup returns, but, before the LX_OP completes, everything
else is dummied out - for example, attempts to process keystrokes
return NoSymbol and zero-length strings.)

lx_kbmap_setup
--------------

LX_OP *lx_kbmap_setup(LX_CONN *xc)

Starts the initialization process for xc.  When the relevant requests
are complete, the LX_OP returned will finish.  (If the application
doesn't care about exactly when this happens, this is a use case for
lx_op_drop().  See pending-operations for more.)

lx_kbmap_update
---------------

void lx_kbmap_update(LX_CONN *xc, const LX_EVENT_MappingNotify *e)

Updates internal state according to the MappingNotify event.  You
should call this with any MappignNotify event received on xc.

lx_kbmap_keysym
---------------

LX_KEYSYM lx_kbmap_keysym(LX_CONN *xc, unsigned char kc, unsigned int st)

Maps a keystroke, keycode kc with state st, to a keysym.  If none can
be determined, returns LX_KEYSYM_NoSymbol.

lx_kbmap_string
---------------

int lx_kbmap_string(
	LX_CONN *xc,
	unsigned char kc,
	unsigned int st,
	unsigned char str[LX_KBMAP_MAX_STRING],
	LX_KEYSYM *sym	)

Maps a keystroke, keycode kc with state st, to a string.  The string is
stored through str and its length is returned; LX_KBMAP_MAX_STRING is
large enough to hold the longest string it can return.  (The length is
returned rather than NUL-terminating the string because NUL can appear
in the string.)

If sym is non-nil, the relevant keysym is stored through it.  If this
argument is nil, the keysym is not stored anywhere.  This store is
always done, even when the returned string is zero-length; if no keysym
can be determined, the keysym stored is LX_KEYSYM_NoSymbol.

Note that lx_kbmap_string has no way to return the encoding of the
returned string.  In principle it could do so, or there could be a call
to control which encoding to return.  But, until and unless we have a
client that is prepared to handle something other than octet strings in
an unspecified encoding, lx_kbmap_string handles just Latin-1.  (My
preferred evolution would be to return a string of Unicode codepoints
rather than supporting things like 8859-7 or KOI-8 or whatever.  I18n
is messy.)