An action alist is an association list mapping predefined
symbols recognized by action functions to values these functions are
supposed to interpret accordingly. In each call,
display-buffer constructs a new, possibly empty action alist
and passes that entire list on to any action function it calls.
By design, action functions are free in their interpretation of
action alist entries. In fact, some entries like
previous-window have a meaning only
for one or a few action functions, and are ignored by the rest. Other
are supposed to be respected by most action functions, including those
provided by application programs and external packages.
In the previous subsection we have described in detail how
individual action functions interpret the action alist entries they
care about. Here we give a reference list of all known action alist
entries according to their symbols, together with their values and
action functions (see Buffer Display Action Functions) that
recognize them. Throughout this list, the terms “buffer” will refer
to the buffer
display-buffer is supposed to display, and
“value” refers to the entry’s value.
If the value is non-
nil, this signals that the selected window
must not be used for displaying the buffer. All action functions that
(re-)use an existing window should respect this entry.
The value must specify a window that may have displayed the buffer
display-buffer-in-previous-window will give
preference to such a window provided it is still live and not
dedicated to another buffer.
The value is either a major mode or a list of major modes.
display-buffer-reuse-mode-window may reuse a window whenever
the value specified by this entry matches the major mode of that
window’s buffer. Other action functions ignore such entries.
The value must be a function taking one argument (a frame), supposed
to return non-
nil if that frame is a candidate for displaying
the buffer. This entry is used by
The value specifies the set of frames to search for a window that can be reused because it already displays the buffer. It can be set as follows:
nilmeans consider only windows on the selected frame. (Actually, the last frame used that is not a minibuffer-only frame.)
tmeans consider windows on all frames.
visiblemeans consider windows on all visible frames.
Note that the meaning of
nil differs slightly from that of the
all-frames argument to
next-window (see Cyclic Window Ordering).
A major client of this is
display-buffer-reuse-window, but all
other action functions that try to reuse a window are affected as
display-buffer-in-previous-window consults it when
searching for a window that previously displayed the buffer on another
nil value prevents another frame from being raised or
selected, if the window chosen by
display-buffer is displayed
there. Primarily affected by this are
display-buffer-pop-up-frame should be affected as well, but
there is no guarantee that the window manager will comply.
The value specifies an alist of window parameters to give the chosen window. All action functions that choose a window should process this entry.
The value specifies a minimum height of the window used, in lines. If
a window is not or cannot be made as high as specified by this entry,
the window is not considered for use. The only client of this entry
Note that providing such an entry alone does not necessarily make the
window as tall as specified by its value. To actually resize an
existing window or make a new window as tall as specified by that
window-height entry specifying that value should be
provided as well. Such a
window-height entry can, however,
specify a completely different value or ask the window height to be
fit to that of its buffer in which case the
entry provides the guaranteed minimum height of the window used.
The value specifies whether and how to adjust the height of the chosen window and can be one of the following:
nilmeans to leave the height of the chosen window alone.
fit-window-to-buffer, see Resizing Windows.
By convention, the height of the chosen window is adjusted only if the window is part of a vertical combination (see Windows and Frames) to avoid changing the height of other, unrelated windows. Also, this entry should be processed only under certain conditions which are specified right below this list.
This entry is similar to the
window-height entry described
before, but used to adjust the chosen window’s width instead. The
value can be one of the following:
nilmeans to leave the width of the chosen window alone.
By convention, the width of the chosen window is adjusted only if the window is part of a horizontal combination (see Windows and Frames) to avoid changing the width of other, unrelated windows. Also, this entry should be processed under only certain conditions which are specified right below this list.
nil, such an entry tells
display-buffer to mark
any window it creates as dedicated to its buffer (see Dedicated Windows). It does that by calling
the chosen window as first argument and the entry’s value as second.
nil such an entry tells Emacs to preserve the size of
the window chosen (see Preserving Window Sizes). The value should
(t . nil) to preserve the width of the window,
(nil . t) to preserve its height or
(t . t) to
preserve both, its width and its height. This entry should be
processed only under certain conditions which are specified right
after this list.
The value specifies an alist of frame parameters to give a new frame,
if one is created.
display-buffer-pop-up-frame is its one and
The value specifies the parent frame to be used when the buffer is
displayed on a child frame. This entry is used only by
The value specifies an alist of frame parameters to use when the buffer
is displayed on a child frame. This entry is used only by
The value denotes the side of the frame or window where a new window
displaying the buffer shall be created. This entry is used by
display-buffer-in-side-window to indicate the side of the frame
where a new side window shall be placed (see Displaying Buffers in Side Windows). It is also used by
display-buffer-in-atom-window to indicate the side of an
existing window where the new window shall be located (see Atomic Windows).
nil, the value specifies the slot of the side window
supposed to display the buffer. This entry is used only by
The value specifies a direction which, together with a
display-buffer-in-direction to determine the
location of the window to display the buffer.
The value specifies a window that is in some way related to the window
display-buffer. This entry is currently used by
display-buffer-in-atom-window to indicate the window on whose
side the new window shall be created. It is also used by
display-buffer-in-direction to specify the reference window on
whose side the resulting window shall appear.
If the value is non-
display-buffer does not
necessarily have to display the buffer and the caller is prepared to
accept that. This entry is not intended for user customizations,
since there is no guarantee that an arbitrary caller of
display-buffer will be able to handle the case that no window
will display the buffer.
display-buffer-no-window is the only
action function that cares about this entry.
By convention, the entries
preserve-size are applied after the chosen window’s buffer
has been set up and if and only if that window never showed another
buffer before. More precisely, the latter means that the window must
have been either created by the current
display-buffer call or
the window was created earlier by
display-buffer to show the
buffer and never was used to show another buffer until it was reused
by the current invocation of