Pdfium Impl Navigation

pdfium-impl-navigation

This skill covers reading the navigation structure of a PDF with pdfium-render. Four cooperating concepts:

• Bookmarks: the document outline tree (the table of contents a viewer shows in its side panel).
• Links: the clickable rectangles on a page.
• Destinations: a target page plus a view setting (where a link or bookmark jumps to).
• Actions: what happens on interaction (jump to a page, open a URL, launch a file).

The whole cluster is read-oriented. PdfDocument::bookmarks() returns an immutable reference and there is no bookmarks_mut(); this skill reads the navigation structure rather than building it.

Default API surface: pdfium-render 0.9.x. Version notes for 0.8.x are inline and collected in the version table.

Quick reference

Full signatures: references/methods.md. Working code: references/examples.md.

Bookmarks: the outline tree

document.bookmarks() returns &PdfBookmarks. The collection has four methods: root(), find_first_by_title(), find_all_by_title(), and iter().

PdfBookmarks has NO len() and NO is_empty() method. To count bookmarks, use bookmarks.iter().count(). To test for an empty outline, use bookmarks.root().is_none().

bookmarks.iter() walks the entire tree depth-first in prefix order, which is the simplest way to read every entry. For structural traversal, a PdfBookmark exposes parent(), first_child(), next_sibling(), children_len(), and three sub-iterators: iter_siblings(), iter_direct_children(), and iter_all_descendants().

A bookmark's target is reached two ways. bookmark.destination() returns an Option<PdfDestination> for a direct page target. bookmark.action() returns an Option<PdfAction> for an action-based target (a URL, a remote file). ALWAYS check both: a bookmark that opens a URL has an action() but no destination().

Links: the clickable rectangles on a page

page.links() returns &PdfPageLinks. page.links_mut() returns a mutable reference; both exist since 0.7.31.

PdfPageLinks has len(), is_empty(), get(), first(), last(), iter(), as_range(), as_range_inclusive(), and link_at_point(x, y) for hit-testing a coordinate.

A PdfLink exposes exactly three methods: action(), destination(), and rect(). The clickable area is rect(), returning Result<PdfRect, PdfiumError>.

The rect-not-bounds trap

The link's clickable area method is named rect(), not bounds(), and it returns PdfRect, not PdfQuadPoints. This differs from PdfPageObject::bounds(), which returns PdfQuadPoints since 0.8.28. ALWAYS call link.rect(). There is no link.bounds().

Destinations: target page plus view

A PdfDestination has exactly two methods:

• page_index() returns Result<PdfPageIndex, PdfiumError>, the zero-based target page index.
• view_settings() returns Result<PdfDestinationViewSettings, PdfiumError>, the zoom and fit mode the viewer applies on arrival.

The view-settings-not-view trap

In pdfium-render 0.8.10 this method was named view(). It was RENAMED to view_settings(). The current 0.8.x and 0.9.x API has only view_settings(). ALWAYS call view_settings(). Treat view() as a removed older name.

PdfDestinationViewSettings is an enum with 9 variants: Unknown, SpecificCoordinatesAndZoom, FitPageToWindow, FitPageHorizontallyToWindow, FitPageVerticallyToWindow, FitPageToRectangle, FitBoundsToWindow, FitBoundsHorizontallyToWindow, and FitBoundsVerticallyToWindow. Several carry data (coordinates, a zoom factor, a rectangle). See references/methods.md.

Actions: what happens on interaction

PdfAction is an enum with 6 variants. ALWAYS match it with an Unsupported arm and a catch-all:

PdfAction methods: action_type() returns a PdfActionType (6 variants: GoToDestinationInSameDocument, GoToDestinationInRemoteDocument, GoToDestinationInEmbeddedDocument, Launch, Uri, Unsupported), is_supported(), is_unsupported(), and five as_*_action() narrowing methods, each with a _mut companion.

Verified data accessors on the subtype structs:

• PdfActionUri::uri() returns Result<String, PdfiumError>, the target URL (read as 7-bit ASCII). Added 0.7.31.
• PdfActionLocalDestination::destination() returns Result<PdfDestination, PdfiumError>.
• PdfActionLaunch, PdfActionRemoteDestination, PdfActionEmbeddedDestination, and PdfActionUnsupported have NO public methods of their own in 0.8.x or 0.9.x. Do not expect a file_path() or similar accessor.

PdfActionCommon is a real public trait but is currently empty (reserved for future expansion). Do not look for methods on it.

PdfAction has NO bookmark() or link() back-reference method. An action does not know which link or bookmark owns it.

Decision tree

Reading PDF navigation structure?
|
+-- Need the table of contents / outline?
|     -> document.bookmarks().iter(), read title() + destination()
|
+-- Need a specific bookmark by name?
|     -> bookmarks.find_first_by_title("...") or find_all_by_title("...")
|
+-- Need every clickable link on a page?
|     -> page.links().iter()
|
+-- Need the link under a known x,y coordinate?
|     -> page.links().link_at_point(x, y)
|
+-- Have a link or bookmark, need where it goes?
|     -> try .destination() for a direct page target
|     -> try .action() and match the PdfAction enum
|
+-- Have a PdfAction, need the URL?
      -> match PdfActionType::Uri, narrow with as_uri_action(), call uri()

Pattern: traverse the bookmark tree

use pdfium_render::prelude::*;

let pdfium = Pdfium::default();
let document = pdfium.load_pdf_from_file("input.pdf", None)?;

for bookmark in document.bookmarks().iter() {
    let title = bookmark.title().unwrap_or_default();
    match bookmark.destination() {
        Some(destination) => {
            let page = destination.page_index()?;
            println!("{title} -> page {page}");
        }
        None => println!("{title} -> (action or no target)"),
    }
}

bookmarks.iter() is depth-first prefix order, so the output mirrors the visual outline.

Pattern: read links and branch on action type

for (page_index, page) in document.pages().iter().enumerate() {
    for link in page.links().iter() {
        let Some(action) = link.action() else { continue };
        match action.action_type() {
            PdfActionType::Uri => {
                if let Some(uri) = action.as_uri_action() {
                    println!("page {page_index}: URL {}", uri.uri()?);
                }
            }
            PdfActionType::GoToDestinationInSameDocument => {
                if let Some(local) = action.as_local_destination_action() {
                    let target = local.destination()?.page_index()?;
                    println!("page {page_index}: jump to page {target}");
                }
            }
            other => println!("page {page_index}: {other:?}"),
        }
    }
}

Version table

Critical rules

• ALWAYS call link.rect() for a link's clickable area. There is no link.bounds(), and the type is PdfRect, not PdfQuadPoints.
• ALWAYS call destination.view_settings(). The old name view() was removed.
• NEVER call len() or is_empty() on PdfBookmarks; those methods do not exist. Use iter().count() and root().is_none().
• ALWAYS match PdfAction and PdfActionType with an Unsupported arm and a catch-all _.
• ALWAYS check both destination() and action() to resolve where a bookmark or link leads. A URL bookmark has an action() but no destination().
• NEVER expect methods on PdfActionLaunch, PdfActionRemoteDestination, PdfActionEmbeddedDestination, PdfActionUnsupported, or the empty PdfActionCommon trait. Verified data accessors exist only on PdfActionUri and PdfActionLocalDestination.
• NEVER pin PdfPageIndex to u16; it became c_int in 0.9.0.

Companion skills

• pdfium-syntax-pages for pages(), len(), and reaching a PdfPage.
• pdfium-impl-document-features for metadata, attachments, permissions.
• pdfium-core-coordinates for PdfRect, PdfPoints, PdfPageIndex.
• pdfium-impl-annotations for Widget and link annotations on a page.
• pdfium-errors-runtime for PdfiumError handling.

Reference files

• references/methods.md : complete API signatures with version annotations.
• references/examples.md : working, verified Rust examples.
• references/anti-patterns.md : real failures, why they happen, and the fix.