From 3a51f0eb4168885b869641e9d5c98e3f40e5a515 Mon Sep 17 00:00:00 2001 From: Martin Rudalics Date: Sun, 28 Oct 2012 13:56:15 +0100 Subject: [PATCH] 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. --- doc/lispref/ChangeLog | 8 ++++ doc/lispref/windows.texi | 83 +++++++++++++++++++++++++++------------- 2 files changed, 65 insertions(+), 26 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index aea26248452..fe12e27a070 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,11 @@ +2012-10-28 Martin Rudalics + + * 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 * variables.texi (Generalized Variables): New section, diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 31d33bffbdd..d0e149eb165 100644 --- 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 -- 2.39.2