master 10d371e: Document pixel-fill-region

[Lars Ingebrigtsen]

branch: master
commit 10d371e4fa0aa5f18f006f6698052ba18c1f5987
Author: Lars Ingebrigtsen <larsi@gnus.org>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    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.
---
 doc/lispref/text.texi        | 33 +++++++++++++++++++++++++++++++++
 etc/NEWS                     |  2 ++
 lisp/textmodes/pixel-fill.el | 22 ++++++++++++++++++++++
 3 files changed, 57 insertions(+)

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 25579e7..ff42cea 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 dba5ed9..5268647 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 eff09df..a66f07e 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