Function: display-buffer-use-some-window

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

Signature

(display-buffer-use-some-window BUFFER ALIST)

Documentation

Display BUFFER in an existing window.

Search for a usable window, set that window to the buffer, and return the window. If no suitable window is found, return nil.

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-switch-frame entry, then in the event that a window on another frame is chosen, avoid raising that frame.

If ALIST contains a non-nil some-window entry, then prefer the least recently used window if the entry's value is lru or nil, or the most recently used window if it's mru. If the value is a function, it is called with two arguments: a buffer and an alist, and should return the window where to display the buffer.

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

Source Code

;; Defined in /usr/src/emacs/lisp/window.el.gz
(defun display-buffer-use-some-window (buffer alist)
  "Display BUFFER in an existing window.
Search for a usable window, set that window to the buffer, and
return the window.  If no suitable window is found, return nil.

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-switch-frame' entry, then in the
event that a window on another frame is chosen, avoid raising
that frame.

If ALIST contains a non-nil `some-window' entry, then prefer the least
recently used window if the entry's value is `lru' or nil, or the most
recently used window if it's `mru'.  If the value is a function, it is
called with two arguments: a buffer and an alist, and should return
the window where to display the buffer.

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* ((not-this-window (cdr (assq 'inhibit-same-window alist)))
	 (some-window-method (cdr (assq 'some-window alist)))
	 (frame (or (window--frame-usable-p (selected-frame))
		    (window--frame-usable-p (last-nonminibuffer-frame))))
	 (window
	  ;; Reuse an existing window.
	  (or (cond
	       ((memq some-window-method '(nil lru))
		(display-buffer--lru-window
		 ;; If ALIST specifies 'lru-frames' or 'window-min-width'
		 ;; let them prevail.
		 (append alist `((lru-frames . ,frame)
				 (window-min-width . full-width)))))
	       ((eq some-window-method 'mru)
		(get-mru-window nil nil t))
	       ((functionp some-window-method)
		(funcall some-window-method buffer alist)))
	      (let ((window (get-buffer-window buffer 'visible)))
		(unless (and not-this-window
			     (eq window (selected-window)))
		  window))
	      (get-largest-window 'visible nil not-this-window)
	      (let ((window (get-buffer-window buffer 0)))
		(unless (and not-this-window
			     (eq window (selected-window)))
		  window))
	      (get-largest-window 0 nil not-this-window)))
	 (quit-restore (and (window-live-p window)
			    (window-parameter window 'quit-restore)))
	 (quad (nth 1 quit-restore)))
    (when (window-live-p window)
      ;; If the window was used by `display-buffer' before, try to
      ;; resize it to its old height but don't signal an error.
      (when (and (listp quad)
		 (integerp (nth 3 quad))
		 (> (nth 3 quad) (window-total-height window)))
	(condition-case nil
	    (window-resize window (- (nth 3 quad) (window-total-height window)))
	  (error nil)))

      (prog1
	  (window--display-buffer buffer window 'reuse alist)
	(window--even-window-sizes window)
	(unless (cdr (assq 'inhibit-switch-frame alist))
	  (window--maybe-raise-frame (window-frame window)))))))