1PDF::API2::Content(3) User Contributed Perl DocumentationPDF::API2::Content(3)
2
6 PDF::API2::Content - Methods for adding graphics and text to a PDF
7
9 # Start with a PDF page (new or opened)
10 my $pdf = PDF::API2->new();
11 my $page = $pdf->page();
12 # Add a new content object
14 my $content = $page->graphics();
15 my $content = $page->text();
16 # Then call the methods below to add graphics and text to the page.
18
20 The methods in this section change the coordinate system for the
21 current content object relative to the rest of the document.
22 Changes to the coordinate system only affect subsequent paths or text.
24 A call to any of the methods in this section resets the coordinate
26 system before applying its changes, unless the "relative" option is
27 set.
28 translate
30 $content = $content->translate($x, $y);
31 Moves the origin along the x and y axes.
33 rotate
35 $content = $content->rotate($degrees);
36 Rotates the coordinate system counter-clockwise.
38 Use a negative argument to rotate clockwise.
40 scale
42 $content = $content->scale($x, $y);
43 Scales (stretches) the coordinate systems along the x and y axes. A
45 value of 1 for either $x or $y represents 100% scale (i.e. no change).
46 skew
48 $content = $content->skew($a, $b);
49 Skews the coordinate system by $a degrees (counter-clockwise) from the
51 x axis and $b degrees (clockwise) from the y axis.
52 transform
54 $content = $content->transform(
55 translate => [$x, $y],
56 rotate => $degrees,
57 scale => [$x, $y],
58 skew => [$a, $b],
59 repeat => $boolean,
60 );
61 Performs multiple coordinate transformations, in the order recommended
63 by the PDF specification (translate, rotate, scale, then skew).
64 Omitted options will be unchanged.
65 If "repeat" is true and if this is not the first call to a
67 transformation method, the previous transformation will be performed
68 again, modified by any other provided arguments.
69 matrix
71 $graphics = $graphics->matrix($a, $b, $c, $d, $e, $f);
72 ($a, $b, $c, $d, $e, $f) = $text->matrix($a, $b, $c, $d, $e, $f);
74 Sets the current transformation matrix manually. Unless you have a
76 particular need to enter transformations manually, you should use the
77 "transform" method instead.
78 The return value differs based on whether the caller is a graphics
80 content object or a text content object.
81
83 save
84 $content = $content->save();
85 Saves the current graphics state on a stack.
87 restore
89 $content = $content->restore();
90 Restores the most recently saved graphics state, removing it from the
92 stack.
93 line_width
95 $content = $content->line_width($points);
96 Sets the width of the stroke in points.
98 line_cap
100 $content = $content->line_cap($style);
101 Sets the shape that will be used at the ends of open subpaths (and
103 dashes, if any) when they are stroked.
104 • "butt" or 0 = Butt Cap, default
106 The stroke ends at the end of the path, with no projection.
108 • "round" or 1 = Round Cap)
110 An arc is drawn around the end of the path with a diameter equal to
112 the line width, and is filled in.
113 • "square" or 2 = Projecting Square Cap
115 The stroke continues past the end of the path for half the line
117 width.
118 line_join
120 $content = $content->line_join($style);
121 Sets the style of join to be used at corners of a path.
123 • "miter" or 0 = Miter Join, default
125 The outer edges of the stroke extend until they meet, up to the
127 limit specified below. If the limit would be surpassed, a bevel
128 join is used instead.
129 • "round" or 1 = Round Join
131 A circle with a diameter equal to the linewidth is drawn around the
133 corner point, producing a rounded corner.
134 • "bevel" or 2 = Bevel Join
136 A triangle is drawn to fill in the notch between the two strokes.
138 miter_limit
140 $content = $content->miter_limit($ratio);
141 Sets the miter limit when the line join style is a miter join.
143 The $ratio is the maximum length of the miter (inner to outer corner)
145 divided by the line width. Any miter above this ratio will be converted
146 to a bevel join. The practical effect is that lines meeting at shallow
147 angles are chopped off instead of producing long pointed corners.
148 There is no documented default miter limit.
150 line_dash_pattern
152 # Solid line
153 $content = $content->line_dash_pattern();
154 # Equal length lines and gaps
156 $content = $content->line_dash_pattern($length);
157 # Specified line and gap lengths
159 $content = $content->line_dash_pattern($line1, $gap1, $line2, $gap2, ...);
160 # Offset the starting point
162 $content = $content->line_dash_pattern(
163 pattern => [$line1, $gap1, $line2, $gap2, ...],
164 offset => $points,
165 );
166 Sets the line dash pattern.
168 If called without any arguments, a solid line will be drawn.
170 If called with one argument, the dashes and gaps will have equal
172 lengths.
173 If called with two or more arguments, the arguments represent
175 alternating dash and gap lengths.
176 If called with a hash of arguments, a dash phase may be set, which
178 specifies the distance into the pattern at which to start the dash.
179 flatness_tolerance
181 $content = $content->flatness_tolerance($tolerance);
182 Sets the maximum distance in device pixels between the mathematically
184 correct path for a curve and an approximation constructed from straight
185 line segments.
186 $tolerance is an integer between 0 and 100, where 0 represents the
188 device's default flatness tolerance.
189 egstate
191 $content = $content->egstate($object);
192 Adds a PDF::API2::Resource::ExtGState object containing a set of
194 graphics state parameters.
195
197 Note that paths will not appear until a path painting method is called
198 ("stroke", "fill", or "paint").
199 move
201 $content = $content->move($x, $y);
202 Starts a new path at the specified coordinates.
204 line
206 $content = $content->line($x, $y);
207 Extends the path in a line from the current coordinates to the
209 specified coordinates.
210 hline
212 $content = $content->hline($x);
213 Extends the path in a horizontal line from the current position to the
215 specified x coordinate.
216 vline
218 $content = $content->vline($x);
219 Extends the path in a vertical line from the current position to the
221 specified y coordinate.
222 polyline
224 $content = $content->polyline($x1, $y1, $x2, $y2, ...);
225 Extends the path from the current position in one or more straight
227 lines.
228 curve
230 $content = $content->curve($cx1, $cy1, $cx2, $cy2, $x, $y);
231 Extends the path in a curve from the current point to "($x, $y)", using
233 the two specified points to create a cubic Bezier curve.
234 spline
236 $content = $content->spline($cx1, $cy1, $x, $y);
237 Extends the path in a curve from the current point to "($x, $y)", using
239 the two specified points to create a spline.
240 arc
242 $content = $content->arc($x, $y, $major, $minor, $a, $b);
243 Extends the path along an arc of an ellipse centered at "[$x, $y]".
245 $major and $minor represent the axes of the ellipse, and the arc moves
246 from $a degrees to $b degrees.
247 close
249 $content = $content->close();
250 Closes the current path by extending a line from the current position
252 to the starting position.
253 end
255 $content = $content->end();
256 Ends the current path without filling or stroking.
258
260 The following are convenience methods for drawing closed paths.
261 Note that shapes will not appear until a path painting method is called
263 ("stroke", "fill", or "paint").
264 rectangle
266 $content = $content->rectangle($x1, $y1, $x2, $y2);
267 Creates a new rectangle-shaped path, between the two points "[$x1,
269 $y1]" and "[$x2, $y2]".
270 circle
272 $content = $content->circle($x, $y, $radius);
273 Creates a new circular path centered on "[$x, $y]" with the specified
275 radius.
276 ellipse
278 $content = $content->ellipse($x, $y, $major, $minor);
279 Creates a new elliptical path centered on "[$x, $y]" with the specified
281 major and minor axes.
282 pie
284 $content = $content->pie($x, $y, $major, $minor, $a, $b);
285 Creates a new wedge-shaped path from an ellipse centered on "[$x, $y]"
287 with the specified major and minor axes, extending from $a degrees to
288 $b degrees.
289
291 stroke_color
292 $content = $content->stroke_color($color, @arguments);
293 Sets the stroke color, which is black by default.
295 # Use a named color
297 $content->stroke_color('blue');
298 # Use an RGB color (start with '#')
300 $content->stroke_color('#FF0000');
301 # Use a CMYK color (start with '%')
303 $content->stroke_color('%FF000000');
304 # Use a spot color with 100% coverage.
306 my $spot = $pdf->colorspace('spot', 'PANTONE Red 032 C', '#EF3340');
307 $content->stroke_color($spot, 1.0);
308 RGB and CMYK colors can have one-byte, two-byte, three-byte, or four-
310 byte values for each color, depending on the level of precision needed.
311 For instance, cyan can be given as %F000 or %FFFF000000000000.
312 fill_color
314 $content = $content->fill_color($color, @arguments);
315 Sets the fill color, which is black by default. Arguments are the same
317 as in "stroke_color".
318 stroke
320 $content = $content->stroke();
321 Strokes the current path.
323 fill
325 $content = $content->fill(rule => $rule);
326 Fills the current path.
328 $rule describes which areas are filled in when the path intersects with
330 itself.
331 • nonzero (default)
333 Use the nonzero winding number rule. This tends to mean that the
335 entire area enclosed by the path is filled in, with some exceptions
336 depending on the direction of the path.
337 • even-odd
339 Use the even-odd rule. This tends to mean that the presence of
341 fill alternates each time the path is intersected.
342 See PDF specification 1.7 section 8.5.3.3, Filling, for more details.
344 paint
346 $content = $content->paint(rule => $rule);
347 Fills and strokes the current path. $rule is as described in "fill".
349 clip
351 $content = $content->clip(rule => $rule);
352 Modifies the current clipping path (initially the entire page) by
354 intersecting it with the current path following the next path-painting
355 command. $rule is as described in "fill".
356
358 object
359 $content = $content->object($object, $x, $y, $scale_x, $scale_y);
360 Places an image or other external object (a.k.a. XObject) on the page
362 in the specified location.
363 For images, $scale_x and $scale_y represent the width and height of the
365 image on the page in points. If $scale_x is omitted, it will default
366 to 72 pixels per inch. If $scale_y is omitted, the image will be
367 scaled proportionally based on the image dimensions.
368 For other external objects, the scale is a multiplier, where 1 (the
370 default) represents 100% (i.e. no change).
371 If coordinate transformations have been made (see Coordinate
373 Transformations above), the position and scale will be relative to the
374 updated coordinates.
375 If no coordinate transformations are needed, this method can be called
377 directly from the PDF::API2::Page object instead.
378
380 All of the following parameters that take a size are applied before any
381 scaling takes place, so you don't need to adjust values to counteract
382 scaling.
383 font
385 $content = $content->font($font, $size);
386 Sets the font and font size. $font is an object created by calling
388 "font" in PDF::API2 to add the font to the document.
389 my $pdf = PDF::API2->new();
391 my $page = $pdf->page();
392 my $text = $page->text();
393 my $font = $pdf->font('Helvetica');
395 $text->font($font, 24);
396 $text->position(72, 720);
397 $text->text('Hello, World!');
398 $pdf->save('sample.pdf');
400 character_spacing
402 $spacing = $content->character_spacing($spacing);
403 Sets the spacing between characters. This is initially zero.
405 word_spacing
407 $spacing = $content->word_spacing($spacing);
408 Sets the spacing between words. This is initially zero (i.e. just the
410 width of the space).
411 Word spacing might only affect simple fonts and composite fonts where
413 the space character is a single-byte code. This is a limitation of the
414 PDF specification at least as of version 1.7 (see section 9.3.3). It's
415 possible that a later version of the specification will support word
416 spacing in fonts that use multi-byte codes.
417 hscale
419 $scale = $content->hscale($scale);
420 Sets/gets the percentage of horizontal text scaling. Enter a scale
422 greater than 100 to stretch text, less than 100 to squeeze text, or 100
423 to disable any existing scaling.
424 leading
426 $leading = $content->leading($leading);
427 Sets/gets the text leading, which is the distance between baselines.
429 This is initially zero (i.e. the lines will be printed on top of each
430 other).
431 render
433 $mode = $content->render($mode);
434 Sets the text rendering mode.
436 • 0 = Fill text
438 • 1 = Stroke text (outline)
440 • 2 = Fill, then stroke text
442 • 3 = Neither fill nor stroke text (invisible)
444 • 4 = Fill text and add to path for clipping
446 • 5 = Stroke text and add to path for clipping
448 • 6 = Fill, then stroke text and add to path for clipping
450 • 7 = Add text to path for clipping
452 rise
454 $distance = $content->rise($distance);
455 Adjusts the baseline up or down from its current location. This is
457 initially zero.
458 Use this to create superscripts or subscripts (usually with an
460 adjustment to the font size as well).
461
463 position
464 # Set
465 $content = $content->position($x, $y);
466 # Get
468 ($x, $y) = $content->position();
469 If called with arguments, moves to the start of the current line of
471 text, offset by $x and $y.
472 If called without arguments, returns the current position of the cursor
474 (before the effects of any coordinate transformation methods).
475 crlf
477 $content = $content->crlf();
478 Moves to the start of the next line, based on the "leading" setting.
480 If leading isn't set, a default distance of 120% of the font size will
482 be used.
483 text
485 my $width = $content->text($text, %options);
486 Places text on the page. Returns the width of the text in points.
488 Options:
490 • align
492 One of "left" (default), "center", or "right". Text will be placed
494 such that it begins, is centered on, or ends at the current text
495 position, respectively.
496 In each case, the position will then be moved to the end of the
498 text.
499 • indent
501 Indents the text by the number of points.
503 If "align" is set to anything other than "left", this setting will
505 be ignored.
506 • underline
508 Underlines the text. The value may be one of the following:
510 • auto
512 Determines the underline distance from the text based on the
514 font and font size.
515 • $distance
517 Manually set the underline distance in points. A positive
519 distance moves the line downward.
520 • [$distance, $thickness, ...]
522 Manually set both the underline distance and line thickness,
524 both in points.
525 Repeat these arguments to include multiple underlines.
527 text_justified
529 my $width = $content->text_justified($text, $width, %options);
530 As "text", filling the specified width by adjusting the space between
532 words.
533 paragraph
535 # Scalar context
536 $overflow_text = $content->paragraph($text, $width, $height, %options);
537 # Array context
539 ($overflow, $height) = $content->paragraph($text, $width, $height, %options);
540 Fills the rectangle with as much of the provided text as will fit.
542 In array context, returns the remaining text (if any) of the positioned
544 text and the remaining (unused) height. In scalar context, returns the
545 remaining text (if any).
546 Line spacing follows "leading", if set, or 120% of the font size by
548 default.
549 Options
551 • align
553 Specifies the alignment for each line of text. May be set to
555 "left" (default), "center", "right", or "justified".
556 • align-last
558 Specifies the alignment for the last line of justified text. May
560 be set to "left" (default), "center", "right", or "justified".
561 • underline
563 As described in "text".
565 text_width
567 my $width = $content->text_width($line, %overrides);
568 Returns the width of a line of text based on the current text state
570 attributes. These can optionally be overridden:
571 my $width = $content->text_width($line,
573 font => $font,
574 size => $size,
575 character_spacing => $spacing,
576 word_spacing => $spacing,
577 hscale => $scale,
578 );
579
581 See "MIGRATION" in PDF::API2 for an overview.
582 transform(%hyphen_prefixed_options);
584 Remove hyphens from option names ("-translate" becomes "translate",
585 etc.).
586 transform_rel
588 Replace with "transform", setting option "repeat" to true. Remove
589 hyphens from the names of other options.
590 linewidth
592 Replace with "line_width".
593 linecap
595 Replace with "line_cap".
596 linejoin
598 Replace with "line_join".
599 meterlimit
601 miterlimit
602 Replace with "miter_limit".
603 linedash
605 Replace with "line_dash_pattern". Remove hyphens from option
606 names. Rename "-shift" to "offset".
607 flatness
609 Replace with "flatness_tolerance".
610 poly
612 Replace with "move" (first two arguments) and "polyline" (remaining
613 arguments).
614 endpath
616 Replace with "end".
617 rect
619 Replace with "rectangle", converting the $w (third) and $h (fourth)
620 arguments to the X and Y values of the upper-right corner:
621 # Old
623 $content->rect($x, $y, $w, $h);
624 # New
626 $content->rectangle($x, $y, $x + $w, $y + $h);
627 rectxy
629 Replace with "rectangle".
630 fill(1)
632 Replace with "$content->fill(rule => 'even-odd')".
633 fillstroke
635 Replace with "paint".
636 clip(1)
638 Replace with "$content->clip(rule => 'even-odd')".
639 image
641 formimage
642 Replace with "object".
643 charspace
645 Replace with "character_spacing".
646 wordspace
648 Replace with "word_spacing".
649 hspace
651 Replace with "hscale".
652 lead
654 Replace with "leading".
655 distance
657 Replace with "position".
658 cr Replace with either "position" (if called with arguments) or "crlf"
660 (if called without arguments).
661 nl Replace with "crlf".
663 text(%hyphen_prefixed_options)
665 Remove initial hyphens from option names.
666 text_center
668 Replace with "text", setting "align" to "center".
669 text_right
671 Replace with "text", setting "align" to "right".
672 paragraph(%hyphen_prefixed_options)
674 Remove initial hyphens from option names. "-align-last" becomes
675 "align-last".
676 section
678 paragraphs
679 Replace with "paragraph".
680 advancewidth
682 Replace with "text_width".
683perl v5.36.0 2023-01-20 PDF::API2::Content(3)