PDF::API2::Page - Methods to interact with individual pages
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();
# 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'}->@*;
# 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.
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.
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.
$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.
my $canvas = $page->graphics(%options);
Returns a the PDF::API2::Content manpage 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.
my $text = $page->text(%options);
Returns a the PDF::API2::Content manpage object for including textual content.
The options are the same as the graphics method.
$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 the PDF::API2::Content manpage after making the appropriate transformations.
my $annotation = $page->annotation();
Returns a new the PDF::API2::Annotation manpage object.
See MIGRATION in the PDF::API2 manpage 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.
|