GtkLevelBar: GTK+ 3 Reference Manual

## GtkLevelBar GtkLevelBar — A bar that can used as a level indicator |

## Functions

GtkWidget * | gtk_level_bar_new ()
GtkWidget * | gtk_level_bar_new_for_interval ()
void | gtk_level_bar_set_mode ()
GtkLevelBarMode | gtk_level_bar_get_mode ()
void | gtk_level_bar_set_value ()
gdouble | gtk_level_bar_get_value ()
void | gtk_level_bar_set_min_value ()
gdouble | gtk_level_bar_get_min_value ()
void | gtk_level_bar_set_max_value ()
gdouble | gtk_level_bar_get_max_value ()
void | gtk_level_bar_set_inverted ()
gboolean | gtk_level_bar_get_inverted ()
void | gtk_level_bar_add_offset_value ()
void | gtk_level_bar_remove_offset_value ()
gboolean | gtk_level_bar_get_offset_value ()

## Properties

gboolean | inverted | Read / Write
gdouble | max-value | Read / Write
gdouble | min-value | Read / Write
GtkLevelBarMode | mode | Read / Write
gdouble | value | Read / Write

## Style Properties

gint | min-block-height | Read / Write
gint | min-block-width | Read / Write

## Signals

void | offset-changed | Has Details

## Types and Values

#define | GTK_LEVEL_BAR_OFFSET_LOW
#define | GTK_LEVEL_BAR_OFFSET_HIGH
#define | GTK_LEVEL_BAR_OFFSET_FULL
enum | GtkLevelBarMode
struct | GtkLevelBar

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkLevelBar

## Implemented Interfaces

GtkLevelBar implements AtkImplementorIface, GtkBuildable and GtkOrientable.

## Includes

    #include <gtk/gtk.h>

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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    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_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

    1
    2
    3
    4
    5
    6
    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.

## Functions

### gtk_level_bar_new ()

    GtkWidget *
    gtk_level_bar_new (void);

Creates a new GtkLevelBar.

#### Returns

a GtkLevelBar.

Since: 3.6

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

#### Parameters

min_value | a positive value |
max_value | a positive value |

#### Returns

a GtkLevelBar

Since: 3.6

### gtk_level_bar_set_mode ()

    void
    gtk_level_bar_set_mode (GtkLevelBar *self,
                            GtkLevelBarMode mode);

Sets the value of the “mode” property.

#### Parameters

self | a GtkLevelBar |
mode | a GtkLevelBarMode |

Since: 3.6

### gtk_level_bar_get_mode ()

    GtkLevelBarMode
    gtk_level_bar_get_mode (GtkLevelBar *self);

Returns the value of the “mode” property.

#### Parameters

self | a GtkLevelBar |

#### Returns

a GtkLevelBarMode

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.

#### Parameters

self | a GtkLevelBar |
value | a value in the interval between “min-value” and “max-value” |

Since: 3.6

### gtk_level_bar_get_value ()

    gdouble
    gtk_level_bar_get_value (GtkLevelBar *self);

Returns the value of the “value” property.

#### Parameters

self | a GtkLevelBar |

#### Returns

a value in the interval between “min-value” and “max-value”

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.

#### Parameters

self | a GtkLevelBar |
value | a positive value |

Since: 3.6

### gtk_level_bar_get_min_value ()

    gdouble
    gtk_level_bar_get_min_value (GtkLevelBar *self);

Returns the value of the “min-value” property.

#### Parameters

self | a GtkLevelBar |

#### Returns

a positive value

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.

#### Parameters

self | a GtkLevelBar |
value | a positive value |

Since: 3.6

### gtk_level_bar_get_max_value ()

    gdouble
    gtk_level_bar_get_max_value (GtkLevelBar *self);

Returns the value of the “max-value” property.

#### Parameters

self | a GtkLevelBar |

#### Returns

a positive value

Since: 3.6

### gtk_level_bar_set_inverted ()

    void
    gtk_level_bar_set_inverted (GtkLevelBar *self,
                                gboolean inverted);

Sets the value of the “inverted” property.

#### Parameters

self | a GtkLevelBar |
inverted | `TRUE` to invert the level bar |

Since: 3.8

### gtk_level_bar_get_inverted ()

    gboolean
    gtk_level_bar_get_inverted (GtkLevelBar *self);

Return the value of the “inverted” property.

#### Parameters

self | a GtkLevelBar |

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

#### Parameters

self | a GtkLevelBar |
name | the name of the new offset |
value | the value for the new offset |

Since: 3.6

### gtk_level_bar_remove_offset_value ()

    void
    gtk_level_bar_remove_offset_value (GtkLevelBar *self,
                                       const gchar *name);

Removes an offset marker previously added with `gtk_level_bar_add_offset_value()`.

#### Parameters

self | a GtkLevelBar |
name | the name of an offset in the bar. | [allow-none]

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.

#### Parameters

self | a GtkLevelBar |
name | the name of an offset in the bar. | [allow-none]
value | location where to store the value. | [out]

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

#### Members

GTK_LEVEL_BAR_MODE_CONTINUOUS | the bar has a continuous mode |
GTK_LEVEL_BAR_MODE_DISCRETE | the bar has a discrete mode |

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.

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.

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.

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

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.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 3.6

## Style Property Details

### The `“min-block-height”` style property

      “min-block-height”         gint

The min-block-height style property determines the minimum height for blocks filling the GtkLevelBar widget.

`GtkLevelBar:min-block-height` has been deprecated since version 3.20 and should not be used in newly-written code.

Use the standard min-width/min-height CSS properties on the block elements; the value of this style property is ignored.

Flags: Read / Write

Allowed values: >= 1

Default value: 3

Since: 3.6

### The `“min-block-width”` style property

      “min-block-width”          gint

The min-block-width style property determines the minimum width for blocks filling the GtkLevelBar widget.

`GtkLevelBar:min-block-width` has been deprecated since version 3.20 and should not be used in newly-written code.

Use the standard min-width/min-height CSS properties on the block elements; the value of this style property is ignored.

Flags: Read / Write

Allowed values: >= 1

Default value: 3

Since: 3.6

## Signal Details

### The `“offset-changed”` signal

    void
    user_function (GtkLevelBar *self,
                   gchar       *name,
                   gpointer     user_data)

Emitted when an offset specified on the bar changes value as an effect to `gtk_level_bar_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.

#### Parameters

self | a GtkLevelBar |
name | the name of the offset that changed value |
user_data | user data set when the signal handler was connected. |

Flags: Has Details

Since: 3.6