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->meterlimit($ratio)
109 Note: This method is named incorrectly, and will be renamed in a
110 future release.
111 Sets the miter (not meter) limit when the line join style is a
113 miter join.
114 The ratio is the maximum length of the miter divided by the line
116 width. Any miter above this ratio will be converted to a bevel
117 join.
118 $content->linedash($on_off)
120 $content->linedash($on, $off)
121 Sets the line dash pattern.
122 If passed with one argument, the strokes and spaces will have equal
124 lengths.
125 If passed with two arguments, the strokes will have length $on, and
127 the spaces will have length $off.
128 $content->flatness($tolerance)
130 (Advanced) Sets the maximum variation in output pixels when drawing
131 curves.
132 $content->egstate($object)
134 (Advanced) Adds an Extended Graphic State object containing
135 additional state parameters.
136 Path Construction (Drawing)
138 $content->move($x, $y)
139 Starts a new path at the specified coordinates.
140 $content->line($x, $y)
142 Extends the path in a line from the current coordinates to the
143 specified coordinates, and updates the current position to be the
144 new coordinates.
145 Note: The line will not appear until you call "stroke".
147 $content->hline($x)
149 $content->vline($y)
150 Shortcut for drawing horizontal and vertical lines from the current
151 position.
152 $content->poly($x1, $y1, ..., $xn, $yn)
154 Shortcut for creating a polyline path. Moves to "[$x1, $y1]", and
155 then extends the path in lines along the specified coordinates.
156 $content->curve($cx1, $cy1, $cx2, $cy2, $x, $y)
158 Extends the path in a curve from the current point to "($x, $y)",
159 using the two specified points to create a cubic Bezier curve, and
160 updates the current position to be the new point.
161 Note: The curve will not appear until you call "stroke".
163 $content->spline($cx1, $cy1, $x, $y)
165 Extends the path in a curve from the current point to "($x, $y)",
166 using the two specified points to create a spline, and updates the
167 current position to be the new point.
168 Note: The curve will not appear until you call "stroke".
170 $content->arc($x, $y, $a, $b, $alpha, $beta, $move)
172 Extends the path along an arc of an ellipse centered at "[x, y]".
173 The major and minor axes of the ellipse are $a and $b,
174 respectively, and the arc moves from $alpha degrees to $beta
175 degrees. The current position is then set to the endpoint of the
176 arc.
177 Set $move to a true value if this arc is the beginning of a new
179 path instead of the continuation of an existing path.
180 $content->bogen($x1, $y1, $x2, $y2, $radius, $move, $outer, $reverse)
182 Extends the path along an arc of a circle of the specified radius
183 between "[x1, y1]" to "[x2, y2]". The current position is then set
184 to the endpoint of the 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 Set $outer to a true value to draw the larger arc between the two
190 points instead of the smaller one.
191 Set $reverse to a true value to start from the end of the arc and
193 extend to the beginning.
194 Note: 2*r cannot be smaller than the distance from "[x1, y1]" to
196 "[x2, y2]".
197 $content->close
199 Closes and ends the current path by extending a line from the
200 current position to the starting position.
201 $content->endpath
203 Ends the current path without explicitly enclosing it.
204 $content->ellipse($x, $y, $a, $b)
206 Creates an elliptical path centered on "[$x, $y]", with major and
207 minor axes specified by $a and $b, respectively.
208 Note: The ellipse will not appear until you call "stroke" or
210 "fill".
211 $content->circle($x, $y, $radius)
213 Creates a circular path centered on "[$x, $y]" with the specified
214 radius.
215 Note: The circle will not appear until you call "stroke" or "fill".
217 $content->pie($x, $y, $a, $b, $alpha, $beta)
219 Creates a pie-shaped path from an ellipse centered on "[$x, $y]".
220 The major and minor axes of the ellipse are $a and $b,
221 respectively, and the arc moves from $alpha degrees to $beta
222 degrees.
223 Note: The pie will not appear until you call "stroke" or "fill".
225 $content->rect($x1, $y1, $w1, $h1, ..., $xn, $yn, $wn, $hn)
227 Creates paths for one or more rectangles, with their lower left
228 points at "[$x, $y]" and with the specified widths and heights.
229 Note: The rectangle will not appear until you call "stroke" or
231 "fill".
232 $content->rectxy($x1, $y1, $x2, $y2)
234 Creates a rectangular path, with "[$x1, $y1]" and and "[$x2, $y2]"
235 specifying opposite corners.
236 Note: The rectangle will not appear until you call "stroke" or
238 "fill".
239 Path Painting (Drawing)
241 $content->stroke
242 Strokes the current path.
243 $content->fill($use_even_odd_fill)
245 Fills the current path.
246 If the path intersects with itself, the nonzero winding rule will
248 be used to determine which part of the path is filled in. If you
249 would prefer to use the even-odd rule, pass a true argument.
250 See the PDF Specification, section 8.5.3.3, for more details on
252 filling.
253 $content->fillstroke($use_even_odd_fill)
255 Fills and then strokes the current path.
256 $content->clip($use_even_odd_fill)
258 Modifies the current clipping path by intersecting it with the
259 current path.
260 Colors
262 $content->fillcolor($color)
263 $content->strokecolor($color)
264 Sets the fill or stroke color.
265 # Use a named color
267 $content->fillcolor('blue');
268 # Use an RGB color (start with '#')
270 $content->fillcolor('#FF0000');
271 # Use a CMYK color (start with '%')
273 $content->fillcolor('%FF000000');
274 RGB and CMYK colors can have one-byte, two-byte, three-byte, or
276 four-byte values for each color. For instance, cyan can be given
277 as %F000 or %FFFF000000000000.
278 External Objects
280 $content->image($image_object, $x, $y, $width, $height)
281 $content->image($image_object, $x, $y, $scale)
282 $content->image($image_object, $x, $y)
283 # Example
284 my $image_object = $pdf->image_jpeg($my_image_file);
285 $content->image($image_object, 100, 200);
286 Places an image on the page in the specified location.
288 If coordinate transformations have been made (see Coordinate
290 Transformations above), the position and scale will be relative to
291 the updated coordinates. Otherwise, [0,0] will represent the
292 bottom left corner of the page, and $width and $height will be
293 measured at 72dpi.
294 For example, if you have a 600x600 image that you would like to be
296 shown at 600dpi (i.e. one inch square), set the width and height to
297 72.
298 $content->formimage($form_object, $x, $y, $scale)
300 $content->formimage($form_object, $x, $y)
301 Places an XObject on the page in the specified location.
302 Text State Parameters
304 All of the following parameters that take a size are applied before any
305 scaling takes place, so you don't need to adjust values to counteract
306 scaling.
307 $spacing = $content->charspace($spacing)
309 Sets the spacing between characters. This is initially zero.
310 $spacing = $content->wordspace($spacing)
312 Sets the spacing between words. This is initially zero (or, in
313 other words, just the width of the space).
314 $scale = $content->hspace($scale)
316 Note: This method is named incorrectly, and will be renamed in a
317 future release.
318 Sets the percentage of horizontal text scaling (not spacing). This
320 is initially 100 (i.e. no scaling), and must be passed as an
321 integer.
322 $leading = $content->lead($leading)
324 Sets the text leading, which is the distance between baselines.
325 This is initially zero (i.e. the lines will be printed on top of
326 each other).
327 $mode = $content->render($mode)
329 Sets the text rendering mode.
330 0 = Fill text
332 1 = Stroke text (outline)
333 2 = Fill, then stroke text
334 3 = Neither fill nor stroke text (invisible)
335 4 = Fill text and add to path for clipping
336 5 = Stroke text and add to path for clipping
337 6 = Fill, then stroke text and add to path for clipping
338 7 = Add text to path for clipping
339 $distance = $content->rise($distance)
340 Adjusts the baseline up or down from its current location. This is
341 initially zero.
342 Use this for creating superscripts or subscripts (usually with an
344 adjustment to the font size as well).
345 %state = $content->textstate(charspace => $value, wordspace => $value,
347 ...)
348 Shortcut for setting multiple text state parameters at once.
349 This can also be used without arguments to retrieve the current
351 text state settings.
352 Note: This does not currently work with the "save" and "restore"
354 commands.
355 $content->font($font_object, $size)
357 # Example
358 my $pdf = PDF::API2->new();
359 my $font = $pdf->corefont('Helvetica');
360 $content->font($font, 12);
361 Sets the font and font size.
363 Text-Positioning
365 Note: There is a very good chance that these commands will be replaced
366 in a future release.
367 $content->distance($dx, $dy)
369 Moves to the start of the next line, offset by the given amounts,
370 which are both required.
371 $content->cr($vertical_offset)
373 If passed with an argument, moves to the start of the next line,
374 offset by the given value.
375 If passed without an argument, moves to the start of the next line.
377 Note that this is equivalent to a carriage return plus line feed.
379 To get just a carriage return, pass zero as the argument.
380 $content->nl
382 Moves to the start of the next line.
383 ($tx, $ty) = $content->textpos()
385 Gets the current estimated text position.
386 Note: This does not affect the PDF in any way.
388 Text-Showing
390 $width = $content->text($text, %options)
391 Adds text to the page.
392 Options:
394 -indent
396 Indents the text by the number of points.
397 -underline => 'auto'
399 -underline => $distance
400 -underline => [$distance, $thickness, ...]
401 Underlines the text. $distance is the number of units beneath
402 the baseline, and $thickness is the width of the line.
403 Multiple underlines can be made by passing several distances
405 and thicknesses.
406 $content->text_center($text)
408 As "text", but centered on the current point.
409 $txt->text_right $text, %options
411 As "text", but right-aligned to the current point.
412 $width = $txt->advancewidth($string, %text_state)
414 Returns the width of the string based on all currently set text-
415 state attributes. These can optionally be overridden.
416 Advanced Methods
418 $content->add @content
419 Add raw content to the PDF stream. You will generally want to use
420 the other methods in this class instead.
421 $content->compressFlate
423 Marks content for compression on output. This is done
424 automatically in nearly all cases, so you shouldn't need to call
425 this yourself.
426 $content->textstart
428 Starts a text object. You will likely want to use the "text"
429 method instead.
430 $content->textend
432 Ends a text object.
433perl v5.12.2 2011-01-24 PDF::API2::Content(3)