PdfDocument
A loaded PDF document. Construct with open.
val doc = PdfDocument.open(bytes) // unencrypted
val doc = PdfDocument.open(bytes, "secret".encodeToByteArray())
println("${doc.pageCount} pages, PDF ${doc.version}")
println(doc.pages[0].extractText())
// Editing returns a writer; the document itself is immutable.
val editor = doc.edit()
editor.setInfo(title = "Reviewed")
val updated: ByteArray = editor.saveIncremental()Holds the raw byte buffer plus the xref table; pages and indirect objects are resolved lazily and cached.
Thread-safe for concurrent reads and rendering after construction: object resolution parses from per-call readers and synchronizes only its caches, so multiple threads may render pages of the same document, including the same page, simultaneously.
Properties
Interactive form (AcroForm) catalog metadata. null when the catalog has no /AcroForm entry. The document carries no interactive form fields.
The scripts of the catalog's /AA dictionary: the five document triggers of ISO 32000-1 §12.6.3, Table 197. Null when the catalog has no /AA.
Article threads (/Threads). Each thread is a reading-order sequence of bead rectangles on pages. Readers use them to jump between columns in a multi-column layout. Empty list when the catalog has no /Threads.
Embedded file attachments. These are typically the document author's supplementary files: source artwork, datasets, XML schemas, etc. Empty list when the document has no /EmbeddedFiles name tree.
The PDF bookmark tree, with every /Outlines field intact (destination, colour, style, open/closed). Top-level entries come from the catalog /Outlines /First chain; empty when the document has no bookmarks.
The document catalog (/Root in the trailer).
Document-level JavaScript scripts from /Names /JavaScript. Map keys are the script names; values are the JS source. Empty when none.
Flattened interactive-form fields (the AcroForm field tree's terminal fields, with inheritable attributes resolved). Empty when the document has no form. Drives form-filling via io.github.yuroyami.kitepdf.writer.PdfEditor.
The most bytes of decoded images that this document keeps, so that an image drawn again, on another page or at another zoom, does not decode again. The image used least recently leaves first, and an image larger than the whole budget is not kept. The default is DEFAULT_IMAGE_CACHE_BUDGET_BYTES; 0 keeps no image. Lower it for a small heap, and call dropDecodedImageCache when the app runs low on memory.
Document /Info dictionary (title, author, dates, …). Returns an empty info object if the trailer has no /Info or it doesn't resolve.
True if open found a working password for an encrypted doc.
True if the document is encrypted.
Tagged-PDF accessibility metadata. null when the document has no /MarkInfo dict, which means it is not tagged.
Format-neutral metadata for KiteDocument viewers: /Info values, falling back to XMP where /Info is silent, plus the catalog /Lang.
The catalog's /OpenAction, run when the document opens (ISO 32000-1 §12.6.2). Null when the document defines none.
Optional Content / layers metadata (read-only). null when the catalog has no /OCProperties.
Format-neutral outline for KiteDocument viewers: bookmarks with each destination resolved to a zero-based page index (null when unresolvable).
Initial page-layout hint (/PageLayout). PageLayout.SinglePage when absent.
Initial UI panel hint (/PageMode). PageMode.UseNone when absent.
Document permissions (ISO 32000-1 §7.6.3.2 Table 22). Always allow-all for unencrypted documents; reflects the /P bit-flags from the security handler otherwise.
The live backing array, zero-copy. Mutating it corrupts lazy object resolution, which is why touching it takes the KiteRawApi opt-in.
Viewer-preferences hints (/ViewerPreferences). Returns PdfViewerPreferences.DEFAULT when the catalog doesn't carry the dict.
Parsed XMP metadata. Extracts the common Dublin Core / Adobe PDF / XMP-basic properties. Falls back to the trailer /Info dict when XMP is absent. Call info explicitly if you need both views.
Raw XMP metadata packet as a UTF-8 string, or null if the catalog has no /Metadata stream (or it doesn't resolve to one).
Functions
Frees every decoded image that this document keeps, for example when the app runs low on memory. An image decodes again when it is next drawn.
Start an immutable incremental-update transaction. Edits are appended to the original bytes (see PdfEditor); this document is never mutated. Editing an encrypted document writes fresh AES IVs, so random is required there and must be backed by the caller's platform CSPRNG. Plain documents do not consume randomness.
Look up a form field by its fully-qualified name; null if not present.
Which page a field is drawn on, counting from zero, or null when no page holds its widget. A field with widgets on several pages reports the first one, which is what a script's field.page reports too.
Resolve a /Dest (on a Link annotation or outline) or /A /D (a GoTo action's destination) to a typed PdfDestination. Accepts any of: an explicit array, a name pointing into the catalog's name-tree, or a dict containing /D (a wrapped destination). Returns null when the destination can't be resolved.
Find needle across the whole document, page by page. The result is a lazy Sequence, so a UI can surface incremental hits while later pages are still being extracted. See PdfPage.search for matching rules.