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->gfx();
15           my $content = $page->text();
16
17           # Then call the methods below add graphics and text to the page.
18

METHODS

20   Coordinate Transformations
21       The methods in this section change the coordinate system for the
22       current content object relative to the rest of the document.
23
24       If you call more than one of these methods, the PDF specification
25       recommends calling them in the following order: translate, rotate,
26       scale, skew.  Each change builds on the last, and you can get
27       unexpected results when calling them in a different order.
28
29       $content->translate($x, $y)
30           Moves the origin along the x and y axes.
31
32       $content->rotate($degrees)
33           Rotates the coordinate system counter-clockwise.
34
35           Use a negative argument to rotate clockwise.
36
37       $content->scale($sx, $sy)
38           Scales (stretches) the coordinate systems along the x and y axes.
39
40       $content->skew($sa, $sb)
41           Skews the coordinate system by $sa degrees (counter-clockwise) from
42           the x axis and $sb degrees (clockwise) from the y axis.
43
44       $content->transform(%options)
45               $content->transform(
46                   -translate => [$x, $y],
47                   -rotate    => $degrees,
48                   -scale     => [$sx, $sy],
49                   -skew      => [$sa, $sb],
50               )
51
52           Performs multiple coordinate transformations at once, in the order
53           recommended by the PDF specification (translate, rotate, scale,
54           then skew).
55
56           This is equivalent to making each transformation separately.
57
58       $content->transform_rel(%options)
59           Makes transformations similarly to "transform", except that it adds
60           to the previously set values.
61
62       $content->matrix($a, $b, $c, $d, $e, $f)
63           (Advanced) Sets the current transformation matrix manually.  Unless
64           you have a particular need to enter transformations manually, you
65           should use the "transform" method instead.
66
67   Graphics State Parameters
68       $content->save
69           Saves the current graphics state and text state on a stack.
70
71       $content->restore
72           Restores the most recently saved graphics state and text state,
73           removing it from the stack.
74
75       $content->linewidth($width)
76           Sets the width of the stroke.
77
78       $content->linecap($style)
79           Sets the style to be used at the end of a stroke.
80
81           0 = Butt Cap
82               The stroke ends at the end of the path, with no projection.
83
84           1 = Round Cap
85               An arc is drawn around the end of the path with a diameter
86               equal to the line width, and is filled in.
87
88           2 = Projecting Square Cap
89               The stroke continues past the end of the path for half the line
90               width.
91
92       $content->linejoin($style)
93           Sets the style of join to be used at corners of a path.
94
95           0 = Miter Join
96               The outer edges of the stroke extend until they meet, up to the
97               limit specified below.  If the limit would be surpassed, a
98               bevel join is used instead.
99
100           1 = Round Join
101               A circle with a diameter equal to the linewidth is drawn around
102               the corner point, producing a rounded corner.
103
104           2 = Bevel Join
105               A triangle is drawn to fill in the notch between the two
106               strokes.
107
108       $content->miterlimit($ratio)
109           Sets the miter limit when the line join style is a miter join.
110
111           The $ratio is the maximum length of the miter (inner to outer
112           corner) divided by the line width. Any miter above this ratio will
113           be converted to a bevel join. The practical effect is that lines
114           meeting at shallow angles are chopped off instead of producing long
115           pointed corners.
116
117           There is no documented default miter limit.
118
119       $content->linedash()
120       $content->linedash($length)
121       $content->linedash($dash_length, $gap_length, ...)
122       $content->linedash(-pattern => [$dash_length, $gap_length, ...], -shift
123       => $offset)
124           Sets the line dash pattern.
125
126           If called without any arguments, a solid line will be drawn.
127
128           If called with one argument, the dashes and gaps will have equal
129           lengths.
130
131           If called with two or more arguments, the arguments represent
132           alternating dash and gap lengths.
133
134           If called with a hash of arguments, a dash phase may be set, which
135           specifies the distance into the pattern at which to start the dash.
136
137       $content->flatness($tolerance)
138           (Advanced) Sets the maximum variation in output pixels when drawing
139           curves.
140
141       $content->egstate($object)
142           (Advanced) Adds an Extended Graphic State object containing
143           additional state parameters.
144
145   Path Construction (Drawing)
146       $content->move($x, $y)
147           Starts a new path at the specified coordinates.
148
149       $content->line($x, $y)
150           Extends the path in a line from the current coordinates to the
151           specified coordinates, and updates the current position to be the
152           new coordinates.
153
154           Note: The line will not appear until you call "stroke".
155
156       $content->hline($x)
157       $content->vline($y)
158           Shortcut for drawing horizontal and vertical lines from the current
159           position.
160
161       $content->poly($x1, $y1, ..., $xn, $yn)
162           Shortcut for creating a polyline path.  Moves to "[$x1, $y1]", and
163           then extends the path in lines along the specified coordinates.
164
165       $content->curve($cx1, $cy1, $cx2, $cy2, $x, $y)
166           Extends the path in a curve from the current point to "($x, $y)",
167           using the two specified points to create a cubic Bezier curve, and
168           updates the current position to be the new point.
169
170           Note: The curve will not appear until you call "stroke".
171
172       $content->spline($cx1, $cy1, $x, $y)
173           Extends the path in a curve from the current point to "($x, $y)",
174           using the two specified points to create a spline, and updates the
175           current position to be the new point.
176
177           Note: The curve will not appear until you call "stroke".
178
179       $content->arc($x, $y, $a, $b, $alpha, $beta, $move)
180           Extends the path along an arc of an ellipse centered at "[x, y]".
181           The major and minor axes of the ellipse are $a and $b,
182           respectively, and the arc moves from $alpha degrees to $beta
183           degrees.  The current position is then set to the endpoint of the
184           arc.
185
186           Set $move to a true value if this arc is the beginning of a new
187           path instead of the continuation of an existing path.
188
189       $content->bogen($x1, $y1, $x2, $y2, $radius, $move, $outer, $reverse)
190           Extends the path along an arc of a circle of the specified radius
191           between "[x1,y1]" to "[x2,y2]".  The current position is then set
192           to the endpoint of the arc.
193
194           Set $move to a true value if this arc is the beginning of a new
195           path instead of the continuation of an existing path.
196
197           Set $outer to a true value to draw the larger arc between the two
198           points instead of the smaller one.
199
200           Set $reverse to a true value to draw the mirror image of the
201           specified arc.
202
203           "$radius * 2" cannot be smaller than the distance from "[x1,y1]" to
204           "[x2,y2]".
205
206           Note: The curve will not appear until you call "stroke".
207
208       $content->close()
209           Closes and ends the current path by extending a line from the
210           current position to the starting position.
211
212       $content->endpath()
213           Ends the current path without explicitly enclosing it.
214
215       $content->ellipse($x, $y, $a, $b)
216           Creates an elliptical path centered on "[$x,$y]", with major and
217           minor axes specified by $a and $b, respectively.
218
219           Note: The ellipse will not appear until you call "stroke" or
220           "fill".
221
222       $content->circle($x, $y, $radius)
223           Creates a circular path centered on "[$x, $y]" with the specified
224           radius.
225
226           Note: The circle will not appear until you call "stroke" or "fill".
227
228       $content->pie($x, $y, $a, $b, $alpha, $beta)
229           Creates a pie-shaped path from an ellipse centered on "[$x,$y]".
230           The major and minor axes of the ellipse are $a and $b,
231           respectively, and the arc moves from $alpha degrees to $beta
232           degrees.
233
234           Note: The pie will not appear until you call "stroke" or "fill".
235
236       $content->rect($x1, $y1, $w1, $h1, ..., $xn, $yn, $wn, $hn)
237           Creates paths for one or more rectangles, with their lower left
238           points at "[$x,$y]" and with the specified widths and heights.
239
240           Note: The rectangles will not appear until you call "stroke" or
241           "fill".
242
243       $content->rectxy($x1, $y1, $x2, $y2)
244           Creates a rectangular path, with "[$x1,$y1]" and and "[$x2,$y2]"
245           specifying opposite corners.
246
247           Note: The rectangle will not appear until you call "stroke" or
248           "fill".
249
250   Path Painting (Drawing)
251       $content->stroke
252           Strokes the current path.
253
254       $content->fill($use_even_odd_fill)
255           Fills the current path.
256
257           If the path intersects with itself, the nonzero winding rule will
258           be used to determine which part of the path is filled in.  If you
259           would prefer to use the even-odd rule, pass a true argument.
260
261           See the PDF Specification, section 8.5.3.3, for more details on
262           filling.
263
264       $content->fillstroke($use_even_odd_fill)
265           Fills and then strokes the current path.
266
267       $content->clip($use_even_odd_fill)
268           Modifies the current clipping path by intersecting it with the
269           current path.
270
271   Colors
272       $content->fillcolor($color)
273       $content->strokecolor($color)
274           Sets the fill or stroke color.
275
276               # Use a named color
277               $content->fillcolor('blue');
278
279               # Use an RGB color (start with '#')
280               $content->fillcolor('#FF0000');
281
282               # Use a CMYK color (start with '%')
283               $content->fillcolor('%FF000000');
284
285           RGB and CMYK colors can have one-byte, two-byte, three-byte, or
286           four-byte values for each color.  For instance, cyan can be given
287           as %F000 or %FFFF000000000000.
288
289   External Objects
290       $content->image($image_object, $x, $y, $width, $height)
291       $content->image($image_object, $x, $y, $scale)
292       $content->image($image_object, $x, $y)
293               # Example
294               my $image_object = $pdf->image_jpeg($my_image_file);
295               $content->image($image_object, 100, 200);
296
297           Places an image on the page in the specified location.
298
299           If coordinate transformations have been made (see Coordinate
300           Transformations above), the position and scale will be relative to
301           the updated coordinates.  Otherwise, [0,0] will represent the
302           bottom left corner of the page, and $width and $height will be
303           measured at 72dpi.
304
305           For example, if you have a 600x600 image that you would like to be
306           shown at 600dpi (i.e. one inch square), set the width and height to
307           72.
308
309       $content->formimage($form_object, $x, $y, $scale)
310       $content->formimage($form_object, $x, $y)
311           Places an XObject on the page in the specified location.
312
313   Text State Parameters
314       All of the following parameters that take a size are applied before any
315       scaling takes place, so you don't need to adjust values to counteract
316       scaling.
317
318       $spacing = $content->charspace($spacing)
319           Sets the spacing between characters.  This is initially zero.
320
321       $spacing = $content->wordspace($spacing)
322           Sets the spacing between words.  This is initially zero (or, in
323           other words, just the width of the space).
324
325           Word spacing might only affect simple fonts and composite fonts
326           where the space character is a single-byte code.  This is a
327           limitation of the PDF specification at least as of version 1.7 (see
328           section 9.3.3).  It's possible that a later version of the
329           specification will support word spacing in fonts that use multi-
330           byte codes.
331
332       $scale = $content->hscale($scale)
333           Sets and returns the percentage of horizontal text scaling.  Enter
334           a scale greater than 100 to stretch text, less than 100 to squeeze
335           text, or 100 to disable any existing scaling.
336
337       $leading = $content->leading($leading)
338           Sets the text leading, which is the distance between baselines.
339           This is initially zero (i.e. the lines will be printed on top of
340           each other).
341
342       $mode = $content->render($mode)
343           Sets the text rendering mode.
344
345           0 = Fill text
346           1 = Stroke text (outline)
347           2 = Fill, then stroke text
348           3 = Neither fill nor stroke text (invisible)
349           4 = Fill text and add to path for clipping
350           5 = Stroke text and add to path for clipping
351           6 = Fill, then stroke text and add to path for clipping
352           7 = Add text to path for clipping
353       $distance = $content->rise($distance)
354           Adjusts the baseline up or down from its current location.  This is
355           initially zero.
356
357           Use this for creating superscripts or subscripts (usually with an
358           adjustment to the font size as well).
359
360       %state = $content->textstate(charspace => $value, wordspace => $value,
361       ...)
362           Shortcut for setting multiple text state parameters at once.
363
364           This can also be used without arguments to retrieve the current
365           text state settings.
366
367           Note: This does not currently work with the "save" and "restore"
368           commands.
369
370       $content->font($font_object, $size)
371               # Example
372               my $pdf = PDF::API2->new();
373               my $font = $pdf->corefont('Helvetica');
374               $content->font($font, 12);
375
376           Sets the font and font size.
377
378   Text-Positioning
379       Note: There is a very good chance that these commands will be replaced
380       in a future release.
381
382       $content->distance($dx, $dy)
383           Moves to the start of the next line, offset by the given amounts,
384           which are both required.
385
386       $content->cr()
387       $content->cr($vertical_offset)
388           Moves the cursor to the start of the line when called without an
389           argument.  If leading has been set, the cursor will move to the
390           next line instead.
391
392           An offset can be passed as an argument to override the leading
393           value.  A positive offset will move the cursor up, and a negative
394           offset will move the cursor down.
395
396           Pass zero as the argument to ignore the leading and get just a
397           carriage return.
398
399       $content->nl()
400           Moves to the start of the next line.
401
402       ($tx, $ty) = $content->textpos()
403           Gets the current estimated text position.
404
405           Note: This does not affect the PDF in any way.
406
407   Text-Showing
408       $width = $content->text($text, %options)
409           Adds text to the page.
410
411           Returns the width of the text in points.
412
413           Options:
414
415           -indent
416               Indents the text by the number of points.
417
418           -underline => 'auto'
419           -underline => $distance
420           -underline => [$distance, $thickness, ...]
421               Underlines the text.  $distance is the number of units beneath
422               the baseline, and $thickness is the width of the line.
423
424               Multiple underlines can be made by passing several distances
425               and thicknesses.
426
427       $width = $content->text_center($text, %options)
428           As "text", but centered on the current point.
429
430       $width = $content->text_right($text, %options)
431           As "text", but right-aligned to the current point.
432
433       $width = $content->text_justified($text, $width, %options)
434           As "text", filling the specified width by adjusting the space
435           between words.
436
437       $width = $txt->advancewidth($string, %text_state)
438           Returns the width of the string based on all currently set text
439           state attributes.  These can optionally be overridden.
440
441       $overflow_text = $content->paragraph($text, $width, $height, %options)
442           Fill the rectangle with as much of the provided text as will fit.
443
444           Line spacing is set using the "leading" call.
445
446           In array context, returns the remaining text (if any) of the
447           positioned text and the remaining (unused) height.  In scalar
448           context, returns the remaining text (if any).
449
450           Options
451
452           -align => $alignment
453               Specifies the alignment for each line of text.  May be set to
454               left, center, right, or justified.  Default is left.
455
456           -align-last => $alignment
457               Specifies the alignment for the last line of justified text.
458               May be set to left, center, right, or justified.  Default is
459               left.
460
461           -underline => $distance
462           -underline => [ $distance, $thickness, ... ]
463               If a scalar, distance below baseline, else array reference with
464               pairs of distance and line thickness.
465
466       $overflow_text = $content->paragraphs($text, $width, $height, %options)
467           As "paragraph", but start a new line after every newline character.
468
469   Advanced Methods
470       $content->add @content
471           Add raw content to the PDF stream.  You will generally want to use
472           the other methods in this class instead.
473
474       $content->compressFlate
475           Marks content for compression on output.  This is done
476           automatically in nearly all cases, so you shouldn't need to call
477           this yourself.
478
479       $content->textstart
480           Starts a text object.  You will likely want to use the "text"
481           method instead.
482
483       $content->textend
484           Ends a text object.
485
486
487
488perl v5.34.0                      2021-08-02             PDF::API2::Content(3)
Impressum