API Definition

adafruit_progressbar

Dynamic progress bar widget for CircuitPython displays

  • Author(s): Brent Rubell and Hugo Dahl

Implementation Notes

Software and Dependencies:

class adafruit_progressbar.ProgressBarBase(position: Tuple[int, int], size: Tuple[int, int], value: Union[int, float] = 0, bar_color=65280, border_color=16777215, fill_color=0, border_thickness: int = 1, margin_size: int = 1, value_range: Union[Tuple[int, int], Tuple[float, float]] = (0, 100))

The base class for dynamic progress bar widgets.

Parameters:
  • position (Tuple[int, int]) – The coordinates (x, y) of the top left corner
  • size (Tuple[int, int]) – The size (width, height) of the progress bar
  • bar_color (int) – The color of the bar representing the value. This can be a hexadecimal value for color (0x224466). Default: 0x00FF00 (Solid green)
  • border_color (int) – The color of the border around the progress bar. This can be a hexadecimal value for color (0x4488BB). Default: 0xFFFFFF (White)
  • fill_color (int) – The colour of the bar representing the remainder of the value. i.e. if the current value is 42%, the 42 value is represented by the bar_color parameter. The remainder, 58%, will be displayed in this color. This can also be a hexadecimal value for color (0xEE7755). Default: 0x000000 (Black)
  • margin_size (bool) – Specify whether a margin between the border of the widget and the bar representing the value should be visible or not. Default: True
  • value_range (Tuple[int, int] or Tuple[float, float]) – Specify the range of allowed values for which the progress should be displayed. When setting the “value” property, this range is the one against which its progression will be determined. Default: (0.0, 1.0)
bar_color

The color of the bar’s fill

Return type:int/None
border_color

Returns the currently configured value for the color of the outline (border) of the widget.

Return type:int
border_thickness

Gets the currently configured thickness of the border (in pixels)

Return type:int
fill

The fill of the progress bar. Can be a hex value for a color or None for transparent.

Return type:int
fill_height() → int

Returns the amount of vertical space within the widget which can be used for value display. This is typically the width of the widget as defined, minus any visually reserved space.

Return type:int
fill_width() → int

Returns the amount of horizontal space within the widget which can be used for value display. This is typically the width of the widget as defined, minus any visually reserved space.

Return type:int
get_value_ratio(value: Union[int, float]) → float

Gets the ratio (percentage) of a given value within the range of self.minimum and self.maximum.

Parameters:value (int/float) – The value for which the ration should be calculated
Returns:The ratio of value:range
Return type:float
margin_size

Returns the size of the margin on a single side of the display

Return int:
maximum

The maximum (highest) value which can be displayed

Return type:int/float
minimum

The minimum (lowest) value which can be displayed

Return type:int/float
progress

Gets the current displayed value of the widget.

Returns:The current progress ratio
Return type:float
range

The range which can be handled as a Tuple(min,max)

Return type:Tuple(int/float, int/float)
value

The current value of the control, used to determine its progress/ratio :rtype: int/float

widget_height

The total height of the widget, in pixels. Includes the border and margin.

Return type:int
widget_size

The size at the outer edge of the control, returned as a tuple (width, height)

Return type:int
widget_width

The total width of the widget, in pixels. Includes the border and margin.

Return type:Tuple[int, int]

horizontalprogressbar

Dynamic progress bar widget for CircuitPython displays

  • Author(s): Brent Rubell, Hugo Dahl

Implementation Notes

Software and Dependencies:

class adafruit_progressbar.horizontalprogressbar.HorizontalFillDirection

Bases: object

This enum is used to specify the direction in which the progress bar’s display bar should fill as the value represented increases.

DEFAULT = 0

Fill from the right-hand side toward the left

LEFT_TO_RIGHT = 0

Specifies the default fill direction (LEFT_TO_RIGHT)

class adafruit_progressbar.horizontalprogressbar.HorizontalProgressBar(position: Tuple[int, int], size: Tuple[int, int], min_value: Union[int, float] = 0, max_value: Union[int, float] = 100, value: Union[int, float] = 0, bar_color: Union[int, Tuple[int, int, int]] = 65280, outline_color: Union[int, Tuple[int, int, int]] = 16777215, fill_color: Union[int, Tuple[int, int, int]] = 4473924, border_thickness: int = 1, margin_size: int = 1, direction: adafruit_progressbar.horizontalprogressbar.HorizontalFillDirection = 0)

Bases: adafruit_progressbar.ProgressBarBase

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:

--------------------------------
| Left-to-right  |  1-3 to 2-4 |
--------------------------------
| Right-to-left  |  2-4 to 1-3 |
--------------------------------

Horizontal

1-----------------------2
|                       |
|                       |
3-----------------------4
Parameters:
  • position (Tuple[int, int]) – The coordinates of the top-left corner of progress bar.
  • size (Tuple[int, int]) – The size in (width, height) of the progress bar, in pixels
  • min_value (int, float) – The lowest value which can be displayed by the progress bar. When the “value” property is set to the same value, no bar is displayed.
  • max_value (int, float) – This highest value which can be displayed by the progress bar. When the “value” property is set to the same value, the bar shows as full.
  • value (int, float) – The starting value to be displayed. Must be between the values of min_value and max_value, inclusively.
  • bar_color (int, Tuple[byte, byte, byte]) – The color of the value portion of the progress bar. Can be a hex value for color (i.e. 0x225588).
  • outline_color (int, Tuple[byte, byte, byte]) – The colour for the outline of the progress bar. Can be a hex value for color (i.e. 0x225588).
  • fill_color (int, Tuple[byte, byte, byte]) – The colour for the background within the progress bar. Can be a hex value for color (i.e. 0x225588).
  • border_thickness (int) – The thickness of the outer border of the widget. If it is 1 or larger, will be displayed with the color of the “outline_color” parameter.
  • margin_size (int) – The thickness (in pixels) of the margin between the border and the bar. If it is 1 or larger, will be filled in by the color of the “fill_color” parameter.
  • direction (HorizontalFillDirection) – The direction of the fill
bar_color

The color of the bar’s fill

Return type:int/None
border_color

Returns the currently configured value for the color of the outline (border) of the widget.

Return type:int
border_thickness

Gets the currently configured thickness of the border (in pixels)

Return type:int
fill

The fill of the progress bar. Can be a hex value for a color or None for transparent.

Return type:int
fill_height() → int

Returns the amount of vertical space within the widget which can be used for value display. This is typically the width of the widget as defined, minus any visually reserved space.

Return type:int
fill_width() → int

Returns the amount of horizontal space within the widget which can be used for value display. This is typically the width of the widget as defined, minus any visually reserved space.

Return type:int
get_value_ratio(value: Union[int, float]) → float

Gets the ratio (percentage) of a given value within the range of self.minimum and self.maximum.

Parameters:value (int/float) – The value for which the ration should be calculated
Returns:The ratio of value:range
Return type:float
margin_size

Returns the size of the margin on a single side of the display

Return int:
maximum

The maximum (highest) value which can be displayed

Return type:int/float
minimum

The minimum (lowest) value which can be displayed

Return type:int/float
progress

Gets the current displayed value of the widget.

Returns:The current progress ratio
Return type:float
range

The range which can be handled as a Tuple(min,max)

Return type:Tuple(int/float, int/float)
value

The current value of the control, used to determine its progress/ratio :rtype: int/float

widget_height

The total height of the widget, in pixels. Includes the border and margin.

Return type:int
widget_size

The size at the outer edge of the control, returned as a tuple (width, height)

Return type:int
widget_width

The total width of the widget, in pixels. Includes the border and margin.

Return type:Tuple[int, int]

progressbar

Dynamic progress bar widget for CircuitPython displays

  • Author(s): Brent Rubell

Implementation Notes

Software and Dependencies:

class adafruit_progressbar.progressbar.ProgressBar(x: int, y: int, width: int, height: int, progress: float = 0.0, bar_color=65280, outline_color=16777215, stroke: int = 1)

Bases: adafruit_progressbar.horizontalprogressbar.HorizontalProgressBar

A dynamic progress bar widget.

NOTE: This class is made available for backward compatibility with v1.x of the adafruit_progressbar library. New uses should not use this class, but instead, use its successor, HorizontalProgressBar.

Parameters:
  • x (int) – The x-position of the top left corner.
  • y (int) – The y-position of the top left corner.
  • width (int) – The width of the progress bar.
  • height (int) – The height of the progress bar.
  • bar_color – The color of the progress bar. Can be a hex value for color.
  • outline_color (int) – The outline of the progress bar. Can be a hex value for color.
  • stroke (int) – Used for the outline_color
bar_color

The color of the bar’s fill

Return type:int/None
border_color

Returns the currently configured value for the color of the outline (border) of the widget.

Return type:int
border_thickness

Gets the currently configured thickness of the border (in pixels)

Return type:int
fill

The fill of the progress bar. Can be a hex value for a color or None for transparent.

Return type:int
fill_height() → int

Returns the amount of vertical space within the widget which can be used for value display. This is typically the width of the widget as defined, minus any visually reserved space.

Return type:int
fill_width() → int

Returns the amount of horizontal space within the widget which can be used for value display. This is typically the width of the widget as defined, minus any visually reserved space.

Return type:int
get_value_ratio(value: Union[int, float]) → float

Gets the ratio (percentage) of a given value within the range of self.minimum and self.maximum.

Parameters:value (int/float) – The value for which the ration should be calculated
Returns:The ratio of value:range
Return type:float
margin_size

Returns the size of the margin on a single side of the display

Return int:
maximum

The maximum (highest) value which can be displayed

Return type:int/float
minimum

The minimum (lowest) value which can be displayed

Return type:int/float
progress

Gets the progress value displayed

Rtype float:
range

The range which can be handled as a Tuple(min,max)

Return type:Tuple(int/float, int/float)
value

The current value of the control, used to determine its progress/ratio :rtype: int/float

widget_height

The total height of the widget, in pixels. Includes the border and margin.

Return type:int
widget_size

The size at the outer edge of the control, returned as a tuple (width, height)

Return type:int
widget_width

The total width of the widget, in pixels. Includes the border and margin.

Return type:Tuple[int, int]

verticalprogressbar

Dynamic progress bar widget for CircuitPython displays

  • Author(s): Brent Rubell, Hugo Dahl

Implementation Notes

Software and Dependencies:

class adafruit_progressbar.verticalprogressbar.VerticalFillDirection

Bases: object

This enum is used to specify the direction in which the progress bar’s display bar should fill as the value represented increases.

BOTTOM_TO_TOP = 0

Default fill direction (BOTTOM_TO_TOP)

DEFAULT = 0

Fills from the top down toward the bottom

class adafruit_progressbar.verticalprogressbar.VerticalProgressBar(position: Tuple[int, int], size: Tuple[int, int], min_value: Union[int, float] = 0, max_value: Union[int, float] = 100, value: Union[int, float] = 0, bar_color: Union[int, Tuple[int, int, int]] = 65280, outline_color: Union[int, Tuple[int, int, int]] = 16777215, fill_color: Union[int, Tuple[int, int, int]] = 4473924, border_thickness: int = 1, margin_size: int = 1, direction: adafruit_progressbar.horizontalprogressbar.HorizontalFillDirection = 0)

Bases: adafruit_progressbar.horizontalprogressbar.HorizontalProgressBar

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:

--------------------------------
| Bottom-to-top  |  3-4 to 1-2 |
--------------------------------
| Top-to-bottom  |  1-2 to 3-4 |
--------------------------------

1--2
|  |
|  |
|  |
|  |
3--4
Parameters:
  • position (Tuple[int, int]) – The coordinates of the top-left corner of progress bar.
  • size (Tuple[int, int]) – The size in (width, height) of the progress bar, in pixels
  • min_value (int, float) – The lowest value which can be displayed by the progress bar. When the “value” property is set to the same value, no bar is displayed.
  • max_value (int, float) – This highest value which can be displayed by the progress bar. When the “value” property is set to the same value, the bar shows as full.
  • value (int, float) – The starting value to be displayed. Must be between the values of min_value and max_value, inclusively.
  • bar_color (int, Tuple[byte, byte, byte]) – The color of the value portion of the progress bar. Can be a hex value for color (i.e. 0x225588).
  • outline_color (int, Tuple[byte, byte, byte]) – The colour for the outline of the progress bar. Can be a hex value for color (i.e. 0x225588).
  • fill_color (int, Tuple[byte, byte, byte]) – The colour for the background within the progress bar. Can be a hex value for color (i.e. 0x225588).
  • border_thickness (int) – The thickness of the outer border of the widget. If it is 1 or larger, will be displayed with the color of the “outline_color” parameter.
  • margin_size (int) – The thickness (in pixels) of the margin between the border and the bar. If it is 1 or larger, will be filled in by the color of the “fill_color” parameter.
  • direction (VerticalFillDirection) – The direction of the fill
bar_color

The color of the bar’s fill

Return type:int/None
border_color

Returns the currently configured value for the color of the outline (border) of the widget.

Return type:int
border_thickness

Gets the currently configured thickness of the border (in pixels)

Return type:int
fill

The fill of the progress bar. Can be a hex value for a color or None for transparent.

Return type:int
fill_height() → int

Returns the amount of vertical space within the widget which can be used for value display. This is typically the width of the widget as defined, minus any visually reserved space.

Return type:int
fill_width() → int

Returns the amount of horizontal space within the widget which can be used for value display. This is typically the width of the widget as defined, minus any visually reserved space.

Return type:int
get_value_ratio(value: Union[int, float]) → float

Gets the ratio (percentage) of a given value within the range of self.minimum and self.maximum.

Parameters:value (int/float) – The value for which the ration should be calculated
Returns:The ratio of value:range
Return type:float
margin_size

Returns the size of the margin on a single side of the display

Return int:
maximum

The maximum (highest) value which can be displayed

Return type:int/float
minimum

The minimum (lowest) value which can be displayed

Return type:int/float
progress

Gets the current displayed value of the widget.

Returns:The current progress ratio
Return type:float
range

The range which can be handled as a Tuple(min,max)

Return type:Tuple(int/float, int/float)
value

The current value of the control, used to determine its progress/ratio :rtype: int/float

widget_height

The total height of the widget, in pixels. Includes the border and margin.

Return type:int
widget_size

The size at the outer edge of the control, returned as a tuple (width, height)

Return type:int
widget_width

The total width of the widget, in pixels. Includes the border and margin.

Return type:Tuple[int, int]