Description
The GtkLevelBar is a bar 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 gtk_level_bar_set_value() to set the current value, and
gtk_level_bar_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 gtk_level_bar_set_min_value() and
gtk_level_bar_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 was introduced in GTK+ 3.6.
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
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.
Functions
gtk_level_bar_new_for_interval ()
GtkWidget *
gtk_level_bar_new_for_interval (gdouble min_value,
gdouble max_value);
Utility constructor that creates a new GtkLevelBar for the specified
interval.
Since: 3.6
gtk_level_bar_set_value ()
void
gtk_level_bar_set_value (GtkLevelBar *self,
gdouble value);
Sets the value of the “value” property.
Since: 3.6
gtk_level_bar_set_min_value ()
void
gtk_level_bar_set_min_value (GtkLevelBar *self,
gdouble value);
Sets the value of the “min-value” property.
You probably want to update preexisting level offsets after calling
this function.
Since: 3.6
gtk_level_bar_set_max_value ()
void
gtk_level_bar_set_max_value (GtkLevelBar *self,
gdouble value);
Sets the value of the “max-value” property.
You probably want to update preexisting level offsets after calling
this function.
Since: 3.6
gtk_level_bar_get_inverted ()
gboolean
gtk_level_bar_get_inverted (GtkLevelBar *self);
Return the value of the “inverted” property.
Returns
TRUE if the level bar is inverted
Since: 3.8
gtk_level_bar_add_offset_value ()
void
gtk_level_bar_add_offset_value (GtkLevelBar *self,
const gchar *name,
gdouble 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
.
Since: 3.6
gtk_level_bar_get_offset_value ()
gboolean
gtk_level_bar_get_offset_value (GtkLevelBar *self,
const gchar *name,
gdouble *value);
Fetches the value specified for the offset marker name
in self
,
returning TRUE in case an offset named name
was found.
Returns
TRUE if the specified offset is found
Since: 3.6
Types and Values
GTK_LEVEL_BAR_OFFSET_LOW
#define GTK_LEVEL_BAR_OFFSET_LOW "low"
The name used for the stock low offset included by GtkLevelBar.
Since: 3.6
GTK_LEVEL_BAR_OFFSET_HIGH
#define GTK_LEVEL_BAR_OFFSET_HIGH "high"
The name used for the stock high offset included by GtkLevelBar.
Since: 3.6
GTK_LEVEL_BAR_OFFSET_FULL
#define GTK_LEVEL_BAR_OFFSET_FULL "full"
The name used for the stock full offset included by GtkLevelBar.
Since: 3.20
enum GtkLevelBarMode
Describes how GtkLevelBar contents should be rendered.
Note that this enumeration could be extended with additional modes
in the future.
Since: 3.6
struct GtkLevelBar
struct GtkLevelBar;
Property Details
The “inverted” property
“inverted” gboolean
Level bars normally grow from top to bottom or left to right.
Inverted level bars grow in the opposite direction.
Owner: GtkLevelBar
Flags: Read / Write
Default value: FALSE
Since: 3.8
The “max-value” property
“max-value” gdouble
The “max-value” property determaxes the maximum value of
the interval that can be displayed by the bar.
Owner: GtkLevelBar
Flags: Read / Write
Allowed values: >= 0
Default value: 1
Since: 3.6
The “min-value” property
“min-value” gdouble
The “min-value” property determines the minimum value of
the interval that can be displayed by the bar.
Owner: GtkLevelBar
Flags: Read / Write
Allowed values: >= 0
Default value: 0
Since: 3.6
The “mode” property
“mode” GtkLevelBarMode
The “mode” property determines the way GtkLevelBar
interprets the value properties to draw the level fill area.
Specifically, when the value is GTK_LEVEL_BAR_MODE_CONTINUOUS,
GtkLevelBar will draw a single block representing the current value in
that area; when the value is GTK_LEVEL_BAR_MODE_DISCRETE,
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 of “min-value” and “max-value”.
Owner: GtkLevelBar
Flags: Read / Write
Default value: GTK_LEVEL_BAR_MODE_CONTINUOUS
Since: 3.6
The “value” property
“value” gdouble
The “value” property determines the currently
filled value of the level bar.
Owner: GtkLevelBar
Flags: Read / Write
Allowed values: >= 0
Default value: 0
Since: 3.6