Module text 

Text Measurement and Wrapping

Provides text wrapping for the XFA layout engine. Key functions:

• wrap_text() — wraps text to fit within a maximum width
• measure_text() — measures text dimensions without wrapping

Font Metrics

Text measurement uses FontMetrics.resolved_widths when available (populated from PDF /Widths arrays). Falls back to glyph advances from the font file via ttf_parser.

Coordinate System

All measurements are in PDF points (1pt = 1/72 inch).

XFA Spec 3.3 §8.1 — Text Placement in Growable Containers (p277-279):

• Growable width: text records interpreted as lines, width = longest line.
• Growable height: container increases height to accommodate text.
• Text split between lines only (§8.7 p291), NOT within a line.
• Orphan/widow controls may restrict split points. Not implemented yet because the layout engine does not currently track widow/orphan state across container and page splits.
• Text within rotated containers cannot be split. Not checked yet because rotation metadata is not propagated into this measurement layer.

Structs

FontMetrics

Font properties for text measurement.

TextLayout

Text wrapping and measurement result.

Enums

FontFamily

Font family classification for width table selection.

Functions

measure_text

Compute the bounding box of text without wrapping.

text_split_points

Compute valid split positions (y-offsets) for multiline text.

wrap_text

Wrap text to fit within a given width, and compute the resulting size.