Trait TextSurface 

pub trait TextSurface: SurfaceMut {
    // Required methods
    fn width_mode(&self) -> WidthMode;
    fn eaw_wide(&self) -> bool;

    // Provided methods
    fn set_str(
        &mut self,
        pos: impl Into<Position>,
        s: &str,
        style: impl Into<Style>,
    ) -> Position { ... }
    fn set_str_wrap(
        &mut self,
        pos: impl Into<Position>,
        s: &str,
        wrap: WrapMode,
        style: impl Into<Style>,
    ) -> Position { ... }
    fn set_str_rect(
        &mut self,
        rect: impl Into<Rect>,
        s: &str,
        style: impl Into<Style>,
    ) -> Position { ... }
    fn set_str_rect_wrap(
        &mut self,
        rect: impl Into<Rect>,
        s: &str,
        wrap: WrapMode,
        style: impl Into<Style>,
    ) -> Position { ... }
    fn set_str_truncate(
        &mut self,
        pos: impl Into<Position>,
        s: &str,
        tail: &str,
        tail_style: impl Into<Style>,
    ) -> Position { ... }
    fn set_str_rect_truncate(
        &mut self,
        rect: impl Into<Rect>,
        s: &str,
        tail: &str,
        tail_style: impl Into<Style>,
    ) -> Position { ... }
    fn str_width(&self, s: &str) -> u16 { ... }
    fn grapheme_width(&self, g: &str) -> u8 { ... }
    fn grapheme_cells<'a>(
        &self,
        s: &'a str,
    ) -> impl Iterator<Item = (&'a str, u8)> { ... }
}

A SurfaceMut with a text-measurement policy and string-painting helpers.

Implement this for surface types that can accept styled text. The only required decisions are width_mode, which controls how grapheme clusters are measured, and eaw_wide, which controls East-Asian Ambiguous code points.

The default set_str family paints text literally: each grapheme cluster is drawn with the given style and inline SGR / OSC 8 escapes are not interpreted. Use Painter, which is itself a TextSurface, to parse inline style and hyperlink escapes. Newline and carriage return move the paint cursor within the active clip rectangle.

Required Methods

fn width_mode(&self) -> WidthMode

Return the width-measurement mode used when shaping strings.

WidthMode::Wc uses the first code point of each grapheme cluster; WidthMode::Grapheme measures the whole cluster. The selected mode is used by the set_str family and str_width.

This method is pure policy lookup. It should not inspect or mutate the surface contents.

fn eaw_wide(&self) -> bool

Return the East-Asian Ambiguous width policy for this surface.

When true, code points whose East-Asian-Width property is Ambiguous are measured as two cells. When false, they are measured as one. The flag is passed to char_width and grapheme_width by all text operations.

Provided Methods

fn set_str( &mut self, pos: impl Into<Position>, s: &str, style: impl Into<Style>, ) -> Position

Paint s at pos, clipped to the surface bounds.

Every cell painted gets style. This default implementation paints literally: escape sequences in s are drawn as visible characters, not interpreted. For SGR/OSC 8-aware painting that turns inline escapes into styling, wrap the surface in a Painter. Newline moves to the next row at the surface’s left edge; carriage return moves to that left edge on the current row. If a non-zero-width grapheme cluster would cross the right edge, painting stops.

Parameters

• pos — starting cell position.
• s — UTF-8 string to paint. Escape sequences are drawn literally.
• style — style applied to every cell painted in this call.

Returns

The cursor position immediately after the last written cell, or the position where painting stopped. The returned position may be outside the surface when input reaches the bottom edge.

Errors and panics

This method does not return errors and does not intentionally panic.

Usage note

Use set_str_wrap when text should continue on following rows instead of truncating at the right edge.

fn set_str_wrap( &mut self, pos: impl Into<Position>, s: &str, wrap: WrapMode, style: impl Into<Style>, ) -> Position

Paint s at pos with an explicit right-edge behavior.

This is the same operation as set_str, except wrap decides what happens when a non-zero-width grapheme cluster would cross the surface’s right edge: WrapMode::Truncate stops, and WrapMode::Wrap continues at the left edge of the next row until the bottom edge is reached.

Parameters

• pos — starting cell position.
• s — UTF-8 string to paint.
• wrap — wrapping policy at the right edge.
• style — initial style for painted cells.

Returns

The cursor position immediately after the last written cell, or where painting stopped.

Errors and panics

This method does not return errors and does not intentionally panic.

fn set_str_rect( &mut self, rect: impl Into<Rect>, s: &str, style: impl Into<Style>, ) -> Position

Paint s inside rect, clipped to the surface bounds.

Painting starts at rect’s top-left corner and is clipped to rect ∩ self.bounds(). Newline and carriage return use rect’s left edge as the return column. If a non-zero-width grapheme cluster would cross rect’s right edge, painting stops.

Parameters

• rect — clipping rectangle and starting origin.
• s — UTF-8 string to paint.
• style — initial style for painted cells.

Returns

The cursor position immediately after the last written cell, or where painting stopped.

Errors and panics

This method does not return errors and does not intentionally panic.

fn set_str_rect_wrap( &mut self, rect: impl Into<Rect>, s: &str, wrap: WrapMode, style: impl Into<Style>, ) -> Position

Paint s inside rect with an explicit right-edge behavior.

This is the rectangular form of set_str_wrap. WrapMode::Wrap flows to the next row at rect’s left edge; WrapMode::Truncate stops at rect’s right edge.

Parameters

• rect — clipping rectangle and starting origin.
• s — UTF-8 string to paint.
• wrap — wrapping policy at the rectangle’s right edge.
• style — initial style for painted cells.

Returns

The cursor position immediately after the last written cell, or where painting stopped.

Errors and panics

This method does not return errors and does not intentionally panic.

fn set_str_truncate( &mut self, pos: impl Into<Position>, s: &str, tail: &str, tail_style: impl Into<Style>, ) -> Position

Paint s at pos, truncating with a tail indicator on overflow.

When a cluster would cross the surface’s right edge, painting stops and tail is stamped over the trailing columns, ending at the right edge. The tail appears only when s actually overflows. tail is painted with tail_style and may carry inline escape sequences, so it can be a single glyph ("…"), a word (" more"), or a multi-style span. A tail wider than the surface is dropped in favor of a hard truncate.

Parameters

• pos — starting cell position.
• s — UTF-8 string to paint.
• tail — truncation indicator, painted when s overflows.
• tail_style — starting style for the tail.

Returns

The cursor position immediately after the last written cell, or where painting stopped.

Errors and panics

This method does not return errors and does not intentionally panic.

fn set_str_rect_truncate( &mut self, rect: impl Into<Rect>, s: &str, tail: &str, tail_style: impl Into<Style>, ) -> Position

Paint s inside rect, truncating with a tail indicator on overflow.

This is the rectangular form of set_str_truncate: the clip rectangle is rect ∩ self.bounds(), and the tail is stamped at rect’s right edge when the text overflows it.

Parameters

• rect — clipping rectangle and starting origin.
• s — UTF-8 string to paint.
• tail — truncation indicator, painted when s overflows.
• tail_style — starting style for the tail.

Returns

The cursor position immediately after the last written cell, or where painting stopped.

Errors and panics

This method does not return errors and does not intentionally panic.

fn str_width(&self, s: &str) -> u16

Measure the display width of s in terminal columns.

The measurement segments s into grapheme clusters under this surface’s width_mode and eaw_wide policy and sums their widths. Like the default set_str family, this does not interpret inline escape sequences: an SGR or OSC 8 sequence in s is measured as the width of its visible bytes. Use Painter, whose str_width skips recognized escapes, to measure escape-bearing text.

Parameters

• s — string to measure.

Returns

The display width in cells, saturated at u16::MAX.

Errors and panics

This method does not fail or intentionally panic.

fn grapheme_width(&self, g: &str) -> u8

Measure one extended grapheme cluster in cells under this surface’s width mode and East-Asian Ambiguous policy.

Parameters

• g — a single grapheme cluster.

Returns

The cluster width in cells, normally 0, 1, or 2.

Errors and panics

This method does not fail or intentionally panic.

fn grapheme_cells<'a>(&self, s: &'a str) -> impl Iterator<Item = (&'a str, u8)>

Iterate s as (cluster, width) pairs under this surface’s width mode and East-Asian Ambiguous policy.

Parameters

• s — UTF-8 string to segment and measure.

Returns

An iterator yielding borrowed cluster slices and their cell widths.

Errors and panics

This method does not fail or intentionally panic.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl TextSurface for TextBuffer

impl<'s, S: TextSurface + ?Sized> TextSurface for Painter<'s, S>

A Painter is itself a TextSurface whose set_str family recognizes inline SGR and OSC 8 hyperlink sequences, updating the running the running style as the input is parsed. This is the escape-aware counterpart to the literal painting of the default TextSurface methods.

impl<I, O> TextSurface for Screen<I, O>

where I: Input, O: Write,