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

Clarify the semantics of 'string-pixel-width'

Browse source 
* doc/lispref/display.texi (Size of Displayed Text):
* lisp/emacs-lisp/subr-x.el (string-pixel-width):
* src/xdisp.c (Fwindow_text_pixel_size, Fbuffer_text_pixel_size):
Doc fixes.  (Bug#73129)
This commit is contained in:
Eli Zaretskii 2024-09-09 14:28:12 +03:00
parent 9f0603207b
commit 03e5698167
3 changed files with 13 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
doc/lispref/display.texi
View file

@ -2238,7 +2238,7 @@ displayed in a given window. This function is used by
it contains. it contains.
@defun window-text-pixel-size &optional window from to x-limit y-limit mode-lines ignore-line-at-end @defun window-text-pixel-size &optional window from to x-limit y-limit mode-lines ignore-line-at-end
This function returns the size of the text of @var{window}'s buffer in This function returns the dimensions of the text of @var{window}'s buffer in
pixels. @var{window} must be a live window and defaults to the pixels. @var{window} must be a live window and defaults to the
selected one. The return value is a cons of the maximum pixel-width selected one. The return value is a cons of the maximum pixel-width
of any text line and the maximum pixel-height of all text lines. This of any text line and the maximum pixel-height of all text lines. This
@ -2387,7 +2387,11 @@ meaning as with @code{window-text-pixel-size}.
@defun string-pixel-width string @defun string-pixel-width string
This is a convenience function that uses @code{window-text-pixel-size} This is a convenience function that uses @code{window-text-pixel-size}
to compute the width of @var{string} (in pixels). to compute the width of @var{string} (in pixels). Caveat: if you call
this function to measure the width of a string with embedded newlines,
it will then return the width of the widest substring that does not
include newlines. The meaning of this result is the widest line taken
by the string if inserted into a buffer.
@end defun @end defun
@defun line-pixel-height @defun line-pixel-height

6
lisp/emacs-lisp/subr-x.el
View file

@ -338,7 +338,11 @@ This construct can only be used with lexical binding."
;;;###autoload ;;;###autoload
(defun string-pixel-width (string) (defun string-pixel-width (string)
"Return the width of STRING in pixels." "Return the width of STRING in pixels.
If you call this function to measure pixel width of a string
with embedded newlines, it returns the width of the widest
substring that does not include newlines."
(declare (important-return-value t)) (declare (important-return-value t))
(if (zerop (length string)) (if (zerop (length string))
0 0

4
src/xdisp.c
View file

@ -11774,7 +11774,7 @@ window_text_pixel_size (Lisp_Object window, Lisp_Object from, Lisp_Object to,
} }
DEFUN ("window-text-pixel-size", Fwindow_text_pixel_size, Swindow_text_pixel_size, 0, 7, 0, DEFUN ("window-text-pixel-size", Fwindow_text_pixel_size, Swindow_text_pixel_size, 0, 7, 0,
doc: /* Return the size of the text of WINDOW's buffer in pixels. doc: /* Return the dimensions of the text of WINDOW's buffer in pixels.
WINDOW must be a live window and defaults to the selected one. The WINDOW must be a live window and defaults to the selected one. The
return value is a cons of the maximum pixel-width of any text line and return value is a cons of the maximum pixel-width of any text line and
the pixel-height of all the text lines in the accessible portion of the pixel-height of all the text lines in the accessible portion of
@ -11854,7 +11854,7 @@ screen line that includes TO to the returned height of the text. */)
} }
DEFUN ("buffer-text-pixel-size", Fbuffer_text_pixel_size, Sbuffer_text_pixel_size, 0, 4, 0, DEFUN ("buffer-text-pixel-size", Fbuffer_text_pixel_size, Sbuffer_text_pixel_size, 0, 4, 0,
doc: /* Return size of whole text of BUFFER-OR-NAME in WINDOW. doc: /* Return the dimensions of whole text of BUFFER-OR-NAME in WINDOW.
BUFFER-OR-NAME must specify a live buffer or the name of a live buffer BUFFER-OR-NAME must specify a live buffer or the name of a live buffer
and defaults to the current buffer. WINDOW must be a live window and and defaults to the current buffer. WINDOW must be a live window and
defaults to the selected one. The return value is a cons of the maximum defaults to the selected one. The return value is a cons of the maximum