Stateful Icon Mixin (Core)

ttkbootstrap_icons.stateful_icon_mixin.StatefulIconMixin

Mixin that maps per-state ttk image onto a child style.

The host class must expose the following attributes and property:

Attributes:

Name	Type	Description
name		Base icon name used when a state does not override name.
size		Pixel size of the icon to render.

Properties

image: A Tk-compatible image (e.g., PhotoImage) for the current instance (used as the '' fallback).

The host may optionally override _render_icon() to supply a custom image renderer. The default implementation constructs a new instance of the host's class (type(self)) with (name, size, color) and returns its .image.

Note

This mixin does not define __init__ and does not assume any specific constructor signature on the host beyond (name: str, size: int, color: Optional[str] = None). If your constructor differs, override _render_icon() to render state images without instantiation.

_is_regenerating = False class-attribute

_original_image = None class-attribute instance-attribute

_widget_mappings = {} class-attribute

_button_color_for_state(style, parent_style, state)

Resolve the parent style's foreground color for a given state.

Parameters:

Name	Type	Description	Default
style	Style	ttk Style instance.	required
parent_style	str	Parent style name (e.g., 'my.TButton').	required
state	str	State flag to resolve (e.g., 'hover').	required

Returns:

Type	Description
Optional[str]	The resolved color string or None if not available.

_ensure_original_image()

Ensure the untinted base image is cached for the '' fallback.

Notes

Uses the instance's own .image to avoid re-instantiation or recursion during host initialization.

_on_theme_changed(event) classmethod

Handle <> event by regenerating all mapped icons.

_parse_statespec(style, parent_style, statespec)

Parse the state spec into (state, icon_name, color) triples.

If statespec is not provided, triples are derived from the parent's foreground map using the base icon.

Parameters:

Name	Type	Description	Default
style	Style	ttk Style instance.	required
parent_style	str	Parent style name to read maps from.	required
statespec	Optional[list[IconStateSpec]]	Optional list describing per-state overrides. Each item is a (state, spec) pair where spec is either a color string or a dict with keys name and/or color.	required

Returns:

Type	Description
list[tuple[str, str, Optional[str]]]	A list of triples (state, icon_name, color_or_None). If color is
list[tuple[str, str, Optional[str]]]	None, the caller will resolve to the parent's state foreground.

_render_icon(name, size, color)

Render a Tk-compatible image for (name, size, color).

By default, this constructs a new instance of type(self) with the provided (name, size, color) and returns its .image. If your host class requires a different constructor or you want a more direct path, override this method.

Parameters:

Name	Type	Description	Default
name	str	Icon name to render.	required
size	int	Icon size in pixels.	required
color	Optional[str]	Optional color to tint the icon. If None, render untinted.	required

Returns:

Type	Description
object	A Tk-compatible image object (e.g., PhotoImage).

_slug(token) staticmethod

Return a style-safe token by replacing unsupported characters.

Parameters:

Name	Type	Description	Default
token	str	Arbitrary token (e.g., icon name).	required

Returns:

Type	Description
str	A string containing only alphanumerics, '-' or '_'.

_state_tuple(state) staticmethod

Convert a state string into a ttk lookup tuple.

Parameters:

Name	Type	Description	Default
state	str	Single state flag (e.g., 'hover', 'pressed').	required

Returns:

Type	Description
tuple[str, ...]	A one-element tuple containing state.

map(widget, *, subclass=None, statespec=None, mode='merge')

Apply per-state images to a child style derived from the widget's style.

This computes per-state images from statespec (or the parent's foreground map when statespec is omitted), generates a child style name, and maps the image option accordingly. The empty-state ('') fallback is always set to the instance's original untinted image.

Parameters:

Name	Type	Description	Default
widget	Widget	ttk widget to style (e.g., ttk.Button).	required
subclass	Optional[str]	Optional child style prefix. If omitted, the name is generated by concatenating the unique icon names used (including the base) and appending the size, e.g., "house-house-fill-16.my.TButton".	None
statespec	Optional[list[IconStateSpec]]	Optional list of per-state overrides. Each item is a (state, spec) pair where spec is a color string or a dict with name and/or color. If color is omitted, the icon color follows the parent's foreground for that state.	None
mode	StateMapMode	Merge strategy for the child style's image map. * "merge" (default): Read the existing image map for the same child style, overwrite incoming states, preserve order of existing entries, and append new states. * "replace": Ignore any existing map and apply only the provided states (plus the fallback).	'merge'

Returns:

Type	Description
None	None