Merge pull request #64 from NoraCodes/progressbar-improvements

Make ProgressBar API safe and more ergonomic

Author: NoraCodes

CHANGELOG.md

@@ -8,7 +8,7 @@ project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 ### Added
 
-- `ProgressBar` control for tracking the completion of a task
+- `ProgressBar` control for tracking the completion of a task with automatic value conversions
 - `enable()` and `disable()` methods on all controls
 - `RadioButtons` control for groups of radio buttons
 - `Combobox::selected()` method to retrieve the currently selected index of the combobox

iui/examples/inputs-grid.rs

@@ -4,7 +4,7 @@
 extern crate iui;
 use iui::prelude::*;
 use iui::controls::{Label, Spinbox, Slider, Entry, MultilineEntry, LayoutGrid, 
-    GridAlignment, GridExpand, HorizontalSeparator};
+    GridAlignment, GridExpand, HorizontalSeparator, ProgressBar};
 use std::rc::Rc;
 use std::cell::RefCell;
 
@@ -59,11 +59,12 @@ fn main() {
 
     // Set up the outputs for the application. Organization is very similar to the
     // previous setup.
-    let (add_label, sub_label, text_label, bigtext_label) = {
+    let (add_label, sub_label, text_label, bigtext_label, progress_bar) = {
         let add_label = Label::new(&ui, "");
         let sub_label = Label::new(&ui, "");
         let text_label = Label::new(&ui, "");
         let bigtext_label = Label::new(&ui, "");
+        let progress_bar = ProgressBar::indeterminate(&ui);
         grid.append(&ui, add_label.clone(), 
             1, 0, 1, 1, GridExpand::Neither, GridAlignment::Fill, GridAlignment::Fill);
         grid.append(&ui, sub_label.clone(),
@@ -74,7 +75,9 @@ fn main() {
             1, 4, 1, 1, GridExpand::Neither, GridAlignment::Fill, GridAlignment::Fill);
         grid.append(&ui, bigtext_label.clone(),
             1, 5, 1, 1, GridExpand::Neither, GridAlignment::Fill, GridAlignment::Fill);
-        (add_label, sub_label, text_label, bigtext_label)
+        grid.append(&ui, progress_bar.clone(),
+            0, 6, 2, 1, GridExpand::Neither, GridAlignment::Fill, GridAlignment::Fill);
+        (add_label, sub_label, text_label, bigtext_label, progress_bar)
     };
 
     // The window allows all constituent components to be displayed.
@@ -116,14 +119,16 @@ fn main() {
         let mut sub_label = sub_label.clone();
         let mut text_label = text_label.clone();
         let mut bigtext_label = bigtext_label.clone();
+        let mut progress_bar = progress_bar.clone();
         move || {
             let state = state.borrow();
 
-            // Update all the labels
+            // Update all the outputs
             add_label.set_text(&ui, &format!("Added: {}", state.slider_val + state.spinner_val));
             sub_label.set_text(&ui, &format!("Subtracted: {}", state.slider_val - state.spinner_val));
             text_label.set_text(&ui, &format!("Text: {}", state.entry_val));
             bigtext_label.set_text(&ui, &format!("Multiline Text: {}", state.multi_val));
+            progress_bar.set_value(&ui, (state.slider_val + state.spinner_val) as u32);
         }
     });
     event_loop.run(&ui);

iui/examples/inputs.rs

@@ -2,7 +2,7 @@
 
 extern crate iui;
 use iui::prelude::*;
-use iui::controls::{Label, Spinbox, Slider, Entry, MultilineEntry, VerticalBox, HorizontalBox, HorizontalSeparator, Group, Spacer};
+use iui::controls::{Label, Spinbox, Slider, Entry, MultilineEntry, VerticalBox, HorizontalBox, HorizontalSeparator, Group, Spacer, ProgressBar};
 use std::rc::Rc;
 use std::cell::RefCell;
 
@@ -52,19 +52,21 @@ fn main() {
 
     // Set up the outputs for the application. Organization is very similar to the
     // previous setup.
-    let (output_group, add_label, sub_label, text_label, bigtext_label) = {
+    let (output_group, add_label, sub_label, text_label, bigtext_label, progress_bar) = {
         let mut output_group = Group::new(&ui, "Outputs");
         let mut output_vbox = VerticalBox::new(&ui);
         let add_label = Label::new(&ui, "");
         let sub_label = Label::new(&ui, "");
         let text_label = Label::new(&ui, "");
         let bigtext_label = Label::new(&ui, "");
+        let progress_bar = ProgressBar::indeterminate(&ui);
         output_vbox.append(&ui, add_label.clone(), LayoutStrategy::Compact);
         output_vbox.append(&ui, sub_label.clone(), LayoutStrategy::Compact);
+        output_vbox.append(&ui, progress_bar.clone(), LayoutStrategy::Compact);
         output_vbox.append(&ui, text_label.clone(), LayoutStrategy::Compact);
         output_vbox.append(&ui, bigtext_label.clone(), LayoutStrategy::Stretchy);
         output_group.set_child(&ui, output_vbox);
-        (output_group, add_label, sub_label, text_label, bigtext_label)
+        (output_group, add_label, sub_label, text_label, bigtext_label, progress_bar)
     };
 
     // This horizontal box will arrange the two groups of controls.
@@ -111,14 +113,16 @@ fn main() {
         let mut sub_label = sub_label.clone();
         let mut text_label = text_label.clone();
         let mut bigtext_label = bigtext_label.clone();
+        let mut progress_bar = progress_bar.clone();
         move || {
             let state = state.borrow();
 
-            // Update all the labels
+            // Update all the outputs 
             add_label.set_text(&ui, &format!("Added: {}", state.slider_val + state.spinner_val));
             sub_label.set_text(&ui, &format!("Subtracted: {}", state.slider_val - state.spinner_val));
             text_label.set_text(&ui, &format!("Text: {}", state.entry_val));
             bigtext_label.set_text(&ui, &format!("Multiline Text: {}", state.multi_val));
+            progress_bar.set_value(&ui, (state.slider_val + state.spinner_val) as u32)
         }
     });
     event_loop.run(&ui);

iui/src/controls/progressbar.rs

@@ -3,7 +3,37 @@ use std::mem;
 use ui::UI;
 use ui_sys::{self, uiControl, uiProgressBar};
 
-/// An enum representing the value of a `ProgressBar`
+/// An enum representing the value of a `ProgressBar`.
+/// 
+/// # Values
+/// 
+/// A `ProgressBarValue` can be either `Determinate`, a number from 0 up to 100, or
+/// `Indeterminate`, representing a process that is still in progress but has no
+/// completeness metric availble.
+/// 
+/// # Conversions
+/// 
+/// A `ProgressBarValue` can be made from a `u32` or an `Option<u32>`, and the relevant functions
+/// take a type that is generic over this behavior, so it's easy to set the progress of a bar.
+/// 
+/// ```
+/// # use iui::prelude::*;
+/// # use iui::controls::{ProgressBar, ProgressBarValue};
+/// # let ui = UI::init().unwrap();
+/// # let mut window = Window::new(&ui, "Test Window", 0, 0, WindowType::NoMenubar);
+/// let mut progressbar = ProgressBar::indeterminate(&ui);
+/// progressbar.set_value(&ui, 54);
+/// 
+/// // Perhaps this is the result of some fallible progress-checking function.
+/// let maybe_progress: Option<u32> = None;
+/// progressbar.set_value(&ui, maybe_progress);
+/// 
+/// // And of course, you can always set it by hand.
+/// progressbar.set_value(&ui, ProgressBarValue::Indeterminate);
+/// # window.set_child(&ui, progressbar); 
+/// # ui.quit();
+/// # ui.main();
+/// ```
 pub enum ProgressBarValue {
     /// Represents a set, consistent percentage of the bar to be filled
     ///
@@ -15,6 +45,25 @@ pub enum ProgressBarValue {
     Indeterminate,
 }
 
+impl From<u32> for ProgressBarValue {
+    fn from(value: u32) -> ProgressBarValue {
+        if value <= 100 {
+            ProgressBarValue::Determinate(value)
+        } else {
+            ProgressBarValue::Determinate(100)
+        }
+    }
+}
+
+impl From<Option<u32>> for ProgressBarValue {
+    fn from(value: Option<u32>) -> ProgressBarValue {
+        match value {
+            Some(v) => v.into(),
+            None => ProgressBarValue::Indeterminate
+        }
+    }
+}
+
 define_control! {
   /// A bar that fills up with a set percentage, used to show completion of a
   ///
@@ -34,27 +83,16 @@ impl ProgressBar {
     }
 
     /// Create a new indeterminate progress bar
-    pub fn indeterminate() -> ProgressBar {
+    pub fn indeterminate(ctx: &UI) -> ProgressBar {
         let mut pb = ProgressBar::new();
-        pb.set_indeterminate();
+        pb.set_value(ctx, ProgressBarValue::Indeterminate);
         pb
     }
 
-    /// Set the value of the progress bar to a determinate value
-    ///
-    /// If `value` is larger than 100, than the value will be set to 100.
-    pub fn set_determinate(&mut self, value: u32) {
-        self.set_value(ProgressBarValue::Determinate(value));
-    }
-
-    /// Set the value of the progress bar to be indeterminate
-    pub fn set_indeterminate(&mut self) {
-        self.set_value(ProgressBarValue::Indeterminate);
-    }
-
-    /// Set the value of the progress bar
-    pub fn set_value(&mut self, value: ProgressBarValue) {
-        let sys_value = match value {
+    /// Set the value of the progress bar. See [`ProgressBarValue`] for the values that can be passed in.
+    /// [`ProgressBarValue`]: enum.ProgressBarValue.html
+    pub fn set_value<V: Into<ProgressBarValue>>(&mut self, _ctx: &UI, value: V) {
+        let sys_value = match value.into() {
             ProgressBarValue::Determinate(value) => {
                 let value = if value > 100 { 100 } else { value };
                 value as i32
@@ -65,7 +103,7 @@ impl ProgressBar {
     }
 
     /// Get the value of the progress bar
-    pub fn value(&self) -> ProgressBarValue {
+    pub fn value(&self, _ctx: &UI) -> ProgressBarValue {
         let sys_value = unsafe { ui_sys::uiProgressBarValue(self.uiProgressBar) };
         if sys_value.is_negative() {
             assert!(