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

This command makes buffer-or-name appear in some window, but it does not select that window and does not make the buffer specified by buffer-or-name current. The identity of the selected window is unaltered by this function. The argument buffer-or-name must be a buffer or the name of an existing buffer.

not-this-window non-nil means to display the specified buffer in a window other than the selected one, even if it is already displayed 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 optional 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:

• nil means consider windows on the selected frame. (Actually, the last non-minibuffer frame.)
• t means consider windows on all frames.
• visible means consider windows on all visible frames.
• 0 means consider windows on all visible or iconified frames.
• A frame means consider windows on that frame only.

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 visible and iconified frames for a window displaying buffer-or-name. If there is such a window, display-buffer makes that window's frame visible and raises it if necessary, and returns the window. If there is no such window or display-buffer-reuse-frames is nil, the behavior of display-buffer is determined by the variables described next.

— User Option: pop-up-windows

This variable specifies whether display-buffer is allowed to split (see Splitting Windows) an existing window. If this variable is non-nil, display-buffer tries to split the largest or least recently used window on the selected frame. (If the selected frame is a minibuffer-only frame, display-buffer tries to split a window on another frame instead.) If this variable is nil or the variable pop-up-frames (see below) is non-nil, display-buffer does not split any window.

— User Option: split-window-preferred-function

This variable must specify a function with one argument, which is a window. The display-buffer routines will call this function with one or more candidate windows when they look for a window to split. The function is expected to split that window and return the new window. If the function returns nil, this means that the argument window cannot (or shall not) be split.

The default value of split-window-preferred-function is the function split-window-sensibly described below. If you customize this option, bear in mind that the display-buffer routines may call your function up to two times when trying to split a window. The argument of the first call is the largest window on the chosen frame (as returned by get-largest-window). If that call fails to return a live window, your function is called a second time with the least recently used window on that frame (as returned by get-lru-window).

The function specified by this option may try to split any other window instead of the argument window. Note that the window selected at the time display-buffer was invoked is still selected when your function is called. Hence, you can split the selected window (instead of the largest or least recently used one) by simply ignoring the window argument in the body of your function. You can even choose to not split any window as long as the return value of your function specifies a live window or nil, but you are not encouraged to do so unconditionally. If you want display-buffer to never split any windows, set pop-up-windows to nil.

— Function: split-window-sensibly window

This function takes a window as argument and tries to split that window in a suitable way. The two variables described next are useful for tuning the behavior of this function.

— User Option: split-height-threshold

This variable specifies whether split-window-sensibly may split windows vertically. If it is an integer, split-window-sensibly tries to vertically split a window only if it has at least this many lines. If the window has less lines, splitting fails, or the value of this variable is nil, split-window-sensibly will try to split the window horizontally, subject to restrictions of split-width-threshold (see below). If splitting horizontally fails too and the window is the only window on its frame, split-window-sensibly will try to split the window vertically disregarding the value of split-height-threshold. If this fails as well, split-window-sensibly returns nil.

split-window-sensibly does not split vertically a window whose height is fixed (see Resizing Windows). Also, it vertically splits a window only if the space taken up by that window can accommodate two windows one above the other that are both at least window-min-height lines tall. Moreover, if the window that shall be split has a mode line, split-window-sensibly does not split the window unless the new window can accomodate a mode line too.

— User Option: split-width-threshold

This variable specifies whether split-window-sensibly may split windows horizontally. If it is an integer, split-window-sensibly tries to horizontally split a window only if it has at least this many columns. If it is nil, split-window-sensibly will not split the window horizontally. (It still might split the window vertically, though, see above.)

split-window-sensibly does not split horizontally a window if that window's width is fixed (see Resizing Windows). Also, it horizontally splits a window only if the space that window takes up can accommodate two windows side by side that are both at least window-min-width columns wide.

— User Option: even-window-heights

This variable specifies whether display-buffer should even out window heights if the buffer gets displayed in an existing window, above or beneath another window. If even-window-heights is non-nil, the default, window heights will be evened out. If either of the involved window has fixed height (see Resizing Windows) or even-window-heights is nil, the original window heights will be left alone.

— User Option: pop-up-frames

This variable specifies whether display-buffer should make new frames. If it is non-nil, display-buffer looks for a window already displaying buffer-or-name on any visible or iconified frame. If it finds such a window, it makes that window's frame visible and raises it if necessary, and returns the window. Otherwise it makes a new frame, unless the variable's value is graphic-only and the selected frame is not on a graphic display. See Frames, for more information.

Note that the value of pop-up-windows does 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.

— User Option: pop-up-frame-function

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

The value of this variable must 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 this variable is a function that creates a frame using the parameters specified by pop-up-frame-alist described next.

— User Option: pop-up-frame-alist

This variable holds an alist specifying frame parameters used by the default value of pop-up-frame-function for making new frames. See Frame Parameters, for more information about frame parameters.

— User Option: special-display-buffer-names

A list of buffer names identifying buffers that should be displayed specially. If the name of buffer-or-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 that list is the buffer name, and the rest of that list says how to create the frame. There are two possibilities for the rest of that 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 specifying 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 special-display-buffer-names above.

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

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

— Function: special-display-popup-frame buffer &optional args

This function tries to make buffer visible in a frame of its own. If buffer is already displayed in some window, it makes that window's frame visible and raises it. Otherwise, it creates a frame that is dedicated to buffer. The return value is the window used to display buffer.

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.

— User Option: 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 variable takes precedence over all the other options described above.