PDF::Builder::Content::Text(3) User Contributed Perl Documentation NAME 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::Builder 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()). METHODS Single Lines from a String text_left $width = $content->text_left($text, %opts) Alias for "text". Implemented for symmetry, for those who use a lot of "text_center" and "text_right", and desire a matching "text_left". Adds text to the page (left justified), at the current position. Note that there is no maximum width, and nothing to keep you from overflowing the physical page on the right! The width used (in points) is returned. text_center $width = $content->text_center($text, %opts) As "text", but centered on the current point. Adds text to the page (centered). The width used (in points) is returned. text_right $width = $content->text_right($text, %opts) As "text", but right-aligned to the current point. Adds text to the page (right justified). Note that there is no maximum width, and nothing to keep you from overflowing the physical page on the left! The width used (in points) is returned. text_justified $width = $content->text_justified($text, $width, %opts) 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. The unchanged $width is returned, unless there was some reason to change it (e.g., overflow). Options: 'nocs' => value If this option value is 1 (default 0), do not use any intercharacter spacing. This is useful for connected characters, such as fonts for Arabic, Devanagari, Latin cursive handwriting, etc. You don't want to add additional space between characters during justification, which would disconnect them. Word (interword) spacing values (explicit or default) are doubled if nocs is 1. This is to make up for the lack of added/subtracted intercharacter spacing. 'wordsp' => value The percentage of one space character (default 100) that is the maximum amount to add to (each) interword spacing to expand the line. If "nocs" is 1, double "value". 'charsp' => value 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 "nocs" is 1, force "value" to 0. 'wordspa' => value 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 "nocs" is 1, double "value". 'charspa' => value 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. If "nocs" is 1, force "value" to 0. 'condw' => value The percentage of one space character (default 25) that is the maximum amount to subtract from (each) interword spacing to condense the line. If "nocs" is 1, double "value". 'condc' => value 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 "nocs" is 1, force "value" to 0. 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. Multiple Lines from a String 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. Hyphenation 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 more desirable paragraph shaping. 'hyphenate' => value 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. 'spHH' => value 0: do not split at a hard hyphen (x\2D), 1: OK to split (default) 'spOP' => value 0: do not split after most punctuation, 1: OK to split (default) 'spDR' => value 0: do not split after a run of one or more digits, 1: OK to split (default) 'spLR' => value 0: do not split after a run of one or more ASCII letters, 1: OK to split (default) 'spCC' => value 0: do not split in camelCase between a lowercase letter and an uppercase letter, 1: OK to split (default) 'spRB' => value 0: do not split on a Required Blank ( ), is default. 1: OK to split on Required Blank. Try to avoid this; it is a desperation move! 'spFS' => value 0: do not split where it will just fit (middle of word!), is default. 1: OK to split to just fit the available space. Try to avoid this; it is a super desperation move, and the split will probably make no linguistic sense! 'min_prefix' => value Minimum number of letters before word split point (hyphenation point). The default is 2. 'min_suffix' => value Minimum number of letters after word split point (hyphenation point). The default is 3. Methods text_fill_left, text_fill ($width, $leftover) = $content->text_fill_left($string, $width, %opts) 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. ($width, $leftover) = $content->text_fill($string, $width, %opts) Alias for text_fill_left(). text_fill_center ($width, $leftover) = $content->text_fill_center($string, $width, %opts) 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. text_fill_right ($width, $leftover) = $content->text_fill_right($string, $width, %opts) 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. text_fill_justified ($width, $leftover) = $content->text_fill_justified($string, $width, %opts) 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". See "text_justified" for options to control stretch and condense. The last line is unjustified (normal size) and left aligned by default, although the option Options: 'last_align' => place where place is 'left' (default), 'center', or 'right' (may be shortened to first letter) allows you to specify the alignment of the last line output. Larger Text Segments paragraph ($overflow_text, $unused_height) = $txt->paragraph($text, $width,$height, $continue, %opts) ($overflow_text, $unused_height) = $txt->paragraph($text, $width,$height, %opts) $overflow_text = $txt->paragraph($text, $width,$height, $continue, %opts) $overflow_text = $txt->paragraph($text, $width,$height, %opts) 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). $continue is optional, with a default value of 0. An %opts list may be given after the fixed parameters, whether or not $continue is explicitly given. 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. Options: 'pndnt' => $indent Give the amount of indent (positive) or outdent (negative, for "hanging") for paragraph first lines). This setting is ignored for centered text. 'align' => $choice $choice is 'justified', 'right', 'center', 'left'; the default is 'left'. See "text_justified" call for options to control how a line is expanded or condensed if $choice is 'justified'. $choice may be shortened to the first letter. 'last_align' => place where place is 'left' (default), 'center', or 'right' (may be shortened to first letter) allows you to specify the alignment of the last line output, but applies only when "align" is 'justified'. 'underline' => $distance 'underline' => [ $distance, $thickness, ... ] If a scalar, distance below baseline, else array reference with pairs of distance and line thickness. 'spillover' => $over 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). Example: $txt->font($font,$fontsize); $txt->leading($leading); $txt->translate($x,$y); $overflow = $txt->paragraph( 'long paragraph here ...', $width, $y+$leading-$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 (hyphenation) to better fit to a given width, and nothing is done for "widows and orphans". section, paragraphs ($overflow_text, $continue, $unused_height) = $txt->section($text, $width,$height, $continue, %opts) $overflow_text = $txt->section($text, $width,$height, $continue, %opts) 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. $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. For compatibility with recent changes to PDF::API2, paragraphs is accepted as an alias for "section". Options: 'pvgap' => $vertical 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". Alternate name: paragraphs This is for compatibiity with PDF::API2. textlabel $width = $txt->textlabel($x,$y, $font, $size, $text, %opts) Place a line of text at an arbitrary "[$x,$y]" on the page, with various text settings (treatments) specified in the call. $font A previously created font. $size The font size (points). $text The text to be printed (a single line). Options: 'rotate' => $deg Rotate $deg degrees counterclockwise from due East. 'color' => $cspec A color name or permitted spec, such as "#CCE840", for the character fill. 'strokecolor' => $cspec A color name or permitted spec, such as "#CCE840", for the character outline. 'charspace' => $cdist Additional distance between characters. 'wordspace' => $wdist Additional distance between words. 'hscale' => $hfactor Horizontal scaling mode (percentage of normal, default is 100). 'render' => $mode Character rendering mode (outline only, fill only, etc.). See "render" call. 'left' => 1 Left align on the given point. This is the default. 'center' => 1 Center the text on the given point. 'right' => 1 Right align on the given point. 'align' => $placement Alternate to left, center, and right. $placement is 'left' (default), 'center', or 'right'. Other options available to "text", such as underlining, can be used here. The width used (in points) is returned. Please note that textlabel() was not designed to interoperate with other text operations. It is a standalone operation, and does not leave a "next write" position (or any other setting) for another "text" mode operation. A following write will likely be at "(0,0)", and not at the expected location. textlabel() is intended as an "all in one" convenience function for single lines of text, such as a label on some graphics, and not as part of putting down multiple pieces of text. It is possible to figure out the position of a following write (either "textlabel" or "text") by adding the returned width to the original position's x value (assuming left-justified positioning). Complex Column Output with Markup column ($rc, $next_y, $unused) = $text->column($page, $text, $grfx, $markup, $txt, %opts) This method fills out a column of text on a page, returning any unused portion that could not be fit, and where it left off on the page. Tag names, CSS entries, markup type, etc. are case-sensitive (usually lower-case letters only). For example, you cannot give a

paragraph in HTML or a P selector in CSS styling. $page is the page context. Currently, its only use is for page annotations for links ('md1' []() and 'html' ), so if you're not using those, you may pass anything such as "undef" for $page if you wish. $text is the text context, so that various font and text-output operations may be performed. It is often, but not necessarily always, the same as the object containing the "column" method. $grfx is the graphics (gfx) context. It may be a dummy (e.g., undef) if no graphics are to be drawn, but graphical items such as the column outline ('outline' option) and horizontal rule (

in HTML markup) use it. Currently, text-decoration underline (default for links, 'md1' "[]()" and 'html' "") or line-through or overline use the text context, but may in the future require a valid graphics context. Images (when implemented) will require a graphics context. $markup is information on what sort of markup is being used to format and lay out the column's text: 'pre' The input material has already been processed and is already in the desired form. $txt is an array reference to the list of hashes. This must be used when you are calling column() a second (or later) time to output material left over from the first call. It may also be used when the caller application has already processed the text into the appropriate format, and other markup isn't being used. 'none' If none is specified, there is no markup in use. At most, a blank line or a new text array element specifies a new paragraph, and that's it. $txt may be a single string, or an array (list) of strings. The input txt is a list (anonymous array reference) of strings, each containing one or more paragraphs. A single string may also be given. An empty line between paragraphs may be used to separate the paragraphs. Paragraphs may not span array elements. 'md1' This specifies a certain flavor of Markdown compatible with Text::Markdown: * or _ italics, ** bold, *** bold+italic; bulleted list *, numbered list 1. 2. etc.; #, ## etc. headings and subheadings; ---, ===, ___ horizontal rule; [label](URL) external links (to HTML page or within this document, see 'a') ` (backticks) enclose a "code" section HTML (see below) may be mixed in as desired (although not within "code" blocks marked by backticks, where <, >, and & get turned into HTML entities, disabling the intended tags). Markdown will be converted into HTML, which will then be interpreted into PDF. Note that Text::Markdown may produce HTML for certain features, that is not yet supported by HTML processing (see 'html' section below). Let us know if you need such a feature! The input txt is a list (anonymous array reference) of strings, each containing one or more paragraphs and other markup. A single string may also be given. Per Markdown formatting, an empty line between paragraphs may be used to separate the paragraphs. Separate array elements will first be glued together into a single string before processing, permitting paragraphs to span array elements if desired. There are other flavors of Markdown, so other mdn flavors may be defined in the future, such as POD from Perl code. 'html' This specifies that a subset of HTML markup is used, along with some attributes and CSS. Currently, HTML tags 'i'/'em' (italic), 'b'/'strong' (bold), 'p' (paragraph), 'font' (font face->font-family, color, size->font-size), 'span' (needs style= attribute with CSS to do anything useful), 'ul', 'ol', 'li' (bulleted, numbered lists), 'img' (TBD, image, empty. hspace->margin-left/right, vspace->margin-top/bottom, width, height), 'a' (anchor/link, web page URL or this document target #p[-x-y[-z]]), 'pre', 'code' (TBD, preformatted and code blocks), 'h1' through 'h6' (headings) 'hr' (horizontal rule) 'br' (TBD, line break, empty) 'sup', 'sub' (TBD superscript and subscript) 's', 'strike', 'del' (line-through) 'u', 'ins' (underline) 'ovl' (TBD -- non-HTML, overline) 'k' (TBD -- non-HTML, kerning left/right shift) 'blockquote' (block quote) are supported (fully or in part unless "TBD"), along with limited CSS for color, font-size, font-family, etc.