PDF::Bu...:Outline(3)

💖 PDF::Builder::Outline — manage PDF outlines (a.k.a. bookmarks) 💖

okay bestie, so this is the module that handles outlines for you — and if you've ever called them "bookmarks", same thing, no cap. It inherits from PDF::Builder::Basic::PDF::Dict, which is very giving of it.

---

✨ SYNOPSIS ✨

# Get/create the top-level outline tree
my $outlines = $pdf->outline();

# Add an entry
my $item = $outlines->outline();
$item->title('First Page');
$item->dest($pdf->open_page(1), fit-def);

like. look at that. three lines and you have a bookmark tree. iconic behavior fr fr 🌸

---

🧚 METHODS 🧚

🌟 new

$outline = PDF::Builder::Outline->new($api, $parent)

$outline = PDF::Builder::Outline->new($api)

returns a fresh new outline object — this is the one that gets called from $outlines->outline() under the hood, iykyk.

by default, if you don't pass a $parent, the new bookmark just slides in at the end of whatever list of bookmarks already exists. and if you do hand it a $parent, bestie it becomes the child of that $parent bookmark. choose your fighter 💅

---

🔍 Examine the Outline Tree

🌈 has_children

$boolean = $outline->has_children()

returns true if the current outline item has children (aka child items). is it a parent? vibe check says yes 💖

🌈 count

$integer = $outline->count()

returns the number of descendants that are visible when the current outline item is open (expanded). so like, the ones you can actually see rn, not the ones hiding in the collapsed depths.

🌈 first

$child = $outline->first()

returns the first child of the current outline level, if one exists. if not… well. nothing. sorry bestie 🫶

🌈 last

$child = $outline->last()

returns the last child of the current outline level, if one exists. the final one. the closer. main character of the end of the list ✨

🌈 parent

$parent = $outline->parent()

returns the parent of the current item — unless you're already at the top level of the outline tree, in which case, no parent, you're free, you're unbothered 👑

🌈 prev

$sibling = $outline->prev() # Get

$sibling = $outline->prev(outline_obj) # Set

returns the previous item of the current level of the outline tree. if you're already at the first item it returns undef — nothing before you, you're the beginning, periodt.

🌈 next

$sibling = $outline->next() # Get

$sibling = $outline->next(outline_obj) # Set

returns the next item of the current level of the outline tree. and if you're already at the last item? undef. no more siblings, you've reached the end of the line 💀

---

🛠️ Modify the Outline Tree

🦋 outline

$child_outline = $parent_outline->outline()

returns a new sub-outline (nested outline, we love a hierarchy) added at the end of $parent_outline's children. if there are no existing children, it just creates the first one. no drama, no fuss 💜

🦋 insert_after

$sibling = $outline->insert_after()

adds an outline item immediately following the $outline item. right behind it. shadowing it. respectful though 🎀

🦋 insert_before

$sibling = $outline->insert_before()

adds an outline item immediately preceding the $outline item. cutting the line, but make it cute 💅

🦋 delete

$outline->delete()

removes the current outline item from the outline tree. and here's the thing bestie — if the item has any children, they will effectively be deleted as well, because they will no longer be linked. gone. unlinked. unreachable. so be sure before you do it 😭

🦋 is_open

$boolean = $outline->is_open() # Get

$outline = $outline->is_open($boolean) # Set

get/set whether the outline is expanded (open) or collapsed (closed).

$boolean is 0/false to close (collapse) the outline — which hides its children — or 1/true to open (expand) it, which makes its children visible. simple as that 🫶

🦋 open

$outline->open()

sets the status of the outline to open (i.e., expanded). it's the alternate route to is_open(true). same destination, different path, both slay ✨

🦋 closed

$outline->closed()

sets the status of the outline to closed (i.e., collapsed). the alternate method to is_open(false). and yeah the method is called closed, not close — read it again bestie, i'll wait 🙈

---

🎀 Set Outline Attributes

⭐ title

$title = $outline->title() # Get

$outline = $outline->title($text) # Set

get/set the title of the outline item. the name. the label. the thing people actually click on 💖

⭐ dest

$outline->dest($page_object, %position)

$outline->dest($page_object)

sets the destination page and optional position of the outline.

%position can be any of those listed in "Page Fit Options" in PDF::Builder::Docs — go check that list, it's all there.

"xyz" is the default fit setting, with position (left and top) and zoom the same as the calling page's. lowkey convenient.

$outline->dest($name, %position)

$outline->dest($name)

this version connects the Outline to a "Named Destination" defined elsewhere, with optional positioning as described above.

⚠️ heads up bestie: PDF::Builder's dest() is not the same (i.e., an alias) as PDF::API2's destination(). the argument lists are quite different. do not mix them up, i am begging 🙏

---

🎯 Destination targets

🌸 uri, url

$outline->uri($url)

defines the outline as launch-url with url $url — typically a web page. click and you're on the internet, slay 🌈

alternate name: "url"

either "uri" or "url" may be used; "uri" is for compatibility with PDF::API2.

🌸 launch, file

$outline->launch($file)

defines the outline as launch-file with filepath $file. this is typically a local application or file — like, something on your actual machine 🖥️

alternate name: "file"

either "launch" or "file" may be used; "launch" is for compatibility with PDF::API2.

🌸 pdf, pdf_file, pdfile

$outline->pdf($pdffile, $page_number, %position, %args)

$outline->pdf($pdffile, $page_number)

defines the destination of the outline as a PDF-file with filepath $pdffile, on page $pagenum (default 0), and position %position (same as dest()). pointing at another pdf? yes. go off 📄✨

alternate names: "pdf_file" and "pdfile"

either "pdf" or "pdf_file" (or the older "pdfile") may be used; "pdf" is for compatibility with PDF::API2.

---

💌 ok that's the whole page bestie, you ate that. this was perl v5.42.0, dated 2026-01-17, brought to you by the User Contributed Perl Documentation girlies. mwah, go build some bookmarks 🎀💖✨