window).
@end defun
+@anchor{Window Group}Sometimes several windows collectively and
+cooperatively display a buffer, for example, under the management of
+Follow Mode (@pxref{Follow Mode,,, emacs}), where the windows together
+display a bigger portion of the buffer than one window could alone.
+It is often useful to consider such a @dfn{window group} as a single
+entity. Several functions such as @code{window-group-start}
+(@pxref{Window Start and End}) allow you to do this by supplying, as
+an argument, one of the windows as a stand in for the whole group.
+
+@defun selected-window-group
+@vindex selected-window-group-function
+When the selected window is a member of a group of windows, this
+function returns a list of the windows in the group, ordered such that
+the first window in the list is displaying the earliest part of the
+buffer, and so on. Otherwise the function returns a list containing
+just the selected window.
+
+The selected window is considered part of a group when the buffer
+local variable @code{selected-window-group-function} is set to a
+function. In this case, @code{selected-window-group} calls it with no
+arguments and returns its result (which should be the list of windows
+in the group).
+@end defun
+
@node Windows and Frames
@section Windows and Frames
width of a window. The return value of many of these functions can be
specified either in units of pixels or in units of lines and columns.
On a graphical display, the latter actually correspond to the height and
-width of a ``default'' character specified by the frame's default font
+width of a default character specified by the frame's default font
as returned by @code{frame-char-height} and @code{frame-char-width}
-(@pxref{Size and Position}). Thus, if a window is displaying text with
-a different font or size, the reported line height and column width for
+(@pxref{Frame Font}). Thus, if a window is displaying text with a
+different font or size, the reported line height and column width for
that window may differ from the actual number of text lines or columns
displayed within it.
children.
@end defun
-@cindex window pixel height
-@cindex pixel height of a window
-@cindex total pixel height of a window
+@cindex window pixel width
+@cindex pixel width of a window
+@cindex total pixel width of a window
@defun window-pixel-width &optional Lisp_Object &optional window
This function returns the width of window @var{window} in pixels.
@cindex window body height
@cindex body height of a window
-@cindex window body width
The @dfn{body height} of a window is the height of its text area, which
does not include a mode or header line, a horizontal scroll bar, or a
bottom divider.
exceed its total height as returned by @code{window-total-height}.
@end defun
+@cindex window body width
@cindex body width of a window
-@cindex body size of a window
-@cindex window body size
The @dfn{body width} of a window is the width of its text area, which
does not include the scroll bar, fringes, margins or a right divider.
exceed its total width as returned by @code{window-total-width}.
@end defun
+@cindex window body size
+@cindex body size of a window
@defun window-body-size &optional window horizontal pixelwise
This function returns the body height or body width of @var{window}. If
@var{horizontal} is omitted or @code{nil}, it is equivalent to calling
argument @var{pixelwise} is passed to the function called.
@end defun
- For compatibility with previous versions of Emacs,
+For compatibility with previous versions of Emacs,
@code{window-height} is an alias for @code{window-total-height}, and
@code{window-width} is an alias for @code{window-body-width}. These
aliases are considered obsolete and will be removed in the future.
(@pxref{Scroll Bars}), and display margins (@pxref{Display Margins}) are
described in the corresponding sections.
+If your Lisp program needs to make layout decisions, you will find the
+following function useful:
+
+@defun window-max-chars-per-line &optional window face
+This function returns the number of characters displayed in the
+specified @var{face} in the specified @var{window} (which must be a
+live window). If @var{face} was remapped (@pxref{Face Remapping}),
+the information is returned for the remapped face. If omitted or
+@code{nil}, @var{face} defaults to the default face, and @var{window}
+defaults to the selected window. Unlike @code{window-body-width},
+this function accounts for the actual size of the @var{face}'s font,
+instead of working in units of frame's canonical character width. It
+also accounts for space used by the continuation glyph, if
+@var{window} lacks one or both of its fringes.
+@end defun
+
@cindex fixed-size window
@vindex window-min-height
@vindex window-min-width
@code{window-min-height} and @code{window-min-width}, which specify the
smallest allowable window height and width. They also obey the variable
@code{window-size-fixed}, with which a window can be @dfn{fixed} in
-size:
+size (@pxref{Preserving Window Sizes}).
@defopt window-min-height
This option specifies the minimum total height, in lines, of any window.
units of pixels. This currently affects functions like
@code{split-window} (@pxref{Splitting Windows}), @code{maximize-window},
@code{minimize-window}, @code{fit-window-to-buffer},
-@code{shrink-window-if-larger-than-buffer} (all listed below) and
-@code{fit-frame-to-buffer} (@pxref{Size and Position}).
+@code{fit-frame-to-buffer} and
+@code{shrink-window-if-larger-than-buffer} (all listed below).
Note that when a frame's pixel size is not a multiple of its character
size, at least one window may get resized pixelwise even if this
If the option @code{fit-frame-to-buffer} (see below) is non-@code{nil},
this function will try to resize the frame of @var{window} to fit its
-contents by calling @code{fit-frame-to-buffer} (@pxref{Size and
-Position}).
+contents by calling @code{fit-frame-to-buffer} (see below).
@end deffn
@defopt fit-window-to-buffer-horizontally
non-@code{nil} value means frames can be resized in both dimensions.
@end defopt
+If you have a frame that displays only one window, you can fit that
+frame to its buffer using the command @code{fit-frame-to-buffer}.
+
+@deffn Command fit-frame-to-buffer &optional frame max-height min-height max-width min-width only
+This command adjusts the size of @var{frame} to display the contents of
+its buffer exactly. @var{frame} can be any live frame and defaults to
+the selected one. Fitting is done only if @var{frame}'s root window is
+live. The arguments @var{max-height}, @var{min-height}, @var{max-width}
+and @var{min-width} specify bounds on the new total size of
+@var{frame}'s root window. @var{min-height} and @var{min-width} default
+to the values of @code{window-min-height} and @code{window-min-width}
+respectively.
+
+If the optional argument @var{only} is @code{vertically}, this function
+may resize the frame vertically only. If @var{only} is
+@code{horizontally}, it may resize the frame horizontally only.
+@end deffn
+
+The behavior of @code{fit-frame-to-buffer} can be controlled with the
+help of the two options listed next.
+
+@defopt fit-frame-to-buffer-margins
+This option can be used to specify margins around frames to be fit by
+@code{fit-frame-to-buffer}. Such margins can be useful to avoid, for
+example, that such frames overlap the taskbar.
+
+It specifies the numbers of pixels to be left free on the left, above,
+the right, and below a frame that shall be fit. The default specifies
+@code{nil} for each which means to use no margins. The value specified
+here can be overridden for a specific frame by that frame's
+@code{fit-frame-to-buffer-margins} parameter, if present.
+@end defopt
+
+@defopt fit-frame-to-buffer-sizes
+This option specifies size boundaries for @code{fit-frame-to-buffer}.
+It specifies the total maximum and minimum lines and maximum and minimum
+columns of the root window of any frame that shall be fit to its buffer.
+If any of these values is non-@code{nil}, it overrides the corresponding
+argument of @code{fit-frame-to-buffer}.
+@end defopt
+
@deffn Command shrink-window-if-larger-than-buffer &optional window
This command attempts to reduce @var{window}'s height as much as
possible while still showing its full buffer, but no less than
@defun split-window &optional window size side pixelwise
This function creates a new live window next to the window
@var{window}. If @var{window} is omitted or @code{nil}, it defaults
-to the selected window. That window is ``split'', and reduced in
+to the selected window. That window is split, and reduced in
size. The space is taken up by the new window, which is returned.
The optional second argument @var{size} determines the sizes of
areas like a mode line or a scroll bar. The function
@code{window-min-size} (@pxref{Window Sizes}) can be used to determine
the minimum requirements of @var{window} in this regard. Since the new
-window usually ``inherits'' areas like the mode line or the scroll bar
+window usually inherits areas like the mode line or the scroll bar
from @var{window}, that function is also a good guess for the minimum
size of the new window. The caller should specify a smaller size only
if it correspondingly removes an inherited area before the next
coding. As a rule, such selections (including those made by the macros
@code{save-selected-window} and @code{with-selected-window} below) are
not recorded thus avoiding to pollute @code{buffer-list-update-hook}.
-Selections that ``really count'' are those causing a visible change in
+Selections that really count are those causing a visible change in
the next redisplay of @var{window}'s frame and should be always
recorded. This also means that to run a function each time a window
gets selected, putting it on @code{buffer-list-update-hook} should be
nor the buffer list.
@end defun
+@cindex window use time
+@cindex use time of window
+@cindex window order by time of last use
+@defun window-use-time &optional window
+This functions returns the use time of window @var{window}.
+@var{window} must be a live window and defaults to the selected one.
+The @dfn{use time} of a window is not really a time value, but it does
+increase monotonically with each window selection, so the window with
+the lowest use time is the least recently selected one, and the
+window with the highest use time is the most recently selected
+one.
+@end defun
+
+
@node Cyclic Window Ordering
@section Cyclic Ordering of Windows
@cindex cyclic ordering of windows
The optional argument @var{minibuf} specifies whether minibuffer windows
should be included in the cyclic ordering. Normally, when @var{minibuf}
is @code{nil}, a minibuffer window is included only if it is currently
-``active''; this matches the behavior of @kbd{C-x o}. (Note that a
+active; this matches the behavior of @kbd{C-x o}. (Note that a
minibuffer window is active as long as its minibuffer is in use; see
@ref{Minibuffers}).
@cindex least recently used window
@defun get-lru-window &optional all-frames dedicated not-selected
-This function returns a live window which is heuristically the ``least
-recently used'' window. The optional argument @var{all-frames} has
+This function returns a live window which is heuristically the least
+recently used. The optional argument @var{all-frames} has
the same meaning as in @code{next-window}.
If any full-width windows are present, only those windows are
function returns @code{nil} in that case.
@end defun
+@cindex most recently used window
+@defun get-mru-window &optional all-frames dedicated not-selected
+This function is like @code{get-lru-window}, but it returns the most
+recently used window instead. The meaning of the arguments is the
+same as described for @code{get-lru-window}.
+@end defun
+
@cindex largest window
@defun get-largest-window &optional all-frames dedicated not-selected
This function returns the window with the largest area (height times
This function returns a list of all windows currently displaying
@var{buffer-or-name}. @var{buffer-or-name} should be a buffer or the
name of an existing buffer. If omitted or @code{nil}, it defaults to
-the current buffer.
+the current buffer. If the currently selected window displays
+@var{buffer-or-name}, it will be the first in the list returned by
+this function.
The arguments @var{minibuf} and @var{all-frames} have the same
meanings as in the function @code{next-window} (@pxref{Cyclic Window
list (@pxref{Buffer List}). However, this is not done if the
optional argument @var{norecord} is non-@code{nil}.
-Sometimes, @code{switch-to-buffer} may be unable to display the buffer
-in the selected window. This happens if the selected window is a
-minibuffer window, or if the selected window is strongly dedicated to
-its buffer (@pxref{Dedicated Windows}). In that case, the command
-normally tries to display the buffer in some other window, by invoking
-@code{pop-to-buffer} (see below). However, if the optional argument
-@var{force-same-window} is non-@code{nil}, it signals an error
-instead.
+Sometimes, the selected window may not be suitable for displaying the
+buffer. This happens if the selected window is a minibuffer window, or
+if the selected window is strongly dedicated to its buffer
+(@pxref{Dedicated Windows}). In such cases, the command normally tries
+to display the buffer in some other window, by invoking
+@code{pop-to-buffer} (see below).
+
+If the optional argument @var{force-same-window} is non-@code{nil} and
+the selected window is not suitable for displaying the buffer, this
+function always signals an error when called non-interactively. In
+interactive use, if the selected window is a minibuffer window, this
+function will try to use some other window instead. If the selected
+window is strongly dedicated to its buffer, the option
+@code{switch-to-buffer-in-dedicated-window} described next can be used
+to proceed.
@end deffn
+@defopt switch-to-buffer-in-dedicated-window
+This option, if non-@code{nil}, allows @code{switch-to-buffer} to
+proceed when called interactively and the selected window is strongly
+dedicated to its buffer.
+
+The following values are respected:
+
+@table @code
+@item nil
+Disallows switching and signals an error as in non-interactive use.
+
+@item prompt
+Prompts the user whether to allow switching.
+
+@item pop
+Invokes @code{pop-to-buffer} to proceed.
+
+@item t
+Marks the selected window as non-dedicated and proceeds.
+@end table
+
+When called non-interactively, @code{switch-to-buffer} always signals an
+error when the selected window is dedicated to its buffer and
+@var{force-same-window} is non-@code{nil}.
+@end defopt
+
By default, @code{switch-to-buffer} shows the buffer at its position of
@code{point}. This behavior can be tuned using the following option.
@defopt display-buffer-base-action
The value of this option should be a display action. This option can
-be used to define a ``standard'' display action for calls to
+be used to define a standard display action for calls to
@code{display-buffer}.
@end defopt
@end defun
@defun display-buffer-reuse-window buffer alist
-This function tries to ``display'' @var{buffer} by finding a window
+This function tries to display @var{buffer} by finding a window
that is already displaying it.
If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry,
is added to the newly created frame's parameters.
@end defun
+@defun display-buffer-use-some-frame buffer alist
+This function tries to display @var{buffer} by trying to find a
+frame that meets a predicate (by default any frame other than the
+current frame).
+
+If this function chooses a window on another frame, it makes that frame
+visible and, unless @var{alist} contains an @code{inhibit-switch-frame}
+entry (@pxref{Choosing Window Options}), raises that frame if necessary.
+
+If @var{alist} has a non-nil @code{frame-predicate} entry, its value is a
+function taking one argument (a frame), returning non-nil if the
+frame is a candidate; this function replaces the default predicate.
+
+If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry,
+the selected window is used; thus if the selected frame has a single
+window, it is not used.
+
+@end defun
+
@defun display-buffer-pop-up-window buffer alist
This function tries to display @var{buffer} by splitting the largest
or least recently-used window (typically one on the selected frame).
(provided *foo* was put by @code{display-buffer} there before) or a
popped-up window as follows: If the window is part of a vertical
combination, it will set its height to ten lines. Note that if, instead
-of the number ``10'', we specified the function
+of the number 10, we specified the function
@code{fit-window-to-buffer}, @code{display-buffer} would come up with a
one-line window to fit the empty buffer. If the window is part of a
horizontal combination, it sets its width to 40 columns. Whether a new
and @code{split-width-threshold} (@pxref{Choosing Window Options}).
Now suppose we combine this call with a preexisting setup for
-`display-buffer-alist' as follows.
+@code{display-buffer-alist} as follows.
@example
@group
selected one is dedicated to its buffer, @code{display-buffer} will
proceed as described in the previous example. Note, however, that when
it tries to adjust the height of any reused or popped-up window, it will
-in any case try to set its number of lines to ``5'' since that value
+in any case try to set its number of lines to 5 since that value
overrides the corresponding specification in the @var{action} argument
of @code{display-buffer}.
to split this way.
@end defopt
+@defopt even-window-sizes
+This variable, if non-nil, causes @code{display-buffer} to even window
+sizes whenever it reuses an existing window and that window is adjacent
+to the selected one.
+
+If its value is @code{width-only}, sizes are evened only if the reused
+window is on the left or right of the selected one and the selected
+window is wider than the reused one. If its value is @code{height-only}
+sizes are evened only if the reused window is above or beneath the
+selected window and the selected window is higher than the reused one.
+Any other non-@code{nil} value means to even sizes in any of these cases
+provided the selected window is larger than the reused one in the sense
+of their combination.
+@end defopt
+
@defopt pop-up-frames
If the value of this variable is non-@code{nil}, that means
@code{display-buffer} may display buffers by making new frames. The
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
+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
position to change in response until after the next redisplay.
@end defun
+@defun window-group-start &optional window
+@vindex window-group-start-function
+This function is like @code{window-start}, except that when
+@var{window} is a part of a group of windows (@pxref{Window Group}),
+@code{window-group-start} returns the start position of the entire
+group. This condition holds when the buffer local variable
+@code{window-group-start-function} is set to a function. In this
+case, @code{window-group-start} calls the function with the single
+argument @var{window}, then returns its result.
+@end defun
+
@cindex window end position
@defun window-end &optional window update
This function returns the position where display of its buffer ends in
text will end if scrolling is not required.
@end defun
+@vindex window-group-end-function
+@defun window-group-end window update
+This function is like @code{window-end}, except that when @var{window}
+is a part of a group of windows (@pxref{Window Group}),
+@code{window-group-end} returns the end position of the entire group.
+This condition holds when the buffer local variable
+@code{window-group-end-function} is set to a function. In this case,
+@code{window-group-end} calls the function with the two arguments
+@var{window} and @var{update}, then returns its result. The argument
+@var{update} has the same meaning as in @code{window-end}.
+@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. It returns @var{position}.
point to the left margin on the middle line in the window.
For example, if point @w{is 1} and you set the start of the window
-@w{to 37}, the start of the next line, point will be ``above'' the top
+@w{to 37}, the start of the next line, point will be above the top
of the window. The display routines will automatically move point if
it is still 1 when redisplay occurs. Here is an example:
position that works well with point, and thus @var{position} is not used.
@end defun
+@vindex set-window-group-start-function
+@defun set-window-group-start window position &optional noforce
+This function is like @code{set-window-start}, except that when
+@var{window} is a part of a group of windows (@pxref{Window Group}),
+@code{set-window-group-start} sets the start position of the entire
+group. This condition holds when the buffer local variable
+@code{set-window-group-start-function} is set to a function. In this
+case, @code{set-window-group-start} calls the function with the three
+arguments @var{window}, @var{position}, and @var{noforce}, then
+returns its result. The arguments @var{position} and @var{noforce} in
+this function have the same meaning as in @code{set-window-start}.
+@end defun
+
@defun pos-visible-in-window-p &optional position window partially
This function returns non-@code{nil} if @var{position} is within the
range of text currently visible on the screen in @var{window}. It
-returns @code{nil} if @var{position} is scrolled vertically out of view.
-Locations that are partially obscured are not considered visible unless
-@var{partially} is non-@code{nil}. The argument @var{position} defaults
-to the current position of point in @var{window}; @var{window}, to the
-selected window. If @var{position} is @code{t}, that means to check the
-last visible position in @var{window}.
+returns @code{nil} if @var{position} is scrolled vertically out of
+view. Locations that are partially obscured are not considered
+visible unless @var{partially} is non-@code{nil}. The argument
+@var{position} defaults to the current position of point in
+@var{window}; @var{window} defaults to the selected window. If
+@var{position} is @code{t}, that means to check either the first
+visible position of the last screen line in @var{window}, or the
+end-of-buffer position, whichever comes first.
This function considers only vertical scrolling. If @var{position} is
out of view only because @var{window} has been scrolled horizontally,
@end example
@end defun
+@vindex pos-visible-in-window-group-p-function
+@defun pos-visible-in-window-group-p &optional position window partially
+This function is like @code{pos-visible-in-window-p}, except that when
+@var{window} is a part of a group of windows (@pxref{Window Group}),
+@code{pos-visible-in-window-group-p} tests the visibility of @var{pos}
+in the entire group, not just in the single @var{window}. This
+condition holds when the buffer local variable
+@code{pos-visible-in-window-group-p-function} is set to a function.
+In this case @code{pos-visible-in-window-group-p} calls the function
+with the three arguments @var{position}, @var{window}, and
+@var{partially}, then returns its result. The arguments
+@var{position} and @var{partially} have the same meaning as in
+@code{pos-visible-in-window-p}.
+@end defun
+
@defun window-line-height &optional line window
This function returns the height of text line @var{line} in
@var{window}. If @var{line} is one of @code{header-line} or
@cindex centering point
This function scrolls the text in the selected window so that point is
displayed at a specified vertical position within the window. It does
-not ``move point'' with respect to the text.
+not move point with respect to the text.
If @var{count} is a non-negative number, that puts the line containing
point @var{count} lines down from the top of the window. If
a more convenient way to achieve this.
@end deffn
+@vindex recenter-group-function
+@defun recenter-group &optional count
+This function is like @code{recenter}, except that when the selected
+window is part of a group of windows (@pxref{Window Group}),
+@code{recenter-group} scrolls the entire group. This condition holds
+when the buffer local variable @code{recenter-group-function} is set
+to a function. In this case, @code{recenter-group} calls the function
+with the argument @var{count}, then returns its result. The argument
+@var{count} has the same meaning as in @code{recenter}, but with
+respect to the entire window group.
+@end defun
+
@defopt recenter-redisplay
If this variable is non-@code{nil}, calling @code{recenter} with a
@code{nil} argument redraws the frame. The default value is
disappear off to the left depends on their width, and could vary from
line to line.
- Because we read from side to side in the ``inner loop'', and from top
-to bottom in the ``outer loop'', the effect of horizontal scrolling is
+ Because we read from side to side in the inner loop, and from top
+to bottom in the outer loop, the effect of horizontal scrolling is
not like that of textual or vertical scrolling. Textual scrolling
involves selection of a portion of text to display, and vertical
scrolling moves the window contents contiguously; but horizontal
@end group
@end example
+
@node Coordinates and Windows
@section Coordinates and Windows
@cindex frame-relative coordinate
@cindex coordinate, relative to frame
@cindex window position
- This section describes functions that report the position of a
-window. Most of these functions report positions relative to the
-window's frame. In this case, the coordinate origin @samp{(0,0)} lies
-near the upper left corner of the frame. For technical reasons, on
-graphical displays the origin is not located at the exact corner of
-the graphical window as it appears on the screen. If Emacs is built
-with the GTK+ toolkit, the origin is at the upper left corner of the
-frame area used for displaying Emacs windows, below the title-bar,
-GTK+ menu bar, and tool bar (since these are drawn by the window
-manager and/or GTK+, not by Emacs). But if Emacs is not built with
-GTK+, the origin is at the upper left corner of the tool bar (since in
-this case Emacs itself draws the tool bar). In both cases, the X and
-Y coordinates increase rightward and downward respectively.
-
- Except where noted, X and Y coordinates are reported in integer
-character units, i.e., numbers of lines and columns respectively. On a
-graphical display, each ``line'' and ``column'' corresponds to the
-height and width of a default character specified by the frame's
-default font.
-
-@defun window-edges &optional window
+This section describes functions that report the position of a window.
+Most of these functions report positions relative to an origin at the
+native position of the window's frame (@pxref{Frame Geometry}). Some
+functions report positions relative to the origin of the display of the
+window's frame. In any case, the origin has the coordinates (0, 0) and
+X and Y coordinates increase rightward and downward
+respectively.
+
+ For the following functions, X and Y coordinates are reported in
+integer character units, i.e., numbers of lines and columns
+respectively. On a graphical display, each ``line'' and ``column''
+corresponds to the height and width of the default character specified by
+the frame's default font (@pxref{Frame Font}).
+
+@defun window-edges &optional window body absolute pixelwise
This function returns a list of the edge coordinates of @var{window}.
If @var{window} is omitted or @code{nil}, it defaults to the selected
window.
margins. On a text terminal, if the window has a neighbor on its right,
its right edge includes the separator line between the window and its
neighbor.
-@end defun
-@defun window-inside-edges &optional window
-This function is similar to @code{window-edges}, but the returned edge
-values are for the text area of the window. They exclude any header
-line, mode line, scroll bar, fringes, window divider, display margins,
-and vertical separator.
+If the optional argument @var{body} is @code{nil}, this means to
+return the edges corresponding to the total size of @var{window}.
+@var{body} non-@code{nil} means to return the edges of @var{window}'s
+body (aka text area). If @var{body} is non-@code{nil}, @var{window}
+must specify a live window.
+
+If the optional argument @var{absolute} is @code{nil}, this means to
+return edges relative to the native position of @var{window}'s frame.
+@var{absolute} non-@code{nil} means to return coordinates relative to
+the origin (0, 0) of @var{window}'s display. On non-graphical systems
+this argument has no effect.
+
+If the optional argument @var{pixelwise} is @code{nil}, this means to
+return the coordinates in terms of the default character width and
+height of @var{window}'s frame (@pxref{Frame Font}), rounded if
+necessary. @var{pixelwise} non-@code{nil} means to return the
+coordinates in pixels. Note that the pixel specified by @var{right} and
+@var{bottom} is immediately outside of these edges. If @var{absolute}
+is non-@code{nil}, @var{pixelwise} is implicitly non-@code{nil} too.
@end defun
-@defun window-top-line &optional window
-This function returns the Y coordinate of the topmost row of
-@var{window}, equivalent to the @var{top} entry in the list returned
-by @code{window-edges}.
+@defun window-body-edges &optional window
+This function returns the edges of @var{window}'s body (@pxref{Window
+Sizes}). Calling @code{(window-body-edges window)} is equivalent to
+calling @code{(window-edges window t)}, see above.
@end defun
+@comment The following two functions are confusing and hardly used.
+@ignore
@defun window-left-column &optional window
-This function returns the X coordinate of the leftmost column of
-@var{window}, equivalent to the @var{left} entry in the list returned
-by @code{window-edges}.
+This function returns the leftmost column of @var{window}. This value
+equals the @var{left} entry in the list returned by @code{(window-edges
+window)} minus the number of columns occupied by the internal border of
+@var{window}'s frame.
+@end defun
+
+@defun window-top-line &optional window
+This function returns the topmost row of @var{window}. This value is
+equal to the @var{top} entry in the list returned by @code{(window-edges
+window)} minus the number of lines occupied by the internal border of
+@var{window}'s frame.
@end defun
+@end ignore
The following functions can be used to relate a set of
frame-relative coordinates to a window:
@defun window-at x y &optional frame
-This function returns the live window at the frame-relative
-coordinates @var{x} and @var{y}, on frame @var{frame}. If there is no
-window at that position, the return value is @code{nil}. If
-@var{frame} is omitted or @code{nil}, it defaults to the selected
+This function returns the live window at the coordinates @var{x} and
+@var{y} given in default character sizes (@pxref{Frame Font}) relative
+to the native position of @var{frame} (@pxref{Frame Geometry}).
+
+If there is no window at that position, the return value is @code{nil}.
+If @var{frame} is omitted or @code{nil}, it defaults to the selected
frame.
@end defun
@defun coordinates-in-window-p coordinates window
-This function checks whether a window @var{window} occupies the
-frame-relative coordinates @var{coordinates}, and if so, which part of
-the window that is. @var{window} should be a live window.
+This function checks whether a window @var{window} occupies the frame
+relative coordinates @var{coordinates}, and if so, which part of the
+window that is. @var{window} should be a live window.
+
@var{coordinates} should be a cons cell of the form @code{(@var{x}
-. @var{y})}, where @var{x} and @var{y} are frame-relative coordinates.
+. @var{y})}, where @var{x} and @var{y} are given in default character
+sizes (@pxref{Frame Font}) relative to the native position of
+@var{window}'s frame (@pxref{Frame Geometry}).
If there is no window at the specified position, the return value is
@code{nil} . Otherwise, the return value is one of the following:
The coordinates are in the divider separating @var{window} from a
window on the right.
-@item right-divider
+@item bottom-divider
The coordinates are in the divider separating @var{window} from a
window beneath.
The following functions return window positions in pixels, rather
than character units. Though mostly useful on graphical displays,
they can also be called on text terminals, where the screen area of
-each text character is taken to be ``one pixel''.
+each text character is taken to be one pixel.
@defun window-pixel-edges &optional window
This function returns a list of pixel coordinates for the edges of
-@var{window}. If @var{window} is omitted or @code{nil}, it defaults
-to the selected window.
+@var{window}. Calling @code{(window-pixel-edges window)} is equivalent
+to calling @code{(window-edges window nil nil t)}, see above.
+@end defun
-The return value has the form @code{(@var{left} @var{top} @var{right}
-@var{bottom})}. The list elements are, respectively, the X pixel
-coordinate of the left window edge, the Y pixel coordinate of the top
-edge, one more than the X pixel coordinate of the right edge, and one
-more than the Y pixel coordinate of the bottom edge.
+@comment The following two functions are confusing and hardly used.
+@ignore
+@defun window-pixel-left &optional window
+This function returns the left pixel edge of window @var{window}. This
+value equals the @var{left} entry in the list returned by
+@code{(window-pixel-edges window)} minus the number of pixels occupied
+by the internal border of @var{window}'s frame. @var{window} must be a
+valid window and defaults to the selected one.
@end defun
-@defun window-inside-pixel-edges &optional window
-This function is like @code{window-pixel-edges}, except that it
-returns the pixel coordinates for the edges of the window's text area,
-rather than the pixel coordinates for the edges of the window itself.
-@var{window} must specify a live window.
+@defun window-pixel-top &optional window
+This function returns the top pixel edge of window @var{window}. This
+value is equal to the @var{top} entry in the list returned by
+@code{(window-pixel-edges window)} minus the number of pixels occupied
+by the internal border of @var{window}'s frame. @var{window} must be a
+valid window and defaults to the selected one.
@end defun
+@end ignore
- The following functions return window positions in pixels, relative
-to the display screen rather than the frame:
+@defun window-body-pixel-edges &optional window
+This function returns the pixel edges of @var{window}'s body. Calling
+@code{(window-body-pixel-edges window)} is equivalent to calling
+@code{(window-edges window t nil t)}, see above.
+@end defun
+
+ The following functions return window positions in pixels, relative to
+the origin of the display screen rather than that of the frame:
@defun window-absolute-pixel-edges &optional window
-This function is like @code{window-pixel-edges}, except that it
-returns the edge pixel coordinates relative to the top left corner of
-the display screen.
+This function returns the pixel coordinates of @var{WINDOW} relative to
+an origin at (0, 0) of the display of @var{window}'s frame. Calling
+@code{(window-absolute-pixel-edges)} is equivalent to calling
+@code{(window-edges window nil t t)}, see above.
@end defun
-@defun window-inside-absolute-pixel-edges &optional window
-This function is like @code{window-inside-pixel-edges}, except that it
-returns the edge pixel coordinates relative to the top left corner of
-the display screen. @var{window} must specify a live window.
-@end defun
+@defun window-absolute-body-pixel-edges &optional window
+This function returns the pixel coordinates of @var{WINDOW}'s body
+relative to an origin at (0, 0) of the display of @var{window}'s frame.
+Calling @code{(window-absolute-body-pixel-edges window)} is equivalent
+to calling @code{(window-edges window t t t)}, see above.
-@defun window-pixel-left &optional window
-This function returns the left pixel edge of window @var{window}.
-@var{window} must be a valid window and defaults to the selected one.
+Combined with @code{set-mouse-absolute-pixel-position}, this function
+can be used to move the mouse pointer to an arbitrary buffer position
+visible in some window:
+
+@example
+@group
+(let ((edges (window-absolute-body-pixel-edges))
+ (position (pos-visible-in-window-p nil nil t)))
+ (set-mouse-absolute-pixel-position
+ (+ (nth 0 edges) (nth 0 position))
+ (+ (nth 1 edges) (nth 1 position))))
+@end group
+@end example
+
+On a graphical terminal this form ``warps'' the mouse cursor to the
+upper left corner of the glyph at the selected window's point. A
+position calculated this way can be also used to show a tooltip window
+there.
@end defun
-@defun window-pixel-top &optional window
-This function returns the top pixel edge of window @var{window}.
-@var{window} must be a valid window and defaults to the selected one.
+The following function returns the screen coordinates of a buffer
+position visible in a window:
+
+@defun window-absolute-pixel-position &optional position window
+If the buffer position @var{position} is visible in window @var{window},
+this function returns the display coordinates of the upper/left corner
+of the glyph at @var{position}. The return value is a cons of the X-
+and Y-coordinates of that corner, relative to an origin at (0, 0) of
+@var{window}'s display. It returns @code{nil} if @var{position} is not
+visible in @var{window}.
+
+@var{window} must be a live window and defaults to the selected
+window. @var{position} defaults to the value of @code{window-point}
+of @var{window}.
+
+This means that in order to move the mouse pointer to the position of
+point in the selected window, it's sufficient to write:
+
+@example
+@group
+(let ((position (window-absolute-pixel-position)))
+ (set-mouse-absolute-pixel-position
+ (car position) (cdr position)))
+@end group
+@end example
@end defun
@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.
+This variable holds a list of functions to be called if the size of
+any window changes for any reason. The functions are called at the
+beginning of a redisplay cycle, 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