Function: display-buffer-in-previous-window

display-buffer-in-previous-window is a byte-compiled function defined in window.el.gz.

Signature

(display-buffer-in-previous-window BUFFER ALIST)

Documentation

Display BUFFER in a window previously showing it.

ALIST is an association list of action symbols and values. See Info node (elisp) Buffer Display Action Alists for details of such alists.

If ALIST has a non-nil inhibit-same-window entry, the selected window is not usable. A dedicated window is usable only if it already shows BUFFER. If ALIST contains a previous-window entry, the window specified by that entry (either a variable or a value) is usable even if it never showed BUFFER before.

If ALIST contains a reusable-frames entry, its value determines which frames to search for a usable window:
  nil -- the selected frame (actually the last non-minibuffer frame)
  A frame -- just that frame
  visible -- all visible frames
  0 -- all frames on the current terminal
  t -- all frames.

If ALIST contains no reusable-frames entry, search just the selected frame if display-buffer-reuse-frames and pop-up-frames are both nil; search all frames on the current terminal if either of those variables is non-nil.

If more than one window is usable according to these rules, apply the following order of preference:

- Use the window specified by any previous-window ALIST entry,
  provided it is not the selected window.

- Use a window that showed BUFFER before, provided it is not the
  selected window.

- Use the selected window if it is either specified by a
  previous-window ALIST entry or showed BUFFER before.

This is an action function for buffer display, see Info node (elisp) Buffer Display Action Functions. It should be called only by display-buffer or a function directly or indirectly called by the latter.

View in manual

Probably introduced at or before Emacs version 24.3.

Source Code

;; Defined in /usr/src/emacs/lisp/window.el.gz
(defun display-buffer-in-previous-window (buffer alist)
  "Display BUFFER in a window previously showing it.
ALIST is an association list of action symbols and values.  See
Info node `(elisp) Buffer Display Action Alists' for details of
such alists.

If ALIST has a non-nil `inhibit-same-window' entry, the selected
window is not usable.  A dedicated window is usable only if it
already shows BUFFER.  If ALIST contains a `previous-window'
entry, the window specified by that entry (either a variable
or a value) is usable even if it never showed BUFFER before.

If ALIST contains a `reusable-frames' entry, its value determines
which frames to search for a usable window:
  nil -- the selected frame (actually the last non-minibuffer frame)
  A frame   -- just that frame
  `visible' -- all visible frames
  0   -- all frames on the current terminal
  t   -- all frames.

If ALIST contains no `reusable-frames' entry, search just the
selected frame if `display-buffer-reuse-frames' and
`pop-up-frames' are both nil; search all frames on the current
terminal if either of those variables is non-nil.

If more than one window is usable according to these rules,
apply the following order of preference:

- Use the window specified by any `previous-window' ALIST entry,
  provided it is not the selected window.

- Use a window that showed BUFFER before, provided it is not the
  selected window.

- Use the selected window if it is either specified by a
  `previous-window' ALIST entry or showed BUFFER before.

This is an action function for buffer display, see Info
node `(elisp) Buffer Display Action Functions'.  It should be
called only by `display-buffer' or a function directly or
indirectly called by the latter."
  (let* ((alist-entry (assq 'reusable-frames alist))
	 (inhibit-same-window
	  (cdr (assq 'inhibit-same-window alist)))
	 (frames (cond
		  (alist-entry (cdr alist-entry))
		  ((window--pop-up-frames alist)
		   0)
		  (display-buffer-reuse-frames 0)
		  (t (last-nonminibuffer-frame))))
         (previous-window (cdr (assq 'previous-window alist)))
	 best-window second-best-window window)
    ;; Scan windows whether they have shown the buffer recently.
    (catch 'best
      (dolist (window (window-list-1 (frame-first-window) 'nomini frames))
	(when (and (assq buffer (window-prev-buffers window))
		   (not (window-dedicated-p window)))
	  (if (eq window (selected-window))
	      (unless inhibit-same-window
		(setq second-best-window window))
	    (setq best-window window)
	    (throw 'best t)))))
    ;; When ALIST has a `previous-window' entry, that entry may override
    ;; anything we found so far.
    (when (and previous-window (symbolp previous-window)
               (boundp previous-window))
      (setq previous-window (symbol-value previous-window)))
    (when (and (setq window previous-window)
	       (window-live-p window)
	       (or (eq buffer (window-buffer window))
                   (not (window-dedicated-p window))))
      (if (eq window (selected-window))
	  (unless inhibit-same-window
	    (setq second-best-window window))
	(setq best-window window)))
    ;; Return best or second best window found.
    (when (setq window (or best-window second-best-window))
      (window--display-buffer buffer window 'reuse alist))))