This section describes low-level functions for examining and setting the contents of windows. See Switching to a Buffer in a Window, for higher-level functions for displaying a specific buffer in a window.
This function returns the buffer that window is displaying. If
window is omitted or nil it defaults to the selected
window. If window is an internal window, this function returns
nil.
This function makes window display buffer-or-name.
window should be a live window; if nil, it defaults to
the selected window. buffer-or-name should be a buffer, or the
name of an existing buffer. This function does not change which
window is selected, nor does it directly change which buffer is
current (see The Current Buffer). Its return value is nil.
If window is strongly dedicated to a buffer and buffer-or-name does not specify that buffer, this function signals an error. See Dedicated Windows.
By default, this function resets window’s position, display
margins, fringe widths, and scroll bar settings, based on the local
variables in the specified buffer. However, if the optional argument
keep-margins is non-nil, it leaves window’s display
margins, fringes and scroll bar settings alone.
When writing an application, you should normally use
display-buffer (see Choosing a Window for Displaying a Buffer) or the higher-level
functions described in Switching to a Buffer in a Window, instead of calling
set-window-buffer directly.
This runs window-scroll-functions, followed by
window-configuration-change-hook. See Hooks for Window Scrolling and Changes.
This buffer-local variable records the number of times a buffer has been
displayed in a window. It is incremented each time
set-window-buffer is called for the buffer.
This buffer-local variable records the time at which a buffer was last
displayed in a window. The value is nil if the buffer has
never been displayed. It is updated each time
set-window-buffer is called for the buffer, with the value
returned by current-time (see Time of Day).
This function returns the first window displaying buffer-or-name
in the cyclic ordering of windows, starting from the selected window
(see Cyclic Ordering of Windows). If no such window exists, the
return value is nil.
buffer-or-name should be a buffer or the name of a buffer; if
omitted or nil, it defaults to the current buffer. The
optional argument all-frames specifies which windows to
consider:
t means consider windows on all existing 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 Ordering of Windows). This function may be changed in a future version of Emacs
to eliminate this discrepancy.
The following function can tell for a specific window whether its buffer shares the text of some other buffer (see Indirect Buffers).
This function returns non-nil if window is indirectly
related to buffer-or-name. window must be a live window and
defaults to the selected window. buffer-or-name may be a buffer
or the name of an existing buffer and defaults to the current buffer.
window is indirectly related to buffer-or-name if one of the following conditions hold:
It returns nil if none of the above holds.
This function returns a list of all windows currently displaying
buffer-or-name. buffer-or-name should be a buffer or the
name of an existing buffer. If omitted or nil, it defaults to
the current buffer. If the currently selected window displays
buffer-or-name, it will be the first in the list returned by
this function.
The arguments minibuf and all-frames have the same
meanings as in the function next-window (see Cyclic Ordering of Windows). Note that the all-frames argument does not
behave exactly like in get-buffer-window.
The optional argument indirect non-nil means to append to
the list of windows showing buffer-or-name a list of all windows
that are indirectly related to buffer-or-name, that is, windows
for which window-indirect-buffer-p (see above) with the window
and the buffer specified by buffer-or-name as arguments returns
non-nil.
This command replaces buffer-or-name with some other buffer, in
all windows displaying it. buffer-or-name should be a buffer, or
the name of an existing buffer; if omitted or nil, it defaults to
the current buffer.
The replacement buffer in each window is usually chosen via
switch-to-prev-buffer (see Window History). With the
exception of side windows (see Side Windows), any dedicated window
displaying buffer-or-name is deleted if possible (see Dedicated Windows). If such a window is the only window on its frame and there
are other frames on the same terminal, the frame is deleted as well. If
the dedicated window is the only window on the only frame on its
terminal, the buffer is replaced anyway.
The main purpose of this function is to decide what to do with windows
whose buffers are about to be killed by kill-buffer
(see Killing Buffers). It will, however, also remove the buffer
specified by buffer-or-name from the lists of previous and next
buffers (see Window History) of all windows (including dead windows
that are only referenced by window configurations) and remove any
quit-restore or quit-restore-prev parameters
(see Window Parameters) referencing that buffer.
This function does not replace the buffer specified by buffer-or-name in any minibuffer window showing it, nor does it delete minibuffer windows or minibuffer frames. It removes, however, that buffer from the lists of previous and next buffers of all minibuffer windows.
By default, replace-buffer-in-windows deletes only windows
dedicated to their buffers and ignores any quit-restore or
quit-restore-prev parameters of the windows it works on. The
following option is useful for circumventing these restrictions.
If this option is nil, kill-buffer (and in consequence
replace-buffer-in-windows) may only delete windows that are
dedicated to the buffer about to be killed. If this is non-nil,
replace-buffer-in-windows has quit-restore-window
(see Quitting Windows) deal with any such window. That function may
delete such a window even if it’s not dedicated to its buffer. Also,
delete-windows-on will use quit-restore-window as fallback
when a window cannot be deleted and another buffer must be shown in it.