Trait TextInputDocument 

pub trait TextInputDocument {
    // Required methods
    fn char_count(&self) -> Option<usize>;
    fn text_in(&self, range: Range<usize>) -> Option<String>;
    fn selection(&self) -> Option<Range<usize>>;
    fn caret(&self) -> Option<usize>;
    fn composition_range(&self) -> Option<Range<usize>>;
    fn first_line_rect(&self, range: Range<usize>) -> Option<FirstLineRect>;
    fn offset_at_point(&self, window_point: Point) -> Option<usize>;
    fn visible_text_rect(&self) -> Option<Rect>;
    fn is_editable(&self) -> bool;
    fn is_secure(&self) -> bool;
    fn writing_tools_allowed(&self) -> bool;
    fn utf16_index(&self) -> Option<Rc<Utf16Index>>;

    // Provided methods
    fn is_available(&self) -> bool { ... }
    fn char_to_utf16(&self, char_offset: usize) -> Option<usize> { ... }
    fn utf16_to_char(&self, utf16_offset: usize) -> Option<usize> { ... }
    fn char_range_to_utf16(&self, range: Range<usize>) -> Option<Range<usize>> { ... }
    fn utf16_range_to_chars(&self, range: Range<usize>) -> Option<Range<usize>> { ... }
    fn flush_pending_input(&self) -> bool { ... }
    fn revisions(&self) -> Option<InputRevisions> { ... }
    fn text_changed_since(&self, revision: u64) -> Option<TextChanged> { ... }
}

A text widget’s document, as a platform’s text input system reads it.

See the module documentation for the offsets (characters), the coordinates (window-logical) and what None means. Object-safe: a bridge holds &dyn TextInputDocument for whichever widget has focus.

Required Methods

fn char_count(&self) -> Option<usize>

The length of the document, in characters.

fn text_in(&self, range: Range<usize>) -> Option<String>

The text of range, clamped to the document.

In the document’s own character space: a paragraph break is one \n, a line break inside a paragraph is U+2028, an embedded object (an image, a table’s anchor) is its U+FFFC, so offsets into the answer are offsets into the document. None for a secure field, whatever its reveal state: its text does not leave it.

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

The selection, lowest offset first, whichever end the caret is at. An empty range is a caret with nothing selected.

fn caret(&self) -> Option<usize>

The caret: the end of the selection that moves.

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

The range the input method’s composition occupies, while one is in progress: its preedit, inserted tentatively in the document (macOS calls it marked text). None when nothing is being composed.

fn first_line_rect(&self, range: Range<usize>) -> Option<FirstLineRect>

Where the first line of range is drawn, and which characters of range that line holds.

range is clamped to the document. A range that wraps onto later lines answers for its first line only, and covered ends where that line does, so a caller wanting every line asks again from there. For a non-empty range covered is never empty, so such a walk always advances. An empty range answers with the caret rectangle at its offset.

A secure field that shows nothing at all (no echo) answers every range with the same rectangle, at the start of its empty line, covering the whole range: its geometry would otherwise tell the text’s length.

None before the widget’s first layout.

fn offset_at_point(&self, window_point: Point) -> Option<usize>

The character offset nearest window_point.

None outside the visible_text_rect, and for a secure field that shows nothing. Inside it, a point beside a line answers that line’s nearest end, and a point below the last line the end of the document.

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

The rectangle the widget shows its text in, the part of the document that is on screen.

fn is_editable(&self) -> bool

Does the widget take text? false for a read-only one, which refuses an input-system commit, and while the widget is busy.

fn is_secure(&self) -> bool

Is this a secure field, a password? Its text is never given out (see text_in), and a bridge offers it none of the features that would read it or write into it from outside the keyboard. true while the widget is busy, the cautious answer.

fn writing_tools_allowed(&self) -> bool

May the system’s Writing Tools read and replace this widget’s text? The application’s writing_tools setting; always false for a secure field, and while the widget is busy.

fn utf16_index(&self) -> Option<Rc<Utf16Index>>

The UTF-16 index of the document as it stands, for converting offsets.

Built once per change of the document’s text and shared until the next, so a caller converting several offsets for one question asks for it once. The conversion methods below go through it.

Provided Methods

fn is_available(&self) -> bool

Can the document answer now without changing anything? Asking changes nothing, and when the answer is true neither do the queries that follow, until the application runs again: they insert no typing, run no callback and request no frame.

false while the widget is in the middle of its own work, and while it holds typing not yet inserted, which a query would insert first (see the module documentation), firing the application’s change callbacks. A bridge called where application code must not run (Windows asks from inside a window procedure, ahead of winit) asks it first and answers as if there were no document when it is false. None of the other queries can serve as this question.

true by default: a document that batches nothing and never holds its state across a call into the platform answers every query or None, changing nothing.

fn char_to_utf16(&self, char_offset: usize) -> Option<usize>

A character offset as a UTF-16 offset. See Utf16Index::char_to_utf16.

fn utf16_to_char(&self, utf16_offset: usize) -> Option<usize>

A UTF-16 offset as a character offset. See Utf16Index::utf16_to_char.

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

A character range as a UTF-16 range. See Utf16Index::char_range_to_utf16.

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

A UTF-16 range as a character range. See Utf16Index::utf16_range_to_chars.

fn flush_pending_input(&self) -> bool

Insert typing the widget batched for its next frame, now, firing what its frame tick would (the change callbacks, the arrivals report). Returns whether anything was inserted.

Call it only where a change may be reported: from the application’s handling of an event, never inside a platform lock nor ahead of the toolkit in a window procedure. After it, is_available answers true unless the widget is busy. false by default: a document that batches nothing has nothing to insert.

fn revisions(&self) -> Option<InputRevisions>

The document’s revisions: of its text, its selection and its layout. Each grows whenever the thing it counts changes, and never goes back.

A platform bridge keeps the revisions it last reported and asks again after every event: what grew is what it reports (OnTextChange, OnSelectionChange, OnLayoutChange on Windows). None by default, and while the widget is busy: the bridge then compares the text itself.

fn text_changed_since(&self, revision: u64) -> Option<TextChanged>

What changed in the text since text revision revision, merged into one range, and what caused it. Ask it only when revisions says the text revision grew.

None when the widget no longer knows (the revision is too old, or a change came with no range): the caller treats the whole text as changed. None by default.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors