LevelBar
Superclasses: Widget
, InitiallyUnowned
, Object
Implemented Interfaces: Accessible
, AccessibleRange
, Buildable
, ConstraintTarget
, Orientable
GtkLevelBar
is a widget that can be used as a level indicator.
Typical use cases are displaying the strength of a password, or showing the charge level of a battery.
Use set_value
to set the current value, and
add_offset_value
to set the value offsets at which
the bar will be considered in a different state. GTK will add a few
offsets by default on the level bar: LEVEL_BAR_OFFSET_LOW
,
LEVEL_BAR_OFFSET_HIGH
and LEVEL_BAR_OFFSET_FULL
, with
values 0.25, 0.75 and 1.0 respectively.
Note that it is your responsibility to update preexisting offsets when changing the minimum or maximum value. GTK will simply clamp them to the new range.
Adding a custom offset on the bar
static GtkWidget *
create_level_bar (void)
{
GtkWidget *widget;
GtkLevelBar *bar;
widget = gtk_level_bar_new ();
bar = GTK_LEVEL_BAR (widget);
// This changes the value of the default low offset
gtk_level_bar_add_offset_value (bar,
GTK_LEVEL_BAR_OFFSET_LOW,
0.10);
// This adds a new offset to the bar; the application will
// be able to change its color CSS like this:
//
// levelbar block.my-offset {
// background-color: magenta;
// border-style: solid;
// border-color: black;
// border-width: 1px;
// }
gtk_level_bar_add_offset_value (bar, "my-offset", 0.60);
return widget;
}
The default interval of values is between zero and one, but it’s possible
to modify the interval using set_min_value
and
set_max_value
. The value will be always drawn in
proportion to the admissible interval, i.e. a value of 15 with a specified
interval between 10 and 20 is equivalent to a value of 0.5 with an interval
between 0 and 1. When DISCRETE
is used, the bar level
is rendered as a finite number of separated blocks instead of a single one.
The number of blocks that will be rendered is equal to the number of units
specified by the admissible interval.
For instance, to build a bar rendered with five blocks, it’s sufficient to set the minimum value to 0 and the maximum value to 5 after changing the indicator mode to discrete.
GtkLevelBar as GtkBuildable
The GtkLevelBar
implementation of the GtkBuildable
interface supports a
custom <offsets>
element, which can contain any number of <offset>
elements,
each of which must have “name” and “value” attributes.
CSS nodes
levelbar[.discrete]
╰── trough
├── block.filled.level-name
┊
├── block.empty
┊
GtkLevelBar
has a main CSS node with name levelbar and one of the style
classes .discrete or .continuous and a subnode with name trough. Below the
trough node are a number of nodes with name block and style class .filled
or .empty. In continuous mode, there is exactly one node of each, in discrete
mode, the number of filled and unfilled nodes corresponds to blocks that are
drawn. The block.filled nodes also get a style class .level-name corresponding
to the level for the current value.
In horizontal orientation, the nodes are always arranged from left to right, regardless of text direction.
Accessibility
GtkLevelBar
uses the METER
role.
Constructors
Methods
- class LevelBar
- add_offset_value(name: str, value: float) None
Adds a new offset marker on
self
at the position specified byvalue
.When the bar value is in the interval topped by
value
(or betweenvalue
andmax_value
in case the offset is the last one on the bar) a style class namedlevel-```name`
will be applied when rendering the level bar fill.If another offset marker named
name
exists, its value will be replaced byvalue
.- Parameters:
name – the name of the new offset
value – the value for the new offset
- get_mode() LevelBarMode
Returns the
mode
of theGtkLevelBar
.
- get_offset_value(name: str | None = None) tuple[bool, float]
Fetches the value specified for the offset marker
name
inself
.- Parameters:
name – the name of an offset in the bar
- remove_offset_value(name: str | None = None) None
Removes an offset marker from a
GtkLevelBar
.The marker must have been previously added with
add_offset_value
.- Parameters:
name – the name of an offset in the bar
- set_inverted(inverted: bool) None
Sets whether the
GtkLevelBar
is inverted.- Parameters:
inverted –
True
to invert the level bar
- set_max_value(value: float) None
Sets the
max-value
of theGtkLevelBar
.You probably want to update preexisting level offsets after calling this function.
- Parameters:
value – a positive value
- set_min_value(value: float) None
Sets the
min-value
of theGtkLevelBar
.You probably want to update preexisting level offsets after calling this function.
- Parameters:
value – a positive value
- set_mode(mode: LevelBarMode) None
Sets the
mode
of theGtkLevelBar
.- Parameters:
mode – a
GtkLevelBarMode
Properties
- class LevelBar
- props.inverted: bool
Whether the
GtkLeveBar
is inverted.Level bars normally grow from top to bottom or left to right. Inverted level bars grow in the opposite direction.
- props.max_value: float
Determines the maximum value of the interval that can be displayed by the bar.
- props.min_value: float
Determines the minimum value of the interval that can be displayed by the bar.
- props.mode: LevelBarMode
Determines the way
GtkLevelBar
interprets the value properties to draw the level fill area.Specifically, when the value is
CONTINUOUS
,GtkLevelBar
will draw a single block representing the current value in that area; when the value isDISCRETE
, the widget will draw a succession of separate blocks filling the draw area, with the number of blocks being equal to the units separating the integral roundings ofmin_value
andmax_value
.
Signals
- class LevelBar.signals
- offset_changed(name: str) None
Emitted when an offset specified on the bar changes value.
This typically is the result of a
add_offset_value
call.The signal supports detailed connections; you can connect to the detailed signal “changed::x” in order to only receive callbacks when the value of offset “x” changes.
- Parameters:
name – the name of the offset that changed value