elisp: Display Action Functions
27.14 Action Functions for ‘display-buffer’
===========================================
The following basic action functions are defined in Emacs. Each of
these functions takes two arguments: BUFFER, the buffer to display, and
ALIST, an action alist. Each action function returns the window if it
succeeds, and ‘nil’ if it fails.
-- Function: display-buffer-same-window buffer alist
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 (
Dedicated Windows). It also fails if
ALIST has a non-‘nil’ ‘inhibit-same-window’ entry.
-- Function: display-buffer-reuse-window buffer alist
This function tries to display BUFFER by finding a window that is
already displaying it.
If ALIST has a non-‘nil’ ‘inhibit-same-window’ entry, the selected
window is not eligible for reuse. If ALIST contains a
‘reusable-frames’ entry, its value determines which frames to
search for a reusable window:
• ‘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.
Note that these meanings differ slightly from those of the
ALL-FRAMES argument to ‘next-window’ (Cyclic Window
Ordering).
If ALIST contains no ‘reusable-frames’ entry, this function
normally searches just the selected frame; however, if the variable
‘pop-up-frames’ is non-‘nil’, it searches all frames on the current
terminal. Choosing Window Options.
If this function chooses a window on another frame, it makes that
frame visible and, unless ALIST contains an ‘inhibit-switch-frame’
entry (Choosing Window Options), raises that frame if
necessary.
-- Function: display-buffer-pop-up-frame buffer alist
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’ (Choosing
Window Options). If ALIST contains a ‘pop-up-frame-parameters’
entry, the associated value is added to the newly created frame’s
parameters.
-- Function: display-buffer-use-some-frame buffer alist
This function tries to display BUFFER by trying to find a frame
that meets a predicate (by default any frame other than the current
frame).
If this function chooses a window on another frame, it makes that
frame visible and, unless ALIST contains an ‘inhibit-switch-frame’
entry (Choosing Window Options), 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 used; thus if the selected frame has a single window, it
is not used.
-- Function: display-buffer-pop-up-window buffer alist
This function tries to display BUFFER by splitting the largest or
least recently-used window (typically one on the selected frame).
It actually performs the split by calling the function specified in
‘split-window-preferred-function’ (Choosing Window
Options).
The size of the new window can be adjusted by supplying
‘window-height’ and ‘window-width’ entries in ALIST. To adjust the
window’s height, use an entry whose CAR is ‘window-height’ and
whose CDR is one of:
• ‘nil’ means to leave the height of the new window alone.
• A number specifies the desired height of the new window. An
integer specifies the number of lines of the window. A
floating-point number gives the fraction of the window’s
height with respect to the height of the frame’s root window.
• If the CDR specifies a function, that function is called with
one argument: the new window. The function is supposed to
adjust the height of the window; its return value is ignored.
Suitable functions are ‘shrink-window-if-larger-than-buffer’
and ‘fit-window-to-buffer’, see Resizing Windows.
To adjust the window’s width, use an entry whose CAR is
‘window-width’ and whose CDR is one of:
• ‘nil’ means to leave the width of the new window alone.
• A number specifies the desired width of the new window. An
integer specifies the number of columns of the window. A
floating-point number gives the fraction of the window’s width
with respect to the width of the frame’s root window.
• If the CDR specifies a function, that function is called with
one argument: the new window. The function is supposed to
adjust the width of the window; its return value is ignored.
If ALIST contains a ‘preserve-size’ entry, Emacs will try to
preserve the size of the new window during future resize operations
(Preserving Window Sizes). The CDR of that entry must be a
cons cell whose CAR, if non-‘nil’, means to preserve the width of
the window and whose CDR, if non-‘nil’, means to preserve the
height of the window.
This function can fail if no window splitting can be performed for
some reason (e.g., if the selected frame has an ‘unsplittable’
frame parameter; Buffer Parameters).
-- Function: display-buffer-below-selected buffer alist
This function tries to display BUFFER in a window below the
selected window. This means to either split the selected window or
use the window below the selected one. If it does create a new
window, it will also adjust its size provided ALIST contains a
suitable ‘window-height’ or ‘window-width’ entry, see above.
-- Function: display-buffer-in-previous-window buffer alist
This function tries to display BUFFER in a window previously
showing it. If ALIST has a non-‘nil’ ‘inhibit-same-window’ entry,
the selected window is not eligible for reuse. If ALIST contains a
‘reusable-frames’ entry, its value determines which frames to
search for a suitable window as with ‘display-buffer-reuse-window’.
If ALIST has a ‘previous-window’ entry, the window specified by
that entry will override any other window found by the methods
above, even if that window never showed BUFFER before.
-- Function: display-buffer-at-bottom buffer alist
This function tries to display BUFFER in a window at the bottom of
the selected frame.
This either splits the window at the bottom of the frame or the
frame’s root window, or reuses an existing window at the bottom of
the selected frame.
-- Function: display-buffer-use-some-window buffer alist
This function tries to display BUFFER by choosing an existing
window and displaying the buffer in that window. It can fail if
all windows are dedicated to another buffer (Dedicated
Windows).
-- Function: display-buffer-no-window buffer alist
If ALIST has a non-‘nil’ ‘allow-no-window’ entry, then this
function does not display ‘buffer’. This allows you to override
the default action and avoid displaying the buffer. It is assumed
that when the caller specifies a non-‘nil’ ‘allow-no-window’ value
it can handle a ‘nil’ value returned from ‘display-buffer’ in this
case.
To illustrate the use of action functions, consider the following
example.
(display-buffer
(get-buffer-create "*foo*")
'((display-buffer-reuse-window
display-buffer-pop-up-window
display-buffer-pop-up-frame)
(reusable-frames . 0)
(window-height . 10) (window-width . 40)))
Evaluating the form above will cause ‘display-buffer’ to proceed as
follows: If a buffer called *foo* already appears on a visible or
iconified frame, it will reuse its window. Otherwise, it will try to
pop up a new window or, if that is impossible, a new frame and show the
buffer there. If all these steps fail, it will proceed using whatever
‘display-buffer-base-action’ and ‘display-buffer-fallback-action’
prescribe.
Furthermore, ‘display-buffer’ will try to adjust a reused window
(provided *foo* was put by ‘display-buffer’ there before) or a popped-up
window as follows: If the window is part of a vertical combination, it
will set its height to ten lines. Note that if, instead of the number
10, we specified the function ‘fit-window-to-buffer’, ‘display-buffer’
would come up with a one-line window to fit the empty buffer. If the
window is part of a horizontal combination, it sets its width to 40
columns. Whether a new window is vertically or horizontally combined
depends on the shape of the window split and the values of
‘split-window-preferred-function’, ‘split-height-threshold’ and
‘split-width-threshold’ (Choosing Window Options).
Now suppose we combine this call with a preexisting setup for
‘display-buffer-alist’ as follows.
(let ((display-buffer-alist
(cons
'("\\*foo\\*"
(display-buffer-reuse-window display-buffer-below-selected)
(reusable-frames)
(window-height . 5))
display-buffer-alist)))
(display-buffer
(get-buffer-create "*foo*")
'((display-buffer-reuse-window
display-buffer-pop-up-window
display-buffer-pop-up-frame)
(reusable-frames . 0)
(window-height . 10) (window-width . 40))))
This form will have ‘display-buffer’ first try reusing a window that
shows *foo* on the selected frame. If there’s no such window, it will
try to split the selected window or, if that is impossible, use the
window below the selected window.
If there’s no window below the selected one, or the window below the
selected one is dedicated to its buffer, ‘display-buffer’ will proceed
as described in the previous example. Note, however, that when it tries
to adjust the height of any reused or popped-up window, it will in any
case try to set its number of lines to 5 since that value overrides the
corresponding specification in the ACTION argument of ‘display-buffer’.
Info Catalog
elisp: Choosing Window
elisp: Windows
elisp: Choosing Window Options