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
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.
Precisely how `display-buffer' finds or creates a window depends on the variables described below.
A window can be marked as "dedicated" to a particular buffer. Then XEmacs will not automatically change which buffer appears in the window, such as `display-buffer' might normally do.
- Function: window-dedicated-p window
This function returns WINDOW's dedicated object, usually `t' or
`nil'.
- Function: set-window-buffer-dedicated window buffer
This function makes WINDOW display BUFFER and be dedicated to that
buffer. Then XEmacs will not automatically change which buffer
appears in WINDOW. If BUFFER is `nil', this function makes WINDOW
not be dedicated (but doesn't change which buffer appears in it
currently).
- 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: 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.
See 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 properties from
`pop-up-frame-plist'.
- Variable: pop-up-frame-plist
This variable holds a plist specifying frame properties used when
`display-buffer' makes a new frame. Frame Properties for
more information about frame properties.
- Variable: 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 a plist, specifying frame properties, 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.)
- Variable: 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
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.
This function 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-plist
This variable holds frame properties for
`special-display-popup-frame' to use when it creates a frame.
- Variable: 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.
- Variable: 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' does not try to use that window.
- 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.