X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/727f97393714c5c92aef793f0749ebfde1d14f3c..39eb0cb563f5287270f3946804456dc766386638:/doc/lispref/windows.texi diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 7a705353a1..13c9ca5322 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -1,7 +1,7 @@ @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 @@ -717,7 +717,7 @@ window. 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 @@ -767,7 +767,7 @@ called with the arguments @var{window}, @var{size}, and @var{side}, 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}. @@ -1296,10 +1296,12 @@ 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 @@ -1353,10 +1355,9 @@ within that frame. @var{frame} should be a live frame; if omitted or @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. @@ -1865,7 +1866,7 @@ default value is empty, i.e., @code{(nil . nil)}. @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 @@ -1923,6 +1924,10 @@ frames to search for a reusable window: 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 @@ -1966,7 +1971,7 @@ height of the frame's root window. @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}. @@ -1987,7 +1992,7 @@ width of the frame's root window. @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 @@ -2239,8 +2244,9 @@ 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 +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 @@ -2323,10 +2329,11 @@ same frame. The following option can be used to override this behavior. @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 @@ -2357,6 +2364,7 @@ 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 @@ -2561,6 +2569,7 @@ so @code{window-point} will stay behind text inserted there. @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 @@ -3052,10 +3061,11 @@ pixels. In this case, the return value is @var{lines}. @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 @@ -3185,6 +3195,7 @@ The value returned is @var{columns}. 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) @@ -3616,10 +3627,10 @@ This parameter is installed by the buffer display functions (@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