ratatui/widgets/
clear.rs

1use crate::{
2    buffer::Buffer,
3    layout::Rect,
4    widgets::{Widget, WidgetRef},
5};
6
7/// A widget to clear/reset a certain area to allow overdrawing (e.g. for popups).
8///
9/// This widget **cannot be used to clear the terminal on the first render** as `ratatui` assumes
10/// the render area is empty. Use [`crate::Terminal::clear`] instead.
11///
12/// # Examples
13///
14/// ```
15/// use ratatui::{
16///     layout::Rect,
17///     widgets::{Block, Clear},
18///     Frame,
19/// };
20///
21/// fn draw_on_clear(f: &mut Frame, area: Rect) {
22///     let block = Block::bordered().title("Block");
23///     f.render_widget(Clear, area); // <- this will clear/reset the area first
24///     f.render_widget(block, area); // now render the block widget
25/// }
26/// ```
27///
28/// # Popup Example
29///
30/// For a more complete example how to utilize `Clear` to realize popups see
31/// the example `examples/popup.rs`
32#[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
33pub struct Clear;
34
35impl Widget for Clear {
36    fn render(self, area: Rect, buf: &mut Buffer) {
37        self.render_ref(area, buf);
38    }
39}
40
41impl WidgetRef for Clear {
42    fn render_ref(&self, area: Rect, buf: &mut Buffer) {
43        for x in area.left()..area.right() {
44            for y in area.top()..area.bottom() {
45                buf[(x, y)].reset();
46            }
47        }
48    }
49}
50
51#[cfg(test)]
52mod tests {
53    use super::*;
54    use crate::{buffer::Buffer, layout::Rect, widgets::Widget};
55    #[test]
56    fn render() {
57        let mut buffer = Buffer::with_lines(["xxxxxxxxxxxxxxx"; 7]);
58        let clear = Clear;
59        clear.render(Rect::new(1, 2, 3, 4), &mut buffer);
60        let expected = Buffer::with_lines([
61            "xxxxxxxxxxxxxxx",
62            "xxxxxxxxxxxxxxx",
63            "x   xxxxxxxxxxx",
64            "x   xxxxxxxxxxx",
65            "x   xxxxxxxxxxx",
66            "x   xxxxxxxxxxx",
67            "xxxxxxxxxxxxxxx",
68        ]);
69        assert_eq!(buffer, expected);
70    }
71}
ratatui/widgets/clear.rs

ratatui/widgets/
clear.rs
