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->gfx();
15 my $content = $page->text();
16 # Then call the methods below add graphics and text to the page.
18
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 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 $content->translate($x, $y)
30 Moves the origin along the x and y axes.
31 $content->rotate($degrees)
33 Rotates the coordinate system counter-clockwise.
34 Use a negative argument to rotate clockwise.
36 $content->scale($sx, $sy)
38 Scales (stretches) the coordinate systems along the x and y axes.
39 $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 $content->transform(%options)
45 $content->transform(
46 -translate => [$x, $y],
47 -rotate => $degrees,
48 -scale => [$sx, $sy],
49 -skew => [$sa, $sb],
50 )
51 Performs multiple coordinate transformations at once, in the order
53 recommended by the PDF specification (translate, rotate, scale,
54 then skew).
55 This is equivalent to making each transformation separately.
57 $content->transform_rel(%options)
59 Makes transformations similarly to "transform", except that it adds
60 to the previously set values.
61 $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 Graphics State Parameters
68 $content->save
69 Saves the current graphics state and text state on a stack.
70 $content->restore
72 Restores the most recently saved graphics state and text state,
73 removing it from the stack.
74 $content->linewidth($width)
76 Sets the width of the stroke.
77 $content->linecap($style)
79 Sets the style to be used at the end of a stroke.
80 0 = Butt Cap
82 The stroke ends at the end of the path, with no projection.
83 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 2 = Projecting Square Cap
89 The stroke continues past the end of the path for half the line
90 width.
91 $content->linejoin($style)
93 Sets the style of join to be used at corners of a path.
94 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 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 2 = Bevel Join
105 A triangle is drawn to fill in the notch between the two
106 strokes.
107 $content->miterlimit($ratio)
109 Sets the miter limit when the line join style is a miter join.
110 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 There is no documented default miter limit.
118 $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 If called without any arguments, a solid line will be drawn.
127 If called with one argument, the dashes and gaps will have equal
129 lengths.
130 If called with two or more arguments, the arguments represent
132 alternating dash and gap lengths.
133 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 $content->flatness($tolerance)
138 (Advanced) Sets the maximum variation in output pixels when drawing
139 curves.
140 $content->egstate($object)
142 (Advanced) Adds an Extended Graphic State object containing
143 additional state parameters.
144 Path Construction (Drawing)
146 $content->move($x, $y)
147 Starts a new path at the specified coordinates.
148 $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 Note: The line will not appear until you call "stroke".
155 $content->hline($x)
157 $content->vline($y)
158 Shortcut for drawing horizontal and vertical lines from the current
159 position.
160 $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 $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 Note: The curve will not appear until you call "stroke".
171 $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 Note: The curve will not appear until you call "stroke".
178 $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 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 $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 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 Set $outer to a true value to draw the larger arc between the two
198 points instead of the smaller one.
199 Set $reverse to a true value to draw the mirror image of the
201 specified arc.
202 "$radius * 2" cannot be smaller than the distance from "[x1,y1]" to
204 "[x2,y2]".
205 Note: The curve will not appear until you call "stroke".
207 $content->close()
209 Closes and ends the current path by extending a line from the
210 current position to the starting position.
211 $content->endpath()
213 Ends the current path without explicitly enclosing it.
214 $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 Note: The ellipse will not appear until you call "stroke" or
220 "fill".
221 $content->circle($x, $y, $radius)
223 Creates a circular path centered on "[$x, $y]" with the specified
224 radius.
225 Note: The circle will not appear until you call "stroke" or "fill".
227 $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 Note: The pie will not appear until you call "stroke" or "fill".
235 $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 Note: The rectangles will not appear until you call "stroke" or
241 "fill".
242 $content->rectxy($x1, $y1, $x2, $y2)
244 Creates a rectangular path, with "[$x1,$y1]" and and "[$x2,$y2]"
245 specifying opposite corners.
246 Note: The rectangle will not appear until you call "stroke" or
248 "fill".
249 Path Painting (Drawing)
251 $content->stroke
252 Strokes the current path.
253 $content->fill($use_even_odd_fill)
255 Fills the current path.
256 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 See the PDF Specification, section 8.5.3.3, for more details on
262 filling.
263 $content->fillstroke($use_even_odd_fill)
265 Fills and then strokes the current path.
266 $content->clip($use_even_odd_fill)
268 Modifies the current clipping path by intersecting it with the
269 current path.
270 Colors
272 $content->fillcolor($color)
273 $content->strokecolor($color)
274 Sets the fill or stroke color.
275 # Use a named color
277 $content->fillcolor('blue');
278 # Use an RGB color (start with '#')
280 $content->fillcolor('#FF0000');
281 # Use a CMYK color (start with '%')
283 $content->fillcolor('%FF000000');
284 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 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 Places an image on the page in the specified location.
298 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 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 $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 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 $spacing = $content->charspace($spacing)
319 Sets the spacing between characters. This is initially zero.
320 $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 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 $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 $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 $mode = $content->render($mode)
343 Sets the text rendering mode.
344 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 Use this for creating superscripts or subscripts (usually with an
358 adjustment to the font size as well).
359 %state = $content->textstate(charspace => $value, wordspace => $value,
361 ...)
362 Shortcut for setting multiple text state parameters at once.
363 This can also be used without arguments to retrieve the current
365 text state settings.
366 Note: This does not currently work with the "save" and "restore"
368 commands.
369 $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 Sets the font and font size.
377 Text-Positioning
379 Note: There is a very good chance that these commands will be replaced
380 in a future release.
381 $content->distance($dx, $dy)
383 Moves to the start of the next line, offset by the given amounts,
384 which are both required.
385 $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 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 Pass zero as the argument to ignore the leading and get just a
397 carriage return.
398 $content->nl()
400 Moves to the start of the next line.
401 ($tx, $ty) = $content->textpos()
403 Gets the current estimated text position.
404 Note: This does not affect the PDF in any way.
406 Text-Showing
408 $width = $content->text($text, %options)
409 Adds text to the page.
410 Returns the width of the text in points.
412 Options:
414 -indent
416 Indents the text by the number of points.
417 -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 Multiple underlines can be made by passing several distances
425 and thicknesses.
426 $width = $content->text_center($text, %options)
428 As "text", but centered on the current point.
429 $width = $content->text_right($text, %options)
431 As "text", but right-aligned to the current point.
432 $width = $content->text_justified($text, $width, %options)
434 As "text", filling the specified width by adjusting the space
435 between words.
436 $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 $overflow_text = $content->paragraph($text, $width, $height, %options)
442 Fill the rectangle with as much of the provided text as will fit.
443 Line spacing is set using the "leading" call.
445 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 Options
451 -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 -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 -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 $overflow_text = $content->paragraphs($text, $width, $height, %options)
467 As "paragraph", but start a new line after every newline character.
468 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 $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 $content->textstart
480 Starts a text object. You will likely want to use the "text"
481 method instead.
482 $content->textend
484 Ends a text object.
485perl v5.34.0 2021-08-02 PDF::API2::Content(3)