Struct kas_widgets::edit::EditField

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

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

This widget implements the mechanics of text layout and event handling. If you want a box with a border, use EditBox instead.

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.

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

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 set_outer_rect(&mut self, outer_rect: Rect, style: FrameStyle)

Set outer rect

Optionally, call this immediately after Self::set_rect with the “outer” rect and frame style. In this case, a frame will be drawn using this outer_rect and style. The advantages are:

• The “error state” background can correctly fill the frame
• Clicks on the frame get registered as clicks on self

Any other widgets painted over the outer_rect should be drawn after the EditField.

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: i32, ideal_lines: i32)

Adjust the height allocation

pub fn with_lines(self, min_lines: i32, ideal_lines: i32) -> 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, error_state: bool) -> Action

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 copy 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>

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

Is this widget navigable via Tab key?

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

Mouse focus handler

fn steal_event( &mut self, _: &mut EventCx<'_>, _: &Self::Data, _: &Id, _: &Event ) -> IsUsed

Potentially steal an event before it reaches a child

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

Handler for messages from children/descendants

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

Handler for scrolling

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

fn get_str(&self) -> &str

Get text by reference

fn get_string(&self) -> String

Get text as a String

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

fn set_string(&mut self, string: String) -> Action

Set text from a string

fn set_str(&mut self, text: &str) -> Action

Set text from a &str

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

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)

Set size and position

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

Translate a coordinate to an Id

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

Draw a widget and its children

fn as_layout(&self) -> &dyn Layout

Get as a dyn Layout

fn id_ref(&self) -> &Id

Get the widget’s identifier

fn rect(&self) -> Rect

Get the widget’s region, relative to its parent.

fn widget_name(&self) -> &'static str

Get the name of the widget struct

fn num_children(&self) -> usize

Get the number of child widgets

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

Access a child as a dyn Layout

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

Navigation in spatial order

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

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

fn translation(&self) -> Offset

Get translation of children relative to this widget

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

fn scroll_axes(&self, size: Size) -> (bool, bool)

Given size size, returns whether (horiz, vert) scrolling is required

fn max_scroll_offset(&self) -> Offset

Get the maximum scroll offset

fn scroll_offset(&self) -> Offset

Get the current scroll offset

fn set_scroll_offset(&mut self, cx: &mut EventCx<'_>, offset: Offset) -> Offset

Set the scroll offset

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

fn to_string(&self) -> String

Converts the given value to a String.

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 for_child_node( &mut self, data: &Self::Data, index: usize, closure: Box<dyn FnOnce(Node<'_>) + '_> )

Call closure on child with given index, if index < self.num_children().