Skip to content

ProgressBar

Usage

The task being monitored can be of known or indeterminate length.

If a progress bar has a max value, it is a determinate progress bar. The value of the progress bar can be altered over time, indicating progress on a task. The visual indicator of the progress bar will be filled indicating the proportion of value relative to max. max can be any positive numerical value.

import toga

progress = toga.ProgressBar(max=100, value=1)

# Start progress animation
progress.start()

# Update progress to 10%
progress.value = 10

# Stop progress animation
progress.stop()

If a progress bar does not have a max value (i.e., max == None), it is an indeterminate progress bar. Any change to the value of an indeterminate progress bar will be ignored. When started, an indeterminate progress bar animates as a throbbing or "ping pong" animation.

import toga

progress = toga.ProgressBar(max=None)

# Start progress animation
progress.start()

# Stop progress animation
progress.stop()

Notes

  • The visual appearance of progress bars varies from platform to platform. Toga will try to provide a visual distinction between running and not-running determinate progress bars, but this cannot be guaranteed.

Reference

Bases: Widget

Source code in core/src/toga/widgets/progressbar.py 
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
class ProgressBar(Widget):
    _MIN_WIDTH = 100

    def __init__(
        self,
        id: str | None = None,
        style: StyleT | None = None,
        max: str | SupportsFloat = 1.0,
        value: str | SupportsFloat = 0.0,
        running: bool = False,
        **kwargs,
    ):
        """Create a new Progress Bar widget.

        :param id: The ID for the widget.
        :param style: A style object. If no style is provided, a default style
            will be applied to the widget.
        :param max: The value that represents completion of the task. Must
            be > 0.0; defaults to 1.0. A value of `None` indicates that the task
            length is indeterminate.
        :param value: The current progress against the maximum value. Must be
            between 0.0 and `max`; any value outside this range will be
            clipped. Defaults to 0.0.
        :param running: Describes whether the indicator is running at the time
            it is created. Default is False.
        :param kwargs: Initial style properties.
        """
        super().__init__(id, style, **kwargs)

        self.max = max
        self.value = value

        if running:
            self.start()

    def _create(self) -> Any:
        return self.factory.ProgressBar(interface=self)

    @property
    def enabled(self) -> Literal[True]:
        """Is the widget currently enabled? i.e., can the user interact with the widget?

        ProgressBar widgets cannot be disabled; this property will always return True;
        any attempt to modify it will be ignored.
        """
        return True

    @enabled.setter
    def enabled(self, value: object) -> None:
        pass

    @property
    def is_running(self) -> bool:
        """Describe if the activity indicator is currently running.

        Use `start()` and `stop()` to change the running state.

        True if this activity indicator is running; False otherwise.
        """
        return self._impl.is_running()

    @property
    def is_determinate(self) -> bool:
        """Describe whether the progress bar has a known or indeterminate maximum.

        True if the progress bar has determinate length; False otherwise.
        """
        return self.max is not None

    def start(self) -> None:
        """Start the progress bar.

        If the progress bar is already started, this is a no-op.
        """
        if not self.is_running:
            self._impl.start()

    def stop(self) -> None:
        """Stop the progress bar.

        If the progress bar is already stopped, this is a no-op.
        """
        if self.is_running:
            self._impl.stop()

    @property
    def value(self) -> float:
        """The current value of the progress indicator.

        If the progress bar is determinate, the value must be between 0 and
        `max`. Any value outside this range will be clipped.

        If the progress bar is indeterminate, changes in value will be ignored,
        and the current value will be returned as `None`.
        """
        return self._impl.get_value()

    @value.setter
    def value(self, value: str | SupportsFloat) -> None:
        if self.max is not None:
            value = max(0.0, min(self.max, float(value)))
            self._impl.set_value(value)

    @property
    def max(self) -> float | None:
        """The value indicating completion of the task being monitored.

        Must be a number > 0, or `None` for a task of indeterminate length.
        """
        return self._impl.get_max()

    @max.setter
    def max(self, value: str | SupportsFloat | None) -> None:
        if value is None:
            self._impl.set_max(None)
        elif float(value) > 0.0:
            self._impl.set_max(float(value))
        else:
            raise ValueError("max value must be None, or a numerical value > 0")

enabled property writable

Is the widget currently enabled? i.e., can the user interact with the widget?

ProgressBar widgets cannot be disabled; this property will always return True; any attempt to modify it will be ignored.

is_determinate property

Describe whether the progress bar has a known or indeterminate maximum.

True if the progress bar has determinate length; False otherwise.

is_running property

Describe if the activity indicator is currently running.

Use start() and stop() to change the running state.

True if this activity indicator is running; False otherwise.

max property writable

The value indicating completion of the task being monitored.

Must be a number > 0, or None for a task of indeterminate length.

value property writable

The current value of the progress indicator.

If the progress bar is determinate, the value must be between 0 and max. Any value outside this range will be clipped.

If the progress bar is indeterminate, changes in value will be ignored, and the current value will be returned as None.

__init__(id=None, style=None, max=1.0, value=0.0, running=False, **kwargs)

Create a new Progress Bar widget.

:param id: The ID for the widget. :param style: A style object. If no style is provided, a default style will be applied to the widget. :param max: The value that represents completion of the task. Must be > 0.0; defaults to 1.0. A value of None indicates that the task length is indeterminate. :param value: The current progress against the maximum value. Must be between 0.0 and max; any value outside this range will be clipped. Defaults to 0.0. :param running: Describes whether the indicator is running at the time it is created. Default is False. :param kwargs: Initial style properties.

Source code in core/src/toga/widgets/progressbar.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
def __init__(
    self,
    id: str | None = None,
    style: StyleT | None = None,
    max: str | SupportsFloat = 1.0,
    value: str | SupportsFloat = 0.0,
    running: bool = False,
    **kwargs,
):
    """Create a new Progress Bar widget.

    :param id: The ID for the widget.
    :param style: A style object. If no style is provided, a default style
        will be applied to the widget.
    :param max: The value that represents completion of the task. Must
        be > 0.0; defaults to 1.0. A value of `None` indicates that the task
        length is indeterminate.
    :param value: The current progress against the maximum value. Must be
        between 0.0 and `max`; any value outside this range will be
        clipped. Defaults to 0.0.
    :param running: Describes whether the indicator is running at the time
        it is created. Default is False.
    :param kwargs: Initial style properties.
    """
    super().__init__(id, style, **kwargs)

    self.max = max
    self.value = value

    if running:
        self.start()

start()

Start the progress bar.

If the progress bar is already started, this is a no-op.

Source code in core/src/toga/widgets/progressbar.py 
77
78
79
80
81
82
83
def start(self) -> None:
    """Start the progress bar.

    If the progress bar is already started, this is a no-op.
    """
    if not self.is_running:
        self._impl.start()

stop()

Stop the progress bar.

If the progress bar is already stopped, this is a no-op.

Source code in core/src/toga/widgets/progressbar.py 
85
86
87
88
89
90
91
def stop(self) -> None:
    """Stop the progress bar.

    If the progress bar is already stopped, this is a no-op.
    """
    if self.is_running:
        self._impl.stop()