GTK+ 3 Reference Manual: GtkLevelBar

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

## Synopsis

    #include <gtk/gtk.h>

    #define             GTK_LEVEL_BAR_OFFSET_LOW
    #define             GTK_LEVEL_BAR_OFFSET_HIGH
    enum                GtkLevelBarMode;
    struct              GtkLevelBar;
    GtkWidget *         gtk_level_bar_new                   (void);
    GtkWidget *         gtk_level_bar_new_for_interval      (gdouble min_value,
                                                             gdouble max_value);
    void                gtk_level_bar_set_mode              (GtkLevelBar *self,
                                                             GtkLevelBarMode mode);
    GtkLevelBarMode     gtk_level_bar_get_mode              (GtkLevelBar *self);
    void                gtk_level_bar_set_value             (GtkLevelBar *self,
                                                             gdouble value);
    gdouble             gtk_level_bar_get_value             (GtkLevelBar *self);
    void                gtk_level_bar_set_min_value         (GtkLevelBar *self,
                                                             gdouble value);
    gdouble             gtk_level_bar_get_min_value         (GtkLevelBar *self);
    void                gtk_level_bar_set_max_value         (GtkLevelBar *self,
                                                             gdouble value);
    gdouble             gtk_level_bar_get_max_value         (GtkLevelBar *self);
    void                gtk_level_bar_set_inverted          (GtkLevelBar *self,
                                                             gboolean inverted);
    gboolean            gtk_level_bar_get_inverted          (GtkLevelBar *self);
    void                gtk_level_bar_add_offset_value      (GtkLevelBar *self,
                                                             const gchar *name,
                                                             gdouble value);
    void                gtk_level_bar_remove_offset_value   (GtkLevelBar *self,
                                                             const gchar *name);
    gboolean            gtk_level_bar_get_offset_value      (GtkLevelBar *self,
                                                             const gchar *name,
                                                             gdouble *value);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkWidget
                   +----GtkLevelBar

## Implemented Interfaces

GtkLevelBar implements AtkImplementorIface, GtkBuildable and GtkOrientable.

## Properties

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

## Style Properties

      "min-block-height"         gint                  : Read / Write
      "min-block-width"          gint                  : Read / Write

## Signals

      "offset-changed"                                 : Has Details

## 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 two offsets by default on the level bar: GTK_LEVEL_BAR_OFFSET_LOW and GTK_LEVEL_BAR_OFFSET_HIGH, with values 0.25 and 0.75 respectively.

Example 21. 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
    static GtkWidget *
    create_level_bar (void)
    {
      GtkWidget *level_bar;

      level_bar = gtk_level_bar_new ();

      /* This changes the value of the default low offset */
      gtk_level_bar_add_offset_value (GTK_LEVEL_BAR (level_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 by using the following selector,
       * either by adding it to its CSS file or using
       * gtk_css_provider_load_from_data() and gtk_style_context_add_provider()
       *
       * .level-bar.fill-block.level-my-offset {
       *   background-color: green;
       *   border-style: solid;
       *   border-color: black;
       *   border-style: 1px;
       * }
       */
      gtk_level_bar_add_offset_value (GTK_LEVEL_BAR (level_bar),
                                      "my-offset", 0.60);

      return level_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 and 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.

## Details

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

### enum GtkLevelBarMode

    typedef enum {
      GTK_LEVEL_BAR_MODE_CONTINUOUS,
      GTK_LEVEL_BAR_MODE_DISCRETE
    } GtkLevelBarMode;

Describes how GtkLevelBar contents should be rendered. Note that this enumeration could be extended with additional modes in the future.

`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;

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

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

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

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

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

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

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

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

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

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

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

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

`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()`.

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

`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

## Property Details

### The `"inverted"` property

      "inverted"                 gboolean              : Read / Write

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

Default value: FALSE

Since 3.8

### The `"max-value"` property

      "max-value"                gdouble               : Read / Write

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

Allowed values: >= 0

Default value: 1

Since 3.6

### The `"min-value"` property

      "min-value"                gdouble               : Read / Write

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

Allowed values: >= 0

Default value: 0

Since 3.6

### The `"mode"` property

      "mode"                     GtkLevelBarMode       : Read / Write

The "bar-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".

Default value: GTK_LEVEL_BAR_MODE_CONTINUOUS

Since 3.6

### The `"value"` property

      "value"                    gdouble               : Read / Write

The "value" property determines the currently filled value of the level bar.

Allowed values: >= 0

Default value: 0

Since 3.6

## Style Property Details

### The `"min-block-height"` style property

      "min-block-height"         gint                  : Read / Write

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

Allowed values: >= 1

Default value: 3

Since 3.6

### The `"min-block-width"` style property

      "min-block-width"          gint                  : Read / Write

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

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)      : Has Details

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.

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

Since 3.6