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

  "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 52. Adding a custom offset on the bar


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_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 "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