Input events and (interactive "e")

Input events and (interactive "e")

[Eli Zaretskii]

Am I the only one, or do we indeed fail to document that
(interactive "e") is not just for mouse events?

The ELisp manual consistently talks about mouse events only, when it
discusses how to access non-keyboard input events and how to define
functions that are run by these events.  By just reading the manual,
you might think that only mouse events have meaningful parameters in
the event list, and only commands bound to mouse events can access
them using the event-* functions But in fact, it looks like _any_
event generated by the command loop can be bound to a command, and
that command can access the event parameters by treating its argument
as a list, using (interactive "e") to get that argument.  For example,
on Windows I can do this:

 (defun my-lang-change (event)
     ""
   (interactive "e")
   (message "%S" event))
 (global-set-key [language-change] 'my-lang-change)

and the pressing Alt-Shift to switch keyboard layout will show in the
echo area the contents of the event list produced for the
language-change event.

Also, the way to bind such events to commands is not documented at
all, AFAICS.

Is all of this omitted from the documentation on purpose, or should we
add that?

And btw, what is the story behind special-event-map, and why should
events be put on that map?  E.g., is it bad that language-change event
is not on that map?

Re: Input events and (interactive "e")

[Stefan Monnier]

> And btw, what is the story behind special-event-map, and why should
> events be put on that map?

Think of "C-x <someevent> C-s".  Should "someevent" be considered as
part of the whole key-sequence for the purpose of command lookup, or is
"someevent" sufficiently special that it should be run immediately
regardless of the previous "C-x" and then ignored from the overall
key-sequence which will just read "C-x C-s"?

If the latter, then your event should be handled by special-event-map.


        Stefan

Re: Input events and (interactive "e")

[Juanma Barranquero]

On Sun, Jun 24, 2012 at 6:45 AM, Stefan Monnier
<monnier@iro.umontreal.ca> wrote:

> If the latter, then your event should be handled by special-event-map.

In that case, language-change should be in special-event-map IMO.

    Juanma

Re: Input events and (interactive "e")

[Eli Zaretskii]

> From: Juanma Barranquero <lekktu@gmail.com>
> Date: Sun, 24 Jun 2012 13:49:14 +0200
> Cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org
> 
> On Sun, Jun 24, 2012 at 6:45 AM, Stefan Monnier
> <monnier@iro.umontreal.ca> wrote:
> 
> > If the latter, then your event should be handled by special-event-map.
> 
> In that case, language-change should be in special-event-map IMO.

Right.

RE: Input events and (interactive "e")

[Drew Adams]

> Think of "C-x <someevent> C-s".  Should "someevent" be considered as
> part of the whole key-sequence for the purpose of command 
> lookup, or is "someevent" sufficiently special that it should be run
> immediately regardless of the previous "C-x" and then ignored from
> the overall key-sequence which will just read "C-x C-s"?
> If the latter, then your event should be handled by special-event-map.

1. This info was helpful to me.  I've added it to the commentary in
`thumb-frm.el', which mentions that users can substitute thumbifying for
iconifying everywhere, including, say, clicking a window-mgr minimize button.
It's good to be aware of, even if a user might never accidentally do `C-x
<click-minimize-button> C-s'.

2. I support Eli's questions about documenting `e' more generally.  No doubt
there is stuff here, too, that I and others are unaware of.

Re: Input events and (interactive "e")

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org
> Date: Sun, 24 Jun 2012 00:45:08 -0400
> 
> > And btw, what is the story behind special-event-map, and why should
> > events be put on that map?
> 
> Think of "C-x <someevent> C-s".  Should "someevent" be considered as
> part of the whole key-sequence for the purpose of command lookup, or is
> "someevent" sufficiently special that it should be run immediately
> regardless of the previous "C-x" and then ignored from the overall
> key-sequence which will just read "C-x C-s"?
> 
> If the latter, then your event should be handled by special-event-map.

Thanks, I will add something along these lines to the manual.

How about the broader question, regarding non-keyboard events and "e":
any hints and/or suggestions there?  Should I just document what I
found out and understood?

Re: Input events and (interactive "e")

[Stefan Monnier]

> How about the broader question, regarding non-keyboard events and "e":
> any hints and/or suggestions there?  Should I just document what I
> found out and understood?

IIRC, the meaning of "e" was extended so that you can have a single
command that works both for mouse-clicks and for key events.
I guess the docs were never updated accordingly.


        Stefan

Re: Input events and (interactive "e")

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org
> Date: Sun, 24 Jun 2012 14:57:44 -0400
> 
> > How about the broader question, regarding non-keyboard events and "e":
> > any hints and/or suggestions there?  Should I just document what I
> > found out and understood?
> 
> IIRC, the meaning of "e" was extended so that you can have a single
> command that works both for mouse-clicks and for key events.

I rather meant events that are neither keyboard nor mouse events.
Like delete-frame, help-echo, etc.

> I guess the docs were never updated accordingly.

OK, I will take a stab on that.

Re: Input events and (interactive "e")

[Stefan Monnier]

>> > How about the broader question, regarding non-keyboard events and "e":
>> > any hints and/or suggestions there?  Should I just document what I
>> > found out and understood?
>> IIRC, the meaning of "e" was extended so that you can have a single
>> command that works both for mouse-clicks and for key events.
> I rather meant events that are neither keyboard nor mouse events.
> Like delete-frame, help-echo, etc.

AFAIK, Emacs has never made such a distinction.


        Stefan

Re: Input events and (interactive "e")

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Sun, 24 Jun 2012 21:40:54 -0400
> Cc: emacs-devel@gnu.org
> 
> >> > How about the broader question, regarding non-keyboard events and "e":
> >> > any hints and/or suggestions there?  Should I just document what I
> >> > found out and understood?
> >> IIRC, the meaning of "e" was extended so that you can have a single
> >> command that works both for mouse-clicks and for key events.
> > I rather meant events that are neither keyboard nor mouse events.
> > Like delete-frame, help-echo, etc.
> 
> AFAIK, Emacs has never made such a distinction.

I understand, but the problem is, the manual doesn't make that clear
at all.  If you read the manual, "e" is only about mouse events,
accessing non-mouse event lists is not covered (in fact, even the fact
that they are lists is barely mentioned), and binding them to keys is
described deceptively, because the text uses KEY to describe what
should have been called EVENT.