Go to the previous, next section.
In this section we describe convenient functions that choose a window automatically and use it to display a specified buffer. These functions can also split an existing window in certain circumstances. We also describe variables that parameterize the heuristics used for choosing a window. See the preceding section for low-level functions that give you more precise control.
Do not use the functions in this section in order to make a buffer
current so that a Lisp program can access or modify it; they are too
drastic for that purpose, since they change the display of buffers in
windows, which is gratuitous and will surprise the user. Instead, use
set-buffer (see section The Current Buffer) and save-excursion
(see section Excursions), which designate buffers as current for programmed
access without affecting the display of buffers in windows.
Command: switch-to-buffer buffer-or-name &optional norecord
This function makes buffer-or-name the current buffer, and also
displays the buffer in the selected window. This means that a human can
see the buffer and subsequent keyboard commands will apply to it.
Contrast this with set-buffer, which makes buffer-or-name
the current buffer but does not display it in the selected window.
See section The Current Buffer.
If buffer-or-name does not identify an existing buffer, then a new buffer by that name is created.
Normally the specified buffer is put at the front of the buffer list.
This affects the operation of other-buffer. However, if
norecord is non-nil, this is not done. See section The Buffer List.
The switch-to-buffer function is often used interactively, as
the binding of C-x b. It is also used frequently in programs. It
always returns nil.
Command: switch-to-buffer-other-window buffer-or-name
This function makes buffer-or-name the current buffer and
displays it in a window not currently selected. It then selects that
window. The handling of the buffer is the same as in
switch-to-buffer.
The previously selected window is absolutely never used to display the buffer. If it is the only window, then it is split to make a distinct window for this purpose. If the selected window is already displaying the buffer, then it continues to do so, but another window is nonetheless found to display it in as well.
Function: pop-to-buffer buffer-or-name &optional other-window
This function makes buffer-or-name the current buffer and switches to it in some window, preferably not the window previously selected. The "popped-to" window becomes the selected window.
If the variable pop-up-frames is non-nil,
pop-to-buffer creates a new frame to display the buffer in.
Otherwise, if the variable pop-up-windows is non-nil,
windows may be split to create a new window that is different from the
original window. For details, see section Choosing a Window.
If other-window is non-nil, pop-to-buffer finds or
creates another window even if buffer-or-name is already visible
in the selected window. Thus buffer-or-name could end up
displayed in two windows. On the other hand, if buffer-or-name is
already displayed in the selected window and other-window is
nil, then the selected window is considered sufficient display
for buffer-or-name, so that nothing needs to be done.
If buffer-or-name is a string that does not name an existing buffer, a buffer by that name is created.
An example use of this function is found at the end of section Process Filter Functions.
Go to the previous, next section.