1PDF::API2::Page(3)    User Contributed Perl Documentation   PDF::API2::Page(3)
2
3
4

NAME

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

SYNOPSIS

9           my $pdf = PDF::API2->new();
10
11           # Add a page to a new or existing PDF
12           my $page = $pdf->page();
13
14           # Set the page size
15           $page->size('letter');
16
17           # Set prepress page boundaries
18           $page->boundaries(media => '12x18', trim => 0.5 * 72);
19
20           # Add an image
21           my $image = $pdf->image('/path/to/file.jpg');
22           $page->object($image, $x, $y, $w, $h);
23
24           # Add textual content
25           my $text = $page->text();
26
27           # Add graphical content (paths and shapes)
28           my $canvas = $page->graphics();
29

METHODS

31   size
32           # Set the page size using a common name
33           $page->size('letter');
34
35           # Set the page size using coordinates in points (X1, Y1, X2, Y2)
36           $page->size([0, 0, 612, 792]);
37
38           # Get the page coordinates in points
39           my @rectangle = $page->size();
40
41       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
45       Returns the coordinates of the rectangle enclosing the physical page
46       size when called without arguments.
47
48       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
52           # Set
53           $page = $page->boundaries(media => $size);
54
55           # Get
56           @rectangle = $page->boundaries->{'media'}->@*;
57
58   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
66           # Get
67           %boundaries = $page->boundaries();
68           ($x1, $y1, $x2, $y2) = $page->boundaries('trim');
69
70       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
74       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
78       Page Boundaries
79
80       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
85       •   media
86
87           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
92       •   crop
93
94           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
98           This is a historical page boundary.  You'll likely want to set the
99           bleed and/or trim boxes instead.
100
101       •   bleed
102
103           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
111       •   trim
112
113           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
118       •   art
119
120           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
124       Page Sizes
125
126       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
130       The following formats are available:
131
132       •   a standard paper size
133
134               $page->boundaries(media => 'A4');
135
136           Aliases for the most common paper sizes are built in (case-
137           insensitive).
138
139           US: Letter, Legal, Ledger, Tabloid
140
141           Metric: 4A0, 2A0, A0 - A6, 4B0, 2B0, and B0 - B6
142
143       •   a "WxH" string in inches
144
145               $page->boundaries(media => '8.5x11');
146
147           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
151           Examples: "4x6", "12x18", "8.5x11"
152
153       •   a number (in points) representing a reduction from the next-larger
154           box
155
156               # Note: There are 72 points per inch
157               $page->boundaries(media => '12x18', trim => 0.5 * 72);
158
159               # 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
163           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
167           The "next-larger box" follows this order, stopping at the first
168           defined value:
169
170               art -> trim -> bleed -> media
171
172               crop -> media
173
174           This option isn't available for the media box since it is by
175           definition the largest boundary.
176
177       •   [$width, $height] in points
178
179               $page->boundaries(media => [8.5 * 72, 11 * 7.2]);
180
181           For other page or boundary sizes, the width and height (in points)
182           can be given directly as an array.
183
184       •   [$x1, $y1, $x2, $y2] in points
185
186               $page->boundaries(media => [0, 0, 8.5 * 72, 11 * 72]);
187
188           Finally, the raw coordinates of the bottom-left and top-right
189           corners of a rectangle can be specified.
190
191   rotation
192           $page = $page->rotation($degrees);
193
194       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
197       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
202       To create a landscape page without moving the origin, use "size".
203
204   graphics
205           my $canvas = $page->graphics(%options);
206
207       Returns a PDF::API2::Content object for drawing paths and shapes.
208
209       The following options are available:
210
211       •   prepend (boolean)
212
213           If true, place the drawing at the beginning of the page's content
214           stream instead of the end.
215
216       •   compress (boolean)
217
218           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
222   text
223           my $text = $page->text(%options);
224
225       Returns a PDF::API2::Content object for including textual content.
226
227       The options are the same as the "graphics" method.
228
229   object
230           $page = $page->object($object, $x, $y, $scale_x, $scale_y);
231
232       Places an image or other external object (a.k.a. XObject) on the page
233       in the specified location.
234
235       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
240       For other external objects, the scale is a multiplier, where 1 (the
241       default) represents 100% (i.e. no change).
242
243       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
248   annotation
249           my $annotation = $page->annotation();
250
251       Returns a new PDF::API2::Annotation object.
252

MIGRATION

254       See "MIGRATION" in PDF::API2 for an overview.
255
256       gfx Replace with "graphics".
257
258       rotate
259           Replace with "rotation".
260
261       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
266           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
270       cropbox
271       bleedbox
272       trimbox
273       artbox
274       get_cropbox
275       get_bleedbox
276       get_trimbox
277       get_artbox
278           Replace with "boundaries".
279
280
281
282perl v5.36.0                      2023-01-20                PDF::API2::Page(3)
Impressum