KiteDocViewState
Observable state + control surface of a KiteDocView.
Everything a navigation/zoom widget needs lives here, so widgets are just composables that take a KiteDocViewState. Place them inside the viewport (via KiteDocView's overlay slot), next to it, or anywhere else in your tree.
Reads (currentPage, zoom, panOffset…) are snapshot-state backed and recompose their readers automatically. Navigation suspends until finished; calls made before the state is attached to a composed KiteDocView are remembered and applied on attach.
The suspend calls, such as scrollTo and animateZoomTo, may come from any thread. They run on the thread of the KiteDocView that shows the state, so do not block that thread to wait for one. The calls that do not suspend, such as setZoom and clearSelection, belong on the main thread.
Constructors
Opens at a saved reading position instead of a page number.
Opens at position, including the continuous layout's pixel offset.
Properties
Where the reader is. Always exact, even mid-layout, unlike a global page number which cannot exist until the pages before it are counted.
The slot the viewport rests on: the snapped page in paged mode, the page nearest the viewport centre in continuous mode.
The leading visible page and how many pixels have scrolled past its leading edge. Unlike currentLocation, this anchors the viewport edge, not its centre, so a continuous viewport can be restored without a jump. Reads observe scroll state. Paged and single-page layouts report zero. See KiteScrollPosition for the layout and zoom boundaries.
Explicitly named alias of currentPage; includes chapter placeholders.
The form field that has the caret, or null when none has. A viewer shows the platform keyboard while it is set, and what the reader types goes through the document's scripts.
App-owned highlights, each with its own fill colour and its own optional margin marker. Painted over the page after searchHighlights, in list order, so later entries win where they overlap. Clear by assigning an empty list.
True once every chapter is laid out and pageCount is final.
True while the view scrolls or turns a page, by a gesture or by an animation, and false with no viewer. Reads observe scroll state, so a snapshotFlow can wait for the view to settle before it counts currentLocation as a place the reader went to, and something that turns pages for the reader can hold off while the reader moves the view.
True while text selection owns the pointer, and while the selection it produced is still on screen.
True once zoomed in beyond the minimum (with a small epsilon). A double tap from here goes back to the minimum. Whether a drag pans or turns the page depends on whether the zoomed page overflows the viewport, not on this flag, so a range that does not start at 1 still routes the gestures by what shows (#398).
Pages laid out so far. While a book is still paginating this grows; show it as an approximate total until isComplete.
Fires on every selection change, including clearing (null).
Search hits to paint as translucent quads over their pages (colour: KiteDocViewColors.searchHighlight). Feed it from PdfDocument.search, EpubDocument.search or KiteStructuredText.search (quads are display-space, as both produce); clear it by assigning an empty list.
The active text selection, or null. Set by the long-press-drag gesture, and by a mouse press and drag on text; observe via snapshot reads or onSelectionChange. The viewer never touches the clipboard itself. Read KiteTextSelection.text and copy in the app (see the sample's selection actions). On a desktop, bind Ctrl or Cmd with C to that copy.
The bounds of selection in viewport pixels, under the current zoom and pan, or null without a selection or while its page has no place on screen. It reads snapshot state, so a menu placed by it follows the page as it moves (#408).
True only while the finger is still down on the long-press drag that is building the selection; false the moment it lifts.
Current zoom factor. 1 = fit. Bounded by KiteZoomSpec.minZoom/maxZoom.
Functions
Animates to slot page (coerced into range).
Animates to slot. Slots include chapter placeholders.
Commits the field that has the caret, as leaving it does, and returns once the document's scripts have finished with it and with every call the viewer made to them before.
A position to save now and reopen with later. Survives a font size, page size or margin change: hand it to rememberKiteDocViewState.
hitTestDisplay run backwards for a rectangle: rect, in the display space of the page pageIndex, to the viewport pixels it is painted at under the current zoom and pan. Null while that page has no place in the layout: a paged layout places only its current page.
The topmost app-owned highlight under a viewport tap, or null on unmarked paper. Uses the same display-space geometry as painting, including page rotation, zoom and pan. Search results are intentionally excluded: only highlights belong to the host's marks.
Maps a viewport point (the space gesture callbacks like onTap report in) to the page under it, or null when it lands on background/spacing.
Maps a viewport point to the page under it, in the page's display space: points from the top-left corner of the page as it is shown, y down, with its rotation applied, whatever the format. Null when the point lands on background or spacing.
The real page in slot, or null for a placeholder or an out-of-range slot. Reads only the published strip: it never lays out a chapter (#340).
hitTest run backwards for a rectangle: rect, in the page space of the page pageIndex, such as the rectangle of a PDF annotation, to the viewport pixels it is painted at. Null while that page has no place in the layout. See displayRectToViewport.
How the raster of the page in slot pageIndex stands: loading, ready or failed, or null while that page is not on screen. A host can show a failed page with a retry button in its pagePlaceholder. A page that failed keeps the last bitmap it had, and retryPage renders it again. Rasterized mode only: a Vectorized page draws on every frame.
The previous page in reading order, crossing back a chapter if needed and skipping empty ones.
Restores a page and scroll offset. Continuous layouts apply position's offset on their scroll axis; the other layouts navigate to its page. Calls before composition are retained for the initial list measurement.
Jumps to a saved reading position, laying out only its chapter.
Jumps to location, laying out its chapter first if needed.
Jumps to slot page (coerced into range) without animation. See scrollToSlot.
Jumps to slot without animation. Slots include chapter placeholders.
Sets zoom immediately, clamped to the active KiteZoomSpec range. A zoom that is not a finite number, such as a fit ratio of 0 / 0 taken before layout, is ignored (#338).
The exact published slot of location, or null while that page is unavailable. Unlike navigation, this never substitutes a placeholder or lays out a chapter.