feat(docs): scrolling doc proofread, edited and clarified... (#7170)
This commit is contained in:
Victor Wheeler
@@ -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
|
||||
***
|
||||
|
||||
Reference in New Issue
Block a user