feat: add 'mousescroll' option (#12355)

Add 'mousescroll' option to control how many lines to scroll by when a
mouse wheel keycode is received. The mousescroll option controls both
horizontal and vertical scrolling. The option is a string in the format:

    set mousescroll=direction:count,direction:count

Where direction is either "ver" or "hor", and count is a non negative
integer. If a direction is omitted, a default value is used. The default
values remain unchanged, that is 3 for vertical scrolling, and 6 for
horizontal scrolling. As such, the mousescroll default is "ver:3,hor:6".

Add mousescroll documentation
 - Add option documentation in options.txt
 - Add brief summary in quickref.txt

Update :help scroll-mouse-wheel
 - Mention mousescroll option as a means of controlling scrolling.
 - Remove obsolete suggestion to map scroll wheel keys to <C-U> to
   scroll by a single line -- users should prefer the mousescroll option.
 - Add some information about the consequences of remapping scroll wheel
   keys (they lose their magic ability to affect inactive windows).

Update :help vim-differences
 - Add brief mousescroll summary under Options

Add mousescroll tests
 - Test option validation
 - Test default mousescroll value and behavior
 - Test fallback to default values
 - Test mouse vertical and horizontal scrolling in normal mode
 - Test mouse vertical and horizontal scrolling in insert mode

6 files changed, 87 insertions, 8 deletions

diff --git a/src/nvim/edit.c b/src/nvim/edit.c
index 26422f06b1..06f6d7f97b 100644
--- a/src/nvim/edit.c
+++ b/src/nvim/edit.c
@@ -8557,14 +8557,12 @@ static void ins_mousescroll(int dir)
   }
 
   // Don't scroll the window in which completion is being done.
-  if (!pum_visible()
-      || curwin != old_curwin) {
+  if (!pum_visible() || curwin != old_curwin) {
     if (dir == MSCR_DOWN || dir == MSCR_UP) {
       if (mod_mask & (MOD_MASK_SHIFT | MOD_MASK_CTRL)) {
-        scroll_redraw(dir,
-                      (curwin->w_botline - curwin->w_topline));
+        scroll_redraw(dir, (long)(curwin->w_botline - curwin->w_topline));
       } else {
-        scroll_redraw(dir, 3L);
+        scroll_redraw(dir, p_mousescroll_vert);
       }
     } else {
       mouse_scroll_horiz(dir);
diff --git a/src/nvim/mouse.c b/src/nvim/mouse.c
index 3aee20dc7b..2ea108d3df 100644
--- a/src/nvim/mouse.c
+++ b/src/nvim/mouse.c
@@ -688,7 +688,7 @@ bool mouse_scroll_horiz(int dir)
     return false;
   }
 
-  int step = 6;
+  int step = (int)p_mousescroll_hor;
   if (mod_mask & (MOD_MASK_SHIFT | MOD_MASK_CTRL)) {
     step = curwin->w_width_inner;
   }
diff --git a/src/nvim/normal.c b/src/nvim/normal.c
index ed624c0c9f..f871b6a884 100644
--- a/src/nvim/normal.c
+++ b/src/nvim/normal.c
@@ -3392,8 +3392,8 @@ static void nv_mousescroll(cmdarg_T *cap)
     if (mod_mask & (MOD_MASK_SHIFT | MOD_MASK_CTRL)) {
       (void)onepage(cap->arg ? FORWARD : BACKWARD, 1L);
     } else {
-      cap->count1 = 3;
-      cap->count0 = 3;
+      cap->count1 = p_mousescroll_vert;
+      cap->count0 = p_mousescroll_vert;
       nv_scroll_line(cap);
     }
   } else {
diff --git a/src/nvim/option.c b/src/nvim/option.c
index bcaa4bb9b8..a3bd960fa5 100644
--- a/src/nvim/option.c
+++ b/src/nvim/option.c
@@ -2366,6 +2366,69 @@ static bool valid_spellfile(const char_u *val)
   return true;
 }
 
+/// Handle setting 'mousescroll'.
+/// @return error message, NULL if it's OK.
+static char *check_mousescroll(char *string)
+{
+  long vertical = -1;
+  long horizontal = -1;
+
+  for (;;) {
+    char *end = vim_strchr(string, ',');
+    size_t length = end ? (size_t)(end - string) : STRLEN(string);
+
+    // Both "ver:" and "hor:" are 4 bytes long.
+    // They should be followed by at least one digit.
+    if (length <= 4) {
+      return e_invarg;
+    }
+
+    long *direction;
+
+    if (memcmp(string, "ver:", 4) == 0) {
+      direction = &vertical;
+    } else if (memcmp(string, "hor:", 4) == 0) {
+      direction = &horizontal;
+    } else {
+      return e_invarg;
+    }
+
+    // If the direction has already been set, this is a duplicate.
+    if (*direction != -1) {
+      return e_invarg;
+    }
+
+    // Verify that only digits follow the colon.
+    for (size_t i = 4; i < length; i++) {
+      if (!ascii_isdigit(string[i])) {
+        return N_("E548: digit expected");
+      }
+    }
+
+    string += 4;
+    *direction = getdigits_int(&string, false, -1);
+
+    // Num options are generally kept within the signed int range.
+    // We know this number won't be negative because we've already checked for
+    // a minus sign. We'll allow 0 as a means of disabling mouse scrolling.
+    if (*direction == -1) {
+      return e_invarg;
+    }
+
+    if (!end) {
+      break;
+    }
+
+    string = end + 1;
+  }
+
+  // If a direction wasn't set, fallback to the default value.
+  p_mousescroll_vert = (vertical == -1) ? MOUSESCROLL_VERT_DFLT : vertical;
+  p_mousescroll_hor = (horizontal == -1) ? MOUSESCROLL_HOR_DFLT : horizontal;
+
+  return NULL;
+}
+
 /// Handle string options that need some action to perform when changed.
 /// Returns NULL for success, or an error message for an error.
 ///
@@ -2859,6 +2922,8 @@ ambw_end:
     if (check_opt_strings(p_mousem, p_mousem_values, false) != OK) {
       errmsg = e_invarg;
     }
+  } else if (varp == &p_mousescroll) {  // 'mousescroll'
+    errmsg = check_mousescroll((char *)p_mousescroll);
   } else if (varp == &p_swb) {  // 'switchbuf'
     if (opt_strings_flags(p_swb, p_swb_values, &swb_flags, true) != OK) {
       errmsg = e_invarg;
diff --git a/src/nvim/option_defs.h b/src/nvim/option_defs.h
index 531527ea3c..237288fbad 100644
--- a/src/nvim/option_defs.h
+++ b/src/nvim/option_defs.h
@@ -153,6 +153,11 @@
 #define MOUSE_NONE      ' '             // don't use Visual selection
 #define MOUSE_NONEF     'x'             // forced modeless selection
 
+// default vertical and horizontal mouse scroll values.
+// Note: This should be in sync with the default mousescroll option.
+#define MOUSESCROLL_VERT_DFLT   3
+#define MOUSESCROLL_HOR_DFLT    6
+
 #define COCU_ALL        "nvic"          // flags for 'concealcursor'
 
 /// characters for p_shm option:
@@ -528,6 +533,9 @@ EXTERN long p_mls;              // 'modelines'
 EXTERN char_u *p_mouse;       // 'mouse'
 EXTERN char_u *p_mousem;      // 'mousemodel'
 EXTERN int p_mousef;           // 'mousefocus'
+EXTERN char_u *p_mousescroll;  // 'mousescroll'
+EXTERN long p_mousescroll_vert INIT(= MOUSESCROLL_VERT_DFLT);
+EXTERN long p_mousescroll_hor INIT(= MOUSESCROLL_HOR_DFLT);
 EXTERN long p_mouset;           // 'mousetime'
 EXTERN int p_more;              // 'more'
 EXTERN char_u *p_opfunc;      // 'operatorfunc'
diff --git a/src/nvim/options.lua b/src/nvim/options.lua
index a0fbf8d9f0..addc08d560 100644
--- a/src/nvim/options.lua
+++ b/src/nvim/options.lua
@@ -1622,6 +1622,14 @@ return {
       defaults={if_true="extend"}
     },
     {
+      full_name='mousescroll',
+      short_desc=N_("amount to scroll by when scrolling with a mouse"),
+      type='string', list='comma', scope={'global'},
+      vi_def=true,
+      varname='p_mousescroll',
+      defaults={if_true="ver:3,hor:6"}
+    },
+    {
       full_name='mouseshape', abbreviation='mouses',
       short_desc=N_("shape of the mouse pointer in different modes"),
       type='string', list='onecomma', scope={'global'},