An action function is a function display-buffer calls for
choosing a window to display a buffer. Action functions take two
arguments: buffer, the buffer to display, and alist, an
action alist (see Action Alists for Buffer Display). They are
supposed to return a window displaying buffer if they succeed
and nil if they fail.
The following basic action functions are defined in Emacs.
This function tries to display buffer in the selected window.
It fails if the selected window is a minibuffer window or is dedicated
to another buffer (see Dedicated Windows). It also fails if
alist has a non-nil inhibit-same-window entry.
This function tries to display buffer by finding a window that is already displaying it. Windows on the selected frame are preferred to windows on other frames.
If alist has a non-nil inhibit-same-window entry,
the selected window is not eligible for reuse. The set of frames to
search for a window already displaying buffer can be specified
with the help of the reusable-frames action alist entry. If
alist contains no reusable-frames entry, this function
searches just the selected frame.
If this function chooses a window on another frame, it makes that
frame visible and, unless alist contains an
inhibit-switch-frame entry, raises that frame if necessary.
This function tries to display buffer by finding a window that is displaying a buffer in a given mode.
If alist contains a mode entry, its value specifies a
major mode (a symbol) or a list of major modes. If alist
contains no mode entry, the current major mode of buffer
is used instead. A window is a candidate if it displays a buffer
whose mode derives from one of the modes specified thusly.
The behavior is also controlled by alist entries for
inhibit-same-window, reusable-frames and
inhibit-switch-frame, like display-buffer-reuse-window
does.
This function tries to display buffer by splitting the largest
or least recently-used window (usually located on the selected frame).
It actually performs the split by calling the function specified by
split-window-preferred-function (see Additional Options for Displaying Buffers).
The size of the new window can be adjusted by supplying
window-height and window-width entries in alist.
If alist contains a preserve-size entry, Emacs will also
try to preserve the size of the new window during future resize
operations (see Preserving Window Sizes).
This function fails if no window can be split. More often than not,
this happens because no window is large enough to allow splitting.
Setting split-height-threshold or split-width-threshold
to lower values may help in this regard. Splitting also fails when
the selected frame has an unsplittable frame parameter;
see Buffer Parameters.
This function tries to display buffer in a window where it was displayed previously.
If alist contains a non-nil inhibit-same-window
entry, the selected window is not eligible for use. A dedicated
window is usable only if it already shows buffer. If
alist contains a previous-window entry, the window
specified by that entry is usable even if it never showed buffer
before.
If alist contains a reusable-frames entry (see Action Alists for Buffer Display), its value determines which frames to search
for a suitable window. If alist contains no
reusable-frames entry, this function searches just the selected
frame if display-buffer-reuse-frames and pop-up-frames
are both nil; it searches all frames on the current terminal if
either of those variables is non-nil.
If more than one window qualifies as usable according to these rules, this function makes a choice in the following order of preference:
previous-window alist entry,
provided it is not the selected window.
previous-window alist entry or showed buffer
before.
This function tries to display buffer by choosing an existing
window and displaying the buffer in that window. It first tries to find
a window that has not been used recently (see Cyclic Ordering of Windows) on any frame specified by a lru-frames alist
entry, falling back to the selected frame if no such entry exists. It
also prefers windows that satisfy the constraints specified by
window-min-width and window-min-height alist
entries; preferring full-width windows if no window-min-width
entry is found. Finally, it will not return a window whose use time is
higher than that specified by any lru-time entry provided by
alist.
If no less recently used window is found, this function will try to use some other window, preferably a large window on some visible frame. It can fail if all windows are dedicated to other buffers (see Dedicated Windows).
This function is similar to display-buffer-use-some-window, but
will try harder to not use the a recently used window. In particular,
it does not use the selected window. In addition, it will first try to
reuse a window that shows buffer already, base the decision
whether it should use a window showing another buffer on that window’s
use time alone and pop up a new window if no usable window is found.
Finally, this function will bump the use time (see Selecting Windows) of any window it returns in order to avoid that further
invocations will use that window for showing another buffer. An
application that wants to display several buffers in a row can help this
function by providing a lru-time alist entry it has
initially set to the value of the selected window’s use time. Each
invocation of this function will then bump the use time of the window
returned to a value higher than that and a subsequent invocation will
inhibit this function to use a window it returned earlier.
This function tries to display buffer at a location specified by
alist. For this purpose, alist should contain a
direction entry whose value is one of left, above
(or up), right and below (or down). Other
values are usually interpreted as below.
If alist also contains a window entry, its value
specifies a reference window. That value can be a special symbol like
main which stands for the selected frame’s main window
(see Side Window Options and Functions) or root standing
for the selected frame’s root window (see Windows and Frames). It
can also specify an arbitrary valid window. Any other value (or
omitting the window entry entirely) means to use the selected
window as reference window.
This function first tries to reuse a window in the specified direction
that already shows buffer. If no such window exists, it tries
to split the reference window in order to produce a new window in the
specified direction. If this fails as well, it will try to display
buffer in an existing window in the specified direction. In
either case, the window chosen will appear on the side of the
reference window specified by the direction entry, sharing at
least one edge with the reference window.
If the reference window is live, the edge the chosen window will share
with it is always the opposite of the one specified by the
direction entry. For example, if the value of the
direction entry is left, the chosen window’s right edge
coordinate (see Coordinates and Windows) will equal the reference
window’s left edge coordinate.
If the reference window is internal, a reused window must share with
it the edge specified by the direction entry. Hence if, for
example, the reference window is the frame’s root window and the value
of the direction entry is left, a reused window must be
on the left of the frame. This means that the left edge coordinate of
the chosen window and that of the reference window are the same.
A new window, however, will be created by splitting the reference window such that the chosen window will share the opposite edge with the reference window. In our example, a new root window would be created with a new live window and the reference window as its children. The chosen window’s right edge coordinate would then equal the left edge coordinate of the reference window. Its left edge coordinate would equal the left edge coordinate of the frame’s new root window.
Four special values for direction entries allow to implicitly
specify the selected frame’s main window as the reference window:
leftmost, top, rightmost and bottom. This
means that instead of, for example, (direction . left) (window . main) one can just specify (direction . leftmost). An existing window alist entry is ignored
in such cases.
This function tries to display buffer in a window below the selected window. If there is a window below the selected one and that window already displays buffer, it reuses that window.
If there is no such window, this function tries to create a new window
by splitting the selected one, and displays buffer there. It will
also try to adjust that window’s size provided alist contains a
suitable window-height or window-width entry, see above.
If splitting the selected window fails and there is a non-dedicated window below the selected one showing some other buffer, this function tries to use that window for showing buffer.
If alist contains a window-min-height entry, this
function ensures that the window used is or can become at least as
high as specified by that entry’s value. Note that this is only a
guarantee. In order to actually resize the window used, alist
must also provide an appropriate window-height entry.
This function tries to display buffer in a window at the bottom of the selected frame.
This either tries to split the window at the bottom of the frame or the frame’s root window, or to reuse an existing window at the bottom of the selected frame.
This function creates a new frame, and displays the buffer in that
frame’s window. It actually performs the frame creation by calling
the function specified in pop-up-frame-function
(see Additional Options for Displaying Buffers). If alist contains a
pop-up-frame-parameters entry, the associated value is added to
the newly created frame’s parameters.
This function displays the buffer on the current frame, deleting all other windows so that it takes up the full frame.
This function tries to display buffer in a child frame
(see Child Frames) of the selected frame, either reusing an
existing child frame or by making a new one. If alist has a
non-nil child-frame-parameters entry, the corresponding
value is an alist of frame parameters to give the new frame. A
parent-frame parameter specifying the selected frame is
provided by default. If the child frame should become the child of
another frame, a corresponding entry must be added to alist.
The appearance of child frames is largely dependent on the parameters
provided via alist. It is advisable to use at least ratios to
specify the size (see Size Parameters) and the position
(see Position Parameters) of the child frame, and to add a
keep-ratio parameter (see Frame Interaction Parameters), in
order to make sure that the child frame remains visible. For other
parameters that should be considered see Child Frames.
This function tries to display buffer by finding a frame that meets a predicate (by default any frame other than the selected frame).
If this function chooses a window on another frame, it makes that
frame visible and, unless alist contains an
inhibit-switch-frame entry, raises that frame if necessary.
If alist has a non-nil frame-predicate entry, its
value is a function taking one argument (a frame), returning
non-nil if the frame is a candidate; this function replaces the
default predicate.
If alist has a non-nil inhibit-same-window entry,
the selected window is not used; thus if the selected frame has a
single window, it is not used.
If alist has a non-nil allow-no-window entry, then
this function does not display buffer and returns the symbol
fail. This constitutes the only exception to the convention
that an action function returns either nil or a window showing
buffer. If alist has no such allow-no-window
entry, this function returns nil.
If this function returns fail, display-buffer will skip
the execution of any further display actions and return nil
immediately. If this function returns nil,
display-buffer will continue with the next display action, if
any.
It is assumed that when a caller of display-buffer specifies a
non-nil allow-no-window entry, it is also able to handle
a nil return value.
Two other action functions are described in their proper
sections—display-buffer-in-side-window (see Displaying Buffers in Side Windows) and display-buffer-in-atom-window
(see Atomic Windows).