NAME

PDF::Make::Builder::Text - Word-wrapped text paragraph for PDF::Make

SYNOPSIS

$builder->add_text(
    text     => 'Hello, world!',
    align    => 'center',
    margin   => 10,
    overflow => 1,
    font     => { size => 12, colour => '#333' },
);

DESCRIPTION

Renders a word-wrapped text paragraph at the current cursor position, handling line breaking, alignment, indentation, and automatic page overflow.

PROPERTIES

text (Str, required)

The text content to render. When runs is given this is the plain string behind them, which tagged output and extraction read; add_text derives it for you.

runs (ArrayRef)

Styled inline runs, for text whose style changes mid-sentence:

$pdf->add_text(runs => [
    { text => 'Amount due: ' },
    { text => '1,240.00', bold => 1 },
    { text => ' by 30 September.', italic => 1, colour => '#aa0000' },
]);

Each run is a hashref of text plus any of bold, italic, colour, size, family and line_height, each defaulting to the block font. Lines break across run boundaries, and a line's baseline and height come from the largest run on it, so a bigger or bolder segment makes room for itself.

When runs is absent the original single-font path renders the block, and its output is unchanged - documents produced before runs existed still render byte for byte as they did. For a single run the two paths choose the same line breaks, which t/45-runs.t asserts against the shipped algorithm.

align (Str, default 'left')

Horizontal alignment: 'left', 'center', or 'right'.

indent (Int, default 0)

Number of space-widths to indent the first line.

padding (Num, default 0)

Inset in points applied on all sides of the text block.

spacing (Num, default 0)

Extra vertical spacing in points between wrapped lines, and after the entire text block.

pad (Str)

Padding character used for dot leaders (e.g. in TOC entries).

pad_end (Str)

Text appended after the pad characters (e.g. a page number).

margin (Num, default 5)

Vertical margin in points added after the text block.

overflow (Bool, default 0)

When true, automatically creates new pages if the text exceeds the remaining space on the current page.

preformatted (Bool, default 0)

When true, the text is rendered verbatim: hard newlines and all in-line whitespace are preserved (leading spaces indent), and tabs are expanded to four spaces. Whitespace is never collapsed, but physical lines longer than the content width are soft-wrapped (at whitespace where possible, mid-token otherwise) so nothing runs off the page. Preformatted text is always left-aligned, and align, indent, and pad are ignored; page overflow still applies. Use this for code blocks and other pre-formatted content where the default whitespace-collapsing word-wrap would destroy the layout.

font (HashRef)

Font overrides: colour, size, family, line_height.

end_w (Num, default 0)

Set after rendering to the width of the last rendered line.

METHODS

add($builder)

Renders the word-wrapped text onto the builder's current page, advancing the cursor. Returns $self.

SEE ALSO

PDF::Make::Builder, PDF::Make::Builder::Font, PDF::Make::Builder::Text::H1