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