Function: display-buffer-in-direction

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

Signature

(display-buffer-in-direction BUFFER ALIST)

Documentation

Try to display BUFFER in a direction specified by ALIST.

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

ALIST has to contain a direction entry whose value should be one of left, above (or up), right and below (or down). Other values are usually interpreted as below.

If ALIST also contains a window entry, its value specifies a reference window. That value can be a special symbol like main (which stands for the selected frame's main window) or root (standings for the selected frame's root window) or an arbitrary valid window. Any other value (or omitting the window entry) means to use the selected window as reference window.

This function tries to reuse or split a window such that the window produced this way is on the side of the reference window specified by the direction entry.

Four special values for direction entries allow to implicitly specify the selected frame's main window as reference window: leftmost, top, rightmost and bottom. Hence, instead of
(direction . left) (window . main) one can simply write
(direction . leftmost).

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

Source Code

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

ALIST has to contain a `direction' entry whose value should be
one of `left', `above' (or `up'), `right' and `below' (or `down').
Other values are usually interpreted as `below'.

If ALIST also contains a `window' entry, its value specifies a
reference window.  That value can be a special symbol like
`main' (which stands for the selected frame's main window) or
`root' (standings for the selected frame's root window) or an
arbitrary valid window.  Any other value (or omitting the
`window' entry) means to use the selected window as reference
window.

This function tries to reuse or split a window such that the
window produced this way is on the side of the reference window
specified by the `direction' entry.

Four special values for `direction' entries allow to implicitly
specify the selected frame's main window as reference window:
`leftmost', `top', `rightmost' and `bottom'.  Hence, instead of
`(direction . left) (window . main)' one can simply write
`(direction . leftmost)'.

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 ((direction (cdr (assq 'direction alist))))
    (when direction
      (let ((window (cdr (assq 'window alist)))
	    within windows other-window-shows-buffer other-window)
	;; Sanitize WINDOW.
	(cond
	 ((or (eq window 'main)
              (memq direction '(top bottom leftmost rightmost)))
	  (setq window (window-main-window)))
	 ((eq window 'root)
	  (setq window (frame-root-window)))
	 ((window-valid-p window))
	 (t
	  (setq window (selected-window))))
	(setq within (not (window-live-p window)))
	;; Sanitize DIRECTION
	(cond
	 ((memq direction '(left above right below)))
	 ((eq direction 'leftmost)
	  (setq direction 'left))
	 ((memq direction '(top up))
	  (setq direction 'above))
	 ((eq direction 'rightmost)
	  (setq direction 'right))
	 ((memq direction '(bottom down))
	  (setq direction 'below))
	 (t
	  (setq direction 'below)))

	(setq alist
	      (append alist
		      `(,(if temp-buffer-resize-mode
                             '(window-height . resize-temp-buffer-window)
                           '(window-height . fit-window-to-buffer))
                        ,(when temp-buffer-resize-mode
                           '(preserve-size . (nil . t))))))

	(setq windows (windows-sharing-edge window direction within))
	(dolist (other windows)
	  (cond
	   ((and (not other-window-shows-buffer)
		 (eq buffer (window-buffer other)))
	    (setq other-window-shows-buffer t)
	    (setq other-window other))
	   ((not other-window)
	    (setq other-window other))))
	(or (and other-window-shows-buffer
		 (window--display-buffer buffer other-window 'reuse alist))
	    (and (setq other-window
		       (window--try-to-split-window-in-direction
			window direction alist))
		 (window--display-buffer buffer other-window 'window alist))
	    (and (setq window other-window)
		 (not (window-dedicated-p other-window))
		 (not (window-minibuffer-p other-window))
		 (window--display-buffer buffer other-window 'reuse alist)))))))