@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
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
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
@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.
+
+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
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}
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
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
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
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}.
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
@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
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
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
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