Struct TextArea 

pub struct TextArea<M, D = TextBuffer> { /* private fields */ }

Lines of text somebody edits, drawn from a TextDocument.

Blinking

As TextInput: the caret blinks only while the widget has focus, and an unfocused editor asks for no frames.

Focus

No focus ring. The caret is the sign that the keyboard goes here, and a ring around a widget the size of a window would frame the whole window.

Moving by word

Ctrl and an arrow move by word, and so does Option on a Mac; Command and an arrow go to the start or end of the line, and with Home or End to the start or end of the document. Shift extends with all of them.

Selecting

A press places the caret, a second on the same spot takes the word under it, and a third takes the line — its text, not the newline after it, so deleting a line taken that way leaves an empty one rather than pulling the next one up. A fourth press starts the count again. Dragging extends from where the press landed, and Shift extends with the arrows, Home, End and a click. The word rule is TextInput’s, shared so that a double-click takes the same run of characters in a field as in an editor.

Implementations

impl<M> TextArea<M, TextBuffer>

pub fn from_text(text: &str) -> Self

An editor over a buffer holding text.

pub fn text(&self) -> String

The whole text of the buffer.

pub fn set_text(&mut self, text: &str)

Replaces the text, putting the caret at the start. Silent, and the undo history goes with the old text.

impl<M, D: TextDocument> TextArea<M, D>

pub fn new(doc: D) -> Self

An editor over doc.

pub fn with_change(self, message: M) -> Self

Sets the message emitted after every edit a person makes.

pub fn with_clipboard(self, message: fn(ClipboardRequest) -> M) -> Self

Sets how clipboard requests reach the application. Without it, copy, cut and paste do nothing.

pub fn with_style(self, style: TextStyle) -> Self

Sets the font and size.

pub fn with_size(self, size_px: u16) -> Self

Sets the size, keeping the font.

pub fn with_gutter(self, gutter: bool) -> Self

Whether to number the lines down the left.

pub fn with_tab_width(self, columns: u8) -> Self

Sets how many columns apart the tab stops are; four unless told. A column is a space wide, and at least one.

pub fn with_read_only(self, read_only: bool) -> Self

Shows the text and places a caret in it, but changes nothing.

pub fn with_smooth_scroll(self, smooth: bool) -> Self

Whether the wheel moves the text a pixel at a time, as a trackpad reports it, rather than a whole line once a line’s worth has built up. Off unless told. A fast wheel goes as far either way.

pub fn document(&self) -> Ref<'_, D>

The document.

pub fn document_mut(&mut self) -> &mut D

The document, to change. Silent; the caret is clamped to whatever the document says next time it is used.

pub fn set_document(&mut self, doc: D)

Replaces the document, putting the caret at the start.

pub const fn style(&self) -> TextStyle

The font and size.

pub fn set_style(&mut self, style: TextStyle)

Replaces the font and size. The measured width of the text goes with the old font, and is taken again as the lines are drawn.

pub const fn gutter(&self) -> bool

Whether the lines are numbered.

pub fn set_gutter(&mut self, gutter: bool)

Numbers the lines, or stops.

pub const fn tab_width(&self) -> u8

How many columns apart the tab stops are.

pub fn set_tab_width(&mut self, columns: u8)

Moves the tab stops columns apart, at least one. Tabs are part of how wide a line is, so that is measured again as the lines are drawn.

pub const fn is_read_only(&self) -> bool

Whether editing is off.

pub fn set_read_only(&mut self, read_only: bool)

Turns editing off or on.

pub const fn smooth_scroll(&self) -> bool

Whether the wheel scrolls a pixel at a time.

pub fn set_smooth_scroll(&mut self, smooth: bool)

Scrolls by the pixel, or by the line. Turned off, the view settles on the line it was part way through.

pub const fn caret(&self) -> Pos

Where the caret is.

pub fn set_caret(&mut self, pos: Pos)

Puts the caret at pos, clamped to the document, and clears the selection. The view follows on the next event or paint.

pub fn selection(&self) -> Option<(Pos, Pos)>

The selection as (from, to), or None if nothing is selected.

pub fn select_all(&mut self)

Selects everything.

pub fn selected_text(&self) -> Option<String>

The selected text, lines joined by \n, or None if nothing is selected.

pub fn insert_text(&mut self, text: &str)

Replaces the selection, or inserts at the caret, and leaves the caret after the text. Silent: this is how an application answers a ClipboardRequest::Paste, and it knows it did.

pub const fn top(&self) -> usize

First line drawn.

pub fn set_top(&mut self, line: usize)

Scrolls so line is the first drawn, clamped to the lines known.

pub const fn top_px(&self) -> i32

Pixels of the first line drawn that are scrolled up out of view: 0 unless smooth_scroll is on, and less than a row.

pub fn visible_rows(&self) -> usize

Whole rows the last paint had room for; 0 before the first.

pub fn go_to(&mut self, line: usize)

Puts the caret at the start of 0-based line, clamped to the lines known, and scrolls so the line sits in the middle of the view — as far as the last paint’s row count can say where the middle is.

pub fn select_range(&mut self, from: Pos, to: Pos)

Selects [from, to) with the caret at to, both clamped to the document, and scrolls the selection into view: centred on its first line if that was off screen, and sideways on the next paint, which has the fonts to measure it with. What a find lands on. Silent.

pub fn scroll_x(&self) -> i32

Pixels the text is scrolled sideways.

Trait Implementations

impl<M> Default for TextArea<M, TextBuffer>

fn default() -> Self

Returns the “default value” for a type.

impl<M, D: TextDocument> Describe for TextArea<M, D>

const KIND: &'static str = "text-area"

The name a form file uses for this widget. Kebab-case.

const DOC: &'static str = "Lines of text somebody edits."

One line saying what this widget is, for somebody choosing one.

const GROUP: Group = Group::Input

Which shelf of the catalogue this belongs on.

const ICON: &'static Icon

The widget’s glyph: a small portrait of the thing, for a palette to draw beside — or instead of — its name.

const PROPERTIES: &'static [Property]

Every property, in the order an inspector should show them.

fn get(&self, name: &str) -> Option<Value>

The current value.

fn apply(&mut self, name: &str, value: Value) -> Result<(), Mismatch>

Applies a value, reporting only what went wrong.

fn set(&mut self, name: &str, value: Value) -> Result<(), PropertyError>

Applies a value, reporting what went wrong and where.

impl<M: Clone + 'static, D: TextDocument> Widget<M> for TextArea<M, D>

fn snap(&mut self, now_ms: u64) -> Animation

Blinking is a schedule, not a motion; see TextInput.

fn describe(&self) -> Option<&dyn DynDescribe>

This widget’s property description, if it has one.

fn describe_mut(&mut self) -> Option<&mut dyn DynDescribe>

The mutable half of describe.

fn measure(&self, ctx: &mut MeasureCtx<'_>, _offered: Offer) -> Measured

How big this widget would like to be, given what the caller can promise.

fn paint(&self, ctx: &mut PaintCtx<'_>, canvas: &mut Pen<'_>)

Draws into canvas, which is already clipped to this widget’s bounds intersected with the damage region being repainted.

fn on_event(&mut self, event: &Event<'_>, ctx: &mut EventCtx<'_, M>) -> Handled

Reacts to an event routed to this widget.

fn accepts_pointer(&self) -> bool

Returns true if the pointer can hit this widget.

fn focusable(&self) -> bool

Returns true if this widget can take keyboard focus.

fn animate(&mut self, now_ms: u64) -> Animation

Advances time-based state. Called only while this widget has asked to animate — see EventCtx::request_animation — and stops being called the moment it answers Wake::Never.

fn preserves_focus(&self) -> bool

Returns true if a press on this widget should leave focus exactly where it is.