Struct TextInput 

pub struct TextInput<'a> { /* private fields */ }

A single-line editable text field: the stateless drawing half of TextInputState, the same split List has with ListState.

Draws state.value() (masked with mask if set, or placeholder while state.value() is empty), scrolled horizontally by state.scroll() and clipped to surface.area()’s width, with a caret cell at the cursor’s display column. Neither scrolling nor the caret’s column is byte- or char-based: both go through retroglyph_core::text::width_usize, the same display-width measurement truncate uses, so a value containing a double-width character (CJK, most emoji) still puts the caret in the right screen column.

This widget does not call TextInputState::ensure_visible: like List/ListState::ensure_visible, that’s the caller’s job, once per frame, with the actual current field width (which can change on resize).

The caret always renders as an inverted-color cell (caret_style), not by driving a real terminal cursor via a backend’s Cursor facet: render only has a Surface, not a Backend, and a cell-drawn caret renders identically (including in headless snapshot tests) on every backend. An app that wants a blinking, backend-native caret instead can position one itself from state.cursor()/state.scroll() alongside this widget.

This widget draws one field, nothing more: which field is focused (and therefore routed input), what Enter does, validation, and layout are all the app’s job. IME/text composition and multi-line editing are out of scope for this crate entirely; see docs/ROADMAP.md.

Examples

use retroglyph_core::grid::{Grid, Rect};
use retroglyph_ui::{StatefulWidget, Surface, TextInput, TextInputState};

let mut state = TextInputState::new();
state.set_value("hello");

let area = Rect::new(0, 0, 10, 1);
let mut grid = Grid::new(10, 1);
TextInput::new().render(&mut Surface::new(&mut grid, area, 0), &mut state);

Implementations

impl<'a> TextInput<'a>

pub fn new() -> Self

An empty-placeholder, unmasked text input, styled from Theme::DARK (as if TextInput::theme had been called); call TextInput::theme/TextInput::theme_on for a different Theme.

pub const fn placeholder(self, placeholder: &'a str) -> Self

Text shown, in placeholder_style, when state.value() is empty.

pub const fn mask(self, mask: char) -> Self

Render every character of state.value() as mask instead of its real glyph, e.g. '*' for a password field. Column math (scrolling, caret position) still uses the real value’s display width, not the mask’s: masking only ever substitutes one fixed-width glyph, so this is exact as long as mask itself is a single-column character.

pub const fn style(self, style: Style) -> Self

Set the style of the value/placeholder text (placeholder uses placeholder_style instead of this while shown).

pub const fn placeholder_style(self, style: Style) -> Self

Set the style of the placeholder text, shown in place of the value while it’s empty.

pub const fn caret_style(self, style: Style) -> Self

Set the style of the caret cell.

pub fn theme(self, theme: Theme) -> Self

Applies theme’s named roles: style becomes theme.fg on theme.panel_bg, placeholder_style becomes theme.dim on the same background, and caret_style becomes theme.bg on theme.accent. See List::theme for why an explicit background is baked in rather than left unset.

pub fn theme_on(self, theme: Theme, bg: Color) -> Self

Same as TextInput::theme, but text is drawn on bg instead of theme.panel_bg.

Trait Implementations

impl<'a> Clone for TextInput<'a>

fn clone(&self) -> TextInput<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for TextInput<'a>

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

Formats the value using the given formatter.

impl Default for TextInput<'_>

fn default() -> Self

Returns the “default value” for a type.

impl StatefulWidget for TextInput<'_>

type State = TextInputState

The externally owned state this widget reads and/or updates while rendering.

fn render(&self, surface: &mut Surface<'_>, state: &mut Self::State)

Draw this widget into surface, filling surface.area(), using and/or updating state.

impl<'a> Copy for TextInput<'a>