Provided by: libpdf-builder-perl_3.025-1_all 
NAME
PDF::Builder::Page - Methods to interact with individual pages
SYNOPSIS
my $pdf = PDF::Builder->new();
# Add a page to a new or existing PDF
my $page = $pdf->page();
# Set the physical (media) page size
# Set prepress page boundaries, a convenience function for those times when
# it is not necessary to set other prepress (print-related) page boundaries
$page->size('letter'); # by common size name
#$page->size([0, 0, 612, 792]); # by points LLx,LLy, URx,URy
# alternately, can set (or get) 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);
# Create a content object for text
my $text = $page->text();
# Create a content object for drawing shapes
my $canvas = $page->graphics(); # or gfx()
# Now to draw graphics (using $canvas object) and text (using $text object).
# NOTE that everything in the graphics (canvas) object will be laid down on
# the page BEFORE anything in the text object is laid down. That is,
# text will cover graphics, but not vice-versa. This is simply due to
# the order in which the objects were defined.
METHODS
$page = PDF::Builder::Page->new($pdf, $parent, $index)
Returns a page object (called from $pdf->page()).
Page Size Methods
$page->userunit($value)
Sets the User Unit for this one page. See "User Units" in PDF::Builder::Docs for more
information.
$page->mediabox($alias)
$page->mediabox($alias, 'orient' => 'orientation')
$page->mediabox($w,$h)
$page->mediabox($llx,$lly, $urx,$ury)
($llx,$lly, $urx,$ury) = $page->mediabox()
Sets or gets the Media Box for this one page. See "Media Box" in PDF::Builder::Docs
for more information. The method always returns the current bounds (after any set
operation).
($llx,$lly, $urx,$ury) = $page->get_mediabox()
Gets the Media Box corner coordinates based on best estimates or the default. These
are in the order given in a mediabox call (4 coordinates).
This method is Deprecated, and will likely be removed in the future. Use the global
($pdf) or page ($page) mediabox() call with no parameters instead.
$page->cropbox($alias)
$page->cropbox($alias, 'orient' => 'orientation')
$page->cropbox($w,$h)
$page->cropbox($llx,$lly, $urx,$ury)
($llx,$lly, $urx,$ury) = $page->cropbox()
Sets or gets the Crop Box for this one page. See "Crop Box" in PDF::Builder::Docs for
more information. The method always returns the current bounds (after any set
operation).
($llx,$lly, $urx,$ury) = $page->get_cropbox()
Gets the Crop Box based on best estimates or the default.
This method is Deprecated, and will likely be removed in the future. Use the global
($pdf) or page ($page) cropbox() call with no parameters instead.
$page->bleedbox($alias)
$page->bleedbox($alias, 'orient' => 'orientation')
$page->bleedbox($w,$h)
$page->bleedbox($llx,$lly, $urx,$ury)
($llx,$lly, $urx,$ury) = $page->bleedbox()
Sets or gets or gets the Bleed Box for this one page. See "Bleed Box" in
PDF::Builder::Docs for more information. The method always returns the current bounds
(after any set operation).
($llx,$lly, $urx,$ury) = $page->get_bleedbox()
Gets the Bleed Box based on best estimates or the default.
This method is Deprecated, and will likely be removed in the future. Use the global
($pdf) or page ($page) bleedbox() call with no parameters instead.
$page->trimbox($alias)
$page->trimbox($alias, 'orient' => 'orientation')
$page->trimbox($w,$h)
$page->trimbox($llx,$lly, $urx,$ury)
($llx,$lly, $urx,$ury) = $page->trimbox()
Sets or gets the Trim Box for this one page. See "Trim Box" in PDF::Builder::Docs for
more information. The method always returns the current bounds (after any set
operation).
($llx,$lly, $urx,$ury) = $page->get_trimbox()
Gets the Trim Box based on best estimates or the default.
This method is Deprecated, and will likely be removed in the future. Use the global
($pdf) or page ($page) trimbox() call with no parameters instead.
$page->artbox($alias)
$page->artbox($alias, 'orient' => 'orientation')
$page->artbox($w,$h)
$page->artbox($llx,$lly, $urx,$ury)
($llx,$lly, $urx,$ury) = $page->artbox()
Sets or gets the Art Box for this one page. See "Art Box" in PDF::Builder::Docs for
more information. The method always returns the current bounds (after any set
operation).
($llx,$lly, $urx,$ury) = $page->get_artbox()
Gets the Art Box based on best estimates or the default.
This method is Deprecated, and will likely be removed in the future. Use the global
($pdf) or page ($page) artbox() call with no parameters instead.
$page->rotate($deg)
Rotates the page by the given degrees, which must be a multiple of 90. An angle that
is not a multiple of 90 will be rounded to the nearest 90 degrees, with a message.
Note that the rotation angle is clockwise for a positive amount! E.g., a rotation of
+90 (or -270) will have the bottom edge of the paper at the left of the screen. After
rotating the page 180 degrees, "[0, 0]" (originally lower left corner) will be 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.
(This allows you to auto-rotate to landscape without changing the mediabox! There are
other ways to accomplish this end, such as using the "size()" method, which will not
change the coordinate system (move the origin).)
Note that some users have reported problems with using "rotate", that the dimensions
were limited to the smaller of the original height or width. If you experience this,
be sure to check whether you are doing some sort of crop box or other clipping, that
might not rotate as expected with the rest of the page. In other words, you might need
to manually adjust the crop box dimensions.
Do not confuse this "rotate()" call with the graphics context rotation (Content.pm)
"rotate()", which permits any angle, is of opposite direction, and does not shift the
origin!
Alternate name: "rotation"
This has been added for PDF::API2 compatibility.
$page->size($size) # Set
@rectangle = $page->size() # Get
Set the physical page size or return the coordinates of the rectangle enclosing the
physical page size. This is an alternate method provided for compatibility with
PDF::API2.
# Set the physical page (media) size using a common size 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();
See Page Sizes below for possible values. The size method is a convenient shortcut
for setting the PDF's media box when other prepress (print-related) page boundaries
aren't required. It's equivalent to the following:
# Set
$page = $page->boundaries('media' => $size);
# Get
@rectangle = $page->boundaries()->{'media'}->@*;
$page = $page->boundaries(%boundaries)
\%boundaries = $page->boundaries()
Set prepress page boundaries to facilitate printing. Returns the current page
boundaries if called without arguments. This is an alternate method provided for
compatibility with PDF::API2.
# Set
$page->boundaries(
# 13x19 inch physical sheet size
'media' => '13x19',
# sheet content is 11x17 with 0.25" bleed
'bleed' => [0.75 * 72, 0.75 * 72, 12.25 * 72, 18.25 * 72],
# 11x17 final trimmed size
'trim' => 0.25 * 72,
);
# Get
%boundaries = $page->boundaries();
($x1,$y1, $x2,$y2) = $page->boundaries('trim');
The %boundaries hash contains one or more page boundary keys (see Page Boundaries) to
set or replace, each with a corresponding size (see Page Sizes).
If called without arguments, the returned hashref will contain (Get) all five
boundaries. If called with one string argument, it returns the coordinates for the
specified page boundary. If more than one boundary type is given, only the first is
processed, and a warning is given that the remainder are ignored.
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 as defined for PDF, 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 rectangular coordinates. For convenience, PDF::Builder 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 (and others) Metric: 4A0, 2A0, A0 - A6, 4B0, 2B0, and B0 - B6
(and others)
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 representing a reduction (in points) from the next-larger box
For example, a 12" x 18" physical sheet to be trimmed down to an 11" x 17" sheet can
be specified as follows:
# 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 page boundary is assumed to be
centered within 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 absolute (raw) coordinates of the bottom-left and top-right corners of a
rectangle can be specified.
$gfx = $page->gfx(%opts)
$gfx = $page->gfx($prepend)
$gfx = $page->gfx()
Returns a graphics content object, for drawing paths and shapes.
You may specify the "prepend" flag in the old or new way. The old way is to give a
single boolean value (0 false, non-zero true). The new way is to give a hash element
named 'prepend', with the same values.
gfx(boolean_value $prepend)
gfx('prepend' => boolean_value)
If $prepend is true, or the option 'prepend' is given with a true value, the content
will be prepended to the page description (at the beginning of the page's content
stream). Otherwise, it will be appended. The default is false.
gfx('compress' => boolean_value)
You may specify a compression flag saying whether the drawing instructions are to be
compressed. If not given, the default is for the overall PDF compression setting to be
used (on by default).
You may have more than one gfx object. They and text objects will be output as objects
and streams in the order defined, with all actions pertaining to this gfx object
appearing in one stream. However, note that graphics and text objects are not fully
independent of each other: the exit state (linewidth, strokecolor, etc.) of one object
is the entry state of the next object in line to be output, and so on.
If you intermix multiple gfx and text objects on a page, the results may be confusing.
Say you have $gfx1, $text1, $gfx2, and $text2 on your page (created in that order).
PDF::Builder will output all the $gfx1->action calls in one stream, then all the
$text1->action calls in the next stream, and likewise for $gfx2 usage and finally
$text2.
Then it's PDF's turn to confuse you. PDF will process the entire $gfx1 object stream,
accumulating the graphics state to the end of the stream, and using that as the entry
state into $text1. In a similar manner, $gfx2 and $text2 are read, processed, and
rendered. Thus, a change in, say, the dash pattern in the middle of $gfx1, after you
have output some $gfx2, $text1, and $text2 material, may suddenly show up at the
beginning of $text1 (and continue through $gfx2 and $text2)!
It is possible to use multiple graphics objects, to avoid having to change settings
constantly, but you may want to consider resetting all your settings at the first call
to each object, so that you are starting from a known base. This may most easily be
done by using $type->restore() and ->save() just after creating $type:
$text1 = $page->text();
$text1->save();
$grfx1 = $page->gfx();
$grfx1->restore();
$grfx1->save();
$text2 = $page->text();
$text2->restore();
$text2->save();
$grfx2 = $page->gfx();
$grfx1->restore();
Alternate name: "graphics"
This has been added for PDF::API2 compatibility.
$text = $page->text(%opts)
$text = $page->text($prepend)
$text = $page->text()
Returns a text content object, for writing text. See PDF::Builder::Content for
details.
You may specify the "prepend" flag in the old or new way. The old way is to give a
single boolean value (0 false, non-zero true). The new way is to give a hash element
named 'prepend', with the same values.
text(boolean_value $prepend)
text('prepend' => boolean_value)
If $prepend is true, or the option 'prepend' is given with a true value, the content
will be prepended to the page description (at the beginning of the page's content
stream). Otherwise, it will be appended. The default is false.
text('compress' => boolean_value)
You may specify a compression flag saying whether the text content is to be
compressed. If not given, the default is for the overall PDF compression setting to be
used (on by default).
Please see the discussion above in "gfx()" regarding multiple graphics and text
objects on one page, how they are grouped into PDF objects and streams, and the
rendering consequences of running through one entire object at a time, before moving
on to the next.
The text object has many settings and attributes of its own, but shares many with
graphics (gfx), such as strokecolor, fillcolor, linewidth, linedash, and the like.
Thus there is some overlap in attributes, and graphics and text calls can affect each
other.
$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::Builder::Content after making the appropriate transformations.
$ant = $page->annotation()
Returns a new annotation object.
$page->resource($type, $key, $obj)
Adds a resource to the page-inheritance tree.
Example:
$co->resource('Font', $fontkey, $fontobj);
$co->resource('XObject', $imagekey, $imageobj);
$co->resource('Shading', $shadekey, $shadeobj);
$co->resource('ColorSpace', $spacekey, $speceobj);
Note: You only have to add the required resources if they are NOT handled by the
*font*, *image*, *shade* or *space* methods.