Progress Bar#

Availability (Key)#

macOS

GTK

Windows

iOS

Android

Web

The progress bar is a simple widget for showing a percentage progress for task completion.

Usage#

import toga

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

# Update progress
progress.value = 10

A progress bar can be in one of four visual states, determined by its max properties, and with the start() and stop() methods. Calling the start() method will make the progress bar enter running mode, and calling stop() will exit running mode. See the table below:

max

is_running

Behavior

None

False

disabled

None

True

indeterminate (continuous animation)

number

False

show percentage

number

True

show percentage and busy animation

If a progress bar is indeterminate, it is communicating that it has no exact percentage to report, but that work is still begin done. It may communicate this by continuously pulsing back and forth, for example.

A second type of animation occurs when a percentage is displayed and the application wants to signal that progress is still “busy”. Such an animation might involve gradually altering a lighting gradient on the progress bar.

Note: Not every platform may support these animations.

ProgressBar state examples:

# use indeterminate mode
progress.max = None
print(progress.is_determinate) #  => False
progress.start()
print(progress.is_running) #  => True

# show percentage and busy animation (if supported)
progress.max = 100
print(progress.is_determinate) #  => True

# signal that no work is begin done with the disabled state
progress.max = None
print(progress.is_determinate) #  => False
progress.stop()
print(progress.is_running) #  => False

Reference#

class toga.widgets.progressbar.ProgressBar(id=None, style=None, max=1, value=0, running=False, factory=None)#
Parameters:
  • id (str) – An identifier for this widget.

  • style (Style) – An optional style object. If no style is provided then a new one will be created for the widget.

  • max (float) – The maximum value of the progressbar.

  • value (float) – To define the current progress of the progressbar.

  • running (bool) – Set the initial running mode.

MIN_WIDTH = 100#
property is_determinate#

Determinate progress bars have a numeric max value (not None).

Returns:

True if this progress bar is determinate (max is not None) False if max is None

property is_running#

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

Returns:

True if this progress bar is running False otherwise

property max#

The maximum value of the progressbar.

Returns:

The maximum value as a int or float.

start()#

Starting this progress bar puts it into running mode.

stop()#

Stop this progress bar (if not already stopped).

property value#

Returns: The current value as a int or float.