Function: display-buffer-record-window

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

Signature

(display-buffer-record-window TYPE WINDOW BUFFER)

Documentation

Record information for window used by display-buffer.

WINDOW is the window used for or created by a buffer display action function. BUFFER is the buffer to display. Note that this function must be called before BUFFER is explicitly made WINDOW's buffer (although WINDOW may show BUFFER already).

TYPE specifies the type of the calling operation and must be one of the symbols reuse (meaning that WINDOW exists already and will be used for displaying BUFFER), window (WINDOW was created on an already existing frame), frame (WINDOW was created on a new frame) or tab (WINDOW is the selected window and BUFFER was created in a new tab).

This function installs or updates the quit-restore parameter of WINDOW. The quit-restore parameter is a list of four elements: The first element is one of the symbols window, frame, same or other. The second element is either one of the symbols window or frame or a list whose elements are the buffer previously shown in the window, that buffer's window start and window point, and the window's height. The third element is the window selected at the time the parameter was created. The fourth element is BUFFER.

If TYPE is reuse, BUFFER is different from the one currently displayed in WINDOW, and WINDOW already has a quit-restore parameter, install or update a quit-restore-prev parameter for this window. This allows for quitting WINDOW in a similar fashion but also keeps the very first quit-restore parameter stored for this window around. Consequently, WINDOW (or its frame) can be eventually deleted by quit-restore-widow if that parameter's fourth element equals WINDOW's buffer.

Source Code

;; Defined in /usr/src/emacs/lisp/window.el.gz
(defun display-buffer-record-window (type window buffer)
  "Record information for window used by `display-buffer'.
WINDOW is the window used for or created by a buffer display
action function.  BUFFER is the buffer to display.  Note that
this function must be called before BUFFER is explicitly made
WINDOW's buffer (although WINDOW may show BUFFER already).

TYPE specifies the type of the calling operation and must be one
of the symbols `reuse' (meaning that WINDOW exists already and
will be used for displaying BUFFER), `window' (WINDOW was created
on an already existing frame), `frame' (WINDOW was created on a
new frame) or `tab' (WINDOW is the selected window and BUFFER was
created in a new tab).

This function installs or updates the `quit-restore' parameter of
WINDOW.  The `quit-restore' parameter is a list of four elements:
The first element is one of the symbols `window', `frame', `same'
or `other'.  The second element is either one of the symbols
`window' or `frame' or a list whose elements are the buffer
previously shown in the window, that buffer's window start and
window point, and the window's height.  The third element is the
window selected at the time the parameter was created.  The
fourth element is BUFFER.

If TYPE is `reuse', BUFFER is different from the one currently displayed
in WINDOW, and WINDOW already has a `quit-restore' parameter, install or
update a `quit-restore-prev' parameter for this window.  This allows for
quitting WINDOW in a similar fashion but also keeps the very first
`quit-restore' parameter stored for this window around.  Consequently,
WINDOW (or its frame) can be eventually deleted by `quit-restore-widow'
if that parameter's fourth element equals WINDOW's buffer."
  (cond
   ((eq type 'reuse)
    (let ((quit-restore (window-parameter window 'quit-restore)))
      (if (eq (window-buffer window) buffer)
	  ;; WINDOW shows BUFFER already.  Update WINDOW's quit-restore
	  ;; parameter, if any.
	  (when (consp quit-restore)
	    (setcar quit-restore 'same)
	    ;; The selected-window might have changed in
	    ;; between (Bug#20353).
	    (unless (or (eq window (selected-window))
			(eq window (nth 2 quit-restore)))
	      (setcar (cddr quit-restore) (selected-window))))
	;; WINDOW shows another buffer.
	(with-current-buffer (window-buffer window)
	  (set-window-parameter
	   window (if quit-restore 'quit-restore-prev 'quit-restore)
	   (list 'other
		 ;; A quadruple of WINDOW's buffer, start, point and height.
		 (list (current-buffer) (window-start window)
		       ;; Preserve window-point-insertion-type (Bug#12855).
		       (copy-marker
			(window-point window) window-point-insertion-type)
		       (if (window-combined-p window)
                           (window-total-height window)
			 (window-total-width window)))
		 (selected-window) buffer))))))
   ((eq type 'window)
    ;; WINDOW has been created on an existing frame.
    (set-window-parameter
     window 'quit-restore
     (list 'window 'window (selected-window) buffer)))
   ((eq type 'frame)
    ;; WINDOW has been created on a new frame.
    (set-window-parameter
     window 'quit-restore
     (list 'frame 'frame (selected-window) buffer)))
   ((eq type 'tab)
    ;; WINDOW has been created on a new tab.
    (set-window-parameter
     window 'quit-restore
     (list 'tab 'tab (selected-window) buffer)))))