Struct RichTextEditor 

pub struct RichTextEditor { /* private fields */ }

Implementations

impl RichTextEditor

pub fn read_only(document: TextDocument) -> Self

Construct a read-only rich text viewer bound to document. The document can also back an editable RichTextEditor::editor in another part of the UI — both widgets receive document events independently via on_change subscriptions.

pub fn editor(document: TextDocument) -> Self

Construct an editable rich text editor bound to document. Uses the full editor preset: every command accepted, caret blinks, MultilineTextInput accessibility role, full clipboard support. Multiple editors on the same document share live edits via per-widget on_change subscriptions.

pub fn style(self, style: impl RichTextEditorStyle) -> Self

Per-call style override for the editor chrome (border, padding, focus ring). Replaces the theme-wide style_slots.rich_text_editor and the IntUI default RecipeRichTextEditorStyle for just this editor.

pub fn content_padding(self, amount: f32) -> Self

Set a uniform padding (logical pixels) between the text content and the editor’s chrome. Replaces the style’s default insets (TextInput-style for editable, none for read-only). Use content_padding_symmetric or content_padding_each for per-axis / per-edge control.

pub fn content_padding_symmetric(self, vertical: f32, horizontal: f32) -> Self

Set vertical and horizontal padding (logical pixels) between the text content and the editor’s chrome. Replaces the style’s default insets.

pub fn content_padding_each( self, top: f32, right: f32, bottom: f32, left: f32, ) -> Self

Set per-edge padding (top, right, bottom, left) between the text content and the editor’s chrome. Replaces the style’s default insets.

pub fn content_padding_top(self, top: f32) -> Self

Set just the top inset between the text and the chrome. Leaves the other edges at their previously-set values, defaulting to 0.0 for any edge never touched.

pub fn content_padding_right(self, right: f32) -> Self

Set just the right inset between the text and the chrome.

pub fn content_padding_bottom(self, bottom: f32) -> Self

Set just the bottom inset between the text and the chrome.

pub fn content_padding_left(self, left: f32) -> Self

Set just the left inset between the text and the chrome.

pub fn wrap_mode(self, mode: WrapMode) -> Self

Set the line-wrap mode. WrapMode::Word (the default) wraps at word boundaries; WrapMode::None allows horizontal overflow — pair with .h_scroll_policy(ScrollPolicy::Auto) to expose a scroll bar.

pub fn show_highlights(self, show: bool) -> Self

Whether this view applies the document’s syntax / search / spell highlighting. editor defaults to true; read_only defaults to false (a bare preview). A highlights-off view pulls a clean snapshot (no highlights at all, even metric ones like keyword bold) and ignores paint-only highlight events entirely, so it does zero work when the shared document’s search/spell highlights change.

pub fn annotation_spans(self, spans: Vec<TextAnnotationSpan>) -> Self

Declare the annotations (comment threads) covering ranges of this document, for the accessibility tree only.

Each span becomes a Role::Comment node, and every Role::TextRun it covers points at it through AccessKit’s details relation — the W3C annotations pattern, and the reason a screen reader can say “has comment” and let the user navigate in rather than reciting the thread every time the caret crosses the span.

Painting is a separate concern: a highlight session draws the underline. A highlight carries no text and this carries no colour, so neither is derivable from the other and both are supplied independently.

pub fn set_highlight_mask(&self, mask: HighlightMask)

Set which highlight sessions this view renders, at runtime.

HighlightMask::all shows every session on the document (the default); HighlightMask::only shows a chosen set — which is how a per-editor find banner keeps one pane’s find highlighting out of another pane over the same document. show_highlights(false) still overrides this to nothing.

Forces a re-pull on the next tick so the change is visible immediately.

pub fn typography_defaults(self, defaults: EditorTypographyDefaults) -> Self

Set the initial non-destructive default typography (font family / line height / first-line indent) applied to runs and blocks that carry no explicit override. Applied before the first layout. These are display defaults — they never mutate the bound document (no undo entry, no modified); use set_typography_defaults or EditorHandle::set_typography_defaults to change them after mount. Preferred text size is font_size_scale.

pub fn background(self, color: impl Into<ColorProp>) -> Self

Override the editor background fill. Accepts a Color, a theme role (SurfaceRole::Content, …), or a Signal. Threaded into the active [RichTextEditorStyle]’s make_body, so the common case (“give the editor a surface”) needs no custom style. None uses the style’s default surface.

pub fn selection_color(self, color: impl Into<ColorProp>) -> Self

Override the selection-highlight color. Accepts a Color, theme role, or Signal. Resolved against the active theme on every paint; None uses the engine/theme default.

pub fn caret_color(self, color: impl Into<ColorProp>) -> Self

Override the caret / insertion-point color. Accepts a Color, theme role, or Signal. Resolved against the active theme on every paint; None tracks the theme’s editor_caret role.

pub fn text_color(self, color: impl Into<ColorProp>) -> Self

Override the default text color. Accepts a Color, theme role, or Signal. Resolved against the active theme on every paint; None tracks the theme’s editor_fg role (so dark / light swaps follow automatically). A role or Signal stays reactive; a bare Color pins it.

pub fn v_scroll_policy(self, policy: ScrollPolicy) -> Self

Set the vertical scroll-bar visibility policy.

pub fn h_scroll_policy(self, policy: ScrollPolicy) -> Self

Set the horizontal scroll-bar visibility policy.

pub fn estimate_height_before_layout(self, on: bool) -> Self

Window paint-time culling to the accumulated ancestor clip rather than this editor’s own bounds.

Enable this only for an editor deliberately laid out at its full document height inside an outer ScrollArea (v_scroll_policy(ScrollPolicy::AlwaysOff), no max_lines) — “dubious mode”. Such an editor’s own viewport spans the whole document, so the viewport-derived render cull keeps nothing; this makes it cull to the visible clip band instead, so a huge document only rasterizes the rows on screen. Correct under nested ScrollAreas (the clip is the intersection of all clipping ancestors), and positioning / hit-testing are unaffected.

A normal self-scrolling editor already culls correctly from its own scroll offset and doesn’t need this — leave it off (the default). (The window is computed relative to the editor’s own scroll offset as well, so enabling it on a self-scroller degrades to a correct-but-redundant cull rather than rendering the wrong rows.) Guess this editor’s height from its text until something has laid it out.

content_height() is 0 until layout_full has run, and that waits for the editor to have been through a frame on screen. The zero falls through to the min_lines floor, so an editor that has never been shown claims the same few lines whatever it holds.

For an editor that is on screen that is invisible — it lays out on the first frame and the floor never shows. Turn this on for one that may not be: a row of a long column, most of which is below the fold. There the page’s height is the sum of its rows’ claims, so the scroll extent starts wrong by an order of magnitude and settles a row at a time as the reader arrives — and anything drawing that extent draws the settling.

Off by default, deliberately. The estimate is crude by construction, and an editor that lays out immediately gains nothing from it while every consumer of its first-frame size pays for the guess — including the windowed-render path, whose culling is derived from the editor’s own bounds.

Never a floor: it goes through the same clamp a real height does, so max_lines still caps it and an over-estimate corrects downwards when the layout lands.

pub fn window_to_clip(self, on: bool) -> Self

pub fn scroll_policy(self, policy: ScrollPolicy) -> Self

Set the same scroll-bar visibility policy on both axes.

pub fn follow_caret_in_page(self, follow: bool) -> Self

Whether moving the caret also scrolls any enclosing scroll area to keep the caret on screen — the standard editor “caret stays visible as you type / navigate” behaviour. On by default.

It fires only on a caret move, never on a plain wheel / scrollbar scroll, so the reader can still scroll freely away from the caret and the view holds until the caret next moves. This is what makes an editor that grows to its content with its own scroll suppressed (a flowing page inside an outer ScrollArea) track the caret at all — there the editor’s internal caret-visibility is a no-op, so the enclosing-page follow is the only mechanism that reveals the caret. Pass false for the rare layout where a caret change must never move the surrounding page.

pub fn typewriter(self, anchor: Option<f32>) -> Self

Typewriter scrolling: pin the caret’s line at fraction of the way down the enclosing scroll area — 0.0 at the top, 0.5 centred, 1.0 at the bottom — and let the document scroll under it. None (the default) leaves the ordinary minimal-reveal follow in charge.

Unlike that follow, which only acts once the caret would leave the viewport, a pin re-asserts on every caret move, so the line being written holds a constant height on screen. The classic writing-app feature.

Three behaviours come with it, each of them the consensus answer among the editors that ship this well:

• The pointer stands the pin down. A click places the caret without scrolling, and that position becomes the new resting place; a drag-selection is never interrupted. The next keystroke resumes pinning. Editors that re-centre on pointer input instead have open bugs about the view fighting the mouse and about drag-selection becoming unusable.
• The rendered row is pinned, not the paragraph. Under soft wrap a long paragraph spans several visual rows; pinning the logical line would leave the caret far from the mark.
• Typing snaps, page jumps glide. Animating a pin that updates on every keystroke is what produces the “screen bouncing” complaint other implementations attract.

Requires follow_caret_in_page (on by default). fraction is clamped to 0.0..=1.0.

Near the start of the document the pin gives way to the scroll range — the caret rides above its line until there is room — and near the end it would do the same, which is usually not what you want: pair this with ScrollArea::scroll_past_end(1.0 - fraction) so the last line can still reach the pin.

Takes a plain value, like typography_defaults; to follow a setting live, push changes onto the handle with EditorHandle::set_typewriter.

pub fn overscroll_behavior(self, behavior: OverscrollBehavior) -> Self

Set the wheel scroll-chaining behavior at the editor’s boundary (default OverscrollBehavior::Chain). With Chain, a wheel event the editor can no longer absorb (already at the top/bottom, or content that fits so there is nothing to scroll) is declined so it bubbles to an ancestor scrollable — an editor embedded in a scrolling form/page lets the page scroll once the editor reaches its edge. OverscrollBehavior::Contain keeps the event at the editor instead. Mirrors the identical knob on ScrollArea / ListView / TableView / GridView.

pub fn min_lines(self, n: u32) -> Self

Set a minimum height (in lines of text) for the editor’s intrinsic size.

Setting either min_lines or max_lines switches the editor from greedy sizing (consume the proposal) to intrinsic sizing: size_that_fits returns clamp(content_height, min_lines × line_height, max_lines × line_height) for the dimension the parent leaves unspecified. A parent like VStack proposes unbounded height to non-Expand children, so the editor lands at its intrinsic height — exactly the messenger-composer / chat-input pattern.

A parent that forces the height (e.g. FixedSize) wins regardless. This is intentional and matches Teksilo’s general layout discipline: parents always have the final say on the dimensions they pin.

min_lines measures the visible text area, not the outer widget — min_lines(1) reports a height equal to one line of text at the typesetter’s default font + size, even before the document has any content.

pub fn max_lines(self, n: u32) -> Self

Set a maximum height (in lines of text) for the editor’s intrinsic size. Past this cap the vertical scroll bar absorbs further content growth.

See min_lines for the intrinsic-mode switch and the parent-proposal interaction. max_lines measures the visible text area, not the outer widget.

pub fn follow_text_scale(self, follow: bool) -> Self

Whether this editor’s text grows with the global accessibility text scale (ctx.text_scale). Defaults to true — like every other text surface, the editor magnifies when the user raises the app-wide text size. Pass false for an editor whose font sizes are document content (a WYSIWYG / print-layout editor) that must stay at its true point size regardless of the reader’s UI accessibility setting.

Composed with font_size_scale:
engine.font_scale = (follow ? text_scale : 1.0) × font_size_scale.

pub fn font_size_scale(self, scale: f32) -> Self

Per-editor logical font-size multiplier (1.0 = 100 %). Applied before shaping (same channel as accessibility text scale), so text grows, re-wraps, and stays sharp — the knob for a “Text size” preference. Composed as (follow_text_scale ? ctx.text_scale : 1.0) × font_size_scale. Clamped to [0.1, 10.0]. Use set_font_size_scale after mount.

pub fn context_menu( self, factory: impl Fn(Point, &mut EventContext<'_>) -> Option<Box<dyn Widget>> + 'static, ) -> Self

Replace the built-in right-click context menu with a user-provided factory. Same shape as the framework’s [teksilo_core::widget_builder::ContextMenuFactory]: the closure receives the click position (widget-local) and a full EventContext, and returns Some(menu_widget) to mount or None to decline (falling through to the next ancestor with a factory).

Taking this branch disables the default menu unconditionally. The framework’s show_context_menu_for handles the overlay lifecycle (open at pointer, dismiss on click-outside / Escape, focus-restore on dismiss), so the factory only needs to build the menu content.

This is an inherent method: it shadows the blanket WidgetBuilder::context_menu trait method so the user can chain it directly on the editor. Internally, the factory is installed on the editor’s arena node via the same HandlerSet::context_menu plumbing.

pub fn default_context_menu(self, enabled: bool) -> Self

Enable (default) or disable the widget’s built-in right-click context menu (Cut / Copy / Paste / Paste Unformatted / Select All). When disabled, right-click bubbles past the widget unhandled and context_target_at stays available for applications that render their own menu.

Note: if a user factory is installed via context_menu, that factory wins regardless of this flag — this setter only governs the default menu.

pub fn font_registrar(self, registrar: &dyn FontRegistrar) -> Self

Install a custom font registrar for the fallback private engine. Only has effect when the editor is built outside a windowed teksilo-app — once build() sees a SharedTypesetter in app_state, the private engine is replaced with one that shares the app’s typesetter and this registrar is ignored.

pub fn on_change(self, f: impl Fn() + 'static) -> Self

Install a callback fired once per batch of genuine user content edits (typing, paste, cut, delete) — and not on a programmatic set_djot / set_markdown / set_html load or a document reset, and not while an IME composition (CJK/Kana candidate preview, dead-key accent) is still in progress — only the settled result of a commit fires it. The callback runs on the UI thread during the editor’s frame drain, so it may touch Signals directly — e.g. flip a “dirty” flag or kick a debounced autosave. Replaces any prior change callback on this editor.

For a reactive change token (which also bumps on loads/format-only changes, and on intermediate IME composition steps), observe document_version instead.

pub fn on_text_inserted(self, f: impl Fn(EditSource, usize) + 'static) -> Self

Install a callback fired at each insertion, with the EditSource the text came through and how many characters it was.

Additive to on_change rather than a replacement for it, because they answer different questions. on_change fires once per drain batch and says that the document changed — the right shape for a dirty flag and a debounced autosave, and the wrong one for counting: a batch can carry a typed run and a paste, and after the fact nothing can tell them apart.

Reported where the text is, not derived afterwards. Every site below holds the literal &str about to be inserted, so the count is what was actually written rather than a position delta — which is a different number the moment an insertion replaces a selection.

Fires for text arriving through:

• the keyboard, once per batched run of typed characters;
• an IME commit, once for the settled result and never for the intermediate composition states;
• a paste, of plain text or HTML;
• an assistive technology, through AccessKit’s SetValue and ReplaceSelectedText.

It does not fire for a programmatic set_djot / set_markdown / set_html load, for undo or redo, or for a format-only change: none of those is text arriving.

Replaces any prior callback on this editor. Runs on the UI thread.

pub fn document_version(&self) -> Signal<u64>

Reactive counter that bumps on every document change (content edits, format changes, load events). Starts at 0. Use as a change token to invalidate external caches.

pub fn cursor_position(&self) -> usize

Current cursor position in the document, in character units. Exposed for tests and for applications that need to mirror the caret position externally (status bar, outline panel, etc.).

pub fn cursor_anchor(&self) -> usize

Current selection anchor (equal to cursor_position when there is no selection).

pub fn is_composing(&self) -> bool

true while an IME composition (CJK/Kana candidate preview, dead-key accent) is actively in progress — i.e. on_change is currently suppressed for this editor. Exposed so a caller doing its own while-typing scanning (e.g. an autocorrect feature) can gate its own trigger logic the same way, as defense-in-depth alongside on_change’s own gate.

pub fn cursor_position_signal(&self) -> Signal<usize>

Reactive cursor position signal. Observers fire whenever the cursor moves (arrow keys, click, Home/End, …). Useful for status bars and tests.

pub fn cursor_anchor_signal(&self) -> Signal<usize>

Reactive selection anchor signal.

pub fn has_selection(&self) -> Signal<bool>

Reactive signal — true whenever the editor has a non-empty selection. Updates synchronously after every cursor mutation.

pub fn can_undo(&self) -> Signal<bool>

Reactive undo-availability signal, suitable for toolbar button enable-state. Updated through the frame loop’s debounce drain so toolbars don’t flicker during rapid editing.

pub fn can_redo(&self) -> Signal<bool>

Reactive redo-availability signal.

pub fn caret_char_format(&self) -> TextFormat

Read the current character format at the widget’s caret — the right source for toolbars that mirror bold/italic/underline state.

When a selection is active, the format is read from selection_start() rather than position(). Rationale (matches godot-rich-text’s query_char_format): position() lands at the end of the selection and may fall on a run with different formatting (or past the last character, on an empty virtual element) — a toolbar observing that value would flicker or lie. selection_start() always points at the first character of the selected range, so the reading is stable and matches what a user would expect from “tell me the format of what I have selected.”

pub fn scroll_y(&self) -> Signal<f32>

Reactive vertical scroll offset in logical pixels. Bind to a scroll bar or observe for scroll-position persistence.

pub fn scroll_x(&self) -> Signal<f32>

Reactive horizontal scroll offset in logical pixels. Non-zero only when wrap_mode is WrapMode::None.

pub fn context_target_at(&self, point: Point) -> Option<ContextTarget>

Classify what is under point in the widget’s local coordinates (origin at the widget’s top-left, scroll offset handled internally by the typesetter), for applications building an external context menu. Returns None if the point does not land on any hit region.

pub fn selected_text(&self) -> String

Currently selected text, or an empty string if nothing is selected.

pub fn select_all(&self)

Select the entire document programmatically. Equivalent to the final step of the Ctrl+A ladder; resets the ladder state so a subsequent Ctrl+A starts fresh at level 1.

pub fn deselect(&self)

Clear any current selection.

pub fn insert_text(&self, text: &str)

Insert plain text at the widget’s caret. Replaces any selection.

pub fn insert_html(&self, html: &str)

Insert a fragment parsed from HTML at the widget’s caret. Replaces any selection. Uses text-document’s TextCursor::insert_html, which parses the HTML into a DocumentFragment and inserts it.

pub fn insert_djot(&self, djot: &str)

Insert a fragment parsed from djot at the widget’s caret. Replaces any selection. Uses text-document’s TextCursor::insert_djot, which parses the djot into a DocumentFragment and inserts it — so unlike insert_text, block-level source really does produce new blocks rather than literal newlines in one paragraph.

pub fn insert_block(&self)

Split the current block at the widget’s caret, as pressing Enter does.

pub fn insert_image(&self, name: &str, alt: &str, width: u32, height: u32)

Insert an inline image by logical resource name. width and height are in logical pixels.

alt is the image’s accessible description and its export representation. It is passed straight through rather than defaulted here: the caller is the only layer that knows what the picture shows, and an empty string chosen on its behalf would be an accessibility decision made silently by a widget wrapper.

pub fn delete_selection(&self)

Delete the current selection. No-op when nothing is selected.

pub fn select_word(&self)

Select the word under the widget’s caret.

pub fn select_line(&self)

Select the paragraph / block under the widget’s caret.

pub fn set_caret_position(&self, position: usize)

Move the caret to an absolute character position. Collapses any existing selection (passes [MoveMode::MoveAnchor]). Resets CursorAffinity to Downstream — programmatic placement can’t know whether the caller wanted the upstream side of a wrap boundary, so we default to the same placement that existed before affinity was introduced.

pub fn focused_signal(&self) -> Signal<bool>

Reactive signal — true while this editor holds keyboard focus.

A per-editor find banner (Ctrl+F) targets whichever editor is focused, and the split view has two of them; focused_side only names the Primary/Secondary pane, not which editor. This is the per-editor answer, mirroring has_selection.

pub fn select_range(&self, start: usize, end: usize)

Select the character range [start, end), without collapsing — unlike set_caret_position, which always moves both ends together.

The anchor lands at start and the caret (focus) at end, so the standard selection highlight marks the range and a subsequent replace acts on it. Used to select a search match. (The non-collapsing two-call shape is the same one the AccessKit SetTextSelection handler uses.)

pub fn reveal_range( &self, ctx: &mut EventContext<'_>, start: usize, end: usize, ) -> bool

Scroll the character range [start, end) into view within the enclosing scroll area.

Reveals an arbitrary offset range — the current search match — rather than the live caret the follow-into-view path tracks, and works whether or not the editor is focused.

Returns whether it could. false means this editor has no layout to locate the range in — never laid out, or parked dormant in a tab that is not on screen — and nothing was requested. A caller holding several editors over one document (two split panes; a stream row and that row’s own tab) must try the next rather than take the first as the answer: revealing through a dormant one silently does nothing, which reads as “the viewport does not follow”.

Under typewriter scrolling the range is pinned to the anchor rather than merely revealed, so a search walks matches to the same height the caret writes at instead of leaving them wherever they happened to fall. Because a search jump is a deliberate, screen-sized move, it glides.

pub fn set_bold(&self, enabled: bool)

Apply bold to the current selection (or set the typing bold state when no selection is active). Pairs with is_bold and toggle_bold.

pub fn set_italic(&self, enabled: bool)

Apply italic to the current selection.

pub fn set_underline(&self, enabled: bool)

Apply underline to the current selection.

pub fn set_strikethrough(&self, enabled: bool)

Apply strikethrough to the current selection.

pub fn set_font_size(&self, size: u32)

Set the font size (in points) for the current selection.

pub fn set_font_family(&self, family: impl Into<String>)

Set the font family for the current selection. family must be a name resolvable by the shared typesetter’s font registrar.

pub fn toggle_bold(&self)

Toggle bold on the current selection, reading the current state via caret_char_format. Matches the Ctrl+B keyboard shortcut’s behaviour.

pub fn toggle_italic(&self)

Toggle italic; see toggle_bold.

pub fn toggle_underline(&self)

Toggle underline; see toggle_bold.

pub fn toggle_strikethrough(&self)

Toggle strikethrough; see toggle_bold.

pub fn set_superscript(&self, enabled: bool)

Raise the selection to superscript, or drop it back to the baseline.

pub fn set_subscript(&self, enabled: bool)

Lower the selection to subscript, or drop it back to the baseline.

pub fn set_vertical_alignment(&self, alignment: CharVerticalAlignment)

Set the selection’s vertical alignment directly. Normal is the baseline; Middle exists in the model but has no toolbar affordance.

pub fn get_vertical_alignment(&self) -> CharVerticalAlignment

The caret’s vertical alignment, Normal when unset.

pub fn is_superscript(&self) -> bool

True while the caret sits in superscript text.

pub fn is_subscript(&self) -> bool

True while the caret sits in subscript text.

pub fn toggle_superscript(&self)

Flip superscript on the selection. Turning it on replaces subscript.

pub fn toggle_subscript(&self)

Flip subscript on the selection. Turning it on replaces superscript.

pub fn apply_block_format(&self, fmt: BlockFormat)

Set an arbitrary [BlockFormat] on the caret’s current block. The higher-level helpers set_alignment and set_heading_level go through this method. Exposed so apps that need less common fields (indent, left_margin, line_height, …) don’t have to reach through TextDocument::cursor() and lose the widget’s caret continuity.

pub fn apply_text_format(&self, fmt: TextFormat)

Set an arbitrary [TextFormat] on the current selection. Public counterpart of the private apply_char_format helper, for apps that need fields beyond the dedicated set_bold / set_italic / … setters (e.g. letter_spacing, foreground_color).

pub fn set_alignment(&self, alignment: Alignment)

Set the paragraph alignment for the current block (or the block containing the selection anchor).

pub fn clear_direction(&self)

Unset the block’s direction, handing the paragraph back to automatic detection.

Not the same as setting left-to-right. An explicit direction pins the paragraph and overrides the bidi algorithm, so “clearing” a direction by writing LeftToRight would force Arabic and Hebrew prose to lay out backwards. Only an unset direction lets the text speak for itself.

pub fn set_direction(&self, direction: TextDirection)

Set the base reading direction of the current block.

This is the paragraph direction, not a character property: it decides which edge unaligned text sits against and, more importantly, overrides the bidi algorithm’s first-strong-character guess — which misreads an Arabic paragraph opening with a Latin acronym as left-to-right.

pub fn set_heading_level(&self, level: u8)

Set the heading level of the current block. 0 = plain paragraph; 1..=6 follow the HTML <h1>..<h6> convention.

pub fn insert_list(&self, ordered: bool)

Create a list at the current selection. ordered = true uses decimal numbering; ordered = false uses a bullet disc. Choose a specific style with create_list.

pub fn create_list(&self, style: ListStyle)

Create a list with an explicit [ListStyle]. Exposed for applications that want e.g. lowercase Roman numerals or circle bullets.

pub fn indent(&self)

Increase the nesting depth of the caret’s current list item by one. No-op when the caret is not inside a list. Equivalent to pressing Tab while the caret is on a list item — same behaviour, same nest_current_list_item codepath, exposed for toolbar buttons that do not want to synthesise key events.

pub fn outdent(&self)

Decrease the nesting depth of the caret’s current list item by one. No-op at depth 0 (use Backspace at block-start to exit the list entirely). Toolbar counterpart of Shift+Tab.

pub fn remove_from_list(&self)

Take the caret’s block out of its list entirely, leaving a plain paragraph. No-op when the caret is not inside a list.

outdent deliberately stops at depth 0 — Shift+Tab should not silently destroy the list — so a toolbar that offers “remove list formatting” needs this instead. Backspace at block-start reaches the same codepath from the keyboard.

pub fn is_in_blockquote(&self) -> bool

True iff the caret currently sits inside a blockquote frame at any nesting depth. Used by the toolbar to drive the toggle button’s pressed state and the context menu’s label.

pub fn selection_spans_multiple_frames(&self) -> bool

True iff the current selection spans more than one frame. The “Toggle blockquote” affordance is disabled in this case because wrapping a cross-frame range has no well-defined semantics (different blocks already belong to different containers).

pub fn toggle_blockquote(&self)

Wrap the current block (or selection) in a blockquote, or unwrap the innermost enclosing blockquote if already inside one. No-op (returns silently) when the selection spans multiple frames.

pub fn increase_blockquote_depth(&self)

Equivalent to pressing Tab inside a blockquote — wraps the current block in a deeper nested quote. No-op when the caret is not in a quote.

pub fn decrease_blockquote_depth(&self)

Equivalent to pressing Shift+Tab inside a blockquote — pops one nesting level. At depth 1 unwraps the block to a plain paragraph. No-op when the caret is not in a quote.

pub fn insert_table(&self, rows: usize, columns: usize)

Insert a fresh rows × columns table at the caret. Any existing selection is replaced.

pub fn remove_current_table(&self)

Remove the table containing the caret (if any). No-op when the caret is not inside a table.

pub fn insert_row_above(&self)

Insert a row above the caret’s current table row. No-op when outside a table.

pub fn insert_row_below(&self)

Insert a row below the caret’s current table row.

pub fn insert_column_before(&self)

Insert a column before the caret’s current table column.

pub fn insert_column_after(&self)

Insert a column after the caret’s current table column.

pub fn remove_current_row(&self)

Remove the caret’s current table row.

pub fn remove_current_column(&self)

Remove the caret’s current table column.

pub fn is_in_table(&self) -> bool

Whether the caret is currently inside a table cell.

pub fn is_bold(&self) -> bool

Whether the current selection / typing position is bold.

pub fn is_italic(&self) -> bool

Whether italic.

pub fn set_link(&self, href: &str)

Point the selection at href.

Merges, so formatting already on the range is kept. A collapsed selection formats nothing (as everywhere else), so a caller linking existing text should select it first — see link_at_caret for the range of a link already there.

pub fn clear_link(&self)

Take the link off the selection, leaving its text.

pub fn link_at_caret(&self) -> Option<LinkExtent>

The link the caret is in, and how far it reaches.

Coalesced across the runs an inner mark splits a link into, so the range covers the whole link rather than the piece under the caret. None when the caret is not on a link.

pub fn is_link(&self) -> bool

Whether the caret / selection sits on a link.

pub fn is_underline(&self) -> bool

Whether underline.

pub fn is_strikethrough(&self) -> bool

Whether strikethrough.

pub fn get_heading_level(&self) -> u8

Current heading level (0 = plain paragraph). Reads the caret’s current block format.

pub fn get_alignment(&self) -> Alignment

Current block alignment.

pub fn get_direction(&self) -> Option<TextDirection>

The block’s explicitly-set reading direction, if it has one. None means the bidi algorithm decides from the text.

pub fn undo(&self)

Undo the most recent edit. Mirrors Ctrl+Z. No-op when the undo stack is empty.

pub fn break_undo_merge(&self)

Close the current undo entry, so the next edit starts a new one.

Typing coalesces into word-sized undo steps by looking only at the shape of two edits — adjacent, moments apart. It cannot see that the user did something else in between, somewhere else in the application, that they would remember as a dividing line. A host that knows one was crossed says so here, and the burst before it stops merging with the burst after.

pub fn redo(&self)

Redo the most recently undone edit. Mirrors Ctrl+Y / Ctrl+Shift+Z. No-op when the redo stack is empty.

pub fn begin_edit_block(&self)

Begin grouping subsequent edits into a single undo entry.

Must be paired with end_edit_block. Prefer edit_block, which pairs them for you.

pub fn end_edit_block(&self)

Close the group opened by begin_edit_block.

pub fn edit_block<R>(&self, edits: impl FnOnce() -> R) -> R

Run edits as one undo entry.

The scoped form of begin_edit_block — the block is closed even if edits returns early, which hand-pairing gets wrong eventually.

pub fn set_default_language(&self, language: &str)

Set the document-wide default language (ISO 639-1 code, e.g. “en”, “fr”, “de”). Blocks that don’t set their own language inherit it for hyphenation. Forces a full re-layout so the change takes effect on the next frame. No-op-safe if the document rejects the update.

pub fn default_language(&self) -> String

The document-wide default language (ISO 639-1 code). Defaults to "en" when never set.

pub fn handle(&self) -> EditorHandle

Cheap clone-able handle for external toolbars / palettes — see EditorHandle. The handle shares the editor’s internal state (same Rc<RefCell<…>>), so mutations through the handle are immediately observable through the editor’s reactive signals (and vice versa).

Use this when the caller needs to invoke editor commands from on_activate_fn / ctx.effect closures that outlive the borrow of &editor: RichTextEditor itself is move-only (the optional context-menu factory holds a Box<dyn Fn>, which prevents Clone).

pub fn copy(&self, ctx: &EventContext<'_>)

Copy the current selection to the system clipboard (plain + HTML payloads). No-op when there is no selection.

All clipboard methods take &EventContext because they only need read access — the clipboard handle is looked up via ctx.app_state::<ClipboardHandle>(). A call site that holds &mut EventContext can pass &ctx directly; Rust reborrows automatically.

pub fn cut(&self, ctx: &EventContext<'_>)

Cut the current selection: copy first, then remove.

pub fn paste(&self, ctx: &EventContext<'_>)

Paste from the system clipboard. Prefers an in-process fragment over HTML over plain text — see rich_text/clipboard.rs.

pub fn paste_unformatted(&self, ctx: &EventContext<'_>)

Paste plain text only, stripping any rich payload.

pub fn can_paste(&self, ctx: &EventContext<'_>) -> bool

Whether a paste would insert anything — true iff the system clipboard carries text or an HTML payload (the shapes paste can consume; an HTML-only clipboard pastes fine, so probing plain text alone would under-report).

Clipboard contents are not reactively observable, so this is a point-in-time query rather than a Signal: pass the active EventContext. It probes the clipboard (an X11 HTML probe can round-trip to the selection owner), so a menu / toolbar builder should re-query when the menu opens, not per frame. Returns false when no clipboard backend is installed (headless or feature-off builds) — the same “silently no-op” degradation the paste path itself uses.

pub fn set_font_size_scale(&self, scale: f32)

Set the per-editor logical font-size multiplier (1.0 = 100 %). Composed with accessibility text scale at paint; forces relayout. See font_size_scale.

pub fn get_font_size_scale(&self) -> f32

Current per-editor font-size scale (1.0 = 100 %).

pub fn set_typography_defaults(&self, defaults: EditorTypographyDefaults)

Set the non-destructive default typography at runtime. Re-lays out and schedules a repaint. Never mutates the document.

pub fn get_typography_defaults(&self) -> EditorTypographyDefaults

Current default typography (see typography_defaults).

pub fn set_typewriter(&self, anchor: Option<f32>)

Set the typewriter-scrolling anchor at runtime — see typewriter. None turns pinning off.

Takes effect on the next caret move rather than scrolling immediately: a pin is a follow rule, and re-anchoring the page the instant a setting changes would jump the view under a reader who is not even typing.

pub fn get_typewriter(&self) -> Option<f32>

Current typewriter anchor (see typewriter).

pub fn set_command_filter(&self, filter: CommandFilter)

Narrow (or restore) what the keyboard may do on this mounted editor.

The other three policy dimensions — caret, accessibility role, clipboard surface — describe what kind of surface this is and are fixed at construction; only the command filter is a mode the host can change while the writer is looking at it. Swapping in CommandFilter::ForwardOnly gives a forward-only drafting mode; CommandFilter::All restores ordinary editing.

Every gate reads the filter live — the keyboard dispatch, the default context menu, and drag-and-drop — so this takes effect on the next event without rebuilding the widget.

pub fn command_filter(&self) -> CommandFilter

The filter currently in force (see set_command_filter).

pub fn set_caret_highlight(&self, highlight: Option<CaretHighlight>)

Draw an ambient band behind the sentence — or paragraph — the caret is in.

None (the default) draws nothing and registers no session on the document. The band shows only while this editor has focus, so two panes over one document never band twice, and it disappears when focus leaves the editor entirely.

The band is registered below every other highlight layer, so a find match or a spell squiggle always paints over it. Give it a paint-only format — a background colour — or it will force a reshape on every caret move.

pub fn get_caret_highlight(&self) -> Option<CaretHighlight>

What this editor’s caret band is currently configured to draw.

pub fn caret_window_rect(&self) -> Option<Rect>

The caret’s rectangle in absolute window (tree) coordinates, or None when the editor is unfocused or has not been laid out yet.

The same rect the OS-IME reporting and the caret follow use, exposed for hosts that need to position something against the caret (and for tests that need to assert where a pin actually put it).

pub fn format_version(&self) -> Signal<u64>

Signal that bumps on every format-only document event (bold / italic / heading / alignment / list style changes …). Distinct from document_version, which also bumps on content changes. Useful for toolbar observers that want to refresh button state on format changes without flickering during plain typing.

pub fn document_loaded_count(&self) -> Signal<u64>

Signal that bumps once per document-loaded event (fires when an async set_html / set_markdown import completes). Starts at 0; observers see a new value each time a long import finishes.

pub fn on_link_activated( self, handler: impl Fn(&str, &mut EventContext<'_>) + 'static, ) -> Self

Install a callback fired when the user Primary-clicks a link (an element with an anchor href). The callback receives the href string and the active EventContext.

The callback replaces any prior link-click callback on this builder chain. To stop observing, reconstruct the editor without the setter.

pub fn on_image_missing( self, resolve: impl Fn(&str) -> Option<(String, Vec<u8>)> + 'static, ) -> Self

Supply an image’s bytes on demand, when the document has no resource under that name.

An inline image references its pixels by name, and those pixels live on the document. So a name that arrives without them — which is exactly what pasting an image into a second editor is, since the interchange format carries the reference and not the bytes — lays out at its full size and paints nothing.

Rather than make every host re-scan its document after every edit for names that have appeared, the editor asks for what it is missing, once, at the moment it needs it. The bytes are written onto the document, so the answer is permanent and every later reader (a save, an export, a second view of the same document) sees them too.

One hook serves paste, drag-and-drop, and an undo that re-inserts a deleted image, without any of them knowing it exists.

pub fn on_files_dropped( self, handler: impl Fn(&[PathBuf], &mut EventContext<'_>) + 'static, ) -> Self

Install a callback fired when files are dropped on the editor.

The editor places the caret at the drop point and then hands the paths over: what a dropped file means — a picture to embed, a link to write, a document to include — is the host’s policy, and a text editor that guessed would be wrong for every host but one.

Without this, file drops are declined, and the drag bubbles to whatever ancestor claims it.

pub fn on_image_resized( self, handler: impl Fn(&ImageResize, &mut EventContext<'_>) + 'static, ) -> Self

Install a callback fired when the reader finishes dragging one of a selected image’s corner grips.

The widget does not resize the picture itself. It cannot: an image’s display size lives in the host’s own document format (an attribute, a style, a column of a table), and only the host knows how to write it there so it survives a save. So the drag reports a size and the host decides what that means — the same division of labour as on_image_activated.

Fired once, on release. During the drag the widget shows an outline at the proposed size, which costs no relayout and keeps one gesture to one entry on the host’s undo stack.

pub fn on_image_activated( self, handler: impl Fn(&ImageActivation, &mut EventContext<'_>) + 'static, ) -> Self

Install a callback fired when the user Primary-clicks an inline image. The callback receives the activation (see ImageActivation) and the active EventContext.

Trait Implementations

impl Debug for RichTextEditor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Widget for RichTextEditor

fn build(&mut self, ctx: &mut BuildContext<'_>) -> Vec<WidgetId>

Compose child widgets. Called once after the widget is placed in the arena, and again on environment change (theme switch, locale switch). Takes &mut self — store child IDs, signal handles, any state needed later. Returns the list of root child IDs (empty for leaf widgets).

fn layout_response( &self, proposal: SizeProposal, ctx: &LayoutContext<'_>, ) -> LayoutResponse

Respond to the parent’s size proposal with this widget’s wanted size, grow/shrink weights, and compression floor (see [LayoutResponse]).

fn place_children( &self, bounds: Rect, _proposal: SizeProposal, children: &mut [WidgetPlacement], _ctx: &LayoutContext<'_>, )

Position children within the allocated bounds.

fn children(&self) -> Vec<WidgetId>

Return the child widget IDs that this widget manages.

fn clips_children(&self) -> bool

Whether this widget clips its children to its bounds.

fn focus_reveal_rect(&self, _bounds: Rect) -> Option<Rect>

The rectangle (in absolute tree coordinates) that best represents this widget when the framework reveals it into an ancestor scroll area on focus gain. Returning None (the default) reveals the widget’s whole bounds — correct for most controls.

fn accessibility(&self, builder: &mut AccessNodeBuilder)

Declare this widget’s accessibility identity.

fn type_name(&self) -> &'static str

Concrete type name of this widget (e.g. "teksilo_widgets::button::Button"). The default implementation resolves at the impl site via std::any::type_name::<Self>(), so calls through &dyn Widget correctly dispatch to the monomorphized fn for the concrete type — getting the concrete name through the vtable without per-impl boilerplate.

fn cacheable_layout(&self) -> bool

Whether this widget’s layout_response may be memoized by the per-pass layout cache. Defaults to true.

fn paint(&self, _bounds: Rect, _canvas: &mut Canvas, _ctx: &PaintContext<'_>)

Draw the widget’s visual representation.

fn wants_after_paint(&self) -> bool

Whether this widget wants its after_paint hook to fire each frame. Returning false (the default) saves a virtual call per widget per frame for the vast majority of widgets that don’t aggregate descendant geometry.

fn after_paint(&self, _view: &WidgetTreeView<'_>, _ctx: &PaintContext<'_>)

Called once per frame after this widget’s subtree has finished painting. Receives a read-only view of the layout-resolved arena so a parent can read its descendants’ final bounds — e.g. TitleBar aggregates its drag region and control-button rects into a single HitRegions payload for the Windows backend’s WM_NCHITTEST.

fn wants_post_paint(&self) -> bool

Whether this widget wants its post_paint hook to fire each frame. Returning false (the default) saves a virtual call per widget per frame for the vast majority of widgets that don’t draw a foreground over their children.

fn post_paint( &self, _bounds: Rect, _canvas: &mut Canvas, _ctx: &PaintContext<'_>, )

Draw a foreground layer over this widget’s children.

fn wants_descendant_redirects(&self) -> bool

Whether this widget wants the AT walker to consult its a11y_redirect_descendant hook for every descendant during AT tree emission, not just its direct arena children.

fn a11y_redirect_descendant( &self, _self_id: WidgetId, _descendant: WidgetId, ) -> Option<NodeId>

Optional redirection hook for AT-tree placement of a child.

fn accessible_title_hint(&self) -> Option<String>

Suggest an accessible title to an enclosing container that wraps this widget as content — typically a modal / dialog shell that wants to propagate the inner content’s visible title as the shell’s own accessible name.

fn initial_focus_hint(&self) -> Option<WidgetId>

Optional hint that directs initial focus to a specific descendant when this widget is the root of a deferred-built modal surface.

fn accessibility_children(&self) -> Option<Vec<WidgetId>>

Optional override for the child ORDER presented to assistive technology, when it must differ from the paint / z-order child order returned by children.

fn as_any(&self) -> Option<&(dyn Any + 'static)>

Downcast hook. Default implementation returns None; concrete widgets override with Some(self) when they want to expose their concrete type to test-level introspection or reflection. The trait already bounds on std::any::Any so concrete types satisfy the 'static requirement.

fn as_any_mut(&mut self) -> Option<&mut (dyn Any + 'static)>

Mutable counterpart of as_any. Default returns None; widgets that want to expose mutable state to tests (e.g. so a test can mutate a Scene inside a SceneView post-layout) override with Some(self). Should follow the same opt-in pattern as as_any: only widgets that opt into & introspection should opt into &mut.

fn hit_shape(&self, _local_point: Point, _bounds: Rect) -> bool

Whether the point lies inside this widget’s actual shape, not just its rectangular bounds. Consulted by hit-testing right after the bounds check: returning false for a point that is inside the bounding box makes the widget transparent to the click there, so it falls through to whatever sibling is painted underneath (the same machinery as a fully pass-through node, but shape-aware).

fn preserves_children_on_rebuild(&self) -> bool

How rebuild_single_widget treats this widget’s existing children when re-running its build().

fn tooltip_has_content(&self) -> bool

Whether this widget, used as tooltip content, currently has anything worth showing.

fn declare_shortcuts(&self) -> Vec<Shortcut>

Declare the rebindable keyboard shortcuts this widget exposes, without installing handlers. The framework calls this at arena insertion time (before build()) and at certain lazy boundaries (e.g. Switcher walks declarations on its not-yet-mounted Pending slots), so settings UIs and the ShortcutRegistry see the keystrokes the moment the owning container mounts — even if build() hasn’t run.

fn take_handler_set(&mut self) -> Option<HandlerSet>

Extract attached handler set from a WidgetWithHandlers wrapper. Called during arena insertion to transfer handlers to the WidgetNode. Default: returns None (no attached handlers).