GNU Emacs Lisp Reference Manual

25.8: Choosing a Window for Display

This section describes the basic facility that chooses a window to display a buffer in---display-buffer. All the higher-level functions and commands use this subroutine. Here we describe how to use display-buffer and how to customize it.

Command: display-buffer buffer-or-name &optional not-this-window

This command makes buffer-or-name appear in some window, like pop-to-buffer, but it does not select that window and does not make the buffer current. The identity of the selected window is unaltered by this function.

If not-this-window is non-nil, it means to display the specified buffer in a window other than the selected one, even if it is already on display in the selected window. This can cause the buffer to appear in two windows at once. Otherwise, if buffer-or-name is already being displayed in any window, that is good enough, so this function does nothing.

display-buffer returns the window chosen to display buffer-or-name.

Precisely how display-buffer finds or creates a window depends on the variables described below.

User Option: pop-up-windows

This variable controls whether display-buffer makes new windows. If it is non-nil and there is only one window, then that window is split. If it is nil, then display-buffer does not split the single window, but uses it whole.

User Option: split-height-threshold

This variable determines when display-buffer may split a window, if there are multiple windows. display-buffer always splits the largest window if it has at least this many lines. If the largest window is not this tall, it is split only if it is the sole window and pop-up-windows is non-nil.

User Option: pop-up-frames

This variable controls whether display-buffer makes new frames. If it is non-nil, display-buffer looks for an existing window already displaying the desired buffer, on any visible frame. If it finds one, it returns that window. Otherwise it makes a new frame. The variables pop-up-windows and split-height-threshold do not matter if pop-up-frames is non-nil.

If pop-up-frames is nil, then display-buffer either splits a window or reuses one.

See Frames, for more information.

Variable: pop-up-frame-function

This variable specifies how to make a new frame if pop-up-frames is non-nil.

Its value should be a function of no arguments. When display-buffer makes a new frame, it does so by calling that function, which should return a frame. The default value of the variable is a function that creates a frame using parameters from pop-up-frame-alist.

Variable: pop-up-frame-alist

This variable holds an alist specifying frame parameters used when display-buffer makes a new frame. See Frame Parameters, for more information about frame parameters.

Variable: special-display-buffer-names

A list of buffer names for buffers that should be displayed specially. If the buffer's name is in this list, display-buffer handles the buffer specially.

By default, special display means to give the buffer a dedicated frame.

If an element is a list, instead of a string, then the CAR of the list is the buffer name, and the rest of the list says how to create the frame. There are two possibilities for the rest of the list. It can be an alist, specifying frame parameters, or it can contain a function and arguments to give to it. (The function's first argument is always the buffer to be displayed; the arguments from the list come after that.)

Variable: special-display-regexps

A list of regular expressions that specify buffers that should be displayed specially. If the buffer's name matches any of the regular expressions in this list, display-buffer handles the buffer specially.

By default, special display means to give the buffer a dedicated frame.

If an element is a list, instead of a string, then the CAR of the list is the regular expression, and the rest of the list says how to create the frame. See above, under special-display-buffer-names.

Variable: special-display-function

This variable holds the function to call to display a buffer specially. It receives the buffer as an argument, and should return the window in which it is displayed.

The default value of this variable is special-display-popup-frame.

Function: special-display-popup-frame buffer

This function makes buffer visible in a frame of its own. If buffer is already displayed in a window in some frame, it makes the frame visible and raises it, to use that window. Otherwise, it creates a frame that will be dedicated to buffer.

This function uses an existing window displaying buffer whether or not it is in a frame of its own; but if you set up the above variables in your init file, before buffer was created, then presumably the window was previously made by this function.

User Option: special-display-frame-alist

This variable holds frame parameters for special-display-popup-frame to use when it creates a frame.

Variable: same-window-buffer-names

A list of buffer names for buffers that should be displayed in the selected window. If the buffer's name is in this list, display-buffer handles the buffer by switching to it in the selected window.

Variable: same-window-regexps

A list of regular expressions that specify buffers that should be displayed in the selected window. If the buffer's name matches any of the regular expressions in this list, display-buffer handles the buffer by switching to it in the selected window.

Variable: display-buffer-function

This variable is the most flexible way to customize the behavior of display-buffer. If it is non-nil, it should be a function that display-buffer calls to do the work. The function should accept two arguments, the same two arguments that display-buffer received. It should choose or create a window, display the specified buffer, and then return the window.

This hook takes precedence over all the other options and hooks described above.

A window can be marked as ``dedicated'' to its buffer. Then display-buffer does not try to use that window.

Function: window-dedicated-p window

This function returns t if window is marked as dedicated; otherwise nil.

Function: set-window-dedicated-p window flag

This function marks window as dedicated if flag is non-nil, and nondedicated otherwise.