LevelBar

open class LevelBar : Widget, LevelBarProtocol

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

(C Language Example):


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

(plain Language Example):

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.

The LevelBar type acts as a reference-counted owner of an underlying GtkLevelBar instance. It provides the methods that can operate on this data type through LevelBarProtocol conformance. Use LevelBar as a strong reference or owner of a GtkLevelBar instance.

  • Designated initialiser from the underlying `C` data type.
    

    This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the LevelBar instance.

    Declaration

    Swift

    @inlinable
    public init(_ op: UnsafeMutablePointer<GtkLevelBar>)

    Parameters

    op

    pointer to the underlying object

  • Designated initialiser from a constant pointer to the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the LevelBar instance.

    Declaration

    Swift

    @inlinable
    public init(_ op: UnsafePointer<GtkLevelBar>)

    Parameters

    op

    pointer to the underlying object

  • Optional initialiser from a non-mutating gpointer to the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the LevelBar instance.

    Declaration

    Swift

    @inlinable
    override public init!(gpointer op: gpointer?)

    Parameters

    op

    gpointer to the underlying object

  • Optional initialiser from a non-mutating gconstpointer to the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the LevelBar instance.

    Declaration

    Swift

    @inlinable
    override public init!(gconstpointer op: gconstpointer?)

    Parameters

    op

    pointer to the underlying object

  • Optional initialiser from a constant pointer to the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the LevelBar instance.

    Declaration

    Swift

    @inlinable
    public init!(_ op: UnsafePointer<GtkLevelBar>?)

    Parameters

    op

    pointer to the underlying object

  • Optional initialiser from the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the LevelBar instance.

    Declaration

    Swift

    @inlinable
    public init!(_ op: UnsafeMutablePointer<GtkLevelBar>?)

    Parameters

    op

    pointer to the underlying object

  • Designated initialiser from the underlying C data type. Will retain GtkLevelBar. i.e., ownership is transferred to the LevelBar instance.

    Declaration

    Swift

    @inlinable
    public init(retaining op: UnsafeMutablePointer<GtkLevelBar>)

    Parameters

    op

    pointer to the underlying object

  • Reference intialiser for a related type that implements LevelBarProtocol Will retain GtkLevelBar.

    Declaration

    Swift

    @inlinable
    public init<T>(levelBar other: T) where T : LevelBarProtocol

    Parameters

    other

    an instance of a related type that implements LevelBarProtocol

  • Unsafe typed initialiser. Do not use unless you know the underlying data type the pointer points to conforms to LevelBarProtocol.

    Declaration

    Swift

    @inlinable
    override public init<T>(cPointer p: UnsafeMutablePointer<T>)

    Parameters

    cPointer

    pointer to the underlying object

  • Unsafe typed, retaining initialiser. Do not use unless you know the underlying data type the pointer points to conforms to LevelBarProtocol.

    Declaration

    Swift

    @inlinable
    override public init<T>(retainingCPointer cPointer: UnsafeMutablePointer<T>)

    Parameters

    cPointer

    pointer to the underlying object

  • Unsafe untyped initialiser. Do not use unless you know the underlying data type the pointer points to conforms to LevelBarProtocol.

    Declaration

    Swift

    @inlinable
    override public init(raw p: UnsafeRawPointer)

    Parameters

    p

    raw pointer to the underlying object

  • Unsafe untyped, retaining initialiser. Do not use unless you know the underlying data type the pointer points to conforms to LevelBarProtocol.

    Declaration

    Swift

    @inlinable
    override public init(retainingRaw raw: UnsafeRawPointer)
  • Unsafe untyped initialiser. Do not use unless you know the underlying data type the pointer points to conforms to LevelBarProtocol.

    Declaration

    Swift

    @inlinable
    public required init(raw p: UnsafeMutableRawPointer)

    Parameters

    p

    mutable raw pointer to the underlying object

  • Unsafe untyped, retaining initialiser. Do not use unless you know the underlying data type the pointer points to conforms to LevelBarProtocol.

    Declaration

    Swift

    @inlinable
    required public init(retainingRaw raw: UnsafeMutableRawPointer)

    Parameters

    raw

    mutable raw pointer to the underlying object

  • Unsafe untyped initialiser. Do not use unless you know the underlying data type the pointer points to conforms to LevelBarProtocol.

    Declaration

    Swift

    @inlinable
    override public init(opaquePointer p: OpaquePointer)

    Parameters

    p

    opaque pointer to the underlying object

  • Unsafe untyped, retaining initialiser. Do not use unless you know the underlying data type the pointer points to conforms to LevelBarProtocol.

    Declaration

    Swift

    @inlinable
    override public init(retainingOpaquePointer p: OpaquePointer)

    Parameters

    p

    opaque pointer to the underlying object

  • Creates a new GtkLevelBar.

    Declaration

    Swift

    @inlinable
    public init()
  • Utility constructor that creates a new GtkLevelBar for the specified interval.

    Declaration

    Swift

    @inlinable
    public init(interval minValue: Double, maxValue: Double)
  • Utility constructor that creates a new GtkLevelBar for the specified interval.

    Declaration

    Swift

    @inlinable
    public static func newFor(interval minValue: Double, maxValue: Double) -> Widget!