1PDF::Builder::Content::UTseexrt(C3o)ntributed Perl DocumPeDnFt:a:tBiuoinlder::Content::Text(3)
2
3
4

NAME

6       PDF::Builder::Content::Text - additional specialized text-related
7       formatting methods. Inherits from PDF::Builder::Content
8
9       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

METHODS

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
19           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
24       $width = $content->text_center($text, %opts)
25       $width = $content->text_center($text)
26           As "text", but centered on the current point.
27
28           Adds text to the page (centered).  The width used (in points) is
29           returned.
30
31       $width = $content->text_right($text, %opts)
32       $width = $content->text_right($text)
33           As "text", but right-aligned to the current point.
34
35           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
39       $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
47           The unchanged $width is returned, unless there was some reason to
48           change it (e.g., overflow).
49
50           Options:
51
52           -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
60               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
64           -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
69           -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
75           -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
81           -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
87           -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
92           -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
98           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
102   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
108       Hyphenation
109
110       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
118       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
124       -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
129       -spHH => value
130           0: do not split at a hard hyphen (x\2D), 1: OK to split (default)
131
132       -spOP => value
133           0: do not split after most punctuation, 1: OK to split (default)
134
135       -spDR => value
136           0: do not split after a run of one or more digits, 1: OK to split
137           (default)
138
139       -spLR => value
140           0: do not split after a run of one or more ASCII letters, 1: OK to
141           split (default)
142
143       -spCC => value
144           0: do not split in camelCase between a lowercase letter and an
145           uppercase letter, 1: OK to split (default)
146
147       Methods
148
149       ($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
155       ($width, $leftover) = $content->text_fill($string, $width, %opts)
156       ($width, $leftover) = $content->text_fill($string, $width)
157           Alias for text_fill_left().
158
159       ($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
166       ($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
172       ($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
179           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
184           Options:
185
186           -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
191       ($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
202           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
207           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
212           Options:
213
214           -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
219           -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
225           -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
231           -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
236           -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
241               $over is 1 or 0, with the default 1 (spills over the width).
242
243           Example:
244
245               $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
252           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
259       ($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
273           $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
278           For compatibility with recent changes to PDF::API2, paragraphs is
279           accepted as an alias for "section".
280
281           Options:
282
283           -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
288           See "paragraph" for other %opts you can use, such as -align and
289           -pndnt.
290
291       $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
296           $font
297               A previously created font.
298
299           $size
300               The font size (points).
301
302           $text
303               The text to be printed (a single line).
304
305           Options:
306
307           -rotate => $deg
308               Rotate $deg degrees counterclockwise from due East.
309
310           -color => $cspec
311               A color name or permitted spec, such as "#CCE840", for the
312               character fill.
313
314           -strokecolor => $cspec
315               A color name or permitted spec, such as "#CCE840", for the
316               character outline.
317
318           -charspace => $cdist
319               Additional distance between characters.
320
321           -wordspace => $wdist
322               Additional distance between words.
323
324           -hscale => $hfactor
325               Horizontal scaling mode (percentage of normal, default is 100).
326
327           -render => $mode
328               Character rendering mode (outline only, fill only, etc.). See
329               "render" call.
330
331           -left => 1
332               Left align on the given point. This is the default.
333
334           -center => 1
335               Center the text on the given point.
336
337           -right => 1
338               Right align on the given point.
339
340           -align => $placement
341               Alternate to -left, -center, and -right. $placement is 'left'
342               (default), 'center', or 'right'.
343
344           Other options available to "text", such as underlining, can be used
345           here.
346
347           The width used (in points) is returned.
348
349       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
355       "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).
361
362
363
364perl v5.34.0                      2021-07-22    PDF::Builder::Content::Text(3)
Impressum