Meter

Bases: Frame

A circular progress meter widget with customizable appearance and optional text display.

The Meter widget displays a value as a circular arc indicator with optional value text, prefix/suffix labels, and subtitle. Supports both full circle and semi-circle styles, segmented or solid indicators, and interactive mode for user input.

The meter value can be accessed and modified using:

get() / set(value) - Standard value-widget API methods
.value property - Direct property access
configure(value=x) - Via the configure interface

Events

<<Change>>: Fired whenever the meter value changes. Provides event.data with keys: value, prev_value.

init

__init__(
    master: Master = None,
    accent: str = None,
    value: int | float = 0,
    minvalue: int | float = 0,
    maxvalue: int | float = 100,
    value_format: str = "{:.0f}",
    value_prefix: str = None,
    value_suffix: str = None,
    value_font: str = None,
    dtype: type[int] | type[float] = int,
    secondary_font: str = None,
    secondary_style: str = None,
    subtitle: str = None,
    size: int = 200,
    thickness: int = 10,
    indicator_width: int = 0,
    segment_width: int = 0,
    arc_range: int = None,
    arc_offset: int = None,
    meter_type: Literal["semi", "full"] = "full",
    show_text: bool = True,
    interactive: bool = False,
    step_size: int | float = 1,
    **kwargs: Any,
)

Initialize a Meter widget.

Parameters:

Name	Type	Description	Default
`master`	`Master`	The parent widget.	`None`
`accent`	`str`	Accent token for the meter indicator (e.g., 'primary', 'success').	`None`
`bootstyle`		DEPRECATED - Use `accent` instead.	required
`value`	`int \| float`	Current meter value.	`0`
`minvalue`	`int \| float`	Minimum value for the meter range.	`0`
`maxvalue`	`int \| float`	Maximum value for the meter range.	`100`
`value_format`	`str`	Format string for displaying the value (e.g., "{:.0f}", "{:.2f}").	`'{:.0f}'`
`value_prefix`	`str`	Text to display before the value (e.g., "$", "@").	`None`
`value_suffix`	`str`	Text to display after the value (e.g., "%", "mph").	`None`
`value_font`	`str`	Font specification for the value text (e.g., "-size 36 -weight bold").	`None`
`dtype`	`type[int] \| type[float]`	Data type for the value variable (int or float).	`int`
`secondary_font`	`str`	Font specification for prefix, suffix, and subtitle text.	`None`
`secondary_style`	`str`	Style name for prefix, suffix, and subtitle color.	`None`
`subtitle`	`str`	Optional subtitle text displayed below the value.	`None`
`size`	`int`	Width and height of the meter in pixels.	`200`
`thickness`	`int`	Width of the meter arc in pixels.	`10`
`indicator_width`	`int`	Width of the indicator segment when using a wedge-style indicator. 0 means fill from start to current value.	`0`
`segment_width`	`int`	Width of each segment for a segmented meter style. 0 means solid.	`0`
`arc_range`	`int`	Total arc range in degrees. None uses defaults (360 for full, 270 for semi).	`None`
`arc_offset`	`int`	Starting angle offset in degrees. None uses defaults (-90 for full, 135 for semi).	`None`
`meter_type`	`Literal['semi', 'full']`	Meter style - 'full' for full circle or 'semi' for semicircle.	`'full'`
`show_text`	`bool`	Whether to display the value text and labels.	`True`
`interactive`	`bool`	Whether the meter responds to mouse clicks/drags to change value.	`False`
`step_size`	`int \| float`	Increment step when in interactive mode.	`1`
`**kwargs`	`Any`	Additional keyword arguments passed to the Frame parent class.	`{}`

Events

<<Change>>: Emitted when the value changes (see on_changed()).

get

get()

Return the current meter value.

This is part of the standard value-widget API. It is equivalent to accessing the .value property.

Returns:

Type	Description
	The current meter value (int or float depending on dtype).

set

set(value)

Set the meter value.

This is part of the standard value-widget API. It is equivalent to setting the .value property.

Parameters:

Name	Type	Description	Default
`value`		The new meter value.	required

step

step(delta: int | float = 1)

Increment or decrement meter value with automatic bounce at limits.

Parameters:

Name	Type	Description	Default
`delta`	`int \| float`	Amount to step by (default 1).	`1`

on_changed

on_changed(callback: Callable[[Any], Any]) -> str

Bind a callback to the <<Change>> virtual event.

off_changed

off_changed(bind_id: str)

Remove a previously registered <<Change>> callback.