elisp: Choosing Window Options
27.15 Additional Options for Displaying Buffers
===============================================
The behavior of the standard display actions of ‘display-buffer’ (
Choosing Window) can be modified by a variety of user options.
-- User Option: pop-up-windows
If the value of this variable is non-‘nil’, ‘display-buffer’ is
allowed to split an existing window to make a new window for
displaying in. This is the default.
This variable is provided mainly for backward compatibility. It is
obeyed by ‘display-buffer’ via a special mechanism in
‘display-buffer-fallback-action’, which only calls the action
function ‘display-buffer-pop-up-window’ (Display Action
Functions) when the value is ‘nil’. It is not consulted by
‘display-buffer-pop-up-window’ itself, which the user may specify
directly in ‘display-buffer-alist’ etc.
-- User Option: split-window-preferred-function
This variable specifies a function for splitting a window, in order
to make a new window for displaying a buffer. It is used by the
‘display-buffer-pop-up-window’ action function to actually split
the window (Display Action Functions).
The default value is ‘split-window-sensibly’, which is documented
below. The value must be a function that takes one argument, a
window, and return either a new window (which will be used to
display the desired buffer) or ‘nil’ (which means the splitting
failed).
-- Function: split-window-sensibly &optional window
This function tries to split WINDOW, and return the newly created
window. If WINDOW cannot be split, it returns ‘nil’. If WINDOW is
omitted or ‘nil’, it defaults to the selected window.
This function obeys the usual rules that determine when a window
may be split (Splitting Windows). It first tries to split
by placing the new window below, subject to the restriction imposed
by ‘split-height-threshold’ (see below), in addition to any other
restrictions. If that fails, it tries to split by placing the new
window to the right, subject to ‘split-width-threshold’ (see
below). If that fails, and the window is the only window on its
frame, this function again tries to split and place the new window
below, disregarding ‘split-height-threshold’. If this fails as
well, this function gives up and returns ‘nil’.
-- User Option: split-height-threshold
This variable, used by ‘split-window-sensibly’, specifies whether
to split the window placing the new window below. If it is an
integer, that means to split only if the original window has at
least that many lines. If it is ‘nil’, that means not to split
this way.
-- User Option: split-width-threshold
This variable, used by ‘split-window-sensibly’, specifies whether
to split the window placing the new window to the right. If the
value is an integer, that means to split only if the original
window has at least that many columns. If the value is ‘nil’, that
means not to split this way.
-- User Option: even-window-sizes
This variable, if non-‘nil’, causes ‘display-buffer’ to even window
sizes whenever it reuses an existing window and that window is
adjacent to the selected one.
If its value is ‘width-only’, sizes are evened only if the reused
window is on the left or right of the selected one and the selected
window is wider than the reused one. If its value is ‘height-only’
sizes are evened only if the reused window is above or beneath the
selected window and the selected window is higher than the reused
one. Any other non-‘nil’ value means to even sizes in any of these
cases provided the selected window is larger than the reused one in
the sense of their combination.
-- User Option: pop-up-frames
If the value of this variable is non-‘nil’, that means
‘display-buffer’ may display buffers by making new frames. The
default is ‘nil’.
A non-‘nil’ value also means that when ‘display-buffer’ is looking
for a window already displaying BUFFER-OR-NAME, it can search any
visible or iconified frame, not just the selected frame.
This variable is provided mainly for backward compatibility. It is
obeyed by ‘display-buffer’ via a special mechanism in
‘display-buffer-fallback-action’, which calls the action function
‘display-buffer-pop-up-frame’ (Display Action Functions) if
the value is non-‘nil’. (This is done before attempting to split a
window.) This variable is not consulted by
‘display-buffer-pop-up-frame’ itself, which the user may specify
directly in ‘display-buffer-alist’ etc.
-- User Option: pop-up-frame-function
This variable specifies a function for creating a new frame, in
order to make a new window for displaying a buffer. It is used by
the ‘display-buffer-pop-up-frame’ action function (Display
Action Functions).
The value should be a function that takes no arguments and returns
a frame, or ‘nil’ if no frame could be created. The default value
is a function that creates a frame using the parameters specified
by ‘pop-up-frame-alist’ (see below).
-- User Option: pop-up-frame-alist
This variable holds an alist of frame parameters (Frame
Parameters), which is used by the default function in
‘pop-up-frame-function’ to make a new frame. The default is ‘nil’.
-- User Option: same-window-buffer-names
A list of buffer names for buffers that should be displayed in the
selected window. If a buffer’s name is in this list,
‘display-buffer’ handles the buffer by showing 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 showing 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.
Info Catalog
elisp: Display Action Functions
elisp: Windows
elisp: Window History