Sponsoring The Perl Toolchain Summit 2025: Help make this important event another success Learn more

 / 
PDF-Builder-3.026
River stage one • 2 direct dependents • 2 total dependents
/ PDF::Builder::Outline

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

new


            

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

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

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

    Return the previous item of the current level of the outline tree.

next


            

              
              
$sibling = $outline->next()

    Return the next item of the current level of the outline tree.

Modify the Outline Tree

outline


            

              
              
$child_outline = $parent_outline->outline()

    Returns a new sub-outline (nested outline) added at the end of the current outline's children.

insert_after


            

              
              
$sibling = $outline->insert_after()

    Add an outline item immediately following the current item.

insert_before


            

              
              
$sibling = $outline->insert_before()

    Add an outline item immediately preceding the current 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).

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.

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.