bug#74423: Low level key events

[Eli Zaretskii <eliz@gnu.org>]

> Date: Wed, 4 Dec 2024 22:25:32 +0100
> Cc: monnier@iro.umontreal.ca, luangruo@yahoo.com, 74423@debbugs.gnu.org
> From: Cecilio Pardo <cpardo@imayhem.com>
> 
> On 04/12/2024 21:01, Eli Zaretskii wrote:
> >> +  DEFVAR_LISP ("enable-low-level-key-events", Venable_low_level_key_events,
> >> +	       doc: /* If non-nil, reception of low-level key events is enabled.
> >> +
> >> +The value configures the set of keys that are handled:
> >> +
> >> +If t, send events for all keys.
> >> +
> >> +If a number, send events for the corresponding keysym.  When calling
> >> +'llk-init', a set of variables with the xk- prefix is initialized with
> >> +the numeric values for keysyms.  This numbers are platform dependent.
> > 
> > This seems to say that it is impossible to make the value do the same
> > on all platforms?  If so, I think it's less useful than it could be,
> > because Emacs generally tries to abstract platform-specific issues as
> > much as possible, to facilitate platform-independent Lisp programs
> > that work the same on all supported systems.
> > 
> > Also, there's no information here where to find the list of these xk-
> > numbers.
> 
> Those are variables, like xk-shift-l, xk-a, xk-f1. There is also
> llk-keysyms, that has a list of all xk-* symbols and their numeric values.
> 
> llk-init initializes all of these variables, using numbers that are 
> platform dependent (XK_* constant KeySyms for X, VK_* "virtual keys" for 
> windows. GDK keys match X keys.
> 
> Numbers are different, but users should use the variables, not the 
> numbers, for binding and comparing to event values.

This should be explicitly told in the doc string.  Also, if the xk-*
variables are platform-independent, the rule to map their names to
keyboard keys should be explained somewhere, perhaps in the manual, so
that Lisp programmers could easily know how to identify the keys which
they stand for.

> I can translate the Windows numbers to the X equivalents, so that they 
> are equal on both platforms.

I'm not sure this is needed, if the xk-* names are the same.

> In any case, I will document this better, with a manual change
> proposal.

Thanks.  This facility definitely needs to be in the ELisp manual
before we install it.