Text::PDF::Pages(3pm)

💖 NAME 💖

Text::PDF::Pages — bestie, it's a PDF pages hierarchical element ✨ and it inherits from Text::PDF::Dict (yes, we're part of the Text::PDF family, it's giving royal lineage 👑).

---

🦋 DESCRIPTION 🦋

Okay so picture this: a Pages object is literally the parent to other pages objects, or to the page objects themselves. It's the momager of the pages tree 💅 no cap.

---

🌸 METHODS 🌸

✨ Text::PDF::Pages->new($pdfs,$parent)

This creates a brand new Pages object, slay 🎀 Now listen, because this trips people up: $parent here is not the file context for the object — it's the parent pages object for this pages. Got it? Okay but wait, there's more: if you're using this class to create a root node, then $parent should point to the file context instead, and you can tell that's the case because it doesn't have a Type of Pages 🫶 And $pdfs? That's the file object (or objects, plural, we love options) in which to create the new Pages object.

---

🌈 $p->out_obj($isnew)

Tells all the files that this thing is destined for that they should output this object come time to output 📢 If this object has no parent, then it must be the root — main character energy honestly. So it sets itself as the root for the files in question and tells it to be output too. And if $isnew is set, then it calls new_obj rather than out_obj to create as a new object in the file ✨

---

🎀 $p->find_page($pnum)

Returns the given page, using the page count values in the pages tree. And heads up bestie: pages start at 0 🔢 (zero-indexed, we're programmers, it's fine)

---

💅 $p->add_page($page, $pnum)

Inserts the page before the given $pnum. And plot twist 😭 $pnum can be -ve to count from the END of the document — so -1 is after the last page. Likewise $pnum can be greater than the number of pages currently in the document, to append 🍓

Okay real talk, 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 💀 To tidy up such a mess, it is best to call $p->rebuild_tree to rebuild the pages tree into something efficient. Do not skip this step, I'm begging 🙈

---

🧚 $root_pages = $p->rebuild_tree([@pglist])

Rebuilds the pages tree to make a nice balanced tree that conforms to Adobe recommendations 🌟 (balanced tree = the vibe check passed). If passed a pglist then the tree is built for that list of pages. And ngl, no check is made of whether the pglist actually contains pages, so that's on you 👀

Returns the top of the tree for insertion in the root object.

---

⭐ @pglist = $p->get_pages

Returns a list of page objects in the document, in page order 📚 obsessed with the ordering honestly.

---

🔥 $p->find_prop($key)

Searches up through the inheritance tree to find a property. Ancestry dot com behaviour, we love to see it ✨

---

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

Creates or edits the resource dictionary at this level in the hierarchy. And if the font is already supported, even through the hierarchy, then it is not added — because why would we duplicate, that's not the move 🫶

---

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

Specifies the bounding box for this and all child pages 📦 If the values are identical to those inherited then no change is made (no unnecessary edits, periodt). And $param specifies the attribute name so that other 'bounding box'es can be set with this method — yes, all the bounding boxes, plural, iconic 💅

---

🌸 $p->proc_set(@entries)

Ensures that the current resource contains all the entries in the proc_sets listed. And if necessary, it creates a local resource dictionary to achieve this ✨ it just does what needs to be done, no drama.

---

🦋 $p->get_top

Returns the top of the pages tree 🌈 (short, sweet, and up top where it belongs)

---

and that's the whole page bestie, you ate 💖

This one's from perl v5.36.0, dated 2022-10-22, and it's the Text::PDF::Pages(3pm) manual — go forth and build your pages tree 🌟