bug#74423: Low level key events

[Po Lu via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

Eli Zaretskii <eliz@gnu.org> writes:

>> 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.

I suggest calling XKeysymToString rather than interning the numerical
value of keysyms received.  This gives users some indication of the
identity of these keysyms without tediously referring to (at times
vendor-specific) keysymdef.h files.