Class LevelBar

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gobject.InitiallyUnowned
org.gnome.gtk.Widget
org.gnome.gtk.LevelBar
All Implemented Interfaces:
Accessible, AccessibleRange, Buildable, ConstraintTarget, Orientable, Proxy
@Generated("org.javagi.JavaGI") public class LevelBar extends Widget implements Accessible, AccessibleRange, Buildable, ConstraintTarget, Orientable

Shows a level indicator.

Typical use cases are displaying the strength of a password, or showing the charge level of a battery.

An example GtkLevelBar

Use setValue(double) to set the current value, and addOffsetValue(String, double) 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

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-width: 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 setMinValue(double) and setMaxValue(double). 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 LevelBarMode.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 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

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.

Accessibility

GtkLevelBar uses the Gtk.AccessibleRole.meter role.

  • Constructor Details

    • LevelBar

      public LevelBar(MemorySegment address)
      Create a LevelBar instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • LevelBar

      public LevelBar()
      Create a new LevelBar.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the LevelBar class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected LevelBar asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class Widget
      Returns:
      the instance as if it were its parent type

    • forInterval

      public static LevelBar forInterval(double minValue, double maxValue)
      Creates a new GtkLevelBar for the specified interval.
      Parameters:
      minValue - a positive value
      maxValue - a positive value
      Returns:
      a GtkLevelBar

    • addOffsetValue

      public void addOffsetValue(String name, double value)

      Adds a new offset marker on this LevelBar at the position specified by value.

      When the bar value is in the interval topped by value (or between value and Gtk.LevelBar: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:
      name - the name of the new offset
      value - the value for the new offset

    • getInverted

      public boolean getInverted()
      Returns whether the levelbar is inverted.
      Returns:
      true if the level bar is inverted

    • getMaxValue

      public double getMaxValue()
      Returns the max-value of the GtkLevelBar.
      Returns:
      a positive value

    • getMinValue

      public double getMinValue()
      Returns the min-value of the GtkLevelBar.
      Returns:
      a positive value

    • getMode

      public LevelBarMode getMode()
      Returns the mode of the GtkLevelBar.
      Returns:
      a GtkLevelBarMode

    • getOffsetValue

      public boolean getOffsetValue(@Nullable String name, Out<Double> value)
      Fetches the value specified for the offset marker name in self.
      Parameters:
      name - the name of an offset in the bar
      value - location where to store the value
      Returns:
      true if the specified offset is found

    • getValue

      public double getValue()
      Returns the value of the GtkLevelBar.
      Returns:
      a value in the interval between Gtk.LevelBar:min-value and Gtk.LevelBar:max-value

    • removeOffsetValue

      public void removeOffsetValue(@Nullable String name)

      Removes an offset marker from a GtkLevelBar.

      The marker must have been previously added with addOffsetValue(String, double).

      Parameters:
      name - the name of an offset in the bar

    • setInverted

      public void setInverted(boolean inverted)
      Sets whether the GtkLevelBar is inverted.
      Parameters:
      inverted - true to invert the level bar

    • setMaxValue

      public void setMaxValue(double value)

      Sets the max-value of the GtkLevelBar.

      You probably want to update preexisting level offsets after calling this function.

      Parameters:
      value - a positive value

    • setMinValue

      public void setMinValue(double value)

      Sets the min-value of the GtkLevelBar.

      You probably want to update preexisting level offsets after calling this function.

      Parameters:
      value - a positive value

    • setMode

      public void setMode(LevelBarMode mode)
      Sets the mode of the GtkLevelBar.
      Parameters:
      mode - a GtkLevelBarMode

    • setValue

      public void setValue(double value)
      Sets the value of the GtkLevelBar.
      Parameters:
      value - a value in the interval between Gtk.LevelBar:min-value and Gtk.LevelBar:max-value

    • onOffsetChanged

      public SignalConnection<LevelBar.OffsetChangedCallback> onOffsetChanged(@Nullable String detail, LevelBar.OffsetChangedCallback handler)

      Emitted when an offset specified on the bar changes value.

      This typically is the result of a addOffsetValue(String, double) call.

      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:
      detail - the signal detail
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitOffsetChanged

      public void emitOffsetChanged(@Nullable String detail, String name)
      Emits the "offset-changed" signal. See onOffsetChanged(String, LevelBar.OffsetChangedCallback).

    • builder

      public static LevelBar.Builder<? extends LevelBar.Builder> builder()
      A LevelBar.Builder object constructs a LevelBar with the specified properties. Use the various set...() methods to set properties, and finish construction with LevelBar.Builder.build().
      Returns:
      the builder object