PDF::Builder::Content - Methods for adding graphics and text to a PDF
# Start with a PDF page (new or opened) my $pdf = PDF::Builder->new(); my $page = $pdf->page(); # Add new content object(s) my $content = $page->gfx(); # and/or (as separate object name) my $content = $page->text(); # Then call the methods below to add graphics and text to the page. # Note that negative coordinates can have unpredictable effects, so # keep your coordinates non-negative!
All public methods listed, except as otherwise noted, return $self.
$self
The methods in this section change the coordinate system for the current content object relative to the rest of the document. Note: the changes are relative to the original page coordinates (and thus, absolute), not to the previous position! Thus, translate(10, 10); translate(10, 10); ends up only moving the origin to [10, 10], rather than to [20, 20]. There is one call, transform_rel(), which makes your changes relative to the previous position.
translate(10, 10); translate(10, 10);
[10, 10]
[20, 20]
transform_rel()
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.
CAUTION: a text object ($content) behaves a bit differently. Individual translate, rotate, scale, and skew calls cancel out any previous settings. If you want to combine multiple transformations for text, use the transform call.
transform
Moves the origin along the x and y axes by $dx and $dy respectively.
$dx
$dy
Rotates the coordinate system counter-clockwise (anti-clockwise) around the current origin. Use a negative argument to rotate clockwise. Note that 360 degrees will be treated as 0 degrees.
Scales (stretches) the coordinate systems along the x and y axes. Separate multipliers are provided for x and y.
Skews the coordinate system by $skx degrees (counter-clockwise/anti-clockwise) from the x axis and $sky degrees (clockwise) from the y axis. Note that 360 degrees will be treated the same as 0 degrees.
$skx
$sky
Use one or more of the given %opts:
$content->transform( -translate => [$dx,$dy], -rotate => $degrees, -scale => [$sx,$sy], -skew => [$skx,$sky], -matrix => [$a, $b, $c, $d, $e, $f], -point => [$x,$y] )
A six element list may be given (-matrix) for a further transformation matrix:
-matrix
$a = cos(rot) * scale factor for X $b = sin(rot) * tan(skew for X) $c = -sin(rot) * tan(skew for Y) $d = cos(rot) * scale factor for Y $e = translation for X $f = translation for Y
Performs multiple coordinate transformations at once, in the order recommended by the PDF specification (translate, rotate, scale, skew). This is equivalent to making each transformation separately, in the indicated order. A matrix of 6 values may also be given (-matrix). The transformation matrix is updated. A -point may be given (a point to be multiplied [transformed] by the completed matrix).
-point
Makes transformations similarly to transform, except that it adds to the previously set values, rather than replacing them (except for scale, which multiplies the new values with the old).
Unlike transform, -matrix and -point are not supported.
(Advanced) Sets the current transformation matrix manually. Unless you have a particular need to enter transformations manually, you should use the transform method instead.
In text mode, the text matrix is returned. In graphics mode, $self is returned.
The following calls also affect the text state.
Sets the width of the stroke. This is the line drawn in graphics mode, or the outline of a character in text mode (with appropriate render mode). If no $width is given, the current setting is returned. If the width is being set, $self is returned so that calls may be chained.
render
$width
Sets the style to be used at the end of a stroke. This applies to lines which come to a free-floating end, not to "joins" ("corners") in polylines (see linejoin).
linejoin
The stroke ends at the end of the path, with no projection.
A semicircular arc is drawn around the end of the path with a diameter equal to the line width, and is filled in.
The stroke continues past the end of the path for half the line width.
If no $style is given, the current setting is returned. If the style is being set, $self is returned so that calls may be chained.
$style
Sets the style of join to be used at corners of a path (within a multisegment polyline).
The outer edges of the strokes extend until they meet, up to the limit specified by miterlimit. If the limit would be surpassed, a bevel join is used instead. For a given linewidth, the more acute the angle is (closer to 0 degrees), the higher the ratio of miter length to linewidth will be, and that's what miterlimit controls.
A filled circle with a diameter equal to the linewidth is drawn around the corner point, producing a rounded corner. The arc will meet up with the sides of the line in a smooth tangent.
A filled triangle is drawn to fill in the notch between the two strokes.
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.
The default miter limit is 10.0 (approximately 11.5 degree cutoff angle).
If no $ratio is given, the current setting is returned. If the ratio is being set, $self is returned so that calls may be chained.
$ratio
Note: This was originally misnamed as meterlimit. That name is deprecated and will be removed some time in the future, so you should change any usage in your code from meterlimit to miterlimit.
meterlimit
miterlimit
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 (strokes and spaces) 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, the -pattern array may have one or more elements, specifying the dash and gap lengths. A dash phase may be set (-shift), which is a positive integer specifying the distance into the pattern at which to start the dashed line. If you are using -full or -clear hash entries, please be aware that they have been deprecated and will be removed. Use the -pattern array instead. Note that if you wish to give a shift amount, using -shift, you need to use -pattern instead of one or two elements.
-shift
-pattern
If an odd number of dash array elements are given, the list is repeated by the reader software to form an even number of elements (pairs).
If a single argument of -1 is given, the current setting is returned. This is an array consisting of two elements: an anonymous array containing the dash pattern (default: empty), and the shift (offset) amount (default: 0). If the dash pattern is being set, $self is returned so that calls may be chained.
(Advanced) Sets the maximum variation in output pixels when drawing curves.
If no $tolerance is given, the current setting is returned. If the tolerance is being set, $self is returned so that calls may be chained.
$tolerance
(Advanced) Adds an Extended Graphic State object containing additional state parameters.
Starts a new path at the specified coordinates. Note that multiple x,y pairs can be given, although this isn't that useful (only the last pair would have an effect).
Closes and ends the current path by extending a line from the current position to the starting position.
Ends the current path without explicitly enclosing it. That is, unlike close, there is no line segment drawn back to the starting position.
close
Note: None of these will actually be visible until you call stroke or fill. They are merely setting up the path to draw.
stroke
fill
Extends the path in a line from the current coordinates to the specified coordinates, and updates the current position to be the new coordinates.
Multiple additional [$x,$y] pairs are permitted, to draw joined multiple line segments. Note that this is not equivalent to a polyline (see poly), because the first [$x,$y] pair in a polyline is a move operation. Also, the linecap setting will be used rather than the linejoin setting for treating the ends of segments.
[$x,$y]
poly
linecap
Shortcuts for drawing horizontal and vertical lines from the current position. They are like line(), but to the new x and current y (hline), or to the the current x and new y (vline).
line()
hline
vline
This is a shortcut for creating a polyline path. It moves to [$x1,$y1], and then extends the path in line segments along the specified coordinates. The current position is changed to the last [$x,$y] pair given.
[$x1,$y1]
The difference between a polyline and a line with multiple [$x,$y] pairs is that the first pair in a polyline are a move, while in a line they are a draw. Also, linejoin instead of linecap is used to control the appearance of the ends of line segments.
line
This creates paths for one or more rectangles, with their lower left points at [$x,$y] and specified widths (+x direction) and heights (+y direction). Negative widths and heights are permitted, which draw to the left (-x) and below (-y) the given corner point, respectively. The current position is changed to the [$x,$y] of the last rectangle given. Note that this is the starting point of the rectangle, not the end point.
This creates a rectangular path, with [$x1,$y1] and [$x2,$y2] specifying opposite corners. They can be Lower Left and Upper Right, or Upper Left and Lower Right, in either order, so long as they are diagonally opposite each other. The current position is changed to the [$x1,$y1] (first) pair.
[$x2,$y2]
This creates a circular path centered on [$xc,$yc] with the specified radius. It does not change the current position.
[$xc,$yc]
This creates a closed elliptical path centered on [$xc,$yc], with axis radii (semidiameters) specified by $rx (x axis) and $ry (y axis), respectively. It does not change the current position.
$rx
$ry
This extends the path along an arc of an ellipse centered at [$xc,$yc]. The semidiameters of the elliptical curve are $rx (x axis) and $ry (y axis), respectively, and the arc sweeps from $alpha degrees to $beta degrees. The current position is then set to the endpoint of the arc.
$alpha
$beta
Set $move to a true value if this arc is the beginning of a new path instead of the continuation of an existing path. Either way, the current position will be updated to the end of the arc. Use $rx == $ry for a circular arc.
$move
$rx == $ry
The optional $dir arc sweep direction defaults to 0 (false), for a counter-clockwise/anti-clockwise sweep. Set to 1 (true) for a clockwise sweep.
$dir
Creates a pie-shaped path from an ellipse centered on [$xc,$yc]. The x-axis and y-axis semidiameters of the ellipse are $rx and $ry, respectively, and the arc sweeps from $alpha degrees to $beta degrees. It does not change the current position. Depending on the sweep angles and direction, this can draw either the pie "slice" or the remaining pie (with slice removed). Use $rx == $ry for a circular pie. Use a different [$xc,$yc] for the slice, to offset it from the remaining pie.
This is a shortcut to draw a section of elliptical (or circular) arc and connect it to the center of the ellipse or circle, to form a pie shape.
This extends the path in a curve from the current point to [$x,$y], using the two specified control points to create a cubic Bezier curve, and updates the current position to be the new point ([$x,$y]).
Within a text object, the text's baseline follows the Bezier curve.
Note that while multiple sets of three [x,y] pairs are permitted, these are treated as independent cubic Bezier curves. There is no attempt made to smoothly blend one curve into the next!
[x,y]
This 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.
Internally, these splines are cubic Bezier curves (see curve) with the two control points synthesized from the two given points.
curve
Note that while multiple sets of two [x,y] pairs are permitted, these are treated as independent splines. There is no attempt made to smoothly blend one spline into the next!
Further note that this "spline" may not match a common definition of a spline being a curve passing through all the given points! It is a piecewise cubic Bezier curve. Use with care, and do not make assumptions about splines for you or your readers.
(German for bow, as in a segment (arc) of a circle. This is a segment of a circle defined by the intersection of two circles of a given radius, with the two intersection points as inputs. There are four possible resulting arcs, which can be selected with $larger and $reverse.)
$larger
$reverse
This 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 ([$x2,$y2]).
Set $move to a true value if this arc is the beginning of a new path instead of the continuation of an existing path. Note that this ($move = false) is not a straight line to P1 and then the arc, but a blending into the curve from the current point. It will often not pass through P1!
Set $larger to a true value to draw the larger ("outer") arc between the two points, instead of the smaller one. Both arcs are drawn clockwise from P1 to P2.
Set $reverse to a true value to draw the mirror image of the specified arc (flip it over, so that its center point is on the other side of the line connecting the two points). Both arcs are drawn counter-clockwise from P1 to P2.
The $radius value cannot be smaller than half the distance from [$x1,$y1] to [$x2,$y2]. If it is too small, the radius will be set to half the distance between the points (resulting in an arc that is a semicircle). This is a silent error.
$radius
Strokes the current path.
Fill the current path's enclosed area. It does not stroke the enclosing path around the area.
If the path intersects with itself, the nonzero winding rule will be used to determine which part of the path is filled in. This basically fills in everything inside the path. If you would prefer to use the even-odd rule, pass a true argument. This basically will fill alternating closed sub-areas.
See the PDF Specification, section 8.5.3.3, for more details on filling.
Fill the enclosed area and then stroke the current path.
Modifies the current clipping path by intersecting it with the current path.
Sets the fill (enclosed area) or stroke (path) color. The interior of text characters are filled, and (if ordered by render) the outline is stroked.
# Use a named color # -> RGB color model # there are many hundreds of named colors defined in # PDF::Builder::Resource::Colors $content->fillcolor('blue'); # Use an RGB color (# followed by 3, 6, 9, or 12 hex digits) # -> RGB color model # This maps to 0-1.0 values for red, green, and blue $content->fillcolor('#FF0000'); # red # Use a CMYK color (% followed by 4, 8, 12, or 16 hex digits) # -> CMYK color model # This maps to 0-1.0 values for cyan, magenta, yellow, and black $content->fillcolor('%FF000000'); # cyan # Use an HSV color (! followed by 3, 6, 9, or 12 hex digits) # -> RGB color model # This maps to 0-360 degrees for the hue, and 0-1.0 values for # saturation and value $content->fillcolor('!FF0000'); # Use an HSL color (& followed by 3, 6, 9, or 12 hex digits) # -> L*a*b color model # This maps to 0-360 degrees for the hue, and 0-1.0 values for # saturation and lightness. Note that 360 degrees = 0 degrees (wraps) $content->fillcolor('&FF0000'); # Use an L*a*b color ($ followed by 3, 6, 9, or 12 hex digits) # -> L*a*b color model # This maps to 0-100 for L, -100 to 100 for a and b $content->fillcolor('$FF0000');
In all cases, if too few digits are given, the given digits are silently right-padded with 0's (zeros). If an incorrect number of digits are given, the next lowest number of expected digits are used, and the remaining digits are silently ignored.
# A single number between 0.0 (black) and 1.0 (white) is an alternate way # of specifying a gray scale. $content->fillcolor(0.5); # Three array elements between 0.0 and 1.0 is an alternate way of specifying # an RGB color. $content->fillcolor(0.3, 0.59, 0.11); # Four array elements between 0.0 and 1.0 is an alternate way of specifying # a CMYK color. $content->fillcolor(0.1, 0.9, 0.3, 1.0);
In all cases, if a number is less than 0, it is silently turned into a 0. If a number is greater than 1, it is silently turned into a 1. This "clamps" all values to the range 0.0-1.0.
# A single reference is treated as a pattern or shading space. # Two or more entries with the first element a Perl reference, is treated # as either an indexed colorspace reference plus color-index(es), or # as a custom colorspace reference plus parameter(s).
If no value was passed in, the current fill color (or stroke color) array is returned, otherwise $self is returned.
Sets the shading matrix.
A hash reference that includes a name() method for the shade name.
name()
An array of 4 items: X-translation, Y-translation, X-scaled and translated, Y-scaled and translated.
# 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 (specifies the lower left corner of the image).
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.
[0,0]
$height
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. (72 Big Points is one inch)
Places an XObject on the page in the specified location (giving the lower left corner of the image) and scale (applied to the image's native height and width). If no scale is given, use 1 for both X and Y. If one scale is given, use for both X and Y. If two scales given, they are for (separately) X and Y. In general, you should not greatly distort an image by using greatly different scaling factors in X and Y, although it is now possible for when that effect is desirable.
Note that while this method is named form image, it is also used for the psedoimages created by the barcode routines. Images are naturally dimensionless (1 point square) and need at some point to be scaled up to the desired point size. Barcodes are naturally sized in points, and should be scaled at approximately 1. Therefore, it would greatly overscale barcodes to multiply by image width and height within formimage, and require scaling of 1/width and 1/height in the call. So, we leave scaling alone within formimage and have the user manually scale images by the image width and height (in pixels) in the call to formimage.
formimage
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.
Sets additional spacing between characters in a line. This is in points, and is initially zero. It may be positive to give an expanded effect to words, or it may be negative to give a condensed effect to words. If $spacing is given, the current setting is replaced by that value and $self is returned (to permit chaining). If $spacing is not given, the current setting is returned.
$spacing
Sets additional spacing between words in a line. This is in points and is initially zero (i.e., just the width of the space, without anything extra). It may be negative to close up sentences a bit. If $spacing is given, the current setting is replaced by that value and $self is returned (to permit chaining). If $spacing is not given, the current setting is returned.
Note that it is a limitation of the PDF specification (as of version 1.7, section 9.3.3) that only spacing with an ASCII space (x20) is adjusted. Neither required blanks (xA0) nor any multiple-byte spaces (including thin and wide spaces) are currently adjusted.
Sets the percentage of horizontal text scaling (relative sizing, not spacing). This is initally 100 (percent, i.e., no scaling). A scale of greater than 100 will stretch the text, while less than 100 will compress it. If $scale is given, the current setting is replaced by that value and $self is returned (to permit chaining). If $scale is not given, the current setting is returned.
$scale
Note that scaling affects all of the character widths, interletter spacing, and interword spacing. It is inadvisable to stretch or compress text by a large amount, as it will quickly make the text unreadable. If your objective is to justify text, you will usually be better off using charspace and wordspace to expand (or slightly condense) a line to fill a desired width. Also see the text_justify() calls for this purpose.
charspace
wordspace
text_justify()
Note: This was originally misnamed as hspace (it is a horizontal scaling factor, not an amount of horizontal space). That name is deprecated and will be removed some time in the future, so you should change any usage in your code from hspace to hscale.
hspace
hscale
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). The unit of leading is points. If $leading is given, the current setting is replaced by that value and $self is returned (to permit chaining). If $leading is not given, the current setting is returned.
$leading
Sets the text rendering mode.
If $mode is given, the current setting is replaced by that value and $self is returned (to permit chaining). If $mode is not given, the current setting is returned.
$mode
Adjusts the baseline up or down from its current location. This is initially zero. A $dist greater than 0 moves the baseline up the page (y increases).
$dist
Use this for creating superscripts or subscripts (usually along with an adjustment to the font size). If $dist is given, the current setting is replaced by that value and $self is returned (to permit chaining). If $dist is not given, the current setting is returned.
This is a shortcut for setting multiple text state parameters at once. If any parameters are set, an empty hash is returned. This can also be used without arguments to retrieve the current text state settings (a hash of the state is returned).
Note: This does not work with the save and restore commands.
save
restore
Sets the font and font size.
# Example (12 point Helvetica) my $pdf = PDF::Builder->new(); my $fontname = $pdf->corefont('Helvetica'); $content->font($fontname, 12);
This moves to the start of the previously-written line, plus an offset by the given amounts, which are both required. [0,0] would overwrite the previous line, while [0,36] would place the new line 36pt above the old line (higher y). The $dx moves to the right, if positive.
[0,36]
distance is analogous to graphic's move, except that it is relative to the beginning of the previous text write, not to the coordinate origin. Note that subsequent text writes will be relative to this new starting (left) point and Y position! E.g., if you give a non-zero $dx, subsequent lines will be indented by that amount.
distance
move
If passed without an argument, moves (down) to the start of the next line (distance set by lead). This is similar to nl().
lead
nl()
If passed with an argument, the lead distance is ignored and the next line starts that far up the page (positive value) or down the page (negative value) from the current line. "Y" increases upward, so a negative value would normally be used to get to the next line down.
An argument of 0 would simply return to the start of the present line, overprinting it with new text. That is, it acts as a simple carriage return, without a linefeed.
Moves to the start of the next line (see lead). If $indent is not given, or is 0, there is no indentation. Otherwise, indent by that amount (outdent if a negative value). The unit of measure is hundredths of a "unit of text space", or roughly 88 per em.
$indent
Returns the current text position on the page (where next write will happen) as an array.
Note: This does not affect the PDF in any way. It only tells you where the the next write will occur.
Options %opts:
Change the font used, overriding $self->{' font'}. The font must have been previously created (i.e., is not the name). Example: use Times-Roman.
Change the font size, overriding $self->{' fontsize'}. Example: 12 pt font.
Change the additional word spacing, overriding $self->wordspace(). Example: add 0.8 pt between words.
Change the additional character spacing, overriding $self->charspace(). Example: subtract 2.1 pt between letters, to condense the text.
Change the horizontal scaling factor, overriding $self->hscale(). Example: stretch text to 125% of its natural width.
Returns the width of the $string based on all currently set text-state attributes. These can optionally be overridden with %opts. Note that these values temporarily replace the existing values, not scaling them up or down. For example, if the existing charspace is 2, and you give in options a value of 3, the value used is 3, not 5.
Note: This does not affect the PDF in any way. It only tells you how much horizontal space a text string will take up.
Adds text to the page (left justified). The width used (in points) is returned.
Options:
Indents the text by the number of points (A value less than 0 gives an outdent.
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.
$distance
$thickness
Example:
# 3 underlines: # distance 4, thickness 1, color red # distance 7, thickness 1.5, color yellow # distance 11, thickness 2, color (strokecolor default) -underline=>[4,[1,'red'],7,[1.5,'yellow'],11,2],
Saves the current graphics state on a PDF stack. See PDF definition 8.4.2 through 8.4.4 for details. This includes the line width, the line cap style, line join style, miter limit, line dash pattern, stroke color, fill color, current transformation matrix, current clipping port, flatness, and dictname. This method applies to both text and gfx objects.
Restores the most recently saved graphics state (see save), removing it from the stack. You cannot restore the graphics state (pop it off the stack) unless you have done at least one save (pushed it on the stack). This method applies to both text and gfx objects.
Add raw content to the PDF stream. You will generally want to use the other methods in this class instead.
Marks content for compression on output. This is done automatically in nearly all cases, so you shouldn't need to call this yourself.
Starts a text object. You will likely want to use the text method (text context, not text output) instead.
text
Ends a text object.
To install PDF::Builder, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PDF::Builder
CPAN shell
perl -MCPAN -e shell install PDF::Builder
For more information on module installation, please visit the detailed CPAN module installation guide.