.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PDF::Builder::Content::Text 3pm"
.TH PDF::Builder::Content::Text 3pm "2021-03-28" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PDF::Builder::Content::Text \- additional specialized text\-related formatting methods. Inherits from PDF::Builder::Content
.PP
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()).
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$width = $content\->text_left($text, %opts)" 4
.el .IP "\f(CW$width\fR = \f(CW$content\fR\->text_left($text, \f(CW%opts\fR)" 4
.IX Item "$width = $content->text_left($text, %opts)"
.PD 0
.ie n .IP "$width = $content\->text_left($text)" 4
.el .IP "\f(CW$width\fR = \f(CW$content\fR\->text_left($text)" 4
.IX Item "$width = $content->text_left($text)"
.PD
Alias for \f(CW\*(C`text\*(C'\fR. Implemented for symmetry, for those who use a lot of
\&\f(CW\*(C`text_center\*(C'\fR and \f(CW\*(C`text_right\*(C'\fR, and desire a \f(CW\*(C`text_left\*(C'\fR.
.Sp
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 \fBreturned\fR.
.ie n .IP "$width = $content\->text_center($text, %opts)" 4
.el .IP "\f(CW$width\fR = \f(CW$content\fR\->text_center($text, \f(CW%opts\fR)" 4
.IX Item "$width = $content->text_center($text, %opts)"
.PD 0
.ie n .IP "$width = $content\->text_center($text)" 4
.el .IP "\f(CW$width\fR = \f(CW$content\fR\->text_center($text)" 4
.IX Item "$width = $content->text_center($text)"
.PD
As \f(CW\*(C`text\*(C'\fR, but centered on the current point.
.Sp
Adds text to the page (centered). 
The width used (in points) is \fBreturned\fR.
.ie n .IP "$width = $content\->text_right($text, %opts)" 4
.el .IP "\f(CW$width\fR = \f(CW$content\fR\->text_right($text, \f(CW%opts\fR)" 4
.IX Item "$width = $content->text_right($text, %opts)"
.PD 0
.ie n .IP "$width = $content\->text_right($text)" 4
.el .IP "\f(CW$width\fR = \f(CW$content\fR\->text_right($text)" 4
.IX Item "$width = $content->text_right($text)"
.PD
As \f(CW\*(C`text\*(C'\fR, but right-aligned to the current point.
.Sp
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 \fBreturned\fR.
.ie n .IP "$width = $content\->text_justified($text, $width, %opts)" 4
.el .IP "\f(CW$width\fR = \f(CW$content\fR\->text_justified($text, \f(CW$width\fR, \f(CW%opts\fR)" 4
.IX Item "$width = $content->text_justified($text, $width, %opts)"
.PD 0
.ie n .IP "$width = $content\->text_justified($text, $width)" 4
.el .IP "\f(CW$width\fR = \f(CW$content\fR\->text_justified($text, \f(CW$width\fR)" 4
.IX Item "$width = $content->text_justified($text, $width)"
.PD
As \f(CW\*(C`text\*(C'\fR, but stretches text (using \f(CW\*(C`wordspace\*(C'\fR, \f(CW\*(C`charspace\*(C'\fR, and (as a  
last resort) \f(CW\*(C`hscale\*(C'\fR) to fill the desired
(available) \f(CW$width\fR. Note that if the desired width is \fIless\fR than the
natural width taken by the text, it will be \fIcondensed\fR to fit, using the
same three routines.
.Sp
The unchanged \f(CW$width\fR is \fBreturned\fR, unless there was some reason to
change it (e.g., overflow).
.Sp
\&\fBOptions:\fR
.RS 4
.IP "\-nocs => value" 4
.IX Item "-nocs => value"
If this option value is 1 (default 0), do \fBnot\fR 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.
.Sp
\&\fIWord\fR (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.
.IP "\-wordsp => value" 4
.IX Item "-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 \f(CW\*(C`\-nocs\*(C'\fR is 1, double \f(CW\*(C`value\*(C'\fR.
.IP "\-charsp => value" 4
.IX Item "-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 \f(CW\*(C`\-nocs\*(C'\fR is 1, force \f(CW\*(C`value\*(C'\fR to 0.
.IP "\-wordspa => value" 4
.IX Item "-wordspa => value"
If adding intercharacter space didn't do enough, the percentage of one space
character (default 100) that is the maximum \fIadditional\fR amount to add to 
(each) interword spacing to further expand the line.
If \f(CW\*(C`\-nocs\*(C'\fR is 1, double \f(CW\*(C`value\*(C'\fR.
.IP "\-charspa => value" 4
.IX Item "-charspa => value"
If adding more interword space didn't do enough, the percentage of one em 
(default 100) that is the maximum \fIadditional\fR amount to add to (each) 
intercharacter spacing to further expand the line.
If \f(CW\*(C`\-nocs\*(C'\fR is 1, force \f(CW\*(C`value\*(C'\fR to 0.
.IP "\-condw => value" 4
.IX Item "-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 \f(CW\*(C`\-nocs\*(C'\fR is 1, double \f(CW\*(C`value\*(C'\fR.
.IP "\-condc => value" 4
.IX Item "-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 \f(CW\*(C`\-nocs\*(C'\fR is 1, force \f(CW\*(C`value\*(C'\fR to 0.
.RE
.RS 4
.Sp
If expansion (or reduction) wordspace and charspace changes didn't do enough 
to make the line fit the desired width, use \f(CW\*(C`hscale()\*(C'\fR to finish expanding or 
condensing the line to fit.
.RE
.SS "Multiple Lines from a String"
.IX Subsection "Multiple Lines from a String"
The string is split at regular blanks (spaces), x20, to find the longest 
substring that will fit the \f(CW$width\fR. 
If a single word is longer than \f(CW$width\fR, it will overflow. 
To stay strictly within the desired bounds, set the option
\&\f(CW\*(C`\-spillover\*(C'\fR=>0 to disallow spillover.
.PP
\fIHyphenation\fR
.IX Subsection "Hyphenation"
.PP
If hyphenation is enabled, those methods which split up a string into multiple
lines (the \*(L"text fill\*(R", paragraph, and section methods) will attempt to split
up the word that overflows the line, in order to pack the text even more
tightly (\*(L"greedy\*(R" 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.
.PP
There are hard coded minimums of 2 letters before the split, and 2 letters after
the split. See \f(CW\*(C`Hyphenate_basic.pm\*(C'\fR. 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 
\&\fIparagraph shaping\fR.
.IP "\-hyphenate => value" 4
.IX Item "-hyphenate => value"
0: no hyphenation (\fBdefault\fR), 1: do basic hyphenation. Always allows
splitting at a soft hyphen (\exAD). Unicode hyphen (U+2010) and non-splitting
hyphen (U+2011) are ignored as split points.
.IP "\-spHH => value" 4
.IX Item "-spHH => value"
0: do \fInot\fR split at a hard hyphen (x\e2D), 1: \fI\s-1OK\s0 to split\fR (\fBdefault\fR)
.IP "\-spOP => value" 4
.IX Item "-spOP => value"
0: do \fInot\fR split after most punctuation, 1: \fI\s-1OK\s0 to split\fR (\fBdefault\fR)
.IP "\-spDR => value" 4
.IX Item "-spDR => value"
0: do \fInot\fR split after a run of one or more digits, 1: \fI\s-1OK\s0 to split\fR (\fBdefault\fR)
.IP "\-spLR => value" 4
.IX Item "-spLR => value"
0: do \fInot\fR split after a run of one or more \s-1ASCII\s0 letters, 1: \fI\s-1OK\s0 to split\fR (\fBdefault\fR)
.IP "\-spCC => value" 4
.IX Item "-spCC => value"
0: do \fInot\fR split in camelCase between a lowercase letter and an
uppercase letter, 1: \fI\s-1OK\s0 to split\fR (\fBdefault\fR)
.PP
\fIMethods\fR
.IX Subsection "Methods"
.ie n .IP "($width, $leftover) = $content\->text_fill_left($string, $width, %opts)" 4
.el .IP "($width, \f(CW$leftover\fR) = \f(CW$content\fR\->text_fill_left($string, \f(CW$width\fR, \f(CW%opts\fR)" 4
.IX Item "($width, $leftover) = $content->text_fill_left($string, $width, %opts)"
.PD 0
.ie n .IP "($width, $leftover) = $content\->text_fill_left($string, $width)" 4
.el .IP "($width, \f(CW$leftover\fR) = \f(CW$content\fR\->text_fill_left($string, \f(CW$width\fR)" 4
.IX Item "($width, $leftover) = $content->text_fill_left($string, $width)"
.PD
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 \fBreturned\fR.
.ie n .IP "($width, $leftover) = $content\->text_fill($string, $width, %opts)" 4
.el .IP "($width, \f(CW$leftover\fR) = \f(CW$content\fR\->text_fill($string, \f(CW$width\fR, \f(CW%opts\fR)" 4
.IX Item "($width, $leftover) = $content->text_fill($string, $width, %opts)"
.PD 0
.ie n .IP "($width, $leftover) = $content\->text_fill($string, $width)" 4
.el .IP "($width, \f(CW$leftover\fR) = \f(CW$content\fR\->text_fill($string, \f(CW$width\fR)" 4
.IX Item "($width, $leftover) = $content->text_fill($string, $width)"
.PD
Alias for \fBtext_fill_left()\fR.
.ie n .IP "($width, $leftover) = $content\->text_fill_center($string, $width, %opts)" 4
.el .IP "($width, \f(CW$leftover\fR) = \f(CW$content\fR\->text_fill_center($string, \f(CW$width\fR, \f(CW%opts\fR)" 4
.IX Item "($width, $leftover) = $content->text_fill_center($string, $width, %opts)"
.PD 0
.ie n .IP "($width, $leftover) = $content\->text_fill_center($string, $width)" 4
.el .IP "($width, \f(CW$leftover\fR) = \f(CW$content\fR\->text_fill_center($string, \f(CW$width\fR)" 4
.IX Item "($width, $leftover) = $content->text_fill_center($string, $width)"
.PD
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 \fBreturned\fR.
.ie n .IP "($width, $leftover) = $content\->text_fill_right($string, $width, %opts)" 4
.el .IP "($width, \f(CW$leftover\fR) = \f(CW$content\fR\->text_fill_right($string, \f(CW$width\fR, \f(CW%opts\fR)" 4
.IX Item "($width, $leftover) = $content->text_fill_right($string, $width, %opts)"
.PD 0
.ie n .IP "($width, $leftover) = $content\->text_fill_right($string, $width)" 4
.el .IP "($width, \f(CW$leftover\fR) = \f(CW$content\fR\->text_fill_right($string, \f(CW$width\fR)" 4
.IX Item "($width, $leftover) = $content->text_fill_right($string, $width)"
.PD
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 \fBreturned\fR.
.ie n .IP "($width, $leftover) = $content\->text_fill_justified($string, $width, %opts)" 4
.el .IP "($width, \f(CW$leftover\fR) = \f(CW$content\fR\->text_fill_justified($string, \f(CW$width\fR, \f(CW%opts\fR)" 4
.IX Item "($width, $leftover) = $content->text_fill_justified($string, $width, %opts)"
.PD 0
.ie n .IP "($width, $leftover) = $content\->text_fill_justified($string, $width)" 4
.el .IP "($width, \f(CW$leftover\fR) = \f(CW$content\fR\->text_fill_justified($string, \f(CW$width\fR)" 4
.IX Item "($width, $leftover) = $content->text_fill_justified($string, $width)"
.PD
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 \fBreturned\fR.
.Sp
Note that the entire line is fit to the available 
width via a call to \f(CW\*(C`text_justified\*(C'\fR. 
See \f(CW\*(C`text_justified\*(C'\fR for options to control stretch and condense.
The last line is unjustified (normal size) and left aligned by default, 
although the option
.Sp
\&\fBOptions:\fR
.RS 4
.IP "\-last_align => place" 4
.IX Item "-last_align => place"
where place is 'left' (default), 'center', or 'right' allows you to specify
the alignment of the last line output.
.RE
.RS 4
.RE
.ie n .IP "($overflow_text, $unused_height) = $txt\->paragraph($text, $width,$height, $continue, %opts)" 4
.el .IP "($overflow_text, \f(CW$unused_height\fR) = \f(CW$txt\fR\->paragraph($text, \f(CW$width\fR,$height, \f(CW$continue\fR, \f(CW%opts\fR)" 4
.IX Item "($overflow_text, $unused_height) = $txt->paragraph($text, $width,$height, $continue, %opts)"
.PD 0
.ie n .IP "($overflow_text, $unused_height) = $txt\->paragraph($text, $width,$height, $continue)" 4
.el .IP "($overflow_text, \f(CW$unused_height\fR) = \f(CW$txt\fR\->paragraph($text, \f(CW$width\fR,$height, \f(CW$continue\fR)" 4
.IX Item "($overflow_text, $unused_height) = $txt->paragraph($text, $width,$height, $continue)"
.ie n .IP "$overflow_text = $txt\->paragraph($text, $width,$height, $continue, %opts)" 4
.el .IP "\f(CW$overflow_text\fR = \f(CW$txt\fR\->paragraph($text, \f(CW$width\fR,$height, \f(CW$continue\fR, \f(CW%opts\fR)" 4
.IX Item "$overflow_text = $txt->paragraph($text, $width,$height, $continue, %opts)"
.ie n .IP "$overflow_text = $txt\->paragraph($text, $width,$height, $continue)" 4
.el .IP "\f(CW$overflow_text\fR = \f(CW$txt\fR\->paragraph($text, \f(CW$width\fR,$height, \f(CW$continue\fR)" 4
.IX Item "$overflow_text = $txt->paragraph($text, $width,$height, $continue)"
.PD
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.
.Sp
Apply the text within the rectangle and \fBreturn\fR any leftover text (if could 
not fit all of it within the rectangle). If called in an array context, the 
unused height is also \fBreturned\fR (may be 0 or negative if it just filled the 
rectangle).
.Sp
If \f(CW$continue\fR is 1, the first line does \fBnot\fR 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.
.Sp
\&\fBOptions:\fR
.RS 4
.ie n .IP "\-pndnt => $indent" 4
.el .IP "\-pndnt => \f(CW$indent\fR" 4
.IX Item "-pndnt => $indent"
Give the amount of indent (positive) or outdent (negative, for \*(L"hanging\*(R")
for paragraph first lines). This setting is ignored for centered text.
.ie n .IP "\-align => $choice" 4
.el .IP "\-align => \f(CW$choice\fR" 4
.IX Item "-align => $choice"
\&\f(CW$choice\fR is 'justified', 'right', 'center', 'left'; the default is 'left'.
See \f(CW\*(C`text_justified\*(C'\fR call for options to control how a line is expanded or
condensed if \f(CW$choice\fR is 'justified'.
.ie n .IP "\-underline => $distance" 4
.el .IP "\-underline => \f(CW$distance\fR" 4
.IX Item "-underline => $distance"
.PD 0
.ie n .IP "\-underline => [ $distance, $thickness, ... ]" 4
.el .IP "\-underline => [ \f(CW$distance\fR, \f(CW$thickness\fR, ... ]" 4
.IX Item "-underline => [ $distance, $thickness, ... ]"
.PD
If a scalar, distance below baseline,
else array reference with pairs of distance and line thickness.
.ie n .IP "\-spillover => $over" 4
.el .IP "\-spillover => \f(CW$over\fR" 4
.IX Item "-spillover => $over"
Controls if words in a line which exceed the given width should be 
\&\*(L"spilled over\*(R" the bounds, or if a new line should be used for this word.
.Sp
\&\f(CW$over\fR is 1 or 0, with the default 1 (spills over the width).
.RE
.RS 4
.Sp
\&\fBExample:\fR
.Sp
.Vb 6
\&    $txt\->font($font,$fontsize);
\&    $txt\->lead($lead);
\&    $txt\->translate($x,$y);
\&    $overflow = $txt\->paragraph( \*(Aqlong paragraph here ...\*(Aq,
\&                                 $width,
\&                                 $y+$lead\-$bottom_margin );
.Ve
.Sp
\&\fBNote:\fR if you need to change any text treatment \fIwithin\fR a paragraph 
(\fBbold\fR or \fIitalicized\fR text, for instance), this can not handle it. Only 
plain text (all the same font, size, etc.) can be typeset with \f(CW\*(C`paragraph()\*(C'\fR.
Also, there is currently very limited line splitting (hyphenation) to better 
fit to a given width, and nothing is done for \*(L"widows and orphans\*(R".
.RE
.ie n .IP "($overflow_text, $continue, $unused_height) = $txt\->section($text, $width,$height, $continue, %opts)" 4
.el .IP "($overflow_text, \f(CW$continue\fR, \f(CW$unused_height\fR) = \f(CW$txt\fR\->section($text, \f(CW$width\fR,$height, \f(CW$continue\fR, \f(CW%opts\fR)" 4
.IX Item "($overflow_text, $continue, $unused_height) = $txt->section($text, $width,$height, $continue, %opts)"
.PD 0
.ie n .IP "($overflow_text, $continue, $unused_height) = $txt\->section($text, $width,$height, $continue)" 4
.el .IP "($overflow_text, \f(CW$continue\fR, \f(CW$unused_height\fR) = \f(CW$txt\fR\->section($text, \f(CW$width\fR,$height, \f(CW$continue\fR)" 4
.IX Item "($overflow_text, $continue, $unused_height) = $txt->section($text, $width,$height, $continue)"
.ie n .IP "$overflow_text = $txt\->section($text, $width,$height, $continue, %opts)" 4
.el .IP "\f(CW$overflow_text\fR = \f(CW$txt\fR\->section($text, \f(CW$width\fR,$height, \f(CW$continue\fR, \f(CW%opts\fR)" 4
.IX Item "$overflow_text = $txt->section($text, $width,$height, $continue, %opts)"
.ie n .IP "$overflow_text = $txt\->section($text, $width,$height, $continue)" 4
.el .IP "\f(CW$overflow_text\fR = \f(CW$txt\fR\->section($text, \f(CW$width\fR,$height, \f(CW$continue\fR)" 4
.IX Item "$overflow_text = $txt->section($text, $width,$height, $continue)"
.PD
The \f(CW$text\fR contains a string with one or more paragraphs \f(CW$width\fR wide, 
starting at the current text position, with a newline \en between each 
paragraph. Each paragraph is output (see \f(CW\*(C`paragraph\*(C'\fR) until the \f(CW$height\fR 
limit is met (a partial paragraph may be at the bottom). Whatever wasn't 
output, will be \fBreturned\fR.
If called in an array context, the 
unused height and the paragraph \*(L"continue\*(R" flag are also \fBreturned\fR.
.Sp
\&\f(CW$continue\fR is 0 for the first call of \fBsection()\fR, 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.
.Sp
\&\fBOptions:\fR
.RS 4
.ie n .IP "\-pvgap => $vertical" 4
.el .IP "\-pvgap => \f(CW$vertical\fR" 4
.IX Item "-pvgap => $vertical"
Additional vertical space (unit: pt) between paragraphs (default 0). Note that this space
will also be added after the last paragraph printed.
.RE
.RS 4
.Sp
See \f(CW\*(C`paragraph\*(C'\fR for other \f(CW%opts\fR you can use, such as \-align and \-pndnt.
.RE
.ie n .IP "$width = $txt\->textlabel($x,$y, $font, $size, $text, %opts)" 4
.el .IP "\f(CW$width\fR = \f(CW$txt\fR\->textlabel($x,$y, \f(CW$font\fR, \f(CW$size\fR, \f(CW$text\fR, \f(CW%opts\fR)" 4
.IX Item "$width = $txt->textlabel($x,$y, $font, $size, $text, %opts)"
.PD 0
.ie n .IP "$width = $txt\->textlabel($x,$y, $font, $size, $text)" 4
.el .IP "\f(CW$width\fR = \f(CW$txt\fR\->textlabel($x,$y, \f(CW$font\fR, \f(CW$size\fR, \f(CW$text\fR)" 4
.IX Item "$width = $txt->textlabel($x,$y, $font, $size, $text)"
.PD
Place a line of text at an arbitrary \f(CW\*(C`[$x,$y]\*(C'\fR on the page, with various text 
settings (treatments) specified in the call.
.RS 4
.ie n .IP "$font" 4
.el .IP "\f(CW$font\fR" 4
.IX Item "$font"
A previously created font.
.ie n .IP "$size" 4
.el .IP "\f(CW$size\fR" 4
.IX Item "$size"
The font size (points).
.ie n .IP "$text" 4
.el .IP "\f(CW$text\fR" 4
.IX Item "$text"
The text to be printed (a single line).
.RE
.RS 4
.Sp
\&\fBOptions:\fR
.ie n .IP "\-rotate => $deg" 4
.el .IP "\-rotate => \f(CW$deg\fR" 4
.IX Item "-rotate => $deg"
Rotate \f(CW$deg\fR degrees counterclockwise from due East.
.ie n .IP "\-color => $cspec" 4
.el .IP "\-color => \f(CW$cspec\fR" 4
.IX Item "-color => $cspec"
A color name or permitted spec, such as \f(CW\*(C`#CCE840\*(C'\fR, for the character \fIfill\fR.
.ie n .IP "\-strokecolor => $cspec" 4
.el .IP "\-strokecolor => \f(CW$cspec\fR" 4
.IX Item "-strokecolor => $cspec"
A color name or permitted spec, such as \f(CW\*(C`#CCE840\*(C'\fR, for the character \fIoutline\fR.
.ie n .IP "\-charspace => $cdist" 4
.el .IP "\-charspace => \f(CW$cdist\fR" 4
.IX Item "-charspace => $cdist"
Additional distance between characters.
.ie n .IP "\-wordspace => $wdist" 4
.el .IP "\-wordspace => \f(CW$wdist\fR" 4
.IX Item "-wordspace => $wdist"
Additional distance between words.
.ie n .IP "\-hscale => $hfactor" 4
.el .IP "\-hscale => \f(CW$hfactor\fR" 4
.IX Item "-hscale => $hfactor"
Horizontal scaling mode (percentage of normal, default is 100).
.ie n .IP "\-render => $mode" 4
.el .IP "\-render => \f(CW$mode\fR" 4
.IX Item "-render => $mode"
Character rendering mode (outline only, fill only, etc.). See \f(CW\*(C`render\*(C'\fR call.
.IP "\-left => 1" 4
.IX Item "-left => 1"
Left align on the given point. This is the default.
.IP "\-center => 1" 4
.IX Item "-center => 1"
Center the text on the given point.
.IP "\-right => 1" 4
.IX Item "-right => 1"
Right align on the given point.
.ie n .IP "\-align => $placement" 4
.el .IP "\-align => \f(CW$placement\fR" 4
.IX Item "-align => $placement"
Alternate to \-left, \-center, and \-right. \f(CW$placement\fR is 'left' (default),
\&'center', or 'right'.
.RE
.RS 4
.Sp
Other options available to \f(CW\*(C`text\*(C'\fR, such as underlining, can be used here.
.Sp
The width used (in points) is \fBreturned\fR.
.RE
.PP
\&\fBPlease note\fR that \f(CW\*(C`textlabel()\*(C'\fR was not designed to interoperate with other
text operations. It is a standalone operation, and does \fInot\fR leave a \*(L"next 
write\*(R" position (or any other setting) for another \f(CW\*(C`text\*(C'\fR mode operation. A 
following write will likely be at \f(CW\*(C`(0,0)\*(C'\fR, and not at the expected location.
.PP
\&\f(CW\*(C`textlabel()\*(C'\fR is intended as an \*(L"all in one\*(R" 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 \fIis\fR
possible to figure out the position of a following write (either \f(CW\*(C`textlabel\*(C'\fR
or \f(CW\*(C`text\*(C'\fR) by adding the returned width to the original position's \fIx\fR value
(assuming left-justified positioning).