Update documentation

Author: hugodahl

adafruit_progressbar/__init__.py

@@ -80,12 +80,13 @@ def __init__(
         position,
         size,
         start_value=0.0,
+        value=0,
         bar_color=0x00FF00,
         outline_color=0xFFFFFF,
         fill_color=0x000000,
         border_thickness=1,
         show_margin=False,
-        value_range=(0.0, 1.0),
+        value_range=(0, 100),
     ):
 
         self._widget_size = size
@@ -100,6 +101,7 @@ def __init__(
         self._border_thickness = border_thickness
         self._show_margin = show_margin
         self._range = value_range
+        self._value = value
 
         super().__init__(
             self._bitmap,
@@ -176,6 +178,24 @@ def fill(self, color):
             self._palette[2] = color
             self._palette.make_opaque(0)
 
+    @property
+    def value(self):
+        """
+        The current value of the control, used to determine its progress/ratio
+        :return: int/float
+        """
+        return self._value
+
+    @value.setter
+    def value(self, value):
+        self._value = value
+        # Convert value to float since we may be dealing with
+        # integer types, and we can't work with integer division
+        # to get a ratio (position) of "value" within range.
+        self.progress = (float(value - self._range[0])) / (
+            abs(self._range[0]) + abs(self._range[1])
+        )
+
     @property
     def progress(self):
         """Gets the current displayed value of the widget."""

adafruit_progressbar/horizontalprogressbar.py

@@ -12,22 +12,88 @@
 """
 
 # import displayio
-from . import ProgressBarBase  # , FillDirection
+from . import ProgressBarBase, FillDirection
 
 
 class HorizontalProgressBar(ProgressBarBase):
-    """
-    A progress bar that goes horizontally.
+    """A dynamic progress bar widget.
+
+    The anchor position is the position where the control would start if it
+    were being read visually or on paper, where the (0, 0) position is
+    the lower-left corner for ascending progress bars (fills from the bottom to
+    to the top in vertical bars, or from the left to the right in horizontal
+    progress bars), upper-left corner for descending progress bars (fills from
+    the top to the bottom).
+
+    Using the diagrams below, the bar will fill in the following directions::
+
+                         -----------------------------
+                         | Horizontal   | Vertical   |
+        ----------------------------------------------
+        | Ascending      |  1-3 to 2-4 |  3-4 to 1-2 |
+        ----------------------------------------------
+        | Descending     |  2-4 to 1-3 |  1-2 to 3-4 |
+        ----------------------------------------------
+
+        Vertical            Horizontal
+
+        1--2                1-----------------------2
+        |  |                |                       |
+        |  |                |                       |
+        |  |                3-----------------------4
+        |  |
+        3--4
+
+    :param anchor_position: The anchor coordinates of the progress bar.
+    :type anchor_position: Tuple[int, int]
+    :param size: The size in (width, height) of the progress bar
+    :type size: Tuple[int, int]
+    :param progress: The percentage of the progress bar.
+    :type progress: float
+    :param bar_color: The color of the progress bar. Can be a hex
+        value for color.
+    :param outline_color: The outline of the progress bar. Can be a hex
+        value for color.
+    :type outline_color: int
+    :param border_thickness: Used for the outline_color
+    :type border_thickness: int
+    :param show_margin: Whether or not to have a margin between the border and
+        the fill, or not.
+    :type show_margin: bool
+    :param direction: The direction of the fill
+    :type direction: FillDirection
+
     """
 
-    def __init__(self):
-        """
-        Get stuff, horizontally!
-        :param args:
-        :param kwargs:
-        """
+    # pylint: disable=bad-option-value, unused-argument, too-many-arguments
+    def __init__(
+        self,
+        anchor_position,
+        size,
+        min_value=0,
+        max_value=100,
+        progress=0.0,
+        value=0,
+        bar_color=0x00FF00,
+        outline_color=0xFFFFFF,
+        fill_color=0x444444,
+        border_thickness=1,
+        show_margin=True,
+        direction=FillDirection.DEFAULT,
+    ):
 
-        super().__init__((0, 0), (100, 20), 0.0)
+        super().__init__(
+            anchor_position,
+            size,
+            progress,
+            bar_color,
+            outline_color,
+            fill_color,
+            value,
+            border_thickness=border_thickness,
+            show_margin=show_margin,
+            value_range=(min_value, max_value),
+        )
 
     def render(self, _previous_value, _new_value, _progress_value) -> None:
         """

adafruit_progressbar/progressbar.py

@@ -22,7 +22,7 @@
 """
 
 # imports
-from horizontalprogressbar import HorizontalProgressBar
+from adafruit_progressbar.horizontalprogressbar import HorizontalProgressBar
 
 
 # pylint: disable=too-many-arguments, too-few-public-methods
@@ -68,49 +68,13 @@ def __init__(
         super().__init__(
             (x, y),
             (width, height),
+            0,
+            100,
             progress,
+            0,
             bar_color,
             outline_color,
-            0x444444,
+            0x000000,
             border_thickness=stroke,
             show_margin=True,
-            value_range=(0.0, 1.0),
         )
-
-    #     _outline_color: int  # The colour used for the border of the widget
-
-    def render(self, _previous_value, _new_value, _progress_value) -> None:
-        """
-        The rendering mechanism to display the newly set value.
-
-        :param _previous_value:  The value from which we are updating
-        :type _previous_value: object
-        :param _new_value: The value to which we are updating
-        :type _new_value: object
-        :param _progress_value: The value of the progress, or ratio between the new value and the
-            maximum value
-        :type _progress_value: float
-        :rtype None:
-        """
-
-        if _previous_value == _new_value:
-            return  # Do nothing if there's nothing to update
-
-        if _previous_value > _new_value:
-            # Remove color in range from width*value+margin to width-margin
-            # from right to left
-            _prev_pixel = max(2, int(self.widget_width * self.progress - 2))
-            _new_pixel = max(int(self.widget_width * _new_value - 2), 2)
-            for _w in range(_prev_pixel, _new_pixel - 1, -1):
-                for _h in range(2, self.widget_height - 2):
-                    self._bitmap[_w, _h] = 0
-        else:
-            # fill from the previous x pixel to the new x pixel
-            _prev_pixel = max(2, int(self.widget_width * self.progress - 3))
-            _new_pixel = min(
-                int(self.widget_width * _new_value - 2),
-                int(self.widget_width * 1.0 - 3),
-            )
-            for _w in range(_prev_pixel, _new_pixel + 1):
-                for _h in range(2, self.widget_height - 2):
-                    self._bitmap[_w, _h] = 2

adafruit_progressbar/verticalprogressbar.py

@@ -9,8 +9,7 @@
 Dynamic progress bar widget for CircuitPython displays
 
 
-* Author(s): Brent Rubell
-                Hugo Dahl
+* Author(s): Brent Rubell, Hugo Dahl
 
 Implementation Notes
 --------------------
@@ -40,13 +39,13 @@ class VerticalProgressBar(ProgressBarBase):
 
     Using the diagrams below, the bar will fill in the following directions::
 
-                     -----------------------------
-                     | Horizontal   | Vertical   |
-    ----------------------------------------------
-    | Ascending      |  1-3 to 2-4 |  3-4 to 1-2 |
-    ----------------------------------------------
-    | Descending     |  2-4 to 1-3 |  1-2 to 3-4 |
-    ----------------------------------------------
+                         -----------------------------
+                         | Horizontal   | Vertical   |
+        ----------------------------------------------
+        | Ascending      |  1-3 to 2-4 |  3-4 to 1-2 |
+        ----------------------------------------------
+        | Descending     |  2-4 to 1-3 |  1-2 to 3-4 |
+        ----------------------------------------------
 
         Vertical            Horizontal
 
@@ -86,9 +85,10 @@ def __init__(
         min_value=0,
         max_value=100,
         progress=0.0,
+        value=0,
         bar_color=0x00FF00,
         outline_color=0xFFFFFF,
-        fill_color=None,
+        fill_color=0x444444,
         stroke=1,
         margin=False,
         direction=FillDirection.DEFAULT,
@@ -130,12 +130,13 @@ def __init__(
             anchor_position,
             size,
             progress,
+            value,
             bar_color,
             outline_color,
             fill_color,
             border_thickness=stroke,
             show_margin=True,
-            value_range=(0.0, 1.0),
+            value_range=(min_value, max_value),
         )
 
     # pylint: disable=too-many-locals

docs/api.rst

@@ -6,6 +6,11 @@ API Definition
 .. If your library file(s) are nested in a directory (e.g. /adafruit_foo/foo.py)
 .. use this format as the module name: "adafruit_foo.foo"
 
+.. automodule:: adafruit_progressbar.horizontalprogressbar
+   :members:
+   :show-inheritance:
+   :inherited-members:
+
 .. automodule:: adafruit_progressbar.progressbar
    :members:
    :show-inheritance: