GtkLevelBar

GtkLevelBar — A bar that can used as a level indicator

Functions

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

Types and Values

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.

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
30
31
32
33
34
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 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 (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 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 “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