Provided by: libpdf-api2-perl_2.033-1_all bug

NAME

       PDF::API2::Content - Methods for adding graphics and text to a PDF

SYNOPSIS

           # 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.

METHODS

   Coordinate Transformations
       The methods in this section change the coordinate system for the current content object
       relative to the rest of the document.

       If you call more than one of these methods, the PDF 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.

       $content->translate($x, $y)
           Moves the origin along the x and y axes.

       $content->rotate($degrees)
           Rotates the coordinate system counter-clockwise.

           Use a negative argument to rotate clockwise.

       $content->scale($sx, $sy)
           Scales (stretches) the coordinate systems along the x and y axes.

       $content->skew($sa, $sb)
           Skews the coordinate system by $sa degrees (counter-clockwise) from the x axis and $sb
           degrees (clockwise) from the y axis.

       $content->transform(%options)
               $content->transform(
                   -translate => [$x, $y],
                   -rotate    => $degrees,
                   -scale     => [$sx, $sy],
                   -skew      => [$sa, $sb],
               )

           Performs multiple coordinate transformations at once, in the order recommended by the
           PDF specification (translate, rotate, scale, then skew).

           This is equivalent to making each transformation separately.

       $content->transform_rel(%options)
           Makes transformations similarly to "transform", except that it adds to the previously
           set values.

       $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 "transform"
           method instead.

   Graphics State Parameters
       $content->save
           Saves the current graphics state and text state on a stack.

       $content->restore
           Restores the most recently saved graphics state and text state, removing it from the
           stack.

       $content->linewidth($width)
           Sets the width of the stroke.

       $content->linecap($style)
           Sets the style to be used at the end of a stroke.

           0 = Butt Cap
               The stroke ends at the end of the path, with no projection.

           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.

           2 = Projecting Square Cap
               The stroke continues past the end of the path for half the line width.

       $content->linejoin($style)
           Sets the style of join to be used at corners of a path.

           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.

           1 = Round Join
               A circle with a diameter equal to the linewidth is drawn around the corner point,
               producing a rounded corner.

           2 = Bevel Join
               A triangle is drawn to fill in the notch between the two strokes.

       $content->miterlimit($ratio)
           Sets the miter limit when the line join style is a miter join.

           The $ratio 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.

           There is no documented default miter limit.

       $content->linedash()
       $content->linedash($length)
       $content->linedash($dash_length, $gap_length, ...)
       $content->linedash(-pattern => [$dash_length, $gap_length, ...], -shift => $offset)
           Sets the line dash pattern.

           If called without any arguments, a solid line will be drawn.

           If called with one argument, the dashes and gaps will have equal lengths.

           If called with two or more arguments, the arguments represent alternating dash and gap
           lengths.

           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.

       $content->flatness($tolerance)
           (Advanced) Sets the maximum variation in output pixels when drawing curves.

       $content->egstate($object)
           (Advanced) Adds an Extended Graphic State object containing additional state
           parameters.

   Path Construction (Drawing)
       $content->move($x, $y)
           Starts a new path at the specified coordinates.

       $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.

           Note: The line will not appear until you call "stroke".

       $content->hline($x)
       $content->vline($y)
           Shortcut for drawing horizontal and vertical lines from the current position.

       $content->poly($x1, $y1, ..., $xn, $yn)
           Shortcut for creating a polyline path.  Moves to "[$x1, $y1]", and then extends the
           path in lines along the specified coordinates.

       $content->curve($cx1, $cy1, $cx2, $cy2, $x, $y)
           Extends the path in a curve from the current point to "($x, $y)", using the two
           specified points to create a cubic Bezier curve, and updates the current position to
           be the new point.

           Note: The curve will not appear until you call "stroke".

       $content->spline($cx1, $cy1, $x, $y)
           Extends the path in a curve from the current point to "($x, $y)", using the two
           specified points to create a spline, and updates the current position to be the new
           point.

           Note: The curve will not appear until you call "stroke".

       $content->arc($x, $y, $a, $b, $alpha, $beta, $move)
           Extends the path along an arc of an ellipse centered at "[x, y]".  The major and minor
           axes of the ellipse are $a and $b, respectively, and the arc moves from $alpha degrees
           to $beta degrees.  The current position is then set to the endpoint of the arc.

           Set $move to a true value if this arc is the beginning of a new path instead of the
           continuation of an existing path.

       $content->bogen($x1, $y1, $x2, $y2, $radius, $move, $outer, $reverse)
           Extends the path along an arc of a circle of the specified radius between "[x1, y1]"
           to "[x2, y2]".  The current position is then set to the endpoint of the arc.

           Set $move to a true value if this arc is the beginning of a new path instead of the
           continuation of an existing path.

           Set $outer to a true value to draw the larger arc between the two points instead of
           the smaller one.

           Set $reverse to a true value to draw the mirror image of the specified arc.

           "$radius * 2" cannot be smaller than the distance from "[x1, y1]" to "[x2, y2]".

           Note: The curve will not appear until you call "stroke".

       $content->close
           Closes and ends the current path by extending a line from the current position to the
           starting position.

       $content->endpath
           Ends the current path without explicitly enclosing it.

       $content->ellipse($x, $y, $a, $b)
           Creates an elliptical path centered on "[$x, $y]", with major and minor axes specified
           by $a and $b, respectively.

           Note: The ellipse will not appear until you call "stroke" or "fill".

       $content->circle($x, $y, $radius)
           Creates a circular path centered on "[$x, $y]" with the specified radius.

           Note: The circle will not appear until you call "stroke" or "fill".

       $content->pie($x, $y, $a, $b, $alpha, $beta)
           Creates a pie-shaped path from an ellipse centered on "[$x, $y]".  The major and minor
           axes of the ellipse are $a and $b, respectively, and the arc moves from $alpha degrees
           to $beta degrees.

           Note: The pie will not appear until you call "stroke" or "fill".

       $content->rect($x1, $y1, $w1, $h1, ..., $xn, $yn, $wn, $hn)
           Creates paths for one or more rectangles, with their lower left points at "[$x, $y]"
           and with the specified widths and heights.

           Note: The rectangle will not appear until you call "stroke" or "fill".

       $content->rectxy($x1, $y1, $x2, $y2)
           Creates a rectangular path, with "[$x1, $y1]" and and "[$x2, $y2]" specifying opposite
           corners.

           Note: The rectangle will not appear until you call "stroke" or "fill".

   Path Painting (Drawing)
       $content->stroke
           Strokes the current path.

       $content->fill($use_even_odd_fill)
           Fills the current path.

           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.

           See the PDF Specification, section 8.5.3.3, for more details on filling.

       $content->fillstroke($use_even_odd_fill)
           Fills and then strokes the current path.

       $content->clip($use_even_odd_fill)
           Modifies the current clipping path by intersecting it with the current path.

   Colors
       $content->fillcolor($color)
       $content->strokecolor($color)
           Sets the fill or stroke color.

               # Use a named color
               $content->fillcolor('blue');

               # Use an RGB color (start with '#')
               $content->fillcolor('#FF0000');

               # Use a CMYK color (start with '%')
               $content->fillcolor('%FF000000');

           RGB and CMYK colors can have one-byte, two-byte, three-byte, or four-byte values for
           each color.  For instance, cyan can be given as %F000 or %FFFF000000000000.

   External Objects
       $content->image($image_object, $x, $y, $width, $height)
       $content->image($image_object, $x, $y, $scale)
       $content->image($image_object, $x, $y)
               # Example
               my $image_object = $pdf->image_jpeg($my_image_file);
               $content->image($image_object, 100, 200);

           Places an image on the page in the specified location.

           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 $width and $height will be
           measured at 72dpi.

           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.

       $content->formimage($form_object, $x, $y, $scale)
       $content->formimage($form_object, $x, $y)
           Places an XObject on the page in the specified location.

   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.

       $spacing = $content->charspace($spacing)
           Sets the spacing between characters.  This is initially zero.

       $spacing = $content->wordspace($spacing)
           Sets the spacing between words.  This is initially zero (or, in other words, just the
           width of the space).

           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 PDF 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.

       $scale = $content->hscale($scale)
           Sets and returns 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.

       $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).

       $mode = $content->render($mode)
           Sets the text rendering mode.

           0 = Fill text
           1 = Stroke text (outline)
           2 = Fill, then stroke text
           3 = Neither fill nor stroke text (invisible)
           4 = Fill text and add to path for clipping
           5 = Stroke text and add to path for clipping
           6 = Fill, then stroke text and add to path for clipping
           7 = Add text to path for clipping
       $distance = $content->rise($distance)
           Adjusts the baseline up or down from its current location.  This is initially zero.

           Use this for creating superscripts or subscripts (usually with an adjustment to the
           font size as well).

       %state = $content->textstate(charspace => $value, wordspace => $value, ...)
           Shortcut for setting multiple text state parameters at once.

           This can also be used without arguments to retrieve the current text state settings.

           Note: This does not currently work with the "save" and "restore" commands.

       $content->font($font_object, $size)
               # Example
               my $pdf = PDF::API2->new();
               my $font = $pdf->corefont('Helvetica');
               $content->font($font, 12);

           Sets the font and font size.

   Text-Positioning
       Note: There is a very good chance that these commands will be replaced in a future
       release.

       $content->distance($dx, $dy)
           Moves to the start of the next line, offset by the given amounts, which are both
           required.

       $content->cr()
       $content->cr($vertical_offset)
           Moves the cursor to the start of the line when called without an argument.  If leading
           has been set, the cursor will move to the next line instead.

           An offset can be passed as an argument to override the leading value.  A positive
           offset will move the cursor up, and a negative offset will move the cursor down.

           Pass zero as the argument to ignore the leading and get just a carriage return.

       $content->nl()
           Moves to the start of the next line.

       ($tx, $ty) = $content->textpos()
           Gets the current estimated text position.

           Note: This does not affect the PDF in any way.

   Text-Showing
       $width = $content->text($text, %options)
           Adds text to the page.

           Options:

           -indent
               Indents the text by the number of points.

           -underline => 'auto'
           -underline => $distance
           -underline => [$distance, $thickness, ...]
               Underlines the text.  $distance is the number of units beneath the baseline, and
               $thickness is the width of the line.

               Multiple underlines can be made by passing several distances and thicknesses.

       $content->text_center($text)
           As "text", but centered on the current point.

       $txt->text_right $text, %options
           As "text", but right-aligned to the current point.

       $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.

   Advanced Methods
       $content->add @content
           Add raw content to the PDF stream.  You will generally want to use the other methods
           in this class instead.

       $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.

       $content->textstart
           Starts a text object.  You will likely want to use the "text" method instead.

       $content->textend
           Ends a text object.