From 643b6f52f0404f283fab80add8ddf534b3fad518 Mon Sep 17 00:00:00 2001 From: Gabor Kiss-Vamosi Date: Tue, 18 May 2021 14:25:17 +0200 Subject: [PATCH] docs add docs for some extra widgets --- docs/widgets/extra/imgbtn.md | 45 ++++++++++--------- docs/widgets/extra/keyboard.md | 59 ++++++++++++------------- docs/widgets/extra/led.md | 9 ++-- docs/widgets/extra/list.md | 66 ++++++---------------------- docs/widgets/extra/span.md | 4 +- examples/widgets/imgbtn/index.rst | 2 +- examples/widgets/keyboard/index.rst | 2 +- examples/widgets/span/index.rst | 6 +-- src/extra/widgets/imgbtn/lv_imgbtn.c | 22 +--------- src/extra/widgets/led/lv_led.c | 1 - 10 files changed, 78 insertions(+), 138 deletions(-) diff --git a/docs/widgets/extra/imgbtn.md b/docs/widgets/extra/imgbtn.md index be5868cfb..5084fd66d 100644 --- a/docs/widgets/extra/imgbtn.md +++ b/docs/widgets/extra/imgbtn.md @@ -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 ``` diff --git a/docs/widgets/extra/keyboard.md b/docs/widgets/extra/keyboard.md index 293cef1a2..25337a068 100644 --- a/docs/widgets/extra/keyboard.md +++ b/docs/widgets/extra/keyboard.md @@ -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 ``` diff --git a/docs/widgets/extra/led.md b/docs/widgets/extra/led.md index cc88d01da..7b82bd42c 100644 --- a/docs/widgets/extra/led.md +++ b/docs/widgets/extra/led.md @@ -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 ``` diff --git a/docs/widgets/extra/list.md b/docs/widgets/extra/list.md index f69142b48..1eb269394 100644 --- a/docs/widgets/extra/list.md +++ b/docs/widgets/extra/list.md @@ -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 diff --git a/docs/widgets/extra/span.md b/docs/widgets/extra/span.md index 1d2979b7b..098b7c61f 100644 --- a/docs/widgets/extra/span.md +++ b/docs/widgets/extra/span.md @@ -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). diff --git a/examples/widgets/imgbtn/index.rst b/examples/widgets/imgbtn/index.rst index 9d7648033..7084327b2 100644 --- a/examples/widgets/imgbtn/index.rst +++ b/examples/widgets/imgbtn/index.rst @@ -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 diff --git a/examples/widgets/keyboard/index.rst b/examples/widgets/keyboard/index.rst index 105e2af61..f68484570 100644 --- a/examples/widgets/keyboard/index.rst +++ b/examples/widgets/keyboard/index.rst @@ -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 diff --git a/examples/widgets/span/index.rst b/examples/widgets/span/index.rst index 50dfb72b0..cc7effe2e 100644 --- a/examples/widgets/span/index.rst +++ b/examples/widgets/span/index.rst @@ -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 diff --git a/src/extra/widgets/imgbtn/lv_imgbtn.c b/src/extra/widgets/imgbtn/lv_imgbtn.c index aaa110f1b..1df41d095 100644 --- a/src/extra/widgets/imgbtn/lv_imgbtn.c +++ b/src/extra/widgets/imgbtn/lv_imgbtn.c @@ -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; diff --git a/src/extra/widgets/led/lv_led.c b/src/extra/widgets/led/lv_led.c index 2cf082c5d..297912b50 100644 --- a/src/extra/widgets/led/lv_led.c +++ b/src/extra/widgets/led/lv_led.c @@ -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)