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 when this widget is editable]. This triggers the action handlers EditGuard::edit followed by EditGuard::activate.

Special behaviour

This is a Viewport widget.

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 call_guard_activate(&mut self, cx: &mut EventCx<'_>, data: &G::Data)

Call the EditGuard’s activate method

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

Call the EditGuard’s edit method

This call also clears the error state (see Editor::set_error).

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 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 with_class(self, class: TextClass) -> Self

Set 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)

Methods from Deref<Target = Editor>

pub fn id_ref(&self) -> &Id

Get a reference to the widget’s identifier

pub fn id(&self) -> Id

Get the widget’s identifier

pub fn as_str(&self) -> &str

Get text contents

pub fn clone_string(&self) -> String

Get the text contents as a String

pub fn pre_commit(&mut self)

Commit outstanding changes to the undo history

Call this before changing the text with set_str or set_string to commit changes to the undo history.

pub fn clear(&mut self, cx: &mut EventState)

Clear text contents and undo history

This method does not call any EditGuard actions; consider also calling EditField::call_guard_edit.

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

Set text contents from a str

This does not interact with undo history; see also Self::clear, Self::pre_commit.

This method does not call any EditGuard actions; consider also calling EditField::call_guard_edit.

Returns true if the text may have changed.

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

Set text contents from a String

This does not interact with undo history or call action handlers on the guard.

This method clears the error state but does not call any EditGuard actions; consider also calling EditField::call_guard_edit.

Returns true if the text is ready and may have changed.

pub fn replace_selected_text(&mut self, cx: &mut EventState, text: &str) -> bool

Replace selected text

This does not interact with undo history or call action handlers on the guard.

This method clears the error state but does not call any EditGuard actions; consider also calling EditField::call_guard_edit.

Returns true if the text is ready and may have changed.

pub fn cursor_range(&self) -> CursorRange

Access the cursor index / selection range

pub fn set_cursor_range(&mut self, range: impl Into<CursorRange>)

Set the cursor index / range

This does not interact with undo history or call action handlers on the guard.

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 multi_line(&self) -> bool

True if the editor uses multi-line mode

pub fn class(&self) -> TextClass

Get the text class used

pub fn has_input_focus(&self) -> bool

Get whether the widget has input focus

This is true when the widget is has keyboard or IME focus.

pub fn has_error(&self) -> bool

Get whether the input state is erroneous

pub fn set_error( &mut self, cx: &mut EventState, message: Option<Cow<'static, str>>, )

Mark the input as erroneous with an optional message

This state should be set from EditGuard::edit when appropriate. The state is cleared immediately before calling EditGuard::edit and also in case a text is directly assigned (e.g. using Self::set_string).

When set, the input field’s background is drawn red. If a message is supplied, then a tooltip will be available on mouse-hover.

Trait Implementations

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> Deref for EditField<G>

type Target = Editor

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

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

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

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 probe(&self, _: Coord) -> Id

Probe a coordinate for a widget’s Id

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

The mouse pointer 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 post_configure(&mut self, cx: &mut ConfigCx<'_>)

Configure self (post-child-configuration actions)

fn recurse_indices(&self) -> ChildIndices

Recursion control

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

Mouse focus handler

fn child_nav_focus(&mut self, cx: &mut EventCx<'_>, id: Id)

Notification that a child received navigation focus

fn handle_resize( &mut self, cx: &mut ConfigCx<'_>, data: &Self::Data, ) -> Option<ActionResize>

Handler for resize requests

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, cx: &mut SizeCx<'_>, axis: AxisInfo) -> SizeRules

Calculate size requirements for an axis

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

Set size and position

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

Draw a widget and its children

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

fn navigable(&self) -> bool

Whether this widget supports navigation focus

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

Tooltip

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

Describe the widget’s role

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 try_probe(&self, coord: Coord) -> Option<Id>

Probe a coordinate for a widget’s Id

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 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> Viewport for EditField<G>

fn content_size(&self) -> Size

Get content size

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

Draw with a scroll offset

fn try_probe_with_offset(&self, coord: Coord, offset: Offset) -> Option<Id>

Probe a coordinate for a widget’s Id

fn set_offset(&mut self, cx: &mut SizeCx<'_>, viewport: Rect, offset: Offset)

Set the scroll offset

fn update_offset( &mut self, cx: &mut ConfigCx<'_>, data: &Self::Data, viewport: Rect, offset: Offset, )

Update the scroll offset

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