mirrors/lvgl
0
0
Fork 0
mirror of https://github.com/lvgl/lvgl.git synced 2024-11-23 01:33:59 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat(docs): scrolling doc proofread, edited and clarified... (#7170)

Browse Source
This commit is contained in:
Victor Wheeler 2024-11-17 14:22:14 -07:00 committed by GitHub
parent f4bd79c54d
commit 30c9f2c450
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 233 additions and 155 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

164
docs/details/base-widget/scroll.rst
View File

@ -23,10 +23,10 @@ Scrollbar
---------
Mode
^^^^
~~~~
Scrollbars are displayed according to a configured ``mode``. The
following ``mode``\ (s) exist:
Scrollbars are displayed according to the configured ``scrollbar-mode``. The
following modes are available:
- :cpp:enumerator:`LV_SCROLLBAR_MODE_OFF`: Never show the scrollbars
- :cpp:enumerator:`LV_SCROLLBAR_MODE_ON`: Always show the scrollbars
@ -36,10 +36,10 @@ following ``mode``\ (s) exist:
:cpp:expr:`lv_obj_set_scrollbar_mode(widget, LV_SCROLLBAR_MODE_...)` sets the scrollbar mode on a Widget.
Styling
^^^^^^^
~~~~~~~
The scrollbars have their own dedicated part, called
:cpp:enumerator:`LV_PART_SCROLLBAR`. For example a scrollbar can turn to red like
A Scrollbar is a dedicated part of a Widget, called
:cpp:enumerator:`LV_PART_SCROLLBAR`. For example, a scrollbar can turn to red like
this:
.. code-block:: c
@ -53,9 +53,9 @@ this:
lv_obj_add_style(widget, &style_red, LV_PART_SCROLLBAR);
A Widget goes to the :cpp:enumerator:`LV_STATE_SCROLLED` state while it's being
scrolled. This allows adding different styles to the scrollbar or the
Widget itself when scrolled. This code makes the scrollbar blue when the
Widget is scrolled:
scrolled. This allows adding different styles to the Widget that will be effective
while it is being scrolled. For example, this code makes the scrollbar blue while
the Widget is being scrolled:
.. code-block:: c
@ -70,9 +70,9 @@ Widget is scrolled:
If the base direction of the :cpp:enumerator:`LV_PART_SCROLLBAR` is RTL
(:c:macro:`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 :cpp:enumerator:`LV_PART_SCROLLBAR` part of a Widget or on
the Widget's or any parent's main part to make a scrollbar inherit the
base direction.
can be set directly on the :cpp:enumerator:`LV_PART_SCROLLBAR` part of a Widget, or
on the Widget's LV_PART_MAIN part, or that of any of its parents, 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.
@ -83,15 +83,18 @@ base direction.
Scrolling Events
----------------
The following events are related to scrolling:
The following events are emitted as part of scrolling:
- :cpp:enumerator:`LV_EVENT_SCROLL_BEGIN`: Scrolling begins. The event parameter is
``NULL`` or an ``lv_anim_t *`` with a scroll animation descriptor that can be modified if required.
- :cpp:enumerator:`LV_EVENT_SCROLL_END`: Scrolling ends.
- :cpp:enumerator:`LV_EVENT_SCROLL`: Scroll happened. Triggered on every position change. Scroll events
- :cpp:enumerator:`LV_EVENT_SCROLL_BEGIN`: Signals that scrolling has begun. The
event parameter is ``NULL`` or an ``lv_anim_t *`` with a scroll animation
descriptor that can be modified if required.
- :cpp:enumerator:`LV_EVENT_SCROLL_END`: Signals that scrolling has ended.
- :cpp:enumerator:`LV_EVENT_SCROLL`: Signals that the scrolling position changed;
triggered on every position change.
Features of scrolling
Features of Scrolling
*********************
Besides, managing "normal" scrolling there are many interesting and
@ -100,7 +103,7 @@ useful additional features.
Scrollable
----------
It's possible to make a Widget non-scrollable with
It is possible to make a Widget non-scrollable with
:cpp:expr:`lv_obj_remove_flag(widget, LV_OBJ_FLAG_SCROLLABLE)`.
Non-scrollable Widgets can still propagate the scrolling (chain) to
@ -109,7 +112,7 @@ their parents.
The direction in which scrolling happens can be controlled by
:cpp:expr:`lv_obj_set_scroll_dir(widget, LV_DIR_...)`.
The following values are possible for the direction:
The following values can be used for the direction:
- :cpp:enumerator:`LV_DIR_TOP`: only scroll up
- :cpp:enumerator:`LV_DIR_LEFT`: only scroll left
@ -121,14 +124,14 @@ The following values are possible for the direction:
OR-ed values are also possible. E.g. :cpp:expr:`LV_DIR_TOP | LV_DIR_LEFT`.
Scroll chain
------------
Scroll chaining
---------------
If a Widget can't be scrolled further (e.g. its content has reached the
bottom-most position) additional scrolling is propagated to its parent.
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.
instead. It continues propagating up the Widget's parent hierarchy up to
the :ref:`Screen <screens>`.
The propagation on scrolling is called "scroll chaining" and it can be
enabled/disabled with ``LV_OBJ_FLAG_SCROLL_CHAIN_HOR/VER`` flag. If
@ -139,23 +142,23 @@ Scroll momentum
---------------
When the user scrolls a Widget and releases it, LVGL can emulate
inertial momentum for the scrolling. It's like the Widget was thrown and
scrolling slows down smoothly.
inertial momentum for the scrolling. It's like the Widget was "thrown"
and scrolling slows down smoothly.
The scroll momentum can be enabled/disabled with the
Scroll momentum can be enabled/disabled with the
:cpp:enumerator:`LV_OBJ_FLAG_SCROLL_MOMENTUM` flag.
Elastic scroll
--------------
Normally a Widget 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 Widget.
content. That is, the top side of the content can't be below the top side
of the Widget, and vice versa for the bottom side.
However, with :cpp:enumerator:`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 Widget. When the Widget is
released the content scrolled in it will be animated back to the valid
released the content scrolled in it is animated back to the closest valid
position.
Snapping
@ -176,19 +179,19 @@ Snap alignment is set with
:cpp:expr:`lv_obj_set_scroll_snap_x(widget, LV_SCROLL_SNAP_...)` and
:cpp:expr:`lv_obj_set_scroll_snap_y(widget, LV_SCROLL_SNAP_...)`.
Under the hood the following happens:
This is what happens under the hood:
1. User scrolls a Widget and releases the screen
2. LVGL calculates where the scroll would end considering scroll momentum
3. LVGL finds the nearest scroll point
4. LVGL scrolls to the snap point with an animation
1. user scrolls and releases a Widget;
2. LVGL calculates where the scroll would end considering scroll momentum;
3. LVGL finds the nearest scroll point;
4. 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
and setting scroll snap alignment to something other than
:cpp:enumerator:`LV_SCROLL_SNAP_NONE`.
This feature can be enabled by the :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_ONE` flag.
@ -196,56 +199,67 @@ This feature can be enabled by the :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_ONE` flag
Scroll on focus
---------------
Imagine that there a lot of Widgets in a group that are on a scrollable
Widget. Pressing the "Tab" button focuses the next Widget but it might
Imagine that there are a lot of Widgets in a group that are on a scrollable
Widget. Pressing the "Tab" button moves focus to the next Widget but it might
be outside the visible area of the scrollable Widget. If the "scroll on
focus" feature is enabled LVGL will automatically scroll Widgets to
bring their children into view. The scrolling happens recursively
bring the child Widget with focus into view. The scrolling happens recursively
therefore even nested scrollable Widgets are handled properly. The
Widget will be scrolled into view even if it's on a different page of a
Widget will be scrolled into view even if it is on a different page of a
tabview.
Scroll manually
***************
The following API functions allow manual scrolling of Widgets:
Scrolling Programmatically
**************************
The following API functions allow programmatic scrolling of Widgets:
- ``lv_obj_scroll_by(widget, x, y, LV_ANIM_ON/OFF)`` scroll by ``x`` and ``y`` values
- ``lv_obj_scroll_to(widget, x, y, LV_ANIM_ON/OFF)`` scroll to bring the given coordinate to the top left corner
- ``lv_obj_scroll_to_x(widget, x, LV_ANIM_ON/OFF)`` scroll to bring the given coordinate to the left side
- ``lv_obj_scroll_to_y(widget, 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.
From time to time you may need to retrieve the *scroll position* of a
scrollable Widget, either to restore it later, or to dynamically display some
elements according to its current scroll position. Here is an example to illustrate
how to combine scroll event and store the scroll-top position.
.. code-block:: c
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);
static void store_scroll_top_value_event_cb(lv_event_t* e) {
lv_obj_t * scr = lv_event_get_target(e);
scroll_value = lv_obj_get_scroll_top(scr);
printf("%d pixels are scrolled above top edge of display.\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);
lv_obj_t * scr = lv_obj_create(NULL);
lv_obj_add_event_cb(scr, store_scroll_top_value_event_cb, LV_EVENT_SCROLL, NULL);
Scroll coordinates can be retrieved from different axes with these
functions:
Scroll coordinates can be retrieved from different axes with these functions:
- ``lv_obj_get_scroll_x(widget)`` Get the ``x`` coordinate of Widget
- ``lv_obj_get_scroll_y(widget)`` Get the ``y`` coordinate of Widget
- ``lv_obj_get_scroll_top(widget)`` Get the scroll coordinate from the top
- ``lv_obj_get_scroll_bottom(widget)`` Get the scroll coordinate from the bottom
- ``lv_obj_get_scroll_left(widget)`` Get the scroll coordinate from the left
- ``lv_obj_get_scroll_right(widget)`` Get the scroll coordinate from the right
- :cpp:expr:`lv_obj_get_scroll_x(widget)` Pixels scrolled past left edge of Widget's view window.
- :cpp:expr:`lv_obj_get_scroll_y(widget)` Pixels scrolled past top of Widget's view window.
- :cpp:expr:`lv_obj_get_scroll_top(widget)` Identical to :cpp:expr:`lv_obj_get_scroll_y(widget)`
- :cpp:expr:`lv_obj_get_scroll_bottom(widget)` Pixels scrolled past bottom of Widget's view window.
- :cpp:expr:`lv_obj_get_scroll_left(widget)` Identical to :cpp:expr:`lv_obj_get_scroll_x(widget)`.
- :cpp:expr:`lv_obj_get_scroll_right(widget)` Pixels scrolled past right edge of Widget's view window.
Setting scroll position can be done with these functions:
- :cpp:expr:`lv_obj_scroll_by(widget, dx, dy, anim_enable)` Scroll by given amount of pixels.
- :cpp:expr:`lv_obj_scroll_by_bounded(widget, dx, dy, animation_enable)` Scroll by given amount of pixels.
- :cpp:expr:`lv_obj_scroll_to(widget, x, y, animation_enable)` Scroll to given coordinate on Widget.
- :cpp:expr:`lv_obj_scroll_to_x(widget, x, animation_enable)` Scroll to X coordinate on Widget.
- :cpp:expr:`lv_obj_scroll_to_y(widget, y, animation_enable)` Scroll to Y coordinate on Widget.
- :cpp:expr:`lv_obj_scroll_to_view(widget, animation_enable)` Scroll ``obj``'s parent Widget until ``obj`` becomes visible.
- :cpp:expr:`lv_obj_scroll_to_view_recursive(widget, animation_enable)` Scroll ``obj``'s parent Widgets recursively until ``obj`` becomes visible.
Self size
Self Size
*********
Self size is a property of a Widget. Normally, the user shouldn't use
@ -266,22 +280,23 @@ a Widget. Here is an example to see how to handle the event:
.. code-block:: c
if(event_code == LV_EVENT_GET_SELF_SIZE) {
lv_point_t * p = lv_event_get_param(e);
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 self width. */
}
if(p->y >= 0) {
p->y = 50; /* Set or calculate self height. */
}
}
//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
}
}
.. _scroll_example:
Examples
********
@ -290,5 +305,6 @@ Examples
.. _scroll_api:
API
***

62
examples/scroll/lv_example_scroll_1.c
View File

@ -1,15 +1,54 @@
#include "../lv_examples.h"
#if LV_BUILD_EXAMPLES
static lv_obj_t * panel;
static lv_obj_t * save_button;
static lv_obj_t * restore_button;
static int saved_scroll_x;
static int saved_scroll_y;
static void scroll_update_cb(lv_event_t * e);
static void button_event_cb(lv_event_t * e);
static void scroll_update_cb(lv_event_t * e)
{
LV_UNUSED(e);
LV_LOG("scroll info: x:%3"LV_PRId32", y:%3"LV_PRId32", top:%3"LV_PRId32", "
"bottom:%3"LV_PRId32", left:%3"LV_PRId32", right:%3"LV_PRId32"\n",
lv_obj_get_scroll_x(panel),
lv_obj_get_scroll_y(panel),
lv_obj_get_scroll_top(panel),
lv_obj_get_scroll_bottom(panel),
lv_obj_get_scroll_left(panel),
lv_obj_get_scroll_right(panel)
);
}
static void button_event_cb(lv_event_t * e)
{
lv_obj_t * obj = lv_event_get_target_obj(e);
if(obj == save_button) {
saved_scroll_x = lv_obj_get_scroll_x(panel);
saved_scroll_y = lv_obj_get_scroll_y(panel);
}
else {
lv_obj_scroll_to(panel, saved_scroll_x, saved_scroll_y, LV_ANIM_ON);
}
}
/**
* 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_t * scr;
scr = lv_screen_active();
panel = lv_obj_create(scr);
lv_obj_set_size(panel, 200, 200);
lv_obj_center(panel);
lv_obj_align(panel, LV_ALIGN_CENTER, 44, 0);
lv_obj_t * child;
lv_obj_t * label;
@ -38,6 +77,25 @@ void lv_example_scroll_1(void)
label = lv_label_create(child);
lv_label_set_text(label, "Bottom");
lv_obj_center(label);
/* When LV_OBJ_FLAG_SCROLL_ELASTIC is cleared, scrolling does not go past edge bounaries. */
/* lv_obj_clear_flag(panel, LV_OBJ_FLAG_SCROLL_ELASTIC); */
/* Call `scroll_update_cb` while panel is being scrolled. */
lv_obj_add_event_cb(panel, scroll_update_cb, LV_EVENT_SCROLL, NULL);
/* Set up buttons that save and restore scroll position. */
save_button = lv_button_create(scr);
restore_button = lv_button_create(scr);
lv_obj_t * lbl;
lbl = lv_label_create(save_button);
lv_label_set_text_static(lbl, "Save");
lbl = lv_label_create(restore_button);
lv_label_set_text_static(lbl, "Restore");
lv_obj_align_to(save_button, panel, LV_ALIGN_OUT_LEFT_MID, -10, -20);
lv_obj_align_to(restore_button, panel, LV_ALIGN_OUT_LEFT_MID, -10, 20);
lv_obj_add_event_cb(save_button, button_event_cb, LV_EVENT_CLICKED, NULL);
lv_obj_add_event_cb(restore_button, button_event_cb, LV_EVENT_CLICKED, NULL);
}
#endif

162
src/core/lv_obj_scroll.h
View File

@ -31,7 +31,7 @@ extern "C" {
typedef enum {
LV_SCROLLBAR_MODE_OFF, /**< Never show scrollbars*/
LV_SCROLLBAR_MODE_ON, /**< Always show scrollbars*/
LV_SCROLLBAR_MODE_ACTIVE, /**< Show scroll bars when object is being scrolled*/
LV_SCROLLBAR_MODE_ACTIVE, /**< Show scroll bars when Widget is being scrolled*/
LV_SCROLLBAR_MODE_AUTO, /**< Show scroll bars when the content is large enough to be scrolled*/
} lv_scrollbar_mode_t;
@ -53,29 +53,29 @@ typedef enum {
/**
* Set how the scrollbars should behave.
* @param obj pointer to an object
* @param obj pointer to Widget
* @param mode LV_SCROLL_MODE_ON/OFF/AUTO/ACTIVE
*/
void lv_obj_set_scrollbar_mode(lv_obj_t * obj, lv_scrollbar_mode_t mode);
/**
* Set the object in which directions can be scrolled
* @param obj pointer to an object
* @param dir the allow scroll directions. An element or OR-ed values of `lv_dir_t`
* Set direction Widget can be scrolled
* @param obj pointer to Widget
* @param dir one or more bit-wise OR-ed values of `lv_dir_t` enumeration
*/
void lv_obj_set_scroll_dir(lv_obj_t * obj, lv_dir_t dir);
/**
* Set where to snap the children when scrolling ends horizontally
* @param obj pointer to an object
* @param align the snap align to set from `lv_scroll_snap_t`
* @param obj pointer to Widget
* @param align value from `lv_scroll_snap_t` enumeration
*/
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 vertically
* @param obj pointer to an object
* @param align the snap align to set from `lv_scroll_snap_t`
* @param obj pointer to Widget
* @param align value from `lv_scroll_snap_t` enumeration
*/
void lv_obj_set_scroll_snap_y(lv_obj_t * obj, lv_scroll_snap_t align);
@ -85,92 +85,97 @@ void lv_obj_set_scroll_snap_y(lv_obj_t * obj, lv_scroll_snap_t align);
/**
* Get the current scroll mode (when to hide the scrollbars)
* @param obj pointer to an object
* @param obj pointer to Widget
* @return the current scroll mode from `lv_scrollbar_mode_t`
*/
lv_scrollbar_mode_t lv_obj_get_scrollbar_mode(const lv_obj_t * obj);
/**
* Get the object in which directions can be scrolled
* @param obj pointer to an object
* Get directions Widget can be scrolled (set with `lv_obj_set_scroll_dir()`)
* @param obj pointer to Widget
* @return current scroll direction bit(s)
*/
lv_dir_t lv_obj_get_scroll_dir(const lv_obj_t * obj);
/**
* Get where to snap the children when scrolling ends horizontally
* @param obj pointer to an object
* @return the current snap align from `lv_scroll_snap_t`
* Get where to snap child Widgets when horizontal scrolling ends.
* @param obj pointer to Widget
* @return current snap value from `lv_scroll_snap_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 vertically
* @param obj pointer to an object
* @return the current snap align from `lv_scroll_snap_t`
* Get where to snap child Widgets when vertical scrolling ends.
* @param obj pointer to Widget
* @return current snap value from `lv_scroll_snap_t`
*/
lv_scroll_snap_t lv_obj_get_scroll_snap_y(const lv_obj_t * obj);
/**
* Get current X scroll position.
* @param obj pointer to an object
* @return 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
* Get current X scroll position. Identical to `lv_obj_get_scroll_left()`.
* @param obj pointer to scrollable container Widget
* @return current scroll position from left edge
* - If Widget is not scrolled return 0.
* - If scrolled return > 0.
* - If scrolled inside (elastic scroll) return < 0.
*/
int32_t lv_obj_get_scroll_x(const lv_obj_t * obj);
/**
* Get current Y scroll position.
* @param obj pointer to an object
* @return 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
* Get current Y scroll position. Identical to `lv_obj_get_scroll_top()`.
* @param obj pointer to scrollable container Widget
* @return current scroll position from top edge
* - If Widget is not scrolled return 0.
* - If scrolled return > 0.
* - If scrolled inside (elastic scroll) return < 0.
*/
int32_t lv_obj_get_scroll_y(const lv_obj_t * obj);
/**
* Return the height of the area above the object.
* That is the number of pixels the object can be scrolled up.
* Normally positive but can be negative when scrolled inside.
* @param obj pointer to an object
* @return the scrollable area above the object in pixels
* Number of pixels a scrollable container Widget can be scrolled down
* before its top edge appears. When LV_OBJ_FLAG_SCROLL_ELASTIC flag
* is set in Widget, this value can go negative while Widget is being
* dragged below its normal top-edge boundary.
* @param obj pointer to scrollable container Widget
* @return pixels Widget can be scrolled down before its top edge appears
*/
int32_t lv_obj_get_scroll_top(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.
* @param obj pointer to an object
* @return the scrollable area below the object in pixels
* Number of pixels a scrollable container Widget can be scrolled up
* before its bottom edge appears. When LV_OBJ_FLAG_SCROLL_ELASTIC flag
* is set in Widget, this value can go negative while Widget is being
* dragged above its normal bottom-edge boundary.
* @param obj pointer to scrollable container Widget
* @return pixels Widget can be scrolled up before its bottom edge appears
*/
int32_t lv_obj_get_scroll_bottom(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 left.
* Normally positive but can be negative when scrolled inside.
* @param obj pointer to an object
* @return the scrollable area on the left of the object in pixels
* Number of pixels a scrollable container Widget can be scrolled right
* before its left edge appears. When LV_OBJ_FLAG_SCROLL_ELASTIC flag
* is set in Widget, this value can go negative while Widget is being
* dragged farther right than its normal left-edge boundary.
* @param obj pointer to scrollable container Widget
* @return pixels Widget can be scrolled right before its left edge appears
*/
int32_t lv_obj_get_scroll_left(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 right.
* Normally positive but can be negative when scrolled inside.
* @param obj pointer to an object
* @return the scrollable area on the right of the object in pixels
* Number of pixels a scrollable container Widget can be scrolled left
* before its right edge appears. When LV_OBJ_FLAG_SCROLL_ELASTIC flag
* is set in Widget, this value can go negative while Widget is being
* dragged farther left than its normal right-edge boundary.
* @param obj pointer to scrollable container Widget
* @return pixels Widget can be scrolled left before its right edge appears
*/
int32_t lv_obj_get_scroll_right(lv_obj_t * obj);
/**
* Get the X and Y coordinates where the scrolling will end for this object if a scrolling animation is in progress.
* Get the X and Y coordinates where the scrolling will end for Widget if a scrolling animation is in progress.
* If no scrolling animation, give the current `x` or `y` scroll position.
* @param obj pointer to an object
* @param end pointer to store the result
* @param obj pointer to scrollable Widget
* @param end pointer to `lv_point_t` object in which to store result
*/
void lv_obj_get_scroll_end(lv_obj_t * obj, lv_point_t * end);
@ -179,20 +184,20 @@ void lv_obj_get_scroll_end(lv_obj_t * obj, lv_point_t * end);
*====================*/
/**
* Scroll by a given amount of pixels
* @param obj pointer to an object to scroll
* @param x pixels to scroll horizontally
* @param y pixels to scroll vertically
* Scroll by given amount of pixels.
* @param obj pointer to scrollable Widget to scroll
* @param dx pixels to scroll horizontally
* @param dy pixels to scroll vertically
* @param anim_en LV_ANIM_ON: scroll with animation; LV_ANIM_OFF: scroll immediately
* @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
*/
void lv_obj_scroll_by(lv_obj_t * obj, int32_t x, int32_t y, lv_anim_enable_t anim_en);
void lv_obj_scroll_by(lv_obj_t * obj, int32_t dx, int32_t dy, lv_anim_enable_t anim_en);
/**
* Scroll by a given amount of pixels.
* Scroll by given amount of pixels.
* `dx` and `dy` will be limited internally to allow scrolling only on the content area.
* @param obj pointer to an object to scroll
* @param obj pointer to scrollable Widget to scroll
* @param dx pixels to scroll horizontally
* @param dy pixels to scroll vertically
* @param anim_en LV_ANIM_ON: scroll with animation; LV_ANIM_OFF: scroll immediately
@ -201,9 +206,9 @@ void lv_obj_scroll_by(lv_obj_t * obj, int32_t x, int32_t y, lv_anim_enable_t ani
void lv_obj_scroll_by_bounded(lv_obj_t * obj, int32_t dx, int32_t dy, lv_anim_enable_t anim_en);
/**
* Scroll to a given coordinate on an object.
* Scroll to given coordinate on Widget.
* `x` and `y` will be limited internally to allow scrolling only on the content area.
* @param obj pointer to an object to scroll
* @param obj pointer to scrollable Widget to scroll
* @param x pixels to scroll horizontally
* @param y pixels to scroll vertically
* @param anim_en LV_ANIM_ON: scroll with animation; LV_ANIM_OFF: scroll immediately
@ -211,56 +216,55 @@ void lv_obj_scroll_by_bounded(lv_obj_t * obj, int32_t dx, int32_t dy, lv_anim_en
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 X coordinate on an object.
* Scroll to X coordinate on Widget.
* `x` will be limited internally to allow scrolling only on the content area.
* @param obj pointer to an object to scroll
* @param obj pointer to scrollable Widget to scroll
* @param x pixels to scroll horizontally
* @param 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 Y coordinate on an object
* Scroll to Y coordinate on Widget.
* `y` will be limited internally to allow scrolling only on the content area.
* @param obj pointer to an object to scroll
* @param obj pointer to scrollable Widget to scroll
* @param y pixels to scroll vertically
* @param 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 an object until it becomes visible on its parent
* @param obj pointer to an object to scroll into view
* Scroll `obj`'s parent Widget until `obj` becomes visible.
* @param obj pointer to Widget to scroll into view
* @param 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.
* 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
* @param obj pointer to an object to scroll into view
* Scroll `obj`'s parent Widgets recursively until `obj` becomes visible.
* Widget will be scrolled into view even it has nested scrollable parents.
* @param obj pointer to Widget to scroll into view
* @param 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);
/**
* Tell whether an object is being scrolled or not at this moment
* @param obj pointer to an object
* Tell whether Widget is being scrolled or not at this moment
* @param obj pointer to Widget
* @return true: `obj` is being scrolled
*/
bool lv_obj_is_scrolling(const lv_obj_t * obj);
/**
* Check the children of `obj` and scroll `obj` to fulfill the scroll_snap settings
* @param obj an object whose children needs to checked and snapped
* Check children of `obj` and scroll `obj` to fulfill scroll_snap settings.
* @param obj Widget whose children need to be checked and snapped
* @param anim_en LV_ANIM_ON/OFF
*/
void lv_obj_update_snap(lv_obj_t * obj, lv_anim_enable_t anim_en);
/**
* Get the area of the scrollbars
* @param obj pointer to an object
* @param obj pointer to Widget
* @param hor pointer to store the area of the horizontal scrollbar
* @param ver pointer to store the area of the vertical scrollbar
*/
@ -268,13 +272,13 @@ void lv_obj_get_scrollbar_area(lv_obj_t * obj, lv_area_t * hor, lv_area_t * ver)
/**
* Invalidate the area of the scrollbars
* @param obj pointer to an object
* @param obj pointer to Widget
*/
void lv_obj_scrollbar_invalidate(lv_obj_t * obj);
/**
* Checks if the content is scrolled "in" and adjusts it to a normal position.
* @param obj pointer to an object
* @param obj pointer to Widget
* @param anim_en LV_ANIM_ON/OFF
*/
void lv_obj_readjust_scroll(lv_obj_t * obj, lv_anim_enable_t anim_en);