@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Windows
@chapter Windows
@cindex valid windows
A @dfn{valid window} is one that is either live or internal. A valid
-window can be @dfn{deleted}, i.e. removed from its frame
+window can be @dfn{deleted}, i.e., removed from its frame
(@pxref{Deleting Windows}); then it is no longer valid, but the Lisp
object representing it might be still referenced from other Lisp
objects. A deleted window may be made valid again by restoring a saved
This function returns the parent window of @var{window}. If
@var{window} is omitted or @code{nil}, it defaults to the selected
window. The return value is @code{nil} if @var{window} has no parent
-(i.e. it is a minibuffer window or the root window of its frame).
+(i.e., it is a minibuffer window or the root window of its frame).
@end defun
Each internal window always has at least two child windows. If this
@defun window-full-height-p &optional window
This function returns non-@code{nil} if @var{window} has no other
-window above or below it in its frame, i.e. its total height equals
+window above or below it in its frame, i.e., its total height equals
the total height of the root window on that frame. If @var{window} is
omitted or @code{nil}, it defaults to the selected window.
@end defun
@defun window-full-width-p &optional window
This function returns non-@code{nil} if @var{window} has no other
-window to the left or right in its frame, i.e. its total width equals
+window to the left or right in its frame, i.e., its total width equals
that of the root window on that frame. If @var{window} is omitted or
@code{nil}, it defaults to the selected window.
@end defun
moves it as far as possible but does not signal a error.
This function tries to resize windows adjacent to the edge that is
-moved. If this is not possible for some reason (e.g. if that adjacent
+moved. If this is not possible for some reason (e.g., if that adjacent
window is fixed-size), it may resize other windows.
@end defun
This section describes functions for creating a new window by
@dfn{splitting} an existing one.
-@deffn Command split-window &optional window size side
+@defun split-window &optional window size side
This function creates a new live window next to the window
@var{window}. If @var{window} is omitted or @code{nil}, it defaults
to the selected window. That window is ``split'', and reduced in
lieu of the usual action of @code{split-window}. Otherwise, this
function obeys the @code{window-atom} or @code{window-side} window
parameter, if any. @xref{Window Parameters}.
-@end deffn
+@end defun
As an example, here is a sequence of @code{split-window} calls that
yields the window configuration discussed in @ref{Windows and Frames}.
This function removes @var{window} from display and returns
@code{nil}. If @var{window} is omitted or @code{nil}, it defaults to
the selected window. If deleting the window would leave no more
-windows in the window tree (e.g. if it is the only live window in the
+windows in the window tree (e.g., if it is the only live window in the
frame), an error is signaled.
By default, the space taken up by @var{window} is given to one of its
@end smallexample
@noindent
-This can be counterintutive, in particular if @var{W4} were used for
+This can be counterintuitive, in particular if @var{W4} were used for
displaying a buffer only temporarily (@pxref{Temporary Displays}), and
you want to continue working with the initial layout.
@cindex window combination limit
@defun set-window-combination-limit window limit
-This functions sets the @dfn{combination limit} of the window
+This function sets the @dfn{combination limit} of the window
@var{window} to @var{limit}. This value can be retrieved via the
function @code{window-combination-limit}. See below for its effects;
note that it is only meaningful for internal windows. The
@cindex selecting a window
@defun select-window window &optional norecord
-This function makes @var{window} the selected window, as well as the
-window selected within its frame (@pxref{Basic Windows}). @var{window}
-must be a live window. This function makes also @var{window}'s buffer
-current (@pxref{Buffers and Windows}). The return value is
+This function makes @var{window} the selected window and the window
+selected within its frame (@pxref{Basic Windows}) and selects that
+frame. @var{window} must be a live window. This function also makes
+@var{window}'s buffer (@pxref{Buffers and Windows}) current and sets
+that buffer's value of @code{point} to the value of @code{window-point}
+(@pxref{Window Point}) in @var{window}. The return value is
@var{window}.
By default, this function also moves @var{window}'s buffer to the front
@defun set-frame-selected-window frame window &optional norecord
This function makes @var{window} the window selected within the frame
-@var{frame}. @var{frame} should be a live frame; if omitted or
-@code{nil}, it defaults to the selected frame. @var{window} should be
-a live window; if omitted or @code{nil}, it defaults to the selected
-window.
+@var{frame}. @var{frame} should be a live frame; if @code{nil}, it
+defaults to the selected frame. @var{window} should be a live window;
+if @code{nil}, it defaults to the selected window.
If @var{frame} is the selected frame, this makes @var{window} the
selected window.
@noindent
Each action function is called in turn, passing the buffer as the
first argument and the combined action alist as the second argument,
-until one of the functions returns non-@code{nil}.
+until one of the functions returns non-@code{nil}. The caller can
+pass @code{(allow-no-window . t)} as an element of the action alist to
+indicate its readiness to handle the case of not displaying the
+buffer in a window.
The argument @var{action} can also have a non-@code{nil}, non-list
value. This has the special meaning that the buffer should be
@defvar display-buffer-overriding-action
The value of this variable should be a display action, which is
treated with the highest priority by @code{display-buffer}. The
-default value is empty, i.e. @code{(nil . nil)}.
+default value is empty, i.e., @code{(nil . nil)}.
@end defvar
@defopt display-buffer-alist
The value of this option is an alist mapping conditions to display
actions. Each condition may be either a regular expression matching a
-buffer name or a function that takes two arguments - a buffer name and
+buffer name or a function that takes two arguments: a buffer name and
the @var{action} argument passed to @code{display-buffer}. If the name
of the buffer passed to @code{display-buffer} either matches a regular
expression in this alist or the function specified by a condition
A frame means consider windows on that frame only.
@end itemize
+Note that these meanings differ slightly from those of the
+@var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window
+Ordering}).
+
If @var{alist} contains no @code{reusable-frames} entry, this function
normally searches just the selected frame; however, if the variable
@code{pop-up-frames} is non-@code{nil}, it searches all frames on the
@item
If the @sc{cdr} specifies a function, that function is called with one
-argument - the new window. The function is supposed to adjust the
+argument: the new window. The function is supposed to adjust the
height of the window; its return value is ignored. Suitable functions
are @code{shrink-window-if-larger-than-buffer} and
@code{fit-window-to-buffer}, see @ref{Resizing Windows}.
@item
If the @sc{cdr} specifies a function, that function is called with one
-argument - the new window. The function is supposed to adjust the width
+argument: the new window. The function is supposed to adjust the width
of the window; its return value is ignored.
@end itemize
This function can fail if no window splitting can be performed for some
-reason (e.g. if the selected frame has an @code{unsplittable} frame
+reason (e.g., if the selected frame has an @code{unsplittable} frame
parameter; @pxref{Buffer Parameters}).
@end defun
Each list element has the form @code{(@var{buffer} @var{window-start}
@var{window-pos})}, where @var{buffer} is a buffer previously shown in
-the window, @var{window-start} is the window start position when that
-buffer was last shown, and @var{window-pos} is the point position when
+the window, @var{window-start} is the window start position
+(@pxref{Window Start and End}) when that buffer was last shown, and
+@var{window-pos} is the point position (@pxref{Window Point}) when
that buffer was last shown in @var{window}.
The list is ordered so that earlier elements correspond to more
@defopt switch-to-visible-buffer
If this variable is non-@code{nil}, @code{switch-to-prev-buffer} and
@code{switch-to-next-buffer} may switch to a buffer that is already
-visible on the same frame, provided the buffer was shown in the relevant
-window before. If it is @code{nil}, @code{switch-to-prev-buffer} and
-@code{switch-to-next-buffer} always try to avoid switching to a buffer
-that is already visible in another window on the same frame.
+visible on the same frame, provided the buffer was shown in the
+relevant window before. If it is @code{nil},
+@code{switch-to-prev-buffer} and @code{switch-to-next-buffer} always
+try to avoid switching to a buffer that is already visible in another
+window on the same frame. The default is @code{t}.
@end defopt
@code{replace-buffer-in-windows} (@pxref{Buffers and Windows}) which is
called when a buffer gets killed, deletes the window in case (1) and
behaves like @code{delete-windows-on} otherwise.
+@c FIXME: Does replace-buffer-in-windows _delete_ a window in case (1)?
When @code{bury-buffer} (@pxref{The Buffer List}) operates on the
selected window (which shows the buffer that shall be buried), it
@code{switch-to-prev-buffer} (@pxref{Window History}) to show some other
buffer instead.
-The optional argument @var{bury-or-kill} specifes how to deal with
+The optional argument @var{bury-or-kill} specifies how to deal with
@var{window}'s buffer. The following values are handled:
@table @code
@node Window Start and End
@section The Window Start and End Positions
@cindex window start position
+@cindex display-start position
Each window maintains a marker used to keep track of a buffer position
that specifies where in the buffer display should start. This position
@end defun
@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 than the height
-of the window, for example in the presence of large images.
+If this variable is non-@code{nil}, the @code{line-move},
+@code{scroll-up}, and @code{scroll-down} functions will automatically
+modify the vertical scroll 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
@node Horizontal Scrolling
the horizontal scrolling of a window as necessary to ensure that point
is always visible. However, you can still set the horizontal
scrolling value explicitly. The value you specify serves as a lower
-bound for automatic scrolling, i.e. automatic scrolling will not
+bound for automatic scrolling, i.e., automatic scrolling will not
scroll a window to a column less than the specified one.
@deffn Command scroll-left &optional count set-minimum
Here is how you can determine whether a given position @var{position}
is off the screen due to horizontal scrolling:
+@c FIXME: Maybe hscroll-on-screen-p is a better name?
@example
@group
(defun hscroll-on-screen (window position)
Y coordinates increase rightward and downward respectively.
Except where noted, X and Y coordinates are reported in integer
-character units, i.e. numbers of lines and columns respectively. On a
+character units, i.e., numbers of lines and columns respectively. On a
graphical display, each ``line'' and ``column'' corresponds to the
height and width of a default character specified by the frame's
default font.
(@pxref{Choosing Window}) and consulted by @code{quit-restore-window}
(@pxref{Quitting Windows}). It contains four elements:
-The first element is one of the symbols @code{window} - meaning that the
-window has been specially created by @code{display-buffer}, @code{frame}
-- a separate frame has been created, @code{same} - the window has
-displayed the same buffer before, or @code{other} - the window showed
+The first element is one of the symbols @code{window}, meaning that the
+window has been specially created by @code{display-buffer}; @code{frame},
+a separate frame has been created; @code{same}, the window has
+displayed the same buffer before; or @code{other}, the window showed
another buffer before.
The second element is either one of the symbols @code{window} or