Slider (lv_slider)

A Bar with a draggable knob the user moves to set the value. Horizontal or vertical.

Overview

The Slider looks like a Bar with a knob. Drag the knob to set the value. Like Bar, a Slider can be vertical or horizontal.

Value, range and orientation

Defaults: value = 0, range = [0..100], horizontal orientation, width/height roughly 2"/0.1" (scaled by LV_DPI_DEF).

• lv_slider_set_value(slider, v, LV_ANIM_ON/OFF) — animation length comes from the anim_time style.
• lv_slider_set_range(slider, min, max) — pass min > max to flip the drawing direction (e.g. 100..0 for a right-to-left fill).
• lv_slider_set_orientation(slider, LV_SLIDER_ORIENTATION_*) — AUTO/HORIZONTAL/VERTICAL. The default AUTO picks based on width/height.

Reversed direction

Swap min and max to reverse the fill direction without changing orientation — useful for right-to-left progress or top-down level meters.

Modes

The Slider can be in one of the following modes:

• LV_SLIDER_MODE_NORMAL A normal Slider as described above (default)
• LV_SLIDER_SYMMETRICAL Draw the indicator from the zero value to current value. Requires negative minimum range and positive maximum range.
• LV_SLIDER_RANGE Allows setting the start value as well by lv_slider_set_start_value(slider, new_value, LV_ANIM_ON/OFF). The start value must always be smaller than the end value.

The mode can be changed with lv_slider_set_mode(slider, LV_SLIDER_MODE_...)

Styling

• LV_PART_MAIN The background of the Slider. Uses the typical background style properties. padding makes the indicator smaller in the respective direction.
• LV_PART_INDICATOR The indicator that shows the current state of the Slider; also uses the typical background style properties.
• LV_PART_KNOB A rectangle (or circle) drawn at the current value; also uses the typical background style properties to describe the knob(s). By default, the knob is round (radius-style can modify this) with side length equal to the smaller dimension of the Slider. The knob can be made larger with the padding values. Padding values can be asymmetric as well.

Slider has three parts: LV_PART_MAIN (track), LV_PART_INDICATOR (filled portion), and LV_PART_KNOB. Each accepts the full background style stack — bg_color, bg_grad_color + bg_grad_dir for gradients, radius, border_*, outline_*, shadow_*, and pad_*. Attach named styles with selector="main", selector="indicator", or selector="knob". Combine part and state to get interactive feedback, e.g. selector="pressed|knob" to highlight the knob only while it is being dragged. Local style_* props on the <lv_slider> tag target MAIN.

Image indicator

Setting bg_image_src on a part adds a bitmap on top of the solid fill, clipped to the part's current bounds. The track image shows the full width at all times; the indicator image is revealed left-to-right as the knob moves. Assign different bitmaps to LV_PART_MAIN and LV_PART_INDICATOR to texture both independently.

• lv_obj_set_style_bg_image_src(slider, src, selector)

Knob-only mode

Normally, the Slider can be adjusted either by dragging the knob, or by clicking on the Slider bar. In the latter case the knob moves to the point clicked and the Slider value changes accordingly. In some cases it is desirable to set the Slider to react on dragging the knob only. This feature is enabled by adding the LV_OBJ_FLAG_ADV_HITTEST flag: lv_obj_add_flag(slider, LV_OBJ_FLAG_ADV_HITTEST).

Any extended click area (set by lv_obj_set_ext_click_area(slider, value)) increases the knob's click area.

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 Slider binds its integer value to a Subject. The link is two-way: the end user's drag updates the subject, and any application-side write into the subject moves the knob. Integer and float subjects are both supported.

• lv_slider_bind_value(slider, 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).

A Slider's value can also drive another widget's state via the generic bind_state_if_* helpers — handy for guards like "disable submit when the value exceeds a threshold".

Events

• LV_EVENT_VALUE_CHANGED Sent while the Slider is being dragged or changed with keys. The event is sent continuously while the Slider is being dragged.
• LV_EVENT_RELEASED Sent once when Slider is released.

To update another widget on every value change without an event callback, bind both widgets to the same Subject — see the Data binding section above.

Learn more about Events emitted by all Widgets.

Keys

• LV_KEY_UP/RIGHT Increment Slider's value by 1.
• LV_KEY_DOWN/LEFT Decrement Slider's value by 1.

Learn more about Keys.