mirror of
https://github.com/lvgl/lvgl.git
synced 2025-01-28 07:03:00 +08:00
docs add docs for some extra widgets
This commit is contained in:
Gabor Kiss-Vamosi
parent
ca01593561
commit
643b6f52f0
@ -6,41 +6,44 @@
|
||||
|
||||
## 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.
|
||||
Before reading this section, please read the [Button](/widgets/btn) section for better understanding.
|
||||
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.
|
||||
|
||||
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
|
||||
The Image button object has only a main part called `LV_IMG_BTN_PART_MAIN` from where all *image* style properties are used.
|
||||
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.
|
||||
- `LV_PART_MAIN` Refers to the image(s). If background style properties are used, a rectangle will be drawn behind the image button.
|
||||
|
||||
## Usage
|
||||
|
||||
### Image sources
|
||||
To set the image in a state, use the `lv_imgbtn_set_src(imgbtn, LV_BTN_STATE_..., &img_src)`.
|
||||
The image sources works the same as described in the [Image object](/widgets/img) except that, "Symbols" are not supported by the Image button.
|
||||
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/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.
|
||||
Using the tiled feature the *middle* image will be repeated to fill the width of the object.
|
||||
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.
|
||||
The possible states are:
|
||||
- `LV_IMGBTN_STATE_RELEASED`
|
||||
- `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
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
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.
|
||||
- `LV_EVENT_VALUE_CHANGED` Sent when the button is toggled.
|
||||
|
||||
Learn more about [Events](/overview/event).
|
||||
|
||||
## Keys
|
||||
The following *Keys* are processed by the Buttons:
|
||||
- **LV_KEY_RIGHT/UP** - Go to toggled state if toggling is enabled.
|
||||
- **LV_KEY_LEFT/DOWN** - Go to non-toggled state if toggling is enabled.
|
||||
- `LV_KEY_RIGHT/UP` Go to toggled state if `LV_OBJ_FLAG_CHECHABLE` is enabled.
|
||||
- `LV_KEY_LEFT/DOWN` Go to non-toggled state if `LV_OBJ_FLAG_CHECHABLE` 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).
|
||||
|
||||
@ -48,7 +51,7 @@ Learn more about [Keys](/overview/indev).
|
||||
|
||||
```eval_rst
|
||||
|
||||
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_imgbtn/index.rst
|
||||
.. include:: ../../../examples/widgets/imgbtn/index.rst
|
||||
|
||||
```
|
||||
|
||||
|
||||
@ -8,64 +8,59 @@
|
||||
|
||||
## 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
|
||||
Similarly to Button matices Keyboards consist of 2 part:
|
||||
- `LV_KEYBOARD_PART_BG` which is 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.
|
||||
Similarly to Button matrices Keyboards consist of 2 part:
|
||||
- `LV_PART_MAIN` The main part and uses all the typical background properties
|
||||
- `LV_PART_ITEMS` The buttons and it also uses all typical background properties and the *text* properties.
|
||||
|
||||
## Usage
|
||||
|
||||
### Modes
|
||||
The Keyboards have thefollowing modes:
|
||||
- **LV_KEYBOARD_MODE_TEXT_LOWER** - Display lower case letters
|
||||
- **LV_KEYBOARD_MODE_TEXT_UPPER** - Display upper case letters
|
||||
- **LV_KEYBOARD_MODE_TEXT_SPECIAL** - Display special characters
|
||||
- **LV_KEYBOARD_MODE_NUM** - Display numbers, +/- sign, and decimal dot.
|
||||
The Keyboards have the following modes:
|
||||
- `LV_KEYBOARD_MODE_TEXT_LOWER` Display lower case letters
|
||||
- `LV_KEYBOARD_MODE_TEXT_UPPER` Display upper case letters
|
||||
- `LV_KEYBOARD_MODE_TEXT_SPECIAL` Display special characters
|
||||
- `LV_KEYBOARD_MODE_NUM` Display numbers, +/- sign, and decimal dot.
|
||||
|
||||
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
|
||||
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)`.
|
||||
|
||||
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
|
||||
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.
|
||||
Keep in mind that, using following keywords will have the same effect as with the original map:
|
||||
- *LV_SYMBOL_OK* - Apply.
|
||||
- *LV_SYMBOL_CLOSE* - Close.
|
||||
- *LV_SYMBOL_BACKSPACE* - Delete on the left.
|
||||
- *LV_SYMBOL_LEFT* - Move the cursor left.
|
||||
- *LV_SYMBOL_RIGHT* - Move the cursor right.
|
||||
- *"ABC"* - Load the uppercase map.
|
||||
- *"abc"* - Load the lower case map.
|
||||
- *"Enter"* - New line.
|
||||
- `LV_SYMBOL_OK` Apply.
|
||||
- `LV_SYMBOL_CLOSE` or `LV_SYMBOL_KEYBOARD` Close.
|
||||
- `LV_SYMBOL_BACKSPACE` Delete on the left.
|
||||
- `LV_SYMBOL_LEFT` Move the cursor left.
|
||||
- `LV_SYMBOL_RIGHT` Move the cursor right.
|
||||
- `LV_SYMBOL_NEW_LINE` New line.
|
||||
- *"ABC"* Load the uppercase map.
|
||||
- *"abc"* Load the lower case map.
|
||||
- *"1#"* Load the lower case map.
|
||||
|
||||
## 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_APPLY** - The *Ok* button is clicked.
|
||||
- **LV_EVENT_CANCEL** - The *Close* button is clicked.
|
||||
- `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_CANCEL` - The *Close* button is clicked.
|
||||
|
||||
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.
|
||||
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).
|
||||
|
||||
## Keys
|
||||
|
||||
The following *Keys* are processed by the buttons:
|
||||
- **LV_KEY_RIGHT/UP/LEFT/RIGHT** - To navigate among the buttons and select one.
|
||||
- **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).
|
||||
|
||||
@ -75,7 +70,7 @@ Learn more about [Keys](/overview/indev).
|
||||
|
||||
```eval_rst
|
||||
|
||||
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_keyboard/index.rst
|
||||
.. include:: ../../../examples/widgets/keyboard/index.rst
|
||||
|
||||
```
|
||||
|
||||
|
||||
@ -11,9 +11,12 @@ The LEDs are rectangle-like (or circle) object. It's brightness can be adjusted.
|
||||
## Parts and Styles
|
||||
The LEDs have only one main part, called `LV_LED_PART_MAIN` and it uses all the typical background style properties.
|
||||
|
||||
|
||||
## 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
|
||||
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.
|
||||
|
||||
## 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).
|
||||
|
||||
@ -34,7 +37,7 @@ Learn more about [Keys](/overview/indev).
|
||||
|
||||
```eval_rst
|
||||
|
||||
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_led/index.rst
|
||||
.. include:: ../../../examples/widgets/led/index.rst
|
||||
|
||||
```
|
||||
|
||||
|
||||
@ -5,78 +5,38 @@
|
||||
# List (lv_list)
|
||||
|
||||
## Overview
|
||||
The Lists are built from a background [Page](/widgets/page) and [Buttons](/widgets/btn) on it.
|
||||
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.
|
||||
The List is basically a rectangle with vertical layout to which Buttons and Texts can be added
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
The buttons on the list are treated as normal buttons and they only have a main part called `LV_BTN_PART_MAIN`.
|
||||
**Buttons and Texts**
|
||||
See the [/widgets/core/btn](Button)'s and [/widgets/core/label](Label)'s documentation.
|
||||
|
||||
## Usage
|
||||
|
||||
### Add 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")`.
|
||||
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.
|
||||
### Buttons
|
||||
`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.
|
||||
|
||||
The width of the buttons is set to maximum according to the object width.
|
||||
The height of the buttons are adjusted automatically according to the content. (*content height* + *padding_top* + *padding_bottom*).
|
||||
The text starts to scroll horizontally if its too long.
|
||||
|
||||
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
|
||||
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).
|
||||
|
||||
## Keys
|
||||
The following *Keys* are processed by the Lists:
|
||||
- **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.
|
||||
No *Keys* are processed by the object type.
|
||||
|
||||
Learn more about [Keys](/overview/indev).
|
||||
|
||||
|
||||
## Example
|
||||
|
||||
```eval_rst
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
.. include:: /header.rst
|
||||
:github_url: |github_link_base|/widgets/span.md
|
||||
```
|
||||
# span (lv_span)
|
||||
# Span (lv_span)
|
||||
|
||||
## 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.
|
||||
|
||||
## 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).
|
||||
|
||||
|
||||
@ -4,7 +4,7 @@ C
|
||||
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
|
||||
|
||||
MicroPython
|
||||
|
||||
@ -4,7 +4,7 @@ C
|
||||
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
|
||||
|
||||
MicroPython
|
||||
|
||||
@ -1,10 +1,10 @@
|
||||
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
|
||||
|
||||
MicroPython
|
||||
|
||||
@ -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);
|
||||
|
||||
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;
|
||||
|
||||
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*/
|
||||
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 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;
|
||||
|
||||
lv_res_t info_res = LV_RES_OK;
|
||||
if(lv_img_src_get_type(src) == LV_IMG_SRC_SYMBOL) {
|
||||
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);
|
||||
}
|
||||
info_res = lv_img_decoder_get_info(src, &header);
|
||||
|
||||
if(info_res == LV_RES_OK) {
|
||||
imgbtn->act_cf = header.cf;
|
||||
|
||||
@ -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;
|
||||
led->color = lv_theme_get_color_primary(obj);
|
||||
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)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user