27.11 Switching to a Buffer in a Window

This section describes high-level functions for switching to a specified buffer in some window. In general, “switching to a buffer” means to (1) show the buffer in some window, (2) make that window the selected window (and its frame the selected frame), and (3) make the buffer the current buffer.

Do not use these functions to make a buffer temporarily current just so a Lisp program can access or modify it. They have side-effects, such as changing window histories (see Window History), which will surprise the user if used that way. If you want to make a buffer current to modify it in Lisp, use with-current-buffer, save-current-buffer, or set-buffer. See Current Buffer.

Command: switch-to-buffer buffer-or-name &optional norecord force-same-window

This command attempts to display buffer-or-name in the selected window and make it the current buffer. It is often used interactively (as the binding of C-x b), as well as in Lisp programs. The return value is the buffer switched to.

If buffer-or-name is nil, it defaults to the buffer returned by other-buffer (see Buffer List). If buffer-or-name is a string that is not the name of any existing buffer, this function creates a new buffer with that name; the new buffer’s major mode is determined by the variable major-mode (see Major Modes).

Normally, the specified buffer is put at the front of the buffer list—both the global buffer list and the selected frame’s buffer list (see Buffer List). However, this is not done if the optional argument norecord is non-nil.

Sometimes, switch-to-buffer may be unable to display the buffer in the selected window. This happens if the selected window is a minibuffer window, or if the selected window is strongly dedicated to its buffer (see Dedicated Windows). In that case, the command normally tries to display the buffer in some other window, by invoking pop-to-buffer (see below). However, if the optional argument force-same-window is non-nil, it signals an error instead.

By default, switch-to-buffer shows the buffer at its position of point. This behavior can be tuned using the following option.

User Option: switch-to-buffer-preserve-window-point

If this variable is nil, switch-to-buffer displays the buffer specified by buffer-or-name at the position of that buffer’s point. If this variable is already-displayed, it tries to display the buffer at its previous position in the selected window, provided the buffer is currently displayed in some other window on any visible or iconified frame. If this variable is t, switch-to-buffer unconditionally tries to display the buffer at its previous position in the selected window.

This variable is ignored if the buffer is already displayed in the selected window or never appeared in it before, or if switch-to-buffer calls pop-to-buffer to display the buffer.

The next two commands are similar to switch-to-buffer, except for the described features.

Command: switch-to-buffer-other-window buffer-or-name &optional norecord

This function displays the buffer specified by buffer-or-name in some window other than the selected window. It uses the function pop-to-buffer internally (see below).

If the selected window already displays the specified buffer, it continues to do so, but another window is nonetheless found to display it as well.

The buffer-or-name and norecord arguments have the same meanings as in switch-to-buffer.

Command: switch-to-buffer-other-frame buffer-or-name &optional norecord

This function displays the buffer specified by buffer-or-name in a new frame. It uses the function pop-to-buffer internally (see below).

If the specified buffer is already displayed in another window, in any frame on the current terminal, this switches to that window instead of creating a new frame. However, the selected window is never used for this.

The buffer-or-name and norecord arguments have the same meanings as in switch-to-buffer.

The above commands use the function pop-to-buffer, which flexibly displays a buffer in some window and selects that window for editing. In turn, pop-to-buffer uses display-buffer for displaying the buffer. Hence, all the variables affecting display-buffer will affect it as well. See Choosing Window, for the documentation of display-buffer.

Command: pop-to-buffer buffer-or-name &optional action norecord

This function makes buffer-or-name the current buffer and displays it in some window, preferably not the window previously selected. It then selects the displaying window. If that window is on a different graphical frame, that frame is given input focus if possible (see Input Focus). The return value is the buffer that was switched to.

If buffer-or-name is nil, it defaults to the buffer returned by other-buffer (see Buffer List). If buffer-or-name is a string that is not the name of any existing buffer, this function creates a new buffer with that name; the new buffer’s major mode is determined by the variable major-mode (see Major Modes).

If action is non-nil, it should be a display action to pass to display-buffer (see Choosing Window). Alternatively, a non-nil, non-list value means to pop to a window other than the selected one—even if the buffer is already displayed in the selected window.

Like switch-to-buffer, this function updates the buffer list unless norecord is non-nil.