procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation of 'window-text-pixel-size'

Browse source 
* doc/lispref/display.texi (Size of Displayed Text): Clarify the
description of 'window-text-pixel-size'.
This commit is contained in:
Eli Zaretskii 2020-06-06 20:10:37 +03:00
parent fbd49f969e
commit dd366b5d3b
1 changed files with 31 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

53
doc/lispref/display.texi
View file

@ -2023,36 +2023,45 @@ it contains.
@defun window-text-pixel-size &optional window from to x-limit y-limit mode-and-header-line @defun window-text-pixel-size &optional window from to x-limit y-limit mode-and-header-line
This function returns the size of the text of @var{window}'s buffer in This function returns the size of the text of @var{window}'s buffer in
pixels. @var{window} must be a live window and defaults to the selected pixels. @var{window} must be a live window and defaults to the
one. The return value is a cons of the maximum pixel-width of any text selected one. The return value is a cons of the maximum pixel-width
line and the maximum pixel-height of all text lines. of any text line and the maximum pixel-height of all text lines. This
function exists to allow Lisp programs to adjust the dimensions of
@var{window} to the buffer text it needs to display.
The optional argument @var{from}, if non-@code{nil}, specifies the first The optional argument @var{from}, if non-@code{nil}, specifies the
text position to consider and defaults to the minimum accessible first text position to consider, and defaults to the minimum
position of the buffer. If @var{from} is @code{t}, it uses the minimum accessible position of the buffer. If @var{from} is @code{t}, it
accessible position that is not a newline character. The optional stands for the minimum accessible position that is not a newline
argument @var{to}, if non-@code{nil}, specifies the last text position character. The optional argument @var{to}, if non-@code{nil},
to consider and defaults to the maximum accessible position of the specifies the last text position to consider, and defaults to the
buffer. If @var{to} is @code{t}, it uses the maximum accessible maximum accessible position of the buffer. If @var{to} is @code{t},
position that is not a newline character. it stands for the maximum accessible position that is not a newline
character.
The optional argument @var{x-limit}, if non-@code{nil}, specifies the The optional argument @var{x-limit}, if non-@code{nil}, specifies the
maximum pixel-width that can be returned. @var{x-limit} @code{nil} or maximum X coordinate beyond which text should be ignored; it is
omitted, means to use the pixel-width of @var{window}'s body therefore also the largest value of pixel-width that the function can
(@pxref{Window Sizes}); this is useful when the caller does not intend return. If @var{x-limit} @code{nil} or omitted, it means to use the
to change the width of @var{window}. Otherwise, the caller should pixel-width of @var{window}'s body (@pxref{Window Sizes}); this
specify here the maximum width @var{window}'s body may assume. Text default means that text of truncated lines wider than the window will
whose x-coordinate is beyond @var{x-limit} is ignored. Since be ignored. This default is useful when the caller does not intend to
change the width of @var{window}. Otherwise, the caller should
specify here the maximum width @var{window}'s body may assume; in
particular, if truncated lines are expected and their text needs to be
accounted for, @var{x-limit} should be set to a large value. Since
calculating the width of long lines can take some time, it's always a calculating the width of long lines can take some time, it's always a
good idea to make this argument as small as needed; in particular, if good idea to make this argument as small as needed; in particular, if
the buffer might contain long lines that will be truncated anyway. the buffer might contain long lines that will be truncated anyway.
The optional argument @var{y-limit}, if non-@code{nil}, specifies the The optional argument @var{y-limit}, if non-@code{nil}, specifies the
maximum pixel-height that can be returned. Text lines whose maximum Y coordinate beyond which text is to be ignored; it is
y-coordinate is beyond @var{y-limit} are ignored. Since calculating the therefore also the maximum pixel-height that the function can return.
pixel-height of a large buffer can take some time, it makes sense to If @var{y-limit} is nil or omitted, it means to considers all the
specify this argument; in particular, if the caller does not know the lines of text till the buffer position specified by @var{to}. Since
size of the buffer. calculating the pixel-height of a large buffer can take some time, it
makes sense to specify this argument; in particular, if the caller
does not know the size of the buffer.
The optional argument @var{mode-and-header-line} @code{nil} or omitted The optional argument @var{mode-and-header-line} @code{nil} or omitted
means to not include the height of the mode- or header-line of means to not include the height of the mode- or header-line of