GTK+ 3 Reference Manual: GtkLevelBar

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

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

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

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

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

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.

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.

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