TextWriter¶
(New in v1.16.18) This class represents a MuPDF text object. It can be thought of as a store of text spans – each span having its own position, font and font size. It is an elegant alternative for writing text to PDF pages, when compared with methods Page.insertText()
and friends:
Improved text positioning: The position of the last inserted character is returned, as well as the combined rectangle of text stored so far.
Automatic fallback fonts: If a character is not represented by the chosen font, alternative fonts are automatically checked. This significantly reduces the risk of seeing unprintable symbols in the output, so-called “TOFUs”. PyMuPDF now also comes with a “universal” font, which supports all Latin characters (incuding Cyrillic and Greek), and all CJK characters (Chinese, Japanese, Korean).
Reusability: A TextWriter exists independent from any page. The same text can be written multiple times, to the same or other pages, same or different PDFs, choosing different colors or transparency.
Transparency support: Parameter opacity is supported. This offers a handy way to write watermark-style text.
Justified text: Supported for any font – not just simple fonts as in
Page.insertText()
.
Using this object entails three steps:
When created, a TextWriter object requires a fixed page rectangle in relation to which it calculates text positions. Pages with different dimensions cannot use this TextWriter object.
Store text in the TextWriter using method either
TextWriter.append()
orTextWriter.fillTextbox()
.Output the stored text on any PDF page with the same rectangle. This is the only point, where pages are referenced.
TextWriters do not support text rotation. But the new method Page.writeText()
is able to combine one or more TextWriters and jointly write them to any rectangle and with any rotation angle – much like Page.showPDFpage()
.
Class API
-
class
TextWriter
¶ -
__init__
(self, rect, opacity=1, color=None)¶ - Parameters
rect (rect-like) – rectangle internally used for text positioning computations.
opacity (float) – sets the transparency for the text to store here. Values outside the interval
[0, 1)
will be ignored. A value of e.g. 0.5 means 50% transparency.color (float,sequ) – the color of the text. All colors are specified as floats 0 <= color <= 1. A single float represents some gray level, a sequence implies the colorspace via its length.
-
append
(pos, text, font=None, fontsize=11, language=None)¶ Add new text, usually (but not necessarily) representing a text span.
- Parameters
pos (point_like) – start position of the text, the bottom left point of the first character.
text (str) – a string (Python 2: unicode is mandatory!) of arbitrary length. It will be written starting at position “pos”.
font – a Font. If omitted,
fitz.Font("helv")
will be used.fontsize (float) – the fontsize, a positive number, default 11.
language (str) – the language to use, e.g. “en” for English. Meaningful values should be compliant with the ISO 639 standards 1, 2, 3 or 5. Reserved for future use: currently has no effect as far as we know.
- Returns
-
fillTextbox
(rect, text, font="helv", fontsize=11, align=0, warn=True)¶ Fill a given rectangle with text. This is a convenience method to use instead of
append()
(which is internally invoked).- Parameters
rect (rect_like) – the area to fill. No part of the text will appear outside of this.
text (str,sequ) – the text. Can be specified as a (UTF-8) string or a list / tuple of strings. A string will first be converted to a list using splitlines(). Every list item will begin on a new line (forced line breaks).
font – the Font
fontsize (float) – the fontsize.
align (int) – text alignment. Use one of TEXT_ALIGN_LEFT, TEXT_ALIGN_CENTER, TEXT_ALIGN_RIGHT or TEXT_ALIGN_JUSTIFY.
warn (bool) – print a warning if the area is too small, or raise an exception.
-
writeText
(page, opacity=None, color=None, overlay=True)¶ Write the accumulated text to the page.
- Parameters
page – write to this Page.
opacity (float) – overwrite the value of the TextWriter for this output.
color (sequ) – overwrite the value of the TextWriter for this output.
overlay (bool) – put in foreground (default) or background.
-
textRect
¶ The area currently occupied. This value changes when more text is added.
-
lastPoint
¶ The “cursor position” after the last written character.
-
opacity
¶ The text opacity (modifyable).
-
color
¶ The text color (modifyable).
-
rect
¶ The rectangle for which this TextWriter was created. Must not be modified.
-
Note
Opacity and color apply to all the text in this object.
If you need different colors / transpareny, you must create a separate TextWriter. Whenever you determine the color should change, simply append the text to the respective TextWriter using the previously returned
lastPoint
as position for the new text.Appending items can occur in arbitrary order: only the position parameter controls where text appears.
Font and fontsize can freely vary within the same TextWriter. This can be used to let text with different properties appear on the same displayed line: just specify pos accordingly, and e.g. set it to
lastPoint
of the previously added item.