Gnome::Gtk4::LevelBar
Description
Gnome::Gtk4::LevelBar 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: GTK_LEVEL_BAR_OFFSET_LOW
, GTK_LEVEL_BAR_OFFSET_HIGH
and GTK_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
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 GTK_LEVEL_BAR_MODE_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 Gnome::Gtk4::LevelBar implementation of the Gnome::Gtk4::R-Buildable 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
Gnome::Gtk4::LevelBar 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
Gnome::Gtk4::LevelBar uses the GTK_ACCESSIBLE_ROLE_METER
role.
Class initialization
new
:native-object
Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.
multi method new ( N-Object :$native-object! )
new-levelbar
Creates a new Gnome::Gtk4::LevelBar.
method new-levelbar ( --> Gnome::Gtk4::LevelBar \)
new-for-interval
Creates a new Gnome::Gtk4::LevelBar for the specified interval.
method new-for-interval ( Num() $min-value, Num() $max-value --> Gnome::Gtk4::LevelBar \)
$min-value; a positive value.
$max-value; a positive value.
Methods
add-offset-value
Adds a new offset marker on $self
at the position specified by $value
.
When the bar value is in the interval topped by $value
(or between $value
and max-value in case the offset is the last one on the bar) a style class named level-` $name
will be applied when rendering the level bar fill.
If another offset marker named $name
exists, its value will be replaced by $value
.
method add-offset-value ( Str $name, Num() $value )
$name; the name of the new offset.
$value; the value for the new offset.
get-inverted
Returns whether the levelbar is inverted.
method get-inverted (--> Bool )
Return value; True
if the level bar is inverted.
get-max-value
Returns the max-value` of the Gnome::Gtk4::LevelBar.
method get-max-value (--> Num )
Return value; a positive value.
get-min-value
Returns the min-value` of the Gnome::Gtk4::LevelBar.
method get-min-value (--> Num )
Return value; a positive value.
get-mode
Returns the mode of the Gnome::Gtk4::LevelBar.
method get-mode (--> GtkLevelBarMode )
Return value; a enumeration GtkLevelBarMode defined in Gnome::Gtk4::T-enums
.
get-offset-value
Fetches the value specified for the offset marker $name
in $self
.
method get-offset-value ( Str $name, Num() $value --> Bool )
$name; the name of an offset in the bar.
$value; (transfer ownership: full) location where to store the value.
Return value; True
if the specified offset is found.
get-value
Returns the value of the Gnome::Gtk4::LevelBar.
method get-value (--> Num )
Return value; a value in the interval between min-value and max-value.
remove-offset-value
Removes an offset marker from a Gnome::Gtk4::LevelBar.
The marker must have been previously added with .add-offset-value()
.
method remove-offset-value ( Str $name )
$name; the name of an offset in the bar.
set-inverted
Sets whether the Gnome::Gtk4::LevelBar is inverted.
method set-inverted ( Bool() $inverted )
$inverted;
True
to invert the level bar.
set-max-value
Sets the max-value` of the Gnome::Gtk4::LevelBar.
You probably want to update preexisting level offsets after calling this function.
method set-max-value ( Num() $value )
$value; a positive value.
set-min-value
Sets the min-value` of the Gnome::Gtk4::LevelBar.
You probably want to update preexisting level offsets after calling this function.
method set-min-value ( Num() $value )
$value; a positive value.
set-mode
Sets the mode of the Gnome::Gtk4::LevelBar.
method set-mode ( GtkLevelBarMode $mode )
$mode; a
enumeration GtkLevelBarMode defined in Gnome::Gtk4::T-enums
.
set-value
Sets the value of the Gnome::Gtk4::LevelBar.
method set-value ( Num() $value )
$value; a value in the interval between min-value and max-value.
Signals
offset-changed
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.
method handler ( Str $name, Int :$_handle_id, N-GObject :$_native-object, Gnome::Gtk4::LevelBar :$_widget, *C<user>-options )
$name; the name of the offset that changed value.
$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::LevelBar object.
$_widget; The object which registered the signal. User code may have left the object going out of scope.
user
-options; A list of named arguments provided at the.register-signal()
method from Gnome::GObject::Object.