New display action alist entry 'post-command-select-window' (bug#67993)

* doc/lispref/windows.texi (Buffer Display Action Alists):
Add 'post-command-select-window'.

* lisp/window.el (display-buffer): Add 'post-command-select-window'
to the docstring and handle at the end of function.

3 files changed, 35 insertions, 0 deletions

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 93b25cbe67f..f14e74bc785 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -3344,6 +3344,16 @@ It is called @emph{after} the buffer is displayed, and @emph{before}
 the entries @code{window-height}, @code{window-width} and
 @code{preserve-size} are applied that could resize the window to fit
 it to the inserted contents.
+
+@vindex post-command-select-window@r{, a buffer display action alist entry}
+@item post-command-select-window
+If the value is non-@code{nil}, the buffer displayed by @code{display-buffer}
+is selected after the current command is executed by running the hook
+@code{post-command-hook} (@pxref{Command Overview}).
+If the value is @code{nil}, the buffer selected by such functions as
+@code{pop-to-buffer} is deselected, and the window that was selected
+before calling this function will remain selected regardless of which
+windows were selected afterwards within this command.
 @end table
 
 By convention, the entries @code{window-height}, @code{window-width}
diff --git a/etc/NEWS b/etc/NEWS
index 03b8c3b517a..939caed14f6 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -262,6 +262,12 @@ Anything following the symbol 'mode-line-format-right-align' in
 right-aligned to is controlled by the new user option
 'mode-line-right-align-edge'.
 
+** Windows
+
+*** New buffer display action alist entry 'post-command-select-window'.
+It specifies whether the window of the displayed buffer should be
+selected or deselected at the end of executing the current command.
+
 ** Tab Bars and Tab Lines
 
 *** New user option 'tab-bar-tab-name-format-functions'.
diff --git a/lisp/window.el b/lisp/window.el
index 23977691f50..65651b2931b 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -7798,6 +7798,14 @@ Action alist entries are:
     and `preserve-size' are applied.  The function is supposed
     to fill the window body with some contents that might depend
     on dimensions of the displayed window.
+ `post-command-select-window' -- A non-nil value means that after the
+    current command is executed and the hook `post-command-hook' is called,
+    the window displayed by this function will be selected.  A nil value
+    means that if functions like `pop-to-buffer' selected another window,
+    at the end of this command that window will be deselected, and the
+    window that was selected before calling this function will remain
+    selected regardless of which windows were selected afterwards within
+    this command.
 
 The entries `window-height', `window-width', `window-size' and
 `preserve-size' are applied only when the window used for
@@ -7853,6 +7861,17 @@ specified by the ACTION argument."
       (while (and functions (not window))
         (setq window (funcall (car functions) buffer alist)
               functions (cdr functions)))
+      (when-let ((select (assq 'post-command-select-window alist)))
+        (letrec ((old-selected-window (selected-window))
+                 (postfun
+                  (lambda ()
+                    (if (cdr select)
+                        (when (window-live-p window)
+                          (select-window window))
+                      (when (window-live-p old-selected-window)
+                        (select-window old-selected-window)))
+                    (remove-hook 'post-command-hook postfun))))
+          (add-hook 'post-command-hook postfun)))
       (and (windowp window) window))))
 
 (defun display-buffer-other-frame (buffer)