Guide API
Skip to main content

tvision_rs/screen/
cell.rs

1//! `Cell`, a single screen cell (documented on the type).
2
3use crate::color::Style;
4
5/// One character cell of the screen: its text (a grapheme cluster), its colour
6/// [`Style`], and the wide/trail flags that track double-width glyphs.
7///
8/// A single screen cell: its text (a grapheme cluster), its colour [`Style`],
9/// and flags tracking double-width glyphs.
10///
11/// One cell can hold a whole grapheme cluster (a base character plus combining
12/// marks / ZWJ sequence), stored as an owned `String`. Double-width handling: a
13/// width-2 grapheme occupies a [`wide`](Cell::is_wide) lead cell immediately
14/// followed by a [`trail`](Cell::is_wide_trail) continuation cell whose symbol
15/// is empty.
16///
17/// `PartialEq` is derived because the render diff compares the back buffer
18/// against the front buffer cell-by-cell to emit only changed cells.
19///
20/// # Turbo Vision heritage
21///
22/// Ports `TScreenCell` + `TCellChar` (`scrncell.h`). The original packs the text
23/// inline as up to 15 UTF-8 bytes; here it is an owned `String`. The colour is a
24/// typed [`Style`] rather than a packed attribute byte (deviation D6), and the
25/// inline grapheme model carries combining marks and ZWJ sequences (deviation
26/// D13).
27#[derive(Clone, Debug, PartialEq, Eq)]
28pub struct Cell {
29    /// The grapheme cluster shown in this cell. Empty for a wide-char trail.
30    symbol: String,
31    /// Colour attributes.
32    style: Style,
33    /// This cell holds the lead of a double-width grapheme.
34    wide: bool,
35    /// This cell is the trailing half of the preceding double-width grapheme.
36    trail: bool,
37}
38
39impl Default for Cell {
40    /// A blank cell: a single space with the default style. (A space is the
41    /// conventional on-screen blank and matches the ratatui-derived buffer shape.)
42    fn default() -> Self {
43        Cell {
44            symbol: String::from(" "),
45            style: Style::default(),
46            wide: false,
47            trail: false,
48        }
49    }
50}
51
52impl Cell {
53    /// A blank cell carrying the given style (the usual fill for clearing a
54    /// region to a background colour).
55    pub fn blank(style: Style) -> Self {
56        Cell {
57            symbol: String::from(" "),
58            style,
59            wide: false,
60            trail: false,
61        }
62    }
63
64    /// Set the text to a single `char`, clearing the wide/trail flags.
65    pub fn set_char(&mut self, ch: char) {
66        self.symbol.clear();
67        self.symbol.push(ch);
68        self.wide = false;
69        self.trail = false;
70    }
71
72    /// Set the text to a grapheme cluster, flagging it `wide` if it is a
73    /// double-width glyph.
74    pub fn set_str(&mut self, s: &str, wide: bool) {
75        self.symbol.clear();
76        self.symbol.push_str(s);
77        self.wide = wide;
78        self.trail = false;
79    }
80
81    /// Mark this cell as the trailing half of a double-width glyph (empty symbol,
82    /// `trail` set).
83    pub fn set_wide_trail(&mut self) {
84        self.symbol.clear();
85        self.wide = false;
86        self.trail = true;
87    }
88
89    /// The grapheme cluster occupying this cell (empty for a wide trail).
90    pub fn symbol(&self) -> &str {
91        &self.symbol
92    }
93
94    pub fn style(&self) -> Style {
95        self.style
96    }
97
98    pub fn set_style(&mut self, style: Style) {
99        self.style = style;
100    }
101
102    /// Whether this cell leads a double-width glyph.
103    pub fn is_wide(&self) -> bool {
104        self.wide
105    }
106
107    /// Whether this cell is the trailing half of a double-width glyph.
108    pub fn is_wide_trail(&self) -> bool {
109        self.trail
110    }
111}
112
113#[cfg(test)]
114mod tests {
115    use super::*;
116    use crate::color::Color;
117
118    #[test]
119    fn default_is_blank_space() {
120        let c = Cell::default();
121        assert_eq!(c.symbol(), " ");
122        assert_eq!(c.style(), Style::default());
123        assert!(!c.is_wide());
124        assert!(!c.is_wide_trail());
125    }
126
127    #[test]
128    fn set_char_clears_flags() {
129        let mut c = Cell::default();
130        c.set_wide_trail();
131        c.set_char('A');
132        assert_eq!(c.symbol(), "A");
133        assert!(!c.is_wide());
134        assert!(!c.is_wide_trail());
135    }
136
137    #[test]
138    fn wide_glyph_and_trail() {
139        // A double-width grapheme (e.g. a CJK ideograph) leads, trail follows.
140        let mut lead = Cell::default();
141        lead.set_str("中", true);
142        assert_eq!(lead.symbol(), "中");
143        assert!(lead.is_wide());
144        assert!(!lead.is_wide_trail());
145
146        let mut trail = Cell::default();
147        trail.set_wide_trail();
148        assert_eq!(trail.symbol(), "");
149        assert!(!trail.is_wide());
150        assert!(trail.is_wide_trail());
151    }
152
153    #[test]
154    fn grapheme_cluster_symbol() {
155        // Combining mark clusters into one cell.
156        let mut c = Cell::default();
157        c.set_str("é", false); // e + combining acute, as one grapheme
158        assert_eq!(c.symbol(), "é");
159        assert!(!c.is_wide());
160    }
161
162    #[test]
163    fn style_roundtrips() {
164        let mut c = Cell::default();
165        let s = Style::new(Color::Bios(0xF), Color::Bios(0x1));
166        c.set_style(s);
167        assert_eq!(c.style(), s);
168        assert_eq!(Cell::blank(s).style(), s);
169    }
170
171    #[test]
172    fn equality_tracks_all_fields() {
173        let mut a = Cell::default();
174        let mut b = Cell::default();
175        assert_eq!(a, b);
176        a.set_char('X');
177        assert_ne!(a, b);
178        b.set_char('X');
179        assert_eq!(a, b);
180        b.set_style(Style::new(Color::Bios(1), Color::Default));
181        assert_ne!(a, b);
182    }
183}