Gtk.LevelBar

g Atk.ImplementorIface Atk.ImplementorIface Gtk.Widget Gtk.Widget Atk.ImplementorIface->Gtk.Widget GObject.GInterface GObject.GInterface GObject.GInterface->Atk.ImplementorIface Gtk.Buildable Gtk.Buildable GObject.GInterface->Gtk.Buildable Gtk.Orientable Gtk.Orientable GObject.GInterface->Gtk.Orientable GObject.InitiallyUnowned GObject.InitiallyUnowned GObject.InitiallyUnowned->Gtk.Widget GObject.Object GObject.Object GObject.Object->GObject.InitiallyUnowned Gtk.Buildable->Gtk.Widget Gtk.LevelBar Gtk.LevelBar Gtk.Orientable->Gtk.LevelBar Gtk.Widget->Gtk.LevelBar

Example

../_images/LevelBar.png
Subclasses:

None

Methods

Inherited:

Gtk.Widget (278), GObject.Object (37), Gtk.Buildable (10), Gtk.Orientable (2)

Structs:

Gtk.WidgetClass (12), 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 (82), GObject.Object (7), Gtk.Buildable (10)

do_offset_changed (name)

Properties

Inherited:

Gtk.Widget (39), Gtk.Orientable (1)

Name

Type

Flags

Short Description

inverted

bool

r/w/en

Invert the direction in which the level bar grows

max-value

float

r/w/en

Maximum value level that can be displayed by the bar

min-value

float

r/w/en

Minimum value level that can be displayed by the bar

mode

Gtk.LevelBarMode

r/w/en

The mode of the value indicator displayed by the bar

value

float

r/w/en

Currently filled value level of the level bar

Style Properties

Inherited:

Gtk.Widget (17)

Name

Type

Default

Flags

Short Description

min-block-height

int

3

d/r/w

Minimum height for blocks that fill the bar deprecated

min-block-width

int

3

d/r/w

Minimum width for blocks that fill the bar deprecated

Signals

Inherited:

Gtk.Widget (69), GObject.Object (1)

Name

Short Description

offset-changed

Emitted when an offset specified on the bar changes value as an effect to Gtk.LevelBar.add_offset_value() being called.

Fields

Inherited:

Gtk.Widget (69), GObject.Object (1)

Name

Type

Access

Description

parent

Gtk.Widget

r

Class Details

class Gtk.LevelBar(**kwargs)
Bases:

Gtk.Widget, Gtk.Orientable

Abstract:

No

Structure:

Gtk.LevelBarClass

The Gtk.LevelBar 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.LevelBar.set_value() to set the current value, and 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
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-style: 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 Gtk.LevelBar.set_min_value() and 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 was introduced in GTK+ 3.6.

Gtk.LevelBar as Gtk.Buildable

The Gtk.LevelBar implementation of the Gtk.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
levelbar[.discrete]
╰── trough
    ├── block.filled.level-name
    ┊
    ├── block.empty
    ┊

Gtk.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.

classmethod new()[source]
Returns:

a Gtk.LevelBar.

Return type:

Gtk.Widget

Creates a new Gtk.LevelBar.

New in version 3.6.

classmethod new_for_interval(min_value, max_value)[source]
Parameters:
  • min_value (float) – a positive value

  • max_value (float) – a positive value

Returns:

a Gtk.LevelBar

Return type:

Gtk.Widget

Utility constructor that creates a new Gtk.LevelBar for the specified interval.

New in version 3.6.

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 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.

New in version 3.6.

get_inverted()[source]
Returns:

True if the level bar is inverted

Return type:

bool

Return the value of the Gtk.LevelBar :inverted property.

New in version 3.8.

get_max_value()[source]
Returns:

a positive value

Return type:

float

Returns the value of the Gtk.LevelBar :max-value property.

New in version 3.6.

get_min_value()[source]
Returns:

a positive value

Return type:

float

Returns the value of the Gtk.LevelBar :min-value property.

New in version 3.6.

get_mode()[source]
Returns:

a Gtk.LevelBarMode

Return type:

Gtk.LevelBarMode

Returns the value of the Gtk.LevelBar :mode property.

New in version 3.6.

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, returning True in case an offset named name was found.

New in version 3.6.

get_value()[source]
Returns:

a value in the interval between Gtk.LevelBar :min-value and Gtk.LevelBar :max-value

Return type:

float

Returns the value of the Gtk.LevelBar :value property.

New in version 3.6.

remove_offset_value(name)[source]
Parameters:

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

Removes an offset marker previously added with Gtk.LevelBar.add_offset_value().

New in version 3.6.

set_inverted(inverted)[source]
Parameters:

inverted (bool) – True to invert the level bar

Sets the value of the Gtk.LevelBar :inverted property.

New in version 3.8.

set_max_value(value)[source]
Parameters:

value (float) – a positive value

Sets the value of the Gtk.LevelBar :max-value property.

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

New in version 3.6.

set_min_value(value)[source]
Parameters:

value (float) – a positive value

Sets the value of the Gtk.LevelBar :min-value property.

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

New in version 3.6.

set_mode(mode)[source]
Parameters:

mode (Gtk.LevelBarMode) – a Gtk.LevelBarMode

Sets the value of the Gtk.LevelBar :mode property.

New in version 3.6.

set_value(value)[source]
Parameters:

value (float) – a value in the interval between Gtk.LevelBar :min-value and Gtk.LevelBar :max-value

Sets the value of the Gtk.LevelBar :value property.

New in version 3.6.

do_offset_changed(name) virtual
Parameters:

name (str) –

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 as an effect to Gtk.LevelBar.add_offset_value() being called.

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.

New in version 3.6.

Property Details

Gtk.LevelBar.props.inverted
Name:

inverted

Type:

bool

Default Value:

False

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

Level bars normally grow from top to bottom or left to right. Inverted level bars grow in the opposite direction.

New in version 3.8.

Gtk.LevelBar.props.max_value
Name:

max-value

Type:

float

Default Value:

1.0

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

The Gtk.LevelBar :max-value property determaxes the maximum value of the interval that can be displayed by the bar.

New in version 3.6.

Gtk.LevelBar.props.min_value
Name:

min-value

Type:

float

Default Value:

0.0

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

The Gtk.LevelBar :min-value property determines the minimum value of the interval that can be displayed by the bar.

New in version 3.6.

Gtk.LevelBar.props.mode
Name:

mode

Type:

Gtk.LevelBarMode

Default Value:

Gtk.LevelBarMode.CONTINUOUS

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

The Gtk.LevelBar :mode property determines the way Gtk.LevelBar interprets the value properties to draw the level fill area. Specifically, when the value is Gtk.LevelBarMode.CONTINUOUS, Gtk.LevelBar 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 Gtk.LevelBar :min-value and Gtk.LevelBar :max-value.

New in version 3.6.

Gtk.LevelBar.props.value
Name:

value

Type:

float

Default Value:

0.0

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

The Gtk.LevelBar :value property determines the currently filled value of the level bar.

New in version 3.6.