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()).
Alias for text. Implemented for symmetry, for those who use a lot of text_center and text_right, and desire a text_left.
text
text_center
text_right
text_left
Adds text to the page (left justified). The width used (in points) is returned.
As text, but centered on the current point.
Adds text to the page (centered). The width used (in points) is returned.
As text, but right-aligned to the current point.
Adds text to the page (right justified). The width used (in points) is returned.
As text, but stretches text (using wordspace, charspace, and (as a last resort) hscale) to fill the desired (available) $width. Note that if the desired width is less than the natural width taken by the text, it will be condensed to fit, using the same three routines.
wordspace
charspace
hscale
$width
The unchanged $width is returned, unless there was some reason to change it (e.g., overflow).
Options:
The percentage of one space character (default 100) that is the maximum amount to add to (each) interword spacing to expand the line.
If adding interword space didn't do enough, the percentage of one em (default 100) that is the maximum amount to add to (each) intercharacter spacing to further expand the line.
If adding intercharacter space didn't do enough, the percentage of one space character (default 100) that is the maximum additional amount to add to (each) interword spacing to further expand the line.
If adding more interword space didn't do enough, the percentage of one em (default 100) that is the maximum additional amount to add to (each) intercharacter spacing to further expand the line.
The percentage of one space character (default 25) that is the maximum amount to subtract from (each) interword spacing to condense the line.
If removing interword space didn't do enough, the percentage of one em (default 10) that is the maximum amount to subtract from (each) intercharacter spacing to further condense the line.
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.
hscale()
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.
-spillover
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.
Hyphenate_basic.pm
0: no hyphenation (default), 1: do basic hyphenation. Always allows splitting at a soft hyphen (\xAD). Unicode hyphen (U+2010) and non-splitting hyphen (U+2011) are ignored as split points.
0: do not split at a hard hyphen (x\2D), 1: OK to split (default)
0: do not split after most punctuation, 1: OK to split (default)
0: do not split after a run of one or more digits, 1: OK to split (default)
0: do not split after a run of one or more ASCII letters, 1: OK to split (default)
0: do not split in camelCase between a lowercase letter and an uppercase letter, 1: OK to split (default)
Fill a line of 'width' with as much text as will fit, and outputs it left justified. The width actually used, and the leftover text (that didn't fit), are returned.
Alias for text_fill_left().
Fill a line of 'width' with as much text as will fit, and outputs it centered. The width actually used, and the leftover text (that didn't fit), are returned.
Fill a line of 'width' with as much text as will fit, and outputs it right justified. The width actually used, and the leftover text (that didn't fit), are returned.
Fill a line of 'width' with as much text as will fit, and outputs it fully justified (stretched or condensed). The width actually used, and the leftover text (that didn't fit), are returned.
Note that the entire line is fit to the available width via a call to text_justified. The last line is unjustified (normal size) and left aligned by default, although the option
text_justified
where place is 'left' (default), 'center', or 'right' allows you to specify the alignment of the last line output.
Print a single string into a rectangular area on the page, of given width and maximum height. The baseline of the first (top) line is at the current text position.
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.
$continue
Give the amount of indent (positive) or outdent (negative, for "hanging") for paragraph first lines). This setting is ignored for centered text.
$choice is 'justified', 'right', 'center', 'left'; the default is 'left'.
$choice
If a scalar, distance below baseline, else array reference with pairs of distance and line thickness.
Controls if words in a line which exceed the given width should be "spilled over" the bounds, or if a new line should be used for this word.
$over is 1 or 0, with the default 1 (spills over the width).
$over
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 (hypenation) to better fit to a given width, and nothing is done for "widows and orphans".
paragraph()
The $text contains a string with one or more paragraphs $width wide, starting at the current text position, with a newline \n between each paragraph. Each paragraph is output (see paragraph) until the $height limit is met (a partial paragraph may be at the bottom). Whatever wasn't output, will be returned. If called in an array context, the unused height and the paragraph "continue" flag are also returned.
$text
paragraph
$height
$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.
Additional vertical space (unit: pt) between paragraphs (default 0). Note that this space will also be added after the last paragraph printed.
See paragraph for other %opts you can use, such as -align and -pndnt.
%opts
Place a line of text at an arbitrary [$x,$y] on the page, with various text settings (treatments) specified in the call.
[$x,$y]
A previously created font.
The font size (points).
The text to be printed (a single line).
Rotate $deg degrees counterclockwise from due East.
$deg
A color name or permitted spec, such as #CCE840, for the character fill.
#CCE840
A color name or permitted spec, such as #CCE840, for the character outline.
Additional distance between characters.
Additional distance between words.
Horizontal scaling mode (percentage of normal, default is 100).
Character rendering mode (outline only, fill only, etc.). See render call.
render
Left align on the given point. This is the default.
Center the text on the given point.
Right align on the given point.
Alternate to -left, -center, and -right. $placement is 'left' (default), 'center', or 'right'.
$placement
Other options available to text, such as underlining, can be used here.
The width used is returned.
To install PDF::Builder, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PDF::Builder
CPAN shell
perl -MCPAN -e shell install PDF::Builder
For more information on module installation, please visit the detailed CPAN module installation guide.