@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.
- 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:
@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 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
@end group
@end smallexample
+@need 3000
Now, the screen looks like this:
@smallexample
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
@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
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
@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.
@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
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
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
-@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
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
@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
-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
+@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
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
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
@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
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
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.
@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
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
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
@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}:
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: