Struct EditField 

pub struct EditField<G: EditGuard = DefaultGuard<()>> {
    pub guard: G,
    /* private fields */
}

A text-edit field (single- or multi-line)

The EditBox widget should be preferred in most cases; this widget is a component of EditBox and has some special behaviour.

By default, the editor supports a single-line only; Self::with_multi_line and Self::with_class can be used to change this.

Event handling

This widget attempts to handle all standard text-editor input and scroll events.

Key events for moving the edit cursor (e.g. arrow keys) are consumed only if the edit cursor is moved while key events for adjusting or using the selection (e.g. Command::Copy and Command::Deselect) are consumed only when a selection exists. In contrast, key events for inserting or deleting text are always consumed.

Command::Enter inserts a line break in multi-line mode, but in single-line mode or if the Shift key is held it is treated the same as Command::Activate.

Performance and limitations

Text representation is via a single String. Edit operations are O(n) where n is the length of text (with text layout algorithms having greater cost than copying bytes in the backing String). This isn’t necessarily slow; when run with optimizations the type can handle type-setting around 20kB of UTF-8 in under 10ms (with significant scope for optimization, given that currently layout is re-run from scratch on each key stroke). Regardless, this approach is not designed to scale to handle large documents via a single EditField widget.

Messages

SetValueText may be used to replace the entire text and ReplaceSelectedText may be used to replace selected text, where Self::is_editable. This triggers the action handlers EditGuard::edit followed by EditGuard::activate.

Fields

guard: G

The associated EditGuard implementation

Implementations

impl<G: EditGuard> EditField<G>

pub fn new(guard: G) -> EditField<G>

Construct an EditBox with an EditGuard

pub fn as_str(&self) -> &str

Get text contents

pub fn clone_string(&self) -> String

Get the text contents as a String

pub fn set_str(&mut self, cx: &mut EventState, text: &str)

pub fn set_string(&mut self, cx: &mut EventState, string: String)

Set text contents from a String

This method does not call action handlers on the EditGuard.

pub fn replace_selection(&mut self, cx: &mut EventCx<'_>, text: &str)

Replace selected text

This method does not call action handlers on the EditGuard.

pub fn typeset_size(&self) -> Size

Get the size of the type-set text

EditField ensures text has no left or top overhang.

pub fn draw_with_offset(&self, draw: DrawCx<'_>, rect: Rect, offset: Offset)

Draw with an offset

Draws at position self.rect() - offset.

This may be called instead of Layout::draw.

impl<A: 'static> EditField<DefaultGuard<A>>

pub fn text<S: ToString>(text: S) -> Self

Construct an EditField with the given inital text (no event handling)

pub fn string( value_fn: impl Fn(&A) -> String + 'static, ) -> EditField<StringGuard<A>>

Construct a read-only EditField displaying some String value

pub fn parser<T: Debug + Display + FromStr, M: Debug + 'static>( value_fn: impl Fn(&A) -> T + 'static, msg_fn: impl Fn(T) -> M + 'static, ) -> EditField<ParseGuard<A, T>>

Construct an EditField for a parsable value (e.g. a number)

On update, value_fn is used to extract a value from input data which is then formatted as a string via Display. If, however, the input field has focus, the update is ignored.

On every edit, the guard attempts to parse the field’s input as type T via FromStr, caching the result and setting the error state.

On field activation and focus loss when a T value is cached (see previous paragraph), on_afl is used to construct a message to be emitted via EventCx::push. The cached value is then cleared to avoid sending duplicate messages.

pub fn instant_parser<T: Debug + Display + FromStr, M: Debug + 'static>( value_fn: impl Fn(&A) -> T + 'static, msg_fn: impl Fn(T) -> M + 'static, ) -> EditField<InstantParseGuard<A, T>>

Construct an EditField for a parsable value (e.g. a number)

On update, value_fn is used to extract a value from input data which is then formatted as a string via Display. If, however, the input field has focus, the update is ignored.

On every edit, the guard attempts to parse the field’s input as type T via FromStr. On success, the result is converted to a message via on_afl then emitted via EventCx::push.

impl<A: 'static> EditField<StringGuard<A>>

pub fn with_msg<M>(self, msg_fn: impl Fn(&str) -> M + 'static) -> Self

where M: Debug + 'static,

Assign a message function for a String value

The msg_fn is called when the field is activated (Enter) and when it loses focus after content is changed.

This method sets self as editable (see Self::with_editable).

impl<G: EditGuard> EditField<G>

pub fn with_text(self, text: impl ToString) -> Self

Set the initial text (inline)

This method should only be used on a new EditField.

pub fn with_editable(self, editable: bool) -> Self

Set whether this EditField is editable (inline)

pub fn is_editable(&self) -> bool

Get whether this EditField is editable

pub fn set_editable(&mut self, editable: bool)

Set whether this EditField is editable

pub fn with_multi_line(self, multi_line: bool) -> Self

Set whether this EditField uses multi-line mode

This method does two things:

• Changes the text class (see Self::with_class)
• Changes the vertical height allocation (see Self::with_lines)

pub fn multi_line(&self) -> bool

True if the editor uses multi-line mode

See also: Self::with_multi_line

pub fn with_class(self, class: TextClass) -> Self

Set the text class used

pub fn class(&self) -> TextClass

Get the text class used

pub fn set_lines(&mut self, min_lines: f32, ideal_lines: f32)

Adjust the height allocation

pub fn with_lines(self, min_lines: f32, ideal_lines: f32) -> Self

Adjust the height allocation (inline)

pub fn set_width_em(&mut self, min_em: f32, ideal_em: f32)

Adjust the width allocation

pub fn with_width_em(self, min_em: f32, ideal_em: f32) -> Self

Adjust the width allocation (inline)

pub fn has_edit_focus(&self) -> bool

Get whether the widget has edit focus

This is true when the widget is editable and has keyboard focus.

pub fn has_error(&self) -> bool

Get whether the input state is erroneous

pub fn set_error_state(&mut self, cx: &mut EventState, error_state: bool)

Set the error state

When true, the input field’s background is drawn red. This state is cleared by Self::set_string.

Trait Implementations

impl<G> Clone for EditField<G>

where G: Clone + EditGuard,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<G> Debug for EditField<G>

where G: Debug + EditGuard,

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

Formats the value using the given formatter.

impl<G> Default for EditField<G>

where G: Default + EditGuard,

fn default() -> Self

Returns the “default value” for a type.

impl<G: EditGuard> Events for EditField<G>

const REDRAW_ON_MOUSE_OVER: bool = true

Does this widget have a different appearance on mouse over?

fn mouse_over_icon(&self) -> Option<CursorIcon>

The mouse cursor icon to use on mouse over

fn configure(&mut self, cx: &mut ConfigCx<'_>)

Configure self

fn update(&mut self, cx: &mut ConfigCx<'_>, data: &G::Data)

Update self using input data

fn handle_event( &mut self, cx: &mut EventCx<'_>, data: &G::Data, event: Event<'_>, ) -> IsUsed

Handle an Event

fn handle_messages(&mut self, cx: &mut EventCx<'_>, data: &G::Data)

Handler for messages from children/descendants

fn make_child_id(&mut self, index: usize) -> Id

Make an identifier for a child

fn configure_recurse(&mut self, cx: &mut ConfigCx<'_>, data: &Self::Data)

Configure children

fn update_recurse(&mut self, cx: &mut ConfigCx<'_>, data: &Self::Data)

Update children

fn handle_mouse_over(&mut self, cx: &mut EventCx<'_>, state: bool)

Mouse focus handler

fn handle_scroll( &mut self, cx: &mut EventCx<'_>, data: &Self::Data, scroll: Scroll, )

Handler for scrolling

impl<G: EditGuard> Layout for EditField<G>

fn rect(&self) -> Rect

Get the widget’s region

fn size_rules(&mut self, sizer: SizeCx<'_>, axis: AxisInfo) -> SizeRules

Get size rules for the given axis

fn set_rect(&mut self, cx: &mut ConfigCx<'_>, rect: Rect, hints: AlignHints)

Set size and position

fn draw(&self, draw: DrawCx<'_>)

Draw a widget and its children

fn try_probe(&self, coord: Coord) -> Option<Id>

Probe a coordinate for a widget’s Id

impl<G: EditGuard> Tile for EditField<G>

fn navigable(&self) -> bool

Whether this widget supports navigation focus

fn role(&self, _: &mut dyn RoleCx) -> Role<'_>

Describe the widget’s role

fn probe(&self, _: Coord) -> Id

Probe a coordinate for a widget’s Id

fn as_tile(&self) -> &dyn Tile

Get as a dyn Tile

fn id_ref(&self) -> &Id

Get a reference to the widget’s identifier

fn identify(&self) -> IdentifyWidget<'_>

Return a Display-able widget identifier

fn get_child(&self, index: usize) -> Option<&dyn Tile>

Access a child as a dyn Tile, if available

fn child_indices(&self) -> ChildIndices

Get child indices available to recursion

fn nav_next(&self, reverse: bool, from: Option<usize>) -> Option<usize>

Navigation in spatial order

fn id(&self) -> Id

Get the widget’s identifier

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

Tooltip

fn role_child_properties(&self, cx: &mut dyn RoleCx, index: usize)

Specify additional role properties for child index

fn find_child_index(&self, id: &Id) -> Option<usize>

Find the child which is an ancestor of this id, if any

fn translation(&self, index: usize) -> Offset

Get translation of child index relative to this widget

impl<G: EditGuard> Widget for EditField<G>

type Data = <G as EditGuard>::Data

Input data type

fn as_node<'__a>(&'__a mut self, data: &'__a Self::Data) -> Node<'__a>

Erase type

fn child_node<'__n>( &'__n mut self, data: &'__n Self::Data, index: usize, ) -> Option<Node<'__n>>

Access a child as a Node, if available