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 to 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               repeat    => $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 "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
70   matrix
71           $graphics = $graphics->matrix($a, $b, $c, $d, $e, $f);
72
73           ($a, $b, $c, $d, $e, $f) = $text->matrix($a, $b, $c, $d, $e, $f);
74
75       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
79       The return value differs based on whether the caller is a graphics
80       content object or a text content object.
81

GRAPHICS STATE

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

PATH CONSTRUCTION (DRAWING)

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

SHAPE CONSTRUCTION (DRAWING)

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

PATH PAINTING (DRAWING)

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

EXTERNAL OBJECTS

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

TEXT STATE

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

TEXT PLACEMENT

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

MIGRATION

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