GNU Info
(elisp)Choosing Window
Choosing a Window for Display
=============================
This section describes the basic facility that chooses a window to
display a buffer in--`display-buffer'. All the higher-level functions
and commands use this subroutine. Here we describe how to use
`display-buffer' and how to customize it.
- Command: display-buffer buffer-or-name &optional not-this-window
frame
This command makes BUFFER-OR-NAME appear in some window, like
`pop-to-buffer', but it does not select that window and does not
make the buffer current. The identity of the selected window is
unaltered by this function.
If NOT-THIS-WINDOW is non-`nil', it means to display the specified
buffer in a window other than the selected one, even if it is
already on display in the selected window. This can cause the
buffer to appear in two windows at once. Otherwise, if
BUFFER-OR-NAME is already being displayed in any window, that is
good enough, so this function does nothing.
`display-buffer' returns the window chosen to display
BUFFER-OR-NAME.
If the argument FRAME is non-`nil', it specifies which frames to
check when deciding whether the buffer is already displayed. If
the buffer is already displayed in some window on one of these
frames, `display-buffer' simply returns that window. Here are the
possible values of FRAME:
* If it is `nil', consider windows on the selected frame.
* If it is `t', consider windows on all frames.
* If it is `visible', consider windows on all visible frames.
* If it is 0, consider windows on all visible or iconified
frames.
* If it is a frame, consider windows on that frame.
Precisely how `display-buffer' finds or creates a window depends on
the variables described below.
- User Option: display-buffer-reuse-frames
If this variable is non-`nil', `display-buffer' searches existing
frames for a window displaying the buffer. If the buffer is
already displayed in a window in some frame, `display-buffer' makes
the frame visible and raises it, to use that window. If the
buffer is not already displayed, or if
`display-buffer-reuse-frames' is `nil', `display-buffer''s
behavior is determined by other variables, described below.
- User Option: pop-up-windows
This variable controls whether `display-buffer' makes new windows.
If it is non-`nil' and there is only one window, then that window
is split. If it is `nil', then `display-buffer' does not split
the single window, but uses it whole.
- User Option: split-height-threshold
This variable determines when `display-buffer' may split a window,
if there are multiple windows. `display-buffer' always splits the
largest window if it has at least this many lines. If the largest
window is not this tall, it is split only if it is the sole window
and `pop-up-windows' is non-`nil'.
- User Option: even-window-heights
This variable determines if `display-buffer' should even out window
heights if the buffer gets displayed in an existing window, above
or beneath another existing window. If `even-window-heights' is
`t', the default, window heights will be evened out. If
`even-window-heights' is `nil', the orginal window heights will be
left alone.
- User Option: pop-up-frames
This variable controls whether `display-buffer' makes new frames.
If it is non-`nil', `display-buffer' looks for an existing window
already displaying the desired buffer, on any visible frame. If
it finds one, it returns that window. Otherwise it makes a new
frame. The variables `pop-up-windows' and
`split-height-threshold' do not matter if `pop-up-frames' is
non-`nil'.
If `pop-up-frames' is `nil', then `display-buffer' either splits a
window or reuses one.
Note: Frames, for more information.
- Variable: pop-up-frame-function
This variable specifies how to make a new frame if `pop-up-frames'
is non-`nil'.
Its value should be a function of no arguments. When
`display-buffer' makes a new frame, it does so by calling that
function, which should return a frame. The default value of the
variable is a function that creates a frame using parameters from
`pop-up-frame-alist'.
- User Option: pop-up-frame-alist
This variable holds an alist specifying frame parameters used when
`display-buffer' makes a new frame. Note: Frame Parameters, for
more information about frame parameters.
- User Option: special-display-buffer-names
A list of buffer names for buffers that should be displayed
specially. If the buffer's name is in this list, `display-buffer'
handles the buffer specially.
By default, special display means to give the buffer a dedicated
frame.
If an element is a list, instead of a string, then the CAR of the
list is the buffer name, and the rest of the list says how to
create the frame. There are two possibilities for the rest of the
list. It can be an alist, specifying frame parameters, or it can
contain a function and arguments to give to it. (The function's
first argument is always the buffer to be displayed; the arguments
from the list come after that.)
- User Option: special-display-regexps
A list of regular expressions that specify buffers that should be
displayed specially. If the buffer's name matches any of the
regular expressions in this list, `display-buffer' handles the
buffer specially.
By default, special display means to give the buffer a dedicated
frame.
If an element is a list, instead of a string, then the CAR of the
list is the regular expression, and the rest of the list says how
to create the frame. See above, under
`special-display-buffer-names'.
- Variable: special-display-function
This variable holds the function to call to display a buffer
specially. It receives the buffer as an argument, and should
return the window in which it is displayed.
The default value of this variable is
`special-display-popup-frame'.
- Function: special-display-popup-frame buffer &rest args
This function makes BUFFER visible in a frame of its own. If
BUFFER is already displayed in a window in some frame, it makes
the frame visible and raises it, to use that window. Otherwise, it
creates a frame that will be dedicated to BUFFER.
If ARGS is an alist, it specifies frame parameters for the new
frame.
If ARGS is a list whose CAR is a symbol, then `(car ARGS)' is
called as a function to actually create and set up the frame; it
is called with BUFFER as first argument, and `(cdr ARGS)' as
additional arguments.
This function always uses an existing window displaying BUFFER,
whether or not it is in a frame of its own; but if you set up the
above variables in your init file, before BUFFER was created, then
presumably the window was previously made by this function.
- User Option: special-display-frame-alist
This variable holds frame parameters for
`special-display-popup-frame' to use when it creates a frame.
- User Option: same-window-buffer-names
A list of buffer names for buffers that should be displayed in the
selected window. If the buffer's name is in this list,
`display-buffer' handles the buffer by switching to it in the
selected window.
- User Option: same-window-regexps
A list of regular expressions that specify buffers that should be
displayed in the selected window. If the buffer's name matches
any of the regular expressions in this list, `display-buffer'
handles the buffer by switching to it in the selected window.
- Variable: display-buffer-function
This variable is the most flexible way to customize the behavior of
`display-buffer'. If it is non-`nil', it should be a function
that `display-buffer' calls to do the work. The function should
accept two arguments, the same two arguments that `display-buffer'
received. It should choose or create a window, display the
specified buffer, and then return the window.
This hook takes precedence over all the other options and hooks
described above.
A window can be marked as "dedicated" to its buffer. Then
`display-buffer' will not try to use that window to display any other
buffer.
- Function: window-dedicated-p window
This function returns `t' if WINDOW is marked as dedicated;
otherwise `nil'.
- Function: set-window-dedicated-p window flag
This function marks WINDOW as dedicated if FLAG is non-`nil', and
nondedicated otherwise.
automatically generated by info2www version 1.2.2.9