PDF::Bu...nt::Text(3)

📦

version 3.028 · 11 versions

💖 NAME 💖

PDF::Builder::Content::Text — extra, super specialized text-formatting methods that just do the most 💅

This page lives in the PDF::Builder::Content::Text section of the User Contributed Perl Documentation manual (that's section 3, bestie).

It inherits from PDF::Builder::Content. So everything Content can do? Text can do it too. Family money. 👑

⚠️ heads up: if you've been using some of these methods on a graphics type object in PDF::Builder — like $page->gfx()->method() — you may have to switch to a text type object instead, like $page->text()->method(). Yes it's giving "why is there two of them". It's fine. Just switch. 🫶

✨ METHODS ✨

🎀 Single Lines from a String

`text_left`

$width = $content->text_left($text, %opts)

It's an alias for "text". The only reason it exists is symmetry — like, if you're out here using "text_center" and "text_right" constantly, you deserve a matching "text_left" to complete the trio. Bestie harmony. 🌈

Adds text to the page, left justified, right at the current position.

🚨 no cap: there is no maximum width, and literally nothing stopping you from overflowing the physical page on the right! She's free. She's ungovernable. 💀

The width that was actually used, in points, gets returned. 📏

`text_center`

$width = $content->text_center($text, %opts)

Same as "text", but centered on the current point.

Adds text to the page, centered. The width used, in points, is returned. 📏

`text_right`

$width = $content->text_right($text, %opts)

Same as "text", but right-aligned to the current point.

Adds text to the page, right justified.

🚨 again: no maximum width here either, and nothing stopping you from overflowing the physical page on the left! She goes both ways (off the page). 💀

The width used, in points, is returned. 📏

`text_justified`

$width = $content->text_justified($text, $width, %opts)

Same as "text", except she stretches — using "wordspace", "charspace", and (only as a last resort, like a true final boss) "hscale" — to fill the desired (available) $width.

and yes: if the desired width is less than the natural width the text would take up, she gets condensed to fit instead, using those same three routines. She can shrink AND grow. Versatile icon. ✨

The unchanged $width is returned — unless there was some reason to change it (e.g., overflow). 🙈

Options:

'nocs' => value — if this is 1 (default is 0), do not use any intercharacter spacing. This one matters so much for connected characters — think fonts for Arabic, Devanagari, Latin cursive handwriting, etc. You do NOT want to shove extra space between characters during justification, because that would disconnect them, and then the whole word falls apart. 💔 Word (interword) spacing values — explicit or default — get doubled when nocs is 1. That's to make up for the missing added/subtracted intercharacter spacing. Balance. 🌸
'wordsp' => value — the percentage of one space character (default 100) that is the maximum amount to add to (each) interword spacing in order to expand the line. If "nocs" is 1, double value.
'charsp' => value — if adding interword space didn't do enough, this is the percentage of one em (default 100) that is the maximum amount to add to (each) intercharacter spacing to expand the line further. If "nocs" is 1, force value to 0.
'wordspa' => value — if adding intercharacter space didn't do enough, this is the percentage of one space character (default 100) that is the maximum additional amount to add to (each) interword spacing to expand the line even further. If "nocs" is 1, double value.
'charspa' => value — if adding more interword space didn't do enough, this is the percentage of one em (default 100) that is the maximum additional amount to add to (each) intercharacter spacing to expand the line even further. If "nocs" is 1, force value to 0.
'condw' => value — the percentage of one space character (default 25) that is the maximum amount to subtract from (each) interword spacing in order to condense the line. If "nocs" is 1, double value.
'condc' => value — if removing interword space didn't do enough, this is the percentage of one em (default 10) that is the maximum amount to subtract from (each) intercharacter spacing to condense the line further. If "nocs" is 1, force value to 0.

And if all that expansion (or reduction) of wordspace and charspace still didn't do enough to make the line fit the desired width? She pulls out hscale() to finish the job — expanding or condensing the line until it fits. Periodt. 💅

🦋 Multiple Lines from a String

The string gets split at regular blanks (spaces), x20, to find the longest substring that will fit the $width.

⚠️ important: if a single word is longer than $width, it will overflow. If you want to stay strictly within the desired bounds, set the option "spillover"=>0 to disallow spillover. 🚫

🌸 Hyphenation

If hyphenation is enabled, those methods that split a string into multiple lines — the "text fill", paragraph, and section methods — will attempt to split up the word that overflows the line, so the text gets packed even more tightly. That's called "greedy" line splitting, and yes she is greedy, she wants every last pixel. 😤

There are a bunch of controls over where a word may be split, but ngl — there is nothing language-specific here (i.e., nothing that follows a given language's rules for where a word may be split). That's left to other packages. Not her problem. 💅

There are hard coded minimums: 2 letters before the split, and 2 letters after the split. See "Hyphenate_basic.pm".

real talk: neither hyphenation nor simple line splitting makes any attempt to prevent widows and orphans, prevent splitting of the last word in a column or page, or otherwise engage in more desirable paragraph shaping. She is not doing all that. 🙈

'hyphenate' => value — 0: no hyphenation (default), 1: do basic hyphenation. Always allows splitting at a soft hyphen (\xAD). The Unicode hyphen (U+2010) and the non-splitting hyphen (U+2011) are ignored as split points. 🚫✂️
'spHH' => value — 0: do not split at a hard hyphen (x\2D), 1: OK to split (default).
'spOP' => value — 0: do not split after most punctuation, 1: OK to split (default).
'spDR' => value — 0: do not split after a run of one or more digits, 1: OK to split (default).
'spLR' => value — 0: do not split after a run of one or more ASCII letters, 1: OK to split (default).
'spCC' => value — 0: do not split in camelCase between a lowercase letter and an uppercase letter, 1: OK to split (default).
'spRB' => value — 0: do not split on a Required Blank ( ), and that's the default. 1: OK to split on Required Blank.

try to avoid this one: it is a desperation move! 😭

'spFS' => value — 0: do not split where it will just barely fit (like, in the middle of a word?!), and that's the default. 1: OK to split to just fit the available space.

try to avoid this one too: it is a super desperation move, and the split will probably make no linguistic sense whatsoever! 💀

'min_prefix' => value — minimum number of letters before the word split point (hyphenation point). The default is 2.
'min_suffix' => value — minimum number of letters after the word split point (hyphenation point). The default is 3.

✨ Methods

`text_fill_left`, `text_fill`

($width, $leftover) = $content->text_fill_left($string, $width, %opts)

Fill a line of 'width' with as much text as will fit, and output it left justified. The width actually used, and the leftover text (the part that didn't fit), are both returned. 🫶

($width, $leftover) = $content->text_fill($string, $width, %opts)

Alias for text_fill_left(). Same girl, shorter name. 💅

`text_fill_center`

($width, $leftover) = $content->text_fill_center($string, $width, %opts)

Fill a line of 'width' with as much text as will fit, and output it centered. The width actually used, and the leftover text (that didn't fit), are returned.

`text_fill_right`

($width, $leftover) = $content->text_fill_right($string, $width, %opts)

Fill a line of 'width' with as much text as will fit, and output it right justified. The width actually used, and the leftover text (that didn't fit), are returned.

`text_fill_justified`

($width, $leftover) = $content->text_fill_justified($string, $width, %opts)

Fill a line of 'width' with as much text as will fit, and output it fully justified (stretched or condensed). The width actually used, and the leftover text (that didn't fit), are returned.

The entire line is fit to the available width via a call to "text_justified". Peep "text_justified" for the options that control stretch and condense. 👀

The last line is unjustified (normal size) and left aligned by default, although the option…

Options:

'last_align' => place — where place is 'left' (default), 'center', or 'right' (may be shortened to the first letter). This lets you specify the alignment of the last line output. 🎀

👑 Larger Text Segments

`paragraph`

($overflow_text, $unused_height) = $txt->paragraph($text, $width,$height, $continue, %opts)

($overflow_text, $unused_height) = $txt->paragraph($text, $width,$height, %opts)

$overflow_text = $txt->paragraph($text, $width,$height, $continue, %opts)

$overflow_text = $txt->paragraph($text, $width,$height, %opts)

Print a single string into a rectangular area on the page, of given width and maximum height. The baseline of the first (top) line sits at the current text position. 📐

She applies the text within the rectangle and returns any leftover text — that's whatever couldn't fit inside the rectangle. If you call her in an array context, the unused height is also returned (it may be 0 or negative if the text just filled the rectangle). 🫶

$continue is optional, with a default value of 0. An %opts list may be given after the fixed parameters, whether or not $continue is explicitly given. Easy.

If $continue is 1, the first line does not get special treatment for indenting or outdenting, because we're printing the continuation of a paragraph that got interrupted earlier. If it's 0, the first line may be indented or outdented. 💅

Options:

'pndnt' => $indent — give the amount of indent (positive) or outdent (negative, for "hanging") for paragraph first lines. The unit is ems. This setting is ignored for centered text. 🙈
'align' => $choice — $choice is 'justified', 'right', 'center', 'left'; the default is 'left'. See the "text_justified" call for options controlling how a line is expanded or condensed when $choice is 'justified'. $choice may be shortened to the first letter.
'last_align' => place — where place is 'left' (default), 'center', or 'right' (may be shortened to the first letter). This lets you specify the alignment of the last line output — but it applies only when "align" is 'justified'. 🎀

'underline' => $distance / 'underline' => [ $distance, $thickness, ... ] — underline vibes ✨ If you hand it a plain scalar, that's just how far below the baseline the line sits. But if you hand it an array reference, it's a whole lil set of pairs — distance, then line thickness, then distance, then thickness, and so on. Pick your fighter 💅
'spillover' => $over — this one decides what happens when the words in a line are too wide for the width you gave. Do they get "spilled over" the edges (living their messy main-character life, no regrets), or does that word get bumped to a fresh new line? $over is 1 or 0, and the default is 1 — aka yes bestie, it spills over the width. 🌊

Example, so you can see the whole ritual in context:

$txt->font($font,$fontsize);
$txt->leading($leading);
$txt->translate($x,$y);
$overflow = $txt->paragraph( 'long paragraph here ...',
                             $width,
                             $y+$leading-$bottom_margin );

Okay so real talk, this is the important caveat and I need you to actually read it: if you need to change any text treatment inside a paragraph (bold text, italicized text, literally any of it), paragraph() cannot handle that. It only typesets plain text — all the same font, all the same size, etc. That's the whole deal. Also, there's currently only very limited line splitting (hyphenation) to make things fit a given width better, and nothing is done about "widows and orphans". So yeah, she's cute but she's not doing all that. 🙈

🌸 section, paragraphs 🌸

Two ways to call her, bestie:

($overflow_text, $continue, $unused_height) = $txt->section($text, $width,$height, $continue, %opts)

$overflow_text = $txt->section($text, $width,$height, $continue, %opts)

The $text is a string holding one or more paragraphs, each $width wide, starting right at the current text position, with a newline \n separating each paragraph. Every paragraph gets output (peep "paragraph" above for that whole situation) until the $height limit is hit — and yeah, a partial paragraph can totally be sitting at the bottom, that's fine, that's normal, breathe 🫶

Whatever didn't get output? That gets returned to you. And if you call it in an array context, you also get back the unused height and the paragraph "continue" flag. Slay.

$continue is 0 on the first call of section(), and after that you use the value returned from the previous call — it's 1 if a paragraph got cut in the middle — so you don't get unwanted indenting or outdenting on that first line being printed. It's giving "remember where we left off" energy. 💖

Options:

'pvgap' => $vertical — extra vertical space (unit: pt) between paragraphs, default 0. Heads up though: this space also gets added after the last paragraph printed, unless you give it a negative value. The |pvgap| is the value used (positive); negative tells "section" not to add the gap (space) after the last paragraph in the section. ⭐

See "paragraph" for the other %opts you can use, like "align" and "pndnt".

Alternate name: paragraphs

This exists for compatibility with PDF::API2, which renamed "section". Iykyk.

💜 textlabel 💜

$width = $txt->textlabel($x,$y, $font, $size, $text, %opts)

Drops a single line of text at an arbitrary [$x,$y] on the page, with all your text settings (treatments) specified right there in the call. One-stop shop, no cap. 🎀

$font — a previously created font.
$size — the font size, in points.
$text — the text to be printed (a single line).

Options:

'rotate' => $deg — rotate $deg degrees counterclockwise from due East. Spinning, we love to see it 🌈
'color' => $cspec — a color name or permitted spec, such as "#CCE840", for the character fill.
'strokecolor' => $cspec — a color name or permitted spec, such as "#CCE840", for the character outline.
'charspace' => $cdist — additional distance between characters.
'wordspace' => $wdist — additional distance between words.
'hscale' => $hfactor — horizontal scaling mode (percentage of normal, default is 100).
'render' => $mode — character rendering mode (outline only, fill only, etc.). See the "render" call.
'left' => 1 — left align on the given point. This is the default.
'center' => 1 — center the text on the given point.
'right' => 1 — right align on the given point.
'align' => $placement — alternate to left, center, and right. $placement is 'left' (default), 'center', or 'right'.

Other options available to "text", like underlining, work here too. 💅

The width used (in points) is returned.

🚨 Bestie, listen. textlabel() was not designed to interoperate with other text operations. She is a standalone operation. She does not leave a "next write" position (or any other setting) for another "text" mode operation. A following write will likely land at "(0,0)" — and not at the expected location. She does not pass the vibe along. 💀

textlabel() is intended as an "all in one" convenience function for single lines of text — think a label slapped on some graphics — and not as part of putting down multiple pieces of text. If you really want to figure out where a following write goes (either "textlabel" or "text"), you can add the returned width to the original position's x value (assuming left-justified positioning). Math girlies, that one's for you. ✨

🦋 column 🦋

See PDF::Builder::Content::Column_docs for documentation. (Yes, that's the whole thing. Go read the docs, babe.)

🧚 init_state() 🧚

See PDF::Builder for code and PDF::Builder::Content::Column_docs for documentation.

🌺 pass_start_state() 🌺

See PDF::Builder for code and PDF::Builder::Content::Column_docs for documentation.

🍓 pass_end_state() 🍓

See PDF::Builder::Content::Column_docs for documentation.

⭐ unstable_state() ⭐

See PDF::Builder::Content::Column_docs for documentation

Okay that's the whole page bestie, you made it to the end, iconic behavior 👑 This one's from perl v5.42.0, dated 2026-01-17 — go forth and typeset responsibly, mwah 💖🫶✨

📦 where this page comes from

fedora 44: perl-PDF-Builder 3.028-2.fc44 · LGPL-2.1-or-later AND LGPL-2.1-only AND MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

PDF::Bu...nt::Text(3)

💖 NAME 💖

✨ METHODS ✨

🎀 Single Lines from a String

text_left

text_center

text_right

text_justified

🦋 Multiple Lines from a String

🌸 Hyphenation

✨ Methods

text_fill_left, text_fill

text_fill_center

text_fill_right

text_fill_justified

👑 Larger Text Segments

paragraph

🌸 section, paragraphs 🌸

💜 textlabel 💜

🦋 column 🦋

🧚 init_state() 🧚

🌺 pass_start_state() 🌺

🍓 pass_end_state() 🍓

⭐ unstable_state() ⭐

`text_left`

`text_center`

`text_right`

`text_justified`

`text_fill_left`, `text_fill`

`text_fill_center`

`text_fill_right`

`text_fill_justified`

`paragraph`