---

29.13.3 Action Alists for Buffer Display

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 allow-no-window or previous-window have a meaning only for one or a few action functions, and are ignored by the rest. Other entries, like inhibit-same-window or window-parameters, 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 Action Functions for Buffer Display) 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.

inhibit-same-window

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.

previous-window

The value must specify a window that may have displayed the buffer previously. display-buffer-in-previous-window will give preference to such a window provided it is still live and not dedicated to another buffer.

mode

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.

frame-predicate

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 display-buffer-use-some-frame.

reusable-frames

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:

• nil means consider only windows on the selected frame. (Actually, the last frame used that is not a minibuffer-only frame.)
• 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.
• t means consider windows on all frames. (Note that this value is rarely the right thing to use—it might also return a tooltip frame.)

Note that the meaning of nil differs slightly from that of the all-frames argument to next-window (see Cyclic Ordering of Windows).

A major client of this is display-buffer-reuse-window, but all other action functions that try to reuse a window are affected as well. display-buffer-in-previous-window consults it when searching for a window that previously displayed the buffer on another frame.

inhibit-switch-frame

A non-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-use-some-frame and display-buffer-reuse-window. Ideally, display-buffer-pop-up-frame should be affected as well, but there is no guarantee that the window manager will comply.

window-parameters

The value specifies an alist of window parameters to give the chosen window. All action functions that choose a window should process this entry.

window-min-width

The value specifies a minimum width of the window used, in canonical frame columns. The special value full-width means the chosen window should be one that has no other windows on the left or right of it in its frame.

This entry is currently honored by display-buffer-use-some-window and display-buffer-use-least-recent-window, which try hard to avoid returning a less recently used window that does not satisfy the entry.

Note that providing such an entry alone does not necessarily make the window as wide as specified by its value. To actually resize an existing window or make a new window as wide as specified by this entry’s value, a window-width entry specifying that value should be provided as well. Such a window-width entry can, however, specify a completely different value, or ask the window width to fit that of its buffer, in which case the window-min-width entry provides the guaranteed minimum width of the window.

window-min-height

The value specifies a minimum height of the window used, in canonical frame lines. The special value full-height means the chosen window should be a full-height window, one that has no other windows above or below it in its frame.

This entry is currently honored by display-buffer-below-selected which does not use a window that is not as high as specified by this entry. It’s also honored by display-buffer-use-some-window and display-buffer-use-least-recent-window which try hard to avoid returning a less recently used window if it does not satisfy this constraint.

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 value, a 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 window-min-height entry provides the guaranteed minimum height of the window used.

window-height

The value specifies whether and how to adjust the height of the chosen window and can be one of the following:

• nil means to leave the height of the chosen window alone.
• An integer number specifies the desired total height of the chosen window in lines.
• A floating-point number specifies the fraction of the chosen window’s desired total height with respect to the total height of its frame’s root window.
• A cons cell whose CAR is body-lines and whose CDR is an integer that specifies the height of the chosen window’s body in frame lines.
• If the value specifies a function, that function is called with one argument—the chosen window. The function is supposed to adjust the height of the window; its return value is ignored. Suitable functions are fit-window-to-buffer and shrink-window-if-larger-than-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.

window-width

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:

• nil means to leave the width of the chosen window alone.
• An integer specifies the desired total width of the chosen window in columns.
• A floating-point number specifies the fraction of the chosen window’s desired total width with respect to the total width of the frame’s root window.
• A cons cell whose CAR is body-columns and whose CDR is an integer that specifies the width of the chosen window’s body in frame columns.
• If the value specifies a function, that function is called with one argument—the chosen window. The function is supposed to adjust the width of the window; its return value is ignored.

window-size

This entry is a combination of the two preceding ones and can be used to adjust the chosen window’s height and width. Since windows can be resized in one direction only without affecting other windows, window-size is effective only to set up the size of a window appearing alone on a frame. The value can be one of the following:

• nil means to leave the size of the chosen window alone.
• A cons cell of two integers specifies the desired total width and height of the chosen window in lines and columns. It’s effect is to adjust the size of the frame accordingly.
• A cons cell whose CAR equals body-chars and whose CDR is a cons cell of two integers—the desired body width and height of the chosen window in frame columns and lines. It’s effect is to adjust the size of the frame accordingly.
• If the value specifies a function, that function is called with one argument—the chosen window. The function is supposed to adjust the size of the window’s frame; its return value is ignored.

This entry should be processed under only certain conditions which are specified right below this list.

dedicated

If non-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 set-window-dedicated-p with the chosen window as first argument and the entry’s value as second. Side windows are by default dedicated with the value side (see Side Window Options and Functions).

preserve-size

If non-nil such an entry tells Emacs to preserve the size of the window chosen (see Preserving Window Sizes). The value should be either (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.

lru-frames

The value specifies the set of frames to search for a window that can be used to display the buffer. It is honored by display-buffer-use-some-window and display-buffer-use-least-recent-window when trying to find a less recently used window showing some other buffer. Its values are the same as for the reusable-frames entry described above.

lru-time

The value is supposed to specify a use time (see Selecting Windows). This entry is honored by display-buffer-use-some-window and display-buffer-use-least-recent-window when trying to find a less recently used window showing some other buffer. If a window’s use time is higher than the value specified by this option, these action functions will not consider such a window for displaying the buffer.

bump-use-time

If non-nil, such an entry will cause display-buffer to bump the use time (see Selecting Windows) of the window it uses. This should avoid later use of this window by action functions like display-buffer-use-some-window and display-buffer-use-least-recent-window for showing another buffer.

There is a fine difference between using this entry and using the action function display-buffer-use-least-recent-window. Calling the latter means to only bump the use times of windows that function uses for displaying the buffer. The entry described here will cause display-buffer to bump the use time of any window used for displaying a buffer.

pop-up-frame-parameters

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 only addressee.

parent-frame

The value specifies the parent frame to be used when the buffer is displayed on a child frame. This entry is used only by display-buffer-in-child-frame.

child-frame-parameters

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 display-buffer-in-child-frame.

side

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

slot

If non-nil, the value specifies the slot of the side window supposed to display the buffer. This entry is used only by display-buffer-in-side-window.

direction

The value specifies a direction which, together with a window entry, allows display-buffer-in-direction to determine the location of the window to display the buffer.

window

The value specifies a window that is in some way related to the window chosen by 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.

allow-no-window

If the value is non-nil, 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.

body-function

The value must be a function taking one argument (a displayed window). This function can be used to fill the displayed window’s body with some contents that might depend on dimensions of the displayed window. It is called after the buffer is displayed, and before the entries window-height, window-width and preserve-size are applied that could resize the window to fit it to the inserted contents.

By convention, the entries window-height, window-width and 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 display-buffer.

If no window-height, window-width or window-size entry was specified, the window may still be resized automatically when the buffer is temporary and temp-buffer-resize-mode has been enabled, Temporary Displays. In that case, the CDR of a window-height, window-width or window-size entry can be used to inhibit or override the default behavior of temp-buffer-resize-mode for specific buffers or invocations of display-buffer.