| Current File : //home/strato/chroot/opt/RZperl536/man/man3/PDF::API2::Content.3 |
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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::API2::Content 3"
.TH PDF::API2::Content 3 "2014-02-20" "perl v5.36.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::API2::Content \- Methods for adding graphics and text to a PDF
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& # Start with a PDF page (new or opened)
\& my $pdf = PDF::API2\->new();
\& my $page = $pdf\->page();
\&
\& # Add a new content object
\& my $content = $page\->gfx();
\& my $content = $page\->text();
\&
\& # Then call the methods below add graphics and text to the page.
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "Coordinate Transformations"
.IX Subsection "Coordinate Transformations"
The methods in this section change the coordinate system for the
current content object relative to the rest of the document.
.PP
If you call more than one of these methods, the \s-1PDF\s0 specification
recommends calling them in the following order: translate, rotate,
scale, skew. Each change builds on the last, and you can get
unexpected results when calling them in a different order.
.ie n .IP "$content\->translate($x, $y)" 4
.el .IP "\f(CW$content\fR\->translate($x, \f(CW$y\fR)" 4
.IX Item "$content->translate($x, $y)"
Moves the origin along the x and y axes.
.ie n .IP "$content\->rotate($degrees)" 4
.el .IP "\f(CW$content\fR\->rotate($degrees)" 4
.IX Item "$content->rotate($degrees)"
Rotates the coordinate system counter-clockwise.
.Sp
Use a negative argument to rotate clockwise.
.ie n .IP "$content\->scale($sx, $sy)" 4
.el .IP "\f(CW$content\fR\->scale($sx, \f(CW$sy\fR)" 4
.IX Item "$content->scale($sx, $sy)"
Scales (stretches) the coordinate systems along the x and y axes.
.ie n .IP "$content\->skew($sa, $sb)" 4
.el .IP "\f(CW$content\fR\->skew($sa, \f(CW$sb\fR)" 4
.IX Item "$content->skew($sa, $sb)"
Skews the coordinate system by \f(CW$sa\fR degrees (counter-clockwise) from
the x axis and \f(CW$sb\fR degrees (clockwise) from the y axis.
.ie n .IP "$content\->transform(%options)" 4
.el .IP "\f(CW$content\fR\->transform(%options)" 4
.IX Item "$content->transform(%options)"
.Vb 6
\& $content\->transform(
\& \-translate => [$x, $y],
\& \-rotate => $degrees,
\& \-scale => [$sx, $sy],
\& \-skew => [$sa, $sb],
\& )
.Ve
.Sp
Performs multiple coordinate transformations at once, in the order
recommended by the \s-1PDF\s0 specification (translate, rotate, scale, then
skew).
.Sp
This is equivalent to making each transformation separately.
.ie n .IP "$content\->transform_rel(%options)" 4
.el .IP "\f(CW$content\fR\->transform_rel(%options)" 4
.IX Item "$content->transform_rel(%options)"
Makes transformations similarly to \f(CW\*(C`transform\*(C'\fR, except that it adds
to the previously set values.
.ie n .IP "$content\->matrix($a, $b, $c, $d, $e, $f)" 4
.el .IP "\f(CW$content\fR\->matrix($a, \f(CW$b\fR, \f(CW$c\fR, \f(CW$d\fR, \f(CW$e\fR, \f(CW$f\fR)" 4
.IX Item "$content->matrix($a, $b, $c, $d, $e, $f)"
(Advanced) Sets the current transformation matrix manually. Unless
you have a particular need to enter transformations manually, you
should use the \f(CW\*(C`transform\*(C'\fR method instead.
.SS "Graphics State Parameters"
.IX Subsection "Graphics State Parameters"
.ie n .IP "$content\->save" 4
.el .IP "\f(CW$content\fR\->save" 4
.IX Item "$content->save"
Saves the current graphics state and text state on a stack.
.ie n .IP "$content\->restore" 4
.el .IP "\f(CW$content\fR\->restore" 4
.IX Item "$content->restore"
Restores the most recently saved graphics state and text state,
removing it from the stack.
.ie n .IP "$content\->linewidth($width)" 4
.el .IP "\f(CW$content\fR\->linewidth($width)" 4
.IX Item "$content->linewidth($width)"
Sets the width of the stroke.
.ie n .IP "$content\->linecap($style)" 4
.el .IP "\f(CW$content\fR\->linecap($style)" 4
.IX Item "$content->linecap($style)"
Sets the style to be used at the end of a stroke.
.RS 4
.IP "0 = Butt Cap" 4
.IX Item "0 = Butt Cap"
The stroke ends at the end of the path, with no projection.
.IP "1 = Round Cap" 4
.IX Item "1 = Round Cap"
An arc is drawn around the end of the path with a diameter equal to
the line width, and is filled in.
.IP "2 = Projecting Square Cap" 4
.IX Item "2 = Projecting Square Cap"
The stroke continues past the end of the path for half the line width.
.RE
.RS 4
.RE
.ie n .IP "$content\->linejoin($style)" 4
.el .IP "\f(CW$content\fR\->linejoin($style)" 4
.IX Item "$content->linejoin($style)"
Sets the style of join to be used at corners of a path.
.RS 4
.IP "0 = Miter Join" 4
.IX Item "0 = Miter Join"
The outer edges of the stroke extend until they meet, up to the limit
specified below. If the limit would be surpassed, a bevel join is
used instead.
.IP "1 = Round Join" 4
.IX Item "1 = Round Join"
A circle with a diameter equal to the linewidth is drawn around the
corner point, producing a rounded corner.
.IP "2 = Bevel Join" 4
.IX Item "2 = Bevel Join"
A triangle is drawn to fill in the notch between the two strokes.
.RE
.RS 4
.RE
.ie n .IP "$content\->meterlimit($ratio)" 4
.el .IP "\f(CW$content\fR\->meterlimit($ratio)" 4
.IX Item "$content->meterlimit($ratio)"
Note: This method is named incorrectly, and will be renamed in a
future release.
.Sp
Sets the miter (not meter) limit when the line join style is a miter
join.
.Sp
The ratio is the maximum length of the miter divided by the line
width. Any miter above this ratio will be converted to a bevel join.
.ie n .IP "$content\->\fBlinedash()\fR" 4
.el .IP "\f(CW$content\fR\->\fBlinedash()\fR" 4
.IX Item "$content->linedash()"
.PD 0
.ie n .IP "$content\->linedash($length)" 4
.el .IP "\f(CW$content\fR\->linedash($length)" 4
.IX Item "$content->linedash($length)"
.ie n .IP "$content\->linedash($on, $off)" 4
.el .IP "\f(CW$content\fR\->linedash($on, \f(CW$off\fR)" 4
.IX Item "$content->linedash($on, $off)"
.PD
Sets the line dash pattern.
.Sp
If passed without any arguments, a solid line will be drawn.
.Sp
If passed with one argument, the strokes and spaces will have equal
lengths.
.Sp
If passed with two arguments, the strokes will have length \f(CW$on\fR, and
the spaces will have length \f(CW$off\fR.
.ie n .IP "$content\->flatness($tolerance)" 4
.el .IP "\f(CW$content\fR\->flatness($tolerance)" 4
.IX Item "$content->flatness($tolerance)"
(Advanced) Sets the maximum variation in output pixels when drawing
curves.
.ie n .IP "$content\->egstate($object)" 4
.el .IP "\f(CW$content\fR\->egstate($object)" 4
.IX Item "$content->egstate($object)"
(Advanced) Adds an Extended Graphic State object containing additional
state parameters.
.SS "Path Construction (Drawing)"
.IX Subsection "Path Construction (Drawing)"
.ie n .IP "$content\->move($x, $y)" 4
.el .IP "\f(CW$content\fR\->move($x, \f(CW$y\fR)" 4
.IX Item "$content->move($x, $y)"
Starts a new path at the specified coordinates.
.ie n .IP "$content\->line($x, $y)" 4
.el .IP "\f(CW$content\fR\->line($x, \f(CW$y\fR)" 4
.IX Item "$content->line($x, $y)"
Extends the path in a line from the current coordinates to the
specified coordinates, and updates the current position to be the new
coordinates.
.Sp
Note: The line will not appear until you call \f(CW\*(C`stroke\*(C'\fR.
.ie n .IP "$content\->hline($x)" 4
.el .IP "\f(CW$content\fR\->hline($x)" 4
.IX Item "$content->hline($x)"
.PD 0
.ie n .IP "$content\->vline($y)" 4
.el .IP "\f(CW$content\fR\->vline($y)" 4
.IX Item "$content->vline($y)"
.PD
Shortcut for drawing horizontal and vertical lines from the current
position.
.ie n .IP "$content\->poly($x1, $y1, ..., $xn, $yn)" 4
.el .IP "\f(CW$content\fR\->poly($x1, \f(CW$y1\fR, ..., \f(CW$xn\fR, \f(CW$yn\fR)" 4
.IX Item "$content->poly($x1, $y1, ..., $xn, $yn)"
Shortcut for creating a polyline path. Moves to \f(CW\*(C`[$x1, $y1]\*(C'\fR, and
then extends the path in lines along the specified coordinates.
.ie n .IP "$content\->curve($cx1, $cy1, $cx2, $cy2, $x, $y)" 4
.el .IP "\f(CW$content\fR\->curve($cx1, \f(CW$cy1\fR, \f(CW$cx2\fR, \f(CW$cy2\fR, \f(CW$x\fR, \f(CW$y\fR)" 4
.IX Item "$content->curve($cx1, $cy1, $cx2, $cy2, $x, $y)"
Extends the path in a curve from the current point to \f(CW\*(C`($x, $y)\*(C'\fR,
using the two specified points to create a cubic Bezier curve, and
updates the current position to be the new point.
.Sp
Note: The curve will not appear until you call \f(CW\*(C`stroke\*(C'\fR.
.ie n .IP "$content\->spline($cx1, $cy1, $x, $y)" 4
.el .IP "\f(CW$content\fR\->spline($cx1, \f(CW$cy1\fR, \f(CW$x\fR, \f(CW$y\fR)" 4
.IX Item "$content->spline($cx1, $cy1, $x, $y)"
Extends the path in a curve from the current point to \f(CW\*(C`($x, $y)\*(C'\fR,
using the two specified points to create a spline, and updates the
current position to be the new point.
.Sp
Note: The curve will not appear until you call \f(CW\*(C`stroke\*(C'\fR.
.ie n .IP "$content\->arc($x, $y, $a, $b, $alpha, $beta, $move)" 4
.el .IP "\f(CW$content\fR\->arc($x, \f(CW$y\fR, \f(CW$a\fR, \f(CW$b\fR, \f(CW$alpha\fR, \f(CW$beta\fR, \f(CW$move\fR)" 4
.IX Item "$content->arc($x, $y, $a, $b, $alpha, $beta, $move)"
Extends the path along an arc of an ellipse centered at \f(CW\*(C`[x, y]\*(C'\fR.
The major and minor axes of the ellipse are \f(CW$a\fR and \f(CW$b\fR,
respectively, and the arc moves from \f(CW$alpha\fR degrees to \f(CW$beta\fR
degrees. The current position is then set to the endpoint of the arc.
.Sp
Set \f(CW$move\fR to a true value if this arc is the beginning of a new
path instead of the continuation of an existing path.
.ie n .IP "$content\->bogen($x1, $y1, $x2, $y2, $radius, $move, $outer, $reverse)" 4
.el .IP "\f(CW$content\fR\->bogen($x1, \f(CW$y1\fR, \f(CW$x2\fR, \f(CW$y2\fR, \f(CW$radius\fR, \f(CW$move\fR, \f(CW$outer\fR, \f(CW$reverse\fR)" 4
.IX Item "$content->bogen($x1, $y1, $x2, $y2, $radius, $move, $outer, $reverse)"
Extends the path along an arc of a circle of the specified radius
between \f(CW\*(C`[x1, y1]\*(C'\fR to \f(CW\*(C`[x2, y2]\*(C'\fR. The current position is then set
to the endpoint of the arc.
.Sp
Set \f(CW$move\fR to a true value if this arc is the beginning of a new
path instead of the continuation of an existing path.
.Sp
Set \f(CW$outer\fR to a true value to draw the larger arc between the two
points instead of the smaller one.
.Sp
Set \f(CW$reverse\fR to a true value to draw the mirror image of the
specified arc.
.Sp
\&\f(CW\*(C`$radius * 2\*(C'\fR cannot be smaller than the distance from \f(CW\*(C`[x1, y1]\*(C'\fR to
\&\f(CW\*(C`[x2, y2]\*(C'\fR.
.Sp
Note: The curve will not appear until you call \f(CW\*(C`stroke\*(C'\fR.
.ie n .IP "$content\->close" 4
.el .IP "\f(CW$content\fR\->close" 4
.IX Item "$content->close"
Closes and ends the current path by extending a line from the current
position to the starting position.
.ie n .IP "$content\->endpath" 4
.el .IP "\f(CW$content\fR\->endpath" 4
.IX Item "$content->endpath"
Ends the current path without explicitly enclosing it.
.ie n .IP "$content\->ellipse($x, $y, $a, $b)" 4
.el .IP "\f(CW$content\fR\->ellipse($x, \f(CW$y\fR, \f(CW$a\fR, \f(CW$b\fR)" 4
.IX Item "$content->ellipse($x, $y, $a, $b)"
Creates an elliptical path centered on \f(CW\*(C`[$x, $y]\*(C'\fR, with major and
minor axes specified by \f(CW$a\fR and \f(CW$b\fR, respectively.
.Sp
Note: The ellipse will not appear until you call \f(CW\*(C`stroke\*(C'\fR or \f(CW\*(C`fill\*(C'\fR.
.ie n .IP "$content\->circle($x, $y, $radius)" 4
.el .IP "\f(CW$content\fR\->circle($x, \f(CW$y\fR, \f(CW$radius\fR)" 4
.IX Item "$content->circle($x, $y, $radius)"
Creates a circular path centered on \f(CW\*(C`[$x, $y]\*(C'\fR with the specified
radius.
.Sp
Note: The circle will not appear until you call \f(CW\*(C`stroke\*(C'\fR or \f(CW\*(C`fill\*(C'\fR.
.ie n .IP "$content\->pie($x, $y, $a, $b, $alpha, $beta)" 4
.el .IP "\f(CW$content\fR\->pie($x, \f(CW$y\fR, \f(CW$a\fR, \f(CW$b\fR, \f(CW$alpha\fR, \f(CW$beta\fR)" 4
.IX Item "$content->pie($x, $y, $a, $b, $alpha, $beta)"
Creates a pie-shaped path from an ellipse centered on \f(CW\*(C`[$x, $y]\*(C'\fR.
The major and minor axes of the ellipse are \f(CW$a\fR and \f(CW$b\fR,
respectively, and the arc moves from \f(CW$alpha\fR degrees to \f(CW$beta\fR
degrees.
.Sp
Note: The pie will not appear until you call \f(CW\*(C`stroke\*(C'\fR or \f(CW\*(C`fill\*(C'\fR.
.ie n .IP "$content\->rect($x1, $y1, $w1, $h1, ..., $xn, $yn, $wn, $hn)" 4
.el .IP "\f(CW$content\fR\->rect($x1, \f(CW$y1\fR, \f(CW$w1\fR, \f(CW$h1\fR, ..., \f(CW$xn\fR, \f(CW$yn\fR, \f(CW$wn\fR, \f(CW$hn\fR)" 4
.IX Item "$content->rect($x1, $y1, $w1, $h1, ..., $xn, $yn, $wn, $hn)"
Creates paths for one or more rectangles, with their lower left points
at \f(CW\*(C`[$x, $y]\*(C'\fR and with the specified widths and heights.
.Sp
Note: The rectangle will not appear until you call \f(CW\*(C`stroke\*(C'\fR or \f(CW\*(C`fill\*(C'\fR.
.ie n .IP "$content\->rectxy($x1, $y1, $x2, $y2)" 4
.el .IP "\f(CW$content\fR\->rectxy($x1, \f(CW$y1\fR, \f(CW$x2\fR, \f(CW$y2\fR)" 4
.IX Item "$content->rectxy($x1, $y1, $x2, $y2)"
Creates a rectangular path, with \f(CW\*(C`[$x1, $y1]\*(C'\fR and and \f(CW\*(C`[$x2, $y2]\*(C'\fR
specifying opposite corners.
.Sp
Note: The rectangle will not appear until you call \f(CW\*(C`stroke\*(C'\fR or \f(CW\*(C`fill\*(C'\fR.
.SS "Path Painting (Drawing)"
.IX Subsection "Path Painting (Drawing)"
.ie n .IP "$content\->stroke" 4
.el .IP "\f(CW$content\fR\->stroke" 4
.IX Item "$content->stroke"
Strokes the current path.
.ie n .IP "$content\->fill($use_even_odd_fill)" 4
.el .IP "\f(CW$content\fR\->fill($use_even_odd_fill)" 4
.IX Item "$content->fill($use_even_odd_fill)"
Fills the current path.
.Sp
If the path intersects with itself, the nonzero winding rule will be
used to determine which part of the path is filled in. If you would
prefer to use the even-odd rule, pass a true argument.
.Sp
See the \s-1PDF\s0 Specification, section 8.5.3.3, for more details on
filling.
.ie n .IP "$content\->fillstroke($use_even_odd_fill)" 4
.el .IP "\f(CW$content\fR\->fillstroke($use_even_odd_fill)" 4
.IX Item "$content->fillstroke($use_even_odd_fill)"
Fills and then strokes the current path.
.ie n .IP "$content\->clip($use_even_odd_fill)" 4
.el .IP "\f(CW$content\fR\->clip($use_even_odd_fill)" 4
.IX Item "$content->clip($use_even_odd_fill)"
Modifies the current clipping path by intersecting it with the current
path.
.SS "Colors"
.IX Subsection "Colors"
.ie n .IP "$content\->fillcolor($color)" 4
.el .IP "\f(CW$content\fR\->fillcolor($color)" 4
.IX Item "$content->fillcolor($color)"
.PD 0
.ie n .IP "$content\->strokecolor($color)" 4
.el .IP "\f(CW$content\fR\->strokecolor($color)" 4
.IX Item "$content->strokecolor($color)"
.PD
Sets the fill or stroke color.
.Sp
.Vb 2
\& # Use a named color
\& $content\->fillcolor(\*(Aqblue\*(Aq);
\&
\& # Use an RGB color (start with \*(Aq#\*(Aq)
\& $content\->fillcolor(\*(Aq#FF0000\*(Aq);
\&
\& # Use a CMYK color (start with \*(Aq%\*(Aq)
\& $content\->fillcolor(\*(Aq%FF000000\*(Aq);
.Ve
.Sp
\&\s-1RGB\s0 and \s-1CMYK\s0 colors can have one-byte, two-byte, three-byte, or
four-byte values for each color. For instance, cyan can be given as
\&\f(CW%F000\fR or \f(CW%FFFF000000000000\fR.
.SS "External Objects"
.IX Subsection "External Objects"
.ie n .IP "$content\->image($image_object, $x, $y, $width, $height)" 4
.el .IP "\f(CW$content\fR\->image($image_object, \f(CW$x\fR, \f(CW$y\fR, \f(CW$width\fR, \f(CW$height\fR)" 4
.IX Item "$content->image($image_object, $x, $y, $width, $height)"
.PD 0
.ie n .IP "$content\->image($image_object, $x, $y, $scale)" 4
.el .IP "\f(CW$content\fR\->image($image_object, \f(CW$x\fR, \f(CW$y\fR, \f(CW$scale\fR)" 4
.IX Item "$content->image($image_object, $x, $y, $scale)"
.ie n .IP "$content\->image($image_object, $x, $y)" 4
.el .IP "\f(CW$content\fR\->image($image_object, \f(CW$x\fR, \f(CW$y\fR)" 4
.IX Item "$content->image($image_object, $x, $y)"
.PD
.Vb 3
\& # Example
\& my $image_object = $pdf\->image_jpeg($my_image_file);
\& $content\->image($image_object, 100, 200);
.Ve
.Sp
Places an image on the page in the specified location.
.Sp
If coordinate transformations have been made (see Coordinate
Transformations above), the position and scale will be relative to the
updated coordinates. Otherwise, [0,0] will represent the bottom left
corner of the page, and \f(CW$width\fR and \f(CW$height\fR will be measured at
72dpi.
.Sp
For example, if you have a 600x600 image that you would like to be
shown at 600dpi (i.e. one inch square), set the width and height to 72.
.ie n .IP "$content\->formimage($form_object, $x, $y, $scale)" 4
.el .IP "\f(CW$content\fR\->formimage($form_object, \f(CW$x\fR, \f(CW$y\fR, \f(CW$scale\fR)" 4
.IX Item "$content->formimage($form_object, $x, $y, $scale)"
.PD 0
.ie n .IP "$content\->formimage($form_object, $x, $y)" 4
.el .IP "\f(CW$content\fR\->formimage($form_object, \f(CW$x\fR, \f(CW$y\fR)" 4
.IX Item "$content->formimage($form_object, $x, $y)"
.PD
Places an XObject on the page in the specified location.
.SS "Text State Parameters"
.IX Subsection "Text State Parameters"
All of the following parameters that take a size are applied before
any scaling takes place, so you don't need to adjust values to
counteract scaling.
.ie n .IP "$spacing = $content\->charspace($spacing)" 4
.el .IP "\f(CW$spacing\fR = \f(CW$content\fR\->charspace($spacing)" 4
.IX Item "$spacing = $content->charspace($spacing)"
Sets the spacing between characters. This is initially zero.
.ie n .IP "$spacing = $content\->wordspace($spacing)" 4
.el .IP "\f(CW$spacing\fR = \f(CW$content\fR\->wordspace($spacing)" 4
.IX Item "$spacing = $content->wordspace($spacing)"
Sets the spacing between words. This is initially zero (or, in other
words, just the width of the space).
.ie n .IP "$scale = $content\->hspace($scale)" 4
.el .IP "\f(CW$scale\fR = \f(CW$content\fR\->hspace($scale)" 4
.IX Item "$scale = $content->hspace($scale)"
Note: This method is named incorrectly, and will be renamed in a
future release.
.Sp
Sets the percentage of horizontal text scaling (not spacing). This is
initially 100 (i.e. no scaling), and must be passed as an integer.
.ie n .IP "$leading = $content\->lead($leading)" 4
.el .IP "\f(CW$leading\fR = \f(CW$content\fR\->lead($leading)" 4
.IX Item "$leading = $content->lead($leading)"
Sets the text leading, which is the distance between baselines. This
is initially zero (i.e. the lines will be printed on top of each
other).
.ie n .IP "$mode = $content\->render($mode)" 4
.el .IP "\f(CW$mode\fR = \f(CW$content\fR\->render($mode)" 4
.IX Item "$mode = $content->render($mode)"
Sets the text rendering mode.
.RS 4
.IP "0 = Fill text" 4
.IX Item "0 = Fill text"
.PD 0
.IP "1 = Stroke text (outline)" 4
.IX Item "1 = Stroke text (outline)"
.IP "2 = Fill, then stroke text" 4
.IX Item "2 = Fill, then stroke text"
.IP "3 = Neither fill nor stroke text (invisible)" 4
.IX Item "3 = Neither fill nor stroke text (invisible)"
.IP "4 = Fill text and add to path for clipping" 4
.IX Item "4 = Fill text and add to path for clipping"
.IP "5 = Stroke text and add to path for clipping" 4
.IX Item "5 = Stroke text and add to path for clipping"
.IP "6 = Fill, then stroke text and add to path for clipping" 4
.IX Item "6 = Fill, then stroke text and add to path for clipping"
.IP "7 = Add text to path for clipping" 4
.IX Item "7 = Add text to path for clipping"
.RE
.RS 4
.RE
.ie n .IP "$distance = $content\->rise($distance)" 4
.el .IP "\f(CW$distance\fR = \f(CW$content\fR\->rise($distance)" 4
.IX Item "$distance = $content->rise($distance)"
.PD
Adjusts the baseline up or down from its current location. This is
initially zero.
.Sp
Use this for creating superscripts or subscripts (usually with an
adjustment to the font size as well).
.ie n .IP "%state = $content\->textstate(charspace => $value, wordspace => $value, ...)" 4
.el .IP "\f(CW%state\fR = \f(CW$content\fR\->textstate(charspace => \f(CW$value\fR, wordspace => \f(CW$value\fR, ...)" 4
.IX Item "%state = $content->textstate(charspace => $value, wordspace => $value, ...)"
Shortcut for setting multiple text state parameters at once.
.Sp
This can also be used without arguments to retrieve the current text
state settings.
.Sp
Note: This does not currently work with the \f(CW\*(C`save\*(C'\fR and \f(CW\*(C`restore\*(C'\fR commands.
.ie n .IP "$content\->font($font_object, $size)" 4
.el .IP "\f(CW$content\fR\->font($font_object, \f(CW$size\fR)" 4
.IX Item "$content->font($font_object, $size)"
.Vb 4
\& # Example
\& my $pdf = PDF::API2\->new();
\& my $font = $pdf\->corefont(\*(AqHelvetica\*(Aq);
\& $content\->font($font, 12);
.Ve
.Sp
Sets the font and font size.
.SS "Text-Positioning"
.IX Subsection "Text-Positioning"
Note: There is a very good chance that these commands will be replaced
in a future release.
.ie n .IP "$content\->distance($dx, $dy)" 4
.el .IP "\f(CW$content\fR\->distance($dx, \f(CW$dy\fR)" 4
.IX Item "$content->distance($dx, $dy)"
Moves to the start of the next line, offset by the given amounts,
which are both required.
.ie n .IP "$content\->cr($vertical_offset)" 4
.el .IP "\f(CW$content\fR\->cr($vertical_offset)" 4
.IX Item "$content->cr($vertical_offset)"
If passed with an argument, moves to the start of the next line,
offset by the given value.
.Sp
If passed without an argument, moves to the start of the next line.
.Sp
Note that this is equivalent to a carriage return plus line feed. To
get just a carriage return, pass zero as the argument.
.ie n .IP "$content\->nl" 4
.el .IP "\f(CW$content\fR\->nl" 4
.IX Item "$content->nl"
Moves to the start of the next line.
.ie n .IP "($tx, $ty) = $content\->\fBtextpos()\fR" 4
.el .IP "($tx, \f(CW$ty\fR) = \f(CW$content\fR\->\fBtextpos()\fR" 4
.IX Item "($tx, $ty) = $content->textpos()"
Gets the current estimated text position.
.Sp
Note: This does not affect the \s-1PDF\s0 in any way.
.SS "Text-Showing"
.IX Subsection "Text-Showing"
.ie n .IP "$width = $content\->text($text, %options)" 4
.el .IP "\f(CW$width\fR = \f(CW$content\fR\->text($text, \f(CW%options\fR)" 4
.IX Item "$width = $content->text($text, %options)"
Adds text to the page.
.Sp
Options:
.RS 4
.IP "\-indent" 4
.IX Item "-indent"
Indents the text by the number of points.
.IP "\-underline => 'auto'" 4
.IX Item "-underline => 'auto'"
.PD 0
.ie n .IP "\-underline => $distance" 4
.el .IP "\-underline => \f(CW$distance\fR" 4
.IX Item "-underline => $distance"
.ie n .IP "\-underline => [$distance, $thickness, ...]" 4
.el .IP "\-underline => [$distance, \f(CW$thickness\fR, ...]" 4
.IX Item "-underline => [$distance, $thickness, ...]"
.PD
Underlines the text. \f(CW$distance\fR is the number of units beneath the
baseline, and \f(CW$thickness\fR is the width of the line.
.Sp
Multiple underlines can be made by passing several distances and
thicknesses.
.RE
.RS 4
.RE
.ie n .IP "$content\->text_center($text)" 4
.el .IP "\f(CW$content\fR\->text_center($text)" 4
.IX Item "$content->text_center($text)"
As \f(CW\*(C`text\*(C'\fR, but centered on the current point.
.ie n .IP "$txt\->text_right $text, %options" 4
.el .IP "\f(CW$txt\fR\->text_right \f(CW$text\fR, \f(CW%options\fR" 4
.IX Item "$txt->text_right $text, %options"
As \f(CW\*(C`text\*(C'\fR, but right-aligned to the current point.
.ie n .IP "$width = $txt\->advancewidth($string, %text_state)" 4
.el .IP "\f(CW$width\fR = \f(CW$txt\fR\->advancewidth($string, \f(CW%text_state\fR)" 4
.IX Item "$width = $txt->advancewidth($string, %text_state)"
Returns the width of the string based on all currently set text-state
attributes. These can optionally be overridden.
.SS "Advanced Methods"
.IX Subsection "Advanced Methods"
.ie n .IP "$content\->add @content" 4
.el .IP "\f(CW$content\fR\->add \f(CW@content\fR" 4
.IX Item "$content->add @content"
Add raw content to the \s-1PDF\s0 stream. You will generally want to use the
other methods in this class instead.
.ie n .IP "$content\->compressFlate" 4
.el .IP "\f(CW$content\fR\->compressFlate" 4
.IX Item "$content->compressFlate"
Marks content for compression on output. This is done automatically
in nearly all cases, so you shouldn't need to call this yourself.
.ie n .IP "$content\->textstart" 4
.el .IP "\f(CW$content\fR\->textstart" 4
.IX Item "$content->textstart"
Starts a text object. You will likely want to use the \f(CW\*(C`text\*(C'\fR method
instead.
.ie n .IP "$content\->textend" 4
.el .IP "\f(CW$content\fR\->textend" 4
.IX Item "$content->textend"
Ends a text object.