Struct DocumentFlow 

pub struct DocumentFlow { /* private fields */ }

Implementations

impl DocumentFlow

pub fn new() -> Self

Create an empty flow with no content.

After construction the caller typically calls set_viewport and one of the layout_* methods before the first render.

pub fn set_viewport(&mut self, width: f32, height: f32)

Set the visible area dimensions in logical pixels.

The viewport controls:

• Culling: only blocks within the viewport are rendered.
• Selection highlight: multi-line selection extends to the viewport width.
• Layout width (in ContentWidthMode::Auto): text wraps at viewport_width / zoom.

Call this when the widget’s container resizes. A resize by itself does not relayout — re-run layout_full / layout_blocks if the wrap width changed.

pub fn viewport_width(&self) -> f32

Current viewport width in logical pixels.

pub fn viewport_height(&self) -> f32

Current viewport height in logical pixels.

pub fn set_content_width(&mut self, width: f32)

Pin content width at a fixed value, independent of viewport.

Text wraps at this width regardless of how wide the viewport is. Use for page-like (WYSIWYG) layout or documents with an explicit column width. Pass f32::INFINITY for no-wrap mode.

pub fn set_content_width_auto(&mut self)

Reflow content width to follow the viewport (the default).

Text re-wraps on every viewport resize. Standard editor and web-style layout.

pub fn layout_width(&self) -> f32

The effective width used for text layout (line wrapping, table columns, etc.).

In ContentWidthMode::Auto, equals viewport_width / zoom so that text reflows to fit the zoomed viewport. In ContentWidthMode::Fixed, equals the set value (zoom only magnifies the rendered output).

pub fn content_width_mode(&self) -> ContentWidthMode

The currently configured content-width mode.

pub fn set_scroll_offset(&mut self, offset: f32)

Set the vertical scroll offset in logical pixels from the top of the document. Affects culling and screen-space y coordinates in the rendered frame.

pub fn scroll_offset(&self) -> f32

Current vertical scroll offset.

pub fn set_render_window(&mut self, window: Option<(f32, f32)>)

Restrict render culling to the content-space band [top, top + height] instead of the default [scroll_offset, scroll_offset + viewport_height].

This affects only which blocks / lines / decorations are emitted into the frame — glyph screen positions, hit-testing and caret geometry all still key off scroll_offset and are unchanged. It exists for an editor laid out at its full document height inside an outer ScrollArea (“bastard mode”): its own viewport spans the whole document (so the viewport-derived window culls nothing) and scroll_offset stays 0 (the ancestor scrolls it by translation), so the true visible band must be supplied from the ancestor clip. Pass None (the default) to restore the viewport-derived window.

pub fn render_window(&self) -> Option<(f32, f32)>

The active render window, if any. See set_render_window.

pub fn content_height(&self) -> f32

Total content height after layout, in logical pixels.

pub fn max_content_width(&self) -> f32

Maximum content width across all laid-out lines, in logical pixels. Used for horizontal scrollbar range when wrapping is disabled.

pub fn set_zoom(&mut self, zoom: f32)

Set the display zoom level (PDF-style, no reflow).

Zoom is a pure display transform: layout stays at base size and all screen-space output (glyph quads, decorations, caret rects) is scaled by this factor. Hit-test inputs are inversely scaled.

For browser-style zoom that reflows text, combine with set_content_width(viewport_width / zoom).

Clamped to 0.1..=10.0. Default is 1.0.

pub fn zoom(&self) -> f32

Current display zoom level.

pub fn set_font_scale(&mut self, font_scale: f32)

Set the per-document logical font-scale factor (1.0 = none).

Unlike set_zoom (a post-layout display transform that does not change font metrics), font_scale multiplies the resolved logical font size before shaping. Glyph advances, line heights, and content_height all grow, and text re-wraps — true text magnification, the mechanism behind an app-wide “grow all text” accessibility setting. Takes effect on the next layout_* call. Clamped to 0.1..=10.0.

pub fn font_scale(&self) -> f32

Current logical font-scale factor.

pub fn set_raster_scale(&mut self, raster_scale: f32)

Set the raster densification scale for content drawn under a scale transform (a zoomed scene viewport).

Orthogonal to set_zoom: zoom multiplies the emitted screen coordinates, raster_scale only changes the physical ppem glyphs are rasterized at — layout, metrics, and screen rects are identical at every raster scale, so no relayout is needed after changing it. The next render rasterizes missing glyphs at the new density; old-density entries age out of the atlas via the normal LRU. Scaled rasters (!= 1.0) are unhinted.

Clamped to 0.1..=16.0. Default is 1.0.

pub fn raster_scale(&self) -> f32

Current raster densification scale.

pub fn has_layout(&self) -> bool

Whether any layout_* method has run on this flow at least once. Callers that need to distinguish “never laid out” from “laid out against a stale scale factor” read this alongside layout_dirty_for_scale.

pub fn layout_dirty_for_scale(&self, service: &TextFontService) -> bool

Returns true when the backing TextFontService has had its HiDPI scale factor changed since this flow was last laid out, meaning stored shaped advances and cached ppem values are stale.

Call after every service.set_scale_factor(...) to decide whether to re-run layout_full / layout_blocks before the next render. Returns false for flows that have never been laid out at all (nothing to invalidate).

pub fn layout_full(&mut self, service: &TextFontService, flow: &FlowSnapshot)

Full layout from a text-document FlowSnapshot.

Clears any existing flow state and lays out every element (blocks, tables, frames) from the snapshot in flow order. Call on document load or DocumentReset. For single-block edits prefer relayout_block.

pub fn layout_blocks( &mut self, service: &TextFontService, block_params: Vec<BlockLayoutParams>, )

Lay out a list of blocks from scratch.

Framework-agnostic entry point — the caller assembles BlockLayoutParams directly without going through text-document. Replaces any existing flow state.

pub fn add_block( &mut self, service: &TextFontService, params: &BlockLayoutParams, ) -> Result<(), RelayoutError>

Append a block to the current flow, in O(1).

The block counterpart of add_frame / add_table, and the incremental alternative to re-running layout_blocks after content grows.

Streaming consumers (a log/console view tailing output) need this: a full re-layout is O(N) in the whole document, so appending one line to a 100 000-line buffer costs over a second, while this stays flat at the cost of shaping the one new line, whatever the buffer already holds. See docs/streaming-baseline.md for the measurements.

Appends at the tail: the new block takes the current content_height as its y (margin-collapsed against the previous block, exactly as a bulk layout would place it), so an append-only sequence produces a flow identical to laying the same blocks out in one call.

Invariants

Like relayout_block, this is an incremental operation, so it must not run against a layout shaped at a different HiDPI scale: appending at the current scale while every existing block sits at the old one would leave the flow permanently mixed-scale — and worse, stamping the flow as freshly laid out would clear the very staleness flag (layout_dirty_for_scale) the caller relies on to know it must re-layout. Returns RelayoutError::ScaleDirty instead; the caller re-runs layout_full / layout_blocks.

Unlike relayout_block there is no NoLayout error: appending to an empty flow is how an append-only buffer legitimately starts.

pub fn remove_leading(&mut self, n: usize) -> usize

Drop the first n blocks of the flow, returning how many were removed.

The eviction half of a bounded streaming buffer: pair it with add_block to hold a scrollback cap. Usually O(n) plus one Vec memmove of the survivors — nothing is reshaped. The return value is the count actually evicted, which is less than n when the flow holds fewer leading blocks than that, or a table/frame stops the walk.

Survivors keep their absolute y, so the vacated band at the top becomes empty and content_height does not change: content below never moves, and the viewport stays where the user put it. Callers that want the freed space reclaimed re-run a full layout_blocks.

Only leading top-level blocks are evicted; a leading table or frame stops the walk. Evicting the widest block re-derives max_content_width from the survivors, so the horizontal scroll range stops describing content that is gone.

pub fn layout_window( &mut self, service: &TextFontService, window: &[(usize, BlockLayoutParams)], total_rows: usize, row_height: f32, )

Shape only window — a slice of a much larger uniform-row-height document — placing each row at y = index * row_height.

The memory counterpart of add_block: add_block makes growing a buffer cheap, this makes holding a large one cheap. A resident shaped line costs ~6.5 KB, so a fully laid-out 100 000-line buffer costs ~623 MB, against ~1 MB for a viewport-sized window; render already culls to the viewport, so shaping the rest buys nothing. See docs/streaming-baseline.md.

content_height is derived from total_rows, so the scrollbar spans the whole document even though almost none of it is shaped. Re-call this when the visible range moves; append at the tail with add_block and trim the front with remove_leading while following output, which avoids re-shaping the window on every line.

Invariants

Correct only for genuinely uniform rows: one row = one visual line of exactly row_height — no wrapping, no embedded newlines, no per-row margins, one font size throughout (log/console output, monospaced code). Variable-height or wrapped content must use layout_blocks / layout_full. window must be sorted ascending by index. Both are checked in debug builds.

Rows outside the window are not laid out, so block_visual_info and hit-testing answer only for resident rows; derive off-window geometry arithmetically from row_height.

Behaviour worth knowing

Like layout_blocks, this drops any paint overlay — re-apply spans after re-windowing or the rows render in base colours. Since re-windowing happens on every visible-range change, that re-apply belongs on the scroll path, not in one-off setup.

max_content_width reports the widest row seen so far in this session: not the document’s widest (unknowable without shaping all of it), and deliberately not the window’s widest, which would make the horizontal scrollbar jump on every vertical scroll.

f32 places rows exactly only to 2^24, so past ~840 000 rows at a 20 px row height positions begin quantizing — far beyond the target sizes, but not unbounded.

pub fn set_uniform_extent(&mut self, total_rows: usize, row_height: f32)

Declare the total extent of a uniform-row-height document without shaping anything.

Keeps the scrollbar honest when the row count changes outside the shaped window — a line appended while the user is scrolled away from the tail, where add_block would wrongly shape a row nowhere near the window. Leaves the shaped window untouched.

Only meaningful for a flow driven by layout_window. On a normally laid-out flow this overwrites the accumulated content_height with a fabricated total_rows * row_height that bears no relation to the real content, so the scroll range goes wrong; nothing in the type distinguishes the two, so this is the caller’s contract.

pub fn block_params_for(&self, block: &BlockSnapshot) -> BlockLayoutParams

Convert one document block snapshot into layout params using this flow’s own bridge options — the per-block half of layout_full’s conversion, exposed for the windowed streaming path.

layout_window takes already-built BlockLayoutParams, but only this flow knows the code-block colours, echo char, and justified-hyphenation policy that layout_full folds in through BridgeOptions. A streaming consumer building a window of rows from document snapshots calls this per row, so the windowed and full paths shape a given block identically. The result is a plain value the caller may tint (set a fragment’s foreground_color) before handing the window to layout_window.

pub fn add_frame( &mut self, service: &TextFontService, params: &FrameLayoutParams, )

Append a frame to the current flow. The frame’s position (inline, float, absolute) is carried in params.

pub fn add_table( &mut self, service: &TextFontService, params: &TableLayoutParams, )

Append a table to the current flow.

pub fn relayout_block( &mut self, service: &TextFontService, params: &BlockLayoutParams, ) -> Result<(), RelayoutError>

Relayout a single block after its content or formatting changed.

Re-shapes and re-wraps just that block, then shifts subsequent items if the height changed. Much cheaper than a full layout for single-block edits (typing, format toggles). If the block lives inside a table cell, the row height is re-measured and content below the table shifts.

Invariants

This is an incremental operation and only makes sense when a valid layout is already installed on this flow, laid out against the same HiDPI scale factor the service currently reports. Violations produce a RelayoutError:

• RelayoutError::NoLayout if no layout_* method has run on this flow yet — there is nothing to update.
• RelayoutError::ScaleDirty if the service’s scale factor has changed since the last layout — reshaping a single block would leave neighbors at the old ppem and produce an inconsistent flow. The caller must re-run layout_full / layout_blocks first.

Both conditions are detected structurally from has_layout and layout_dirty_for_scale, so callers that already guard those don’t need to handle the error.

pub fn apply_paint_spans_for( &mut self, spans_by_block: HashMap<usize, Vec<PaintSpan>>, )

Replace the paint-only color overlay for the whole flow, re-derived from the captured base layout. Recolors without reshaping or reflowing — the fast path for search / spell / paint-only syntax highlights. Call render afterward to refresh the GPU frame.

pub fn apply_block_paint_spans( &mut self, block_id: usize, spans: &[PaintSpan], ) -> bool

Apply (or clear) the paint overlay for a single block. Returns false if the block has no captured base (no full layout yet).

pub fn render(&mut self, service: &mut TextFontService) -> &RenderFrame

Render the visible viewport and return the produced frame.

Performs viewport culling, rasterizes any glyphs missing from the atlas into it, and emits glyph quads, image quads, and decoration rectangles. The returned reference borrows both self and service; drop it before the next mutation.

On every call, stale glyphs (unused for ~120 frames) are evicted from the atlas to reclaim slot space.

pub fn render_block_only( &mut self, service: &mut TextFontService, block_id: usize, ) -> &RenderFrame

Incremental render that only re-renders one block’s glyphs.

Reuses cached glyph / decoration data for all other blocks from the last full render(). Call after relayout_block when only one block’s text changed.

Falls back to a full render if the block’s height changed (subsequent glyph positions would be stale), if scroll offset or zoom changed since the last full render, or if the block lives inside a table / frame (those are cached with a different key).

pub fn render_cursor_only( &mut self, service: &mut TextFontService, ) -> &RenderFrame

Lightweight render that only updates cursor/selection decorations.

Reuses the existing glyph quads and images from the last full render(). Use when only the cursor blinked or the selection changed. Falls back to a full render if the scroll offset or zoom changed in the meantime.

pub fn layout_single_line( &mut self, service: &mut TextFontService, text: &str, format: &TextFormat, max_width: Option<f32>, raster_scale: f32, ) -> SingleLineResult

Lay out a single line of text and return GPU-ready glyph quads. Fast path for labels, tooltips, overlays — anything that doesn’t need the full document pipeline.

If max_width is set and the shaped text exceeds it, the output is truncated with an ellipsis character. Glyph quads are positioned with the top-left at (0, 0).

raster_scale densifies glyph bitmaps for content drawn under a scale transform (pass 1.0 for unscaled UI): rasterization happens at size × scale_factor × raster_scale physical pixels while every returned metric and screen rect stays in logical pixels — layout is identical at every raster scale.

pub fn layout_paragraph( &mut self, service: &mut TextFontService, text: &str, format: &TextFormat, max_width: f32, max_lines: Option<usize>, raster_scale: f32, ) -> ParagraphResult

Lay out a multi-line paragraph by wrapping text at max_width.

Multi-line counterpart to layout_single_line. Shapes the input, breaks it at Unicode line-break opportunities (greedy, left-aligned), and rasterizes each line’s glyphs into paragraph-local coordinates starting at (0, 0).

If max_lines is Some(n), at most n lines are emitted and any remainder is silently dropped.

See layout_single_line for the raster_scale contract (pass 1.0 for unscaled UI).

pub fn layout_single_line_markup( &mut self, service: &mut TextFontService, markup: &InlineMarkup, format: &TextFormat, max_width: Option<f32>, raster_scale: f32, ) -> SingleLineResult

Single-line layout with inline markup. See layout_single_line for the plain variant. Accepts parsed [label](url), *italic*, and **bold** spans and annotates the output with per-span bounding rectangles for hit-testing.

pub fn layout_paragraph_markup( &mut self, service: &mut TextFontService, markup: &InlineMarkup, format: &TextFormat, max_width: f32, max_lines: Option<usize>, raster_scale: f32, ) -> ParagraphResult

Paragraph layout with inline markup. Multi-line counterpart to layout_single_line_markup. Emits a LaidOutSpan for every link segment so the caller can hit-test against wrapped links.

pub fn hit_test(&self, x: f32, y: f32) -> Option<HitTestResult>

Map a screen-space point to a document position. Coordinates are relative to the widget’s top-left corner; the scroll offset is applied internally. Returns None when the flow has no content.

pub fn character_geometry( &self, block_id: usize, char_start: usize, char_end: usize, ) -> Vec<CharacterGeometry>

Per-character advance geometry within a laid-out block.

Used by accessibility layers that need to expose character positions to screen readers (AccessKit’s character_positions / character_widths on Role::TextRun). char_start and char_end are block-relative character offsets. Returns one entry per character in the range, with position measured in run-local coordinates (the first character sits at 0).

pub fn caret_rect(&self, position: usize, affinity: CursorAffinity) -> [f32; 4]

Screen-space caret rectangle at a document position with the given affinity, as [x, y, width, height]. Feed this to the platform IME for composition window placement. For drawing the caret itself, use the DecorationKind::Cursor entry in RenderFrame::decorations instead.

Affinity only changes the result at soft-wrap boundaries; at every other position the two affinities return the same rect. CursorAffinity::Downstream matches the pre-affinity behavior.

pub fn set_cursor(&mut self, cursor: &CursorDisplay)

Replace the cursor display with a single cursor.

pub fn set_cursors(&mut self, cursors: &[CursorDisplay])

Replace the cursor display with multiple cursors (multi-caret editing). Each cursor independently generates a caret and optional selection highlight.

pub fn set_selection_color(&mut self, color: [f32; 4])

Set the selection highlight color [r, g, b, a] in 0..=1 space. Default: [0.26, 0.52, 0.96, 0.3] (translucent blue).

pub fn set_cursor_color(&mut self, color: [f32; 4])

Set the caret color [r, g, b, a]. Default: black.

pub fn set_text_color(&mut self, color: [f32; 4])

Set the default text color [r, g, b, a], used when a fragment has no explicit foreground_color. Default: black.

pub fn text_color(&self) -> [f32; 4]

Current default text color.

pub fn set_code_block_background(&mut self, color: [f32; 4])

Set the background painted behind fenced code blocks when the block carries no explicit background_color. Hosts wire this from the active theme so dark / light swaps reach the cards. Default [0.95, 0.95, 0.95, 1.0] (light grey). Affects future layout_full / relayout_block calls; existing layouts keep their already-converted background until they next re-shape.

pub fn code_block_background(&self) -> [f32; 4]

Current code-block background default.

pub fn set_hyphenate_justified(&mut self, enabled: bool)

Auto-hyphenate justified blocks (that don’t set hyphenate explicitly) on future layout_full / relayout_block calls. Enable on prose/rich-text surfaces; leave off for single-line or label widgets. Default false.

pub fn hyphenate_justified(&self) -> bool

Whether justified blocks are auto-hyphenated.

pub fn set_code_block_foreground(&mut self, color: Option<[f32; 4]>)

Set the foreground used for monospaced runs (inline code, fenced code blocks) that carry no explicit foreground_color. None (default) keeps the engine’s text_color. Hosts wire this from the active theme alongside set_code_block_background.

pub fn code_block_foreground(&self) -> Option<[f32; 4]>

Current code-block foreground override.

pub fn set_echo_char(&mut self, echo: Option<char>)

Set the echo / masking character for secure (password) fields.

When Some(c), every character laid out by future layout_full calls is replaced with c before shaping, so the real text never reaches the shaper or the glyph atlas. None (default) lays text out verbatim. One echo char is emitted per source char, preserving char counts so caret / selection / hit-test (all char-indexed) stay aligned with the host document’s positions.

Affects future layout_full calls; existing layouts keep their already-converted glyphs until they next re-shape. The incremental relayout_block path takes pre-converted BlockLayoutParams, so hosts driving that path must thread the same echo char through their own crate::bridge::BridgeOptions.

pub fn echo_char(&self) -> Option<char>

Current echo / masking character, if any.

pub fn block_visual_info(&self, block_id: usize) -> Option<BlockVisualInfo>

Visual position and height of a laid-out block. Returns None if block_id is not in the current layout.

pub fn is_block_in_table(&self, block_id: usize) -> bool

Whether a block lives inside any table cell.

pub fn scroll_to_position(&mut self, position: usize) -> f32

Scroll so that position is visible, placing it roughly one third from the top of the viewport. Returns the new offset. Affinity defaults to Downstream since scroll targeting picks any acceptable line for the position.

pub fn ensure_caret_visible(&mut self) -> Option<f32>

Scroll the minimum amount needed to make the current caret visible. Call after arrow-key / click / typing. Returns Some(new_offset) if the scroll moved, None otherwise.

Trait Implementations

impl Default for DocumentFlow

fn default() -> Self

Returns the “default value” for a type.