:right-sidebar: True LevelBar =================================================================== .. currentmodule:: gi.repository.Gtk .. class:: LevelBar(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.AccessibleRange`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`, :class:`~gi.repository.Gtk.Orientable` ``GtkLevelBar`` is a 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. .. image:: https://docs.gtk.org/gtk4/levelbar.png Use :obj:`~gi.repository.Gtk.LevelBar.set_value` to set the current value, and :obj:`~gi.repository.Gtk.LevelBar.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: :const:`~gi.repository.Gtk.LEVEL_BAR_OFFSET_LOW`, :const:`~gi.repository.Gtk.LEVEL_BAR_OFFSET_HIGH` and :const:`~gi.repository.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 -------------------------------------------------------------------------------- .. code-block:: c :dedent: 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 :obj:`~gi.repository.Gtk.LevelBar.set_min_value` and :obj:`~gi.repository.Gtk.LevelBar.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 :const:`~gi.repository.Gtk.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 ```` element, which can contain any number of ```` elements, each of which must have "name" and "value" attributes. CSS nodes -------------------------------------------------------------------------------- .. code-block:: :dedent: 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 :const:`~gi.repository.Gtk.AccessibleRole.METER` role. Constructors ------------ .. rst-class:: interim-class .. class:: LevelBar :no-index: .. classmethod:: new() -> ~gi.repository.Gtk.Widget Creates a new ``GtkLevelBar``\. .. classmethod:: new_for_interval(min_value: float, max_value: float) -> ~gi.repository.Gtk.Widget Creates a new ``GtkLevelBar`` for the specified interval. :param min_value: a positive value :param max_value: a positive value Methods ------- .. rst-class:: interim-class .. class:: LevelBar :no-index: .. method:: add_offset_value(name: str, value: float) -> None 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 :obj:`~gi.repository.Gtk.LevelBar.props.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``\. :param name: the name of the new offset :param value: the value for the new offset .. method:: get_inverted() -> bool Returns whether the levelbar is inverted. .. method:: get_max_value() -> float Returns the ``max-value`` of the ``GtkLevelBar``\. .. method:: get_min_value() -> float Returns the ``min-value`` of the ``GtkLevelBar``\. .. method:: get_mode() -> ~gi.repository.Gtk.LevelBarMode Returns the ``mode`` of the ``GtkLevelBar``\. .. method:: get_offset_value(name: str | None = None) -> ~typing.Tuple[bool, float] Fetches the value specified for the offset marker ``name`` in ``self``\. :param name: the name of an offset in the bar .. method:: get_value() -> float Returns the ``value`` of the ``GtkLevelBar``\. .. method:: remove_offset_value(name: str | None = None) -> None Removes an offset marker from a ``GtkLevelBar``\. The marker must have been previously added with :obj:`~gi.repository.Gtk.LevelBar.add_offset_value`\. :param name: the name of an offset in the bar .. method:: set_inverted(inverted: bool) -> None Sets whether the ``GtkLevelBar`` is inverted. :param inverted: :const:`True` to invert the level bar .. method:: set_max_value(value: float) -> None Sets the ``max-value`` of the ``GtkLevelBar``\. You probably want to update preexisting level offsets after calling this function. :param value: a positive value .. method:: set_min_value(value: float) -> None Sets the ``min-value`` of the ``GtkLevelBar``\. You probably want to update preexisting level offsets after calling this function. :param value: a positive value .. method:: set_mode(mode: ~gi.repository.Gtk.LevelBarMode) -> None Sets the ``mode`` of the ``GtkLevelBar``\. :param mode: a ``GtkLevelBarMode`` .. method:: set_value(value: float) -> None Sets the value of the ``GtkLevelBar``\. :param value: a value in the interval between :obj:`~gi.repository.Gtk.LevelBar.props.min_value` and :obj:`~gi.repository.Gtk.LevelBar.props.max_value` Properties ---------- .. rst-class:: interim-class .. class:: LevelBar :no-index: .. attribute:: props.inverted :type: bool The type of the None singleton. .. attribute:: props.max_value :type: float The type of the None singleton. .. attribute:: props.min_value :type: float The type of the None singleton. .. attribute:: props.mode :type: ~gi.repository.Gtk.LevelBarMode The type of the None singleton. .. attribute:: props.value :type: float The type of the None singleton. Signals ------- .. rst-class:: interim-class .. class:: LevelBar.signals :no-index: .. method:: offset_changed(name: str) -> None The type of the None singleton. :param name: the name of the offset that changed value