1PDF::API2::Page(3) User Contributed Perl Documentation PDF::API2::Page(3)
2
6 PDF::API2::Page - Methods to interact with individual pages
7
9 my $pdf = PDF::API2->new();
10 # Add a page to a new or existing PDF
12 my $page = $pdf->page();
13 # Set the page size
15 $page->size('letter');
16 # Set prepress page boundaries
18 $page->boundaries(media => '12x18', trim => 0.5 * 72);
19 # Add an image
21 my $image = $pdf->image('/path/to/file.jpg');
22 $page->object($image, $x, $y, $w, $h);
23 # Add textual content
25 my $text = $page->text();
26 # Add graphical content (paths and shapes)
28 my $canvas = $page->graphics();
29
31 size
32 # Set the page size using a common name
33 $page->size('letter');
34 # Set the page size using coordinates in points (X1, Y1, X2, Y2)
36 $page->size([0, 0, 612, 792]);
37 # Get the page coordinates in points
39 my @rectangle = $page->size();
40 Set the physical page size (a.k.a. media box) when called with an
42 argument. See "Page Sizes" below for possible values. Returns the
43 $page object.
44 Returns the coordinates of the rectangle enclosing the physical page
46 size when called without arguments.
47 The size method is a convenient shortcut for setting the PDF's media
49 box when print-related page boundaries aren't required. It's
50 equivalent to the following:
51 # Set
53 $page = $page->boundaries(media => $size);
54 # Get
56 @rectangle = $page->boundaries->{'media'}->@*;
57 boundaries
59 # Set
60 $page->boundaries(
61 media => '13x19',
62 bleed => [0.75 * 72, 0.75 * 72, 12.25 * 72, 18.25 * 72],
63 trim => 0.25 * 72,
64 );
65 # Get
67 %boundaries = $page->boundaries();
68 ($x1, $y1, $x2, $y2) = $page->boundaries('trim');
69 Set or replace all prepress page boundaries when called with a hash
71 containing one or more page boundary definitions. Returns the $page
72 object.
73 Returns the current page boundaries if called without arguments.
75 Returns the coordinates for the specified page boundary if called with
76 one argument.
77 Page Boundaries
79 PDF defines five page boundaries. When creating PDFs for print shops,
81 you'll most commonly use just the media box and trim box. Traditional
82 print shops may also use the bleed box when adding printer's marks and
83 other information.
84 • media
86 The media box defines the boundaries of the physical medium on
88 which the page is to be printed. It may include any extended area
89 surrounding the finished page for bleed, printing marks, or other
90 such purposes. The default value is a US letter page (8.5" x 11").
91 • crop
93 The crop box defines the region to which the contents of the page
95 shall be clipped (cropped) when displayed or printed. The default
96 value is the page's media box.
97 This is a historical page boundary. You'll likely want to set the
99 bleed and/or trim boxes instead.
100 • bleed
102 The bleed box defines the region to which the contents of the page
104 shall be clipped when output in a production environment. This may
105 include any extra bleed area needed to accommodate the physical
106 limitations of cutting, folding, and trimming equipment. The
107 actual printed page (media box) may include printing marks that
108 fall outside the bleed box. The default value is the page's crop
109 box.
110 • trim
112 The trim box defines the intended dimensions of the finished page
114 after trimming. It may be smaller than the media box to allow for
115 production-related content, such as printing instructions, cut
116 marks, or color bars. The default value is the page's crop box.
117 • art
119 The art box defines the extent of the page's meaningful content
121 (including potential white space) as intended by the page's
122 creator. The default value is the page's crop box.
123 Page Sizes
125 PDF page sizes are stored as rectangle coordinates. For convenience,
127 PDF::API2 also supports a number of aliases and shortcuts that are more
128 human-friendly.
129 The following formats are available:
131 • a standard paper size
133 $page->boundaries(media => 'A4');
135 Aliases for the most common paper sizes are built in (case-
137 insensitive).
138 US: Letter, Legal, Ledger, Tabloid
140 Metric: 4A0, 2A0, A0 - A6, 4B0, 2B0, and B0 - B6
142 • a "WxH" string in inches
144 $page->boundaries(media => '8.5x11');
146 Many US paper sizes are commonly identified by their size in inches
148 rather than by a particular name. These can be passed as strings
149 with the width and height separated by an "x".
150 Examples: "4x6", "12x18", "8.5x11"
152 • a number (in points) representing a reduction from the next-larger
154 box
155 # Note: There are 72 points per inch
157 $page->boundaries(media => '12x18', trim => 0.5 * 72);
158 # Equivalent
160 $page->boundaries(media => [0, 0, 12 * 72, 18 * 72],
161 trim => [0.5 * 72, 0.5 * 72, 11.5 * 72, 17.5 * 72]);
162 This example shows a 12" x 18" physical sheet that will be reduced
164 to a final size of 11" x 17" by trimming 0.5" from each edge. The
165 smaller boundary is assumed to be centered on the larger one.
166 The "next-larger box" follows this order, stopping at the first
168 defined value:
169 art -> trim -> bleed -> media
171 crop -> media
173 This option isn't available for the media box since it is by
175 definition the largest boundary.
176 • [$width, $height] in points
178 $page->boundaries(media => [8.5 * 72, 11 * 7.2]);
180 For other page or boundary sizes, the width and height (in points)
182 can be given directly as an array.
183 • [$x1, $y1, $x2, $y2] in points
185 $page->boundaries(media => [0, 0, 8.5 * 72, 11 * 72]);
187 Finally, the raw coordinates of the bottom-left and top-right
189 corners of a rectangle can be specified.
190 rotation
192 $page = $page->rotation($degrees);
193 Rotates the page clockwise when displayed or printed. $degrees must be
195 a multiple of 90 and may be negative for counter-clockwise rotation.
196 The coordinate system follows the page rotation. In other words, after
198 rotating the page 180 degrees, [0, 0] will be in the top right corner
199 of the page rather than the bottom left, X will increase to the right,
200 and Y will increase downward.
201 To create a landscape page without moving the origin, use "size".
203 graphics
205 my $canvas = $page->graphics(%options);
206 Returns a PDF::API2::Content object for drawing paths and shapes.
208 The following options are available:
210 • prepend (boolean)
212 If true, place the drawing at the beginning of the page's content
214 stream instead of the end.
215 • compress (boolean)
217 Manually specify whether the drawing instructions should be
219 compressed. If unspecified, the PDF's compression setting will be
220 used, which is on by default.
221 text
223 my $text = $page->text(%options);
224 Returns a PDF::API2::Content object for including textual content.
226 The options are the same as the "graphics" method.
228 object
230 $page = $page->object($object, $x, $y, $scale_x, $scale_y);
231 Places an image or other external object (a.k.a. XObject) on the page
233 in the specified location.
234 For images, $scale_x and $scale_y represent the width and height of the
236 image on the page in points. If $scale_x is omitted, it will default
237 to 72 pixels per inch. If $scale_y is omitted, the image will be
238 scaled proportionally based on the image dimensions.
239 For other external objects, the scale is a multiplier, where 1 (the
241 default) represents 100% (i.e. no change).
242 If the object to be placed depends on a coordinate transformation (e.g.
244 rotation or skew), first create a content object using "graphics", then
245 call "object" in PDF::API2::Content after making the appropriate
246 transformations.
247 annotation
249 my $annotation = $page->annotation();
250 Returns a new PDF::API2::Annotation object.
252
254 See "MIGRATION" in PDF::API2 for an overview.
255 gfx Replace with "graphics".
257 rotate
259 Replace with "rotation".
260 mediabox
262 get_mediabox
263 Replace with "size" if not in a print shop environment or
264 "boundaries" if more complex page boundaries are needed.
265 If using page size aliases (e.g. "letter" or "A4"), check the Page
267 Sizes section to ensure that the alias you're using is still
268 supported (you'll get an error if it isn't).
269 cropbox
271 bleedbox
272 trimbox
273 artbox
274 get_cropbox
275 get_bleedbox
276 get_trimbox
277 get_artbox
278 Replace with "boundaries".
279perl v5.36.0 2023-01-20 PDF::API2::Page(3)