Skip to content

Meter

ttkbootstrap.widgets.Meter (Frame)

A radial meter that can be used to show progress of long running operations or the amount of work completed; can also be used as a dial when set to interactive=True.

This widget is very flexible. There are two primary meter types which can be set with the metertype parameter: 'full' and 'semi', which shows the arc of the meter in a full or semi-circle. You can also customize the arc of the circle with the arcrange and arcoffset parameters.

The meter indicator can be displayed as a solid color or with stripes using the stripethickness parameter. By default, the stripethickness is 0, which results in a solid meter indicator. A higher stripethickness results in larger wedges around the arc of the meter.

Various text and label options exist. The center text and meter indicator is formatted with the meterstyle parameter. You can set text on the left and right of this center label using the textleft and textright parameters. This is most commonly used for '$', '%', or other such symbols.

If you need access to the variables that update the meter, you you can access these via the amountusedvar, amounttotalvar, and the labelvar. The value of these properties can also be retrieved via the configure method.

Examples:

import ttkbootstrap as ttk
from ttkbootstrap.constants import *

app = ttk.Window()

meter = ttk.Meter(
    metersize=180,
    padding=5,
    amountused=25,
    metertype="semi",
    subtext="miles per hour",
    interactive=True,
)
meter.pack()

# update the amount used directly
meter.configure(amountused = 50)

# update the amount used with another widget
entry = ttk.Entry(textvariable=meter.amountusedvar)
entry.pack(fill=X)

# increment the amount by 10 steps
meter.step(10)

# decrement the amount by 15 steps
meter.step(-15)

# update the subtext
meter.configure(subtext="loading...")

app.mainloop()

__init__(self, master=None, bootstyle='default', arcrange=None, arcoffset=None, amounttotal=100, amountused=0, wedgesize=0, metersize=200, metertype='full', meterthickness=10, showtext=True, interactive=False, stripethickness=0, textleft=None, textright=None, textfont='-size 20 -weight bold', subtext=None, subtextstyle='default', subtextfont='-size 10', stepsize=1, **kwargs) special

Parameters:

Name Type Description Default
master Widget

The parent widget.

None
arcrange int

The range of the arc if degrees from start to end.

None
arcoffset int

The amount to offset the arc's starting position in degrees. 0 is at 3 o'clock.

None
amounttotal int

The maximum value of the meter.

100
amountused int

The current value of the meter; displayed in a center label if the showtext property is set to True.

0
wedgesize int

Sets the length of the indicator wedge around the arc. If greater than 0, this wedge is set as an indicator centered on the current meter value.

0
metersize int

The meter is square. This represents the size of one side if the square as measured in screen units.

200
bootstyle str

Sets the indicator and center text color. One of primary, secondary, success, info, warning, danger, light, dark.

'default'
metertype 'full', 'semi'

Displays the meter as a full circle or semi-circle.

'full'
meterthickness int

The thickness of the indicator.

10
showtext bool

Indicates whether to show the left, center, and right text labels on the meter.

True
interactive bool

Indicates that the user may adjust the meter value with mouse interaction.

False
stripethickness int

The indicator can be displayed as a solid band or as striped wedges around the arc. If the value is greater than 0, the indicator changes from a solid to striped, where the value is the thickness of the stripes (or wedges).

0
textleft str

A short string inserted to the left of the center text.

None
textright str

A short string inserted to the right of the center text.

None
textfont Union[str, Font]

The font used to render the center text.

'-size 20 -weight bold'
subtext str

Supplemental text that appears below the center text.

None
subtextstyle str

The bootstyle color of the subtext. One of primary, secondary, success, info, warning, danger, light, dark. The default color is Theme specific and is a lighter shade based on whether it is a 'light' or 'dark' theme.

'default'
subtextfont Union[str, Font]

The font used to render the subtext.

'-size 10'
stepsize int

Sets the amount by which to change the meter indicator when incremented by mouse interaction.

1
**kwargs

Other keyword arguments that are passed directly to the Frame widget that contains the meter components.

{}
Source code in ttkbootstrap/widgets.py
def __init__(
    self,
    master=None,
    bootstyle=DEFAULT,
    arcrange=None,
    arcoffset=None,
    amounttotal=100,
    amountused=0,
    wedgesize=0,
    metersize=200,
    metertype=FULL,
    meterthickness=10,
    showtext=True,
    interactive=False,
    stripethickness=0,
    textleft=None,
    textright=None,
    textfont="-size 20 -weight bold",
    subtext=None,
    subtextstyle=DEFAULT,
    subtextfont="-size 10",
    stepsize=1,
    **kwargs,
):
    """
    Parameters:

        master (Widget):
            The parent widget.

        arcrange (int):
            The range of the arc if degrees from start to end.

        arcoffset (int):
            The amount to offset the arc's starting position in degrees.
            0 is at 3 o'clock.

        amounttotal (int):
            The maximum value of the meter.

        amountused (int):
            The current value of the meter; displayed in a center label
            if the `showtext` property is set to True.

        wedgesize (int):
            Sets the length of the indicator wedge around the arc. If
            greater than 0, this wedge is set as an indicator centered
            on the current meter value.

        metersize (int):
            The meter is square. This represents the size of one side
            if the square as measured in screen units.

        bootstyle (str):
            Sets the indicator and center text color. One of primary,
            secondary, success, info, warning, danger, light, dark.

        metertype ('full', 'semi'):
            Displays the meter as a full circle or semi-circle.

        meterthickness (int):
            The thickness of the indicator.

        showtext (bool):
            Indicates whether to show the left, center, and right text
            labels on the meter.

        interactive (bool):
            Indicates that the user may adjust the meter value with
            mouse interaction.

        stripethickness (int):
            The indicator can be displayed as a solid band or as
            striped wedges around the arc. If the value is greater than
            0, the indicator changes from a solid to striped, where the
            value is the thickness of the stripes (or wedges).

        textleft (str):
            A short string inserted to the left of the center text.

        textright (str):
            A short string inserted to the right of the center text.

        textfont (Union[str, Font]):
            The font used to render the center text.

        subtext (str):
            Supplemental text that appears below the center text.

        subtextstyle (str):
            The bootstyle color of the subtext. One of primary,
            secondary, success, info, warning, danger, light, dark.
            The default color is Theme specific and is a lighter
            shade based on whether it is a 'light' or 'dark' theme.

        subtextfont (Union[str, Font]):
            The font used to render the subtext.

        stepsize (int):
            Sets the amount by which to change the meter indicator
            when incremented by mouse interaction.

        **kwargs:
            Other keyword arguments that are passed directly to the
            `Frame` widget that contains the meter components.
    """
    super().__init__(master=master, **kwargs)

    # widget variables
    self.amountusedvar = tk.IntVar(value=amountused)
    self.amountusedvar.trace_add("write", self._draw_meter)
    self.amounttotalvar = tk.IntVar(value=amounttotal)
    self.labelvar = tk.StringVar(value=subtext)

    # misc settings
    self._set_arc_offset_range(metertype, arcoffset, arcrange)
    self._towardsmaximum = True
    self._metersize = utility.scale_size(self, metersize)
    self._meterthickness = utility.scale_size(self, meterthickness)
    self._stripethickness = stripethickness
    self._showtext = showtext
    self._wedgesize = wedgesize
    self._stepsize = stepsize        
    self._textleft = textleft
    self._textright = textright
    self._textfont = textfont
    self._subtext = subtext
    self._subtextfont = subtextfont
    self._subtextstyle = subtextstyle
    self._bootstyle = bootstyle
    self._interactive = interactive
    self._bindids = {}

    self._setup_widget()

configure(self, cnf=None, **kwargs)

Configure the options for this widget.

Parameters:

Name Type Description Default
cnf Dict[str, Any]

A dictionary of configuration options.

None
**kwargs

Optional keyword arguments.

{}
Source code in ttkbootstrap/widgets.py
def configure(self, cnf=None, **kwargs):
    """Configure the options for this widget.

    Parameters:
        cnf (Dict[str, Any], optional):
            A dictionary of configuration options.

        **kwargs: Optional keyword arguments.
    """
    if cnf is not None:
        return self._configure_get(cnf)
    else:
        self._configure_set(**kwargs)

step(self, delta=1)

Increase the indicator value by delta

The indicator will reverse direction and count down once it reaches the maximum value.

Parameters:

Name Type Description Default
delta int

The amount to change the indicator.

1
Source code in ttkbootstrap/widgets.py
def step(self, delta=1):
    """Increase the indicator value by `delta`

    The indicator will reverse direction and count down once it
    reaches the maximum value.

    Parameters:

        delta (int):
            The amount to change the indicator.
    """
    amountused = self.amountusedvar.get()
    amounttotal = self.amounttotalvar.get()
    if amountused >= amounttotal:
        self._towardsmaximum = True
        self.amountusedvar.set(amountused - delta)
    elif amountused <= 0:
        self._towardsmaximum = False
        self.amountusedvar.set(amountused + delta)
    elif self._towardsmaximum:
        self.amountusedvar.set(amountused - delta)
    else:
        self.amountusedvar.set(amountused + delta)