ProgressWidget API¶

`ProgressWidget(widget_id=None)` ¶

Bases: BaseWidget

Create a linear progress bar to visually display task completion status.

Linear progress bars are a classic way to display task progress, data loading, step completion, and other scenarios. They clearly communicate the process from start to finish.

Core Features

Dynamic Updates: Support setting, increasing, decreasing, resetting, or directly completing progress.
Themed: Provides multiple preset themes (such as success, warning, error) to visually reflect status through color.
Text Labels: Can add descriptive labels above the progress bar.
Percentage Display: Option to show precise completion percentage inside the progress bar.
Custom Appearance: Freely adjust the width, height, border radius, and background color of the progress bar.

Attributes:

Name	Type	Description
`value`	`float`	Current progress value.
`max_value`	`float`	Maximum progress value, default is 100.
`label`	`Optional[str]`	Descriptive text displayed above the progress bar.
`theme`	`ProgressTheme`	Color theme of the progress bar.

Examples:

Create a progress bar showing file download progress:

Python

from email_widget.widgets import ProgressWidget
from email_widget.core.enums import ProgressTheme

download_progress = (ProgressWidget()
                     .set_label("File Download Progress")
                     .set_value(75)
                     .set_theme(ProgressTheme.PRIMARY)
                     .set_height("24px"))

# Assuming email is an Email object
# email.add_widget(download_progress)

Create a progress bar showing storage usage with warning status:

Python

storage_usage = (ProgressWidget()
                 .set_label("Storage Usage")
                 .set_value(95)
                 .set_theme(ProgressTheme.WARNING)
                 .show_percentage(True))

Initialize ProgressWidget.

Parameters:

Name	Type	Description	Default
`widget_id`	`Optional[str]`	Optional Widget ID.	`None`

Attributes¶

`max_value` `property` ¶

Get the maximum progress value.

Returns:

Name	Type	Description
`float`	`float`	Maximum progress value.

`percentage` `property` ¶

Get the percentage of current progress.

Returns:

Name	Type	Description
`float`	`float`	Current progress percentage (0-100).

`value` `property` ¶

Get the current progress value.

Returns:

Name	Type	Description
`float`	`float`	Current progress value.

Functions¶

`complete()` ¶

Set progress to maximum value (100%).

Returns:

Name	Type	Description
`ProgressWidget`	`ProgressWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> widget = ProgressWidget().complete() # Progress becomes 100%

`decrement(amount=1.0)` ¶

Decrease the progress value.

Parameters:

Name	Type	Description	Default
`amount`	`float`	Amount to decrease, default is 1.0.	`1.0`

Returns:

Name	Type	Description
`ProgressWidget`	`ProgressWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> widget = ProgressWidget().set_value(50).decrement(5) # Progress becomes 45

`get_template_context()` ¶

Get the context data required for template rendering

`increment(amount=1.0)` ¶

Increase the progress value.

Parameters:

Name	Type	Description	Default
`amount`	`float`	Amount to increase, default is 1.0.	`1.0`

Returns:

Name	Type	Description
`ProgressWidget`	`ProgressWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> widget = ProgressWidget().set_value(50).increment(10) # Progress becomes 60

`reset()` ¶

Reset progress to 0.

Returns:

Name	Type	Description
`ProgressWidget`	`ProgressWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> widget = ProgressWidget().set_value(75).reset() # Progress becomes 0

`set_background_color(color)` ¶

Set the background color of the progress bar.

Parameters:

Name	Type	Description	Default
`color`	`str`	CSS color value, such as "#e0e0e0", "lightgray".	required

Returns:

Name	Type	Description
`ProgressWidget`	`ProgressWidget`	Returns self to support method chaining.

Raises:

Type	Description
`ValueError`	When the color format is invalid.

Examples:

Python Console Session

>>> widget = ProgressWidget().set_background_color("#f0f0f0")

`set_border_radius(radius)` ¶

Set the border radius of the progress bar.

Parameters:

Name	Type	Description	Default
`radius`	`str`	CSS border radius value, such as "10px", "50%".	required

Returns:

Name	Type	Description
`ProgressWidget`	`ProgressWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> widget = ProgressWidget().set_border_radius("5px")

`set_height(height)` ¶

Set the height of the progress bar.

Parameters:

Name	Type	Description	Default
`height`	`str`	CSS height value, such as "20px", "1em".	required

Returns:

Name	Type	Description
`ProgressWidget`	`ProgressWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> widget = ProgressWidget().set_height("24px")

`set_label(label)` ¶

Set the descriptive label displayed above the progress bar.

Parameters:

Name	Type	Description	Default
`label`	`str`	Label text.	required

Returns:

Name	Type	Description
`ProgressWidget`	`ProgressWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> widget = ProgressWidget().set_label("Task Completion")

`set_max_value(max_val)` ¶

Set the maximum progress value.

Parameters:

Name	Type	Description	Default
`max_val`	`float`	Maximum progress value.	required

Returns:

Name	Type	Description
`ProgressWidget`	`ProgressWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> widget = ProgressWidget().set_max_value(200)

`set_theme(theme)` ¶

Set the color theme of the progress bar.

Parameters:

Name	Type	Description	Default
`theme`	`ProgressTheme`	Progress bar theme enum value.	required

Returns:

Name	Type	Description
`ProgressWidget`	`ProgressWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> widget = ProgressWidget().set_theme(ProgressTheme.SUCCESS)

`set_value(value)` ¶

Set the current progress value.

Parameters:

Name	Type	Description	Default
`value`	`float`	Progress value, should be between 0 and `max_value`.	required

Returns:

Name	Type	Description
`ProgressWidget`	`ProgressWidget`	Returns self to support method chaining.

Raises:

Type	Description
`ValueError`	When the value is outside the valid range.

Examples:

Python Console Session

>>> widget = ProgressWidget().set_value(75)

`set_width(width)` ¶

Set the width of the progress bar.

Parameters:

Name	Type	Description	Default
`width`	`str`	CSS width value, such as "100%", "500px".	required

Returns:

Name	Type	Description
`ProgressWidget`	`ProgressWidget`	Returns self to support method chaining.

Raises:

Type	Description
`ValueError`	When the width format is invalid.

Examples:

Python Console Session

>>> widget = ProgressWidget().set_width("80%")

`show_percentage(show=True)` ¶

Set whether to display percentage text inside the progress bar.

Parameters:

Name	Type	Description	Default
`show`	`bool`	Whether to show percentage, default is True.	`True`

Returns:

Name	Type	Description
`ProgressWidget`	`ProgressWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> widget = ProgressWidget().show_percentage(False) # Hide percentage

ProgressWidget API¶

ProgressWidget(widget_id=None) ¶

Attributes¶

max_value property ¶

percentage property ¶

value property ¶

Functions¶

complete() ¶

decrement(amount=1.0) ¶

get_template_context() ¶

increment(amount=1.0) ¶

reset() ¶

set_background_color(color) ¶

set_border_radius(radius) ¶

set_height(height) ¶

set_label(label) ¶

set_max_value(max_val) ¶

set_theme(theme) ¶

set_value(value) ¶

set_width(width) ¶

show_percentage(show=True) ¶

`ProgressWidget(widget_id=None)` ¶

`max_value` `property` ¶

`percentage` `property` ¶

`value` `property` ¶

`complete()` ¶

`decrement(amount=1.0)` ¶

`get_template_context()` ¶

`increment(amount=1.0)` ¶

`reset()` ¶

`set_background_color(color)` ¶

`set_border_radius(radius)` ¶

`set_height(height)` ¶

`set_label(label)` ¶

`set_max_value(max_val)` ¶

`set_theme(theme)` ¶

`set_value(value)` ¶

`set_width(width)` ¶

`show_percentage(show=True)` ¶