patch 9.0.0917: the WinScrolled autocommand event is not enoughv9.0.0917

Problem:    The WinScrolled autocommand event is not enough.
Solution:   Add WinResized and provide information about what changed.
            (closes #11576)

2 files changed, 69 insertions, 12 deletions

diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index 86ae60f67..fbd0b0df3 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -1371,21 +1371,24 @@ WinNew				When a new window was created.  Not done for
 				Before a WinEnter event.
 
 							*WinScrolled*
-WinScrolled			After scrolling the content of a window or
-				resizing a window in the current tab page.
-
-				When more than one window scrolled or resized
-				only one WinScrolled event is triggered.  You
-				can use the `winlayout()` and `getwininfo()`
-				functions to see what changed.
+WinScrolled			After any window in the current tab page
+				scrolled the text (horizontally or vertically)
+				or changed width or height.  See
+				|win-scrolled-resized|.
 
 				The pattern is matched against the |window-ID|
 				of the first window that scrolled or resized.
 				Both <amatch> and <afile> are set to the
 				|window-ID|.
 
+				|v:event| is set with information about size
+				and scroll changes. |WinScrolled-event|
+
 				Only starts triggering after startup finished
 				and the first screen redraw was done.
+				Does not trigger when defining the first
+				WinScrolled or WinResized event, but may
+				trigger when adding more.
 
 				Non-recursive: the event will not trigger
 				while executing commands for the WinScrolled
@@ -1393,11 +1396,17 @@ WinScrolled			After scrolling the content of a window or
 				window to scroll or change size, then another
 				WinScrolled event will be triggered later.
 
-				Does not trigger when the command is added,
-				only after the first scroll or resize.
-							*E1312*
-				It is not allowed to change the window layout
-				here (split, close or move windows).
+
+							*WinResized*
+WinResized			After a window in the current tab page changed
+				width or height.
+				See |win-scrolled-resized|.
+
+				|v:event| is set with information about size
+				changes. |WinResized-event|
+
+				Same behavior as |WinScrolled| for the
+				pattern, triggering and recursiveness.
 
 ==============================================================================
 6. Patterns					*autocmd-patterns* *{aupat}*
diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt
index 2d96b043b..12676ff3a 100644
--- a/runtime/doc/windows.txt
+++ b/runtime/doc/windows.txt
@@ -631,6 +631,54 @@ it).
 The minimal height and width of a window is set with 'winminheight' and
 'winminwidth'.  These are hard values, a window will never become smaller.
 
+
+WinScrolled and WinResized autocommands ~
+						*win-scrolled-resized*
+If you want to get notified of changes in window sizes, the |WinResized|
+autocommand event can be used.
+If you want to get notified of text in windows scrolling vertically or
+horizontally, the |WinScrolled| autocommand event can be used.  This will also
+trigger in window size changes.
+							*WinResized-event*
+The |WinResized| event is triggered after updating the display, several
+windows may have changed size then.  A list of the IDs of windows that changed
+since last time is provided in the v:event.windows variable, for example:
+	[1003, 1006]
+							*WinScrolled-event*
+The |WinScrolled| event is triggered after |WinResized|, and also if a window
+was scrolled.  That can be vertically (the text at the top of the window
+changed) or horizontally (when 'wrap' is off or when the first displayed part
+of the first line changes).  Note that |WinScrolled| will trigger many more
+times than |WinResized|, it may slow down editing a bit.
+
+The information provided by |WinScrolled| is a dictionary for each window that
+has changes, using the window ID as the key, and a total count of the changes
+with the key "all".  Example value for |v:event| (|Vim9| syntax):
+	{
+	   all: {width: 0, height: 2, leftcol: 0, topline: 1, skipcol: 0},
+	   1003: {width: 0, height: -1, leftcol: 0, topline: 0, skipcol: 0},
+	   1006: {width: 0, height: 1, leftcol: 0, topline: 1, skipcol: 0},
+	}
+
+Note that the "all" entry has the absolute values of the individual windows
+accumulated.
+
+If you need more information about what changed, or you want to "debounce" the
+events (not handle every event to avoid doing too much work), you may want to
+use the `winlayout()` and `getwininfo()` functions.
+
+|WinScrolled| and |WinResized| do not trigger when the first autocommand is
+added, only after the first scroll or resize.  They may trigger when switching
+to another tab page.
+
+The commands executed are expected to not cause window size or scroll changes.
+If this happens anyway, the event will trigger again very soon.  In other
+words: Just before triggering the event, the current sizes and scroll
+positions are stored and used to decide whether there was a change.
+								*E1312*
+It is not allowed to change the window layout here (split, close or move
+windows).
+
 ==============================================================================
 7. Argument and buffer list commands			*buffer-list*