ratatui/widgets/block/
padding.rs

1/// Defines the padding for a [`Block`].
2///
3/// See the [`padding`] method of [`Block`] to configure its padding.
4///
5/// This concept is similar to [CSS padding].
6///
7/// **NOTE**: Terminal cells are often taller than they are wide, so to make horizontal and vertical
8/// padding seem equal, doubling the horizontal padding is usually pretty good.
9///
10/// # Example
11///
12/// ```
13/// use ratatui::widgets::Padding;
14///
15/// Padding::uniform(1);
16/// Padding::horizontal(2);
17/// Padding::left(3);
18/// Padding::proportional(4);
19/// Padding::symmetric(5, 6);
20/// ```
21///
22/// [`Block`]: crate::widgets::Block
23/// [`padding`]: crate::widgets::Block::padding
24/// [CSS padding]: https://developer.mozilla.org/en-US/docs/Web/CSS/padding
25#[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash)]
26pub struct Padding {
27    /// Left padding
28    pub left: u16,
29    /// Right padding
30    pub right: u16,
31    /// Top padding
32    pub top: u16,
33    /// Bottom padding
34    pub bottom: u16,
35}
36
37impl Padding {
38    /// `Padding` with all fields set to `0`
39    pub const ZERO: Self = Self {
40        left: 0,
41        right: 0,
42        top: 0,
43        bottom: 0,
44    };
45
46    /// Creates a new `Padding` by specifying every field individually.
47    ///
48    /// Note: the order of the fields does not match the order of the CSS properties.
49    pub const fn new(left: u16, right: u16, top: u16, bottom: u16) -> Self {
50        Self {
51            left,
52            right,
53            top,
54            bottom,
55        }
56    }
57
58    /// Creates a `Padding` with all fields set to `0`.
59    #[deprecated = "use Padding::ZERO"]
60    pub const fn zero() -> Self {
61        Self::ZERO
62    }
63
64    /// Creates a `Padding` with the same value for `left` and `right`.
65    pub const fn horizontal(value: u16) -> Self {
66        Self {
67            left: value,
68            right: value,
69            top: 0,
70            bottom: 0,
71        }
72    }
73
74    /// Creates a `Padding` with the same value for `top` and `bottom`.
75    pub const fn vertical(value: u16) -> Self {
76        Self {
77            left: 0,
78            right: 0,
79            top: value,
80            bottom: value,
81        }
82    }
83
84    /// Creates a `Padding` with the same value for all fields.
85    pub const fn uniform(value: u16) -> Self {
86        Self {
87            left: value,
88            right: value,
89            top: value,
90            bottom: value,
91        }
92    }
93
94    /// Creates a `Padding` that is visually proportional to the terminal.
95    ///
96    /// This represents a padding of 2x the value for `left` and `right` and 1x the value for
97    /// `top` and `bottom`.
98    pub const fn proportional(value: u16) -> Self {
99        Self {
100            left: 2 * value,
101            right: 2 * value,
102            top: value,
103            bottom: value,
104        }
105    }
106
107    /// Creates a `Padding` that is symmetric.
108    ///
109    /// The `x` value is used for `left` and `right` and the `y` value is used for `top` and
110    /// `bottom`.
111    pub const fn symmetric(x: u16, y: u16) -> Self {
112        Self {
113            left: x,
114            right: x,
115            top: y,
116            bottom: y,
117        }
118    }
119
120    /// Creates a `Padding` that only sets the `left` padding.
121    pub const fn left(value: u16) -> Self {
122        Self {
123            left: value,
124            right: 0,
125            top: 0,
126            bottom: 0,
127        }
128    }
129
130    /// Creates a `Padding` that only sets the `right` padding.
131    pub const fn right(value: u16) -> Self {
132        Self {
133            left: 0,
134            right: value,
135            top: 0,
136            bottom: 0,
137        }
138    }
139
140    /// Creates a `Padding` that only sets the `top` padding.
141    pub const fn top(value: u16) -> Self {
142        Self {
143            left: 0,
144            right: 0,
145            top: value,
146            bottom: 0,
147        }
148    }
149
150    /// Creates a `Padding` that only sets the `bottom` padding.
151    pub const fn bottom(value: u16) -> Self {
152        Self {
153            left: 0,
154            right: 0,
155            top: 0,
156            bottom: value,
157        }
158    }
159}
160
161#[cfg(test)]
162mod tests {
163    use super::*;
164
165    #[test]
166    fn new() {
167        assert_eq!(
168            Padding::new(1, 2, 3, 4),
169            Padding {
170                left: 1,
171                right: 2,
172                top: 3,
173                bottom: 4
174            }
175        );
176    }
177
178    #[test]
179    fn constructors() {
180        assert_eq!(Padding::horizontal(1), Padding::new(1, 1, 0, 0));
181        assert_eq!(Padding::vertical(1), Padding::new(0, 0, 1, 1));
182        assert_eq!(Padding::uniform(1), Padding::new(1, 1, 1, 1));
183        assert_eq!(Padding::proportional(1), Padding::new(2, 2, 1, 1));
184        assert_eq!(Padding::symmetric(1, 2), Padding::new(1, 1, 2, 2));
185        assert_eq!(Padding::left(1), Padding::new(1, 0, 0, 0));
186        assert_eq!(Padding::right(1), Padding::new(0, 1, 0, 0));
187        assert_eq!(Padding::top(1), Padding::new(0, 0, 1, 0));
188        assert_eq!(Padding::bottom(1), Padding::new(0, 0, 0, 1));
189    }
190
191    #[test]
192    const fn can_be_const() {
193        const _PADDING: Padding = Padding::new(1, 1, 1, 1);
194        const _UNI_PADDING: Padding = Padding::uniform(1);
195        const _HORIZONTAL: Padding = Padding::horizontal(1);
196        const _VERTICAL: Padding = Padding::vertical(1);
197        const _PROPORTIONAL: Padding = Padding::proportional(1);
198        const _SYMMETRIC: Padding = Padding::symmetric(1, 1);
199        const _LEFT: Padding = Padding::left(1);
200        const _RIGHT: Padding = Padding::right(1);
201        const _TOP: Padding = Padding::top(1);
202        const _BOTTOM: Padding = Padding::bottom(1);
203    }
204}
ratatui/widgets/block/padding.rs

ratatui/widgets/block/
padding.rs
