Gtk.LevelBar¶

Example¶

Subclasses:: None

Methods¶

Inherited:: Gtk.Widget (181), GObject.Object (37), Gtk.Accessible (15), Gtk.Buildable (1), Gtk.Orientable (2)
Structs:: Gtk.WidgetClass (18), GObject.ObjectClass (5)

class	`new` ()
class	`new_for_interval` (min_value, max_value)
	`add_offset_value` (name, value)
	`get_inverted` ()
	`get_max_value` ()
	`get_min_value` ()
	`get_mode` ()
	`get_offset_value` (name)
	`get_value` ()
	`remove_offset_value` (name)
	`set_inverted` (inverted)
	`set_max_value` (value)
	`set_min_value` (value)
	`set_mode` (mode)
	`set_value` (value)

Virtual Methods¶

Inherited:: Gtk.Widget (25), GObject.Object (7), Gtk.Accessible (6), Gtk.Buildable (9), Gtk.AccessibleRange (1)

Properties¶

Inherited:: Gtk.Widget (34), Gtk.Accessible (1), Gtk.Orientable (1)

Name	Type	Flags
`inverted`	`bool`	r/w/en
`max-value`	`float`	r/w/en
`min-value`	`float`	r/w/en
`mode`	`Gtk.LevelBarMode`	r/w/en
`value`	`float`	r/w/en

Signals¶

Inherited:: Gtk.Widget (13), GObject.Object (1)

Name	Short Description
`offset-changed`	Emitted when an offset specified on the bar changes value.

Fields¶

Inherited:: Gtk.Widget (13), GObject.Object (1)

Class Details¶

class Gtk.LevelBar(**kwargs)¶

Bases:: Gtk.Widget, Gtk.AccessibleRange, Gtk.Orientable
Abstract:: No

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.

An example Gtk.LevelBar

Use [method`Gtk`.LevelBar.set_value] to set the current value, and [method`Gtk`.LevelBar.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

```c static Gtk.Widget * create_level_bar (void) { Gtk.Widget *widget; Gtk.LevelBar *bar;

widget = Gtk.LevelBar.new (); bar = GTK_LEVEL_BAR (widget);

// This changes the value of the default low offset

Gtk.LevelBar.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.LevelBar.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 [method`Gtk`.LevelBar.set_min_value] and [method`Gtk`.LevelBar.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.LevelBarMode.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.

Gtk.LevelBar as Gtk.Buildable

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 Gtk.AccessibleRole.METER role.

classmethod new()[source]¶

Returns:: a GtkLevelBar.
Return type:: Gtk.Widget

Creates a new GtkLevelBar.

classmethod new_for_interval(min_value, max_value)[source]¶

Parameters:

min_value (float) – a positive value
max_value (float) – a positive value

Returns:

a GtkLevelBar

Return type:

Gtk.Widget

Creates a new GtkLevelBar for the specified interval.

add_offset_value(name, value)[source]¶

Parameters:

name (str) – the name of the new offset
value (float) – the value for the new offset

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 [property`Gtk`.LevelBar: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.

get_inverted()[source]¶

Returns:: True if the level bar is inverted
Return type:: bool

Returns whether the levelbar is inverted.

get_max_value()[source]¶

Returns:: a positive value
Return type:: float

Returns the max-value of the GtkLevelBar.

get_min_value()[source]¶

Returns:: a positive value
Return type:: float

Returns the min-value of the GtkLevelBar.

get_mode()[source]¶

Returns:: a GtkLevelBarMode
Return type:: Gtk.LevelBarMode

Returns the mode of the GtkLevelBar.

get_offset_value(name)[source]¶

Parameters:

name (str or None) – the name of an offset in the bar

Returns:

True if the specified offset is found

value:: location where to store the value

Return type:

(bool, value: float)

Fetches the value specified for the offset marker name in self.

get_value()[source]¶

Returns:: a value in the interval between [property`Gtk`.LevelBar:min-value] and [property`Gtk`.LevelBar:max-value]
Return type:: float

Returns the value of the GtkLevelBar.

remove_offset_value(name)[source]¶

Parameters:: name (str or None) – the name of an offset in the bar

Removes an offset marker from a GtkLevelBar.

The marker must have been previously added with [method`Gtk`.LevelBar.add_offset_value].

set_inverted(inverted)[source]¶

Parameters:: inverted (bool) – True to invert the level bar

Sets whether the GtkLevelBar is inverted.

set_max_value(value)[source]¶

Parameters:: value (float) – a positive value

Sets the max-value of the GtkLevelBar.

You probably want to update preexisting level offsets after calling this function.

set_min_value(value)[source]¶

Parameters:: value (float) – a positive value

Sets the min-value of the GtkLevelBar.

You probably want to update preexisting level offsets after calling this function.

set_mode(mode)[source]¶

Parameters:: mode (Gtk.LevelBarMode) – a GtkLevelBarMode

Sets the mode of the GtkLevelBar.

set_value(value)[source]¶

Parameters:: value (float) – a value in the interval between [property`Gtk`.LevelBar:min-value] and [property`Gtk`.LevelBar:max-value]

Sets the value of the GtkLevelBar.

Signal Details¶

Gtk.LevelBar.signals.offset_changed(level_bar, name)¶

Signal Name:

offset-changed

Flags:

RUN_FIRST, DETAILED

Parameters:

level_bar (Gtk.LevelBar) – The object which received the signal
name (str) – the name of the offset that changed value

Emitted when an offset specified on the bar changes value.

This typically is the result of a [method`Gtk`.LevelBar.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.

Property Details¶

Gtk.LevelBar.props.inverted¶

Name:: inverted
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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.

Gtk.LevelBar.props.max_value¶

Name:: max-value
Type:: float
Default Value:: 1.0
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Determines the maximum value of the interval that can be displayed by the bar.

Gtk.LevelBar.props.min_value¶

Name:: min-value
Type:: float
Default Value:: 0.0
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Determines the minimum value of the interval that can be displayed by the bar.

Gtk.LevelBar.props.mode¶

Name:: mode
Type:: Gtk.LevelBarMode
Default Value:: Gtk.LevelBarMode.CONTINUOUS
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Determines the way GtkLevelBar interprets the value properties to draw the level fill area.

Specifically, when the value is Gtk.LevelBarMode.CONTINUOUS, GtkLevelBar will draw a single block representing the current value in that area; when the value is Gtk.LevelBarMode.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 [property`Gtk`.LevelBar:min-value] and [property`Gtk`.LevelBar:max-value].

Gtk.LevelBar.props.value¶

Name:: value
Type:: float
Default Value:: 0.0
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Determines the currently filled value of the level bar.