Horizontal mouse wheel scrolling amount (bug#43568)

* lisp/mwheel.el (mouse-wheel-scroll-amount-horizontal): New defcustom.
(mwheel-scroll): Use it.

* doc/emacs/frames.texi (Mouse Commands): Update doc about horizontal
scrolling step.

doc/emacs/frames.texi

@@ -214,7 +214,11 @@ speed is linked to how fast you move the wheel.  This mode also
 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.
+@vindex mouse-wheel-scroll-amount-horizontal
+Emacs also supports horizontal scrolling with the @key{Shift}
+modifier.  Typing a numeric prefix arg (e.g., @kbd{M-5}) before
+starting horizontal scrolling changes its step value defined
+by the user option @code{mouse-wheel-scroll-amount-horizontal}.
 
 @vindex mouse-wheel-tilt-scroll
 @vindex mouse-wheel-flip-direction

etc/NEWS

@@ -148,7 +148,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. 'M-5') before starting horizontal scrolling changes its step value.
+The value is saved in the user option 'mouse-wheel-scroll-amount-horizontal'.
 
 ---
 ** The default value of 'frame-title-format' and 'icon-title-format' has changed.

lisp/mwheel.el

@@ -146,6 +146,16 @@ face height."
   :group 'mouse
   :type 'boolean)
 
+(defcustom mouse-wheel-scroll-amount-horizontal 1
+  "Amount to scroll windows horizontally.
+Its value can be changed dynamically by using a numeric prefix argument
+before starting horizontal scrolling.
+It has effect when `mouse-wheel-scroll-amount' binds the value `hscroll'
+to one of modifiers (`Shift' by default)."
+  :group 'mouse
+  :type 'number
+  :version "28.1")
+
 ;;; For tilt-scroll
 ;;;
 (defcustom mouse-wheel-tilt-scroll nil
@@ -243,11 +253,15 @@ active 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.
+The value is saved in the variable `mouse-wheel-scroll-amount-horizontal'."
+  (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 +289,12 @@ non-Windows systems."
         (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-amount-horizontal arg))
                      (funcall (if mouse-wheel-flip-direction
                                   mwheel-scroll-left-function
-                                mwheel-scroll-right-function) 1))
+                                mwheel-scroll-right-function)
+                              mouse-wheel-scroll-amount-horizontal))
                     ((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 +311,12 @@ non-Windows systems."
                           ;; 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-amount-horizontal arg))
                      (funcall (if mouse-wheel-flip-direction
                                   mwheel-scroll-right-function
-                                mwheel-scroll-left-function) 1))
+                                mwheel-scroll-left-function)
+                              mouse-wheel-scroll-amount-horizontal))
                     ((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.