github-code/lvgl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(all) Proofread, fix typos and add clarifications in confusing areas (#2528)

Browse Source 
Co-authored-by: Gabor Kiss-Vamosi <kisvegabor@gmail.com>
This commit is contained in:
Kevin Thibedeau
2021-09-06 04:55:37 -04:00
committed by GitHub
parent 715d580d8c
commit 7d9fe20a0e
36 changed files with 654 additions and 656 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
docs/overview/scroll.md
View File

@@ -5,22 +5,22 @@
# Scroll
## Overview
In LVGL scrolling works very intuitively: if an object is out of its parent content area (the size without paddings), the parent becomes scrollable and scrollbar(s) will appear. That's it.
In LVGL scrolling works very intuitively: if an object is outside of 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_t`, `lv_img`, `lv_btn`, `lv_meter`, etc
The object can either be scrolled either horizontally or vertically in one stroke; diagonal scrolling is not possible.
The object can either be scrolled horizontally or vertically in one stroke; diagonal scrolling is not possible.
### Scrollbar
#### Mode
The scrollbars are displayed according to the set `mode`. The following `mode`s exist:
Scrollbars are displayed according to a configured `mode`. The following `mode`s exist:
- `LV_SCROLLBAR_MODE_OFF` Never show the scrollbars
- `LV_SCROLLBAR_MODE_ON` Always show the scrollbars
- `LV_SCROLLBAR_MODE_ACTIVE` Show scroll bars while object is being scrolled
- `LV_SCROLLBAR_MODE_ACTIVE` Show scroll bars while a object is being scrolled
- `LV_SCROLLBAR_MODE_AUTO` Show scroll bars when the content is large enough to be scrolled
`lv_obj_set_scrollbar_mode(obj, LV_SCROLLBAR_MODE_...)` set the scrollbar mode on an object.
`lv_obj_set_scrollbar_mode(obj, LV_SCROLLBAR_MODE_...)` sets the scrollbar mode on an object.
#### Styling
@@ -35,12 +35,12 @@ lv_style_set_bg_color(&style_red, lv_color_red());
lv_obj_add_style(obj, &style_red, LV_PART_SCROLLBAR);
```
The object goes to `LV_STATE_SCROLLED` state while it's being scrolled. It allows adding different style to the scrollbar or the object itself when scrolled.
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:
```c
static lv_style_t style_blue;
lv_style_init(&style_blue);
lv_style_set_bg_color(&style_red, lv_color_blue());
lv_style_set_bg_color(&style_blue, lv_color_blue());
...
@@ -49,7 +49,7 @@ 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 obejct's or any parent's main part to make scrollbar inherit the base direction.
or on the object's or any parent's main part to make a scrollbar inherit the base direction.
### Events
The following events are related to scrolling:
@@ -63,16 +63,16 @@ TODO
## Features of scrolling
Besides, managing "normal" scrolling there are many interesting and useful additional features too.
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_clear_flag(obj, LV_OBJ_FLAG_SCROLLABLE)`.
Non-scrollable object can still propagate the scrolling (chain) to the parents.
Non-scrollable objects can still propagate the scrolling (chain) to their parents.
The direction in which scrolling can happen can be controlled by `lv_obj_set_scroll_dir(obj, LV_DIR_...)`.
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 up
- `LV_DIR_LEFT` only scroll left
@@ -86,33 +86,33 @@ 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) the scrolling is propagated to its parent. If the parent can be scrolled in that direction than it will be scrolled instead.
It propagates to the grandparent and grand-grandparents too.
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 the `LV_OBJ_FLAG_SCROLL_CHAIN` 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 a momentum for the scrolling. It's like the object was thrown and scrolling slows down smoothly.
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 the content can't be scrolled inside the object. That is the top side of the content can't be below the top side of the object.
Normally an object can't be scrolled past the extremeties 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 can be added when the user "over-scrolls" the content. The scrolling slows down, and the content can be scrolled inside 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.
The object can align the snapped children in 4 ways:
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 the scrolled object
- `LV_SCROLL_SNAP_END` Align the children to the right/bottom side of the scrolled object
- `LV_SCROLL_SNAP_CENTER` Align the children to the center of the scrolled object
- `LV_SCROLL_SNAP_START` Align the children to the left/top side of a scrolled object
- `LV_SCROLL_SNAP_END` Align the children to the right/bottom side of a scrolled object
- `LV_SCROLL_SNAP_CENTER` Align the children to the center of a scrolled object
The alignment can be set with `lv_obj_set_scroll_snap_x/y(obj, LV_SCROLL_SNAP_...)`:
Snap alignment is set with `lv_obj_set_scroll_snap_x/y(obj, LV_SCROLL_SNAP_...)`:
Under the hood the following happens:
1. User scrolls an object and releases the screen
@@ -122,34 +122,34 @@ Under the hood the following happens:
### Scroll one
The "scroll one" feature tells LVGL to allow scrolling only one snappable child at a time.
So this requires to make the children snappable and set a scroll snap alignment different from `LV_SCROLL_SNAP_NONE`.
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 scrollable object. Pressing the "Tab" button focuses the next object, but it might be out of the visible area of the scrollable object.
If the "scroll on focus" features is enabled LVGL will automatically scroll to the objects to bring the children into the view.
The scrolling happens recursively therefore even nested scrollable object are handled properly.
The object will be scrolled to the view even if it's on a different page of a tabview.
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 to manually scroll objects:
The following API functions allow manual scrolling of objects:
- `lv_obj_scroll_by(obj, x, y, LV_ANIM_ON/OFF)` scroll by `x` and `y` values
- `lv_obj_scroll_to(obj, x, y, LV_ANIM_ON/OFF)` scroll to bring the given coordinate to the top left corner
- `lv_obj_scroll_to_x(obj, x, LV_ANIM_ON/OFF)` scroll to bring the given coordinate to the left side
- `lv_obj_scroll_to_y(obj, y, LV_ANIM_ON/OFF)` scroll to bring the given coordinate to the left side
- `lv_obj_scroll_to_y(obj, y, LV_ANIM_ON/OFF)` scroll to bring the given coordinate to the top side
## 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 tell the size of the content. To understand it better take the example of a table.
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.
It means not only the children can make an object scrollable but a larger self size too.
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
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:
```c
if(event_code == LV_EVENT_GET_SELF_SIZE) {
lv_point_t * p = lv_event_get_param(e);