Next: Temporary Displays, Up: Displaying Buffers [Contents][Index]

#### 20.6.1 How `display-buffer` works

The `display-buffer` command (as well as commands that call it internally) chooses a window to display by following the steps given below. See Choosing a Window for Display in The Emacs Lisp Reference Manual, for details about how to alter this sequence of steps.

- First, check if the buffer should be displayed in the selected window regardless of other considerations. You can tell Emacs to do this by adding the desired buffer’s name to the list `same-window-buffer-names`, or adding a matching regular expression to the list `same-window-regexps`. By default, these variables are `nil`, so this step is skipped.
- Otherwise, if the buffer is already displayed in an existing window, reuse that window. Normally, only windows on the selected frame are considered, but windows on other frames are also reusable if you change `pop-up-frames` (see below) to `t`.
- Otherwise, optionally create a new frame and display the buffer there. By default, this step is skipped. To enable it, change the variable `pop-up-frames` to a non-`nil` value. The special value `graphic-only` means to do this only on graphical displays.
- Otherwise, try to create a new window by splitting a window on the selected frame, and display the buffer in that new window.

  The split can be either vertical or horizontal, depending on the variables `split-height-threshold` and `split-width-threshold`. These variables should have integer values. If `split-height-threshold` is smaller than the chosen window’s height, the split puts the new window below. Otherwise, if `split-width-threshold` is smaller than the window’s width, the split puts the new window on the right. If neither condition holds, Emacs tries to split so that the new window is below—but only if the window was not split before (to avoid excessive splitting).

- Otherwise, display the buffer in a window previously showing it. Normally, only windows on the selected frame are considered, but if `pop-up-frames` is non-`nil` the window may be also on another frame.
- Otherwise, display the buffer in an existing window on the selected frame.
- If all the above methods fail for whatever reason, create a new frame and display the buffer there.

A more advanced and flexible way to customize the behavior of `display-buffer` is by using the option `display-buffer-alist` mentioned in the next section.

Next: Temporary Displays, Up: Displaying Buffers [Contents][Index]