Skip to content

FloodGauge

Bases: ConfigureDelegationMixin, Canvas

A canvas-based progress widget with determinate and indeterminate modes.

Provides an enhanced alternative to ttk.Progressbar with full styling control, horizontal/vertical orientations, customizable text overlays with format masks, and bounce-style animation for indeterminate mode.

Attributes:

Name Type Description
variable IntVar

Tkinter IntVar for value binding.
textvariable StringVar

Tkinter StringVar for text binding.

value property writable 

value: int

Get or set the progress value.

__init__ 

__init__(
    master: Master = None,
    value: int = 0,
    maximum: int = 100,
    mode: str = "determinate",
    mask: Optional[str] = None,
    text: str = "",
    font: Union[tuple[str, int], str] = ("Helvetica", 12),
    accent: str = None,
    orient: str = "horizontal",
    length: int = 200,
    thickness: int = 50,
    increment: int = 1,
    **kwargs: Any,
) -> None

Initialize a FloodGauge widget.

Parameters:

Name Type Description Default
master Master

Parent widget. If None, uses the default root window.

 None
value int

Initial progress value (0-maximum).

 0
maximum int

Maximum value for determinate range.

 100
mode str

Progress mode - 'determinate' for known progress or 'indeterminate' for unknown duration.

 'determinate'
mask str

Format string for text overlay with '{}' placeholder for the value. Examples: '{}% Complete' or 'Progress: {}/100'. If None, no automatic text formatting is applied.

 None
text str

Static text label shown when no mask is specified.

 ''
font tuple | str

Font specification as tuple (family, size) or string like 'Arial 12 bold'.

 ('Helvetica', 12)
accent str

Accent token from bootstack (e.g., 'primary', 'success', 'info', 'warning', 'danger').

 None
orient str

Widget orientation - 'horizontal' or 'vertical'.

 'horizontal'
length int

Size in pixels along the main axis (width if horizontal, height if vertical).

 200
thickness int

Size in pixels along the minor axis (height if horizontal, width if vertical).

 50
increment int

Step size for value changes when using step() method or during animations.

 1

Other Parameters:

Name Type Description
variable IntVar

Tkinter IntVar for value binding.
textvariable StringVar

Tkinter StringVar for text binding.
Note

The widget automatically updates colors when the theme changes via the <<ThemeChanged>> event. When using variable or textvariable bindings, the widget redraws automatically when the variables change.

destroy 

destroy() -> None

Clean up resources before destroying the widget.

get 

get() -> int

Return the current progress value.

set 

set(value: int) -> None

Set the progress value.

Parameters:

Name Type Description Default
value int

The new progress value.

 required

step 

step(amount: int = 1) -> None

Increment the progress value by the specified amount.

Parameters:

Name Type Description Default
amount int

Amount to increment. Value wraps around after reaching maximum.

 1

start 

start(
    step_size: Optional[int] = None,
    interval: Optional[int] = None,
) -> None

Start the progress animation.

For indeterminate mode, starts bouncing animation. For determinate mode, auto-increments the value at regular intervals.

Parameters:

Name Type Description Default
step_size int

Amount to increment per animation step. Defaults to 8 for indeterminate mode, 1 for determinate mode.

 None
interval int

Time in milliseconds between animation steps. Defaults to 20ms for indeterminate mode, 50ms for determinate mode.

 None

stop 

stop() -> None

Stop the progress animation and cancel any scheduled updates.