@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
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}.
@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.
@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
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
@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
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)
(@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
HCoop / bpt / emacs.git / blobdiff