Reformulate description of windows basics. Describe changes in window ordering.

* windows.texi (Basic Windows): Reformulate description of live,
internal and valid windows.
(Cyclic Window Ordering): Describe new argument of
get-lru-window and get-largest-window.  Add description of
window-in-direction.

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index aea2624..fe12e27 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,11 @@
+2012-10-28  Martin Rudalics  <rudalics@gmx.at>
+
+       * windows.texi (Basic Windows): Reformulate description of live,
+       internal and valid windows.
+       (Cyclic Window Ordering): Describe new argument of
+       get-lru-window and get-largest-window.  Add description of
+       window-in-direction.
+
 2012-10-27  Glenn Morris  <rgm@gnu.org>
 
        * variables.texi (Generalized Variables): New section,

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 31d33bf..d0e149e 100644 (file)
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -76,30 +76,35 @@ within the area of the frame.  When a window is created, resized, or
 deleted, the change in window space is taken from or given to the
 adjacent windows, so that the total area of the frame is unchanged.
 
-@cindex live windows
-@cindex internal windows
-  A @dfn{live window} is one that is actually displaying a buffer in a
-frame.  Such a window can be @dfn{deleted}, i.e. removed from the
-frame (@pxref{Deleting Windows}); then it is no longer live, but the
-Lisp object representing it might be still referenced from other Lisp
-objects.  A deleted window may be brought back to life by restoring a
-saved window configuration (@pxref{Window Configurations}).
-
 @defun windowp object
 This function returns @code{t} if @var{object} is a window (whether or
-not it is live).  Otherwise, it returns @code{nil}.
+not it displays a buffer).  Otherwise, it returns @code{nil}.
 @end defun
 
+@cindex live windows
+A @dfn{live window} is one that is actually displaying a buffer in a
+frame.
+
 @defun window-live-p object
 This function returns @code{t} if @var{object} is a live window and
 @code{nil} otherwise.  A live window is one that displays a buffer.
 @end defun
 
-  The windows in each frame are organized into a @dfn{window tree}.
-@xref{Windows and Frames}.  The leaf nodes of each window tree are
-live windows---the ones actually displaying buffers.  The internal
-nodes of the window tree are internal windows, which are not live.
-You can distinguish internal windows from deleted windows with
+@cindex internal windows
+The windows in each frame are organized into a @dfn{window tree}.
+@xref{Windows and Frames}.  The leaf nodes of each window tree are live
+windows---the ones actually displaying buffers.  The internal nodes of
+the window tree are @dfn{internal windows}, which are not live.
+
+@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
+(@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
+window configuration (@pxref{Window Configurations}).
+
+   You can distinguish valid windows from deleted windows with
 @code{window-valid-p}.
 
 @defun window-valid-p object
@@ -1317,31 +1322,37 @@ meaning as for @code{next-window}.
 criterion, without selecting it:
 
 @cindex least recently used window
-@defun get-lru-window &optional all-frames dedicated
+@defun get-lru-window &optional all-frames dedicated not-selected
 This function returns a live window which is heuristically the ``least
 recently used'' window.  The optional argument @var{all-frames} has
 the same meaning as in @code{next-window}.
 
 If any full-width windows are present, only those windows are
-considered.  The selected window is never returned, unless 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}.
+considered.  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 selected
+window is never returned, unless it is the only candidate.  However, if
+the optional argument @var{not-selected} is non-@code{nil}, this
+function returns @code{nil} in that case.
 @end defun
 
 @cindex largest window
-@defun get-largest-window &optional all-frames dedicated
+@defun get-largest-window &optional all-frames dedicated not-selected
 This function returns the window with the largest area (height times
-width).  A minibuffer window is never a candidate.  A dedicated window
+width).  The optional argument @var{all-frames} specifies the windows to
+search, and has the same meaning as in @code{next-window}.
+
+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}.
+argument @var{dedicated} is non-@code{nil}.  The selected window is not
+a candidate if the optional argument @var{not-selected} is
+non-@code{nil}.  If the optional argument @var{not-selected} is
+non-@code{nil} and the selected window is the only candidate, this
+function returns @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,
 starting from the selected window.
-
-The optional argument @var{all-frames} specifies the windows to
-search, and has the same meaning as in @code{next-window}.
 @end defun
 
 @cindex window that satisfies a predicate
@@ -1359,6 +1370,26 @@ windows to search, and have the same meanings as in
 @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
 @cindex examining windows