PDF::Builder::Outline(3)                   User Contributed Perl Documentation


NAME
       PDF::Builder::Outline - Manage PDF outlines (a.k.a. bookmarks)

       Inherits from PDF::Builder::Basic::PDF::Dict

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

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

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

           Returns a new outline object (called from $outlines->outline()).

           By default, if $parent is omitted, the new bookmark is placed at
           the end of any existing list of bookmarks. Otherwise, it becomes
           the child of the $parent bookmark.

   Examine the Outline Tree
       has_children

           $boolean = $outline->has_children()

           Return true if the current outline item has children (child items).

       count

           $integer = $outline->count()

           Return the number of descendants that are visible when the current
           outline item is open (expanded).

       first

           $child = $outline->first()

           Return the first child of the current outline level, if one exists.

       last

           $child = $outline->last()

           Return the last child of the current outline level, if one exists.

       parent

           $parent = $outline->parent()

           Return the parent of the current item, if not at the top level of
           the outline tree.

       prev

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

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

           Return the previous item of the current level of the outline tree
           ("undef" if already at the first item).

       next

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

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

           Return the next item of the current level of the outline tree
           ("undef" if already at the last item).

   Modify the Outline Tree
       outline

           $child_outline = $parent_outline->outline()

           Returns a new sub-outline (nested outline) added at the end of the
           $parent_outline's children. If there are no existing children,
           create the first one.

       insert_after

           $sibling = $outline->insert_after()

           Add an outline item immediately following the $outline item.

       insert_before

           $sibling = $outline->insert_before()

           Add an outline item immediately preceding the $outline item.

       delete

           $outline->delete()

           Remove the current outline item from the outline tree. If the item
           has any children, they will effectively be deleted as well, since
           they will no longer be linked.

       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
           (hide its children), or 1/true to open (expand) it (make its
           children visible).

       open

           $outline->open()

           Set the status of the outline to open (i.e., expanded).

           This is an alternate method to using is_open(true).

       closed

           $outline->closed()

           Set the status of the outline to closed (i.e., collapsed).

           This is an alternate method to using is_open(false).

   Set Outline Attributes
       title

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

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

           Get/set the title of the outline item.

       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.

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

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

               $outline->dest($name)

           Connect the Outline to a "Named Destination" defined elsewhere, and
           optional positioning as described above.

           Note that PDF::Builder's dest() is not the same (i.e., an alias) as
           PDF::API2's destination(). The argument lists are quite different.

   Destination targets
       uri, url

           $outline->uri($url)

           Defines the outline as launch-url with url $url, typically a web
           page.

           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.

           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()).

           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.

perl v5.42.0                      2026-02-08          PDF::Builder::Outline(3)