Struct TextEditor 

pub struct TextEditor { /* private fields */ }

Editable text: a Paragraph with a TextSelection, typing, deletion and input-method composition.

Every change to the text (typing, deleting, composing, a new style, undo and redo) lays the text out again, which allocates; moving the caret, drawing paragraph and the geometry queries do not (except the move that keeps a preedit as text, an edit). A change that fails leaves the editor as it was.

Input methods (IME) compose text before committing it: forward their preedit to set_composition (an empty preedit removes it) and the committed text to insert; underline for_each_composition_rect and report ime_area to the window so the candidate list appears next to the text. Typing replaces an active preedit, deleting cancels it (restoring any selection it replaced), and moving the caret keeps it as ordinary text.

Edits can be undone and redone (undo, redo): typing is one step per word, and Backspace or Delete pressed repeatedly one step, until the caret moves. A preedit is not an edit until it is committed or kept. Up to 100 steps are kept.

Not yet supported: styled spans, a maximum length.

Implementations

impl TextEditor

pub fn new( system: &mut TextSystem, text: impl Into<String>, style: ParagraphStyle, ) -> Result<Self, ParagraphError>

An editor holding text set in style, with the caret at the end.

Errors

ParagraphError if style is out of range or a font cannot be read.

pub fn text(&self) -> &str

The text, including any preedit text being composed.

pub fn style(&self) -> &ParagraphStyle

The style the text is set in.

pub fn paragraph(&self) -> &Paragraph

The laid-out text, to draw and to hit-test.

pub fn selection(&self) -> TextSelection

The caret or selected range.

pub fn selected_text(&self) -> &str

The selected text (empty for a caret), for copying.

pub fn composition(&self) -> Option<Range<usize>>

The byte range of the preedit text an input method is composing, if any.

pub fn shows_caret(&self) -> bool

Whether to draw the caret: an input method can hide it while it composes.

pub fn set_selection(&mut self, selection: TextSelection)

Selects selection (clamped to this text), for example from a click or a drag. A preedit being composed stays as ordinary text.

pub fn move_caret(&mut self, motion: Motion, extend: bool)

Moves the caret by motion, or with extend moves the selection’s focus (shift + navigation keys). A preedit being composed stays as ordinary text.

pub fn insert( &mut self, system: &mut TextSystem, text: &str, ) -> Result<(), ParagraphError>

Types text (a key press, a paste or committed input-method text): it replaces the preedit being composed if there is one, otherwise the selection, and the caret follows it.

Errors

ParagraphError::UnreadableFont if a font chosen for the new text cannot be read.

pub fn paste( &mut self, system: &mut TextSystem, text: &str, ) -> Result<(), ParagraphError>

Inserts text as insert does, as an undo step of its own: for a paste or a drop, rather than typing.

Errors

ParagraphError::UnreadableFont if a font chosen for the new text cannot be read.

pub fn delete( &mut self, system: &mut TextSystem, motion: Motion, ) -> Result<(), ParagraphError>

Deletes the selection, or with a caret the text between it and where motion would move it: Previous for Backspace (one character, so a combining accent comes off its letter; a line break or emoji goes whole), Next for Delete, PreviousWord and NextWord with Ctrl, LineStart to delete to the start of the line. A preedit being composed is removed instead.

Errors

ParagraphError::UnreadableFont if a font chosen for the remaining text cannot be read.

pub fn undo(&mut self, system: &mut TextSystem) -> Result<bool, ParagraphError>

Takes back the last edit, selecting what was selected before it; false if there was none. A preedit being composed is removed first.

Errors

ParagraphError::UnreadableFont if a font cannot be read; the edit stays undoable.

pub fn redo(&mut self, system: &mut TextSystem) -> Result<bool, ParagraphError>

Makes the last undone edit again, selecting what it left selected; false if there was none. A new edit makes undone ones unavailable.

Errors

ParagraphError::UnreadableFont if a font cannot be read; the edit stays redoable.

pub fn can_undo(&self) -> bool

Whether there is an edit to undo.

pub fn can_redo(&self) -> bool

Whether there is an edit to redo.

pub fn set_text( &mut self, system: &mut TextSystem, text: &str, ) -> Result<(), ParagraphError>

Replaces the whole text with text, the caret at its end, and forgets the edits to undo and redo (as loading a new document does).

Errors

ParagraphError::UnreadableFont if a font chosen for text cannot be read.

pub fn set_style( &mut self, system: &mut TextSystem, style: ParagraphStyle, ) -> Result<(), ParagraphError>

Sets the text in style, keeping the text and the selection.

Errors

ParagraphError if style is out of range or a font cannot be read; the editor keeps its previous style.

pub fn set_width( &mut self, max_width: Option<f32>, ) -> Result<(), ParagraphError>

Wraps the text at max_width pixels (None: only at line breaks) without shaping it again: call when the editor is resized.

Errors

ParagraphError::InvalidWidth if max_width is negative or not finite; nothing changes.

pub fn set_composition( &mut self, system: &mut TextSystem, text: &str, cursor: Option<Range<usize>>, ) -> Result<(), ParagraphError>

Shows an input method’s preedit text in place of the selection (or of the previous preedit), with the input method’s cursor (a byte range within text) selected, or the caret hidden for None. An empty text removes the preedit and restores what it replaced: the selected text, selected again, or the caret where it was.

Errors

ParagraphError::InvalidRange if cursor is reversed, outside text or splits a character; ParagraphError::UnreadableFont if a font cannot be read. Nothing changes on error.

pub fn for_each_composition_rect(&self, f: impl FnMut(Rect))

Calls f with each rectangle covering the preedit text (one per line it spans), relative to the paragraph’s top-left corner: draw an underline along their bottoms.

pub fn ime_area(&self) -> Rect

Where an input method should show its candidate window, relative to the paragraph’s top-left corner: around the preedit text while composing, otherwise the caret.

Trait Implementations

impl Debug for TextEditor

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

Formats the value using the given formatter.