Github/emacs
2
0
Fork 1
mirror of git://git.sv.gnu.org/emacs.git synced 2026-06-14 12:31:25 +00:00
Code Issues Projects Releases Packages Wiki Activity

; Fix documentation of window-dimension functions

Browse source 
* doc/lispref/windows.texi (Window Sizes):
* src/window.c (Fwindow_body_height, Fwindow_total_height)
(Fwindow_total_width, Fwindow_body_width): Clarify that window
dimensions are returned in canonical columns and lines.
(Bug#80620)
This commit is contained in:
Eli Zaretskii 2026-03-19 17:40:31 +02:00
parent 5c961f4903
commit ee42c392d2
2 changed files with 61 additions and 61 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

74
doc/lispref/windows.texi
View file

@ -704,10 +704,10 @@ in the group).
Emacs provides miscellaneous functions for finding the height and width
of a window. The return value of many of these functions can be
specified either in units of pixels or in units of lines and columns.
On a graphical display, the latter actually correspond to the height and
width of a default character specified by the frame's default font as
returned by @code{frame-char-height} and @code{frame-char-width}
specified either in units of pixels or in units of canonical lines and
columns. On a graphical display, the latter actually correspond to the
height and width of a default character specified by the frame's default
font as returned by @code{frame-char-height} and @code{frame-char-width}
(@pxref{Frame Font}). Thus, if a window is displaying text with a
different font or size, the reported line height and column width for
that window may differ from the actual number of text lines or columns
@ -720,10 +720,10 @@ displayed within it.
its body and its top and bottom decorations (@pxref{Basic Windows}).
@defun window-total-height &optional window round
This function returns the total height, in lines, of the window
@var{window}. If @var{window} is omitted or @code{nil}, it defaults to
the selected window. If @var{window} is an internal window, the return
value is the total height occupied by its descendant windows.
This function returns the total height, in canonical lines, of the
window @var{window}. If @var{window} is omitted or @code{nil}, it
defaults to the selected window. If @var{window} is an internal window,
the return value is the total height occupied by its descendant windows.
If a window's pixel height is not an integral multiple of its frame's
default character height, the number of lines occupied by the window is
@ -736,9 +736,9 @@ vertically combined and has a next sibling, the topmost row of that
sibling can be calculated as the sum of this window's topmost row and
total height (@pxref{Coordinates and Windows})
If the optional argument @var{round} is @code{ceiling}, this
function returns the smallest integer larger than @var{window}'s pixel
height divided by the character height of its frame; if it is
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 canonical 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.
@ -751,19 +751,19 @@ The @dfn{total width} of a window is the number of columns comprising its
body and its left and right decorations (@pxref{Basic Windows}).
@defun window-total-width &optional window round
This function returns the total width, in columns, of the window
@var{window}. If @var{window} is omitted or @code{nil}, it defaults to
the selected window. If @var{window} is internal, the return value is
the total width occupied by its descendant windows.
This function returns the total width, in canonical columns, of the
window @var{window}. If @var{window} is omitted or @code{nil}, it
defaults to the selected window. If @var{window} is internal, the
return value is the total width occupied by its descendant windows.
If a window's pixel width is not an integral multiple of its frame's
character width, the number of columns occupied by the window is rounded
internally. This is done in a way such that, if the window is a parent
window, the sum of the total widths of all its children internally
equals the total width of their parent. This means that although two
windows have the same pixel width, their internal total widths may
differ by one column. This means also, that if this window is
horizontally combined and has a next sibling, the leftmost column of
canonical character width, the number of columns occupied by the window
is rounded internally. This is done in a way such that, if the window
is a parent window, the sum of the total widths of all its children
internally equals the total width of their parent. This means that
although two windows have the same pixel width, their internal total
widths may differ by one column. This means also, that if this window
is horizontally combined and has a next sibling, the leftmost column of
that sibling can be calculated as the sum of this window's leftmost
column and total width (@pxref{Coordinates and Windows}). The optional
argument @var{round} behaves as it does for @code{window-total-height}.
@ -835,17 +835,17 @@ does not include any of its top or bottom decorations (@pxref{Basic
Windows}).
@defun window-body-height &optional window pixelwise
This function returns the height, in lines, of the body of window
@var{window}. If @var{window} is omitted or @code{nil}, it defaults to
the selected window; otherwise it must be a live window.
This function returns the height, in canonical lines, of the body of
window @var{window}. If @var{window} is omitted or @code{nil}, it
defaults to the selected window; otherwise it must be a live window.
The optional argument @var{pixelwise} defines the units to use for the
height. If @code{nil}, return the body height of @var{window} in
characters, rounded down to the nearest integer, if necessary. This
means that if a line at the bottom of the text area is only partially
visible, that line is not counted. It also means that the height of a
window's body can never exceed its total height as returned by
@code{window-total-height}.
canonical characters, rounded down to the nearest integer, if necessary.
This means that if a line at the bottom of the text area is only
partially visible, that line is not counted. It also means that the
height of a window's body can never exceed its total height as returned
by @code{window-total-height}.
If @var{pixelwise} is @code{remap} and the default face is remapped
(@pxref{Face Remapping}), use the remapped face to determine the
@ -867,16 +867,16 @@ glyphs, which leaves 2 columns less for text display. (The function
peculiarity into account.)
@defun window-body-width &optional window pixelwise
This function returns the width, in columns, of the body of window
@var{window}. If @var{window} is omitted or @code{nil}, it defaults to
the selected window; otherwise it must be a live window.
This function returns the width, in canonical columns, of the body of
window @var{window}. If @var{window} is omitted or @code{nil}, it
defaults to the selected window; otherwise it must be a live window.
The optional argument @var{pixelwise} defines the units to use for the
width. If @code{nil}, return the body width of @var{window} in
characters, rounded down to the nearest integer, if necessary. This
means that if a column on the right of the text area is only partially
visible, that column is not counted. It also means that the width of
a window's body can never exceed its total width as returned by
canonical characters, rounded down to the nearest integer, if necessary.
This means that if a column on the right of the text area is only
partially visible, that column is not counted. It also means that the
width of a window's body can never exceed its total width as returned by
@code{window-total-width}.
If @var{pixelwise} is @code{remap} and the default face is remapped

48
src/window.c
View file

@ -859,7 +859,7 @@ zero if WINDOW was created after that. */)
}
DEFUN ("window-total-height", Fwindow_total_height, Swindow_total_height, 0, 2, 0,
doc: /* Return the height of window WINDOW in lines.
doc: /* Return the height of window WINDOW in canonical lines.
WINDOW must be a valid window and defaults to the selected one.
The return value includes the heights of WINDOW's mode and header line
@ -867,17 +867,17 @@ and its bottom divider, if any. If WINDOW is an internal window, the
total height is the height of the screen areas spanned by its children.
If WINDOW's pixel height is not an integral multiple of its frame's
character height, the number of lines occupied by WINDOW is rounded
internally. This is done in a way such that, if WINDOW is a parent
window, the sum of the total heights of all its children internally
equals the total height of WINDOW.
canonical character height, the number of lines occupied by WINDOW is
rounded internally. This is done in a way such that, if WINDOW is a
parent window, the sum of the total heights of all its children
internally equals the total height of WINDOW.
If the optional argument ROUND is `ceiling', return the smallest integer
larger than WINDOW's pixel height divided by the character height of
WINDOW's frame. ROUND `floor' means to return the largest integer
smaller than WINDOW's pixel height divided by the character height of
WINDOW's frame. Any other value of ROUND means to return the internal
total height of WINDOW. */)
larger than WINDOW's pixel height divided by the canonical character
height of WINDOW's frame. ROUND `floor' means to return the largest
integer smaller than WINDOW's pixel height divided by the canonical
character height of WINDOW's frame. Any other value of ROUND means to
return the internal total height of WINDOW. */)
(Lisp_Object window, Lisp_Object round)
{
struct window *w = decode_valid_window (window);
@ -895,7 +895,7 @@ total height of WINDOW. */)
}
DEFUN ("window-total-width", Fwindow_total_width, Swindow_total_width, 0, 2, 0,
doc: /* Return the total width of window WINDOW in columns.
doc: /* Return the total width of window WINDOW in canonical columns.
WINDOW must be a valid window and defaults to the selected one.
The return value includes the widths of WINDOW's fringes, margins,
@ -904,17 +904,17 @@ window, the total width is the width of the screen areas spanned by its
children.
If WINDOW's pixel width is not an integral multiple of its frame's
character width, the number of lines occupied by WINDOW is rounded
internally. This is done in a way such that, if WINDOW is a parent
window, the sum of the total widths of all its children internally
equals the total width of WINDOW.
canonical character width, the number of lines occupied by WINDOW is
rounded internally. This is done in a way such that, if WINDOW is a
parent window, the sum of the total widths of all its children
internally equals the total width of WINDOW.
If the optional argument ROUND is `ceiling', return the smallest integer
larger than WINDOW's pixel width divided by the character width of
WINDOW's frame. ROUND `floor' means to return the largest integer
smaller than WINDOW's pixel width divided by the character width of
WINDOW's frame. Any other value of ROUND means to return the internal
total width of WINDOW. */)
larger than WINDOW's pixel width divided by the canonical character
width of WINDOW's frame. ROUND `floor' means to return the largest
integer smaller than WINDOW's pixel width divided by the canonical
character width of WINDOW's frame. Any other value of ROUND means to
return the internal total width of WINDOW. */)
(Lisp_Object window, Lisp_Object round)
{
struct window *w = decode_valid_window (window);
@ -1145,8 +1145,8 @@ marginal areas, or scroll bars.
The optional argument PIXELWISE defines the units to use for the
width. If nil, return the largest integer smaller than WINDOW's pixel
width in units of the character width of WINDOW's frame. If PIXELWISE
is `remap' and the default face is remapped (see
width in units of the canonical character width of WINDOW's frame.
If PIXELWISE is `remap' and the default face is remapped (see
`face-remapping-alist'), use the remapped face to determine the
character width. For any other non-nil value, return the width in
pixels.
@ -1170,8 +1170,8 @@ horizontal divider.
The optional argument PIXELWISE defines the units to use for the
height. If nil, return the largest integer smaller than WINDOW's
pixel height in units of the character height of WINDOW's frame. If
PIXELWISE is `remap' and the default face is remapped (see
pixel height in units of the canonical character height of WINDOW's
frame. If PIXELWISE is `remap' and the default face is remapped (see
`face-remapping-alist'), use the remapped face to determine the
character height. For any other non-nil value, return the height in
pixels. */)