PDF::Bu...F::Pages(3)

💖 PDF::Builder::Basic::PDF::Pages(3) 💖

okay so bestie, we're diving into PDF::Builder::Basic::PDF::Pages — it's the PDF pages hierarchical element, which is a very fancy way of saying it's the boss of all the page things. It lives in the User Contributed Perl Documentation section of your man pages, section 3, and it's out here being iconic.

---

🌸 NAME 🌸

PDF::Builder::Basic::PDF::Pages — the PDF pages hierarchical element, fr fr.

It inherits from PDF::Builder::Basic::PDF::Dict, so all that Dict energy is in its bloodline. 💅

---

🦋 DESCRIPTION 🦋

A Pages object is the parent to other pages objects, or to page objects themselves. Think of it like the group chat admin — it's not the messages, it's the one holding the messages together. 👑

---

✨ METHODS ✨

🎀 new

PDF::Builder::Basic::PDF::Pages->new($pdf, $parent)

This creates a new Pages object in a PDF. ✨

Now listen, because this part trips people up: the $parent here is not the file context for the object — it's the parent pages object for these pages. If we're using this class to make a root node, then $parent should point to the file context, which you can identify by it not having a Type of Pages. 🕵️♀️

And $pdf is the file object (or a reference to an array of one file object — that's 3.016 and later — or multiple file objects in earlier versions) in which to create the new Pages object. Slay.

---

🌈 find_page

$p->find_page($page_number)

Returns the given page, using the page count values in the pages tree.

⚠️ Pages start at 0. Zero. Not one. Not me forgetting that every single time. 😭

---

💜 add_page

$p->add_page($page, $page_number)

Inserts the page before the given $page_number.

$page_number can be negative to count backwards from the END of the document — -1 is after the last page. Likewise $page_number can be greater than the number of pages currently in the document, to append. It's giving flexible. 💅

🫶 Heads up though: this method only guarantees to provide a reasonable pages tree if pages are appended or prepended to the document. Pages inserted in the middle of the document may simply be inserted in the appropriate leaf in the pages tree without adding any new branches or leaves, leaving it unbalanced — which means slower performance, but still usable. Not broken, just a little unhinged. 💀

---

🧚 get_pages

@objects = $p->get_pages()

Returns a list of page objects in the document, in page order. In order. Like a well-behaved bestie. ✨

---

🍓 find_prop

$p->find_prop($key)

Searches up through the inheritance tree to find a property (key). Going up, up, up like it's climbing the family tree. 🌳

---

👑 add_font

$p->add_font($pdf, $font)

Creates or edits the resource dictionary at this level in the hierarchy. If the font is already supported — even through the hierarchy — then it is not added. No duplicates here, we don't do that. 🙈

🚨 CAUTION: if this method was used in older releases, the code may have swapped the order of $pdf and $font, requiring ad hoc swapping of parameters in user code, contrary to the POD definition above. Now the code matches the documentation. Periodt. ✅

---

🌸 bbox

$p->bbox($xmin,$ymin, $xmax,$ymax, $param)

$p->bbox($xmin,$ymin, $xmax,$ymax)

Specifies the bounding box for this and all child pages. If the values are identical to those inherited, no change is made. 📦

$param specifies the attribute name so that other 'bounding box'es can be set with this method. Yes, "bounding box'es". We respect the original apostrophe. 💅

---

💖 proc_set

$p->proc_set(@entries)

Ensures that the current resource contains all the entries in the proc_sets listed. If necessary, it creates a local resource dictionary to achieve this. Whatever it takes. 💪

---

⭐ get_top

$p->get_top()

Returns the top of the pages tree. The summit. The main character. 👑

---

and that's the whole page, bestie!! 🦋💖✨

This lil masterpiece is documented in the User Contributed Perl Documentation, built with perl v5.42.0, and dated 2026-01-17. Go forth and nest your pages correctly, no cap. 🫶🎀