Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PDF::API2::Content(3) User Contributed Perl DocumentationPDF::API2::Content(3)

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

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

perl v5.24.1			  2017-01-26		 PDF::API2::Content(3)

NAME | SYNOPSIS | METHODS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=PDF::API2::Content&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help