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}