Struct kas_widgets::edit::EditField

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

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

This widget implements the mechanics of text layout and event handling. It does not draw any background (even to indicate an error state) or borders (even to indicate focus), thus usually it is better to use a derived type like 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 EditField<()>

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

Construct an EditField with the given inital text

pub fn empty() -> Self

Construct an empty EditField

pub fn with_guard<G: EditGuard>(self, guard: G) -> EditField<G>

Set an EditGuard

Technically, this consumes self and reconstructs another EditField with a different parameterisation.

This method calls EditGuard::update after applying guard to self and discards any message emitted.

pub fn on_activate<F: FnMut(&mut EventMgr<'_>, &str) -> Response + 'static>( self, f: F ) -> EditField<GuardActivate<F>>

Set a guard function, called on activation

The closure f is called when the EditField is activated (when the “enter” key is pressed).

This method is a parametisation of EditField::with_guard. Any guard previously assigned to the EditField will be replaced.

pub fn on_afl<F: FnMut(&mut EventMgr<'_>, &str) + 'static>( self, f: F ) -> EditField<GuardAFL<F>>

Set a guard function, called on activation and input-focus lost

The closure f is called when the EditField is activated (when the “enter” key is pressed) and when keyboard focus is lost.

This method is a parametisation of EditField::with_guard. Any guard previously assigned to the EditField will be replaced.

pub fn on_edit<F: FnMut(&mut EventMgr<'_>, &str) + 'static>( self, f: F ) -> EditField<GuardEdit<F>>

Set a guard function, called on edit

The closure f is called when the EditField is edited by the user.

This method is a parametisation of EditField::with_guard. Any guard previously assigned to the EditField will be replaced.

pub fn on_update<F: FnMut(&str) + 'static>( self, f: F ) -> EditField<GuardUpdate<F>>

Set a guard function, called on update

The closure f is called when the EditField is updated (by the user or programmatically). It is also called immediately by this method.

This method is a parametisation of EditField::with_guard. Any guard previously assigned to the EditField will be replaced.

impl<G: EditGuard> EditField<G>

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

Get whether the widget currently has keyboard input focus

pub fn has_error(&self) -> bool

Get whether the input state is erroneous

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

Set the error state

When true, the input field’s background is drawn red.

Trait Implementations

impl<G: Clone + EditGuard> Clone for EditField<G>

fn clone(&self) -> EditField<G>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<G: Debug + EditGuard> Debug for EditField<G>

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> 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, size_mgr: SizeMgr<'_>, axis: AxisInfo) -> SizeRules

Get size rules for the given axis

fn set_rect(&mut self, mgr: &mut ConfigMgr<'_>, rect: Rect)

Set size and position

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

Draw a widget and its children

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

Translate a coordinate to a WidgetId

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, mgr: &mut EventMgr<'_>, offset: Offset) -> Offset

Set the scroll offset

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

fn handle_event(&mut self, mgr: &mut EventMgr<'_>, event: Event) -> Response

Handle an Event sent to this widget

fn pre_configure(&mut self, _: &mut ConfigMgr<'_>, id: WidgetId)

Pre-configuration

fn navigable(&self) -> bool

Is this widget navigable via Tab key?

fn configure(&mut self, mgr: &mut ConfigMgr<'_>)

Configure widget

fn translation(&self) -> Offset

Get translation of children relative to this widget

fn nav_next( &mut self, mgr: &mut ConfigMgr<'_>, reverse: bool, from: Option<usize> ) -> Option<usize>

Navigation in spatial order

fn steal_event( &mut self, mgr: &mut EventMgr<'_>, id: &WidgetId, event: &Event ) -> Response

Potentially steal an event before it reaches a child

fn handle_unused(&mut self, mgr: &mut EventMgr<'_>, event: Event) -> Response

Handle an event sent to child index but left unhandled

fn handle_message(&mut self, mgr: &mut EventMgr<'_>)

Handler for messages from children/descendants

fn handle_scroll(&mut self, mgr: &mut EventMgr<'_>, scroll: Scroll)

Handler for scrolling

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

fn num_children(&self) -> usize

Get the number of child widgets

fn get_child(&self, _index: usize) -> Option<&dyn Widget>

Get a reference to a child widget by index, or None if the index is out of bounds.

fn get_child_mut(&mut self, _index: usize) -> Option<&mut dyn Widget>

Mutable variant of get

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

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

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

Make an identifier for a child

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

fn id_ref(&self) -> &WidgetId

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 as_widget(&self) -> &dyn Widget

Erase type

fn as_widget_mut(&mut self) -> &mut dyn Widget

Erase type