Struct Painter 

pub struct Painter<'s, S: TextSurface + ?Sized> { /* private fields */ }

Paint styled strings into a TextSurface.

The painter snapshots its target’s WidthMode and eaw_wide policy at construction, both fixed for the painter’s lifetime. It holds no style of its own: each paint call starts with an empty pen over the base style it is given, parses the input’s inline SGR and OSC 8 sequences into that pen, and writes each cell as the pen inherited onto the base. Text is written into the borrowed target surface; dropping a painter has no side effects.

Implementations

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

pub fn new(target: &'s mut S) -> Self

Create a new painter over target.

Parameters

• target — mutable surface receiving painted cells.

Returns

A painter bound to target.

Errors and panics

This constructor does not fail or intentionally panic.

Trait Implementations

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

fn bounds(&self) -> Rect

Return the valid region in this value’s own coordinate space.

fn width(&self) -> u16

Return the width of Self::bounds in terminal cell columns.

fn height(&self) -> u16

Return the height of Self::bounds in terminal cell rows.

fn contains(&self, pos: Position) -> bool

Test whether a position lies inside Self::bounds.

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

fn cell(&self, pos: Position) -> Option<&Cell>

Read the cell at a position.

fn draw<T: SurfaceMut + ?Sized>(&self, target: &mut T, at: Position)

Copy self’s cells into target, mapping the top-left of self.bounds() to at in target coordinates.

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

fn set_cell(&mut self, pos: Position, cell: &Cell)

Place cell at pos. Implementations are responsible for wide-cell semantics (continuation markers, blanking covered cells) and any dirty tracking they care to do. Taking &Cell lets implementations skip the clone when the destination already matches.

fn cell_mut(&mut self, pos: Position) -> Option<&mut Cell>

Mutable handle to the cell at pos. Returns None for out-of-bounds positions.

fn insert_lines(&mut self, y: u16, count: u16, bounds_bottom: u16, fill: &Cell)

Insert n blank rows at y, pushing existing rows down within [y, bounds_bottom). Rows pushed past bounds_bottom are lost. Freed top rows are filled with fill.

fn delete_lines(&mut self, y: u16, count: u16, bounds_bottom: u16, fill: &Cell)

Delete n rows at y, pulling existing rows up within [y, bounds_bottom). The bottom n rows of the window are filled with fill.

fn insert_cells( &mut self, pos: Position, count: u16, bounds_right: u16, fill: &Cell, )

Insert n blank cells at pos, pushing cells in [pos.x, bounds_right) right within row pos.y. Cells pushed past bounds_right are lost. The freed slots [pos.x, pos.x + n) are filled with fill.

fn delete_cells( &mut self, pos: Position, count: u16, bounds_right: u16, fill: &Cell, )

Delete n cells at pos, pulling cells in [pos.x + n, bounds_right) left within row pos.y. The freed slots [bounds_right - n, bounds_right) are filled with fill.

fn fill(&mut self, cell: &Cell)

Fill the entire surface bounds with cell.

fn fill_rect(&mut self, rect: Rect, cell: &Cell)

Fill the intersection of rect and Bounded::bounds with cell.

fn clear(&mut self)

Clear the entire surface bounds to Cell::BLANK.

fn clear_rect(&mut self, rect: Rect)

Clear a rectangle to Cell::BLANK.

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.

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

Measure s, skipping recognized inline SGR and OSC 8 escape sequences so they contribute no width. This is the escape-aware counterpart to the literal default str_width.

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

Paint s starting at pos, clipped to the target bounds.

The painter’s running Style takes precedence and inherits any unset fields from style, so the running style carries across calls and style only fills in what it has not set. Inline SGR and OSC 8 sequences then update the running style as the input is processed. Newline advances to the next row at the bounds’ left edge; carriage return returns to that left edge on the current row. Right-edge behavior is WrapMode::Truncate.

Parameters

• pos — starting cell position.
• s — UTF-8 input string.
• style — base style the running style inherits unset fields from.

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_wrap( &mut self, pos: impl Into<Position>, s: &str, wrap: WrapMode, style: impl Into<Style>, ) -> Position

Paint s starting at pos with explicit wrapping behavior.

The target bounds are the clipping rectangle. WrapMode::Truncate stops at the right edge; WrapMode::Wrap continues on the next row at the bounds’ left edge until the bottom edge is reached.

Parameters

• pos — starting cell position.
• s — UTF-8 input string.
• wrap — right-edge behavior for non-zero-width clusters.
• style — initial style for this call.

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 into rect, clipped to rect ∩ target.bounds().

Painting starts at rect’s top-left. Newline and carriage return use rect’s left edge as the return column. Right-edge behavior is WrapMode::Truncate.

Parameters

• rect — origin and clipping rectangle.
• s — UTF-8 input string.
• style — initial style for this call.

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 into rect with explicit wrapping behavior.

The clipping rectangle is rect ∩ target.bounds(). WrapMode::Wrap flows down inside rect; WrapMode::Truncate stops at rect’s right edge.

Parameters

• rect — origin and clipping rectangle.
• s — UTF-8 input string.
• wrap — right-edge behavior for non-zero-width clusters.
• style — initial style for this call.

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 starting at pos, truncating with a tail indicator.

Text is painted across the target bounds. When a non-zero-width cluster would cross the right edge, painting stops and tail is stamped over the trailing columns so it ends exactly at the right edge. The tail appears only when the text actually overflows; text that fits is left untouched.

tail is painted with tail_style as its starting style and may carry its own inline escape sequences, so it can be a single glyph ("…"), a word (" more"), or a multi-style span. If the tail is wider than the available space, it is dropped and the text is hard-truncated instead.

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.

This is the rectangular form of set_str_truncate: the clip rectangle is rect ∩ target.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 width_mode(&self) -> WidthMode

Return the width-measurement mode used when shaping strings.

fn eaw_wide(&self) -> bool

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

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.

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.