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 prepress page boundaries when called with a hash containing one or
71 more page boundary definitions. Returns the $page object.
72 Returns the current page boundaries if called without arguments.
74 Returns the coordinates for the specified page boundary if called with
75 one argument.
76 Page Boundaries
78 PDF defines five page boundaries. When creating PDFs for print shops,
80 you'll most commonly use just the media box and trim box. Traditional
81 print shops may also use the bleed box when adding printer's marks and
82 other information.
83 • media
85 The media box defines the boundaries of the physical medium on
87 which the page is to be printed. It may include any extended area
88 surrounding the finished page for bleed, printing marks, or other
89 such purposes. The default value is a US letter page (8.5" x 11").
90 • crop
92 The crop box defines the region to which the contents of the page
94 shall be clipped (cropped) when displayed or printed. The default
95 value is the page's media box.
96 This is a historical page boundary. You'll likely want to set the
98 bleed and/or trim boxes instead.
99 • bleed
101 The bleed box defines the region to which the contents of the page
103 shall be clipped when output in a production environment. This may
104 include any extra bleed area needed to accommodate the physical
105 limitations of cutting, folding, and trimming equipment. The
106 actual printed page (media box) may include printing marks that
107 fall outside the bleed box. The default value is the page's crop
108 box.
109 • trim
111 The trim box defines the intended dimensions of the finished page
113 after trimming. It may be smaller than the media box to allow for
114 production-related content, such as printing instructions, cut
115 marks, or color bars. The default value is the page's crop box.
116 • art
118 The art box defines the extent of the page's meaningful content
120 (including potential white space) as intended by the page's
121 creator. The default value is the page's crop box.
122 Page Sizes
124 PDF page sizes are stored as rectangle coordinates. For convenience,
126 PDF::API2 also supports a number of aliases and shortcuts that are more
127 human-friendly.
128 The following formats are available:
130 • a standard paper size
132 $page->boundaries(media => 'A4');
134 Aliases for the most common paper sizes are built in (case-
136 insensitive).
137 US: Letter, Legal, Ledger, Tabloid
139 Metric: 4A0, 2A0, A0 - A6, 4B0, 2B0, and B0 - B6
141 • a "WxH" string in inches
143 $page->boundaries(media => '8.5x11');
145 Many US paper sizes are commonly identified by their size in inches
147 rather than by a particular name. These can be passed as strings
148 with the width and height separated by an "x".
149 Examples: "4x6", "12x18", "8.5x11"
151 • a number (in points) representing a reduction from the next-larger
153 box
154 # Note: There are 72 points per inch
156 $page->boundaries(media => '12x18', trim => 0.5 * 72);
157 # Equivalent
159 $page->boundaries(media => [0, 0, 12 * 72, 18 * 72],
160 trim => [0.5 * 72, 0.5 * 72, 11.5 * 72, 17.5 * 72]);
161 This example shows a 12" x 18" physical sheet that will be reduced
163 to a final size of 11" x 17" by trimming 0.5" from each edge. The
164 smaller boundary is assumed to be centered on the larger one.
165 The "next-larger box" follows this order, stopping at the first
167 defined value:
168 art -> trim -> bleed -> media
170 crop -> media
172 This option isn't available for the media box since it is by
174 definition the largest boundary.
175 • [$width, $height] in points
177 $page->boundaries(media => [8.5 * 72, 11 * 7.2]);
179 For other page or boundary sizes, the width and height (in points)
181 can be given directly as an array.
182 • [$x1, $y1, $x2, $y2] in points
184 $page->boundaries(media => [0, 0, 8.5 * 72, 11 * 72]);
186 Finally, the raw coordinates of the bottom-left and top-right
188 corners of a rectangle can be specified.
189 rotation
191 $page = $page->rotation($degrees);
192 Rotates the page clockwise when displayed or printed. $degrees must be
194 a multiple of 90 and may be negative for counter-clockwise rotation.
195 The coordinate system follows the page rotation. In other words, after
197 rotating the page 180 degrees, [0, 0] will be in the top right corner
198 of the page rather than the bottom left, X will increase to the right,
199 and Y will increase downward.
200 To create a landscape page without moving the origin, use "size".
202 graphics
204 my $canvas = $page->graphics(%options);
205 Returns a PDF::API2::Content object for drawing paths and shapes.
207 The following options are available:
209 • prepend (boolean)
211 If true, place the drawing at the beginning of the page's content
213 stream instead of the end.
214 • compress (boolean)
216 Manually specify whether the drawing instructions should be
218 compressed. If unspecified, the PDF's compression setting will be
219 used, which is on by default.
220 text
222 my $text = $page->text(%options);
223 Returns a PDF::API2::Content object for including textual content.
225 The options are the same as the "graphics" method.
227 object
229 $page = $page->object($object, $x, $y, $scale_x, $scale_y);
230 Places an image or other external object (a.k.a. XObject) on the page
232 in the specified location.
233 For images, $scale_x and $scale_y represent the width and height of the
235 image on the page in points. If $scale_x is omitted, it will default
236 to 72 pixels per inch. If $scale_y is omitted, the image will be
237 scaled proportionally based on the image dimensions.
238 For other external objects, the scale is a multiplier, where 1 (the
240 default) represents 100% (i.e. no change).
241 If the object to be placed depends on a coordinate transformation (e.g.
243 rotation or skew), first create a content object using "graphics", then
244 call "object" in PDF::API2::Content after making the appropriate
245 transformations.
246 annotation
248 my $annotation = $page->annotation();
249 Returns a new PDF::API2::Annotation object.
251
253 See "MIGRATION" in PDF::API2 for an overview.
254 gfx Replace with "graphics".
256 rotate
258 Replace with "rotation".
259 mediabox
261 get_mediabox
262 Replace with "size" if not in a print shop environment or
263 "boundaries" if more complex page boundaries are needed.
264 If using page size aliases (e.g. "letter" or "A4"), check the Page
266 Sizes section to ensure that the alias you're using is still
267 supported (you'll get an error if it isn't).
268 cropbox
270 bleedbox
271 trimbox
272 artbox
273 get_cropbox
274 get_bleedbox
275 get_trimbox
276 get_artbox
277 Replace with "boundaries".
278perl v5.34.0 2022-01-21 PDF::API2::Page(3)