@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Windows
@chapter Windows
* Windows and Frames:: Relating windows to the frame they appear on.
* Window Sizes:: Accessing a window's size.
* Resizing Windows:: Changing the sizes of windows.
+* Preserving Window Sizes:: Preserving the size of windows.
* Splitting Windows:: Creating a new window.
* Deleting Windows:: Removing a window from its frame.
* Recombining Windows:: Preserving the frame layout when splitting and
@section Basic Concepts of Emacs Windows
@cindex window
-A @dfn{window} is a area of the screen that is used to display a
-buffer (@pxref{Buffers}). In Emacs Lisp, windows are represented by a
-special Lisp object type.
+A @dfn{window} is an area of the screen that is used to display a buffer
+(@pxref{Buffers}). In Emacs Lisp, windows are represented by a special
+Lisp object type.
@cindex multiple windows
Windows are grouped into frames (@pxref{Frames}). Each frame
@cindex valid windows
A @dfn{valid window} is one that is either live or internal. A valid
-window can be @dfn{deleted}, i.e. removed from its frame
+window can be @dfn{deleted}, i.e., removed from its frame
(@pxref{Deleting Windows}); then it is no longer valid, but the Lisp
object representing it might be still referenced from other Lisp
objects. A deleted window may be made valid again by restoring a saved
Each window belongs to exactly one frame (@pxref{Frames}).
-@defun window-frame window
+@defun window-frame &optional window
This function returns the frame that the window @var{window} belongs
to. If @var{window} is @code{nil}, it defaults to the selected
window.
This function returns the parent window of @var{window}. If
@var{window} is omitted or @code{nil}, it defaults to the selected
window. The return value is @code{nil} if @var{window} has no parent
-(i.e. it is a minibuffer window or the root window of its frame).
+(i.e., it is a minibuffer window or the root window of its frame).
@end defun
Each internal window always has at least two child windows. If this
@end smallexample
@noindent
-The root window of this frame is an internal window, @code{W1}. Its
+The root window of this frame is an internal window, @var{W1}. Its
child windows form a horizontal combination, consisting of the live
-window @code{W2} and the internal window @code{W3}. The child windows
-of @code{W3} form a vertical combination, consisting of the live
-windows @code{W4} and @code{W5}. Hence, the live windows in this
-window tree are @code{W2} @code{W4}, and @code{W5}.
+window @var{W2} and the internal window @var{W3}. The child windows
+of @var{W3} form a vertical combination, consisting of the live
+windows @var{W4} and @var{W5}. Hence, the live windows in this
+window tree are @var{W2}, @var{W4}, and @var{W5}.
The following functions can be used to retrieve a child window of an
internal window, and the siblings of a child window.
-@defun window-top-child window
+@defun window-top-child &optional window
This function returns the topmost child window of @var{window}, if
@var{window} is an internal window whose children form a vertical
combination. For any other type of window, the return value is
@code{nil}.
@end defun
-@defun window-left-child window
+@defun window-left-child &optional window
This function returns the leftmost child window of @var{window}, if
@var{window} is an internal window whose children form a horizontal
combination. For any other type of window, the return value is
and previous window, respectively, in the cyclic ordering of windows
(@pxref{Cyclic Window Ordering}).
- You can use the following functions to find the first live window on
-a frame, and to retrieve the entire window tree of a frame:
+ You can use the following functions to find the first live window on a
+frame and the window nearest to a given window.
@defun frame-first-window &optional frame-or-window
This function returns the live window at the upper left corner of the
to the selected frame. If @var{frame-or-window} specifies a window,
this function returns the first window on that window's frame. Under
the assumption that the frame from our canonical example is selected
-@code{(frame-first-window)} returns @code{W2}.
+@code{(frame-first-window)} returns @var{W2}.
@end defun
+@cindex window in direction
+@defun window-in-direction direction &optional window ignore sign wrap mini
+This function returns the nearest live window in direction
+@var{direction} as seen from the position of @code{window-point} in
+window @var{window}. The argument @var{direction} must be one of
+@code{above}, @code{below}, @code{left} or @code{right}. The optional
+argument @var{window} must denote a live window and defaults to the
+selected one.
+
+This function does not return a window whose @code{no-other-window}
+parameter is non-@code{nil} (@pxref{Window Parameters}). If the nearest
+window's @code{no-other-window} parameter is non-@code{nil}, this
+function tries to find another window in the indicated direction whose
+@code{no-other-window} parameter is @code{nil}. If the optional
+argument @var{ignore} is non-@code{nil}, a window may be returned even
+if its @code{no-other-window} parameter is non-@code{nil}.
+
+If the optional argument @var{sign} is a negative number, it means to
+use the right or bottom edge of @var{window} as reference position
+instead of @code{window-point}. If @var{sign} is a positive number, it
+means to use the left or top edge of @var{window} as reference position.
+
+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.
+
+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}.
+
+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:
+
@defun window-tree &optional frame
This function returns a list representing the window tree for frame
@var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to
@code{window-edges} (@pxref{Coordinates and Windows}).
@end defun
+
@node Window Sizes
@section Window Sizes
@cindex window size
@smallexample
@group
- _________________________________________
- ^ |______________ Header Line_______________|
- | |LS|LF|LM| |RM|RF|RS| ^
- | | | | | | | | | |
- Window | | | | Text Area | | | | Window
- Total | | | | (Window Body) | | | | Body
- Height | | | | | | | | Height
- | | | | |<- Window Body Width ->| | | | |
- | |__|__|__|_______________________|__|__|__| v
- v |_______________ Mode Line _______________|
-
- <----------- Window Total Width -------->
+ ____________________________________________
+ |______________ Header Line ______________|RD| ^
+ ^ |LS|LM|LF| |RF|RM|RS| | |
+ | | | | | | | | | | |
+Window | | | | Text Area | | | | | Window
+Body | | | | | (Window Body) | | | | | Total
+Height | | | | | | | | | Height
+ | | | | |<- Window Body Width ->| | | | | |
+ v |__|__|__|_______________________|__|__|__| | |
+ |_________ Horizontal Scroll Bar _________| | |
+ |_______________ Mode Line _______________|__| |
+ |_____________ Bottom Divider _______________| v
+ <---------- Window Total Width ------------>
@end group
@end smallexample
@cindex text area of a window
@cindex body of a window
At the center of the window is the @dfn{text area}, or @dfn{body},
-where the buffer text is displayed. On each side of the text area is
-a series of vertical areas; from innermost to outermost, these are the
-left and right margins, denoted by LM and RM in the schematic
-(@pxref{Display Margins}); the left and right fringes, denoted by LF
-and RF (@pxref{Fringes}); and the left or right scroll bar, only one of
-which is present at any time, denoted by LS and RS (@pxref{Scroll
-Bars}). At the top of the window is an optional header line
-(@pxref{Header Lines}), and at the bottom of the window is the mode
-line (@pxref{Mode Line Format}).
-
- Emacs provides several functions for finding the height and width of
-a window. Except where noted, Emacs reports window heights and widths
-as integer numbers of lines and columns, respectively. On a graphical
-display, each ``line'' and ``column'' actually corresponds to the
-height and width of a ``default'' character specified by the frame's
-default font. Thus, if a window is displaying text with a different
-font or size, the reported height and width for that window may differ
-from the actual number of text lines or columns displayed within it.
+where the buffer text is displayed. The text area can be surrounded by
+a series of optional areas. On the left and right, from innermost to
+outermost, these are the left and right fringes, denoted by LF and RF
+(@pxref{Fringes}); the left and right margins, denoted by LM and RM in
+the schematic (@pxref{Display Margins}); the left or right vertical
+scroll bar, only one of which is present at any time, denoted by LS and
+RS (@pxref{Scroll Bars}); and the right divider, denoted by RD
+(@pxref{Window Dividers}). At the top of the window is the header line
+(@pxref{Header Lines}). At the bottom of the window are the horizontal
+scroll bar (@pxref{Scroll Bars}); the mode line (@pxref{Mode Line
+Format}); and the bottom divider (@pxref{Window Dividers}).
+
+ Emacs provides miscellaneous functions for finding the height and
+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
+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
+that window may differ from the actual number of text lines or columns
+displayed within it.
@cindex window height
@cindex height of a window
@cindex total height of a window
+ The @dfn{total height} of a window is the number of lines comprising
+the window's body, the header line, the horizontal scroll bar, the mode
+line and the bottom divider (if any).
+
+@defun window-total-height &optional window round
+This function returns the total height, in lines, of the window
+@var{window}. If @var{window} is omitted or @code{nil}, it defaults to
+the selected window. If @var{window} is an internal window, the return
+value is the total height occupied by its descendant windows.
+
+ If a window's pixel height is not an integral multiple of its frame's
+default character height, the number of lines occupied by the window is
+rounded internally. This is done in a way such that, if the window is a
+parent window, the sum of the total heights of all its child windows
+internally equals the total height of their parent. This means that
+although two windows have the same pixel height, their internal total
+heights may differ by one line. This means also, that if window is
+vertically combined and has a next sibling, the topmost row of that
+sibling can be calculated as the sum of this window's topmost row and
+total height (@pxref{Coordinates and Windows})
+
+ If the optional argument @var{round} is @code{ceiling}, this
+function returns the smallest integer larger than @var{window}'s pixel
+height divided by the character height of its frame; if it is
+@code{floor}, it returns the largest integer smaller than said value;
+with any other @var{round} it returns the internal value of
+@var{windows}'s total height.
+@end defun
+
@cindex window width
@cindex width of a window
@cindex total width of a window
- The @dfn{total height} of a window is the distance between the top
-and bottom of the window, including the header line (if one exists)
-and the mode line. The @dfn{total width} of a window is the distance
-between the left and right edges of the mode line. Note that the
-height of a frame is not the same as the height of its windows, since
-a frame may also contain an echo area, menu bar, and tool bar
-(@pxref{Size and Position}).
+The @dfn{total width} of a window is the number of lines comprising the
+window's body, its margins, fringes, scroll bars and a right divider (if
+any).
-@defun window-total-height &optional window
-This function returns the total height, in lines, of the window
-@var{window}. If @var{window} is omitted or @code{nil}, it defaults
-to the selected window. If @var{window} is an internal window, the
-return value is the total height occupied by its descendant windows.
+@defun window-total-width &optional window round
+This function returns the total width, in columns, of the window
+@var{window}. If @var{window} is omitted or @code{nil}, it defaults to
+the selected window. If @var{window} is internal, the return value is
+the total width occupied by its descendant windows.
+
+ If a window's pixel width is not an integral multiple of its frame's
+character width, the number of lines occupied by the window is rounded
+internally. This is done in a way such that, if the window is a parent
+window, the sum of the total widths of all its children internally
+equals the total width of their parent. This means that although two
+windows have the same pixel width, their internal total widths may
+differ by one column. This means also, that if this window is
+horizontally combined and has a next sibling, the leftmost column of
+that sibling can be calculated as the sum of this window's leftmost
+column and total width (@pxref{Coordinates and Windows}). The optional
+argument @var{round} behaves as it does for @code{window-total-height}.
@end defun
-@defun window-total-width &optional window
-This function returns the total width, in columns, of the window
-@var{window}. If @var{window} is omitted or @code{nil}, it defaults
-to the selected window. If @var{window} is internal, the return value
-is the total width occupied by its descendant windows.
+@defun window-total-size &optional window horizontal round
+This function returns either the total height in lines or the total
+width in columns of the window @var{window}. If @var{horizontal} is
+omitted or @code{nil}, this is equivalent to calling
+@code{window-total-height} for @var{window}; otherwise it is equivalent
+to calling @code{window-total-width} for @var{window}. The optional
+argument @var{round} behaves as it does for @code{window-total-height}.
+@end defun
+
+The following two functions can be used to return the total size of a
+window in units of pixels.
+
+@cindex window pixel height
+@cindex pixel height of a window
+@cindex total pixel height of a window
+
+@defun window-pixel-height &optional window
+This function returns the total height of window @var{window} in pixels.
+@var{window} must be a valid window and defaults to the selected one.
+
+The return value includes mode and header line, a horizontal scroll bar
+and a bottom divider, if any. If @var{window} is an internal window,
+its pixel height is the pixel height of the screen areas spanned by its
+children.
@end defun
-@defun window-total-size &optional window horizontal
-This function returns either the total height or width of the window
-@var{window}. If @var{horizontal} is omitted or @code{nil}, this is
-equivalent to calling @code{window-total-height} for @var{window};
-otherwise it is equivalent to calling @code{window-total-width} for
-@var{window}.
+@cindex window pixel height
+@cindex pixel height of a window
+@cindex total pixel height of a window
+
+@defun window-pixel-width &optional Lisp_Object &optional window
+This function returns the width of window @var{window} in pixels.
+@var{window} must be a valid window and defaults to the selected one.
+
+The return value includes the fringes and margins of @var{window} as
+well as any vertical dividers or scroll bars belonging to @var{window}.
+If @var{window} is an internal window, its pixel width is the width of
+the screen areas spanned by its children.
@end defun
@cindex full-width window
window has any adjacent windows.
@defun window-full-height-p &optional window
-This function returns non-@code{nil} if @var{window} has no other
-window above or below it in its frame, i.e. its total height equals
-the total height of the root window on that frame. If @var{window} is
-omitted or @code{nil}, it defaults to the selected window.
+This function returns non-@code{nil} if @var{window} has no other window
+above or below it in its frame. More precisely, this means that the
+total height of @var{window} equals the total height of the root window
+on that frame. The minibuffer window does not count in this regard. If
+@var{window} is omitted or @code{nil}, it defaults to the selected
+window.
@end defun
@defun window-full-width-p &optional window
This function returns non-@code{nil} if @var{window} has no other
-window to the left or right in its frame, i.e. its total width equals
+window to the left or right in its frame, i.e., its total width equals
that of the root window on that frame. If @var{window} is omitted or
@code{nil}, it defaults to the selected window.
@end defun
@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.
+
+@defun window-body-height &optional window pixelwise
+This function returns the height, in lines, of the body of window
+@var{window}. If @var{window} is omitted or @code{nil}, it defaults to
+the selected window; otherwise it must be a live window.
+
+If the optional argument @var{pixelwise} is non-@code{nil}, this
+function returns the body height of @var{window} counted in pixels.
+
+If @var{pixelwise} is @code{nil}, the return value is rounded down to
+the nearest integer, if necessary. This means that if a line at the
+bottom of the text area is only partially visible, that line is not
+counted. It also means that the height of a window's body can never
+exceed its total height as returned by @code{window-total-height}.
+@end defun
+
@cindex body width of a window
@cindex body size of a window
@cindex window body size
- The @dfn{body height} of a window is the height of its text area,
-which does not include the mode or header line. Similarly, the
-@dfn{body width} is the width of the text area, which does not include
-the scroll bar, fringes, or margins.
-
-@defun window-body-height &optional window
-This function returns the body height, in lines, of the window
-@var{window}. If @var{window} is omitted or @code{nil}, it defaults
-to the selected window; otherwise it must be a live window.
-
-If there is a partially-visible line at the bottom of the text area,
-that counts as a whole line; to exclude such a partially-visible line,
-use @code{window-text-height}, below.
-@end defun
-
-@defun window-body-width &optional window
-This function returns the body width, in columns, of the window
-@var{window}. If @var{window} is omitted or @code{nil}, it defaults
-to the selected window; otherwise it must be a live window.
-@end defun
-
-@defun window-body-size &optional window horizontal
-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 @code{window-body-height} for @var{window}; otherwise it is
-equivalent to calling @code{window-body-width}.
+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.
+
+@defun window-body-width &optional window pixelwise
+This function returns the width, in columns, of the body of window
+@var{window}. If @var{window} is omitted or @code{nil}, it defaults to
+the selected window; otherwise it must be a live window.
+
+If the optional argument @var{pixelwise} is non-@code{nil}, this
+function returns the body width of @var{window} in units of pixels.
+
+If @var{pixelwise} is @code{nil}, the return value is rounded down to
+the nearest integer, if necessary. This means that if a column on the
+right of the text area is only partially visible, that column is not
+counted. It also means that the width of a window's body can never
+exceed its total width as returned by @code{window-total-width}.
@end defun
-@defun window-text-height &optional window
-This function is like @code{window-body-height}, except that any
-partially-visible line at the bottom of the text area is not counted.
+@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
+@code{window-body-height} for @var{window}; otherwise it is equivalent
+to calling @code{window-body-width}. In either case, the optional
+argument @var{pixelwise} is passed to the function called.
@end defun
For compatibility with previous versions of Emacs,
@code{window-width} is an alias for @code{window-body-width}. These
aliases are considered obsolete and will be removed in the future.
+ The pixel heights of a window's mode and header line can be retrieved
+with the functions given below. Their return value is usually accurate
+unless the window has not been displayed before: In that case, the
+return value is based on an estimate of the font used for the window's
+frame.
+
+@defun window-mode-line-height &optional window
+This function returns the height in pixels of @var{window}'s mode line.
+@var{window} must be a live window and defaults to the selected one. If
+@var{window} has no mode line, the return value is zero.
+@end defun
+
+@defun window-header-line-height &optional window
+This function returns the height in pixels of @var{window}'s header
+line. @var{window} must be a live window and defaults to the selected
+one. If @var{window} has no header line, the return value is zero.
+@end defun
+
+Functions for retrieving the height and/or width of window dividers
+(@pxref{Window Dividers}), fringes (@pxref{Fringes}), scroll bars
+(@pxref{Scroll Bars}), and display margins (@pxref{Display Margins}) are
+described in the corresponding sections.
+
@cindex fixed-size window
@vindex window-min-height
@vindex window-min-width
Commands that change the size of windows (@pxref{Resizing Windows}),
or split them (@pxref{Splitting Windows}), obey the variables
-@code{window-min-height} and @code{window-min-width}, which specify
-the smallest allowable window height and width. @xref{Change
-Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs
-Manual}. They also obey the variable @code{window-size-fixed}, with
-which a window can be @dfn{fixed} in size:
-
-@defvar window-size-fixed
-If this buffer-local variable is non-@code{nil}, the size of any
-window displaying the buffer cannot normally be changed. Deleting a
-window or changing the frame's size may still change its size, if
-there is no choice.
-
-If the value is @code{height}, then only the window's height is fixed;
-if the value is @code{width}, then only the window's width is fixed.
-Any other non-@code{nil} value fixes both the width and the height.
-@end defvar
+@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:
+
+@defopt window-min-height
+This option specifies the minimum total height, in lines, of any window.
+Its value has to accommodate at least one text line as well as a mode
+and header line, a horizontal scroll bar and a bottom divider, if
+present.
+@end defopt
-@defun window-size-fixed-p &optional window horizontal
-This function returns a non-@code{nil} value if @var{window}'s height
-is fixed. If @var{window} is omitted or @code{nil}, it defaults to
-the selected window. If the optional argument @var{horizontal} is
-non-@code{nil}, the return value is non-@code{nil} if @var{window}'s
-width is fixed.
+@defopt window-min-width
+This option specifies the minimum total width, in columns, of any
+window. Its value has to accommodate two text columns as well as
+margins, fringes, a scroll bar and a right divider, if present.
+@end defopt
-A @code{nil} return value does not necessarily mean that @var{window}
-can be resized in the desired direction. To determine that, use the
-function @code{window-resizable}. @xref{Resizing Windows}.
+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}.
+
+@defun window-min-size &optional window horizontal ignore pixelwise
+This function returns the minimum size of @var{window}. @var{window}
+must be a valid window and defaults to the selected one. The optional
+argument @var{horizontal} non-@code{nil} means to return the minimum
+number of columns of @var{window}; otherwise return the minimum number
+of @var{window}'s lines.
+
+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.
+
+The optional argument @var{ignore}, if non-@code{nil}, means ignore
+restrictions imposed by fixed size windows, @code{window-min-height} or
+@code{window-min-width} settings. If @var{ignore} equals @code{safe},
+live windows may get as small as @code{window-safe-min-height} lines and
+@code{window-safe-min-width} columns. If @var{ignore} is a window,
+ignore restrictions for that window only. Any other non-@code{nil}
+value means ignore all of the above restrictions for all windows.
+
+The optional argument @var{pixelwise} non-@code{nil} means to return the
+minimum size of @var{window} counted in pixels.
@end defun
- @xref{Coordinates and Windows}, for more functions that report the
-positions of various parts of a window relative to the frame, from
-which you can calculate its size. In particular, you can use the
-functions @code{window-pixel-edges} and
-@code{window-inside-pixel-edges} to find the size in pixels, for
-graphical displays.
-
@node Resizing Windows
@section Resizing Windows
@cindex window resizing
arguments. Resizing an internal window causes its child windows to be
resized to fit the same space.
-@defun window-resizable window delta &optional horizontal ignore
+@defun window-resizable window delta &optional horizontal ignore pixelwise
This function returns @var{delta} if the size of @var{window} can be
changed vertically by @var{delta} lines. If the optional argument
@var{horizontal} is non-@code{nil}, it instead returns @var{delta} if
that the window cannot be resized.
Normally, the variables @code{window-min-height} and
-@code{window-min-width} specify the smallest allowable window size.
-@xref{Change Window,, Deleting and Rearranging Windows, emacs, The GNU
-Emacs Manual}. However, if the optional argument @var{ignore} is
-non-@code{nil}, this function ignores @code{window-min-height} and
-@code{window-min-width}, as well as @code{window-size-fixed}.
-Instead, it considers the minimum-height window to be one consisting
-of a header (if any), a mode line, plus a text area one line tall; and
-a minimum-width window as one consisting of fringes, margins, and
-scroll bar (if any), plus a text area two columns wide.
-@end defun
-
-@defun window-resize window delta &optional horizontal ignore
+@code{window-min-width} specify the smallest allowable window size
+(@pxref{Window Sizes}). However, if the optional argument @var{ignore}
+is non-@code{nil}, this function ignores @code{window-min-height} and
+@code{window-min-width}, as well as @code{window-size-fixed}. Instead,
+it considers the minimum-height window to be one consisting of a header
+and a mode line, a horizontal scrollbar and a bottom divider (if any),
+plus a text area one line tall; and a minimum-width window as one
+consisting of fringes, margins, a scroll bar and a right divider (if
+any), plus a text area two columns wide.
+
+If the optional argument @var{pixelwise} is non-@code{nil},
+@var{delta} is interpreted as pixels.
+@end defun
+
+@defun window-resize window delta &optional horizontal ignore pixelwise
This function resizes @var{window} by @var{delta} increments. If
@var{horizontal} is @code{nil}, it changes the height by @var{delta}
lines; otherwise, it changes the width by @var{delta} columns. A
The optional argument @var{ignore} has the same meaning as for the
function @code{window-resizable} above.
+If the optional argument @var{pixelwise} is non-@code{nil},
+@var{delta} will be interpreted as pixels.
+
The choice of which window edges this function alters depends on the
values of the option @code{window-combination-resize} and the
combination limits of the involved windows; in some cases, it may alter
both edges. @xref{Recombining Windows}. To resize by moving only the
bottom or right edge of a window, use the function
-@code{adjust-window-trailing-edge}, below.
+@code{adjust-window-trailing-edge}.
@end defun
@c The commands enlarge-window, enlarge-window-horizontally,
@c shrink-window, and shrink-window-horizontally are documented in the
@c Emacs manual. They are not preferred for calling from Lisp.
-@defun adjust-window-trailing-edge window delta &optional horizontal
+@defun adjust-window-trailing-edge window delta &optional horizontal pixelwise
This function moves @var{window}'s bottom edge by @var{delta} lines.
If optional argument @var{horizontal} is non-@code{nil}, it instead
moves the right edge by @var{delta} columns. If @var{window} is
@code{nil}, it defaults to the selected window.
+If the optional argument @var{pixelwise} is non-@code{nil},
+@var{delta} is interpreted as pixels.
+
A positive @var{delta} moves the edge downwards or to the right; a
negative @var{delta} moves it upwards or to the left. If the edge
cannot be moved as far as specified by @var{delta}, this function
moves it as far as possible but does not signal a error.
This function tries to resize windows adjacent to the edge that is
-moved. If this is not possible for some reason (e.g. if that adjacent
+moved. If this is not possible for some reason (e.g., if that adjacent
window is fixed-size), it may resize other windows.
@end defun
+@cindex pixelwise, resizing windows
+@defopt window-resize-pixelwise
+If the value of this option is non-@code{nil}, Emacs resizes windows in
+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}).
+
+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
+option is @code{nil}. The default value is @code{nil}.
+@end defopt
+
The following commands resize windows in more specific ways. When
called interactively, they act on the selected window.
-@deffn Command fit-window-to-buffer &optional window max-height min-height override
-This command adjusts the height of @var{window} to fit the text in it.
-It returns non-@code{nil} if it was able to resize @var{window}, and
-@code{nil} otherwise. If @var{window} is omitted or @code{nil}, it
-defaults to the selected window. Otherwise, it should be a live
-window.
-
-The optional argument @var{max-height}, if non-@code{nil}, specifies
-the maximum total height that this function can give @var{window}.
-The optional argument @var{min-height}, if non-@code{nil}, specifies
-the minimum total height that it can give, which overrides the
-variable @code{window-min-height}.
+@deffn Command fit-window-to-buffer &optional window max-height min-height max-width min-width preserve-size
+This command adjusts the height or width of @var{window} to fit the text
+in it. It returns non-@code{nil} if it was able to resize @var{window},
+and @code{nil} otherwise. If @var{window} is omitted or @code{nil}, it
+defaults to the selected window. Otherwise, it should be a live window.
+
+If @var{window} is part of a vertical combination, this function adjusts
+@var{window}'s height. The new height is calculated from the actual
+height of the accessible portion of its buffer. The optional argument
+@var{max-height}, if non-@code{nil}, specifies the maximum total height
+that this function can give @var{window}. The optional argument
+@var{min-height}, if non-@code{nil}, specifies the minimum total height
+that it can give, which overrides the variable @code{window-min-height}.
+Both @var{max-height} and @var{min-height} are specified in lines and
+include mode and header line and a bottom divider, if any.
+
+If @var{window} is part of a horizontal combination and the value of the
+option @code{fit-window-to-buffer-horizontally} (see below) is
+non-@code{nil}, this function adjusts @var{window}'s height. The new
+width of @var{window} is calculated from the maximum length of its
+buffer's lines that follow the current start position of @var{window}.
+The optional argument @var{max-width} specifies a maximum width and
+defaults to the width of @var{window}'s frame. The optional argument
+@var{min-width} specifies a minimum width and defaults to
+@code{window-min-width}. Both @var{max-width} and @var{min-width} are
+specified in columns and include fringes, margins and scrollbars, if
+any.
-If the optional argument @var{override} is non-@code{nil}, this
-function ignores any size restrictions imposed by
-@code{window-min-height} and @code{window-min-width}.
+The optional argument @var{preserve-size}, if non-@code{nil}, will
+install a parameter to preserve the size of @var{window} during future
+resize operations (@pxref{Preserving Window Sizes}).
-@vindex fit-frame-to-buffer
-If the option @code{fit-frame-to-buffer} is non-@code{nil}, this
-command may resize the frame to fit its contents.
+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}).
@end deffn
+@defopt fit-window-to-buffer-horizontally
+If this is non-@code{nil}, @code{fit-window-to-buffer} can resize
+windows horizontally. If this is @code{nil} (the default)
+@code{fit-window-to-buffer} never resizes windows horizontally. If this
+is @code{only}, it can resize windows horizontally only. Any other
+value means @code{fit-window-to-buffer} can resize windows in both
+dimensions.
+@end defopt
+
+@defopt fit-frame-to-buffer
+If this option is non-@code{nil}, @code{fit-window-to-buffer} can fit a
+frame to its buffer. A frame is fit if and only if its root window is a
+live window and this option is non-@code{nil}. If this is
+@code{horizontally}, frames are fit horizontally only. If this is
+@code{vertically}, frames are fit vertically only. Any other
+non-@code{nil} value means frames can be resized in both dimensions.
+@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
This command does nothing if the window is already too short to
display all of its buffer, or if any of the buffer is scrolled
off-screen, or if the window is the only live window in its frame.
+
+This command calls @code{fit-window-to-buffer} (see above) to do its
+work.
@end deffn
+
@cindex balancing window sizes
@deffn Command balance-windows &optional window-or-frame
This function balances windows in a way that gives more space to
@end deffn
+@node Preserving Window Sizes
+@section Preserving Window Sizes
+@cindex preserving window sizes
+
+A window can get resized explicitly by using one of the functions from
+the preceding section or implicitly, for example, when resizing an
+adjacent window, when splitting or deleting a window (@pxref{Splitting
+Windows}, @pxref{Deleting Windows}) or when resizing the window's frame
+(@pxref{Size and Position}).
+
+ It is possible to avoid implicit resizing of a specific window when
+there are one or more other resizable windows on the same frame. For
+this purpose, Emacs must be advised to @dfn{preserve} the size of that
+window. There are two basic ways to do that.
+
+@defvar window-size-fixed
+If this buffer-local variable is non-@code{nil}, the size of any window
+displaying the buffer cannot normally be changed. Deleting a window or
+changing the frame's size may still change the window's size, if there
+is no choice.
+
+If the value is @code{height}, then only the window's height is fixed;
+if the value is @code{width}, then only the window's width is fixed.
+Any other non-@code{nil} value fixes both the width and the height.
+
+If this variable is @code{nil}, this does not necessarily mean that any
+window showing the buffer can be resized in the desired direction. To
+determine that, use the function @code{window-resizable}.
+@xref{Resizing Windows}.
+@end defvar
+
+Often @code{window-size-fixed} is overly aggressive because it inhibits
+any attempt to explicitly resize or split an affected window as well.
+This may even happen after the window has been resized implicitly, for
+example, when deleting an adjacent window or resizing the window's
+frame. The following function tries hard to never disallow resizing
+such a window explicitly:
+
+@defun window-preserve-size &optional window horizontal preserve
+This function (un-)marks the height of window @var{window} as preserved
+for future resize operations. @var{window} must be a live window and
+defaults to the selected one. If the optional argument @var{horizontal}
+is non-@code{nil}, it (un-)marks the width of @var{window} as preserved.
+
+If the optional argument @var{preserve} is @code{t}, this means to
+preserve the current height/width of @var{window}'s body. The
+height/width of @var{window} will change only if Emacs has no better
+choice. Resizing a window whose height/width is preserved by this
+function never throws an error.
+
+If @var{preserve} is @code{nil}, this means to stop preserving the
+height/width of @var{window}, lifting any respective restraint induced
+by a previous call of this function for @var{window}. Calling
+@code{enlarge-window}, @code{shrink-window} or
+@code{fit-window-to-buffer} with @var{window} as argument may also
+remove the respective restraint.
+@end defun
+
+@code{window-preserve-size} is currently invoked by the following
+functions:
+
+@table @code
+@item fit-window-to-buffer
+If the optional argument @var{preserve-size} of that function
+(@pxref{Resizing Windows}) is non-@code{nil}, the size established by
+that function is preserved.
+
+@item display-buffer
+If the @var{alist} argument of that function (@pxref{Choosing Window})
+contains a @code{preserve-size} entry, the size of the window produced
+by that function is preserved.
+@end table
+
+ @code{window-preserve-size} installs a window parameter (@pxref{Window
+Parameters}) called @code{preserved-size} which is consulted by the
+window resizing functions. This parameter will not prevent resizing the
+window when the window shows another buffer than the one when
+@code{window-preserve-size} was invoked or if its size has changed since
+then.
+
+The following function can be used to check whether the height of a
+particular window is preserved:
+
+@defun window-preserved-size &optional window horizontal
+This function returns the preserved height of window @var{window} in
+pixels. @var{window} must be a live window and defaults to the selected
+one. If the optional argument @var{horizontal} is non-@code{nil}, it
+returns the preserved width of @var{window}. It returns @code{nil} if
+the size of @var{window} is not preserved.
+@end defun
+
+
@node Splitting Windows
@section Splitting Windows
@cindex splitting windows
This section describes functions for creating a new window by
@dfn{splitting} an existing one.
-@deffn Command split-window &optional window size side
+@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
window is given @minus{}@var{size} lines (or columns).
If @var{size} is @code{nil}, this function obeys the variables
-@code{window-min-height} and @code{window-min-width}. @xref{Change
-Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs
-Manual}. Thus, it signals an error if splitting would result in
-making a window smaller than those variables specify. However, a
+@code{window-min-height} and @code{window-min-width} (@pxref{Window
+Sizes}). Thus, it signals an error if splitting would result in making
+a window smaller than those variables specify. However, a
non-@code{nil} value for @var{size} causes those variables to be
-ignored; in that case, the smallest allowable window is considered to
-be one that has space for a text area one line tall and/or two columns
+ignored; in that case, the smallest allowable window is considered to be
+one that has space for a text area one line tall and/or two columns
wide.
+Hence, if @var{size} is specified, it's the caller's responsibility to
+check whether the emanating windows are large enough to encompass all
+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
+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
+redisplay.
+
The optional third argument @var{side} determines the position of the
new window relative to @var{window}. If it is @code{nil} or
@code{below}, the new window is placed below @var{window}. If it is
window is placed on the left of @var{window}. In both these cases,
@var{size} specifies a total window width, in columns.
+The optional fourth argument @var{pixelwise}, if non-@code{nil}, means
+to interpret @var{size} in units of pixels, instead of lines and
+columns.
+
If @var{window} is a live window, the new window inherits various
properties from it, including margins and scroll bars. If
@var{window} is an internal window, the new window inherits the
lieu of the usual action of @code{split-window}. Otherwise, this
function obeys the @code{window-atom} or @code{window-side} window
parameter, if any. @xref{Window Parameters}.
-@end deffn
+@end defun
As an example, here is a sequence of @code{split-window} calls that
yields the window configuration discussed in @ref{Windows and Frames}.
function.
@end defopt
+
@node Deleting Windows
@section Deleting Windows
@cindex deleting windows
This function removes @var{window} from display and returns
@code{nil}. If @var{window} is omitted or @code{nil}, it defaults to
the selected window. If deleting the window would leave no more
-windows in the window tree (e.g. if it is the only live window in the
+windows in the window tree (e.g., if it is the only live window in the
frame), an error is signaled.
By default, the space taken up by @var{window} is given to one of its
@node Recombining Windows
@section Recombining Windows
+@cindex recombining windows
+@cindex windows, recombining
-When deleting the last sibling of a window @code{W}, its parent window
-is deleted too, with @code{W} replacing it in the window tree. This
-means that @code{W} must be recombined with its parent's siblings to
+When deleting the last sibling of a window @var{W}, its parent window
+is deleted too, with @var{W} replacing it in the window tree. This
+means that @var{W} must be recombined with its parent's siblings to
form a new window combination (@pxref{Windows and Frames}). In some
occasions, deleting a live window may even entail the deletion of two
internal windows.
@end smallexample
@noindent
-Deleting @code{W5} in this configuration normally causes the deletion of
-@code{W3} and @code{W4}. The remaining live windows @code{W2},
-@code{W6} and @code{W7} are recombined to form a new horizontal
-combination with parent @code{W1}.
+Deleting @var{W5} in this configuration normally causes the deletion of
+@var{W3} and @var{W4}. The remaining live windows @var{W2},
+@var{W6} and @var{W7} are recombined to form a new horizontal
+combination with parent @var{W1}.
Sometimes, however, it makes sense to not delete a parent window like
-@code{W4}. In particular, a parent window should not be removed when it
+@var{W4}. In particular, a parent window should not be removed when it
was used to preserve a combination embedded in a combination of the same
type. Such embeddings make sense to assure that when you split a window
and subsequently delete the new window, Emacs reestablishes the layout
of the associated frame as it existed before the splitting.
- Consider a scenario starting with two live windows @code{W2} and
-@code{W3} and their parent @code{W1}.
+ Consider a scenario starting with two live windows @var{W2} and
+@var{W3} and their parent @var{W1}.
@smallexample
@group
@end smallexample
@noindent
-Split @code{W2} to make a new window @code{W4} as follows.
+Split @var{W2} to make a new window @var{W4} as follows.
@smallexample
@group
@noindent
Now, when enlarging a window vertically, Emacs tries to obtain the
corresponding space from its lower sibling, provided such a window
-exists. In our scenario, enlarging @code{W4} will steal space from
-@code{W3}.
+exists. In our scenario, enlarging @var{W4} will steal space from
+@var{W3}.
@smallexample
@group
@end smallexample
@noindent
-Deleting @code{W4} will now give its entire space to @code{W2},
-including the space earlier stolen from @code{W3}.
+Deleting @var{W4} will now give its entire space to @var{W2},
+including the space earlier stolen from @var{W3}.
@smallexample
@group
@end smallexample
@noindent
-This can be counterintuitive, in particular if @code{W4} were used for
+This can be counterintuitive, in particular if @var{W4} were used for
displaying a buffer only temporarily (@pxref{Temporary Displays}), and
you want to continue working with the initial layout.
The behavior can be fixed by making a new parent window when splitting
-@code{W2}. The variable described next allows to do that.
+@var{W2}. The variable described next allows to do that.
@defopt window-combination-limit
This variable controls whether splitting a window shall make a new
the child windows are deleted (see below).
@end defopt
- If @code{window-combination-limit} is @code{t}, splitting @code{W2} in
+ If @code{window-combination-limit} is @code{t}, splitting @var{W2} in
the initial configuration of our scenario would have produced this:
@smallexample
@end smallexample
@noindent
-A new internal window @code{W5} has been created; its children are
-@code{W2} and the new live window @code{W4}. Now, @code{W2} is the only
-sibling of @code{W4}, so enlarging @code{W4} will try to shrink
-@code{W2}, leaving @code{W3} unaffected. Observe that @code{W5}
+A new internal window @var{W5} has been created; its children are
+@var{W2} and the new live window @var{W4}. Now, @var{W2} is the only
+sibling of @var{W4}, so enlarging @var{W4} will try to shrink
+@var{W2}, leaving @var{W3} unaffected. Observe that @var{W5}
represents a vertical combination of two windows embedded in the
-vertical combination @code{W1}.
+vertical combination @var{W1}.
@cindex window combination limit
@defun set-window-combination-limit window limit
-This functions sets the @dfn{combination limit} of the window
+This function sets the @dfn{combination limit} of the window
@var{window} to @var{limit}. This value can be retrieved via the
function @code{window-combination-limit}. See below for its effects;
note that it is only meaningful for internal windows. The
siblings.
If, in the configuration shown at the beginning of this section, the
-combination limit of @code{W4} (the parent window of @code{W6} and
-@code{W7}) is @code{t}, deleting @code{W5} will not implicitly delete
-@code{W4} too.
+combination limit of @var{W4} (the parent window of @var{W6} and
+@var{W7}) is @code{t}, deleting @var{W5} will not implicitly delete
+@var{W4} too.
@end defun
Alternatively, the problems sketched above can be avoided by always
@noindent
If @code{window-combination-resize} is @code{nil}, splitting window
-@code{W3} leaves the size of @code{W2} unchanged:
+@var{W3} leaves the size of @var{W2} unchanged:
@smallexample
@group
@end smallexample
@noindent
-If @code{window-combination-resize} is @code{t}, splitting @code{W3}
+If @code{window-combination-resize} is @code{t}, splitting @var{W3}
instead leaves all three live windows with approximately the same
height:
@end smallexample
@noindent
-Deleting any of the live windows @code{W2}, @code{W3} or @code{W4} will
+Deleting any of the live windows @var{W2}, @var{W3} or @var{W4} will
distribute its space proportionally among the two remaining live
windows.
@cindex selecting a window
@defun select-window window &optional norecord
-This function makes @var{window} the selected window, as well as the
-window selected within its frame (@pxref{Basic Windows}). @var{window}
-must be a live window. This function makes also @var{window}'s buffer
-current (@pxref{Buffers and Windows}). The return value is
-@var{window}.
+This function makes @var{window} the selected window and the window
+selected within its frame (@pxref{Basic Windows}) and selects that
+frame. It also makes @var{window}'s buffer (@pxref{Buffers and
+Windows}) current and sets that buffer's value of @code{point} to the
+value of @code{window-point} (@pxref{Window Point}) in @var{window}.
+@var{window} must be a live window. The return value is @var{window}.
By default, this function also moves @var{window}'s buffer to the front
-of the buffer list (@pxref{The Buffer List}), and makes @var{window} the
+of the buffer list (@pxref{Buffer List}), and makes @var{window} the
most recently selected window. However, if the optional argument
@var{norecord} is non-@code{nil}, these additional actions are omitted.
+
+This function runs @code{buffer-list-update-hook} (@pxref{Buffer List})
+unless @var{norecord} is non-@code{nil}. Note that applications and
+internal routines often temporarily select a window in order to simplify
+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
+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
+the right choice.
@end defun
@cindex most recently selected windows
@defun set-frame-selected-window frame window &optional norecord
This function makes @var{window} the window selected within the frame
-@var{frame}. @var{frame} should be a live frame; if omitted or
-@code{nil}, it defaults to the selected frame. @var{window} should be
-a live window; if omitted or @code{nil}, it defaults to the selected
-window.
+@var{frame}. @var{frame} should be a live frame; if @code{nil}, it
+defaults to the selected frame. @var{window} should be a live window;
+if @code{nil}, it defaults to the selected window.
If @var{frame} is the selected frame, this makes @var{window} the
selected window.
@code{next-window}.
@end defun
-@cindex window in direction
-@defun window-in-direction direction &optional window ignore
-This function returns the nearest window in direction @var{direction} as
-seen from the position of @code{window-point} in window @var{window}.
-The argument @var{direction} must be one of @code{above}, @code{below},
-@code{left} or @code{right}. The optional argument @var{window} must
-denote a live window and defaults to the selected one.
-
-This function does not return a window whose @code{no-other-window}
-parameter is non-@code{nil}. If the nearest window's
-@code{no-other-window} parameter is non-@code{nil}, this function tries
-to find another window in the indicated direction whose
-@code{no-other-window} parameter is @code{nil}. If the optional
-argument @var{ignore} is non-@code{nil}, a window may be returned even
-if its @code{no-other-window} parameter is non-@code{nil}.
-
-If it doesn't find a suitable window, this function returns @code{nil}.
-@end defun
-
@node Buffers and Windows
@section Buffers and Windows
@deffn Command replace-buffer-in-windows &optional buffer-or-name
This command replaces @var{buffer-or-name} with some other buffer, in
-all windows displaying it. @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.
+all windows displaying it. @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 replacement buffer in each window is chosen via
@code{switch-to-prev-buffer} (@pxref{Window History}). Any dedicated
-window displaying @var{buffer-or-name} is deleted (@pxref{Dedicated
-Windows}), unless it is the only window on its frame---if it is the
-only window, and that frame is not the only frame on its terminal, the
-frame is ``dismissed'' by calling the function specified by
-@code{frame-auto-hide-function} (@pxref{Quitting Windows}). If the
-dedicated window is the only window on the only frame on its terminal,
-the buffer is replaced anyway.
+window displaying @var{buffer-or-name} is deleted if possible
+(@pxref{Dedicated Windows}). If such a window is the only window on its
+frame and there are other frames on the same terminal, the frame is
+deleted as well. If the dedicated window is the only window on the only
+frame on its terminal, the buffer is replaced anyway.
@end deffn
+
@node Switching Buffers
@section Switching to a Buffer in a Window
@cindex switching to a buffer
@cindex displaying a buffer
- This section describes high-level functions for switching to a
-specified buffer in some window.
+This section describes high-level functions for switching to a specified
+buffer in some window. In general, ``switching to a buffer'' means to
+(1) show the buffer in some window, (2) make that window the selected
+window (and its frame the selected frame), and (3) make the buffer the
+current buffer.
Do @emph{not} use these functions to make a buffer temporarily
current just so a Lisp program can access or modify it. They have
@deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window
This command attempts to display @var{buffer-or-name} in the selected
-window, and makes it the current buffer. It is often used
-interactively (as the binding of @kbd{C-x b}), as well as in Lisp
-programs. The return value is the buffer switched to.
+window and make it the current buffer. It is often used interactively
+(as the binding of @kbd{C-x b}), as well as in Lisp programs. The
+return value is the buffer switched to.
If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
-returned by @code{other-buffer} (@pxref{The Buffer List}). If
+returned by @code{other-buffer} (@pxref{Buffer List}). If
@var{buffer-or-name} is a string that is not the name of any existing
buffer, this function creates a new buffer with that name; the new
buffer's major mode is determined by the variable @code{major-mode}
Normally, the specified buffer is put at the front of the buffer
list---both the global buffer list and the selected frame's buffer
-list (@pxref{The Buffer List}). However, this is not done if the
+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
instead.
@end deffn
-By default, @code{switch-to-buffer} sets @code{window-point} of the
-window used to the buffer's position of @code{point}. This behavior can
-be tuned using the following option.
+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 switch-to-buffer-preserve-window-point
If this variable is @code{nil}, @code{switch-to-buffer} displays the
buffer.
@end defopt
-The next two functions are similar to @code{switch-to-buffer}, except
-for the described features.
+The next two commands are similar to @code{switch-to-buffer}, except for
+the described features.
@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
-This function makes the buffer specified by @var{buffer-or-name}
-current and displays it in some window other than the selected window.
-It uses the function @code{pop-to-buffer} internally (see below).
+This function displays the buffer specified by @var{buffer-or-name} in
+some window other than the selected window. It uses the function
+@code{pop-to-buffer} internally (see below).
If the selected window already displays the specified buffer, it
continues to do so, but another window is nonetheless found to display
@end deffn
@deffn Command switch-to-buffer-other-frame buffer-or-name &optional norecord
-This function makes the buffer specified by @var{buffer-or-name}
-current and displays it, usually in a new frame. It uses the function
-@code{pop-to-buffer} (see below).
+This function displays the buffer specified by @var{buffer-or-name} in a
+new frame. It uses the function @code{pop-to-buffer} internally (see
+below).
If the specified buffer is already displayed in another window, in any
frame on the current terminal, this switches to that window instead of
was switched to.
If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
-returned by @code{other-buffer} (@pxref{The Buffer List}). If
+returned by @code{other-buffer} (@pxref{Buffer List}). If
@var{buffer-or-name} is a string that is not the name of any existing
buffer, this function creates a new buffer with that name; the new
buffer's major mode is determined by the variable @code{major-mode}
@noindent
Each action function is called in turn, passing the buffer as the
first argument and the combined action alist as the second argument,
-until one of the functions returns non-@code{nil}.
+until one of the functions returns non-@code{nil}. The caller can
+pass @code{(allow-no-window . t)} as an element of the action alist to
+indicate its readiness to handle the case of not displaying the
+buffer in a window.
The argument @var{action} can also have a non-@code{nil}, non-list
value. This has the special meaning that the buffer should be
@defvar display-buffer-overriding-action
The value of this variable should be a display action, which is
treated with the highest priority by @code{display-buffer}. The
-default value is empty, i.e. @code{(nil . nil)}.
+default value is empty, i.e., @code{(nil . nil)}.
@end defvar
@defopt display-buffer-alist
The value of this option is an alist mapping conditions to display
actions. Each condition may be either a regular expression matching a
-buffer name or a function that takes two arguments - a buffer name and
+buffer name or a function that takes two arguments: a buffer name and
the @var{action} argument passed to @code{display-buffer}. If the name
of the buffer passed to @code{display-buffer} either matches a regular
expression in this alist or the function specified by a condition
A frame means consider windows on that frame only.
@end itemize
+Note that these meanings differ slightly from those of the
+@var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window
+Ordering}).
+
If @var{alist} contains no @code{reusable-frames} entry, this function
normally searches just the selected frame; however, if the variable
@code{pop-up-frames} is non-@code{nil}, it searches all frames on the
@item
A number specifies the desired height of the new window. An integer
-number specifies the number of lines of the window. A floating point
+specifies the number of lines of the window. A floating-point
number gives the fraction of the window's height with respect to the
height of the frame's root window.
@item
If the @sc{cdr} specifies a function, that function is called with one
-argument - the new window. The function is supposed to adjust the
+argument: the new window. The function is supposed to adjust the
height of the window; its return value is ignored. Suitable functions
are @code{shrink-window-if-larger-than-buffer} and
@code{fit-window-to-buffer}, see @ref{Resizing Windows}.
@item
A number specifies the desired width of the new window. An integer
-number specifies the number of columns of the window. A floating point
+specifies the number of columns of the window. A floating-point
number gives the fraction of the window's width with respect to the
width of the frame's root window.
@item
If the @sc{cdr} specifies a function, that function is called with one
-argument - the new window. The function is supposed to adjust the width
+argument: the new window. The function is supposed to adjust the width
of the window; its return value is ignored.
@end itemize
+If @var{alist} contains a @code{preserve-size} entry, Emacs will try to
+preserve the size of the new window during future resize operations
+(@pxref{Preserving Window Sizes}). The @sc{cdr} of that entry must be a
+cons cell whose @sc{car}, if non-@code{nil}, means to preserve the width
+of the window and whose @sc{cdr}, if non-@code{nil}, means to preserve
+the height of the window.
+
This function can fail if no window splitting can be performed for some
-reason (e.g. if there is just one frame and it has an
-@code{unsplittable} frame parameter; @pxref{Buffer Parameters}).
+reason (e.g., if the selected frame has an @code{unsplittable} frame
+parameter; @pxref{Buffer Parameters}).
@end defun
@defun display-buffer-below-selected buffer alist
methods above, even if that window never showed @var{buffer} before.
@end defun
+@defun display-buffer-at-bottom buffer alist
+This function tries to display @var{buffer} in a window at the bottom
+of the selected frame.
+
+This either splits the window at the bottom of the frame or the
+frame's root window, or reuses an existing window at the bottom of the
+selected frame.
+@end defun
+
@defun display-buffer-use-some-window buffer alist
This function tries to display @var{buffer} by choosing an existing
window and displaying the buffer in that window. It can fail if all
windows are dedicated to another buffer (@pxref{Dedicated Windows}).
@end defun
+@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.
+@end defun
+
To illustrate the use of action functions, consider the following
example.
@noindent
Evaluating the form above will cause @code{display-buffer} to proceed as
-follows: If `*foo*' already appears on a visible or iconified frame, it
-will reuse its window. Otherwise, it will try to pop up a new window
-or, if that is impossible, a new frame. If all these steps fail, it
-will proceed using whatever @code{display-buffer-base-action} and
+follows: If a buffer called *foo* already appears on a visible or
+iconified frame, it will reuse its window. Otherwise, it will try to
+pop up a new window or, if that is impossible, a new frame and show the
+buffer there. If all these steps fail, it will proceed using whatever
+@code{display-buffer-base-action} and
@code{display-buffer-fallback-action} prescribe.
Furthermore, @code{display-buffer} will try to adjust a reused window
-(provided `*foo*' was put by @code{display-buffer} there before) or a
+(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
@end example
@noindent
-Evaluating this form will cause @code{display-buffer} to first try
-reusing a window showing @code{*foo*} on the selected frame.
-If no such window exists, it will try to split the selected window or,
-if that is impossible, use the window below the selected window.
+This form will have @code{display-buffer} first try reusing a window
+that shows *foo* on the selected frame. If there's no such window, it
+will try to split the selected window or, if that is impossible, use the
+window below the selected window.
If there's no window below the selected one, or the window below the
selected one is dedicated to its buffer, @code{display-buffer} will
the window (@pxref{Display Action Functions}).
The default value is @code{split-window-sensibly}, which is documented
-below. The value must be a function that takes one argument, a
-window, and return either a new window (which is used to display the
+below. The value must be a function that takes one argument, a window,
+and return either a new window (which will be used to display the
desired buffer) or @code{nil} (which means the splitting failed).
@end defopt
@defopt same-window-buffer-names
A list of buffer names for buffers that should be displayed in the
selected window. If a buffer's name is in this list,
-@code{display-buffer} handles the buffer by switching to it in the
-selected window.
+@code{display-buffer} handles the buffer by showing it in the selected
+window.
@end defopt
@defopt same-window-regexps
A list of regular expressions that specify buffers that should be
displayed in the selected window. If the buffer's name matches any of
the regular expressions in this list, @code{display-buffer} handles the
-buffer by switching to it in the selected window.
+buffer by showing it in the selected window.
@end defopt
@defun same-window-p buffer-name
@section Window History
@cindex window history
-Each window remembers the buffers it has previously displayed, and the order
-in which these buffers were removed from it. This history is used,
-for example, by @code{replace-buffer-in-windows} (@pxref{Buffers and
-Windows}). This list is automatically maintained by Emacs, but you can
-use the following functions to explicitly inspect or alter it:
+Each window remembers in a list the buffers it has previously displayed,
+and the order in which these buffers were removed from it. This history
+is used, for example, by @code{replace-buffer-in-windows}
+(@pxref{Buffers and Windows}). The list is automatically maintained by
+Emacs, but you can use the following functions to explicitly inspect or
+alter it:
@defun window-prev-buffers &optional window
This function returns a list specifying the previous contents of
-@var{window}, which should be a live window and defaults to the
-selected window.
+@var{window}. The optional argument @var{window} should be a live
+window and defaults to the selected one.
Each list element has the form @code{(@var{buffer} @var{window-start}
@var{window-pos})}, where @var{buffer} is a buffer previously shown in
-the window, @var{window-start} is the window start position when that
-buffer was last shown, and @var{window-pos} is the point position when
-that buffer was last shown.
+the window, @var{window-start} is the window start position
+(@pxref{Window Start and End}) when that buffer was last shown, and
+@var{window-pos} is the point position (@pxref{Window Point}) when
+that buffer was last shown in @var{window}.
The list is ordered so that earlier elements correspond to more
recently-shown buffers, and the first element usually corresponds to the
If repeated invocations of this command have already shown all buffers
previously shown in @var{window}, further invocations will show buffers
-from the buffer list of the frame @var{window} appears on (@pxref{The
-Buffer List}), trying to skip buffers that are already shown in another
-window on that frame.
+from the buffer list of the frame @var{window} appears on (@pxref{Buffer
+List}), trying to skip buffers that are already shown in another window
+on that frame.
@end deffn
@deffn Command switch-to-next-buffer &optional window
If there is no recent invocation of @code{switch-to-prev-buffer} that
can be undone, this function tries to show a buffer from the buffer list
-of the frame @var{window} appears on (@pxref{The Buffer List}).
+of the frame @var{window} appears on (@pxref{Buffer List}).
@end deffn
By default @code{switch-to-prev-buffer} and @code{switch-to-next-buffer}
@defopt switch-to-visible-buffer
If this variable is non-@code{nil}, @code{switch-to-prev-buffer} and
@code{switch-to-next-buffer} may switch to a buffer that is already
-visible on the same frame, provided the buffer was shown in the relevant
-window before. If it is @code{nil}, @code{switch-to-prev-buffer} and
-@code{switch-to-next-buffer} always try to avoid switching to a buffer
-that is already visible in another window on the same frame.
+visible on the same frame, provided the buffer was shown in the
+relevant window before. If it is @code{nil},
+@code{switch-to-prev-buffer} and @code{switch-to-next-buffer} always
+try to avoid switching to a buffer that is already visible in another
+window on the same frame. The default is @code{t}.
@end defopt
windows by marking these windows as @dfn{dedicated} to their buffers.
@code{display-buffer} (@pxref{Choosing Window}) never uses a dedicated
window for displaying another buffer in it. @code{get-lru-window} and
-@code{get-largest-window} (@pxref{Selecting Windows}) do not consider
-dedicated windows as candidates when their @var{dedicated} argument is
-non-@code{nil}. The behavior of @code{set-window-buffer}
+@code{get-largest-window} (@pxref{Cyclic Window Ordering}) do not
+consider dedicated windows as candidates when their @var{dedicated}
+argument is non-@code{nil}. The behavior of @code{set-window-buffer}
(@pxref{Buffers and Windows}) with respect to dedicated windows is
slightly different, see below.
-When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to
-delete a dedicated window and that window is the only window on its
-frame, it deletes the window's frame too, provided there are other
-frames left. @code{replace-buffer-in-windows} (@pxref{Switching
-Buffers}) tries to delete all dedicated windows showing its buffer
-argument. When such a window is the only window on its frame, that
-frame is deleted, provided there are other frames left. If there are
-no more frames left, some other buffer is displayed in the window, and
-the window is marked as non-dedicated.
-
-When you kill a buffer (@pxref{Killing Buffers}) displayed in a
-dedicated window, any such window usually gets deleted too, since
-@code{kill-buffer} calls @code{replace-buffer-in-windows} for cleaning
-up windows. Burying a buffer (@pxref{The Buffer List}) deletes the
-selected window if it is dedicated to that buffer. If, however, that
-window is the only window on its frame, @code{bury-buffer} displays
-another buffer in it and iconifies the frame.
+ Functions supposed to remove a buffer from a window or a window from
+a frame can behave specially when a window they operate on is dedicated.
+We will distinguish three basic cases, namely where (1) the window is
+not the only window on its frame, (2) the window is the only window on
+its frame but there are other frames on the same terminal left, and (3)
+the window is the only window on the only frame on the same terminal.
+
+ In particular, @code{delete-windows-on} (@pxref{Deleting Windows})
+handles case (2) by deleting the associated frame and case (3) by
+showing another buffer in that frame's only window. The function
+@code{replace-buffer-in-windows} (@pxref{Buffers and Windows}) which is
+called when a buffer gets killed, deletes the window in case (1) and
+behaves like @code{delete-windows-on} otherwise.
+@c FIXME: Does replace-buffer-in-windows _delete_ a window in case (1)?
+
+ When @code{bury-buffer} (@pxref{Buffer List}) operates on the
+selected window (which shows the buffer that shall be buried), it
+handles case (2) by calling @code{frame-auto-hide-function}
+(@pxref{Quitting Windows}) to deal with the selected frame. The other
+two cases are handled as with @code{replace-buffer-in-windows}.
@defun window-dedicated-p &optional window
This function returns non-@code{nil} if @var{window} is dedicated to its
hand, a window has been reused for displaying the buffer, you might
prefer showing the buffer previously shown in that window, by calling the
function @code{switch-to-prev-buffer} (@pxref{Window History}).
-Finally, you might want to either bury (@pxref{The Buffer List}) or kill
+Finally, you might want to either bury (@pxref{Buffer List}) or kill
(@pxref{Killing Buffers}) the window's buffer.
The following command uses information on how the window for
The function specified by this option is called to automatically hide
frames. This function is called with one argument---a frame.
-The function specified here is called by @code{bury-buffer} (@pxref{The
-Buffer List}) when the selected window is dedicated and shows the buffer
-to bury. It is also called by @code{quit-restore-window} (see above)
-when the frame of the window to quit has been specially created for
-displaying that window's buffer and the buffer is not killed.
+The function specified here is called by @code{bury-buffer}
+(@pxref{Buffer List}) when the selected window is dedicated and shows
+the buffer to bury. It is also called by @code{quit-restore-window}
+(see above) when the frame of the window to quit has been specially
+created for displaying that window's buffer and the buffer is not
+killed.
The default is to call @code{iconify-frame} (@pxref{Visibility of
Frames}). Alternatively, you may specify either @code{delete-frame}
@node Window Start and End
@section The Window Start and End Positions
@cindex window start position
+@cindex display-start position
Each window maintains a marker used to keep track of a buffer position
that specifies where in the buffer display should start. This position
@end defun
@defvar auto-window-vscroll
-If this variable is non-@code{nil}, the line-move, scroll-up, and
-scroll-down functions will automatically modify the vertical scroll
-position to scroll through display rows that are taller than the height
-of the window, for example in the presence of large images.
+If this variable is non-@code{nil}, the @code{line-move},
+@code{scroll-up}, and @code{scroll-down} functions will automatically
+modify the vertical scroll position to scroll through display rows
+that are taller than the height of the window, for example in the
+presence of large images.
@end defvar
@node Horizontal Scrolling
the horizontal scrolling of a window as necessary to ensure that point
is always visible. However, you can still set the horizontal
scrolling value explicitly. The value you specify serves as a lower
-bound for automatic scrolling, i.e. automatic scrolling will not
+bound for automatic scrolling, i.e., automatic scrolling will not
scroll a window to a column less than the specified one.
@deffn Command scroll-left &optional count set-minimum
Here is how you can determine whether a given position @var{position}
is off the screen due to horizontal scrolling:
+@c FIXME: Maybe hscroll-on-screen-p is a better name?
@example
@group
(defun hscroll-on-screen (window position)
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
+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.
right of the rightmost column, and the Y coordinate one row down from
the bottommost row.
-Note that these are the actual outer edges of the window, including
-any header line, mode line, scroll bar, fringes, and display 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
+Note that these are the actual outer edges of the window, including any
+header line, mode line, scroll bar, fringes, window divider and display
+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, display margins, and vertical
-separator.
+line, mode line, scroll bar, fringes, window divider, display margins,
+and vertical separator.
@end defun
@defun window-top-line &optional window
@item header-line
The coordinates are in the header line of @var{window}.
+@item right-divider
+The coordinates are in the divider separating @var{window} from a
+window on the right.
+
+@item right-divider
+The coordinates are in the divider separating @var{window} from a
+window beneath.
+
@item vertical-line
The coordinates are in the vertical line between @var{window} and its
neighbor to the right. This value occurs only if the window doesn't
the display screen. @var{window} must specify a live window.
@end defun
+@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.
+@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.
+@end defun
+
+
@node Window Configurations
@section Window Configurations
@cindex window configurations
A @dfn{window configuration} records the entire layout of one
frame---all windows, their sizes, which buffers they contain, how those
-buffers are scrolled, and their values of point and the mark; also their
+buffers are scrolled, and their value of point; also their
fringes, margins, and scroll bar settings. It also includes the value
of @code{minibuffer-scroll-window}. As a special exception, the window
configuration does not record the value of point in the selected window
@defun compare-window-configurations config1 config2
This function compares two window configurations as regards the
-structure of windows, but ignores the values of point and mark and the
+structure of windows, but ignores the values of point and the
saved scrolling positions---it can return @code{t} even if those
aspects differ.
The function @code{equal} can also compare two window configurations; it
regards configurations as unequal if they differ in any respect, even a
-saved point or mark.
+saved point.
@end defun
@defun window-configuration-frame config
(@code{set-window-configuration} effectively clones the windows of a
frame into the root window of that very frame only).
+@cindex window state
@defun window-state-get &optional window writable
This function returns the state of @var{window} as a Lisp object. The
argument @var{window} must be a valid window and defaults to the root
the following function to restore the state of the window.
@defun window-state-put state &optional window ignore
-This function puts the window state @var{state} into @var{window}. The
-argument @var{state} should be the state of a window returned by an
-earlier invocation of @code{window-state-get}, see above. The optional
-argument @var{window} must specify a live window and defaults to the
-selected one.
+This function puts the window state @var{state} into @var{window}.
+The argument @var{state} should be the state of a window returned by
+an earlier invocation of @code{window-state-get}, see above. The
+optional argument @var{window} can be either a live window or an
+internal window (@pxref{Windows and Frames}) and defaults to the
+selected one. If @var{window} is not live, it is replaced by a live
+window before putting @var{state} into it.
If the optional argument @var{ignore} is non-@code{nil}, it means to ignore
minimum window sizes and fixed-size restrictions. If @var{ignore}
from. It is installed by @code{window-state-get} (@pxref{Window
Configurations}).
+@item @code{preserved-size}
+This parameter specifies a buffer, a direction where @code{nil} means
+vertical and @code{t} horizontal, and a size in pixels. If this window
+displays the specified buffer and its size in the indicated direction
+equals the size specified by this parameter, then Emacs will try to
+preserve the size of this window in the indicated direction. This
+parameter is installed and updated by the function
+@code{window-preserve-size} (@pxref{Preserving Window Sizes}).
+
@item @code{quit-restore}
This parameter is installed by the buffer display functions
(@pxref{Choosing Window}) and consulted by @code{quit-restore-window}
(@pxref{Quitting Windows}). It contains four elements:
-The first element is one of the symbols @code{window} - meaning that the
-window has been specially created by @code{display-buffer}, @code{frame}
-- a separate frame has been created, @code{same} - the window has
-displayed the same buffer before, or @code{other} - the window showed
+The first element is one of the symbols @code{window}, meaning that the
+window has been specially created by @code{display-buffer}; @code{frame},
+a separate frame has been created; @code{same}, the window has
+displayed the same buffer before; or @code{other}, the window showed
another buffer before.
The second element is either one of the symbols @code{window} or