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:

  1. 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.

  2. Store text in the TextWriter using method either TextWriter.append() or TextWriter.fillTextbox().

  3. 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

textRect and lastPoint after this text has been added.

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

  1. Opacity and color apply to all the text in this object.

  2. 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.

  3. Appending items can occur in arbitrary order: only the position parameter controls where text appears.

  4. 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.