KiteDocument
A parsed document from any handler: the fz_document equivalent. Lets a viewer treat a io.github.yuroyami.kitepdf.PdfDocument and an io.github.yuroyami.kitepdf.epub.EpubDocument uniformly.
A document is CHAPTERS of pages. A PDF is one chapter. A reflowable EPUB is one chapter per spine item, and a chapter can be laid out without the ones before it, so a reader opens at chapter 20 without paginating chapters 0 to 19 first. Everything about chapters has a one-chapter default, so a handler that does not need them implements nothing.
Two ways to address a page:
KiteLocation (chapter, page): always available for a ready chapter.
a global index into pages: only once every earlier chapter is ready.
A viewer that wants to show a page before the whole document is laid out must work in locations. pageCount and pages lay out everything.
Properties
How many chapters. One for a document that does not have them.
True once every chapter is laid out, so global page indices are final.
Pages laid out so far. Equals pageCount once isComplete.
Title/authors/language; defaults empty so third-party implementors don't break.
The navigation tree (PDF bookmarks / EPUB table of contents) with destinations resolved to page indices; empty when the document has none.
Functions
A re-flow-proof position for location. Prepares its chapter first.
True when chapter is laid out and its pages can be read.
The chapters on screen now. A document that drops laid-out chapters to stay within a memory budget keeps these, so a tap, a long press or a draw on the screen does not wait for a layout. A viewer calls it each time the chapters on screen change. Does nothing by default.
Where bookmark sits in the current layout. Prepares that chapter, and only that chapter. Clamps into range rather than failing.
The location of a global page index, or null when the index is out of range or not reached yet.
The page at location. Prepares its chapter first.
Pages in chapter. Prepares it first. Zero for an empty chapter.
The global index of location, or null while an earlier chapter is not ready yet and the index cannot be known.
Lays out chapter if it is not ready yet. The one expensive call.
prepareChapter, with checkpoint called between two steps of the layout, so that a caller on a thread that must keep drawing frames, as in a browser, can suspend there and go on after a frame. A document that lays a chapter out in steps calls it; by default the chapter is prepared at once. No lock is held across a checkpoint, so two callers for one chapter may each lay it out, and the first to finish keeps its pages. A wrapper that overrides prepareChapter should override this one too: by delegation sends it straight to the wrapped document.