Struct kas_widgets::edit::EditField
source · pub struct EditField<G: EditGuard = DefaultGuard<()>> {
pub guard: G,
/* private fields */
}
Expand description
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§
source§impl<A: 'static> EditField<DefaultGuard<A>>
impl<A: 'static> EditField<DefaultGuard<A>>
sourcepub fn text<S: ToString>(text: S) -> Self
pub fn text<S: ToString>(text: S) -> Self
Construct an EditField
with the given inital text
(no event handling)
sourcepub fn string(
value_fn: impl Fn(&A) -> String + 'static
) -> EditField<StringGuard<A>>
pub fn string( value_fn: impl Fn(&A) -> String + 'static ) -> EditField<StringGuard<A>>
Construct a read-only EditField
displaying some String
value
sourcepub 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>>
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.
sourcepub 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>>
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
.
source§impl<A: 'static> EditField<StringGuard<A>>
impl<A: 'static> EditField<StringGuard<A>>
sourcepub fn with_msg<M>(self, msg_fn: impl Fn(&str) -> M + 'static) -> Selfwhere
M: Debug + 'static,
pub fn with_msg<M>(self, msg_fn: impl Fn(&str) -> M + 'static) -> Selfwhere
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
).
source§impl<G: EditGuard> EditField<G>
impl<G: EditGuard> EditField<G>
sourcepub fn set_outer_rect(&mut self, outer_rect: Rect, style: FrameStyle)
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
.
sourcepub fn with_text(self, text: impl ToString) -> Self
pub fn with_text(self, text: impl ToString) -> Self
Set the initial text (inline)
This method should only be used on a new EditField
.
sourcepub fn with_editable(self, editable: bool) -> Self
pub fn with_editable(self, editable: bool) -> Self
Set whether this EditField
is editable (inline)
sourcepub fn is_editable(&self) -> bool
pub fn is_editable(&self) -> bool
Get whether this EditField
is editable
sourcepub fn set_editable(&mut self, editable: bool)
pub fn set_editable(&mut self, editable: bool)
Set whether this EditField
is editable
sourcepub fn with_multi_line(self, multi_line: bool) -> Self
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
)
sourcepub fn multi_line(&self) -> bool
pub fn multi_line(&self) -> bool
True if the editor uses multi-line mode
See also: Self::with_multi_line
sourcepub fn with_class(self, class: TextClass) -> Self
pub fn with_class(self, class: TextClass) -> Self
Set the text class used
sourcepub fn with_lines(self, min_lines: i32, ideal_lines: i32) -> Self
pub fn with_lines(self, min_lines: i32, ideal_lines: i32) -> Self
Adjust the height allocation (inline)
sourcepub fn set_width_em(&mut self, min_em: f32, ideal_em: f32)
pub fn set_width_em(&mut self, min_em: f32, ideal_em: f32)
Adjust the width allocation
sourcepub fn with_width_em(self, min_em: f32, ideal_em: f32) -> Self
pub fn with_width_em(self, min_em: f32, ideal_em: f32) -> Self
Adjust the width allocation (inline)
sourcepub fn has_edit_focus(&self) -> bool
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.
sourcepub fn set_error_state(&mut self, error_state: bool) -> Action
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§
source§impl<G: EditGuard> Events for EditField<G>
impl<G: EditGuard> Events for EditField<G>
source§fn update(&mut self, cx: &mut ConfigCx<'_>, data: &G::Data)
fn update(&mut self, cx: &mut ConfigCx<'_>, data: &G::Data)
source§fn handle_hover(&mut self, cx: &mut EventCx<'_>, state: bool) -> IsUsed
fn handle_hover(&mut self, cx: &mut EventCx<'_>, state: bool) -> IsUsed
source§fn steal_event(
&mut self,
_: &mut EventCx<'_>,
_: &Self::Data,
_: &Id,
_: &Event
) -> IsUsed
fn steal_event( &mut self, _: &mut EventCx<'_>, _: &Self::Data, _: &Id, _: &Event ) -> IsUsed
source§fn configure_recurse(&mut self, cx: &mut ConfigCx<'_>, data: &Self::Data)
fn configure_recurse(&mut self, cx: &mut ConfigCx<'_>, data: &Self::Data)
source§fn update_recurse(&mut self, cx: &mut ConfigCx<'_>, data: &Self::Data)
fn update_recurse(&mut self, cx: &mut ConfigCx<'_>, data: &Self::Data)
source§impl<G: EditGuard> Layout for EditField<G>
impl<G: EditGuard> Layout for EditField<G>
source§fn size_rules(&mut self, sizer: SizeCx<'_>, axis: AxisInfo) -> SizeRules
fn size_rules(&mut self, sizer: SizeCx<'_>, axis: AxisInfo) -> SizeRules
source§fn widget_name(&self) -> &'static str
fn widget_name(&self) -> &'static str
source§fn num_children(&self) -> usize
fn num_children(&self) -> usize
source§fn get_child(&self, index: usize) -> Option<&dyn Layout>
fn get_child(&self, index: usize) -> Option<&dyn Layout>
dyn Layout
Read moresource§fn find_child_index(&self, id: &Id) -> Option<usize>
fn find_child_index(&self, id: &Id) -> Option<usize>
id
, if any Read moresource§fn translation(&self) -> Offset
fn translation(&self) -> Offset
source§impl<G: EditGuard> Scrollable for EditField<G>
impl<G: EditGuard> Scrollable for EditField<G>
Auto Trait Implementations§
impl<G> RefUnwindSafe for EditField<G>where
G: RefUnwindSafe,
impl<G = DefaultGuard<()>> !Send for EditField<G>
impl<G = DefaultGuard<()>> !Sync for EditField<G>
impl<G> Unpin for EditField<G>where
G: Unpin,
impl<G> UnwindSafe for EditField<G>where
G: UnwindSafe,
Blanket Implementations§
source§impl<W> AdaptWidget for Wwhere
W: Widget,
impl<W> AdaptWidget for Wwhere
W: Widget,
source§fn on_configure<F>(self, f: F) -> AdaptEvents<Self>
fn on_configure<F>(self, f: F) -> AdaptEvents<Self>
Events::configure
Read moresource§fn on_update<F>(self, f: F) -> AdaptEvents<Self>
fn on_update<F>(self, f: F) -> AdaptEvents<Self>
Events::update
Read moresource§fn on_message<M, H>(self, handler: H) -> AdaptEvents<Self>
fn on_message<M, H>(self, handler: H) -> AdaptEvents<Self>
M
Read moresource§fn on_messages<H>(self, handler: H) -> AdaptEvents<Self>
fn on_messages<H>(self, handler: H) -> AdaptEvents<Self>
source§fn with_min_size_px(self, w: i32, h: i32) -> Reserve<Self>
fn with_min_size_px(self, w: i32, h: i32) -> Reserve<Self>
source§fn with_min_size_em(self, w: f32, h: f32) -> Reserve<Self>
fn with_min_size_em(self, w: f32, h: f32) -> Reserve<Self>
source§fn with_label<D, T>(self, direction: D, label: T) -> WithLabel<Self, D>
fn with_label<D, T>(self, direction: D, label: T) -> WithLabel<Self, D>
source§impl<W> AdaptWidgetAny for W
impl<W> AdaptWidgetAny for W
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
§impl<S, T> Cast<T> for Swhere
T: Conv<S>,
impl<S, T> Cast<T> for Swhere
T: Conv<S>,
§impl<S, T> CastApprox<T> for Swhere
T: ConvApprox<S>,
impl<S, T> CastApprox<T> for Swhere
T: ConvApprox<S>,
§fn try_cast_approx(self) -> Result<T, Error>
fn try_cast_approx(self) -> Result<T, Error>
§fn cast_approx(self) -> T
fn cast_approx(self) -> T
§impl<S, T> CastFloat<T> for Swhere
T: ConvFloat<S>,
impl<S, T> CastFloat<T> for Swhere
T: ConvFloat<S>,
§fn cast_trunc(self) -> T
fn cast_trunc(self) -> T
§fn cast_nearest(self) -> T
fn cast_nearest(self) -> T
§fn cast_floor(self) -> T
fn cast_floor(self) -> T
§fn try_cast_trunc(self) -> Result<T, Error>
fn try_cast_trunc(self) -> Result<T, Error>
§fn try_cast_nearest(self) -> Result<T, Error>
fn try_cast_nearest(self) -> Result<T, Error>
§fn try_cast_floor(self) -> Result<T, Error>
fn try_cast_floor(self) -> Result<T, Error>
§fn try_cast_ceil(self) -> Result<T, Error>
fn try_cast_ceil(self) -> Result<T, Error>
source§impl<W> LayoutExt for W
impl<W> LayoutExt for W
source§fn identify(&self) -> IdentifyWidget<'_>
fn identify(&self) -> IdentifyWidget<'_>
source§fn is_strict_ancestor_of(&self, id: &Id) -> bool
fn is_strict_ancestor_of(&self, id: &Id) -> bool
id
is not self and is a descendant Read more