Progress Bar¶
macOS |
GTK+ |
Windows |
iOS |
Android |
Django |
---|---|---|---|---|---|
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:
|
|
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 inital running mode.
factory (
module
) – A python module that is capable to return a implementation of this class with the same name. (optional & normally not needed)
- MIN_WIDTH = 100¶
- add(*children)¶
Add nodes as children of this one. If a node already has a different parent, it will be moved over. This does nothing if a node already is a child of this node.
- Parameters
children – Nodes to add as children of this node.
- Raises
ValueError – If this node is a leaf, and cannot have children.
- property app¶
The App to which this widget belongs. On setting the app we also iterate over all children of this widget and set them to the same app.
- Returns
The
toga.App
to which this widget belongs.- Raises
ValueError – If the widget is already associated with another app.
- property can_have_children¶
Determine if the node can have children.
This does not resolve whether there actually are any children; it only confirms whether children are theoretically allowed.
- property children¶
The children of this node. This always returns a list, even if the node is a leaf and cannot have children.
- Returns
A list of the children for this widget.
- property enabled¶
- focus()¶
- property id¶
The node identifier. This id can be used to target styling directives
- Returns
The widgets identifier as a
str
.
- insert(index, child)¶
Insert a node as a child of this one. If the node already has a different parent, it will be moved over. This does nothing if the node already is a child of this node.
- Parameters
index – Position of child node.
child – A node to insert as a child of this node.
- Raises
ValueError – If this node is a leaf, and cannot have children.
- 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 ifmax
is None
- property is_running¶
Use
start()
andstop()
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
orfloat
.
- property parent¶
The parent of this node.
- Returns
The parent of this node. Returns None if this node is the root node.
- refresh()¶
Refresh the layout and appearance of the tree this node is contained in.
- refresh_sublayouts()¶
- remove(*children)¶
Remove child nodes of this node. This does nothing if a given node is not a child of this node.
- Parameters
children – Child nodes to remove.
- Raises
ValueError – If this node is a leaf, and cannot have children.
- property root¶
The root of the tree containing this node.
- Returns
The root node. Returns self if this node is the root node.
- 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
orfloat
.
- property window¶
The Window to which this widget belongs. On setting the window, we automatically update all children of this widget to belong to the same window.
- Returns
The
toga.Window
to which the widget belongs.