Struct gtk4::LevelBar

source ·

#[repr(transparent)]
pub struct LevelBar { /* private fields */ }

Expand description

LevelBar 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.

An example GtkLevelBar

Use set_value() to set the current value, and 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: LEVEL_BAR_OFFSET_LOW, LEVEL_BAR_OFFSET_HIGH and 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

⚠️ The following code is in c ⚠️

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 set_min_value() and 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 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 LevelBar implementation of the Buildable 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
    ┊

LevelBar 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

LevelBar uses the AccessibleRole::Meter role.

Properties

`inverted`

Whether the GtkLeveBar is inverted.

Level bars normally grow from top to bottom or left to right. Inverted level bars grow in the opposite direction.

Readable | Writeable

`max-value`

Determines the maximum value of the interval that can be displayed by the bar.

Readable | Writeable

`min-value`

Determines the minimum value of the interval that can be displayed by the bar.

Readable | Writeable

`mode`

Determines the way LevelBar interprets the value properties to draw the level fill area.

Specifically, when the value is LevelBarMode::Continuous, LevelBar will draw a single block representing the current value in that area; when the value is LevelBarMode::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.

Readable | Writeable

`value`

Determines the currently filled value of the level bar.

Readable | Writeable

Widget

`can-focus`

Whether the widget or any of its descendents can accept the input focus.

This property is meant to be set by widget implementations, typically in their instance init function.

Readable | Writeable

`can-target`

Whether the widget can receive pointer events.

Readable | Writeable

`css-classes`

A list of css classes applied to this widget.

Readable | Writeable

`css-name`

The name of this widget in the CSS tree.

This property is meant to be set by widget implementations, typically in their instance init function.

Readable | Writeable | Construct Only

`cursor`

The cursor used by @widget.

Readable | Writeable

`focus-on-click`

Whether the widget should grab focus when it is clicked with the mouse.

This property is only relevant for widgets that can take focus.

Readable | Writeable

`focusable`

Whether this widget itself will accept the input focus.

Readable | Writeable

`halign`

How to distribute horizontal space if widget gets extra space.

Readable | Writeable

`has-default`

Whether the widget is the default widget.

Readable

`has-focus`

Whether the widget has the input focus.

Readable

Enables or disables the emission of the ::query-tooltip signal on @widget.

A value of true indicates that @widget can have a tooltip, in this case the widget will be queried using query-tooltip to determine whether it will provide a tooltip or not.

Readable | Writeable

`height-request`

Override for height request of the widget.

If this is -1, the natural request will be used.

Readable | Writeable

`hexpand`

Whether to expand horizontally.

Readable | Writeable

`hexpand-set`

Whether to use the hexpand property.

Readable | Writeable

`layout-manager`

The LayoutManager instance to use to compute the preferred size of the widget, and allocate its children.

This property is meant to be set by widget implementations, typically in their instance init function.

Readable | Writeable

`margin-bottom`

Margin on bottom side of widget.

This property adds margin outside of the widget’s normal size request, the margin will be added in addition to the size from WidgetExt::set_size_request() for example.

Readable | Writeable

`margin-end`

Margin on end of widget, horizontally.

This property supports left-to-right and right-to-left text directions.

This property adds margin outside of the widget’s normal size request, the margin will be added in addition to the size from WidgetExt::set_size_request() for example.

Readable | Writeable

`margin-start`

Margin on start of widget, horizontally.

This property supports left-to-right and right-to-left text directions.

This property adds margin outside of the widget’s normal size request, the margin will be added in addition to the size from WidgetExt::set_size_request() for example.

Readable | Writeable

`margin-top`

Margin on top side of widget.

This property adds margin outside of the widget’s normal size request, the margin will be added in addition to the size from WidgetExt::set_size_request() for example.

Readable | Writeable

`name`

The name of the widget.

Readable | Writeable

`opacity`

The requested opacity of the widget.

Readable | Writeable

`overflow`

How content outside the widget’s content area is treated.

This property is meant to be set by widget implementations, typically in their instance init function.

Readable | Writeable

`parent`

The parent widget of this widget.

Readable

`receives-default`

Whether the widget will receive the default action when it is focused.

Readable | Writeable

`root`

The Root widget of the widget tree containing this widget.

This will be None if the widget is not contained in a root widget.

Readable

`scale-factor`

The scale factor of the widget.

Readable

`sensitive`

Whether the widget responds to input.

Readable | Writeable

Sets the text of tooltip to be the given string, which is marked up with Pango markup.

Also see Tooltip::set_markup().

This is a convenience property which will take care of getting the tooltip shown if the given string is not None: has-tooltip will automatically be set to true and there will be taken care of query-tooltip in the default signal handler.

Note that if both tooltip-text and tooltip-markup are set, the last one wins.

Readable | Writeable

Sets the text of tooltip to be the given string.

Also see Tooltip::set_text().

This is a convenience property which will take care of getting the tooltip shown if the given string is not None: has-tooltip will automatically be set to true and there will be taken care of query-tooltip in the default signal handler.

Note that if both tooltip-text and tooltip-markup are set, the last one wins.

Readable | Writeable

`valign`

How to distribute vertical space if widget gets extra space.

Readable | Writeable

`vexpand`

Whether to expand vertically.

Readable | Writeable

`vexpand-set`

Whether to use the vexpand property.

Readable | Writeable

`visible`

Whether the widget is visible.

Readable | Writeable

`width-request`

Override for width request of the widget.

If this is -1, the natural request will be used.

Readable | Writeable

Accessible

`accessible-role`

The accessible role of the given Accessible implementation.

The accessible role cannot be changed once set.

Readable | Writeable

Orientable

`orientation`

The orientation of the orientable.

Readable | Writeable

Signals

`offset-changed`

Emitted when an offset specified on the bar changes value.

This typically is the result of a LevelBar::add_offset_value() 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.

Detailed

Widget

`destroy`

Signals that all holders of a reference to the widget should release the reference that they hold.

May result in finalization of the widget if all references are released.

This signal is not suitable for saving widget state.

`direction-changed`

Emitted when the text direction of a widget changes.

`hide`

Emitted when @widget is hidden.

`keynav-failed`

Emitted if keyboard navigation fails.

See WidgetExt::keynav_failed() for details.

`map`

Emitted when @widget is going to be mapped.

A widget is mapped when the widget is visible (which is controlled with visible) and all its parents up to the toplevel widget are also visible.

The ::map signal can be used to determine whether a widget will be drawn, for instance it can resume an animation that was stopped during the emission of unmap.

`mnemonic-activate`

Emitted when a widget is activated via a mnemonic.

The default handler for this signal activates @widget if @group_cycling is false, or just makes @widget grab focus if @group_cycling is true.

`move-focus`

Emitted when the focus is moved.

The ::move-focus signal is a keybinding signal.

The default bindings for this signal are Tab to move forward, and Shift+Tab to move backward.

Action

Emitted when the widgets tooltip is about to be shown.

This happens when the has-tooltip property is true and the hover timeout has expired with the cursor hovering “above” @widget; or emitted when @widget got focus in keyboard mode.

Using the given coordinates, the signal handler should determine whether a tooltip should be shown for @widget. If this is the case true should be returned, false otherwise. Note that if @keyboard_mode is true, the values of @x and @y are undefined and should not be used.

The signal handler is free to manipulate @tooltip with the therefore destined function calls.

`realize`

Emitted when @widget is associated with a gdk::Surface.

This means that WidgetExt::realize() has been called or the widget has been mapped (that is, it is going to be drawn).

`show`

Emitted when @widget is shown.

`state-flags-changed`

Emitted when the widget state changes.

See WidgetExt::state_flags().

`unmap`

Emitted when @widget is going to be unmapped.

A widget is unmapped when either it or any of its parents up to the toplevel widget have been set as hidden.

As ::unmap indicates that a widget will not be shown any longer, it can be used to, for example, stop an animation on the widget.

`unrealize`

Emitted when the gdk::Surface associated with @widget is destroyed.

This means that WidgetExt::unrealize() has been called or the widget has been unmapped (that is, it is going to be hidden).

Implements

WidgetExt, glib::ObjectExt, AccessibleExt, BuildableExt, ConstraintTargetExt, AccessibleRangeExt, OrientableExt, WidgetExtManual, AccessibleExtManual

Struct gtk4::LevelBar

Widget

Accessible

Orientable

Widget

Implementations§

impl LevelBar

pub fn new() -> LevelBar

pub fn for_interval(min_value: f64, max_value: f64) -> LevelBar

pub fn builder() -> LevelBarBuilder

pub fn add_offset_value(&self, name: &str, value: f64)

pub fn is_inverted(&self) -> bool

pub fn max_value(&self) -> f64

pub fn min_value(&self) -> f64

pub fn mode(&self) -> LevelBarMode

pub fn offset_value(&self, name: Option<&str>) -> Option<f64>

pub fn value(&self) -> f64

pub fn remove_offset_value(&self, name: Option<&str>)

pub fn set_inverted(&self, inverted: bool)

pub fn set_max_value(&self, value: f64)

pub fn set_min_value(&self, value: f64)

pub fn set_mode(&self, mode: LevelBarMode)

pub fn set_value(&self, value: f64)

pub fn connect_offset_changed<F: Fn(&Self, &str) + 'static>( &self, detail: Option<&str>, f: F ) -> SignalHandlerId

pub fn connect_inverted_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

pub fn connect_max_value_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

pub fn connect_min_value_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

pub fn connect_mode_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

pub fn connect_value_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

Trait Implementations§

impl Clone for LevelBar

fn clone(&self) -> Self

fn clone_from(&mut self, source: &Self)

impl Debug for LevelBar

fn fmt(&self, f: &mut Formatter<'_>) -> Result

impl Default for LevelBar

fn default() -> Self

impl Display for LevelBar

fn fmt(&self, f: &mut Formatter<'_>) -> Result

impl HasParamSpec for LevelBar

type ParamSpec = ParamSpecObject

type SetValue = LevelBar

type BuilderFn = fn(_: &str) -> ParamSpecObjectBuilder<'_, LevelBar>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for LevelBar

fn hash<H>(&self, state: &mut H)where H: Hasher,

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

impl Ord for LevelBar

fn cmp(&self, other: &Self) -> Ordering

fn max(self, other: Self) -> Selfwhere Self: Sized,

fn min(self, other: Self) -> Selfwhere Self: Sized,

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

impl ParentClassIs for LevelBar

type Parent = Widget

impl<OT: ObjectType> PartialEq<OT> for LevelBar

fn eq(&self, other: &OT) -> bool

fn ne(&self, other: &Rhs) -> bool

impl<OT: ObjectType> PartialOrd<OT> for LevelBar

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

fn lt(&self, other: &Rhs) -> bool