@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2011
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/windows
@node Windows, Frames, Buffers, Top
* Buffers and Windows:: Each window displays the contents of a buffer.
* Displaying Buffers:: Higher-level functions for displaying a buffer
and choosing a window for it.
-* Choosing Window:: How to choose a window for displaying a buffer.
-* Dedicated Windows:: How to avoid displaying another buffer in
- a specific window.
+* Choosing Window:: How to choose a window for displaying a buffer.
+* Dedicated Windows:: How to avoid displaying another buffer in
+ a specific window.
* Window Point:: Each window has its own location of point.
* Window Start and End:: Buffer positions indicating which text is
on-screen in a window.
represents that screen area in Emacs Lisp. It should be
clear from the context which is meant.
- Emacs groups windows into frames, @xref{Frames}. A frame represents
-an area of screen available for Emacs to use. Each frame always
-contains at least one window, but you can subdivide it vertically or
-horizontally into multiple, nonoverlapping Emacs windows.
+ Emacs groups windows into frames; see @ref{Frames}. A frame
+represents an area of screen available for Emacs to use. Each frame
+always contains at least one window, but you can subdivide it
+vertically or horizontally into multiple, nonoverlapping Emacs
+windows.
In each frame, at any time, one and only one window is designated as
@dfn{selected within the frame}. The frame's cursor appears in that
window, but the other windows have ``non-selected'' cursors, normally
-less visible. (@pxref{Cursor Parameters}, for customizing this.) At
+less visible. (@xref{Cursor Parameters}, for customizing this.) At
any time, one frame is the selected frame; and the window selected
within that frame is @dfn{the selected window}. The selected window's
buffer is usually the current buffer (except when @code{set-buffer} has
-been used), @xref{Current Buffer}.
+been used); see @ref{Current Buffer}.
For practical purposes, a window exists only while it is displayed in
a frame. Once removed from the frame, the window is effectively deleted
and should not be used, @emph{even though there may still be references
-to it} from other Lisp objects, @xref{Deleting Windows}. Restoring a
+to it} from other Lisp objects; see @ref{Deleting Windows}. Restoring a
saved window configuration is the only way for a window no longer on the
-screen to come back to life, @xref{Window Configurations}.
+screen to come back to life; see @ref{Window Configurations}.
@cindex multiple windows
Users create multiple windows so they can look at several buffers at
@deffn Command split-window &optional window size horizontal
This function splits a new window out of @var{window}'s screen area. It
-returns the new window. @var{window} defaults to the selected window.
-When you split the selected window, it remains selected.
+returns the new window. The default for @var{window} is the selected
+window. When you split the selected window, it remains selected.
If @var{horizontal} is non-@code{nil}, then @var{window} splits into two
side by side windows. The original window keeps the leftmost @var{size}
@end smallexample
Normally, Emacs indicates the border between two side-by-side windows
-with a scroll bar, @xref{Scroll Bars}, or @samp{|} characters. The
-display table can specify alternative border characters; @xref{Display
+with a scroll bar (@pxref{Scroll Bars}), or with @samp{|} characters. The
+display table can specify alternative border characters; see @ref{Display
Tables}.
@end deffn
(@pxref{Window Configurations}). Restoring a window configuration also
deletes any windows that aren't part of that configuration.
- When you delete a window, the space it took up is given to one
-adjacent window.
+ When you delete a window, the space it took up is given to one of
+its sibling windows adjacent to it.
@c Emacs 19 feature
@defun window-live-p window
@deffn Command delete-window &optional window
This function removes @var{window} from display and returns @code{nil}.
-@var{window} defaults to the selected window. An error is signaled if
-@var{window} is the only window on its frame.
+The default for @var{window} is the selected window. An error is
+signaled if @var{window} is the only window on its frame.
@end deffn
@deffn Command delete-other-windows &optional window
This function makes @var{window} the only window on its frame, by
-deleting the other windows in that frame. @var{window} defaults to the
-selected window. The return value is @code{nil}.
+deleting the other windows in that frame. The default for @var{window}
+is the selected window. The return value is @code{nil}.
@end deffn
@deffn Command delete-windows-on &optional buffer-or-name frame
This function deletes all windows showing @var{buffer-or-name}. If
-there are no windows showing @var{buffer-or-name}, it does nothing.
-@var{buffer-or-name} may be a buffer or the name of an existing buffer
-and defaults to the current buffer.
+there are no windows showing @var{buffer-or-name}, it does nothing. The
+optional argument @var{buffer-or-name} may be a buffer or the name of an
+existing buffer and defaults to the current buffer.
@code{delete-windows-on} operates frame by frame. If a frame has
several windows showing different buffers, then those showing
(@pxref{Dedicated Windows}), and there are other frames left, that
window's frame is deleted.
-The argument @var{frame} specifies which frames to operate on. This
-function does not use it in quite the same way as the other functions
-which scan all windows; specifically, the values @code{t} and @code{nil}
-have the opposite of their meanings in other functions. Here are the
-full details:
+The optional argument @var{frame} specifies which frames to operate on.
+This function does not use it in quite the same way as the other
+functions which scan all windows; specifically, the values @code{t} and
+@code{nil} have the opposite of their meanings in other functions. Here
+are the full details:
@itemize @bullet
@item
@defun select-window window &optional norecord
This function makes @var{window} the selected window. The cursor then
-appears in @var{window} (on redisplay). Unless @var{window} was already
-selected, @code{select-window} makes @var{window}'s buffer the current
-buffer. The return value is @var{window}.
+appears in @var{window} (after redisplay). Unless @var{window} was
+already selected, @code{select-window} makes @var{window}'s buffer the
+current buffer. The return value is @var{window}.
Normally, @var{window}'s selected buffer is moved to the front of the
buffer list (@pxref{The Buffer List}) and @var{window} becomes the most
current buffer. It returns the value of the last form in @var{forms}.
This macro does not save or restore anything about the sizes,
-arrangement or contents of windows; therefore, if the @var{forms} change
+arrangement or contents of windows; therefore, if @var{forms} change
them, the change persists. If the previously selected window of some
frame is no longer live at the time of exit from @var{forms}, that
frame's selected window is left alone. If the previously selected
restores the previously selected window and current buffer. The ordering
of recently selected windows and the buffer list remain unchanged unless
you deliberately change them within @var{forms}, for example, by calling
-@code{select-window} with argument @var{norecord} nil or omitted there.
+@code{select-window} with argument @var{norecord} @code{nil}.
@end defmac
@cindex finding windows
@defun get-lru-window &optional frame dedicated
This function returns the window least recently ``used'' (that is,
-selected). If any full-width windows are present, it only considers
-these.
+selected) among a set of candidate windows. If any full-width windows
+are present, it only considers these.
-The selected window can be the least recently used window if it is the
-only window. A newly created window becomes the least recently used
-window until it is selected. A minibuffer window is never a candidate.
-A dedicated window (@pxref{Dedicated Windows}) is never a candidate
-unless the @var{dedicated} argument is non-@code{nil}, so if all
-existing windows are dedicated, the value is @code{nil}.
+The selected window is returned if it is the only candidate. A
+minibuffer window is never a candidate. A dedicated window
+(@pxref{Dedicated Windows}) is never a candidate unless the optional
+argument @var{dedicated} is non-@code{nil}.
-The argument @var{frame} specifies which windows are considered.
+The optional argument @var{frame} specifies which windows are
+considered.
@itemize @bullet
@item
width). If there are no side-by-side windows, then this is the window
with the most lines. A minibuffer window is never a candidate. A
dedicated window (@pxref{Dedicated Windows}) is never a candidate unless
-the @var{dedicated} argument is non-@code{nil}, so if all existing
-windows are dedicated, the value is @code{nil}.
+the optional argument @var{dedicated} is non-@code{nil}.
If there are two candidate windows of the same size, this function
-prefers the one that comes first in the cyclic ordering of windows
+prefers the one that comes first in the cyclic ordering of windows,
starting from the selected window (@pxref{Cyclic Window Ordering}).
-The argument @var{frame} specifies which set of windows to consider, see
-@code{get-lru-window} above.
+The optional argument @var{frame} specifies which set of windows to
+consider, see @code{get-lru-window} above.
@end defun
@cindex window that satisfies a predicate
specific order. For any given configuration of windows, this order
never varies. It is called the @dfn{cyclic ordering of windows}.
- This ordering generally goes from top to bottom, and from left to
-right. But it may go down first or go right first, depending on the
-order in which windows were split.
+ For a particular frame, this ordering generally goes from top to
+bottom, and from left to right. But it may go down first or go right
+first, depending on the order in which windows were split.
If the first split was vertical (into windows one above each other),
and then the subwindows were split horizontally, then the ordering is
In general, within each set of siblings at any level in the window tree
(@pxref{Window Tree}), the order is left to right, or top to bottom.
-@deffn Command next-window &optional window minibuf all-frames
+@defun next-window &optional window minibuf all-frames
@cindex minibuffer window, and @code{next-window}
This function returns the window following @var{window} in the cyclic
ordering of windows. This is the window @kbd{C-x o} selects if typed
-when @var{window} is selected. @var{window} defaults to the selected
-window.
+when @var{window} is selected. The default for @var{window} is the
+selected window.
-The value of the argument @var{minibuf} specifies whether the minibuffer
-is included in the window order. Normally, when @var{minibuf} is
-@code{nil}, the minibuffer is included only if it is currently
-``active''; this matches the behavior of @kbd{C-x o}. (The minibuffer
-window is active while the minibuffer is in use, @xref{Minibuffers}.)
+The value of the optional argument @var{minibuf} specifies whether the
+minibuffer is included in the window order. Normally, when
+@var{minibuf} is @code{nil}, the minibuffer is included only if it is
+currently ``active''; this matches the behavior of @kbd{C-x o}. (The
+minibuffer window is active while the minibuffer is in use; see
+@ref{Minibuffers}.)
If @var{minibuf} is @code{t}, the cyclic ordering includes the
minibuffer window even if it is not active. If @var{minibuf} is neither
@code{t} nor @code{nil}, the minibuffer window is not included even if
it is active.
-The argument @var{all-frames} specifies which frames to consider. Here
-are the possible values and their meanings:
+The optional argument @var{all-frames} specifies which frames to
+consider. Here are the possible values and their meanings:
@table @asis
@item @code{nil}
@result{} #<window 56 on windows.texi>
@end group
@end example
-@end deffn
+@end defun
-@deffn Command previous-window &optional window minibuf all-frames
+@defun previous-window &optional window minibuf all-frames
This function returns the window preceding @var{window} in the cyclic
ordering of windows. The other arguments specify which windows to
include in the cycle, as in @code{next-window}.
-@end deffn
+@end defun
@deffn Command other-window count &optional all-frames
This function selects another window in the cyclic ordering of windows.
the selected window. In an interactive call, @var{count} is the numeric
prefix argument.
-The argument @var{all-frames} has the same meaning as in
+The optional argument @var{all-frames} has the same meaning as in
@code{next-window}, but the @var{minibuf} argument of @code{next-window}
is always effectively @code{nil}. This function returns @code{nil}.
@end deffn
@defun window-list &optional frame minibuf window
This function returns a list of all windows on @var{frame}, starting
-with @var{window}. @var{frame} defaults to the selected frame;
-@var{window} to the selected window.
+with @var{window}. The default for @var{frame} is the selected frame;
+the default for @var{window} is the selected window.
The value of @var{minibuf} specifies if the minibuffer window shall be
included in the result list. If @var{minibuf} is @code{t}, the result
@defun set-window-buffer window buffer-or-name &optional keep-margins
This function makes @var{window} display @var{buffer-or-name} as its
-contents. It returns @code{nil}. @var{buffer-or-name} must be a
-buffer, or the name of an existing buffer. This is the fundamental
-primitive for changing which buffer is displayed in a window, and all
-ways of doing that call this function.
+contents. It returns @code{nil}. The default for @var{window} is the
+selected window. The argument @var{buffer-or-name} must specify a
+buffer or the name of an existing buffer.
+
+@code{set-window-buffer} is the fundamental primitive for changing which
+buffer is displayed in a window, and all ways of doing that call this
+function.
@example
@group
Normally, displaying @var{buffer-or-name} in @var{window} resets the
window's position, display margins, fringe widths, and scroll bar
-settings, to values based on the local variables of that buffer.
+settings based on the local variables of that buffer.
However, if @var{keep-margins} is non-@code{nil}, display margins and
fringe widths of @var{window} remain unchanged. @xref{Fringes}.
-This function signals an error when @var{window} is @dfn{strongly}
-dedicated to its buffer (@pxref{Dedicated Windows}) and does not already
-display @var{buffer-or-name}.
+@code{set-window-buffer} signals an error when @var{window} is
+@dfn{strongly} dedicated to its buffer (@pxref{Dedicated Windows}) and
+does not already display @var{buffer-or-name}.
-This function runs @code{window-scroll-functions} before running
-@code{window-configuration-change-hook}.
+Note that this function runs @code{window-scroll-functions} before
+running @code{window-configuration-change-hook}.
@end defun
@defvar buffer-display-count
@end defvar
@defun window-buffer &optional window
-This function returns the buffer that @var{window} is displaying.
-@var{window} defaults to the selected window.
+This function returns the buffer that @var{window} is displaying. The
+default for @var{window} is the selected window.
@example
@group
cyclic ordering of windows, starting from the selected window.
@xref{Cyclic Window Ordering}.
-@var{BUFFER-OR-NAME} may be a buffer or a buffer name and defaults to
-the current buffer. The argument @var{all-frames} specifies which
-windows to consider:
+The argument @var{BUFFER-OR-NAME} may be a buffer or a buffer name and
+defaults to the current buffer. The optional argument @var{all-frames}
+specifies which windows to consider:
@itemize @bullet
@item
@defun get-buffer-window-list &optional buffer-or-name minibuf all-frames
This function returns a list of all windows currently displaying
-@var{buffer-or-name}. @var{buffer-or-name} may be a buffer or the name
-of an existing buffer and defaults to the current buffer.
+@var{buffer-or-name}. The argument @var{buffer-or-name} may be a buffer
+or the name of an existing buffer and defaults to the current buffer.
The two remaining arguments work like the same-named arguments of
@code{next-window}; they are @emph{not} like the optional arguments of
displays the buffer in the selected window. This means that a human can
see the buffer and subsequent keyboard commands will apply to it.
Contrast this with @code{set-buffer}, which makes @var{buffer-or-name}
-the current buffer but does not display it in the selected window,
-@xref{Current Buffer}.
+the current buffer but does not display it in the selected window;
+see @ref{Current Buffer}.
If @var{buffer-or-name} is @code{nil}, @code{switch-to-buffer} chooses a
buffer using @code{other-buffer}. If @var{buffer-or-name} is a string
that does not identify an existing buffer, then a new buffer by that
name is created. The major mode for the new buffer is set according to
-the variable @code{default-major-mode}, @xref{Auto Major Mode}.
+the variable @code{major-mode}; see @ref{Auto Major Mode}.
+
+When the selected window is the minibuffer window or is strongly
+dedicated to its buffer (@pxref{Dedicated Windows}), this function calls
+@code{pop-to-buffer} (see below) to display the buffer in some other
+window.
Normally the specified buffer is put at the front of the buffer list
(both the selected frame's buffer list and the frame-independent buffer
for the described features.
@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
-This function makes @var{buffer-or-name} the current buffer, displays it
-in a window not currently selected, and selects that window. The
-handling of the buffer is the same as in @code{switch-to-buffer}.
+This function makes the buffer specified by @var{buffer-or-name} current
+and displays it in a window not currently selected, using the function
+@code{pop-to-buffer} (see below).
The currently selected window is absolutely never used to do the job.
-If it is the only window, then it is split to make a distinct window for
-this purpose. If the selected window is already displaying the buffer,
-then it continues to do so, but another window is nonetheless found to
-display it in as well.
+If the selected window already displays @var{buffer-or-name}, then it
+continues to do so, but another window is nonetheless found to display
+it in as well.
This function updates the buffer list just like @code{switch-to-buffer}
unless @var{norecord} is non-@code{nil}.
@end deffn
-@deffn Command pop-to-buffer buffer-or-name &optional other-window norecord
-This command makes @var{buffer-or-name} the current buffer and switches
+@defun pop-to-buffer buffer-or-name &optional other-window norecord
+This function makes @var{buffer-or-name} the current buffer and switches
to it in some window, preferably not the window previously selected.
The ``popped-to'' window becomes the selected window. Its frame is
-given the X server's focus, if possible, @xref{Input Focus}. The return
-value is the buffer that was switched to.
+given the X server's focus, if possible; see @ref{Input Focus}. The
+return value is the buffer that was switched to.
If @var{buffer-or-name} is @code{nil}, that means to choose some other
buffer, but you don't specify which. If @var{buffer-or-name} is a
string that does not name an existing buffer, a buffer by that name is
created. The major mode for the new buffer is set according to the
-variable @code{default-major-mode}. @xref{Auto Major Mode}.
-
-If the variable @code{pop-up-frames} is non-@code{nil},
-@code{pop-to-buffer} looks for a window in any visible frame already
-displaying the buffer; if there is one, it selects and returns that
-window. If no such window exists, it creates a new frame and displays
-the buffer in it.
-
-If @code{pop-up-frames} is @code{nil}, then @code{pop-to-buffer}
-operates entirely within the selected frame. (If the selected frame has
-just a minibuffer, @code{pop-to-buffer} operates within the most
-recently selected frame that was not just a minibuffer.)
+variable @code{major-mode}. @xref{Auto Major Mode}.
+
+If either of the variables @code{display-buffer-reuse-frames} or
+@code{pop-up-frames} is non-@code{nil}, @code{pop-to-buffer} looks for a
+window in any visible frame already displaying the buffer; if there is
+one, it selects and returns that window. If no such window exists and
+@code{pop-up-frames} is non-@code{nil}, it creates a new frame and
+displays the buffer in it. Otherwise, @code{pop-to-buffer} operates
+entirely within the selected frame. (If the selected frame has just a
+minibuffer, @code{pop-to-buffer} operates within the most recently
+selected frame that was not just a minibuffer.)
If the variable @code{pop-up-windows} is non-@code{nil}, windows may be
split to create a new window that is different from the original window.
-For details, @xref{Choosing Window}.
+For details, see @ref{Choosing Window}.
If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or
creates another window even if @var{buffer-or-name} is already visible
This function updates the buffer list just like @code{switch-to-buffer}
unless @var{norecord} is non-@code{nil}.
-@end deffn
+@end defun
@deffn Command replace-buffer-in-windows &optional buffer-or-name
This function replaces @var{buffer-or-name} in all windows displaying
don't care which other buffer is used; you just want to make sure that
@var{buffer-or-name} is no longer displayed.
-@var{buffer-or-name} may be a buffer or the name of an existing buffer
-and defaults to the current buffer.
+The argument @var{buffer-or-name} may be a buffer or the name of an
+existing buffer and defaults to the current buffer.
If a window displaying @var{buffer-or-name} is dedicated
(@pxref{Dedicated Windows}), and is not the only window on its frame,
This section describes the basic facility that chooses a window to
display a buffer in---@code{display-buffer}. Higher-level functions and
-commands like @code{switch-to-buffer} and @code{pop-to-buffer} use this
+commands, like @code{switch-to-buffer} and @code{pop-to-buffer}, use this
subroutine. Here we describe how to use @code{display-buffer} and how
to customize it.
This command makes @var{buffer-or-name} appear in some window, but it
does not select that window and does not make the buffer specified by
@var{buffer-or-name} current. The identity of the selected window is
-unaltered by this function. @var{buffer-or-name} must be a buffer, or
-the name of an existing buffer.
+unaltered by this function. The argument @var{buffer-or-name} must be a
+buffer or the name of an existing buffer.
@var{not-this-window} non-@code{nil} means to display the specified
buffer in a window other than the selected one, even if it is already
@code{display-buffer} returns the window chosen to display
@var{buffer-or-name}.
-If the argument @var{frame} is non-@code{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,
-@code{display-buffer} simply returns that window. Here are the possible
-values of @var{frame}:
+If the optional argument @var{frame} is non-@code{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, @code{display-buffer} simply returns that window. Here
+are the possible values of @var{frame}:
@itemize @bullet
@item
@defopt display-buffer-reuse-frames
If this variable is non-@code{nil}, @code{display-buffer} searches
-existing frames for a window displaying @var{buffer-or-name}. If the
-buffer is already displayed in a window in some frame,
-@code{display-buffer} makes the frame visible and raises it, to use that
-window. If the buffer is not already displayed, or
+visible and iconified frames for a window displaying
+@var{buffer-or-name}. If there is such a window, @code{display-buffer}
+makes that window's frame visible and raises it if necessary, and
+returns the window. If there is no such window or
@code{display-buffer-reuse-frames} is @code{nil}, the behavior of
@code{display-buffer} is determined by the variables described next.
@end defopt
@defopt pop-up-windows
This variable specifies whether @code{display-buffer} is allowed to
-split (@pxref{Splitting Windows}) an existing window . If it is
-non-@code{nil}, @code{display-buffer} tries to the split the largest or
+split (@pxref{Splitting Windows}) an existing window. If this variable
+is non-@code{nil}, @code{display-buffer} tries to split the largest or
least recently used window on the selected frame. (If the selected
-frame is a minibuffer-only frame, it tries to split a window on another
-frame instead.) If @code{pop-up-windows} is nil or the variable
-@code{pop-up-frames} (see below) is non-@code{nil},
+frame is a minibuffer-only frame, @code{display-buffer} tries to split a
+window on another frame instead.) If this variable is @code{nil} or the
+variable @code{pop-up-frames} (see below) is non-@code{nil},
@code{display-buffer} does not split any window.
@end defopt
-@defvar split-window-preferred-function
-This variable specifies how to split a window. Its value, if
-non-@code{nil}, should be a function of one argument, which is a
-window. If this variable specifies a function, @code{display-buffer}
-will call it with one or more candidate windows when it looks for a
-window to split. If the argument window fits, the function is
-expected to split it and return a new window. If the function returns
-@code{nil}, the argument window will not be split.
-
-If the value of this variable is @code{nil}, @code{display-buffer}
-uses the two variables described next to decide whether and which
-window to split.
-@end defvar
+@defopt split-window-preferred-function
+This variable must specify a function with one argument, which is a
+window. The @code{display-buffer} routines will call this function with
+one or more candidate windows when they look for a window to split. The
+function is expected to split that window and return the new window. If
+the function returns @code{nil}, this means that the argument window
+cannot (or shall not) be split.
+
+The default value of @code{split-window-preferred-function} is the
+function @code{split-window-sensibly} described below. If you
+customize this option, bear in mind that the @code{display-buffer}
+routines may call your function up to two times when trying to split a
+window. The argument of the first call is the largest window on the
+chosen frame (as returned by @code{get-largest-window}). If that call
+fails to return a live window, your function is called a second time
+with the least recently used window on that frame (as returned by
+@code{get-lru-window}).
+
+The function specified by this option may try to split any other window
+instead of the argument window. Note that the window selected at the
+time @code{display-buffer} was invoked is still selected when your
+function is called. Hence, you can split the selected window (instead
+of the largest or least recently used one) by simply ignoring the window
+argument in the body of your function. You can even choose to not split
+any window as long as the return value of your function specifies a live
+window or @code{nil}, but you are not encouraged to do so
+unconditionally. If you want @code{display-buffer} to never split any
+windows, set @code{pop-up-windows} to @code{nil}.
+@end defopt
+
+@defun split-window-sensibly window
+This function takes a window as argument and tries to split that window
+in a suitable way. The two variables described next are useful for
+tuning the behavior of this function.
+@end defun
@defopt split-height-threshold
-This variable specifies whether @code{display-buffer} may split a window
-vertically, provided there are multiple windows. If the value is a
-number, @code{display-buffer} splits a window only if it has at least
-this many lines. If no window is tall enough, or if the value of this
-variable is @code{nil}, @code{display-buffer} tries to split some window
-horizontally, subject to restrictions of @code{split-width-threshold}
-(see below). If splitting horizontally is impossible too,
-@code{display-buffer} splits a window vertically only if it's the only
-window on its frame and not the minibuffer window, and only if
-@code{pop-up-windows} is non-@code{nil}.
-
-A window whose height is fixed (@pxref{Resizing Windows}) cannot be
-split vertically by @code{display-buffer}. Also, @code{display-buffer}
-splits a window vertically only if it can accommodate two windows that
-are both at least `window-min-height' lines tall. Moreover, if the
-window that shall be split has a mode line, the window must be at least
-four lines tall in order to make sure that the new window can have a
-mode line as well. If the original window doesn't have a mode line, a
-height of two lines suffices.
+This variable specifies whether @code{split-window-sensibly} may split
+windows vertically. If it is an integer, @code{split-window-sensibly}
+tries to vertically split a window only if it has at least this many
+lines. If the window has less lines, splitting fails, or the value of
+this variable is @code{nil}, @code{split-window-sensibly} will try to
+split the window horizontally, subject to restrictions of
+@code{split-width-threshold} (see below). If splitting horizontally
+fails too and the window is the only window on its frame,
+@code{split-window-sensibly} will try to split the window vertically
+disregarding the value of @code{split-height-threshold}. If this fails
+as well, @code{split-window-sensibly} returns @code{nil}.
+
+@code{split-window-sensibly} does not split vertically a window whose
+height is fixed (@pxref{Resizing Windows}). Also, it vertically splits
+a window only if the space taken up by that window can accommodate two
+windows one above the other that are both at least
+@code{window-min-height} lines tall. Moreover, if the window that shall
+be split has a mode line, @code{split-window-sensibly} does not split
+the window unless the new window can accommodate a mode line too.
@end defopt
@defopt split-width-threshold
-This variable specifies whether @code{display-buffer} may split a window
-horizontally. If the value is a number, @code{display-buffer} may split
-a window if it has at least this many columns. If the value of this
-variable is @code{nil}, @code{display-buffer} will not split any windows
-horizontally. (It still might split some window vertically, though, see
-above.)
-
-A window whose width is fixed (@pxref{Resizing Windows}) cannot be split
-horizontally by @code{display-buffer}. Also, @code{display-buffer}
-splits a window horizontally only if it can accommodate two windows that
-are both at least `window-min-width' columns wide.
+This variable specifies whether @code{split-window-sensibly} may split
+windows horizontally. If it is an integer, @code{split-window-sensibly}
+tries to horizontally split a window only if it has at least this many
+columns. If it is @code{nil}, @code{split-window-sensibly} will not
+split the window horizontally. (It still might split the window
+vertically, though, see above.)
+
+@code{split-window-sensibly} does not split horizontally a window if
+that window's width is fixed (@pxref{Resizing Windows}). Also, it
+horizontally splits a window only if the space that window takes up can
+accommodate two windows side by side that are both at least
+@code{window-min-width} columns wide.
@end defopt
@defopt even-window-heights
@c Emacs 19 feature
@defopt pop-up-frames
-This variable specifies whether @code{display-buffer} makes new frames.
-If it is non-@code{nil}, @code{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,
-unless the variable's value is @code{graphic-only} and the selected
-frame is not on a graphic display. @xref{Frames}, for more information.
+This variable specifies whether @code{display-buffer} should make new
+frames. If it is non-@code{nil}, @code{display-buffer} looks for a
+window already displaying @var{buffer-or-name} on any visible or
+iconified frame. If it finds such a window, it makes that window's
+frame visible and raises it if necessary, and returns the window.
+Otherwise it makes a new frame, unless the variable's value is
+@code{graphic-only} and the selected frame is not on a graphic display.
+@xref{Frames}, for more information.
Note that the value of @code{pop-up-windows} does not matter if
@code{pop-up-frames} is non-@code{nil}. If @code{pop-up-frames} is
This variable specifies how to make a new frame if @code{pop-up-frames}
is non-@code{nil}.
-Its value should be a function of no arguments. When
+The value of this variable must be a function of no arguments. When
@code{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
-@code{pop-up-frame-alist}.
+function, which should return a frame. The default value of this
+variable is a function that creates a frame using the parameters
+specified by @code{pop-up-frame-alist} described next.
@end defopt
@defopt pop-up-frame-alist
-This variable holds an alist specifying frame parameters used when
-@code{display-buffer} makes a new frame. @xref{Frame Parameters}, for
-more information about frame parameters.
+This variable holds an alist specifying frame parameters used by the
+default value of @code{pop-up-frame-function} for making new frames.
+@xref{Frame Parameters}, for more information about frame parameters.
@end defopt
@defopt special-display-buffer-names
of frame parameters.
@end defun
-@defvar special-display-function
+@defopt 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
@code{special-display-popup-frame}, see below.
-@end defvar
+@end defopt
@defun special-display-popup-frame buffer &optional args
This function tries to make @var{buffer} visible in a frame of its own.
@end defun
@c Emacs 19 feature
-@defvar display-buffer-function
+@defopt display-buffer-function
This variable is the most flexible way to customize the behavior of
@code{display-buffer}. If it is non-@code{nil}, it should be a function
that @code{display-buffer} calls to do the work. The function should
This variable takes precedence over all the other options described
above.
-@end defvar
+@end defopt
If all options described above fail to produce a suitable window,
@code{display-buffer} tries to reuse an existing window. As a last
@cindex dedicated window
Functions for displaying a buffer can be told to not use specific
-windows by marking these window as @dfn{dedicated} to their buffers.
+windows by marking these windows as @dfn{dedicated} to their buffers.
@code{display-buffer} (@pxref{Choosing Window}) never uses a dedicated
window for displaying another buffer in it. @code{get-lru-window} and
@code{get-largest-window} (@pxref{Selecting Windows}) do not consider
dedicated window, any such window usually gets deleted too, since
@code{kill-buffer} calls @code{replace-buffer-in-windows} for cleaning
up windows. Burying a buffer (@pxref{The Buffer List}) deletes the
-selected window if it is dedicated and shows that buffer. However, if
-that window is the only window on its frame, another buffer is displayed
-in it and the frame is iconified.
+selected window if it is dedicated to that buffer. If, however, that
+window is the only window on its frame, @code{bury-buffer} displays
+another buffer in it and iconifies the frame.
@defun window-dedicated-p &optional window
This function returns non-@code{nil} if @var{window} is dedicated to its
buffer and @code{nil} otherwise. More precisely, the return value is
the value assigned by the last call of @code{set-window-dedicated-p} for
@var{window} or @code{nil} if that function was never called with
-@var{WINDOW} as its argument. @var{WINDOW} defaults to the selected
-window.
+@var{window} as its argument. The default for @var{window} is the
+selected window.
@end defun
@defun set-window-dedicated-p window flag
@dfn{strongly} dedicated to its buffer. @code{set-window-buffer}
signals an error when the window it acts upon is strongly dedicated to
its buffer and does not already display the buffer it is asked to
-display. In any other case, @code{set-window-buffer} will display
-another buffer in that window. Other functions do not treat @code{t}
-differently from any non-@code{nil} value.
+display. Other functions do not treat @code{t} differently from any
+non-@code{nil} value.
@end defun
@node Window Point
@end itemize
@cindex cursor
-As far as the user is concerned, point is where the cursor is, and
+ As far as the user is concerned, point is where the cursor is, and
when the user switches to another buffer, the cursor jumps to the
position of point in that buffer.
@defun window-point &optional window
This function returns the current position of point in @var{window}.
For a nonselected window, this is the value point would have (in that
-window's buffer) if that window were selected. @var{window} defaults to
-the selected window.
+window's buffer) if that window were selected. The default for
+@var{window} is the selected window.
When @var{window} is the selected window and its buffer is also the
current buffer, the value returned is the same as point in that buffer.
this simply does @code{goto-char}.
@end defun
+@defvar window-point-insertion-type
+This variable specifies the marker insertion type (@pxref{Marker
+Insertion Types}) of @code{window-point}. The default is @code{nil},
+so @code{window-point} will stay behind text inserted there.
+@end defvar
+
@node Window Start and End
@section The Window Start and End Positions
@cindex window start position
@cindex window end position
@defun window-end &optional window update
This function returns the position where display of its buffer ends in
-@var{window}. @var{window} defaults to the selected window.
+@var{window}. The default for @var{window} is the selected window.
Simply changing the buffer text or moving point does not update the
value that @code{window-end} returns. The value is updated only when
selected window. If @var{position} is @code{t}, that means to check the
last visible position in @var{window}.
-The @code{pos-visible-in-window-p} function considers only vertical
-scrolling. If @var{position} is out of view only because @var{window}
-has been scrolled horizontally, @code{pos-visible-in-window-p} returns
-non-@code{nil} anyway. @xref{Horizontal Scrolling}.
+This function considers only vertical scrolling. If @var{position} is
+out of view only because @var{window} has been scrolled horizontally,
+@code{pos-visible-in-window-p} returns non-@code{nil} anyway.
+@xref{Horizontal Scrolling}.
If @var{position} is visible, @code{pos-visible-in-window-p} returns
@code{t} if @var{partially} is @code{nil}; if @var{partially} is
@end defun
@defun window-line-height &optional line window
-This function returns information about text line @var{line} in @var{window}.
-If @var{line} is one of @code{header-line} or @code{mode-line},
-@code{window-line-height} returns information about the corresponding
-line of the window. Otherwise, @var{line} is a text line number
-starting from 0. A negative number counts from the end of the window.
-The argument @var{line} defaults to the current line in @var{window};
-@var{window}, to the selected window.
+This function returns the height of text line @var{line} in
+@var{window}. If @var{line} is one of @code{header-line} or
+@code{mode-line}, @code{window-line-height} returns information about
+the corresponding line of the window. Otherwise, @var{line} is a text
+line number starting from 0. A negative number counts from the end of
+the window. The default for @var{line} is the current line in
+@var{window}; the default for @var{window} is the selected window.
If the display is not up to date, @code{window-line-height} returns
@code{nil}. In that case, @code{pos-visible-in-window-p} may be used
If the window contains a row which is taller than the height of the
window (for example in the presence of a large image), the scroll
-functions will adjust the window vscroll to scroll the partially
-visible row. To disable this feature, Lisp code may bind the variable
-`auto-window-vscroll' to @code{nil} (@pxref{Vertical Scrolling}).
+functions will adjust the window's vertical scroll position to scroll
+the partially visible row. To disable this feature, Lisp code may bind
+the variable @code{auto-window-vscroll} to @code{nil} (@pxref{Vertical
+Scrolling}).
@deffn Command scroll-up &optional count
This function scrolls the text in the selected window upward
@end defopt
@defopt scroll-step
-This variable is an older variant of @code{scroll-conservatively}. The
-difference is that it if its value is @var{n}, that permits scrolling
+This variable is an older variant of @code{scroll-conservatively}.
+The difference is that if its value is @var{n}, that permits scrolling
only by precisely @var{n} lines, not a smaller number. This feature
does not work with @code{scroll-margin}. The default value is zero.
@end defopt
@cindex vertical fractional scrolling
@cindex vertical scroll position
-@dfn{Vertical fractional scrolling} means shifting text in a window up
-or down by a specified multiple or fraction of a line. Each window has
-a @dfn{vertical scroll position}, which is a number, never less than
+ @dfn{Vertical fractional scrolling} means shifting text in a window
+up or down by a specified multiple or fraction of a line. Each window
+has a @dfn{vertical scroll position}, which is a number, never less than
zero. It specifies how far to raise the contents of the window.
Raising the window contents generally makes all or part of some lines
disappear off the top, and all or part of some other lines appear at the
bottom. The usual value is zero.
-The vertical scroll position is measured in units of the normal line
+ The vertical scroll position is measured in units of the normal line
height, which is the height of the default font. Thus, if the value is
.5, that means the window contents are scrolled up half the normal line
height. If it is 3.3, that means the window contents are scrolled up
somewhat over three times the normal line height.
-What fraction of a line the vertical scrolling covers, or how many
+ What fraction of a line the vertical scrolling covers, or how many
lines, depends on what the lines contain. A value of .5 could scroll a
line whose height is very short off the screen, while a value of 3.3
could scroll just part of the way through a tall line or an image.
@defun window-vscroll &optional window pixels-p
This function returns the current vertical scroll position of
-@var{window}. @var{window} defaults to the selected window. If
-@var{pixels-p} is non-@code{nil}, the return value is measured in
+@var{window}. The default for @var{window} is the selected window.
+If @var{pixels-p} is non-@code{nil}, the return value is measured in
pixels, rather than in units of the normal line height.
@example
@defvar auto-window-vscroll
If this variable is non-@code{nil}, the line-move, scroll-up, and
scroll-down functions will automatically modify the vertical scroll
-position to scroll through display rows that are taller that the height
+position to scroll through display rows that are taller than the height
of the window, for example in the presence of large images.
@end defvar
@defun window-hscroll &optional window
This function returns the total leftward horizontal scrolling of
@var{window}---the number of columns by which the text in @var{window}
-is scrolled left past the left margin. @var{window} defaults to the
-selected window.
+is scrolled left past the left margin. The default for
+@var{window} is the selected window.
The return value is never negative. It is zero when no horizontal
scrolling has been done in @var{window} (which is usually the case).
@end example
@end defun
-Here is how you can determine whether a given position @var{position} is
-off the screen due to horizontal scrolling:
+ Here is how you can determine whether a given position @var{position}
+is off the screen due to horizontal scrolling:
@example
@group
The following three functions return size information about a window:
@defun window-height &optional window
-This function returns the number of lines in @var{window}, including its
-mode line and header line, if any. If @var{window} fills its entire
-frame except for the echo area, this is typically one less than the
-value of @code{frame-height} on that frame. @var{window} defaults to
-the selected window.
+This function returns the number of lines in @var{window} (by default
+the selected window), including any mode line and header line.
+The result is almost always less than the value of @code{frame-height}
+for the associated frame, because the latter also includes any echo
+area. Depending on the toolkit in use, the frame height can also
+include the menu bar and tool bar (@pxref{Size and Position}).
+Therefore in general it is not straightforward to compare window and
+frame heights (see @code{window-full-height-p} below).
@example
@group
mode line (if any) or the header line (if any).
@end defun
+@defun window-full-height-p &optional window
+This function returns non-@code{nil} if @var{window} is as tall as the
+frame that contains it. The default for @var{window} is the selected
+window.
+@end defun
+
@defun window-width &optional window
-This function returns the number of columns in @var{window}.
-@var{window} defaults to the selected window.
+This function returns the number of columns in @var{window}. The
+default for @var{window} is the selected window.
The return value does not include the window's scroll bar or the column
of @samp{|} characters that separates side-by-side windows. Moreover,
@defun window-full-width-p &optional window
This function returns non-@code{nil} if @var{window} is as wide as the
-frame that contains it; otherwise @code{nil}. @var{window} defaults to
-the selected window.
+frame that contains it; otherwise @code{nil}. The default for
+@var{window} is the selected window.
@end defun
@defun window-edges &optional window
This function returns a list of the edge coordinates of @var{window}.
-@var{window} defaults to the selected window.
+The default for @var{window} is the selected window.
The order of the list is @code{(@var{left} @var{top} @var{right}
@var{bottom})}, all elements relative to 0, 0 at the top left corner of
@cindex changing window size
@cindex window size, changing
-The window size functions fall into two classes: high-level commands
+ The window size functions fall into two classes: high-level commands
that change the size of windows and low-level functions that access
window size. Emacs does not permit overlapping windows or gaps between
windows, so resizing a window always affects at least one other window.
If there are various other windows from which lines or columns can be
stolen, and some of them specify fixed size (using
@code{window-size-fixed}, see below), they are left untouched while
-other windows are ``robbed''. If it would be necessary to alter the
+other windows are ``robbed.'' If it would be necessary to alter the
size of a fixed-size window, @code{enlarge-window} gets an error
instead.
function returns @code{nil}.
@end defun
-@defun fit-window-to-buffer &optional window max-height min-height
-This function makes @var{window} the right height to display its
-contents exactly. @var{window} defaults to the selected window.
+@deffn Command fit-window-to-buffer &optional window max-height min-height
+This command makes @var{window} the right height to display its
+contents exactly. The default for @var{window} is the selected window.
-The argument @var{max-height} specifies the maximum height the window
-is allowed to be; @code{nil} means use the frame height. The argument
-@var{min-height} specifies the minimum height for the window;
-@code{nil} means use @code{window-min-height}. All these height
-values include the mode line and/or header line.
-@end defun
+The optional argument @var{max-height} specifies the maximum height the
+window is allowed to be; @code{nil} means use the maximum permissible
+height of a window on @var{window}'s frame. The optional argument
+@var{min-height} specifies the minimum height for the window; @code{nil}
+means use @code{window-min-height}. All these height values include the
+mode line and/or header line.
+
+This function can delete windows when their height shrinks below
+@var{min-height}. It returns non-@code{nil} if it orderly resized
+@var{window}, and @code{nil} otherwise.
+@end deffn
@deffn Command shrink-window-if-larger-than-buffer &optional window
This command shrinks @var{window} vertically to be as small as possible
while still showing the full contents of its buffer---but not less than
-@code{window-min-height} lines. @var{window} defaults to the selected
-window.
+@code{window-min-height} lines. The default for @var{window} is
+the selected window.
However, this command does nothing if the window is already too small to
display the whole text of the buffer, or if part of the contents are
@code{window-min-height} automatically deletes it, and no window may be
created shorter than this. The value is measured in line units. When
the window wants a mode line and/or a header line, they are counted as
-one line each. The default value of this variable is @code{4}. A value
-less than @code{1} is ignored.
+one line each. The default value is @code{4}. A value less than
+@code{1} is ignored.
@end defopt
@defopt window-min-width
@end defopt
@cindex balancing window sizes
-Emacs provides two functions to balance windows, that means, to even out
+Emacs provides two functions to balance windows, that is, to even out
the sizes of windows on the same frame. The minibuffer window and
fixed-size windows are not resized by these functions.
@var{window-or-frame} specifies a window, it balances this window and
its ``siblings'' only. Think of a sibling as the other (original or
new) window with respect to the present one, involved in the process of
-splitting, @xref{Splitting Windows}. Since a sibling may have been
+splitting; see @ref{Splitting Windows}. Since a sibling may have been
split again, a window can have more than one sibling.
@end deffn
@deffn Command balance-windows-area
This function attempts to give all windows on the selected frame
-approximately the same share of the screen area. This means, that
+approximately the same share of the screen area. This means that
full-width or full-height windows are not given more space than other
windows.
@end deffn
of @code{minibuffer-scroll-window}. As a special exception, the window
configuration does not record the value of point in the selected window
for the current buffer. Also, the window configuration does not record
-the values of window parameters, @xref{Window Parameters}.
+the values of window parameters; see @ref{Window Parameters}.
- You can bring back an entire frame layout by restoring a window
-configuration previously saved. If you want to record the layout of all
+ You can bring back an entire frame layout by restoring a previously
+saved window configuration. If you want to record the layout of all
frames instead of just one, use a frame configuration instead of a
-window configuration, @xref{Frame Configurations}.
+window configuration; see @ref{Frame Configurations}.
@defun current-window-configuration &optional frame
This function returns a new object representing @var{frame}'s current
-window configuration. @var{frame} defaults to the selected frame.
+window configuration. The default for @var{frame} is the selected
+frame.
@end defun
@defun set-window-configuration configuration
additional information with windows.
@defun window-parameter window parameter
-This function returns @var{window}'s value for @var{parameter}.
-@var{window} defaults to the selected window. If @var{window} has no
-setting for @var{parameter}, this function returns @code{nil}.
+This function returns @var{window}'s value for @var{parameter}. The
+default for @var{window} is the selected window. If @var{window}
+has no setting for @var{parameter}, this function returns @code{nil}.
@end defun
-@defun window-parameters &optional window
+@defun window-parameters &optional window
This function returns all parameters of @var{window} and their values.
-@var{window} defaults to the selected window. The return value is an
-association list of elements of the form (@var{parameter}
-. @var{value}).
+The default for @var{window} is the selected window. The return value
+is an association list of elements of the form @code{(@var{parameter}
+. @var{value})}.
@end defun
@defun set-window-parameter window parameter value
This function sets @var{window}'s value of @var{parameter} to
-@var{value} and returns @var{value}. @var{window} defaults to the
-selected window.
+@var{value} and returns @var{value}. The default for @var{window}
+is the selected window.
@end defun
Currently, window parameters are not saved in window configurations and
any change of a parameter introduced via @code{set-window-parameter} can
be undone only by invoking @code{set-window-parameter} for the same
parameter again. Since @code{save-window-excursion} relies on window
-configurations, window parameters are not saved and restored by that
-special form either, @xref{Window Configurations}.
+configurations (@pxref{Window Configurations}), window parameters are
+not saved and restored by that special form, either.
@node Window Hooks
@section Hooks for Window Scrolling and Changes
Windows}) is what you need here.
@end defvar
-@defvar redisplay-end-trigger-functions
-This abnormal hook is run whenever redisplay in a window uses text that
-extends past a specified end trigger position. You set the end trigger
-position with @code{set-window-redisplay-end-trigger}. The functions
-are called with two arguments: the window, and the end trigger position.
-Storing @code{nil} for the end trigger position turns off the feature,
-and the trigger value is automatically reset to @code{nil} just after
-the hook is run.
-@end defvar
-
-@defun set-window-redisplay-end-trigger window position
-This function sets @var{window}'s end trigger position at
-@var{position}.
-@end defun
-
-@defun window-redisplay-end-trigger &optional window
-This function returns @var{window}'s current end trigger position.
-If @var{window} is @code{nil} or omitted, it uses the selected window.
-@end defun
-
@defvar window-configuration-change-hook
A normal hook that is run every time you change the window configuration
of an existing frame. This includes splitting or deleting windows,
frame selected.
@end defvar
-@ignore
- arch-tag: 3f6c36e8-df49-4986-b757-417feed88be3
-@end ignore
+ In addition, you can use @code{jit-lock-register} to register a Font
+Lock fontification function, which will be called whenever parts of a
+buffer are (re)fontified because a window was scrolled or its size
+changed. @xref{Other Font Lock Variables}.