Function: pop-to-buffer

pop-to-buffer is an interactive and byte-compiled function defined in window.el.gz.

Signature

(pop-to-buffer BUFFER-OR-NAME &optional ACTION NORECORD)

Documentation

Display buffer specified by BUFFER-OR-NAME and select its window.

BUFFER-OR-NAME may be a buffer, a string (a buffer name), or nil. If it is a string not naming an existent buffer, create a buffer with that name. If BUFFER-OR-NAME is nil, choose some other buffer. In either case, make that buffer current and return it.

This uses display-buffer as a subroutine. The optional ACTION argument is passed to display-buffer as its ACTION argument. See display-buffer for more information. ACTION is t if called interactively with a prefix argument, which means to pop to a window other than the selected one even if the buffer is already displayed in the selected window.

If a suitable window is found, select that window. If it is not on the selected frame, raise that window's frame and give it input focus.

Optional third arg NORECORD non-nil means do not put this buffer at the front of the list of recently selected ones.

Other relevant functions are documented in the buffer group.

View in manual

Probably introduced at or before Emacs version 17.

Key Bindings

Shortdoc

;; buffer
(pop-to-buffer "*foo*")
    e.g. => #<buffer *foo*>

Source Code

;; Defined in /usr/src/emacs/lisp/window.el.gz
;;; Display + selection commands:
(defun pop-to-buffer (buffer-or-name &optional action norecord)
  "Display buffer specified by BUFFER-OR-NAME and select its window.
BUFFER-OR-NAME may be a buffer, a string (a buffer name), or nil.
If it is a string not naming an existent buffer, create a buffer
with that name.  If BUFFER-OR-NAME is nil, choose some other
buffer.  In either case, make that buffer current and return it.

This uses `display-buffer' as a subroutine.  The optional ACTION
argument is passed to `display-buffer' as its ACTION argument.
See `display-buffer' for more information.  ACTION is t if called
interactively with a prefix argument, which means to pop to a
window other than the selected one even if the buffer is already
displayed in the selected window.

If a suitable window is found, select that window.  If it is not
on the selected frame, raise that window's frame and give it
input focus.

Optional third arg NORECORD non-nil means do not put this buffer
at the front of the list of recently selected ones."
  (interactive (list (read-buffer "Pop to buffer: " (other-buffer))
		     (if current-prefix-arg t)))
  (let* ((buffer (window-normalize-buffer-to-switch-to buffer-or-name))
         (old-frame (selected-frame))
	 (window (display-buffer buffer action)))
    ;; Don't assume that `display-buffer' has supplied us with a window
    ;; (Bug#24332).
    (if window
        (let ((frame (window-frame window)))
          ;; If we chose another frame, make sure it gets input focus.
          (unless (eq frame old-frame)
            (select-frame-set-input-focus frame norecord))
          ;; Make sure the window is selected (Bug#8615), (Bug#6954)
          (select-window window norecord))
      ;; If `display-buffer' failed to supply a window, just make the
      ;; buffer current.
      (set-buffer buffer))
    ;; Return BUFFER even when we got no window.
    buffer))