events: VimSuspend, VimResume #8280

closes #3648
ref #5959

runtime/doc/autocmd.txt

@@ -272,10 +272,11 @@ Name			triggered by ~
 |GUIEnter|		after starting the GUI successfully
 |GUIFailed|		after starting the GUI failed
 |TermResponse|		after the terminal response to |t_RV| is received
-
 |QuitPre|		when using `:quit`, before deciding whether to quit
-|VimLeavePre|		before exiting Vim, before writing the shada file
-|VimLeave|		before exiting Vim, after writing the shada file
+|VimLeavePre|		before exiting Nvim, before writing the shada file
+|VimLeave|		before exiting Nvim, after writing the shada file
+|VimResume|		after Nvim is resumed
+|VimSuspend|		before Nvim is suspended
 
 	Various
 |DirChanged|		after the |current-directory| was changed
@@ -1009,6 +1010,10 @@ VimLeavePre			Before exiting Vim, just before writing the
 VimResized			After the Vim window was resized, thus 'lines'
 				and/or 'columns' changed.  Not when starting
 				up though.
+							*VimResume*
+VimResume			After Nvim resumes from |suspend| state.
+							*VimSuspend*
+VimSuspend			Before Nvim enters |suspend| state.
 							*WinEnter*
 WinEnter			After entering another window.  Not done for
 				the first window, when Vim has just started.

runtime/doc/starting.txt

@@ -687,25 +687,17 @@ CTRL-Z			Suspend Vim, like ":stop".
 			Command-line mode, the CTRL-Z is inserted as a normal
 			character.  In Visual mode Vim goes back to Normal
 			mode.
-			Note: if CTRL-Z undoes a change see |mswin.vim|.
-
 
 :sus[pend][!]	or			*:sus* *:suspend* *:st* *:stop*
-:st[op][!]		Suspend Vim.
+:st[op][!]		Suspend Vim.  Vim will continue if you make it the
+			foreground job again.
 			If the '!' is not given and 'autowrite' is set, every
 			buffer with changes and a file name is written out.
 			If the '!' is given or 'autowrite' is not set, changed
 			buffers are not written, don't forget to bring Vim
 			back to the foreground later!
 
-In the GUI, suspending is implemented as iconising gvim.  In Windows 95/NT,
-gvim is minimized.
-
-On many Unix systems, it is possible to suspend Vim with CTRL-Z.  This is only
-possible in Normal and Visual mode (see next chapter, |vim-modes|).  Vim will
-continue if you make it the foreground job again.  On other systems, CTRL-Z
-will start a new shell.  This is the same as the ":sh" command.  Vim will
-continue if you exit from the shell.
+In the GUI, suspending is implementation-defined.
 
 In X-windows the selection is disowned when Vim suspends.  this means you
 can't paste it in another application (since Vim is going to sleep an attempt

src/nvim/auevents.lua

@@ -92,6 +92,8 @@ return {
     'VimLeave',               -- before exiting Vim
     'VimLeavePre',            -- before exiting Vim and writing ShaDa file
     'VimResized',             -- after Vim window was resized
+    'VimResume',              -- after Nvim is resumed
+    'VimSuspend',             -- before Nvim is suspended
     'WinNew',                 -- when entering a new window
     'WinEnter',               -- after entering a window
     'WinLeave',               -- before leaving a window

src/nvim/ex_docmd.c

@@ -6300,15 +6300,18 @@ static void ex_stop(exarg_T *eap)
     if (!eap->forceit) {
       autowrite_all();
     }
+    apply_autocmds(EVENT_VIMSUSPEND, NULL, NULL, false, NULL);
     ui_cursor_goto((int)Rows - 1, 0);
     ui_linefeed();
     ui_flush();
     ui_call_suspend();  // call machine specific function
+
     ui_flush();
     maketitle();
     resettitle();  // force updating the title
     redraw_later_clear();
     ui_refresh();  // may have resized window
+    apply_autocmds(EVENT_VIMRESUME, NULL, NULL, false, NULL);
   }
 }
 

test/functional/ui/screen_basic_spec.lua

@@ -4,6 +4,7 @@ local spawn, set_session, clear = helpers.spawn, helpers.set_session, helpers.cl
 local feed, command = helpers.feed, helpers.command
 local insert = helpers.insert
 local eq = helpers.eq
+local eval = helpers.eval
 local iswin = helpers.iswin
 
 describe('screen', function()
@@ -75,11 +76,26 @@ describe('Screen', function()
       local function check()
         eq(true, screen.suspended)
       end
+
+      command('let g:ev = []')
+      command('autocmd VimResume  * :call add(g:ev, "r")')
+      command('autocmd VimSuspend * :call add(g:ev, "s")')
+
+      eq(false, screen.suspended)
       command('suspend')
+      eq({ 's', 'r' }, eval('g:ev'))
+
       screen:expect(check)
       screen.suspended = false
+
       feed('<c-z>')
+      eq({ 's', 'r', 's', 'r' }, eval('g:ev'))
+
       screen:expect(check)
+      screen.suspended = false
+
+      command('suspend')
+      eq({ 's', 'r', 's', 'r', 's', 'r' }, eval('g:ev'))
     end)
   end)