From 35fc61cb5b5eba8bbb9d8f0700332fbab38f40ca Mon Sep 17 00:00:00 2001 From: Bram Moolenaar Date: Tue, 22 Nov 2022 12:40:50 +0000 Subject: patch 9.0.0917: the WinScrolled autocommand event is not enough Problem: The WinScrolled autocommand event is not enough. Solution: Add WinResized and provide information about what changed. (closes #11576) --- runtime/doc/autocmd.txt | 33 +++++++++++++++++++++------------ runtime/doc/windows.txt | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 69 insertions(+), 12 deletions(-) (limited to 'runtime/doc') 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 and 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* -- cgit v1.2.1