1PDF::API2::Content(3) User Contributed Perl DocumentationPDF::API2::Content(3)
2
3
4

NAME

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

SYNOPSIS

9           # Start with a PDF page (new or opened)
10           my $pdf = PDF::API2->new();
11           my $page = $pdf->page();
12
13           # Add a new content object
14           my $content = $page->graphics();
15           my $content = $page->text();
16
17           # Then call the methods below add graphics and text to the page.
18

COORDINATE TRANSFORMATIONS

20       The methods in this section change the coordinate system for the
21       current content object relative to the rest of the document.
22
23       Changes to the coordinate system only affect subsequent paths or text.
24
25       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
29   translate
30           $content = $content->translate($x, $y);
31
32       Moves the origin along the x and y axes.
33
34   rotate
35           $content = $content->rotate($degrees);
36
37       Rotates the coordinate system counter-clockwise.
38
39       Use a negative argument to rotate clockwise.
40
41   scale
42           $content = $content->scale($x, $y);
43
44       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
47   skew
48           $content = $content->skew($a, $b);
49
50       Skews the coordinate system by $a degrees (counter-clockwise) from the
51       x axis and $b degrees (clockwise) from the y axis.
52
53   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
62       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
66       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
71   matrix
72           $graphics = $graphics->matrix($a, $b, $c, $d, $e, $f);
73
74           ($a, $b, $c, $d, $e, $f) = $text->matrix($a, $b, $c, $d, $e, $f);
75
76       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
80       The return value differs based on whether the caller is a graphics
81       content object or a text content object.
82

GRAPHICS STATE

84   save
85           $content = $content->save();
86
87       Saves the current graphics state on a stack.
88
89   restore
90           $content = $content->restore();
91
92       Restores the most recently saved graphics state, removing it from the
93       stack.
94
95   line_width
96           $content = $content->line_width($points);
97
98       Sets the width of the stroke in points.
99
100   line_cap
101           $content = $content->line_cap($style);
102
103       Sets the shape that will be used at the ends of open subpaths (and
104       dashes, if any) when they are stroked.
105
106       •   "butt" or 0 = Butt Cap, default
107
108           The stroke ends at the end of the path, with no projection.
109
110       •   "round" or 1 = Round Cap)
111
112           An arc is drawn around the end of the path with a diameter equal to
113           the line width, and is filled in.
114
115       •   "square" or 2 = Projecting Square Cap
116
117           The stroke continues past the end of the path for half the line
118           width.
119
120   line_join
121           $content = $content->line_join($style);
122
123       Sets the style of join to be used at corners of a path.
124
125       •   "miter" or 0 = Miter Join, default
126
127           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
131       •   "round" or 1 = Round Join
132
133           A circle with a diameter equal to the linewidth is drawn around the
134           corner point, producing a rounded corner.
135
136       •   "bevel" or 2 = Bevel Join
137
138           A triangle is drawn to fill in the notch between the two strokes.
139
140   miter_limit
141           $content = $content->miter_limit($ratio);
142
143       Sets the miter limit when the line join style is a miter join.
144
145       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
150       There is no documented default miter limit.
151
152   line_dash_pattern
153           # Solid line
154           $content = $content->line_dash_pattern();
155
156           # Equal length lines and gaps
157           $content = $content->line_dash_pattern($length);
158
159           # Specified line and gap lengths
160           $content = $content->line_dash_pattern($line1, $gap1, $line2, $gap2, ...);
161
162           # Offset the starting point
163           $content = $content->line_dash_pattern(
164               pattern => [$line1, $gap1, $line2, $gap2, ...],
165               offset => $points,
166           );
167
168       Sets the line dash pattern.
169
170       If called without any arguments, a solid line will be drawn.
171
172       If called with one argument, the dashes and gaps will have equal
173       lengths.
174
175       If called with two or more arguments, the arguments represent
176       alternating dash and gap lengths.
177
178       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
181   flatness_tolerance
182           $content = $content->flatness_tolerance($tolerance);
183
184       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
188       $tolerance is an integer between 0 and 100, where 0 represents the
189       device's default flatness tolerance.
190
191   egstate
192           $content = $content->egstate($object);
193
194       Adds a PDF::API2::Resource::ExtGState object containing a set of
195       graphics state parameters.
196

PATH CONSTRUCTION (DRAWING)

198       Note that paths will not appear until a path painting method is called
199       ("stroke", "fill", or "paint").
200
201   move
202           $content = $content->move($x, $y);
203
204       Starts a new path at the specified coordinates.
205
206   line
207           $content = $content->line($x, $y);
208
209       Extends the path in a line from the current coordinates to the
210       specified coordinates.
211
212   hline
213           $content = $content->hline($x);
214
215       Extends the path in a horizontal line from the current position to the
216       specified x coordinate.
217
218   vline
219           $content = $content->vline($x);
220
221       Extends the path in a vertical line from the current position to the
222       specified y coordinate.
223
224   polyline
225           $content = $content->polyline($x1, $y1, $x2, $y2, ...);
226
227       Extends the path from the current position in one or more straight
228       lines.
229
230   curve
231           $content = $content->curve($cx1, $cy1, $cx2, $cy2, $x, $y);
232
233       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
236   spline
237           $content = $content->spline($cx1, $cy1, $x, $y);
238
239       Extends the path in a curve from the current point to "($x, $y)", using
240       the two specified points to create a spline.
241
242   arc
243           $content = $content->arc($x, $y, $major, $minor, $a, $b);
244
245       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
249   close
250           $content = $content->close();
251
252       Closes the current path by extending a line from the current position
253       to the starting position.
254
255   end
256           $content = $content->end();
257
258       Ends the current path without filling or stroking.
259

SHAPE CONSTRUCTION (DRAWING)

261       The following are convenience methods for drawing closed paths.
262
263       Note that shapes will not appear until a path painting method is called
264       ("stroke", "fill", or "paint").
265
266   rectangle
267           $content = $content->rectangle($x1, $y1, $x2, $y2);
268
269       Creates a new rectangle-shaped path, between the two points "[$x1,
270       $y1]" and "[$x2, $y2]".
271
272   circle
273           $content = $content->circle($x, $y, $radius);
274
275       Creates a new circular path centered on "[$x, $y]" with the specified
276       radius.
277
278   ellipse
279           $content = $content->ellipse($x, $y, $major, $minor);
280
281       Creates a new elliptical path centered on "[$x, $y]" with the specified
282       major and minor axes.
283
284   pie
285           $content = $content->pie($x, $y, $major, $minor, $a, $b);
286
287       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

PATH PAINTING (DRAWING)

292   stroke_color
293           $content = $content->stroke_color($color, @arguments);
294
295       Sets the stroke color, which is black by default.
296
297           # Use a named color
298           $content->stroke_color('blue');
299
300           # Use an RGB color (start with '#')
301           $content->stroke_color('#FF0000');
302
303           # Use a CMYK color (start with '%')
304           $content->stroke_color('%FF000000');
305
306           # 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
310       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
314   fill_color
315           $content = $content->fill_color($color, @arguments);
316
317       Sets the fill color, which is black by default.  Arguments are the same
318       as in "stroke_color".
319
320   stroke
321           $content = $content->stroke();
322
323       Strokes the current path.
324
325   fill
326           $content = $content->fill(rule => $rule);
327
328       Fills the current path.
329
330       $rule describes which areas are filled in when the path intersects with
331       itself.
332
333       •   nonzero (default)
334
335           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
339       •   even-odd
340
341           Use the even-odd rule.  This tends to mean that the presence of
342           fill alternates each time the path is intersected.
343
344       See PDF specification 1.7 section 8.5.3.3, Filling, for more details.
345
346   paint
347           $content = $content->paint(rule => $rule);
348
349       Fills and strokes the current path.  $rule is as described in "fill".
350
351   clip
352           $content = $content->clip(rule => $rule);
353
354       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

EXTERNAL OBJECTS

359   object
360           $content = $content->object($object, $x, $y, $scale_x, $scale_y);
361
362       Places an image or other external object (a.k.a. XObject) on the page
363       in the specified location.
364
365       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
370       For other external objects, the scale is a multiplier, where 1 (the
371       default) represents 100% (i.e. no change).
372
373       If coordinate transformations have been made (see Coordinate
374       Transformations above), the position and scale will be relative to the
375       updated coordinates.
376
377       If no coordinate transformations are needed, this method can be called
378       directly from the PDF::API2::Page object instead.
379

TEXT STATE

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
385   font
386           $content = $content->font($font, $size);
387
388       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
391           my $pdf = PDF::API2->new();
392           my $page = $pdf->page();
393           my $text = $pdf->text();
394
395           my $font = $pdf->font('Helvetica');
396           $text->font($font, 24);
397           $text->position(72, 720);
398           $text->text('Hello, World!');
399
400           $pdf->save('sample.pdf');
401
402   character_spacing
403           $spacing = $content->character_spacing($spacing);
404
405       Sets the spacing between characters.  This is initially zero.
406
407   word_spacing
408           $spacing = $content->word_spacing($spacing);
409
410       Sets the spacing between words.  This is initially zero (i.e. just the
411       width of the space).
412
413       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
419   hscale
420           $scale = $content->hscale($scale);
421
422       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
426   leading
427           $leading = $content->leading($leading);
428
429       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
433   render
434           $mode = $content->render($mode);
435
436       Sets the text rendering mode.
437
438       •   0 = Fill text
439
440       •   1 = Stroke text (outline)
441
442       •   2 = Fill, then stroke text
443
444       •   3 = Neither fill nor stroke text (invisible)
445
446       •   4 = Fill text and add to path for clipping
447
448       •   5 = Stroke text and add to path for clipping
449
450       •   6 = Fill, then stroke text and add to path for clipping
451
452       •   7 = Add text to path for clipping
453
454   rise
455           $distance = $content->rise($distance);
456
457       Adjusts the baseline up or down from its current location.  This is
458       initially zero.
459
460       Use this to create superscripts or subscripts (usually with an
461       adjustment to the font size as well).
462

TEXT PLACEMENT

464   position
465           # Set
466           $content = $content->position($x, $y);
467
468           # Get
469           ($x, $y) = $content->position();
470
471       If called with arguments, moves to the start of the current line of
472       text, offset by $x and $y.
473
474       If called without arguments, returns the current position of the cursor
475       (before the effects of any coordinate transformation methods).
476
477   crlf
478           $content = $content->crlf();
479
480       Moves to the start of the next line, based on the "leading" setting.
481
482       If leading isn't set, a default distance of 120% of the font size will
483       be used.
484
485   text
486           my $width = $content->text($text, %options);
487
488       Places text on the page.  Returns the width of the text in points.
489
490       Options:
491
492       •   align
493
494           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
498           In each case, the position will then be moved to the end of the
499           text.
500
501       •   indent
502
503           Indents the text by the number of points.
504
505           If "align" is set to anything other than "left", this setting will
506           be ignored.
507
508       •   underline
509
510           Underlines the text.  The value may be one of the following:
511
512           •   auto
513
514               Determines the underline distance from the text based on the
515               font and font size.
516
517           •   $distance
518
519               Manually set the underline distance in points.  A positive
520               distance moves the line downward.
521
522           •   [$distance, $thickness, ...]
523
524               Manually set both the underline distance and line thickness,
525               both in points.
526
527               Repeat these arguments to include multiple underlines.
528
529   text_justified
530           my $width = $content->text_justified($text, $width, %options);
531
532       As "text", filling the specified width by adjusting the space between
533       words.
534
535   paragraph
536           # Scalar context
537           $overflow_text = $content->paragraph($text, $width, $height, %options);
538
539           # Array context
540           ($overflow, $height) = $content->paragraph($text, $width, $height, %options);
541
542       Fills the rectangle with as much of the provided text as will fit.
543
544       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
548       Line spacing follows "leading", if set, or 120% of the font size by
549       default.
550
551       Options
552
553       •   align
554
555           Specifies the alignment for each line of text.  May be set to
556           "left" (default), "center", "right", or "justified".
557
558       •   align-last
559
560           Specifies the alignment for the last line of justified text.  May
561           be set to "left" (default), "center", "right", or "justified".
562
563       •   underline
564
565           As described in "text".
566
567   text_width
568           my $width = $content->text_width($line, %overrides);
569
570       Returns the width of a line of text based on the current text state
571       attributes.  These can optionally be overridden:
572
573           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

MIGRATION

582       See "MIGRATION" in PDF::API2 for an overview.
583
584       transform(%hyphen_prefixed_options);
585           Remove hyphens from option names ("-translate" becomes "translate",
586           etc.).
587
588       transform_rel
589           Replace with "transform", setting option "relative" to true.
590           Remove hyphens from the names of other options.
591
592       linewidth
593           Replace with "line_width".
594
595       linecap
596           Replace with "line_cap".
597
598       linejoin
599           Replace with "line_join".
600
601       meterlimit
602       miterlimit
603           Replace with "miter_limit".
604
605       linedash
606           Replace with "line_dash_pattern".  Remove hyphens from option
607           names.  Rename "-shift" to "offset".
608
609       flatness
610           Replace with "flatness_tolerance".
611
612       poly
613           Replace with "move" (first two arguments) and "polyline" (remaining
614           arguments).
615
616       endpath
617           Replace with "end".
618
619       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
623               # Old
624               $content->rect($x, $y, $w, $h);
625
626               # New
627               $content->rectangle($x, $y, $x + $w, $y + $h);
628
629       rectxy
630           Replace with "rectangle".
631
632       fill(1)
633           Replace with "$content->fill(rule => 'even-odd')".
634
635       fillstroke
636           Replace with "paint".
637
638       clip(1)
639           Replace with "$content->clip(rule => 'even-odd')".
640
641       image
642       formimage
643           Replace with "object".
644
645       charspace
646           Replace with "character_spacing".
647
648       wordspace
649           Replace with "word_spacing".
650
651       hspace
652           Replace with "hscale".
653
654       lead
655           Replace with "leading".
656
657       distance
658           Replace with "position".
659
660       cr  Replace with either "position" (if called with arguments) or "crlf"
661           (if called without arguments).
662
663       nl  Replace with "crlf".
664
665       text(%hyphen_prefixed_options)
666           Remove initial hyphens from option names.
667
668       text_center
669           Replace with "text", setting "align" to "center".
670
671       text_right
672           Replace with "text", setting "align" to "right".
673
674       paragraph(%hyphen_prefixed_options)
675           Remove initial hyphens from option names.  "-align-last" becomes
676           "align-last".
677
678       section
679       paragraphs
680           Replace with "paragraph".
681
682       advancewidth
683           Replace with "text_width".
684
685
686
687perl v5.34.0                      2022-01-21             PDF::API2::Content(3)
Impressum