altui_core/widgets/
gauge.rs

1use crate::{
2    buffer::Buffer,
3    layout::Rect,
4    style::{Color, Style},
5    symbols,
6    text::{Span, Spans},
7    widgets::{Block, Widget},
8};
9
10/// A widget to display a task progress.
11///
12/// # Examples:
13///
14/// ```
15/// # use altui_core::widgets::{Widget, Gauge, Block, Borders};
16/// # use altui_core::style::{Style, Color, Modifier};
17/// Gauge::default()
18///     .block(Block::default().borders(Borders::ALL).title("Progress"))
19///     .gauge_style(Style::default().fg(Color::White).bg(Color::Black).add_modifier(Modifier::ITALIC))
20///     .percent(20);
21/// ```
22#[derive(Debug, Clone)]
23pub struct Gauge<'a> {
24    block: Option<Block<'a>>,
25    ratio: f64,
26    label: Option<Span<'a>>,
27    use_unicode: bool,
28    style: Style,
29    gauge_style: Style,
30}
31
32impl<'a> Default for Gauge<'a> {
33    fn default() -> Gauge<'a> {
34        Gauge {
35            block: None,
36            ratio: 0.0,
37            label: None,
38            use_unicode: false,
39            style: Style::default(),
40            gauge_style: Style::default(),
41        }
42    }
43}
44
45impl<'a> Gauge<'a> {
46    pub fn block(mut self, block: Block<'a>) -> Gauge<'a> {
47        self.block = Some(block);
48        self
49    }
50
51    pub fn percent(mut self, percent: u16) -> Gauge<'a> {
52        assert!(
53            percent <= 100,
54            "Percentage should be between 0 and 100 inclusively."
55        );
56        self.ratio = f64::from(percent) / 100.0;
57        self
58    }
59
60    /// Sets ratio ([0.0, 1.0]) directly.
61    pub fn ratio(mut self, ratio: f64) -> Gauge<'a> {
62        assert!(
63            (0.0..=1.0).contains(&ratio),
64            "Ratio should be between 0 and 1 inclusively."
65        );
66        self.ratio = ratio;
67        self
68    }
69
70    pub fn label<T>(mut self, label: T) -> Gauge<'a>
71    where
72        T: Into<Span<'a>>,
73    {
74        self.label = Some(label.into());
75        self
76    }
77
78    pub fn style(mut self, style: Style) -> Gauge<'a> {
79        self.style = style;
80        self
81    }
82
83    pub fn gauge_style(mut self, style: Style) -> Gauge<'a> {
84        self.gauge_style = style;
85        self
86    }
87
88    pub fn use_unicode(mut self, unicode: bool) -> Gauge<'a> {
89        self.use_unicode = unicode;
90        self
91    }
92}
93
94impl<'a> Widget for Gauge<'a> {
95    fn render(&mut self, area: Rect, buf: &mut Buffer) {
96        buf.set_style(area, self.style);
97        let gauge_area = match self.block.as_mut() {
98            Some(b) => {
99                let inner_area = b.inner(area);
100                b.render(area, buf);
101                inner_area
102            }
103            None => area,
104        };
105        buf.set_style(gauge_area, self.gauge_style);
106        if gauge_area.height < 1 {
107            return;
108        }
109
110        // compute label value and its position
111        // label is put at the center of the gauge_area
112        let label = {
113            let pct = f64::round(self.ratio * 100.0);
114            self.label
115                .as_ref()
116                .cloned()
117                .unwrap_or_else(|| Span::from(format!("{}%", pct)))
118        };
119        let clamped_label_width = gauge_area.width.min(label.width() as u16);
120        let label_col = gauge_area.left() + (gauge_area.width - clamped_label_width) / 2;
121        let label_row = gauge_area.top() + gauge_area.height / 2;
122
123        // the gauge will be filled proportionally to the ratio
124        let filled_width = f64::from(gauge_area.width) * self.ratio;
125        let end = if self.use_unicode {
126            gauge_area.left() + filled_width.floor() as u16
127        } else {
128            gauge_area.left() + filled_width.round() as u16
129        };
130        for y in gauge_area.top()..gauge_area.bottom() {
131            // render the filled area (left to end)
132            for x in gauge_area.left()..end {
133                // spaces are needed to apply the background styling
134                buf.get_mut(x, y)
135                    .set_symbol(" ")
136                    .set_fg(self.gauge_style.bg.unwrap_or(Color::Reset))
137                    .set_bg(self.gauge_style.fg.unwrap_or(Color::Reset));
138            }
139            if self.use_unicode && self.ratio < 1.0 {
140                buf.get_mut(end, y)
141                    .set_symbol(get_unicode_block(filled_width % 1.0));
142            }
143        }
144        // set the span
145        buf.set_span(label_col, label_row, &label, clamped_label_width);
146    }
147}
148
149fn get_unicode_block<'a>(frac: f64) -> &'a str {
150    match (frac * 8.0).round() as u16 {
151        1 => symbols::block::ONE_EIGHTH,
152        2 => symbols::block::ONE_QUARTER,
153        3 => symbols::block::THREE_EIGHTHS,
154        4 => symbols::block::HALF,
155        5 => symbols::block::FIVE_EIGHTHS,
156        6 => symbols::block::THREE_QUARTERS,
157        7 => symbols::block::SEVEN_EIGHTHS,
158        8 => symbols::block::FULL,
159        _ => " ",
160    }
161}
162
163/// A compact widget to display a task progress over a single line.
164///
165/// # Examples:
166///
167/// ```
168/// # use altui_core::widgets::{Widget, LineGauge, Block, Borders};
169/// # use altui_core::style::{Style, Color, Modifier};
170/// # use altui_core::symbols;
171/// LineGauge::default()
172///     .block(Block::default().borders(Borders::ALL).title("Progress"))
173///     .gauge_style(Style::default().fg(Color::White).bg(Color::Black).add_modifier(Modifier::BOLD))
174///     .line_set(symbols::line::THICK)
175///     .ratio(0.4);
176/// ```
177pub struct LineGauge<'a> {
178    block: Option<Block<'a>>,
179    ratio: f64,
180    label: Option<Spans<'a>>,
181    line_set: symbols::line::Set,
182    style: Style,
183    gauge_style: Style,
184}
185
186impl<'a> Default for LineGauge<'a> {
187    fn default() -> Self {
188        Self {
189            block: None,
190            ratio: 0.0,
191            label: None,
192            style: Style::default(),
193            line_set: symbols::line::NORMAL,
194            gauge_style: Style::default(),
195        }
196    }
197}
198
199impl<'a> LineGauge<'a> {
200    pub fn block(mut self, block: Block<'a>) -> Self {
201        self.block = Some(block);
202        self
203    }
204
205    pub fn ratio(mut self, ratio: f64) -> Self {
206        assert!(
207            (0.0..=1.0).contains(&ratio),
208            "Ratio should be between 0 and 1 inclusively."
209        );
210        self.ratio = ratio;
211        self
212    }
213
214    pub fn line_set(mut self, set: symbols::line::Set) -> Self {
215        self.line_set = set;
216        self
217    }
218
219    pub fn label<T>(mut self, label: T) -> Self
220    where
221        T: Into<Spans<'a>>,
222    {
223        self.label = Some(label.into());
224        self
225    }
226
227    pub fn style(mut self, style: Style) -> Self {
228        self.style = style;
229        self
230    }
231
232    pub fn gauge_style(mut self, style: Style) -> Self {
233        self.gauge_style = style;
234        self
235    }
236}
237
238impl<'a> Widget for LineGauge<'a> {
239    fn render(&mut self, area: Rect, buf: &mut Buffer) {
240        buf.set_style(area, self.style);
241        let gauge_area = match self.block.as_mut() {
242            Some(b) => {
243                let inner_area = b.inner(area);
244                b.render(area, buf);
245                inner_area
246            }
247            None => area,
248        };
249
250        if gauge_area.height < 1 {
251            return;
252        }
253
254        let ratio = self.ratio;
255        let label = self
256            .label
257            .as_ref()
258            .cloned()
259            .unwrap_or_else(move || Spans::from(format!("{:.0}%", ratio * 100.0)));
260        let (col, row) = buf.set_spans(
261            gauge_area.left(),
262            gauge_area.top(),
263            &label,
264            gauge_area.width,
265        );
266        let start = col + 1;
267        if start >= gauge_area.right() {
268            return;
269        }
270
271        let end = start
272            + (f64::from(gauge_area.right().saturating_sub(start)) * self.ratio).floor() as u16;
273        for col in start..end {
274            buf.get_mut(col, row)
275                .set_symbol(self.line_set.horizontal)
276                .set_style(Style {
277                    fg: self.gauge_style.fg,
278                    bg: None,
279                    add_modifier: self.gauge_style.add_modifier,
280                    sub_modifier: self.gauge_style.sub_modifier,
281                });
282        }
283        for col in end..gauge_area.right() {
284            buf.get_mut(col, row)
285                .set_symbol(self.line_set.horizontal)
286                .set_style(Style {
287                    fg: self.gauge_style.bg,
288                    bg: None,
289                    add_modifier: self.gauge_style.add_modifier,
290                    sub_modifier: self.gauge_style.sub_modifier,
291                });
292        }
293    }
294}
295
296#[cfg(test)]
297mod tests {
298    use super::*;
299
300    #[test]
301    #[should_panic]
302    fn gauge_invalid_percentage() {
303        Gauge::default().percent(110);
304    }
305
306    #[test]
307    #[should_panic]
308    fn gauge_invalid_ratio_upper_bound() {
309        Gauge::default().ratio(1.1);
310    }
311
312    #[test]
313    #[should_panic]
314    fn gauge_invalid_ratio_lower_bound() {
315        Gauge::default().ratio(-0.5);
316    }
317}
altui_core/widgets/gauge.rs

altui_core/widgets/
gauge.rs
