[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master 10d371e: Document pixel-fill-region
From: |
Lars Ingebrigtsen |
Subject: |
master 10d371e: Document pixel-fill-region |
Date: |
Tue, 30 Nov 2021 10:46:34 -0500 (EST) |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- master 10d371e: Document pixel-fill-region,
Lars Ingebrigtsen <=