@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Windows
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
If the optional argument @var{wrap} is non-@code{nil}, this means to
wrap @var{direction} around frame borders. For example, if @var{window}
is at the top of the frame and @var{direction} is @code{above}, then
-return the minibuffer window provided the frame has one, and a window at
-the bottom of the frame otherwise.
+this function usually returns the frame's minibuffer window if it's
+active and a window at the bottom of the frame otherwise.
If the optional argument @var{mini} is @code{nil}, this means to return
the minibuffer window if and only if it is currently active. If
-@var{mini} is non-@code{nil}, it returns the minibuffer window even when
-it's not active. However, if @var{wrap} non-@code{nil}, it always acts
-as if @var{mini} were @code{nil}.
+@var{mini} is non-@code{nil}, this function may return the minibuffer
+window even when it's not active. However, if @var{wrap} is
+non-@code{nil}, it always acts as if @var{mini} were @code{nil}.
If it doesn't find a suitable window, this function returns @code{nil}.
@end defun
-The following function allows to retrieve the entire window tree of a
-frame:
+The following function allows the entire window tree of a frame to be
+retrieved:
@defun window-tree &optional frame
This function returns a list representing the window tree for frame
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{Frame Font}). Thus, if a window is displaying text with a
different font or size, the reported line height and column width for
children.
@end defun
-@cindex window pixel height
-@cindex pixel height of a window
-@cindex total pixel height of a window
+@defun window-pixel-height-before-size-change &optional Lisp_Object &optional window
+This function returns the height of window @var{window} in pixels at the
+time @code{window-size-change-functions} was run for the last time on
+@var{window}'s frame (@pxref{Window Hooks}).
+@end defun
+
+@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.
the screen areas spanned by its children.
@end defun
+@defun window-pixel-width-before-size-change &optional Lisp_Object &optional window
+This function returns the width of window @var{window} in pixels at the
+time @code{window-size-change-functions} was run for the last time on
+@var{window}'s frame (@pxref{Window Hooks}).
+@end defun
+
@cindex full-width window
@cindex full-height window
The following functions can be used to determine whether a given
@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 face @var{face} in the specified window @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 @var{face}'s font, instead of working in units of the canonical
+character width of @var{window}'s frame (@pxref{Frame Font}). 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.
The following function tells how small a specific window can get taking
into account the sizes of its areas and the values of
@code{window-min-height}, @code{window-min-width} and
-@code{window-size-fixed}.
+@code{window-size-fixed} (@pxref{Preserving Window Sizes}).
@defun window-min-size &optional window horizontal ignore pixelwise
This function returns the minimum size of @var{window}. @var{window}
The return value makes sure that all components of @var{window} remain
fully visible if @var{window}'s size were actually set to it. With
@var{horizontal} @code{nil} it includes the mode and header line, the
-horizontal scroll bar and the bottom divider. With @var{horizontal}
-non-@code{nil} it includes the fringes, a scroll bar, and a right
-divider, if present. It does not, however, include the space reserved
-for the margins.
+horizontal scroll bar and the bottom divider, if present. With
+@var{horizontal} non-@code{nil} it includes the margins and fringes, the
+vertical scroll bar and the right divider, if present.
The optional argument @var{ignore}, if non-@code{nil}, means ignore
restrictions imposed by fixed size windows, @code{window-min-height} or
@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
By default, the space taken up by @var{window} is given to one of its
adjacent sibling windows, if any. However, if the variable
@code{window-combination-resize} is non-@code{nil}, the space is
-proportionally distributed among any remaining windows in the window
-combination. @xref{Recombining Windows}.
+proportionally distributed among any remaining windows in the same
+window combination. @xref{Recombining Windows}.
The behavior of this function may be altered by the window parameters
of @var{window}, so long as the variable
you want to continue working with the initial layout.
The behavior can be fixed by making a new parent window when splitting
-@var{W2}. The variable described next allows to do that.
+@var{W2}. The variable described next allows that to be done.
@defopt window-combination-limit
This variable controls whether splitting a window shall make a new
Alternatively, the problems sketched above can be avoided by always
resizing all windows in the same combination whenever one of its windows
-is split or deleted. This also permits to split windows that would be
+is split or deleted. This also permits splitting windows that would be
otherwise too small for such an operation.
@defopt window-combination-resize
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 an
+integer that does increase monotonically with each call of
+@code{select-window} with a @code{nil} @var{norecord} argument. The
+window with the lowest use time is usually called the least recently
+used window while the window with the highest use time is called the
+most recently used one (@pxref{Cyclic Window Ordering}).
+@end defun
+
+
@node Cyclic Window Ordering
@section Cyclic Ordering of Windows
@cindex cyclic ordering of windows
For any given configuration of windows, this order never varies. It
is called the @dfn{cyclic ordering of windows}.
- The ordering is determined by a depth-first traversal of the frame's
-window tree, retrieving the live windows which are the leaf nodes of
-the tree (@pxref{Windows and Frames}). If the minibuffer is active,
-the minibuffer window is included too. The ordering is cyclic, so the
-last window in the sequence is followed by the first one.
+ The ordering is determined by a depth-first traversal of each frame's
+window tree, retrieving the live windows which are the leaf nodes of the
+tree (@pxref{Windows and Frames}). If the minibuffer is active, the
+minibuffer window is included too. The ordering is cyclic, so the last
+window in the sequence is followed by the first one.
@defun next-window &optional window minibuf all-frames
@cindex minibuffer window, and @code{next-window}
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
@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
+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
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}.
+This option does not affect non-interactive calls of
+@code{switch-to-buffer}.
@end defopt
By default, @code{switch-to-buffer} shows the buffer at its position of
@deffn Command pop-to-buffer buffer-or-name &optional action norecord
This function makes @var{buffer-or-name} the current buffer and
-displays it in some window, preferably not the window previously
+displays it in some window, preferably not the window currently
selected. It then selects the displaying window. If that window is
on a different graphical frame, that frame is given input focus if
possible (@pxref{Input Focus}). The return value is the buffer that
@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,
@end defun
@defun display-buffer-use-some-frame buffer alist
-This function tries to ``display'' @var{buffer} by trying to find a
+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).
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{frame-predicate} entry, its
+value is a function taking one argument (a frame), returning
+non-@code{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
@defun display-buffer-no-window buffer alist
If @var{alist} has a non-@code{nil} @code{allow-no-window} entry, then
-this function does not display @code{buffer}. This allows to override
-the default action and avoid displaying the buffer. It is assumed that
-when the caller specifies a non-@code{nil} @code{allow-no-window} value
-it can handle a @code{nil} value returned from @code{display-buffer} in
-this case.
+this function does not display @code{buffer}. This allows you to
+override the default action and avoid displaying the buffer. It is
+assumed that when the caller specifies a non-@code{nil}
+@code{allow-no-window} value it can handle a @code{nil} value returned
+from @code{display-buffer} in this case.
@end defun
To illustrate the use of action functions, consider the following
(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
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}.
desired buffer) or @code{nil} (which means the splitting failed).
@end defopt
-@defun split-window-sensibly window
-This function tries to split @var{window}, and return the newly
-created window. If @var{window} cannot be split, it returns
-@code{nil}.
+@defun split-window-sensibly &optional window
+This function tries to split @var{window}, and return the newly created
+window. If @var{window} cannot be split, it returns @code{nil}. If
+@var{window} is omitted or @code{nil}, it defaults to the selected
+window.
This function obeys the usual rules that determine when a window may
be split (@pxref{Splitting Windows}). It first tries to split by
@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.
+This variable, if non-@code{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
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 &optional 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-window-group-function
+@defun recenter-window-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-window-group} scrolls the entire group. This condition
+holds when the buffer local variable
+@code{recenter-window-group-function} is set to a function. In this
+case, @code{recenter-window-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
effect after the change---just like the value returned by
@code{window-hscroll} (below).
+Note that text in paragraphs whose base direction is right-to-left
+(@pxref{Bidirectional Display}) moves in the opposite direction: e.g.,
+it moves to the right when @code{scroll-left} is invoked with a
+positive value of @var{count}.
+
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
any farther right have no effect.
@defun window-hscroll &optional window
This function returns the total leftward horizontal scrolling of
@var{window}---the number of columns by which the text in @var{window}
-is scrolled left past the left margin. The default for
-@var{window} is the selected window.
+is scrolled left past the left margin. (In right-to-left paragraphs,
+the value is the total amount of the rightward scrolling instead.)
+The default for @var{window} is the selected window.
The return value is never negative. It is zero when no horizontal
scrolling has been done in @var{window} (which is usually the case).
@defun set-window-hscroll window columns
This function sets horizontal scrolling of @var{window}. The value of
@var{columns} specifies the amount of scrolling, in terms of columns
-from the left margin. The argument @var{columns} should be zero or
-positive; if not, it is taken as zero. Fractional values of
-@var{columns} are not supported at present.
+from the left margin (right margin in right-to-left paragraphs). The
+argument @var{columns} should be zero or positive; if not, it is taken
+as zero. Fractional values of @var{columns} are not supported at
+present.
Note that @code{set-window-hscroll} may appear not to work if you test
it by evaluating a call with @kbd{M-:} in a simple way. What happens
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''
+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 a default character specified by
+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
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
@group
(let ((edges (window-absolute-body-pixel-edges))
(position (pos-visible-in-window-p nil nil t)))
- (x-set-mouse-absolute-pixel-position
+ (set-mouse-absolute-pixel-position
(+ (nth 0 edges) (nth 0 position))
(+ (nth 1 edges) (nth 1 position))))
@end group
The argument @var{configuration} must be a value that was previously
returned by @code{current-window-configuration}. The configuration is
restored in the frame from which @var{configuration} was made, whether
-that frame is selected or not. This always counts as a window size
-change and triggers execution of the @code{window-size-change-functions}
-(@pxref{Window Hooks}), because @code{set-window-configuration} doesn't
-know how to tell whether the new configuration actually differs from the
-old one.
+that frame is selected or not. In some rare cases this may trigger
+execution of the @code{window-size-change-functions} (@pxref{Window
+Hooks}) even if the size of windows did not change at all. The
+@code{window-configuration-change-hook} functions will be called if and
+only if at least one window was added to or deleted from the frame.
If the frame from which @var{configuration} was saved is dead, all this
function does is restore the three variables @code{window-min-height},
@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.
+window changes for any reason. The functions are called once per
+redisplay, and once for each frame on which size changes have occurred.
+
+Each function receives the frame as its sole argument. To find out
+whether a specific window has changed size, compare the return values of
+@code{window-pixel-width-before-size-change} and
+@code{window-pixel-width} respectively
+@code{window-pixel-height-before-size-change} and
+@code{window-pixel-height} for that window (@pxref{Window Sizes}).
+
+These function are usually only called when at least one window was
+added or has changed size since the last time this hook was run for the
+associated frame. In some rare cases this hook also runs when a window
+that was added intermittently has been deleted afterwards. In these
+cases none of the windows on the frame will appear to have changed its
+size.
You may use @code{save-selected-window} in these functions
(@pxref{Selecting Windows}). However, do not use
@code{save-window-excursion} (@pxref{Window Configurations}); exiting
-that macro counts as a size change, which would cause these functions
-to be called over and over.
+that macro counts as a size change, which would cause these functions to
+be called again.
@end defvar
@defvar window-configuration-change-hook
-A normal hook that is run every time you change the window configuration
-of an existing frame. This includes splitting or deleting windows,
-changing the sizes of windows, or displaying a different buffer in a
-window.
+A normal hook that is run every time the window configuration of a frame
+changes. Window configuration changes include splitting and deleting
+windows and the display of a different buffer in a window. Resizing the
+frame or individual windows do not count as configuration changes. Use
+@code{window-size-change-functions}, see above, when you want to track
+size changes that are not caused by the deletion or creation of windows.
The buffer-local part of this hook is run once for each window on the
affected frame, with the relevant window selected and its buffer