Floodgauge

Bases: Canvas

A canvas-based widget that displays progress in determinate or indeterminate mode, styled using ttkbootstrap's color system.

This widget mimics the behavior of ttk.Progressbar with additional features: - Canvas-based drawing for full styling control - Bounce-style animation for indeterminate mode - Lightened trough color based on the bootstyle - Support for variable and textvariable bindings - Auto-updating label based on mask or textvariable - Theme-reactive color updates via <> event

Parameters:

Name	Type	Description	Default
master	Widget	Parent widget.	None
value	int	Initial value of the progress bar.	0
maximum	int	The maximum value for the determinate range.	100
mode	str	'determinate' or 'indeterminate' mode.	'determinate'
mask	str	A string with a '{}' placeholder for formatted text output, e.g. 'Progress: {}%'.	None
text	str	A static fallback label (used if no mask is specified).	''
font	Font or tuple	The font used for the label (default: Helvetica 14 bold).	('Helvetica', 12)
bootstyle	str	A ttkbootstrap style keyword such as 'primary', 'info', etc.	'primary'
orient	str	'horizontal' or 'vertical' orientation.	'horizontal'
length	int	The long dimension of the widget (width if horizontal, height if vertical). Defaults to 200.	200
thickness	int	The short axis of the widget (height if horizontal, width if vertical). Defaults to 50.	50
variable	IntVar	Bound variable for the current value.	required
textvariable	StringVar	Bound variable for the display label.	required

Source code in src/ttkbootstrap/widgets/floodgauge.py

class Floodgauge(Canvas):
    """
    A canvas-based widget that displays progress in determinate or indeterminate mode,
    styled using ttkbootstrap's color system.

    This widget mimics the behavior of ttk.Progressbar with additional features:
    - Canvas-based drawing for full styling control
    - Bounce-style animation for indeterminate mode
    - Lightened trough color based on the bootstyle
    - Support for variable and textvariable bindings
    - Auto-updating label based on mask or textvariable
    - Theme-reactive color updates via <<ThemeChanged>> event

    Parameters:
        master (Widget, optional):
            Parent widget.

        value (int):
            Initial value of the progress bar.

        maximum (int):
            The maximum value for the determinate range.

        mode (str):
            'determinate' or 'indeterminate' mode.

        mask (str, optional):
            A string with a '{}' placeholder for formatted text output, e.g. 'Progress: {}%'.

        text (str, optional):
            A static fallback label (used if no mask is specified).

        font (Font or tuple):
            The font used for the label (default: Helvetica 14 bold).

        bootstyle (str):
            A ttkbootstrap style keyword such as 'primary', 'info', etc.

        orient (str):
            'horizontal' or 'vertical' orientation.

        length (int):
            The long dimension of the widget (width if horizontal, height if vertical). Defaults to 200.

        thickness (int):
            The short axis of the widget (height if horizontal, width if vertical). Defaults to 50.

        variable (tk.IntVar, optional):
            Bound variable for the current value.

        textvariable (tk.StringVar, optional):
            Bound variable for the display label.
    """

    def __init__(
            self,
            master: Optional[Misc] = None,
            value: int = 0,
            maximum: int = 100,
            mode: str = "determinate",
            mask: Optional[str] = None,
            text: str = "",
            font: Union[tuple[str, int], str] = ("Helvetica", 12),
            bootstyle: str = "primary",
            orient: str = "horizontal",
            length: int = 200,
            thickness: int = 50,
            **kwargs: Any
    ) -> None:
        self.variable = kwargs.pop("variable", IntVar(value=value))
        self.textvariable = kwargs.pop("textvariable", StringVar(value=text))

        self.length = length
        self.thickness = thickness
        self.orient = orient
        canvas_kwargs = dict(highlightthickness=0, **kwargs)

        if self.orient == "horizontal":
            canvas_kwargs.update(width=self.length, height=self.thickness)
        else:
            canvas_kwargs.update(width=self.thickness, height=self.length)

        super().__init__(master, **canvas_kwargs)

        self.variable.trace_add("write", lambda n, i, m: self._on_var_change())
        self.textvariable.trace_add("write", lambda n, i, m: self._on_text_change())

        self.value = self.variable.get()
        self.text = self.textvariable.get()
        self.maximum = maximum
        self.mode = mode
        self.mask = mask
        self.font = font
        self._step_size = 1
        self._running = False
        self._after_id = None
        self._pulse_pos = 0
        self._pulse_direction = 1
        self._bootstyle = bootstyle

        self._update_theme_colors()

        self.bind("<Configure>", self._on_resize)
        self.bind("<<ThemeChanged>>", lambda e: self._update_theme_colors())
        self._draw()

    def _update_theme_colors(self) -> None:
        style = Style.get_instance()
        self.bar_color = style.colors.get(self._bootstyle)
        self.trough_color = Colors.update_hsv(self.bar_color, 0, -0.5, 0.3)
        self.text_color = contrast_color(self.bar_color, 'hex')
        self._draw()

    def _on_resize(self, event: Event) -> None:
        if self.orient == "horizontal":
            self.length = event.width
            self.thickness = event.height
        else:
            self.length = event.height
            self.thickness = event.width
        self._draw()

    def _draw(self) -> None:
        self.delete("all")
        w = self.winfo_width()
        h = self.winfo_height()

        self.create_rectangle(0, 0, w, h, fill=self.trough_color, width=0)

        if self.mode == "determinate":
            ratio = max(0.0, min(1.0, self.value / self.maximum))
            if self.orient == "horizontal":
                fill = int(ratio * w)
                self.create_rectangle(0, 0, fill, h, fill=self.bar_color, width=0)
            else:
                fill = int(ratio * h)
                self.create_rectangle(0, h - fill, w, h, fill=self.bar_color, width=0)
        else:
            if self.orient == "horizontal":
                pulse_width = max(10, int(w * 0.2))
                x = self._pulse_pos
                self.create_rectangle(x, 0, x + pulse_width, h, fill=self.bar_color, width=0)
            else:
                pulse_height = max(10, int(h * 0.2))
                y = self._pulse_pos
                self.create_rectangle(0, y - pulse_height, w, y, fill=self.bar_color, width=0)

        if self.mask:
            label = self.mask.format(int(self.value))
            self.textvariable.set(label)
        elif self.textvariable:
            label = self.textvariable.get()
        else:
            label = self.text

        if label:
            self.create_text(
                w // 2,
                h // 2,
                text=label,
                font=self.font,
                fill=self.text_color,
                anchor="center"
            )

    def _on_var_change(self) -> None:
        self.value = self.variable.get()
        self._draw()

    def _on_text_change(self) -> None:
        self.text = self.textvariable.get()
        self._draw()

    def step(self, amount: int = 1) -> None:
        """Increment the progress value.

        Parameters:
            amount (int, optional): The amount to increment. Defaults to 1.
                                   Value wraps around after reaching maximum.
        """
        self.value = (self.value + amount) % (self.maximum + 1)
        self.variable.set(self.value)
        self._draw()

    def start(self, step_size: Optional[int] = None, interval: Optional[int] = None) -> None:
        """Start the progress animation.

        For indeterminate mode, starts the bouncing animation. For determinate
        mode, starts auto-incrementing the value.

        Parameters:
            step_size (int, optional): Amount to increment per animation step.
                                      Defaults to 8 for indeterminate mode,
                                      1 for determinate mode.

            interval (int, optional): Time in milliseconds between animation steps.
                                     Defaults to 20ms for indeterminate mode,
                                     50ms for determinate mode.
        """
        if self.mode == "indeterminate":
            self._step_size = step_size if step_size is not None else 8
            interval = interval if interval is not None else 20
        else:
            self._step_size = step_size if step_size is not None else 1
            interval = interval if interval is not None else 50

        self._running = True
        self._pulse_direction = 1
        self._run_animation(interval)

    def stop(self) -> None:
        """Stop the progress animation.

        Cancels any running animation and halts auto-incrementing or bouncing.
        """
        self._running = False
        if self._after_id:
            self.after_cancel(self._after_id)
            self._after_id = None

    def _run_animation(self, interval: int) -> None:
        if not self._running:
            return

        if self.mode == "indeterminate":
            self._animate_indeterminate(interval)
        else:
            self.step(self._step_size)
            self._after_id = self.after(interval, lambda: self._run_animation(interval))

    def _animate_indeterminate(self, interval: int) -> None:
        if not self._running:
            return

        if self.orient == "horizontal":
            w = self.winfo_width()
            pulse_width = max(10, int(w * 0.2))
            max_pos = w - pulse_width
            self._pulse_pos += self._step_size * self._pulse_direction
            if self._pulse_pos >= max_pos:
                self._pulse_pos = max_pos
                self._pulse_direction = -1
            elif self._pulse_pos <= 0:
                self._pulse_pos = 0
                self._pulse_direction = 1
        else:
            h = self.winfo_height()
            pulse_height = max(10, int(h * 0.2))
            max_pos = h
            self._pulse_pos += self._step_size * self._pulse_direction
            if self._pulse_pos >= max_pos:
                self._pulse_pos = max_pos
                self._pulse_direction = -1
            elif self._pulse_pos <= pulse_height:
                self._pulse_pos = pulse_height
                self._pulse_direction = 1

        self._draw()
        self._after_id = self.after(interval, lambda: self._animate_indeterminate(interval))

    def configure(self, cnf: Optional[str] = None, **kwargs: Any) -> Any:
        """Configure the options for this widget.

        Parameters:
            cnf (str, optional): Option name to query. If provided without
                                kwargs, returns the current value.

            **kwargs: Widget options to set (value, maximum, mask, text, font,
                     bootstyle, length, thickness, variable, textvariable).
        """
        if cnf is not None and not kwargs:
            custom = {
                "value": ("value", "value", "Value", self.variable.get()),
                "maximum": ("maximum", "maximum", "Maximum", self.maximum),
                "mask": ("mask", "mask", "Mask", self.mask),
                "text": ("text", "text", "Text", self.textvariable.get()),
                "font": ("font", "font", "Font", self.font),
                "bootstyle": ("bootstyle", "bootstyle", "Bootstyle", self._bootstyle),
                "variable": ("variable", "variable", "Variable", str(self.variable)),
                "textvariable": ("textvariable", "textvariable", "Textvariable", str(self.textvariable)),
                "length": ("length", "length", "Length", self.length),
                "thickness": ("thickness", "thickness", "Thickness", self.thickness),
            }
            if cnf in custom:
                return custom[cnf]
            else:
                raise TclError(f"unknown option '{cnf}'")

        if "value" in kwargs:
            self.value = kwargs.pop("value")
            self.variable.set(self.value)
        if "maximum" in kwargs:
            self.maximum = kwargs.pop("maximum")
        if "mask" in kwargs:
            self.mask = kwargs.pop("mask")
        if "text" in kwargs:
            self.text = kwargs.pop("text")
            self.textvariable.set(self.text)
        if "font" in kwargs:
            self.font = kwargs.pop("font")
        if "bootstyle" in kwargs:
            self._bootstyle = kwargs.pop("bootstyle")
            self._update_theme_colors()
        if "length" in kwargs:
            self.length = kwargs.pop("length")
            if self.orient == "horizontal":
                self.configure(width=self.length)
            else:
                self.configure(height=self.length)
        if "thickness" in kwargs:
            self.thickness = kwargs.pop("thickness")
            if self.orient == "horizontal":
                self.configure(height=self.thickness)
            else:
                self.configure(width=self.thickness)
        if "variable" in kwargs:
            self.variable = kwargs.pop("variable")
            self.variable.trace_add("write", lambda n, i, m: self._on_var_change())
        if "textvariable" in kwargs:
            self.textvariable = kwargs.pop("textvariable")
            self.textvariable.trace_add("write", lambda n, i, m: self._on_text_change())

        result = super().configure(**kwargs)
        self._draw()
        return result

    def cget(self, key: str) -> Any:
        """Get the current value of a configuration option.

        Parameters:
            key (str): The option name to query.

        Returns:
            The current value of the specified option.
        """
        if key == "value":
            return self.variable.get()
        if key == "text":
            return self.textvariable.get()
        if key == "maximum":
            return self.maximum
        if key == "mask":
            return self.mask
        if key == "bootstyle":
            return self._bootstyle
        if key == "font":
            return self.font
        if key == "length":
            return self.length
        if key == "thickness":
            return self.thickness
        if key == "variable":
            return str(self.variable)
        if key == "textvariable":
            return str(self.textvariable)
        return super().cget(key)

    def keys(self) -> list[str]:
        """Get the list of valid configuration option names.

        Returns:
            list: List of configuration option names.
        """
        return [
            "value", "maximum", "mask", "text", "font",
            "bootstyle", "length", "thickness", "variable", "textvariable"
        ]

    def items(self) -> Any:
        """Get all configuration options as key-value pairs.

        Returns:
            dict_items: Iterator of (option, value) pairs.
        """
        return {k: self.cget(k) for k in self.keys()}.items()

    __getitem__ = lambda self, key: self.cget(key)
    __setitem__ = lambda self, key, value: self.configure(**{key: value})

cget(key)

Get the current value of a configuration option.

Parameters:

Name	Type	Description	Default
key	str	The option name to query.	required

Returns:

Type	Description
Any	The current value of the specified option.

Source code in src/ttkbootstrap/widgets/floodgauge.py

def cget(self, key: str) -> Any:
    """Get the current value of a configuration option.

    Parameters:
        key (str): The option name to query.

    Returns:
        The current value of the specified option.
    """
    if key == "value":
        return self.variable.get()
    if key == "text":
        return self.textvariable.get()
    if key == "maximum":
        return self.maximum
    if key == "mask":
        return self.mask
    if key == "bootstyle":
        return self._bootstyle
    if key == "font":
        return self.font
    if key == "length":
        return self.length
    if key == "thickness":
        return self.thickness
    if key == "variable":
        return str(self.variable)
    if key == "textvariable":
        return str(self.textvariable)
    return super().cget(key)

configure(cnf=None, **kwargs)

Configure the options for this widget.

Parameters:

Name	Type	Description	Default
cnf	str	Option name to query. If provided without kwargs, returns the current value.	None
**kwargs	Any	Widget options to set (value, maximum, mask, text, font, bootstyle, length, thickness, variable, textvariable).	{}

Source code in src/ttkbootstrap/widgets/floodgauge.py

def configure(self, cnf: Optional[str] = None, **kwargs: Any) -> Any:
    """Configure the options for this widget.

    Parameters:
        cnf (str, optional): Option name to query. If provided without
                            kwargs, returns the current value.

        **kwargs: Widget options to set (value, maximum, mask, text, font,
                 bootstyle, length, thickness, variable, textvariable).
    """
    if cnf is not None and not kwargs:
        custom = {
            "value": ("value", "value", "Value", self.variable.get()),
            "maximum": ("maximum", "maximum", "Maximum", self.maximum),
            "mask": ("mask", "mask", "Mask", self.mask),
            "text": ("text", "text", "Text", self.textvariable.get()),
            "font": ("font", "font", "Font", self.font),
            "bootstyle": ("bootstyle", "bootstyle", "Bootstyle", self._bootstyle),
            "variable": ("variable", "variable", "Variable", str(self.variable)),
            "textvariable": ("textvariable", "textvariable", "Textvariable", str(self.textvariable)),
            "length": ("length", "length", "Length", self.length),
            "thickness": ("thickness", "thickness", "Thickness", self.thickness),
        }
        if cnf in custom:
            return custom[cnf]
        else:
            raise TclError(f"unknown option '{cnf}'")

    if "value" in kwargs:
        self.value = kwargs.pop("value")
        self.variable.set(self.value)
    if "maximum" in kwargs:
        self.maximum = kwargs.pop("maximum")
    if "mask" in kwargs:
        self.mask = kwargs.pop("mask")
    if "text" in kwargs:
        self.text = kwargs.pop("text")
        self.textvariable.set(self.text)
    if "font" in kwargs:
        self.font = kwargs.pop("font")
    if "bootstyle" in kwargs:
        self._bootstyle = kwargs.pop("bootstyle")
        self._update_theme_colors()
    if "length" in kwargs:
        self.length = kwargs.pop("length")
        if self.orient == "horizontal":
            self.configure(width=self.length)
        else:
            self.configure(height=self.length)
    if "thickness" in kwargs:
        self.thickness = kwargs.pop("thickness")
        if self.orient == "horizontal":
            self.configure(height=self.thickness)
        else:
            self.configure(width=self.thickness)
    if "variable" in kwargs:
        self.variable = kwargs.pop("variable")
        self.variable.trace_add("write", lambda n, i, m: self._on_var_change())
    if "textvariable" in kwargs:
        self.textvariable = kwargs.pop("textvariable")
        self.textvariable.trace_add("write", lambda n, i, m: self._on_text_change())

    result = super().configure(**kwargs)
    self._draw()
    return result

items()

Get all configuration options as key-value pairs.

Returns:

Name	Type	Description
dict_items	Any	Iterator of (option, value) pairs.

Source code in src/ttkbootstrap/widgets/floodgauge.py

def items(self) -> Any:
    """Get all configuration options as key-value pairs.

    Returns:
        dict_items: Iterator of (option, value) pairs.
    """
    return {k: self.cget(k) for k in self.keys()}.items()

keys()

Get the list of valid configuration option names.

Returns:

Name	Type	Description
list	list[str]	List of configuration option names.

Source code in src/ttkbootstrap/widgets/floodgauge.py

def keys(self) -> list[str]:
    """Get the list of valid configuration option names.

    Returns:
        list: List of configuration option names.
    """
    return [
        "value", "maximum", "mask", "text", "font",
        "bootstyle", "length", "thickness", "variable", "textvariable"
    ]

start(step_size=None, interval=None)

Start the progress animation.

For indeterminate mode, starts the bouncing animation. For determinate mode, starts auto-incrementing the value.

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

Source code in src/ttkbootstrap/widgets/floodgauge.py

def start(self, step_size: Optional[int] = None, interval: Optional[int] = None) -> None:
    """Start the progress animation.

    For indeterminate mode, starts the bouncing animation. For determinate
    mode, starts auto-incrementing the value.

    Parameters:
        step_size (int, optional): Amount to increment per animation step.
                                  Defaults to 8 for indeterminate mode,
                                  1 for determinate mode.

        interval (int, optional): Time in milliseconds between animation steps.
                                 Defaults to 20ms for indeterminate mode,
                                 50ms for determinate mode.
    """
    if self.mode == "indeterminate":
        self._step_size = step_size if step_size is not None else 8
        interval = interval if interval is not None else 20
    else:
        self._step_size = step_size if step_size is not None else 1
        interval = interval if interval is not None else 50

    self._running = True
    self._pulse_direction = 1
    self._run_animation(interval)

step(amount=1)

Increment the progress value.

Parameters:

Name	Type	Description	Default
amount	int	The amount to increment. Defaults to 1. Value wraps around after reaching maximum.	1

Source code in src/ttkbootstrap/widgets/floodgauge.py

def step(self, amount: int = 1) -> None:
    """Increment the progress value.

    Parameters:
        amount (int, optional): The amount to increment. Defaults to 1.
                               Value wraps around after reaching maximum.
    """
    self.value = (self.value + amount) % (self.maximum + 1)
    self.variable.set(self.value)
    self._draw()

stop()

Stop the progress animation.

Cancels any running animation and halts auto-incrementing or bouncing.

Source code in src/ttkbootstrap/widgets/floodgauge.py

def stop(self) -> None:
    """Stop the progress animation.

    Cancels any running animation and halts auto-incrementing or bouncing.
    """
    self._running = False
    if self._after_id:
        self.after_cancel(self._after_id)
        self._after_id = None