diff options
Diffstat (limited to 'doc/lispref/windows.texi')
| -rw-r--r-- | doc/lispref/windows.texi | 91 |
1 files changed, 34 insertions, 57 deletions
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index c7c466c7d36..5fe007ba02d 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -1129,16 +1129,15 @@ are the opposite of what they are in those other functions. @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. Unless @var{window} already is the -selected window, its buffer becomes the current buffer (@pxref{Buffers -and Windows}). The return value is @var{window}. +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 +@var{window}. -By default, this function also moves @var{window}'s selected buffer to -the front of the buffer list (@pxref{The Buffer List}), and makes -@var{window} the most recently selected window. However, if the -optional argument @var{norecord} is non-@code{nil}, these additional -actions are omitted. +By default, this function also moves @var{window}'s buffer to the front +of the buffer list (@pxref{The Buffer List}), and makes @var{window} the +most recently selected window. However, if the optional argument +@var{norecord} is non-@code{nil}, these additional actions are omitted. @end defun @cindex most recently selected windows @@ -2276,19 +2275,18 @@ For a nonselected window, this is the value point would have (in that window's buffer) if that window were selected. The default for @var{window} is the selected window. -When @var{window} is the selected window and its buffer is also the -current buffer, the value returned is the same as point in that buffer. -Strictly speaking, it would be more correct to return the ``top-level'' -value of point, outside of any @code{save-excursion} forms. But that -value is hard to find. +When @var{window} is the selected window, the value returned is the +value of point in that window's buffer. Strictly speaking, it would be +more correct to return the ``top-level'' value of point, outside of any +@code{save-excursion} forms. But that value is hard to find. @end defun @defun set-window-point window position This function positions point in @var{window} at position @var{position} in @var{window}'s buffer. It returns @var{position}. -If @var{window} is selected, and its buffer is current, -this simply does @code{goto-char}. +If @var{window} is selected, this simply does @code{goto-char} in +@var{window}'s buffer. @end defun @defvar window-point-insertion-type @@ -3155,42 +3153,21 @@ as @code{save-window-excursion}: @end defun @defmac save-window-excursion forms@dots{} -This special form records the window configuration, executes @var{forms} -in sequence, then restores the earlier window configuration. The window -configuration includes, for each window, the value of point and the -portion of the buffer that is visible. It also includes the choice of -selected window. However, it does not include the value of point in -the current buffer; use @code{save-excursion} also, if you wish to -preserve that. - -Don't use this construct when @code{save-selected-window} is sufficient. - -Exit from @code{save-window-excursion} always triggers execution of -@code{window-size-change-functions}. (It doesn't know how to tell -whether the restored configuration actually differs from the one in -effect at the end of the @var{forms}.) - -The return value is the value of the final form in @var{forms}. -For example: - -@example -@group -(split-window) - @result{} #<window 25 on control.texi> -@end group -@group -(setq w (selected-window)) - @result{} #<window 19 on control.texi> -@end group -@group -(save-window-excursion - (delete-other-windows w) - (switch-to-buffer "foo") - 'do-something) - @result{} do-something - ;; @r{The screen is now split again.} -@end group -@end example +This macro records the window configuration of the selected frame, +executes @var{forms} in sequence, then restores the earlier window +configuration. The return value is the value of the final form in +@var{forms}. + +Most Lisp code should not use this macro; @code{save-selected-window} +is typically sufficient. In particular, this macro cannot reliably +prevent the code in @var{forms} from opening new windows, because new +windows might be opened in other frames (@pxref{Choosing Window}), and +@code{save-window-excursion} only saves and restores the window +configuration on the current frame. + +Do not use this macro in @code{window-size-change-functions}; exiting +the macro triggers execution of @code{window-size-change-functions}, +leading to an endless loop. @end defmac @defun window-configuration-p object @@ -3426,11 +3403,11 @@ Creating or deleting windows counts as a size change, and therefore causes these functions to be called. Changing the frame size also counts, because it changes the sizes of the existing windows. -It is not a good idea to use @code{save-window-excursion} (@pxref{Window -Configurations}) in these functions, because that always counts as a -size change, and it would cause these functions to be called over and -over. In most cases, @code{save-selected-window} (@pxref{Selecting -Windows}) is what you need here. +You may use @code{save-selected-window} in these functions +(@pxref{Selecting Windows}). However, do not use +@code{save-window-excursion} (@pxref{Window Configurations}); exiting +that macro counts as a size change, which would cause these functions +to be called over and over. @end defvar @defvar window-configuration-change-hook |