uncurses/ansi/progress.rs
1//! Progress-bar OSC sequences.
2//!
3//! ## Category
4//!
5//! OSC 9;4 communicates taskbar or tab progress state: reset, indeterminate,
6//! normal percentage, error percentage, and warning percentage.
7//!
8//! ## OSC framing
9//!
10//! All sequences use `ESC ] 9 ; 4 ; state [; percentage] BEL`. Percentages passed
11//! to writers are clamped into `0..=100` before emission.
12//!
13//! ## Mode interaction
14//!
15//! These notifications are not controlled by terminal modes. Unsupported
16//! terminals ignore the OSC string.
17
18use std::io::{self, Write};
19
20/// Reset or hide progress: exact bytes `ESC ] 9 ; 4 ; 0 BEL` (`b"\x1b]9;4;0\x07"`).
21pub const RESET_PROGRESS_BAR: &[u8] = b"\x1b]9;4;0\x07";
22
23/// Set indeterminate progress: exact bytes `ESC ] 9 ; 4 ; 3 BEL` (`b"\x1b]9;4;3\x07"`).
24pub const SET_INDETERMINATE_PROGRESS_BAR: &[u8] = b"\x1b]9;4;3\x07";
25
26fn clamp_percentage(p: i32) -> u8 {
27 p.clamp(0, 100) as u8
28}
29
30/// Set normal progress with `ESC ] 9 ; 4 ; 1 ; <percentage> BEL`.
31///
32/// `percentage` is clamped to `0..=100` before it is emitted.
33pub fn write_set_progress_bar<W: Write>(w: &mut W, percentage: i32) -> io::Result<()> {
34 write!(w, "\x1b]9;4;1;{}\x07", clamp_percentage(percentage))
35}
36
37/// Set error progress with `ESC ] 9 ; 4 ; 2 ; <percentage> BEL`.
38///
39/// `percentage` is clamped to `0..=100` before it is emitted.
40pub fn write_set_error_progress_bar<W: Write>(w: &mut W, percentage: i32) -> io::Result<()> {
41 write!(w, "\x1b]9;4;2;{}\x07", clamp_percentage(percentage))
42}
43
44/// Set warning progress with `ESC ] 9 ; 4 ; 4 ; <percentage> BEL`.
45///
46/// `percentage` is clamped to `0..=100` before it is emitted.
47pub fn write_set_warning_progress_bar<W: Write>(w: &mut W, percentage: i32) -> io::Result<()> {
48 write!(w, "\x1b]9;4;4;{}\x07", clamp_percentage(percentage))
49}