(syms_of_minibuf): Doc fix.

[gnu-emacs] / lispref / windows.texi

diff --git a/lispref/windows.texi b/lispref/windows.texi
index 708862ab18b2f2a4909cd4c008ce3319a0b432da..1a8093384b6c78e0d45e03f25b504a5de8fcf7e7 100644 (file)
--- a/lispref/windows.texi
+++ b/lispref/windows.texi
@@ -36,25 +36,29 @@ displayed in windows.
 @cindex window
 @cindex selected window
 
 @cindex window
 @cindex selected window
 

-  A @dfn{window} is the physical area of the screen in which a buffer is
-displayed.  The term is also used to refer to a Lisp object that
+  A @dfn{window} in Emacs is the physical area of the screen in which a
+buffer is displayed.  The term is also used to refer to a Lisp object that

 represents that screen area in Emacs Lisp.  It should be
 clear from the context which is meant.
 
 represents that screen area in Emacs Lisp.  It should be
 clear from the context which is meant.
 

-  There is always at least one window in any frame.  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.  There is also
-one 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}.
-
-  For practical purposes, a window exists only while it is displayed on the
-terminal.  Once removed from the display, the window is effectively
-deleted and should not be used, @emph{even though there may still be
-references to it} from other Lisp objects.  Restoring a saved window
-configuration is the only way for a window no longer on the screen to
-come back to life.  (@xref{Deleting Windows}.)
+  Emacs groups windows into frames.  A frame represents an area of
+screen available for Emacs to use.  Each frame always contains at least
+one window, but you can subdivide it vertically or horizontally into
+multiple nonoverlapping Emacs windows.
+
+  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
+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}.
+
+  For practical purposes, a window exists only while it is displayed in
+a frame.  Once removed from the frame, the window is effectively deleted
+and should not be used, @emph{even though there may still be references
+to it} from other Lisp objects.  Restoring a saved window configuration
+is the only way for a window no longer on the screen to come back to
+life.  (@xref{Deleting Windows}.)

 
   Each window has the following attributes:
 
 
   Each window has the following attributes:
 


@@ -93,17 +97,16 @@ how recently the window was selected
 @cindex multiple windows
   Users create multiple windows so they can look at several buffers at
 once.  Lisp libraries use multiple windows for a variety of reasons, but
 @cindex multiple windows
   Users create multiple windows so they can look at several buffers at
 once.  Lisp libraries use multiple windows for a variety of reasons, but

-most often to give different views of the same information.  In Rmail,
-for example, you can move through a summary buffer in one window while
-the other window shows messages one at a time as they are reached.
+most often to display related information.  In Rmail, for example, you
+can move through a summary buffer in one window while the other window
+shows messages one at a time as they are reached.

 
   The meaning of ``window'' in Emacs is similar to what it means in the
 context of general-purpose window systems such as X, but not identical.
 
   The meaning of ``window'' in Emacs is similar to what it means in the
 context of general-purpose window systems such as X, but not identical.

-The X Window System subdivides the screen into X windows; Emacs uses one
-or more X windows, called @dfn{frames} in Emacs terminology, and
-subdivides each of them into (nonoverlapping) Emacs windows.  When you
-use Emacs on an ordinary display terminal, Emacs subdivides the terminal
-screen into Emacs windows.
+The X Window System places X windows on the screen; Emacs uses one or
+more X windows as frames, and subdivides them into
+Emacs windows.  When you use Emacs on a character-only terminal, Emacs
+treats the whole terminal screen as one frame.

 
 @cindex terminal screen
 @cindex screen of terminal
 
 @cindex terminal screen
 @cindex screen of terminal


@@ -221,6 +224,7 @@ Next, the top window is split horizontally:
 @end group
 @end smallexample
 
 @end group
 @end smallexample
 

+@need 3000

 Now, the screen looks like this:
 
 @smallexample
 Now, the screen looks like this:
 
 @smallexample


@@ -283,7 +287,7 @@ part of the documentation string):
 This function returns non-@code{nil} if there is only one window.  The
 argument @var{no-mini}, if non-@code{nil}, means don't count the
 minibuffer even if it is active; otherwise, the minibuffer window is
 This function returns non-@code{nil} if there is only one window.  The
 argument @var{no-mini}, if non-@code{nil}, means don't count the
 minibuffer even if it is active; otherwise, the minibuffer window is

-included, if active, in the total number of windows,  which is compared
+included, if active, in the total number of windows, which is compared

 against one.
 
 The argument @var{all-frames} specifies which frames to consider.  Here
 against one.
 
 The argument @var{all-frames} specifies which frames to consider.  Here


@@ -300,6 +304,9 @@ Count all windows in all existing frames.
 @item @code{visible}
 Count all windows in all visible frames.
 
 @item @code{visible}
 Count all windows in all visible frames.
 

+@item 0
+Count all windows in all visible or iconified frames.
+

 @item anything else
 Count precisely the windows in the selected frame, and no others.
 @end table
 @item anything else
 Count precisely the windows in the selected frame, and no others.
 @end table


@@ -370,6 +377,8 @@ If it is @code{nil}, operate on the selected frame.
 If it is @code{t}, operate on all frames.
 @item
 If it is @code{visible}, operate on all visible frames.
 If it is @code{t}, operate on all frames.
 @item
 If it is @code{visible}, operate on all visible frames.

+@item 0
+If it is 0, operate on all visible or iconified frames.

 @item
 If it is a frame, operate on that frame.
 @end itemize
 @item
 If it is a frame, operate on that frame.
 @end itemize


@@ -405,6 +414,14 @@ The return value is @var{window}.
 @end example
 @end defun
 
 @end example
 @end defun
 

+@defmac save-selected-window forms@dots{}
+This macro records the selected window, executes @var{forms}
+in sequence, then restores the earlier selected window.
+It does not save or restore anything about the sizes, arrangement
+or contents of windows; therefore, if the @var{forms} change them,
+the changes are permanent.
+@end defmac
+

 @cindex finding windows
   The following functions choose one of the windows on the screen,
 offering various criteria for the choice.
 @cindex finding windows
   The following functions choose one of the windows on the screen,
 offering various criteria for the choice.


@@ -427,6 +444,8 @@ If it is @code{t}, consider windows on all frames.
 @item
 If it is @code{visible}, consider windows on all visible frames.
 @item
 @item
 If it is @code{visible}, consider windows on all visible frames.
 @item

+If it is 0, consider windows on all visible or iconified frames.
+@item

 If it is a frame, consider windows on that frame.
 @end itemize
 @end defun
 If it is a frame, consider windows on that frame.
 @end itemize
 @end defun


@@ -503,6 +522,9 @@ Consider all windows in all existing frames.
 Consider all windows in all visible frames.  (To get useful results, you
 must ensure @var{window} is in a visible frame.)
 
 Consider all windows in all visible frames.  (To get useful results, you
 must ensure @var{window} is in a visible frame.)
 

+@item 0
+Consider all windows in all visible or iconified frames.
+

 @item anything else
 Consider precisely the windows in @var{window}'s frame, and no others.
 @end table
 @item anything else
 Consider precisely the windows in @var{window}'s frame, and no others.
 @end table


@@ -611,20 +633,12 @@ If it is @code{t}, consider windows on all frames.
 @item
 If it is @code{visible}, consider windows on all visible frames.
 @item
 @item
 If it is @code{visible}, consider windows on all visible frames.
 @item

+If it is 0, consider windows on all visible or iconified frames.
+@item

 If it is a frame, consider windows on that frame.
 @end itemize
 @end defun
 
 If it is a frame, consider windows on that frame.
 @end itemize
 @end defun
 

-@deffn Command replace-buffer-in-windows buffer
-This function replaces @var{buffer} with some other buffer in all
-windows displaying it.  The other buffer used is chosen with
-@code{other-buffer}.  In the usual applications of this function, you
-don't care which other buffer is used; you just want to make sure that
-@var{buffer} is no longer displayed.
-
-This function returns @code{nil}.
-@end deffn
-

 @node Displaying Buffers
 @section Displaying Buffers in Windows
 @cindex switching to a buffer
 @node Displaying Buffers
 @section Displaying Buffers in Windows
 @cindex switching to a buffer


@@ -659,8 +673,10 @@ Contrast this with @code{set-buffer}, which makes @var{buffer-or-name}
 the current buffer but does not display it in the selected window.
 @xref{Current Buffer}.
 
 the current buffer but does not display it in the selected window.
 @xref{Current Buffer}.
 

-If @var{buffer-or-name} does not identify an existing buffer, then
-a new buffer by that name is created.
+If @var{buffer-or-name} does not identify an existing buffer, then a new
+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}.

 
 Normally the specified buffer is put at the front of the buffer list.
 This affects the operation of @code{other-buffer}.  However, if
 
 Normally the specified buffer is put at the front of the buffer list.
 This affects the operation of @code{other-buffer}.  However, if


@@ -714,10 +730,25 @@ already displayed in the selected window and @var{other-window} is
 @code{nil}, then the selected window is considered sufficient display
 for @var{buffer-or-name}, so that nothing needs to be done.
 
 @code{nil}, then the selected window is considered sufficient display
 for @var{buffer-or-name}, so that nothing needs to be done.
 

+All the variables that affect @code{display-buffer} affect
+@code{pop-to-buffer} as well.  @xref{Choosing Window}.
+

 If @var{buffer-or-name} is a string that does not name an existing
 If @var{buffer-or-name} is a string that does not name an existing

-buffer, a buffer by that name is created.
+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}.

 @end defun
 
 @end defun
 

+@deffn Command replace-buffer-in-windows buffer
+This function replaces @var{buffer} with some other buffer in all
+windows displaying it.  The other buffer used is chosen with
+@code{other-buffer}.  In the usual applications of this function, you
+don't care which other buffer is used; you just want to make sure that
+@var{buffer} is no longer displayed.
+
+This function returns @code{nil}.
+@end deffn
+

 @node Choosing Window
 @section Choosing a Window for Display
 
 @node Choosing Window
 @section Choosing a Window for Display
 


@@ -800,6 +831,13 @@ If the buffer's name is in this list, @code{display-buffer} handles the
 buffer specially.
 
 By default, special display means to give the buffer a dedicated frame.
 buffer specially.
 
 By default, special display means to give the buffer a dedicated frame.

+
+If an element is a list, instead of a string, then the @sc{car} of the
+list is the buffer name, and the rest of the list says how to create the
+frame.  There are two possibilities for the rest of the list.  It can be
+an alist, specifying frame parameters, or it can contain a function and
+arguments to give to it.  (The function's first argument is always the
+buffer to be displayed; the arguments from the list come after that.)

 @end defvar
 
 @defvar special-display-regexps
 @end defvar
 
 @defvar special-display-regexps


@@ -809,6 +847,10 @@ expressions in this list, @code{display-buffer} handles the buffer
 specially.
 
 By default, special display means to give the buffer a dedicated frame.
 specially.
 
 By default, special display means to give the buffer a dedicated frame.

+
+If an element is a list, instead of a string, then the @sc{car} of the
+list is the regular expression, and the rest of the list says how to
+create the frame.  See above, under @code{special-display-buffer-names}.

 @end defvar
 
 @defvar special-display-function
 @end defvar
 
 @defvar special-display-function


@@ -837,6 +879,20 @@ This variable holds frame parameters for
 @code{special-display-popup-frame} to use when it creates a frame.
 @end defopt
 
 @code{special-display-popup-frame} to use when it creates a frame.
 @end defopt
 

+@defopt same-window-buffer-names
+A list of buffer names for buffers that should be displayed in the
+selected window.  If the buffer's name is in this list,
+@code{display-buffer} handles the buffer by switching to it in the
+selected window.
+@end defopt
+
+@defopt same-window-regexps
+A list of regular expressions that specify buffers that should be
+displayed in the selected window.  If the buffer's name matches any of
+the regular expressions in this list, @code{display-buffer} handles the
+buffer by switching to it in the selected window.
+@end defopt
+

 @c Emacs 19 feature
 @defvar display-buffer-function
 This variable is the most flexible way to customize the behavior of
 @c Emacs 19 feature
 @defvar display-buffer-function
 This variable is the most flexible way to customize the behavior of


@@ -947,8 +1003,14 @@ When you create a window, or display a different buffer in it, the
 display-start position is set to a display-start position recently used
 for the same buffer, or 1 if the buffer doesn't have any.
 
 display-start position is set to a display-start position recently used
 for the same buffer, or 1 if the buffer doesn't have any.
 

-For a realistic example, see the description of @code{count-lines} in
-@ref{Text Lines}.
+Redisplay updates the window-start position (if you have not specified
+it explicitly since the previous redisplay) so that point appears on the
+screen.  Nothing except redisplay automatically changes the window-start
+position; if you move point, do not expect the window-start position to
+change in response until after the next redisplay.
+
+For a realistic example of using @code{window-start}, see the
+description of @code{count-lines} in @ref{Text Lines}.

 @end defun
 
 @defun window-end &optional window
 @end defun
 
 @defun window-end &optional window


@@ -1121,10 +1183,6 @@ This function scrolls the text in another window upward @var{count}
 lines.  Negative values of @var{count}, or @code{nil}, are handled
 as in @code{scroll-up}.
 
 lines.  Negative values of @var{count}, or @code{nil}, are handled
 as in @code{scroll-up}.
 

-The window that is scrolled is normally the one following the selected
-window in the cyclic ordering of windows---the window that
-@code{next-window} would return.  @xref{Cyclic Window Ordering}.
-

 You can specify a buffer to scroll with the variable
 @code{other-window-scroll-buffer}.  When the selected window is the
 minibuffer, the next window is normally the one at the top left corner.
 You can specify a buffer to scroll with the variable
 @code{other-window-scroll-buffer}.  When the selected window is the
 minibuffer, the next window is normally the one at the top left corner.


@@ -1384,14 +1442,16 @@ window:
 @noindent
 The bottom edge is at line 23 because the last line is the echo area.
 
 @noindent
 The bottom edge is at line 23 because the last line is the echo area.
 

-If @var{window} is at the upper left corner of its frame, @var{right}
-and @var{bottom} are the same as the values returned by
-@code{(window-width)} and @code{(window-height)} respectively, and
-@var{top} and @var{bottom} are zero.  For example, the edges of the
-following window are @w{@samp{0 0 5 8}}.  Assuming that the frame has
-more than 8 columns, the last column of the window (column 7) holds a
-border rather than text.  The last row (row 4) holds the mode line,
-shown here with @samp{xxxxxxxxx}.
+If @var{window} is at the upper left corner of its frame, then
+@var{bottom} is the same as the value of @code{(window-height)},
+@var{right} is almost the same as the value of
+@code{(window-width)}@footnote{They are not exactly equal because
+@var{right} includes the vertical separator line or scroll bar, while
+@code{(window-width)} does not.}, and @var{top} and @var{left} are zero.
+For example, the edges of the following window are @w{@samp{0 0 5 8}}.
+Assuming that the frame has more than 8 columns, the last column of the
+window (column 7) holds a border rather than text.  The last row (row 4)
+holds the mode line, shown here with @samp{xxxxxxxxx}.

 
 @example
 @group
 
 @example
 @group


@@ -1520,6 +1580,28 @@ created narrower than this.  The absolute minimum width is one; any
 value below that is ignored.  The default value is 10.
 @end defopt
 
 value below that is ignored.  The default value is 10.
 @end defopt
 

+@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 changed size, or precisely how;
+however, if your size-change function keeps track, after each change, of
+the windows that interest you, you can figure out what has changed by
+comparing the old size data with the new.
+
+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} 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} is what you need here.
+@end defvar
+

 @node Coordinates and Windows
 @section Coordinates and Windows
 
 @node Coordinates and Windows
 @section Coordinates and Windows
 


@@ -1538,6 +1620,7 @@ If you omit @var{frame}, the selected frame is used.
 This function checks whether a particular frame position falls within
 the window @var{window}.
 
 This function checks whether a particular frame position falls within
 the window @var{window}.
 

+@need 3000

 The argument @var{coordinates} is a cons cell of this form:
 
 @example
 The argument @var{coordinates} is a cons cell of this form:
 
 @example


@@ -1606,6 +1689,11 @@ 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}.
 
 @var{configuration} must be a value that was previously returned by
 @code{current-window-configuration}.
 

+This function always counts as a window size change and triggers
+execution of the @code{window-size-change-functions}.  (It doesn't know
+how to tell whether the new configuration actually differs from the old
+one.)
+

 Here is a way of using this function to get the same effect
 as @code{save-window-excursion}:
 
 Here is a way of using this function to get the same effect
 as @code{save-window-excursion}:
 


@@ -1628,6 +1716,13 @@ 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.
 
 However, it does not include the value of point in the current buffer;
 use @code{save-excursion} if you wish to preserve that.
 

+Don't use this construct when @code{save-selected-window} is all you need.
+
+Exit from @code{save-window-excursion} always triggers execution of the
+@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:
 
 The return value is the value of the final form in @var{forms}.
 For example: