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
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 action alists.
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-bufferbuilds a list of action functions and an action alist, by consolidating display actions from the following sources (in order):
- The variable
- The user option
- The action argument.
- The user option
- The constant
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 pass
(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-
nil, non-list 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
)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
display-buffer. The 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-buffereither matches a regular expression in this alist or the function specified by a condition returns non-
display-bufferuses 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