.\" 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 3pm"
.TH PDF::API2::Content 3pm "2023-09-29" "perl v5.36.0" "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\->graphics();
\&    my $content = $page\->text();
\&
\&    # Then call the methods below to add graphics and text to the page.
.Ve
.SH "COORDINATE TRANSFORMATIONS"
.IX Header "COORDINATE TRANSFORMATIONS"
The methods in this section change the coordinate system for the current content
object relative to the rest of the document.
.PP
Changes to the coordinate system only affect subsequent paths or text.
.PP
A call to any of the methods in this section resets the coordinate system before
applying its changes, unless the \f(CW\*(C`relative\*(C'\fR option is set.
.SS "translate"
.IX Subsection "translate"
.Vb 1
\&    $content = $content\->translate($x, $y);
.Ve
.PP
Moves the origin along the x and y axes.
.SS "rotate"
.IX Subsection "rotate"
.Vb 1
\&    $content = $content\->rotate($degrees);
.Ve
.PP
Rotates the coordinate system counter-clockwise.
.PP
Use a negative argument to rotate clockwise.
.SS "scale"
.IX Subsection "scale"
.Vb 1
\&    $content = $content\->scale($x, $y);
.Ve
.PP
Scales (stretches) the coordinate systems along the x and y axes.  A value of 1
for either \f(CW$x\fR or \f(CW$y\fR represents 100% scale (i.e. no change).
.SS "skew"
.IX Subsection "skew"
.Vb 1
\&    $content = $content\->skew($a, $b);
.Ve
.PP
Skews the coordinate system by \f(CW$a\fR degrees (counter-clockwise) from the x axis
and \f(CW$b\fR degrees (clockwise) from the y axis.
.SS "transform"
.IX Subsection "transform"
.Vb 7
\&    $content = $content\->transform(
\&        translate => [$x, $y],
\&        rotate    => $degrees,
\&        scale     => [$x, $y],
\&        skew      => [$a, $b],
\&        repeat    => $boolean,
\&    );
.Ve
.PP
Performs multiple coordinate transformations, in the order recommended by the
\&\s-1PDF\s0 specification (translate, rotate, scale, then skew).  Omitted options will
be unchanged.
.PP
If \f(CW\*(C`repeat\*(C'\fR is true and if this is not the first call to a transformation
method, the previous transformation will be performed again, modified by any
other provided arguments.
.SS "matrix"
.IX Subsection "matrix"
.Vb 1
\&    $graphics = $graphics\->matrix($a, $b, $c, $d, $e, $f);
\&
\&    ($a, $b, $c, $d, $e, $f) = $text\->matrix($a, $b, $c, $d, $e, $f);
.Ve
.PP
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.
.PP
The return value differs based on whether the caller is a graphics content
object or a text content object.
.SH "GRAPHICS STATE"
.IX Header "GRAPHICS STATE"
.SS "save"
.IX Subsection "save"
.Vb 1
\&    $content = $content\->save();
.Ve
.PP
Saves the current graphics state on a stack.
.SS "restore"
.IX Subsection "restore"
.Vb 1
\&    $content = $content\->restore();
.Ve
.PP
Restores the most recently saved graphics state, removing it from the stack.
.SS "line_width"
.IX Subsection "line_width"
.Vb 1
\&    $content = $content\->line_width($points);
.Ve
.PP
Sets the width of the stroke in points.
.SS "line_cap"
.IX Subsection "line_cap"
.Vb 1
\&    $content = $content\->line_cap($style);
.Ve
.PP
Sets the shape that will be used at the ends of open subpaths (and dashes, if
any) when they are stroked.
.IP "\(bu" 4
\&\*(L"butt\*(R" or 0 = Butt Cap, default
.Sp
The stroke ends at the end of the path, with no projection.
.IP "\(bu" 4
\&\*(L"round\*(R" or 1 = Round Cap)
.Sp
An arc is drawn around the end of the path with a diameter equal to the line
width, and is filled in.
.IP "\(bu" 4
\&\*(L"square\*(R" or 2 = Projecting Square Cap
.Sp
The stroke continues past the end of the path for half the line width.
.SS "line_join"
.IX Subsection "line_join"
.Vb 1
\&    $content = $content\->line_join($style);
.Ve
.PP
Sets the style of join to be used at corners of a path.
.IP "\(bu" 4
\&\*(L"miter\*(R" or 0 = Miter Join, default
.Sp
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 "\(bu" 4
\&\*(L"round\*(R" or 1 = Round Join
.Sp
A circle with a diameter equal to the linewidth is drawn around the corner
point, producing a rounded corner.
.IP "\(bu" 4
\&\*(L"bevel\*(R" or 2 = Bevel Join
.Sp
A triangle is drawn to fill in the notch between the two strokes.
.SS "miter_limit"
.IX Subsection "miter_limit"
.Vb 1
\&    $content = $content\->miter_limit($ratio);
.Ve
.PP
Sets the miter limit when the line join style is a miter join.
.PP
The \f(CW$ratio\fR is the maximum length of the miter (inner to outer corner) divided
by the line width. Any miter above this ratio will be converted to a bevel
join. The practical effect is that lines meeting at shallow angles are chopped
off instead of producing long pointed corners.
.PP
There is no documented default miter limit.
.SS "line_dash_pattern"
.IX Subsection "line_dash_pattern"
.Vb 2
\&    # Solid line
\&    $content = $content\->line_dash_pattern();
\&
\&    # Equal length lines and gaps
\&    $content = $content\->line_dash_pattern($length);
\&
\&    # Specified line and gap lengths
\&    $content = $content\->line_dash_pattern($line1, $gap1, $line2, $gap2, ...);
\&
\&    # Offset the starting point
\&    $content = $content\->line_dash_pattern(
\&        pattern => [$line1, $gap1, $line2, $gap2, ...],
\&        offset => $points,
\&    );
.Ve
.PP
Sets the line dash pattern.
.PP
If called without any arguments, a solid line will be drawn.
.PP
If called with one argument, the dashes and gaps will have equal lengths.
.PP
If called with two or more arguments, the arguments represent alternating dash
and gap lengths.
.PP
If called with a hash of arguments, a dash phase may be set, which specifies the
distance into the pattern at which to start the dash.
.SS "flatness_tolerance"
.IX Subsection "flatness_tolerance"
.Vb 1
\&    $content = $content\->flatness_tolerance($tolerance);
.Ve
.PP
Sets the maximum distance in device pixels between the mathematically correct
path for a curve and an approximation constructed from straight line segments.
.PP
\&\f(CW$tolerance\fR is an integer between 0 and 100, where 0 represents the device's
default flatness tolerance.
.SS "egstate"
.IX Subsection "egstate"
.Vb 1
\&    $content = $content\->egstate($object);
.Ve
.PP
Adds a PDF::API2::Resource::ExtGState object containing a set of graphics
state parameters.
.SH "PATH CONSTRUCTION (DRAWING)"
.IX Header "PATH CONSTRUCTION (DRAWING)"
Note that paths will not appear until a path painting method is called
(\*(L"stroke\*(R", \*(L"fill\*(R", or \*(L"paint\*(R").
.SS "move"
.IX Subsection "move"
.Vb 1
\&    $content = $content\->move($x, $y);
.Ve
.PP
Starts a new path at the specified coordinates.
.SS "line"
.IX Subsection "line"
.Vb 1
\&    $content = $content\->line($x, $y);
.Ve
.PP
Extends the path in a line from the current coordinates to the specified
coordinates.
.SS "hline"
.IX Subsection "hline"
.Vb 1
\&    $content = $content\->hline($x);
.Ve
.PP
Extends the path in a horizontal line from the current position to the specified
x coordinate.
.SS "vline"
.IX Subsection "vline"
.Vb 1
\&    $content = $content\->vline($x);
.Ve
.PP
Extends the path in a vertical line from the current position to the specified y
coordinate.
.SS "polyline"
.IX Subsection "polyline"
.Vb 1
\&    $content = $content\->polyline($x1, $y1, $x2, $y2, ...);
.Ve
.PP
Extends the path from the current position in one or more straight lines.
.SS "curve"
.IX Subsection "curve"
.Vb 1
\&    $content = $content\->curve($cx1, $cy1, $cx2, $cy2, $x, $y);
.Ve
.PP
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.
.SS "spline"
.IX Subsection "spline"
.Vb 1
\&    $content = $content\->spline($cx1, $cy1, $x, $y);
.Ve
.PP
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.
.SS "arc"
.IX Subsection "arc"
.Vb 1
\&    $content = $content\->arc($x, $y, $major, $minor, $a, $b);
.Ve
.PP
Extends the path along an arc of an ellipse centered at \f(CW\*(C`[$x, $y]\*(C'\fR.  \f(CW$major\fR
and \f(CW$minor\fR represent the axes of the ellipse, and the arc moves from \f(CW$a\fR
degrees to \f(CW$b\fR degrees.
.SS "close"
.IX Subsection "close"
.Vb 1
\&    $content = $content\->close();
.Ve
.PP
Closes the current path by extending a line from the current position to the
starting position.
.SS "end"
.IX Subsection "end"
.Vb 1
\&    $content = $content\->end();
.Ve
.PP
Ends the current path without filling or stroking.
.SH "SHAPE CONSTRUCTION (DRAWING)"
.IX Header "SHAPE CONSTRUCTION (DRAWING)"
The following are convenience methods for drawing closed paths.
.PP
Note that shapes will not appear until a path painting method is called
(\*(L"stroke\*(R", \*(L"fill\*(R", or \*(L"paint\*(R").
.SS "rectangle"
.IX Subsection "rectangle"
.Vb 1
\&    $content = $content\->rectangle($x1, $y1, $x2, $y2);
.Ve
.PP
Creates a new rectangle-shaped path, between the two points \f(CW\*(C`[$x1, $y1]\*(C'\fR
and \f(CW\*(C`[$x2, $y2]\*(C'\fR.
.SS "circle"
.IX Subsection "circle"
.Vb 1
\&    $content = $content\->circle($x, $y, $radius);
.Ve
.PP
Creates a new circular path centered on \f(CW\*(C`[$x, $y]\*(C'\fR with the specified radius.
.SS "ellipse"
.IX Subsection "ellipse"
.Vb 1
\&    $content = $content\->ellipse($x, $y, $major, $minor);
.Ve
.PP
Creates a new elliptical path centered on \f(CW\*(C`[$x, $y]\*(C'\fR with the specified major
and minor axes.
.SS "pie"
.IX Subsection "pie"
.Vb 1
\&    $content = $content\->pie($x, $y, $major, $minor, $a, $b);
.Ve
.PP
Creates a new wedge-shaped path from an ellipse centered on \f(CW\*(C`[$x, $y]\*(C'\fR with the
specified major and minor axes, extending from \f(CW$a\fR degrees to \f(CW$b\fR degrees.
.SH "PATH PAINTING (DRAWING)"
.IX Header "PATH PAINTING (DRAWING)"
.SS "stroke_color"
.IX Subsection "stroke_color"
.Vb 1
\&    $content = $content\->stroke_color($color, @arguments);
.Ve
.PP
Sets the stroke color, which is black by default.
.PP
.Vb 2
\&    # Use a named color
\&    $content\->stroke_color(\*(Aqblue\*(Aq);
\&
\&    # Use an RGB color (start with \*(Aq#\*(Aq)
\&    $content\->stroke_color(\*(Aq#FF0000\*(Aq);
\&
\&    # Use a CMYK color (start with \*(Aq%\*(Aq)
\&    $content\->stroke_color(\*(Aq%FF000000\*(Aq);
\&
\&    # Use a spot color with 100% coverage.
\&    my $spot = $pdf\->colorspace(\*(Aqspot\*(Aq, \*(AqPANTONE Red 032 C\*(Aq, \*(Aq#EF3340\*(Aq);
\&    $content\->stroke_color($spot, 1.0);
.Ve
.PP
\&\s-1RGB\s0 and \s-1CMYK\s0 colors can have one-byte, two-byte, three-byte, or four-byte values
for each color, depending on the level of precision needed.  For instance, cyan
can be given as \f(CW%F000\fR or \f(CW%FFFF000000000000\fR.
.SS "fill_color"
.IX Subsection "fill_color"
.Vb 1
\&    $content = $content\->fill_color($color, @arguments);
.Ve
.PP
Sets the fill color, which is black by default.  Arguments are the same as in
\&\*(L"stroke_color\*(R".
.SS "stroke"
.IX Subsection "stroke"
.Vb 1
\&    $content = $content\->stroke();
.Ve
.PP
Strokes the current path.
.SS "fill"
.IX Subsection "fill"
.Vb 1
\&    $content = $content\->fill(rule => $rule);
.Ve
.PP
Fills the current path.
.PP
\&\f(CW$rule\fR describes which areas are filled in when the path intersects with itself.
.IP "\(bu" 4
nonzero (default)
.Sp
Use the nonzero winding number rule.  This tends to mean that the entire area
enclosed by the path is filled in, with some exceptions depending on the
direction of the path.
.IP "\(bu" 4
even-odd
.Sp
Use the even-odd rule.  This tends to mean that the presence of fill alternates
each time the path is intersected.
.PP
See \s-1PDF\s0 specification 1.7 section 8.5.3.3, Filling, for more details.
.SS "paint"
.IX Subsection "paint"
.Vb 1
\&    $content = $content\->paint(rule => $rule);
.Ve
.PP
Fills and strokes the current path.  \f(CW$rule\fR is as described in \*(L"fill\*(R".
.SS "clip"
.IX Subsection "clip"
.Vb 1
\&    $content = $content\->clip(rule => $rule);
.Ve
.PP
Modifies the current clipping path (initially the entire page) by intersecting
it with the current path following the next path-painting command.  \f(CW$rule\fR is
as described in \*(L"fill\*(R".
.SH "EXTERNAL OBJECTS"
.IX Header "EXTERNAL OBJECTS"
.SS "object"
.IX Subsection "object"
.Vb 1
\&    $content = $content\->object($object, $x, $y, $scale_x, $scale_y);
.Ve
.PP
Places an image or other external object (a.k.a. XObject) on the page in the
specified location.
.PP
If \f(CW$x\fR and \f(CW$y\fR are omitted, the object will be placed at \f(CW\*(C`[0, 0]\*(C'\fR.
.PP
For images, \f(CW$scale_x\fR and \f(CW$scale_y\fR represent the width and height of the
image on the page in points.  If \f(CW$scale_x\fR is omitted, it will default to 72
pixels per inch.  If \f(CW$scale_y\fR is omitted, the image will be scaled
proportionally based on the image dimensions.
.PP
For other external objects, the scale is a multiplier, where 1 (the default)
represents 100% (i.e. no change).
.PP
If coordinate transformations have been made (see Coordinate Transformations
above), the position and scale will be relative to the updated coordinates.
.PP
If no coordinate transformations are needed, this method can be called directly
from the PDF::API2::Page object instead.
.SH "TEXT STATE"
.IX Header "TEXT STATE"
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.
.SS "font"
.IX Subsection "font"
.Vb 1
\&    $content = $content\->font($font, $size);
.Ve
.PP
Sets the font and font size.  \f(CW$font\fR is an object created by calling
\&\*(L"font\*(R" in \s-1PDF::API2\s0 to add the font to the document.
.PP
.Vb 3
\&    my $pdf = PDF::API2\->new();
\&    my $page = $pdf\->page();
\&    my $text = $page\->text();
\&
\&    my $font = $pdf\->font(\*(AqHelvetica\*(Aq);
\&    $text\->font($font, 24);
\&    $text\->position(72, 720);
\&    $text\->text(\*(AqHello, World!\*(Aq);
\&
\&    $pdf\->save(\*(Aqsample.pdf\*(Aq);
.Ve
.SS "character_spacing"
.IX Subsection "character_spacing"
.Vb 1
\&    $spacing = $content\->character_spacing($spacing);
.Ve
.PP
Sets the spacing between characters.  This is initially zero.
.SS "word_spacing"
.IX Subsection "word_spacing"
.Vb 1
\&    $spacing = $content\->word_spacing($spacing);
.Ve
.PP
Sets the spacing between words.  This is initially zero (i.e. just the width of
the space).
.PP
Word spacing might only affect simple fonts and composite fonts where the space
character is a single-byte code.  This is a limitation of the \s-1PDF\s0 specification
at least as of version 1.7 (see section 9.3.3).  It's possible that a later
version of the specification will support word spacing in fonts that use
multi-byte codes.
.SS "hscale"
.IX Subsection "hscale"
.Vb 1
\&    $scale = $content\->hscale($scale);
.Ve
.PP
Sets/gets the percentage of horizontal text scaling.  Enter a scale greater than
100 to stretch text, less than 100 to squeeze text, or 100 to disable any
existing scaling.
.SS "leading"
.IX Subsection "leading"
.Vb 1
\&    $leading = $content\->leading($leading);
.Ve
.PP
Sets/gets 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).
.SS "render"
.IX Subsection "render"
.Vb 1
\&    $mode = $content\->render($mode);
.Ve
.PP
Sets the text rendering mode.
.IP "\(bu" 4
0 = Fill text
.IP "\(bu" 4
1 = Stroke text (outline)
.IP "\(bu" 4
2 = Fill, then stroke text
.IP "\(bu" 4
3 = Neither fill nor stroke text (invisible)
.IP "\(bu" 4
4 = Fill text and add to path for clipping
.IP "\(bu" 4
5 = Stroke text and add to path for clipping
.IP "\(bu" 4
6 = Fill, then stroke text and add to path for clipping
.IP "\(bu" 4
7 = Add text to path for clipping
.SS "rise"
.IX Subsection "rise"
.Vb 1
\&    $distance = $content\->rise($distance);
.Ve
.PP
Adjusts the baseline up or down from its current location.  This is initially
zero.
.PP
Use this to create superscripts or subscripts (usually with an adjustment to the
font size as well).
.SH "TEXT PLACEMENT"
.IX Header "TEXT PLACEMENT"
.SS "position"
.IX Subsection "position"
.Vb 2
\&    # Set
\&    $content = $content\->position($x, $y);
\&
\&    # Get
\&    ($x, $y) = $content\->position();
.Ve
.PP
If called with arguments, moves to the start of the current line of text, offset
by \f(CW$x\fR and \f(CW$y\fR.
.PP
If called without arguments, returns the current position of the cursor (before
the effects of any coordinate transformation methods).
.SS "crlf"
.IX Subsection "crlf"
.Vb 1
\&    $content = $content\->crlf();
.Ve
.PP
Moves to the start of the next line, based on the \*(L"leading\*(R" setting.
.PP
If leading isn't set, a default distance of 120% of the font size will be used.
.SS "text"
.IX Subsection "text"
.Vb 1
\&    my $width = $content\->text($text, %options);
.Ve
.PP
Places text on the page.  Returns the width of the text in points.
.PP
Options:
.IP "\(bu" 4
align
.Sp
One of \f(CW\*(C`left\*(C'\fR (default), \f(CW\*(C`center\*(C'\fR, or \f(CW\*(C`right\*(C'\fR.  Text will be placed such that
it begins, is centered on, or ends at the current text position, respectively.
.Sp
In each case, the position will then be moved to the end of the text.
.IP "\(bu" 4
indent
.Sp
Indents the text by the number of points.
.Sp
If \f(CW\*(C`align\*(C'\fR is set to anything other than \f(CW\*(C`left\*(C'\fR, this setting will be ignored.
.IP "\(bu" 4
underline
.Sp
Underlines the text.  The value may be one of the following:
.RS 4
.IP "\(bu" 4
auto
.Sp
Determines the underline distance from the text based on the font and font size.
.IP "\(bu" 4
\&\f(CW$distance\fR
.Sp
Manually set the underline distance in points.  A positive distance moves the
line downward.
.IP "\(bu" 4
[$distance, \f(CW$thickness\fR, ...]
.Sp
Manually set both the underline distance and line thickness, both in points.
.Sp
Repeat these arguments to include multiple underlines.
.RE
.RS 4
.RE
.SS "text_justified"
.IX Subsection "text_justified"
.Vb 1
\&    my $width = $content\->text_justified($text, $width, %options);
.Ve
.PP
As \f(CW\*(C`text\*(C'\fR, filling the specified width by adjusting the space between words.
.SS "paragraph"
.IX Subsection "paragraph"
.Vb 2
\&    # Scalar context
\&    $overflow_text = $content\->paragraph($text, $width, $height, %options);
\&
\&    # Array context
\&    ($overflow, $height) = $content\->paragraph($text, $width, $height, %options);
.Ve
.PP
Fills the rectangle with as much of the provided text as will fit.
.PP
In array context, returns the remaining text (if any) of the positioned text and
the remaining (unused) height.  In scalar context, returns the remaining text
(if any).
.PP
Line spacing follows \*(L"leading\*(R", if set, or 120% of the font size by default.
.PP
\&\fBOptions\fR
.IP "\(bu" 4
align
.Sp
Specifies the alignment for each line of text.  May be set to \f(CW\*(C`left\*(C'\fR (default),
\&\f(CW\*(C`center\*(C'\fR, \f(CW\*(C`right\*(C'\fR, or \f(CW\*(C`justified\*(C'\fR.
.IP "\(bu" 4
align-last
.Sp
Specifies the alignment for the last line of justified text.  May be set to
\&\f(CW\*(C`left\*(C'\fR (default), \f(CW\*(C`center\*(C'\fR, \f(CW\*(C`right\*(C'\fR, or \f(CW\*(C`justified\*(C'\fR.
.IP "\(bu" 4
underline
.Sp
As described in \*(L"text\*(R".
.SS "text_width"
.IX Subsection "text_width"
.Vb 1
\&    my $width = $content\->text_width($line, %overrides);
.Ve
.PP
Returns the width of a line of text based on the current text state attributes.
These can optionally be overridden:
.PP
.Vb 7
\&    my $width = $content\->text_width($line,
\&        font => $font,
\&        size => $size,
\&        character_spacing => $spacing,
\&        word_spacing => $spacing,
\&        hscale => $scale,
\&    );
.Ve
.SH "MIGRATION"
.IX Header "MIGRATION"
See \*(L"\s-1MIGRATION\*(R"\s0 in \s-1PDF::API2\s0 for an overview.
.IP "transform(%hyphen_prefixed_options);" 4
.IX Item "transform(%hyphen_prefixed_options);"
Remove hyphens from option names (\f(CW\*(C`\-translate\*(C'\fR becomes \f(CW\*(C`translate\*(C'\fR, etc.).
.IP "transform_rel" 4
.IX Item "transform_rel"
Replace with \*(L"transform\*(R", setting option \f(CW\*(C`repeat\*(C'\fR to true.  Remove
hyphens from the names of other options.
.IP "linewidth" 4
.IX Item "linewidth"
Replace with \*(L"line_width\*(R".
.IP "linecap" 4
.IX Item "linecap"
Replace with \*(L"line_cap\*(R".
.IP "linejoin" 4
.IX Item "linejoin"
Replace with \*(L"line_join\*(R".
.IP "meterlimit" 4
.IX Item "meterlimit"
.PD 0
.IP "miterlimit" 4
.IX Item "miterlimit"
.PD
Replace with \*(L"miter_limit\*(R".
.IP "linedash" 4
.IX Item "linedash"
Replace with \*(L"line_dash_pattern\*(R".  Remove hyphens from option names.  Rename
\&\f(CW\*(C`\-shift\*(C'\fR to \f(CW\*(C`offset\*(C'\fR.
.IP "flatness" 4
.IX Item "flatness"
Replace with \*(L"flatness_tolerance\*(R".
.IP "poly" 4
.IX Item "poly"
Replace with \*(L"move\*(R" (first two arguments) and \*(L"polyline\*(R" (remaining
arguments).
.IP "endpath" 4
.IX Item "endpath"
Replace with \*(L"end\*(R".
.IP "rect" 4
.IX Item "rect"
Replace with \*(L"rectangle\*(R", converting the \f(CW$w\fR (third) and \f(CW$h\fR (fourth)
arguments to the X and Y values of the upper-right corner:
.Sp
.Vb 2
\&    # Old
\&    $content\->rect($x, $y, $w, $h);
\&
\&    # New
\&    $content\->rectangle($x, $y, $x + $w, $y + $h);
.Ve
.IP "rectxy" 4
.IX Item "rectxy"
Replace with \*(L"rectangle\*(R".
.IP "\fBfill\fR\|(1)" 4
.IX Item "fill"
Replace with \f(CW\*(C`$content\->fill(rule => \*(Aqeven\-odd\*(Aq)\*(C'\fR.
.IP "fillstroke" 4
.IX Item "fillstroke"
Replace with \*(L"paint\*(R".
.IP "\fBclip\fR\|(1)" 4
.IX Item "clip"
Replace with \f(CW\*(C`$content\->clip(rule => \*(Aqeven\-odd\*(Aq)\*(C'\fR.
.IP "image" 4
.IX Item "image"
.PD 0
.IP "formimage" 4
.IX Item "formimage"
.PD
Replace with \*(L"object\*(R".
.IP "charspace" 4
.IX Item "charspace"
Replace with \*(L"character_spacing\*(R".
.IP "wordspace" 4
.IX Item "wordspace"
Replace with \*(L"word_spacing\*(R".
.IP "hspace" 4
.IX Item "hspace"
Replace with \*(L"hscale\*(R".
.IP "lead" 4
.IX Item "lead"
Replace with \*(L"leading\*(R".
.IP "distance" 4
.IX Item "distance"
Replace with \*(L"position\*(R".
.IP "cr" 4
.IX Item "cr"
Replace with either \*(L"position\*(R" (if called with arguments) or \*(L"crlf\*(R" (if
called without arguments).
.IP "nl" 4
.IX Item "nl"
Replace with \*(L"crlf\*(R".
.IP "text(%hyphen_prefixed_options)" 4
.IX Item "text(%hyphen_prefixed_options)"
Remove initial hyphens from option names.
.IP "text_center" 4
.IX Item "text_center"
Replace with \*(L"text\*(R", setting \f(CW\*(C`align\*(C'\fR to \f(CW\*(C`center\*(C'\fR.
.IP "text_right" 4
.IX Item "text_right"
Replace with \*(L"text\*(R", setting \f(CW\*(C`align\*(C'\fR to \f(CW\*(C`right\*(C'\fR.
.IP "paragraph(%hyphen_prefixed_options)" 4
.IX Item "paragraph(%hyphen_prefixed_options)"
Remove initial hyphens from option names.  \f(CW\*(C`\-align\-last\*(C'\fR becomes \f(CW\*(C`align\-last\*(C'\fR.
.IP "section" 4
.IX Item "section"
.PD 0
.IP "paragraphs" 4
.IX Item "paragraphs"
.PD
Replace with \*(L"paragraph\*(R".
.IP "advancewidth" 4
.IX Item "advancewidth"
Replace with \*(L"text_width\*(R".