Struct EditBox 

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

A text-edit box

A single- or multi-line editor for unformatted text. See also notes on EditField.

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

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.

kas::messages::SetScrollOffset may be used to set the scroll offset.

Implementations

impl<G: EditGuard> EditBox<G>

pub fn new(guard: G) -> Self

Construct an EditBox with an EditGuard

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

Clear text contents and undo history

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 set_str(&mut self, cx: &mut EventState, text: &str)

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

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

Set text contents from a String

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

This method does not call action handlers on the EditGuard.

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

Replace selected text

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

pub fn guard(&self) -> &G

Access the edit guard

pub fn guard_mut(&mut self) -> &mut G

Access the edit guard mutably

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

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

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

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

Construct a read-only EditBox 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, ) -> EditBox<ParseGuard<A, T>>

Construct an EditBox 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, ) -> EditBox<InstantParseGuard<A, T>>

Construct an EditBox 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> EditBox<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> EditBox<G>

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

Set the initial text (inline)

This method should only be used on a new EditBox.

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

Set whether this widget is editable (inline)

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

Set whether this EditBox uses multi-line mode

This setting has two effects: the vertical size allocation is increased and wrapping is enabled if true. Default: false.

This method is ineffective if the text class is set by Self::with_class to anything other than TextClass::Editor.

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 EditBox<G>

where G: Debug + EditGuard,

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

Formats the value using the given formatter.

impl<G> Default for EditBox<G>

where G: Default + EditGuard,

fn default() -> Self

Returns the “default value” for a type.

impl<G: EditGuard> Deref for EditBox<G>

type Target = Editor

The resulting type after dereferencing.

fn deref(&self) -> &Editor

Dereferences the value.

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

fn deref_mut(&mut self) -> &mut Editor

Mutably dereferences the value.

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

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

Probe a coordinate for a widget’s Id

fn handle_event( &mut self, cx: &mut EventCx<'_>, _: &Self::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 handle_resize( &mut self, cx: &mut ConfigCx<'_>, _: &Self::Data, ) -> Option<ActionResize>

Handler for resize requests

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

Handler for scrolling

const REDRAW_ON_MOUSE_OVER: bool = false

Does this widget have a different appearance on mouse over?

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

The mouse pointer icon to use on mouse over

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

Make an identifier for a child

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

Configure self

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

Configure self (post-child-configuration actions)

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

Update self using input data

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

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

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<'_>, outer_rect: Rect, hints: AlignHints)

Set size and position

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

Draw a widget and its children

fn rect(&self) -> Rect

Get the widget’s region

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

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

Tooltip

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

Describe the widget’s role

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

Get translation of child index relative to this widget

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

Whether this widget supports navigation focus

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

impl<G: EditGuard> Widget for EditBox<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