tvision_rs/desktop/background.rs
1//! `Background`, the desktop backdrop (documented on the type).
2
3use crate::theme::Role;
4use crate::view::{DrawCtx, Rect, View, ViewState};
5
6/// Desktop background fill.
7///
8/// The simplest concrete view: it fills its entire extent with a repeated
9/// pattern character styled with [`Role::Background`], and handles no events.
10/// Its grow mode stretches it with its owner on the right and bottom edges, so
11/// it always covers the desktop.
12///
13/// Fills its extent with a single repeated `pattern` character, styled through
14/// [`Role::Background`] from the active [`Theme`](crate::theme::Theme).
15///
16/// # Example
17/// ```
18/// # use tvision_rs::{Background, Rect};
19/// let _bg = Background::new(Rect::new(0, 0, 80, 25), '▒');
20/// ```
21///
22/// # Turbo Vision heritage
23///
24/// Ports `TBackground` (`tbkgrnd.cpp`), which overrides only its draw method. The
25/// background colour index becomes [`Role::Background`] (deviation D7), and the
26/// streaming machinery is dropped (deviation D12).
27pub struct Background {
28 st: ViewState,
29 /// The character tiled across the entire background extent on every draw.
30 ///
31 /// Set this to any printable Unicode scalar before (or after) construction to
32 /// customise the fill. The default desktop fill is `'\u{2591}'` (░ U+2591
33 /// LIGHT SHADE). Any single-column glyph works; double-width characters fill
34 /// correctly but leave a trailing continuation cell for each glyph.
35 pub pattern: char,
36}
37
38impl Background {
39 /// Construct a background filling `bounds` with `pattern`.
40 ///
41 /// Sets the grow mode so the background stretches with its owner on the right
42 /// and bottom edges, always covering the desktop.
43 pub fn new(bounds: Rect, pattern: char) -> Self {
44 let mut st = ViewState::new(bounds);
45 // Grow with the owner's right and bottom edges.
46 st.grow_mode.hi_x = true;
47 st.grow_mode.hi_y = true;
48 Background { st, pattern }
49 }
50}
51
52impl View for Background {
53 fn state(&self) -> &ViewState {
54 &self.st
55 }
56
57 fn state_mut(&mut self) -> &mut ViewState {
58 &mut self.st
59 }
60
61 /// Fill the entire extent with `pattern`, styled with [`Role::Background`].
62 fn draw(&mut self, ctx: &mut DrawCtx) {
63 let ext = self.st.get_extent();
64 let style = ctx.style(Role::Background);
65 ctx.fill(ext, self.pattern, style);
66 }
67
68 // The background does not handle events — it uses the default no-op routing
69 // (mouse-down selection happens in the owning group).
70}
71
72#[cfg(test)]
73mod tests {
74 use super::*;
75 use crate::backend::{HeadlessBackend, Renderer};
76 use crate::screen::Buffer;
77 use crate::theme::Theme;
78 use crate::view::{DrawCtx, Point};
79
80 // -- Constructor ---------------------------------------------------------
81
82 #[test]
83 fn new_stores_pattern_and_bounds() {
84 let bg = Background::new(Rect::new(0, 0, 10, 5), '▒');
85 assert_eq!(bg.pattern, '▒');
86 assert_eq!(bg.st.origin, Point::new(0, 0));
87 assert_eq!(bg.st.size, Point::new(10, 5));
88 }
89
90 #[test]
91 fn new_sets_grow_hi_x_and_hi_y() {
92 let bg = Background::new(Rect::new(0, 0, 10, 5), '▒');
93 assert!(bg.st.grow_mode.hi_x, "grow-right must be set");
94 assert!(bg.st.grow_mode.hi_y, "grow-down must be set");
95 // lo_x, lo_y, rel, fixed must stay clear
96 assert!(!bg.st.grow_mode.lo_x);
97 assert!(!bg.st.grow_mode.lo_y);
98 assert!(!bg.st.grow_mode.rel);
99 assert!(!bg.st.grow_mode.fixed);
100 }
101
102 #[test]
103 fn new_inherits_view_state_defaults() {
104 let bg = Background::new(Rect::new(5, 3, 25, 10), '░');
105 // visible must be set (view-state default)
106 assert!(bg.st.state.visible);
107 // limit_lo_y must be set (view-state default)
108 assert!(bg.st.drag_mode.limit_lo_y);
109 }
110
111 // -- draw ----------------------------------------------------------------
112
113 #[test]
114 fn draw_fills_extent_with_pattern() {
115 let theme = Theme::classic_blue();
116 let mut bg = Background::new(Rect::new(0, 0, 4, 2), 'X');
117 let mut buf = Buffer::new(4, 2);
118 {
119 let bounds = bg.state().get_bounds();
120 let mut ctx = DrawCtx::new(&mut buf, &theme, bounds, bounds.a);
121 bg.draw(&mut ctx);
122 }
123 // Every cell must contain 'X'
124 for y in 0..2u16 {
125 for x in 0..4u16 {
126 assert_eq!(buf.get(x, y).symbol(), "X", "cell ({x},{y}) must be 'X'");
127 }
128 }
129 // Style must be Role::Background
130 let expected_style = theme.style(Role::Background);
131 assert_eq!(buf.get(0, 0).style(), expected_style);
132 assert_eq!(buf.get(3, 1).style(), expected_style);
133 }
134
135 // -- Snapshot test -------------------------------------------------------
136
137 /// End-to-end snapshot: `Background` through the real `Renderer` +
138 /// `HeadlessBackend` path (the template every widget test copies).
139 /// Drawn through `&mut dyn View` so the *trait* dispatch exercises `DrawCtx`.
140 #[test]
141 fn background_render_pipeline_snapshot() {
142 let theme = Theme::classic_blue();
143 let mut bg: Box<dyn View> = Box::new(Background::new(Rect::new(0, 0, 6, 3), '▒'));
144 let (backend, screen) = HeadlessBackend::new(6, 3);
145 let mut r = Renderer::new(Box::new(backend));
146 r.render(|buf: &mut Buffer| {
147 let bounds = bg.state().get_bounds();
148 let mut dc = DrawCtx::new(buf, &theme, bounds, bounds.a);
149 bg.draw(&mut dc);
150 });
151 insta::assert_snapshot!(screen.snapshot());
152 }
153}