Document pixel-fill-region

* doc/lispref/text.texi (Filling): Document pixel-fill-region.

* lisp/textmodes/pixel-fill.el (pixel-fill-width): Add new helper
function.

3 files changed, 57 insertions, 0 deletions

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 25579e79eae..ff42ceaf9c6 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -1651,6 +1651,39 @@ The variable @code{paragraph-separate} controls how to distinguish
 paragraphs.  @xref{Standard Regexps}.
 @end deffn
 
+@defun pixel-fill-region start end pixel-width
+Most Emacs buffers use monospaced text, so all the filling functions
+(like @code{fill-region}) work based on the number of characters and
+@code{char-width}.  However, Emacs can render other types of things,
+like text that contains images and using proportional fonts, and the
+@code{pixel-fill-region} exists to handle that.  For instance, this
+Lisp snippet will insert text using a proportional font, and then fill
+this to be no wider than 300 pixels:
+
+@lisp
+(insert (propertize
+	 "This is a sentence that's ends here."
+	 'face 'variable-pitch))
+(pixel-fill-region (point) (point-max) 300)
+@end lisp
+
+If @var{start} isn't at the start of a line, that pixel position will
+be used as the indentation prefix on subsequent lines.
+
+The @code{pixel-fill-width} helper function can be used to compute the
+pixel width to use.  If given no arguments, it'll return a value
+slightly less than the width of the current window.  The first
+optional value, @var{columns}, specifies the number of columns using
+the standard, monospaced fonts, e.g. @code{fill-column}.  The second
+optional value is the window to use.  You'd typically use it like
+this:
+
+@lisp
+(pixel-fill-region
+  start end (pixel-fill-width fill-column))
+@end lisp
+@end defun
+
 @deffn Command fill-individual-paragraphs start end &optional justify citation-regexp
 This command fills each paragraph in the region according to its
 individual fill prefix.  Thus, if the lines of a paragraph were indented
diff --git a/etc/NEWS b/etc/NEWS
index dba5ed92475..52686479ce2 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -306,8 +306,10 @@ For instance, to enable jumping to the *Messages* buffer with
 
 ** pixel-fill
 
++++
 *** This is a new package that deals with filling variable-pitch text.
 
++++
 *** New function 'pixel-fill-region'.
 This fills the region to be no wider than a specified pixel width.
 
diff --git a/lisp/textmodes/pixel-fill.el b/lisp/textmodes/pixel-fill.el
index eff09dfca65..a66f07e1a99 100644
--- a/lisp/textmodes/pixel-fill.el
+++ b/lisp/textmodes/pixel-fill.el
@@ -43,6 +43,28 @@ of a line or the end of a line."
   :type 'boolean
   :version "29.1")
 
+(defun pixel-fill-width (&optional columns window)
+  "Return the pixel width corresponding to COLUMNS in WINDOW.
+If COLUMNS in nil, use the enture window width.
+
+If WINDOW is nil, this defaults to the current window."
+  (unless window
+    (setq window (selected-window)))
+  (let ((frame (window-frame window)))
+    (if columns
+        (* (frame-char-width frame) columns)
+      (- (window-body-width nil t)
+         (* 2 (frame-char-width frame))
+         ;; We need to adjust the available width for when the user
+         ;; disables the fringes, which will cause the display
+         ;; engine usurp one column for the continuation glyph.
+         (if (and (fboundp 'fringe-columns)
+                  (or (not (zerop (fringe-columns 'right)))
+                      (not (zerop (fringe-columns 'left)))))
+             0
+           (* (frame-char-width frame) 2))
+         1))))
+
 (defun pixel-fill-region (start end pixel-width)
   "Fill the region between START and END.
 This will attempt to reformat the text in the region to have no