lv_obj_scroll.h

Typedefs

typedef _lv_scrollbar_mode_t lv_scrollbar_mode_t
typedef _lv_scroll_snap_t lv_scroll_snap_t

Enums

enum _lv_scrollbar_mode_t

Scrollbar modes: shows when should the scrollbars be visible

Values:

enumerator LV_SCROLLBAR_MODE_OFF

Never show scrollbars

enumerator LV_SCROLLBAR_MODE_ON

Always show scrollbars

enumerator LV_SCROLLBAR_MODE_ACTIVE

Show scroll bars when object is being scrolled

enumerator LV_SCROLLBAR_MODE_AUTO

Show scroll bars when the content is large enough to be scrolled

enum _lv_scroll_snap_t

Scroll span align options. Tells where to align the snappable children when scroll stops.

Values:

enumerator LV_SCROLL_SNAP_NONE

Do not align, leave where it is

enumerator LV_SCROLL_SNAP_START

Align to the left/top

enumerator LV_SCROLL_SNAP_END

Align to the right/bottom

enumerator LV_SCROLL_SNAP_CENTER

Align to the center

Functions

void lv_obj_set_scrollbar_mode(lv_obj_t *obj, lv_scrollbar_mode_t mode)

Set how the scrollbars should behave.

Parameters:

  • obj -- pointer to an object

  • mode -- LV_SCROLL_MODE_ON/OFF/AUTO/ACTIVE

void lv_obj_set_scroll_dir(lv_obj_t *obj, lv_dir_t dir)

Set the object in which directions can be scrolled

Parameters:

  • obj -- pointer to an object

  • dir -- the allow scroll directions. An element or OR-ed values of lv_dir_t

void lv_obj_set_scroll_snap_x(lv_obj_t *obj, lv_scroll_snap_t align)

Set where to snap the children when scrolling ends horizontally

Parameters:

  • obj -- pointer to an object

  • align -- the snap align to set from lv_scroll_snap_t

void lv_obj_set_scroll_snap_y(lv_obj_t *obj, lv_scroll_snap_t align)

Set where to snap the children when scrolling ends vertically

Parameters:

  • obj -- pointer to an object

  • align -- the snap align to set from lv_scroll_snap_t

lv_scrollbar_mode_t lv_obj_get_scrollbar_mode(const lv_obj_t *obj)

Get the current scroll mode (when to hide the scrollbars)

Parameters:

obj -- pointer to an object

Returns:

the current scroll mode from lv_scrollbar_mode_t

lv_dir_t lv_obj_get_scroll_dir(const lv_obj_t *obj)

Get the object in which directions can be scrolled

Parameters:

  • obj -- pointer to an object

  • dir -- the allow scroll directions. An element or OR-ed values of lv_dir_t

lv_scroll_snap_t lv_obj_get_scroll_snap_x(const lv_obj_t *obj)

Get where to snap the children when scrolling ends horizontally

Parameters:

obj -- pointer to an object

Returns:

the current snap align from lv_scroll_snap_t

lv_scroll_snap_t lv_obj_get_scroll_snap_y(const lv_obj_t *obj)

Get where to snap the children when scrolling ends vertically

Parameters:

obj -- pointer to an object

Returns:

the current snap align from lv_scroll_snap_t

int32_t lv_obj_get_scroll_x(const lv_obj_t *obj)

Get current X scroll position.

Parameters:

obj -- pointer to an object

Returns:

the current scroll position from the left edge. If the object is not scrolled return 0 If scrolled return > 0 If scrolled in (elastic scroll) return < 0

int32_t lv_obj_get_scroll_y(const lv_obj_t *obj)

Get current Y scroll position.

Parameters:

obj -- pointer to an object

Returns:

the current scroll position from the top edge. If the object is not scrolled return 0 If scrolled return > 0 If scrolled inside return < 0

int32_t lv_obj_get_scroll_top(lv_obj_t *obj)

Return the height of the area above the object. That is the number of pixels the object can be scrolled down. Normally positive but can be negative when scrolled inside.

Parameters:

obj -- pointer to an object

Returns:

the scrollable area above the object in pixels

int32_t lv_obj_get_scroll_bottom(lv_obj_t *obj)

Return the height of the area below the object. That is the number of pixels the object can be scrolled down. Normally positive but can be negative when scrolled inside.

Parameters:

obj -- pointer to an object

Returns:

the scrollable area below the object in pixels

int32_t lv_obj_get_scroll_left(lv_obj_t *obj)

Return the width of the area on the left the object. That is the number of pixels the object can be scrolled down. Normally positive but can be negative when scrolled inside.

Parameters:

obj -- pointer to an object

Returns:

the scrollable area on the left the object in pixels

int32_t lv_obj_get_scroll_right(lv_obj_t *obj)

Return the width of the area on the right the object. That is the number of pixels the object can be scrolled down. Normally positive but can be negative when scrolled inside.

Parameters:

obj -- pointer to an object

Returns:

the scrollable area on the right the object in pixels

void lv_obj_get_scroll_end(lv_obj_t *obj, lv_point_t *end)

Get the X and Y coordinates where the scrolling will end for this object if a scrolling animation is in progress. If no scrolling animation, give the current x or y scroll position.

Parameters:

  • obj -- pointer to an object

  • end -- pointer to store the result

void lv_obj_scroll_by(lv_obj_t *obj, int32_t x, int32_t y, lv_anim_enable_t anim_en)

Scroll by a given amount of pixels

Note

> 0 value means scroll right/bottom (show the more content on the right/bottom)

Note

e.g. dy = -20 means scroll down 20 px

Parameters:

  • obj -- pointer to an object to scroll

  • x -- pixels to scroll horizontally

  • y -- pixels to scroll vertically

  • anim_en -- LV_ANIM_ON: scroll with animation; LV_ANIM_OFF: scroll immediately

void lv_obj_scroll_by_bounded(lv_obj_t *obj, int32_t dx, int32_t dy, lv_anim_enable_t anim_en)

Scroll by a given amount of pixels. dx and dy will be limited internally to allow scrolling only on the content area.

Note

e.g. dy = -20 means scroll down 20 px

Parameters:

  • obj -- pointer to an object to scroll

  • dx -- pixels to scroll horizontally

  • dy -- pixels to scroll vertically

  • anim_en -- LV_ANIM_ON: scroll with animation; LV_ANIM_OFF: scroll immediately

void lv_obj_scroll_to(lv_obj_t *obj, int32_t x, int32_t y, lv_anim_enable_t anim_en)

Scroll to a given coordinate on an object. x and y will be limited internally to allow scrolling only on the content area.

Parameters:

  • obj -- pointer to an object to scroll

  • x -- pixels to scroll horizontally

  • y -- pixels to scroll vertically

  • anim_en -- LV_ANIM_ON: scroll with animation; LV_ANIM_OFF: scroll immediately

void lv_obj_scroll_to_x(lv_obj_t *obj, int32_t x, lv_anim_enable_t anim_en)

Scroll to a given X coordinate on an object. x will be limited internally to allow scrolling only on the content area.

Parameters:

  • obj -- pointer to an object to scroll

  • x -- pixels to scroll horizontally

  • anim_en -- LV_ANIM_ON: scroll with animation; LV_ANIM_OFF: scroll immediately

void lv_obj_scroll_to_y(lv_obj_t *obj, int32_t y, lv_anim_enable_t anim_en)

Scroll to a given Y coordinate on an object y will be limited internally to allow scrolling only on the content area.

Parameters:

  • obj -- pointer to an object to scroll

  • y -- pixels to scroll vertically

  • anim_en -- LV_ANIM_ON: scroll with animation; LV_ANIM_OFF: scroll immediately

void lv_obj_scroll_to_view(lv_obj_t *obj, lv_anim_enable_t anim_en)

Scroll to an object until it becomes visible on its parent

Parameters:

  • obj -- pointer to an object to scroll into view

  • anim_en -- LV_ANIM_ON: scroll with animation; LV_ANIM_OFF: scroll immediately

void lv_obj_scroll_to_view_recursive(lv_obj_t *obj, lv_anim_enable_t anim_en)

Scroll to an object until it becomes visible on its parent. Do the same on the parent's parent, and so on. Therefore the object will be scrolled into view even it has nested scrollable parents

Parameters:

  • obj -- pointer to an object to scroll into view

  • anim_en -- LV_ANIM_ON: scroll with animation; LV_ANIM_OFF: scroll immediately

lv_result_t _lv_obj_scroll_by_raw(lv_obj_t *obj, int32_t x, int32_t y)

Low level function to scroll by given x and y coordinates. LV_EVENT_SCROLL is sent.

Parameters:

  • obj -- pointer to an object to scroll

  • x -- pixels to scroll horizontally

  • y -- pixels to scroll vertically

Returns:

LV_RESULT_INVALID: to object was deleted in LV_EVENT_SCROLL; LV_RESULT_OK: if the object is still valid

bool lv_obj_is_scrolling(const lv_obj_t *obj)

Tell whether an object is being scrolled or not at this moment

Parameters:

obj -- pointer to an object

Returns:

true: obj is being scrolled

void lv_obj_update_snap(lv_obj_t *obj, lv_anim_enable_t anim_en)

Check the children of obj and scroll obj to fulfill the scroll_snap settings

Parameters:

  • obj -- an object whose children needs to checked and snapped

  • anim_en -- LV_ANIM_ON/OFF

void lv_obj_get_scrollbar_area(lv_obj_t *obj, lv_area_t *hor, lv_area_t *ver)

Get the area of the scrollbars

Parameters:

  • obj -- pointer to an object

  • hor -- pointer to store the area of the horizontal scrollbar

  • ver -- pointer to store the area of the vertical scrollbar

void lv_obj_scrollbar_invalidate(lv_obj_t *obj)

Invalidate the area of the scrollbars

Parameters:

obj -- pointer to an object

void lv_obj_readjust_scroll(lv_obj_t *obj, lv_anim_enable_t anim_en)

Checks if the content is scrolled "in" and adjusts it to a normal position.

Parameters:

  • obj -- pointer to an object

  • anim_en -- LV_ANIM_ON/OFF