Struct TextEdit

pub struct TextEdit<Msg: Clone> { /* private fields */ }

A text input field.

Single-line by default; switches to a multi-row text-area via Self::multiline. Single-line mode honours the optional inline builders for picker-style fields:

• Self::align — horizontal alignment of the displayed text;
• Self::borderless — drop the surrounding pill / border so the field can sit inside a parent that already paints its own surface;
• Self::fixed_width — pin the preferred width to a specific number of pixels instead of claiming max_width;
• Self::font_size — override the text font size;
• Self::select_on_focus — auto-select the value on focus so the next keystroke replaces it (numeric pickers, short-form inputs).
• Self::password_toggle — pin a built-in show / hide-password eye icon to the right edge of the field; the bullet substitution flips with the externally-owned visible state on each tap.

text_edit( "Username", &self.username )
    .on_change( |s| Msg::UsernameChanged( s ) )
    .on_submit( Msg::Submit )
.into()

Password field with show / hide toggle

text_edit( "Password", &self.password )
    .on_change( |s| Msg::PasswordChanged( s ) )
    .password_toggle( self.password_visible, Msg::TogglePassword )
.into()

password_toggle overrides Self::secure when both are set — the toggle’s visible parameter drives the bullet substitution from then on. The widget still wipes the buffer on drop and skips the IME registration (the same hardening Self::secure gives) regardless of the current visibility, so flipping the eye does not weaken the field’s threat model at runtime.

Implementations

impl<Msg: Clone> TextEdit<Msg>

pub fn draw( &self, canvas: &mut Canvas, rect: Rect, focused: bool, cursor_pos: usize, selection_anchor: usize, )

Draw the field into canvas at rect.

cursor_pos is the byte offset of the text cursor — supplied by the runtime from its persistent cursor state rather than from the widget itself. selection_anchor is the other end of the selection range; when selection_anchor == cursor_pos no highlight is painted.

impl<Msg: Clone> TextEdit<Msg>

pub fn new(placeholder: String, value: String) -> Self

Create a text field with the given placeholder and initial value.

The cursor is placed at the end of the initial value.

pub fn password_toggle(self, visible: bool, on_toggle: Msg) -> Self

Add a “show / hide password” eye toggle pinned to the right edge of the field. visible controls whether the value renders as bullets (false) or plain text (true); a tap on the icon emits on_toggle so the caller can flip its own bool state and re-render. Works with or without an explicit Self::secure — when this is set, the toggle’s visible drives the bullet substitution and the secure field is ignored.

pub fn effective_secure(&self) -> bool

Effective secure flag honoured by drawing / measurement / hit-testing — Self::password_toggle takes precedence over the manual Self::secure when both are set.

pub fn font_size(self, px: f32) -> Self

Pin the single-line font size to an explicit fixed px. Without any font-size call the size follows the process crate::WidgetScaling mode at the theme default; see Self::font_size_fluid to follow the mode at a custom design px. Ignored in multiline mode.

pub fn font_size_fluid(self, design_px: f32) -> Self

Set a font size that follows the process crate::WidgetScaling mode at the given design px — the fluid counterpart of Self::font_size. Encoded as a negative sentinel so it flows through the handler snapshot as a plain f32 without threading a canvas; every consumer resolves it via resolve_font_size.

pub fn height(self, h: impl Into<Length>) -> Self

Set the single-line field height. Accepts logical f32 pixels or any Length (e.g. Length::vmin( 9.0 ).clamp( 44.0, 72.0 ) to scale the box with the surface, or to match a fluid button). Ignored in multiline mode, where the height follows Self::rows.

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

Select the whole value when the field receives focus, so the next keystroke replaces it. Default false.

pub fn align(self, a: TextAlign) -> Self

Set the horizontal alignment of the displayed text. Default TextAlign::Left.

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

Skip the field’s background fill and border stroke — useful when the field is nested inside a container that already paints its own surface.

pub fn fixed_width(self, w: f32) -> Self

Override the preferred width reported to the parent layout. Pass None (default) to fall back to claiming max_width.

pub fn cursor(self, shape: CursorShape) -> Self

Override the pointer cursor shape shown on hover. Defaults to CursorShape::Text (I-beam).

pub fn multiline(self, m: bool) -> Self

Switch to multiline (text-area) mode. The box is laid out with Self::rows visible rows of height, line breaks in the value are rendered as separate rows, and Enter inserts a \n instead of firing Self::on_submit. Ignored when Self::secure is true.

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

Configure the number of visible rows in multiline mode. Defaults to 5; ignored when Self::multiline is false.

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

Set the callback invoked on every keystroke with the updated value.

pub fn on_submit(self, msg: Msg) -> Self

Set the message emitted when Enter is pressed.

pub fn secure(self, s: bool) -> Self

Enable or disable password mode.

When true, this widget:

1. Renders the value as bullet characters (•) instead of the raw glyphs.
2. Forces single-line mode (multiline + secure is mutually exclusive — passwords don’t have line breaks).
3. Wipes the underlying byte buffer with zero before the String allocation is returned to the allocator. The wipe runs in Drop for both the TextEdit itself and for the per-frame crate::widget::WidgetHandlers::TextEdit snapshot the runtime keeps for input dispatch — so the in-tree copies that ltk owns never linger as plain text in freed memory.

Threat model — what secure covers

Inside the widget tree the runtime keeps two copies of the value for the lifetime of one frame: the TextEdit itself and the WidgetHandlers snapshot. Both run the secure_zero wipe on Drop, so when the next frame replaces them (the typical case — view() rebuilds every frame) the freed allocations are overwritten before being released back to the allocator. The wipe uses volatile writes + a compiler_fence so the optimiser cannot elide it as dead code (the implementation is in the crate-private secure_mem module).

What secure does not cover

• The application’s own state. The String you pass in through text_edit( placeholder, &self.password ) lives on your struct, not on the widget. Wiping it is your job — typically a Drop impl on the credential container, or an explicit secure_mem::secure_zero( password.as_bytes_mut() ) after the auth handshake completes.
• Callback-allocated copies. Every keystroke passes through on_change( |s: String| ... ), which receives a fresh String clone. If your closure stores or forwards that String (e.g. clone it into a worker thread for PAM), each stored copy is the consumer’s responsibility to wipe. ltk only owns the buffers it allocated itself.
• OS-level disclosure surfaces. Swap-out, hibernation images, and core dumps are outside any user-space wipe’s reach. For threat models that require resistance to these, compile against an mlock-aware allocator, disable swap on the credential mount, and restrict core-dump capability with prctl( PR_SET_DUMPABLE, 0 ) on the process.
• Compositor-side records. Wayland text-input protocols can surface preedit / commit strings to the compositor’s IME stack. secure does not suppress text-input-v3 — the field still registers so the on-screen keyboard activates on it — but it is flagged Password with SensitiveData | HiddenText, asking the IME / OSK to skip prediction, autocorrect and storing the value. The value still reaches the (trusted) compositor/IME; for a stricter threat model, suppress text-input on secure fields instead (at the cost of losing the OSK there).

See the in-repo SECURITY.md for the full threat-model write-up (the Hardening features section enumerates each guarantee and its boundary).

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

Render the field read-only: shows the value styled as a field but takes no focus and accepts no input.

pub fn id(self, id: WidgetId) -> Self

Assign a stable identifier for focus management.

pub fn preferred_size(&self, max_width: f32, canvas: &Canvas) -> (f32, f32)

Return the preferred (width, height) given available max_width.

Single-line: theme-defined HEIGHT. Multiline: enough room for Self::rows lines plus padding.

pub fn is_multiline(&self) -> bool

true when the widget is laid out as a multi-row text area — i.e. Self::multiline was set and Self::effective_secure is false. A password_toggle field collapses to single-line like an explicit secure( true ) does.

pub fn byte_offset_at_self( &self, canvas: &Canvas, rect: Rect, pos: Point, cursor_pos: usize, ) -> usize

Translate a pointer position inside rect to the byte offset in the field’s value that the cursor should land on. Thin wrapper around byte_offset_at using this widget’s value / flags.

pub fn paint_bounds(&self, rect: Rect) -> Rect

Border stroke is centered on rect, so half the stroke width plus ~1 px of antialiasing bleed sits outside. The widest stroke is the focused border, so use that as the envelope.

pub fn display_text(&self) -> String

Return the display string — bullet characters in secure mode, plain value otherwise.

pub fn into_element(self) -> Element<Msg>

Wrap this widget in an Element.

pub fn insert_str(&mut self, s: &str) -> Option<Msg>

Insert a string at the current cursor position, advance the cursor, and return the on_change message if one is set.

pub fn backspace(&mut self) -> Option<Msg>

Delete the character before the cursor and return the on_change message if one is set. Does nothing if the cursor is already at position 0.

Trait Implementations

impl<Msg: Clone> Drop for TextEdit<Msg>

fn drop(&mut self)

When secure( true ) is set, scrub the value bytes before the underlying String allocation is returned to the allocator. The non-secure path is a no-op so the cost is paid only by widgets that opted into credential handling.

impl<Msg: Clone> From<TextEdit<Msg>> for Element<Msg>

fn from(t: TextEdit<Msg>) -> Self

Converts to this type from the input type.