Next: Display Action Functions, Previous: Switching Buffers, Up: Windows [Contents][Index]

### 27.13 Choosing a Window for Display

The command `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 `switch-to-buffer` and `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 `nil`. See Display Action Functions, for a list of predefined action functions.

`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-`nil` value.

Command: display-buffer buffer-or-name &optional action frame

  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):

  - The variable `display-buffer-overriding-action`.
  - The user option `display-buffer-alist`.
  - The action argument.
  - The user option `display-buffer-base-action`.
  - The constant `display-buffer-fallback-action`.

  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 `t`.

  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 `(reusable-frames . frame)` to the action alist of action. See Display Action Functions.

Variable: display-buffer-overriding-action

  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)`.

User Option: display-buffer-alist

  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 returns non-`nil`, then `display-buffer` uses the corresponding display action to display the buffer.

User Option: display-buffer-base-action

  The value of this option should be a display action. This option can be used to define a standard display action for calls to `display-buffer`.

Constant: display-buffer-fallback-action

  This display action specifies the fallback behavior for `display-buffer` if no other display actions are given.

Next: Display Action Functions, Previous: Switching Buffers, Up: Windows [Contents][Index]