Next: Choosing Window Options, Previous: Choosing Window, Up: Windows [Contents][Index]
display-bufferThe 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.
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.
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.
Note that these meanings differ slightly from those of the
all-frames argument to next-window (see 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. See 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 (see Choosing Window Options), 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 is 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. A
window is a candidate if it displays a buffer that derives from one of
the given modes.
The behavior is also controlled by entries for
inhibit-same-window, reusable-frames and
inhibit-switch-frame as is done in the function
display-buffer-reuse-window.
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 Choosing Window Options). If alist contains a
pop-up-frame-parameters entry, the associated value
is added to the newly created frame’s parameters.
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 be or 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 the
keep-ratio 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 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 (see 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.
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 (see 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.
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.
If alist contains a preserve-size entry, Emacs will try to
preserve the size of the new window during future resize operations
(see 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; see Buffer Parameters).
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 display buffer there. It will
also 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, it uses that window for showing buffer.
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.
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.
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 (see Dedicated Windows).
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.
If the alist argument of any of these functions contains a
window-parameters entry, display-buffer assigns the
elements of the associated value as window parameters of the chosen
window.
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 (see 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.
Next: Choosing Window Options, Previous: Choosing Window, Up: Windows [Contents][Index]