EpubDocument
A parsed EPUB, reflowed onto fixed-size pages and rendered through the shared KiteCanvas the PDF engine uses. The second document handler on :kitepdf-core.
Pipeline: ZipReader unzips the OCF container; HtmlParser builds a DOM per spine document; the CSS cascade (StyleResolver, via BoxBuilder) turns each into a LayoutBox tree; BoxLayout resolves the box model (margins, borders, padding, width, inline line breaking with justification) into document-space geometry; Paginator slices it into pages; and EpubPage paints backgrounds, borders, text and images.
Properties
How many times the book's scripts changed a chapter, for every document over the book (#41). A viewer collects it, takes each chapter's page count again, since a change can add or take pages, and draws a page again when its EpubPage.chapterVersion has moved. The document that the scripts run over has the chapter's new pages ready when this moves.
EPUB-specific metadata (title, authors, cover path, reading direction).
True for a pre-paginated (fixed-layout) book, a roll included: one page per chapter, no reflow. A book that mixes fixed and reflowable chapters is false, and renditionOf tells its chapters apart.
Format-neutral title/authors/language for KiteDocument viewers.
Format-neutral outline for KiteDocument viewers: tableOfContents with each href turned into a KiteBookmark target.
How many of the book's remote resources have landed, for every document over the book (#38). A viewer collects it, and draws a page again when that page's EpubPage.remoteVersion has moved.
The scripted chapters, in reading order (#40). Reads the markup of every chapter once.
Page size, font size and margin. Change at runtime via withSettings.
Navigation tree from EPUB 3 nav.xhtml or EPUB 2 toc.ncx (empty if none).
Functions
Fetches the remote resources that size chapter's layout, its fonts and its images without both a width and a height, and waits at most wait for them, for a caller that lays chapter out next (#38). Returns once each has landed or failed, or once wait has passed, and at once without EpubSettings.resourceFetcher or for a chapter the book does not have.
A position that survives a re-flow: the chapter, plus how far into its text the page starts. Change the font size and the same words keep the same offset, even though they move to another page.
A reading position for an internal href (chapter3.xhtml#part-two), built without laying anything out. Resolve it with locate, which prepares that one chapter. This is the cheap half of following a link.
The zip path of chapter's document, as resource takes it, for a host that reads or shows the chapter's own markup (#41). Throws IndexOutOfBoundsException for a chapter the book does not have.
Fetches chapter's remote resources through EpubSettings.resourceFetcher, and returns once each has landed or failed (#38). Only https URLs are fetched (EPUB Reading Systems 3.3, 3.3). Returns at once without a fetcher, or for a chapter the book does not have.
The fragment of chapter's URL without its #, percent-encoded as a URL keeps it, or null before the reader reached one (#550). The chapter's scripts read it as location.hash, and the element it names is the one :target matches.
Whether chapter names a resource outside the book's container by an http or https URL (EPUB 3.3, 3.6): its manifest item has the remote-resources property (EPUB 3.3, D.6.4), or its markup or styles name one for an image, a video poster, a background or a font (#38). Reads the chapter's markup and styles once, and does not lay it out.
Whether chapter is scripted: its manifest item has the scripted property, its document has a script element (#40), or one of its frames shows a document of the book whose scripts run (#528). Without a script handler such a chapter shows what its markup shows, noscript content included; EpubScriptSession, or EpubScriptRunner of kitepdf-javascript, runs its scripts over this library's own layout (#235). Reads the chapter's markup once, and does not lay it out.
Keeps chapters in memory past the budget, so that a gesture or a draw on the screen does not lay a chapter out again on the UI thread (#377). The chapters kept before are dropped again when the budget needs the room.
The element an internal link points at, to show a note, a glossary entry or a citation in place instead of turning the page (#227). Reads the markup of the target's chapter only, and does not lay it out.
Where bookmark sits now. A KiteBookmark.Flow prepares its chapter and no other; a fragment wins over an offset, and both clamp into range rather than failing. A KiteBookmark.Page counts the pages of the whole book, so it lays out the chapters before its page, in order, and clamps to the last page. Save a book's position as a Flow bookmark, as bookmarkOf gives.
Where the element that href names is on screen: the page that shows its first line, and one rectangle per line of it on that page (#36). href is a zip path with a fragment, as EpubOverlayClip.textHref and EpubPage.links give it. An element without text of its own gives its page from the anchor map, with no rectangle. Null when the book has no such chapter or element. Lays out the chapter.
The location of a global index, or null past what is laid out so far.
Marks the element that href names as the one being read aloud, as EPUB Reading Systems 3.3, 9.2.3 asks (#525). The element gets the book's media:active-class, and the root element of its chapter gets the media:playback-active-class while playing. One element of the book holds the mark at a time, so a new call takes it off the last one. Null takes it off. A class that the document gave the element itself stays.
Where chapter's document breaks the rules of XML, or an empty list for a well-formed one and for one that the manifest serves as text/html (#517). EPUB 3.3 requires an XHTML or SVG content document to be well-formed XML, and EPUB Reading Systems 3.3 asks a reading system to treat one that is not as in error. KitePDF still lays out what it can of such a chapter, and KiteDocView reports the errors on the chapter's first page. Reads the chapter's markup once, does not lay it out, and gives at most 20 errors.
chapter's media overlay: the clips of its synchronised narration, in document order, or null when the chapter has none (#36). Parsed on first use, without laying the chapter out. locateFragment finds each clip's text on the page.
The global index of location. Null while any earlier chapter is still unlaid, because the pages before it have not been counted yet.
Zero-based page of an internal href: path.xhtml or path.xhtml#id, zip-root-relative, exactly as EpubPage.links and TocEntry carry them. Null for unknown targets and external URLs; an unknown fragment falls back to its document's first page. This is the navigation half of a link tap: viewers scroll to the returned page.
Lays out one chapter. This is where a book's time goes, so it is also the only thing a reader has to wait for: opening at chapter 20 prepares chapter 20, not chapters 0 to 20.
Lays chapter out a step at a time, each step the parse of the chapter, its box tree, a child of a block in normal flow, or its pages, and calls checkpoint between two (#389). A viewer on a thread that must draw frames suspends in checkpoint once a frame's share of time is used, and the layout goes on after the frame. No lock is held across a checkpoint, so two callers for one chapter may each lay it out; the first to finish publishes its pages, as prepareChapter would.
What a speech engine says for the element that href names: the text of that element in reading order, as EpubPage.readingOrder gives it, with the pronunciation hints of its spans (#525). A reading aloud speaks it for a media overlay clip without audio. An element over several pages gives the items of each page in turn. Images are left out. Empty when the book has no such chapter or element, or the element has no text. Lays out the chapter.
How chapter asks to be shown: the rendition properties of its spine entry, and the book's for the rest. A chapter whose layout is EpubLayout.PRE_PAGINATED is one page at the size it declares, and the others reflow, in the same book (#37).
The bytes of the book's file at path, a zip path as EpubMedia.sources, EpubMedia.poster and EpubLink.href give it, or null when the book has no such file. The feed for a player of the book's media (#29). A fragment after # is ignored. A data: URL, as a page gives one for a resource the document carries in itself, gives the bytes it holds (#514).
The media type that the manifest gives the file at path, or null when it gives none.
Find needle across the book, lazily page by page (a UI can show incremental results). Same matching rules as KiteStructuredText.search: case-insensitive by default, line breaks read as one space, a hyphenated line break joins directly, matches never cross blocks. Each hit carries its chapter/page location in this layout and its global page index. Iterating the sequence prepares the whole book, as pages does.
Makes fragment the fragment of chapter's URL, as a viewer does when the reader goes to a place in the chapter through a link, the table of contents or a bookmark (#550). The element it names becomes the chapter's target. A chapter whose style sheets use :target is laid out again, and chapterChanges moves; any other chapter keeps its pages. A script session takes the new fragment the next time EpubScriptHandler.chapterOpened runs for the chapter, and its scripts get popstate and hashchange then. Lays out the chapter.
Shorthand for withSettings changing only the body font size (points).
Shorthand for withSettings changing only the page margin (points).
Shorthand for withSettings changing the page size, e.g. on resize / rotation.