Overview

The Page consist of two containers on each other: the bottom is the background (or base) and the top is the scrollable. If you create a child on the page it will be automatically moved to the scrollable container. If the scrollable container become greater then the background it can be scrolled by dragging (like the lists on smart phones).

By default the scrollable's auto fit attribute is enabled vertically so its height will increased to include all its children. The width of the scrollable is automatically adjusted to the background width (minus the background's horizontal padding).

The background object can be referenced as the page itself like: lv_obj_set_width(page, 100).

The scrollable object can be get with: lv_page_get_scrl(page).

Scrollbars can be shown according to four policies:

  • LV_SB_MODE_OFF: Never show scrollbars
  • LV_SB_MODE_ON: Always show scrollbars
  • LV_SB_MODE_DRAG: Show scrollbars when page is being dragged
  • LV_SB_MODE_AUTO: Show scrollbars when the scrollable container is large enough to be scrolled

You can set scroll bar show policy by: lv_page_set_sb_mode(page, SB_MODE). The default value is LV_PAGE_SB_MODE_ON;

You can glue a children to the page. In this case you can scroll the page with dragging the child object. It can be enabled by the lv_page_glue_obj(child, true)

You can focus to an object on a page with: lv_page_focus(page, child, anim_time). It will moves the scrollable container to show a child. If the last parameter is not zero then the page will move with an animation.

A release and a press action can be assigned to the Page with lv_page_set_rel_action(page, my_rel_action) and lv_page_set_pr_action(page, my_pr_action). The action can be triggered from the Background and the Scrollable object too.

There are functions to directly set/get the scrollable's attributes:

  • lv_page_set_scrl_fit()
  • lv_page_set_scrl_width()
  • lv_page_set_scrl_height()
  • lv_page_set_scrl_layout()

Style usage

Use lv_page_set_style(page, LV_PAGE_STYLE_..., &style) to set a new style for an element of the page:

  • LV_PAGE_STYLE_BG background's style which uses all style.body properties (default: lv_style_pretty_color)
  • LV_PAGE_STYLE_SCRL scrollable's style which uses all style.body properties (default: lv_style_pretty)
  • LV_PAGE_STYLE_SB scroll bar's style which uses all style.body properties. hor/ver* padding sets the scrollbars' padding respectively and the inner padding sets the scrollbar's width. (default: lv_style_pretty_color)

Notes

  • The background draws its border when the scrollable is drawn. It ensures that the page always will have closed shape even if the scrollable has the same color as the page's parent.
Example of Page in Littlev Graphics Library

						/*Create a scroll bar style*/
static lv_style_t style_sb;
lv_style_copy(&style_sb, &lv_style_plain);
style_sb.body.main_color = LV_COLOR_BLACK;
style_sb.body.grad_color = LV_COLOR_BLACK;
style_sb.body.border.color = LV_COLOR_WHITE;
style_sb.body.border.width = 1;
style_sb.body.border.opa = LV_OPA_70;
style_sb.body.radius = LV_RADIUS_CIRCLE;
style_sb.body.opa = LV_OPA_60;
style_sb.body.padding.hor = 3;          /*Horizontal padding on the right*/
style_sb.body.padding.inner = 8;        /*Scrollbar width*/

/*Create a page*/
lv_obj_t * page = lv_page_create(lv_scr_act(), NULL);
lv_obj_set_size(page, 150, 200);
lv_obj_align(page, NULL, LV_ALIGN_CENTER, 0, 0);
lv_page_set_style(page, LV_PAGE_STYLE_SB, &style_sb);           /*Set the scrollbar style*/
lv_page_set_sb_mode(page, LV_SB_MODE_AUTO);                     /*Show scroll bars is scrolling is possible*/

/*Create a label on the page*/
lv_obj_t * label = lv_label_create(page, NULL);
lv_label_set_long_mode(label, LV_LABEL_LONG_BREAK);             /*Automatically break long lines*/
lv_obj_set_width(label, lv_page_get_scrl_width(page));          /*Set the width. Lines will break here*/
lv_label_set_text(label, "Lorem ipsum dolor sit amet, consectetur adipiscing elit,\n"
                         "sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n"
                         "Ut enim ad minim veniam, quis nostrud exercitation ullamco\n"
                         "laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure\n"
                         "dolor in reprehenderit in voluptate velit esse cillum dolore\n"
                         "eu fugiat nulla pariatur.\n"
                         "Excepteur sint occaecat cupidatat non proident, sunt in culpa\n"
                         "qui officia deserunt mollit anim id est laborum.");

lv_obj_t *

lv_page_create

(lv_obj_t * par, lv_obj_t * copy);

Create a page objects

par pointer to an object, it will be the parent of the new page

copy pointer to a page object, if not NULL then the new object will be copied from it

return pointer to the created page

lv_obj_t *

lv_page_get_scrl

(lv_obj_t * page);

Get the scrollable object of a page

page pointer to a page object

return pointer to a container which is the scrollable part of the page

void

lv_page_set_rel_action

(lv_obj_t * page, lv_action_t rel_action);

Set a release action for the page

page pointer to a page object

rel_action a function to call when the page is released

void

lv_page_set_pr_action

(lv_obj_t * page, lv_action_t pr_action);

Set a press action for the page

page pointer to a page object

pr_action a function to call when the page is pressed

void

lv_page_set_sb_mode

(lv_obj_t * page, lv_sb_mode_t sb_mode);

Set the scroll bar mode on a page

page pointer to a page object

sb.mode the new mode from 'lv_page_sb.mode_t' enum

void

lv_page_set_scrl_fit

(lv_obj_t *page, bool hor_en, bool ver_en);

Set the fit attribute of the scrollable part of a page.
It means it can set its size automatically to involve all children.
(Can be set separately horizontally and vertically)

page pointer to a page object

hor_en true: enable horizontal fit

ver_en true: enable vertical fit

void

lv_page_set_scrl_width

(lv_obj_t *page, lv_coord_t w);

Set width of the scrollable part of a page

page pointer to a page object

w the new width of the scrollable (it ha no effect is horizontal fit is enabled)

void

lv_page_set_scrl_height

(lv_obj_t *page, lv_coord_t h);

Set height of the scrollable part of a page

page pointer to a page object

h the new height of the scrollable (it ha no effect is vertical fit is enabled)

void

lv_page_set_scrl_layout

(lv_obj_t * page, lv_layout_t layout);

Set the layout of the scrollable part of the page

page pointer to a page object

layout a layout from 'lv_cont_layout_t'

void

lv_page_set_style

(lv_obj_t *page, lv_page_style_t type, lv_style_t *style);

Set a style of a page

page pointer to a page object

type which style should be set

style pointer to a style

lv_sb_mode_t

lv_page_get_sb_mode

(lv_obj_t * page);

Set the scroll bar mode on a page

page pointer to a page object

return the mode from 'lv_page_sb_mode_t' enum

lv_coord_t

lv_page_get_scrl_width

(lv_obj_t *page);

Get width of the scrollable part of a page

page pointer to a page object

return the width of the scrollable

lv_coord_t

lv_page_get_scrl_height

(lv_obj_t *page);

Get height of the scrollable part of a page

page pointer to a page object

return the height of the scrollable

lv_layout_t

lv_page_get_scrl_layout

(lv_obj_t * page);

Get the layout of the scrollable part of a page

page pointer to page object

return the layout from 'lv_cont_layout_t'

bool

lv_page_get_scrl_hor_fit

(lv_obj_t * page);

Get horizontal fit attribute of the scrollable part of a page

page pointer to a page object

return true: horizontal fit is enabled; false: disabled

bool

lv_page_get_scrl_fit_ver

(lv_obj_t * page);

Get vertical fit attribute of the scrollable part of a page

page pointer to a page object

return true: vertical fit is enabled; false: disabled

lv_style_t *

lv_page_get_style

(lv_obj_t *page, lv_page_style_t type);

Get a style of a page

page pointer to page object

type which style should be get

return style pointer to a style

void

lv_page_glue_obj

(lv_obj_t * obj, bool glue);

Glue the object to the page. After it the page can be moved (dragged) with this object too.

obj pointer to an object on a page

glue true: enable glue, false: disable glue

void

lv_page_focus

(lv_obj_t * page, lv_obj_t * obj, uint16_t anim_time);

Focus on an object. It ensures that the object will be visible on the page.

page pointer to a page object

obj pointer to an object to focus (must be on the page)

anim_time scroll animation time in milliseconds (0: no animation)

LittlevGL - Open-source Embedded GUI Library

LittlevGL is a free and open-source graphics library providing everything you need to create embedded GUI with easy-to-use graphical elements, beautiful visual effects and low memory footprint.

If you like LittlevGL, please
support its deveopment!


The founder of Littlev Graphics Library (LittlevGL) and related software modules is:
Gábor Kiss-Vámosi
All Rights Reserved ©  2018 Hungary