Struct VirtualTerminal 

pub struct VirtualTerminal { /* private fields */ }

In-memory virtual terminal with cursor tracking and ANSI interpretation.

Example

use ftui_pty::virtual_terminal::VirtualTerminal;

let mut vt = VirtualTerminal::new(80, 24);
vt.feed(b"Hello, World!");
assert_eq!(vt.char_at(0, 0), Some('H'));
assert_eq!(vt.char_at(12, 0), Some('!'));
assert_eq!(vt.cursor(), (13, 0));

Implementations

impl VirtualTerminal

pub fn new(width: u16, height: u16) -> Self

Create a new virtual terminal with the given dimensions.

Panics

Panics if width or height is 0.

pub fn with_quirks(width: u16, height: u16, quirks: QuirkSet) -> Self

Create a new virtual terminal with quirks enabled.

Panics

Panics if width or height is 0.

pub const fn width(&self) -> u16

Terminal width in columns.

pub const fn height(&self) -> u16

Terminal height in rows.

pub const fn cursor(&self) -> (u16, u16)

Current cursor position (x, y), 0-indexed.

pub const fn cursor_visible(&self) -> bool

Whether the cursor is currently visible.

pub const fn is_alternate_screen(&self) -> bool

Whether alternate screen mode is active.

pub fn title(&self) -> &str

Current window title (set via OSC 0/2).

pub const fn quirks(&self) -> QuirkSet

Active quirk set.

pub fn set_quirks(&mut self, quirks: QuirkSet)

Override the active quirk set.

pub fn scrollback_len(&self) -> usize

Number of lines in the scrollback buffer.

pub fn set_max_scrollback(&mut self, max: usize)

Set the maximum scrollback lines.

pub fn char_at(&self, x: u16, y: u16) -> Option<char>

Get the character at (x, y). Returns None if out of bounds.

pub fn style_at(&self, x: u16, y: u16) -> Option<&CellStyle>

Get the style at (x, y). Returns None if out of bounds.

pub fn cell_at(&self, x: u16, y: u16) -> Option<&VCell>

Get a reference to the cell at (x, y). Returns None if out of bounds.

pub fn row_text(&self, y: u16) -> String

Get the text content of a row (trailing spaces trimmed).

pub fn screen_text(&self) -> String

Get all visible text as a string (rows separated by newlines).

pub fn scrollback_line(&self, idx: usize) -> Option<String>

Get a scrollback line by index (0 = oldest).

pub fn feed(&mut self, data: &[u8])

Feed raw bytes into the terminal (ANSI-aware).

pub fn feed_str(&mut self, s: &str)

Feed a string into the terminal.

pub fn put_str(&mut self, s: &str)

Write a plain-text string to the terminal.

Each character is fed through put_char, which handles auto-wrap, wide characters, insert mode, and charset translation — but no ANSI escape sequences are interpreted. Use this when you have pre-sanitized text and want deterministic character-level output.

Example

use ftui_pty::virtual_terminal::VirtualTerminal;

let mut vt = VirtualTerminal::new(10, 1);
vt.put_str("Hello");
assert_eq!(vt.row_text(0), "Hello");
assert_eq!(vt.cursor(), (5, 0));

pub fn set_cursor_position(&mut self, x: u16, y: u16)

Move the cursor to an absolute position, clamped to terminal bounds.

Coordinates are 0-indexed. Out-of-range values are clamped: x to width - 1, y to height - 1.

Example

use ftui_pty::virtual_terminal::VirtualTerminal;

let mut vt = VirtualTerminal::new(80, 24);
vt.set_cursor_position(5, 10);
assert_eq!(vt.cursor(), (5, 10));

// Out-of-range values are clamped.
vt.set_cursor_position(999, 999);
assert_eq!(vt.cursor(), (79, 23));

pub fn clear(&mut self)

Clear the entire visible display, filling every cell with the current style’s background.

This is the programmatic equivalent of ESC[2J. The cursor position is not changed. Scrollback is not affected — use clear_scrollback for that.

Example

use ftui_pty::virtual_terminal::VirtualTerminal;

let mut vt = VirtualTerminal::new(5, 1);
vt.put_str("Hello");
vt.clear();
assert_eq!(vt.row_text(0), "");

pub fn clear_scrollback(&mut self)

Clear the scrollback buffer.

This removes all lines that have scrolled off the visible area. The visible display is not affected.

pub fn cpr_response(&self) -> Vec<u8>

Generate a cursor position report (CPR) response. Format: ESC [ Py ; Px R (1-indexed).

pub fn da1_response(&self) -> Vec<u8>

Generate a device attributes (DA1) response. Reports as a VT220 with ANSI color.

pub fn put_char(&mut self, ch: char)

Place a single character at the current cursor position, applying all terminal output logic: charset translation, Unicode width detection, auto-wrap (DECAWM), wide-character handling, insert mode (IRM), and cursor advancement.

This is the character-level entry point that feed and feed_str use internally after ANSI/UTF-8 parsing. Call it directly when you already have decoded characters and want the terminal to handle wrapping, widths, and cursor movement.

Zero-width characters (combining marks, ZWJ) are silently skipped.

Example

use ftui_pty::virtual_terminal::VirtualTerminal;

let mut vt = VirtualTerminal::new(10, 3);
vt.put_char('H');
vt.put_char('i');
assert_eq!(vt.row_text(0), "Hi");
assert_eq!(vt.cursor(), (2, 0));