Function: display-buffer-reuse-window

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

Signature

(display-buffer-reuse-window BUFFER ALIST)

Documentation

Return a window that is already displaying BUFFER.

Preferably use a window on the selected frame if such a window exists. Return nil if no usable window is found.

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 eligible for reuse.

If ALIST contains a reusable-frames entry, its value determines which frames to search for a reusable 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 ALIST has a non-nil inhibit-switch-frame entry, then in the event that a window on another frame is chosen, avoid raising that frame.

If ALIST has a non-nil reuse-indirect entry and no window showing BUFFER has been found, try to find a window that is indirectly related to BUFFER and return that window. This would be a window for which window-indirect-buffer-p with the window and BUFFER as arguments returns non-nil. If a suitable window has been found and the cdr of the entry equals the symbol buffer, do not replace the buffer of that window with BUFFER but return the window with its old buffer in place. Otherwise, put BUFFER into that window and return the window.

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 31.1.

Source Code

;; Defined in /usr/src/emacs/lisp/window.el.gz
(defun display-buffer-reuse-window (buffer alist)
  "Return a window that is already displaying BUFFER.
Preferably use a window on the selected frame if such a window
exists.  Return nil if no usable window is found.

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 eligible for reuse.

If ALIST contains a `reusable-frames' entry, its value determines
which frames to search for a reusable 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 ALIST has a non-nil `inhibit-switch-frame' entry, then in the
event that a window on another frame is chosen, avoid raising
that frame.

If ALIST has a non-nil `reuse-indirect' entry and no window showing
BUFFER has been found, try to find a window that is indirectly related
to BUFFER and return that window.  This would be a window for which
`window-indirect-buffer-p' with the window and BUFFER as arguments
returns non-nil.  If a suitable window has been found and the cdr of the
entry equals the symbol `buffer', do not replace the buffer of that
window with BUFFER but return the window with its old buffer in place.
Otherwise, put BUFFER into that window and return the window.

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* ((reusable-frames (assq 'reusable-frames alist))
	 (reuse-indirect (assq 'reuse-indirect alist))
	 (frames (cond (reusable-frames (cdr reusable-frames))
		       ((window--pop-up-frames alist)
			0)
		       (display-buffer-reuse-frames 0)
		       (t (last-nonminibuffer-frame))))
	 (inhibit-same (cdr (assq 'inhibit-same-window alist)))
	 (window
	  ;; Avoid calling 'get-buffer-window-list' if the selected
	  ;; window already shows BUFFER and can be used.
	  (if (and (eq buffer (window-buffer)) (not inhibit-same))
	      (selected-window)
            ;; Preferably use a window on the selected frame,
            ;; if such a window exists (Bug#36680).
            (let* ((windows-raw
		    (get-buffer-window-list
                     buffer 'nomini frames reuse-indirect))
		   (windows (if inhibit-same
				(delq (selected-window) windows-raw)
			      windows-raw))
                   (first (car windows))
                   (this-frame (selected-frame)))
              (cond
               ((eq (window-frame first) this-frame)
                first)
               ((catch 'found
                  (dolist (next (cdr windows))
                    (when (eq (window-frame next) this-frame)
                      (throw 'found next)))))
               (t first))))))
    (when (window-live-p window)
      (when (and (eq (cdr reuse-indirect) 'buffer)
		 (not (eq (window-buffer window) buffer)))
	;; Pretend we were asking for a window showing the buffer of
	;; that window.
	(setq buffer (window-buffer window)))
      (prog1 (window--display-buffer buffer window 'reuse alist)
	(unless (cdr (assq 'inhibit-switch-frame alist))
	  (window--maybe-raise-frame (window-frame window)))))))