@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-2013 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Windows
@chapter Windows
@section Basic Concepts of Emacs Windows
@cindex window
-A @dfn{window} is a area of the screen that is used to display a
-buffer (@pxref{Buffers}). In Emacs Lisp, windows are represented by a
-special Lisp object type.
+A @dfn{window} is an area of the screen that is used to display a buffer
+(@pxref{Buffers}). In Emacs Lisp, windows are represented by a special
+Lisp object type.
@cindex multiple windows
Windows are grouped into frames (@pxref{Frames}). Each frame
@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
@end smallexample
@noindent
-The root window of this frame is an internal window, @code{W1}. Its
+The root window of this frame is an internal window, @var{W1}. Its
child windows form a horizontal combination, consisting of the live
-window @code{W2} and the internal window @code{W3}. The child windows
-of @code{W3} form a vertical combination, consisting of the live
-windows @code{W4} and @code{W5}. Hence, the live windows in this
-window tree are @code{W2} @code{W4}, and @code{W5}.
+window @var{W2} and the internal window @var{W3}. The child windows
+of @var{W3} form a vertical combination, consisting of the live
+windows @var{W4} and @var{W5}. Hence, the live windows in this
+window tree are @var{W2} @var{W4}, and @var{W5}.
The following functions can be used to retrieve a child window of an
internal window, and the siblings of a child window.
and previous window, respectively, in the cyclic ordering of windows
(@pxref{Cyclic Window Ordering}).
- You can use the following functions to find the first live window on
-a frame, and to retrieve the entire window tree of a frame:
+ You can use the following functions to find the first live window on a
+frame and the window nearest to a given window.
@defun frame-first-window &optional frame-or-window
This function returns the live window at the upper left corner of the
to the selected frame. If @var{frame-or-window} specifies a window,
this function returns the first window on that window's frame. Under
the assumption that the frame from our canonical example is selected
-@code{(frame-first-window)} returns @code{W2}.
+@code{(frame-first-window)} returns @var{W2}.
@end defun
+@cindex window in direction
+@defun window-in-direction direction &optional window ignore
+This function returns the nearest live window in direction
+@var{direction} as seen from the position of @code{window-point} in
+window @var{window}. The argument @var{direction} must be one of
+@code{above}, @code{below}, @code{left} or @code{right}. The optional
+argument @var{window} must denote a live window and defaults to the
+selected one.
+
+This function does not return a window whose @code{no-other-window}
+parameter is non-@code{nil} (@pxref{Window Parameters}). If the nearest
+window's @code{no-other-window} parameter is non-@code{nil}, this
+function tries to find another window in the indicated direction whose
+@code{no-other-window} parameter is @code{nil}. If the optional
+argument @var{ignore} is non-@code{nil}, a window may be returned even
+if its @code{no-other-window} parameter is non-@code{nil}.
+
+If it doesn't find a suitable window, this function returns @code{nil}.
+@end defun
+
+The following function allows to retrieve the entire window tree of a
+frame:
+
@defun window-tree &optional frame
This function returns a list representing the window tree for frame
@var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to
@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
@node Recombining Windows
@section Recombining Windows
-When deleting the last sibling of a window @code{W}, its parent window
-is deleted too, with @code{W} replacing it in the window tree. This
-means that @code{W} must be recombined with its parent's siblings to
+When deleting the last sibling of a window @var{W}, its parent window
+is deleted too, with @var{W} replacing it in the window tree. This
+means that @var{W} must be recombined with its parent's siblings to
form a new window combination (@pxref{Windows and Frames}). In some
occasions, deleting a live window may even entail the deletion of two
internal windows.
@end smallexample
@noindent
-Deleting @code{W5} in this configuration normally causes the deletion of
-@code{W3} and @code{W4}. The remaining live windows @code{W2},
-@code{W6} and @code{W7} are recombined to form a new horizontal
-combination with parent @code{W1}.
+Deleting @var{W5} in this configuration normally causes the deletion of
+@var{W3} and @var{W4}. The remaining live windows @var{W2},
+@var{W6} and @var{W7} are recombined to form a new horizontal
+combination with parent @var{W1}.
Sometimes, however, it makes sense to not delete a parent window like
-@code{W4}. In particular, a parent window should not be removed when it
+@var{W4}. In particular, a parent window should not be removed when it
was used to preserve a combination embedded in a combination of the same
type. Such embeddings make sense to assure that when you split a window
and subsequently delete the new window, Emacs reestablishes the layout
of the associated frame as it existed before the splitting.
- Consider a scenario starting with two live windows @code{W2} and
-@code{W3} and their parent @code{W1}.
+ Consider a scenario starting with two live windows @var{W2} and
+@var{W3} and their parent @var{W1}.
@smallexample
@group
@end smallexample
@noindent
-Split @code{W2} to make a new window @code{W4} as follows.
+Split @var{W2} to make a new window @var{W4} as follows.
@smallexample
@group
@noindent
Now, when enlarging a window vertically, Emacs tries to obtain the
corresponding space from its lower sibling, provided such a window
-exists. In our scenario, enlarging @code{W4} will steal space from
-@code{W3}.
+exists. In our scenario, enlarging @var{W4} will steal space from
+@var{W3}.
@smallexample
@group
@end smallexample
@noindent
-Deleting @code{W4} will now give its entire space to @code{W2},
-including the space earlier stolen from @code{W3}.
+Deleting @var{W4} will now give its entire space to @var{W2},
+including the space earlier stolen from @var{W3}.
@smallexample
@group
@end smallexample
@noindent
-This can be counterintuitive, in particular if @code{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.
The behavior can be fixed by making a new parent window when splitting
-@code{W2}. The variable described next allows to do that.
+@var{W2}. The variable described next allows to do that.
@defopt window-combination-limit
This variable controls whether splitting a window shall make a new
the child windows are deleted (see below).
@end defopt
- If @code{window-combination-limit} is @code{t}, splitting @code{W2} in
+ If @code{window-combination-limit} is @code{t}, splitting @var{W2} in
the initial configuration of our scenario would have produced this:
@smallexample
@end smallexample
@noindent
-A new internal window @code{W5} has been created; its children are
-@code{W2} and the new live window @code{W4}. Now, @code{W2} is the only
-sibling of @code{W4}, so enlarging @code{W4} will try to shrink
-@code{W2}, leaving @code{W3} unaffected. Observe that @code{W5}
+A new internal window @var{W5} has been created; its children are
+@var{W2} and the new live window @var{W4}. Now, @var{W2} is the only
+sibling of @var{W4}, so enlarging @var{W4} will try to shrink
+@var{W2}, leaving @var{W3} unaffected. Observe that @var{W5}
represents a vertical combination of two windows embedded in the
-vertical combination @code{W1}.
+vertical combination @var{W1}.
@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
siblings.
If, in the configuration shown at the beginning of this section, the
-combination limit of @code{W4} (the parent window of @code{W6} and
-@code{W7}) is @code{t}, deleting @code{W5} will not implicitly delete
-@code{W4} too.
+combination limit of @var{W4} (the parent window of @var{W6} and
+@var{W7}) is @code{t}, deleting @var{W5} will not implicitly delete
+@var{W4} too.
@end defun
Alternatively, the problems sketched above can be avoided by always
@noindent
If @code{window-combination-resize} is @code{nil}, splitting window
-@code{W3} leaves the size of @code{W2} unchanged:
+@var{W3} leaves the size of @var{W2} unchanged:
@smallexample
@group
@end smallexample
@noindent
-If @code{window-combination-resize} is @code{t}, splitting @code{W3}
+If @code{window-combination-resize} is @code{t}, splitting @var{W3}
instead leaves all three live windows with approximately the same
height:
@end smallexample
@noindent
-Deleting any of the live windows @code{W2}, @code{W3} or @code{W4} will
+Deleting any of the live windows @var{W2}, @var{W3} or @var{W4} will
distribute its space proportionally among the two remaining live
windows.
@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.
@code{next-window}.
@end defun
-@cindex window in direction
-@defun window-in-direction direction &optional window ignore
-This function returns the nearest window in direction @var{direction} as
-seen from the position of @code{window-point} in window @var{window}.
-The argument @var{direction} must be one of @code{above}, @code{below},
-@code{left} or @code{right}. The optional argument @var{window} must
-denote a live window and defaults to the selected one.
-
-This function does not return a window whose @code{no-other-window}
-parameter is non-@code{nil}. If the nearest window's
-@code{no-other-window} parameter is non-@code{nil}, this function tries
-to find another window in the indicated direction whose
-@code{no-other-window} parameter is @code{nil}. If the optional
-argument @var{ignore} is non-@code{nil}, a window may be returned even
-if its @code{no-other-window} parameter is non-@code{nil}.
-
-If it doesn't find a suitable window, this function returns @code{nil}.
-@end defun
-
@node Buffers and Windows
@section Buffers and Windows
@deffn Command replace-buffer-in-windows &optional buffer-or-name
This command replaces @var{buffer-or-name} with some other buffer, in
-all windows displaying it. @var{buffer-or-name} should be a buffer,
-or the name of an existing buffer; if omitted or @code{nil}, it
-defaults to the current buffer.
+all windows displaying it. @var{buffer-or-name} should be a buffer, or
+the name of an existing buffer; if omitted or @code{nil}, it defaults to
+the current buffer.
The replacement buffer in each window is chosen via
@code{switch-to-prev-buffer} (@pxref{Window History}). Any dedicated
-window displaying @var{buffer-or-name} is deleted (@pxref{Dedicated
-Windows}), unless it is the only window on its frame---if it is the
-only window, and that frame is not the only frame on its terminal, the
-frame is ``dismissed'' by calling the function specified by
-@code{frame-auto-hide-function} (@pxref{Quitting Windows}). If the
-dedicated window is the only window on the only frame on its terminal,
-the buffer is replaced anyway.
+window displaying @var{buffer-or-name} is deleted if possible
+(@pxref{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.
@end deffn
+
@node Switching Buffers
@section Switching to a Buffer in a Window
@cindex switching to a buffer
@cindex displaying a buffer
- This section describes high-level functions for switching to a
-specified buffer in some window.
+This section describes high-level functions for switching to a specified
+buffer in some window. In general, ``switching to a buffer'' means to
+(1) show the buffer in some window, (2) make that window the selected
+window (and its frame the selected frame), and (3) make the buffer the
+current buffer.
Do @emph{not} use these functions to make a buffer temporarily
current just so a Lisp program can access or modify it. They have
@deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window
This command attempts to display @var{buffer-or-name} in the selected
-window, and makes it the current buffer. It is often used
-interactively (as the binding of @kbd{C-x b}), as well as in Lisp
-programs. The return value is the buffer switched to.
+window and make it the current buffer. It is often used interactively
+(as the binding of @kbd{C-x b}), as well as in Lisp programs. The
+return value is the buffer switched to.
If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
returned by @code{other-buffer} (@pxref{The Buffer List}). If
instead.
@end deffn
-By default, @code{switch-to-buffer} sets @code{window-point} of the
-window used to the buffer's position of @code{point}. This behavior can
-be tuned using the following option.
+By default, @code{switch-to-buffer} shows the buffer at its position of
+@code{point}. This behavior can be tuned using the following option.
@defopt switch-to-buffer-preserve-window-point
If this variable is @code{nil}, @code{switch-to-buffer} displays the
buffer.
@end defopt
-The next two functions are similar to @code{switch-to-buffer}, except
-for the described features.
+The next two commands are similar to @code{switch-to-buffer}, except for
+the described features.
@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
-This function makes the buffer specified by @var{buffer-or-name}
-current and displays it in some window other than the selected window.
-It uses the function @code{pop-to-buffer} internally (see below).
+This function displays the buffer specified by @var{buffer-or-name} in
+some window other than the selected window. It uses the function
+@code{pop-to-buffer} internally (see below).
If the selected window already displays the specified buffer, it
continues to do so, but another window is nonetheless found to display
@end deffn
@deffn Command switch-to-buffer-other-frame buffer-or-name &optional norecord
-This function makes the buffer specified by @var{buffer-or-name}
-current and displays it, usually in a new frame. It uses the function
-@code{pop-to-buffer} (see below).
+This function displays the buffer specified by @var{buffer-or-name} in a
+new frame. It uses the function @code{pop-to-buffer} internally (see
+below).
If the specified buffer is already displayed in another window, in any
frame on the current terminal, this switches to that window instead of
@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 there is just one frame and it has an
-@code{unsplittable} frame parameter; @pxref{Buffer Parameters}).
+reason (e.g., if the selected frame has an @code{unsplittable} frame
+parameter; @pxref{Buffer Parameters}).
@end defun
@defun display-buffer-below-selected buffer alist
@noindent
Evaluating the form above will cause @code{display-buffer} to proceed as
-follows: If `*foo*' already appears on a visible or iconified frame, it
-will reuse its window. Otherwise, it will try to pop up a new window
-or, if that is impossible, a new frame. If all these steps fail, it
-will proceed using whatever @code{display-buffer-base-action} and
+follows: If a buffer called *foo* already appears on a visible or
+iconified frame, it will reuse its window. Otherwise, it will try to
+pop up a new window or, if that is impossible, a new frame and show the
+buffer there. If all these steps fail, it will proceed using whatever
+@code{display-buffer-base-action} and
@code{display-buffer-fallback-action} prescribe.
Furthermore, @code{display-buffer} will try to adjust a reused window
-(provided `*foo*' was put by @code{display-buffer} there before) or a
+(provided *foo* was put by @code{display-buffer} there before) or a
popped-up window as follows: If the window is part of a vertical
combination, it will set its height to ten lines. Note that if, instead
of the number ``10'', we specified the function
@end example
@noindent
-Evaluating this form will cause @code{display-buffer} to first try
-reusing a window showing @code{*foo*} on the selected frame.
-If no such window exists, it will try to split the selected window or,
-if that is impossible, use the window below the selected window.
+This form will have @code{display-buffer} first try reusing a window
+that shows *foo* on the selected frame. If there's no such window, it
+will try to split the selected window or, if that is impossible, use the
+window below the selected window.
If there's no window below the selected one, or the window below the
selected one is dedicated to its buffer, @code{display-buffer} will
the window (@pxref{Display Action Functions}).
The default value is @code{split-window-sensibly}, which is documented
-below. The value must be a function that takes one argument, a
-window, and return either a new window (which is used to display the
+below. The value must be a function that takes one argument, a window,
+and return either a new window (which will be used to display the
desired buffer) or @code{nil} (which means the splitting failed).
@end defopt
@defopt same-window-buffer-names
A list of buffer names for buffers that should be displayed in the
selected window. If a buffer's name is in this list,
-@code{display-buffer} handles the buffer by switching to it in the
-selected window.
+@code{display-buffer} handles the buffer by showing it in the selected
+window.
@end defopt
@defopt 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, @code{display-buffer} handles the
-buffer by switching to it in the selected window.
+buffer by showing it in the selected window.
@end defopt
@defun same-window-p buffer-name
@section Window History
@cindex window history
-Each window remembers the buffers it has previously displayed, and the order
-in which these buffers were removed from it. This history is used,
-for example, by @code{replace-buffer-in-windows} (@pxref{Buffers and
-Windows}). This list is automatically maintained by Emacs, but you can
-use the following functions to explicitly inspect or alter it:
+Each window remembers in a list the buffers it has previously displayed,
+and the order in which these buffers were removed from it. This history
+is used, for example, by @code{replace-buffer-in-windows}
+(@pxref{Buffers and Windows}). The list is automatically maintained by
+Emacs, but you can use the following functions to explicitly inspect or
+alter it:
@defun window-prev-buffers &optional window
This function returns a list specifying the previous contents of
-@var{window}, which should be a live window and defaults to the
-selected window.
+@var{window}. The optional argument @var{window} should be a live
+window and defaults to the selected one.
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
-that buffer was last shown.
+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
recently-shown buffers, and the first element usually corresponds to the
@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
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 windows as candidates when their @var{dedicated} argument is
-non-@code{nil}. The behavior of @code{set-window-buffer}
+@code{get-largest-window} (@pxref{Cyclic Window Ordering}) do not
+consider dedicated windows as candidates when their @var{dedicated}
+argument is non-@code{nil}. The behavior of @code{set-window-buffer}
(@pxref{Buffers and Windows}) with respect to dedicated windows is
slightly different, see below.
-When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to
-delete a dedicated window and that window is the only window on its
-frame, it deletes the window's frame too, provided there are other
-frames left. @code{replace-buffer-in-windows} (@pxref{Switching
-Buffers}) tries to delete all dedicated windows showing its buffer
-argument. When such a window is the only window on its frame, that
-frame is deleted, provided there are other frames left. If there are
-no more frames left, some other buffer is displayed in the window, and
-the window is marked as non-dedicated.
-
-When you kill a buffer (@pxref{Killing Buffers}) displayed in a
-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 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.
+ Functions supposed to remove a buffer from a window or a window from
+a frame can behave specially when a window they operate on is dedicated.
+We will distinguish three basic cases, namely where (1) the window is
+not the only window on its frame, (2) the window is the only window on
+its frame but there are other frames on the same terminal left, and (3)
+the window is the only window on the only frame on the same terminal.
+
+ In particular, @code{delete-windows-on} (@pxref{Deleting Windows})
+handles case (2) by deleting the associated frame and case (3) by
+showing another buffer in that frame's only window. The function
+@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
+handles case (2) by calling @code{frame-auto-hide-function}
+(@pxref{Quitting Windows}) to deal with the selected frame. The other
+two cases are handled as with @code{replace-buffer-in-windows}.
@defun window-dedicated-p &optional window
This function returns non-@code{nil} if @var{window} is dedicated to its
@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