Trait InputHandler

pub trait InputHandler {
    // Required methods
    fn selection(&self) -> Selection;
    fn set_selection(&mut self, selection: Selection);
    fn composition_range(&self) -> Option<Range<usize>>;
    fn set_composition_range(&mut self, range: Option<Range<usize>>);
    fn is_char_boundary(&self, i: usize) -> bool;
    fn len(&self) -> usize;
    fn slice(&self, range: Range<usize>) -> Cow<'_, str>;
    fn replace_range(&mut self, range: Range<usize>, text: &str);
    fn hit_test_point(&self, point: Point) -> HitTestPoint;
    fn line_range(&self, index: usize, affinity: Affinity) -> Range<usize>;
    fn bounding_box(&self) -> Option<Rect>;
    fn slice_bounding_box(&self, range: Range<usize>) -> Option<Rect>;
    fn handle_action(&mut self, action: Action);

    // Provided methods
    fn is_empty(&self) -> bool { ... }
    fn utf8_to_utf16(&self, utf8_range: Range<usize>) -> usize { ... }
    fn utf16_to_utf8(&self, utf16_range: Range<usize>) -> usize { ... }
}

A lock on a text field that allows the platform to retrieve state and make edits.

This trait is implemented by the application or UI framework. The platform acquires this lock temporarily to apply edits corresponding to some user input. So long as the InputHandler has not been dropped, the only changes to the document state must come from calls to InputHandler.

Some methods require a mutable lock, as indicated when acquiring the lock with WinHandler::text_input. If a mutable method is called on a immutable lock, InputHandler may panic.

All ranges, lengths, and indices are specified in UTF-8 code units, unless specified otherwise.

Required Methods

fn selection(&self) -> Selection

The document’s current Selection.

If the selection is a vertical caret bar, then range.start == range.end. Both selection.anchor and selection.active must be less than or equal to the value returned from InputHandler::len(), and must land on a extended grapheme cluster boundary in the document.

fn set_selection(&mut self, selection: Selection)

Set the document’s selection.

If the selection is a vertical caret bar, then range.start == range.end. Both selection.anchor and selection.active must be less than or equal to the value returned from InputHandler::len().

Properties of the Selection other than anchor and active may be ignored by the handler.

The set_selection implementation should round up (downstream) both selection.anchor and selection.active to the nearest extended grapheme cluster boundary.

Requires a mutable lock.

fn composition_range(&self) -> Option<Range<usize>>

The current composition region.

This should be Some only if the IME is currently active, in which case it represents the range of text that may be modified by the IME.

Both range.start and range.end must be less than or equal to the value returned from InputHandler::len(), and must land on a extended grapheme cluster boundary in the document.

fn set_composition_range(&mut self, range: Option<Range<usize>>)

Set the composition region.

If this is Some it means that the IME is currently active for this region of the document. If it is None it means that the IME is not currently active.

Both range.start and range.end must be less than or equal to the value returned from InputHandler::len().

The set_selection implementation should round up (downstream) both range.start and range.end to the nearest extended grapheme cluster boundary.

Requires a mutable lock.

fn is_char_boundary(&self, i: usize) -> bool

Check if the provided index is the first byte of a UTF-8 code point sequence, or is the end of the document.

Equivalent in functionality to str::is_char_boundary.

fn len(&self) -> usize

The length of the document in UTF-8 code units.

fn slice(&self, range: Range<usize>) -> Cow<'_, str>

Returns the subslice of the document represented by range.

Panics

Panics if the start or end of the range do not fall on a code point boundary.

fn replace_range(&mut self, range: Range<usize>, text: &str)

Replaces a range of the text document with text.

This method also sets the composition range to None, and updates the selection:

• If both the selection’s anchor and active are < range.start, then nothing is updated. - If both the selection’s anchor and active are > range.end, then subtract range.len() from both, and add text.len().
• If neither of the previous two conditions are true, then set both anchor and active to range.start + text.len().

After the above update, if we increase each end of the selection if necessary to put it on a grapheme cluster boundary.

Requires a mutable lock.

Panics

Panics if either end of the range does not fall on a code point boundary.

fn hit_test_point(&self, point: Point) -> HitTestPoint

Given a Point, determine the corresponding text position.

fn line_range(&self, index: usize, affinity: Affinity) -> Range<usize>

Returns the range, in UTF-8 code units, of the line (soft- or hard-wrapped) containing the byte specified by index.

fn bounding_box(&self) -> Option<Rect>

Returns the bounding box, in window coordinates, of the visible text document.

For instance, a text box’s bounding box would be the rectangle of the border surrounding it, even if the text box is empty. If the text document is completely offscreen, return None.

fn slice_bounding_box(&self, range: Range<usize>) -> Option<Rect>

Returns the bounding box, in window coordinates, of the range of text specified by range.

Ranges will always be equal to or a subrange of some line range returned by InputHandler::line_range. If a range spans multiple lines, slice_bounding_box may panic.

fn handle_action(&mut self, action: Action)

Applies an Action to the text field.

Requires a mutable lock.

Provided Methods

fn is_empty(&self) -> bool

Returns true if the length of the document is 0.

fn utf8_to_utf16(&self, utf8_range: Range<usize>) -> usize

Returns the number of UTF-16 code units in the provided UTF-8 range.

Converts the document into UTF-8, looks up the range specified by utf8_range (in UTF-8 code units), reencodes that substring into UTF-16, and then returns the number of UTF-16 code units in that substring.

This is automatically implemented, but you can override this if you have some faster system to determine string length.

Panics

Panics if the start or end of the range do not fall on a code point boundary.

fn utf16_to_utf8(&self, utf16_range: Range<usize>) -> usize

Returns the number of UTF-8 code units in the provided UTF-16 range.

Converts the document into UTF-16, looks up the range specified by utf16_range (in UTF-16 code units), reencodes that substring into UTF-8, and then returns the number of UTF-8 code units in that substring.

This is automatically implemented, but you can override this if you have some faster system to determine string length.

Implementors