Next: Window Point, Previous: Displaying Buffers, Up: Windows [Contents][Index]
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.
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.
buffer-or-name can be a buffer or the name of one.
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.
If override-frame is non-nil, display on that frame instead
of the current frame (or the dedicated frame).
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 SXEmacs will not automatically change which buffer appears in the
window, such as display-buffer might normally do.
This function returns window’s dedicated object, usually t
or nil.
This function makes window display buffer and be dedicated
to that buffer. Then SXEmacs 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).
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.
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.
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.
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.
This variable holds a plist specifying frame properties used when
display-buffer makes a new frame. See Frame Properties, for
more information about frame properties.
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.)
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.
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.
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.
This variable holds frame properties for
special-display-popup-frame to use when it creates a frame.
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.
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.
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.
This function returns t if window is marked as dedicated;
otherwise nil.
This function marks window as dedicated if flag is
non-nil, and nondedicated otherwise.
Next: Window Point, Previous: Displaying Buffers, Up: Windows [Contents][Index]