Function: window--display-buffer

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

Signature

(window--display-buffer BUFFER WINDOW TYPE &optional ALIST)

Documentation

Display BUFFER in WINDOW.

WINDOW must be a live window chosen by a buffer display action function for showing BUFFER. TYPE tells whether WINDOW existed already before that action function was called or is a new window created by that function. ALIST is a buffer display action alist as compiled by display-buffer.

TYPE must be one of the following symbols: reuse (which means WINDOW existed before the call of display-buffer and may already show BUFFER or not), window (WINDOW was created on an existing frame), frame (WINDOW was created on a new frame), or tab
(WINDOW is the selected window and BUFFER was displayed in a new tab).
TYPE is passed unaltered to display-buffer-record-window.

Handle WINDOW's dedicated flag as follows: If WINDOW already shows BUFFER, leave it alone. Otherwise, if ALIST contains a dedicated entry and WINDOW is either new or that entry's value equals side, set WINDOW's dedicated flag to the value of that entry. Otherwise, if WINDOW is new and the value of display-buffer-mark-dedicated is non-nil, set WINDOW's dedicated flag to that value. In any other case, reset WINDOW's dedicated flag to nil.

If ALIST contains a non-nil bump-use-time entry, bump use time of WINDOW so further calls of display-buffer-use-some-window and display-buffer-use-least-recent-window will try to avoid it.

Return WINDOW if BUFFER and WINDOW are live.

Source Code

;; Defined in /usr/src/emacs/lisp/window.el.gz
(defun window--display-buffer (buffer window type &optional alist)
  "Display BUFFER in WINDOW.
WINDOW must be a live window chosen by a buffer display action
function for showing BUFFER.  TYPE tells whether WINDOW existed
already before that action function was called or is a new window
created by that function.  ALIST is a buffer display action alist
as compiled by `display-buffer'.

TYPE must be one of the following symbols: `reuse' (which means
WINDOW existed before the call of `display-buffer' and may
already show BUFFER or not), `window' (WINDOW was created on an
existing frame), `frame' (WINDOW was created on a new frame), or `tab'
(WINDOW is the selected window and BUFFER was displayed in a new tab).
TYPE is passed unaltered to `display-buffer-record-window'.

Handle WINDOW's dedicated flag as follows: If WINDOW already
shows BUFFER, leave it alone.  Otherwise, if ALIST contains a
`dedicated' entry and WINDOW is either new or that entry's value
equals `side', set WINDOW's dedicated flag to the value of that
entry.  Otherwise, if WINDOW is new and the value of
`display-buffer-mark-dedicated' is non-nil, set WINDOW's
dedicated flag to that value.  In any other case, reset WINDOW's
dedicated flag to nil.

If ALIST contains a non-nil `bump-use-time' entry, bump use time
of WINDOW so further calls of `display-buffer-use-some-window'
and `display-buffer-use-least-recent-window' will try to avoid
it.

Return WINDOW if BUFFER and WINDOW are live."
  (when (and (buffer-live-p buffer) (window-live-p window))
    (display-buffer-record-window type window buffer)
    (unless (eq buffer (window-buffer window))
      ;; Unless WINDOW already shows BUFFER reset its dedicated flag.
      (set-window-dedicated-p window nil)
      (set-window-buffer window buffer))
    (when (cdr (assq 'bump-use-time alist))
      ;; Bump WINDOW's use time so 'display-buffer--lru-window' will try
      ;; to avoid it.
      (window-bump-use-time window))
    (let ((alist-dedicated (assq 'dedicated alist)))
      ;; Maybe dedicate WINDOW to BUFFER if asked for.
      (cond
       ;; Don't dedicate WINDOW if it is dedicated because it shows
       ;; BUFFER already or it is reused and is not a side window.
       ((or (window-dedicated-p window)
            (and (eq type 'reuse)
		 (not (window-parameter window 'window-side)))))
       ;; Otherwise, if ALIST contains a 'dedicated' entry, use that
       ;; entry's value (which may be nil).
       (alist-dedicated
        (set-window-dedicated-p window (cdr alist-dedicated)))
       ;; Otherwise, if 'display-buffer-mark-dedicated' is non-nil,
       ;; use that.
       (display-buffer-mark-dedicated
        (set-window-dedicated-p window display-buffer-mark-dedicated))))
    (when (memq type '(window frame tab))
      (set-window-prev-buffers window nil))

    (when (functionp (cdr (assq 'body-function alist)))
      (let ((inhibit-read-only t)
            (inhibit-modification-hooks t))
        (funcall (cdr (assq 'body-function alist)) window)))

    (let* ((frame (window-frame window))
           (quit-restore (window-parameter window 'quit-restore))
	   (window-height (assq 'window-height alist))
           (height (cdr window-height))
	   (window-width (assq 'window-width alist))
           (width (cdr window-width))
           (window-size (assq 'window-size alist))
           (size (cdr window-size))
	   (preserve-size (cdr (assq 'preserve-size alist))))
      (cond
       ((or (eq type 'frame)
	    (and (eq (car quit-restore) 'same)
		 (eq (nth 1 quit-restore) 'frame)))
	;; A window that never showed another buffer but BUFFER ever
        ;; since it was created on a new frame.
        ;;
        ;; Adjust size of frame if asked for.  We probably should do
        ;; that only for a single window frame.
	(cond
	 ((not size)
          (when window-size
            (setq resize-temp-buffer-window-inhibit t)))
	 ((consp size)
          ;; Modifying the parameters of a newly created frame might
          ;; not work everywhere, but then `temp-buffer-resize-mode'
          ;; will certainly fail in a similar fashion.
          (if (eq (car size) 'body-chars)
	      (let ((width (+ (frame-text-width frame)
                              (* (frame-char-width frame) (cadr size))
                              (- (window-body-width window t))))
                    (height (+ (frame-text-height frame)
                               (* (frame-char-height frame) (cddr size))
                               (- (window-body-height window t)))))
                (modify-frame-parameters
                 frame `((height . (text-pixels . ,height))
                         (width . (text-pixels . ,width)))))
	    (let ((width (- (+ (frame-width frame) (car size))
                            (window-total-width window)))
                  (height (- (+ (frame-height frame) (cdr size))
                             (window-total-height window))))
	      (modify-frame-parameters
	       frame `((height . ,height) (width . ,width)))))
          (setq resize-temp-buffer-window-inhibit t))
         ((functionp size)
	  (ignore-errors (funcall size window))
          (setq resize-temp-buffer-window-inhibit t))))
       ((or (eq type 'window)
	    (and (eq (car quit-restore) 'same)
		 (eq (nth 1 quit-restore) 'window)))
	;; A window that never showed another buffer but BUFFER ever
        ;; since it was created on an existing frame.  Adjust its width
        ;; and/or height if asked for.
	(cond
         ((not height)
	  (when window-height
            (setq resize-temp-buffer-window-inhibit 'vertical)))
	 ((numberp height)
	  (let* ((new-height
		  (if (integerp height)
		      height
		    (round
		     (* (window-total-height (frame-root-window window))
			height))))
		 (delta (- new-height (window-total-height window))))
	    (when (and (window--resizable-p window delta nil 'safe)
		       (window-combined-p window))
	      (window-resize window delta nil 'safe)))
          (setq resize-temp-buffer-window-inhibit 'vertical))
         ((and (consp height) (eq (car height) 'body-lines))
	  (let* ((delta (- (* (frame-char-height frame) (cdr height))
                           (window-body-height window t))))
	    (and (window--resizable-p window delta nil 'safe nil nil nil t)
		 (window-combined-p window)
                 (window-resize window delta nil 'safe t)))
          (setq resize-temp-buffer-window-inhibit 'vertical))
         ((functionp height)
	  (ignore-errors (funcall height window))
          (setq resize-temp-buffer-window-inhibit 'vertical)))
	;; Adjust width of window if asked for.
	(cond
	 ((not width)
          (when window-width
            (setq resize-temp-buffer-window-inhibit 'horizontal)))
	 ((numberp width)
	  (let* ((new-width
		  (if (integerp width)
		      width
		    (round
		     (* (window-total-width (frame-root-window window))
			width))))
		 (delta (- new-width (window-total-width window))))
	    (when (and (window--resizable-p window delta t 'safe)
		       (window-combined-p window t))
	      (window-resize window delta t 'safe)))
          (setq resize-temp-buffer-window-inhibit 'horizontal))
         ((and (consp width) (eq (car width) 'body-columns))
	  (let* ((delta (- (* (frame-char-width frame) (cdr width))
                           (window-body-width window t))))
	    (and (window--resizable-p window delta t 'safe nil nil nil t)
		 (window-combined-p window t)
                 (window-resize window delta t 'safe t)))
          (setq resize-temp-buffer-window-inhibit 'horizontal))
	 ((functionp width)
	  (ignore-errors (funcall width window))
          (setq resize-temp-buffer-window-inhibit 'horizontal)))

	;; Preserve window size if asked for.
	(when (consp preserve-size)
	  (window-preserve-size window t (car preserve-size))
	  (window-preserve-size window nil (cdr preserve-size)))))

      ;; Assign any window parameters specified.
      (let ((parameters (cdr (assq 'window-parameters alist))))
        (dolist (parameter parameters)
          (set-window-parameter
           window (car parameter) (cdr parameter)))))
    window))