Re: Additional cleanup around xterm-mouse

[Stefan Monnier]

> -@defun read-key &optional prompt
> +@defun read-key &optional prompt all-fallbacks-disabled

FWIW, I would call it "fallbacks-disabled".

> -          (key (read-key-sequence "Set key globally: " nil t)))
> +          (key (read-key-sequence
> +                "Set key globally: " nil
> +                ;; FIXME: It'd be nicer if this was set to
> +                ;; 'all-fallbacks, however that would not apply the
> +                ;; transformations applied by local-function-key-map,
> +                ;; for example control modified function keys.
> +                ;; `widget-key-sequence-read-event' queries the user
> +                ;; which key they want in this case, perhaps do the
> +                ;; same here?
> +                'downcase-last)))

The name `all-fallbacks` makes it sound like it *enables* all fallbacks.
Similarly `downcase-last` makes it sound like we'll downcase the last event.

Not sure what would be best, but I'd suggest `dont-fallback` and 
`dont-downcase-last`.

> -                  (catch 'read-key (read-key-sequence-vector prompt nil t)))
> +                  (catch 'read-key
> +                    (read-key-sequence-vector prompt nil
> +                                              (if all-fallbacks-disabled
> +                                                  'all-fallbacks
> +                                                'downcase-last))))

BTW, just like above, it might be the case that many/most uses of
`read-key` would actually prefer `dont-fallback`, so I think a FIXME
should be added here saying we should review all uses of `read-key`
to see if they would benefit from the use of the new argument.

> @@ -3490,11 +3490,11 @@ 'key-sequence
>  (defun widget-key-sequence-read-event (ev)
>    (interactive (list
>               (let ((inhibit-quit t) quit-flag)
> -               (read-event "Insert KEY, EVENT, or CODE: "))))
> +               (read-key "Insert KEY, EVENT, or CODE: " t))))
>    (let ((ev2 (and (memq 'down (event-modifiers ev))
> -               (read-event)))
> -     (tr (and (keymapp function-key-map)
> -              (lookup-key function-key-map (vector ev)))))
> +               (read-key nil t)))
> +     (tr (and (keymapp local-function-key-map)
> +              (lookup-key local-function-key-map (vector ev)))))
>      (when (and (integerp ev)
>              (or (and (<= ?0 ev) (< ev (+ ?0 (min 10 
> read-quoted-char-radix))))
>                  (and (<= ?a (downcase ev))

AFAICT this function doesn't make it possible to read double or triple clicks.
Maybe it should be consolidated with `help--read-key-sequence`.

> +   * If a key sequence is unbound, we check Vfunction_key_map to see
> +   if some trailing subsequence might be the beginning of a function
> +   key's sequence.  If so, we try to read the whole function key, and
> +   substitute its symbolic name into the key sequence.

Nowadays this deserves some serious quotes around "function key" since
function keys are normally handled in `input-decode-map` instead.

> +   * If a `down-' mouse click event is unbound, it is discarded.
> +
> +   * If a `drag-' or `double-' event is unbound, it is turned into
> +   similar click events if that would make them bound.  We try to turn
> +   `triple-' events first into `double-' events, then into clicks.
> +
> +   * If a capital letter is unbound, it is turned into a lower case
> +   letter if that would make it bound.
> +
> +   If FALLBACKS_DISABLED is Qnil, all of the above fallbacks are
> +   applied.  If it is Qall_fallbacks, then none of the fallbacks are
> +   applied.  If it is Qdowncase_last, the capital letter fallback is
> +   not applied, but all other ones are applied.

Hmm... now that I think about it, I wonder if we need to make changes in
`read_key_sequence` at all, because we can instead arrange for all keys
to be bound:

    diff --git a/lisp/subr.el b/lisp/subr.el
    index 725722cbee..1ca1d51d44 100644
    --- a/lisp/subr.el
    +++ b/lisp/subr.el
    @@ -2453,10 +2453,11 @@ memory-limit
     ;;;; Input and display facilities.
     
     (defconst read-key-empty-map (make-sparse-keymap))
    -
    +(defconst read-key-full-map
    +  (let ((map (make-sparse-keymap))) (define-key map [t] 'dummy) map))
     (defvar read-key-delay 0.01) ;Fast enough for 100Hz repeat rate, hopefully.
     
    -(defun read-key (&optional prompt)
    +(defun read-key (&optional prompt dont-fallback)
       "Read a key from the keyboard.
     Contrary to `read-event' this will not return a raw event but instead will
     obey the input decoding and translations usually done by 
`read-key-sequence'.
    @@ -2468,7 +2469,8 @@ read-key
       ;; always inherits the input method, in practice read-key does not
       ;; inherit the input method (at least not if it's based on quail).
       (let ((overriding-terminal-local-map nil)
    -       (overriding-local-map read-key-empty-map)
    +       (overriding-local-map
    +        (if dont-fallback read-key-full-map read-key-empty-map))
             (echo-keystrokes 0)
            (old-global-map (current-global-map))
             (timer (run-with-idle-timer

WDYT?

> diff --git a/src/lread.c b/src/lread.c
> index 3ef874039a..74ed474944 100644
> --- a/src/lread.c
> +++ b/src/lread.c
> @@ -782,6 +782,12 @@ DEFUN ("read-char", Fread_char, Sread_char, 0, 3, 0,
>  
>  DEFUN ("read-event", Fread_event, Sread_event, 0, 3, 0,
>         doc: /* Read an event object from the input stream.
> +
> +If you want to read mouse events (for example, to discard an expected
> +button up event inside a button down command), call `read-key' which
> +can return events via `input-decode-map' such as all mouse events
> +generated by `xterm-mouse-mode'.
> +
>  If the optional argument PROMPT is non-nil, display that as a prompt.
>  If PROMPT is nil or the string \"\", the key sequence/events that led
>  to the current command is used as the prompt.

I like that.  I'd say "decode events via" instead of "return events
via", tho.  And I'd also mention function keys since the same applies if
you want to read `f7` in a tty.


        Stefan