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

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. buffer-or-name must be a buffer, or the name of an existing buffer.

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.

If the argument frame is non-nil, it specifies which frames to check when deciding whether the buffer is already displayed. If the buffer is already displayed in some window on one of these frames, display-buffer simply returns that window. Here are the possible values of frame:

• If it is nil, consider windows on the selected frame. (Actually, the last non-minibuffer frame.)
• If it is t, consider windows on all frames.
• If it is visible, consider windows on all visible frames.
• If it is 0, consider windows on all visible or iconified frames.
• If it is a frame, consider windows on that frame.

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

— User Option: display-buffer-reuse-frames

If this variable is non-nil, display-buffer searches existing frames for a window displaying the buffer. If the buffer is already displayed in a window in some frame, display-buffer makes the frame visible and raises it, to use that window. If the buffer is not already displayed, or if display-buffer-reuse-frames is nil, display-buffer's behavior is determined by other 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: even-window-heights

This variable determines if display-buffer should even out window heights if the buffer gets displayed in an existing window, above or beneath another existing window. If even-window-heights is t, the default, window heights will be evened out. If even-window-heights is nil, the original window heights will be left alone.

— 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.

— User Option: 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.

— User Option: 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.

— User Option: 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 (its cdr). 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.)

For example:

          (("myfile" (minibuffer) (menu-bar-lines . 0)))
     

specifies to display a buffer named `myfile' in a dedicated frame with specified minibuffer and menu-bar-lines parameters.

The list of frame parameters can also use the phony frame parameters same-frame and same-window. If the specified frame parameters include (same-window . value) and value is non-nil, that means to display the buffer in the current selected window. Otherwise, if they include (same-frame . value) and value is non-nil, that means to display the buffer in a new window in the currently selected frame.

— User Option: 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.

— Function: special-display-p buffer-name

This function returns non-nil if displaying a buffer named buffer-name with display-buffer would create a special frame. The value is t if it would use the default frame parameters, or else the specified list of frame parameters.

— 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 &optional args

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 returns the window it used.

If args is an alist, it specifies frame parameters for the new frame.

If args is a list whose car is a symbol, then (car args) is called as a function to actually create and set up the frame; it is called with buffer as first argument, and (cdr args) as additional arguments.

This function always 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.

— User Option: 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.

— User Option: 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.

— Function: same-window-p buffer-name

This function returns t if displaying a buffer named buffer-name with display-buffer would put 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 first two arguments that display-buffer received. It should choose or create a window, display the specified buffer in it, and then return the window.

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

— Function: window-dedicated-p window

This function returns non-nil 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.