display-buffer flexibly chooses a window for
display, and displays a specified buffer in that window. It can be
called interactively, via the key binding C-x 4 C-o. It is also
used as a subroutine by many functions and commands, including
pop-to-buffer (see Switching Buffers).
This command performs several complex steps to find a window to
display in. These steps are described by means of display
actions, which have the form
(function . alist).
Here, function is either a function or a list of functions,
which we refer to as action functions; alist is an
association list, which we refer to as an action alist.
An action function accepts two arguments: the buffer to display and
an action alist. It attempts to display the buffer in some window,
picking or creating a window according to its own criteria. If
successful, it returns the window; otherwise, it returns
See Display Action Functions, for a list of predefined action
display-buffer works by combining display actions from
several sources, and calling the action functions in turn, until one
of them manages to display the buffer and returns a non-
This command makes buffer-or-name appear in some window, without selecting the window or making the buffer current. The argument buffer-or-name must be a buffer or the name of an existing buffer. The return value is the window chosen to display the buffer.
The optional argument action, if non-
nil, should normally
be a display action (described above).
display-buffer builds a
list of action functions and an action alist, by consolidating display
actions from the following sources (in order):
Each action function is called in turn, passing the buffer as the
first argument and the combined action alist as the second argument,
until one of the functions returns non-
nil. The caller can
(allow-no-window . t) as an element of the action alist to
indicate its readiness to handle the case of not displaying the
buffer in a window.
The argument action can also have a non-
value. This has the special meaning that the buffer should be
displayed in a window other than the selected one, even if the
selected window is already displaying it. If called interactively
with a prefix argument, action is
The optional argument frame, if non-
nil, specifies which
frames to check when deciding whether the buffer is already displayed.
It is equivalent to adding an element
. frame) to the action alist of action. See Display Action Functions.
The value of this variable should be a display action, which is
treated with the highest priority by
default value is empty, i.e.,
(nil . nil).
The value of this option is an alist mapping conditions to display
actions. Each condition may be either a regular expression matching a
buffer name or a function that takes two arguments: a buffer name and
the action argument passed to
display-buffer. If the name
of the buffer passed to
display-buffer either matches a regular
expression in this alist or the function specified by a condition
display-buffer uses the
corresponding display action to display the buffer.
The value of this option should be a display action. This option can
be used to define a standard display action for calls to
This display action specifies the fallback behavior for
display-buffer if no other display actions are given.