Expand spectrum of window change functions

* src/window.c (run_window_change_functions): Run window
change functions for Qwindow_state_change_functions.
(resize_frame_windows): Set frame's window_change slot when
single-window frames change size.
(Qwindow_state_change_functions): New symbol.
(Vwindow_state_change_functions): New Lisp variable.
* doc/lispref/windows.texi (Selecting Windows): Mention
'window-selection/state-change-functions' and add reference to
Window Hooks.
(Window Hooks): Document 'window-state-change-functions'.
* etc/NEWS: Mention new hook 'window-state-change-functions'.

1 files changed, 40 insertions, 6 deletions

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 6b5aa66a955..afb81e6874f 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -1758,7 +1758,7 @@ raise the frame or make sure input focus is directed to that frame.
 @xref{Input Focus}.
 @end defun
 
-@cindex select window hook
+@cindex select window hooks
 @cindex running a hook when a window gets selected
 For historical reasons, Emacs does not run a separate hook whenever a
 window gets selected.  Applications and internal routines often
@@ -1774,8 +1774,8 @@ useful.
   However, when its @var{norecord} argument is @code{nil},
 @code{select-window} updates the buffer list and thus indirectly runs
 the normal hook @code{buffer-list-update-hook} (@pxref{Buffer List}).
-Consequently, that hook provides a reasonable way to run a function
-whenever a window gets selected more ``permanently''.
+Consequently, that hook provides one way to run a function whenever a
+window gets selected more ``permanently''.
 
   Since @code{buffer-list-update-hook} is also run by functions that are
 not related to window management, it will usually make sense to save the
@@ -1787,6 +1787,13 @@ temporarily passes a non-@code{nil} @var{norecord} argument.  If
 possible, the macro @code{with-selected-window} (see below) should be
 used in such cases.
 
+  Emacs also runs the hook @code{window-selection-change-functions}
+whenever the redisplay routine detects that another window has been
+selected since last redisplay.  @xref{Window Hooks}, for a detailed
+explanation.  @code{window-state-change-functions} (described in the
+same section) is another abnormal hook run after a different window
+has been selected but is triggered by other window changes as well.
+
 @cindex most recently selected windows
   The sequence of calls to @code{select-window} with a non-@code{nil}
 @var{norecord} argument determines an ordering of windows by their
@@ -6039,7 +6046,7 @@ buffer are (re)fontified because a window was scrolled or its size
 changed.  @xref{Other Font Lock Variables}.
 
 @cindex window change functions
-   The remainder of this section covers four hooks that are called at
+   The remainder of this section covers five hooks that are called at
 the end of redisplay provided a significant, non-scrolling change of a
 window has been detected.  For simplicity, these hooks and the
 functions they call will be collectively referred to as @dfn{window
@@ -6108,10 +6115,37 @@ window has changed since the last time window change functions were
 run.  In this case the frame is passed as argument.
 @end defvar
 
+@cindex window state change
+The fourth of these hooks is run after a @dfn{window state change} has
+been detected, which means that at least one of the three preceding
+window changes has occurred.
+
+@defvar window-state-change-functions
+This variable specifies functions called at the end of redisplay when
+a window buffer or size change occurred or the selected window or a
+frame's selected window has changed.  The value should be a list of
+functions that take one argument.
+
+Functions specified buffer-locally are called for any window showing
+the corresponding buffer if that window has been added or assigned
+another buffer, total or body size or has been selected or deselected
+(among all windows or among all windows on its frame) since the last
+time window change functions were run.  In this case the window is
+passed as argument.
+
+Functions specified by the default value are called for a frame if at
+least one window on that frame has been added, deleted or assigned
+another buffer, total or body size or that frame has been selected or
+deselected or the frame's selected window has changed since the last
+time window change functions were run.  In this case the frame is
+passed as argument.
+@end defvar
+
 @cindex window configuration change
-The fourth of these hooks is run when a @dfn{window configuration
+The fifth of these hooks is run when a @dfn{window configuration
 change} has been detected which means that either the buffer or the
-size of a window changed.
+size of a window changed.  It differs from the four preceding hooks in
+the way it is run.
 
 @defvar window-configuration-change-hook
 This variable specifies functions called at the end of redisplay when