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 |
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
|
{} |
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)