Struct TextInput 

pub struct TextInput<M> { /* private fields */ }

A single-line text field with a caret.

Selecting

Taking focus selects everything, which is what makes Tab-and-type replace a setpoint rather than append to it. A press places the caret, a second on the same spot takes the word under it, a third takes the whole field, and dragging — with a mouse or a finger — extends from where the press landed. Shift extends with the arrows, Home and End; ⌘A or Ctrl+A takes everything. Typing, Backspace and Delete replace what is selected.

The clipboard

⌘C, ⌘X and ⌘V — or Ctrl — when the application has said where they go with with_clipboard. The widget has no clipboard to reach, so it asks: copy and cut hand over the text, paste emits ClipboardRequest::Paste and the application answers with insert_text. Without that wiring the three keys do nothing at all, which is what a panel with no clipboard wants.

A password field refuses copy and cut. Its whole job is that what is on the screen cannot be read, and handing the value to the system clipboard would undo that for one keystroke. Pasting into one is still allowed.

Moving by word

Ctrl and an arrow move by word, and so does Option on a Mac — the widget cannot ask which keyboard it is in front of, so it takes both spellings. Command and an arrow go to the start or the end, which is what Command does on the machine that has it and what Home and End do everywhere. Shift extends with all of them.

What it still does not do

No undo. A kiosk field takes a name, a PIN or a setpoint; TextArea is where an editor’s machinery lives.

Blinking

The caret blinks only while the field has focus: taking focus requests animation, and losing it makes Widget::animate answer None, which is how a widget hands the CPU back. An unfocused panel therefore has nothing running on a timer at all — the difference between a device that idles and one that keeps a core awake for its whole service life. Typing resets the phase so the caret stays solid while it is moving.

A blink damages the whole field rather than the caret, because Widget::animate reports that something changed, not where. On a Pi 3 that is 26 kpx twice a second — 58 µs, or 0.35% of one 60 Hz frame — against the 32 px the caret actually occupies. The 800× coarseness is real and the cost of removing it is a wider trait; the measurement is why it has not been paid.

Implementations

impl<M> TextInput<M>

pub fn new() -> Self

An empty field.

pub fn with_placeholder(self, placeholder: impl Into<String>) -> Self

Sets the text shown when the field is empty.

pub fn with_submit(self, message: M) -> Self

Sets the message emitted when Enter is pressed.

pub fn with_clipboard(self, message: fn(ClipboardRequest) -> M) -> Self

Wires copy, cut and paste to the application, which owns the clipboard.

Without this the three keys do nothing: a panel with no window system has nowhere to copy to, and a widget that pretended otherwise would be lying about where the text went.

pub fn with_max_chars(self, max: usize) -> Self

Caps the number of characters the field will hold.

pub fn with_style(self, style: TextStyle) -> Self

Sets the font and size.

pub fn with_size(self, size_px: u16) -> Self

Sets the size, keeping the font.

pub const fn style(&self) -> TextStyle

The font and size this field draws in.

pub fn with_password(self, password: bool) -> Self

Draws every character as *. The text is still stored in the clear — this hides a PIN from someone standing behind the panel, and nothing more.

pub fn text(&self) -> &str

The current contents.

pub fn set_text(&mut self, text: impl Into<String>)

Replaces the contents, putting the caret at the end.

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

Inserts text at the caret, replacing the selection: the answer to ClipboardRequest::Paste.

A field is one line, so this takes what it is given up to the first line break and drops the rest, along with any other control characters. Pasting three lines into a setpoint has no meaning a widget could guess at, and joining them into one would invent a value nobody copied.

What is left is truncated to fit max_chars rather than refused: a paste one character too long is still mostly what somebody wanted.

pub fn set_style(&mut self, style: TextStyle)

Replaces the font and size.

pub fn clear(&mut self)

Empties the field.

pub const fn caret(&self) -> usize

Caret position, as a character index.

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

The selection as character indices, low end first, or None when there is only a caret.

pub fn selected_text(&self) -> Option<&str>

The selected text, or None when nothing is selected.

pub fn select_all(&mut self)

Selects everything, with the caret at the end.

pub fn select_range(&mut self, from: usize, to: usize)

Selects from..to, clamped to the text, with the caret at to.

The pair may be given either way round: the caret lands on to, which is the end a further Shift-arrow moves.

pub fn clear_selection(&mut self)

Drops the selection, leaving the caret where it is.

pub fn caret_x(&self, engine: &mut TextEngine, bounds: Rect) -> i32

Horizontal offset of the caret from the field’s left edge.

Measured through the engine rather than counted as characters times a width, which is the only thing that works with a proportional font.

Trait Implementations

impl<M: Clone> Clone for TextInput<M>

fn clone(&self) -> TextInput<M>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<M: Debug> Debug for TextInput<M>

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

Formats the value using the given formatter.

impl<M> Default for TextInput<M>

fn default() -> Self

Returns the “default value” for a type.

impl<M> Describe for TextInput<M>

const KIND: &'static str = "text-input"

The name a form file uses for this widget. Kebab-case.

const DOC: &'static str = "A line of text somebody types into."

One line saying what this widget is, for somebody choosing one.

const GROUP: Group = Group::Input

Which shelf of the catalogue this belongs on.

const ICON: &'static Icon

The widget’s glyph: a small portrait of the thing, for a palette to draw beside — or instead of — its name.

const PROPERTIES: &'static [Property]

Every property, in the order an inspector should show them.

fn get(&self, name: &str) -> Option<Value>

The current value.

fn apply(&mut self, name: &str, value: Value) -> Result<(), Mismatch>

Applies a value, reporting only what went wrong.

fn set(&mut self, name: &str, value: Value) -> Result<(), PropertyError>

Applies a value, reporting what went wrong and where.

impl<M: Clone + 'static> Widget<M> for TextInput<M>

fn snap(&mut self, now_ms: u64) -> Animation

Blinking is a schedule, so it survives Motion::None unchanged — there is nothing to land, and stopping it would be a regression dressed up as a preference.

fn describe(&self) -> Option<&dyn DynDescribe>

This widget’s property description, if it has one.

fn describe_mut(&mut self) -> Option<&mut dyn DynDescribe>

The mutable half of describe.

fn measure(&self, ctx: &mut MeasureCtx<'_>, _offered: Offer) -> Measured

How big this widget would like to be, given what the caller can promise.

fn paint(&self, ctx: &mut PaintCtx<'_>, canvas: &mut Pen<'_>)

Draws into canvas, which is already clipped to this widget’s bounds intersected with the damage region being repainted.

fn on_event(&mut self, event: &Event<'_>, ctx: &mut EventCtx<'_, M>) -> Handled

Reacts to an event routed to this widget.

fn accepts_pointer(&self) -> bool

Returns true if the pointer can hit this widget.

fn focusable(&self) -> bool

Returns true if this widget can take keyboard focus.

fn animate(&mut self, now_ms: u64) -> Animation

Advances time-based state. Called only while this widget has asked to animate — see EventCtx::request_animation — and stops being called the moment it answers Wake::Never.

fn preserves_focus(&self) -> bool

Returns true if a press on this widget should leave focus exactly where it is.