@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2011
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/windows
@section Basic Concepts of Emacs Windows
@cindex window
-A @dfn{window} in Emacs is the physical area of the screen in which a
-buffer is displayed, see @ref{Buffers}. The term is also used to refer
-to a Lisp object that represents that screen area in Emacs Lisp. It
-should be clear from the context which is meant.
+A @dfn{window} is a area of the screen which is used to display a
+buffer (@pxref{Buffers}). In Emacs Lisp, windows are represented by a
+special Lisp object type.
@cindex multiple windows
- Emacs groups windows into frames; see @ref{Frames}. Each frame always
-contains at least one window, but you can subdivide it into multiple,
-non-overlapping Emacs windows. Users create multiple windows so they
-can look at several buffers at once. Lisp libraries use multiple
-windows for a variety of reasons, but most often to display related
-information. In Rmail, for example, you can move through a summary
-buffer in one window while the other window shows messages one at a time
-as they are reached.
+ Windows are grouped into frames (@pxref{Frames}). Each frame
+contains at least one window; the user can subdivide it into multiple,
+non-overlapping windows to view several buffers at once. Lisp
+programs can use multiple windows for a variety of purposes. In
+Rmail, for example, you can view a summary of message titles in one
+window, and the contents of the selected message in another window.
@cindex terminal screen
@cindex screen of terminal
- The meaning of ``window'' in Emacs is similar to what it means in the
-context of general-purpose window systems such as X, but not identical.
-The X Window System places X windows on the screen; Emacs uses one or
-more X windows as frames, and subdivides them into Emacs windows. When
-you use Emacs on a character-only terminal, Emacs treats the whole
-terminal screen as one frame.
+ Emacs uses the word ``window'' with a different meaning than in
+graphical desktop environments and window systems, such as the X
+Window System. When Emacs is run on X, each of its graphical X
+windows is an Emacs frame (containing one or more Emacs windows).
+When Emacs is run on a text-only terminal, the frame fills the entire
+terminal screen.
@cindex tiled windows
- Most window systems support arbitrarily located overlapping windows.
-In contrast, Emacs windows are @dfn{tiled}; they never overlap, and
-together they fill the whole screen or frame. Because of the way in
-which Emacs creates new windows (@pxref{Splitting Windows}) and resizes
-them (@pxref{Resizing Windows}), not all conceivable tilings of windows
-on an Emacs frame are actually possible.
-
- For practical purposes, a window exists only while it is displayed in
-a frame. Once removed from the frame, the window is effectively deleted
-and should not be used, even though the Lisp object representing it
-might be still referenced from other Lisp objects; see @ref{Deleting
-Windows}. Restoring a saved window configuration is the only way for a
-window no longer on the screen to come back to life; see @ref{Window
-Configurations}.
-
-@defun windowp object
-This function returns @code{t} if @var{object} is a window, @code{nil}
-otherwise. It can return @code{t} if @var{object} denotes a window that
-has been deleted.
-@end defun
+ Unlike X windows, Emacs windows are @dfn{tiled}; they never overlap
+within the area of the frame. When a window is created, resized, or
+deleted, the change in window space is taken from or given to the
+adjacent windows, so that the total area of the frame is unchanged.
@cindex live windows
@cindex internal windows
- For historical reasons a window is considered @dfn{live} if and only
-if it currently displays a buffer; see @ref{Buffers and Windows}. In
-order to show multiple windows within one and the same frame, Emacs
-organizes them in form of a tree called window tree; see @ref{Windows
-and Frames}. The internal nodes of a window tree are called internal
-windows and are not considered live. The leaf nodes of a window tree
-constitute the windows displaying buffers and only they will be called
-live here.
+ A @dfn{live window} is one that is actually displaying a buffer in a
+frame. Such a window can be @dfn{deleted}, i.e. removed from the
+frame (@pxref{Deleting Windows}); then it is no longer live, but the
+Lisp object representing it might be still referenced from other Lisp
+objects. A deleted window may be brought back to life by restoring a
+saved window configuration (@pxref{Window Configurations}).
+
+@defun windowp object
+This function returns @code{t} if @var{object} is a window (whether or
+not it is live). Otherwise, it returns @code{nil}.
+@end defun
@defun window-live-p object
This function returns @code{t} if @var{object} is a live window and
-@code{nil} otherwise. A live window is a window that displays a buffer.
+@code{nil} otherwise. A live window is one that displays a buffer.
@end defun
-@defun window-any-p object
-This function returns @code{t} if @var{object} denotes a live or an
-internal window and @code{nil} otherwise. In particular, this function
-returns @code{nil} if @var{object} is a window that has been
-deleted.
+ The windows in each frame are organized into a @dfn{window tree}.
+@xref{Windows and Frames}. The leaf nodes of each window tree are
+live windows---the ones actually displaying buffers. The internal
+nodes of the window tree are internal windows, which are not live.
+You can distinguish internal windows from deleted windows with
+@code{window-valid-p}.
+
+@defun window-valid-p object
+This function returns @code{t} if @var{object} is a live window, or an
+internal window in a window tree. Otherwise, it returns @code{nil},
+including for the case where @var{object} is a deleted window.
@end defun
@cindex selected window
-In each frame, at any time, one and only one window is designated as
-@dfn{selected within the frame}. Also, at any time, one frame is the
-selected frame (@pxref{Input Focus}). The window selected within the
-selected frame is the @dfn{selected window}.
-
- The selected window is always a live window. Its buffer is usually
-the current buffer (except when @code{set-buffer} has been used); see
-@ref{Current Buffer}.
+@cindex window selected within a frame
+ In each frame, at any time, exactly one Emacs window is designated
+as @dfn{selected within the frame}. For the selected frame, that
+window is called the @dfn{selected window}---the one in which most
+editing takes place, and in which the cursor for selected windows
+appears (@pxref{Cursor Parameters}). The selected window's buffer is
+usually also the current buffer, except when @code{set-buffer} has
+been used (@pxref{Current Buffer}). As for non-selected frames, the
+window selected within the frame becomes the selected window if the
+frame is ever selected. @xref{Selecting Windows}.
@defun selected-window
-This function returns the selected window. This is the window in which
-the cursor for selected windows (@pxref{Cursor Parameters}) appears and
-to which many commands apply.
-@end defun
-
-The window handling functions can be roughly grouped into functions
-operating on live windows only and functions that accept any window as
-argument. Many of these functions accept as argument the value
-@code{nil} to specify the selected window. The two functions below can
-be used to ``normalize'' arguments specifying windows in a uniform
-manner.
-
-@defun window-normalize-any-window window
-This function returns the normalized value for @var{window} which can be
-any window that has not been deleted. More precisely, if @var{window}
-is @code{nil}, it returns the selected window. If @var{window} denotes
-a live or internal window, it returns that window. Otherwise, this
-function signals an error.
-@end defun
-
-@defun window-normalize-live-window window
-This functions returns the normalized value for a live window
-@var{window}. More precisely, if @var{window} is @code{nil}, it returns
-the selected window. If @var{window} is a live window, it returns that
-window. Otherwise, this function signals an error.
+This function returns the selected window (which is always a live
+window).
@end defun
-
@node Windows and Frames
@section Windows and Frames
-Each window is part of one and only one frame (@pxref{Frames}); you can
-get that frame with the function described next.
+Each window belongs to exactly one frame (@pxref{Frames}).
@defun window-frame window
-This function returns the frame that @var{window} is on. The argument
-@var{window} can be any window and defaults to the selected one.
+This function returns the frame that the window @var{window} belongs
+to. If @var{window} is @code{nil}, it defaults to the selected
+window.
@end defun
-The following function returns a list of all live windows on a specific
-frame.
+@defun window-list &optional frame minibuffer window
+This function returns a list of live windows belonging to the frame
+@var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to
+the selected frame.
-@defun window-list &optional frame minibuf window
-This function returns a list of @var{frame}'s live windows, starting
-with @var{window}. The optional argument @var{frame} has to denote a
-live frame and defaults to the selected frame. The optional argument
-@var{window} has to denote a live window on the frame specified by
-@var{frame} and defaults to the selected one.
+The optional argument @var{minibuffer} specifies whether to include
+the minibuffer window in the returned list. If @var{minibuffer} is
+@code{t}, the minibuffer window is included. If @var{minibuffer} is
+@code{nil} or omitted, the minibuffer window is included only if it is
+active. If @var{minibuffer} is neither @code{nil} nor @code{t}, the
+minibuffer window is never included.
-The argument @var{minibuf} specifies if the minibuffer window shall be
-included in the return value. If @var{minibuf} is @code{t}, the result
-always includes the minibuffer window. If @var{minibuf} is @code{nil}
-or omitted, that includes the minibuffer window only if it is active.
-If @var{minibuf} is neither @code{nil} nor @code{t}, the result never
-includes the minibuffer window.
+The optional argument @var{window}, if non-@code{nil}, should be a live
+window on the specified frame; then @var{window} will be the first
+element in the returned list. If @var{window} is omitted or @code{nil},
+the window selected within the frame is the first element.
@end defun
@cindex window tree
-Windows within one and the same frame are organized in form of a tree
-called @dfn{window tree}. The leaf nodes of a window tree constitute
-the windows visible to the user. These are the windows associated with
-buffers and are usually called live windows. The internal nodes of a
-window tree are needed for finding, traversing and displaying the live
-windows.
-
- A minibuffer window (@pxref{Minibuffer Windows}) is not considered
-part of its frame's window tree unless the frame is a minibuffer-only
-frame. Most functions covered in this section accept, however, the
-minibuffer window as argument. Also, the minibuffer window is listed by
-the function @code{window-tree} described at the end of this section.
-
- A window tree is rooted at the root window of its frame.
+@cindex root window
+ Windows in the same frame are organized into a @dfn{window tree},
+whose leaf nodes are the live windows. The internal nodes of a window
+tree are not live; they exist for the purpose of organizing the
+relationships between live windows. The root node of a window tree is
+called the @dfn{root window}. It can be either a live window (if the
+frame has just one window), or an internal window.
+
+ A minibuffer window (@pxref{Minibuffer Windows}) is not part of its
+frame's window tree unless the frame is a minibuffer-only frame.
+Nonetheless, most of the functions in this section accept the
+minibuffer window as an argument. Also, the function
+@code{window-tree} described at the end of this section lists the
+minibuffer window alongside the actual window tree.
@defun frame-root-window &optional frame-or-window
-This function returns the root window of @var{frame-or-window}. The
-argument @var{frame-or-window} has to denote either a window or a frame
-and defaults to the selected frame. If @var{frame-or-window} denotes a
-window, the return value is the root window of that window's frame.
-This function always returns a window; a live window if the frame
-specified by @var{frame-or-window} contains no other live windows and an
-internal window otherwise.
+This function returns the root window for @var{frame-or-window}. The
+argument @var{frame-or-window} should be either a window or a frame;
+if omitted or @code{nil}, it defaults to the selected frame. If
+@var{frame-or-window} is a window, the return value is the root window
+of that window's frame.
@end defun
-@cindex subwindow
-All other windows of a frame with the exception of the minibuffer window
-are subwindows of the frame's root window. A window is considered a
-@dfn{subwindow} of another window if it occupies a part of that other
-window's screen area.
-
-The functions described next allow to access the members of a window
-tree and take an arbitrary window as argument.
+@cindex parent window
+@cindex child window
+@cindex sibling window
+ When a window is split, there are two live windows where previously
+there was one. One of these is represented by the same Lisp window
+object as the original window, and the other is represented by a
+newly-created Lisp window object. Both of these live windows become
+leaf nodes of the window tree, as @dfn{child windows} of a single
+internal window. If necessary, Emacs automatically creates this
+internal window, which is also called the @dfn{parent window}, and
+assigns it to the appropriate position in the window tree. A set of
+windows that share the same parent are called @dfn{siblings}.
@cindex parent window
@defun window-parent &optional window
-Return @var{window}'s parent in the window tree. The optional argument
-@var{window} can denote an arbitrary window and defaults to the selected
-one. The return value is @code{nil} if @var{window} is a minibuffer
-window or the root window of its frame and an internal window otherwise.
+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).
@end defun
-@cindex child window
- Parent windows do not appear on the screen. The screen area of a
-parent window is the rectangular part of the window's frame occupied by
-the window's @dfn{child windows}, that is, the set of windows having
-that window as their parent. Each parent window has at least two child
-windows, so there are no ``Matryoshka'' windows. Minibuffer windows do
-not have child windows.
+ Each internal window always has at least two child windows. If this
+number falls to one as a result of window deletion, Emacs
+automatically deletes the internal window, and its sole remaining
+child window takes its place in the window tree.
+
+ Each child window can be either a live window, or an internal window
+(which in turn would have its own child windows). Therefore, each
+internal window can be thought of as occupying a certain rectangular
+@dfn{screen area}---the union of the areas occupied by the live
+windows that are ultimately descended from it.
@cindex window combination
@cindex vertical combination
@cindex horizontal combination
-The children of any parent window form either a vertical or a horizontal
-combination of windows. A @dfn{vertical combination} is a set of
-windows arranged one above each other. A @dfn{horizontal combination}
-is a set of windows arranged side by side. Consider the frame shown
-below (for simplicity we assume that the frame does not contain a
-minibuffer window):
+ For each internal window, the screen areas of the immediate children
+are arranged either vertically or horizontally (never both). If the
+child windows are arranged one above the other, they are said to form
+a @dfn{vertical combination}; if they are arranged side by side, they
+are said to form a @dfn{horizontal combination}. Consider the
+following example:
@smallexample
@group
______________________________________
| ______ ____________________________ |
|| || __________________________ ||
- || ||| ___________ ___________ |||
- || |||| || ||||
- || |||| || ||||
- || ||||_____W6____||_____W7____||||
+ || ||| |||
+ || ||| |||
+ || ||| |||
|| |||____________W4____________|||
|| || __________________________ ||
|| ||| |||
+ || ||| |||
|| |||____________W5____________|||
||__W2__||_____________W3_____________ |
|__________________W1__________________|
@end group
@end smallexample
-The root window of the frame is @code{W1}---a horizontal combination of
-the live window @code{W2} and the internal window @code{W3}. Hence
-@code{(window-parent W1)} is @code{nil} while @code{(window-parent W2)}
-and @code{(window-parent W3)} are both @code{W1}.
-
- The internal window @code{W3} is a vertical combination of @code{W4}
-and the live window @code{W5}. The internal window @code{W4} is a
-horizontal combination of the live windows @code{W6} and @code{W7}. The
-windows you can actually see on the screen are @code{W2}, @code{W5},
-@code{W6} and @code{W7}.
-
- For any parent window, the first child window can be retrieved by the
-functions given next.
-
-@defun window-top-child &optional window
-This function returns @var{window}'s first vertical child window. The
-optional argument @var{window} can be an arbitrary window and defaults
-to the selected one. The return value is @code{nil} if @var{window} is
-a live window or its children form a horizontal combination. In the
-example above @code{(window-top-child W3)} is @code{W4} while
-@code{(window-top-child W4)} is @code{nil}.
+@noindent
+The root window of this frame is an internal window, @code{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}.
+
+ 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
+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 &optional window
-This function returns @var{window}'s first horizontal child window. The
-optional argument @var{window} can be an arbitrary window and defaults
-to the selected one. The return value is @code{nil} if @var{window} is
-a live window or its children form a vertical combination. In the
-example above @code{(window-left-child W4)} is @code{W6} while
-@code{(window-left-child W3)} is @code{nil}.
+@defun window-left-child 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
+@code{nil}.
@end defun
@defun window-child window
-This function return @var{window}'s first child window. The return
-value is @code{nil} if @var{window} is a live window. In the example
-above @code{(window-child W3)} is @code{W4} while @code{(window-child
-W4)} is @code{W6}.
+This function returns the first child window of the internal window
+@var{window}---the topmost child window for a vertical combination, or
+the leftmost child window for a horizontal combination. If
+@var{window} is a live window, the return value is @code{nil}.
@end defun
-The following function is useful to determine whether a window is part
-of a vertical or horizontal combination.
-
-@defun window-iso-combined-p &optional window horizontal
-This function returns non-@code{nil} if and only if @var{window} is
-vertically combined. The argument @var{window} can specify any window
-and defaults to the selected one. The actual return value is the first
-vertical child of window.
+@defun window-combined-p &optional window horizontal
+This function returns a non-@code{nil} value if and only if
+@var{window} is part of a vertical combination. If @var{window} is
+omitted or @code{nil}, it defaults to the selected one.
-If the optional argument @var{horizontal} is non-@code{nil}, this means
-to return non-@code{nil} if and only if @var{window} is horizontally
-combined. In this case, the return value is the first horizontal child
-of window.
+If the optional argument @var{horizontal} is non-@code{nil}, this
+means to return non-@code{nil} if and only if @var{window} is part of
+a horizontal combination.
@end defun
-@cindex sibling window
-For any window that is part of a combination, the other windows in that
-combination are called the window's @dfn{siblings}. The only windows
-that do not have siblings are root windows of frames and minibuffer
-windows. A window's siblings can be retrieved with the following two
-functions.
-
@defun window-next-sibling &optional window
-This function returns @var{window}'s next sibling. The optional
-argument @var{window} can be an arbitrary window and defaults to the
-selected window. It returns @code{nil} if @var{window} is the last
-child of its parent. In our example @code{(window-next-sibling W2)} is
-@code{W3} while @code{(window-next-sibling W3)} is @code{nil}.
+This function returns the next sibling of the window @var{window}. If
+omitted or @code{nil}, @var{window} defaults to the selected window.
+The return value is @code{nil} if @var{window} is the last child of
+its parent.
@end defun
@defun window-prev-sibling &optional window
-This function returns @var{window}'s previous sibling. The optional
-argument @var{window} can be an arbitrary window and defaults to the
-selected window. It returns @code{nil} if @var{window} is the first
-child of its parent. In our example @code{(window-prev-sibling W3)} is
-@code{W2} and @code{(window-prev-sibling W2)} is @code{nil}.
+This function returns the previous sibling of the window @var{window}.
+If omitted or @code{nil}, @var{window} defaults to the selected
+window. The return value is @code{nil} if @var{window} is the first
+child of its parent.
@end defun
-The functions @code{window-next-sibling} and @code{window-prev-sibling}
-should not be confused with the functions @code{next-window} and
-@code{previous-window} which respectively return the next and previous
-window in the cyclic ordering of windows, see @ref{Cyclic Window
-Ordering}.
+The functions @code{window-next-sibling} and
+@code{window-prev-sibling} should not be confused with the functions
+@code{next-window} and @code{previous-window} which respectively
+return the next and previous window in the cyclic ordering of windows
+(@pxref{Cyclic Window Ordering}).
- In order to find the first live window on a frame, the following
-function can be used.
+ 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:
@defun frame-first-window &optional frame-or-window
This function returns the live window at the upper left corner of the
@code{(frame-first-window)} returns @code{W2}.
@end defun
-You can get the window tree of a frame with the following function.
-
-@cindex window tree
@defun window-tree &optional frame
-This function returns the window tree for frame @var{frame}. The
-optional argument @var{frame} must be a live frame and defaults to the
-selected one.
+This function returns a list representing the window tree for frame
+@var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to
+the selected frame.
The return value is a list of the form @code{(@var{root} @var{mini})},
-where @var{root} represents the window tree of the frame's
-root window, and @var{mini} is the frame's minibuffer window.
+where @var{root} represents the window tree of the frame's root
+window, and @var{mini} is the frame's minibuffer window.
-If the root window is live, @var{root} specifies the root window and
-nothing else. Otherwise, @var{root} is a list @code{(@var{dir}
-@var{edges} @var{w1} @var{w2} ...)} where @var{dir} is @code{nil} for a
-horizontal combination, and @code{t} for a vertical combination,
-@var{edges} gives the size and position of the combination, and the
-remaining elements are the child windows. Each child window may again
-be a live window or a list representing a window combination, and so on.
-The @var{edges} element is a list @code{(@var{left}@var{ top}@var{
-right}@var{ bottom})} similar to the value returned by
-@code{window-edges}, see @ref{Coordinates and Windows}.
+If the root window is live, @var{root} is that window itself.
+Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1}
+@var{w2} ...)} where @var{dir} is @code{nil} for a horizontal
+combination and @code{t} for a vertical combination, @var{edges} gives
+the size and position of the combination, and the remaining elements
+are the child windows. Each child window may again be a window object
+(for a live window) or a list with the same format as above (for an
+internal window). The @var{edges} element is a list @code{(@var{left}
+@var{top} @var{right} @var{bottom})}, similar to the value returned by
+@code{window-edges} (@pxref{Coordinates and Windows}).
@end defun
-
@node Window Sizes
@section Window Sizes
@cindex window size
@cindex size of window
-Emacs windows are rectangular. The structure of a live window can be
-roughly sketched as follows:
+ The following schematic shows the structure of a live window:
@smallexample
@group
- _________________________________________
- ^ |______________ Header Line_______________|
+ _________________________________________
+ ^ |______________ Header Line_______________|
| |LS|LF|LM| |RM|RF|RS| ^
| | | | | | | | | |
Window | | | | Text Area | | | | Window
@end smallexample
@cindex window body
+@cindex text area of a window
@cindex body of a window
-The text area constitutes the body of the window. In its most simple
-form, a window consists of its body alone. LS and RS stand for the left
-and right scroll bar (@pxref{Scroll Bars}) respectively. Only one of
-them can be present at any time. LF and RF denote the left and right
-fringe, see @ref{Fringes}. LM and RM, finally, stand for the left and
-right display margin, see @ref{Display Margins}. The header line, if
-present, is located above theses areas, the mode line below, see
-@ref{Mode Line Format}.
+ 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.
@cindex window height
-@cindex total window height
@cindex height of a window
@cindex total height of a window
-The @dfn{total height of a window} is specified as the total number of
-lines occupied by the window. Any mode or header line is included in a
-window's total height. For an internal window, the total height is
-calculated recursively from the total heights of its child windows.
-
@cindex window width
-@cindex total window width
@cindex width of a window
@cindex total width of a window
-The @dfn{total width of a window} denotes the total number of columns of
-the window. Any scroll bar and the column of @samp{|} characters that
-separate the window from its right sibling are included in a window's
-total width. On a window-system, fringes and display margins are
-included in a window's total width too. For an internal window, the
-total width is calculated recursively from the total widths of its child
-windows.
-
-@cindex total size of a window
-@cindex total window size
-The following function is the standard interface for getting the total
-size of any window:
-
-@defun window-total-size &optional window &optional horizontal
-This function returns the total number of lines of @var{window}. The
-argument @var{window} can denote any window and defaults to the selected
-one. If @var{window} is live, the return value includes any header or
-mode lines of @var{window}. If @var{window} is internal, the return
-value is the sum of the total heights of @var{window}'s child windows
-provided these are vertically combined and the height of @var{window}'s
-first child if they are horizontally combined.
-
- If the optional argument @var{horizontal} is non-@code{nil}, this
-function returns the total number of columns of @var{window}. If
-@var{window} is live, the return value includes any vertical divider
-column or scroll bars of @var{window}. On a window-system, the return
-value includes the space occupied by any margins and fringes of
-@var{window} too. If @var{window} is internal, the return value is the
-sum of the total widths of @var{window}'s child windows provided these
-are horizontally combined and the width of @var{window}'s first child
-otherwise.
-@end defun
-
-Alternatively, the following two functions can be used to retrieve
-either the total height or the 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}).
@defun window-total-height &optional window
-This function returns the total number of lines of @var{window}.
-@var{window} can be any window and defaults to the selected one. The
-return value includes @var{window}'s mode line and header line, if any.
-If @var{window} is internal the return value is the sum of heights of
-@var{window}'s child windows for a vertical combination and the height
-of @var{window}'s first child otherwise.
+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.
@end defun
@defun window-total-width &optional window
-This function returns the total number of columns of @var{window}.
-@var{window} can be any window and defaults to the selected one. The
-return value includes any vertical dividers or scrollbars of
-@var{window}. On a window-system the return value also includes the
-space occupied by any margins and fringes of @var{window}. If
-@var{window} is internal, the return value is the sum of the widths of
-@var{window}'s child windows for a horizontal combination and the width
-of @var{window}'s first child otherwise.
-@end defun
-
-The total height of any window is usually less than the height of the
-window's frame, because the latter may also include the minibuffer
-window. Depending on the toolkit in use, the frame height can also
-include the menu bar and the tool bar (@pxref{Size and Position}).
-Therefore, in general it is not straightforward to compare window and
-frame heights. The following function is useful to determine whether
-there are no other windows above or below a specified window.
-
-@cindex full-height window
-@defun window-full-height-p &optional window
-This function returns non-@code{nil} if there is no other window above
-or below @var{window} on the containing frame. More precisely, this
-function returns @code{t} if and only if the total height of
-@var{window} equals the total height of the root window (@pxref{Windows
-and Frames}) of @var{window}'s frame. The @var{window} argument may
-denote any window and defaults to the selected one.
+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.
@end defun
-@cindex full-width window
-The following function can be used to determine whether there are no
-other windows on the left or right of a specified window.
-
-@defun window-full-width-p &optional window
-This function returns non-@code{nil} if there are no other windows on
-the left or right of @var{window}; @code{nil} otherwise. More
-precisely, this function returns @code{t} if and only if the total width
-of @var{window} equals the total width of the root window
-(@pxref{Windows and Frames}) of @var{window}'s frame. The @var{window}
-argument may denote any window and defaults to the selected one.
+@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}.
@end defun
-@cindex top line of window
-@cindex left column of window
- The windows of a frame are unambiguously characterized by the
-combination of their top line and left column within that frame.
+@cindex full-width window
+@cindex full-height window
+ The following functions can be used to determine whether a given
+window has any adjacent windows.
-@defun window-top-line &optional window
-This function returns the top line of @var{window}. The argument
-@var{window} can denote any window and defaults to the selected one.
+@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.
@end defun
-@defun window-left-column &optional window
-This function returns the left column of @var{window}. The argument
-@var{window} can denote any window and defaults to the selected one.
+@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
+that of the root window on that frame. If @var{window} is omitted or
+@code{nil}, it defaults to the selected window.
@end defun
-For a frame displaying one window only, that window's top line and left
-column are both zero. When a frame displays a window @var{WB} below a
-window @var{WA}, the top line of @var{WB} can be calculated by adding
-the total height of @var{WA} to the top line of @var{WA}. When a frame
-displays a window @var{WR} on the right of a window @var{WL}, the left
-column of @var{WR} can be calculated by adding the total width of
-@var{WL} to the left column of @var{WL}.
-
@cindex window body height
@cindex body height of a window
-The @dfn{body height of a window} is specified as the total number of
-lines occupied by the window's text area. Mode or header lines are not
-included in a window's body height.
-
@cindex window body width
@cindex body width of a window
-The @dfn{body width of a window} denotes the total number of columns
-occupied by the window's text area. Scroll bars or columns of @samp{|}
-characters that separate side-by-side windows are not included in a
-window's body width.
-
@cindex body size of a window
@cindex window body size
-The following functions retrieve height and width of the body of a live
-window:
-
-@defun window-body-size &optional window horizontal
-This function returns the number of lines of @var{window}'s text area.
-@var{window} must be a live window and defaults to the selected one.
-The return value does not count any mode or header line of @var{window}.
-
-Optional argument @var{horizontal} non-@code{nil} means to return the
-number of columns of @var{window}'s text area. In this case the return
-value does not include any vertical divider or scroll bar owned by
-@var{window}. On a window-system the return value does not include the
-number of columns used for @var{window}'s fringes or display margins
-either.
-@end defun
+ 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 number of lines of @var{window}'s body.
-@var{window} must be a live window and defaults to the selected one.
+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.
-The return value does not include @var{window}'s mode line and header
-line, if any. If a line at the bottom of the window is only partially
-visible, that line is included in the return value. If you do not
-want to include a partially visible bottom line in the return value,
-use @code{window-text-height} instead.
+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 number of columns of @var{window}'s body.
-@var{window} must be a live window and defaults to the selected one.
-
-The return value does not include any vertical dividers or scroll bars
-owned by @var{window}. On a window-system the return value does not
-include the number of columns used for @var{window}'s fringes or
-display margins either.
+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
-The following functions have been used in earlier versions of Emacs.
-They are still supported but due to the confusing nomenclature they
-should not be used any more in future code.
-
-@defun window-height &optional window
-This function is an alias for `window-total-height', see above.
+@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}.
@end defun
-@defun window-width &optional window
-This function is an alias for `window-body-width', see above.
+@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.
@end defun
-@cindex minimum window size
- The following two options constrain the sizes of windows to a minimum
-height and width. Their values are honored when windows are split
-(@pxref{Splitting Windows}) or resized (@pxref{Resizing Windows}). Any
-request to make a window smaller than specified here will usually result
-in an error.
-
-@defopt window-min-height
-The value of this variable specifies how short a window may be. The
-value is measured in line units and has to account for any header or
-mode line. The default value for this option is @code{4}. Values less
-than @code{1} are ignored.
-@end defopt
-
-@defopt window-min-width
-The value of this variable specifies how narrow a window may be. The
-value is measured in characters and includes any margins, fringes,
-scroll bar and vertical divider column. The default value for this
-option is @code{10}. A value less than @code{2} is ignored.
-@end defopt
-
-Applications should not rebind these variables. To shrink a specific
-window to a height or width less than the one specified here, they
-should rather invoke @code{window-resize} (@pxref{Resizing Windows})
-with a non-@code{nil} @var{ignore} argument. The function
-@code{split-window} (@pxref{Splitting Windows}) can make a window
-smaller than specified here by calling it with a non-@code{nil}
-@var{size} argument. Interactively, the values specified here cannot be
-overridden.
-
- Earlier versions of Emacs could delete a window when its size dropped
-below @code{window-min-height} or @code{window-min-width}. As a rule,
-the current version of Emacs does no more delete windows by side-effect.
-The only exception to this rule are requests to resize a frame which may
-implicitly delete windows when they do not fit on the frame any more,
-see @ref{Size and Position}.
-
- The size of a window can be fixed which means that it cannot be split
-(@pxref{Splitting Windows}) or resized (@pxref{Resizing Windows}).
+ 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.
@cindex fixed-size window
+ 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 variable is non-@code{nil}, in a given buffer, then the size of
-any window displaying that buffer remains fixed unless you either
-explicitly change it or Emacs has no other choice.
+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.
-
-This variable automatically becomes buffer-local when set.
@end defvar
-Commands supposed to explicitly change the size of windows such as
-@code{enlarge-window} (@pxref{Resizing Windows}) get an error if they
-had to change a window size which is fixed. Other functions like
-@code{window-resize} (@pxref{Resizing Windows}) have an optional
-@var{ignore} argument which allows to change the size of fixed-size
-windows.
-
- Deleting a window or changing a frame's size may change the size of a
-fixed-size window, if there is no other alternative.
-
- The height of a vertical combination of windows cannot be changed
-when the height of all these windows is fixed. Its width cannot be
-changed if the width of at least one of these windows is fixed.
-Similarly, the width of a horizontal combination of windows cannot be
-changed when the width of all these windows is fixed. Its height cannot
-be changed if the height of at least one of these windows is fixed.
-
- The next function allows to check whether the size of an arbitrary
-window is fixed.
-
@defun window-size-fixed-p &optional window horizontal
-This function returns non-@code{nil} if @var{window}'s height is fixed.
-The argument @var{window} can be an arbitrary window and defaults to the
-selected one. Optional argument @var{horizontal} non-@code{nil} means
-return non-@code{nil} if @var{window}'s width is fixed.
+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.
-If this function returns @code{nil}, this does not necessarily mean that
-@var{window} can be resized in the desired direction. The function
-@code{window-resizable} (@pxref{Resizing Windows}) can tell that.
+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}.
@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 changing window size
@cindex window size, changing
-Emacs does not permit overlapping windows or gaps between windows, so
-changing the size of a window always affects at least one other window.
-When a frame contains just one window, that window can be resized only
-by resizing the window's frame. The functions described below are
-therefore meaningful only in the context of a frame containing at least
-two windows. The size of the corresponding frame never changes when
-invoking a function described in this section.
-
- The routines changing window sizes always operate in one dimension at
-a time. This means that windows can be resized only either vertically
-or horizontally. If a window shall be resized in both dimensions, it
-must be resized in one dimension first and in the other dimension
-afterwards. If the second resize operation fails, the frame might end
-up in an unsatisfactory state. To avoid such states, it might be useful
-to save the current window configuration (@pxref{Window Configurations})
-before attempting the first resize operation and restore the saved
-configuration in case the second resize operation fails.
-
- Functions that resize windows are supposed to obey restrictions
-imposed by window minimum sizes and fixed-size windows, see @ref{Window
-Sizes}. In order to determine whether resizing a specific window is
-possible in the first place, the following function can be used:
-
-@defun window-resizable window delta &optional horizontal ignore side noup nodown
+ This section describes functions for resizing a window without
+changing the size of its frame. Because live windows do not overlap,
+these functions are meaningful only on frames that contain two or more
+windows: resizing a window also changes the size of a neighboring
+window. If there is just one window on a frame, its size cannot be
+changed except by resizing the frame (@pxref{Size and Position}).
+
+ Except where noted, these functions also accept internal windows as
+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
This function returns @var{delta} if the size of @var{window} can be
-changed vertically by @var{delta} lines. Optional argument
-@var{horizontal} non-@code{nil} means to return @var{delta} if
-@var{window} can be resized horizontally by @var{delta} columns. A
-return value of zero means that @var{window} is not resizable.
-
-If @var{delta} is a positive number, this means that @var{window} shall
-be enlarged by @var{delta} lines or columns. If @var{window} cannot be
-enlarged by @var{delta} lines or columns, this function returns the
-maximum value in the range from 0 to @var{delta} by which @var{window}
-can be enlarged.
-
-If @var{delta} is a negative number, this means that @var{window} shall
-be shrunk by -@var{delta} lines or columns. If @var{window} cannot be
-shrunk by -@var{delta} lines or columns, this function returns the
-minimum value in the range from @var{delta} to 0 that can be used for
-shrinking @var{window}.
-
-Optional argument @var{ignore} non-@code{nil} means ignore any
-restrictions imposed by the variables @code{window-min-height} or
-@code{window-min-width} and @code{window-size-fixed}. In this case the
-minimum height of a window is specified as the minimum number of lines
-that allow viewing any header or mode line and at least one line of the
-text area of window. The minimum width of a window includes any
-fringes, margins and the scroll bar as well as two text columns.
-
-If @var{ignore} denotes a window, this means to ignore restrictions for
-that window only. If @var{ignore} equals the constant @code{safe}, this
-means a live window may get as small as one line or two columns.
-
-Optional argument @var{noup} non-@code{nil} means don't go up in the
-window tree but try to steal or distribute the space needed for the
-resize operation among the other windows within @var{window}'s
-combination. Optional argument @var{nodown} non-@code{nil} means don't
-check whether @var{window} itself and its subwindows can be resized.
-@end defun
-
-The function @code{window-resizable} does not change any window sizes.
-The following function does:
+changed vertically by @var{delta} lines. If the optional argument
+@var{horizontal} is non-@code{nil}, it instead returns @var{delta} if
+@var{window} can be resized horizontally by @var{delta} columns. It
+does not actually change the window size.
+
+If @var{window} is @code{nil}, it defaults to the selected window.
+
+A positive value of @var{delta} means to check whether the window can be
+enlarged by that number of lines or columns; a negative value of
+@var{delta} means to check whether the window can be shrunk by that many
+lines or columns. If @var{delta} is non-zero, a return value of 0 means
+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
-This function resizes @var{window} vertically by @var{delta} lines. The
-argument @var{window} can denote an arbitrary window and defaults to the
-selected one. An attempt to resize the root window of a frame will
-raise an error.
-
-Second argument @var{delta} a positive number means @var{window} shall
-be enlarged by @var{delta} lines. If @var{delta} is negative, that
-means @var{window} shall be shrunk by -@var{delta} lines.
-
-Optional argument @var{horizontal} non-@code{nil} means to resize
-@var{window} horizontally by @var{delta} columns. In this case a
-positive @var{delta} means enlarge @var{window} by @var{delta} columns.
-A negative @var{delta} means @var{window} shall be shrunk by
--@var{delta} columns.
-
-Optional argument @var{ignore} has the same meaning as for the function
-@code{window-resizable} above.
-
-This function can simultaneously move two edges of WINDOW. Exactly
-which edges of @var{window} are moved and which other windows are
-resized along with @var{window} is determined by the splits and nest
-status of the involved windows (@pxref{Splitting Windows}). If only the
-low (right) edge of @var{window} shall be moved, the function
-@code{adjust-window-trailing-edge} described below should be used.
-@end defun
-
-The next four commands are simple interfaces to @code{window-resize}.
-They always operate on the selected window, never delete any window, and
-always raise an error when resizing would violate a restriction imposed
-by @code{window-min-height}, @code{window-min-width}, or
-@code{window-size-fixed}.
-
-@deffn Command enlarge-window delta &optional horizontal
-This function makes the selected window @var{delta} lines taller.
-Interactively, if no argument is given, it makes the selected window one
-line taller. If optional argument @var{horizontal} is non-@code{nil},
-it makes the selected window wider by @var{delta} columns. If
-@var{delta} is negative, it shrinks the selected window by -@var{delta}
-lines or columns. The return value is @code{nil}.
-@end deffn
+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
+positive @var{delta} means to enlarge the window, and a negative
+@var{delta} means to shrink it.
-@deffn Command enlarge-window-horizontally delta
-This function makes the selected window @var{delta} columns wider.
-Interactively, if no argument is given, it makes the selected window one
-column wider.
-@end deffn
+If @var{window} is @code{nil}, it defaults to the selected window. If
+the window cannot be resized as demanded, an error is signaled.
-@deffn Command shrink-window delta &optional horizontal
-This function makes the selected window @var{delta} lines smaller.
-Interactively, if no argument is given, it makes the selected window one
-line smaller. If optional argument @var{horizontal} is non-@code{nil},
-it makes the selected window narrower by @var{delta} columns. If
-@var{delta} is negative, it enlarges the selected window by -@var{delta}
-lines or columns. The return value is @code{nil}.
-@end deffn
+The optional argument @var{ignore} has the same meaning as for the
+function @code{window-resizable} above.
-@deffn Command shrink-window-horizontally delta
-This function makes the selected window @var{delta} columns narrower.
-Interactively, if no argument is given, it makes the selected window one
-column narrower.
-@end deffn
+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{Splitting Windows}. To resize by moving only the
+bottom or right edge of a window, use the function
+@code{adjust-window-trailing-edge}, below.
+@end defun
-The following function is useful for moving the line dividing two
-windows.
+@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
This function moves @var{window}'s bottom edge by @var{delta} lines.
-Optional argument @var{horizontal} non-@code{nil} means to move
-@var{window}'s right edge by @var{delta} columns. The argument
-@var{window} defaults to the selected window.
+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 @var{delta} is greater zero, this moves the edge downwards or to the
-right. If @var{delta} is less than zero, this moves the edge upwards or
-to the left. If the edge can't be moved by @var{delta} lines or columns,
-it is moved as far as possible in the desired direction but no error is
-signalled.
+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. Only if this is insufficient, it will also resize windows not
-adjacent to that edge. As a consequence, if you move an edge in one
-direction and back in the other direction by the same amount, the
-resulting window configuration will not be necessarily identical to the
-one before the first move. So if your intend to just resize
-@var{window}, you should not use this function but call
-@code{window-resize} (see above) instead.
+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
+ 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 makes @var{window} the right height to display its
-contents exactly. The default for @var{window} is the selected window.
-
-The optional argument @var{max-height} specifies the maximum total
-height the window is allowed to be; @code{nil} means use the maximum
-permissible height of a window on @var{window}'s frame. The optional
-argument @var{min-height} specifies the minimum toatl height for the
-window; @code{nil} means use @code{window-min-height}. All these height
-values include the mode line and/or header line.
-
-If the optional argument @var{override} is non-@code{nil}, this means to
-ignore any restrictions imposed by @code{window-min-height} and
-@code{window-min-width} on the size of @var{window}.
-
-This function returns non-@code{nil} if it orderly resized @var{window},
-and @code{nil} otherwise.
+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 no-@code{nil}, specifies
+the minimum total height that it can give, which overrides the
+variable @code{window-min-height}.
+
+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}.
@end deffn
@deffn Command shrink-window-if-larger-than-buffer &optional window
-This command shrinks @var{window} vertically to be as small as possible
-while still showing the full contents of its buffer---but not less than
-@code{window-min-height} lines. The argument @var{window} must denote
-a live window and defaults to the selected one.
-
-However, this command does nothing if the window is already too small to
-display the whole text of the buffer, or if part of the contents are
-currently scrolled off screen, or if the window is not the full width of
-its frame, or if the window is the only window in its frame.
-
-This command returns non-@code{nil} if it actually shrank the window
-and @code{nil} otherwise.
+This command attempts to reduce @var{window}'s height as much as
+possible while still showing its full buffer, but no less than
+@code{window-min-height} lines. The return value is non-@code{nil} if
+the window was resized, 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.
+
+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.
@end deffn
@cindex balancing window sizes
-Emacs provides two functions to balance windows, that is, to even out
-the sizes of all windows on the same frame. The minibuffer window and
-fixed-size windows are not resized by these functions.
-
@deffn Command balance-windows &optional window-or-frame
This function balances windows in a way that gives more space to
full-width and/or full-height windows. If @var{window-or-frame}
specifies a frame, it balances all windows on that frame. If
-@var{window-or-frame} specifies a window, it balances that window and
-its siblings (@pxref{Windows and Frames}) only.
+@var{window-or-frame} specifies a window, it balances only that window
+and its siblings (@pxref{Windows and Frames}).
@end deffn
@deffn Command balance-windows-area
This function attempts to give all windows on the selected frame
-approximately the same share of the screen area. This means that
-full-width or full-height windows are not given more space than other
-windows.
+approximately the same share of the screen area. Full-width or
+full-height windows are not given more space than other windows.
@end deffn
@cindex maximizing windows
-The following function can be used to give a window the maximum possible
-size without deleting other ones.
-
@deffn Command maximize-window &optional window
-This function maximizes @var{window}. More precisely, this makes
-@var{window} as large as possible without resizing its frame or deleting
-other windows. @var{window} can be any window and defaults to the
-selected one.
+This function attempts to make @var{window} as large as possible, in
+both dimensions, without resizing its frame or deleting other windows.
+If @var{window} is omitted or @code{nil}, it defaults to the selected
+window.
@end deffn
@cindex minimizing windows
-To make a window as small as possible without deleting it the
-following function can be used.
-
@deffn Command minimize-window &optional window
-This function minimizes @var{window}. More precisely, this makes
-@var{window} as small as possible without deleting it or resizing its
-frame. @var{window} can be any window and defaults to the selected one.
+This function attempts to make @var{window} as small as possible, in
+both dimensions, without deleting it or resizing its frame. If
+@var{window} is omitted or @code{nil}, it defaults to the selected
+window.
@end deffn
@cindex splitting windows
@cindex window splitting
-The functions described below are the primitives needed for creating a
-new window. They do not accept a buffer as an argument. Rather, they
-``split'' an existing window into two halves, both displaying the buffer
-previously visible in the window that was split.
+This section describes functions for creating a new window by
+@dfn{splitting} an existing one.
@deffn Command split-window &optional window size side
-This function creates a new window adjacent to @var{window}. It returns
-the new window which is always a live window. The argument @var{window}
-can denote any window and defaults to the selected one. This function
-does not change the selected window.
-
-Optional second argument @var{size} a positive number means make
-@var{window} @var{size} lines (or columns) tall. If @var{size} is
-negative, make the new window @minus{}@var{size} lines (or columns)
-tall. If @var{size} is omitted or @code{nil}, then @var{window} is
-divided evenly into two parts. (If there is an odd line, it is
-allocated to the new window.)
-
-If splitting would result in making a window smaller than
-@code{window-min-height} or @code{window-min-width} (@pxref{Window
-Sizes}), this function usually signals an error. However, if @var{size}
-is non-@code{nil} and valid, a new window of the requested size is
-created. (A size value would be invalid if it assigned less than one
-line or less than two columns to the new window.)
-
-Optional third argument @var{side} @code{nil} (or @code{below})
-specifies that the new window shall be located below @var{window}. The
-value @code{above} means the new window will be located above
-@var{window}. In both cases @var{size} specifies the new number of
-lines for @var{window} (or the new window if @var{size} is negative)
-including space reserved for the mode and/or header line.
-
-If @var{side} is @code{t} or @code{right} the new window will be
-positioned on the right side of @var{window}. The value @code{left}
-means the new window will be located on the left side of @var{window}.
-In both cases @var{size} specifies the new number of columns for
-@var{window} (or the new window provided @var{size} is negative)
-including space reserved for margins, fringes and the scroll bar or a
-divider column.
-
-Any other non-@code{nil} value for @var{side} is currently handled like
-@code{t} (or @code{right}). Since this might change in the future,
-application programs should refrain from using other values.
-
-If @var{window} is live, properties of the new window like margins and
-scroll bars are inherited from @var{window}. If @var{window} is an
-internal window, these properties, as well as the buffer shown in the
-new window, are inherited from the window selected on @var{window}'s
-frame.
-
-If @code{ignore-window-parameters} is non-@code{nil}, this function
-ignores window parameters (@pxref{Window Parameters}). Otherwise, if
-the @code{split-window} parameter of @var{window} is @code{t}, it splits
-the window disregarding any other window parameters. If the
-@code{split-window} parameter specifies a function, that function is
-called with the arguments @var{window}, @var{size}, and @var{side} to
-split @var{window}. If that function is @code{ignore}, nothing is done.
+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
+size. The space is taken up by the new window, which is returned.
+
+The optional second argument @var{size} determines the sizes of
+@var{window} and/or the new window. If it is omitted or @code{nil},
+both windows are given equal sizes; if there is an odd line, it is
+allocated to the new window. If @var{size} is a positive number,
+@var{window} is given @var{size} lines (or columns, depending on the
+value of @var{side}). If @var{size} is a negative number, the new
+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
+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
+wide.
+
+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
+@code{above}, the new window is placed above @var{window}. In both
+these cases, @var{size} specifies a total window height, in lines.
+
+If @var{side} is @code{t} or @code{right}, the new window is placed on
+the right of @var{window}. If @var{side} is @code{left}, the new
+window is placed on the left of @var{window}. In both these cases,
+@var{size} specifies a total window width, in 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
+properties of the window selected within @var{window}'s frame.
+
+The behavior of this function may be altered by the window parameters
+of @var{window}, so long as the variable
+@code{ignore-window-parameters} is non-@code{nil}. If the value of
+the @code{split-window} window parameter is @code{t}, this function
+ignores all other window parameters. Otherwise, if the value of the
+@code{split-window} window parameter is a function, that function is
+called with the arguments @var{window}, @var{size}, and @var{side}, in
+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
-The following example starts with one window on a screen that is 50
-lines high by 80 columns wide; then it splits the window.
-
-@smallexample
-@group
-(setq W1 (selected-window))
- @result{} #<window 8 on windows.texi>
-(setq W2 (split-window W1 15))
- @result{} #<window 28 on windows.texi>
-@end group
-@group
-(window-top-line W1)
- @result{} 0
-(window-total-size W1)
- @result{} 15
-(window-top-line W2)
- @result{} 15
-@end group
-@end smallexample
-
-The screen looks like this:
-
-@smallexample
-@group
- __________
- | | line 0
- | W1 |
- |__________|
- | | line 15
- | W2 |
- |__________|
- line 50
- column 0 column 80
-@end group
-@end smallexample
-
-Next, split the top window into two side-by-side windows:
-
-@smallexample
-@group
-(setq W3 (split-window W1 35 t))
- @result{} #<window 32 on windows.texi>
-@end group
-@group
-(window-left-column W1)
- @result{} 0
-(window-total-size W1 t)
- @result{} 35
-(window-left-column W3)
- @result{} 35
-@end group
-@end smallexample
-
-@need 3000
-Now the screen looks like this:
-
-@smallexample
-@group
- column 35
- __________
- | | | line 0
- | W1 | W3 |
- |____|_____|
- | | line 15
- | W2 |
- |__________|
- line 50
- column 0 column 80
-@end group
-@end smallexample
-
-Normally, Emacs indicates the border between two side-by-side windows
-with a scroll bar (@pxref{Scroll Bars}), or with @samp{|} characters. The
-display table can specify alternative border characters; see @ref{Display
-Tables}.
-
-Below we describe how @code{split-window} can be used to create the
-window configuration from our earlier example (@pxref{Windows and
-Frames}) and how internal windows are created for this purpose. We
-start with a frame containing one live window @code{W2} (in the
-following scenarios window names are assigned in an arbitrary manner in
-order to match the names of the example). Evaluating the form
-@code{(split-window W2 8 t)} creates a new internal window @code{W1}
-with two children---@code{W2} (the window we've split) and a new leaf
-window @code{W6}:
-@smallexample
-@group
- ______________________________________
- | ______ ____________________________ |
- || || ||
- || || ||
- || || ||
- || || ||
- || || ||
- || || ||
- || || ||
- || || ||
- || || ||
- || || ||
- ||__W2__||_____________W6_____________ |
- |__________________W1__________________|
-
-@end group
-@end smallexample
-
-Evaluating now @code{(split-window W6 -3)} creates another internal
-window @code{W3} with two children---@code{W6} and a new live window
-@code{W5}. This leaves us with a vertically combined window @code{W3}
-embedded in the horizontally combined window @code{W1}:
-@smallexample
-@group
- ______________________________________
- | ______ ____________________________ |
- || || __________________________ ||
- || ||| |||
- || ||| |||
- || ||| |||
- || ||| |||
- || ||| |||
- || |||____________W6____________|||
- || || __________________________ ||
- || ||| |||
- || |||____________W5____________|||
- ||__W2__||_____________W3_____________ |
- |__________________W1__________________|
-
-@end group
-@end smallexample
+ As an example, here is a sequence of @code{split-window} calls that
+yields the window configuration discussed in @ref{Windows and Frames}.
+This example demonstrates splitting a live window as well as splitting
+an internal window. We begin with a frame containing a single window
+(a live root window), which we denote by @var{W4}. Calling
+@code{(split-window W4)} yields this window configuration:
-Finally, evaluating @code{(split-window W6 nil t)} should get us the
-desired configuration as depicted below.
-@smallexample
-@group
- ______________________________________
- | ______ ____________________________ |
- || || __________________________ ||
- || ||| ___________ ___________ |||
- || |||| || ||||
- || |||| || ||||
- || ||||_____W6____||_____W7____||||
- || |||____________W4____________|||
- || || __________________________ ||
- || ||| |||
- || |||____________W5____________|||
- ||__W2__||_____________W3_____________ |
- |__________________W1__________________|
-
-@end group
-@end smallexample
-
-The scenario sketched above is the standard way to obtain the desired
-configuration. In Emacs 23 it was also the only way to do that since
-Emacs 23 did't allow splitting internal windows.
-
-With Emacs 24 you can also proceed as follows: Split an initial window
-@code{W6} by evaluating @code{(split-window W6 -3)} to produce the
-following vertical combination:
@smallexample
@group
______________________________________
|| ||
|| ||
|| ||
+ ||_________________W4_________________||
+ | ____________________________________ |
|| ||
|| ||
|| ||
- || ||
- ||_________________W6_________________||
- | ____________________________________ |
- || ||
||_________________W5_________________||
|__________________W3__________________|
@end group
@end smallexample
-Evaluating now @code{(split-window (window-parent W6) -8 'left)} or,
-equivalently, @code{(split-window W3 -8 'left)} should now produce the
-penultimate configuration from the previous scenario from where we can
-continue as described before.
-
- Another strategy starts with splitting an initial window @code{W6} by
-evaluating @code{(split-window W6 nil nil t)} with the following result:
-@smallexample
-@group
- ______________________________________
- | _________________ _________________ |
- || || ||
- || || ||
- || || ||
- || || ||
- || || ||
- || || ||
- || || ||
- || || ||
- || || ||
- || || ||
- ||________W6_______||________W7_______||
- |__________________W4__________________|
-
-@end group
-@end smallexample
-
-Evaluating now @code{(split-window W4 -3)} or @code{(split-window
-(window-parent W6) -3)} should get us a configuration as shown next.
-@smallexample
-@group
- ______________________________________
- | ____________________________________ |
- || ________________ ________________ ||
- ||| || |||
- ||| || |||
- ||| || |||
- ||| || |||
- ||| || |||
- |||_______W6_______||________W7______|||
- ||_________________W4_________________||
- | ____________________________________ |
- || ||
- ||_________________W5_________________||
- |__________________W3__________________|
-
-@end group
-@end smallexample
+@noindent
+The @code{split-window} call has created a new live window, denoted by
+@var{W5}. It has also created a new internal window, denoted by
+@var{W3}, which becomes the root window and the parent of both
+@var{W4} and @var{W5}.
-The desired configuration can be now obtained by evaluating
-@code{(split-window W3 -8 'left)} or, equivalently, @code{(split-window
-(window-parent W5) -8 'left)}.
+ Next, we call @code{(split-window W3 nil 'left)}, passing the
+internal window @var{W3} as the argument. The result:
- For a final approach let's start with the configuration of two live
-windows @code{W6} and @code{W7} shown above. If we now evaluate
-@code{(split-window W4 -8 'left)} or @code{(split-window (window-parent
-W6) -8 'left)} we get the following configuration.
@smallexample
@group
______________________________________
| ______ ____________________________ |
- || || ____________ ____________ ||
- || ||| || |||
- || ||| || |||
- || ||| || |||
- || ||| || |||
- || ||| || |||
- || ||| || |||
- || ||| || |||
- || |||______W6____||______W7____|||
- ||__W2__||_____________W4_____________||
+ || || __________________________ ||
+ || ||| |||
+ || ||| |||
+ || ||| |||
+ || |||____________W4____________|||
+ || || __________________________ ||
+ || ||| |||
+ || ||| |||
+ || |||____________W5____________|||
+ ||__W2__||_____________W3_____________ |
|__________________W1__________________|
-
@end group
@end smallexample
-Evaluating now @code{(split-window W4 -3)} or, for example,
-@code{(split-window (window-parent W6) -3)} should produce the desired
-configuration.
-
- The two options described next can be used to tune the operation of
-@code{split-window}.
-
-@defopt window-splits
-If this variable is nil, the function @code{split-window} can split a
-window if and only if that window's screen estate is sufficiently large
-to accommodate both--itself and the new window.
-
-If this variable is non-@code{nil}, @code{split-window} tries to resize
-all windows that are part of the same combination as the old window to
-accommodate the new window. Hence, the new window can be also created if
-the old window is of fixed size or too small to split (@pxref{Window
-Sizes}).
-
-In any case, the value of this variable is assigned to the splits status
-of the new window and, provided old and new window form a new
-combination, of the old window as well. The splits status of a window
-can be retrieved by invoking the function @code{window-splits} and
-altered by the function @code{set-window-splits} described next.
-
-If @code{window-nest} (see below) is non-@code{nil}, the space for the
-new window is exclusively taken from the old window, but the splits
-status of the involved windows is nevertheless set as described here.
-@end defopt
-
-@defun window-splits &optional window
-This function returns the splits status of @var{window}. The argument
-@var{window} can be any window and defaults to the selected one.
-
-@cindex splits status
-The @dfn{splits status} of a window specifies how resizing and deleting
-that window may affect the size of other windows in the same window
-combination. More precisely, if @var{window}'s splits status is
-@code{nil} and @var{window} is resized, the corresponding space is
-preferably taken from (or given to) @var{window}'s right sibling. When
-@var{window} is deleted, its space is given to its left sibling. If
-@var{window}'s splits status is non-@code{nil}, resizing and deleting
-@var{window} may resize @emph{all} windows in @var{window}'s
+@noindent
+A new live window @var{W2} is created, to the left of the internal
+window @var{W3}. A new internal window @var{W1} is created, becoming
+the new root window.
+
+@defopt window-combination-resize
+If this variable is @code{nil}, @code{split-window} can only split a
+window (denoted by @var{window}) if @var{window}'s screen area is large
+enough to accommodate both itself and the new window.
+
+If this variable is @code{t}, @code{split-window} tries to resize all
+windows that are part of the same combination as @var{window}, in order
+to accommodate the new window. In particular, this may allow
+@code{split-window} to succeed even if @var{window} is a fixed-size
+window or too small to ordinarily split. Furthermore, subsequently
+resizing or deleting @var{window} may resize all other windows in its
combination.
-The splits status is initially set by @code{split-window}
-from the current value of the variable @code{window-splits} (see above)
-and can be reset by the function @code{set-window-splits} (see below).
-@end defun
+The default is @code{nil}. Other values are reserved for future use.
+The value of this variable is ignored when
+@code{window-combination-limit} is non-@code{nil} (see below).
+@end defopt
-@defun set-window-splits window &optional status
-This function sets the splits status (see above) of @var{window} to
-@var{status}. The argument @var{window} can be any window and defaults
-to the selected one. The return value is @var{status}.
-@end defun
+ To illustrate the effect of @code{window-combination-resize},
+consider the following window configuration:
-To illustrate the use of @code{window-splits} consider the following
-window configuration:
@smallexample
@group
______________________________________
@end group
@end smallexample
-Splitting window @code{W3} with @code{window-splits} @code{nil}
-produces a configuration where the size of @code{W2} remains unchanged:
+@noindent
+If @code{window-combination-resize} is @code{nil}, splitting window
+@code{W3} leaves the size of @code{W2} unchanged:
+
@smallexample
@group
______________________________________
@end group
@end smallexample
-Splitting @code{W3} with @code{window-splits} non-@code{nil} instead
-produces a configuration where all windows have approximately the same
+@noindent
+If @code{window-combination-resize} is @code{t}, splitting @code{W3}
+instead leaves all three live windows with approximately the same
height:
@smallexample
@end group
@end smallexample
-@defopt window-nest
-If this variable is @code{nil}, @code{split-window} creates a new parent
-window if and only if the old window has no parent window or shall be
-split orthogonally to the combination it is part of. If this variable
-is non-@code{nil}, @code{split-window} always creates a new parent
-window. If this variable is always non-@code{nil}, a frame's window
-tree is a binary tree so every window but the frame's root window has
-exactly one sibling.
-
-The value of this variable is also assigned to the nest status of the
-new parent window. The nest status of any window can be retrieved via
-the function @code{window-nest} and altered by the function
-@code{set-window-nest}, see below.
+@defopt window-combination-limit
+If the value of this variable is @code{t}, the @code{split-window}
+function always creates a new internal window. If the value is
+@code{nil}, the new live window is allowed to share the existing
+parent window, if one exists, provided the split occurs in the same
+direction as the existing window combination (otherwise, a new
+internal window is created anyway). The default is @code{nil}. Other
+values are reserved for future use.
+
+Thus, if the value of this variable is at all times @code{t}, then at
+all times every window tree is a binary tree (a tree where each window
+except the root window has exactly one sibling).
+
+Furthermore, @code{split-window} calls
+@code{set-window-combination-limit} on the newly-created internal
+window, recording the current value of this variable. This affects
+how the window tree is rearranged when the child windows are deleted
+(see below).
@end defopt
-@defun window-nest &optional window
-This function returns the nest status of @var{window}. The argument
-@var{window} can be any window and defaults to the selected one. Note,
-however, that the nest status is currently meaningful for internal
-windows only.
+@cindex window combination limit
+@defun set-window-combination-limit window limit
+This functions 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
+@code{split-window} function automatically calls this function, passing
+the value of the variable @code{window-combination-limit} as
+@var{limit}.
+@end defun
-@cindex nest status
-The @dfn{nest status} of a window specifies whether that window may be
-removed and its subwindows recombined with that window's siblings when
-such a sibling's subwindow is deleted. The nest status is initially
-assigned by @code{split-window} from the current value of the variable
-@code{window-nest} (see above) and can be reset by the function
-@code{set-window-nest} (see below).
+@defun window-combination-limit window
+This function returns the combination limit for @var{window}.
-If the return value is @code{nil}, subwindows of @var{window} may be
-recombined with @var{window}'s siblings when a window gets deleted. A
-return value of @code{nil} means that subwindows of @var{window} are
-never (re-)combined with @var{window}'s siblings in such a case.
+The combination limit is meaningful only for an internal window. If
+it is @code{nil}, then Emacs is allowed to automatically delete
+@var{window}, in response to a window deletion, in order to group the
+child windows of @var{window} with its sibling windows to form a new
+window combination. If the combination limit is @code{t}, the child
+windows of @var{window} are never automatically re-combined with its
+siblings.
@end defun
-@defun set-window-nest window &optional status
-This functions sets the nest status (see above) of @var{window} to
-@var{status}. The argument @var{window} can be any window and defaults
-to the selected one. Note that setting the nest status is meaningful
-for internal windows only. The return value is @var{status}.
-@end defun
+ To illustrate the effect of @code{window-combination-limit},
+consider the following configuration (throughout this example, we will
+assume that @code{window-combination-resize} is @code{nil}):
-To illustrate the use of @code{window-nest} consider the following
-configuration (throughout the following examples we shall assume that
-@code{window-splits} invariantly is @code{nil}).
@smallexample
@group
______________________________________
@end group
@end smallexample
-Splitting @code{W2} into two windows above each other with
-@code{window-nest} equal @code{nil} will get you a configuration like:
-@smallexample
-@group
- ______________________________________
- | ____________________________________ |
- || ||
- || ||
- ||_________________W2_________________||
- | ____________________________________ |
- || ||
- || ||
- ||_________________W4_________________||
- | ____________________________________ |
- || ||
- || ||
- ||_________________W3_________________||
- |__________________W1__________________|
-
-@end group
-@end smallexample
+@noindent
+If @code{window-combination-limit} is @code{nil}, splitting @code{W2}
+into two windows, one above the other, yields
-If you now enlarge window @code{W4}, Emacs steals the necessary space
-from window @code{W3} resulting in a configuration like:
@smallexample
@group
______________________________________
| ____________________________________ |
|| ||
|| ||
- || ||
||_________________W4_________________||
| ____________________________________ |
|| ||
- ||_________________W3_________________||
- |__________________W1__________________|
-
-@end group
-@end smallexample
-
-Deleting window @code{W4}, will return its space to @code{W2} as
-follows:
-@smallexample
-@group
- ______________________________________
- | ____________________________________ |
- || ||
- || ||
- || ||
- || ||
- || ||
- || ||
- || ||
- ||_________________W2_________________||
- | ____________________________________ |
|| ||
||_________________W3_________________||
|__________________W1__________________|
@end group
@end smallexample
-Hence, with respect to the initial configuration, window @code{W2} has
-grown at the expense of window @code{W3}. If, however, in the initial
-configuration you had split @code{W2} with @code{window-nest} bound to
-@code{t}, a new internal window @code{W5} would have been created as
-depicted below.
-@smallexample
-@group
- ______________________________________
- | ____________________________________ |
- || __________________________________ ||
- ||| |||
- |||________________W2________________|||
- || __________________________________ ||
- ||| |||
- |||________________W4________________|||
- ||_________________W5_________________||
- | ____________________________________ |
- || ||
- || ||
- ||_________________W3_________________||
- |__________________W1__________________|
+@noindent
+The newly-created window, @code{W4}, shares the same internal window
+@code{W1}. If @code{W4} is resized, it is allowed to resize the other
+live window, @code{W3}.
-@end group
-@end smallexample
+ If @code{window-combination-limit} is @code{t}, splitting @code{W2}
+in the initial configuration would instead have produced this:
-Enlarging @code{W4} would now have stolen the necessary space from
-@code{W2} instead of @code{W3} as
@smallexample
@group
______________________________________
| ____________________________________ |
|| __________________________________ ||
+ ||| |||
|||________________W2________________|||
|| __________________________________ ||
||| |||
- ||| |||
|||________________W4________________|||
||_________________W5_________________||
| ____________________________________ |
@end group
@end smallexample
-and the subsequent deletion of @code{W4} would have restored the initial
-configuration.
-
-For interactive use, Emacs provides two commands which always split the
-selected window.
+@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 resizing @code{W4} will resize
+@code{W2}, leaving @code{W3} unaffected.
+
+ For interactive use, Emacs provides two commands which always split
+the selected window. These call @code{split-window} internally.
+
+@deffn Command split-window-right &optional size
+This function splits the selected window into two side-by-side
+windows, putting the selected window on the left. If @var{size} is
+positive, the left window gets @var{size} columns; if @var{size} is
+negative, the right window gets @minus{}@var{size} columns.
+@end deffn
-@deffn Command split-window-above-each-other &optional size
-This function splits the selected window into two windows, one above the
-other, leaving the upper of the two windows selected, with @var{size}
-lines. (If @var{size} is negative, then the lower of the two windows
-gets @minus{}@var{size} lines and the upper window gets the rest, but
-the upper window is still the one selected.) However, if
-@code{split-window-keep-point} (see below) is @code{nil}, then either
-window can be selected.
-
- In other respects, this function is similar to @code{split-window}.
-In particular, the upper window is the original one and the return value
-is the new, lower window.
+@deffn Command split-window-below &optional size
+This function splits the selected window into two windows, one above
+the other, leaving the upper window selected. If @var{size} is
+positive, the upper window gets @var{size} lines; if @var{size} is
+negative, the lower window gets @minus{}@var{size} lines.
@end deffn
@defopt split-window-keep-point
-If this variable is non-@code{nil} (the default), then
-@code{split-window-above-each-other} behaves as described above.
-
- If it is @code{nil}, then @code{split-window-above-each-other}
-adjusts point in each of the two windows to avoid scrolling. (This is
-useful on slow terminals.) It selects whichever window contains the
-screen line that point was previously on. Other functions are not
-affected by this variable.
+If the value of this variable is non-@code{nil} (the default),
+@code{split-window-below} behaves as described above.
+
+If it is @code{nil}, @code{split-window-below} adjusts point in each
+of the two windows to minimize redisplay. (This is useful on slow
+terminals.) It selects whichever window contains the screen line that
+point was previously on. Note that this only affects
+@code{split-window-below}, not the lower-level @code{split-window}
+function.
@end defopt
-@deffn Command split-window-side-by-side &optional size
-This function splits the selected window into two windows
-side-by-side, leaving the selected window on the left with @var{size}
-columns. If @var{size} is negative, the rightmost window gets
-@minus{}@var{size} columns, but the leftmost window still remains
-selected.
-@end deffn
-
-
@node Deleting Windows
@section Deleting Windows
@cindex deleting windows
-A window remains visible on its frame unless you @dfn{delete} it by
-calling certain functions that delete windows. A deleted window cannot
-appear on the screen, but continues to exist as a Lisp object until
-there are no references to it. There is no way to cancel the deletion
-of a window aside from restoring a saved window configuration
-(@pxref{Window Configurations}). Restoring a window configuration also
-deletes any windows that aren't part of that configuration. Erroneous
-information may result from using a deleted window as if it were live.
+ @dfn{Deleting} a window removes it from the frame's window tree. If
+the window is a live window, it disappears from the screen. If the
+window is an internal window, its child windows are deleted too.
-@deffn Command delete-window &optional window
-This function removes @var{window} from display and returns @code{nil}.
-The argument @var{window} can denote any window and defaults to the
-selected one. An error is signaled if @var{window} is the only window
-on its frame. Hence @var{window} must have at least one sibling window
-(@pxref{Windows and Frames}) in order to get deleted.
-
-If the variable @code{ignore-window-parameters} (@pxref{Window
-Parameters}) is non-@code{nil}, this function ignores all parameters of
-@var{window}. Otherwise, if the @code{delete-window} parameter of
-@var{window} is @code{t}, it deletes the window disregarding other
-window parameters. If the @code{delete-window} parameter specifies a
-function, that function is called with @var{window} as its sole
-argument.
+ Even after a window is deleted, it continues to exist as a Lisp
+object, until there are no more references to it. Window deletion can
+be reversed, by restoring a saved window configuration (@pxref{Window
+Configurations}).
-If the splits status of @var{window} (@pxref{Splitting Windows}) is
-@code{nil}, the space @var{window} took up is given to its left sibling
-if such a window exists and to its right sibling otherwise. If the
-splits status of @var{window} is non-@code{nil}, its space is
-proportionally distributed among the remaining windows in the same
-combination.
+@deffn Command delete-window &optional window
+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
+frame), an error is signaled.
+
+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{Splitting Windows}.
+
+The behavior of this function may be altered by the window parameters
+of @var{window}, so long as the variable
+@code{ignore-window-parameters} is non-@code{nil}. If the value of
+the @code{delete-window} window parameter is @code{t}, this function
+ignores all other window parameters. Otherwise, if the value of the
+@code{delete-window} window parameter is a function, that function is
+called with the argument @var{window}, in lieu of the usual action of
+@code{delete-window}. Otherwise, this function obeys the
+@code{window-atom} or @code{window-side} window parameter, if any.
+@xref{Window Parameters}.
@end deffn
@deffn Command delete-other-windows &optional window
-This function makes @var{window} fill its frame and returns @code{nil}.
-The argument @var{window} can denote an arbitrary window and defaults to
-the selected one.
-
-If the variable @code{ignore-window-parameters} (@pxref{Window
-Parameters}) is non-@code{nil}, this function ignores all parameters of
-@var{window}. Otherwise, if the @code{delete-other-windows} parameter
-of @var{window} equals @code{t}, it deletes all other windows
-disregarding any remaining window parameters. If the
-@code{delete-other-windows} parameter of @var{window} specifies a
-function, it calls that function with @var{window} as its sole argument.
+This function makes @var{window} fill its frame, by deleting other
+windows as necessary. If @var{window} is omitted or @code{nil}, it
+defaults to the selected window. The return value is @code{nil}.
+
+The behavior of this function may be altered by the window parameters
+of @var{window}, so long as the variable
+@code{ignore-window-parameters} is non-@code{nil}. If the value of
+the @code{delete-other-windows} window parameter is @code{t}, this
+function ignores all other window parameters. Otherwise, if the value
+of the @code{delete-other-windows} window parameter is a function,
+that function is called with the argument @var{window}, in lieu of the
+usual action of @code{delete-other-windows}. Otherwise, this function
+obeys the @code{window-atom} or @code{window-side} window parameter,
+if any. @xref{Window Parameters}.
@end deffn
@deffn Command delete-windows-on &optional buffer-or-name frame
-This function deletes all windows showing @var{buffer-or-name} and
-returns nil. If there are no windows showing @var{buffer-or-name}, it
-does nothing. The optional argument @var{buffer-or-name} may be a
-buffer or the name of an existing buffer and defaults to the current
-buffer. Invoking this command on a minibuffer signals an error.
-
-The function @code{delete-windows-on} operates by calling
-@code{delete-window} for each window showing @var{buffer-or-name}. If a
-frame has several windows showing different buffers, then those showing
-@var{buffer-or-name} are removed, and the other windows expand to fill
-the space.
-
-If all windows in some frame are showing @var{buffer-or-name} (including
-the case where there is only one window), then that frame is deleted
-provided there are other frames left.
-
-The optional argument @var{frame} specifies which frames to operate on.
-This function does not use it in quite the same way as the other
-functions which scan all live windows (@pxref{Cyclic Window Ordering});
-specifically, the values @code{t} and @code{nil} have the opposite of
-their meanings in the other functions. Here are the full details:
+This function deletes all windows showing @var{buffer-or-name}, by
+calling @code{delete-window} on those windows. @var{buffer-or-name}
+should be a buffer, or the name of a buffer; if omitted or @code{nil},
+it defaults to the current buffer. If there are no windows showing
+the specified buffer, this function does nothing. If the specified
+buffer is a minibuffer, an error is signaled.
+
+If there is a dedicated window showing the buffer, and that window is
+the only one on its frame, this function also deletes that frame if it
+is not the only frame on the terminal.
+
+The optional argument @var{frame} specifies which frames to operate
+on:
@itemize @bullet
@item @code{nil}
@item A frame
means operate on that frame.
@end itemize
-@end deffn
+Note that this argument does not have the same meaning as in other
+functions which scan all live windows (@pxref{Cyclic Window
+Ordering}). Specifically, the values @code{t} and @code{nil} have the
+opposite of their meanings in those other functions.
+@end deffn
@node Selecting Windows
@section Selecting Windows
@cindex selecting a window
@defun select-window window &optional norecord
-This function makes @var{window} the selected window, see @ref{Basic
-Windows}. Unless @var{window} already is the selected window, this also
-makes @var{window}'s buffer (@pxref{Buffers and Windows}) the current
-buffer. Moreover, the cursor for selected windows will be displayed in
-@var{window} after the next redisplay. This function returns
-@var{window}.
+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. Unless @var{window} already is the
+selected window, its buffer becomes the current buffer (@pxref{Buffers
+and Windows}). The return value is @var{window}.
-Normally, @var{window}'s selected buffer is moved to the front of the
-buffer list (@pxref{The Buffer List}) and @var{window} becomes the most
-recently selected window. But if the optional argument @var{norecord}
-is non-@code{nil}, the buffer list remains unchanged and @var{window}
-does not become the most recently selected one.
+By default, this function also moves @var{window}'s selected buffer to
+the front of the buffer list (@pxref{The 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.
@end defun
@cindex most recently selected windows
-The sequence of calls to @code{select-window} with a non-@code{nil}
+ The sequence of calls to @code{select-window} with a non-@code{nil}
@var{norecord} argument determines an ordering of windows by their
selection time. The function @code{get-lru-window} can be used to
-retrieve the least recently selected live window in this ordering, see
-@ref{Cyclic Window Ordering}.
+retrieve the least recently selected live window (@pxref{Cyclic Window
+Ordering}).
@defmac save-selected-window forms@dots{}
This macro records the selected frame, as well as the selected window
changed by this macro.
@end defmac
-@cindex frame selected window
-@cindex window selected within frame
-Earlier (@pxref{Basic Windows}) we mentioned that at any time, exactly
-one window on any frame is selected within the frame. The significance
-of this designation is that selecting the frame also selects this
-window. Conversely, selecting a window for Emacs with
-@code{select-window} also makes that window selected within its frame.
-
-@defun frame-selected-window &optional frame
-This function returns the window on @var{frame} that is selected within
-@var{frame}. The optional argument @var{frame} must denote a live frame
-and defaults to the selected one.
+@defun frame-selected-window &optional frame
+This function returns the window on @var{frame} that is selected
+within that frame. @var{frame} should be a live frame; if omitted or
+@code{nil}, it defaults to the selected frame.
@end defun
@defun set-frame-selected-window frame window &optional norecord
-This function sets the selected window of frame @var{frame} to
-@var{window}. The argument @var{frame} must denote a live frame and
-defaults to the selected one. If @var{frame} is the selected frame,
-this also makes @var{window} the selected window. The argument
-@var{window} must denote a live window. This function returns
-@var{window}.
+This function makes @code{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.
-Optional argument @var{norecord} non-@code{nil} means to neither change
-the list of most recently selected windows (@pxref{Selecting Windows})
-nor the buffer list (@pxref{The Buffer List}).
-@end defun
+If @var{frame} is the selected frame, this makes @var{window} the
+selected window.
+If the optional argument @var{norecord} is non-@code{nil}, this
+function does not alter the list of most recently selected windows,
+nor the buffer list.
+@end defun
@node Cyclic Window Ordering
@section Cyclic Ordering of Windows
@cindex ordering of windows, cyclic
@cindex window ordering, cyclic
-When you use the command @kbd{C-x o} (@code{other-window}) to select
+ When you use the command @kbd{C-x o} (@code{other-window}) to select
some other window, it moves through live windows in a specific order.
-For any given configuration of windows, this order never varies. It is
-called the @dfn{cyclic ordering of windows}.
-
- For a particular frame, this ordering is determined by the window
-tree of that frame, see @ref{Windows and Frames}. More precisely, the
-ordering is obtained by a depth-first traversal of the frame's window
-tree supplemented, if requested, by the frame's minibuffer window.
+For any given configuration of windows, this order never varies. It
+is called the @dfn{cyclic ordering of windows}.
- If there's just one live frame, the cyclic ordering is the ordering
-for that frame. Otherwise, the cyclic ordering is obtained by appending
-the orderings for individual frames in order of the list of all live
-frames, @ref{Finding All Frames}. In any case, the ordering is made
-``cyclic'' by having the last window precede the first window in the
-ordering.
+ 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.
@defun next-window &optional window minibuf all-frames
@cindex minibuffer window, and @code{next-window}
-This function returns the window following @var{window} in the cyclic
-ordering of windows. The argument @var{window} must specify a live
-window and defaults to the selected one.
+This function returns a live window, the one following @var{window} in
+the cyclic ordering of windows. @var{window} should be a live window;
+if omitted or @code{nil}, it defaults to the selected window.
The optional argument @var{minibuf} specifies whether minibuffer windows
shall be included in the cyclic ordering. Normally, when @var{minibuf}
@code{nil}, minibuffer windows are not included even if they are active.
The optional argument @var{all-frames} specifies which frames to
-consider. Here are the possible values and their meanings:
+consider:
@itemize @bullet
@item @code{nil}
-means consider all windows on @var{window}'s frame, plus the minibuffer
-window used by that frame even if it lies in some other frame. If the
-minibuffer counts (as determined by @var{minibuf}), then all windows on
-all frames that share that minibuffer count too.
+means to consider windows on @var{window}'s frame. If the minibuffer
+window is considered (as specified by the @var{minibuf} argument),
+then frames that share the minibuffer window are considered too.
@item @code{t}
-means consider all windows on all existing frames.
+means to consider windows on all existing frames.
@item @code{visible}
-means consider all windows on all visible frames. (To get useful
-results, ensure that @var{window} is on a visible frame.)
+means to consider windows on all visible frames.
@item 0
-means consider all windows on all visible or iconified frames.
+means to consider windows on all visible or iconified frames.
@item A frame
-means consider all windows on that frame.
+means to consider windows on that specific frame.
@item Anything else
-means consider the windows on @var{window}'s frame, and no others.
+means to consider windows on @var{window}'s frame, and no others.
@end itemize
-This example assumes there are two windows, both displaying the
-buffer @samp{windows.texi}:
-
-@example
-@group
-(selected-window)
- @result{} #<window 56 on windows.texi>
-@end group
-@group
-(next-window (selected-window))
- @result{} #<window 52 on windows.texi>
-@end group
-@group
-(next-window (next-window (selected-window)))
- @result{} #<window 56 on windows.texi>
-@end group
-@end example
+If more than one frame is considered, the cyclic ordering is obtained
+by appending the orderings for those frames, in the same order as the
+list of all live frames (@pxref{Finding All Frames}).
@end defun
@defun previous-window &optional window minibuf all-frames
-This function returns the window preceding @var{window} in the cyclic
-ordering of windows. The other arguments specify which windows to
-consider as in @code{next-window}.
+This function returns a live window, the one preceding @var{window} in
+the cyclic ordering of windows. The other arguments are handled like
+in @code{next-window}.
@end defun
@deffn Command other-window count &optional all-frames
-This function selects another window in the cyclic ordering of windows.
-@var{count} specifies the number of windows to skip in the ordering,
-starting with the selected window, before making the selection. If
-@var{count} is a positive number, it skips @var{count} windows forwards.
-@var{count} negative means skip @minus{}@var{count} windows backwards.
-If @var{count} is zero, it does not skip any window, thus re-selecting
-the selected window. In an interactive call, @var{count} is the numeric
-prefix argument.
+This function selects a live window, one @var{count} places from the
+selected window in the cyclic ordering of windows. If @var{count} is
+a positive number, it skips @var{count} windows forwards; if
+@var{count} is negative, it skips @minus{}@var{count} windows
+backwards; if @var{count} is zero, that simply re-selects the selected
+window. When called interactively, @var{count} is the numeric prefix
+argument.
The optional argument @var{all-frames} has the same meaning as in
-@code{next-window}, but the @var{minibuf} argument of @code{next-window}
-is always effectively @code{nil}. This function returns @code{nil}.
+@code{next-window}, like a @code{nil} @var{minibuf} argument to
+@code{next-window}.
This function does not select a window that has a non-@code{nil}
@code{no-other-window} window parameter (@pxref{Window Parameters}).
@end deffn
-The following function returns a copy of the list of windows in the
-cyclic odering.
-
-@defun window-list-1 &optional window &optional minibuf &optional all_frames
-This function returns a list of live windows. The optional arguments
-@var{minibuf} and @var{all-frames} specify the set of windows to include
-in the list. See the description of @code{next-window} for details.
+@defun walk-windows fun &optional minibuf all-frames
+This function calls the function @var{fun} once for each live window,
+with the window as the argument.
-The optional argument @var{window} specifies the first window to list
-and defaults to the selected window. If @var{window} is not on the list
-of windows returned, some other window will be listed first but no error
-is signalled.
-@end defun
-
-The functions described below use @code{window-list-1} for generating a
-copy of the list of all relevant windows. Hence, any change of the
-window configuration that occurs while one of these functions is
-executed is @emph{not} reflected in the list of windows investigated.
-
-@defun walk-windows proc &optional minibuf all-frames
-This function cycles through live windows. It calls the function
-@var{proc} once for each window, with the window as its sole argument.
+It follows the cyclic ordering of windows. The optional arguments
+@var{minibuf} and @var{all-frames} specify the set of windows
+included; these have the same arguments as in @code{next-window}. If
+@var{all-frames} specifies a frame, the first window walked is the
+first window on that frame (the one returned by
+@code{frame-first-window}), not necessarily the selected window.
-The optional arguments @var{minibuf} and @var{all-frames} specify the
-set of windows to include in the walk, see @code{next-window} above. If
-@var{all-frames} specifies a frame, the first window walked is the first
-window on that frame as returned by @code{frame-first-window} and not
-necessarily the selected window.
-
-If @var{proc} changes the window configuration by splitting or deleting
-windows, that change is not reflected in the set of windows walked.
-That set is determined entirely by the set of live windows at the time
-this function was invoked.
+If @var{fun} changes the window configuration by splitting or deleting
+windows, that does not alter the set of windows walked, which is
+determined prior to calling @var{fun} for the first time.
@end defun
-The following function allows to determine whether a specific window is
-the only live window.
-
@defun one-window-p &optional no-mini all-frames
-This function returns non-@code{nil} if the selected window is the only
-window.
+This function returns @code{t} if the selected window is the only live
+window, and @code{nil} otherwise.
-The optional argument @var{no-mini}, if non-@code{nil}, means don't
-count the minibuffer even if it is active; otherwise, the minibuffer
-window is counted when it is active. The optional argument
-@var{all-frames} has the same meaning as for @code{next-window}, see
-above.
+If the minibuffer window is active, it is normally considered (so that
+this function returns @code{nil}). However, if the optional argument
+@var{no-mini} is non-@code{nil}, the minibuffer window is ignored even
+if active. The optional argument @var{all-frames} has the same
+meaning as for @code{next-window}.
@end defun
@cindex finding windows
- The following functions choose (but do not select) one of the windows
-on the screen, offering various criteria for the choice.
+ The following functions return a window which satisfies some
+criterion, without selecting it:
@cindex least recently used window
@defun get-lru-window &optional all-frames dedicated
-This function returns the window least recently ``used'' (that is,
-selected). If any full-width windows are present, it only considers
-these. The optional argument @var{all-frames} has the same meaning as
-in @code{next-window}.
+This function returns a live window which is heuristically the ``least
+recently used'' window. The optional argument @var{all-frames} has
+the same meaning as in @code{next-window}.
-The selected window is returned if it is the only candidate. A
-minibuffer window is never a candidate. A dedicated window
-(@pxref{Dedicated Windows}) is never a candidate unless the optional
-argument @var{dedicated} is non-@code{nil}.
+If any full-width windows are present, only those windows are
+considered. The selected window is never returned, unless it is the
+only candidate. A minibuffer window is never a candidate. A
+dedicated window (@pxref{Dedicated Windows}) is never a candidate
+unless the optional argument @var{dedicated} is non-@code{nil}.
@end defun
@cindex largest window
prefers the one that comes first in the cyclic ordering of windows,
starting from the selected window.
-The optional argument @var{all-frames} specifies which set of windows to
-consider as with @code{next-window}, see above.
+The optional argument @var{all-frames} specifies the windows to
+search, and has the same meaning as in @code{next-window}.
@end defun
@cindex window that satisfies a predicate
@cindex conditional selection of windows
@defun get-window-with-predicate predicate &optional minibuf all-frames default
-This function returns a window satisfying @var{predicate}. It cycles
-through all visible windows calling @var{predicate} on each one of them
-with that window as its argument. The function returns the first window
-for which @var{predicate} returns a non-@code{nil} value; if that never
-happens, it returns @var{default} (which defaults to @code{nil}).
+This function calls the function @var{predicate} for each of the
+windows in the cyclic order of windows in turn, passing it the window
+as an argument. If the predicate returns non-@code{nil} for any
+window, this function stops and returns that window. If no such
+window is found, the return value is @var{default} (which defaults to
+@code{nil}).
The optional arguments @var{minibuf} and @var{all-frames} specify the
-set of windows to investigate. See the description of
-@code{next-window} for details.
+windows to search, and have the same meanings as in
+@code{next-window}.
@end defun
@node Buffers and Windows
@cindex windows, controlling precisely
@cindex buffers, controlled in windows
-To find out which buffer is displayed in a given window the following
-function is used.
+ This section describes low-level functions for examining and setting
+the contents of windows. @xref{Switching Buffers}, for higher-level
+functions for displaying a specific buffer in a window.
@defun window-buffer &optional window
-This function returns the buffer that @var{window} is displaying. The
-argument @var{window} can be any window and defaults to the selected
-one. If @var{window} is an internal window, this function returns
+This function returns the buffer that @var{window} is displaying. If
+@var{window} is omitted or @code{nil} it defaults to the selected
+window. If @var{window} is an internal window, this function returns
@code{nil}.
@end defun
-The basic, low-level function to associate a window with a buffer is
-@code{set-window-buffer}. Higher-level functions like
-@code{switch-to-buffer} and @code{display-buffer} try to obey a number
-of user customizations regulating which windows are supposed to
-display which buffers. @xref{Switching Buffers}. When writing an
-application, you should avoid using @code{set-window-buffer} unless
-you are sure you need it.
-
@defun set-window-buffer window buffer-or-name &optional keep-margins
-This function makes @var{window} display @var{buffer-or-name} and
-returns @code{nil}. The argument @var{window} has to denote a live
-window and defaults to the selected one. The argument
-@var{buffer-or-name} must specify a buffer or the name of an existing
-buffer. An error is signalled when @var{window} is @dfn{strongly}
-dedicated to its buffer (@pxref{Dedicated Windows}) and does not already
-display @var{buffer-or-name}.
-
-Normally, displaying @var{buffer-or-name} in @var{window} resets the
-window's position, display margins, fringe widths, and scroll bar
-settings based on the local variables of the specified buffer. However,
-if the optional argument @var{keep-margins} is non-@code{nil}, display
-margins and fringe widths of @var{window} remain unchanged.
-@xref{Fringes}.
-
-This function is the fundamental primitive for changing which buffer is
-displayed in a window, and all ways of doing that call this function.
-Neither the selected window nor the current buffer are changed by this
-function.
+This function makes @var{window} display @var{buffer-or-name}.
+@var{window} should be a live window; if @code{nil}, it defaults to
+the selected window. @var{buffer-or-name} should be a buffer, or the
+name of an existing buffer. This function does not change which
+window is selected, nor does it directly change which buffer is
+current (@pxref{Current Buffer}). Its return value is @code{nil}.
-This function runs @code{window-scroll-functions} before running
-@code{window-configuration-change-hook}, see @ref{Window Hooks}.
+If @var{window} is @dfn{strongly dedicated} to a buffer and
+@var{buffer-or-name} does not specify that buffer, this function
+signals an error. @xref{Dedicated Windows}.
+
+By default, this function resets @var{window}'s position, display
+margins, fringe widths, and scroll bar settings, based on the local
+variables in the specified buffer. However, if the optional argument
+@var{keep-margins} is non-@code{nil}, it leaves the display margins
+and fringe widths unchanged.
+
+When writing an application, you should normally use the higher-level
+functions described in @ref{Switching Buffers}, instead of calling
+@code{set-window-buffer} directly.
+
+This function runs @code{window-scroll-functions}, followed by
+@code{window-configuration-change-hook}. @xref{Window Hooks}.
@end defun
@defvar buffer-display-count
@end defvar
@defvar buffer-display-time
-This variable records the time at which a buffer was last made visible
-in a window. It is always local in each buffer; each time
-@code{set-window-buffer} is called, it sets this variable to
-@code{(current-time)} in the specified buffer (@pxref{Time of Day}).
-When a buffer is first created, @code{buffer-display-time} starts out
-with the value @code{nil}.
+This buffer-local variable records the time at which a buffer was last
+displayed in a window. The value is @code{nil} if the buffer has
+never been displayed. It is updated each time
+@code{set-window-buffer} is called for the buffer, with the value
+returned by @code{current-time} (@pxref{Time of Day}).
@end defvar
@defun get-buffer-window &optional buffer-or-name all-frames
-This function returns a window displaying @var{buffer-or-name}, or
-@code{nil} if there is none. If there are several such windows, then
-the function returns the first one in the cyclic ordering of windows,
-starting from the selected window, @xref{Cyclic Window Ordering}.
+This function returns the first window displaying @var{buffer-or-name}
+in the cyclic ordering of windows, starting from the selected window
+(@pxref{Cyclic Window Ordering}). If no such window exists, the
+return value is @code{nil}.
-The argument @var{buffer-or-name} may be a buffer or a buffer name and
-defaults to the current buffer. The optional argument @var{all-frames}
-specifies which windows to consider:
+@var{buffer-or-name} should be a buffer or the name of a buffer; if
+omitted or @code{nil}, it defaults to the current buffer. The
+optional argument @var{all-frames} specifies which windows to
+consider:
@itemize @bullet
@item
-@code{nil} means consider windows on the selected frame.
-@item
@code{t} means consider windows on all existing frames.
@item
@code{visible} means consider windows on all visible frames.
0 means consider windows on all visible or iconified frames.
@item
A frame means consider windows on that frame only.
+@item
+Any other value means consider windows on the selected frame.
@end itemize
-Observe that the behavior of @code{get-buffer-window} may differ from
-that of @code{next-window} (@pxref{Cyclic Window Ordering}) when
-@var{all-frames} equals @code{nil} or any value not listed here.
-Perhaps we will change @code{get-buffer-window} in the future to make it
-compatible with the other functions.
+Note that these meanings differ slightly from those of the
+@var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window
+Ordering}). This function may be changed in a future version of Emacs
+to eliminate this discrepancy.
@end defun
@defun get-buffer-window-list &optional buffer-or-name minibuf all-frames
This function returns a list of all windows currently displaying
-@var{buffer-or-name}. The argument @var{buffer-or-name} may be a buffer
-or the name of an existing buffer and defaults to the current buffer.
+@var{buffer-or-name}. @var{buffer-or-name} should be a buffer or the
+name of an existing buffer. If omitted or @code{nil}, it defaults to
+the current buffer.
-The two remaining arguments work like the same-named arguments of
-@code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not}
-like the optional arguments of @code{get-buffer-window}.
+The arguments @var{minibuf} and @var{all-frames} have the same
+meanings as in the function @code{next-window} (@pxref{Cyclic Window
+Ordering}). Note that the @var{all-frames} argument does @emph{not}
+behave exactly like in @code{get-buffer-window}.
@end defun
@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. For each such window, it choose another
-buffer using @code{switch-to-prev-buffer} (@pxref{Window History}).
-
-@var{buffer-or-name} may be a buffer, or the name of an existing
-buffer; it defaults to the current buffer.
-
-If a window displaying @var{buffer-or-name} is dedicated
-(@pxref{Dedicated Windows}), has never displayed any other buffers and
-is not the only window on its frame, that window is deleted. If that
-window is the only window on its frame and there are other frames on the
-frame's terminal, that frame is deleted too; otherwise, the buffer
-provided by the function @code{switch-to-prev-buffer} (@pxref{Window
-History}) is displayed instead.
+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.
@end deffn
-
@node Switching Buffers
@section Switching to a Buffer in a Window
@cindex switching to a buffer
meanings as in @code{switch-to-buffer}.
@end deffn
-The above commands use @code{pop-to-buffer}, which is the function
-used by Lisp programs to flexibly display a buffer in some window and
-select that window for editing:
+The above commands use the function @code{pop-to-buffer}, which
+flexibly displays a buffer in some window and selects that window for
+editing. In turn, @code{pop-to-buffer} uses @code{display-buffer} for
+displaying the buffer. Hence, all the variables affecting
+@code{display-buffer} will affect it as well. @xref{Choosing Window},
+for the documentation of @code{display-buffer}.
@defun pop-to-buffer buffer-or-name &optional action norecord
This function makes @var{buffer-or-name} the current buffer and
possible (@pxref{Input Focus}). The return value is the buffer that
was switched to.
-This function uses @code{display-buffer} to display the buffer, so all
-the variables affecting @code{display-buffer} will affect it as well.
-@xref{Choosing Window}.
-
If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
returned by @code{other-buffer} (@pxref{The Buffer List}). If
@var{buffer-or-name} is a string that is not the name of any existing
The command @code{display-buffer} flexibly chooses a window for
display, and displays a specified buffer in that window. It can be
-called interactively, via the key binding @kbd{C-x 4 o}. It is also
+called interactively, via the key binding @kbd{C-x 4 C-o}. It is also
used as a subroutine by many functions and commands, including
@code{switch-to-buffer} and @code{pop-to-buffer} (@pxref{Switching
Buffers}).
@cindex display action
-@cindex action function, for display-buffer
-@cindex action alist, for display-buffer
+@cindex action function, for @code{display-buffer}
+@cindex action alist, for @code{display-buffer}
This command performs several complex steps to find a window to
display in. These steps are described by means of @dfn{display
actions}, which have the form @code{(@var{function} . @var{alist})}.
@item
The user option @code{display-buffer-alist}.
+@item
+A special action for handling @code{special-display-buffer-names} and
+@code{special-display-regexps}, if either of those variables is
+non-@code{nil}. @xref{Choosing Window Options}.
+
@item
The @var{action} argument.
@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-nil.
+until one of the functions returns non-@code{nil}.
The argument @var{action} can also have a non-@code{nil}, non-list
value. This has the special meaning that the buffer should be
This function tries to display @var{buffer} in the selected window.
It fails if the selected window is a minibuffer window or is dedicated
to another buffer (@pxref{Dedicated Windows}). It also fails if
-@var{alist} has a non-nil @code{inhibit-same-window} entry.
+@var{alist} has a non-@code{nil} @code{inhibit-same-window} entry.
@end defun
@defun display-buffer-reuse-window buffer alist
that is already displaying it.
If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry,
-the selected window is not eligible for reuse.
-
-If @var{alist} contains a @code{reusable-frames} entry, its value
-determines which frames to search for a reusable window:
+the selected window is not eligible for reuse. If @var{alist}
+contains a @code{reusable-frames} entry, its value determines which
+frames to search for a reusable window:
@itemize @bullet
@item
variable @code{display-buffer-reuse-frames} or the variable
@code{pop-up-frames} is non-@code{nil}, it searches all frames on the
current terminal. @xref{Choosing Window Options}.
+
+If this function chooses a window on another frame, it makes that
+frame visible and raises it if necessary.
@end defun
@defun display-buffer-pop-up-frame buffer alist
This function creates a new frame, and displays the buffer in that
-frame's window.
+frame's window. It actually performs the frame creation by calling
+the function specified in @code{pop-up-frame-function}
+(@pxref{Choosing Window Options}).
@end defun
@defun display-buffer-pop-up-window buffer alist
-This function tries to display @var{buffer} by splitting the selected
-window. It uses @code{split-window-sensibly} as a subroutine
-(@pxref{Choosing Window Options}).
+This function tries to display @var{buffer} by splitting the largest
+or least recently-used window (typically one on the selected frame).
+It actually performs the split by calling the function specified in
+@code{split-window-preferred-function} (@pxref{Choosing Window
+Options}).
+
+It 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}).
@end defun
@defun display-buffer-use-some-window buffer alist
options.
@defopt display-buffer-reuse-frames
-If this variable is non-@code{nil}, @code{display-buffer} searches
-visible and iconified frames for a window displaying
-@var{buffer-or-name}. If there is such a window, @code{display-buffer}
-makes that window's frame visible and raises it if necessary, and
-returns the window. If there is no such window or
-@code{display-buffer-reuse-frames} is @code{nil}, the behavior of
-@code{display-buffer} is determined by the variables described next.
+If the value of this variable is non-@code{nil}, @code{display-buffer}
+may search all frames on the current terminal when looking for a
+window already displaying the specified buffer. The default is
+@code{nil}. This variable is consulted by the action function
+@code{display-buffer-reuse-window} (@pxref{Display Action Functions}).
@end defopt
@defopt pop-up-windows
-This variable specifies whether @code{display-buffer} is allowed to
-split (@pxref{Splitting Windows}) an existing window. If this variable
-is non-@code{nil}, @code{display-buffer} tries to split the largest or
-least recently used window on the selected frame. (If the selected
-frame is a minibuffer-only frame, @code{display-buffer} tries to split a
-window on another frame instead.) If this variable is @code{nil} or the
-variable @code{pop-up-frames} (see below) is non-@code{nil},
-@code{display-buffer} does not split any window.
+If the value of this variable is non-@code{nil}, @code{display-buffer}
+is allowed to split an existing window to make a new window for
+displaying in. This is the default.
+
+This variable is provided mainly for backward compatibility. It is
+obeyed by @code{display-buffer} via a special mechanism in
+@code{display-buffer-fallback-action}, which only calls the action
+function @code{display-buffer-pop-up-window} (@pxref{Display Action
+Functions}) when the value is @code{nil}. It is not consulted by
+@code{display-buffer-pop-up-window} itself, which the user may specify
+directly in @code{display-buffer-alist} etc.
@end defopt
@defopt split-window-preferred-function
-This variable must specify a function with one argument, which is a
-window. The @code{display-buffer} routines will call this function with
-one or more candidate windows when they look for a window to split. The
-function is expected to split that window and return the new window. If
-the function returns @code{nil}, this means that the argument window
-cannot (or shall not) be split.
-
-The default value of @code{split-window-preferred-function} is the
-function @code{split-window-sensibly} described below. If you
-customize this option, bear in mind that the @code{display-buffer}
-routines may call your function up to two times when trying to split a
-window. The argument of the first call is the largest window on the
-chosen frame (as returned by @code{get-largest-window}). If that call
-fails to return a live window, your function is called a second time
-with the least recently used window on that frame (as returned by
-@code{get-lru-window}).
-
-The function specified by this option may try to split any other window
-instead of the argument window. Note that the window selected at the
-time @code{display-buffer} was invoked is still selected when your
-function is called. Hence, you can split the selected window (instead
-of the largest or least recently used one) by simply ignoring the window
-argument in the body of your function. You can even choose to not split
-any window as long as the return value of your function specifies a live
-window or @code{nil}, but you are not encouraged to do so
-unconditionally. If you want @code{display-buffer} to never split any
-windows, set @code{pop-up-windows} to @code{nil}.
+This variable specifies a function for splitting a window, in order to
+make a new window for displaying a buffer. It is used by the
+@code{display-buffer-pop-up-window} action function to actually split
+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
+desired buffer) or @code{nil} (which means the splitting failed).
@end defopt
@defun split-window-sensibly window
-This function takes a window as argument and tries to split that window
-in a suitable way. The two variables described next are useful for
-tuning the behavior of this function.
+This function tries to split @code{window}, and return the newly
+created window. If @code{window} cannot be split, it returns
+@code{nil}.
+
+This function obeys the usual rules that determine when a window may
+be split (@pxref{Splitting Windows}). It first tries to split by
+placing the new window below, subject to the restriction imposed by
+@code{split-height-threshold} (see below) in addition to any other
+restrictions. If that fails, it tries to split by placing the new
+window to the right, subject to @code{split-width-threshold} (see
+below). If that fails, and the window is the only window on its
+frame, this function again tries to split and place the new window
+below, disregarding @code{split-height-threshold}. If this fails as
+well, this function gives up and returns @code{nil}.
@end defun
@defopt split-height-threshold
-This variable specifies whether @code{split-window-sensibly} may split
-windows vertically. If it is an integer, @code{split-window-sensibly}
-tries to vertically split a window only if it has at least this many
-lines. If the window has less lines, splitting fails, or the value of
-this variable is @code{nil}, @code{split-window-sensibly} will try to
-split the window horizontally, subject to restrictions of
-@code{split-width-threshold} (see below). If splitting horizontally
-fails too and the window is the only window on its frame,
-@code{split-window-sensibly} will try to split the window vertically
-disregarding the value of @code{split-height-threshold}. If this fails
-as well, @code{split-window-sensibly} returns @code{nil}.
-
-@code{split-window-sensibly} does not split vertically a window whose
-height is fixed (@pxref{Resizing Windows}). Also, it vertically splits
-a window only if the space taken up by that window can accommodate two
-windows one above the other that are both at least
-@code{window-min-height} lines tall. Moreover, if the window that shall
-be split has a mode line, @code{split-window-sensibly} does not split
-the window unless the new window can accommodate a mode line too.
+This variable, used by @code{split-window-sensibly}, specifies whether
+to split the window placing the new window below. If it is an
+integer, that means to split only if the original window has at least
+that many lines. If it is @code{nil}, that means not to split this
+way.
@end defopt
@defopt split-width-threshold
-This variable specifies whether @code{split-window-sensibly} may split
-windows horizontally. If it is an integer, @code{split-window-sensibly}
-tries to horizontally split a window only if it has at least this many
-columns. If it is @code{nil}, @code{split-window-sensibly} will not
-split the window horizontally. (It still might split the window
-vertically, though, see above.)
-
-@code{split-window-sensibly} does not split horizontally a window if
-that window's width is fixed (@pxref{Resizing Windows}). Also, it
-horizontally splits a window only if the space that window takes up can
-accommodate two windows side by side that are both at least
-@code{window-min-width} columns wide.
-@end defopt
-
-@defopt even-window-heights
-This variable specifies whether @code{display-buffer} should even out
-window heights if the buffer gets displayed in an existing window, above
-or beneath another window. If @code{even-window-heights} is
-non-@code{nil}, the default, window heights will be evened out. If
-either of the involved window has fixed height (@pxref{Resizing
-Windows}) or @code{even-window-heights} is @code{nil}, the original
-window heights will be left alone.
+This variable, used by @code{split-window-sensibly}, specifies whether
+to split the window placing the new window to the right. If the value
+is an integer, that means to split only if the original window has at
+least that many columns. If the value is @code{nil}, that means not
+to split this way.
@end defopt
-@c Emacs 19 feature
@defopt pop-up-frames
-This variable specifies whether @code{display-buffer} should make new
-frames. If it is non-@code{nil}, @code{display-buffer} looks for a
-window already displaying @var{buffer-or-name} on any visible or
-iconified frame. If it finds such a window, it makes that window's
-frame visible and raises it if necessary, and returns the window.
-Otherwise it makes a new frame, unless the variable's value is
-@code{graphic-only} and the selected frame is not on a graphic display.
-@xref{Frames}, for more information.
-
-Note that the value of @code{pop-up-windows} does not matter if
-@code{pop-up-frames} is non-@code{nil}. If @code{pop-up-frames} is
-@code{nil}, then @code{display-buffer} either splits a window or reuses
-one.
+If the value of this variable is non-@code{nil}, that means
+@code{display-buffer} may display buffers by making new frames. The
+default is @code{nil}.
+
+A non-@code{nil} value also means that when @code{display-buffer} is
+looking for a window already displaying @var{buffer-or-name}, it can
+search any visible or iconified frame, not just the selected frame.
+
+This variable is provided mainly for backward compatibility. It is
+obeyed by @code{display-buffer} via a special mechanism in
+@code{display-buffer-fallback-action}, which calls the action function
+@code{display-buffer-pop-up-frame} (@pxref{Display Action Functions})
+if the value is non-@code{nil}. (This is done before attempting to
+split a window.) This variable is not consulted by
+@code{display-buffer-pop-up-frame} itself, which the user may specify
+directly in @code{display-buffer-alist} etc.
@end defopt
-@c Emacs 19 feature
@defopt pop-up-frame-function
-This variable specifies how to make a new frame if @code{pop-up-frames}
-is non-@code{nil}.
-
-The value of this variable must be a function of no arguments. When
-@code{display-buffer} makes a new frame, it does so by calling that
-function, which should return a frame. The default value of this
-variable is a function that creates a frame using the parameters
-specified by @code{pop-up-frame-alist} described next.
+This variable specifies a function for creating a new frame, in order
+to make a new window for displaying a buffer. It is used by the
+@code{display-buffer-pop-up-frame} action function (@pxref{Display
+Action Functions}).
+
+The value should be a function that takes no arguments and returns a
+frame, or @code{nil} if no frame could be created. The default value
+is a function that creates a frame using the parameters specified by
+@code{pop-up-frame-alist} (see below).
@end defopt
@defopt pop-up-frame-alist
-This variable holds an alist specifying frame parameters used by the
-default value of @code{pop-up-frame-function} for making new frames.
-@xref{Frame Parameters}, for more information about frame parameters.
+This variable holds an alist of frame parameters (@pxref{Frame
+Parameters}), which is used by the default function in
+@code{pop-up-frame-function} to make a new frame. The default is
+@code{nil}.
@end defopt
@defopt special-display-buffer-names
above.
@end defopt
-If all options described above fail to produce a suitable window,
-@code{display-buffer} tries to reuse an existing window. As a last
-resort, it will try to display @var{buffer-or-name} on a separate frame.
-In that case, the value of @code{pop-up-frames} is disregarded.
-
-
@node Window History
@section Window History
@cindex window history
@section Quitting Windows
When you want to get rid of a window used for displaying a buffer you
-can use the function @code{delete-window} (@pxref{Deleting Windows}) to
-remove that window from its frame. If the buffer has been shown on a
-separate frame, you might want to call @code{delete-frame}
-(@pxref{Deleting Frames}) instead. If, on the other 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
+can call @code{delete-window} or @code{delete-windows-on}
+(@pxref{Deleting Windows}) to remove that window from its frame. If the
+buffer is shown on a separate frame, you might want to call
+@code{delete-frame} (@pxref{Deleting Frames}) instead. If, on the other
+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
(@pxref{Killing Buffers}) the window's buffer.
The following function uses information on how the window for
Quitting @var{window} means to proceed as follows: If @var{window} was
created specially for displaying its current buffer, delete @var{window}
provided its frame contains at least one other live window. If
-@var{window} is the only window on its frame and other frames still
-exist, delete the frame together with @var{window}. If, however, there
-are no other frames left, display some other buffer in @var{window}.
+@var{window} is the only window on its frame and there are other frames
+on the frame's terminal, the value of @var{kill} determines how to
+proceed with the window. If @var{kill} is @code{nil}, the fate of the
+frame is determined by calling @code{frame-auto-hide-function} (see
+below) with that frame as sole argument. If @var{kill} is
+non-@code{nil}, the frame is deleted unconditionally.
If @var{window} was reused for displaying its buffer, this command tries
to display the buffer previously shown in it. It also tries to restore
(@pxref{Window Parameters}) and resets that parameter to @code{nil}
after it's done.
+The following option specifies how to deal with a frame containing just
+one window that shall be either quit or whose buffer shall be buried.
+
+@defopt frame-auto-hide-function
+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
+that shall be buried. It is also called by @code{quit-window} (see
+above) when the frame of the window that shall be quit has been
+specially created for displaying that window's buffer and the buffer
+shall be buried.
+
+The default is to call @code{iconify-frame} (@pxref{Visibility of
+Frames}). Alternatively, you may either specify @code{delete-frame}
+(@pxref{Deleting Frames}) to remove the frame from its display,
+@code{ignore} to leave the frame unchanged, or any other function that
+can take a frame as its sole argument.
+
+Note that the function specified by this option is called if and only if
+there's at least one other frame on the terminal of the frame it's
+supposed to handle and that frame contains only one live window.
+@end defopt
+
@node Window Point
@section Windows and Point
displayed at a specified vertical position within the window. It does
not ``move point'' with respect to the text.
-If @var{count} is a nonnegative number, that puts the line containing
+If @var{count} is a non-negative number, that puts the line containing
point @var{count} lines down from the top of the window. If
@var{count} is a negative number, then it counts upward from the
bottom of the window, so that @minus{}1 stands for the last usable
@end group
@end example
-
@node Coordinates and Windows
@section Coordinates and Windows
+@cindex frame-relative coordinate
+@cindex coordinate, relative to frame
+@cindex window position
-This section describes how to relate screen coordinates to windows.
+ This section describes functions that report the position of a
+window. Most of these functions report positions relative to the
+window's frame. In this case, the coordinate origin @samp{(0,0)} lies
+near the upper left corner of the frame. For technical reasons, on
+graphical displays the origin is not located at the exact corner of
+the graphical window as it appears on the screen. If Emacs is built
+with the GTK+ toolkit, the origin is at the upper left corner of the
+frame area used for displaying Emacs windows, below the title-bar,
+GTK+ menu bar, and tool bar (since these are drawn by the window
+manager and/or GTK+, not by Emacs). But if Emacs is not built with
+GTK+, the origin is at the upper left corner of the tool bar (since in
+this case Emacs itself draws the tool bar). In both cases, the X and
+Y coordinates increase rightward and downward respectively.
+
+ Except where noted, X and Y coordinates are reported in integer
+character units, i.e. numbers of lines and columns respectively. On a
+graphical display, each ``line'' and ``column'' corresponds to the
+height and width of a default character specified by the frame's
+default font.
+
+@defun window-edges &optional window
+This function returns a list of the edge coordinates of @var{window}.
+If @var{window} is omitted or @code{nil}, it defaults to the selected
+window.
-@defun window-at x y &optional frame
-This function returns the window containing the specified cursor
-position in the frame @var{frame}. The coordinates @var{x} and @var{y}
-are measured in characters and count from the top left corner of the
-frame. If they are out of range, @code{window-at} returns @code{nil}.
+The return value has the form @code{(@var{left} @var{top} @var{right}
+@var{bottom})}. These list elements are, respectively, the X
+coordinate of the leftmost column occupied by the window, the Y
+coordinate of the topmost row, the X coordinate one column to the
+right of the rightmost column, and the Y coordinate one row down from
+the bottommost row.
-If you omit @var{frame}, the selected frame is used.
+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-only 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 coordinates-in-window-p coordinates window
-This function checks whether a particular frame position falls within
-the window @var{window}.
+@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.
+@end defun
+
+@defun window-top-line &optional window
+This function returns the Y coordinate of the topmost row of
+@var{window}, equivalent to the @var{top} entry in the list returned
+by @code{window-edges}.
+@end defun
+
+@defun window-left-column &optional window
+This function returns the X coordinate of the leftmost column of
+@var{window}, equivalent to the @var{left} entry in the list returned
+by @code{window-edges}.
+@end defun
+
+ The following functions can be used to relate a set of
+frame-relative coordinates to a window:
+
+@defun window-at x y &optional frame
+This function returns the live window at the frame-relative
+coordinates @var{x} and @var{y}, on frame @var{frame}. If there is no
+window at that position, the return value is @code{nil}. If
+@var{frame} is omitted or @code{nil}, it defaults to the selected
+frame.
+@end defun
-The argument @var{coordinates} is a cons cell of the form @code{(@var{x}
-. @var{y})}. The coordinates @var{x} and @var{y} are measured in
-characters, and count from the top left corner of the screen or frame.
+@defun coordinates-in-window-p coordinates window
+This function checks whether a window @var{window} occupies the
+frame-relative coordinates @var{coordinates}, and if so which part of
+the window that is. @var{window} should be a live window.
+@var{coordinates} should be a cons cell of the form @code{(@var{x}
+. @var{y})}, where @var{x} and @var{y} are frame-relative coordinates.
-The value returned by @code{coordinates-in-window-p} is non-@code{nil}
-if the coordinates are inside @var{window}. The value also indicates
-what part of the window the position is in, as follows:
+If there is no window at the specified position, the return value is
+@code{nil} . Otherwise, the return value is one of the following:
@table @code
@item (@var{relx} . @var{rely})
argument because it always uses the frame that @var{window} is on.
@end defun
+ The following functions return window positions in pixels, rather
+than character units. Though mostly useful on graphical displays,
+they can also be called on text-only terminals, where the screen area
+of each text character is taken to be ``one pixel''.
+
+@defun window-pixel-edges &optional window
+This function returns a list of pixel coordinates for the edges of
+@var{window}. If @var{window} is omitted or @code{nil}, it defaults
+to the selected window.
+
+The return value has the form @code{(@var{left} @var{top} @var{right}
+@var{bottom})}. The list elements are, respectively, the X pixel
+coordinate of the left window edge, the Y pixel coordinate of the top
+edge, one more than the X pixel coordinate of the right edge, and one
+more than the Y pixel coordinate of the bottom edge.
+@end defun
+
+@defun window-inside-pixel-edges &optional window
+This function is like @code{window-pixel-edges}, except that it
+returns the pixel coordinates for the edges of the window's text area,
+rather than the pixel coordinates for the edges of the window itself.
+@var{window} must specify a live window.
+@end defun
+
+ The following functions return window positions in pixels, relative
+to the display screen rather than the frame:
+
+@defun window-absolute-pixel-edges &optional window
+This function is like @code{window-pixel-edges}, except that it
+returns the edge pixel coordinates relative to the top left corner of
+the display screen.
+@end defun
+
+@defun window-inside-absolute-pixel-edges &optional window
+This function is like @code{window-inside-pixel-edges}, except that it
+returns the edge pixel coordinates relative to the top left corner of
+the display screen. @var{window} must specify a live window.
+@end defun
@node Window Configurations
@section Window Configurations
@defun current-window-configuration &optional frame
This function returns a new object representing @var{frame}'s current
window configuration. The default for @var{frame} is the selected
-frame.
+frame. The variable @code{window-persistent-parameters} specifies
+whether and which window parameters are saved by this function, see
+@ref{Window Parameters} for details.
@end defun
@defun set-window-configuration configuration
@group
(let ((config (current-window-configuration)))
(unwind-protect
- (progn (split-window-vertically nil)
+ (progn (split-window-below nil)
@dots{})
(set-window-configuration config)))
@end group
The objects returned by @code{current-window-configuration} die
together with the Emacs process. In order to store a window
-configuration on disk and read it back in another Emacs session the
-following two functions can be used.
+configuration on disk and read it back in another Emacs session, the
+functions described next can be used. These functions are also useful
+to clone the state of a frame into an arbitrary live window
+(@code{set-window-configuration} effectively clones the windows of a
+frame into the root window of that very frame only).
-@defun window-state-get &optional window markers
+@defun window-state-get &optional window writable
This function returns the state of @var{window} as a Lisp object. The
argument @var{window} can be any window and defaults to the root window
of the selected frame.
-The optional argument @var{markers} non-@code{nil} means to use markers
-for sampling positions like @code{window-point} or @code{window-start}.
-This argument should be non-@code{nil} only if the value is used for
-putting the state back in the same session since markers slow down
-processing.
+If the optional argument @var{writable} is non-@code{nil}, this means to
+not use markers for sampling positions like @code{window-point} or
+@code{window-start}. This argument should be non-@code{nil} when the
+state shall be written to disk and read back in another session.
+
+Together, the argument @var{writable} and the variable
+@code{window-persistent-parameters} specify which window parameters are
+saved by this function, see @ref{Window Parameters} for details.
@end defun
-The value returned by @code{window-state-get} can be converted by using
-one of the functions defined by Desktop Save Mode (@pxref{Desktop Save
-Mode}) to an object that can be written to a file. Such objects can be
-read back and converted to a Lisp object representing the state of the
-window. That Lisp object can be used as argument for the following
-function in order to restore the state window in another window.
+The value returned by @code{window-state-get} can be used in the same
+session to make a clone of a window in another window. It can be also
+written to disk and read back in another session. In either case, use
+the function described next 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
The optional argument @var{ignore} non-@code{nil} means to ignore
minimum window sizes and fixed size restrictions. If @var{ignore}
-equals @code{safe}, this means subwindows can get as small as one line
+equals @code{safe}, this means windows can get as small as one line
and/or two columns.
@end defun
is the selected window.
@end defun
+By default, functions saving and restoring window configurations or the
+states of windows (@pxref{Window Configurations}) do not care about
+window parameters. This means, that when you change the value of a
+parameter within the body of a @code{save-window-excursion}, the
+previous value is not restored upon exit of that macro. It also means
+that when you restore via @code{window-state-put} a window state saved
+earlier by @code{window-state-get}, all cloned windows have their
+parameters reset to @code{nil}. The following variable allows to
+override the standard behavior.
+
+@defvar window-persistent-parameters
+This variable is an alist specifying which parameters get saved by
+@code{current-window-configuration} and @code{window-state-get} and
+subsequently restored by @code{set-window-configuration} and
+@code{window-state-put}, see @ref{Window Configurations}.
+
+The @sc{car} of each entry of this alist is the symbol specifying the
+parameter. The @sc{cdr} should be one of the following:
+
+@table @asis
+@item @code{nil}
+This value means the parameter is neither saved by
+@code{window-state-get} nor by @code{current-window-configuration}.
+
+@item @code{t}
+This value specifies that the parameter is saved by
+@code{current-window-configuration} and, provided its @var{writable}
+argument is @code{nil}, by @code{window-state-get}.
+
+@item @code{writable}
+This means that the parameter is saved unconditionally by both
+@code{current-window-configuration} and @code{window-state-get}. This
+value should not be used for parameters whose values do not have a read
+syntax. Otherwise, invoking @code{window-state-put} in another session
+may fail with an @code{invalid-read-syntax} error.
+@end table
+@end defvar
+
Some functions, notably @code{delete-window},
@code{delete-other-windows} and @code{split-window} may behave specially
when their @var{window} argument has a parameter set. You can override
@end defvar
The following parameters are currently used by the window management
-code.
+code:
@table @asis
@item @code{delete-window}
@item @code{no-other-window}
This parameter marks the window as not selectable by @code{other-window}
(@pxref{Cyclic Window Ordering}).
+
+@item @code{clone-of}
+This parameter specifies the window this one has been cloned from and is
+installed by @code{window-state-get}, see @ref{Window Configurations}.
+
+@item @code{quit-restore}
+This parameter tells how to proceed with a window when the buffer it
+shows is no more needed. It is installed by the buffer display
+functions (@pxref{Choosing Window}) and consulted by the function
+@code{quit-window} (@pxref{Quitting Windows}).
@end table
In addition, the parameters @code{window-atom} and @code{window-side}
-are reserved and should not be used by applications. The
-@code{quit-restore} parameter tells how to proceed with a window when
-the buffer it shows is no more needed. This parameter is installed by
-the buffer display functions (@pxref{Choosing Window}) and consulted by
-the function @code{quit-window} (@pxref{Quitting Windows}).
+are reserved and should not be used by applications.
@node Window Hooks