Slider (lv_slider)¶
Overview¶
The Slider object looks like a Bar supplemented with a knob. The knob can be dragged to set a value. Just like Bar, Slider can be vertical or horizontal.
Parts and Styles¶
LV_PART_MAIN
The background of the slider. Uses all 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 all the typical background style properties.LV_PART_KNOB
A rectangle (or circle) drawn at the current value. Also uses all the typical background properties to describe the knob(s). By default, the knob is square (with an optional corner radius) with side length equal to the smaller side of the slider. The knob can be made larger with thepadding
values. Padding values can be asymmetric too.
Usage¶
Value and range¶
To set an initial value use lv_slider_set_value(slider, new_value, LV_ANIM_ON/OFF)
. The animation time is set by the styles' anim_time
property.
To specify the range (min, max values), lv_slider_set_range(slider, min , max)
can be used.
Modes¶
The slider can be one of the following modes:
LV_SLIDER_MODE_NORMAL
A normal slider as described aboveLV_SLIDER_SYMMETRICAL
Draw the indicator form the zero value to current value. Requires negative minimum range and positive maximum range.LV_SLIDER_RANGE
Allows setting the start value too bylv_bar_set_start_value(bar, new_value, LV_ANIM_ON/OFF)
. The start value has to be always smaller than the end value.
The mode can be changed with lv_slider_set_mode(slider, LV_SLIDER_MODE_...)
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 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
: lv_obj_add_flag(slider, LV_OBJ_FLAG_ADV_HITTEST)
.
The extended click area (set by lv_obj_set_ext_click_area(slider, value)
) increases to knob's click area.
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 dragged and once when released. Uselv_slider_is_dragged
to determine whether the Slider is still being dragged or has just been released.LV_EVENT_DRAW_PART_BEGIN
andLV_EVENT_DRAW_PART_END
are sent for the following parts.LV_SLIDER_DRAW_PART_KNOB
The main (right) knob of the sliderpart
:LV_PART_KNOB
draw_area
: area of the indicatorrect_dsc
id
: 0
LV_SLIDER_DRAW_PART_KNOB
The left knob of the sliderpart
:LV_PART_KNOB
draw_area
: area of the indicatorrect_dsc
id
: 1
See the events of the Bar too.
Learn more about Events.
Keys¶
LV_KEY_UP/RIGHT
Increment the slider's value by 1LV_KEY_DOWN/LEFT
Decrement the slider's value by 1
Learn more about Keys.
Example¶
Simple Slider¶
C code
GitHub#include "../../lv_examples.h"
#if LV_USE_SLIDER && LV_BUILD_EXAMPLES
static void slider_event_cb(lv_event_t * e);
static lv_obj_t * slider_label;
/**
* A default slider with a label displaying the current value
*/
void lv_example_slider_1(void)
{
/*Create a slider in the center of the display*/
lv_obj_t * slider = lv_slider_create(lv_scr_act());
lv_obj_center(slider);
lv_obj_add_event_cb(slider, slider_event_cb, LV_EVENT_VALUE_CHANGED, NULL);
/*Create a label below the slider*/
slider_label = lv_label_create(lv_scr_act());
lv_label_set_text(slider_label, "0%");
lv_obj_align_to(slider_label, slider, LV_ALIGN_OUT_BOTTOM_MID, 0, 10);
}
static void slider_event_cb(lv_event_t * e)
{
lv_obj_t * slider = lv_event_get_target(e);
char buf[8];
lv_snprintf(buf, sizeof(buf), "%d%%", (int)lv_slider_get_value(slider));
lv_label_set_text(slider_label, buf);
lv_obj_align_to(slider_label, slider, LV_ALIGN_OUT_BOTTOM_MID, 0, 10);
}
#endif
#
# A default slider with a label displaying the current value
#
def slider_event_cb(e):
slider = e.get_target()
slider_label.set_text("{:d}%".format(slider.get_value()))
slider_label.align_to(slider, lv.ALIGN.OUT_BOTTOM_MID, 0, 10)
# Create a slider in the center of the display
slider = lv.slider(lv.scr_act())
slider.center()
slider.add_event_cb(slider_event_cb, lv.EVENT.VALUE_CHANGED, None)
# Create a label below the slider
slider_label = lv.label(lv.scr_act())
slider_label.set_text("0%")
slider_label.align_to(slider, lv.ALIGN.OUT_BOTTOM_MID, 0, 10)
Slider with custom style¶
C code
GitHub#include "../../lv_examples.h"
#if LV_USE_SLIDER && LV_BUILD_EXAMPLES
/**
* Show how to style a slider.
*/
void lv_example_slider_2(void)
{
/*Create a transition*/
static const lv_style_prop_t props[] = {LV_STYLE_BG_COLOR, 0};
static lv_style_transition_dsc_t transition_dsc;
lv_style_transition_dsc_init(&transition_dsc, props, lv_anim_path_linear, 300, 0, NULL);
static lv_style_t style_main;
static lv_style_t style_indicator;
static lv_style_t style_knob;
static lv_style_t style_pressed_color;
lv_style_init(&style_main);
lv_style_set_bg_opa(&style_main, LV_OPA_COVER);
lv_style_set_bg_color(&style_main, lv_color_hex3(0xbbb));
lv_style_set_radius(&style_main, LV_RADIUS_CIRCLE);
lv_style_set_pad_ver(&style_main, -2); /*Makes the indicator larger*/
lv_style_init(&style_indicator);
lv_style_set_bg_opa(&style_indicator, LV_OPA_COVER);
lv_style_set_bg_color(&style_indicator, lv_palette_main(LV_PALETTE_CYAN));
lv_style_set_radius(&style_indicator, LV_RADIUS_CIRCLE);
lv_style_set_transition(&style_indicator, &transition_dsc);
lv_style_init(&style_knob);
lv_style_set_bg_opa(&style_knob, LV_OPA_COVER);
lv_style_set_bg_color(&style_knob, lv_palette_main(LV_PALETTE_CYAN));
lv_style_set_border_color(&style_knob, lv_palette_darken(LV_PALETTE_CYAN, 3));
lv_style_set_border_width(&style_knob, 2);
lv_style_set_radius(&style_knob, LV_RADIUS_CIRCLE);
lv_style_set_pad_all(&style_knob, 6); /*Makes the knob larger*/
lv_style_set_transition(&style_knob, &transition_dsc);
lv_style_init(&style_pressed_color);
lv_style_set_bg_color(&style_pressed_color, lv_palette_darken(LV_PALETTE_CYAN, 2));
/*Create a slider and add the style*/
lv_obj_t * slider = lv_slider_create(lv_scr_act());
lv_obj_remove_style_all(slider); /*Remove the styles coming from the theme*/
lv_obj_add_style(slider, &style_main, LV_PART_MAIN);
lv_obj_add_style(slider, &style_indicator, LV_PART_INDICATOR);
lv_obj_add_style(slider, &style_pressed_color, LV_PART_INDICATOR | LV_STATE_PRESSED);
lv_obj_add_style(slider, &style_knob, LV_PART_KNOB);
lv_obj_add_style(slider, &style_pressed_color, LV_PART_KNOB | LV_STATE_PRESSED);
lv_obj_center(slider);
}
#endif
#
# Show how to style a slider.
#
# Create a transition
props = [lv.STYLE.BG_COLOR, 0]
transition_dsc = lv.style_transition_dsc_t()
transition_dsc.init(props, lv.anim_t.path_linear, 300, 0, None)
style_main = lv.style_t()
style_indicator = lv.style_t()
style_knob = lv.style_t()
style_pressed_color = lv.style_t()
style_main.init()
style_main.set_bg_opa(lv.OPA.COVER)
style_main.set_bg_color(lv.color_hex3(0xbbb))
style_main.set_radius(lv.RADIUS.CIRCLE)
style_main.set_pad_ver(-2) # Makes the indicator larger
style_indicator.init()
style_indicator.set_bg_opa(lv.OPA.COVER)
style_indicator.set_bg_color(lv.palette_main(lv.PALETTE.CYAN))
style_indicator.set_radius(lv.RADIUS.CIRCLE)
style_indicator.set_transition(transition_dsc)
style_knob.init()
style_knob.set_bg_opa(lv.OPA.COVER)
style_knob.set_bg_color(lv.palette_main(lv.PALETTE.CYAN))
style_knob.set_border_color(lv.palette_darken(lv.PALETTE.CYAN, 3))
style_knob.set_border_width(2)
style_knob.set_radius(lv.RADIUS.CIRCLE)
style_knob.set_pad_all(6) # Makes the knob larger
style_knob.set_transition(transition_dsc)
style_pressed_color.init()
style_pressed_color.set_bg_color(lv.palette_darken(lv.PALETTE.CYAN, 2))
# Create a slider and add the style
slider = lv.slider(lv.scr_act())
slider.remove_style_all() # Remove the styles coming from the theme
slider.add_style(style_main, lv.PART.MAIN)
slider.add_style(style_indicator, lv.PART.INDICATOR)
slider.add_style(style_pressed_color, lv.PART.INDICATOR | lv.STATE.PRESSED)
slider.add_style(style_knob, lv.PART.KNOB)
slider.add_style(style_pressed_color, lv.PART.KNOB | lv.STATE.PRESSED)
slider.center()
Slider with extended drawer¶
C code
GitHub#include "../../lv_examples.h"
#if LV_USE_SLIDER && LV_BUILD_EXAMPLES
static void slider_event_cb(lv_event_t * e);
/**
* Show the current value when the slider is pressed by extending the drawer
*
*/
void lv_example_slider_3(void)
{
/*Create a slider in the center of the display*/
lv_obj_t * slider;
slider = lv_slider_create(lv_scr_act());
lv_obj_center(slider);
lv_slider_set_mode(slider, LV_SLIDER_MODE_RANGE);
lv_slider_set_value(slider, 70, LV_ANIM_OFF);
lv_slider_set_left_value(slider, 20, LV_ANIM_OFF);
lv_obj_add_event_cb(slider, slider_event_cb, LV_EVENT_ALL, NULL);
lv_obj_refresh_ext_draw_size(slider);
}
static void slider_event_cb(lv_event_t * e)
{
lv_event_code_t code = lv_event_get_code(e);
lv_obj_t * obj = lv_event_get_target(e);
/*Provide some extra space for the value*/
if(code == LV_EVENT_REFR_EXT_DRAW_SIZE) {
lv_coord_t * size = lv_event_get_param(e);
*size = LV_MAX(*size, 50);
}
else if(code == LV_EVENT_DRAW_PART_END) {
lv_obj_draw_part_dsc_t * dsc = lv_event_get_param(e);
if(dsc->part == LV_PART_INDICATOR) {
char buf[16];
lv_snprintf(buf, sizeof(buf), "%d - %d", (int)lv_slider_get_left_value(obj), (int)lv_slider_get_value(obj));
lv_point_t label_size;
lv_txt_get_size(&label_size, buf, LV_FONT_DEFAULT, 0, 0, LV_COORD_MAX, 0);
lv_area_t label_area;
label_area.x1 = dsc->draw_area->x1 + lv_area_get_width(dsc->draw_area) / 2 - label_size.x / 2;
label_area.x2 = label_area.x1 + label_size.x;
label_area.y2 = dsc->draw_area->y1 - 10;
label_area.y1 = label_area.y2 - label_size.y;
lv_draw_label_dsc_t label_draw_dsc;
lv_draw_label_dsc_init(&label_draw_dsc);
lv_draw_label(dsc->draw_ctx, &label_draw_dsc, &label_area, buf, NULL);
}
}
}
#endif
def slider_event_cb(e):
code = e.get_code()
obj = e.get_target()
# Provide some extra space for the value
if code == lv.EVENT.REFR_EXT_DRAW_SIZE:
e.set_ext_draw_size(50)
elif code == lv.EVENT.DRAW_PART_END:
# print("DRAW_PART_END")
dsc = lv.obj_draw_part_dsc_t.__cast__(e.get_param())
# print(dsc)
if dsc.part == lv.PART.INDICATOR:
label_text = "{:d} - {:d}".format(obj.get_left_value(),slider.get_value())
label_size = lv.point_t()
lv.txt_get_size(label_size, label_text, lv.font_default(), 0, 0, lv.COORD.MAX, 0)
# print(label_size.x,label_size.y)
label_area = lv.area_t()
label_area.x1 = dsc.draw_area.x1 + dsc.draw_area.get_width() // 2 - label_size.x // 2
label_area.x2 = label_area.x1 + label_size.x
label_area.y2 = dsc.draw_area.y1 - 10
label_area.y1 = label_area.y2 - label_size.y
label_draw_dsc = lv.draw_label_dsc_t()
label_draw_dsc.init()
dsc.draw_ctx.label(label_draw_dsc, label_area, label_text, None)
#
# Show the current value when the slider if pressed by extending the drawer
#
#
#Create a slider in the center of the display
slider = lv.slider(lv.scr_act())
slider.center()
slider.set_mode(lv.slider.MODE.RANGE)
slider.set_value(70, lv.ANIM.OFF)
slider.set_left_value(20, lv.ANIM.OFF)
slider.add_event_cb(slider_event_cb, lv.EVENT.ALL, None)
slider.refresh_ext_draw_size()
API¶
Typedefs
-
typedef uint8_t lv_slider_mode_t¶
Enums
-
enum [anonymous]¶
Values:
-
enumerator LV_SLIDER_MODE_NORMAL¶
-
enumerator LV_SLIDER_MODE_SYMMETRICAL¶
-
enumerator LV_SLIDER_MODE_RANGE¶
-
enumerator LV_SLIDER_MODE_NORMAL¶
-
enum lv_slider_draw_part_type_t¶
type
field inlv_obj_draw_part_dsc_t
ifclass_p = lv_slider_class
Used inLV_EVENT_DRAW_PART_BEGIN
andLV_EVENT_DRAW_PART_END
Values:
-
enumerator LV_SLIDER_DRAW_PART_KNOB¶
The main (right) knob's rectangle
-
enumerator LV_SLIDER_DRAW_PART_KNOB_LEFT¶
The left knob's rectangle
-
enumerator LV_SLIDER_DRAW_PART_KNOB¶
Functions
-
lv_obj_t *lv_slider_create(lv_obj_t *parent)¶
Create a slider object
- Parameters
parent -- pointer to an object, it will be the parent of the new slider.
- Returns
pointer to the created slider
-
static inline void lv_slider_set_value(lv_obj_t *obj, int32_t value, lv_anim_enable_t anim)¶
Set a new value on the slider
- Parameters
obj -- pointer to a slider object
value -- the new value
anim -- LV_ANIM_ON: set the value with an animation; LV_ANIM_OFF: change the value immediately
-
static inline void lv_slider_set_left_value(lv_obj_t *obj, int32_t value, lv_anim_enable_t anim)¶
Set a new value for the left knob of a slider
- Parameters
obj -- pointer to a slider object
value -- new value
anim -- LV_ANIM_ON: set the value with an animation; LV_ANIM_OFF: change the value immediately
-
static inline void lv_slider_set_range(lv_obj_t *obj, int32_t min, int32_t max)¶
Set minimum and the maximum values of a bar
- Parameters
obj -- pointer to the slider object
min -- minimum value
max -- maximum value
-
static inline void lv_slider_set_mode(lv_obj_t *obj, lv_slider_mode_t mode)¶
Set the mode of slider.
- Parameters
obj -- pointer to a slider object
mode -- the mode of the slider. See ::lv_slider_mode_t
-
static inline int32_t lv_slider_get_value(const lv_obj_t *obj)¶
Get the value of the main knob of a slider
- Parameters
obj -- pointer to a slider object
- Returns
the value of the main knob of the slider
-
static inline int32_t lv_slider_get_left_value(const lv_obj_t *obj)¶
Get the value of the left knob of a slider
- Parameters
obj -- pointer to a slider object
- Returns
the value of the left knob of the slider
-
static inline int32_t lv_slider_get_min_value(const lv_obj_t *obj)¶
Get the minimum value of a slider
- Parameters
obj -- pointer to a slider object
- Returns
the minimum value of the slider
-
static inline int32_t lv_slider_get_max_value(const lv_obj_t *obj)¶
Get the maximum value of a slider
- Parameters
obj -- pointer to a slider object
- Returns
the maximum value of the slider
-
bool lv_slider_is_dragged(const lv_obj_t *obj)¶
Give the slider is being dragged or not
- Parameters
obj -- pointer to a slider object
- Returns
true: drag in progress false: not dragged
-
static inline lv_slider_mode_t lv_slider_get_mode(lv_obj_t *slider)¶
Get the mode of the slider.
- Parameters
obj -- pointer to a bar object
- Returns
see ::lv_slider_mode_t
Variables
-
const lv_obj_class_t lv_slider_class¶
-
struct lv_slider_t¶