@group
____________________________________________
|______________ Header Line ______________|RD| ^
- ^ |LS|LF|LM| |RM|RF|RS| | |
+ ^ |LS|LM|LF| |RF|RM|RS| | |
| | | | | | | | | | |
Window | | | | Text Area | | | | | Window
Body | | | | | (Window Body) | | | | | Total
Height | | | | | | | | | Height
| | | | |<- Window Body Width ->| | | | | |
v |__|__|__|_______________________|__|__|__| | |
+ |_________ Horizontal Scroll Bar _________| | |
|_______________ Mode Line _______________|__| |
|_____________ Bottom Divider _______________| v
<---------- Window Total Width ------------>
At the center of the window is the @dfn{text area}, or @dfn{body},
where the buffer text is displayed. The text area can be surrounded by
a series of optional areas. On the left and right, from innermost to
-outermost, these are the left and right margins, denoted by LM and RM in
-the schematic (@pxref{Display Margins}); the left and right fringes,
-denoted by LF and RF (@pxref{Fringes}); the left or right scroll bar,
-only one of which is present at any time, denoted by LS and RS
-(@pxref{Scroll Bars}); and the right divider, denoted by RD
+outermost, these are the left and right fringes, denoted by LF and RF
+(@pxref{Fringes}); the left and right margins, denoted by LM and RM in
+the schematic (@pxref{Display Margins}); the left or right vertical
+scroll bar, only one of which is present at any time, denoted by LS and
+RS (@pxref{Scroll Bars}); and the right divider, denoted by RD
(@pxref{Window Dividers}). At the top of the window is the header line
-(@pxref{Header Lines}); at the bottom of the window is the mode line
-(@pxref{Mode Line Format}) followed by the bottom divider (@pxref{Window
-Dividers}).
+(@pxref{Header Lines}). At the bottom of the window are the horizontal
+scroll bar (@pxref{Scroll Bars}); the mode line (@pxref{Mode Line
+Format}); and the bottom divider (@pxref{Window Dividers}).
Emacs provides miscellaneous functions for finding the height and
width of a window. The return value of many of these functions can be
@cindex height of a window
@cindex total height of a window
The @dfn{total height} of a window is the number of lines comprising
-the window's body, the header line, the mode line and the bottom divider
-(if any). Note that the height of a frame is not the same as the height
-of its root window (@pxref{Windows and Frames}), since a frame may also
-contain an echo area, a menu bar, and a tool bar (@pxref{Size and
-Position}).
+the window's body, the header line, the horizontal scroll bar, the mode
+line and the bottom divider (if any).
@defun window-total-height &optional window round
This function returns the total height, in lines, of the window
the selected window. If @var{window} is an internal window, the return
value is the total height occupied by its descendant windows.
- If a window's pixel height is not an integral multiple of its frame's
+ If a window's pixel height is not an integral multiple of its frame's
default character height, the number of lines occupied by the window is
rounded internally. This is done in a way such that, if the window is a
parent window, the sum of the total heights of all its child windows
internally equals the total height of their parent. This means that
although two windows have the same pixel height, their internal total
-heights may differ by one line. This means also, that if this window is
-vertically combined and has a right sibling, the topmost row of that
+heights may differ by one line. This means also, that if window is
+vertically combined and has a next sibling, the topmost row of that
sibling can be calculated as the sum of this window's topmost row and
total height (@pxref{Coordinates and Windows})
- If the optional argument @var{round} equals @code{ceiling}, this
+ If the optional argument @var{round} is @code{ceiling}, this
function returns the smallest integer larger than @var{window}'s pixel
-height divided by the character height of @var{window}'s frame; if it is
-@code{floor}, it returns the largest integer smaller than @var{window}'s
-pixel height divided by the character height of @var{window}'s frame.
-Any other value of @var{round} means to return the internal value of the
-total height of @var{window}.
+height divided by the character height of its frame; if it is
+@code{floor}, it returns the largest integer smaller than said value;
+with any other @var{round} it returns the internal value of
+@var{windows}'s total height.
@end defun
@cindex window width
the selected window. If @var{window} is internal, the return value is
the total width occupied by its descendant windows.
- If a window's pixel width is not an integral multiple of its frame's
+ If a window's pixel width is not an integral multiple of its frame's
character width, the number of lines occupied by the window is rounded
internally. This is done in a way such that, if the window is a parent
window, the sum of the total widths of all its children internally
equals the total width of their parent. This means that although two
windows have the same pixel width, their internal total widths may
differ by one column. This means also, that if this window is
-horizontally combined and has a right sibling, the leftmost column of
+horizontally combined and has a next sibling, the leftmost column of
that sibling can be calculated as the sum of this window's leftmost
-column and total width (@pxref{Coordinates and Windows}).
-
-If the optional argument @var{round} is @code{ceiling}, this function
-will return the smallest integer larger than @var{window}'s pixel width
-divided by the character width of @var{window}'s frame; if it is
-@code{floor}, it returns the largest integer smaller than @var{window}'s
-pixel width divided by the character width of @var{window}'s frame. Any
-other value of @var{round} means to return the internal total width of
-@var{window}.
+column and total width (@pxref{Coordinates and Windows}). The optional
+argument @var{round} behaves as it does for @code{window-total-height}.
@end defun
@defun window-total-size &optional window horizontal round
omitted or @code{nil}, this is equivalent to calling
@code{window-total-height} for @var{window}; otherwise it is equivalent
to calling @code{window-total-width} for @var{window}. The optional
-argument @code{ROUND} is handled as for @code{window-total-height} and
-@code{window-total-width}.
+argument @var{round} behaves as it does for @code{window-total-height}.
@end defun
The following two functions can be used to return the total size of a
This function returns the total height of window @var{window} in pixels.
@var{window} must be a valid window and defaults to the selected one.
-The return value includes mode and header line and a bottom divider, if
-any. If @var{window} is an internal window, its pixel height is the
-pixel height of the screen areas spanned by its children.
+The return value includes mode and header line, a horizontal scroll bar
+and a bottom divider, if any. If @var{window} is an internal window,
+its pixel height is the pixel height of the screen areas spanned by its
+children.
@end defun
@cindex window pixel height
window has any adjacent windows.
@defun window-full-height-p &optional window
-This function returns non-@code{nil} if @var{window} has no other
-window above or below it in its frame, i.e., its total height equals
-the total height of the root window on that frame. If @var{window} is
-omitted or @code{nil}, it defaults to the selected window.
+This function returns non-@code{nil} if @var{window} has no other window
+above or below it in its frame. More precisely, this means that the
+total height of @var{window} equals the total height of the root window
+on that frame. The minibuffer window does not count in this regard. If
+@var{window} is omitted or @code{nil}, it defaults to the selected
+window.
@end defun
@defun window-full-width-p &optional window
@cindex body height of a window
@cindex window body width
The @dfn{body height} of a window is the height of its text area, which
-does not include a mode or header line or a bottom divider.
+does not include a mode or header line, a horizontal scroll bar, or a
+bottom divider.
@defun window-body-height &optional window pixelwise
This function returns the height, in lines, of the body of window
@code{window-width} is an alias for @code{window-body-width}. These
aliases are considered obsolete and will be removed in the future.
+ The pixel heights of a window's mode and header line can be retrieved
+with the functions given below. Their return value is usually accurate
+unless the window has not been displayed before: In that case, the
+return value is based on an estimate of the font used for the window's
+frame.
+
+@defun window-mode-line-height &optional window
+This function returns the height in pixels of @var{window}'s mode line.
+@var{window} must be a live window and defaults to the selected one. If
+@var{window} has no mode line, the return value is zero.
+@end defun
+
+@defun window-header-line-height &optional window
+This function returns the height in pixels of @var{window}'s header
+line. @var{window} must be a live window and defaults to the selected
+one. If @var{window} has no header line, the return value is zero.
+@end defun
+
+Functions for retrieving the height and/or width of window dividers
+(@pxref{Window Dividers}), fringes (@pxref{Fringes}), scroll bars
+(@pxref{Scroll Bars}), and display margins (@pxref{Display Margins}) are
+described in the corresponding sections.
+
@cindex fixed-size window
@vindex window-min-height
@vindex window-min-width
@defopt window-min-height
This option specifies the minimum total height, in lines, of any window.
Its value has to accommodate at least one text line as well as a mode
-and header line and a bottom divider, if present.
+and header line, a horizontal scroll bar and a bottom divider, if
+present.
@end defopt
@defopt window-min-width
The return value makes sure that all components of @var{window} remain
fully visible if @var{window}'s size were actually set to it. With
-@var{horizontal} @code{nil} it includes the mode and header line and the
-bottom divider. With @var{horizontal} non-@code{nil} it includes the
-fringes, a scroll bar, and a right divider, if present. It does not,
-however, include the space reserved for the margins.
+@var{horizontal} @code{nil} it includes the mode and header line, the
+horizontal scroll bar and the bottom divider. With @var{horizontal}
+non-@code{nil} it includes the fringes, a scroll bar, and a right
+divider, if present. It does not, however, include the space reserved
+for the margins.
The optional argument @var{ignore}, if non-@code{nil}, means ignore
restrictions imposed by fixed size windows, @code{window-min-height} or
(@pxref{Window Sizes}). However, if the optional argument @var{ignore}
is non-@code{nil}, this function ignores @code{window-min-height} and
@code{window-min-width}, as well as @code{window-size-fixed}. Instead,
-it considers the minimum-height window to be one consisting of a header,
-a mode line and a bottom divider (if any), plus a text area one line
-tall; and a minimum-width window as one consisting of fringes, margins,
-a scroll bar and a right divider (if any), plus a text area two columns
-wide.
+it considers the minimum-height window to be one consisting of a header
+and a mode line, a horizontal scrollbar and a bottom divider (if any),
+plus a text area one line tall; and a minimum-width window as one
+consisting of fringes, margins, a scroll bar and a right divider (if
+any), plus a text area two columns wide.
-If the optional argument @code{pixelwise} is non-@code{nil},
-@var{delta} will be interpreted as pixels.
+If the optional argument @var{pixelwise} is non-@code{nil},
+@var{delta} is interpreted as pixels.
@end defun
@defun window-resize window delta &optional horizontal ignore pixelwise
combination limits of the involved windows; in some cases, it may alter
both edges. @xref{Recombining Windows}. To resize by moving only the
bottom or right edge of a window, use the function
-@code{adjust-window-trailing-edge}, below.
+@code{adjust-window-trailing-edge}.
@end defun
@c The commands enlarge-window, enlarge-window-horizontally,
moves the right edge by @var{delta} columns. If @var{window} is
@code{nil}, it defaults to the selected window.
-If the optional argument @code{pixelwise} is non-@code{nil},
-@var{delta} will be interpreted as pixels.
+If the optional argument @var{pixelwise} is non-@code{nil},
+@var{delta} is interpreted as pixels.
A positive @var{delta} moves the edge downwards or to the right; a
negative @var{delta} moves it upwards or to the left. If the edge
@cindex pixelwise, resizing windows
@defopt window-resize-pixelwise
-If the value of this option is non-@code{nil}, windows are resized in
+If the value of this option is non-@code{nil}, Emacs resizes windows in
units of pixels. This currently affects functions like
@code{split-window} (@pxref{Splitting Windows}), @code{maximize-window},
@code{minimize-window}, @code{fit-window-to-buffer},
@code{shrink-window-if-larger-than-buffer} (all listed below) and
@code{fit-frame-to-buffer} (@pxref{Size and Position}).
-Note that when a frame's pixel size is not a multiple of the frame's
-character size, at least one window may get resized pixelwise even if
-this option is @code{nil}. The default value of this option is
-@code{nil}.
+Note that when a frame's pixel size is not a multiple of its character
+size, at least one window may get resized pixelwise even if this
+option is @code{nil}. The default value is @code{nil}.
@end defopt
The following commands resize windows in more specific ways. When
@defun select-window window &optional norecord
This function makes @var{window} the selected window and the window
selected within its frame (@pxref{Basic Windows}) and selects that
-frame. @var{window} must be a live window. This function also makes
-@var{window}'s buffer (@pxref{Buffers and Windows}) current and sets
-that buffer's value of @code{point} to the value of @code{window-point}
-(@pxref{Window Point}) in @var{window}. The return value is
-@var{window}.
+frame. It also makes @var{window}'s buffer (@pxref{Buffers and
+Windows}) current and sets that buffer's value of @code{point} to the
+value of @code{window-point} (@pxref{Window Point}) in @var{window}.
+@var{window} must be a live window. The return value is @var{window}.
By default, this function also moves @var{window}'s buffer to the front
-of the buffer list (@pxref{The Buffer List}), and makes @var{window} the
+of the buffer list (@pxref{Buffer List}), and makes @var{window} the
most recently selected window. However, if the optional argument
@var{norecord} is non-@code{nil}, these additional actions are omitted.
+
+This function runs @code{buffer-list-update-hook} (@pxref{Buffer List})
+unless @var{norecord} is non-@code{nil}. Note that applications and
+internal routines often temporarily select a window in order to simplify
+coding. As a rule, such selections (including those made by the macros
+@code{save-selected-window} and @code{with-selected-window} below) are
+not recorded thus avoiding to pollute @code{buffer-list-update-hook}.
+Selections that ``really count'' are those causing a visible change in
+the next redisplay of @var{window}'s frame and should be always
+recorded. This also means that to run a function each time a window
+gets selected, putting it on @code{buffer-list-update-hook} should be
+the right choice.
@end defun
@cindex most recently selected windows
return value is the buffer switched to.
If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
-returned by @code{other-buffer} (@pxref{The Buffer List}). If
+returned by @code{other-buffer} (@pxref{Buffer List}). If
@var{buffer-or-name} is a string that is not the name of any existing
buffer, this function creates a new buffer with that name; the new
buffer's major mode is determined by the variable @code{major-mode}
Normally, the specified buffer is put at the front of the buffer
list---both the global buffer list and the selected frame's buffer
-list (@pxref{The Buffer List}). However, this is not done if the
+list (@pxref{Buffer List}). However, this is not done if the
optional argument @var{norecord} is non-@code{nil}.
Sometimes, @code{switch-to-buffer} may be unable to display the buffer
was switched to.
If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
-returned by @code{other-buffer} (@pxref{The Buffer List}). If
+returned by @code{other-buffer} (@pxref{Buffer List}). If
@var{buffer-or-name} is a string that is not the name of any existing
buffer, this function creates a new buffer with that name; the new
buffer's major mode is determined by the variable @code{major-mode}
@item
A number specifies the desired height of the new window. An integer
-number specifies the number of lines of the window. A floating point
+specifies the number of lines of the window. A floating-point
number gives the fraction of the window's height with respect to the
height of the frame's root window.
@item
A number specifies the desired width of the new window. An integer
-number specifies the number of columns of the window. A floating point
+specifies the number of columns of the window. A floating-point
number gives the fraction of the window's width with respect to the
width of the frame's root window.
windows are dedicated to another buffer (@pxref{Dedicated Windows}).
@end defun
+@defun display-buffer-no-window buffer alist
+If @var{alist} has a non-@code{nil} @code{allow-no-window} entry, then
+this function does not display @code{buffer}. This allows to override
+the default action and avoid displaying the buffer. It is assumed that
+when the caller specifies a non-@code{nil} @code{allow-no-window} value
+it can handle a @code{nil} value returned from @code{display-buffer} in
+this case.
+@end defun
+
To illustrate the use of action functions, consider the following
example.
If repeated invocations of this command have already shown all buffers
previously shown in @var{window}, further invocations will show buffers
-from the buffer list of the frame @var{window} appears on (@pxref{The
-Buffer List}), trying to skip buffers that are already shown in another
-window on that frame.
+from the buffer list of the frame @var{window} appears on (@pxref{Buffer
+List}), trying to skip buffers that are already shown in another window
+on that frame.
@end deffn
@deffn Command switch-to-next-buffer &optional window
If there is no recent invocation of @code{switch-to-prev-buffer} that
can be undone, this function tries to show a buffer from the buffer list
-of the frame @var{window} appears on (@pxref{The Buffer List}).
+of the frame @var{window} appears on (@pxref{Buffer List}).
@end deffn
By default @code{switch-to-prev-buffer} and @code{switch-to-next-buffer}
behaves like @code{delete-windows-on} otherwise.
@c FIXME: Does replace-buffer-in-windows _delete_ a window in case (1)?
- When @code{bury-buffer} (@pxref{The Buffer List}) operates on the
+ When @code{bury-buffer} (@pxref{Buffer List}) operates on the
selected window (which shows the buffer that shall be buried), it
handles case (2) by calling @code{frame-auto-hide-function}
(@pxref{Quitting Windows}) to deal with the selected frame. The other
hand, a window has been reused for displaying the buffer, you might
prefer showing the buffer previously shown in that window, by calling the
function @code{switch-to-prev-buffer} (@pxref{Window History}).
-Finally, you might want to either bury (@pxref{The Buffer List}) or kill
+Finally, you might want to either bury (@pxref{Buffer List}) or kill
(@pxref{Killing Buffers}) the window's buffer.
The following command uses information on how the window for
The function specified by this option is called to automatically hide
frames. This function is called with one argument---a frame.
-The function specified here is called by @code{bury-buffer} (@pxref{The
-Buffer List}) when the selected window is dedicated and shows the buffer
-to bury. It is also called by @code{quit-restore-window} (see above)
-when the frame of the window to quit has been specially created for
-displaying that window's buffer and the buffer is not killed.
+The function specified here is called by @code{bury-buffer}
+(@pxref{Buffer List}) when the selected window is dedicated and shows
+the buffer to bury. It is also called by @code{quit-restore-window}
+(see above) when the frame of the window to quit has been specially
+created for displaying that window's buffer and the buffer is not
+killed.
The default is to call @code{iconify-frame} (@pxref{Visibility of
Frames}). Alternatively, you may specify either @code{delete-frame}
right of the rightmost column, and the Y coordinate one row down from
the bottommost row.
-Note that these are the actual outer edges of the window, including
-any header line, mode line, scroll bar, fringes, and display margins.
-On a text terminal, if the window has a neighbor on its right, its
-right edge includes the separator line between the window and its
+Note that these are the actual outer edges of the window, including any
+header line, mode line, scroll bar, fringes, window divider and display
+margins. On a text terminal, if the window has a neighbor on its right,
+its right edge includes the separator line between the window and its
neighbor.
@end defun
@defun window-inside-edges &optional window
This function is similar to @code{window-edges}, but the returned edge
values are for the text area of the window. They exclude any header
-line, mode line, scroll bar, fringes, display margins, and vertical
-separator.
+line, mode line, scroll bar, fringes, window divider, display margins,
+and vertical separator.
@end defun
@defun window-top-line &optional window
@item header-line
The coordinates are in the header line of @var{window}.
+@item right-divider
+The coordinates are in the divider separating @var{window} from a
+window on the right.
+
+@item right-divider
+The coordinates are in the divider separating @var{window} from a
+window beneath.
+
@item vertical-line
The coordinates are in the vertical line between @var{window} and its
neighbor to the right. This value occurs only if the window doesn't
the display screen. @var{window} must specify a live window.
@end defun
+@defun window-pixel-left &optional window
+This function returns the left pixel edge of window @var{window}.
+@var{window} must be a valid window and defaults to the selected one.
+@end defun
+
+@defun window-pixel-top &optional window
+This function returns the top pixel edge of window @var{window}.
+@var{window} must be a valid window and defaults to the selected one.
+@end defun
+
+
@node Window Configurations
@section Window Configurations
@cindex window configurations
A @dfn{window configuration} records the entire layout of one
frame---all windows, their sizes, which buffers they contain, how those
-buffers are scrolled, and their values of point and the mark; also their
+buffers are scrolled, and their value of point; also their
fringes, margins, and scroll bar settings. It also includes the value
of @code{minibuffer-scroll-window}. As a special exception, the window
configuration does not record the value of point in the selected window
@defun compare-window-configurations config1 config2
This function compares two window configurations as regards the
-structure of windows, but ignores the values of point and mark and the
+structure of windows, but ignores the values of point and the
saved scrolling positions---it can return @code{t} even if those
aspects differ.
The function @code{equal} can also compare two window configurations; it
regards configurations as unequal if they differ in any respect, even a
-saved point or mark.
+saved point.
@end defun
@defun window-configuration-frame config