Function: display-buffer-use-least-recent-window

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

Signature

(display-buffer-use-least-recent-window BUFFER ALIST)

Documentation

Display BUFFER trying to avoid windows used recently.

This is similar to display-buffer-use-some-window but tries hard to avoid using a window recently used by display-buffer.

Distinctive features are:

- Do not use the selected window.

- Try first to reuse a window that shows BUFFER already on a
  frame specified by a reusable-frames ALIST entry, using the
  selected frame if no such entry has been specified.

- Next try to show BUFFER in the least recently used window. The
  frames to search for such a window can be specified via a
  lru-frames ALIST entry; if no such entry exists, search the
  selected frame only. In addition, try to satisfy constraints
  specified by the following ALIST entries, if present:

  lru-time specifies a use time. Do not return a window whose
    use time is higher than this. When calling this action
    function repeatedly (presumably to display several buffers in
    a row), an application should first save the use time of the
    selected window and pass that same value via such an entry in
    each call of display-buffer. This reduces the probability
    that display-buffer uses the same window as a previous
    call.

  window-min-width specifies a preferred minimum width in
    canonical frame columns. If it is the symbol full-width,
    prefer a full-width window.

  window-min-height specifies a preferred minimum height in
    canonical frame lines. If it is the symbol full-height,
    prefer a full-height window.

- If the preceding steps fail, try to pop up a new window on the
  selected frame.

If a window is found, bump the use time of that window to the highest use time after the selected window. This makes it less probable that a future invocation of this function uses that window for another buffer.

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-least-recent-window (buffer alist)
  "Display BUFFER trying to avoid windows used recently.
This is similar to `display-buffer-use-some-window' but tries
hard to avoid using a window recently used by `display-buffer'.

Distinctive features are:

- Do not use the selected window.

- Try first to reuse a window that shows BUFFER already on a
  frame specified by a `reusable-frames' ALIST entry, using the
  selected frame if no such entry has been specified.

- Next try to show BUFFER in the least recently used window.  The
  frames to search for such a window can be specified via a
  `lru-frames' ALIST entry; if no such entry exists, search the
  selected frame only.  In addition, try to satisfy constraints
  specified by the following ALIST entries, if present:

  `lru-time' specifies a use time.  Do not return a window whose
    use time is higher than this.  When calling this action
    function repeatedly (presumably to display several buffers in
    a row), an application should first save the use time of the
    selected window and pass that same value via such an entry in
    each call of `display-buffer'.  This reduces the probability
    that `display-buffer' uses the same window as a previous
    call.

  `window-min-width' specifies a preferred minimum width in
    canonical frame columns.  If it is the symbol `full-width',
    prefer a full-width window.

  `window-min-height' specifies a preferred minimum height in
    canonical frame lines.  If it is the symbol `full-height',
    prefer a full-height window.

- If the preceding steps fail, try to pop up a new window on the
  selected frame.

If a window is found, bump the use time of that window to the
highest use time after the selected window.  This makes it less
probable that a future invocation of this function uses that
window for another buffer."
  (let* ((alist (cons (cons 'inhibit-same-window t) alist))
         (window
          (or (display-buffer-reuse-window buffer alist)
              (let ((window (display-buffer--lru-window alist)))
                (when (window-live-p window)
                  (let* ((quit-restore (window-parameter window 'quit-restore))
                         (quad (nth 1 quit-restore)))
                    ;; 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)))))))
              (display-buffer-pop-up-window buffer alist))))
    ;; Don't bump use time twice.
    (when (and window (not (cdr (assq 'bump-use-time alist))))
      (window-bump-use-time window))
    window))