elisp: Switching Buffers
27.12 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 (
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’. 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’ (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’ (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 (Buffer List). However, this is not done if the
optional argument NORECORD is non-‘nil’.
Sometimes, the selected window may not be suitable for displaying
the buffer. This happens if the selected window is a minibuffer
window, or if the selected window is strongly dedicated to its
buffer (Dedicated Windows). In such cases, the command
normally tries to display the buffer in some other window, by
invoking ‘pop-to-buffer’ (see below).
If the optional argument FORCE-SAME-WINDOW is non-‘nil’ and the
selected window is not suitable for displaying the buffer, this
function always signals an error when called non-interactively. In
interactive use, if the selected window is a minibuffer window,
this function will try to use some other window instead. If the
selected window is strongly dedicated to its buffer, the option
‘switch-to-buffer-in-dedicated-window’ described next can be used
to proceed.
-- User Option: switch-to-buffer-in-dedicated-window
This option, if non-‘nil’, allows ‘switch-to-buffer’ to proceed
when called interactively and the selected window is strongly
dedicated to its buffer.
The following values are respected:
‘nil’
Disallows switching and signals an error as in non-interactive
use.
‘prompt’
Prompts the user whether to allow switching.
‘pop’
Invokes ‘pop-to-buffer’ to proceed.
‘t’
Marks the selected window as non-dedicated and proceeds.
This option does not affect non-interactive calls of
‘switch-to-buffer’.
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. 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 currently selected.
It then selects the displaying window. If that window is on a
different graphical frame, that frame is given input focus if
possible (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’ (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’ (Major Modes).
If ACTION is non-‘nil’, it should be a display action to pass to
‘display-buffer’ (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’.
Info Catalog
elisp: Buffers and Windows
elisp: Windows
elisp: Choosing Window