bug#4478: 23.1; key bindings for mouse wheel - unclear

bug#4478: 23.1; key bindings for mouse wheel - unclear

[Drew Adams]

1. Doc bug: The doc is not clear about how to bind the mouse wheel
(rotations).
 
2. Code bug / enhancement request: Have a shorter way to bind wheel
actions.
 
--
 
I've been using bindings such as this:
 
(define-key map [wheel-down]   'aaa)
(define-key map [wheel-down]   'bbb)
(define-key map [C-wheel-down] 'ccc)
(define-key map [C-wheel-down] 'ddd)
 
Reading some mail on (I think) help-gnu-emacs got me a bit confused,
however. It gave me the impression that such bindings were only for MS
Windows and that on GNU/Linux `mouse-4' and `mouse-5' must be used
instead of `wheel-down' and `wheel-up'. (That sounds odd; I'd expect
`mouse-4' and `mouse-5' to be a fourth and fifth mouse button, as they
are on Windows.)
 
I looked in the Elisp manual, but I didn't find anything specifically
recommending how one should bind mouse wheel events. I was assuming
that `wheel-down' was platform independent, but now I have a doubt.
 
The Elisp doc (node Misc Events) speaks about events such as (wheel-up
POSITION), but it doesn't speak about just what to use when binding
such keys.  Further, it says that events such as (wheel-up POSITION)
are not generated on some systems and that on those systems "`mouse-4'
and `mouse-5' are used instead". (Why is that?)
 
It does say this, however: "For portable code, use the variables
`mouse-wheel-up-event' and `mouse-wheel-down-event'", and then it goes
on to say where those variables are defined (why does it say where
they are defined?).
 
So after a bit of fiddling I switched to this:
 
(define-key map (vector mouse-wheel-down-event) 'aaa)
(define-key map (vector mouse-wheel-up-event)   'bbb)
(define-key map
  (vector (list 'control mouse-wheel-down-event)) 'ccc)
(define-key map
  (vector (list 'control mouse-wheel-up-event)) 'ddd)
 
I haven't tested on GNU/Linux, but I'm assuming this is what to use
for portable code. Is there a shorter or better way to say this and
still be portable? 
 
1. If there is not, there should be (a shorter way to do this).
 
2. Until then, whatever is the current best way should at least be
documented clearly as the way to bind mouse wheel events.
 
I would even expect the Emacs manual to tell you how to bind
mouse-wheel key sequences...  But AFAICT the Emacs manual isn't too
helpful for even the basics about key binding. I filed a separate bug
(#4472) about that.
 
 
 
In GNU Emacs 23.1.1 (i386-mingw-nt5.1.2600)
 of 2009-07-29 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4)'
 

bug#4478: 23.1; key bindings for mouse wheel - unclear

[Stefan Monnier]

> 1. Doc bug: The doc is not clear about how to bind the mouse wheel
> (rotations).

Indeed.  The way to do it is currently messy and ugly.
 
> I've been using bindings such as this:
 
> (define-key map [wheel-down]   'aaa)
> (define-key map [wheel-down]   'bbb)
> (define-key map [C-wheel-down] 'ccc)
> (define-key map [C-wheel-down] 'ddd)

IIUC this is "the right way".  And it works under w32 and ns.
Under X11, sadly, mouse-wheel events are usually represented as mouse
clicks for buttons 4 and 5, and there's no way for Emacs to know whether
these correspond to mouse clicks (on mice with more than 3 buttons) or
mouse-wheel events.  Worse yet, Emacs doesn't offer an easy way to map
all the variants of `mouse-4' and `mouse-5' (with and without each of
the possible modifiers) to wheel-up and wheel-down.

The code appended below does manage to do such a remap, but as you can
see it's ugly, and worse yet: there can only be one such thing because
it uses the "default" binding.  [ And it probably won't work with
xterm-mouse-mode. ]
 
> (define-key map (vector mouse-wheel-down-event) 'aaa)
> (define-key map (vector mouse-wheel-up-event)   'bbb)
> (define-key map
>   (vector (list 'control mouse-wheel-down-event)) 'ccc)
> (define-key map
>   (vector (list 'control mouse-wheel-up-event)) 'ddd)
 
> I haven't tested on GNU/Linux, but I'm assuming this is what to use
> for portable code. Is there a shorter or better way to say this and
> still be portable? 

I think this is about as good as it gets for now, yes.
 
> 1. If there is not, there should be (a shorter way to do this).

The [wheel-down] and friends shown above is what there should be.
 

        Stefan


(define-key function-key-map [t]
	 '(menu-item "" nil
	   :filter sm-rewrite-mwheel))

(defun sm-rewrite-mwheel (ignore)
  (let* ((events (this-single-command-raw-keys))
         (event (unless (zerop (length events))
                  (aref events (1- (length events))))))
    (message "sm-rewrite-mwheel: key=%s" event)
    (case (event-basic-type event)
      (mouse-4
       (let* ((mods (delete 'click (event-modifiers event)))
              (new-key (event-convert-list (append mods '(wheel-up))))
              (new-event (cons new-key (cdr event))))
         (vector new-event)))
      (mouse-5
       (let* ((mods (delete 'click (event-modifiers event)))
              (new-key (event-convert-list (append mods '(wheel-down))))
              (new-event (cons new-key (cdr event))))
         (vector new-event))))))