| PDF::Builder::Content::Text(3pm) | User Contributed Perl Documentation | PDF::Builder::Content::Text(3pm) |
PDF::Builder::Content::Text - additional specialized text-related formatting methods. Inherits from PDF::Builder::Content
Note: If you have used some of these methods in PDF::API2 with a graphics type object (e.g., $page->gfx()->method()), you may have to change to a text type object (e.g., $page->text()->method()).
Adds text to the page (left justified). Note that there is no maximum width, and nothing to keep you from overflowing the physical page on the right! The width used (in points) is returned.
Adds text to the page (centered). The width used (in points) is returned.
Adds text to the page (right justified). Note that there is no maximum width, and nothing to keep you from overflowing the physical page on the left! The width used (in points) is returned.
The unchanged $width is returned, unless there was some reason to change it (e.g., overflow).
Options:
Word (interword) spacing values (explicit or default) are doubled if -nocs is 1. This is to make up for the lack of added/subtracted intercharacter spacing.
If expansion (or reduction) wordspace and charspace changes didn't do enough to make the line fit the desired width, use "hscale()" to finish expanding or condensing the line to fit.
The string is split at regular blanks (spaces), x20, to find the longest substring that will fit the $width. If a single word is longer than $width, it will overflow. To stay strictly within the desired bounds, set the option "-spillover"=>0 to disallow spillover.
Hyphenation
If hyphenation is enabled, those methods which split up a string into multiple lines (the "text fill", paragraph, and section methods) will attempt to split up the word that overflows the line, in order to pack the text even more tightly ("greedy" line splitting). There are a number of controls over where a word may be split, but note that there is nothing language-specific (i.e., following a given language's rules for where a word may be split). This is left to other packages.
There are hard coded minimums of 2 letters before the split, and 2 letters after the split. See "Hyphenate_basic.pm". Note that 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 paragraph shaping.
Methods
Note that the entire line is fit to the available width via a call to "text_justified". See "text_justified" for options to control stretch and condense. The last line is unjustified (normal size) and left aligned by default, although the option
Options:
Apply the text within the rectangle and return any leftover text (if could not fit all of it within the rectangle). If called in an array context, the unused height is also returned (may be 0 or negative if it just filled the rectangle).
If $continue is 1, the first line does not get special treatment for indenting or outdenting, because we're printing the continuation of the paragraph that was interrupted earlier. If it's 0, the first line may be indented or outdented.
Options:
$over is 1 or 0, with the default 1 (spills over the width).
Example:
$txt->font($font,$fontsize);
$txt->lead($lead);
$txt->translate($x,$y);
$overflow = $txt->paragraph( 'long paragraph here ...',
$width,
$y+$lead-$bottom_margin );
Note: if you need to change any text treatment within a paragraph (bold or italicized text, for instance), this can not handle it. Only plain text (all the same font, size, etc.) can be typeset with "paragraph()". Also, there is currently very limited line splitting (hyphenation) to better fit to a given width, and nothing is done for "widows and orphans".
$continue is 0 for the first call of section(), and then use the value returned from the previous call (1 if a paragraph was cut in the middle) to prevent unwanted indenting or outdenting of the first line being printed.
Options:
See "paragraph" for other %opts you can use, such as -align and -pndnt.
Options:
Other options available to "text", such as underlining, can be used here.
The width used (in points) is returned.
Please note that "textlabel()" was not designed to interoperate with other text operations. It is a standalone operation, and does not leave a "next write" position (or any other setting) for another "text" mode operation. A following write will likely be at "(0,0)", and not at the expected location.
"textlabel()" is intended as an "all in one" convenience function for single lines of text, such as a label on some graphics, and not as part of putting down multiple pieces of text. It is possible to figure out the position of a following write (either "textlabel" or "text") by adding the returned width to the original position's x value (assuming left-justified positioning).
| 2021-03-28 | perl v5.32.1 |