mouse wheel support in Emacs 21.3.50

mouse wheel support in Emacs 21.3.50

[Drew Adams]

GNU Emacs 21.3.50.1 (i386-mingw-nt5.1.2600) of 2004-07-26 on BERATUNG4,
Windows XP SP1.

1. Bug?: Searching Elisp Info for "wheel" shows nothing that is current. It
shows the same stuff as for Emacs 20 ("mouse-wheel"...). Yet, looking at
real mouse wheel events, I see stuff like wheel-up that is not in Info, and
I don't see "mouse-wheel" in real events.

2. What is the latest mouse wheel support? In this version of Emacs
(21.3.50.1), I see mwheel code with no version number, copyright ... 2002.
Is that the latest? Is there any doc for this, besides the source code
comments?

3. I'd like to know how to interpret the components of the various mouse
events. In Emacs 20 this was simple; there was just the POSITION and the
DELTA. Now I see lots of components (with no Elisp Info) - what does each
mean? In particular, if I call read-event and get mouse wheel events, where
can I get the DELTA info that used to be there?

Actually, I can pretty much see what's going on in mwheel-scroll, in terms
of getting the DELTA info (amount), but before I base new code on what
happens in (this 2002) mwheel-scroll code, I wonder if this is a good model;
that is, if this deals with the latest event structure and is the
recommended (i.e. current) way to go about things.

4. Also, how to interpret the various mouse wheel events that I see via
apropos, such as double-wheel-up? Double-clicking I understand, but what is
double-wheeling? And the whole treatment of the wheel as buttons 4 & 5 is
not clear to me. (I imagine that is behind this business of
double-wheeling.) And what if (as I do) I have 5 mouse buttons and a wheel?
I can see that mouse-4 and mouse-5 are correctly bound to real buttons, so
what is their relation to wheeling?

5. Finally, although I have little real hope for this, are there any
guidelines for trying to make code that deals with making the mouse wheel
work in both Emacs 20 and 21? Don't laugh; there are lots of people who use
GNU Emacs 20 - maybe as many as use XEmacs - and who will continue to do so
for one reason or another. It sometimes seems to me that the mapping
(upgrade path, compatibility matrix) between GNU Emacs versions is less well
documented than the mapping between current XEmacs and GNU Emacs. Maybe
that's the way it should be; maybe not. No holy war here, please.

Thanks,

  Drew

Re: mouse wheel support in Emacs 21.3.50

[Stefan Monnier]

> 2. What is the latest mouse wheel support? In this version of Emacs
> (21.3.50.1), I see mwheel code with no version number, copyright ... 2002.
> Is that the latest? Is there any doc for this, besides the source code
> comments?

I'm not sure what you mean by "latest mouse wheel support".
If you're asking about development external to Emacs, I don't don't know of
any such thing.

> 3. I'd like to know how to interpret the components of the various mouse
> events. In Emacs 20 this was simple; there was just the POSITION and the
> DELTA. Now I see lots of components (with no Elisp Info) - what does each
> mean? In particular, if I call read-event and get mouse wheel events, where
> can I get the DELTA info that used to be there?

I don't know w32, so double check it, but I believe you can extract it with
event-click-count.

> And the whole treatment of the wheel as buttons 4 & 5 is not clear to me.

AFAIK it only affects X11.

> I can see that mouse-4 and mouse-5 are correctly bound to real buttons, so
> what is their relation to wheeling?

Most Xservers are configured to map wheel events to mouse-4 and mouse-5.

> 5. Finally, although I have little real hope for this, are there any
> guidelines for trying to make code that deals with making the mouse wheel
> work in both Emacs 20 and 21?

Not that I know, and it's likely to still change in the future, at least
on X11.  What are you trying to do?  I worked on the mwheel.el code, so
I can probably help.
Note that it's not new: there was no guideline before on making mouse wheel
code work on both X11 and w32.  Now at least, it's a bit easier (tho it's
still undocumented).


        Stefan

Re: mouse wheel support in Emacs 21.3.50

[Jason Rumney]

"Drew Adams" <drew.adams@oracle.com> writes:

> 1. Bug?: Searching Elisp Info for "wheel" shows nothing that is current. It
> shows the same stuff as for Emacs 20 ("mouse-wheel"...). Yet, looking at
> real mouse wheel events, I see stuff like wheel-up that is not in Info, and
> I don't see "mouse-wheel" in real events.

I have updated the elisp manual to reflect the current implementation.

The rationale behind it was to separate out the wheel-up and
wheel-down events to make it easier for end users to rebind them (the
single mouse-wheel event was unusual in that you had to look at the
DELTA parameter to see if it was positive or negative, most mouse and
keyboard events are simpler). It also allowed us to reuse the mwheel
implementation, which had some extra features that the previous
Windows-only support did not have.

> 3. I'd like to know how to interpret the components of the various mouse
> events. In Emacs 20 this was simple; there was just the POSITION and the
> DELTA. Now I see lots of components (with no Elisp Info)

There is only POSITION (which like in the old mouse-wheel event is a list).

> In particular, if I call read-event and get mouse wheel events, where
> can I get the DELTA info that used to be there?

That is where the double- and triple- modifiers come in, for
compatibility with the mouse-4 and mouse-5 way of handling the mouse
wheel.

> Actually, I can pretty much see what's going on in mwheel-scroll, in terms
> of getting the DELTA info (amount), but before I base new code on what
> happens in (this 2002) mwheel-scroll code, I wonder if this is a good model;
> that is, if this deals with the latest event structure and is the
> recommended (i.e. current) way to go about things.

I can't see this changing unless X gets proper mouse wheel support
instead of emulating mouse-4 and -5. Unfortunately I think too many
X applications now have mouse-4 and -5 hardcoded for that to change.
One thing that could change is that mouse-4 and mouse-5 could be
translated to wheel-up and wheel-down internally by Emacs, but because
they come to Emacs as mouse button events, wheel-up and wheel-down
will not be able to change I think (eg reintroducing DELTA).

> And the whole treatment of the wheel as buttons 4 & 5 is not clear
> to me.

That is specific to X. On Windows and Mac, wheel-up and wheel-down are
used. If you want to write portable code, use mouse-wheel-up-event and
mouse-wheel-down-event to determine what events you should be dealing
with.

> And what if (as I do) I have 5 mouse buttons and a wheel?

If you are on Windows or Mac, no problem, since the wheel has its own
events. If you're on X, you'll have to map them to mouse-6 and mouse-7
or other applications will become confused (Emacs can be made to
handle them as -4 and -5, with the wheel as -6 and -7, but other
applications are not so flexible).

> 5. Finally, although I have little real hope for this, are there any
> guidelines for trying to make code that deals with making the mouse wheel
> work in both Emacs 20 and 21?

Since Emacs 20 had different mouse wheel handling for different
platforms, such guidelines would be quite complex, as would your code
for handling the differences.

I've never heard of anyone using the mouse wheel in Emacs for anything
other than its default scrolling behaviour, so I'm not sure there is
any demand for such a guide.

RE: mouse wheel support in Emacs 21.3.50

[Drew Adams]

Hi Jason,

Thanks for a detailed explanation. Very clear.

FYI, I wrote an application that lets you use the mouse wheel (or the arrow
keys) to incrementally modify Emacs things (anything, really). This is how I
treat the mouse wheel in both Emacs 20 and 21:

        (cond ;; Emacs 20 mouse wheel.
              ((and (consp evnt) (equal 'mouse-wheel (event-basic-type (car
evnt))))
               ...)
              ;; Emacs 21 mouse wheel: `mwheel.el'
              ((and (consp evnt)
                    (member (event-basic-type (car evnt)) '(wheel-up
wheel-down)))
               (let ((button (mwheel-event-button evnt)))
                 (cond ((eq button mouse-wheel-down-event) ...)
                       ((eq button mouse-wheel-up-event) ...)
                       (t (error "Bad binding in mwheel-scroll"))))

Here is the application, in case you're interested:
http://www.emacswiki.org/cgi-bin/wiki/DoReMi.

Thanks,

  Drew


-----Original Message-----From: Jason Rumney
"Drew Adams" <drew.adams@oracle.com> writes:

> 1. Bug?: Searching Elisp Info for "wheel" shows nothing that is current.
It
> shows the same stuff as for Emacs 20 ("mouse-wheel"...). Yet, looking at
> real mouse wheel events, I see stuff like wheel-up that is not in Info,
and
> I don't see "mouse-wheel" in real events.

I have updated the elisp manual to reflect the current implementation.

The rationale behind it was to separate out the wheel-up and
wheel-down events to make it easier for end users to rebind them (the
single mouse-wheel event was unusual in that you had to look at the
DELTA parameter to see if it was positive or negative, most mouse and
keyboard events are simpler). It also allowed us to reuse the mwheel
implementation, which had some extra features that the previous
Windows-only support did not have.

> 3. I'd like to know how to interpret the components of the various mouse
> events. In Emacs 20 this was simple; there was just the POSITION and the
> DELTA. Now I see lots of components (with no Elisp Info)

There is only POSITION (which like in the old mouse-wheel event is a list).

> In particular, if I call read-event and get mouse wheel events, where
> can I get the DELTA info that used to be there?

That is where the double- and triple- modifiers come in, for
compatibility with the mouse-4 and mouse-5 way of handling the mouse
wheel.

> Actually, I can pretty much see what's going on in mwheel-scroll, in terms
> of getting the DELTA info (amount), but before I base new code on what
> happens in (this 2002) mwheel-scroll code, I wonder if this is a good
model;
> that is, if this deals with the latest event structure and is the
> recommended (i.e. current) way to go about things.

I can't see this changing unless X gets proper mouse wheel support
instead of emulating mouse-4 and -5. Unfortunately I think too many
X applications now have mouse-4 and -5 hardcoded for that to change.
One thing that could change is that mouse-4 and mouse-5 could be
translated to wheel-up and wheel-down internally by Emacs, but because
they come to Emacs as mouse button events, wheel-up and wheel-down
will not be able to change I think (eg reintroducing DELTA).

> And the whole treatment of the wheel as buttons 4 & 5 is not clear
> to me.

That is specific to X. On Windows and Mac, wheel-up and wheel-down are
used. If you want to write portable code, use mouse-wheel-up-event and
mouse-wheel-down-event to determine what events you should be dealing
with.

> And what if (as I do) I have 5 mouse buttons and a wheel?

If you are on Windows or Mac, no problem, since the wheel has its own
events. If you're on X, you'll have to map them to mouse-6 and mouse-7
or other applications will become confused (Emacs can be made to
handle them as -4 and -5, with the wheel as -6 and -7, but other
applications are not so flexible).

> 5. Finally, although I have little real hope for this, are there any
> guidelines for trying to make code that deals with making the mouse wheel
> work in both Emacs 20 and 21?

Since Emacs 20 had different mouse wheel handling for different
platforms, such guidelines would be quite complex, as would your code
for handling the differences.

I've never heard of anyone using the mouse wheel in Emacs for anything
other than its default scrolling behaviour, so I'm not sure there is
any demand for such a guide.