PDF::Builder::Page(3)

📦
version 3.028 · 11 versions
, in fedora 44

✨ PDF::Builder::Page ✨

okay so bestie, welcome to PDF::Builder::Page — the module that lets you vibe with one single page at a time. 💖 It's the "Methods to interact with individual pages" situation, and it inherits from PDF::Builder::Basic::PDF::Pages, iykyk.

(also hiii, you're reading the User Contributed Perl Documentation section 3 version of this page, just so you know where you are 🎀)

🦋 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.
⚠️ real talk though: whatever you put in the graphics (canvas) object lands on the page BEFORE anything in the text object. So text covers graphics, never the other way around. Not a bug, not a setting, it's literally just the order the objects got defined in. 🫶

💅 METHODS 💅

new

$page = PDF::Builder::Page->new($pdf, $parent, $index)

Hands you back a page object. ✨ Fair warning: you're normally not out here calling this yourself — it gets called from $pdf->page(). Let the parent do the work, bestie. 💅

Page Size Methods

Page Sizes

okay so here's the tea: PDF page sizes are actually stored as rectangular coordinates. Boring. So PDF::Builder also gives you a bunch of aliases and shortcuts that are way more human-friendly. 🌸 Here's everything you can throw at it:

  • a standard paper size
$page->boundaries('media' => 'A4');

The most common paper sizes are built in as aliases, and they're case-insensitive. 💫

  • US: Letter, Legal, Ledger, Tabloid (and others)
  • Metric: 4A0, 2A0, A0 - A6, 4B0, 2B0, and B0 - B6 (and others)

PDF::Builder::Resource::PaperSizes has the full list if you want to scroll the whole menu. 📜

  • a "WxH" string in inches
$page->boundaries('media' => '8.5x11');

So many US paper sizes get identified by their inches rather than some fancy name, and honestly? Valid. Just pass a string with the width and height split by an "x". Examples: "4x6", "12x18", "8.5x11". 🦋

  • a number representing a reduction (in points) from the next-larger box

Picture this: a 12" x 18" physical sheet that you're trimming down to an 11" x 17" sheet. You'd write it like this:

# 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]);

So this is a 12" x 18" physical sheet getting reduced to a final 11" x 17" by trimming 0.5" off every edge. The smaller page boundary is assumed to be centered inside the larger one. ✨

The "next-larger box" follows this order, and it stops at the first value that's actually defined:

art -> trim -> bleed -> media
crop -> media
💀 heads up: this option isn't available for the media box, because media is, by definition, the biggest boundary. There's nothing bigger to shrink from, bestie.
  • [$width, $height] in points
$page->boundaries('media' => [8.5 * 72, 11 * 7.2]);

For any other page or boundary size, you can hand over the width and height in points directly as an array. 📐

  • [$x1, $y1, $x2, $y2] in points
$page->boundaries('media' => [0, 0, 8.5 * 72, 11 * 72]);

And finally, the raw absolute coordinates of the bottom-left and top-right corners of a rectangle. Fully unhinged, fully valid. 👑

Page Boundaries

PDF defines five page boundaries, and here they are. 🌈 When you're making PDFs for print shops, you'll most commonly use just the media box and the trim box. Traditional print shops may also use the bleed box when they're adding printer's marks and other info. 🖨️

media

The media box defines the boundaries of the physical medium the page is going to be printed on. It may include any extended area surrounding the finished page for bleed, printing marks, or other such purposes. Default value is whatever PDF defines as default: a US letter page (8.5" x 11").

⚠️ CAUTION: most printers can not print all the way to the edge of the physical medium (paper, etc.). Some space around the edges gets reserved for pinch rollers and friends to move the paper without smearing toner or ink all over the place. 😭

crop

The crop box defines the region the page contents get clipped (cropped) to when displayed or printed. Default value is the page's media box. This one 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 the page contents get clipped to when output in a production environment. It 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. 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 like printing instructions, cut marks, or color bars. 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 whoever created the page. Default value is the page's crop box. 🎨

userunit

$page->userunit($value)

Sets the User Unit for this one page. Want the full lore? See "User Units" in PDF::Builder::Docs. 📏

mediabox

$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. 💖 And plot twist: the method always returns the current bounds, even after a set operation. So you always get an answer back.

cropbox

$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. Same deal as before: it always returns the current bounds (after any set operation). ✨

bleedbox

$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 the Bleed Box for this one page. See "Bleed Box" in PDF::Builder::Docs. And yes, you guessed it — always returns the current bounds (after any set operation). 💅

trimbox

$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. You know the drill: always returns the current bounds (after any set operation). 🎀

artbox

$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. Forever and always: returns the current bounds (after any set operation). 🌈

size

$page->size($size)  # Set

@rectangle = $page->size()  # Get

Sets the physical page size, or returns the coordinates of the rectangle enclosing the physical page size. This is an alternate method that exists 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();

Check out Page Sizes above for the possible values. The size method is a convenient little shortcut for setting the PDF's media box when you don't need other prepress (print-related) page boundaries. It's exactly equivalent to this:

# Set
$page = $page->boundaries('media' => $size);

# Get
@rectangle = $page->boundaries()->{'media'}->@*;

boundaries

$page = $page->boundaries(%boundaries)

%boundaries = $page->boundaries()

Sets prepress page boundaries to make printing easier. If you call it with no arguments, it returns the current page boundaries. Another alternate method, again for compatibility with PDF::API2. 💫

# Set
%boundaries = $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,
);

The %boundaries hash holds one or more page boundary keys (peep Page Boundaries) to set or replace, each with a matching size (peep Page Sizes). The resulting boundaries hash gets returned to you. ✨

# Get
%boundaries = $page->boundaries();
($x1,$y1, $x2,$y2) = $page->boundaries('trim');

So: called with no arguments, the returned hashref contains (Get) all five boundaries. Called with one string argument, it returns the coordinates for that specified page boundary — media, crop, bleed, trim, or art. And if you hand it more than one boundary type? Only the first one gets processed, and you get a warning that the rest are being ignored. 🙈

Page Operation Methods

gfx, graphics

$gfx = $page->gfx(%opts)

$gfx = $page->gfx($prepend)

$gfx = $page->gfx()

Returns a graphics content object, for drawing paths and shapes. 🎨✨

Okay bestie, so you can drop the prepend flag either the old-school way or the new-school way, and honestly both are valid 💅

  • the old way — just hand over a single boolean value (0 = false, non-zero = true)
  • the new way — hand over a hash element called 'prepend', with the exact same values
gfx(boolean_value $prepend)
gfx('prepend' => boolean_value)

So if $prepend is true, or the 'prepend' option is given a true value, your content gets prepended to the page description — like, at the very beginning of the page's content stream. Otherwise? It gets appended. The default is false, no cap.

gfx('compress' => boolean_value)

You can also set a compression flag that says whether the drawing instructions get compressed. If you don't say anything, it just uses the overall PDF compression setting (which is on by default, slay). ✨

Now here's where it gets spicy — you can have more than one gfx object. Those and text objects all get output as objects and streams in the order they were defined, with everything pertaining to a given gfx object landing in one stream. But graphics and text objects are not fully independent of each other, and this is the part everyone trips on: the exit state of one object (linewidth, strokecolor, etc.) becomes the entry state of the next object in line to be output. And so on, and so on. 😭

So if you intermix multiple gfx and text objects on one page, the results can be straight-up confusing. Say you've got $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, then the same 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 all the way to the end of the stream, and use that as the entry state into $text1. Same deal for $gfx2 and $text2 — read, processed, rendered. So a change in, say, the dash pattern in the middle of $gfx1, after you've already output some $gfx2, $text1, and $text2 material, may suddenly pop up at the beginning of $text1 (and keep going through $gfx2 and $text2)! 💀

It is possible to use multiple graphics objects to dodge constantly changing settings, but lowkey you might wanna consider resetting all your settings at the first call to each object, so you're starting from a known base. The easiest way to do that is $type->restore() and ->save() right 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();

Generally you'll want to define the graphics object first, then the text object after it. That sets the order the streams get rendered in (graphics first), which is usually what you want if you're setting a background color, or you've got other graphics you wanna overlay text over. Sometimes though, you might wanna overlay text with graphics — in that case you'd either define the objects text-then-graphics, or define a second graphics stream to lay over the text. Most of the time it genuinely doesn't matter which comes first (text and graphics don't interact or overlay), but either way: be aware of states carried over from the end of one stream into the next. 👑

Alternate name: "graphics" — added for PDF::API2 compatibility, iykyk.

🌸 text 🌸

$text = $page->text(%opts)

$text = $page->text($prepend)

$text = $page->text()

Returns a text content object, for writing text. Peep PDF::Builder::Content for all the deets.

You can drop the "prepend" flag the old way or the new way, same as before. Old way = a single boolean value (0 false, non-zero true). New way = a hash element named 'prepend', same values.

text(boolean_value $prepend)
text('prepend' => boolean_value)

If $prepend is true, or the 'prepend' option comes in true, the content gets prepended to the page description (beginning of the page's content stream). Otherwise it's appended. Default is false.

text('compress' => boolean_value)

You can set a compression flag saying whether the text content gets compressed. If you don't, the default is the overall PDF compression setting to be used (on by default). 🎀

Please, please go read the discussion up in gfx() about multiple graphics and text objects on one page — how they get grouped into PDF objects and streams, and the rendering consequences of running through one whole object (stream) at a time before moving on to the next. Even if you've only got one graphics and one text stream, the order you define them in has consequences for how text overlays graphics or vice-versa. Fr fr.

The text object has a ton of its own settings and attributes, but it shares many with graphics (gfx) — stuff like strokecolor, fillcolor, linewidth, linedash, and the like. So yeah, there's overlap in attributes, and graphics and text calls can affect each other. Watch out. 🦋

🔄 rotate, rotation 🔄

$page->rotate($deg)

Rotates the page by the given degrees, which must be a multiple of 90. An angle that isn't a multiple of 90 gets rounded to the nearest 90 degrees, with a message.

Heads up: the rotation angle is clockwise for a positive amount! So a rotation of +90 (or -270) puts the bottom edge of the paper at the left of the screen. After rotating the page 180 degrees, "[0, 0]" (originally the lower left corner) will be in the top right corner of the page instead of the bottom left. X increases to the right, and Y increases downward.

(This lets you auto-rotate to landscape without changing the mediabox! There are other ways to get the same result, like using the size() method, which won't change the coordinate system or move the origin. 😌)

Ngl, some users have reported problems with "rotate" — that dimensions were limited to the smaller of the original height or width. If that happens to you, check whether you're 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 allows any angle, goes in the opposite direction, and does not shift the origin! 💅

Alternate name: "rotation" — added for PDF::API2 compatibility.

🖼️ 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 at the specified location.

If $x and $y are omitted, the object goes at "[0, 0]".

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 defaults to 72 pixels per inch. If $scale_y is omitted, the image gets scaled proportionally based on the image dimensions.

For other external objects, the scale is a multiplier, where 1 (the default) means 100% — i.e. no change.

If the object you're placing depends on a coordinate transformation (like rotation or skew), first create a content object using "graphics", then call "object" in PDF::Builder::Content after making the appropriate transformations. ✨

🎀 annotation 🎀

$ant = $page->annotation()

Returns a new annotation object. Cute, simple, iconic.

🌈 resource 🌈

$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.

And that's a wrap on part 2, bestie 🫶 this was generated from perl v5.42.0, dated 2026-01-17, for PDF::Builder::Page(3). Go forth and rotate responsibly. 💖

📦 where this page comes from