2026-05-21 22:08 @216.73.216.105 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
NAME
PDF::API2::Page - Methods to interact with individual pages
SYNOPSIS
my $pdf = PDF::API2->new();
# Add a page to a new or existing PDF
my $page = $pdf->page();
# Set the page size
$page->size('letter');
# Set prepress page boundaries
$page->boundaries(media => '12x18', trim => 0.5 * 72);
# Add an image
my $image = $pdf->image('/path/to/file.jpg');
$page->object($image, $x, $y, $w, $h);
# Add textual content
my $text = $page->text();
# Add graphical content (paths and shapes)
my $canvas = $page->graphics();
METHODS
size
# Set the page size using a common name
$page->size('letter');
# Set the page size using coordinates in points (X1, Y1, X2, Y2)
$page->size([0, 0, 612, 792]);
# Get the page coordinates in points
my @rectangle = $page->size();
Set the physical page size (a.k.a. media box) when called with an
argument. See "Page Sizes" below for possible values. Returns the $page
object.
Returns the coordinates of the rectangle enclosing the physical page
size when called without arguments.
The size method is a convenient shortcut for setting the PDF's media box
when print-related page boundaries aren't required. It's equivalent to
the following:
# Set
$page = $page->boundaries(media => $size);
# Get
@rectangle = $page->boundaries->{'media'}->@*;
boundaries
# Set
$page->boundaries(
media => '13x19',
bleed => [0.75 * 72, 0.75 * 72, 12.25 * 72, 18.25 * 72],
trim => 0.25 * 72,
);
# Get
%boundaries = $page->boundaries();
($x1, $y1, $x2, $y2) = $page->boundaries('trim');
Set prepress page boundaries when called with a hash containing one or
more page boundary definitions. Returns the $page object.
Returns the current page boundaries if called without arguments. Returns
the coordinates for the specified page boundary if called with one
argument.
Page Boundaries
PDF defines five page boundaries. When creating PDFs for print shops,
you'll most commonly use just the media box and trim box. Traditional
print shops may also use the bleed box when adding printer's marks and
other information.
* media
The media box defines the boundaries of the physical medium on which
the page is to be printed. It may include any extended area
surrounding the finished page for bleed, printing marks, or other
such purposes. The default value is a US letter page (8.5" x 11").
* crop
The crop box defines the region to which the contents of the page
shall be clipped (cropped) when displayed or printed. The default
value is the page's media box.
This is a historical page boundary. You'll likely want to set the
bleed and/or trim boxes instead.
* bleed
The bleed box defines the region to which the contents of the page
shall be clipped when output in a production environment. This may
include any extra bleed area needed to accommodate the physical
limitations of cutting, folding, and trimming equipment. The actual
printed page (media box) may include printing marks that fall
outside the bleed box. The default value is the page's crop box.
* trim
The trim box defines the intended dimensions of the finished page
after trimming. It may be smaller than the media box to allow for
production-related content, such as printing instructions, cut
marks, or color bars. The default value is the page's crop box.
* art
The art box defines the extent of the page's meaningful content
(including potential white space) as intended by the page's creator.
The default value is the page's crop box.
Page Sizes
PDF page sizes are stored as rectangle coordinates. For convenience,
PDF::API2 also supports a number of aliases and shortcuts that are more
human-friendly.
The following formats are available:
* a standard paper size
$page->boundaries(media => 'A4');
Aliases for the most common paper sizes are built in
(case-insensitive).
US: Letter, Legal, Ledger, Tabloid
Metric: 4A0, 2A0, A0 - A6, 4B0, 2B0, and B0 - B6
* a "WxH" string in inches
$page->boundaries(media => '8.5x11');
Many US paper sizes are commonly identified by their size in inches
rather than by a particular name. These can be passed as strings
with the width and height separated by an "x".
Examples: "4x6", "12x18", "8.5x11"
* a number (in points) representing a reduction from the next-larger
box
# Note: There are 72 points per inch
$page->boundaries(media => '12x18', trim => 0.5 * 72);
# Equivalent
$page->boundaries(media => [0, 0, 12 * 72, 18 * 72],
trim => [0.5 * 72, 0.5 * 72, 11.5 * 72, 17.5 * 72]);
This example shows a 12" x 18" physical sheet that will be reduced
to a final size of 11" x 17" by trimming 0.5" from each edge. The
smaller boundary is assumed to be centered on the larger one.
The "next-larger box" follows this order, stopping at the first
defined value:
art -> trim -> bleed -> media
crop -> media
This option isn't available for the media box since it is by
definition the largest boundary.
* [$width, $height] in points
$page->boundaries(media => [8.5 * 72, 11 * 7.2]);
For other page or boundary sizes, the width and height (in points)
can be given directly as an array.
* [$x1, $y1, $x2, $y2] in points
$page->boundaries(media => [0, 0, 8.5 * 72, 11 * 72]);
Finally, the raw coordinates of the bottom-left and top-right
corners of a rectangle can be specified.
rotation
$page = $page->rotation($degrees);
Rotates the page clockwise when displayed or printed. $degrees must be a
multiple of 90 and may be negative for counter-clockwise rotation.
The coordinate system follows the page rotation. In other words, after
rotating the page 180 degrees, [0, 0] will be in the top right corner of
the page rather than the bottom left, X will increase to the right, and
Y will increase downward.
To create a landscape page without moving the origin, use "size".
graphics
my $canvas = $page->graphics(%options);
Returns a PDF::API2::Content object for drawing paths and shapes.
The following options are available:
* prepend (boolean)
If true, place the drawing at the beginning of the page's content
stream instead of the end.
* compress (boolean)
Manually specify whether the drawing instructions should be
compressed. If unspecified, the PDF's compression setting will be
used, which is on by default.
text
my $text = $page->text(%options);
Returns a PDF::API2::Content object for including textual content.
The options are the same as the "graphics" method.
object
$page = $page->object($object, $x, $y, $scale_x, $scale_y);
Places an image or other external object (a.k.a. XObject) on the page in
the specified location.
For images, $scale_x and $scale_y represent the width and height of the
image on the page in points. If $scale_x is omitted, it will default to
72 pixels per inch. If $scale_y is omitted, the image will be scaled
proportionally based on the image dimensions.
For other external objects, the scale is a multiplier, where 1 (the
default) represents 100% (i.e. no change).
If the object to be placed depends on a coordinate transformation (e.g.
rotation or skew), first create a content object using "graphics", then
call "object" in PDF::API2::Content after making the appropriate
transformations.
annotation
my $annotation = $page->annotation();
Returns a new PDF::API2::Annotation object.
MIGRATION
See "MIGRATION" in PDF::API2 for an overview.
gfx Replace with "graphics".
rotate
Replace with "rotation".
mediabox
get_mediabox
Replace with "size" if not in a print shop environment or
"boundaries" if more complex page boundaries are needed.
If using page size aliases (e.g. "letter" or "A4"), check the Page
Sizes section to ensure that the alias you're using is still
supported (you'll get an error if it isn't).
cropbox
bleedbox
trimbox
artbox
get_cropbox
get_bleedbox
get_trimbox
get_artbox
Replace with "boundaries".
Generated by phpMan Author: Che Dong On Apache Under GNU General Public License - MarkDown Format
2026-05-21 22:08 @216.73.216.105 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)