Bar (lv_bar)

Non-interactive progress bar with a background and an indicator whose length shows the current value.

Overview

The Bar has a background and an indicator. The length of the indicator shows the current value.

Both the start and end of the indicator can be set. Moving the start away from the minimum value lets the indicator begin somewhere in the middle of the bar.

Orientation and size

Width and height pick orientation by default. Override with lv_bar_set_orientation(bar, LV_BAR_ORIENTATION_…) — AUTO, HORIZONTAL, or VERTICAL.

Value and range

• lv_bar_set_value(bar, v, LV_ANIM_ON/OFF) — set value; animation toggle is the last argument.
• lv_bar_set_range(bar, min, max) — default [0..100]. Pass min > max (e.g. 100..0) to flip the fill direction.

Modes

Set with lv_bar_set_mode(bar, LV_BAR_MODE_…):

• NORMAL — default; fills from min to value.
• SYMMETRICAL — fills from zero outward, so positive and negative values pull the indicator in opposite directions. Needs a range that crosses zero (e.g. [-100..100]).
• RANGE — fills between start and value. Set the start with lv_bar_set_start_value(bar, v, LV_ANIM_ON/OFF). Start must be ≤ end.

Styling

• LV_PART_MAIN The Bar's background. It uses the typical background style properties. Adding padding makes the indicator smaller or larger. The anim_time style property sets the animation time if the values set with LV_ANIM_ON.
• LV_PART_INDICATOR The Bar's indicator; also uses the typical background style properties.

Bar has two stylable parts: LV_PART_MAIN (the background track) and LV_PART_INDICATOR (the filled portion). Both accept the full background style stack: bg_color, bg_grad_color + bg_grad_dir for gradients, radius, border_*, shadow_*, and pad_*. Attach a named <style> with selector="main" or selector="indicator" to target a part, or set local style_* props on the <lv_bar> tag for one-off tweaks. Padding on MAIN shrinks the indicator inside the track.

Image indicator

Setting bg_image_src on a part replaces the solid fill with pixels sampled from a bitmap. The image is drawn from the left edge of the part and clipped to its current width, so as the bar value rises the indicator image is progressively revealed left-to-right. Assign different bitmaps to LV_PART_MAIN and LV_PART_INDICATOR to texture both the track and the active fill independently.

• lv_obj_set_style_bg_image_src(bar, src, selector)

Data binding

Data bindings connect a widget property to a piece of global data — a Subject. When the subject's value changes, every widget bound to it updates automatically; and an interactive widget can write back into the subject so other subscribers see the new value.

A Bar binds its value to a Subject. The link is one-way (Subject → Widget) because the bar isn't interactive — application-side writes into the subject update the bar's fill. Integer and float subjects are supported.

• lv_bar_bind_value(bar, subject)

To show the value live in a label next to the widget, attach a label and call lv_label_bind_text(label, subject, "%d") — the format string accepts any printf-style specifier (XML: bind_text + bind_text-fmt).