|
|
| |
PDF::Builder::Content::Text(3) |
User Contributed Perl Documentation |
PDF::Builder::Content::Text(3) |
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::API2 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()).
- $width = $content->text_left($text, %opts)
- $width = $content->text_left($text)
- Alias for "text". Implemented for
symmetry, for those who use a lot of
"text_center" and
"text_right", and desire a
"text_left".
Adds text to the page (left justified). 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.
- $width = $content->text_center($text, %opts)
- $width = $content->text_center($text)
- As "text", but centered on the current
point.
Adds text to the page (centered). The width used (in points)
is returned.
- $width = $content->text_right($text, %opts)
- $width = $content->text_right($text)
- 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.
- $width = $content->text_justified($text, $width, %opts)
- $width = $content->text_justified($text, $width)
- 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.
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 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)
Methods
- ($width, $leftover) = $content->text_fill_left($string, $width,
%opts)
- ($width, $leftover) = $content->text_fill_left($string, $width)
- 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)
- ($width, $leftover) = $content->text_fill($string, $width)
- Alias for text_fill_left().
- ($width, $leftover) = $content->text_fill_center($string, $width,
%opts)
- ($width, $leftover) = $content->text_fill_center($string, $width)
- 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.
- ($width, $leftover) = $content->text_fill_right($string, $width,
%opts)
- ($width, $leftover) = $content->text_fill_right($string, $width)
- 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.
- ($width, $leftover) = $content->text_fill_justified($string, $width,
%opts)
- ($width, $leftover) = $content->text_fill_justified($string,
$width)
- 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.
- ($overflow_text, $unused_height) = $txt->paragraph($text,
$width,$height, $continue, %opts)
- ($overflow_text, $unused_height) = $txt->paragraph($text,
$width,$height, $continue)
- $overflow_text = $txt->paragraph($text, $width,$height, $continue,
%opts)
- $overflow_text = $txt->paragraph($text, $width,$height, $continue)
- 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).
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".
- ($overflow_text, $continue, $unused_height) = $txt->section($text,
$width,$height, $continue, %opts)
- ($overflow_text, $continue, $unused_height) = $txt->section($text,
$width,$height, $continue)
- $overflow_text = $txt->section($text, $width,$height, $continue,
%opts)
- $overflow_text = $txt->section($text, $width,$height, $continue)
- 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.
- $width = $txt->textlabel($x,$y, $font, $size, $text, %opts)
- $width = $txt->textlabel($x,$y, $font, $size, $text)
- 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).
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |