1PDF::Builder::Page(3) User Contributed Perl DocumentationPDF::Builder::Page(3)
2
6 PDF::Builder::Page - Methods to interact with individual pages
7
9 my $pdf = PDF::Builder->new();
10 # Add a page to a new or existing PDF
12 my $page = $pdf->page();
13 # Set the physical (media) page size
15 # Set prepress page boundaries, a convenience function for those times when
16 # it is not necessary to set other prepress (print-related) page boundaries
17 $page->size('letter'); # by common size name
18 #$page->size([0, 0, 612, 792]); # by points LLx,LLy, URx,URy
19 # alternately, can set (or get) prepress page boundaries
21 $page->boundaries('media' => '12x18', 'trim' => 0.5 * 72);
22 # Add an image
24 my $image = $pdf->image('/path/to/file.jpg');
25 $page->object($image, $x,$y, $w,$h);
26 # Create a content object for text
28 my $text = $page->text();
29 # Create a content object for drawing shapes
31 my $canvas = $page->graphics(); # or gfx()
32 # Now to draw graphics (using $canvas object) and text (using $text object).
34 # NOTE that everything in the graphics (canvas) object will be laid down on
35 # the page BEFORE anything in the text object is laid down. That is,
36 # text will cover graphics, but not vice-versa. This is simply due to
37 # the order in which the objects were defined.
38
40 $page = PDF::Builder::Page->new($pdf, $parent, $index)
41 Returns a page object (called from $pdf->page()).
42 Page Size Methods
44 $page->userunit($value)
45 Sets the User Unit for this one page. See "User Units" in
46 PDF::Builder::Docs for more information.
47 $page->mediabox($alias)
49 $page->mediabox($alias, 'orient' => 'orientation')
50 $page->mediabox($w,$h)
51 $page->mediabox($llx,$lly, $urx,$ury)
52 ($llx,$lly, $urx,$ury) = $page->mediabox()
53 Sets or gets the Media Box for this one page. See "Media Box" in
54 PDF::Builder::Docs for more information. The method always returns
55 the current bounds (after any set operation).
56 ($llx,$lly, $urx,$ury) = $page->get_mediabox()
58 Gets the Media Box corner coordinates based on best estimates or
59 the default. These are in the order given in a mediabox call (4
60 coordinates).
61 This method is Deprecated, and will likely be removed in the
63 future. Use the global ($pdf) or page ($page) mediabox() call with
64 no parameters instead.
65 $page->cropbox($alias)
67 $page->cropbox($alias, 'orient' => 'orientation')
68 $page->cropbox($w,$h)
69 $page->cropbox($llx,$lly, $urx,$ury)
70 ($llx,$lly, $urx,$ury) = $page->cropbox()
71 Sets or gets the Crop Box for this one page. See "Crop Box" in
72 PDF::Builder::Docs for more information. The method always returns
73 the current bounds (after any set operation).
74 ($llx,$lly, $urx,$ury) = $page->get_cropbox()
76 Gets the Crop Box based on best estimates or the default.
77 This method is Deprecated, and will likely be removed in the
79 future. Use the global ($pdf) or page ($page) cropbox() call with
80 no parameters instead.
81 $page->bleedbox($alias)
83 $page->bleedbox($alias, 'orient' => 'orientation')
84 $page->bleedbox($w,$h)
85 $page->bleedbox($llx,$lly, $urx,$ury)
86 ($llx,$lly, $urx,$ury) = $page->bleedbox()
87 Sets or gets or gets the Bleed Box for this one page. See "Bleed
88 Box" in PDF::Builder::Docs for more information. The method always
89 returns the current bounds (after any set operation).
90 ($llx,$lly, $urx,$ury) = $page->get_bleedbox()
92 Gets the Bleed Box based on best estimates or the default.
93 This method is Deprecated, and will likely be removed in the
95 future. Use the global ($pdf) or page ($page) bleedbox() call with
96 no parameters instead.
97 $page->trimbox($alias)
99 $page->trimbox($alias, 'orient' => 'orientation')
100 $page->trimbox($w,$h)
101 $page->trimbox($llx,$lly, $urx,$ury)
102 ($llx,$lly, $urx,$ury) = $page->trimbox()
103 Sets or gets the Trim Box for this one page. See "Trim Box" in
104 PDF::Builder::Docs for more information. The method always returns
105 the current bounds (after any set operation).
106 ($llx,$lly, $urx,$ury) = $page->get_trimbox()
108 Gets the Trim Box based on best estimates or the default.
109 This method is Deprecated, and will likely be removed in the
111 future. Use the global ($pdf) or page ($page) trimbox() call with
112 no parameters instead.
113 $page->artbox($alias)
115 $page->artbox($alias, 'orient' => 'orientation')
116 $page->artbox($w,$h)
117 $page->artbox($llx,$lly, $urx,$ury)
118 ($llx,$lly, $urx,$ury) = $page->artbox()
119 Sets or gets the Art Box for this one page. See "Art Box" in
120 PDF::Builder::Docs for more information. The method always returns
121 the current bounds (after any set operation).
122 ($llx,$lly, $urx,$ury) = $page->get_artbox()
124 Gets the Art Box based on best estimates or the default.
125 This method is Deprecated, and will likely be removed in the
127 future. Use the global ($pdf) or page ($page) artbox() call with no
128 parameters instead.
129 $page->rotate($deg)
131 Rotates the page by the given degrees, which must be a multiple of
132 90. An angle that is not a multiple of 90 will be rounded to the
133 nearest 90 degrees, with a message.
134 Note that the rotation angle is clockwise for a positive amount!
136 E.g., a rotation of +90 (or -270) will have the bottom edge of the
137 paper at the left of the screen. After rotating the page 180
138 degrees, "[0, 0]" (originally lower left corner) will be be in the
139 top right corner of the page, rather than the bottom left. X will
140 increase to the right, and Y will increase downward.
141 (This allows you to auto-rotate to landscape without changing the
143 mediabox! There are other ways to accomplish this end, such as
144 using the size() method, which will not change the coordinate
145 system (move the origin).)
146 Note that some users have reported problems with using "rotate",
148 that the dimensions were limited to the smaller of the original
149 height or width. If you experience this, be sure to check whether
150 you are doing some sort of crop box or other clipping, that might
151 not rotate as expected with the rest of the page. In other words,
152 you might need to manually adjust the crop box dimensions.
153 Do not confuse this rotate() call with the graphics context
155 rotation (Content.pm) rotate(), which permits any angle, is of
156 opposite direction, and does not shift the origin!
157 Alternate name: "rotation"
159 This has been added for PDF::API2 compatibility.
161 $page->size($size) # Set
163 @rectangle = $page->size() # Get
164 Set the physical page size or return the coordinates of the
165 rectangle enclosing the physical page size. This is an alternate
166 method provided for compatibility with PDF::API2.
167 # Set the physical page (media) size using a common size name
169 $page->size('letter');
170 # Set the page size using coordinates in points (X1, Y1, X2, Y2)
172 $page->size([0, 0, 612, 792]);
173 # Get the page coordinates in points
175 my @rectangle = $page->size();
176 See Page Sizes below for possible values. The size method is a
178 convenient shortcut for setting the PDF's media box when other
179 prepress (print-related) page boundaries aren't required. It's
180 equivalent to the following:
181 # Set
183 $page = $page->boundaries('media' => $size);
184 # Get
186 @rectangle = $page->boundaries()->{'media'}->@*;
187 $page = $page->boundaries(%boundaries)
189 \%boundaries = $page->boundaries()
190 Set prepress page boundaries to facilitate printing. Returns the
191 current page boundaries if called without arguments. This is an
192 alternate method provided for compatibility with PDF::API2.
193 # Set
195 $page->boundaries(
196 # 13x19 inch physical sheet size
197 'media' => '13x19',
198 # sheet content is 11x17 with 0.25" bleed
199 'bleed' => [0.75 * 72, 0.75 * 72, 12.25 * 72, 18.25 * 72],
200 # 11x17 final trimmed size
201 'trim' => 0.25 * 72,
202 );
203 # Get
205 %boundaries = $page->boundaries();
206 ($x1,$y1, $x2,$y2) = $page->boundaries('trim');
207 The %boundaries hash contains one or more page boundary keys (see
209 Page Boundaries) to set or replace, each with a corresponding size
210 (see Page Sizes).
211 If called without arguments, the returned hashref will contain
213 (Get) all five boundaries. If called with one string argument, it
214 returns the coordinates for the specified page boundary. If more
215 than one boundary type is given, only the first is processed, and a
216 warning is given that the remainder are ignored.
217 Page Boundaries
219 PDF defines five page boundaries. When creating PDFs for print shops,
221 you'll most commonly use just the media box and trim box. Traditional
222 print shops may also use the bleed box when adding printer's marks and
223 other information.
224 media
226 The media box defines the boundaries of the physical medium on
227 which the page is to be printed. It may include any extended area
228 surrounding the finished page for bleed, printing marks, or other
229 such purposes. The default value is as defined for PDF, a US letter
230 page (8.5" x 11").
231 crop
233 The crop box defines the region to which the contents of the page
234 shall be clipped (cropped) when displayed or printed. The default
235 value is the page's media box. This is a historical page boundary.
236 You'll likely want to set the bleed and/or trim boxes instead.
237 bleed
239 The bleed box defines the region to which the contents of the page
240 shall be clipped when output in a production environment. This may
241 include any extra bleed area needed to accommodate the physical
242 limitations of cutting, folding, and trimming equipment. The actual
243 printed page (media box) may include printing marks that fall
244 outside the bleed box. The default value is the page's crop box.
245 trim
247 The trim box defines the intended dimensions of the finished page
248 after trimming. It may be smaller than the media box to allow for
249 production-related content, such as printing instructions, cut
250 marks, or color bars. The default value is the page's crop box.
251 art The art box defines the extent of the page's meaningful content
253 (including potential white space) as intended by the page's
254 creator. The default value is the page's crop box.
255 Page Sizes
257 PDF page sizes are stored as rectangular coordinates. For convenience,
259 PDF::Builder also supports a number of aliases and shortcuts that are
260 more human-friendly. The following formats are available:
261 a standard paper size
263 $page->boundaries('media' => 'A4');
264 Aliases for the most common paper sizes are built in (case-
266 insensitive). US: Letter, Legal, Ledger, Tabloid (and others)
267 Metric: 4A0, 2A0, A0 - A6, 4B0, 2B0, and B0 - B6 (and others)
268 a "WxH" string in inches
270 $page->boundaries('media' => '8.5x11');
271 Many US paper sizes are commonly identified by their size in inches
273 rather than by a particular name. These can be passed as strings
274 with the width and height separated by an "x". Examples: "4x6",
275 "12x18", "8.5x11"
276 a number representing a reduction (in points) from the next-larger box
278 For example, a 12" x 18" physical sheet to be trimmed down to an
279 11" x 17" sheet can be specified as follows:
280 # Note: There are 72 points per inch
282 $page->boundaries('media' => '12x18', 'trim' => 0.5 * 72);
283 # Equivalent
285 $page->boundaries('media' => [0, 0, 12 * 72, 18 * 72],
286 'trim' => [0.5 * 72, 0.5 * 72, 11.5 * 72, 17.5 * 72]);
287 This example shows a 12" x 18" physical sheet that will be reduced
289 to a final size of 11" x 17" by trimming 0.5" from each edge. The
290 smaller page boundary is assumed to be centered within the larger
291 one.
292 The "next-larger box" follows this order, stopping at the first
294 defined value:
295 art -> trim -> bleed -> media
297 crop -> media
298 This option isn't available for the media box, since it is by
300 definition, the largest boundary.
301 [$width, $height] in points
303 $page->boundaries('media' => [8.5 * 72, 11 * 7.2]);
304 For other page or boundary sizes, the width and height (in points)
306 can be given directly as an array.
307 [$x1, $y1, $x2, $y2] in points
309 $page->boundaries('media' => [0, 0, 8.5 * 72, 11 * 72]);
310 Finally, the absolute (raw) coordinates of the bottom-left and top-
312 right corners of a rectangle can be specified.
313 $gfx = $page->gfx(%opts)
315 $gfx = $page->gfx($prepend)
316 $gfx = $page->gfx()
317 Returns a graphics content object, for drawing paths and shapes.
318 You may specify the "prepend" flag in the old or new way. The old
320 way is to give a single boolean value (0 false, non-zero true). The
321 new way is to give a hash element named 'prepend', with the same
322 values.
323 gfx(boolean_value $prepend)
325 gfx('prepend' => boolean_value)
326 If $prepend is true, or the option 'prepend' is given with a true
328 value, the content will be prepended to the page description (at
329 the beginning of the page's content stream). Otherwise, it will be
330 appended. The default is false.
331 gfx('compress' => boolean_value)
333 You may specify a compression flag saying whether the drawing
335 instructions are to be compressed. If not given, the default is for
336 the overall PDF compression setting to be used (on by default).
337 You may have more than one gfx object. They and text objects will
339 be output as objects and streams in the order defined, with all
340 actions pertaining to this gfx object appearing in one stream.
341 However, note that graphics and text objects are not fully
342 independent of each other: the exit state (linewidth, strokecolor,
343 etc.) of one object is the entry state of the next object in line
344 to be output, and so on.
345 If you intermix multiple gfx and text objects on a page, the
347 results may be confusing. Say you have $gfx1, $text1, $gfx2, and
348 $text2 on your page (created in that order). PDF::Builder will
349 output all the $gfx1->action calls in one stream, then all the
350 $text1->action calls in the next stream, and likewise for $gfx2
351 usage and finally $text2.
352 Then it's PDF's turn to confuse you. PDF will process the entire
354 $gfx1 object stream, accumulating the graphics state to the end of
355 the stream, and using that as the entry state into $text1. In a
356 similar manner, $gfx2 and $text2 are read, processed, and rendered.
357 Thus, a change in, say, the dash pattern in the middle of $gfx1,
358 after you have output some $gfx2, $text1, and $text2 material, may
359 suddenly show up at the beginning of $text1 (and continue through
360 $gfx2 and $text2)!
361 It is possible to use multiple graphics objects, to avoid having to
363 change settings constantly, but you may want to consider resetting
364 all your settings at the first call to each object, so that you are
365 starting from a known base. This may most easily be done by using
366 $type->restore() and ->save() just after creating $type:
367 $text1 = $page->text();
369 $text1->save();
370 $grfx1 = $page->gfx();
371 $grfx1->restore();
372 $grfx1->save();
373 $text2 = $page->text();
374 $text2->restore();
375 $text2->save();
376 $grfx2 = $page->gfx();
377 $grfx1->restore();
378 Alternate name: "graphics"
380 This has been added for PDF::API2 compatibility.
382 $text = $page->text(%opts)
384 $text = $page->text($prepend)
385 $text = $page->text()
386 Returns a text content object, for writing text. See
387 PDF::Builder::Content for details.
388 You may specify the "prepend" flag in the old or new way. The old
390 way is to give a single boolean value (0 false, non-zero true). The
391 new way is to give a hash element named 'prepend', with the same
392 values.
393 text(boolean_value $prepend)
395 text('prepend' => boolean_value)
396 If $prepend is true, or the option 'prepend' is given with a true
398 value, the content will be prepended to the page description (at
399 the beginning of the page's content stream). Otherwise, it will be
400 appended. The default is false.
401 text('compress' => boolean_value)
403 You may specify a compression flag saying whether the text content
405 is to be compressed. If not given, the default is for the overall
406 PDF compression setting to be used (on by default).
407 Please see the discussion above in gfx() regarding multiple
409 graphics and text objects on one page, how they are grouped into
410 PDF objects and streams, and the rendering consequences of running
411 through one entire object at a time, before moving on to the next.
412 The text object has many settings and attributes of its own, but
414 shares many with graphics (gfx), such as strokecolor, fillcolor,
415 linewidth, linedash, and the like. Thus there is some overlap in
416 attributes, and graphics and text calls can affect each other.
417 $page = $page->object($object, $x,$y, $scale_x,$scale_y)
419 Places an image or other external object (a.k.a. XObject) on the
420 page in the specified location.
421 For images, $scale_x and $scale_y represent the width and height of
423 the image on the page in points. If $scale_x is omitted, it will
424 default to 72 pixels per inch. If $scale_y is omitted, the image
425 will be scaled proportionally based on the image dimensions.
426 For other external objects, the scale is a multiplier, where 1 (the
428 default) represents 100% (i.e. no change).
429 If the object to be placed depends on a coordinate transformation
431 (e.g. rotation or skew), first create a content object using
432 "graphics", then call "object" in PDF::Builder::Content after
433 making the appropriate transformations.
434 $ant = $page->annotation()
436 Returns a new annotation object.
437 $page->resource($type, $key, $obj)
439 Adds a resource to the page-inheritance tree.
440 Example:
442 $co->resource('Font', $fontkey, $fontobj);
444 $co->resource('XObject', $imagekey, $imageobj);
445 $co->resource('Shading', $shadekey, $shadeobj);
446 $co->resource('ColorSpace', $spacekey, $speceobj);
447 Note: You only have to add the required resources if they are NOT
449 handled by the *font*, *image*, *shade* or *space* methods.
450perl v5.38.0 2023-07-21 PDF::Builder::Page(3)