Guide API
Skip to main content

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}