Function: replace-buffer-in-windows

replace-buffer-in-windows is an interactive and byte-compiled function defined in window.el.gz.

Signature

(replace-buffer-in-windows &optional BUFFER-OR-NAME)

Documentation

Replace BUFFER-OR-NAME with some other buffer in all windows showing it.

BUFFER-OR-NAME may be a buffer or the name of an existing buffer and defaults to the current buffer.

If the option kill-buffer-quit-windows is nil, behave as follows: With the exception of side windows, when a window showing BUFFER-OR-NAME is dedicated, delete that window. If that window is the only window on its frame, delete its frame when there are other frames left. In any other case, call switch-to-prev-buffer to display some other buffer in that window.

If kill-buffer-quit-windows is non-nil, call quit-restore-window for any window showing BUFFER-OR-NAME with the argument BURY-OR-KILL set to killing to avoid that the latter kills the buffer prematurely.

In either case, remove the buffer denoted by BUFFER-OR-NAME from the lists of previous and next buffers of all windows and remove any quit-restore or quit-restore-prev parameters mentioning it.

This function does not replace the buffer specified by BUFFER-OR-NAME in any minibuffer window showing it, nor does it delete minibuffer windows or minibuffer frames. It removes, however, that buffer from the lists of previous and next buffers of all minibuffer windows.

If, for any window showing BUFFER-OR-NAME running the abnormal hook window-deletable-functions returns nil, do not delete that window but show some other buffer in that window.

This function is called by kill-buffer which effectively kills the buffer specified by buffer-or-name afterwards. It never kills a buffer by itself.

View in manual

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/window.el.gz
;; Conceptually, 'replace-buffer-in-windows' would not have to touch the
;; list of previous buffers of a minibuffer window: As a rule,
;; minibuffers are never deleted and any other buffers shown in a
;; minibuffer window are not recorded by 'record-window'.  To be on the
;; safe side, 'replace-buffer-in-windows' now scans minibuffer windows
;; too to make sure that any killed buffer gets removed from all lists
;; of previous and next buffers.  'replace-buffer-in-windows' still does
;; _not_ replace the buffer itself in any minibuffer window showing it.
;; That case is still handled only in 'kill-buffer' itself.
(defun replace-buffer-in-windows (&optional buffer-or-name)
  "Replace BUFFER-OR-NAME with some other buffer in all windows showing it.
BUFFER-OR-NAME may be a buffer or the name of an existing buffer and
defaults to the current buffer.

If the option `kill-buffer-quit-windows' is nil, behave as follows: With
the exception of side windows, when a window showing BUFFER-OR-NAME is
dedicated, delete that window.  If that window is the only window on its
frame, delete its frame when there are other frames left.  In any other
case, call `switch-to-prev-buffer' to display some other buffer in that
window.

If `kill-buffer-quit-windows' is non-nil, call `quit-restore-window' for
any window showing BUFFER-OR-NAME with the argument BURY-OR-KILL set to
`killing' to avoid that the latter kills the buffer prematurely.

In either case, remove the buffer denoted by BUFFER-OR-NAME from the
lists of previous and next buffers of all windows and remove any
`quit-restore' or `quit-restore-prev' parameters mentioning it.

This function does not replace the buffer specified by BUFFER-OR-NAME in
any minibuffer window showing it, nor does it delete minibuffer windows
or minibuffer frames.  It removes, however, that buffer from the lists
of previous and next buffers of all minibuffer windows.

If, for any window showing BUFFER-OR-NAME running the abnormal hook
`window-deletable-functions' returns nil, do not delete that window but
show some other buffer in that window.

This function is called by `kill-buffer' which effectively kills the
buffer specified by `buffer-or-name' afterwards.  It never kills a
buffer by itself."
  (interactive "bBuffer to replace: ")
  (let ((buffer (window-normalize-buffer buffer-or-name)))
    ;; Scan all windows including minibuffer windows.  We have to
    ;; unrecord BUFFER-OR-NAME even in those not showing it.
    (dolist (window (window-list-1 nil t t))
      (when (eq (window-buffer window) buffer)
	(cond
	 ((window-minibuffer-p window))
	 (kill-buffer-quit-windows
	  ;; Try to preserve the current buffer set up by 'kill-buffer'
	  ;; before running the hooks on 'kill-buffer-hook' (Bug#75949).
	  (let ((current-buffer (current-buffer)))
	    (quit-restore-window window 'killing)
	    (when (buffer-live-p current-buffer)
	      (set-buffer current-buffer))))
	 (t
	  (let ((dedicated-side (eq (window-dedicated-p window) 'side)))
            (when (or dedicated-side (not (window--delete window t 'kill)))
	      ;; Switch to another buffer in that window.
	      (set-window-dedicated-p window nil)
	      (if (switch-to-prev-buffer window 'kill)
                  (and dedicated-side (set-window-dedicated-p window 'side))
		(window--delete window nil 'kill))))))

	(when (window-live-p window)
	  ;; If the fourth elements of the 'quit-restore' or
	  ;; 'quit-restore-prev' parameters equal BUFFER, these
	  ;; parameters become useless - in 'quit-restore-window' the
	  ;; fourth element must equal the buffer of WINDOW in order to
	  ;; use that parameter.  If BUFFER is mentioned in the second
	  ;; element of the parameter, 'quit-restore-window' cannot
	  ;; possibly show BUFFER instead; so this parameter becomes
	  ;; useless too.
	  (unrecord-window-buffer window buffer t))))))