From: Stefan Monnier <monnier@iro.umontreal.ca>
Date: Wed, 24 Jan 2024 17:57:33 +0000 (-0500)
Subject: Take stock of the wheel-up/down confusion
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=581d95788dcaa4a5b2c5e98a34b8bce6f713a6f8;p=emacs.git

Take stock of the wheel-up/down confusion

While we're hopefully all aware of the usual confusion between
the scroll operation moving the document or moving the viewport, Emacs
has its very own instance of that confusion where the
`mouse-wheel-down-event` variable is the one that (used to) hold
the value `wheel-up` and vice versa.

Thanks for Po Lu's commit 957b4f826a4 which not only fixed my change
but brought that confusion to my attention.
This patch doesn't fix the problem, but tries to fix the other places
in the code where we did not take it into account.

* doc/lispref/commands.texi (Misc Events): Mention the
wheel-up/down confusion.

* lisp/progmodes/flymake.el (flymake--mode-line-counter-map):
* lisp/completion-preview.el (completion-preview--mouse-map):
Fix wheel-up/down confusion.

* lisp/mwheel.el (mouse-wheel-down-event, mouse-wheel-up-event):
Fix docstrings.

(cherry picked from commit 1f3371b46e8a6a51f88c56785175b48af2a0bed7)
---

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 5f840ac21ec..6c8d42337d0 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -2567,6 +2567,9 @@ some kinds of systems.  On other systems, other events like @code{mouse-4} and
 @code{wheel-up} and @code{wheel-down} events as well as the events
 specified in the variables @code{mouse-wheel-up-event} and
 @code{mouse-wheel-down-event}, defined in @file{mwheel.el}.
+Beware that for historical reasons the @code{mouse-wheel-@emph{up}-event}
+is the variable that holds an event that should be handled similarly to
+@code{wheel-@emph{down}} and vice versa.
 
 @vindex mouse-wheel-left-event
 @vindex mouse-wheel-right-event
diff --git a/lisp/completion-preview.el b/lisp/completion-preview.el
index f552db7aa8e..6fd60f3c416 100644
--- a/lisp/completion-preview.el
+++ b/lisp/completion-preview.el
@@ -135,12 +135,14 @@ If this option is nil, these commands do not display any message."
   "<down-mouse-1>" #'completion-preview-insert
   "C-<down-mouse-1>" #'completion-at-point
   "<down-mouse-2>" #'completion-at-point
+  ;; BEWARE: `mouse-wheel-UP-event' corresponds to `wheel-DOWN' events
+  ;; and vice versa!!
   "<wheel-up>"     #'completion-preview-prev-candidate
   "<wheel-down>"   #'completion-preview-next-candidate
   (key-description (vector mouse-wheel-up-event))
-  #'completion-preview-prev-candidate
+  #'completion-preview-next-candidate
   (key-description (vector mouse-wheel-down-event))
-  #'completion-preview-next-candidate)
+  #'completion-preview-prev-candidate)
 
 (defvar-local completion-preview--overlay nil)
 
diff --git a/lisp/mwheel.el b/lisp/mwheel.el
index 1e08328c875..53042085bf6 100644
--- a/lisp/mwheel.el
+++ b/lisp/mwheel.el
@@ -34,8 +34,8 @@
 ;; Implementation note:
 ;;
 ;; I for one would prefer some way of converting the mouse-4/mouse-5
-;; events into different event types, like 'mwheel-up' or
-;; 'mwheel-down', but I cannot find a way to do this very easily (or
+;; events into different event types, like 'wheel-up' or
+;; 'wheel-down', but I cannot find a way to do this very easily (or
 ;; portably), so for now I just live with it.
 
 (require 'timer)
@@ -63,14 +63,14 @@ They are sometimes generated by things like `xterm-mouse-mode' as well.")
 
 (defcustom mouse-wheel-down-event
   (if mouse-wheel-obey-old-style-wheel-buttons 'mouse-4)
-  "Event used for scrolling down, beside `wheel-down', if any."
+  "Event used for scrolling down, beside `wheel-up', if any."
   :group 'mouse
   :type 'symbol
   :set #'mouse-wheel-change-button)
 
 (defcustom mouse-wheel-up-event
   (if mouse-wheel-obey-old-style-wheel-buttons 'mouse-5)
-  "Event used for scrolling up, beside `wheel-up', if any."
+  "Event used for scrolling up, beside `wheel-down', if any."
   :group 'mouse
   :type 'symbol
   :set #'mouse-wheel-change-button)
diff --git a/lisp/progmodes/flymake.el b/lisp/progmodes/flymake.el
index 225f8ecf874..5974f076556 100644
--- a/lisp/progmodes/flymake.el
+++ b/lisp/progmodes/flymake.el
@@ -1637,14 +1637,16 @@ correctly.")
 
 (defvar flymake--mode-line-counter-map
   (let ((map (make-sparse-keymap)))
+    ;; BEWARE: `mouse-wheel-UP-event' corresponds to `wheel-DOWN' events
+    ;; and vice versa!!
     (define-key map (vector 'mode-line mouse-wheel-down-event)
                 #'flymake--mode-line-counter-scroll-prev)
     (define-key map [mode-line wheel-down]
-                #'flymake--mode-line-counter-scroll-prev)
+                #'flymake--mode-line-counter-scroll-next)
     (define-key map (vector 'mode-line mouse-wheel-up-event)
                 #'flymake--mode-line-counter-scroll-next)
     (define-key map [mode-line wheel-up]
-                #'flymake--mode-line-counter-scroll-next)
+                #'flymake--mode-line-counter-scroll-prev)
     map))
 
 (defun flymake--mode-line-counter-1 (type)