bug#43568: Horizontal mouse wheel scrolling

[Juri Linkov]

Currently the mouse-wheel horizontal scrolling step is hard-coded to the
constant 1.  It's very inconvenient to scroll large amount of text
horizontally by small increments.  For example, the horizontal step is
hard-coded to 3 in Firefox, and to 5 in Chrome.

But since Emacs is much more powerful than web browsers in regard to
customization, the following patch adds a new user option to define the
default step, and also allows the user to change the step dynamically by
using a numeric prefix arg before starting to scroll, e.g. typing 'M-8'
before scrolling will set the scroll step to 8.

diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 1a44d8dc62..6b070d932a 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -214,7 +214,10 @@ Mouse Commands
 supports increasing or decreasing the height of the default face, by
 default bound to scrolling with the @key{Ctrl} modifier.
 
-Emacs also supports horizontal scrolling with the @key{Shift} modifier.
+Emacs also supports horizontal scrolling with the @key{Shift}
+modifier.  Typing a numeric prefix arg (e.g. @kbd{C-u 5}) before
+starting horizontal scrolling changes its step value defined
+by the user option @code{mouse-wheel-scroll-horizontal-step}.
 
 @vindex mouse-wheel-tilt-scroll
 @vindex mouse-wheel-flip-direction
diff --git a/etc/NEWS b/etc/NEWS
index 5a646d2bb9..74959bb2de 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -153,7 +156,9 @@ displays.)
 
 +++
 ** Mouse wheel scrolling with Shift modifier now scrolls horizontally.
-This works in text buffers and over images.
+This works in text buffers and over images.  Typing a numeric prefix arg
+(e.g. 'C-u 5') before starting horizontal scrolling changes its step value.
+Its value is saved in the user option 'mouse-wheel-scroll-horizontal-step'.
 
 ---
 ** The default value of 'frame-title-format' and 'icon-title-format' has 
changed.
diff --git a/lisp/mwheel.el b/lisp/mwheel.el
index c6a7391df1..a49a4254d1 100644
--- a/lisp/mwheel.el
+++ b/lisp/mwheel.el
@@ -146,6 +146,14 @@ mouse-wheel-follow-mouse
   :group 'mouse
   :type 'boolean)
 
+(defcustom mouse-wheel-scroll-horizontal-step 1
+  "Amount to scroll windows horizontally.
+Its value can be changed dynamically by using a numeric prefix argument
+before starting horizontal scrolling."
+  :group 'mouse
+  :type 'number
+  :version "28.1")
+
 ;;; For tilt-scroll
 ;;;
 (defcustom mouse-wheel-tilt-scroll nil
@@ -243,11 +251,14 @@ mouse-wheel--get-scroll-window
                frame nil t)))))
       (mwheel-event-window event)))
 
-(defun mwheel-scroll (event)
+(defun mwheel-scroll (event &optional arg)
   "Scroll up or down according to the EVENT.
 This should be bound only to mouse buttons 4, 5, 6, and 7 on
-non-Windows systems."
-  (interactive (list last-input-event))
+non-Windows systems.
+
+An optional prefix ARG can be used to change the step of horizontal
+scrolling.  The arg numeric value can be typed before starting to scroll."
+  (interactive (list last-input-event current-prefix-arg))
   (let* ((selected-window (selected-window))
          (scroll-window (mouse-wheel--get-scroll-window event))
         (old-point
@@ -275,9 +286,12 @@ mwheel-scroll
         (unwind-protect
            (let ((button (mwheel-event-button event)))
               (cond ((and (eq amt 'hscroll) (eq button mouse-wheel-down-event))
+                     (when (and (natnump arg) (> arg 0))
+                       (setq mouse-wheel-scroll-horizontal-step arg))
                      (funcall (if mouse-wheel-flip-direction
                                   mwheel-scroll-left-function
-                                mwheel-scroll-right-function) 1))
+                                mwheel-scroll-right-function)
+                              mouse-wheel-scroll-horizontal-step))
                     ((eq button mouse-wheel-down-event)
                      (condition-case nil (funcall mwheel-scroll-down-function 
amt)
                        ;; Make sure we do indeed scroll to the beginning of
@@ -294,9 +308,12 @@ mwheel-scroll
                           ;; to only affect scroll-down.  --Stef
                           (set-window-start (selected-window) (point-min))))))
                     ((and (eq amt 'hscroll) (eq button mouse-wheel-up-event))
+                     (when (and (natnump arg) (> arg 0))
+                       (setq mouse-wheel-scroll-horizontal-step arg))
                      (funcall (if mouse-wheel-flip-direction
                                   mwheel-scroll-right-function
-                                mwheel-scroll-left-function) 1))
+                                mwheel-scroll-left-function)
+                              mouse-wheel-scroll-horizontal-step))
                     ((eq button mouse-wheel-up-event)
                      (condition-case nil (funcall mwheel-scroll-up-function 
amt)
                        ;; Make sure we do indeed scroll to the end of the 
buffer.