Github/emacs
2
0
Fork 1
mirror of git://git.sv.gnu.org/emacs.git synced 2026-02-24 13:57:36 +00:00
Code Issues Projects Releases Packages Wiki Activity

Clarify "text area of a window" in the documentation

Browse source 
* src/keyboard.c (Fposn_at_x_y): Clarify that the Y coordinate
includes the header-line and the tab-line.  (Bug#51590)

* doc/lispref/windows.texi (Window Sizes, Splitting Windows)
(Textual Scrolling, Coordinates and Windows): Fix/remove improper
or confusing uses of "text area" of a window.
This commit is contained in:
Eli Zaretskii 2021-11-06 08:59:09 +02:00
parent 4e7e78d578
commit c2e3cd6694
2 changed files with 30 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

54
doc/lispref/windows.texi
View file

@ -131,8 +131,8 @@ including for the case where @var{object} is a deleted window.
|______________ Header Line ______________| | | |______________ Header Line ______________| | |
^ |LS|LM|LF| |RF|RM|RS| | | ^ |LS|LM|LF| |RF|RM|RS| | |
| | | | | | | | | | | | | | | | | | | | | |
Window | | | | Text Area | | | | | Window Window | | | | | | | | | Window
Body | | | | | (Window Body) | | | | | Total Body | | | | | Window Body | | | | | Total
Height | | | | | | | | | Height Height | | | | | | | | | Height
| | | | |<- Window Body Width ->| | | | | | | | | | |<- Window Body Width ->| | | | | |
v |__|__|__|_______________________|__|__|__| | | v |__|__|__|_______________________|__|__|__| | |
@ -145,27 +145,29 @@ Height | | | | | | | | | Height
@end smallexample @end smallexample
@cindex window body @cindex window body
@cindex text area of a window
@cindex body of a window @cindex body of a window
@cindex window decorations @cindex window decorations
@cindex left and right window decorations @cindex left and right window decorations
@cindex top and bottom window decorations @cindex top and bottom window decorations
At the center of that window is the @dfn{text area}, or @dfn{body}, At the center of that window is the @dfn{body}, where the buffer
where the buffer text is displayed. The text area can be surrounded by text is displayed. The body can be surrounded by a series of optional
a series of optional areas which we will call @dfn{window decorations}. areas which we will call @dfn{window decorations}. On the left and
On the left and right, from innermost to outermost, these are the left right, from innermost to outermost, these are the left and right
and right fringes, denoted by LF and RF (@pxref{Fringes}); the left and fringes, denoted by LF and RF (@pxref{Fringes}); the left and right
right margins, denoted by LM and RM in the schematic (@pxref{Display margins, denoted by LM and RM in the schematic (@pxref{Display
Margins}); the left or right vertical scroll bar, only one of which is 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 present at any time, denoted by LS and RS (@pxref{Scroll Bars}); and
right divider, denoted by RD (@pxref{Window Dividers}). Together these the right divider, denoted by RD (@pxref{Window Dividers}). Together
are the window's @dfn{left and right decorations}. these are the window's @dfn{left and right decorations}.
@cindex text area of a window
At the top of the window are the tab line and the header line At the top of the window are the tab line and the header line
(@pxref{Header Lines}). At the bottom of the window are the horizontal (@pxref{Header Lines}). The @dfn{text area} of the window includes
scroll bar (@pxref{Scroll Bars}); the mode line (@pxref{Mode Line the header line and the tab line, if they are present in the window.
Format}); and the bottom divider (@pxref{Window Dividers}). Together At the bottom of the window are the horizontal scroll bar
these form the window's @dfn{top and bottom decorations}. (@pxref{Scroll Bars}); the mode line (@pxref{Mode Line Format}); and
the bottom divider (@pxref{Window Dividers}). Together these form the
window's @dfn{top and bottom decorations}.
There are two special areas omitted in the schematic: There are two special areas omitted in the schematic:
@ -818,7 +820,7 @@ that of the root window on that frame. If @var{window} is omitted or
@cindex window body height @cindex window body height
@cindex body height of a window @cindex body height of a window
The @dfn{body height} of a window is the height of its text area, which The @dfn{body height} of a window is the height of its body, which
does not include any of its top or bottom decorations (@pxref{Basic does not include any of its top or bottom decorations (@pxref{Basic
Windows}). Windows}).
@ -839,9 +841,9 @@ exceed its total height as returned by @code{window-total-height}.
@cindex window body width @cindex window body width
@cindex body width of a window @cindex body width of a window
The @dfn{body width} of a window is the width of its text area, which The @dfn{body width} of a window is the width of its body and of the
does not include any of its left or right decorations (@pxref{Basic text area, which does not include any of its left or right decorations
Windows}). (@pxref{Basic Windows}).
Note that when one or both fringes are removed (by setting their width Note that when one or both fringes are removed (by setting their width
to zero), the display engine reserves two character cells, one on each to zero), the display engine reserves two character cells, one on each
@ -1014,8 +1016,8 @@ Normally, the variables @code{window-min-height} and
is non-@code{nil}, this function ignores @code{window-min-height} and is non-@code{nil}, this function ignores @code{window-min-height} and
@code{window-min-width}, as well as @code{window-size-fixed}. Instead, @code{window-min-width}, as well as @code{window-size-fixed}. Instead,
it considers the minimum height of a window as the sum of its top and it considers the minimum height of a window as the sum of its top and
bottom decorations plus a text area of one line; and its minimum width bottom decorations plus the text of one line; and its minimum width
as the sum of its left and right decorations plus a text area of two as the sum of its left and right decorations plus text that takes two
columns. columns.
If the optional argument @var{pixelwise} is non-@code{nil}, If the optional argument @var{pixelwise} is non-@code{nil},
@ -1355,7 +1357,7 @@ Sizes}). Thus, it signals an error if splitting would result in making
a window smaller than those variables specify. However, a a window smaller than those variables specify. However, a
non-@code{nil} value for @var{size} causes those variables to be non-@code{nil} value for @var{size} causes those variables to be
ignored; in that case, the smallest allowable window is considered 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 one that has space for a text that is one line tall and/or two columns
wide. wide.
Hence, if @var{size} is specified, it's the caller's responsibility to Hence, if @var{size} is specified, it's the caller's responsibility to
@ -5157,7 +5159,7 @@ window.
If @var{count} is negative, it scrolls backward instead. If If @var{count} is negative, it scrolls backward instead. If
@var{count} is @code{nil} (or omitted), the distance scrolled is @var{count} is @code{nil} (or omitted), the distance scrolled is
@code{next-screen-context-lines} lines less than the height of the @code{next-screen-context-lines} lines less than the height of the
window's text area. window's body.
If the selected window cannot be scrolled any further, this function If the selected window cannot be scrolled any further, this function
signals an error. Otherwise, it returns @code{nil}. signals an error. Otherwise, it returns @code{nil}.
@ -5657,8 +5659,8 @@ and its neighbor.
If the optional argument @var{body} is @code{nil}, this means to If the optional argument @var{body} is @code{nil}, this means to
return the edges corresponding to the total size of @var{window}. return the edges corresponding to the total size of @var{window}.
@var{body} non-@code{nil} means to return the edges of @var{window}'s @var{body} non-@code{nil} means to return the edges of @var{window}'s
body (aka text area). If @var{body} is non-@code{nil}, @var{window} body. If @var{body} is non-@code{nil}, @var{window} must specify a
must specify a live window. live window.
If the optional argument @var{absolute} is @code{nil}, this means to If the optional argument @var{absolute} is @code{nil}, this means to
return edges relative to the native position of @var{window}'s frame. return edges relative to the native position of @var{window}'s frame.

2
src/keyboard.c
View file

@ -11348,6 +11348,8 @@ The elements of this list correspond to the arguments of
DEFUN ("posn-at-x-y", Fposn_at_x_y, Sposn_at_x_y, 2, 4, 0, DEFUN ("posn-at-x-y", Fposn_at_x_y, Sposn_at_x_y, 2, 4, 0,
doc: /* Return position information for pixel coordinates X and Y. doc: /* Return position information for pixel coordinates X and Y.
By default, X and Y are relative to text area of the selected window. By default, X and Y are relative to text area of the selected window.
Note that the text area includes the header-line and the tab-line of
the window, if any of them are present.
Optional third arg FRAME-OR-WINDOW non-nil specifies frame or window. Optional third arg FRAME-OR-WINDOW non-nil specifies frame or window.
If optional fourth arg WHOLE is non-nil, X is relative to the left If optional fourth arg WHOLE is non-nil, X is relative to the left
edge of the window. edge of the window.