Skip to main content

SurfaceMut

uncurses::buffer

Trait SurfaceMut 

Source 
pub trait SurfaceMut: Surface {
    // Required methods
    fn set_cell(&mut self, pos: Position, cell: &Cell);
    fn cell_mut(&mut self, pos: Position) -> Option<&mut Cell>;

    // Provided methods
    fn fill(&mut self, cell: &Cell) { ... }
    fn fill_rect(&mut self, rect: Rect, cell: &Cell) { ... }
    fn clear(&mut self) { ... }
    fn clear_rect(&mut self, rect: Rect) { ... }
    fn insert_lines(&mut self, y: u16, n: u16, bounds_bottom: u16, fill: &Cell) { ... }
    fn delete_lines(&mut self, y: u16, n: u16, bounds_bottom: u16, fill: &Cell) { ... }
    fn insert_cells(
        &mut self,
        pos: Position,
        n: u16,
        bounds_right: u16,
        fill: &Cell,
    ) { ... }
    fn delete_cells(
        &mut self,
        pos: Position,
        n: u16,
        bounds_right: u16,
        fill: &Cell,
    ) { ... }
}
Expand description

A rectangular cell grid that can be modified.

SurfaceMut is the trait to use for render targets. It includes a primitive cell write plus higher-level operations used by terminal emulation and drawing code: fills, clears, line insertion/deletion, and cell insertion/deletion within a row.

Implementations are responsible for preserving the same wide-cell invariants as Buffer: a wide primary owns the following continuation slot, continuations should not become visible without their primary, and clipped wide writes should leave blanks rather than half a grapheme.

Required Methods§

Source

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.

§Parameters
  • pos: destination coordinate in this surface’s coordinate space.
  • cell: cell to write.
§Returns

Nothing.

§Panics

Implementations should not panic for out-of-bounds positions.

§Usage notes

Out-of-bounds writes should be ignored. Use this method instead of Self::cell_mut whenever changing content could affect display width or neighboring continuation slots.

Source

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

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

§Parameters
  • pos: coordinate in this surface’s coordinate space.
§Returns

Some(&mut Cell) for an in-bounds cell, or None when pos is not writable.

§Panics

Implementations should not panic for out-of-bounds positions.

§Usage notes

Implementations that track dirty state must mark the cell as touched eagerly — the caller may mutate any field through this handle and the surface has no way to observe a write. Callers must not change the cell’s display width through this handle; use Self::set_cell for wide-cell writes that need continuation-column accounting.

Provided Methods§

Source

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

Fill the entire surface bounds with cell.

§Parameters
  • cell: fill cell to write repeatedly.
§Returns

Nothing.

§Panics

Does not panic unless Self::fill_rect panics.

§Usage notes

This delegates to Self::fill_rect with Bounded::bounds. Wide fills are handled by fill_rect.

Source

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

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

§Parameters
  • rect: requested fill rectangle in this surface’s coordinate space.
  • cell: fill cell to write.
§Behavior

Stepped by cell.width() so wide cells lay down clean primary/continuation pairs; a trailing partial slot at the right edge falls back to a blank. Implementations may override for a bulk-blit fast path.

§Panics

The default implementation does not panic unless Self::set_cell panics.

§Usage notes

Empty intersections are no-ops. A wide fill into an odd-width region leaves the final single column blank because a two-column grapheme cannot fit there.

Source

fn clear(&mut self)

Clear the entire surface bounds to Cell::BLANK.

§Returns

Nothing.

§Panics

Does not panic unless Self::fill panics.

§Usage notes

This is equivalent to self.fill(&Cell::BLANK).

Source

fn clear_rect(&mut self, rect: Rect)

Clear a rectangle to Cell::BLANK.

§Parameters
  • rect: requested clear rectangle in this surface’s coordinate space.
§Returns

Nothing.

§Panics

Does not panic unless Self::fill_rect panics.

§Usage notes

Only the intersection of rect and Bounded::bounds is modified.

Source

fn insert_lines(&mut self, y: u16, n: 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.

§Parameters
  • y: first row to insert at, in this surface’s coordinate space.
  • n: number of rows to insert.
  • bounds_bottom: exclusive lower row bound for the affected region.
  • fill: cell used to fill the newly opened rows.
§Behavior

The default implementation copies cells through Self::set_cell row-by-row from the bottom up, advancing along each source row by the source cell’s width so wide-primary cells move as a unit and their continuation columns are not independently rewritten. Wide primaries that no longer fit are replaced by a blank. Implementations backed by contiguous row storage may override with a row-swap fast path.

§Panics

The default implementation does not panic unless Self::set_cell panics.

§Usage notes

bounds_bottom is clamped to the surface height. Calls with n == 0 or y >= bounds_bottom are no-ops.

Source

fn delete_lines(&mut self, y: u16, n: 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.

§Parameters
  • y: first row to delete, in this surface’s coordinate space.
  • n: number of rows to delete.
  • bounds_bottom: exclusive lower row bound for the affected region.
  • fill: cell used to fill the freed bottom rows.
§Behavior

The default implementation copies cells through Self::set_cell row-by-row from top down, advancing along each source row by the source cell’s width so wide-primary cells move as a unit and their continuation columns are not independently rewritten. Wide primaries that no longer fit are replaced by a blank. Implementations backed by contiguous row storage may override with a row-swap fast path.

§Panics

The default implementation does not panic unless Self::set_cell panics.

§Usage notes

bounds_bottom is clamped to the surface height. Calls with n == 0 or y >= bounds_bottom are no-ops.

Source

fn insert_cells( &mut self, pos: Position, n: 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.

§Parameters
  • pos: row and starting column for insertion.
  • n: number of cells to insert.
  • bounds_right: exclusive right column bound for the affected row region.
  • fill: cell used to fill the newly opened slots.
§Behavior

The default implementation snapshots the row’s primary cells in the affected window through Surface::cell, blanks the window via Self::set_cell, then replays each surviving primary at its shifted position. Wide primaries whose new footprint would cross bounds_right are dropped. Implementations backed by a contiguous row slice may override with an in-place rotate.

§Panics

The default implementation does not panic unless Self::set_cell panics.

§Usage notes

bounds_right is clamped to the surface width. Calls with n == 0, an out-of-bounds row, or pos.x >= bounds_right are no-ops.

Source

fn delete_cells( &mut self, pos: Position, n: 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.

§Parameters
  • pos: row and starting column for deletion.
  • n: number of cells to delete.
  • bounds_right: exclusive right column bound for the affected row region.
  • fill: cell used to fill the freed right-edge slots.
§Behavior

The default implementation snapshots the row’s primary cells in the affected window through Surface::cell, blanks the window via Self::set_cell, then replays each surviving primary at its shifted position. Primaries whose source column falls inside [pos.x, pos.x + n) are dropped. Implementations backed by a contiguous row slice may override with an in-place rotate.

§Panics

The default implementation does not panic unless Self::set_cell panics.

§Usage notes

bounds_right is clamped to the surface width. Calls with n == 0, an out-of-bounds row, or pos.x >= bounds_right are no-ops.

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§