Go through normal keymapsscratch/low-level-key

In this new version I changed the way events are handled.
Now llk-handle generates input events to be used with normal
keymaps, instead of running a command. The function llk-bind
activates event generation for a key and a combination of
events press, release, double, triple.

I also made changes following your notes, such as:

- Clarification on the event's time, documentation of
  keysyms variables moved, don't limit to GUI systems.
- cl-defstruct for the event payload.
- Format and naming conventions.
- Default timeout to mouse double click timeout.

You suggested to auto generate the keysym table, but we
would still need a table to relate the Windows keys to the X
equivalent.

* doc/lispref/commands.texi (Misc Events): Adjust to new semantics.
* src/keyboard.c (syms_of_keyboard): Adust docstring.

FIXME: Old commit msg.

* lisp/low-level-key.el (New file).
(low-level-key): Struct with event data.
(llk-bindings): User bindings for low level key events.
(llk-tap-timeout): User option.
(llk-keysyms): List of available keysyms.
(llk--define-xk): Macro for defining keysyms.
(llk--define-keysyms): Build llk-keysyms.
(llk-bind): Function to create a binding.
(llk--event-history-for-tap): Event history for tap detection.
(llk--detect-n-tap): Function to detect taps.
(describe-low-level-key): Command to get information about a key.
(llk--describe): Show help buffer with information
about an event.
(llk-handle): Handler for key events.
(llk--generate-event): Generate input event for key.
(llk--generate-events): Generate input events for key.

1 files changed, 17 insertions, 24 deletions

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 32b4df6b3bf..01565727e15 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -2670,35 +2670,28 @@ size of the object beneath the gesture: image, window, etc.
 
 @cindex @code{low-level-key} event
 @item (low-level-key @var{is-key-press} @var{key} @var{modifier} @var{time} @var{frame})
-This event is sent on the physical press or release of keys, only on GUI
-systems, currently X, MS-Windows and PGTK, and only if the variable
-@code{enable-low-level-key-events} has a non-@code{nil} value.  See its
-documentation for the values it can take, that allow to filter which
-keys should generate this kind of event.
-
-@var{is-key-press} is @code{t} for a key press, @code{nil} for a key release.
-@var{time} is the event's time in milliseconds, @var{frame} is the
-frame receiving it.  @var{modifier} is @code{nil} if the key is not a
+This event is sent on the physical press or release of keys, only on
+systems where it is supported, currently X, MS-Windows and PGTK, and
+only if the variable @code{enable-low-level-key-events} has a
+non-@code{nil} value.  See its documentation for the values to use, that
+can activate the events for all or some keys.
+
+@var{is-key-press} is @code{t} for a key press, @code{nil} for a key
+release.  @var{time} is the event's time in milliseconds, as reported by
+the underlying platform, and should only be used to measure time
+intervals between events of this same kind.  @var{frame} is the frame
+receiving the event.  @var{modifier} is @code{nil} if the key is not a
 modifier key, @code{t} if it is, but it is unknown which one, or one of
 @code{shift}, @code{control}, @code{meta}, @code{alt}, @code{super},
 @code{hyper}.
 
 @var{key}, an integer, identifies the key pressed or released.  This
-number is platform dependent, but there are variables for most keys that
-can be used in place of the numbers to identify them.  For example, the
-variable @code{xk-backspace} identifies the @key{backspace} key.
-
-The names are parallel to those for KeySyms on X, as defined in
-@file{xkeysymdef.h}.  For example, @code{XK_Shift_L} (the left shift
-key), corresponds to @code{xk-shift-l}.  The @file{xkeysymdef.h} file
-defines different KeySyms for capital and small versions of letters.
-For this event, only the capital version is used, with the variables
-@code{xk-a}, @code{xk-b}, etc.
-
-These variables are initialized by calling the function @code{llk-init}.
-This function also binds a handler to this event, which allows to detect
-double taps on keys (normally modifier keys) and bind commands or
-functions to be run.  See the function @code{llk-bind}.
+number is platform dependent.
+
+This is a special event (@pxref{Special Events}), ignored by
+default. Loading @file{low-level-key.el} sets a handler
+that can generate normal input events for key press, release and multi
+tap.  See the function @code{llk-bind}.
 
 @cindex @code{preedit-text} event
 @item (preedit-text @var{arg})