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::Builder 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 Single Lines from a String
15 $width = $content->text_left($text, %opts)
16 Alias for "text". Implemented for symmetry, for those who use a lot
17 of "text_center" and "text_right", and desire a matching
18 "text_left".
19 Adds text to the page (left justified), at the current position.
21 Note that there is no maximum width, and nothing to keep you from
22 overflowing the physical page on the right! The width used (in
23 points) is returned.
24 $width = $content->text_center($text, %opts)
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 As "text", but right-aligned to the current point.
33 Adds text to the page (right justified). Note that there is no
35 maximum width, and nothing to keep you from overflowing the
36 physical page on the left! The width used (in points) is returned.
37 $width = $content->text_justified($text, $width, %opts)
39 As "text", but stretches text using "wordspace", "charspace", and
40 (as a last resort) "hscale", to fill the desired (available)
41 $width. Note that if the desired width is less than the natural
42 width taken by the text, it will be condensed to fit, using the
43 same three routines.
44 The unchanged $width is returned, unless there was some reason to
46 change it (e.g., overflow).
47 Options:
49 'nocs' => value
51 If this option value is 1 (default 0), do not use any
52 intercharacter spacing. This is useful for connected
53 characters, such as fonts for Arabic, Devanagari, Latin cursive
54 handwriting, etc. You don't want to add additional space
55 between characters during justification, which would disconnect
56 them.
57 Word (interword) spacing values (explicit or default) are
59 doubled if nocs is 1. This is to make up for the lack of
60 added/subtracted intercharacter spacing.
61 'wordsp' => value
63 The percentage of one space character (default 100) that is the
64 maximum amount to add to (each) interword spacing to expand the
65 line. If "nocs" is 1, double "value".
66 'charsp' => value
68 If adding interword space didn't do enough, the percentage of
69 one em (default 100) that is the maximum amount to add to
70 (each) intercharacter spacing to further expand the line. If
71 "nocs" is 1, force "value" to 0.
72 'wordspa' => value
74 If adding intercharacter space didn't do enough, the percentage
75 of one space character (default 100) that is the maximum
76 additional amount to add to (each) interword spacing to further
77 expand the line. If "nocs" is 1, double "value".
78 'charspa' => value
80 If adding more interword space didn't do enough, the percentage
81 of one em (default 100) that is the maximum additional amount
82 to add to (each) intercharacter spacing to further expand the
83 line. If "nocs" is 1, force "value" to 0.
84 'condw' => value
86 The percentage of one space character (default 25) that is the
87 maximum amount to subtract from (each) interword spacing to
88 condense the line. If "nocs" is 1, double "value".
89 'condc' => value
91 If removing interword space didn't do enough, the percentage of
92 one em (default 10) that is the maximum amount to subtract from
93 (each) intercharacter spacing to further condense the line. If
94 "nocs" is 1, force "value" to 0.
95 If expansion (or reduction) wordspace and charspace changes didn't
97 do enough to make the line fit the desired width, use hscale() to
98 finish expanding or condensing the line to fit.
99 Multiple Lines from a String
101 The string is split at regular blanks (spaces), x20, to find the
102 longest substring that will fit the $width. If a single word is longer
103 than $width, it will overflow. To stay strictly within the desired
104 bounds, set the option "spillover"=>0 to disallow spillover.
105 Hyphenation
107 If hyphenation is enabled, those methods which split up a string into
109 multiple lines (the "text fill", paragraph, and section methods) will
110 attempt to split up the word that overflows the line, in order to pack
111 the text even more tightly ("greedy" line splitting). There are a
112 number of controls over where a word may be split, but note that there
113 is nothing language-specific (i.e., following a given language's rules
114 for where a word may be split). This is left to other packages.
115 There are hard coded minimums of 2 letters before the split, and 2
117 letters after the split. See "Hyphenate_basic.pm". Note that neither
118 hyphenation nor simple line splitting makes any attempt to prevent
119 widows and orphans, prevent splitting of the last word in a column or
120 page, or otherwise engage in paragraph shaping.
121 'hyphenate' => value
123 0: no hyphenation (default), 1: do basic hyphenation. Always allows
124 splitting at a soft hyphen (\xAD). Unicode hyphen (U+2010) and non-
125 splitting hyphen (U+2011) are ignored as split points.
126 'spHH' => value
128 0: do not split at a hard hyphen (x\2D), 1: OK to split (default)
129 'spOP' => value
131 0: do not split after most punctuation, 1: OK to split (default)
132 'spDR' => value
134 0: do not split after a run of one or more digits, 1: OK to split
135 (default)
136 'spLR' => value
138 0: do not split after a run of one or more ASCII letters, 1: OK to
139 split (default)
140 'spCC' => value
142 0: do not split in camelCase between a lowercase letter and an
143 uppercase letter, 1: OK to split (default)
144 'spRB' => value
146 0: do not split on a Required Blank ( ), is default. 1: OK to
147 split on Required Blank. Try to avoid this; it is a desperation
148 move!
149 'spFS' => value
151 0: do not split where it will just fit (middle of word!), is
152 default. 1: OK to split to just fit the available space. Try to
153 avoid this; it is a super desperation move, and the split will
154 probably make no linguistic sense!
155 'min_prefix' => value
157 Minimum number of letters before word split point (hyphenation
158 point). The default is 2.
159 'min_suffix' => value
161 Minimum number of letters after word split point (hyphenation
162 point). The default is 3.
163 Methods
165 ($width, $leftover) = $content->text_fill_left($string, $width, %opts)
167 Fill a line of 'width' with as much text as will fit, and outputs
168 it left justified. The width actually used, and the leftover text
169 (that didn't fit), are returned.
170 ($width, $leftover) = $content->text_fill($string, $width, %opts)
172 Alias for text_fill_left().
173 ($width, $leftover) = $content->text_fill_center($string, $width,
175 %opts)
176 Fill a line of 'width' with as much text as will fit, and outputs
177 it centered. The width actually used, and the leftover text (that
178 didn't fit), are returned.
179 ($width, $leftover) = $content->text_fill_right($string, $width, %opts)
181 Fill a line of 'width' with as much text as will fit, and outputs
182 it right justified. The width actually used, and the leftover text
183 (that didn't fit), are returned.
184 ($width, $leftover) = $content->text_fill_justified($string, $width,
186 %opts)
187 Fill a line of 'width' with as much text as will fit, and outputs
188 it fully justified (stretched or condensed). The width actually
189 used, and the leftover text (that didn't fit), are returned.
190 Note that the entire line is fit to the available width via a call
192 to "text_justified". See "text_justified" for options to control
193 stretch and condense. The last line is unjustified (normal size)
194 and left aligned by default, although the option
195 Options:
197 'last_align' => place
199 where place is 'left' (default), 'center', or 'right' (may be
200 shortened to first letter) allows you to specify the alignment
201 of the last line output.
202 Larger Text Segments
204 ($overflow_text, $unused_height) = $txt->paragraph($text,
205 $width,$height, $continue, %opts)
206 $overflow_text = $txt->paragraph($text, $width,$height, $continue,
207 %opts)
208 Print a single string into a rectangular area on the page, of given
209 width and maximum height. The baseline of the first (top) line is
210 at the current text position.
211 Apply the text within the rectangle and return any leftover text
213 (if could not fit all of it within the rectangle). If called in an
214 array context, the unused height is also returned (may be 0 or
215 negative if it just filled the rectangle).
216 If $continue is 1, the first line does not get special treatment
218 for indenting or outdenting, because we're printing the
219 continuation of the paragraph that was interrupted earlier. If it's
220 0, the first line may be indented or outdented.
221 Options:
223 'pndnt' => $indent
225 Give the amount of indent (positive) or outdent (negative, for
226 "hanging") for paragraph first lines). This setting is ignored
227 for centered text.
228 'align' => $choice
230 $choice is 'justified', 'right', 'center', 'left'; the default
231 is 'left'. See "text_justified" call for options to control
232 how a line is expanded or condensed if $choice is 'justified'.
233 $choice may be shortened to the first letter.
234 'last_align' => place
236 where place is 'left' (default), 'center', or 'right' (may be
237 shortened to first letter) allows you to specify the alignment
238 of the last line output, but applies only when "align" is
239 'justified'.
240 'underline' => $distance
242 'underline' => [ $distance, $thickness, ... ]
243 If a scalar, distance below baseline, else array reference with
244 pairs of distance and line thickness.
245 'spillover' => $over
247 Controls if words in a line which exceed the given width should
248 be "spilled over" the bounds, or if a new line should be used
249 for this word.
250 $over is 1 or 0, with the default 1 (spills over the width).
252 Example:
254 $txt->font($font,$fontsize);
256 $txt->leading($leading);
257 $txt->translate($x,$y);
258 $overflow = $txt->paragraph( 'long paragraph here ...',
259 $width,
260 $y+$leading-$bottom_margin );
261 Note: if you need to change any text treatment within a paragraph
263 (bold or italicized text, for instance), this can not handle it.
264 Only plain text (all the same font, size, etc.) can be typeset with
265 paragraph(). Also, there is currently very limited line splitting
266 (hyphenation) to better fit to a given width, and nothing is done
267 for "widows and orphans".
268 ($overflow_text, $continue, $unused_height) = $txt->section($text,
270 $width,$height, $continue, %opts)
271 $overflow_text = $txt->section($text, $width,$height, $continue, %opts)
272 The $text contains a string with one or more paragraphs $width
273 wide, starting at the current text position, with a newline \n
274 between each paragraph. Each paragraph is output (see "paragraph")
275 until the $height limit is met (a partial paragraph may be at the
276 bottom). Whatever wasn't output, will be returned. If called in an
277 array context, the unused height and the paragraph "continue" flag
278 are also returned.
279 $continue is 0 for the first call of section(), and then use the
281 value returned from the previous call (1 if a paragraph was cut in
282 the middle) to prevent unwanted indenting or outdenting of the
283 first line being printed.
284 For compatibility with recent changes to PDF::API2, paragraphs is
286 accepted as an alias for "section".
287 Options:
289 'pvgap' => $vertical
291 Additional vertical space (unit: pt) between paragraphs
292 (default 0). Note that this space will also be added after the
293 last paragraph printed.
294 See "paragraph" for other %opts you can use, such as "align" and
296 "pndnt".
297 $width = $txt->textlabel($x,$y, $font, $size, $text, %opts)
299 Place a line of text at an arbitrary "[$x,$y]" on the page, with
300 various text settings (treatments) specified in the call.
301 $font
303 A previously created font.
304 $size
306 The font size (points).
307 $text
309 The text to be printed (a single line).
310 Options:
312 'rotate' => $deg
314 Rotate $deg degrees counterclockwise from due East.
315 'color' => $cspec
317 A color name or permitted spec, such as "#CCE840", for the
318 character fill.
319 'strokecolor' => $cspec
321 A color name or permitted spec, such as "#CCE840", for the
322 character outline.
323 'charspace' => $cdist
325 Additional distance between characters.
326 'wordspace' => $wdist
328 Additional distance between words.
329 'hscale' => $hfactor
331 Horizontal scaling mode (percentage of normal, default is 100).
332 'render' => $mode
334 Character rendering mode (outline only, fill only, etc.). See
335 "render" call.
336 'left' => 1
338 Left align on the given point. This is the default.
339 'center' => 1
341 Center the text on the given point.
342 'right' => 1
344 Right align on the given point.
345 'align' => $placement
347 Alternate to left, center, and right. $placement is 'left'
348 (default), 'center', or 'right'.
349 Other options available to "text", such as underlining, can be used
351 here.
352 The width used (in points) is returned.
354 Please note that textlabel() was not designed to interoperate with
356 other text operations. It is a standalone operation, and does not leave
357 a "next write" position (or any other setting) for another "text" mode
358 operation. A following write will likely be at "(0,0)", and not at the
359 expected location.
360 textlabel() is intended as an "all in one" convenience function for
362 single lines of text, such as a label on some graphics, and not as part
363 of putting down multiple pieces of text. It is possible to figure out
364 the position of a following write (either "textlabel" or "text") by
365 adding the returned width to the original position's x value (assuming
366 left-justified positioning).
367 Complex Column Output with Markup
369 ($rc, $next_y, $unused) = $text->column($page, $text, $grfx, $markup,
370 $txt, %opts)
371 This method fills out a column of text on a page, returning any
372 unused portion that could not be fit, and where it left off on the
373 page.
374 Tag names, CSS entries, markup type, etc. are case-sensitive
376 (usually lower-case letters only). For example, you cannot give a
377 <P> paragraph in HTML or a P selector in CSS styling.
378 $page is the page context. Currently, its only use is for page
380 annotations for links ('md1' []() and 'html' <a>), so if you're not
381 using those, you may pass anything such as "undef" for $page if you
382 wish.
383 $text is the text context, so that various font and text-output
385 operations may be performed. It is often, but not necessarily
386 always, the same as the object containing the "column" method.
387 $grfx is the graphics (gfx) context. It may be a dummy (e.g.,
389 undef) if no graphics are to be drawn, but graphical items such as
390 the column outline ('outline' option) and horizontal rule (<hr> in
391 HTML markup) use it. Currently, text-decoration underline (default
392 for links, 'md1' "[]()" and 'html' "<a>") or line-through or
393 overline use the text context, but may in the future require a
394 valid graphics context. Images (when implemented) will require a
395 graphics context.
396 $markup is information on what sort of markup is being used to
398 format and lay out the column's text:
399 'pre'
401 The input material has already been processed and is already in
402 the desired form. $txt is an array reference to the list of
403 hashes. This must be used when you are calling column() a
404 second (or later) time to output material left over from the
405 first call. It may also be used when the caller application has
406 already processed the text into the appropriate format, and
407 other markup isn't being used.
408 'none'
410 If none is specified, there is no markup in use. At most, a
411 blank line or a new text array element specifies a new
412 paragraph, and that's it. $txt may be a single string, or an
413 array (list) of strings.
414 The input txt is a list (anonymous array reference) of strings,
416 each containing one or more paragraphs. A single string may
417 also be given. An empty line between paragraphs may be used to
418 separate the paragraphs. Paragraphs may not span array
419 elements.
420 'md1'
422 This specifies a certain flavor of Markdown compatible with
423 Text::Markdown:
424 * or _ italics, ** bold, *** bold+italic;
426 bulleted list *, numbered list 1. 2. etc.;
427 #, ## etc. headings and subheadings;
428 ---, ===, ___ horizontal rule;
429 [label](URL) external links (to HTML page or within this document, see 'a')
430 ` (backticks) enclose a "code" section
431 HTML (see below) may be mixed in as desired (although not
433 within "code" blocks marked by backticks, where <, >, and & get
434 turned into HTML entities, disabling the intended tags).
435 Markdown will be converted into HTML, which will then be
436 interpreted into PDF. Note that Text::Markdown may produce
437 HTML for certain features, that is not yet supported by HTML
438 processing (see 'html' section below). Let us know if you need
439 such a feature!
440 The input txt is a list (anonymous array reference) of strings,
442 each containing one or more paragraphs and other markup. A
443 single string may also be given. Per Markdown formatting, an
444 empty line between paragraphs may be used to separate the
445 paragraphs. Separate array elements will first be glued
446 together into a single string before processing, permitting
447 paragraphs to span array elements if desired.
448 There are other flavors of Markdown, so other mdn flavors may
450 be defined in the future, such as POD from Perl code.
451 'html'
453 This specifies that a subset of HTML markup is used, along with
454 some attributes and CSS. Currently, HTML tags
455 'i'/'em' (italic), 'b'/'strong' (bold),
457 'p' (paragraph),
458 'font' (font face->font-family, color, size->font-size),
459 'span' (needs style= attribute with CSS to do anything useful),
460 'ul', 'ol', 'li' (bulleted, numbered lists),
461 'img' (TBD, image, empty. hspace->margin-left/right,
462 vspace->margin-top/bottom, width, height),
463 'a' (anchor/link, web page URL or this document target #p[-x-y[-z]]),
464 'pre', 'code' (TBD, preformatted and code blocks),
465 'h1' through 'h6' (headings)
466 'hr' (horizontal rule)
467 'br' (TBD, line break, empty)
468 'sup', 'sub' (TBD superscript and subscript)
469 's', 'strike', 'del' (line-through)
470 'u', 'ins' (underline)
471 'ovl' (TBD -- non-HTML, overline)
472 'k' (TBD -- non-HTML, kerning left/right shift)
473 are supported (fully or in part unless "TBD"), along with
475 limited CSS for color, font-size, font-family, etc. <style>
476 tags may be placed in an optional <head> section, or within the
477 <body>. In the latter case, style tags will be pulled out of
478 the body and added (in order) on to the end of any style tag(s)
479 defined in a head section. Multiple style tags will be
480 condensed into a single collection (later definitions of equal
481 precedence overriding earlier). These stylings will have global
482 effect, as though they were defined in the head. As with normal
483 CSS, the hierarchy of a given property (in decreasing
484 precedence) is
485 appearance in a style= tag attribute
487 appearance in a tag attribute (possibly a different name than the property)
488 appearance in a #IDname selector in a <style>
489 appearance in a .classname selector in a <style>
490 appearance in a tag name selector in a <style>
491 Selectors are quite simple: a single tag name (e.g., body), a
493 single class (.cname), or a single ID (#iname). There are no
494 combinations (e.g., "p.abstract" or "ol, ul"), hierarchies
495 (e.g., "ol > li"), specified number of appearance, or other
496 such complications as found in a browser's CSS. Sorry!
497 Supported CSS properties:
499 color (foreground color)
501 display (inline/block)
502 font-family (name as defined to FontManager, e.g. Times)
503 font-size (pt, bare number = pt, % of current size)
504 font-style (normal/italic)
505 font-weight (normal/bold)
506 height (pt, bare number) thickness of horizontal rule
507 list-style-position (outside) TBD inside
508 list-style-type (marker description, see also _marker-before/after)
509 margin-top/right/bottom/left (pt, bare number = pt, % of font-size)
510 text-decoration (none, underline, line-through, overline)
511 text-height (leading, as ratio of baseline-spacing to font-size)
512 text-indent (pt, bare number = pt, % of current font-size)
513 width (pt, bare number) width of horizontal rule
514 Non-standard CSS "properties". You may want to set these in
516 CSS:
517 _marker-before (text to insert before <ol> marker, default nothing)
519 _marker-after (text to insert after <ol> marker, default period)
520 Non-standard CSS "properties". You normally would not set these
522 in CSS:
523 _fs (current running font size, in points, on the properties stack)
525 _href (URL for <a>, normally provided by href= attribute)
526 _left (running number of points to indent on the left, from margin-left and list nesting)
527 _right (running number of points to indent on the right, from margin-right)
528 Sizes may be '%' (of font-size), or 'pt' (the default unit).
530 More support may be added over time. CAUTION: comments /* and
531 */ are NOT currently supported in CSS -- perhaps in the future.
532 Numeric entities (decimal &#nnn; and hexadecimal &#xnnn;) are
534 supported, as well as named entities (— for example).
535 The input txt is a list (anonymous array reference) of strings,
537 each containing one or more paragraphs and other markup. A
538 single string may also be given. Per normal HTML practice,
539 paragraph tags should be used to mark paragraphs. Note that
540 HTML::TreeBuilder is configured to automatically mark top body-
541 level text with paragraph tags, in case you forget to do so,
542 although it is probably better to do it yourself, to maintain
543 more control over the processing. Separate array elements will
544 first be glued together into a single string before processing,
545 permitting paragraphs to span array elements if desired.
546 There are other markup languages out there, such as HTML-like
548 Pango, and man page (troff), that might be supported in the future.
549 It is very unlikely that TeX or LaTeX will ever be supported, as
550 they both already have excellent PDF output.
551 $txt is the input text: a string, an array reference to multiple
553 strings, or an array reference to hashes. See $markup for details.
554 %opts Options -- a number of these are of course, mandatory.
556 'rect' => [x, y, width, height]
558 This defines a column as a rectangular area of a given width
559 and height (both in points) on the current page. In the future,
560 it is expected that more elaborate non-rectangular areas will
561 be definable, but for now, a simple rectangle is all that is
562 permitted. The column's upper left coordinate is "x, y".
563 The top text baseline is assumed to be relative to the UL
565 corner (based on the determined line height), and the column
566 outline clips that baseline, as it does additional baselines
567 down the page (interline spacing is "leading" multiplied by the
568 largest "font_size" or image height needed on that line).
569 Currently, 'rect' is required, as it is the only column shape
571 supported.
572 'relative' => [ x, y, scale(s) ]
574 'relative' defaults to "[ 0, 0, 1, 1 ]", and allows a column
575 outline (currently only 'rect') to be either absolute or
576 relative. "x" and "y" are added to each "x,y" coordinate pair,
577 after scaling. Scaling values:
578 (none) The scaling defaults to 1 in both x and y dimensions
580 (no change).
581 scale (one value) The scaling in both the x (width) and y
582 (height) dimensions uses this value.
583 scale_x, scale_y (two values) There are two separate scaling
584 factors for the x dimension (width) and y dimension (height).
585 This permits a generically-shaped outline to be defined, scaled
587 (perhaps not preserving the aspect ratio) and placed anywhere
588 on the page. This could save you from having to define
589 similarly-shaped columns from scratch multiple times. If you
590 want to define a relative outline, the lower left corner
591 (whether or not it contains a point, and whether or not it's
592 the first one listed) would usually be "0, 0", to have scaling
593 work as expected. In other works, your outline template should
594 be in the lower left corner of the page.
595 'start_y' => $start_y
597 If omitted, it is assumed that you want to start at the top of
598 the defined column (the maximum "y" value minus the maximum
599 vertical extent of this line). If used, the normal value is
600 the "next_y" returned from the previous column() call. It is
601 the deepest extent reached by the previous line (plus leading),
602 and is the top-most point of the new first line of this
603 column() call.
604 Note that the "x" position will be determined by the column
606 shape and size (the left-most point of the baseline), so there
607 is no place to explicitly set an "x" position to start at.
608 'font_size' => $font_size
610 This is the starting font size (in points) to be used. Over the
611 course of the text, it may be modified by markup.
612 The starting font size may be set in a number of ways. It may
614 be inherited from a previous "$text->font(..., font-size)"
615 statement; it may be set via the "font_size" option (overriding
616 any font method inheritance); it may default to 12pt (if
617 neither explicit way is given). For HTML markup, it may of
618 course be modified by the "font" tag or by CSS styling
619 "font-size". For Markdown, it may be modified by CSS styling.
620 'marker_width' => $marker_width
622 This is the width of the gutter to the left of a list item,
623 where (for the first line of the item) the marker lives. The
624 marker contains the symbol (for bulleted/unordered lists) or
625 formatted number and "before" and "after" text (for
626 numbered/ordered lists). Both have a single space before the
627 item text starts. The number is a length, in points.
628 The default is 2 times the font_size passed to column(), and is
630 not adjusted for any changes of font_size in the markup. An
631 explicit value passed in is also not changed -- the gutter
632 width for the marker will be the same in all lists (keeping
633 them aligned). If you plan to have exceptionally long markers,
634 such as an ordered list of years in Roman numerals, such as
635 (MCMXCIX), you may want to make this gutter a bit wider.
636 'leading' => $leading
638 This is the leading ratio used throughout the column text. The
639 "$x, $y" position through "$x + width" is assumed to be the
640 first text baseline. The next line down will be "$y -
641 $leading*$font_size". If the font_size changes for any reason
642 over the course of the column, the baseline spacing (leading *
643 font_size) will also change. The default leading ratio is 1.125
644 (12.5% added to font).
645 'para' => [ $indent, $top-margin ]
647 When starting a new paragraph, these are the default
648 indentation (in points), and the extra vertical spacing for a
649 top margin on a paragraph. The default is "[ 1*$font_size, 0
650 ]". Either may be overridden by the appropriate CSS settings.
651 An outdent may be defined with a negative indentation value.
652 These apply to all $markup types.
653 'outline' => "color string"
655 You may optionaly request that the column be outlined in a
656 given color, to aid in debugging fitting problems.
657 'color' => "color string"
659 The color to draw the text (or rule or other graphic) in. The
660 default is black (#000000).
661 'style' => "CSS styling"
663 You may define CSS (selectors and properties lists) to override
664 the built-in CSS defaults. These will be applied for the entire
665 column() call. You can use this, or "style" tags in 'html', but
666 for 'none' or 'md1', you will need to use this method to set
667 styling.
668 'substitute' => [ [ 'char or string', 'before', 'replace',
670 'after'],... ]
671 When a certain Unicode code point (character) or string is
672 found, insert before text before the character, replace the
673 character or string with replace text, and insert after text
674 after the character. This may make it easier to insert HTML
675 code (font, color, etc.) into Markdown text, if the desired
676 settings and character can not be produced by your Markdown
677 editor. This applies both to 'md1' and 'html' markup. Multiple
678 substitutions may be defined via multiple array elements. If
679 you want to leave the original character or string itself
680 unchanged, you should define the replace text to be the same as
681 'char or string'. 'before' and/or 'after' text may be empty
682 strings if you don't want to insert some sort of markup there.
683 Example: to insert a red cross (X-out) and green tick (check)
685 mark
686 'substitute' => [
688 [ '%cross%', '<font face="ZapfDingbats" color="red">', '8', '</font>' ],
689 [ '%tick%', '<font face="ZapfDingbats" color="green">', '4', '</font>' ],
690 ]
691 should change "%cross%" in Markdown text ('md1') or HTML text
693 ('html') to "<font face="ZapfDingbats" color="green">8</font>"
694 and similarly for "%tick%". This is done after the Markdown is
695 converted to HTML (but before HTML is parsed), so make sure
696 that your macro text (e.g., "%tick%") isn't something that
697 Markdown will try to interpret by itself! Also, Perl's regular
698 expression parser seems to get upset with some characters, such
699 as "|", so don't use them as delimiters (e.g., "|cross|"). You
700 don't have to wrap your macro name in delimiters, but it can
701 make the text structure clearer, and may be necessary in order
702 not to do substitutions in the wrong place.
703 'restore' => flag
705 This integer flag determines what sort of cleanup column() will
706 do upon exit, to restore (or not) the font state (face, bold or
707 normal weight, italic or normal style, size, and color).
708 for rc = 0 (all input markup was used up, without running out
710 of column)
711 restore => 0
712 This is the default. Upon exiting, column() will
713 attempt to restore the state to what one would see if
714 there was yet more text to be output. Note that this is
715 not necessarily what one would see if the entire state
716 was restored to entry conditions. The intent is that
717 another column() call can be immediately made, using
718 whatever font state was left by the previous call, as
719 though the two calls' markup inputs were concatenated.
720 restore => 1
722 This value of "restore" commands that no change be made
723 to the font state, that is, column() exits with the
724 font state left in the last text output. This may or
725 may not be desirable, especially if the last text
726 output left the text in an unexpected state.
727 restore => 2
729 This value of "restore" attempts to bring the font
730 state all the way back to what it was upon entry to the
731 routine, as if it had never been called. Note that if
732 column() was called with no global font settings, that
733 can not be undone, although the color can be changed
734 back to its original state, usually black.
735 CAUTION: The Font Manager is not synchronized with
737 whatever state the font is returned to. You should not
738 request the 'current' font, but should instead
739 explicitly set it to a specific face, etc., which
740 resets 'current'.
741 for rc = 1 (ran out of column space before all the input markup
743 was used up)
744 restore => 0
745 This is the default. Upon exiting, no changes will be
746 made to the font state. As the code will be in the
747 middle of some output, the font state is kept the same,
748 so the next column() call (for the overflow) can pick
749 up where the previous call left off, with regards to
750 the font state.
751 It is equivalent to "restore = 1".
753 restore => 1
755 This is the same as "restore = 0".
756 restore => 2
758 This value of "restore" attempts to bring the font
759 state all the way back to what it was upon entry to the
760 routine, as if it had never been called. Note that if
761 column() was called with no global font settings, that
762 can not be undone, although the color can be changed
763 back to its original state, usually black.
764 CAUTION: The Font Manager is not synchronized with
766 whatever state the font is returned to. You should not
767 request the 'current' font, but should instead
768 explicitly set it to a specific face, etc., which
769 resets 'current'.
770 The Font Manager system is used to supply the requested fonts, so
772 it is up to the application to pre-load the desired font
773 information before column() is called. Any request to change the
774 encoding within column() will be ignored, as the fonts have already
775 been specified for a specific encoding. Needless to say, the
776 encoding used in creating the input text needs to match the
777 specified font encoding.
778 Absent any markup changing the font face or styling, whatever is
780 defined by Font Manager as the current font will be what is used.
781 This way, you may inherit the font from the previous column(), or
782 call "$text-"font($pdf->get_font(), size)> to set both the font and
783 size, or just call "$pdf-"get_font()> to set only the font, relying
784 on the "font_size" option or CSS markup to set the size.
785 Line fitting (paragraph shaping) is currently quite primitive.
787 Words will not be split (hyphenated). It is planned to eventually
788 add Knuth-Plass paragraph shaping, along with proper language-
789 dependent hyphenation.
790 Each change of font automatically supplies its maximum ascender and
792 minimum descender, the extents above and below the text line's
793 baseline. Each block of text with a given face and variant, or
794 change of font size, will be given the same vertical extents -- the
795 extents are font-wide, and not determined on a per-glyph basis. So,
796 unfortunately, a block of text "acemnorsuvwz" will have the same
797 vertical extents as a block of text "bdfghijklpqty". For a given
798 line of text, the highest ascender and the lowest descender (plus
799 leading) will be used to position the line at the appropriate
800 distance below the previous line (or the top of the column). No
801 attempt is made to "fit" projections into recesses (jigsaw-puzzle
802 like). If there is an inset into the side of a column, or it is
803 otherwise not a straight vertical line, so long as the baseline
804 fits within the column outline, no check is made whether descenders
805 or ascenders will fall outside the defined column (i.e., project
806 into the inset). We suggest that you try to keep font sizes fairly
807 consistent, to keep reasonably consistent text vertical extents.
808 Data returned by this call
810 If there is more text than can be accommodated by the column size,
812 the unused portion is returned, with a return code of 1. It is an
813 empty list if all the text could be formatted, and the return code
814 is 0. "next_y" is the y coordinate where any additional text
815 (column() call) could be added to a column (as "start_y") that
816 wasn't completely filled. This would be at the starting point of a
817 new column (i.e., the last paragraph is ended). Note that the
818 application code should check if this position is too far down the
819 page (in the bottom margin) and not blindly use it! Also, as 'md1'
820 is first converted to HTML, any unused portion will be returned as
821 'pre' markup, rather than Markdown or HTML. Be sure to specify
822 'pre' for any continuation of the column (with one or more
823 additional column() calls), rather than 'none', 'md1', or 'html'.
824 $rc The return code.
826 '0' A return code of 0 indicates that the call completed, while
828 using up all the input $txt. It did not run out of defined
829 column space.
830 NOTE: if "restore" has a value of 1, the column() call
832 makes no effort to "restore" conditions to any starting
833 values. If your last bit of text left the "current" font
834 with some "odd" face/family, size, italicized, bolded, or
835 colored; that will be what is used by the next column call
836 (or other PDF::Builder text calls). This is done in order
837 to allow you to easily chain from one column to the next,
838 without having to manually tell the system what font,
839 color, etc. you want to return to. On the other hand, in
840 some cases you may want to start from the same initial
841 coditions as usual. You may want to add get_font(), font(),
842 fillcolor(), and strokecolor() calls as necessary before
843 the next text output, to get the expected text
844 characteristics. Or, you can simply let "restore" default
845 to 0 to get the same effect.
846 '1' A return code of 1 indicates that the call completed by
848 filling up the defined column space. It did not run out of
849 input $txt. You will need to make one or more calls with
850 empty column space (to fill), to use up the remaining input
851 text (with "pre" $markup).
852 If "restore" defaults to 0 (or is set to 1), the text
854 settings in the "current" font are left as-is, so that
855 whatever you were doing when you ran out of defined column
856 (as regards to font face/family, size, italic and bold
857 states, and color) should automatically be the same when
858 you make the next column() call to make more output.
859 Additional return codes may be added in the future, to indicate
861 failures of one sort or another.
862 $next_y
864 The next page "y" coordinate to start at, if using the same
865 column definition as the previous column() definition did
866 (i.e., you didn't completely fill the column, and received a
867 return code of 0). In that case, $next_y would give the page
868 "y" coordinate to pass to column() (as "start_y") to start a
869 new paragraph at.
870 If the return code $rc was 1 (column was used up), the $next_y
872 returned will be -1, as it would be meaningless to use it.
873 $unused
875 This is the unused portion of the input text (return code $rc
876 is 1), in a format ("pre" $markup) suitable for input as $txt.
877 It will be a reference to an array of hashes.
878 If $rc is 0 (all input was used up), $unused is an empty
880 anonymous array. It contains nothing to be used.
881perl v5.36.0 2023-01-23 PDF::Builder::Content::Text(3)