@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 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/windows
@node Windows, Frames, Buffers, Top
displayed in windows.
@menu
-* Basic Windows:: Basic information on using windows.
-* Splitting Windows:: Splitting one window into two windows.
-* Deleting Windows:: Deleting a window gives its space to other windows.
-* Selecting Windows:: The selected window is the one that you edit in.
-* Cyclic Window Ordering:: Moving around the existing windows.
-* Buffers and Windows:: Each window displays the contents of a buffer.
-* Displaying Buffers:: Higher-lever functions for displaying a buffer
- and choosing a window for it.
-* Choosing Window:: How to choose a window for displaying a buffer.
-* Window Point:: Each window has its own location of point.
-* 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.
-* 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.
+* Basic Windows:: Basic information on using windows.
+* Splitting Windows:: Splitting one window into two windows.
+* Deleting Windows:: Deleting a window gives its space to other windows.
+* Selecting Windows:: The selected window is the one that you edit in.
+* Cyclic Window Ordering:: Moving around the existing windows.
+* Buffers and Windows:: Each window displays the contents of a buffer.
+* Displaying Buffers:: Higher-lever functions for displaying a buffer
+ and choosing a window for it.
+* Choosing Window:: How to choose a window for displaying a buffer.
+* Window Point:: Each window has its own location of point.
+* 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.
@end menu
@node Basic Windows
@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 which
+ 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 all intents, a window only exists 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:
@item
containing frame
-@item
+@item
window height
-@item
+@item
window width
-@item
+@item
window edges with respect to the screen or frame
-@item
+@item
the buffer it displays
-@item
+@item
position within the buffer at the upper left of the window
-@item
-the amount of horizontal scrolling, in columns
+@item
+amount of horizontal scrolling, in columns
-@item
+@item
point
-@item
+@item
the mark
-@item
+@item
how recently the window was selected
@end itemize
@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.
+context of general-purpose window systems such as X, but not identical.
+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 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 of the screen or frame. Because of the way
+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}.
new window. Otherwise, it splits into windows one above the other, and
@var{window} keeps the upper @var{size} lines and gives the rest of the
lines to the new window. The original window is therefore the
-right-hand or upper of the two, and the new window is the left-hand or
+left-hand or upper of the two, and the new window is the right-hand or
lower.
If @var{window} is omitted or @code{nil}, then the selected window is
@group
;; @r{Returns window created}
-(setq w2 (split-window w 15))
+(setq w2 (split-window w 15))
@result{} #<window 28 on windows.texi>
@end group
@group
@smallexample
@group
- __________
- | | line 0
+ __________
+ | | line 0
| w |
|__________|
| | line 15
@end group
@end smallexample
+@need 3000
Now, the screen looks like this:
@smallexample
@group
column 35
- __________
- | | | line 0
+ __________
+ | | | line 0
| w | w3 |
|___|______|
| | line 15
column 0 column 80
@end group
@end smallexample
+
+Normally, Emacs indicates the border between two side-by-side windows
+with a scroll bar (@pxref{X Frame Parameters,Scroll Bars}) or @samp{|}
+characters. The display table can specify alternative border
+characters; see @ref{Display Tables}.
@end deffn
@deffn Command split-window-vertically size
@smallexample
@group
(defun split-window-vertically (&optional arg)
- "Split current window into two windows, one above the other."
+ "Split current window into two windows, @dots{}"
(interactive "P")
(split-window nil (and arg (prefix-numeric-value arg))))
@end group
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.
+
+This macro does not save or restore anything about the sizes, arrangement
+or contents of windows; therefore, if the @var{forms} change them,
+the change persists.
+
+Each frame, at any time, has a window selected within the frame. This
+macro only saves @emph{the} selected window; it does not save anything
+about other frames. If the @var{forms} select some other frame and
+alter the window selected within it, the change persists.
+@end defmac
+
@cindex finding windows
The following functions choose one of the windows on the screen,
offering various criteria for the choice.
only window. A newly created window becomes the least recently used
window until it is selected. A minibuffer window is never a candidate.
-The argument @var{frame} controls which set of windows are
-considered.
+The argument @var{frame} controls which windows are considered.
@itemize @bullet
@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
with the most lines. A minibuffer window is never a candidate.
If there are two windows of the same size, then the function returns
-the window which is first in the cyclic ordering of windows (see
+the window that is first in the cyclic ordering of windows (see
following section), starting from the selected window.
The argument @var{frame} controls which set of windows are
@section Cyclic Ordering of Windows
@cindex cyclic ordering of windows
@cindex ordering of windows, cyclic
-@cindex window ordering, cyclic
+@cindex window ordering, cyclic
When you use the command @kbd{C-x o} (@code{other-window}) to select
the next window, it moves through all the windows on the screen in a
@defun next-window &optional window minibuf all-frames
@cindex minibuffer window
This function returns the window following @var{window} in the cyclic
-ordering of windows. This is the window which @kbd{C-x o} would select
-if done when @var{window} is selected. If @var{window} is the only
+ordering of windows. This is the window that @kbd{C-x o} would select
+if typed when @var{window} is selected. If @var{window} is the only
window visible, then this function returns @var{window}. If omitted,
@var{window} defaults to the selected window.
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
-This example assumes there are two windows, both displaying the
+This example assumes there are two windows, both displaying the
buffer @samp{windows.texi}:
@example
@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.
+@defun get-buffer-window-list buffer-or-name &optional minibuf all-frames
+This function returns a list of all the windows currently displaying
+@var{buffer-or-name}.
-This function returns @code{nil}.
-@end deffn
+The two optional arguments work like the optional arguments of
+@code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not}
+like the single optional argument of @code{get-buffer-window}. Perhaps
+we should change @code{get-buffer-window} in the future to make it
+compatible with the other functions.
+
+The argument @var{all-frames} controls which windows to consider.
+
+@itemize @bullet
+@item
+If it is @code{nil}, consider windows on the selected frame.
+@item
+If it is @code{t}, consider windows on all frames.
+@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
@node Displaying Buffers
@section Displaying Buffers in Windows
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
window. The handling of the buffer is the same as in
@code{switch-to-buffer}.
-The previously selected window is absolutely never used to display the
-buffer. If it is the only window, then it is split to make a distinct
-window for 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.
+The currently selected window is absolutely never used to do the job.
+If it is the only window, then it is split to make a distinct window for
+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.
@end deffn
@defun pop-to-buffer buffer-or-name &optional other-window
@code{nil}, then the selected window is considered sufficient display
for @var{buffer-or-name}, so that nothing needs to be done.
-If @var{buffer-or-name} is a string that does not name an existing
-buffer, a buffer by that name is created.
+All the variables that affect @code{display-buffer} affect
+@code{pop-to-buffer} as well. @xref{Choosing Window}.
-An example use of this function is found at the end of @ref{Filter
-Functions}.
+If @var{buffer-or-name} is a string that does not name an existing
+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
- This section describes the basic facility which chooses a window to
+ This section describes the basic facility that chooses a window to
display a buffer in---@code{display-buffer}. All the higher-level
functions and commands use this subroutine. Here we describe how to use
@code{display-buffer} and how to customize it.
Its value should be a function of no arguments. When
@code{display-buffer} makes a new frame, it does so by calling that
function, which should return a frame. The default value of the
-variable is a function which creates a frame using parameters from
+variable is a function that creates a frame using parameters from
@code{pop-up-frame-alist}.
@end defvar
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
@var{buffer} is already displayed in a window in some frame, it makes
the frame visible and raises it, to use that window. Otherwise, it
creates a frame that will be dedicated to @var{buffer}.
+
+This function uses an existing window displaying @var{buffer} whether or
+not it is in a frame of its own; but if you set up the above variables
+in your init file, before @var{buffer} was created, then presumably the
+window was previously made by this function.
@end defun
@defopt special-display-frame-alist
@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
@section The Window Start Position
Each window contains a marker used to keep track of a buffer position
-which specifies where in the buffer display should start. This position
+that specifies where in the buffer display should start. This position
is called the @dfn{display-start} position of the window (or just the
@dfn{start}). The character after this position is the one that appears
at the upper left corner of the window. It is usually, but not
@cindex window top line
This function returns the display-start position of window
@var{window}. If @var{window} is @code{nil}, the selected window is
-used. For example,
+used. For example,
@example
@group
@end group
@end example
-When you create a window, or display a different buffer in it, the the
+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.
-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
This function returns the position of the end of the display in window
@var{window}. If @var{window} is @code{nil}, the selected window is
used.
+
+Simply changing the buffer text or moving point does not update the
+value that @code{window-end} returns. The value is updated only when
+Emacs redisplays and redisplay actually finishes.
+
+If the last redisplay of @var{window} was preempted, and did not finish,
+Emacs does not know the position of the end of display in that window.
+In that case, this function returns a value that is not correct. In a
+future version, @code{window-end} will return @code{nil} in that case.
+@ignore
+in that case, this function returns @code{nil}. You can compute where
+the end of the window @emph{would} have been, if redisplay had finished,
+like this:
+
+@example
+(save-excursion
+ (goto-char (window-start window))
+ (vertical-motion (1- (window-height window))
+ window)
+ (point))
+@end example
+@end ignore
@end defun
@defun set-window-start window position &optional noforce
This function sets the display-start position of @var{window} to
-@var{position} in @var{window}'s buffer.
+@var{position} in @var{window}'s buffer. It returns @var{position}.
The display routines insist that the position of point be visible when a
buffer is displayed. Normally, they change the display-start position
If @var{noforce} is non-@code{nil}, and @var{position} would place point
off screen at the next redisplay, then redisplay computes a new window-start
position that works well with point, and thus @var{position} is not used.
-
-This function returns @var{position}.
@end defun
@defun pos-visible-in-window-p &optional position window
If @var{count} is omitted or @code{nil}, then the length of the scroll
is @code{next-screen-context-lines} lines less than the usable height of
-the window.
+the window (not counting its mode line).
@code{scroll-down} returns @code{nil}.
@end deffn
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.
text to center point vertically in the window. If the value is a
positive integer @var{n}, then redisplay brings point back on screen by
scrolling @var{n} lines in either direction, if possible; otherwise, it
-centers point if possible. The default value is zero.
+centers point. The default value is zero.
@end defopt
@defopt next-screen-context-lines
@var{count} to 4, which positions the current line four lines from the
top.
-Typing @kbd{C-u 0 C-l} positions the current line at the top of the
-window. This action is so handy that some people bind the command to a
-function key. For example,
+With an argument of zero, @code{recenter} positions the current line at
+the top of the window. This action is so handy that some people make a
+separate key binding to do this. For example,
@example
@group
(defun line-to-top-of-window ()
"Scroll current line to top of window.
Replaces three keystroke sequence C-u 0 C-l."
- (interactive)
+ (interactive)
(recenter 0))
-(global-set-key "\C-cl" 'line-to-top-of-window)
+(global-set-key [kp-multiply] 'line-to-top-of-window)
@end group
@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
This function scrolls the selected window @var{count} columns to the
left (or to the right if @var{count} is negative). The return value is
the total amount of leftward horizontal scrolling in effect after the
-change---just like the value returned by @code{window-hscroll}.
+change---just like the value returned by @code{window-hscroll} (below).
@end deffn
@deffn Command scroll-right count
This function scrolls the selected window @var{count} columns to the
right (or to the left if @var{count} is negative). The return value is
the total amount of leftward horizontal scrolling in effect after the
-change---just like the value returned by @code{window-hscroll}.
+change---just like the value returned by @code{window-hscroll} (below).
Once you scroll a window as far right as it can go, back to its normal
position where the total leftward scrolling is zero, attempts to scroll
@example
@group
-(save-excursion
- (goto-char @var{position})
- (and
- (>= (- (current-column) (window-hscroll @var{window})) 0)
- (< (- (current-column) (window-hscroll @var{window}))
- (window-width @var{window}))))
+(defun hscroll-on-screen (window position)
+ (save-excursion
+ (goto-char position)
+ (and
+ (>= (- (current-column) (window-hscroll window)) 0)
+ (< (- (current-column) (window-hscroll window))
+ (window-width window)))))
@end group
@end example
the height (the number of lines) and the width (the number of character
positions in each line). The mode line is included in the height. But
the width does not count the scroll bar or the column of @samp{|}
-characters separates side-by-side windows.
+characters that separates side-by-side windows.
The following three functions return size information about a window:
@end group
@end example
-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}.
+@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, 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
- 0
+ 0
_______
- 0 | |
- | |
- | |
- | |
+ 0 | |
+ | |
+ | |
+ | |
xxxxxxxxx 4
- 7
+ 7
@end group
@end example
@example
@group
___ ___
- | | |
- | | |
- xxxxxxxxx
+ | | |
+ | | |
+ xxxxxxxxx
0 34 7
@end group
windows, so resizing one window affects other windows.
@deffn Command enlarge-window size &optional horizontal
-This function makes the selected window @var{size} lines bigger,
+This function makes the selected window @var{size} lines taller,
stealing lines from neighboring windows. It takes the lines from one
window at a time until that window is used up, then takes from another.
If a window from which lines are stolen shrinks below
lines. If a window from which columns are stolen shrinks below
@code{window-min-width} columns, that window disappears.
-If the window's frame is smaller than @var{size} lines (or columns),
-then the function makes the window occupy the entire height (or width)
-of the frame.
+If the requested size would exceed that of the window's frame, then the
+function makes the window occupy the entire height (or width) of the
+frame.
If @var{size} is negative, this function shrinks the window by
@minus{}@var{size} lines or columns. If that makes the window smaller
than the minimum size (@code{window-min-height} and
@code{window-min-width}), @code{enlarge-window} deletes the window.
-@code{enlarge-window} returns @code{nil}.
+@code{enlarge-window} returns @code{nil}.
@end deffn
@deffn Command enlarge-window-horizontally columns
@end deffn
@cindex minimum window size
- The following two variables constrain the window size changing
+ The following two variables constrain the window-size-changing
functions to a minimum height and width.
@defopt window-min-height
@code{window-min-height} automatically deletes it, and no window may be
created shorter than this. The absolute minimum height is two (allowing
one line for the mode line, and one line for the buffer display).
-Actions which change window sizes reset this variable to two if it is
+Actions that change window sizes reset this variable to two if it is
less than two. The default value is 4.
@end defopt
@node Coordinates and Windows
@section Coordinates and Windows
-This section describes how to compare screen coordinates with windows.
+This section describes how to relate screen coordinates to windows.
@defun window-at x y &optional frame
This function returns the window containing the specified cursor
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
@item vertical-split
The coordinates are in the vertical line between @var{window} and its
-neighbor to the right. This value occurs only if the window doesn't
+neighbor to the right. This value occurs only if the window doesn't
have a scroll bar; positions in a scroll bar are considered outside the
window.
@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}:
This special form records the window configuration, executes @var{forms}
in sequence, then restores the earlier window configuration. The window
configuration includes the value of point and the portion of the buffer
-which is visible. It also includes the choice of selected window.
+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.
+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:
HCoop / bpt / emacs.git / blobdiff