diff lispref/windows.texi @ 21007:66d807bdc5b4

*** empty log message ***

--- a/lispref/windows.texi	Sat Feb 28 01:49:58 1998 +0000
+++ b/lispref/windows.texi	Sat Feb 28 01:53:53 1998 +0000
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/windows
 @node Windows, Frames, Buffers, Top
@@ -24,12 +24,14 @@
 * Window Start::            The display-start position controls which text
                               is on-screen in the window.
 * Vertical Scrolling::      Moving text up and down in the window.
-* Scrolling Hooks::         Hooks that run when you scroll a window.
 * Horizontal Scrolling::    Moving text sideways on the window.
 * Size of Window::          Accessing the size of a window.
 * Resizing Windows::        Changing the size of a window.
 * Coordinates and Windows:: Converting coordinates to windows.
 * Window Configurations::   Saving and restoring the state of the screen.
+* Window Hooks::            Hooks for scrolling, window size changes,
+                              redisplay going past a certain point,
+                              or window configuration changes.
 @end menu
 
 @node Basic Windows
@@ -49,7 +51,7 @@
 
   In each frame, at any time, one and only one window is designated as
 @dfn{selected within the frame}.  The frame's cursor appears in that
-window.  At ant time, one frame is the selected frame; and the window
+window.  At any time, one frame is the selected frame; and the window
 selected within that frame is @dfn{the selected window}.  The selected
 window's buffer is usually the current buffer (except when
 @code{set-buffer} has been used).  @xref{Current Buffer}.
@@ -114,16 +116,16 @@
 @cindex tiled windows
   Most window systems support arbitrarily located overlapping windows.
 In contrast, Emacs windows are @dfn{tiled}; they never overlap, and
-together they fill the whole screen or frame.  Because of the way
-in which Emacs creates new windows and resizes them, you can't create
-every conceivable tiling of windows on an Emacs frame.  @xref{Splitting
-Windows}, and @ref{Size of Window}.
+together they fill the whole screen or frame.  Because of the way in
+which Emacs creates new windows and resizes them, not all conceivable
+tilings of windows on an Emacs frame are actually possible.
+@xref{Splitting Windows}, and @ref{Size of Window}.
 
   @xref{Display}, for information on how the contents of the
 window's buffer are displayed in the window.
 
 @defun windowp object
-  This function returns @code{t} if @var{object} is a window.
+This function returns @code{t} if @var{object} is a window.
 @end defun
 
 @node Splitting Windows
@@ -721,7 +723,7 @@
 always returns @code{nil}.
 @end deffn
 
-@deffn Command switch-to-buffer-other-window buffer-or-name
+@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
 This function makes @var{buffer-or-name} the current buffer and
 displays it in a window not currently selected.  It then selects that
 window.  The handling of the buffer is the same as in
@@ -732,9 +734,12 @@
 this purpose.  If the selected window is already displaying the buffer,
 then it continues to do so, but another window is nonetheless found to
 display it in as well.
+
+This function updates the buffer list just like @code{switch-to-buffer}
+unless @var{norecord} is non-@code{nil}.
 @end deffn
 
-@defun pop-to-buffer buffer-or-name &optional other-window
+@defun pop-to-buffer buffer-or-name &optional other-window norecord
 This function makes @var{buffer-or-name} the current buffer and
 switches to it in some window, preferably not the window previously
 selected.  The ``popped-to'' window becomes the selected window within
@@ -770,6 +775,9 @@
 buffer, a buffer by that name is created.  The major mode for the new
 buffer is set according to the variable @code{default-major-mode}.
 @xref{Auto Major Mode}.
+
+This function updates the buffer list just like @code{switch-to-buffer}
+unless @var{norecord} is non-@code{nil}.
 @end defun
 
 @deffn Command replace-buffer-in-windows buffer
@@ -782,6 +790,14 @@
 This function returns @code{nil}.
 @end deffn
 
+@tindex buffer-display-count
+@defvar buffer-display-count
+This variable is always local in each buffer.  When the buffer is
+created, @code{buffer-display-count} has value 0.  Each time the buffer
+is displayed in a window, that increments the value of
+@code{buffer-display-count}.
+@end defvar
+
 @node Choosing Window
 @section Choosing a Window for Display
 
@@ -790,7 +806,7 @@
 functions and commands use this subroutine.  Here we describe how to use
 @code{display-buffer} and how to customize it.
 
-@deffn Command display-buffer buffer-or-name &optional not-this-window
+@deffn Command display-buffer buffer-or-name &optional not-this-window frame
 This command makes @var{buffer-or-name} appear in some window, like
 @code{pop-to-buffer}, but it does not select that window and does not
 make the buffer current.  The identity of the selected window is
@@ -806,6 +822,13 @@
 @code{display-buffer} returns the window chosen to display
 @var{buffer-or-name}.
 
+If the argument @var{frame} is non-@code{nil}, it specifies which frames
+to check when deciding whether the buffer is already displayed.  Its
+value means the same thing as in functions @code{get-buffer-window}
+(@pxref{Buffers and Windows}).  If the buffer is already displayed
+in some window on one of these frames, @code{display-buffer} simply
+returns that window.
+
 Precisely how @code{display-buffer} finds or creates a window depends on
 the variables described below.
 @end deffn
@@ -972,12 +995,12 @@
 window opened on the buffer if such a window exists.
 
 @item
-Selecting a window sets the value of point in its buffer to the window's
-value of point.  Conversely, deselecting a window sets the window's
-value of point from that of the buffer.  Thus, when you switch between
-windows that display a given buffer, the point value for the selected
-window is in effect in the buffer, while the point values for the other
-windows are stored in those windows.
+Selecting a window sets the value of point in its buffer from the
+window's value of point.  Conversely, deselecting a window sets the
+window's value of point from that of the buffer.  Thus, when you switch
+between windows that display a given buffer, the point value for the
+selected window is in effect in the buffer, while the point values for
+the other windows are stored in those windows.
 
 @item
 As long as the selected window displays the current buffer, the window's
@@ -1293,57 +1316,6 @@
 @end example
 @end deffn
 
-@node Scrolling Hooks
-@section Hooks for Vertical Scrolling
-
-This section describes how a Lisp program can take action whenever a
-window displays a different part of its buffer or a different buffer.
-There are three actions that can change this: scrolling the window,
-switching buffers in the window, and changing the size of the window.
-The first two actions run @code{window-scroll-functions}; the last runs
-@code{window-size-change-functions}.  The paradigmatic use of these
-hooks is Lazy Lock mode; see @ref{Support Modes, Lazy Lock, Font Lock
-Support Modes, emacs, The GNU Emacs Manual}.
-
-@defvar window-scroll-functions
-This variable holds a list of functions that Emacs should call before
-redisplaying a window with scrolling.  It is not a normal hook, because
-each function is called with two arguments: the window, and its new
-display-start position.
-
-Displaying a different buffer in the window also runs these functions.
-
-These functions cannot expect @code{window-end} (@pxref{Window Start})
-to return a meaningful value, because that value is updated only by
-redisplaying the buffer.  So if one of these functions needs to know the
-last character that will fit in the window with its current
-display-start position, it has to find that character using
-@code{vertical-motion} (@pxref{Screen Lines}).
-@end defvar
-
-@defvar window-size-change-functions
-This variable holds a list of functions to be called if the size of any
-window changes for any reason.  The functions are called just once per
-redisplay, and just once for each frame on which size changes have
-occurred.
-
-Each function receives the frame as its sole argument.  There is no
-direct way to find out which windows on that frame have changed size, or
-precisely how.  However, if a size-change function records, at each
-call, the existing windows and their sizes, it can also compare the
-present sizes and the previous sizes.
-
-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.
-@end defvar
-
 @node Horizontal Scrolling
 @section Horizontal Scrolling
 @cindex horizontal scrolling
@@ -1414,7 +1386,7 @@
 
 @defun set-window-hscroll window columns
 This function sets the number of columns from the left margin that
-@var{window} is scrolled to the value of @var{columns}.  The argument
+@var{window} is scrolled from the value of @var{columns}.  The argument
 @var{columns} should be zero or positive; if not, it is taken as zero.
 
 The value returned is @var{columns}.
@@ -1693,9 +1665,9 @@
 The coordinates @var{x} and @var{y} are measured in characters, and
 count from the top left corner of the screen or frame.
 
-The value of @code{coordinates-in-window-p} is non-@code{nil} if the
-coordinates are inside @var{window}.  The value also indicates what part
-of the window the position is in, as follows:
+The value returned by @code{coordinates-in-window-p} is non-@code{nil}
+if the coordinates are inside @var{window}.  The value also indicates
+what part of the window the position is in, as follows:
 
 @table @code
 @item (@var{relx} . @var{rely})
@@ -1726,7 +1698,7 @@
 @cindex window configurations
 @cindex saving window information
 
-  A @dfn{window configuration} records the entire layout of a
+  A @dfn{window configuration} records the entire layout of one
 frame---all windows, their sizes, which buffers they contain, what part
 of each buffer is displayed, and the values of point and the mark.  You
 can bring back an entire previous layout by restoring a window
@@ -1737,19 +1709,21 @@
 Configurations}.
 
 @defun current-window-configuration
-This function returns a new object representing Emacs's current window
-configuration, namely the number of windows, their sizes and current
-buffers, which window is the selected window, and for each window the
-displayed buffer, the display-start position, and the positions of point
-and the mark.  An exception is made for point in the current buffer,
-whose value is not saved.
+This function returns a new object representing the selected frame's
+current window configuration, including the number of windows, their
+sizes and current buffers, which window is the selected window, and for
+each window the displayed buffer, the display-start position, and the
+positions of point and the mark.  An exception is made for point in the
+current buffer, whose value is not saved.
 @end defun
 
 @defun set-window-configuration configuration
-This function restores the configuration of Emacs's windows and
-buffers to the state specified by @var{configuration}.  The argument
-@var{configuration} must be a value that was previously returned by
-@code{current-window-configuration}.
+This function restores the configuration of windows and buffers as
+specified by @var{configuration}.  The argument @var{configuration} must
+be a value that was previously returned by
+@code{current-window-configuration}.  This function operates on the
+frame for which @var{configuration} was made, whether that frame is
+selected or not.
 
 This function always counts as a window size change and triggers
 execution of the @code{window-size-change-functions}.  (It doesn't know
@@ -1776,7 +1750,7 @@
 configuration includes 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} if you wish to preserve that.
+use @code{save-excursion} also, if you wish to preserve that.
 
 Don't use this construct when @code{save-selected-window} is all you need.
 
@@ -1815,3 +1789,85 @@
   Primitives to look inside of window configurations would make sense,
 but none are implemented.  It is not clear they are useful enough to be
 worth implementing.
+
+@node Window Hooks
+@section Hooks for Window Scrolling and Changes
+
+This section describes how a Lisp program can take action whenever a
+window displays a different part of its buffer or a different buffer.
+There are three actions that can change this: scrolling the window,
+switching buffers in the window, and changing the size of the window.
+The first two actions run @code{window-scroll-functions}; the last runs
+@code{window-size-change-functions}.  The paradigmatic use of these
+hooks is Lazy Lock mode; see @ref{Support Modes, Lazy Lock, Font Lock
+Support Modes, emacs, The GNU Emacs Manual}.
+
+@defvar window-scroll-functions
+This variable holds a list of functions that Emacs should call before
+redisplaying a window with scrolling.  It is not a normal hook, because
+each function is called with two arguments: the window, and its new
+display-start position.
+
+Displaying a different buffer in the window also runs these functions.
+
+These functions cannot expect @code{window-end} (@pxref{Window Start})
+to return a meaningful value, because that value is updated only by
+redisplaying the buffer.  So if one of these functions needs to know the
+last character that will fit in the window with its current
+display-start position, it has to find that character using
+@code{vertical-motion} (@pxref{Screen Lines}).
+@end defvar
+
+@defvar window-size-change-functions
+This variable holds a list of functions to be called if the size of any
+window changes for any reason.  The functions are called just once per
+redisplay, and just once for each frame on which size changes have
+occurred.
+
+Each function receives the frame as its sole argument.  There is no
+direct way to find out which windows on that frame have changed size, or
+precisely how.  However, if a size-change function records, at each
+call, the existing windows and their sizes, it can also compare the
+present sizes and the previous sizes.
+
+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.
+@end defvar
+
+@tindex redisplay-end-trigger-functions
+@defvar redisplay-end-trigger-functions
+This abnormal hook is run whenever redisplay in window uses text that
+extends past a specified end trigger position.  You set the end trigger
+position with the function @code{set-window-redisplay-end-trigger}.  The
+functions are called with two arguments: the window, and the end trigger
+position.  Storing @code{nil} for the end trigger position turns off the
+feature, and the trigger value is automatically reset to @code{nil} just
+after the hook is run.
+@end defvar
+
+@tindex set-window-redisplay-end-trigger
+@defun set-window-redisplay-end-trigger window position
+This function sets @var{window}'s end trigger position at
+@var{position}.
+@end defun
+
+@tindex window-redisplay-end-trigger
+@defun window-redisplay-end-trigger window
+This function returns @var{window}'s current end trigger position.
+@end defun
+
+@tindex window-configuration-change-hook
+@defvar window-configuration-change-hook
+A normal hook that is run every time you change the window configuration
+of an existing frame.  This includes splitting or deleting windows,
+changing the sizes of windows, or displaying a different buffer in a
+window.  The frame whose window configuration has changed is the
+selected frame when this hook runs.
+@end defvar