PDF::AP...::Pages(3)

💖 PDF::API2::Basic::PDF::Pages 💖

okay bestie, so this is PDF::API2::Basic::PDF::Pages from the User Contributed Perl Documentation — yes, the real one, the 3 section, we're doing the deep lore today ✨

---

🌸 NAME 🌸

PDF::API2::Basic::PDF::Pages — the low-level page tree object. Like, the actual scaffolding of your PDF. Not the glow-up, the bones. 🦋

---

🎀 DESCRIPTION 🎀

So a Pages object is a parent. That's its whole thing. It's the mom of other pages objects, or of page objects themselves. It's giving family tree but make it PDF. 👑

---

✨ METHODS ✨

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

Okay so this one creates a brand-new Pages object inside a PDF. But heads up, bestie — the plot twist: $parent here is not the file context for the object. Nope. It's the parent pages object for this pages. Different thing. Stay with me. 🙈

BUT — if you're using this class to create a root node, then $parent should point to the file context. And how do you clock the file context? It's the one that doesn't have a Type of Pages. iykyk 💅

And $pdf? That's the file object — or, plot twist number two, a reference to an array of file objects — in which you're creating the new Pages object. 🌈

---

💅 $p->find_page($page_number)

Hands you back the page you asked for, using the page count values in the pages tree. And here's the thing that trips everyone up: pages start at 0. Zero-indexed, no cap. Page one is page zero. Periodt. 🎀

---

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

Slides your page in before the given $page_number. Cute.

Now the fun part — $page_number can be negative to count from the END of the document. So -1 is after the last page. Wild, I know, but that's literally what it says.

Likewise, $page_number can be greater than the number of pages currently in the document, which is how you append. Go off, append. 🦋

---

🎀 @objects = $p->get_pages()

Returns a list of page objects in the document, in page order. All of them. In order. Beautiful. No notes. ⭐

---

🧚 $p->find_prop($key)

Searches up through the inheritance tree to find a property. Climbing the family tree looking for your roots, basically. 🌸

---

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

Creates — or edits — the resource dictionary at this level in the hierarchy.

Important caveat though: if the font is already supported even through the hierarchy, then it is not added. It's already there, bestie, we're not duplicating. 🫶

---

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

Specifies the bounding box for this and all child pages. Everyone inherits. Generational bounding box. 👑

Sneaky detail: if the values are identical to those inherited, then no change is made. Nothing to see here, move along. ✨

And $param? It specifies the attribute name — so that other 'bounding box'es can be set with this method. Yeah, other bounding boxes. Plural. Versatile king. 💅

---

🍓 $p->proc_set(@entries)

Makes sure the current resource contains all the entries in the proc_sets you listed.

And if it doesn't? If necessary, it creates a local resource dictionary to make that happen. Doing it itself because nobody else will. main character energy fr fr. 🔥

---

⭐ $p->get_top

Returns the top of the pages tree. The tippy top. The crown. The root of it all. 🌸

---

Reminder bestie: pages start at 0, $parent is not the file context (unless you're making a root node, in which case it is, because it's the one without a Type of Pages), and -1 in add_page means after the last page. These are the details that eat people alive. 😭

---

aaaand that's the whole page, bestie. This lil doc shipped in perl v5.42.0 and got dated 2025-09-01 — so go forth and build your page tree, you absolute icon. obsessed with you. bye! 🎀✨💖🦋🌸👑