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

docs add docs for some extra widgets

Browse Source
This commit is contained in:
Gabor Kiss-Vamosi
2021-05-18 14:25:17 +02:00
parent ca01593561
commit 643b6f52f0
10 changed files with 78 additions and 138 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
docs/widgets/extra/imgbtn.md
View File

@@ -6,41 +6,44 @@
## Overview ## Overview
The Image button is very similar to the simple 'Button' object. The only difference is that, it displays user-defined images in each state instead of drawing a rectangle. The Image button is very similar to the simple 'Button' object. The only difference is that it displays user-defined images in each state instead of drawing a rectangle.
Before reading this section, please read the [Button](/widgets/btn) section for better understanding.
You can set a left, right and center image, and the center image will be repeated to match the width of the object.
## Parts and Styles ## Parts and Styles
The Image button object has only a main part called `LV_IMG_BTN_PART_MAIN` from where all *image* style properties are used. - `LV_PART_MAIN` Refers to the image(s). If background style properties are used, a rectangle will be drawn behind the image button.
It's possible to recolor the image in each state with *image_recolor* and *image_recolor_opa* proeprties. For example, to make the image darker if it is pressed.
## Usage ## Usage
### Image sources ### Image sources
To set the image in a state, use the `lv_imgbtn_set_src(imgbtn, LV_BTN_STATE_..., &img_src)`. To set the image in a state, use the `lv_imgbtn_set_src(imgbtn, LV_IMGBTN_STATE_..., src_left, src_center, src_right)`.
The image sources works the same as described in the [Image object](/widgets/img) except that, "Symbols" are not supported by the Image button.
The image sources works the same as described in the [Image object](/widgets/coreimg) except that, "Symbols" are not supported by the Image button.
Any of the sources can `NULL`.
If `LV_IMGBTN_TILED` is enabled in *lv_conf.h*, then `lv_imgbtn_set_src_tiled(imgbtn, LV_BTN_STATE_..., &img_src_left, &img_src_mid, &img_src_right)` becomes available. The possible states are:
Using the tiled feature the *middle* image will be repeated to fill the width of the object. - `LV_IMGBTN_STATE_RELEASED`
Therefore with `LV_IMGBTN_TILED`, you can set the width of the Image button using `lv_obj_set_width()`. However, without this option, the width will be always the same as the image source's width. - `LV_IMGBTN_STATE_PRESSED`
- `LV_IMGBTN_STATE_DISABLED`
- `LV_IMGBTN_STATE_CHECKED_RELEASED`
- `LV_IMGBTN_STATE_CHECKED_PRESSED`
- `LV_IMGBTN_STATE_CHECKED_DISABLED`
### Button features If you set the sources only in `LV_IMGBTN_STATE_RELEASED`, the sources will be used in other states too.
If you set e.g. `LV_IMGBTN_STATE_PRESSED` they will be used in pressed state instead of the released images.
Similarly to normal Buttons `lv_imgbtn_set_checkable(imgbtn, true/false)`, `lv_imgbtn_toggle(imgbtn)` and `lv_imgbtn_set_state(imgbtn, LV_BTN_STATE_...)` also works.
## Events ## Events
Beside the [Generic events](../overview/event.html#generic-events), the following [Special events](../overview/event.html#special-events) are sent by the buttons: - `LV_EVENT_VALUE_CHANGED` Sent when the button is toggled.
- **LV_EVENT_VALUE_CHANGED** - Sent when the button is toggled.
Note that, the generic input device related events (like `LV_EVENT_PRESSED`) are sent in the inactive state too. You need to check the state with `lv_btn_get_state(btn)` to ignore the events from inactive buttons.
Learn more about [Events](/overview/event). Learn more about [Events](/overview/event).
## Keys ## Keys
The following *Keys* are processed by the Buttons: - `LV_KEY_RIGHT/UP` Go to toggled state if `LV_OBJ_FLAG_CHECHABLE` is enabled.
- **LV_KEY_RIGHT/UP** - Go to toggled state if toggling is enabled. - `LV_KEY_LEFT/DOWN` Go to non-toggled state if `LV_OBJ_FLAG_CHECHABLE` is enabled.
- **LV_KEY_LEFT/DOWN** - Go to non-toggled state if toggling is enabled. - `LV_KEY_ENTER` Clicks the button
Note that, as usual, the state of `LV_KEY_ENTER` is translated to `LV_EVENT_PRESSED/PRESSING/RELEASED` etc.
Learn more about [Keys](/overview/indev). Learn more about [Keys](/overview/indev).
@@ -48,7 +51,7 @@ Learn more about [Keys](/overview/indev).
```eval_rst ```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_imgbtn/index.rst .. include:: ../../../examples/widgets/imgbtn/index.rst
``` ```

59
docs/widgets/extra/keyboard.md
View File

@@ -8,64 +8,59 @@
## Overview ## Overview
The Keyboard object is a special [Button matrix](/widgets/btnmatrix) with predefined keymaps and other features to realize a virtual keyboard to write text. The Keyboard object is a special [Button matrix](/widgets/core/btnmatrix) with predefined keymaps and other features to realize a virtual keyboard to write texts into a [Text area](/widgets/core/textarea).
## Parts and Styles ## Parts and Styles
Similarly to Button matices Keyboards consist of 2 part: Similarly to Button matrices Keyboards consist of 2 part:
- `LV_KEYBOARD_PART_BG` which is the main part and uses all the typical background properties - `LV_PART_MAIN` The main part and uses all the typical background properties
- `LV_KEYBOARD_PART_BTN` which is virtual part for the buttons. It also uses all typical backround proeprties and the *text* properties. - `LV_PART_ITEMS` The buttons and it also uses all typical background properties and the *text* properties.
## Usage ## Usage
### Modes ### Modes
The Keyboards have thefollowing modes: The Keyboards have the following modes:
- **LV_KEYBOARD_MODE_TEXT_LOWER** - Display lower case letters - `LV_KEYBOARD_MODE_TEXT_LOWER` Display lower case letters
- **LV_KEYBOARD_MODE_TEXT_UPPER** - Display upper case letters - `LV_KEYBOARD_MODE_TEXT_UPPER` Display upper case letters
- **LV_KEYBOARD_MODE_TEXT_SPECIAL** - Display special characters - `LV_KEYBOARD_MODE_TEXT_SPECIAL` Display special characters
- **LV_KEYBOARD_MODE_NUM** - Display numbers, +/- sign, and decimal dot. - `LV_KEYBOARD_MODE_NUM` Display numbers, +/- sign, and decimal dot.
The `TEXT` modes' layout contains buttons to change mode. The `TEXT` modes' layout contains buttons to change mode.
To set the mode manually, use `lv_keyboard_set_mode(kb, mode)`. The default more is `LV_KEYBOARD_MODE_TEXT_UPPER`. To set the mode manually, use `lv_keyboard_set_mode(kb, mode)`. The default mode is `LV_KEYBOARD_MODE_TEXT_UPPER`.
### Assign Text area ### Assign Text area
You can assign a [Text area](/widgets/textarea) to the Keyboard to automatically put the clicked characters there. You can assign a [Text area](/widgets/core/textarea) to the Keyboard to automatically put the clicked characters there.
To assign the text area, use `lv_keyboard_set_textarea(kb, ta)`. To assign the text area, use `lv_keyboard_set_textarea(kb, ta)`.
The assigned text area's **cursor can be managed** by the keyboard: when the keyboard is assigned, the previous text area's cursor will be hidden and the new one will be shown.
When the keyboard is closed by the *Ok* or *Close* buttons, the cursor also will be hidden. The cursor manager feature is enabled by `lv_keyboard_set_cursor_manage(kb, true)`. The default is not managed.
### New Keymap ### New Keymap
You can specify a new map (layout) for the keyboard with `lv_keyboard_set_map(kb, map)` and `lv_keyboard_set_ctrl_map(kb, ctrl_map)`. You can specify a new map (layout) for the keyboard with `lv_keyboard_set_map(kb, map)` and `lv_keyboard_set_ctrl_map(kb, ctrl_map)`.
Learn more about the [Button matrix](/widgets/btnmatrix) object. Learn more about the [Button matrix](/widgets/btnmatrix) object.
Keep in mind that, using following keywords will have the same effect as with the original map: Keep in mind that, using following keywords will have the same effect as with the original map:
- *LV_SYMBOL_OK* - Apply. - `LV_SYMBOL_OK` Apply.
- *LV_SYMBOL_CLOSE* - Close. - `LV_SYMBOL_CLOSE` or `LV_SYMBOL_KEYBOARD` Close.
- *LV_SYMBOL_BACKSPACE* - Delete on the left. - `LV_SYMBOL_BACKSPACE` Delete on the left.
- *LV_SYMBOL_LEFT* - Move the cursor left. - `LV_SYMBOL_LEFT` Move the cursor left.
- *LV_SYMBOL_RIGHT* - Move the cursor right. - `LV_SYMBOL_RIGHT` Move the cursor right.
- *"ABC"* - Load the uppercase map. - `LV_SYMBOL_NEW_LINE` New line.
- *"abc"* - Load the lower case map. - *"ABC"* Load the uppercase map.
- *"Enter"* - New line. - *"abc"* Load the lower case map.
- *"1#"* Load the lower case map.
## Events ## Events
Besides the [Generic events](../overview/event.html#generic-events), the following [Special events](../overview/event.html#special-events) are sent by the keyboards: - `LV_EVENT_VALUE_CHANGED` Sent when the button is pressed/released or repeated after long press. The event data is set to the ID of the pressed/released button.
- **LV_EVENT_VALUE_CHANGED** - Sent when the button is pressed/released or repeated after long press. The event data is set to the ID of the pressed/released button. - `LV_EVENT_READY` - The *Ok* button is clicked.
- **LV_EVENT_APPLY** - The *Ok* button is clicked. - `LV_EVENT_CANCEL` - The *Close* button is clicked.
- **LV_EVENT_CANCEL** - The *Close* button is clicked.
The keyboard has a **default event handler** callback called `lv_keyboard_def_event_cb`. The keyboard has a **default event handler** callback called `lv_keyboard_def_event_cb`.
It handles the button pressing, map changing, the assigned text area, etc. It handles the button pressing, map changing, the assigned text area, etc.
You can completely replace it with your custom event handler however, you can call `lv_keyboard_def_event_cb` at the beginning of your event handler to handle the same things as before. You can remove it and replace it with a custom event handler if you wish.
Learn more about [Events](/overview/event). Learn more about [Events](/overview/event).
## Keys ## Keys
- `LV_KEY_RIGHT/UP/LEFT/RIGHT` To navigate among the buttons and select one.
The following *Keys* are processed by the buttons: - `LV_KEY_ENTER` To press/release the selected button.
- **LV_KEY_RIGHT/UP/LEFT/RIGHT** - To navigate among the buttons and select one.
- **LV_KEY_ENTER** - To press/release the selected button.
Learn more about [Keys](/overview/indev). Learn more about [Keys](/overview/indev).
@@ -75,7 +70,7 @@ Learn more about [Keys](/overview/indev).
```eval_rst ```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_keyboard/index.rst .. include:: ../../../examples/widgets/keyboard/index.rst
``` ```

9
docs/widgets/extra/led.md
View File

@@ -11,9 +11,12 @@ The LEDs are rectangle-like (or circle) object. It's brightness can be adjusted.
## Parts and Styles ## Parts and Styles
The LEDs have only one main part, called `LV_LED_PART_MAIN` and it uses all the typical background style properties. The LEDs have only one main part, called `LV_LED_PART_MAIN` and it uses all the typical background style properties.
## Usage ## Usage
### Color
You can set the color of the LED with `lv_led_set_color(led, lv_color_hex(0xff0080))`.
This will be used as background color, border color, and shadow color.
### Brightness ### Brightness
You can set their brightness with `lv_led_set_bright(led, bright)`. The brightness should be between 0 (darkest) and 255 (lightest). You can set their brightness with `lv_led_set_bright(led, bright)`. The brightness should be between 0 (darkest) and 255 (lightest).
@@ -21,7 +24,7 @@ You can set their brightness with `lv_led_set_bright(led, bright)`. The brightne
Use `lv_led_on(led)` and `lv_led_off(led)` to set the brightness to a predefined ON or OFF value. The `lv_led_toggle(led)` toggles between the ON and OFF state. Use `lv_led_on(led)` and `lv_led_off(led)` to set the brightness to a predefined ON or OFF value. The `lv_led_toggle(led)` toggles between the ON and OFF state.
## Events ## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type. No special event are sent by the LED object.
Learn more about [Events](/overview/event). Learn more about [Events](/overview/event).
@@ -34,7 +37,7 @@ Learn more about [Keys](/overview/indev).
```eval_rst ```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_led/index.rst .. include:: ../../../examples/widgets/led/index.rst
``` ```

66
docs/widgets/extra/list.md
View File

@@ -5,78 +5,38 @@
# List (lv_list) # List (lv_list)
## Overview ## Overview
The Lists are built from a background [Page](/widgets/page) and [Buttons](/widgets/btn) on it. The List is basically a rectangle with vertical layout to which Buttons and Texts can be added
The Buttons contain an optional icon-like [Image](/widgets/img) (which can be a symbol too) and a [Label](/widgets/label).
When the list becomes long enough it can be scrolled.
## Parts and Styles ## Parts and Styles
The List has the same parts as the [Page](/widgets/page)
- `LV_LIST_PART_BG`
- `LV_LIST_PART_SCRL`
- `LV_LIST_PART_SCRLBAR`
- `LV_LIST_PART_EDGE_FLASH`
Refer to the [Page](/widgets/page) documentation for details. **Background**
- `LV_PART_MAIN` The main part of the list that uses all the typical background properties
- `LV_PART_SCROLLBAR` The scrollbar. See the [Base objects](/widgets/obj) documentation for details.
**Buttons and Texts**
The buttons on the list are treated as normal buttons and they only have a main part called `LV_BTN_PART_MAIN`. See the [/widgets/core/btn](Button)'s and [/widgets/core/label](Label)'s documentation.
## Usage ## Usage
### Add buttons ### Buttons
You can add new list elements (button) with `lv_list_add_btn(list, &icon_img, "Text")` or with symbol `lv_list_add_btn(list, SYMBOL_EDIT, "Edit text")`. `lv_list_add_btn(list, icon, text)` adds a full-width button with an icon - that can be an image or symbol - and a text.
If you do not want to add image use `NULL` as image source. The function returns with a pointer to the created button to allow further configurations.
The width of the buttons is set to maximum according to the object width. The text starts to scroll horizontally if its too long.
The height of the buttons are adjusted automatically according to the content. (*content height* + *padding_top* + *padding_bottom*).
The labels are created with `LV_LABEL_LONG_SROLL_CIRC` long mode to automatically scroll the long labels circularly. ### Texts
`lv_list_add_text(list, icon, text)` adds a text.
`lv_list_get_btn_label(list_btn)` and `lv_list_get_btn_img(list_btn)` can be used to get the label and the image of a list button.
The text can be et directly with `lv_list_get_btn_text(list_btn)`.
### Delete buttons
To delete a list element use `lv_list_remove(list, btn_index)`. btn_index can be obtained by `lv_list_get_btn_index(list, btn)` where btn is the return value of `lv_list_add_btn()`.
To clean the list (remove all buttons) use `lv_list_clean(list)`
### Manual navigation
You can navigate manually in the list with `lv_list_up(list)` and `lv_list_down(list)`.
You can focus on a button directly using `lv_list_focus(btn, LV_ANIM_ON/OFF)`.
The **animation time** of up/down/focus movements can be set via: `lv_list_set_anim_time(list, anim_time)`. Zero animation time means not animations.
### Layout
By default the list is vertical. To get a horizontal list use `lv_list_set_layout(list, LV_LAYOUT_ROW_MID)`.
### Edge flash
A circle-like effect can be shown when the list reaches the most top or bottom position.
`lv_list_set_edge_flash(list, true)` enables this feature.
### Scroll propagation
If the list is created on an other scrollable element (like a [Page](/widgets/page)) and the list can't be scrolled further the scrolling can be propagated to the parent.
This way the scroll will be continued on the parent. It can be enabled with `lv_list_set_scroll_propagation(list, true)`
## Events ## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type. No special events are sent by the List, but sent by the Button as usual.
Learn more about [Events](/overview/event). Learn more about [Events](/overview/event).
## Keys ## Keys
The following *Keys* are processed by the Lists: No *Keys* are processed by the object type.
- **LV_KEY_RIGHT/DOWN** Select the next button
- **LV_KEY_LEFT/UP** Select the previous button
Note that, as usual, the state of `LV_KEY_ENTER` is translated to `LV_EVENT_PRESSED/PRESSING/RELEASED` etc.
The Selected buttons are in `LV_BTN_STATE_PR/TG_PR` state.
To manually select a button use `lv_list_set_btn_selected(list, btn)`. When the list is defocused and focused again it will restore the last selected button.
Learn more about [Keys](/overview/indev). Learn more about [Keys](/overview/indev).
## Example ## Example
```eval_rst ```eval_rst

4
docs/widgets/extra/span.md
View File

@@ -2,7 +2,7 @@
.. include:: /header.rst .. include:: /header.rst
:github_url: |github_link_base|/widgets/span.md :github_url: |github_link_base|/widgets/span.md
``` ```
# span (lv_span) # Span (lv_span)
## Overview ## Overview
@@ -47,7 +47,7 @@ use function `lv_span_set_overflow(spangroup, LV_SPAN_OVERFLOW_CLIP)` to set obj
use function `lv_span_set_indent(spangroup, 20)` to set text indent of first line. use function `lv_span_set_indent(spangroup, 20)` to set text indent of first line.
## Events ## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type. No special events are sent by this widget.
Learn more about [Events](/overview/event). Learn more about [Events](/overview/event).

2
examples/widgets/imgbtn/index.rst
View File

@@ -4,7 +4,7 @@ C
Simple Image button Simple Image button
""""""""""""""""""" """""""""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_imgbtn/lv_ex_imgbtn_1 .. lv_example:: widgets/imgbtn/lv_example_imgbtn_1
:language: c :language: c
MicroPython MicroPython

2
examples/widgets/keyboard/index.rst
View File

@@ -4,7 +4,7 @@ C
Keyboard with text area Keyboard with text area
""""""""""""""""""""""" """""""""""""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_keyboard/lv_ex_keyboard_1 .. lv_example:: _widgets/keyboard/lv_example_keyboard_1
:language: c :language: c
MicroPython MicroPython

6
examples/widgets/span/index.rst
View File

@@ -1,10 +1,10 @@
C C
^ ^
span with custom style Span with custom styles
""""""""""""""""""""" """"""""""""""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_span/lv_ex_span_1 .. lv_example:: widgets/span/lv_example_span_1
:language: c :language: c
MicroPython MicroPython

22
src/extra/widgets/imgbtn/lv_imgbtn.c
View File

@@ -81,13 +81,6 @@ void lv_imgbtn_set_src(lv_obj_t * obj, lv_imgbtn_state_t state, const void * src
{ {
LV_ASSERT_OBJ(obj, MY_CLASS); LV_ASSERT_OBJ(obj, MY_CLASS);
if(lv_img_src_get_type(src_left) == LV_IMG_SRC_SYMBOL ||
lv_img_src_get_type(src_mid) == LV_IMG_SRC_SYMBOL ||
lv_img_src_get_type(src_right) == LV_IMG_SRC_SYMBOL) {
LV_LOG_WARN("lv_imgbtn_set_src: symbols are not supported in tiled mode");
return;
}
lv_imgbtn_t * imgbtn = (lv_imgbtn_t *)obj; lv_imgbtn_t * imgbtn = (lv_imgbtn_t *)obj;
imgbtn->img_src_left[state] = src_left; imgbtn->img_src_left[state] = src_left;
@@ -195,10 +188,6 @@ static void draw_main(lv_event_t * e)
/*Simply draw the middle src if no tiled*/ /*Simply draw the middle src if no tiled*/
const void * src = imgbtn->img_src_left[state]; const void * src = imgbtn->img_src_left[state];
if(lv_img_src_get_type(src) == LV_IMG_SRC_SYMBOL) {
LV_LOG_WARN("lv_imgbtn_draw: SYMBOLS are not supported in tiled mode")
return;
}
lv_coord_t tw = lv_obj_get_style_transform_width(obj, LV_PART_MAIN); lv_coord_t tw = lv_obj_get_style_transform_width(obj, LV_PART_MAIN);
lv_coord_t th = lv_obj_get_style_transform_height(obj, LV_PART_MAIN); lv_coord_t th = lv_obj_get_style_transform_height(obj, LV_PART_MAIN);
@@ -278,16 +267,7 @@ static void refr_img(lv_obj_t * obj)
if(src == NULL) return; if(src == NULL) return;
lv_res_t info_res = LV_RES_OK; lv_res_t info_res = LV_RES_OK;
if(lv_img_src_get_type(src) == LV_IMG_SRC_SYMBOL) { info_res = lv_img_decoder_get_info(src, &header);
const lv_font_t * font = lv_obj_get_style_text_font(obj, LV_PART_MAIN);
header.h = lv_font_get_line_height(font);
header.w = lv_txt_get_width(src, (uint16_t)strlen(src), font, 0, LV_TEXT_FLAG_NONE);
header.always_zero = 0;
header.cf = LV_IMG_CF_ALPHA_1BIT;
}
else {
info_res = lv_img_decoder_get_info(src, &header);
}
if(info_res == LV_RES_OK) { if(info_res == LV_RES_OK) {
imgbtn->act_cf = header.cf; imgbtn->act_cf = header.cf;

1
src/extra/widgets/led/lv_led.c
View File

@@ -156,7 +156,6 @@ static void lv_led_constructor(const lv_obj_class_t * class_p, lv_obj_t * obj)
lv_led_t * led = (lv_led_t *)obj; lv_led_t * led = (lv_led_t *)obj;
led->color = lv_theme_get_color_primary(obj); led->color = lv_theme_get_color_primary(obj);
led->bright = LV_LED_BRIGHT_MAX; led->bright = LV_LED_BRIGHT_MAX;
led->bright = LV_LED_BRIGHT_MAX;
} }
static void lv_led_event(const lv_obj_class_t * class_p, lv_event_t * e) static void lv_led_event(const lv_obj_class_t * class_p, lv_event_t * e)