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 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 relative => $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 "relative" is true, the specified transformations will be added to
67 any previous changes to the coordinate system. By default, calling
68 "transform" or any of the other transformation methods will overwrite
69 any previous changes to the coordinate system.
70 matrix
72 $graphics = $graphics->matrix($a, $b, $c, $d, $e, $f);
73 ($a, $b, $c, $d, $e, $f) = $text->matrix($a, $b, $c, $d, $e, $f);
75 Sets the current transformation matrix manually. Unless you have a
77 particular need to enter transformations manually, you should use the
78 "transform" method instead.
79 The return value differs based on whether the caller is a graphics
81 content object or a text content object.
82
84 save
85 $content = $content->save();
86 Saves the current graphics state on a stack.
88 restore
90 $content = $content->restore();
91 Restores the most recently saved graphics state, removing it from the
93 stack.
94 line_width
96 $content = $content->line_width($points);
97 Sets the width of the stroke in points.
99 line_cap
101 $content = $content->line_cap($style);
102 Sets the shape that will be used at the ends of open subpaths (and
104 dashes, if any) when they are stroked.
105 • "butt" or 0 = Butt Cap, default
107 The stroke ends at the end of the path, with no projection.
109 • "round" or 1 = Round Cap)
111 An arc is drawn around the end of the path with a diameter equal to
113 the line width, and is filled in.
114 • "square" or 2 = Projecting Square Cap
116 The stroke continues past the end of the path for half the line
118 width.
119 line_join
121 $content = $content->line_join($style);
122 Sets the style of join to be used at corners of a path.
124 • "miter" or 0 = Miter Join, default
126 The outer edges of the stroke extend until they meet, up to the
128 limit specified below. If the limit would be surpassed, a bevel
129 join is used instead.
130 • "round" or 1 = Round Join
132 A circle with a diameter equal to the linewidth is drawn around the
134 corner point, producing a rounded corner.
135 • "bevel" or 2 = Bevel Join
137 A triangle is drawn to fill in the notch between the two strokes.
139 miter_limit
141 $content = $content->miter_limit($ratio);
142 Sets the miter limit when the line join style is a miter join.
144 The $ratio is the maximum length of the miter (inner to outer corner)
146 divided by the line width. Any miter above this ratio will be converted
147 to a bevel join. The practical effect is that lines meeting at shallow
148 angles are chopped off instead of producing long pointed corners.
149 There is no documented default miter limit.
151 line_dash_pattern
153 # Solid line
154 $content = $content->line_dash_pattern();
155 # Equal length lines and gaps
157 $content = $content->line_dash_pattern($length);
158 # Specified line and gap lengths
160 $content = $content->line_dash_pattern($line1, $gap1, $line2, $gap2, ...);
161 # Offset the starting point
163 $content = $content->line_dash_pattern(
164 pattern => [$line1, $gap1, $line2, $gap2, ...],
165 offset => $points,
166 );
167 Sets the line dash pattern.
169 If called without any arguments, a solid line will be drawn.
171 If called with one argument, the dashes and gaps will have equal
173 lengths.
174 If called with two or more arguments, the arguments represent
176 alternating dash and gap lengths.
177 If called with a hash of arguments, a dash phase may be set, which
179 specifies the distance into the pattern at which to start the dash.
180 flatness_tolerance
182 $content = $content->flatness_tolerance($tolerance);
183 Sets the maximum distance in device pixels between the mathematically
185 correct path for a curve and an approximation constructed from straight
186 line segments.
187 $tolerance is an integer between 0 and 100, where 0 represents the
189 device's default flatness tolerance.
190 egstate
192 $content = $content->egstate($object);
193 Adds a PDF::API2::Resource::ExtGState object containing a set of
195 graphics state parameters.
196
198 Note that paths will not appear until a path painting method is called
199 ("stroke", "fill", or "paint").
200 move
202 $content = $content->move($x, $y);
203 Starts a new path at the specified coordinates.
205 line
207 $content = $content->line($x, $y);
208 Extends the path in a line from the current coordinates to the
210 specified coordinates.
211 hline
213 $content = $content->hline($x);
214 Extends the path in a horizontal line from the current position to the
216 specified x coordinate.
217 vline
219 $content = $content->vline($x);
220 Extends the path in a vertical line from the current position to the
222 specified y coordinate.
223 polyline
225 $content = $content->polyline($x1, $y1, $x2, $y2, ...);
226 Extends the path from the current position in one or more straight
228 lines.
229 curve
231 $content = $content->curve($cx1, $cy1, $cx2, $cy2, $x, $y);
232 Extends the path in a curve from the current point to "($x, $y)", using
234 the two specified points to create a cubic Bezier curve.
235 spline
237 $content = $content->spline($cx1, $cy1, $x, $y);
238 Extends the path in a curve from the current point to "($x, $y)", using
240 the two specified points to create a spline.
241 arc
243 $content = $content->arc($x, $y, $major, $minor, $a, $b);
244 Extends the path along an arc of an ellipse centered at "[$x, $y]".
246 $major and $minor represent the axes of the ellipse, and the arc moves
247 from $a degrees to $b degrees.
248 close
250 $content = $content->close();
251 Closes the current path by extending a line from the current position
253 to the starting position.
254 end
256 $content = $content->end();
257 Ends the current path without filling or stroking.
259
261 The following are convenience methods for drawing closed paths.
262 Note that shapes will not appear until a path painting method is called
264 ("stroke", "fill", or "paint").
265 rectangle
267 $content = $content->rectangle($x1, $y1, $x2, $y2);
268 Creates a new rectangle-shaped path, between the two points "[$x1,
270 $y1]" and "[$x2, $y2]".
271 circle
273 $content = $content->circle($x, $y, $radius);
274 Creates a new circular path centered on "[$x, $y]" with the specified
276 radius.
277 ellipse
279 $content = $content->ellipse($x, $y, $major, $minor);
280 Creates a new elliptical path centered on "[$x, $y]" with the specified
282 major and minor axes.
283 pie
285 $content = $content->pie($x, $y, $major, $minor, $a, $b);
286 Creates a new wedge-shaped path from an ellipse centered on "[$x, $y]"
288 with the specified major and minor axes, extending from $a degrees to
289 $b degrees.
290
292 stroke_color
293 $content = $content->stroke_color($color, @arguments);
294 Sets the stroke color, which is black by default.
296 # Use a named color
298 $content->stroke_color('blue');
299 # Use an RGB color (start with '#')
301 $content->stroke_color('#FF0000');
302 # Use a CMYK color (start with '%')
304 $content->stroke_color('%FF000000');
305 # Use a spot color with 100% coverage.
307 my $spot = $pdf->colorspace('spot', 'PANTONE Red 032 C', '#EF3340');
308 $content->stroke_color($spot, 1.0);
309 RGB and CMYK colors can have one-byte, two-byte, three-byte, or four-
311 byte values for each color, depending on the level of precision needed.
312 For instance, cyan can be given as %F000 or %FFFF000000000000.
313 fill_color
315 $content = $content->fill_color($color, @arguments);
316 Sets the fill color, which is black by default. Arguments are the same
318 as in "stroke_color".
319 stroke
321 $content = $content->stroke();
322 Strokes the current path.
324 fill
326 $content = $content->fill(rule => $rule);
327 Fills the current path.
329 $rule describes which areas are filled in when the path intersects with
331 itself.
332 • nonzero (default)
334 Use the nonzero winding number rule. This tends to mean that the
336 entire area enclosed by the path is filled in, with some exceptions
337 depending on the direction of the path.
338 • even-odd
340 Use the even-odd rule. This tends to mean that the presence of
342 fill alternates each time the path is intersected.
343 See PDF specification 1.7 section 8.5.3.3, Filling, for more details.
345 paint
347 $content = $content->paint(rule => $rule);
348 Fills and strokes the current path. $rule is as described in "fill".
350 clip
352 $content = $content->clip(rule => $rule);
353 Modifies the current clipping path (initially the entire page) by
355 intersecting it with the current path following the next path-painting
356 command. $rule is as described in "fill".
357
359 object
360 $content = $content->object($object, $x, $y, $scale_x, $scale_y);
361 Places an image or other external object (a.k.a. XObject) on the page
363 in the specified location.
364 For images, $scale_x and $scale_y represent the width and height of the
366 image on the page in points. If $scale_x is omitted, it will default
367 to 72 pixels per inch. If $scale_y is omitted, the image will be
368 scaled proportionally based on the image dimensions.
369 For other external objects, the scale is a multiplier, where 1 (the
371 default) represents 100% (i.e. no change).
372 If coordinate transformations have been made (see Coordinate
374 Transformations above), the position and scale will be relative to the
375 updated coordinates.
376 If no coordinate transformations are needed, this method can be called
378 directly from the PDF::API2::Page object instead.
379
381 All of the following parameters that take a size are applied before any
382 scaling takes place, so you don't need to adjust values to counteract
383 scaling.
384 font
386 $content = $content->font($font, $size);
387 Sets the font and font size. $font is an object created by calling
389 "font" in PDF::API2 to add the font to the document.
390 my $pdf = PDF::API2->new();
392 my $page = $pdf->page();
393 my $text = $pdf->text();
394 my $font = $pdf->font('Helvetica');
396 $text->font($font, 24);
397 $text->position(72, 720);
398 $text->text('Hello, World!');
399 $pdf->save('sample.pdf');
401 character_spacing
403 $spacing = $content->character_spacing($spacing);
404 Sets the spacing between characters. This is initially zero.
406 word_spacing
408 $spacing = $content->word_spacing($spacing);
409 Sets the spacing between words. This is initially zero (i.e. just the
411 width of the space).
412 Word spacing might only affect simple fonts and composite fonts where
414 the space character is a single-byte code. This is a limitation of the
415 PDF specification at least as of version 1.7 (see section 9.3.3). It's
416 possible that a later version of the specification will support word
417 spacing in fonts that use multi-byte codes.
418 hscale
420 $scale = $content->hscale($scale);
421 Sets/gets the percentage of horizontal text scaling. Enter a scale
423 greater than 100 to stretch text, less than 100 to squeeze text, or 100
424 to disable any existing scaling.
425 leading
427 $leading = $content->leading($leading);
428 Sets/gets the text leading, which is the distance between baselines.
430 This is initially zero (i.e. the lines will be printed on top of each
431 other).
432 render
434 $mode = $content->render($mode);
435 Sets the text rendering mode.
437 • 0 = Fill text
439 • 1 = Stroke text (outline)
441 • 2 = Fill, then stroke text
443 • 3 = Neither fill nor stroke text (invisible)
445 • 4 = Fill text and add to path for clipping
447 • 5 = Stroke text and add to path for clipping
449 • 6 = Fill, then stroke text and add to path for clipping
451 • 7 = Add text to path for clipping
453 rise
455 $distance = $content->rise($distance);
456 Adjusts the baseline up or down from its current location. This is
458 initially zero.
459 Use this to create superscripts or subscripts (usually with an
461 adjustment to the font size as well).
462
464 position
465 # Set
466 $content = $content->position($x, $y);
467 # Get
469 ($x, $y) = $content->position();
470 If called with arguments, moves to the start of the current line of
472 text, offset by $x and $y.
473 If called without arguments, returns the current position of the cursor
475 (before the effects of any coordinate transformation methods).
476 crlf
478 $content = $content->crlf();
479 Moves to the start of the next line, based on the "leading" setting.
481 If leading isn't set, a default distance of 120% of the font size will
483 be used.
484 text
486 my $width = $content->text($text, %options);
487 Places text on the page. Returns the width of the text in points.
489 Options:
491 • align
493 One of "left" (default), "center", or "right". Text will be placed
495 such that it begins, is centered on, or ends at the current text
496 position, respectively.
497 In each case, the position will then be moved to the end of the
499 text.
500 • indent
502 Indents the text by the number of points.
504 If "align" is set to anything other than "left", this setting will
506 be ignored.
507 • underline
509 Underlines the text. The value may be one of the following:
511 • auto
513 Determines the underline distance from the text based on the
515 font and font size.
516 • $distance
518 Manually set the underline distance in points. A positive
520 distance moves the line downward.
521 • [$distance, $thickness, ...]
523 Manually set both the underline distance and line thickness,
525 both in points.
526 Repeat these arguments to include multiple underlines.
528 text_justified
530 my $width = $content->text_justified($text, $width, %options);
531 As "text", filling the specified width by adjusting the space between
533 words.
534 paragraph
536 # Scalar context
537 $overflow_text = $content->paragraph($text, $width, $height, %options);
538 # Array context
540 ($overflow, $height) = $content->paragraph($text, $width, $height, %options);
541 Fills the rectangle with as much of the provided text as will fit.
543 In array context, returns the remaining text (if any) of the positioned
545 text and the remaining (unused) height. In scalar context, returns the
546 remaining text (if any).
547 Line spacing follows "leading", if set, or 120% of the font size by
549 default.
550 Options
552 • align
554 Specifies the alignment for each line of text. May be set to
556 "left" (default), "center", "right", or "justified".
557 • align-last
559 Specifies the alignment for the last line of justified text. May
561 be set to "left" (default), "center", "right", or "justified".
562 • underline
564 As described in "text".
566 text_width
568 my $width = $content->text_width($line, %overrides);
569 Returns the width of a line of text based on the current text state
571 attributes. These can optionally be overridden:
572 my $width = $content->text_width($line,
574 font => $font,
575 size => $size,
576 character_spacing => $spacing,
577 word_spacing => $spacing,
578 hscale => $scale,
579 );
580
582 See "MIGRATION" in PDF::API2 for an overview.
583 transform(%hyphen_prefixed_options);
585 Remove hyphens from option names ("-translate" becomes "translate",
586 etc.).
587 transform_rel
589 Replace with "transform", setting option "relative" to true.
590 Remove hyphens from the names of other options.
591 linewidth
593 Replace with "line_width".
594 linecap
596 Replace with "line_cap".
597 linejoin
599 Replace with "line_join".
600 meterlimit
602 miterlimit
603 Replace with "miter_limit".
604 linedash
606 Replace with "line_dash_pattern". Remove hyphens from option
607 names. Rename "-shift" to "offset".
608 flatness
610 Replace with "flatness_tolerance".
611 poly
613 Replace with "move" (first two arguments) and "polyline" (remaining
614 arguments).
615 endpath
617 Replace with "end".
618 rect
620 Replace with "rectangle", converting the $w (third) and $h (fourth)
621 arguments to the X and Y values of the upper-right corner:
622 # Old
624 $content->rect($x, $y, $w, $h);
625 # New
627 $content->rectangle($x, $y, $x + $w, $y + $h);
628 rectxy
630 Replace with "rectangle".
631 fill(1)
633 Replace with "$content->fill(rule => 'even-odd')".
634 fillstroke
636 Replace with "paint".
637 clip(1)
639 Replace with "$content->clip(rule => 'even-odd')".
640 image
642 formimage
643 Replace with "object".
644 charspace
646 Replace with "character_spacing".
647 wordspace
649 Replace with "word_spacing".
650 hspace
652 Replace with "hscale".
653 lead
655 Replace with "leading".
656 distance
658 Replace with "position".
659 cr Replace with either "position" (if called with arguments) or "crlf"
661 (if called without arguments).
662 nl Replace with "crlf".
664 text(%hyphen_prefixed_options)
666 Remove initial hyphens from option names.
667 text_center
669 Replace with "text", setting "align" to "center".
670 text_right
672 Replace with "text", setting "align" to "right".
673 paragraph(%hyphen_prefixed_options)
675 Remove initial hyphens from option names. "-align-last" becomes
676 "align-last".
677 section
679 paragraphs
680 Replace with "paragraph".
681 advancewidth
683 Replace with "text_width".
684perl v5.36.0 2022-07-22 PDF::API2::Content(3)