UI: emit mouse_on/mouse_off on attach #11455

closes #11372

runtime/doc/develop.txt

@@ -349,8 +349,8 @@ External UIs are expected to implement these common features:
   chords (<C-,> <C-Enter> <C-S-x> <D-x>) and patterns ("shift shift") that do
   not potentially conflict with Nvim defaults, plugins, etc.
 - Consider the "option_set" |ui-global| event as a hint for other GUI
-  behaviors. UI-related options ('guifont', 'ambiwidth', …) are published in
-  this event.
+  behaviors. Various UI-related options ('guifont', 'ambiwidth', …) are
+  published in this event. See also "mouse_on", "mouse_off".
 
 
  vim:tw=78:ts=8:noet:ft=help:norl:

runtime/doc/ui.txt

@@ -201,8 +201,8 @@ the editor.
 	sent from Nvim, like for |ui-cmdline|.
 
 ["mode_change", mode, mode_idx]
-	The mode changed.  The first parameter `mode` is a string representing
-	the current mode. `mode_idx` is an index into the array received in
+	Editor mode changed.  The `mode` parameter is a string representing
+	the current mode. `mode_idx` is an index into the array emitted in
 	the `mode_info_set` event. UIs should change the cursor style
 	according to the properties specified in the corresponding item. The
 	set of modes reported will change in new versions of Nvim, for
@@ -211,11 +211,11 @@ the editor.
 
 ["mouse_on"]
 ["mouse_off"]
-	Tells the client whether mouse support, as determined by |'mouse'|
-	option, is considered to be active in the current mode. This is mostly
-	useful for a terminal frontend, or other situations where Nvim mouse
-	would conflict with other usages of the mouse. It is safe for a client
-	to ignore this and always send mouse events.
+	|'mouse'| was enabled/disabled in the current editor mode. Useful for
+	a terminal UI, or other situations where Nvim mouse would conflict
+	with other usages of the mouse. UIs may ignore this and always send
+	mouse input, because 'mouse' decides the behavior of |nvim_input()|
+	implicitly.
 
 ["busy_start"]
 ["busy_stop"]

src/nvim/mouse.c

@@ -508,31 +508,30 @@ static win_T *mouse_find_grid_win(int *gridp, int *rowp, int *colp)
   return NULL;
 }
 
-/*
- * setmouse() - switch mouse on/off depending on current mode and 'mouse'
- */
+/// Set UI mouse depending on current mode and 'mouse'.
+///
+/// Emits mouse_on/mouse_off UI event (unless 'mouse' is empty).
 void setmouse(void)
 {
-  int checkfor;
-
   ui_cursor_shape();
 
-  /* be quick when mouse is off */
-  if (*p_mouse == NUL)
+  // Be quick when mouse is off.
+  if (*p_mouse == NUL) {
     return;
+  }
 
-  if (VIsual_active)
+  int checkfor = MOUSE_NORMAL;  // assume normal mode
+  if (VIsual_active) {
     checkfor = MOUSE_VISUAL;
-  else if (State == HITRETURN || State == ASKMORE || State == SETWSIZE)
+  } else if (State == HITRETURN || State == ASKMORE || State == SETWSIZE) {
     checkfor = MOUSE_RETURN;
-  else if (State & INSERT)
+  } else if (State & INSERT) {
     checkfor = MOUSE_INSERT;
-  else if (State & CMDLINE)
+  } else if (State & CMDLINE) {
     checkfor = MOUSE_COMMAND;
-  else if (State == CONFIRM || State == EXTERNCMD)
-    checkfor = ' ';     /* don't use mouse for ":confirm" or ":!cmd" */
-  else
-    checkfor = MOUSE_NORMAL;        /* assume normal mode */
+  } else if (State == CONFIRM || State == EXTERNCMD) {
+    checkfor = ' ';  // don't use mouse for ":confirm" or ":!cmd"
+  }
 
   if (mouse_has(checkfor)) {
     ui_call_mouse_on();

src/nvim/option.c

@@ -5173,6 +5173,13 @@ void ui_refresh_options(void)
     }
     ui_call_option_set(name, value);
   }
+  if (p_mouse != NULL) {
+    if (*p_mouse == NUL) {
+      ui_call_mouse_off();
+    } else {
+      setmouse();
+    }
+  }
 }
 
 /*

test/functional/ui/options_spec.lua

@@ -5,7 +5,7 @@ local command = helpers.command
 local eq = helpers.eq
 local shallowcopy = helpers.shallowcopy
 
-describe('ui receives option updates', function()
+describe('UI receives option updates', function()
   local screen
 
   local function reset(opts, ...)
@@ -47,6 +47,33 @@ describe('ui receives option updates', function()
     end)
   end)
 
+  it('on attach #11372', function()
+    clear()
+    local evs = {}
+    screen = Screen.new(20,5)
+    -- Override mouse_on/mouse_off handlers.
+    function screen._handle_mouse_on()
+      table.insert(evs, 'mouse_on')
+    end
+    function screen._handle_mouse_off()
+      table.insert(evs, 'mouse_off')
+    end
+    screen:attach()
+    screen:expect(function()
+      eq({'mouse_off'}, evs)
+    end)
+    command("set mouse=nvi")
+    screen:expect(function()
+      eq({'mouse_off','mouse_on'}, evs)
+    end)
+    screen:detach()
+    eq({'mouse_off','mouse_on'}, evs)
+    screen:attach()
+    screen:expect(function()
+      eq({'mouse_off','mouse_on','mouse_on'}, evs)
+    end)
+  end)
+
   it("when setting options", function()
     local expected = reset()
     local defaults = shallowcopy(expected)