1PDF::Builder::Content::UTseexrt(C3o)ntributed Perl DocumPeDnFt:a:tBiuoinlder::Content::Text(3)
2
6 PDF::Builder::Content::Text - additional specialized text-related
7 formatting methods. Inherits from PDF::Builder::Content
8 Note: If you have used some of these methods in PDF::API2 with a
10 graphics type object (e.g., $page->gfx()->method()), you may have to
11 change to a text type object (e.g., $page->text()->method()).
12
14 $width = $content->text_left($text, %opts)
15 $width = $content->text_left($text)
16 Alias for "text". Implemented for symmetry, for those who use a lot
17 of "text_center" and "text_right", and desire a "text_left".
18 Adds text to the page (left justified). Note that there is no
20 maximum width, and nothing to keep you from overflowing the
21 physical page on the right! The width used (in points) is
22 returned.
23 $width = $content->text_center($text, %opts)
25 $width = $content->text_center($text)
26 As "text", but centered on the current point.
27 Adds text to the page (centered). The width used (in points) is
29 returned.
30 $width = $content->text_right($text, %opts)
32 $width = $content->text_right($text)
33 As "text", but right-aligned to the current point.
34 Adds text to the page (right justified). Note that there is no
36 maximum width, and nothing to keep you from overflowing the
37 physical page on the left! The width used (in points) is returned.
38 $width = $content->text_justified($text, $width, %opts)
40 $width = $content->text_justified($text, $width)
41 As "text", but stretches text (using "wordspace", "charspace", and
42 (as a last resort) "hscale") to fill the desired (available)
43 $width. Note that if the desired width is less than the natural
44 width taken by the text, it will be condensed to fit, using the
45 same three routines.
46 The unchanged $width is returned, unless there was some reason to
48 change it (e.g., overflow).
49 Options:
51 -nocs => value
53 If this option value is 1 (default 0), do not use any
54 intercharacter spacing. This is useful for connected
55 characters, such as fonts for Arabic, Devanagari, Latin cursive
56 handwriting, etc. You don't want to add additional space
57 between characters during justification, which would disconnect
58 them.
59 Word (interword) spacing values (explicit or default) are
61 doubled if -nocs is 1. This is to make up for the lack of
62 added/subtracted intercharacter spacing.
63 -wordsp => value
65 The percentage of one space character (default 100) that is the
66 maximum amount to add to (each) interword spacing to expand the
67 line. If "-nocs" is 1, double "value".
68 -charsp => value
70 If adding interword space didn't do enough, the percentage of
71 one em (default 100) that is the maximum amount to add to
72 (each) intercharacter spacing to further expand the line. If
73 "-nocs" is 1, force "value" to 0.
74 -wordspa => value
76 If adding intercharacter space didn't do enough, the percentage
77 of one space character (default 100) that is the maximum
78 additional amount to add to (each) interword spacing to further
79 expand the line. If "-nocs" is 1, double "value".
80 -charspa => value
82 If adding more interword space didn't do enough, the percentage
83 of one em (default 100) that is the maximum additional amount
84 to add to (each) intercharacter spacing to further expand the
85 line. If "-nocs" is 1, force "value" to 0.
86 -condw => value
88 The percentage of one space character (default 25) that is the
89 maximum amount to subtract from (each) interword spacing to
90 condense the line. If "-nocs" is 1, double "value".
91 -condc => value
93 If removing interword space didn't do enough, the percentage of
94 one em (default 10) that is the maximum amount to subtract from
95 (each) intercharacter spacing to further condense the line. If
96 "-nocs" is 1, force "value" to 0.
97 If expansion (or reduction) wordspace and charspace changes didn't
99 do enough to make the line fit the desired width, use "hscale()" to
100 finish expanding or condensing the line to fit.
101 Multiple Lines from a String
103 The string is split at regular blanks (spaces), x20, to find the
104 longest substring that will fit the $width. If a single word is longer
105 than $width, it will overflow. To stay strictly within the desired
106 bounds, set the option "-spillover"=>0 to disallow spillover.
107 Hyphenation
109 If hyphenation is enabled, those methods which split up a string into
111 multiple lines (the "text fill", paragraph, and section methods) will
112 attempt to split up the word that overflows the line, in order to pack
113 the text even more tightly ("greedy" line splitting). There are a
114 number of controls over where a word may be split, but note that there
115 is nothing language-specific (i.e., following a given language's rules
116 for where a word may be split). This is left to other packages.
117 There are hard coded minimums of 2 letters before the split, and 2
119 letters after the split. See "Hyphenate_basic.pm". Note that neither
120 hyphenation nor simple line splitting makes any attempt to prevent
121 widows and orphans, prevent splitting of the last word in a column or
122 page, or otherwise engage in paragraph shaping.
123 -hyphenate => value
125 0: no hyphenation (default), 1: do basic hyphenation. Always allows
126 splitting at a soft hyphen (\xAD). Unicode hyphen (U+2010) and non-
127 splitting hyphen (U+2011) are ignored as split points.
128 -spHH => value
130 0: do not split at a hard hyphen (x\2D), 1: OK to split (default)
131 -spOP => value
133 0: do not split after most punctuation, 1: OK to split (default)
134 -spDR => value
136 0: do not split after a run of one or more digits, 1: OK to split
137 (default)
138 -spLR => value
140 0: do not split after a run of one or more ASCII letters, 1: OK to
141 split (default)
142 -spCC => value
144 0: do not split in camelCase between a lowercase letter and an
145 uppercase letter, 1: OK to split (default)
146 Methods
148 ($width, $leftover) = $content->text_fill_left($string, $width, %opts)
150 ($width, $leftover) = $content->text_fill_left($string, $width)
151 Fill a line of 'width' with as much text as will fit, and outputs
152 it left justified. The width actually used, and the leftover text
153 (that didn't fit), are returned.
154 ($width, $leftover) = $content->text_fill($string, $width, %opts)
156 ($width, $leftover) = $content->text_fill($string, $width)
157 Alias for text_fill_left().
158 ($width, $leftover) = $content->text_fill_center($string, $width,
160 %opts)
161 ($width, $leftover) = $content->text_fill_center($string, $width)
162 Fill a line of 'width' with as much text as will fit, and outputs
163 it centered. The width actually used, and the leftover text (that
164 didn't fit), are returned.
165 ($width, $leftover) = $content->text_fill_right($string, $width, %opts)
167 ($width, $leftover) = $content->text_fill_right($string, $width)
168 Fill a line of 'width' with as much text as will fit, and outputs
169 it right justified. The width actually used, and the leftover text
170 (that didn't fit), are returned.
171 ($width, $leftover) = $content->text_fill_justified($string, $width,
173 %opts)
174 ($width, $leftover) = $content->text_fill_justified($string, $width)
175 Fill a line of 'width' with as much text as will fit, and outputs
176 it fully justified (stretched or condensed). The width actually
177 used, and the leftover text (that didn't fit), are returned.
178 Note that the entire line is fit to the available width via a call
180 to "text_justified". See "text_justified" for options to control
181 stretch and condense. The last line is unjustified (normal size)
182 and left aligned by default, although the option
183 Options:
185 -last_align => place
187 where place is 'left' (default), 'center', or 'right' (may be
188 shortened to first letter) allows you to specify the alignment
189 of the last line output.
190 ($overflow_text, $unused_height) = $txt->paragraph($text,
192 $width,$height, $continue, %opts)
193 ($overflow_text, $unused_height) = $txt->paragraph($text,
194 $width,$height, $continue)
195 $overflow_text = $txt->paragraph($text, $width,$height, $continue,
196 %opts)
197 $overflow_text = $txt->paragraph($text, $width,$height, $continue)
198 Print a single string into a rectangular area on the page, of given
199 width and maximum height. The baseline of the first (top) line is
200 at the current text position.
201 Apply the text within the rectangle and return any leftover text
203 (if could not fit all of it within the rectangle). If called in an
204 array context, the unused height is also returned (may be 0 or
205 negative if it just filled the rectangle).
206 If $continue is 1, the first line does not get special treatment
208 for indenting or outdenting, because we're printing the
209 continuation of the paragraph that was interrupted earlier. If it's
210 0, the first line may be indented or outdented.
211 Options:
213 -pndnt => $indent
215 Give the amount of indent (positive) or outdent (negative, for
216 "hanging") for paragraph first lines). This setting is ignored
217 for centered text.
218 -align => $choice
220 $choice is 'justified', 'right', 'center', 'left'; the default
221 is 'left'. See "text_justified" call for options to control
222 how a line is expanded or condensed if $choice is 'justified'.
223 $choice may be shortened to the first letter.
224 -last_align => place
226 where place is 'left' (default), 'center', or 'right' (may be
227 shortened to first letter) allows you to specify the alignment
228 of the last line output, but applies only when "-align" is
229 'justified'.
230 -underline => $distance
232 -underline => [ $distance, $thickness, ... ]
233 If a scalar, distance below baseline, else array reference with
234 pairs of distance and line thickness.
235 -spillover => $over
237 Controls if words in a line which exceed the given width should
238 be "spilled over" the bounds, or if a new line should be used
239 for this word.
240 $over is 1 or 0, with the default 1 (spills over the width).
242 Example:
244 $txt->font($font,$fontsize);
246 $txt->leading($leading);
247 $txt->translate($x,$y);
248 $overflow = $txt->paragraph( 'long paragraph here ...',
249 $width,
250 $y+$leading-$bottom_margin );
251 Note: if you need to change any text treatment within a paragraph
253 (bold or italicized text, for instance), this can not handle it.
254 Only plain text (all the same font, size, etc.) can be typeset with
255 "paragraph()". Also, there is currently very limited line
256 splitting (hyphenation) to better fit to a given width, and nothing
257 is done for "widows and orphans".
258 ($overflow_text, $continue, $unused_height) = $txt->section($text,
260 $width,$height, $continue, %opts)
261 ($overflow_text, $continue, $unused_height) = $txt->section($text,
262 $width,$height, $continue)
263 $overflow_text = $txt->section($text, $width,$height, $continue, %opts)
264 $overflow_text = $txt->section($text, $width,$height, $continue)
265 The $text contains a string with one or more paragraphs $width
266 wide, starting at the current text position, with a newline \n
267 between each paragraph. Each paragraph is output (see "paragraph")
268 until the $height limit is met (a partial paragraph may be at the
269 bottom). Whatever wasn't output, will be returned. If called in an
270 array context, the unused height and the paragraph "continue" flag
271 are also returned.
272 $continue is 0 for the first call of section(), and then use the
274 value returned from the previous call (1 if a paragraph was cut in
275 the middle) to prevent unwanted indenting or outdenting of the
276 first line being printed.
277 For compatibility with recent changes to PDF::API2, paragraphs is
279 accepted as an alias for "section".
280 Options:
282 -pvgap => $vertical
284 Additional vertical space (unit: pt) between paragraphs
285 (default 0). Note that this space will also be added after the
286 last paragraph printed.
287 See "paragraph" for other %opts you can use, such as -align and
289 -pndnt.
290 $width = $txt->textlabel($x,$y, $font, $size, $text, %opts)
292 $width = $txt->textlabel($x,$y, $font, $size, $text)
293 Place a line of text at an arbitrary "[$x,$y]" on the page, with
294 various text settings (treatments) specified in the call.
295 $font
297 A previously created font.
298 $size
300 The font size (points).
301 $text
303 The text to be printed (a single line).
304 Options:
306 -rotate => $deg
308 Rotate $deg degrees counterclockwise from due East.
309 -color => $cspec
311 A color name or permitted spec, such as "#CCE840", for the
312 character fill.
313 -strokecolor => $cspec
315 A color name or permitted spec, such as "#CCE840", for the
316 character outline.
317 -charspace => $cdist
319 Additional distance between characters.
320 -wordspace => $wdist
322 Additional distance between words.
323 -hscale => $hfactor
325 Horizontal scaling mode (percentage of normal, default is 100).
326 -render => $mode
328 Character rendering mode (outline only, fill only, etc.). See
329 "render" call.
330 -left => 1
332 Left align on the given point. This is the default.
333 -center => 1
335 Center the text on the given point.
336 -right => 1
338 Right align on the given point.
339 -align => $placement
341 Alternate to -left, -center, and -right. $placement is 'left'
342 (default), 'center', or 'right'.
343 Other options available to "text", such as underlining, can be used
345 here.
346 The width used (in points) is returned.
348 Please note that "textlabel()" was not designed to interoperate with
350 other text operations. It is a standalone operation, and does not leave
351 a "next write" position (or any other setting) for another "text" mode
352 operation. A following write will likely be at "(0,0)", and not at the
353 expected location.
354 "textlabel()" is intended as an "all in one" convenience function for
356 single lines of text, such as a label on some graphics, and not as part
357 of putting down multiple pieces of text. It is possible to figure out
358 the position of a following write (either "textlabel" or "text") by
359 adding the returned width to the original position's x value (assuming
360 left-justified positioning).
361perl v5.34.0 2022-01-21 PDF::Builder::Content::Text(3)