Scroll
Overview
In LVGL scrolling works very intuitively: if an object is outside its parent content area (the size without padding), the parent becomes scrollable and scrollbar(s) will appear. That's it.
Any object can be scrollable including lv_obj
, lv_image
,
lv_button
, lv_meter
, etc
The object can either be scrolled horizontally or vertically in one stroke; diagonal scrolling is not possible.
Scrollbar
Mode
Scrollbars are displayed according to a configured mode
. The
following mode
(s) exist:
LV_SCROLLBAR_MODE_OFF
: Never show the scrollbarsLV_SCROLLBAR_MODE_ON
: Always show the scrollbarsLV_SCROLLBAR_MODE_ACTIVE
: Show scroll bars while an object is being scrolledLV_SCROLLBAR_MODE_AUTO
: Show scroll bars when the content is large enough to be scrolled
lv_obj_set_scrollbar_mode(obj, LV_SCROLLBAR_MODE_...)
sets the scrollbar mode on an object.
Styling
The scrollbars have their own dedicated part, called
LV_PART_SCROLLBAR
. For example a scrollbar can turn to red like
this:
static lv_style_t style_red;
lv_style_init(&style_red);
lv_style_set_bg_color(&style_red, lv_color_red());
...
lv_obj_add_style(obj, &style_red, LV_PART_SCROLLBAR);
An object goes to the LV_STATE_SCROLLED
state while it's being
scrolled. This allows adding different styles to the scrollbar or the
object itself when scrolled. This code makes the scrollbar blue when the
object is scrolled:
static lv_style_t style_blue;
lv_style_init(&style_blue);
lv_style_set_bg_color(&style_blue, lv_color_blue());
...
lv_obj_add_style(obj, &style_blue, LV_STATE_SCROLLED | LV_PART_SCROLLBAR);
If the base direction of the LV_PART_SCROLLBAR
is RTL
(LV_BASE_DIR_RTL
) the vertical scrollbar will be placed on the left.
Note that, the base_dir
style property is inherited. Therefore, it
can be set directly on the LV_PART_SCROLLBAR
part of an object or on
the object's or any parent's main part to make a scrollbar inherit the
base direction.
pad_left/right/top/bottom
sets the spacing around the scrollbars and
width
sets the scrollbar's width.
Events
The following events are related to scrolling:
LV_EVENT_SCROLL_BEGIN
: Scrolling begins. The event parameter isNULL
or anlv_anim_t *
with a scroll animation descriptor that can be modified if required.LV_EVENT_SCROLL_END
: Scrolling ends.LV_EVENT_SCROLL
: Scroll happened. Triggered on every position change. Scroll events
Basic example
TODO
Features of scrolling
Besides, managing "normal" scrolling there are many interesting and useful additional features.
Scrollable
It's possible to make an object non-scrollable with lv_obj_remove_flag(obj, LV_OBJ_FLAG_SCROLLABLE).
Non-scrollable objects can still propagate the scrolling (chain) to their parents.
The direction in which scrolling happens can be controlled by lv_obj_set_scroll_dir(obj, LV_DIR_...)
.
The following values are possible for the direction:
LV_DIR_TOP
: only scroll upLV_DIR_LEFT
: only scroll leftLV_DIR_BOTTOM
: only scroll downLV_DIR_RIGHT
: only scroll rightLV_DIR_HOR
: only scroll horizontallyLV_DIR_VER
: only scroll verticallyLV_DIR_ALL
: scroll any directions
OR-ed values are also possible. E.g. LV_DIR_TOP | LV_DIR_LEFT.
Scroll chain
If an object can't be scrolled further (e.g. its content has reached the bottom-most position) additional scrolling is propagated to its parent. If the parent can be scrolled in that direction than it will be scrolled instead. It continues propagating to the grandparent and grand-grandparents as well.
The propagation on scrolling is called "scroll chaining" and it can be
enabled/disabled with LV_OBJ_FLAG_SCROLL_CHAIN_HOR/VER
flag. If
chaining is disabled the propagation stops on the object and the
parent(s) won't be scrolled.
Scroll momentum
When the user scrolls an object and releases it, LVGL can emulate inertial momentum for the scrolling. It's like the object was thrown and scrolling slows down smoothly.
The scroll momentum can be enabled/disabled with the
LV_OBJ_FLAG_SCROLL_MOMENTUM
flag.
Elastic scroll
Normally an object can't be scrolled past the extremities of its content. That is the top side of the content can't be below the top side of the object.
However, with LV_OBJ_FLAG_SCROLL_ELASTIC
a fancy effect is added
when the user "over-scrolls" the content. The scrolling slows down, and
the content can be scrolled inside the object. When the object is
released the content scrolled in it will be animated back to the valid
position.
Snapping
The children of an object can be snapped according to specific rules
when scrolling ends. Children can be made snappable individually with
the LV_OBJ_FLAG_SNAPPABLE
flag.
An object can align snapped children in four ways:
LV_SCROLL_SNAP_NONE
: Snapping is disabled. (default)LV_SCROLL_SNAP_START
: Align the children to the left/top side of a scrolled objectLV_SCROLL_SNAP_END
: Align the children to the right/bottom side of a scrolled objectLV_SCROLL_SNAP_CENTER
: Align the children to the center of a scrolled object
Snap alignment is set with
lv_obj_set_scroll_snap_x/y(obj, LV_SCROLL_SNAP_...)
:
Under the hood the following happens:
User scrolls an object and releases the screen
LVGL calculates where the scroll would end considering scroll momentum
LVGL finds the nearest scroll point
LVGL scrolls to the snap point with an animation
Scroll one
The "scroll one" feature tells LVGL to allow scrolling only one
snappable child at a time. This requires making the children snappable
and setting a scroll snap alignment different from
LV_SCROLL_SNAP_NONE
.
This feature can be enabled by the LV_OBJ_FLAG_SCROLL_ONE
flag.
Scroll on focus
Imagine that there a lot of objects in a group that are on a scrollable object. Pressing the "Tab" button focuses the next object but it might be outside the visible area of the scrollable object. If the "scroll on focus" feature is enabled LVGL will automatically scroll objects to bring their children into view. The scrolling happens recursively therefore even nested scrollable objects are handled properly. The object will be scrolled into view even if it's on a different page of a tabview.
Scroll manually
The following API functions allow manual scrolling of objects:
lv_obj_scroll_by(obj, x, y, LV_ANIM_ON/OFF)
scroll byx
andy
valueslv_obj_scroll_to(obj, x, y, LV_ANIM_ON/OFF)
scroll to bring the given coordinate to the top left cornerlv_obj_scroll_to_x(obj, x, LV_ANIM_ON/OFF)
scroll to bring the given coordinate to the left sidelv_obj_scroll_to_y(obj, y, LV_ANIM_ON/OFF)
scroll to bring the given coordinate to the top side
From time to time you may need to retrieve the scroll position of an element, either to restore it later, or to display dynamically some elements according to the current scroll. Here is an example to see how to combine scroll event and store the scroll top position.
static int scroll_value = 0;
static void store_scroll_value_event_cb(lv_event_t* e) {
lv_obj_t* screen = lv_event_get_target(e);
scroll_value = lv_obj_get_scroll_top(screen);
printf("%d pixels are scrolled out on the top\n", scroll_value);
}
lv_obj_t* container = lv_obj_create(NULL);
lv_obj_add_event_cb(container, store_scroll_value_event_cb, LV_EVENT_SCROLL, NULL);
Scroll coordinates can be retrieved from different axes with these functions:
lv_obj_get_scroll_x(obj)
Get thex
coordinate of objectlv_obj_get_scroll_y(obj)
Get they
coordinate of objectlv_obj_get_scroll_top(obj)
Get the scroll coordinate from the toplv_obj_get_scroll_bottom(obj)
Get the scroll coordinate from the bottomlv_obj_get_scroll_left(obj)
Get the scroll coordinate from the leftlv_obj_get_scroll_right(obj)
Get the scroll coordinate from the right
Self size
Self size is a property of an object. Normally, the user shouldn't use this parameter but if a custom widget is created it might be useful.
In short, self size establishes the size of an object's content. To understand it better take the example of a table. Let's say it has 10 rows each with 50 px height. So the total height of the content is 500 px. In other words the "self height" is 500 px. If the user sets only 200 px height for the table LVGL will see that the self size is larger and make the table scrollable.
This means not only the children can make an object scrollable but a larger self size will too.
LVGL uses the LV_EVENT_GET_SELF_SIZE
event to get the self size of
an object. Here is an example to see how to handle the event:
if(event_code == LV_EVENT_GET_SELF_SIZE) {
lv_point_t * p = lv_event_get_param(e);
//If x or y < 0 then it doesn't need to be calculated now
if(p->x >= 0) {
p->x = 200; //Set or calculate the self width
}
if(p->y >= 0) {
p->y = 50; //Set or calculate the self height
}
}
Examples
Nested scrolling
C code
View on GitHub#include "../lv_examples.h"
#if LV_BUILD_EXAMPLES
/**
* Demonstrate how scrolling appears automatically
*/
void lv_example_scroll_1(void)
{
/*Create an object with the new style*/
lv_obj_t * panel = lv_obj_create(lv_screen_active());
lv_obj_set_size(panel, 200, 200);
lv_obj_center(panel);
lv_obj_t * child;
lv_obj_t * label;
child = lv_obj_create(panel);
lv_obj_set_pos(child, 0, 0);
lv_obj_set_size(child, 70, 70);
label = lv_label_create(child);
lv_label_set_text(label, "Zero");
lv_obj_center(label);
child = lv_obj_create(panel);
lv_obj_set_pos(child, 160, 80);
lv_obj_set_size(child, 80, 80);
lv_obj_t * child2 = lv_button_create(child);
lv_obj_set_size(child2, 100, 50);
label = lv_label_create(child2);
lv_label_set_text(label, "Right");
lv_obj_center(label);
child = lv_obj_create(panel);
lv_obj_set_pos(child, 40, 160);
lv_obj_set_size(child, 100, 70);
label = lv_label_create(child);
lv_label_set_text(label, "Bottom");
lv_obj_center(label);
}
#endif
Snapping
C code
View on GitHub#include "../lv_examples.h"
#if LV_BUILD_EXAMPLES && LV_USE_FLEX
static void sw_event_cb(lv_event_t * e)
{
lv_event_code_t code = lv_event_get_code(e);
lv_obj_t * sw = lv_event_get_target(e);
if(code == LV_EVENT_VALUE_CHANGED) {
lv_obj_t * list = lv_event_get_user_data(e);
if(lv_obj_has_state(sw, LV_STATE_CHECKED)) lv_obj_add_flag(list, LV_OBJ_FLAG_SCROLL_ONE);
else lv_obj_remove_flag(list, LV_OBJ_FLAG_SCROLL_ONE);
}
}
/**
* Show an example to scroll snap
*/
void lv_example_scroll_2(void)
{
lv_obj_t * panel = lv_obj_create(lv_screen_active());
lv_obj_set_size(panel, 280, 120);
lv_obj_set_scroll_snap_x(panel, LV_SCROLL_SNAP_CENTER);
lv_obj_set_flex_flow(panel, LV_FLEX_FLOW_ROW);
lv_obj_align(panel, LV_ALIGN_CENTER, 0, 20);
uint32_t i;
for(i = 0; i < 10; i++) {
lv_obj_t * btn = lv_button_create(panel);
lv_obj_set_size(btn, 150, lv_pct(100));
lv_obj_t * label = lv_label_create(btn);
if(i == 3) {
lv_label_set_text_fmt(label, "Panel %"LV_PRIu32"\nno snap", i);
lv_obj_remove_flag(btn, LV_OBJ_FLAG_SNAPPABLE);
}
else {
lv_label_set_text_fmt(label, "Panel %"LV_PRIu32, i);
}
lv_obj_center(label);
}
lv_obj_update_snap(panel, LV_ANIM_ON);
#if LV_USE_SWITCH
/*Switch between "One scroll" and "Normal scroll" mode*/
lv_obj_t * sw = lv_switch_create(lv_screen_active());
lv_obj_align(sw, LV_ALIGN_TOP_RIGHT, -20, 10);
lv_obj_add_event_cb(sw, sw_event_cb, LV_EVENT_ALL, panel);
lv_obj_t * label = lv_label_create(lv_screen_active());
lv_label_set_text(label, "One scroll");
lv_obj_align_to(label, sw, LV_ALIGN_OUT_BOTTOM_MID, 0, 5);
#endif
}
#endif
Styling the scrollbars
C code
View on GitHub#include "../lv_examples.h"
#if LV_BUILD_EXAMPLES && LV_USE_LIST
/**
* Styling the scrollbars
*/
void lv_example_scroll_4(void)
{
lv_obj_t * obj = lv_obj_create(lv_screen_active());
lv_obj_set_size(obj, 200, 100);
lv_obj_center(obj);
lv_obj_t * label = lv_label_create(obj);
lv_label_set_text(label,
"Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n"
"Etiam dictum, tortor vestibulum lacinia laoreet, mi neque consectetur neque, vel mattis odio dolor egestas ligula. \n"
"Sed vestibulum sapien nulla, id convallis ex porttitor nec. \n"
"Duis et massa eu libero accumsan faucibus a in arcu. \n"
"Ut pulvinar odio lorem, vel tempus turpis condimentum quis. Nam consectetur condimentum sem in auctor. \n"
"Sed nisl augue, venenatis in blandit et, gravida ac tortor. \n"
"Etiam dapibus elementum suscipit. \n"
"Proin mollis sollicitudin convallis. \n"
"Integer dapibus tempus arcu nec viverra. \n"
"Donec molestie nulla enim, eu interdum velit placerat quis. \n"
"Donec id efficitur risus, at molestie turpis. \n"
"Suspendisse vestibulum consectetur nunc ut commodo. \n"
"Fusce molestie rhoncus nisi sit amet tincidunt. \n"
"Suspendisse a nunc ut magna ornare volutpat.");
/*Remove the style of scrollbar to have clean start*/
lv_obj_remove_style(obj, NULL, LV_PART_SCROLLBAR | LV_STATE_ANY);
/*Create a transition the animate the some properties on state change*/
static const lv_style_prop_t props[] = {LV_STYLE_BG_OPA, LV_STYLE_WIDTH, 0};
static lv_style_transition_dsc_t trans;
lv_style_transition_dsc_init(&trans, props, lv_anim_path_linear, 200, 0, NULL);
/*Create a style for the scrollbars*/
static lv_style_t style;
lv_style_init(&style);
lv_style_set_width(&style, 4); /*Width of the scrollbar*/
lv_style_set_pad_right(&style, 5); /*Space from the parallel side*/
lv_style_set_pad_top(&style, 5); /*Space from the perpendicular side*/
lv_style_set_radius(&style, 2);
lv_style_set_bg_opa(&style, LV_OPA_70);
lv_style_set_bg_color(&style, lv_palette_main(LV_PALETTE_BLUE));
lv_style_set_border_color(&style, lv_palette_darken(LV_PALETTE_BLUE, 3));
lv_style_set_border_width(&style, 2);
lv_style_set_shadow_width(&style, 8);
lv_style_set_shadow_spread(&style, 2);
lv_style_set_shadow_color(&style, lv_palette_darken(LV_PALETTE_BLUE, 1));
lv_style_set_transition(&style, &trans);
/*Make the scrollbars wider and use 100% opacity when scrolled*/
static lv_style_t style_scrolled;
lv_style_init(&style_scrolled);
lv_style_set_width(&style_scrolled, 8);
lv_style_set_bg_opa(&style_scrolled, LV_OPA_COVER);
lv_obj_add_style(obj, &style, LV_PART_SCROLLBAR);
lv_obj_add_style(obj, &style_scrolled, LV_PART_SCROLLBAR | LV_STATE_SCROLLED);
}
#endif
Right to left scrolling
C code
View on GitHub#include "../lv_examples.h"
#if LV_BUILD_EXAMPLES && LV_FONT_DEJAVU_16_PERSIAN_HEBREW
/**
* Scrolling with Right To Left base direction
*/
void lv_example_scroll_5(void)
{
lv_obj_t * obj = lv_obj_create(lv_screen_active());
lv_obj_set_style_base_dir(obj, LV_BASE_DIR_RTL, 0);
lv_obj_set_size(obj, 200, 100);
lv_obj_center(obj);
lv_obj_t * label = lv_label_create(obj);
lv_label_set_text(label,
"میکروکُنترولر (به انگلیسی: Microcontroller) گونهای ریزپردازنده است که دارای حافظهٔ دسترسی تصادفی (RAM) و حافظهٔ فقطخواندنی (ROM)، تایمر، پورتهای ورودی و خروجی (I/O) و درگاه ترتیبی (Serial Port پورت سریال)، درون خود تراشه است، و میتواند به تنهایی ابزارهای دیگر را کنترل کند. به عبارت دیگر یک میکروکنترلر، مدار مجتمع کوچکی است که از یک CPU کوچک و اجزای دیگری مانند تایمر، درگاههای ورودی و خروجی آنالوگ و دیجیتال و حافظه تشکیل شدهاست.");
lv_obj_set_width(label, 400);
lv_obj_set_style_text_font(label, &lv_font_dejavu_16_persian_hebrew, 0);
}
#endif
Translate on scroll
C code
View on GitHub#include "../lv_examples.h"
#if LV_BUILD_EXAMPLES && LV_USE_FLEX
static void scroll_event_cb(lv_event_t * e)
{
lv_obj_t * cont = lv_event_get_target(e);
lv_area_t cont_a;
lv_obj_get_coords(cont, &cont_a);
int32_t cont_y_center = cont_a.y1 + lv_area_get_height(&cont_a) / 2;
int32_t r = lv_obj_get_height(cont) * 7 / 10;
uint32_t i;
uint32_t child_cnt = lv_obj_get_child_count(cont);
for(i = 0; i < child_cnt; i++) {
lv_obj_t * child = lv_obj_get_child(cont, i);
lv_area_t child_a;
lv_obj_get_coords(child, &child_a);
int32_t child_y_center = child_a.y1 + lv_area_get_height(&child_a) / 2;
int32_t diff_y = child_y_center - cont_y_center;
diff_y = LV_ABS(diff_y);
/*Get the x of diff_y on a circle.*/
int32_t x;
/*If diff_y is out of the circle use the last point of the circle (the radius)*/
if(diff_y >= r) {
x = r;
}
else {
/*Use Pythagoras theorem to get x from radius and y*/
uint32_t x_sqr = r * r - diff_y * diff_y;
lv_sqrt_res_t res;
lv_sqrt(x_sqr, &res, 0x8000); /*Use lvgl's built in sqrt root function*/
x = r - res.i;
}
/*Translate the item by the calculated X coordinate*/
lv_obj_set_style_translate_x(child, x, 0);
/*Use some opacity with larger translations*/
lv_opa_t opa = lv_map(x, 0, r, LV_OPA_TRANSP, LV_OPA_COVER);
lv_obj_set_style_opa(child, LV_OPA_COVER - opa, 0);
}
}
/**
* Translate the object as they scroll
*/
void lv_example_scroll_6(void)
{
lv_obj_t * cont = lv_obj_create(lv_screen_active());
lv_obj_set_size(cont, 200, 200);
lv_obj_center(cont);
lv_obj_set_flex_flow(cont, LV_FLEX_FLOW_COLUMN);
lv_obj_add_event_cb(cont, scroll_event_cb, LV_EVENT_SCROLL, NULL);
lv_obj_set_style_radius(cont, LV_RADIUS_CIRCLE, 0);
lv_obj_set_style_clip_corner(cont, true, 0);
lv_obj_set_scroll_dir(cont, LV_DIR_VER);
lv_obj_set_scroll_snap_y(cont, LV_SCROLL_SNAP_CENTER);
lv_obj_set_scrollbar_mode(cont, LV_SCROLLBAR_MODE_OFF);
uint32_t i;
for(i = 0; i < 20; i++) {
lv_obj_t * btn = lv_button_create(cont);
lv_obj_set_width(btn, lv_pct(100));
lv_obj_t * label = lv_label_create(btn);
lv_label_set_text_fmt(label, "Button %"LV_PRIu32, i);
}
/*Update the buttons position manually for first*/
lv_obj_send_event(cont, LV_EVENT_SCROLL, NULL);
/*Be sure the fist button is in the middle*/
lv_obj_scroll_to_view(lv_obj_get_child(cont, 0), LV_ANIM_OFF);
}
#endif