dear_imgui_rs/widget/
progress.rs

1//! Progress bars
2//!
3//! Simple progress indicators with size and overlay text customization.
4//!
5use crate::sys;
6use crate::ui::Ui;
7use std::borrow::Cow;
8
9fn assert_finite_f32(caller: &str, name: &str, value: f32) {
10    assert!(value.is_finite(), "{caller} {name} must be finite");
11}
12
13fn assert_finite_vec2(caller: &str, name: &str, value: [f32; 2]) {
14    assert!(
15        value[0].is_finite() && value[1].is_finite(),
16        "{caller} {name} must contain finite values"
17    );
18}
19
20/// # Progress Bar Widgets
21impl Ui {
22    /// Creates a progress bar widget.
23    ///
24    /// The fraction should be between 0.0 (0%) and 1.0 (100%).
25    #[doc(alias = "ProgressBar")]
26    pub fn progress_bar(&self, fraction: f32) -> ProgressBar<'_> {
27        ProgressBar::new(self, fraction)
28    }
29
30    /// Creates a progress bar with overlay text.
31    #[doc(alias = "ProgressBar")]
32    pub fn progress_bar_with_overlay<'ui>(
33        &'ui self,
34        fraction: f32,
35        overlay: impl Into<Cow<'ui, str>>,
36    ) -> ProgressBar<'ui> {
37        ProgressBar::new(self, fraction).overlay_text(overlay)
38    }
39}
40
41/// Builder for a progress bar widget.
42///
43/// # Examples
44///
45/// ```no_run
46/// # use dear_imgui_rs::*;
47/// # let mut ctx = Context::create();
48/// # let ui = ctx.frame();
49/// ui.progress_bar(0.6)
50///     .size([100.0, 12.0])
51///     .overlay_text("Progress!")
52///     .build();
53/// ```
54#[derive(Clone, Debug)]
55#[must_use]
56pub struct ProgressBar<'ui> {
57    fraction: f32,
58    size: [f32; 2],
59    overlay_text: Option<Cow<'ui, str>>,
60    ui: &'ui Ui,
61}
62
63impl<'ui> ProgressBar<'ui> {
64    /// Creates a progress bar with a given fraction showing
65    /// the progress (0.0 = 0%, 1.0 = 100%).
66    ///
67    /// The progress bar will be automatically sized to fill the entire width of the window if no
68    /// custom size is specified.
69    #[inline]
70    #[doc(alias = "ProgressBar")]
71    pub fn new(ui: &'ui Ui, fraction: f32) -> Self {
72        ProgressBar {
73            fraction,
74            size: [-1.0, 0.0], // -1.0 means auto-size to fill width
75            overlay_text: None,
76            ui,
77        }
78    }
79
80    /// Sets an optional text that will be drawn over the progress bar.
81    pub fn overlay_text(mut self, overlay_text: impl Into<Cow<'ui, str>>) -> Self {
82        self.overlay_text = Some(overlay_text.into());
83        self
84    }
85
86    /// Sets the size of the progress bar.
87    ///
88    /// Negative values will automatically align to the end of the axis, zero will let the progress
89    /// bar choose a size, and positive values will use the given size.
90    #[inline]
91    pub fn size(mut self, size: impl Into<[f32; 2]>) -> Self {
92        self.size = size.into();
93        self
94    }
95
96    /// Sets the progress fraction (0.0 to 1.0)
97    pub fn fraction(mut self, fraction: f32) -> Self {
98        self.fraction = fraction;
99        self
100    }
101
102    /// Builds the progress bar
103    pub fn build(self) {
104        assert_finite_f32("ProgressBar::build()", "fraction", self.fraction);
105        assert_finite_vec2("ProgressBar::build()", "size", self.size);
106
107        let size_vec: sys::ImVec2 = self.size.into();
108        let overlay_ptr = self
109            .overlay_text
110            .as_deref()
111            .map_or(std::ptr::null(), |txt| self.ui.scratch_txt(txt));
112
113        unsafe {
114            sys::igProgressBar(self.fraction, size_vec, overlay_ptr);
115        }
116    }
117}
dear_imgui_rs/widget/progress.rs

dear_imgui_rs/widget/
progress.rs
