KiteDocView
THE KitePDF viewer composable. It draws a KiteDocument, so a PDF and an EPUB go through the same code path, the same gestures and the same widgets.
// Simple: whole document, vertical continuous scroll.
KiteDocView(rememberKiteDocViewState(doc), Modifier.fillMaxSize())
// Full control: horizontal pager, custom zoom, HUD overlay.
val state = rememberKiteDocViewState(doc)
KiteDocView(
state = state,
layout = KiteDocLayout.Paged(Orientation.Horizontal),
zoomSpec = KiteZoomSpec(maxZoom = 6f),
overlay = { s ->
KiteNavigationControls(s, Modifier.align(Alignment.BottomCenter))
},
)
// …and the same state drives widgets OUTSIDE the viewport too:
KitePageIndicator(state)By default (KiteRenderSpec.Rasterized) pages are vector-rendered into an ImageBitmap per page, size and settled zoom and then drawn as plain images, so scrolling, panning and pinching never redraw the page itself. Switch to KiteRenderSpec.Vectorized for resolution-independent, bitmap-free drawing. See KiteRenderSpec for the per-mode knobs and KiteZoomSpec for gestures.
Parameters
the hoisted control surface. See rememberKiteDocViewState.
continuous strip (any orientation), snap pager (any orientation) or a single fixed page. See KiteDocLayout.
pinch/double-tap/pan behaviour and zoom bounds. Programmatic zoom through KiteDocViewState.setZoom honours the same bounds, so external controls (sliders, loupes) work with gestures fully disabled.
how pages become pixels: KiteRenderSpec.Rasterized (bitmap-cached, with quality/memory/crisp-zoom/hairline knobs) or KiteRenderSpec.Vectorized (live vector draw). See KiteRenderSpec.
page paper + viewport letterbox colours.
gap between pages (continuous gutter / pager spacing). A strip shows the pages of an EPUB roll with no gap, whatever this says (#506).
whether the reader may select text at all. The default, true, is the long-press-to-select behaviour with draggable thumbs. False removes the gesture entirely: no long press selects, no wash is painted, no thumbs appear, and a selection already on screen is dropped. Turn it off for a document shown as a picture, a chart, a scan, a trace, where a text selection means nothing and a stray long press only gets in the way of panning.
gesture scrolling/swiping of the layout itself, the wheel that turns the page of a horizontal paged layout, and the page keys of a keyboard once a press gives the view the focus. Disable to drive paging exclusively through KiteDocViewState (nav buttons).
fires whenever a page finishes a FRESH screen raster: once per page and bitmap size, so again at each settled zoom when crisp zoom is on. It is the bitmap on screen, not an export: it leaves out the form widgets when a form layer draws them (a scripts handler on a PDF), and it never fires in KiteRenderSpec.Vectorized mode (#431). Cache hits from the page-bitmap LRU do not re-fire it. The bitmap is the one the viewer's cache keeps and draws, so treat it as read-only: a host that writes into it changes the page on screen, and one that recycles it breaks the next frame (#705). To export a page, or to get a bitmap of your own, use KitePageRasterizer.rasterize with the form state.
shown in a page's slot until its raster is ready. Defaults to a plain KiteDocViewColors.pageBackground box.
shown in the slot a chapter holds while it is still being laid out. A reflowable EPUB reaches this, and so does a PDF of more than 200 pages for its first frames, while it builds its page list off the main thread. KiteDocLayout.Spread pairs pages across the whole book, so it shows the placeholder until every chapter is laid out. Defaults to an empty page-coloured box.
HUD layer drawn over the viewport; receives state and a BoxScope for alignment. Widgets here float above the pages: KiteNavigationControls, KitePageIndicator, KiteThumbnailStrip or anything of your own.
drawn over each page that the layout composes, in the page's own frame, so it moves and scales with the page. Place an element on a rectangle of the page with KitePageOverlayScope.displayRect or KitePageOverlayScope.pageRect. For an element that keeps its size on screen at any zoom, use overlay and KiteDocViewState.displayRectToViewport instead.
single-tap on the page, reported with the tap position. The tap does not consume pan/swipe, so it coexists with navigation. Typical use is toggling a HUD's visibility. Held back until the double-tap window lapses only when KiteZoomSpec.doubleTapEnabled is on. Taps that land on a link navigate (or go to onLinkTap) instead of reaching this callback.
receives every link the reader taps, in every format, before the viewer acts on it. Return true to keep the viewer from acting, for example after you open a web address or show a note in a popup. Return false, or pass null, and the viewer does what the link asks where it can: it follows a link inside the document, to the place on the page that the link names, turns the page for a PDF link that names NextPage, PrevPage, FirstPage or LastPage, and runs a PDF script link in scripts when that is set. A web or mail address goes to externalLinks, which asks the reader and opens it. Anything else does nothing, and the tap goes on to onTap. KiteDocLayout.SinglePage cannot move, so there a link inside the document goes on to onTap too. A form widget's action that the viewer does not perform, such as a web address or a form submit, comes here as well. See KiteLinkAction for what a link gives.
Convenience entry point: remembers its own state internally. Takes any KiteDocument, so a PdfDocument and an io.github.yuroyami.kitepdf.epub.EpubDocument both go here.
KiteDocView(document = doc, modifier = Modifier.fillMaxSize()) // whole document
KiteDocView(document = doc, page = 0, modifier = Modifier.fillMaxWidth()) // one pageParameters
index of the single page to show, counted over the whole document, or null (default) for the whole document as a continuous vertical scroll. A book that is still laying out shows a placeholder until the chapters before the page are laid out, and an index outside the document shows its nearest page, as KiteDocLayout.SinglePage does.
colour painted behind page content. Ignored when theme is set (the theme owns the paper colour).
optional reading theme: ReaderTheme.Dark for night mode, ReaderTheme.Sepia, or ReaderTheme.Light/null for the author's colours. Applied at render, so switching is instant (no re-layout).
whether the reader may select text. See the state-based KiteDocView for what turning it off removes.