Crate gpui_pdf 

PDF viewing for GPUI — a page-virtualized viewer built on the pure-Rust hayro rasterizer (no native libraries, no system-font dependency).

Two layers, use whichever fits:

• Low-level primitives (host-agnostic, pure): parse a PDF once, read page sizes with page_dims, rasterize a page to a gpui::RenderImage with render_page, and compute the on-screen page range with keep_window. Build your own viewer on these.
• A ready component: PdfView — a self-contained gpui entity that owns its document, scroll position, off-thread rendering, and viewport eviction, so an 800-page file stays as light as a one-pager. It also has built-in zoom, page navigation (including a jump-to-page input), and DPI-aware rendering with a host-settable quality multiplier. Construct it inside cx.new and render the Entity<PdfView> like any child view.

let view = cx.new(|cx| {
    PdfView::new(path, Rc::new(PdfStyle::default), Rc::new(|| 1.0), cx)
});
// then `view.clone()` into your element tree; call `view.update(cx, |v, cx|
// v.release(window, cx))` before dropping it (e.g. when its tab closes).

Structs

FormField

One form widget, described for a host UI: where it is, what it takes, and what it currently holds.

Highlight

A highlight to draw on the PDF, located by its quote. The host derives these from its own store (e.g. the markdown blocks that link this PDF) and hands them to the viewer via PdfView::set_highlights; the viewer finds the quote with the text layer and draws a translucent box over each line it spans. (markup feature.)

NormPoint

A point in normalized page coordinates (0..1 of width/height, top-left origin).

NormRect

A rectangle in normalized page coordinates: each component is a fraction (0..1) of the page’s width/height, origin at the top-left. Resolution- and zoom-independent, so a host maps it to the on-screen page rect at paint time.

OutlineItem

One entry in a PDF’s outline, flattened depth-first.

PageText

A page’s extracted text: the runs in draw order, plus a whitespace-stripped, lowercased index for robust quote matching.

PdfLink

A clickable /Link annotation: its rectangle in normalized page coordinates (0..1 of the crop box, top-left origin, matching the rendered image) and target.

PdfStyle

Colors for the PdfView chrome. Map your theme onto this; PdfStyle::default is a neutral dark palette.

PdfView

Construct with PdfView::new inside cx.new; it loads and measures the file off-thread. Render the resulting Entity<PdfView> like any child view. Call release before dropping it (e.g. when its tab closes) to free the atlas textures gpui won’t free on plain drop.

Selection

The result of a drag selection: the selected text (as a single-line quote), which occurrence of that quote on the page it is (so it re-locates unambiguously), and the rects to draw while selecting.

Enums

FieldKind

What kind of input a form field takes.

FitMode

Automatic zoom-to-fit modes — see PdfView::fit_width / PdfView::fit_page.

LinkTarget

Where a clickable PDF link points.

LoadError

Why loading a PDF failed.

PdfEvent

A page-virtualized PDF viewer: a scrollable column of page slots, each sized from the PDF’s page dimensions up front (so the scrollbar is correct for the whole document) but only rasterized while near the viewport. Pages scrolled away are freed — CPU pixel buffer and GPU atlas texture — so memory is bounded by what’s on screen rather than the page count.

Constants

PAGE_WIDTH

Base on-screen page width (points) at zoom 1.0; pages keep their aspect ratio.

Functions

extract_page_text

Extract the text layer of page index (0-based). Runs a non-rasterizing interpret pass — cheaper than rendering, but still parses the page, so a host should cache the result. Returns None if the page doesn’t exist.

form_fields

Every form-field widget in the document, in page order — what a host needs to overlay inputs on the viewer. Pushbuttons (no value) are skipped; an encrypted or unparseable file yields an empty list.

is_pdf

True if a link/image src points at a PDF (by extension, case-insensitive).

keep_window

The inclusive page-index range (start, end) to keep rasterized for the given scroll position: the pages intersecting the viewport, padded by [MARGIN]. Pure (mirrors PdfView’s slot layout) so it’s unit-testable. page_width is the on-screen column width (base × zoom); scroll_y is how far the content is scrolled down (px ≥ 0); viewport_h is the visible height (px).

normalize_form_appearances

Rewrite bytes so every form widget has a directly-renderable appearance stream. Some(fixed) only when something actually changed; None means nothing to do (no forms, already normalized, encrypted, or unparseable) — the caller keeps the original bytes either way.

outline

Extract the document outline (bookmarks), flattened depth-first. Returns an empty vec when the PDF has no /Outlines.

page_dims

Each page’s (width, height) in points — cheap to read (no rasterization), so a viewer can lay out correctly-sized page slots before any page renders.

page_links

Extract the clickable /Link annotations for every page, indexed by page; pages with none get an empty vec. Rotated pages are skipped for now (their annotation rectangles would need rotating to line up with the render).

parse

Parse a PDF’s bytes into a reusable Document. The Document owns the bytes, so the caller can drop its own copy. Returns LoadError::Locked for a password-protected file (retry with parse_with_password).

parse_with_password

Like parse, but supplies a decryption password for an encrypted PDF. Returns LoadError::Locked if the file is password-protected and password is missing or incorrect.

render_page

Rasterize a single page (0-based) of an already-parsed Document at scale (PDF point-size × this) to a BGRA RenderImage composited onto white. Higher scale = sharper but more memory; PdfView picks scale from the display’s pixel ratio, zoom, and quality so pages are crisp without wasting memory.

set_form_value

Set the value of the field named name (fully qualified, as reported by form_fields) and regenerate its appearance so the result renders in any viewer — not just ours. For Text/Choice pass the literal text; for Checkbox/Radio pass an on-state name from FormField::options (or "Off" to clear). Returns the rewritten bytes, or None when nothing matched (unknown/read-only/signature field, encrypted or unparseable file).

Type Aliases

CreateAreaFn

Invoked when the user finishes a box-drag in “area mode”: the page (0-based), the dragged rect in normalized page coordinates, and the label of the picked color. The host stores it and hands it back as a Highlight with region set. (markup feature.)

CreateHighlightFn

Invoked when the user finishes a drag-selection in “highlight mode”: the page (0-based), the selected one-line quote, which occurrence of it on the page, and the label of the picked color (the opaque tag from [set_highlight_palette], for the host to store). The host turns this into a stored note. (markup feature.)

Document

A parsed PDF. Parse once (not per page) — re-parsing a large file for every page is slow and churns the allocator. hayro’s Pdf is Send + Sync (std feature) and caches pages internally, so it’s shared via Arc across the background render tasks.

HighlightClickFn

Invoked with a Highlight’s id when the user clicks it. (markup feature.)

OpenExternalFn

Invoked from the load-failure pane’s “Open in system viewer” button, so the host can hand the file to the OS default app — the viewer itself stays host-agnostic (no process spawning). Set via PdfView::set_on_open_external; without it the pane shows no button.

PdfQualityFn

Supplies the current render-quality multiplier at paint time (1.0 = native DPI; < 1 is faster and softer, > 1 supersamples). Read like PdfStyleFn, so a host setting change (e.g. a Settings slider) re-renders all open viewers — in every window — automatically. Clamped to a sane range internally.

PdfStyleFn

Supplies the current PdfStyle at paint time. Because PdfView is a persistent entity (not rebuilt by its parent each frame), it reads its colors through this closure — returning fresh colors each call lets the viewer follow live theme changes (and differ per window) without the host pushing updates.