ProgressBar¶

A horizontal bar to visualize task progress. The task being monitored can be of known or indeterminate length.

Usage¶

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¶

class toga.ProgressBar(id=None, style=None, max=1.0, value=0.0, running=False, **kwargs)¶

Bases: Widget

Create a new Progress Bar widget.

Parameters:

id (str | None) – The ID for the widget.
style (StyleT | None) – A style object. If no style is provided, a default style will be applied to the widget.
max (str | SupportsFloat) – 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.
value (str | SupportsFloat) – 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.
running (bool) – Describes whether the indicator is running at the time it is created. Default is False.
kwargs – Initial style properties.

property enabled: 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.

property is_determinate: bool¶

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

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

property is_running: 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.

property max: float | None¶

The value indicating completion of the task being monitored.

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

start()¶

Start the progress bar.

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

Return type:: None

stop()¶

Stop the progress bar.

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

Return type:: None

property value: 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.