1PDF::Builder::Page(3) User Contributed Perl DocumentationPDF::Builder::Page(3)
2
3
4

NAME

6       PDF::Builder::Page - Methods to interact with individual pages
7

SYNOPSIS

9           my $pdf = PDF::Builder->new();
10
11           # Add a page to a new or existing PDF
12           my $page = $pdf->page();
13
14           # 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
20           # alternately, can set (or get) prepress page boundaries
21           $page->boundaries('media' => '12x18', 'trim' => 0.5 * 72);
22
23           # Add an image
24           my $image = $pdf->image('/path/to/file.jpg');
25           $page->object($image, $x,$y, $w,$h);
26
27           # Create a content object for text
28           my $text = $page->text();
29
30           # Create a content object for drawing shapes
31           my $canvas = $page->graphics();  # or gfx()
32
33           # 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

METHODS

40       $page = PDF::Builder::Page->new($pdf, $parent, $index)
41           Returns a page object (called from $pdf->page()).
42
43   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
48       $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
57       ($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
62           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
66       $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
75       ($llx,$lly, $urx,$ury) = $page->get_cropbox()
76           Gets the Crop Box based on best estimates or the default.
77
78           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
82       $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
91       ($llx,$lly, $urx,$ury) = $page->get_bleedbox()
92           Gets the Bleed Box based on best estimates or the default.
93
94           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
98       $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
107       ($llx,$lly, $urx,$ury) = $page->get_trimbox()
108           Gets the Trim Box based on best estimates or the default.
109
110           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
114       $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
123       ($llx,$lly, $urx,$ury) = $page->get_artbox()
124           Gets the Art Box based on best estimates or the default.
125
126           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
130       $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
135           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
142           (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
147           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
154           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
158           Alternate name: "rotation"
159
160           This has been added for PDF::API2 compatibility.
161
162       $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
168               # Set the physical page (media) size using a common size name
169               $page->size('letter');
170
171               # Set the page size using coordinates in points (X1, Y1, X2, Y2)
172               $page->size([0, 0, 612, 792]);
173
174               # Get the page coordinates in points
175               my @rectangle = $page->size();
176
177           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
182               # Set
183               $page = $page->boundaries('media' => $size);
184
185               # Get
186               @rectangle = $page->boundaries()->{'media'}->@*;
187
188       $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
194               # 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
204               # Get
205               %boundaries = $page->boundaries();
206               ($x1,$y1, $x2,$y2) = $page->boundaries('trim');
207
208           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
212           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
218       Page Boundaries
219
220       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
225       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
232       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
238       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
246       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
252       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
256       Page Sizes
257
258       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
262       a standard paper size
263               $page->boundaries('media' => 'A4');
264
265           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
269       a "WxH" string in inches
270               $page->boundaries('media' => '8.5x11');
271
272           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
277       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
281               # Note: There are 72 points per inch
282               $page->boundaries('media' => '12x18', 'trim' => 0.5 * 72);
283
284               # 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
288           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
293           The "next-larger box" follows this order, stopping at the first
294           defined value:
295
296               art -> trim -> bleed -> media
297               crop -> media
298
299           This option isn't available for the media box, since it is by
300           definition, the largest boundary.
301
302       [$width, $height] in points
303               $page->boundaries('media' => [8.5 * 72, 11 * 7.2]);
304
305           For other page or boundary sizes, the width and height (in points)
306           can be given directly as an array.
307
308       [$x1, $y1, $x2, $y2] in points
309               $page->boundaries('media' => [0, 0, 8.5 * 72, 11 * 72]);
310
311           Finally, the absolute (raw) coordinates of the bottom-left and top-
312           right corners of a rectangle can be specified.
313
314       $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
319           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
324           gfx(boolean_value $prepend)
325           gfx('prepend' => boolean_value)
326
327           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
332           gfx('compress' => boolean_value)
333
334           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
338           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
346           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
353           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
362           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
368            $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
379           Alternate name: "graphics"
380
381           This has been added for PDF::API2 compatibility.
382
383       $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
389           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
394           text(boolean_value $prepend)
395           text('prepend' => boolean_value)
396
397           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
402           text('compress' => boolean_value)
403
404           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
408           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
413           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
418       $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
422           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
427           For other external objects, the scale is a multiplier, where 1 (the
428           default) represents 100% (i.e. no change).
429
430           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
435       $ant = $page->annotation()
436           Returns a new annotation object.
437
438       $page->resource($type, $key, $obj)
439           Adds a resource to the page-inheritance tree.
440
441           Example:
442
443               $co->resource('Font', $fontkey, $fontobj);
444               $co->resource('XObject', $imagekey, $imageobj);
445               $co->resource('Shading', $shadekey, $shadeobj);
446               $co->resource('ColorSpace', $spacekey, $speceobj);
447
448           Note: You only have to add the required resources if they are NOT
449           handled by the *font*, *image*, *shade* or *space* methods.
450
451
452
453perl v5.36.0                      2023-01-23             PDF::Builder::Page(3)
Impressum