Struct TextArea 

pub struct TextArea { /* private fields */ }

A multiline text editor that fills its available area.

Implementations

impl TextArea

pub fn debug_raster_count(&self) -> u64

Test/introspection hook: number of real backbuffer re-rasters (each paint into the buffer bumps it). Scrolling within a band must not increment this; re-anchoring or editing must.

pub fn debug_strip_raster_count(&self) -> u64

Test/introspection hook: number of partial (dirty-line-strip) re-rasters. A localized edit within an active band bumps this; a re-anchor or a structural change (resize, wrap re-flow) does not.

impl TextArea

pub fn on_change(self, cb: impl FnMut(&str) + 'static) -> Self

Install a callback fired after every text change.

Fires for: typing, Enter, Tab-insert, backspace/delete, paste, cut, and key-intercept edits that advance the content epoch. It does NOT fire for purely programmatic mutations pushed straight into the shared TextEditState from outside the widget (those bypass the mutation funnel; the epoch mechanism still re-wraps them on the next layout).

impl TextArea

pub fn with_context_menu(self, v: bool) -> Self

Enable or disable the default right-click Cut/Copy/Paste/Select-All context menu. On by default.

impl TextArea

pub fn scroll_offset(&self) -> f64

Current vertical scroll offset (0 = top). Exposed for tests/inspectors.

pub fn with_scroll_watch(self, watch: Rc<Cell<f64>>) -> Self

Publish this widget’s live vertical scroll offset (in px from the top, the same value scroll_offset reports) into a shared cell whenever it changes. Exists so a sibling widget outside the editor’s subtree can mirror the viewport — the Code Editor demo’s line-number gutter uses it to keep the numbers aligned with the scrolled text, which it otherwise cannot see. The cell is refreshed at every offset mutation (wheel, thumb drag, scroll-to-caret, relayout clamp), so it is current before the next frame paints.

impl TextArea

pub fn new(font: Arc<Font>) -> Self

pub fn with_text(self, text: impl Into<String>) -> Self

pub fn with_hint_text(self, hint: impl Into<String>) -> Self

Placeholder text shown, dimmed, while the buffer is empty.

pub fn with_content_h_align(self, a: TextHAlign) -> Self

Static horizontal alignment of the wrapped content.

pub fn with_content_v_align(self, a: TextVAlign) -> Self

Static vertical alignment of the wrapped content block.

pub fn with_h_align_cell(self, cell: Rc<Cell<TextHAlign>>) -> Self

Bind horizontal alignment to a live cell (wins over the static value).

pub fn with_v_align_cell(self, cell: Rc<Cell<TextVAlign>>) -> Self

Bind vertical alignment to a live cell (wins over the static value).

pub fn with_edit_state(self, state: Rc<RefCell<TextEditState>>) -> Self

Adopt an externally-owned edit state so a caller can read the text / selection and mutate it (clear, replace, move cursor) from outside the widget tree. External text mutations must call TextEditState::note_text_change so the wrap cache invalidates.

pub fn with_focus_id(self, id: FocusId) -> Self

Stable id for the programmatic focus channel (crate::focus::request_focus).

pub fn with_key_intercept( self, cb: impl FnMut(&Key, &Modifiers) -> bool + 'static, ) -> Self

Install a pre-default key-chord interceptor. It runs before the widget’s built-in key handling on every KeyDown; returning true consumes the event and suppresses the default action for that key.

pub fn with_highlighter( self, cb: impl Fn(&str) -> Vec<(usize, usize, Color)> + 'static, ) -> Self

Install a per-visual-line syntax highlighter (see LineHighlighter).

pub fn edit_state(&self) -> Rc<RefCell<TextEditState>>

Clone of the shared edit-state handle, for selection/text readback and external mutation.

pub fn selection(&self) -> Option<(usize, usize)>

Current selection as a sorted [start, end) byte range, or None when nothing is selected.

pub fn selected_text(&self) -> String

The currently-selected substring (empty when there is no selection).

pub fn set_cursor_to_start(&mut self)

Collapse the selection and place the cursor at the very start.

pub fn set_cursor_to_end(&mut self)

Collapse the selection and place the cursor at the very end.

pub fn with_font_size(self, size: f64) -> Self

pub fn with_padding(self, p: f64) -> Self

pub fn with_margin(self, m: Insets) -> Self

pub fn with_h_anchor(self, h: HAnchor) -> Self

pub fn with_v_anchor(self, v: VAnchor) -> Self

pub fn with_min_size(self, s: Size) -> Self

pub fn with_max_size(self, s: Size) -> Self

pub fn text(&self) -> String

Current text. Cheap — clones the underlying String.

pub fn cursor(&self) -> usize

Current byte-offset cursor position (for tests and inspectors).

pub fn visual_line_count(&self) -> usize

Count of visual lines at the last layout pass (cache).

Trait Implementations

impl Widget for TextArea

fn has_active_modal(&self) -> bool

While the right-click menu is open it must capture every event (clicks outside dismiss it, Escape closes it).

fn paint_global_overlay(&mut self, ctx: &mut dyn DrawCtx)

The context menu paints at app level so it can overflow the editor bounds and clamp to the viewport.

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

A static name for this widget type, used by the inspector. Default: “Widget”.

fn bounds(&self) -> Rect

Bounding rectangle in parent-local Y-up coordinates.

fn set_bounds(&mut self, b: Rect)

Set the bounding rectangle. Called by the parent during layout.

fn children(&self) -> &[Box<dyn Widget>]

Immutable access to child widgets.

fn children_mut(&mut self) -> &mut Vec<Box<dyn Widget>>

Mutable access to child widgets (required for event dispatch + layout).

fn is_focusable(&self) -> bool

Whether this widget can receive keyboard focus. Default: false.

fn focus_id(&self) -> Option<FocusId>

Stable identifier for the programmatic focus channel (crate::focus::request_focus).

fn accepts_text_input(&self) -> bool

true when this widget accepts free-form character input (typing arbitrary letters, numbers, punctuation). Used by the on-screen software keyboard (crate::widgets::on_screen_keyboard) to decide whether to slide up when this widget gains focus.

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

Current text contents of this widget if it is text-bearing. Used by the on-screen software keyboard to apply the sentence-start auto-capitalize heuristic: an empty field (or one ending in ., !, ?, newline) opens the keyboard with Shift active.

fn margin(&self) -> Insets

Outer margin around this widget in logical units.

fn widget_base(&self) -> Option<&WidgetBase>

Direct read access to the widget’s embedded WidgetBase.

fn widget_base_mut(&mut self) -> Option<&mut WidgetBase>

Mutable counterpart of widget_base.

fn h_anchor(&self) -> HAnchor

Horizontal anchor: how this widget sizes/positions itself horizontally within the slot the parent assigns. Default: HAnchor::FIT (take natural content width).

fn v_anchor(&self) -> VAnchor

Vertical anchor: how this widget sizes/positions itself vertically within the slot the parent assigns. Default: VAnchor::FIT (take natural content height).

fn min_size(&self) -> Size

Minimum size constraint (logical units).

fn max_size(&self) -> Size

Maximum size constraint (logical units).

fn backbuffer_cache_mut(&mut self) -> Option<&mut BackbufferCache>

Opt into per-widget CPU bitmap caching with a dirty flag.

fn backbuffer_band(&self) -> Option<BackbufferBand>

Opt into over-scan band caching for a scrolling backbuffered widget.

fn backbuffer_mode(&self) -> BackbufferMode

Storage format for this widget’s backbuffer. Ignored unless [backbuffer_cache_mut] returns Some. Default BackbufferMode::Rgba — correct for any widget. Opt into BackbufferMode::LcdCoverage only when the widget paints opaque content covering its full bounds.

fn measure_min_height(&self, available_w: f64) -> f64

Report the minimum height this widget needs to fully render its content when given the supplied available_w for width.

fn layout(&mut self, available: Size) -> Size

Compute desired size given available space, and update internal layout.

fn paint(&mut self, ctx: &mut dyn DrawCtx)

Paint this widget’s own content into ctx.

fn paint_overlay(&mut self, ctx: &mut dyn DrawCtx)

Paint decorations that must appear on top of all children.

fn on_event(&mut self, event: &Event) -> EventResult

Handle an event. The event’s positions are already in local Y-up coordinates. Return EventResult::Consumed to stop bubbling.

fn hit_test(&self, local_pos: Point) -> bool

Return true if local_pos (in this widget’s local coordinates) falls inside this widget’s interactive area. Default: axis-aligned rect test.

fn properties(&self) -> Vec<(&'static str, String)>

Return type-specific properties for the inspector properties pane.

fn needs_draw(&self) -> bool

Return true if this widget, or any visible descendant, has an ongoing draw need that should keep the host drawing.

fn next_draw_deadline(&self) -> Option<Instant>

Return the earliest wall-clock instant at which this widget (or any visible descendant) wants the next draw. None = no scheduled wake. The host loop turns a Some(t) into ControlFlow::WaitUntil(t) so e.g. a cursor blink fires without continuous polling.

fn claims_pointer_exclusively(&self, _local_pos: Point) -> bool

When true, hit_test_subtree stops recursing into this widget’s children and returns this widget as the hit target. Used for floating overlays (e.g. a scrollbar painted above its content) that must claim the pointer before children that happen to share the same pixels. Default: false.

fn blocks_child_interaction(&self) -> bool

When true, this widget disables all interaction — pointer and keyboard — within its subtree, reproducing egui’s UiBuilder::disabled(). Unlike [claims_pointer_exclusively], this is a position-independent state predicate: pointer hit-testing stops at this widget (so clicks are swallowed rather than passing through), and focus collection skips the whole subtree (so Tab cannot reach a child). Default: false.

fn hit_test_global_overlay(&self, _local_pos: Point) -> bool

Return true when local_pos hits an app-level overlay owned by this widget. Unlike normal hit testing, ancestors may be missed because the overlay is painted outside their bounds.

fn on_unconsumed_key( &mut self, _key: &Key, _modifiers: Modifiers, ) -> EventResult

Handle a key that was not consumed by the focused widget path.

fn id(&self) -> Option<&str>

Optional human-readable identifier for this widget instance.

fn is_visible(&self) -> bool

Return false to suppress painting this widget and all its children. The widget’s own paint() will not be called. Default: true.

fn text_input_mode(&self) -> KeyboardInputMode

Preferred keyboard input mode for this widget — used by the on-screen software keyboard to pick the initial layer when this widget gains focus. Default is KeyboardInputMode::Text; numeric fields override to Numeric so the digit pad slides up instead of the letter row.

fn try_scroll_to_lift(&mut self, _amount: f64) -> f64

Try to lift this widget’s visible content upward by amount pixels. Used by the on-screen-keyboard auto-scroll so a focused text field doesn’t end up hidden behind the keyboard panel: the App walks UP the focus path and asks each ancestor to absorb some of the deficit.

fn set_label_color(&mut self, _color: Color)

If this widget is text-bearing (e.g. Label), update its foreground colour. Default is a no-op. Composite widgets call this on their children to retint labels without rebuilding them — used by Button when toggling between active (white text on accent) and inactive (theme text on subtle bg) appearances.

fn set_label_text(&mut self, _text: &str)

If this widget is text-bearing (e.g. Label), update its displayed text. Default is a no-op. Composite widgets that own a Label child use this to push live values (e.g. an FPS counter) into the child without bypassing the standard backbuffered glyph cache — calling this on a Label only invalidates the cache when the text actually changed.

fn as_reflect(&self) -> Option<&dyn Reflect>

Opt-in reflection accessor for the inspector’s typed property editors.

fn as_reflect_mut(&mut self) -> Option<&mut dyn Reflect>

Mutable counterpart of as_reflect. Used by the inspector to write edits back into the live widget.

fn has_backbuffer(&self) -> bool

Whether this widget renders into its own offscreen buffer before compositing into the parent.

fn compositing_layer(&mut self) -> Option<CompositingLayer>

Request that this widget subtree be painted into a transient transparent compositing layer before being blended into its parent.

fn backbuffer_spec(&mut self) -> BackbufferSpec

Unified widget-owned backbuffer request.

fn backbuffer_state_mut(&mut self) -> Option<&mut BackbufferState>

Mutable retained backbuffer state for widgets that request a BackbufferSpec other than BackbufferKind::None.

fn mark_dirty(&mut self)

Mark this widget’s own retained surface dirty, if it owns one.

fn contributes_children_to_inspector(&self) -> bool

Whether the inspector should recurse into this widget’s children.

fn show_in_inspector(&self) -> bool

Return false to hide this widget (and its subtree) from the inspector node snapshot entirely. Intended for zero-size utility widgets such as layout-time watchers / tickers / invisible composers — they bloat the inspector tree without providing user-relevant information and, at scale, can make the inspector’s per-frame tree rebuild expensive.

fn lcd_preference(&self) -> Option<bool>

Per-widget LCD subpixel preference for backbuffered text rendering.

fn finish_paint(&mut self, _ctx: &mut dyn DrawCtx)

Called after paint, child painting, and optional overlay painting.

fn defer_paint_to_overlay(&self) -> bool

Opt this widget’s entire subtree out of the normal inline paint pass so it renders in paint_global_overlay instead — the same clip-escaping global pass used by menus and tooltips.

fn clip_children_rect(&self) -> Option<(f64, f64, f64, f64)>

Return a clip rectangle (in local coordinates) that constrains all child painting. paint_subtree applies this clip before recursing into children, then restores the previous clip state afterward. The clip does not affect paint_overlay, which runs after the clip is removed.

fn inspector_child_transform(&self) -> TransAffine

Affine transform applied between this widget and its children during inspector traversal. Mirrors what paint() does — e.g. a widget that pushes pan/zoom in paint() and pops it in finish_paint() makes the framework recurse into its children with pan/zoom active, so collect_inspector_nodes must apply the same transform when accumulating descendant screen bounds. Without this hook the inspector hover overlay lands at the un-transformed canvas position when the widget sits inside a panning/zooming container.

fn child_transform(&self) -> Option<TransAffine>

Affine transform (child-local → this widget’s local space) that the framework applies to all of this widget’s children for painting, hit-testing, and event dispatch alike.

fn padding(&self) -> Insets

Inner padding — space the widget reserves between its own bounds and its child layout area. Only container widgets carry padding; leaf widgets default to Insets::ZERO.

fn tooltip_text(&self) -> Option<&str>

Hover-help text for the central tooltip controller, or None.

fn with_tooltip(self, text: impl Into<String>) -> Self

where Self: Sized,

Builder sugar: attach hover-help text, returning self for chaining.

fn set_tooltip_text(&mut self, text: Option<String>)

Object-safe setter counterpart of with_tooltip, callable on a &mut dyn Widget / Box<dyn Widget> (used by builders that assemble a control tree from boxed widgets, e.g. toolbars). Writes through widget_base_mut; a no-op for widgets without a WidgetBase. Pass None to clear.

fn enforce_integer_bounds(&self) -> bool

Whether paint_subtree should snap this widget’s incoming translation to the physical pixel grid.

fn take_raise_request(&mut self) -> bool

Container widgets (notably crate::widgets::Stack) call this on each child at the start of layout(). A widget that returns true is moved to the END of its parent’s child list — painted last, i.e. raised to the top of the z-order. take_ semantics: the call is also expected to clear the request so the child doesn’t keep getting raised every frame.