NAME

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

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

       $outline = PDF::Builder::Outline->new($api, $parent, $prev)
           Returns a new outline object (called from $outlines->outline()).

   Examine the Outline Tree
       $boolean = $outline->has_children()
           Return true if the current outline item has children (child items).

       $integer = $outline->count()
           Return the number of descendants that are visible when the current outline item is
           open (expanded).

       $child = $outline->first()
           Return the first child of the current outline level, if one exists.

       $child = $outline->last()
           Return the last child of the current outline level, if one exists.

       $parent = $outline->parent()
           Return the parent of the current item, if not at the top level of the outline tree.

       $sibling = $outline->prev()
           Return the previous item of the current level of the outline tree.

       $sibling = $outline->next()
           Return the next item of the current level of the outline tree.

   Modify the Outline Tree
       $child_outline = $parent_outline->outline()
           Returns a new sub-outline (nested outline) added at the end of the current outline's
           children.

       $sibling = $outline->insert_after()
           Add an outline item immediately following the current item.

       $sibling = $outline->insert_before()
           Add an outline item immediately preceding the current item.

       $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.

       $boolean = $outline->is_open() # Get
       $outline = $outline->is_open($boolean) # Set
           Get/set whether the outline is expanded (open) or collapsed (closed).

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

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

       $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 = $outline->title() # Get
       $outline = $outline->title($text) # Set
           Get/set the title of the outline item.

       $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.

   Destination targets
       $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.

       $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.

       $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.