diff options
Diffstat (limited to 'lib/lvgl/docs')
156 files changed, 13375 insertions, 0 deletions
diff --git a/lib/lvgl b/lib/lvgl deleted file mode 160000 -Subproject 0732400e7b564dd0e7dc4a924619d8e19c5b23a diff --git a/lib/lvgl/docs/CHANGELOG.md b/lib/lvgl/docs/CHANGELOG.md new file mode 100644 index 00000000..d32fecb2 --- /dev/null +++ b/lib/lvgl/docs/CHANGELOG.md @@ -0,0 +1,1826 @@ +# Changelog + +## [v8.3.3](https://github.com/lvgl/lvgl/compare/v8.3.2...v8.3.3) 06 October 2022 + +v8.3.3 is the same as v8.3.2. It was released only because the version number was set incorrectly in lvgl.h. + +## [v8.3.2](https://github.com/lvgl/lvgl/compare/v8.3.1...v8.3.2) 27 September 2022 + +### Fixes + +- fix(fragment): fixed child fragment event dispatch [`3683`](https://github.com/lvgl/lvgl/pull/3683) +- fix(sdl): clear streaming/target texture with FillRect [`3682`](https://github.com/lvgl/lvgl/pull/3682) +- fix(sdl): transformation with alpha (#3576) [`3678`](https://github.com/lvgl/lvgl/pull/3678) +- fix(draw_sw): fix image cache to access the freed stack space [`3584`](https://github.com/lvgl/lvgl/pull/3584) +- fix(style): use compile time prop_cnt for const styles [`3609`](https://github.com/lvgl/lvgl/pull/3609) +- fix(demo): can not found lvgl.h file [`3477`](https://github.com/lvgl/lvgl/pull/3477) +- fix(ci) checkout lv_micropython release/v8 branch [`3524`](https://github.com/lvgl/lvgl/pull/3524) +- fix(canvas): fix clipéping on transformation [`b884aba`](https://github.com/lvgl/lvgl/commit/b884abae26f3824b27783a85d18ed51e550347c1) +- fix(draw): allow drawing outline with LV_DRAW_COMPLEX == 0 too [`ece3495`](https://github.com/lvgl/lvgl/commit/ece34950040e218fc73605a4e88f1060c2a274f8) +- fix(colorwheel): fix updating color when using lv_colorwheel_set_hsv [`d59bba1`](https://github.com/lvgl/lvgl/commit/d59bba12db115afb4b6aa53eed2625221dfff2fd) +- fix(slider): find the nearest value on click instead of floor [`dfd14fa`](https://github.com/lvgl/lvgl/commit/dfd14fa778aef25d0db61748a58aa9989ce5e2c8) +- fix(draw): fix border drawing with thick borders [`d5b2a9b`](https://github.com/lvgl/lvgl/commit/d5b2a9b2562cbfa327bf0ec03c11d28576037a14) +- fix(refr): fix true double double buffering logic with transparent screens [`8b605cc`](https://github.com/lvgl/lvgl/commit/8b605cc48224d0497cdd936fa77229e0c3d606d2) +- fix(group): be sure obj is removed from its current group in lv_group_add_obj [`5156ee0`](https://github.com/lvgl/lvgl/commit/5156ee058d5de674a00ffd84d15d460de7f0e53b) +- fix(style): add missing invalidation in lv_obj_remove_local_style_prop [`a0515ba`](https://github.com/lvgl/lvgl/commit/a0515ba30dd74b8b22a6709d334eb03782ee1a4d) + +### Docs + +- docs(draw) remove reference to old lv_fs_add_drv function [`3564`](https://github.com/lvgl/lvgl/pull/3564) +- docs(disp): LV_COLOR_SCREEN_TRANSP remove dependency on LV_COLOR_DEPTH_32 as transparency is supported across all color depths [`3556`](https://github.com/lvgl/lvgl/pull/3556) + +### CI and tests + +- ci: protect test.c with #if LV_BUILD_TEST [`be485d7`](https://github.com/lvgl/lvgl/commit/be485d7605136d2a5d6a633c7cb5b7c525cae7ee) + +### Others + +- chore(rt-thread) backport fixes from v9 [`3604`](https://github.com/lvgl/lvgl/pull/3604) + +- chore: fix warnings [`7640950`](https://github.com/lvgl/lvgl/commit/76409502163ffe67cfbab9c7f24f2226cc8a5941) +- remove accidentally added code [`5022476`](https://github.com/lvgl/lvgl/commit/5022476edc8676f2a6ef7b919d3578159edeef7c) + + +## [v8.3.1](https://github.com/lvgl/lvgl/compare/v8.3.0...v8.3.1) 25 July 2022 + +### Fixes + +- fix(led): add bg_color draw descriptors back to led draw event to support LV_DRAW_COMPLEX 0 [`3515`](https://github.com/lvgl/lvgl/pull/3515) +- fix(slider): fix knob drawing in symmetrical mode [`2967172`](https://github.com/lvgl/lvgl/commit/2967172bee806e77da6ee2307c79e867af3f76bc) +- fix(refr): fix lv_refr_get_top_obj [`9750c97`](https://github.com/lvgl/lvgl/commit/9750c97aff4dc3de80559b150852b829f006d6bf) +- fix(arc): fix arc knob invalidation in SYMMETRICAL mode [`a283273`](https://github.com/lvgl/lvgl/commit/a283273bd27599dae6b044a941b6591ad45e059b) + +### Examples + +- example(freetype): Update the Micropython example to use the Lato font [`71913d3`](https://github.com/lvgl/lvgl/commit/71913d300dde25d1b87d1b44fa1fa47854defd59) +- example(freetype): replace the arial font with lato to avoid licensing issues [`8544cc3`](https://github.com/lvgl/lvgl/commit/8544cc38062d9c817013bbe6aedbb47112e580ad) + +### Docs + +- docs(readme): fix LVGL version typo (8.3.0) [`3462`](https://github.com/lvgl/lvgl/pull/3462) +- docs(tasmota): support LVGL 8.3.0 (#3511) [`62662f6`](https://github.com/lvgl/lvgl/commit/62662f68e9cf90adcb96d42030eca5fa135b96a5) + + + +## [v8.3.0](https://github.com/lvgl/lvgl/compare/v8.2.0...v8.3.0) 6 July 2022 + + +### Overview + +- **Layers** Support transforming (zoom and rotate) any widgets and their children drawn by LVGL. To do this LVGL renders the transformed widgets into a layer and draws that layer as an image applying all the transformations. Layers are also used when `opa` (not `bg_opa`, `border_opa`, etc) and `blend_mode` are set. This way nested objects are blended as one layer to avoid color bleeding. See more [here](https://docs.lvgl.io/master/overview/style.html#opacity-blend-modes-and-transformations). +- **inherit and initial style properties** Besides setting "normal values" for style properties now you can set them to `inherit` (inherit the parent's value) and `initial` (set the system default). See more [here](https://docs.lvgl.io/master/overview/style.html#forced-value-inheritance-default-value) +- **NXP-PXP and VGLITE GPU support** The support for NXP GPUs are added again +- **Color font support** You can use emojis and images in texts with this great new features. See more [here](https://docs.lvgl.io/master/others/imgfont.html). +- **ARM2D GPU support** Get support for ARM's own GPU. +- **PubSub messaging** A publisher-subscriber based messaging system is added to make communication between components easier. See more [here](https://docs.lvgl.io/master/others/msg.html). +- **Pinyin IME** Add support for Pinyin IME Chinese input. See more [here](https://docs.lvgl.io/master/others/ime_pinyin.html). +- **render_start_cb** A new callback is added to `lv_disp_drv_t` to indicate when the rendering starts. It's useful to make synchronization, e.g. wait for a TE signal. + + +### New Features + +- feat(ime_pinyin): add API to support 9-key input mode [`3447`](https://github.com/lvgl/lvgl/pull/3447) +- feat(font): add font placeholder drawing configuration [`3446`](https://github.com/lvgl/lvgl/pull/3446) +- feat(fsdrv): add posix lseek() error checking [`3444`](https://github.com/lvgl/lvgl/pull/3444) +- feat(misc): add asynchronous call function cancellation function [`3439`](https://github.com/lvgl/lvgl/pull/3439) +- feat(ime_pinyin): add API to use Pinyin IME(Chinese input) [`3408`](https://github.com/lvgl/lvgl/pull/3408) +- feat(style) add 'inherit' and 'initial' CSS properties [`3390`](https://github.com/lvgl/lvgl/pull/3390) +- feat(porting): add flushing control to the template [`3384`](https://github.com/lvgl/lvgl/pull/3384) +- feat(anim): add deleted callback (#3279) [`3295`](https://github.com/lvgl/lvgl/pull/3295) +- feat(cmsis-pack): monthly update for May [`3394`](https://github.com/lvgl/lvgl/pull/3394) +- feat(textarea): make it possible to customize the bullet character [`3388`](https://github.com/lvgl/lvgl/pull/3388) +- feat(disp): add a temporary invalidation disable interface [`3378`](https://github.com/lvgl/lvgl/pull/3378) +- feat(group): add edge callbacks when trying to move focus past beginning or end [`3374`](https://github.com/lvgl/lvgl/pull/3374) +- feat(benchmark): make lvgl render at the highest frame rate [`3352`](https://github.com/lvgl/lvgl/pull/3352) +- feat(rt-thread): allow users to control refresh period in the lvgl thread [`3375`](https://github.com/lvgl/lvgl/pull/3375) +- feat(cmsis-pack): Monthly update for May (alpha) [`3359`](https://github.com/lvgl/lvgl/pull/3359) +- feat(demos): add a callback for benchmark [`3353`](https://github.com/lvgl/lvgl/pull/3353) +- feat(gpu): Update lv_gpu_arm2d with new features [`3340`](https://github.com/lvgl/lvgl/pull/3340) +- feat(draw): improve acceleration for LV_IMG_CF_ALPHA_8BIT [`3337`](https://github.com/lvgl/lvgl/pull/3337) +- feat(anim): add the function of getting global animation refresher timer [`3331`](https://github.com/lvgl/lvgl/pull/3331) +- feat(demo): add Weighted FPS and Opa speed log output [`3326`](https://github.com/lvgl/lvgl/pull/3326) +- feat(gpu): Update gpu arm 2d [`3320`](https://github.com/lvgl/lvgl/pull/3320) +- feat(cmsis-pack): Monthly update for April [`3300`](https://github.com/lvgl/lvgl/pull/3300) +- feat(fsdrv) fix issues for win32 backends [`3284`](https://github.com/lvgl/lvgl/pull/3284) +- feat(cmake-build): Option to allow building shared libraries. [`3278`](https://github.com/lvgl/lvgl/pull/3278) +- feat(hal): add render_start_cb to disp_drv [`3274`](https://github.com/lvgl/lvgl/pull/3274) +- feat(cmsis-pack): monthly update for April (v1.0.3-alpha) [`3271`](https://github.com/lvgl/lvgl/pull/3271) +- feat(benchmark): add trace output for running a specific scenario [`3245`](https://github.com/lvgl/lvgl/pull/3245) +- feat(env_support): cmsis pack monthly update [`3209`](https://github.com/lvgl/lvgl/pull/3209) +- feat(tabview): support vertical scrolling [`3184`](https://github.com/lvgl/lvgl/pull/3184) +- feat(span): add an interface for setting the number of lines [`3200`](https://github.com/lvgl/lvgl/pull/3200) +- feat(indev): add possibility to enable/disable all input devices at once [`3179`](https://github.com/lvgl/lvgl/pull/3179) +- feat(font): add imgfont - can be used to add emojis to label/span [`3160`](https://github.com/lvgl/lvgl/pull/3160) +- feat(gpu): add gpu arm2d [`3162`](https://github.com/lvgl/lvgl/pull/3162) +- feat(dma2d): add lv_draw_stm32_dma2d_buffer_copy function [`3147`](https://github.com/lvgl/lvgl/pull/3147) +- feat(disp): add screen out animations [`3081`](https://github.com/lvgl/lvgl/pull/3081) +- feat(menu): make menu widget more compatible with encoder [`3061`](https://github.com/lvgl/lvgl/pull/3061) +- feat(label): added animation style property to apply it to circular scrolling animation of label widget [`3128`](https://github.com/lvgl/lvgl/pull/3128) +- feat(script): add pre-commit configuration for code formatting [`3092`](https://github.com/lvgl/lvgl/pull/3092) +- feat(refr): prevents dirty areas from being modified during rendering [`3107`](https://github.com/lvgl/lvgl/pull/3107) +- feat(log): improve lv_log and add log the result from lv_demo_benchmark [`3084`](https://github.com/lvgl/lvgl/pull/3084) +- feat(fragment): add fragment manager (a UI Controller concept) [`2940`](https://github.com/lvgl/lvgl/pull/2940) +- feat(porting): add a macro lv_run_timer_handler_in_period to simplify porting [`3063`](https://github.com/lvgl/lvgl/pull/3063) +- feat(gpu): reattach nxp pxp vglite accelerators(#3322) [`029eef7`](https://github.com/lvgl/lvgl/commit/029eef79c4cf6fef4ad46f7e335011ba4172381b) +- feat(draw): support transforming widgets and improfe sw transform [`318146a`](https://github.com/lvgl/lvgl/commit/318146a2c25362eabf258470be263a4cfeaefe87) +- feat(msg): add publisher-subscriber messaging [`79a29d7`](https://github.com/lvgl/lvgl/commit/79a29d749d3e261ebadbe31fccbff896f63b4d93) +- feat(benchmark): add an API to run specific scene (#3089) [`305ad00`](https://github.com/lvgl/lvgl/commit/305ad00893c0d18d9a65e28ee03d65f76f8abb0a) +- feat(gpu): add SWM341 gpu support (synwit) [`07b7eea`](https://github.com/lvgl/lvgl/commit/07b7eea56c048a0654c254cadebee8caf5f7933b) +- feat(arc): add lv_arc_align_obj_to_angle and lv_arc_rotate_obj_to_angle [`a76bb70`](https://github.com/lvgl/lvgl/commit/a76bb70a79dfa5b841328f07ede0907c700a039a) +- feat(draw): add draw_ctx->buffer_copy [`d034511`](https://github.com/lvgl/lvgl/commit/d034511bba3a27aa1a29d2e1b612b1adeb4e2ae1) +- feat(dropdown): add lv_dropdown_get_option_index [`9997fb0`](https://github.com/lvgl/lvgl/commit/9997fb00aa60b4478c76fa8387a74ca5b3c595b2) +- feat(tabview) add API to rename tab. [`2c9695a`](https://github.com/lvgl/lvgl/commit/2c9695afb4ed6597ae54806c5eb2a287925343f8) +- feat(indev): send LV_EVENT_PRESS_LOST on release with wait_until_release [`cc18518`](https://github.com/lvgl/lvgl/commit/cc18518e96df63c2a02ee9d423cb7bc23382e5a7) +- feat(style) add 'inherit' and 'initial' CSS properties (#3390) [`9a48de0`](https://github.com/lvgl/lvgl/commit/9a48de0f8b19ec02a44aaf6b330066eed7d0a105) +- feat(draw): improve acceleration for LV_IMG_CF_ALPHA_8BIT (#3337) [`8d3c41d`](https://github.com/lvgl/lvgl/commit/8d3c41d5170dad0455fea3d95b2765db70d3c7c2) +- feat(label): added animation style property to apply it to circular scrolling animation of label widget (#3128) [`340d45c`](https://github.com/lvgl/lvgl/commit/340d45cfa91b7108d43af906fc51b1c431877827) +- feat(gridnav): add lv_gridnav_set_focused [`b6d2daa`](https://github.com/lvgl/lvgl/commit/b6d2daa4935128ca8193863d4deaf58fa40b3154) + +### Performance + +- perf(draw): speed up non normal blend modes [`5a06fce`](https://github.com/lvgl/lvgl/commit/5a06fce472c103b4204002a7932dd6c6d05eb13c) +- perf(draw): minor optimiziation in point transformation [`c6c2864`](https://github.com/lvgl/lvgl/commit/c6c286404898bf559eca6eb5bb007251790c572c) +- perf(layer): cache the layer_type [`ac2e2f1`](https://github.com/lvgl/lvgl/commit/ac2e2f132e264d5f0f0313f4e6adbcf56d937a14) + +### Fixes + +- fix(draw): conflict with external ALIGN define [`3336`](https://github.com/lvgl/lvgl/pull/3336) +- fix(arc): fix bug with LV_ARC_MODE_REVERSE (#3417) [`3418`](https://github.com/lvgl/lvgl/pull/3418) +- fix(fragment): memory leak of fragments #3438 [`3442`](https://github.com/lvgl/lvgl/pull/3442) +- fix(draw): solve memory leaking issue [`3437`](https://github.com/lvgl/lvgl/pull/3437) +- fix(gridnav) correct logic in find_last_focusable [`3423`](https://github.com/lvgl/lvgl/pull/3423) +- fix(examples) correct comment in slider example [`3419`](https://github.com/lvgl/lvgl/pull/3419) +- fix(sdl): add transformation support for the SDL backend [`3403`](https://github.com/lvgl/lvgl/pull/3403) +- fix(bmp): fix with LV_COLOR_16_SWAP [`3412`](https://github.com/lvgl/lvgl/pull/3412) +- fix(sdl): fix LRU, reported in #3402 [`3404`](https://github.com/lvgl/lvgl/pull/3404) +- fix(draw) avoid use-after-free when drawing arcs [`3399`](https://github.com/lvgl/lvgl/pull/3399) +- fix(subpx): fix subpixel rendering font is not displaying bug [`3387`](https://github.com/lvgl/lvgl/pull/3387) +- fix(style): reset style lookup table after gc sweep/lv_deinit [`3385`](https://github.com/lvgl/lvgl/pull/3385) +- fix(benchmark): fix the issue that wrong scene number is used [`3372`](https://github.com/lvgl/lvgl/pull/3372) +- fix(draw): fix colour supports for indexed and alpha-only [`3371`](https://github.com/lvgl/lvgl/pull/3371) +- fix(mem): fix TLSF returning the wrong pointer when the requested size is too large [`3325`](https://github.com/lvgl/lvgl/pull/3325) +- fix(demo): fix warning. [`3344`](https://github.com/lvgl/lvgl/pull/3344) +- fix(config): add LV_GPU_SDL_LRU_SIZE [`3348`](https://github.com/lvgl/lvgl/pull/3348) +- feat(draw): improve acceleration for LV_IMG_CF_ALPHA_8BIT [`3337`](https://github.com/lvgl/lvgl/pull/3337) +- fix(txt): fix returned value of lv_txt_iso8859_1_next(..., NULL) [`3338`](https://github.com/lvgl/lvgl/pull/3338) +- fix(benchmark): remove redundant string for the small screens [`3335`](https://github.com/lvgl/lvgl/pull/3335) +- fix(chart): fix accessing uninitialized point_area [`3327`](https://github.com/lvgl/lvgl/pull/3327) +- fix(config): add LV_LAYER_SIMPLE_BUF_SIZE to Kconfig [`3312`](https://github.com/lvgl/lvgl/pull/3312) +- fix(config): Keep the sequence of widget in order [`3314`](https://github.com/lvgl/lvgl/pull/3314) +- fix(config): fix typo in LV_USE_PERF_MONITOR and LV_USE_MEM_MONITOR [`3313`](https://github.com/lvgl/lvgl/pull/3313) +- fix(refr): initializing row_cnt is to silence the warning [`3309`](https://github.com/lvgl/lvgl/pull/3309) +- fix(meter): fix typo [`3308`](https://github.com/lvgl/lvgl/pull/3308) +- fix(draw): update Makefiles [`3303`](https://github.com/lvgl/lvgl/pull/3303) +- fix(lodepng): fix NULL pointer access [`3307`](https://github.com/lvgl/lvgl/pull/3307) +- fix(Kconfig): change the type of LV_FS_STDIO_LETTER from string to int [`3282`](https://github.com/lvgl/lvgl/pull/3282) +- fix(demo): fix Wformat warning [`3290`](https://github.com/lvgl/lvgl/pull/3290) +- fix(snapshot): add missing ASSERT checks [`3292`](https://github.com/lvgl/lvgl/pull/3292) +- fix(Kconfig): Add LV_USE_GRIDNAV and LV_USE_FRAGMENT to Kconfig [`3270`](https://github.com/lvgl/lvgl/pull/3270) +- fix(msgbox): do not execute init obj when obj == NULL [`3264`](https://github.com/lvgl/lvgl/pull/3264) +- fix(menu): use LV_ASSERT_MALLOC check for new_node [`3263`](https://github.com/lvgl/lvgl/pull/3263) +- fix(canvas):image cache may expire after set canvas's buff [`3267`](https://github.com/lvgl/lvgl/pull/3267) +- fix(obj_style): prevent access to class null pointer [`3252`](https://github.com/lvgl/lvgl/pull/3252) +- fix(png): fix possible memory leak when decoding fails [`3249`](https://github.com/lvgl/lvgl/pull/3249) +- fix(libs): fix possible buffer underflow caused by extension matching [`3250`](https://github.com/lvgl/lvgl/pull/3250) +- fix(fs): track multiple directory handles with win32 backends [`3243`](https://github.com/lvgl/lvgl/pull/3243) +- fix(png): use LV_IMG_CF_TRUE_COLOR_ALPHA instead of LV_IMG_CF_RAW_ALPHA [`3212`](https://github.com/lvgl/lvgl/pull/3212) +- fix(Keil-AC5): slience warnings in Keil-AC5 [`3221`](https://github.com/lvgl/lvgl/pull/3221) +- fix(meter): fix infinite loop caused by loop variable type mismatch [`3232`](https://github.com/lvgl/lvgl/pull/3232) +- fix(chart): remove invalid decision branches [`3231`](https://github.com/lvgl/lvgl/pull/3231) +- fix(gradient): assert before dividing by 0 [`3228`](https://github.com/lvgl/lvgl/pull/3228) +- fix(calendar): fix infinite loop caused by loop variable type mismatch [`3230`](https://github.com/lvgl/lvgl/pull/3230) +- fix(flex): assert before dividing by 0 [`3237`](https://github.com/lvgl/lvgl/pull/3237) +- fix(hal): fix LV_ASSERT_MALLOC wrong placement [`3236`](https://github.com/lvgl/lvgl/pull/3236) +- fix(disp): fix missing null pointer judgment [`3238`](https://github.com/lvgl/lvgl/pull/3238) +- fix(obj_class): fix possible memory leak when the default disp is NULL [`3235`](https://github.com/lvgl/lvgl/pull/3235) +- fix(draw_sw_letter): fix incorrect use of sizeof for a pointer [`3234`](https://github.com/lvgl/lvgl/pull/3234) +- fix(indev): fix null pointer access caused by typo [`3229`](https://github.com/lvgl/lvgl/pull/3229) +- fix(event): remove invalid decision branches [`3233`](https://github.com/lvgl/lvgl/pull/3233) +- fix(draw_mask): remove invalid decision branches [`3225`](https://github.com/lvgl/lvgl/pull/3225) +- fix(spinbox): remove invalid judgment [`3227`](https://github.com/lvgl/lvgl/pull/3227) +- fix(gradient): remove invalid decision branches [`3226`](https://github.com/lvgl/lvgl/pull/3226) +- fix(txt): return 0 if letter_uni is out of range [`3224`](https://github.com/lvgl/lvgl/pull/3224) +- fix(calendar): fix possible array access out of bounds [`3223`](https://github.com/lvgl/lvgl/pull/3223) +- fix(style): remove useless null pointer judgment [`3222`](https://github.com/lvgl/lvgl/pull/3222) +- fix(obj): scrolling exception when use lv_obj_set_parent() [`3210`](https://github.com/lvgl/lvgl/pull/3210) +- fix(libs): fix memcmp memory access overflow [`3205`](https://github.com/lvgl/lvgl/pull/3205) +- fix(png): fix possible file leaks [`3204`](https://github.com/lvgl/lvgl/pull/3204) +- fix(docs): rename task-handler.md to timer-handler.md [`3203`](https://github.com/lvgl/lvgl/pull/3203) +- fix(lru): Fix use of undefined variables [`3181`](https://github.com/lvgl/lvgl/pull/3181) +- fix(rt-thread): Sconscript use LOCAL_CFLAGS to replace LOCAL_CCFLAGS [`3196`](https://github.com/lvgl/lvgl/pull/3196) +- fix(make) make files under draw/gpu [`3202`](https://github.com/lvgl/lvgl/pull/3202) +- fix(docs-CN):fix broken links to docs in dir get-started [`3195`](https://github.com/lvgl/lvgl/pull/3195) +- fix broken links to docs in dir get-started [`3190`](https://github.com/lvgl/lvgl/pull/3190) +- fix(indev): fix warning about formatting uint32_t with %d [`3193`](https://github.com/lvgl/lvgl/pull/3193) +- fix(Kconfig): move LV_USE_IMGFONT to others menu [`3176`](https://github.com/lvgl/lvgl/pull/3176) +- fix(draw): src_buf_tmp will be NULL when LV_DRAW_COMPLEX is '0' [`3163`](https://github.com/lvgl/lvgl/pull/3163) +- fix(span): align the baselines [`3164`](https://github.com/lvgl/lvgl/pull/3164) +- fix(menu): fix crash on delete [`3154`](https://github.com/lvgl/lvgl/pull/3154) +- fix(Kconfig): add missing LV_USE_THEME_MONO [`3146`](https://github.com/lvgl/lvgl/pull/3146) +- fix(demo/stress): remove the unused assets [`3139`](https://github.com/lvgl/lvgl/pull/3139) +- fix(jpg): swap high and low bytes when macro LV_COLOR_16_SWAP is 1 [`3138`](https://github.com/lvgl/lvgl/pull/3138) +- fix(script): in lv_conf_internal fix some widget dependencies when using Kconfig [`3119`](https://github.com/lvgl/lvgl/pull/3119) +- fix(demo): minor fix for benchmark [`3114`](https://github.com/lvgl/lvgl/pull/3114) +- fix(misc): in lv_map() handle if maximum value less than minimum value [`3113`](https://github.com/lvgl/lvgl/pull/3113) +- fix(extra): adjust image decoder initialization order [`3085`](https://github.com/lvgl/lvgl/pull/3085) +- fix(chart): optimize chart invalidation [`3028`](https://github.com/lvgl/lvgl/pull/3028) +- fix(refr): fix performance monitor NULL pointer access [`3105`](https://github.com/lvgl/lvgl/pull/3105) +- fix(misc): Remove duplicate declaration of _lv_log_add. [`3103`](https://github.com/lvgl/lvgl/pull/3103) +- fix(gridnav): get key code from the actual event [`3101`](https://github.com/lvgl/lvgl/pull/3101) +- fix(draw_rect): delete __STDC_VERSION__ to ensure C++ compatibility [`3099`](https://github.com/lvgl/lvgl/pull/3099) +- fix(font):draw placeholder if get_glyph_dsc() returns false [`3000`](https://github.com/lvgl/lvgl/pull/3000) +- fix(conf): work around GCC bug [`3082`](https://github.com/lvgl/lvgl/pull/3082) +- fix(fsdrv): replacing sprintf with lv_snprintf for safety [`3079`](https://github.com/lvgl/lvgl/pull/3079) +- fix(cmsis-pack): add PIDX for cmsis-pack [`3064`](https://github.com/lvgl/lvgl/pull/3064) +- feat(gpu): add SWM341 gpu support (synwit) [`07b7eea`](https://github.com/lvgl/lvgl/commit/07b7eea56c048a0654c254cadebee8caf5f7933b) +- fix(fs): fix cached read and add unit test for lv_fs [`98660a8`](https://github.com/lvgl/lvgl/commit/98660a861d874d29e8356452baff21788b6a9ef1) +- fix(table): invalidate only the changed cell [`306fa19`](https://github.com/lvgl/lvgl/commit/306fa1968238fe33dd95e2865e147bceb4706ad5) +- fix(draw): handle non BLEND_MODE_NORMAL for ARGB drawing [`9ac8ce6`](https://github.com/lvgl/lvgl/commit/9ac8ce69f67234563d4254e29e1903a638bb8f4e) +- fix(draw): revert handling of style_opa on not MAIN parts [`51a7a61`](https://github.com/lvgl/lvgl/commit/51a7a61df365685a7cd04b0512ba3844dcfa7209) +- fix(draw): clip the bg img to the rectangle's area in lv_draw_sw_rect [`77d726e`](https://github.com/lvgl/lvgl/commit/77d726efb2467ff86691dee487f97aac79ea45c2) +- fix(obj): fix LV_OBJ_FLAG_OVERFLOW_VISIBLE [`c742f2c`](https://github.com/lvgl/lvgl/commit/c742f2c8888ad0102cebe91b4069b376068baa81) +- fix(scroll): do not fire scroll begin/end event on every scroll step [`25ce6e3`](https://github.com/lvgl/lvgl/commit/25ce6e3ae9e144e2df5dad34475dda3542015f6a) +- fix(indev): do not send keys to objects in disabled state [`b0a46c4`](https://github.com/lvgl/lvgl/commit/b0a46c4837c922cb1303ef768da3209e7efa45ae) +- fix(disp): make lv_scr_load work better with lv_scr_load_anim and auto_del = true [`52287fd`](https://github.com/lvgl/lvgl/commit/52287fd64ad59c35794d1f4486b777f4eb686abc) +- fix(draw): create intermediate layer for blend modes too [`8b15007`](https://github.com/lvgl/lvgl/commit/8b150075681455c6424ddd536e991307ac828eb4) +- fix(group): in lv_group_remove() fix if the object to focus is deleted [`72cb683`](https://github.com/lvgl/lvgl/commit/72cb683c799f65cd4fbae22dafc3a35c123bb66b) +- fix(draw): be sure angle values are in the correct range [`e624b90`](https://github.com/lvgl/lvgl/commit/e624b90db3515816eee8f6ce72677350487f3a02) +- fix(scroll): send LV_EVENT_SCROLL_BEGIN/END with no animation too [`777fe1e`](https://github.com/lvgl/lvgl/commit/777fe1ea706f38b82ab8ee180548ecb85334a469) +- fix(arc): fix arc image drawing issue [`7153e3f`](https://github.com/lvgl/lvgl/commit/7153e3f8b7b660474b8907954c80e21eb2f0bd21) +- fix(refr): fix memory write out of bounds issue [`13c99fc`](https://github.com/lvgl/lvgl/commit/13c99fc4b66d3e8d0ffcd6fda21d3b5a40b0771c) +- fix(gif): fix rare issue when drawing the gif's background [`b1e2c06`](https://github.com/lvgl/lvgl/commit/b1e2c0665829aa489f444169ce80fcd7cdf487bb) +- fix(chart): fix misaligned horizontal tick lines on bar charts [`4572a0c`](https://github.com/lvgl/lvgl/commit/4572a0c6c92b126e229ce9aada551d71b4f4296b) +- fix(font): use 0 width for non printable characters [`7cf5709`](https://github.com/lvgl/lvgl/commit/7cf5709b0669ab64e437a796c50f6bdb97b9d0d5) +- revert(group): 72cb683c799f65cd4fbae22dafc3a35c123bb66b [`b7b22c1`](https://github.com/lvgl/lvgl/commit/b7b22c190c6d9e11a841289708f55be0be86830f) +- fix(keyboard): don't show popovers on map change [`ac202e7`](https://github.com/lvgl/lvgl/commit/ac202e7b96510b9b12beb8a1eee3dfd65bc56a3d) +- fix(refr): consider masks with LV_OBJ_FLAG_OVERFLOW_VISIBLE [`a7f9dfa`](https://github.com/lvgl/lvgl/commit/a7f9dfa8c3e4fd56cc2db5c3f3926b9391d3661f) +- fix(draw): fix the calculation of the transformed coordinates [`76de7c6`](https://github.com/lvgl/lvgl/commit/76de7c6b7bce6da62f5e961ee477bfa324675683) +- fix(style): fix heap use after free with transition styles [`d9ae58b`](https://github.com/lvgl/lvgl/commit/d9ae58b6977ccfda90e02fa6f5b852d398f8600a) +- fix(tabview, tileview): fix scrolling [`22854ff`](https://github.com/lvgl/lvgl/commit/22854ff3fba236f50893221805c9cc4d378baaca) +- fix(draw): fix disp_bg_img drawing [`dea75d9`](https://github.com/lvgl/lvgl/commit/dea75d9b4a90601bf81bf69d533c4f13e62aa88c) +- fix(textarea): fix max length handling [`127d8e8`](https://github.com/lvgl/lvgl/commit/127d8e82e344cd8762672e787b1ee06390050b65) +- fix(btnmatrix): fix extra draw size calculation to not clip shadow [`7ada130`](https://github.com/lvgl/lvgl/commit/7ada1301c2ee113a5184618538b979f6d9912239) +- fix(indev): scroll_ throw_vect cannot converge to 0 when vect is negative [`e5c11f1`](https://github.com/lvgl/lvgl/commit/e5c11f1f68275d294d5b8892366aa424a5a14bca) +- fix(theme): make the basic theme even more simpler [`62d6f3c`](https://github.com/lvgl/lvgl/commit/62d6f3c533ca6d13fce3056074c1e44ffea355b1) +- fix(color): color mix rounding error [`523062b`](https://github.com/lvgl/lvgl/commit/523062b9ee8a106ad4b3b7bd0ee7baca743f2e5f) +- fix(style): _lv_style_prop_lookup_flags tell all flags for LV_STYLE_PROP_ANY [`e53f602`](https://github.com/lvgl/lvgl/commit/e53f60259c01ab1243b0cf56eb228b7f5eedc203) +- fix(list): use for icon [`b171f7d`](https://github.com/lvgl/lvgl/commit/b171f7dde2a895142385ea1275f3f51255cb2811) +- fix(layout): fix the handling of FLOATING children [`48728a7`](https://github.com/lvgl/lvgl/commit/48728a7839d6859d7d6fc4f86f5fbcbcd9939348) +- fix(style): make color filter inherited [`5546b9d`](https://github.com/lvgl/lvgl/commit/5546b9d740de8d774071328251413ec29c12d288) +- fix(spinbox): set its default width in its class [`3d92972`](https://github.com/lvgl/lvgl/commit/3d9297269598ca40e2f8dd2d8f31150d41e94cb8) +- fix: fix warning [`6c00552`](https://github.com/lvgl/lvgl/commit/6c005526295aeb277edad42b3a05b0c7e6d72eaf) +- fix(draw): fix transformations on subdivided areas [`cbff8e8`](https://github.com/lvgl/lvgl/commit/cbff8e83e50fecc2b4b43d661deb91d8d81d6696) +- fix(slider): fix left knob in ranged mode [`17f5e0a`](https://github.com/lvgl/lvgl/commit/17f5e0accb15871040a6225a9c0471ceadd6dc16) +- fix(Kconfig): allow unchecking LV_CONF_SKIP [`f3a07a3`](https://github.com/lvgl/lvgl/commit/f3a07a3e8a21f3f9f2c48a2803b8bd991968cb05) +- fix(style): fix using width for both width and height in radius transition [`6acbdaa`](https://github.com/lvgl/lvgl/commit/6acbdaa53d941b891db377e65111bd999f04631d) +- fix(dropdown): fix scrolling when options are CENTER aligned [`e651383`](https://github.com/lvgl/lvgl/commit/e651383688dd29ab2e990cd997118435832d959c) +- fix(grid): fix dead branch [`46bf27d`](https://github.com/lvgl/lvgl/commit/46bf27d50bb668bdd1f84489cb70986ee0ef9fab) +- fix(hal): disable driver->screen_transp by default regardless to LV_COLOR_SCREEN_TRANSP [`ff7204e`](https://github.com/lvgl/lvgl/commit/ff7204ecadd10132b436b11c8948b9a882b58798) +- fix(theme): fix mono theme init [`5ec6694`](https://github.com/lvgl/lvgl/commit/5ec6694f7874f3c99a764e7ee2d45a933865c91c) +- fix(bmp) fix typo in BPP condition [`cbc38af`](https://github.com/lvgl/lvgl/commit/cbc38afb3a0d3ca02159ab89242749809e64df0c) +- fix(theme): in the basic theme show the textarea cursor only in focuses state [`bb03fb1`](https://github.com/lvgl/lvgl/commit/bb03fb197c7083680fd7dc730794a52561cabfd4) +- fix(draw): fix img recolor [`23eecce`](https://github.com/lvgl/lvgl/commit/23eecce008dacd8e5f5d56d017e4e5705f0c31e6) +- fix(theme) add disabled style to textarea in the default theme [`00f6759`](https://github.com/lvgl/lvgl/commit/00f67597d3c87ff811e5e682c10ef20227218651) +- fix(meter): improve the precision of tick line drawing [`0255c6d`](https://github.com/lvgl/lvgl/commit/0255c6dd39640d7ec639cbd339a0fbdcdfb2bb82) +- fix(gpu): fix warning with NXP GPU [`6be43b8`](https://github.com/lvgl/lvgl/commit/6be43b83b3dc9340263552167dbbb07c1069bdb0) +- fix(color): compensate rounding error during blending [`42d9c07`](https://github.com/lvgl/lvgl/commit/42d9c07eeb0abfdbf8746da3569a5f8bc156ae71) +- fix(examples) use type-safe function for retrieving event param [`71d535d`](https://github.com/lvgl/lvgl/commit/71d535defd730fc20ed8d57faa2550781be4f3d7) +- fix(draw) ensure variable is initialized to avoid warning [`276f28a`](https://github.com/lvgl/lvgl/commit/276f28a8a2f4ac2f6268a4363879faa6296e14ad) +- feat(draw): improve acceleration for LV_IMG_CF_ALPHA_8BIT (#3337) [`8d3c41d`](https://github.com/lvgl/lvgl/commit/8d3c41d5170dad0455fea3d95b2765db70d3c7c2) +- fix(spinbox): rename lv_spinbox_set_pos to lv_spinbox_set_cursor_pos [`a99eb6b`](https://github.com/lvgl/lvgl/commit/a99eb6bb6ae12f3fcb86f5268a0c000fb165e159) +- fix(layout): use uint16_t LV_LAYOUT_FLEX/GRID [`c596a36`](https://github.com/lvgl/lvgl/commit/c596a36d9ecf92ae5ce1ecc812210bf3a7df4999) +- fix(event) avoid using a boolean as a pointer [`06fff4b`](https://github.com/lvgl/lvgl/commit/06fff4b9bac35d63564de87fa63f7bedd8a0f9f2) +- fix(theme): properly disable transitions if LV_THEME_DEFAULT_TRANSITION_TIME==0 [`242112b`](https://github.com/lvgl/lvgl/commit/242112b2df8b6cc12aa9920cc3b2fdc9a11d807f) +- fix(scroll): fix scroll to view to the left [`7c74f65`](https://github.com/lvgl/lvgl/commit/7c74f6556abbc299a79b1490c06151a43c902f61) +- fix(fs): mark the read cache as invalid by default [`54f9987`](https://github.com/lvgl/lvgl/commit/54f99870b3cac619fb7057618637d7ee19d58bb3) +- fix(menu): fix crash on delete (#3154) [`a6c4c13`](https://github.com/lvgl/lvgl/commit/a6c4c134902f9a4c156672a70108e809b58fa18c) +- fix(roller): fix unexpected jump in infinite mode [`18f2d78`](https://github.com/lvgl/lvgl/commit/18f2d78728c758179e4ef01ebc632da4e1263be7) +- fix(conf): work around GCC bug (#3082) [`c6b34bc`](https://github.com/lvgl/lvgl/commit/c6b34bc85bb6f5e57e1c87857e03d1a0bd225e4c) + +### Examples +- example(ime_pinyin): improved lv_example_ime_pinyin_1 [`3428`](https://github.com/lvgl/lvgl/pull/3428) +- example(imgfont): fix lvgl.h include path [`3405`](https://github.com/lvgl/lvgl/pull/3405) +- example(btnmatrix): update lv_example_btnmatrix_2 to expicitly check which part is drawn [`6b2eac1`](https://github.com/lvgl/lvgl/commit/6b2eac1dd70df62916b46cee8d4b981ff088b1a7) +- example(slider): make lv_example_slider_3 work with dark theme too [`4a766c5`](https://github.com/lvgl/lvgl/commit/4a766c516db7c2572a075ec5ffe748d30af8c7b9) +- example(span): avoid ambiguous meaing [`7bb09e3`](https://github.com/lvgl/lvgl/commit/7bb09e358026aff3d55d881237624baac77db890) +- demo(benchmark): add LV_DEMO_BENCHMARK_RGB565A8 option [`afaa8c9`](https://github.com/lvgl/lvgl/commit/afaa8c93006a88db9f115b2b318eef790928d2a6) + +### Docs + +- docs(indev): add comment in input device part [`3422`](https://github.com/lvgl/lvgl/pull/3422) +- docs(slider) mention that VALUE_CHANGED is not sent on release [`3397`](https://github.com/lvgl/lvgl/pull/3397) +- docs(readme): add version portuguese brazilian [`3349`](https://github.com/lvgl/lvgl/pull/3349) +- docs(pc-simulator): add MDK with FastModel [`3318`](https://github.com/lvgl/lvgl/pull/3318) +- docs(intro): update for v8.2.0 [`3316`](https://github.com/lvgl/lvgl/pull/3316) +- docs(readme) update link to the PlatformIO Registry [`3296`](https://github.com/lvgl/lvgl/pull/3296) +- docs(gesture): fix typo lv_indev_act() -> lv_indev_get_act() [`3291`](https://github.com/lvgl/lvgl/pull/3291) +- docs(scroll) add information about scroll coordinates [`3088`](https://github.com/lvgl/lvgl/pull/3088) +- docs(msgbox) fix typo [`3095`](https://github.com/lvgl/lvgl/pull/3095) +- docs(scroll): use LV_DIR_VER instead of LV_DIR_TOP [`3066`](https://github.com/lvgl/lvgl/pull/3066) +- docs: rearrange the get-started section [`8a81532`](https://github.com/lvgl/lvgl/commit/8a8153219163b689e8f96d6a97c1f128eefd7ce2) +- docs: add section for renderers and gpus [`378aaa6`](https://github.com/lvgl/lvgl/commit/378aaa637bdcaef8f06667ab9d56c914e0a61beb) +- docs collapse APIs by default [`ebd20af`](https://github.com/lvgl/lvgl/commit/ebd20af6e9cbd68230f49b6c85d940569a7db81c) +- docs(images): fix notes about breaking change inf v8.2 [`9a1e385`](https://github.com/lvgl/lvgl/commit/9a1e385b2b3498ed70704bf0ed33e4bd263747d8) +- docs(sim): add link to qt-creator [`88bbef1`](https://github.com/lvgl/lvgl/commit/88bbef14bf69725a1ab62bffa6ab79355ea31c2d) +- docs(chart): describe how to set the space between columns [`746917d`](https://github.com/lvgl/lvgl/commit/746917dcca74c53f6b2dc3849c9d588a0bf91b60) +- docs(README): fix broken link [`c2c44c6`](https://github.com/lvgl/lvgl/commit/c2c44c68ee69cdee16fce7833cbf6d6dc0d551ab) +- docs(examples) avoid redirects when loading examples [`d367bb7`](https://github.com/lvgl/lvgl/commit/d367bb7cf17dc34863f4439bba9b66a820088951) +- docs(gesture): describe how prevent sending events after a gesture [`65db5c9`](https://github.com/lvgl/lvgl/commit/65db5c99e05f86d2ec69ebae9f1fc50fe30a3145) +- docs(get-started): add quick-overview to the index [`91ebf81`](https://github.com/lvgl/lvgl/commit/91ebf810aacfe972f0ae140a1a61031eea9cda0c) +- docs(others): add imgfont to the index [`656a0e5`](https://github.com/lvgl/lvgl/commit/656a0e5167dca8c6c29497130e374080397fa45f) + +### CI and tests + +- ci(slider): add unit test [`3198`](https://github.com/lvgl/lvgl/pull/3198) +- test(line): add unit tests for line widget [`3104`](https://github.com/lvgl/lvgl/pull/3104) +- test(table): replicate issue when reducing table cells [`3121`](https://github.com/lvgl/lvgl/pull/3121) +- test(textarea): add unit test [`3074`](https://github.com/lvgl/lvgl/pull/3074) +- test(table): add unit tests [`3040`](https://github.com/lvgl/lvgl/pull/3040) +- ci(docs) replace use of sed with proper configuration variables [`1816fa5`](https://github.com/lvgl/lvgl/commit/1816fa576cc40ef1795e95ed127d93df5390b0cf) +- ci add Makefile test [`ea79cee`](https://github.com/lvgl/lvgl/commit/ea79cee01a6bec9b3ce5b6c232dd7ca0d020d5c9) +- test(mem) add test for #3324 [`9700664`](https://github.com/lvgl/lvgl/commit/97006647d8ed3af65fd2113ddf01c7882a4dba19) +- test(img): fix image error diff handler [`48d87e1`](https://github.com/lvgl/lvgl/commit/48d87e1ed2d362e9c3bd84eb60c311ad6519ae85) +- ci update docs builder to work with Python 3.10 [`a3d66c9`](https://github.com/lvgl/lvgl/commit/a3d66c9b67d226f8ab4555616ecf2ea62e307962) +- ci make sure LVGL assertions cause tests to fail [`b83c5aa`](https://github.com/lvgl/lvgl/commit/b83c5aa9bc4a278a6758f76e77ac9c403e483948) +- ci remove formatting comment [`d345f76`](https://github.com/lvgl/lvgl/commit/d345f76d02a23d94550b1b60be90585f6f5276b7) +- ci don't run workflows twice on PRs [`fcc1152`](https://github.com/lvgl/lvgl/commit/fcc1152f9c14494f128f26a6b47b00864a70c741) +- ci bump test timeout to 30 seconds [skip ci] [`85e3e23`](https://github.com/lvgl/lvgl/commit/85e3e2387845bd29c9f85b406623e41d36b66808) +- ci limit tests to 15 seconds [`003f18f`](https://github.com/lvgl/lvgl/commit/003f18f86c5c728920575cf1d34dd0f811607a51) +- ci(makefile) fix typo in GitHub action [`a101e70`](https://github.com/lvgl/lvgl/commit/a101e70ebd4120549236abd637049678dd6800e7) +- ci(switch): fix mem leak test [`8481e3a`](https://github.com/lvgl/lvgl/commit/8481e3a33bc3313b679babac31e6193ec4319bcd) +- ci(stale) bump action version [`5977eef`](https://github.com/lvgl/lvgl/commit/5977eeff3c559c0473d5abd8a99687eeb4659c61) +- ci use GCC problem matcher on ARM tests as well [`9fcefe5`](https://github.com/lvgl/lvgl/commit/9fcefe5a49a024054a3cee08d273b8fe5cf8840e) + + +## [v8.2.0](https://github.com/littlevgl/lvgl/compare/v8.1.0...v8.2.0) 31 January 2022 + + +### Overview + +Among many fixes and minor updates these are the most important features in v8.2.0: +- Abstract render layer to make it easier to attach external draw engines +- Add `LV_FLAD_OVERFLOW_VISIBLE`. If enabled the children of an object won't be clipped to the boundary of the object +- Add ffmpeg decoder support to play videos and open a wide variety of image formats +- Add font fallback support +- Add gradient dithering support +- Add "monkey test" +- Add cmsis-pack support +- Add Grid navigation (`lv_gridnav`) + +The GPU support for NXP microcontrollers is still not updated to the new draw architecture. See [#3052](https://github.com/lvgl/lvgl/issues/3052) + +### Breaking Changes + +- :warning: feat(fs): add caching option for lv_fs-read [`2979`](https://github.com/littlevgl/lvgl/pull/2979) +- :warning: feat(span): lv_spangroup_get_expand_width() adds a parameter [`2968`](https://github.com/littlevgl/lvgl/pull/2968) +- :warning: arch(draw): allow replacing the draw engine [`db53ea9`](https://github.com/littlevgl/lvgl/commit/db53ea925c9502b20f38db0fc30c4ef599bdfc33) +- :warning: indexed images are not chroma keyed. Use the alpha chaneel instead. + +### Architectural + +- arch(draw): separate SW renderer to allow replacing it [`2803`](https://github.com/littlevgl/lvgl/pull/2803) +- arch: merge lv_demos [`5414652`](https://github.com/littlevgl/lvgl/commit/5414652a4108dc6761b859fbb48a43e37e67a37a) +- arch(sdl): migrated to use new backend architecture [`2840`](https://github.com/littlevgl/lvgl/pull/2840) +- arch(env): move rt-thread into env_support folder [`3025`](https://github.com/littlevgl/lvgl/pull/3025) +- arch(env): arch(env): move the cmake folder into the env_support folder [`773d50f`](https://github.com/littlevgl/lvgl/commit/773d50f0acafa279fa7440ddcf15e80cf07eda54) +- arch(env): move the zephyr folder into the env_support folder [`4bd1e7e`](https://github.com/littlevgl/lvgl/commit/4bd1e7e9f7acc5295b65440477e76a048094afbf) + +### New Features + +- feat(cmsis-pack): prepare for lvgl v8.2.0 release [`3062`](https://github.com/littlevgl/lvgl/pull/3062) +- feat(gridnav): add lv_gridnav [`2911`](https://github.com/littlevgl/lvgl/pull/2911) +- feat: update the cmsis-pack to 0.8.3 [`3021`](https://github.com/littlevgl/lvgl/pull/3021) +- feat(sdl): support rounded images [`3012`](https://github.com/littlevgl/lvgl/pull/3012) +- feat(cmsis-pack): add cmsis-pack support [`2993`](https://github.com/littlevgl/lvgl/pull/2993) +- feat(event): add preprocessing and stop bubbling features for events [`3003`](https://github.com/littlevgl/lvgl/pull/3003) +- feat(draw): add gradient dithering support [`2872`](https://github.com/littlevgl/lvgl/pull/2872) +- feat(symbols): add guards to LV_SYMBOL_* to allow redefining them [`2973`](https://github.com/littlevgl/lvgl/pull/2973) +- feat(obj): subdivide LV_OBJ_FLAG_SCROLL_CHAIN into ...CHAIN_HOR and ...CHAIN_VER [`2961`](https://github.com/littlevgl/lvgl/pull/2961) +- feat(draw): add draw_bg callback to draw_ctx #2934 [`2935`](https://github.com/littlevgl/lvgl/pull/2935) +- feat(docs): add Chinese readme [`2919`](https://github.com/littlevgl/lvgl/pull/2919) +- feat(txt): add used_width parameter to _lv_txt_get_next_line() [`2898`](https://github.com/littlevgl/lvgl/pull/2898) +- feat(others) add monkey test [`2885`](https://github.com/littlevgl/lvgl/pull/2885) +- feat(rlottie): add animation control options [`2857`](https://github.com/littlevgl/lvgl/pull/2857) +- feat(lv_hal_indev): add missing lv_indev_delete() [`2854`](https://github.com/littlevgl/lvgl/pull/2854) +- feat(freetype): optimize memory allocation [`2849`](https://github.com/littlevgl/lvgl/pull/2849) +- feat(Kconfig): add FreeType config [`2846`](https://github.com/littlevgl/lvgl/pull/2846) +- feat(widgets): add menu widget [`2603`](https://github.com/littlevgl/lvgl/pull/2603) +- feat(refr): add reset function for FPS statistics [`2832`](https://github.com/littlevgl/lvgl/pull/2832) +- feat(Kconfig): add monitor position configuration [`2834`](https://github.com/littlevgl/lvgl/pull/2834) +- feat(examples) add micropython versions of the external library examples [`2762`](https://github.com/littlevgl/lvgl/pull/2762) +- feat(freetype): support bold and italic [`2824`](https://github.com/littlevgl/lvgl/pull/2824) +- feat(font) add fallback support and mem. font load option to FreeType [`2796`](https://github.com/littlevgl/lvgl/pull/2796) +- feat(lib) add ffmpeg video and image decoder [`2805`](https://github.com/littlevgl/lvgl/pull/2805) +- feat(obj): add LV_OBJ_FLAG_OVERFLOW_VISIBLE [`e7ac0e4`](https://github.com/littlevgl/lvgl/commit/e7ac0e41988e5fda772e17292c05d65bcaf58394) +- feat(scrollbar): add more control over scrollbar paddings [`4197b2f`](https://github.com/littlevgl/lvgl/commit/4197b2fd6ebec4b4dcfeeb2c41b724e09b77d1d0) +- feat(dropdown): keep the list on open/close for simpler styling [`9d3134b`](https://github.com/littlevgl/lvgl/commit/9d3134b66e40882c232afa79498c41294603f437) +- feat(qrcode) use destructor instead of lv_qrcode_delete() [`318edd8`](https://github.com/littlevgl/lvgl/commit/318edd8a3f61a65be3ed15a97c0870de0ad4125a) +- feat(disp) allow decoupling the disp_refr timer [`85cc84a`](https://github.com/littlevgl/lvgl/commit/85cc84ad947786bb3d4857290503047946a55c43) +- feat(obj): add lv_obj_get_event_user_data() [`53ececc`](https://github.com/littlevgl/lvgl/commit/53ececc5ec6f62ee4ab47ea66a847679e3836f52) +- feat(obj) add LV_OBJ_FLAG_SCROLL_WITH_ARROW [`70327bd`](https://github.com/littlevgl/lvgl/commit/70327bdb2d758336340c5a3b378ab876bfee2d53) +- feat(slider): consider ext_click_area on the knob with LV_OBJ_FLAG_ADV_HITTEST [`9d3fb41`](https://github.com/littlevgl/lvgl/commit/9d3fb418969c13b93f01a6b0342a1cd8d02e9b6c) + +### Performance + +- perf(sdl): optimize the use of SDL_RenderSetClipRect [`2941`](https://github.com/littlevgl/lvgl/pull/2941) +- perf(color): add faster lv_color_hex function [`2864`](https://github.com/littlevgl/lvgl/pull/2864) + +### Fixes + +- fix(micropython) update examples for new API [`3059`](https://github.com/littlevgl/lvgl/pull/3059) +- fix: increase default value of LV_MEM_SIZE for lv_demo_widgets #3057 [`3058`](https://github.com/littlevgl/lvgl/pull/3058) +- fix(cmsis-pack): fix issue #3032 [`3056`](https://github.com/littlevgl/lvgl/pull/3056) +- fix(porting): add missing function prototypes [`3054`](https://github.com/littlevgl/lvgl/pull/3054) +- fix(kconfig): add missing default values [`3050`](https://github.com/littlevgl/lvgl/pull/3050) +- fix(canvas): force canvas to use sw draw [`3045`](https://github.com/littlevgl/lvgl/pull/3045) +- fix(rt-thread): use ARCH_CPU_BIG_ENDIAN to replace RT_USING_BIG_ENDIAN [`3044`](https://github.com/littlevgl/lvgl/pull/3044) +- fix(gradient): general cleanup and fix for alignment issues [`3036`](https://github.com/littlevgl/lvgl/pull/3036) +- fix(draw): rendering issues for vertical gradient with and without dithering [`3034`](https://github.com/littlevgl/lvgl/pull/3034) +- fix uninitialized variable [`3033`](https://github.com/littlevgl/lvgl/pull/3033) +- fix(lru): lower dependency for standard C functions [`3024`](https://github.com/littlevgl/lvgl/pull/3024) +- fix(env_support): move cmsis-pack to env_support folder [`3026`](https://github.com/littlevgl/lvgl/pull/3026) +- fix(doc): full covering opacity is 255, not 256 [`3022`](https://github.com/littlevgl/lvgl/pull/3022) +- fix uninitialized variables [`3023`](https://github.com/littlevgl/lvgl/pull/3023) +- fix various issues for esp32 [`3007`](https://github.com/littlevgl/lvgl/pull/3007) +- fix(sdl): fix clipped image drawing [`2992`](https://github.com/littlevgl/lvgl/pull/2992) +- fix(draw): missed bg_color renaming in the draw function [`3002`](https://github.com/littlevgl/lvgl/pull/3002) +- fix(porting): fix typo and an unmatched prototype [`2998`](https://github.com/littlevgl/lvgl/pull/2998) +- fix(conf) add missing LV_LOG_LEVEL default definition [`2996`](https://github.com/littlevgl/lvgl/pull/2996) +- fix(refr): crash if full_refresh = 1 [`2999`](https://github.com/littlevgl/lvgl/pull/2999) +- fix(Kconfig): adapt to lvgl's built-in demos [`2989`](https://github.com/littlevgl/lvgl/pull/2989) +- fix(Makefile): compilation errors [`2944`](https://github.com/littlevgl/lvgl/pull/2944) +- fix(rlottie): fix variable name [`2971`](https://github.com/littlevgl/lvgl/pull/2971) +- fix(group): in lv_group_del() remove group from indev (lvgl#2963) [`2964`](https://github.com/littlevgl/lvgl/pull/2964) +- fix(obj): old parent's scroll is not updated in lv_obj_set_parent() [`2965`](https://github.com/littlevgl/lvgl/pull/2965) +- fix(fatfs) add missing cast [`2969`](https://github.com/littlevgl/lvgl/pull/2969) +- fix(snapshot) fix memory leak [`2970`](https://github.com/littlevgl/lvgl/pull/2970) +- fix(examples) move event callback registration outside loop in `lv_example_event_3` [`2959`](https://github.com/littlevgl/lvgl/pull/2959) +- fix(canvas): off by one error in size check in lv_canvas_copy_buf [`2950`](https://github.com/littlevgl/lvgl/pull/2950) +- fix(indev) add braces to avoid compiler warning [`2947`](https://github.com/littlevgl/lvgl/pull/2947) +- fix: fix parameter order in function prototypes [`2929`](https://github.com/littlevgl/lvgl/pull/2929) +- fix(style):add const qualifier for lv_style_get_prop() [`2933`](https://github.com/littlevgl/lvgl/pull/2933) +- fix(dropdown): in lv_dropdown_get_selected_str handle if there are no options [`2925`](https://github.com/littlevgl/lvgl/pull/2925) +- fix: lv_deinit/lv_init crash or hang [`2910`](https://github.com/littlevgl/lvgl/pull/2910) +- fix(rt-thread): improve the structure [`2912`](https://github.com/littlevgl/lvgl/pull/2912) +- fix: removed string format warnings for int32_t and uint32_t [`2924`](https://github.com/littlevgl/lvgl/pull/2924) +- fix(lv_fs_win32): add missing include of <stdio.h> [`2918`](https://github.com/littlevgl/lvgl/pull/2918) +- fix: use unsigned integer literal for bit shifing. [`2888`](https://github.com/littlevgl/lvgl/pull/2888) +- chore(lottie) move rlottie_capi.h to lv_rlottie.c [`2902`](https://github.com/littlevgl/lvgl/pull/2902) +- fix(qrcodegen) add brackets around assert calls [`2897`](https://github.com/littlevgl/lvgl/pull/2897) +- fix(list) guard image creation with LV_USE_IMG [`2881`](https://github.com/littlevgl/lvgl/pull/2881) +- fix(snapshot): make fake display size big enough to avoid align issue. [`2883`](https://github.com/littlevgl/lvgl/pull/2883) +- fix(sdl) correct makefile [`2884`](https://github.com/littlevgl/lvgl/pull/2884) +- fix(draw): fix set_px_cb memory write overflow crash. [`2882`](https://github.com/littlevgl/lvgl/pull/2882) +- fix(freetype): fix memset error [`2877`](https://github.com/littlevgl/lvgl/pull/2877) +- fix(span): fix align and break word [`2861`](https://github.com/littlevgl/lvgl/pull/2861) +- fix(refr): swap buffers only on the last area with direct mode [`2867`](https://github.com/littlevgl/lvgl/pull/2867) +- fix(arc) free memory when drawing full-circle arc [`2869`](https://github.com/littlevgl/lvgl/pull/2869) +- fix(indev): update lv_indev_drv_update to free the read_timer [`2850`](https://github.com/littlevgl/lvgl/pull/2850) +- fix(draw): fix memory access out of bounds when using blend subtract [`2860`](https://github.com/littlevgl/lvgl/pull/2860) +- fix(chart) add lv_chart_refresh() to the functions which modify the data [`2841`](https://github.com/littlevgl/lvgl/pull/2841) +- fix(conf) mismatched macro judgment [`2843`](https://github.com/littlevgl/lvgl/pull/2843) +- fix(ffmpeg): when disabled LV_FFMPEG_AV_DUMP_FORMAT makes av_log quiet [`2838`](https://github.com/littlevgl/lvgl/pull/2838) +- fix(rt-thread): fix a bug of log [`2811`](https://github.com/littlevgl/lvgl/pull/2811) +- fix(log): to allow printf and custom_print_cb to work at same time [`2837`](https://github.com/littlevgl/lvgl/pull/2837) +- fix(keyboard): add missing functions [`2835`](https://github.com/littlevgl/lvgl/pull/2835) +- fix(checkbox) remove unnecessary events [`2829`](https://github.com/littlevgl/lvgl/pull/2829) +- fix(qrcode): replace memcpy() with lv_memcpy() and delete useless macros [`2827`](https://github.com/littlevgl/lvgl/pull/2827) +- fix(font) improve builtin font source files generation process [`2825`](https://github.com/littlevgl/lvgl/pull/2825) +- fix(CMake) split CMakeLists.txt, add options, includes and dependencies [`2753`](https://github.com/littlevgl/lvgl/pull/2753) +- fix(obj): make lv_obj_fade_in/out use the current opa as start value [`2819`](https://github.com/littlevgl/lvgl/pull/2819) +- fix(qrcode):minimize margins as much as possible [`2804`](https://github.com/littlevgl/lvgl/pull/2804) +- fix(scripts): switch all scripts to python3 [`2820`](https://github.com/littlevgl/lvgl/pull/2820) +- fix(event): event_send_core crash in special case. [`2807`](https://github.com/littlevgl/lvgl/pull/2807) +- fix(Kconfig) remove duplicate LV_BUILD_EXAMPLES configuration [`2813`](https://github.com/littlevgl/lvgl/pull/2813) +- fix(obj): in obj event use the current target instead of target [`2785`](https://github.com/littlevgl/lvgl/pull/2785) +- fix(draw_label): radius Mask doesn't work in Specific condition [`2784`](https://github.com/littlevgl/lvgl/pull/2784) +- fix(draw_mask): will crash if get_width/height < 0 [`2793`](https://github.com/littlevgl/lvgl/pull/2793) +- fix(theme) make the basic theme really basic [`a369f18`](https://github.com/littlevgl/lvgl/commit/a369f18c57c6b9d20a37959d621f9cb16348ef99) +- fix(arc): fix knob invalidation [`345f688`](https://github.com/littlevgl/lvgl/commit/345f6882c9802dd9be55dfda5fe50c17e8c002b0) +- fix(theme): add arc, spinner and colorwheel to basic theme [`adc218a`](https://github.com/littlevgl/lvgl/commit/adc218a7b303c564da021714e5a109a5d003fc30) +- fix(conf) define LV_LOG_TRACE_... to 0 in lv_conf_internal.h to avoid warnings [`305284c`](https://github.com/littlevgl/lvgl/commit/305284c2b5aadec7bcfa68c6517c98d44be7c8a9) +- fix(draw): consider opa and clip corner on bg_img [`d51aea4`](https://github.com/littlevgl/lvgl/commit/d51aea4dffc706876ac729373c33a74743bc05e9) +- fix(draw): add grad_cache_mem to GC_ROOTs [`138db9c`](https://github.com/littlevgl/lvgl/commit/138db9c5d6b1f1d42c48d1307f5f508149ab0fda) +- fix(bar, slider): fix shadow drawing on short indicators [`364ca3c`](https://github.com/littlevgl/lvgl/commit/364ca3ca1763fb732a049bfce689e2f588593cd4) +- fix(theme): fix theme initialization issue introduced in 6e0072479 [`d231644`](https://github.com/littlevgl/lvgl/commit/d2316447c5c240960236d41814ef20e63cd56f00) +- fix(draw): add lv_draw_sw_bg [`49642d3`](https://github.com/littlevgl/lvgl/commit/49642d3891c563b6c82bb407bacc4b73329a8c93) +- fix(draw) border_draw crash is special case [`075831a`](https://github.com/littlevgl/lvgl/commit/075831a54c30d294879619c90ca4d16676c0775a) +- fix(theme): fix crash in lv_theme_basic_init [`ca5f04c`](https://github.com/littlevgl/lvgl/commit/ca5f04cfe33e1db0b72a07812557634b86028c27) +- fix(draw): fix indexed image drawing [`5a0dbcc`](https://github.com/littlevgl/lvgl/commit/5a0dbccf890b7a86315140dfe052da6b6aeca531) +- fix(roller): clip overflowing text [`5709528`](https://github.com/littlevgl/lvgl/commit/5709528550f7bdb0a16da1c05ea8094fc085db08) +- fix(align) fix LV_SIZE_CONTENT size calculation with not LEFT or TOP alignment [`9c67642`](https://github.com/littlevgl/lvgl/commit/9c676421ff159de1a96409f5557d36090c1728f9) +- fix(draw): futher bg_img draw fixes [`81bfb76`](https://github.com/littlevgl/lvgl/commit/81bfb765e5baba359e61dcb030f3ee96160a6335) +- fix(btnmatrix): keep the selected button even on release [`d47cd1d`](https://github.com/littlevgl/lvgl/commit/d47cd1d7fe910efc189e2f43f046a09184cfff13) +- fix(sw): make knob size calculation more intuitive [`5ec532d`](https://github.com/littlevgl/lvgl/commit/5ec532dfd5ffa0d47a1ac80c9a468d6362f3d933) +- fix(switch): make knob height calculation similar to slider [`0921dfc`](https://github.com/littlevgl/lvgl/commit/0921dfc8cd9d00e70ead8cbef8a898711af8f43e) +- fix(span): explicitly set span->txt to the return value of lv_mem_realloc(#3005) [`a9a6cb8`](https://github.com/littlevgl/lvgl/commit/a9a6cb8efd16c55a175791a43a3f4043a3a5e01f) +- fix(example): update LVGL_Arduino.ino [`d79283c`](https://github.com/littlevgl/lvgl/commit/d79283c145f92124c800453bcaf1caf1f9684bc5) +- fix(draw) simplify how outline_pad is compnesated [`81d8be1`](https://github.com/littlevgl/lvgl/commit/81d8be13d67d6b17b663bc703c1e0e18a18890a7) +- fix(obj) make LV_OBJ_FLAG_SCROLL_CHAIN part of the enum instead of define [`f8d8856`](https://github.com/littlevgl/lvgl/commit/f8d88567f635f325d6738ce2343f3b3c29f1e40a) +- fix(label): dot not add dots if the label height > 1 font line height [`4d61f38`](https://github.com/littlevgl/lvgl/commit/4d61f3802013b31b0af5f08f66bb86f5179db141) +- fix(event): crash if an object was deleted in an event [`9810920`](https://github.com/littlevgl/lvgl/commit/9810920fc5d34a984bddf6e41156e87e509cfd27) +- fix(build) fix sdl build with make [`43729d1`](https://github.com/littlevgl/lvgl/commit/43729d1502dad0ca797b4b6fb8c69a48c81a2af7) +- fix(config): fix anonymous choice [`71c739c`](https://github.com/littlevgl/lvgl/commit/71c739cc2dbcebf16e8adc805dda182011e725da) +- chore(docs): fix lv_list_add_text [`a5fbf22`](https://github.com/littlevgl/lvgl/commit/a5fbf22d415a52cb2641c6dfda6937a10e4952cc) +- fix(png) check png magic number to be sure it's a png image [`1092550`](https://github.com/littlevgl/lvgl/commit/1092550775c464f9ae8c406786fe02115776d5c6) +- fix(btnmatrix): fix crash if an empty btnmatrix is pressed [`2392f58`](https://github.com/littlevgl/lvgl/commit/2392f585bb9317153f6fb648d2a660cbdc3e276f) +- fix(mem/perf monitor): fix issue introduced in #2910 [`0788d91`](https://github.com/littlevgl/lvgl/commit/0788d918990fd1c03bd7a04941cfbbdf6d21987c) +- fix(layout) fix layout recalculation trigger in lv_obj_add/clear_fleg [`ee65410`](https://github.com/littlevgl/lvgl/commit/ee65410c3725070ed1779c95fb8742107cdd9267) +- fix(obj) fix lv_obj_fade_in [`4931384`](https://github.com/littlevgl/lvgl/commit/49313840ee9b249f2ef9142e872657856810acfc) +- fix(draw): fix clipping children to parent [`5c98ac8`](https://github.com/littlevgl/lvgl/commit/5c98ac85117c24f4da61803f0dc5a9bb6cfd1fdc) +- fix: remove symlinks to be accepted as an Ardunio library [`6701d36`](https://github.com/littlevgl/lvgl/commit/6701d36afe40130479dc83efc05d4860f3f29636) +- chore: fix typos in FATFS config [`74091c4`](https://github.com/littlevgl/lvgl/commit/74091c42f7cf4e85e46e706692accb65879741e2) +- fix(refr): fix missed buffer switch in double full-screen buffer + direct_mode [`731ef5a`](https://github.com/littlevgl/lvgl/commit/731ef5a75ea7feb7319315bd15bc1a43b899c1ca) +- chore(qrcode): fix warnings [`e9d7080`](https://github.com/littlevgl/lvgl/commit/e9d70803e11378eddf435e66c2181c0fa77211c7) +- docs(event): tell to not adjust widgets in draw events [`933d67f`](https://github.com/littlevgl/lvgl/commit/933d67fe5b8596da203c318aa9551aad1c2887e6) +- fix(table, chart): fix memory leaks [`8d52de1`](https://github.com/littlevgl/lvgl/commit/8d52de14b33262a11de87f5d782611a38726a1a7) +- fix(event): handle object deletion in indev->fedback_cb [`bfc8edf`](https://github.com/littlevgl/lvgl/commit/bfc8edf802382f78e96125c886427c99c7f9a600) +- fix(roller): snap on press lost [`fa9340c`](https://github.com/littlevgl/lvgl/commit/fa9340c45fd4a86b4a44878286850f3f67133bf4) +- fix(dropdown) be sure the list is the top object on the screen [`cb7fc2b`](https://github.com/littlevgl/lvgl/commit/cb7fc2bb59f788ce8024d62a5b1e821575a9cb74) +- fix(img) fix invalidation issue on transformations [`d5ede0e`](https://github.com/littlevgl/lvgl/commit/d5ede0ebc6685d4857b5ac554d53c0a7373d7532) +- fix(obj) fix comments of lv_obj_set_pos/x/y [`b9a5078`](https://github.com/littlevgl/lvgl/commit/b9a5078cd9d57662fc6e684d57a0ee4e70ca49c0) + +### Examples + +- example: add non-null judgment to lv_example_obj_2 [`2799`](https://github.com/littlevgl/lvgl/pull/2799) +- example(table): fix text alignment [`b03dc9c`](https://github.com/littlevgl/lvgl/commit/b03dc9cf862584c2e2be2c900fa4ff6e67b336f8) + +### Docs + +- docs(demos) update information to reflect new layout [`3029`](https://github.com/littlevgl/lvgl/pull/3029) +- docs(porting): remove duplicated content [`2984`](https://github.com/littlevgl/lvgl/pull/2984) +- docs(display) fix typo [`2946`](https://github.com/littlevgl/lvgl/pull/2946) +- docs(get-started) add introduction for Tasmota and Berry [`2874`](https://github.com/littlevgl/lvgl/pull/2874) +- docs fix spelling, parameter descriptions, comments, etc [`2865`](https://github.com/littlevgl/lvgl/pull/2865) +- docs: spelling fixes [`2828`](https://github.com/littlevgl/lvgl/pull/2828) +- docs(style) minor style fix [`2818`](https://github.com/littlevgl/lvgl/pull/2818) +- docs(porting/display) fix formatting [`2812`](https://github.com/littlevgl/lvgl/pull/2812) +- docs(roadmap) update [`084439e`](https://github.com/littlevgl/lvgl/commit/084439e9476339ff571820e38bb677157edef135) +- docs(widgets) fix edit links [`7ed1a56`](https://github.com/littlevgl/lvgl/commit/7ed1a5625a5139ede832c0058b2bc6309b395321) +- docs(contributing) update commit message format [`1cd851f`](https://github.com/littlevgl/lvgl/commit/1cd851f8c09e813d75feaf9bf312f887f5ba76f0) +- docs(porting): add more details about adding lvgl to your project [`6ce7348`](https://github.com/littlevgl/lvgl/commit/6ce73486d319bfdb1c379d090036a7eeaabf5b43) +- docs(indev): add description about gestures [`2719862`](https://github.com/littlevgl/lvgl/commit/2719862fc3065b5d72c74c3f5f0923c3f6cc82c6) +- docs(style): describe const styles [`28ffae8`](https://github.com/littlevgl/lvgl/commit/28ffae8c931ff01a4e5d426a2e496053e840c094) +- docs(faq): add "LVGL doesn't start, nothing is drawn on the display" section [`0388d92`](https://github.com/littlevgl/lvgl/commit/0388d9218a36debf6c989eb999ae68478d8f6b02) +- docs add demos [`02a6614`](https://github.com/littlevgl/lvgl/commit/02a6614b38b7d94e56d8fc1f858b0e40a46c024d) +- docs(fs): update fs interface description to the latest API [`285e6b3`](https://github.com/littlevgl/lvgl/commit/285e6b39f99c078e57a611cf84cbfc3b546e112e) +- docs(format) let wrap [`4bf49a8`](https://github.com/littlevgl/lvgl/commit/4bf49a82a3df422ebbfc4e47d4a93c945afdf0fa) +- docs(imgbtn) fix typo [`d792c5f`](https://github.com/littlevgl/lvgl/commit/d792c5f6c2e9d85c693e4f8089cb59c82d8cf805) +- docs(porting) clarify that displays must be registered before input devices [`1c64b78`](https://github.com/littlevgl/lvgl/commit/1c64b78866b4bb920db75a4b19f8ff1eb7f68a76) +- docs(event) fix lv_event_get_original_target vs lv_event_get_current_target [`cdd5128`](https://github.com/littlevgl/lvgl/commit/cdd5128bc0e17b2ffa3f9fc8f5f133d35fca4e35) +- docs(events) rename LV_EVENT_APPLY to LV_EVENT_READY (#2791) [`bf6837f`](https://github.com/littlevgl/lvgl/commit/bf6837f4c045b01144842ae63c4052e4cac7dafb) +- docs(gpu): link style properties and boxing model [`6266851`](https://github.com/littlevgl/lvgl/commit/6266851381d3b1f1e350dc4689e6bc71ece2f5c1) +- docs(gesture): clarify gesture triggering with scrolling [`e3b43ee`](https://github.com/littlevgl/lvgl/commit/e3b43eec943db48f7cbee83e07e531d41bc61ac0) +- docs(contributing): remove the mentioning of the dev branch [`00d4ef3`](https://github.com/littlevgl/lvgl/commit/00d4ef3c53d9b53e993c76d1eb0bafa7b1c9b721) +- docs(bar) fix default range [`eeee48b`](https://github.com/littlevgl/lvgl/commit/eeee48b1c943fc288521e4479d874348f4690842) +- docs(event): tell to not adjust widgets in draw events [`933d67f`](https://github.com/littlevgl/lvgl/commit/933d67fe5b8596da203c318aa9551aad1c2887e6) +- docs(switch) improve wording [`b4986ab`](https://github.com/littlevgl/lvgl/commit/b4986ab5dceb47f934c0a44a58152367f1bf8f43) +- docs(font) fix example to match v8 [`2f80896`](https://github.com/littlevgl/lvgl/commit/2f808965a1892e11cb84f50c6546871d2f2aa122) + +### CI and tests + +- test(bar): add unit tests [`2845`](https://github.com/littlevgl/lvgl/pull/2845) +- test(switch): add initial unit test [`2794`](https://github.com/littlevgl/lvgl/pull/2794) +- test(demo) add tests for widget and stress demos [`3bd6ad8`](https://github.com/littlevgl/lvgl/commit/3bd6ad80e7e7d0936b6e54ca88760db551f7848b) +- test(dropdown) fix to pass again [`918b3de`](https://github.com/littlevgl/lvgl/commit/918b3defd78245136da92f46fac937815ef35a1a) +- test add support for using system heap [`446b1eb`](https://github.com/littlevgl/lvgl/commit/446b1ebf2bc1ba38b5349c660534f113a9a066a9) +- ci remove formatting request workflow [`6de89e4`](https://github.com/littlevgl/lvgl/commit/6de89e4b7b0a0f72cf53e59a90bd22362088eb71) +- ci initial support for cross-architecture tests [`7008770`](https://github.com/littlevgl/lvgl/commit/7008770261903170d19472a52b54fedaafa7bbda) +- ci create handler for formatting requests [`7af7849`](https://github.com/littlevgl/lvgl/commit/7af78498a898cba6263b51094ffbc486d6b30b3a) +- test(style) add test for gradient [`da8f345`](https://github.com/littlevgl/lvgl/commit/da8f34566b0c0f3335c471c518f0766bdeb65766) +- test(event) add test for #2886 [`51ef9c2`](https://github.com/littlevgl/lvgl/commit/51ef9c242ccfff37905d71132aab33d2f642b427) +- ci add workflow to check code formatting [`a2b555e`](https://github.com/littlevgl/lvgl/commit/a2b555e096f7d401b5d8e877a6b5e81ff81c747a) +- ci attempt to speed up cross tests [`80408f7`](https://github.com/littlevgl/lvgl/commit/80408f704e8442a27f6dca96c41f1d3bded7ce52) +- ci apply my updates to the verify-formatting action [`02f02fa`](https://github.com/littlevgl/lvgl/commit/02f02fa78fc4101b1cde87fe912cb3105a689195) +- ci: add arduino linter action [`f79b00c`](https://github.com/littlevgl/lvgl/commit/f79b00cce0d31c7e5519a871b27d803fdb30fdfd) +- ci update action [`be9722c`](https://github.com/littlevgl/lvgl/commit/be9722c420a1ac2e9efde79135bf96bc508edb33) +- ci more formatting action updates [`1f6037c`](https://github.com/littlevgl/lvgl/commit/1f6037ce98c8617221d321d3371ad6dc8649553a) +- ci disable LeakSanitizer on dockerized tests [`c9e1927`](https://github.com/littlevgl/lvgl/commit/c9e19272c62f01544ff7cb5ef15d65b0d4fce5a5) +- ci one last try at this for tonight [`dddafae`](https://github.com/littlevgl/lvgl/commit/dddafaec942b7886722cdec28e2bd0f20f2a3413) +- ci try alternate checkout mechanism [`cb3de30`](https://github.com/littlevgl/lvgl/commit/cb3de308fdcdebb9c980df1d167a6be3657b2540) +- test(style) fix compile error [`ba083df`](https://github.com/littlevgl/lvgl/commit/ba083dfd6dc31d1d9127542cd1aff860d5a0153c) +- test(template) simplify _test_template.c [`b279f63`](https://github.com/littlevgl/lvgl/commit/b279f63d6bf84159aab855b962a9f431d5c40eb3) +- ci force ccache to be saved every time [`a7c590f`](https://github.com/littlevgl/lvgl/commit/a7c590f10d4c39ae33d89ad86ef608092030654b) +- ci switch to codecov v2 [`6b84155`](https://github.com/littlevgl/lvgl/commit/6b841555cd847d07375b92b54a814c41ccb522de) +- ci more debugging for formatting action [`2f8e4bc`](https://github.com/littlevgl/lvgl/commit/2f8e4bc4c43fa395676e2be5d3d55999206190b4) +- ci inline apt-get commands [`90e2b9f`](https://github.com/littlevgl/lvgl/commit/90e2b9f05e73527dfa2b2df0b1da30512827b8a8) +- ci(micropython) use ESP-IDF 4.4 [`b34fe9e`](https://github.com/littlevgl/lvgl/commit/b34fe9ed8b945fd83a1956cf4ddf2d40485a62ca) +- ci add 5k stack limit [`4122dda`](https://github.com/littlevgl/lvgl/commit/4122dda399679baa3b8bbd2e7055412b132227ab) +- ci force use of ccache in PATH [`6de3fa8`](https://github.com/littlevgl/lvgl/commit/6de3fa8004639ea02d45c1be2985290e65a3d6c0) +- ci add back stack usage check at 4 kilobytes [`89135d6`](https://github.com/littlevgl/lvgl/commit/89135d663daca34c9d9695a4c12b4208ef4ba217) +- ci temporarily disable stack usage check [`1900c21`](https://github.com/littlevgl/lvgl/commit/1900c215482b9b1b5af1dd7c5cb8a95e89906b77) +- ci(cross) use python3 instead of python [`df7eaa0`](https://github.com/littlevgl/lvgl/commit/df7eaa020d656c519b5197cd3d19c587cb1dd234) +- ci use specific version tag [`59b4769`](https://github.com/littlevgl/lvgl/commit/59b476934452d5821424c70954aa32be6f476608) +- ci fix check style action [`5bb3686`](https://github.com/littlevgl/lvgl/commit/5bb3686ea8b6feb55d6bb2b345f5c6cee52d514a) +- ci fix typo in formatting action [`d1ccbf6`](https://github.com/littlevgl/lvgl/commit/d1ccbf607fd3aec61c4606a8f2c268225654b792) +- ci test formatting action [`065d821`](https://github.com/littlevgl/lvgl/commit/065d821c7050af6ad94c7d6dc2d4976a817e54a0) +- ci(micropython) switch to newer GCC action [`1fa7257`](https://github.com/littlevgl/lvgl/commit/1fa7257801f4e0d3c184be438fd7ecb067818c48) +- ci(style) force color on diff to help highlight whitespace changes [`04f47ea`](https://github.com/littlevgl/lvgl/commit/04f47eae0d40c8385535428566d1851ff8ea20eb) +- ci(cross) install build-essential [`772f219`](https://github.com/littlevgl/lvgl/commit/772f219c0af4ba013ee9b71883e7dc265e5d22f9) +- ci force pushing to upstream branch [`8277f78`](https://github.com/littlevgl/lvgl/commit/8277f78d132b4c397f39a9e17cdb7bdd381d1778) +- ci ensure lvgl-bot is used to make commits [`9fcf52a`](https://github.com/littlevgl/lvgl/commit/9fcf52a82bb4dbcfc47e69b7875d66a3d25ba87f) + + + + +## [v8.1.0](https://github.com/lvgl/lvgl/compare/v8.0.2...v8.1.0) 10 November 2021 + +### Overview +v8.1 is a minor release, so besides many fixes it contains a lot of new features too. + +Some of the most important features are +- Built in support for SDL based GPU drawing +- Much faster circle drawing in the software renderer +- Several [3rd party libraries](https://docs.lvgl.io/master/libs/index.html) are merged directly into LVGL. +- Add LVGL as an [RT-Thread](https://packages.rt-thread.org/en/detail.html?package=LVGL) and [ESP32](https://components.espressif.com/component/lvgl/lvgl) component + +### Breaking Changes + +- :warning: feat(calendar): add the header directly into the calendar widget [`2e08f80`](https://github.com/lvgl/lvgl/commit/2e08f80361a9d7e5b97f49af6afc3549ffbf2758) + +### Architectural + +- arch add small 3rd party libs to lvgl [`2569`](https://github.com/lvgl/lvgl/pull/2569) + +### New Features + +- feat(display) add direct_mode drawing mode [`2460`](https://github.com/lvgl/lvgl/pull/2460) +- feat(conf): make LV_MEM_BUF_MAX_NUM configurable [`2747`](https://github.com/lvgl/lvgl/pull/2747) +- feat(disp): add non-fullscreen display utilities [`2724`](https://github.com/lvgl/lvgl/pull/2724) +- feat(rlottie) add LVGL-Rlottie interface as 3rd party lib [`2700`](https://github.com/lvgl/lvgl/pull/2700) +- feat(rtthread): prepare for porting the device-driver of rt-thread [`2719`](https://github.com/lvgl/lvgl/pull/2719) +- feat(fsdrv) add driver based on Win32 API [`2701`](https://github.com/lvgl/lvgl/pull/2701) +- feat(span) indent supports percent for fix and break mode [`2693`](https://github.com/lvgl/lvgl/pull/2693) +- feat(rt-thread): implement rt-thread sconscirpt [`2674`](https://github.com/lvgl/lvgl/pull/2674) +- feat(lv_spinbox) support both right-to-left and left-to-right digit steps when clicking encoder button [`2644`](https://github.com/lvgl/lvgl/pull/2644) +- feat add support for rt-thread RTOS [`2660`](https://github.com/lvgl/lvgl/pull/2660) +- feat(disp): Enable rendering to display subsection [`2583`](https://github.com/lvgl/lvgl/pull/2583) +- feat(keyboard): add user-defined modes [`2651`](https://github.com/lvgl/lvgl/pull/2651) +- feat(event) add LV_EVENT_CHILD_CREATED/DELETED [`2618`](https://github.com/lvgl/lvgl/pull/2618) +- feat(btnmatrix/keyboard): add option to show popovers on button press [`2537`](https://github.com/lvgl/lvgl/pull/2537) +- feat(msgbox) add a content area for custom content [`2561`](https://github.com/lvgl/lvgl/pull/2561) +- feat(tests): Include debug information to test builds [`2568`](https://github.com/lvgl/lvgl/pull/2568) +- feat(drawing) hardware accelerated rendering by SDL2 [`2484`](https://github.com/lvgl/lvgl/pull/2484) +- feat(msgbox): omit title label unless needed [`2539`](https://github.com/lvgl/lvgl/pull/2539) +- feat(msgbox): add function to get selected button index [`2538`](https://github.com/lvgl/lvgl/pull/2538) +- feat(make) add lvgl interface target for micropython [`2529`](https://github.com/lvgl/lvgl/pull/2529) +- feat(obj) add lv_obj_move_to_index(obj, index), renamed lv_obj_get_child_id(obj) to lv_obj_get_index(obj) [`2514`](https://github.com/lvgl/lvgl/pull/2514) +- feat(obj) add lv_obj_swap() function [`2461`](https://github.com/lvgl/lvgl/pull/2461) +- feat(mem) LV_MEM_POOL_ALLOC [`2458`](https://github.com/lvgl/lvgl/pull/2458) +- feat(switch) add smooth animation when changing state [`2442`](https://github.com/lvgl/lvgl/pull/2442) +- feat(anim) add interface for handling lv_anim user data. [`2415`](https://github.com/lvgl/lvgl/pull/2415) +- feat(obj) add lv_is_initialized [`2402`](https://github.com/lvgl/lvgl/pull/2402) +- feat(obj) Backport keypad and encoder scrolling from v7 `lv_page` to v8 `lv_obj` [`2390`](https://github.com/lvgl/lvgl/pull/2390) +- feat(snapshot) add API to take snapshot for object [`2353`](https://github.com/lvgl/lvgl/pull/2353) +- feat(anim) add anim timeline [`2309`](https://github.com/lvgl/lvgl/pull/2309) +- feat(span) Add missing spangroup functions [`2379`](https://github.com/lvgl/lvgl/pull/2379) +- feat(img) add img_size property [`2284`](https://github.com/lvgl/lvgl/pull/2284) +- feat(calendar) improve MicroPython example [`2366`](https://github.com/lvgl/lvgl/pull/2366) +- feat(spinbox ) add function to set cursor to specific position [`2314`](https://github.com/lvgl/lvgl/pull/2314) + +- feat(timer) check if lv_tick_inc is called [`aa6641a`](https://github.com/lvgl/lvgl/commit/aa6641a6f1c1311ce7e0f94783ee7f582452a88f) +- feat(event, widgets) improve the parameter of LV_EVENT_DRAW_PART_BEGIN/END [`88c4859`](https://github.com/lvgl/lvgl/commit/88c485949fca2686357a7dee88d5730678ba9bc7) +- feat(docs) improvements to examples [`4b8c73a`](https://github.com/lvgl/lvgl/commit/4b8c73a5770657ab55bbe825f7887e28c55a8a4a) +- feat(obj) send LV_EVENT_DRAW_PART_BEGIN/END for MAIN and SCROLLBAR parts [`b203167`](https://github.com/lvgl/lvgl/commit/b203167c7583905e2cb4006e57a16432841a2353) +- feat(led) send LV_EVENT_DRAW_PART_BEGIN/END [`fcd4aa3`](https://github.com/lvgl/lvgl/commit/fcd4aa3924469c2a92ab6a04b7bc6de6304cc54a) +- feat(chart) send LV_EVENT_DRAW_PART_BEGIN/END before/after the division line drawing section. [`e0ae2aa`](https://github.com/lvgl/lvgl/commit/e0ae2aa106874b1cf60ba54dd043cde8f834f7e9) +- feat(tests) upload coverage to codecov [`4fff99d`](https://github.com/lvgl/lvgl/commit/4fff99da1dd2f8bd0c1e0012d81d46aaadb0d5a3) +- feat(conf) add better check for Kconfig default [`f8fe536`](https://github.com/lvgl/lvgl/commit/f8fe5366bb051cd5090e4a06658eb0d32decc0b3) +- feat(draw) add LV_BLEND_MODE_MULTIPLY [`cc78ef4`](https://github.com/lvgl/lvgl/commit/cc78ef450649a10f260649dc3ba19ac8a6b88e86) +- feat(test) add assert for screenshot compare [`2f7a005`](https://github.com/lvgl/lvgl/commit/2f7a005bd31c10d0a048f55641e4af11bcb5bbfa) +- feat(event) pass the scroll animation to LV_EVENT_SCROLL_BEGIN [`ca54ecf`](https://github.com/lvgl/lvgl/commit/ca54ecfe0eac880203d23b2d2244b9b63b9f7b77) +- feat(obj) place the scrollbar to the left with RTL base dir. [`906448e`](https://github.com/lvgl/lvgl/commit/906448ef6321f160859f21c5937180bb89d8ef1e) +- feat(log) allow overwriting LV_LOG_... macros [`17b8a76`](https://github.com/lvgl/lvgl/commit/17b8a76c4a887c9cf464484406a6631ea0194ad5) +- feat(arc) add support to LV_OBJ_FLAG_ADV_HITTEST [`dfa4f5c`](https://github.com/lvgl/lvgl/commit/dfa4f5cff561a60b4ffcec17e025f1e056854fff) +- feat(event) add LV_SCREEN_(UN)LOAD_START [`7bae9e3`](https://github.com/lvgl/lvgl/commit/7bae9e3ddde9d6bdc06ae437f20a789cd330a556) +- feat(obj) add lv_obj_del_delayed() [`c6a2e15`](https://github.com/lvgl/lvgl/commit/c6a2e15ec23c8e96f71bafa8e43ef67fc4a73d0a) +- feat(docs) add view on GitHub link [`a716ac6`](https://github.com/lvgl/lvgl/commit/a716ac6ed267e0a2e019fe7d2fda1bef0046cdc7) +- feat(event) add LV_EVENT_SCREEN_LOADED/UNLOADED events [`ee5369e`](https://github.com/lvgl/lvgl/commit/ee5369e2d2ce12f47c78a2bf339aa6fb2421ba2b) +- feat(textarea) remove the need of lv_textarea_set_align [`56ebb1a`](https://github.com/lvgl/lvgl/commit/56ebb1a4c8cc988482ac9f118fa3c654553db941) +- feat(rt-thread): support LVGL projects with GCC/Keil(AC5)/Keil(AC6)/IAR [`32d33fe`](https://github.com/lvgl/lvgl/commit/32d33fe4d9a38f6c215a6b9a631eb987339677ae) +- feat(docs) lazy load individual examples as well [`918d948`](https://github.com/lvgl/lvgl/commit/918d94801f2ee4ad7b6c075d96d2e9195459fbb8) + +- feat: add LV_USE_MEM_PERF/MONITOR_POS [`acd0f4f`](https://github.com/lvgl/lvgl/commit/acd0f4fbc71ffbfeb382b7af1fa52caf3cdcda6c) +- feat(canvas) add lv_canvas_set_px_opa [`b3b3ffc`](https://github.com/lvgl/lvgl/commit/b3b3ffc2b3b322f7401d15c4ba2ef0cdb00e2990) +- feat(event) add lv_obj_remove_event_cb_with_user_data [`4eddeb3`](https://github.com/lvgl/lvgl/commit/4eddeb35abee1f9cd2d1fd210f11cc096cb609c7) +- feat(obj) add lv_obj_get_x/y_aligned [`98bc1fe`](https://github.com/lvgl/lvgl/commit/98bc1fe09e12a64333e91b4c25327c283a700af5) + +### Performance + +- perf(draw) reimplement circle drawing algorithms [`2374`](https://github.com/lvgl/lvgl/pull/2374) +- perf(anim_timeline) add lv_anim_timeline_stop() [`2411`](https://github.com/lvgl/lvgl/pull/2411) + +- perf(obj) remove lv_obj_get_child_cnt from cycle limit checks [`ebb9ce9`](https://github.com/lvgl/lvgl/commit/ebb9ce913e604055724fd5f72562c9de0933ff73) +- perf(draw) reimplement rectangle drawing algorithms [`5b3d3dc`](https://github.com/lvgl/lvgl/commit/5b3d3dc8b35bdd16e5dea00ffc40b7a20471079d) +- perf(draw) ignore masks if they don't affect the current draw area [`a842791`](https://github.com/lvgl/lvgl/commit/a8427915c747dfe562f7f7e80adb6d1be5b2eeae) +- perf(refresh) optimize where to wait for lv_disp_flush_ready with 2 buffers [`d0172f1`](https://github.com/lvgl/lvgl/commit/d0172f14a454c98e6979322e7c2622a7001bb3e6) +- perf(draw) speed up additive blending [`3abe517`](https://github.com/lvgl/lvgl/commit/3abe517abf3b62366f2eb4bed77d5c7a691f7ed5) + +### Fixes + +- fix(bidi): add weak characters to the previous strong character's run [`2777`](https://github.com/lvgl/lvgl/pull/2777) +- fix(draw_img): radius mask doesn't work in specific condition [`2786`](https://github.com/lvgl/lvgl/pull/2786) +- fix(border_post): ignore bg_img_opa draw when draw border_post [`2788`](https://github.com/lvgl/lvgl/pull/2788) +- fix(refresh) switch to portable format specifiers [`2781`](https://github.com/lvgl/lvgl/pull/2781) +- fix(stm32) Mark unused variable in stm32 DMA2D driver [`2782`](https://github.com/lvgl/lvgl/pull/2782) +- fix(conf): Make LV_COLOR_MIX_ROUND_OFS configurable [`2766`](https://github.com/lvgl/lvgl/pull/2766) +- fix(misc): correct the comment and code style [`2769`](https://github.com/lvgl/lvgl/pull/2769) +- fix(draw_map) use existing variables instead function calls [`2776`](https://github.com/lvgl/lvgl/pull/2776) +- fix(draw_img): fix typos in API comments [`2773`](https://github.com/lvgl/lvgl/pull/2773) +- fix(draw_img):radius Mask doesn't work in Specific condition [`2775`](https://github.com/lvgl/lvgl/pull/2775) +- fix(proto) Remove redundant prototype declarations [`2771`](https://github.com/lvgl/lvgl/pull/2771) +- fix(conf) better support bool option from Kconfign [`2555`](https://github.com/lvgl/lvgl/pull/2555) +- fix(draw_border):draw error if radius == 0 and parent clip_corner == true [`2764`](https://github.com/lvgl/lvgl/pull/2764) +- fix(msgbox) add declaration for lv_msgbox_content_class [`2761`](https://github.com/lvgl/lvgl/pull/2761) +- fix(core) add L suffix to enums to ensure 16-bit compatibility [`2760`](https://github.com/lvgl/lvgl/pull/2760) +- fix(anim): add lv_anim_get_playtime [`2745`](https://github.com/lvgl/lvgl/pull/2745) +- fix(area) minor fixes [`2749`](https://github.com/lvgl/lvgl/pull/2749) +- fix(mem): ALIGN_MASK should equal 0x3 on 32bit platform [`2748`](https://github.com/lvgl/lvgl/pull/2748) +- fix(template) prototype error [`2755`](https://github.com/lvgl/lvgl/pull/2755) +- fix(anim): remove time_orig from lv_anim_t [`2744`](https://github.com/lvgl/lvgl/pull/2744) +- fix(draw_rect):bottom border lost if enable clip_corner [`2742`](https://github.com/lvgl/lvgl/pull/2742) +- fix(anim) and improvement [`2738`](https://github.com/lvgl/lvgl/pull/2738) +- fix(draw border):border draw error if border width > radius [`2739`](https://github.com/lvgl/lvgl/pull/2739) +- fix(fsdrv): remove the seek call in fs_open [`2736`](https://github.com/lvgl/lvgl/pull/2736) +- fix(fsdrv): skip the path format if LV_FS_xxx_PATH not defined [`2726`](https://github.com/lvgl/lvgl/pull/2726) +- fix: mark unused variable with LV_UNUSED(xxx) instead of (void)xxx [`2734`](https://github.com/lvgl/lvgl/pull/2734) +- fix(fsdrv): fix typo error in commit 752fba34f677ad73aee [`2732`](https://github.com/lvgl/lvgl/pull/2732) +- fix(fsdrv): return error in case of the read/write failure [`2729`](https://github.com/lvgl/lvgl/pull/2729) +- fix(refr) silence compiler warning due to integer type mismatch [`2722`](https://github.com/lvgl/lvgl/pull/2722) +- fix(fs): fix the off-by-one error in the path function [`2725`](https://github.com/lvgl/lvgl/pull/2725) +- fix(timer): remove the code duplication in lv_timer_exec [`2708`](https://github.com/lvgl/lvgl/pull/2708) +- fix(async): remove the wrong comment from lv_async_call [`2707`](https://github.com/lvgl/lvgl/pull/2707) +- fix(kconfig): change CONFIG_LV_THEME_DEFAULT_FONT to CONFIG_LV_FONT_DEFAULT [`2703`](https://github.com/lvgl/lvgl/pull/2703) +- fix add MP support for LVGL 3rd party libraries [`2666`](https://github.com/lvgl/lvgl/pull/2666) +- fix(png) memory leak for sjpg and use lv_mem_... in lv_png [`2704`](https://github.com/lvgl/lvgl/pull/2704) +- fix(gif) unified whence and remove off_t [`2690`](https://github.com/lvgl/lvgl/pull/2690) +- fix(rt-thread): include the rt-thread configuration header file [`2692`](https://github.com/lvgl/lvgl/pull/2692) +- fix(rt-thread): fix the ci error [`2691`](https://github.com/lvgl/lvgl/pull/2691) +- fix(fsdrv) minor fs issue [`2682`](https://github.com/lvgl/lvgl/pull/2682) +- fix(hal) fix typos and wording in docs for lv_hal_indev.h [`2685`](https://github.com/lvgl/lvgl/pull/2685) +- fix(hal tick): add precompile !LV_TICK_CUSTOM for global variables and lv_tick_inc() [`2675`](https://github.com/lvgl/lvgl/pull/2675) +- fix(anim_timeline) avoid calling lv_anim_del(NULL, NULL) [`2628`](https://github.com/lvgl/lvgl/pull/2628) +- fix(kconfig) sync Kconfig with the latest lv_conf_template.h [`2662`](https://github.com/lvgl/lvgl/pull/2662) +- fix(log) reduce the stack usage in log function [`2649`](https://github.com/lvgl/lvgl/pull/2649) +- fix(conf) make a better style alignment in lv_conf_internal.h [`2652`](https://github.com/lvgl/lvgl/pull/2652) +- fix(span) eliminate warning in lv_get_snippet_cnt() [`2659`](https://github.com/lvgl/lvgl/pull/2659) +- fix(config): remove the nonexistent Kconfig [`2654`](https://github.com/lvgl/lvgl/pull/2654) +- fix(Kconfig): add LV_MEM_ADDR config [`2653`](https://github.com/lvgl/lvgl/pull/2653) +- fix(log): replace printf with fwrite to save the stack size [`2655`](https://github.com/lvgl/lvgl/pull/2655) +- fix typos [`2634`](https://github.com/lvgl/lvgl/pull/2634) +- fix LV_FORMAT_ATTRIBUTE fix for gnu > 4.4 [`2631`](https://github.com/lvgl/lvgl/pull/2631) +- fix(meter) make lv_meter_indicator_type_t of type uint8_t [`2632`](https://github.com/lvgl/lvgl/pull/2632) +- fix(span):crash if span->txt = "" [`2616`](https://github.com/lvgl/lvgl/pull/2616) +- fix(disp) set default theme also for non-default displays [`2596`](https://github.com/lvgl/lvgl/pull/2596) +- fix(label):LONG_DOT mode crash if text Utf-8 encode > 1 [`2591`](https://github.com/lvgl/lvgl/pull/2591) +- fix( example) in lv_example_scroll_3.py float_btn should only be created once [`2602`](https://github.com/lvgl/lvgl/pull/2602) +- fix lv_deinit when LV_USE_GPU_SDL is enabled [`2598`](https://github.com/lvgl/lvgl/pull/2598) +- fix add missing LV_ASSERT_OBJ checks [`2575`](https://github.com/lvgl/lvgl/pull/2575) +- fix(lv_conf_internal_gen.py) formatting fixes on the generated file [`2542`](https://github.com/lvgl/lvgl/pull/2542) +- fix(span) opa bug [`2584`](https://github.com/lvgl/lvgl/pull/2584) +- fix(snapshot) snapshot is affected by parent's style because of wrong coords [`2579`](https://github.com/lvgl/lvgl/pull/2579) +- fix(label):make draw area contain ext_draw_size [`2587`](https://github.com/lvgl/lvgl/pull/2587) +- fix(btnmatrix): make ORed values work correctly with lv_btnmatrix_has_btn_ctrl [`2571`](https://github.com/lvgl/lvgl/pull/2571) +- fix compiling of examples when cmake is used [`2572`](https://github.com/lvgl/lvgl/pull/2572) +- fix(lv_textarea) fix crash while delete non-ascii character in pwd mode [`2549`](https://github.com/lvgl/lvgl/pull/2549) +- fix(lv_log.h): remove the duplicated semicolon from LV_LOG_xxx [`2544`](https://github.com/lvgl/lvgl/pull/2544) +- fix(zoom) multiplication overflow on 16-bit platforms [`2536`](https://github.com/lvgl/lvgl/pull/2536) +- fix(printf) use __has_include for more accurate limits information [`2532`](https://github.com/lvgl/lvgl/pull/2532) +- fix(font) add assert in lv_font.c if the font is NULL [`2533`](https://github.com/lvgl/lvgl/pull/2533) +- fix(lv_types.h): remove c/c++ compiler version check [`2525`](https://github.com/lvgl/lvgl/pull/2525) +- fix(lv_utils.c): remove the unneeded header inclusion [`2526`](https://github.com/lvgl/lvgl/pull/2526) +- fix(Kconfig) fix the comment in LV_THEME_DEFAULT_DARK [`2524`](https://github.com/lvgl/lvgl/pull/2524) +- fix(sprintf) add format string for rp2 port [`2512`](https://github.com/lvgl/lvgl/pull/2512) +- fix(span) fix some bugs (overflow,decor,align) [`2518`](https://github.com/lvgl/lvgl/pull/2518) +- fix(color) Bad cast in lv_color_mix() caused UB with 16bpp or less [`2509`](https://github.com/lvgl/lvgl/pull/2509) +- fix(imgbtn) displayed incorrect when the coordinate is negative [`2501`](https://github.com/lvgl/lvgl/pull/2501) +- fix(event) be sure to move all elements in copy “lv_obj_remove_event_cb” [`2492`](https://github.com/lvgl/lvgl/pull/2492) +- fix(draw) use correct pointer in lv_draw_mask assertion [`2483`](https://github.com/lvgl/lvgl/pull/2483) +- feat(mem) LV_MEM_POOL_ALLOC [`2458`](https://github.com/lvgl/lvgl/pull/2458) +- fix(cmake) require 'main' for Micropython [`2444`](https://github.com/lvgl/lvgl/pull/2444) +- fix(docs) add static keyword to driver declaration [`2452`](https://github.com/lvgl/lvgl/pull/2452) +- fix(build) remove main component dependency [`2420`](https://github.com/lvgl/lvgl/pull/2420) +- fix circle drawing algorithms [`2413`](https://github.com/lvgl/lvgl/pull/2413) +- fix(docs) wrong spelling of words in pictures [`2409`](https://github.com/lvgl/lvgl/pull/2409) +- fix(chart) fixed point-following cursor during vertical scroll in charts [`2400`](https://github.com/lvgl/lvgl/pull/2400) +- fix(chart) fixed cursor positioning with large Y rescaling without LV_USE_LARGE_COORD [`2399`](https://github.com/lvgl/lvgl/pull/2399) +- fix(grid.h) typos [`2395`](https://github.com/lvgl/lvgl/pull/2395) +- fix(anim_timeline) heap use after free [`2394`](https://github.com/lvgl/lvgl/pull/2394) +- fix(snapshot) add missing import on MicroPython example [`2389`](https://github.com/lvgl/lvgl/pull/2389) +- fix(disp) Fix assert failure in lv_disp_remove [`2382`](https://github.com/lvgl/lvgl/pull/2382) +- fix(span) modify the underline position [`2376`](https://github.com/lvgl/lvgl/pull/2376) +- fix(color) remove extraneous _LV_COLOR_MAKE_TYPE_HELPER [`2372`](https://github.com/lvgl/lvgl/pull/2372) +- fix(spinner) should not be clickable [`2373`](https://github.com/lvgl/lvgl/pull/2373) +- fix(workflow) silence SDL warning for MicroPython [`2367`](https://github.com/lvgl/lvgl/pull/2367) +- fix (span) fill LV_EVENT_GET_SELF_SIZE [`2360`](https://github.com/lvgl/lvgl/pull/2360) +- fix(workflow) change MicroPython workflow to use master [`2358`](https://github.com/lvgl/lvgl/pull/2358) +- fix(disp) fix memory leak in lv_disp_remove [`2355`](https://github.com/lvgl/lvgl/pull/2355) +- fix(lv_obj.h)typos [`2350`](https://github.com/lvgl/lvgl/pull/2350) +- fix(obj) delete useless type conversion [`2343`](https://github.com/lvgl/lvgl/pull/2343) +- fix(lv_obj_scroll.h) typos [`2345`](https://github.com/lvgl/lvgl/pull/2345) +- fix(txt) enhance the function of break_chars [`2327`](https://github.com/lvgl/lvgl/pull/2327) + +- fix(vglite): update for v8 [`e3e3eea`](https://github.com/lvgl/lvgl/commit/e3e3eeaf8c1593d384c6537244a301cdc1abd3d9) +- fix(widgets) use lv_obj_class for all the widgets [`3fb8baf`](https://github.com/lvgl/lvgl/commit/3fb8baf503411e006765020f60f295a4be16ba2d) +- fix(refr) reduce the nesting level in lv_refr_area [`2df1282`](https://github.com/lvgl/lvgl/commit/2df12827dda3f217fa26d2c98445a9b3f1ff22ab) +- fix(pxp): update for v8 [`8a2a4a1`](https://github.com/lvgl/lvgl/commit/8a2a4a11c81d029ff737980b883c62dfbb4b44c6) +- fix(obj) move clean ups from lv_obj_del to lv_obj_destructor [`b063937`](https://github.com/lvgl/lvgl/commit/b06393747f61e36996a0cb22f9309c951f900ded) +- fix (draw) fix arc bg image drawing with full arcs [`c3b6c6d`](https://github.com/lvgl/lvgl/commit/c3b6c6dc64735e1bde492a8d5570f3e3a9500a0b) +- fix(pxp): update RTOS macro for SDK 2.10 [`00c3eb1`](https://github.com/lvgl/lvgl/commit/00c3eb197cb85e480809d97eb722589d75d81d94) +- fix(textarea) style update in oneline mode + improve sroll to cursor [`60d9a5e`](https://github.com/lvgl/lvgl/commit/60d9a5e493bf17ee9887ba44890d00905bc55970) +- feat(led) send LV_EVENT_DRAW_PART_BEGIN/END [`fcd4aa3`](https://github.com/lvgl/lvgl/commit/fcd4aa3924469c2a92ab6a04b7bc6de6304cc54a) +- fix warnings introduced by 3fb8baf5 [`e302403`](https://github.com/lvgl/lvgl/commit/e3024032dc5de2ece4fa17059ebad4189a5fa670) +- fix(roller) fix partial redraw of the selected area [`6bc40f8`](https://github.com/lvgl/lvgl/commit/6bc40f8c4417a94ab26b25220324e471e03ce443) +- fix(flex) fix layout update and invalidation issues [`5bd82b0`](https://github.com/lvgl/lvgl/commit/5bd82b038b841c0f7c93bbdacdbd61d6b9585846) +- fix(indev) focus on objects on release instead of press [`76a8293`](https://github.com/lvgl/lvgl/commit/76a8293375b705a5e02e4f9c8f8a42d99db762e2) +- fix tests [`449952e`](https://github.com/lvgl/lvgl/commit/449952e3b78d02802960dabb0207b960c82e8e5a) +- fix(dropdown) forget the selected option on encoder longpress [`e66b935`](https://github.com/lvgl/lvgl/commit/e66b9350617eee15e94fb6a353283433e4c2c494) +- fix(obj) improve how the focusing indev is determined [`a04f2de`](https://github.com/lvgl/lvgl/commit/a04f2dea644787ea25ef988a43e10c5005c57066) +- fix(workflow) speed up MicroPython workflow [`38ad5d5`](https://github.com/lvgl/lvgl/commit/38ad5d548b2024f0f742ba769a6715fc376541a1) +- fix(test) do not including anything in test files when not running tests [`9043860`](https://github.com/lvgl/lvgl/commit/90438603ad020799b14bc9839a51dceedfdabd7a) +- fix tests [`36b9db3`](https://github.com/lvgl/lvgl/commit/36b9db38b728b40096b9ee613f4482ef9654d570) +- fix(scroll) fire LV_EVENT_SCROLL_BEGIN in the same spot for both axes [`b158932`](https://github.com/lvgl/lvgl/commit/b1589326d41924292fbc2c62b474dec288bc9da5) +- fix(btnmatrix) fix button invalidation on focus change [`77cedfa`](https://github.com/lvgl/lvgl/commit/77cedfa08f3f8aec67c6a2fe8e5ae9bab5a0e7c7) +- fix(tlsf) do not use <assert.h> [`c9745b9`](https://github.com/lvgl/lvgl/commit/c9745b9c4ea9e7c6de4bd8ad9a0d8001bfb91165) +- fix(template) include lvgl.h in lv_port_*_template.c files [`0ae15bd`](https://github.com/lvgl/lvgl/commit/0ae15bd470548ff159f44e7c3f4b225ab3eec928) +- fix(docs) add margin for example description [`b5f632e`](https://github.com/lvgl/lvgl/commit/b5f632ee7a265ce4f2472522b422b8cd5366aaa9) +- fix(imgbtn) use the correct src in LV_EVENT_GET_SELF_SIZE [`04c515a`](https://github.com/lvgl/lvgl/commit/04c515adac764761e60094db789269130ac89b36) +- fix(color) remove extraneous cast for 8-bit color [`157534c`](https://github.com/lvgl/lvgl/commit/157534cdbfaa7b769114126f74c38661b99d025b) +- fix(workflow) use same Unix port variant for MicroPython submodules [`ac68b10`](https://github.com/lvgl/lvgl/commit/ac68b10e539ddb8bde47ec453a99f2b876e12c65) +- fix(README) improve grammar [`de81889`](https://github.com/lvgl/lvgl/commit/de81889cbdc889360e8bc00684f9ca77ff97d89f) +- fix(printf) skip defining attribute if pycparser is used [`ee9bbea`](https://github.com/lvgl/lvgl/commit/ee9bbea29c807707353e8b9ec09048990de18e4e) +- fix(README) spelling correction [`41869f2`](https://github.com/lvgl/lvgl/commit/41869f238e773e599959c9ef2fee0b7206712ee2) +- fix(color) overflow with 16-bit color depth [`fe6d8d7`](https://github.com/lvgl/lvgl/commit/fe6d8d7636ae283afda68e85b2d1f143d8d05462) +- fix(docs) consider an example to be visible over a wider area [`145a0fa`](https://github.com/lvgl/lvgl/commit/145a0fad0857dad7f2066e7d22436827e0d3fd7d) +- fix(codecov) disable uploading coverage for pull requests [`27d88de`](https://github.com/lvgl/lvgl/commit/27d88de899e91cd5bb9fc69fe9d71cb180cfb44b) +- fix(arc) disable LV_OBJ_FLAG_SCROLL_CHAIN by default [`f172eb3`](https://github.com/lvgl/lvgl/commit/f172eb3fd78481d6076ead395abfd765646ad21e) +- fix(template) update lv_objx_template to v8 [`38bb8af`](https://github.com/lvgl/lvgl/commit/38bb8afc16720e8d8fe6e72be6fae4f9da593bbc) +- fix(align) avoid circular references with LV_SIZE_CONTENT [`038b781`](https://github.com/lvgl/lvgl/commit/038b78122e72db67cec886d09eb2d21aaa019df7) +- fix(draw) with additive blending with 32-bit color depth [`786db2a`](https://github.com/lvgl/lvgl/commit/786db2afe6458e24681b8a40fa798429956d3420) +- fix(arc) fix arc invalidation again [`5ced080`](https://github.com/lvgl/lvgl/commit/5ced08001c384bf7c840750c0e254b5f0115a070) +- fix(align) fix lv_obj_align_to [`93b38e9`](https://github.com/lvgl/lvgl/commit/93b38e92be9ed3ae050a1ee6e5b680ab43fd4850) +- fix(scroll) keep the scroll position on object deleted [`52edbb4`](https://github.com/lvgl/lvgl/commit/52edbb46b0741d2761a11ef1b3d516ec96a7c8b3) +- fix(dropdown) handle LV_KEY_ENTER [`8a50edd`](https://github.com/lvgl/lvgl/commit/8a50edd0689c7133ca18fd476596ddc4088f86a9) +- fix various minor warnings [`924bc75`](https://github.com/lvgl/lvgl/commit/924bc754adcbabaf3518bac6067e7ea37f2f0f04) +- fix(textarea) various cursor drawing fixes [`273a0eb`](https://github.com/lvgl/lvgl/commit/273a0eb32f04e81f326288a71682bea1c812c76a) +- fix(label) consider base dir lv_label_get_letter_pos in special cases [`6df5122`](https://github.com/lvgl/lvgl/commit/6df51225c261b252f0935804b0357d6e585da53d) +- fix(imgbtn) add lv_imgbtn_set_state [`26e15fa`](https://github.com/lvgl/lvgl/commit/26e15fa577f97d510b218fb95fc9a4bd440b00bc) +- fix(printf) add (int) casts to log messages to avoid warnings on %d [`d9d3f27`](https://github.com/lvgl/lvgl/commit/d9d3f271267e760c8459b65c392914143a58b89c) +- fix(test) silence make [`7610d38`](https://github.com/lvgl/lvgl/commit/7610d38bb044b1bd95dd68ab57f79f82e2527cca) +- fix(test) silence make [`37fd9d8`](https://github.com/lvgl/lvgl/commit/37fd9d8a24c276079ed26b5d6704bcefc9f8dc70) +- fix(calendar) update the MP example [`0bab4a7`](https://github.com/lvgl/lvgl/commit/0bab4a72cf769872a9adfd5bfa1c4536e6f909a8) +- fix(scroll) fix scroll_area_into_view with objects larger than the parent [`5240fdd`](https://github.com/lvgl/lvgl/commit/5240fdda5ccc33d166f8201818868add5d1d6d0d) +- fix(msgbox) handle NULL btn map parameter [`769c4a3`](https://github.com/lvgl/lvgl/commit/769c4a30cf962be1f74e0b1cd7ebaefbd6ba8a8b) +- fix (scroll) do not send unnecessary scroll end events [`3ce5226`](https://github.com/lvgl/lvgl/commit/3ce5226c9d9db279904c4f076ae77e6e03572e4c) +- fix(obj_pos) consider all alignments in content size calculation but only if x and y = 0 [`5b27ebb`](https://github.com/lvgl/lvgl/commit/5b27ebb4097166f8c4a50ee5d39249939bf79814) +- fix(img decoder) add error handling if the dsc->data = NULL [`d0c1c67`](https://github.com/lvgl/lvgl/commit/d0c1c673a8ec17b842ebf97d5f21938ec8901346) +- fix(txt): skip basic arabic vowel characters when processing conjunction [`5b54800`](https://github.com/lvgl/lvgl/commit/5b548006eda0695cabf2ee237a7faee8c69e4659) +- fix(typo) rename LV_OBJ_FLAG_SNAPABLE to LV_OBJ_FLAG_SNAPPABLE [`e697807`](https://github.com/lvgl/lvgl/commit/e697807cf5c01be2531fc52df78ecad75ce39a7a) +- fix(lv_printf.h): to eliminate the errors in Keil and IAR [`f6d7dc7`](https://github.com/lvgl/lvgl/commit/f6d7dc7f00d0a20f7f1966ed890a225b1fc87107) +- fix(draw) fix horizontal gradient drawing [`4c034e5`](https://github.com/lvgl/lvgl/commit/4c034e56e049ad3d9bca5eb4b3e8721e60c11d36) +- fix(dropdown) use LV_EVENT_READY/CANCEL on list open/close [`4dd1d56`](https://github.com/lvgl/lvgl/commit/4dd1d566fc30bbaf1424dda8b78df97c6bf07402) +- fix(table) clip overflowing content [`8c15933`](https://github.com/lvgl/lvgl/commit/8c15933030cad6cdbfe4967f566ed6959547fada) +- fix(test) add #if guard to exclude test related files from the build [`c12a22e`](https://github.com/lvgl/lvgl/commit/c12a22ee87681d1344696a3b9531e9100808eb85) +- fix(test) add #if guard to exclude test related files from the build [`fc364a4`](https://github.com/lvgl/lvgl/commit/fc364a466c0693aefa0401f5eddee2bbc3037ef0) +- fix(freetype) fix underline calculation [`76c8ee6`](https://github.com/lvgl/lvgl/commit/76c8ee6b7e81d8640aa5ba620947660a1c90482b) +- fix(style) refresh ext. draw pad for padding and bg img [`37a5d0c`](https://github.com/lvgl/lvgl/commit/37a5d0c85ac28718f4f32eadff3ddaf6b474cf75) +- fix(draw) underflow in subpixel font drawing [`6d5ac70`](https://github.com/lvgl/lvgl/commit/6d5ac702ad20ac3092c224ca36e412b0d6cec321) +- fix(scrollbar) hide the scrollbar if the scrollble flag is removed [`188a946`](https://github.com/lvgl/lvgl/commit/188a9467b1bd45d42368a687736a9151d081c1e8) +- fix(color): minor fixes(#2767) [`a4978d0`](https://github.com/lvgl/lvgl/commit/a4978d0913be705caffe3c080524bb7915a5e3e2) +- fix(group) skip object if an of the parents is hidden [`5799c10`](https://github.com/lvgl/lvgl/commit/5799c1084398b365c7a9669406d4fbe258a501ef) +- fix(obj) fix size invalidation issue on padding change [`33ba722`](https://github.com/lvgl/lvgl/commit/33ba7225f55f0cb17f73ce891466c7ebe1327898) +- fix(label) do not bidi process text in lv_label_ins_text [`e95efc1`](https://github.com/lvgl/lvgl/commit/e95efc152f52b7495acb011353a55b3663f7860e) +- fix(refr) set disp_drv->draw_buf->flushing_last correctly with sw rotation [`c514bdd`](https://github.com/lvgl/lvgl/commit/c514bddd9b4064e2eba0c3ec4c7a51415acd74e4) +- fix(draw) fix drawing small arcs [`8081599`](https://github.com/lvgl/lvgl/commit/8081599e9b65c758bbdc0168f857515bebaf1c80) +- fix(chart) invalidation with LV_CHART_UPDATE_MODE_SHIFT [`d61617c`](https://github.com/lvgl/lvgl/commit/d61617cd67f792908a1554a44c663c73a41bb357) +- fix(build) fix micropython build error [`54338f6`](https://github.com/lvgl/lvgl/commit/54338f6e57518a59615bdd191fcf5af1365eabea) +- fix(draw) fix border width of simple (radius=0, no masking) borders [`20f1867`](https://github.com/lvgl/lvgl/commit/20f186759664f31f07d6613ea8d77df256cd4597) +- fix(calendar) fix calculation today and highlighted day [`8f0b5ab`](https://github.com/lvgl/lvgl/commit/8f0b5ab0230007fa72127b78db500b9ceb84bf35) +- fix(style) initialize colors to black instead of zero [`524f8dd`](https://github.com/lvgl/lvgl/commit/524f8dd50b4407c78fa6cd947c42e73eab401da1) +- fix(sjpg) remove unnecessary typedefs [`c2d93f7`](https://github.com/lvgl/lvgl/commit/c2d93f78b98ba347001bd29d58b6654492bb8d70) +- fix(label) fix clipped italic letters [`2efa6dc`](https://github.com/lvgl/lvgl/commit/2efa6dce78604cdf422ff233a99f7dd5f06b821c) +- fix(draw) shadow drawing with large shadow width [`f810265`](https://github.com/lvgl/lvgl/commit/f810265c0d91135b71ae110d33d43841ec0e44f8) +- fix(dropdown) add missing invalidations [`33b5d4a`](https://github.com/lvgl/lvgl/commit/33b5d4a4fe6f28962ee7988f74d5ae842dc49b04) +- fix(dropdown) adjust the handling of keys sent to the dropdown [`e41c507`](https://github.com/lvgl/lvgl/commit/e41c50780495c7d6ac6a2b0edf12fc98c9d85a6b) +- fix(disp) be sure the pending scr load animation is finished in lv_scr_load_anim [`eb6ae52`](https://github.com/lvgl/lvgl/commit/eb6ae526432453e4b9dbc7a760cd65d164050548) +- fix(color) fox color premult precision with 16-bit color depth [`f334226`](https://github.com/lvgl/lvgl/commit/f3342269f272c474265700527f52d3ba92111531) +- fix(obj_pos) save x,y even if the object is on a layout [`a9b660c`](https://github.com/lvgl/lvgl/commit/a9b660c278658224f05fbe43d0199c48711db9fd) +- fix(scrollbar) hide the scrollbar if the scrollable flag is removed [`d9c6ad0`](https://github.com/lvgl/lvgl/commit/d9c6ad0425e761d605124e4555adc72854fec4a6) +- fix(dropdown) fix list position with RTL base direction [`79edb37`](https://github.com/lvgl/lvgl/commit/79edb37b0ab5015111bade6074fda81ae101b91b) +- fix(obj) fix lv_obj_align_to with RTL base direction [`531afcc`](https://github.com/lvgl/lvgl/commit/531afcc6cec7f67df06e369a185aef6fdc85af7b) +- fix(chart) fix sending LV_EVENT_DRAW_PART_BEGIN/END for the cursor [`34b8cd9`](https://github.com/lvgl/lvgl/commit/34b8cd9c12604bc1029efa39bd66322b8b771dbe) +- fix(arduino) fix the prototype of my_touchpad_read in the LVGL_Arduino.ino [`1a62f7a`](https://github.com/lvgl/lvgl/commit/1a62f7a619faa93406bc5895ac3338c232de2226) +- fix(checkbox) consider the bg border when positioning the indicator [`a39dac9`](https://github.com/lvgl/lvgl/commit/a39dac9e5c82ecabd135953acafa335941ca0a89) +- fix(dropdown) send LV_EVENT_VALUE_CHANGED to allow styling of the list [`dae7039`](https://github.com/lvgl/lvgl/commit/dae7039803030f908986602b3ce308dc1c3974af) +- fix(group) fix infinite loop [`bdce0bc`](https://github.com/lvgl/lvgl/commit/bdce0bc60cb6e938ce39a0defe5b24249bc66a99) +- fix(keyboard) use LVGL heap functions instead of POSIX [`b20a706`](https://github.com/lvgl/lvgl/commit/b20a706112a3107db13bbd405991ece4cbe00a88) +- fix(blend) fix green channel with additive blending [`78158f0`](https://github.com/lvgl/lvgl/commit/78158f039f19eb17bf1b7c173922c1af26c1e528) +- fix(btnmatrix) do not show pressed, focused or focus key states on disabled buttons [`3df2a74`](https://github.com/lvgl/lvgl/commit/3df2a7444758d2df023f321ccb5931de44af2a48) +- fix(font) handle the last pixel of the glyphs in font loader correctly [`fa98989`](https://github.com/lvgl/lvgl/commit/fa9898941f8efa1966cb6f326d1eebdd31211d04) +- fix(table) fix an off-by-one issue in self size calculation [`ea2545a`](https://github.com/lvgl/lvgl/commit/ea2545ae5dade0845889174737d072137bbb6591) +- fix shadowed variable [`e209260`](https://github.com/lvgl/lvgl/commit/e20926056b28bb64f38abc764a4fca045757e800) +- fix shadowed variable [`df60018`](https://github.com/lvgl/lvgl/commit/df600183f211bde0ff34add973a7a401a1da9af1) +- fix(chart) be sure the chart doesn't remain scrolled out on zoom out [`ad5b1bd`](https://github.com/lvgl/lvgl/commit/ad5b1bdc00a4a44e775a280f8b686353ef4f2a38) +- fix(docs) commit to meta repo as lvgl-bot instead of actual commit author [`f0e8549`](https://github.com/lvgl/lvgl/commit/f0e8549fe14d4e95aedcc98a63acce5a4ad1145b) +- fix(table) invalidate the table on cell value change [`cb3692e`](https://github.com/lvgl/lvgl/commit/cb3692e3029ae452eab04dce21715b7863a9f2a1) +- fix(group) allow refocusing objects [`1520208`](https://github.com/lvgl/lvgl/commit/1520208b14c38713719f507273024624a0f54f1a) +- fix(tabview) fix with left and right tabs [`17c5744`](https://github.com/lvgl/lvgl/commit/17c57449eeae8a693ad5601cf4169cf44d57d5c9) +- fix(msgbox) create modals on top layer instead of act screen [`5cf6303`](https://github.com/lvgl/lvgl/commit/5cf6303e741ec22e2e87f69af4109855eb637e63) +- fix(theme) show disabled state on buttons of btnmatrix, msgbox and keyboard [`0be582b`](https://github.com/lvgl/lvgl/commit/0be582b391e60774d6158411b835b679b010a99b) +- fix(label) update lv_label_get_letter_pos to work with LV_BASE_DIR_AUTO too [`580e05a`](https://github.com/lvgl/lvgl/commit/580e05a0e1531d86d5229ade4ced2c336fbce634) +- fix(label) fix in lv_label_get_letter_pos with when pos==line_start [`58f3f56`](https://github.com/lvgl/lvgl/commit/58f3f5625c2b29278c3e122d8eeba4d9bc597db9) +- fix(gif) replace printf statement with LVGL logging [`56f62b8`](https://github.com/lvgl/lvgl/commit/56f62b8d7356017319d21d44a8f450705ec6486b) +- fix(docs) add fsdrv back [`64527a5`](https://github.com/lvgl/lvgl/commit/64527a5a1ba9d37883c1303a3d4ee1a41e9b4ed3) +- fix(table) remove unnecessary invalidation on pressing [`6f90f9c`](https://github.com/lvgl/lvgl/commit/6f90f9cefba0bc1ea74e737e0e659402f0309cf7) +- fix(chart) draw line chart indicator (bullet) [`fba37a3`](https://github.com/lvgl/lvgl/commit/fba37a30abd1b4d7af78a288fb61dccacc99da08) +- fix(anim) return the first anim if exec_cb is NULL in lv_anim_get() [`fb7ea10`](https://github.com/lvgl/lvgl/commit/fb7ea1040153bd0f2d5c282f9fb31add32c55ce9) +- fix(label) fix lv_label_get_letter_on with BIDI enabled [`192419e`](https://github.com/lvgl/lvgl/commit/192419e7bb300bd64b51d684827719fe1c22cfdb) +- fix(checkbox) add missing invalidations [`bb39e9d`](https://github.com/lvgl/lvgl/commit/bb39e9d6f95235445e3ea1bc52b0d5a1b7a2e24a) +- fix(draw) fix gradient calculation of the rectangle is clipped [`13e3470`](https://github.com/lvgl/lvgl/commit/13e347055bd54c37e7fcb645120ea9ab3134ebec) +- fix(chart) fix typo in 655f42b8 [`6118d63`](https://github.com/lvgl/lvgl/commit/6118d63c2f23e2a157c84a010dcfa0d1fa851382) +- fix(example) fix lv_example_chart_2 [`89081c2`](https://github.com/lvgl/lvgl/commit/89081c2d6ee418b326538e1f39345d43864993c8) +- fix(calendar) fix the position calculation today [`ad05e19`](https://github.com/lvgl/lvgl/commit/ad05e196fb3937ebcba211495013700c0022f777) +- fix(tick) minor optimization on lv_tick_inc call test [`b4305df`](https://github.com/lvgl/lvgl/commit/b4305df5745684a785be071149de8dd342817db4) +- fix(docs) use let instead of const for variable which gets changed [`3cf5751`](https://github.com/lvgl/lvgl/commit/3cf5751461d6a85974da4e5c66593736ae140a1a) +- fix(theme) fix the switch style in the default theme [`0c0dc8e`](https://github.com/lvgl/lvgl/commit/0c0dc8ea30289254732cbba7ada7fd4f092caf22) +- fix(tlsf) undef printf before define-ing it [`cc935b8`](https://github.com/lvgl/lvgl/commit/cc935b87f69e6107d12d9ba4a2c83103f7dd4356) +- fix(msgbox) prevent the buttons being wider than the msgbox [`73e036b`](https://github.com/lvgl/lvgl/commit/73e036bba748e8677f219f573cba5f82c4158a17) +- fix(chart) don't draw series lines with < 1 points [`655f42b`](https://github.com/lvgl/lvgl/commit/655f42b852669f27ab8bfde84bf70cf0b7ea027d) +- fix(tests) remove src/test_runners when cleaning [`6726b0f`](https://github.com/lvgl/lvgl/commit/6726b0f5df3f4689368782b601bb01f76498123b) +- fix(label) remove duplicated lv_obj_refresh_self_size [`a070ecf`](https://github.com/lvgl/lvgl/commit/a070ecfe8c1cf7c07c035ba6c35c3ffaef56d6e1) +- fix(colorwheel) disable LV_OBJ_FLAG_SCROLL_CHAIN by default [`48d1c29`](https://github.com/lvgl/lvgl/commit/48d1c292a3c19380d5669baf911954cc1b083d43) + +- fix(obj) do not set the child's position in lv_obj_set_parent [`d89a5fb`](https://github.com/lvgl/lvgl/commit/d89a5fbbd2af33cf759c120e6a14b334099c4c98) +- feat: add LV_USE_MEM_PERF/MONITOR_POS [`acd0f4f`](https://github.com/lvgl/lvgl/commit/acd0f4fbc71ffbfeb382b7af1fa52caf3cdcda6c) +- fix(scroll) in scroll to view functions respect disabled LV_OBJ_FLAG_SCROLLABLE [`9318e02`](https://github.com/lvgl/lvgl/commit/9318e02ef5e29d2f6ce0ab4b2aa67c6542752822) +- fix(flex) remove unused variable [`747b6a2`](https://github.com/lvgl/lvgl/commit/747b6a2a9af9bafe4e6c778cca23e278cb7e4ea4) +- feat(canvas) add lv_canvas_set_px_opa [`b3b3ffc`](https://github.com/lvgl/lvgl/commit/b3b3ffc2b3b322f7401d15c4ba2ef0cdb00e2990) +- fix(textarea) allow using cursor with not full bg_opa [`c9d3965`](https://github.com/lvgl/lvgl/commit/c9d396571d0726aab5d011f37df648d337e5bc12) +- fix(txt) _lv_txt_get_next_line return 0 on empty texts [`82f3fbc`](https://github.com/lvgl/lvgl/commit/82f3fbcad7b710a89b876c32f3583090c99e847c) +- fix(btnmatrix) always update row_cnt [`86012ae`](https://github.com/lvgl/lvgl/commit/86012aefc7197209357290c780029aa39b3738dc) +- fix(scroll) minor fixes on obj scroll handling [`a4128a8`](https://github.com/lvgl/lvgl/commit/a4128a83562e0daacd949333ba7cbfec650f8050) +- fix(table) consider border width for cell positions [`f2987b6`](https://github.com/lvgl/lvgl/commit/f2987b6591046f1384b0089187fd81da10834021) +- fix(log) be sure LV_LOG_... is not empty if logs are disabled [`47734c4`](https://github.com/lvgl/lvgl/commit/47734c4abedf6b6005069d15a8c4c2fcff73f85e) +- fix(arc) fix LV_ARC_MODE_REVERSE [`df3b969`](https://github.com/lvgl/lvgl/commit/df3b96900b1266ed4856438d9121e39905d510bb) +- fix(obj) in lv_obj_move_to_index() do not send LV_EVENT_CHILD_CHANGED on all changed child [`32e8276`](https://github.com/lvgl/lvgl/commit/32e8276db7403d8dc9c9b9f0c77d331049e8c07d) +- feat(event) add lv_obj_remove_event_cb_with_user_data [`4eddeb3`](https://github.com/lvgl/lvgl/commit/4eddeb35abee1f9cd2d1fd210f11cc096cb609c7) +- fix(draw) fix shadow drawing with radius=0 [`4250e3c`](https://github.com/lvgl/lvgl/commit/4250e3c62737697cd8bc78d991a3d66216efa437) +- fix(msgbox) directly store the pointer of all children [`eb5eaa3`](https://github.com/lvgl/lvgl/commit/eb5eaa39406473cd90a7f78d710ce950cbf47548) +- fix(draw) use the filtered colors in lv_obj_init_draw_xxx_dsc() functions [`78725f2`](https://github.com/lvgl/lvgl/commit/78725f23da24fe22543ab3388c87bf3cfbd0e51a) +- fix(arc) fix full arc invalidation [`98b9ce5`](https://github.com/lvgl/lvgl/commit/98b9ce599751c9de0421acd419430cc6ccd7cad9) +- chore(led) expose LV_LED_BRIGHT_MIN/MAX in led.h [`3f18b23`](https://github.com/lvgl/lvgl/commit/3f18b234f601edefb16b1ffdb0c539e823b1c025) +- fix(group) keep the focused object in lv_group_swap_obj [`a997147`](https://github.com/lvgl/lvgl/commit/a9971471ba34352a1d7b307977cb2f635b28a031) +- fix(obj) swap objects in the group too in lv_obj_swap() [`52c7558`](https://github.com/lvgl/lvgl/commit/52c7558ab46a7024e05499edb483f115b13086f0) +- fix(theme) use opacity on button's shadow in the default theme [`c5342e9`](https://github.com/lvgl/lvgl/commit/c5342e9324c492c70b65f8c228d44b7a290cf110) +- fix(win) enable clip_corner and border_post by default [`493ace3`](https://github.com/lvgl/lvgl/commit/493ace352fea0eaa37abccaa0938c0c4a12a995a) +- fix(draw) fix rectangle drawing with clip_corner enabled [`01237da`](https://github.com/lvgl/lvgl/commit/01237da474b9703fb544163db5f66645c2b6935c) +- fix(arc) fix other invalidation issues [`b0a7337`](https://github.com/lvgl/lvgl/commit/b0a733766daee1edfabaec8df4a5fedd0180ccaf) +- feat(obj) add lv_obj_get_x/y_aligned [`98bc1fe`](https://github.com/lvgl/lvgl/commit/98bc1fe09e12a64333e91b4c25327c283a700af5) +- fix(calendar) fix incorrect highlight of today [`adbac52`](https://github.com/lvgl/lvgl/commit/adbac5220b2d75f08de110b3f426066e24f46998) +- fix(arc, meter) fix invalidation in special cases [`0f14f49`](https://github.com/lvgl/lvgl/commit/0f14f49465ca701c98f76ac95bda4a537c0fadfa) +- fix(canvas) invalidate the image on delete [`a1b362c`](https://github.com/lvgl/lvgl/commit/a1b362c98622ecbc063cfb17fb091fdab4522e8a) +- fix(msgbox) return the correct pointer from lv_msgbox_get_text [`50ea6fb`](https://github.com/lvgl/lvgl/commit/50ea6fb3fefb3a6edc958154c575dcdcacbfdb3a) +- fix(bidi) fix the handling of LV_BASE_DIR_AUTO in several widgets [`7672847`](https://github.com/lvgl/lvgl/commit/7672847ce325e909981582b4153993025da7fe50) +- fix(build) remove main component dependency (#2420) [`f2c2393`](https://github.com/lvgl/lvgl/commit/f2c2393b305cd71d2fc01ff8945965dccb8488b4) +- fix(meter) fix inner mask usage [`c28c146`](https://github.com/lvgl/lvgl/commit/c28c14631040fd08da122e192458cb0c65bc9faf) +- fix(log) fix warning for empty log macros [`4dba8df`](https://github.com/lvgl/lvgl/commit/4dba8df2a196fc7a2b7a8686efb6e47fc6cf0fc6) +- fix(theme) improve button focus of keyboard [`2504b7e`](https://github.com/lvgl/lvgl/commit/2504b7e4361ad8009e005faf112987585c2e8356) +- fix(tabview) send LV_EVENT_VALUE_CHANGED only once [`933d282`](https://github.com/lvgl/lvgl/commit/933d2829aca8bc269c0b481f2a535274626374bc) +- fix(obj style) fix children reposition if the parent's padding changes. [`57cf661`](https://github.com/lvgl/lvgl/commit/57cf6610a9ec2e6458035abfdaa5554f4296c89c) +- fix(template) update indev template for v8 [`d8a3d3d`](https://github.com/lvgl/lvgl/commit/d8a3d3d0d759ad0145f134a3f08433f3fdffcb75) +- fix(obj) detecting which indev sent LV_EVENT_FOCUS [`f03d4b8`](https://github.com/lvgl/lvgl/commit/f03d4b8cb9928077a04b839db0bd5c625919d903) +- fix(roller) adjust the size of the selected area correctly [`01d1c87`](https://github.com/lvgl/lvgl/commit/01d1c873e19d0d77e1444ba79468db63f26a448a) +- fix(imgbtn) consider width==LV_SIZE_CONTENT if only mid. img is set [`7e49f48`](https://github.com/lvgl/lvgl/commit/7e49f48894c5c3eb9793dbf1c8630f3cfdc3c091) +- fix(flex) fix NULL pointer dereference [`97ba12f`](https://github.com/lvgl/lvgl/commit/97ba12f280f0fa5400ff18c5317b9736063d8391) +- fix(obj, switch) do not send LV_EVENT_VALUE_CHANGED twice [`713b39e`](https://github.com/lvgl/lvgl/commit/713b39ecdb7e8e219cc295bad7d953ff2136f138) +- fix(coords) fix using large coordinates [`428db94`](https://github.com/lvgl/lvgl/commit/428db9494dc43d65026a9c1fb42c50daede82fc2) +- fix(chart) fix crash if no series are added [`c728b5c`](https://github.com/lvgl/lvgl/commit/c728b5ceda0a5a93d5a0859eb88261db582cf1eb) +- fix(meter) fix needle image invalidation [`54d8e81`](https://github.com/lvgl/lvgl/commit/54d8e8170bd4964909cee15a256408e7f08ccf21) +- fix(mem) add lv_ prefix to tlsf functions and types [`0d52b59`](https://github.com/lvgl/lvgl/commit/0d52b59cb16dda377f8a1ac581a851b830b7bf53) +- fix(pxp) change LV_COLOR_TRANSP to LV_COLOR_CHROMA_KEY to v8 compatibility [`81f3068`](https://github.com/lvgl/lvgl/commit/81f3068dd77d47e7079e6697ea5d00f69202c1bd) + +### Examples + +- example(chart) add area chart example [`2507`](https://github.com/lvgl/lvgl/pull/2507) +- example(anim) add demo to use cubic-bezier [`2393`](https://github.com/lvgl/lvgl/pull/2393) +- feat(example) add lv_example_chart_9.py [`2604`](https://github.com/lvgl/lvgl/pull/2604) +- feat(example) add lv_example_chart_8.py [`2611`](https://github.com/lvgl/lvgl/pull/2611) +- feat(example) chart example to add gap between the old and new data [`2565`](https://github.com/lvgl/lvgl/pull/2565) +- feat(example) add lv example list 2 [`2545`](https://github.com/lvgl/lvgl/pull/2545) +- feat(examples) add MicroPython version of lv_example_anim_3 and allow loading roller font dynamically [`2412`](https://github.com/lvgl/lvgl/pull/2412) +- feat(examples) added MP version of second tabview example [`2347`](https://github.com/lvgl/lvgl/pull/2347) +- fix(example):format codes [`2731`](https://github.com/lvgl/lvgl/pull/2731) +- fix(example) minor fixes in lv_example_chart_2.py [`2601`](https://github.com/lvgl/lvgl/pull/2601) +- feat(example) add text with gradient example [`462fbcb`](https://github.com/lvgl/lvgl/commit/462fbcbf49f47b9f329b6c15d2ca04ef09806cd9) +- fix(example_roller_3) mask free param bug [`2553`](https://github.com/lvgl/lvgl/pull/2553) +- fix(examples) don't compile assets unless needed [`2523`](https://github.com/lvgl/lvgl/pull/2523) +- fix(example) scroll example sqort types [`2498`](https://github.com/lvgl/lvgl/pull/2498) +- fix(examples) join usage [`2425`](https://github.com/lvgl/lvgl/pull/2425) +- fix(examples) add missing lv.PART.INDICATOR [`2423`](https://github.com/lvgl/lvgl/pull/2423) +- fix(examples) use lv.grid_fr for MicroPython [`2419`](https://github.com/lvgl/lvgl/pull/2419) +- fix(examples) remove symlinks [`2406`](https://github.com/lvgl/lvgl/pull/2406) +- fix(examples) import 'u'-prefixed versions of modules [`2365`](https://github.com/lvgl/lvgl/pull/2365) +- fix(examples) remove cast in MP scripts [`2354`](https://github.com/lvgl/lvgl/pull/2354) +- fix(examples) fix MicroPython examples and run the examples with CI [`2339`](https://github.com/lvgl/lvgl/pull/2339) +- fix(examples) align with renamed Micropython APIs [`2338`](https://github.com/lvgl/lvgl/pull/2338) + +- fix(examples) adjust canvas example for MicroPython API change [`52d1c2e`](https://github.com/lvgl/lvgl/commit/52d1c2e5b53eda4270abc0caa0eb309b35c010c8) +- fix(example) revert test code [`77e2c1f`](https://github.com/lvgl/lvgl/commit/77e2c1ff3d3ff035a3613f2ed0e5538513e8b4a1) +- feat(example) add checkbox example for radio buttons [`d089b36`](https://github.com/lvgl/lvgl/commit/d089b364e700d1216813106f7b4dfa6cee9aa806) +- feat(example) add text with gradient example [`462fbcb`](https://github.com/lvgl/lvgl/commit/462fbcbf49f47b9f329b6c15d2ca04ef09806cd9) +- fix(examples) exclude example animimg images if animimg is disabled [`4d7d306`](https://github.com/lvgl/lvgl/commit/4d7d30677af9ef158fe51fb1d8900d234ea5e181) +- fix(example) adjust the object sizes in lv_example_anim_timeline_1() [`71a10e4`](https://github.com/lvgl/lvgl/commit/71a10e4ecd4acfddcea279a0b5da219dfb002ff7) +- fix(example) revert text code from lv_example_checkbox_2 [`28e9593`](https://github.com/lvgl/lvgl/commit/28e9593e5802a2e7d493515059c6327e60ccbf28) + + +### Docs + +- docs: fix typo [`2765`](https://github.com/lvgl/lvgl/pull/2765) +- docs(colorwheel) fix old API names [`2643`](https://github.com/lvgl/lvgl/pull/2643) +- docs(display) fix typo [`2624`](https://github.com/lvgl/lvgl/pull/2624) +- docs add static for lv_indev_drv_t [`2605`](https://github.com/lvgl/lvgl/pull/2605) +- docs(animimg) add to extra widgets index and fix example [`2610`](https://github.com/lvgl/lvgl/pull/2610) +- docs(animimg) Add missing animation image page [`2609`](https://github.com/lvgl/lvgl/pull/2609) +- docs(group) remove reference to lv_cont which is gone in v8 [`2580`](https://github.com/lvgl/lvgl/pull/2580) +- docs(style) use correct API name for local styles [`2550`](https://github.com/lvgl/lvgl/pull/2550) +- docs(all) Proofread, fix typos and add clarifications in confusing areas [`2528`](https://github.com/lvgl/lvgl/pull/2528) +- docs(flex) update flex.md [`2517`](https://github.com/lvgl/lvgl/pull/2517) +- docs more spelling fixes [`2499`](https://github.com/lvgl/lvgl/pull/2499) +- docs fix typo: arae -> area [`2488`](https://github.com/lvgl/lvgl/pull/2488) +- docs(readme) fix typo: hosing → hosting. [`2477`](https://github.com/lvgl/lvgl/pull/2477) +- docs update company name and year [`2476`](https://github.com/lvgl/lvgl/pull/2476) +- docs fix typos [`2472`](https://github.com/lvgl/lvgl/pull/2472) +- docs(overview) fix typo [`2465`](https://github.com/lvgl/lvgl/pull/2465) +- docs(bar) fix typos in widget examples [`2463`](https://github.com/lvgl/lvgl/pull/2463) +- docs(overview) fix typo [`2454`](https://github.com/lvgl/lvgl/pull/2454) +- docs(chart) typos [`2427`](https://github.com/lvgl/lvgl/pull/2427) +- docs(layout) add internal padding paragraph to grid and flex layout p… [`2392`](https://github.com/lvgl/lvgl/pull/2392) +- docs(porting) fix indev example to remove v7 bool return [`2381`](https://github.com/lvgl/lvgl/pull/2381) +- docs(README) fix broken references [`2329`](https://github.com/lvgl/lvgl/pull/2329) +- docs(grid) typo fix [`2310`](https://github.com/lvgl/lvgl/pull/2310) +- docs(color) language fixes [`2302`](https://github.com/lvgl/lvgl/pull/2302) +- docs(lv_obj_style) update add_style and remove_style function headers [`2287`](https://github.com/lvgl/lvgl/pull/2287) + +- docs(contributing) add commit message format section [`3668e54`](https://github.com/lvgl/lvgl/commit/3668e54f06b9e51f407b6f6eb24829c03e3d0ac5) +- docs minor typo fixes [`84c0086`](https://github.com/lvgl/lvgl/commit/84c00862ae0213a54469e08900da7acf435ed5fe) +- docs(arduino) update some outdated information [`9a77102`](https://github.com/lvgl/lvgl/commit/9a77102c40f68140d0ba2c6c5e493e51a8773f64) +- docs(keyboard) add note regarding event handler [`255f729`](https://github.com/lvgl/lvgl/commit/255f7294d387d65bbc56c0f8af84f7fa2f3cfdfa) +- docs minor CSS fix [`acbb680`](https://github.com/lvgl/lvgl/commit/acbb680683fc726e942f59d4296501838e90bde1) +- docs minor CSS improvements [`7f367d6`](https://github.com/lvgl/lvgl/commit/7f367d6956c4d87b75a90cf1798550e986c5c248) +- docs(keyboard) change `LV_KEYBOARD_MODE_NUM` to `LV_KEYBOARD_MODE_NUMBER` [`6e83d37`](https://github.com/lvgl/lvgl/commit/6e83d378e933c426550a7d6bc8fd0dd7fa9ba051) +- docs(textarea) clarify the use of text selection bg_color [`65673c0`](https://github.com/lvgl/lvgl/commit/65673c0e15c48b5926da26ae1a1b8d0a0a8161a3) +- docs list all examples on one page [`25acaf4`](https://github.com/lvgl/lvgl/commit/25acaf45ca87271106b23b52d0d941228e117859) +- docs(examples) add MicroPython examples [`6f37c4f`](https://github.com/lvgl/lvgl/commit/6f37c4fc560c13545177e15576c5b3085c8f2c2a) +- docs(filesystem) update to v8 [`7971ade`](https://github.com/lvgl/lvgl/commit/7971ade47b15898efb6fca17d34ca30f1ee5c926) +- docs(style) complete the description of style the properties [`55e8846`](https://github.com/lvgl/lvgl/commit/55e8846871f812f888c8354e4ec8974ac0650165) +- docs example list fixes [`cd600d1`](https://github.com/lvgl/lvgl/commit/cd600d105650bae08f9732a654c6a2c85e610cd5) +- docs(style) complete the description of style the properties [`ff087da`](https://github.com/lvgl/lvgl/commit/ff087dafb4ecd016ee4920bfe4f162b1db58f7cb) +- docs(README) update links, examples, and add services menu [`3471bd1`](https://github.com/lvgl/lvgl/commit/3471bd1c698ee58f6632415559dcc34e9d2ee3c0) +- docs(color) update colors' docs [`9056b5e`](https://github.com/lvgl/lvgl/commit/9056b5ee1bfea6796307bdf983a4a00ea47fe9f0) +- docs update lv_fs.h, layer and align.png to v8 [`31ab062`](https://github.com/lvgl/lvgl/commit/31ab0628d5cfc57e55f42e5f59689388b034177c) +- docs(color) minor fix [`ac8f453`](https://github.com/lvgl/lvgl/commit/ac8f4534a51b418377c2eac62dbd731b9be71977) +- docs update changelog [`c386110`](https://github.com/lvgl/lvgl/commit/c386110e2390399ab97936622e59c510ba414e19) +- docs(extra) add extra/README.md [`8cd504d`](https://github.com/lvgl/lvgl/commit/8cd504d58bb679fe1f260e3eee59fcb0b85cb589) +- docs add lazy load to the iframes of the examples [`c49e830`](https://github.com/lvgl/lvgl/commit/c49e830aad2c847611f3398767e85c193909559a) +- docs(os) add example and clarify some points [`d996453`](https://github.com/lvgl/lvgl/commit/d996453207caa50a90a66d05565431fa288be96b) +- docs(rlottie) fix build error [`ce0b564`](https://github.com/lvgl/lvgl/commit/ce0b56458846daa65288f901e9b8ef1083eab468) +- docs include paths in libs [`f5f9562`](https://github.com/lvgl/lvgl/commit/f5f956233657f95b45a45d872e5d6e68c05eecd4) +- docs libs fixes [`8e7bba6`](https://github.com/lvgl/lvgl/commit/8e7bba6acec66a4f6b80496de9fd21a8e3c4c6ee) +- docs(obj) add comment lv_obj_get_x/y/width/height about postponed layout recalculation [`533066e`](https://github.com/lvgl/lvgl/commit/533066e6accbe2cbe1b60556eb61ebb2a07185a2) +- docs fix example list [`ed77ed1`](https://github.com/lvgl/lvgl/commit/ed77ed1dae088ef29194cf3c6bb552e1ee67d78b) +- docs describe the options to include or skip lv_conf.h [`174ef66`](https://github.com/lvgl/lvgl/commit/174ef6692e0b05338890a1cf524d9dcbf5c25f6c) +- docs(overview) spelling fixes [`d2efb8c`](https://github.com/lvgl/lvgl/commit/d2efb8c6e5ceedbb9d9c1a1c89ef709e6570e360) +- docs(table) describe keypad/encoder navigation [`749d1b3`](https://github.com/lvgl/lvgl/commit/749d1b3ec31ec2ef27f594ed0a4af93edb2c10f0) +- docs update CHANGELOG [`0f8bc18`](https://github.com/lvgl/lvgl/commit/0f8bc18f6aacb6a74e0bda59068d3d178fa66434) +- docs(image) mention the frame_id parameter of lv_img_decoder_open [`2433732`](https://github.com/lvgl/lvgl/commit/2433732570a817f566308e025d89227a8c650f5f) +- docs(arduino) update how to use the examples [`06962a5`](https://github.com/lvgl/lvgl/commit/06962a564fd668eced22b2e9bc19e7732abf94ec) +- docs(rlottie): fix typo in commands [`ed9169c`](https://github.com/lvgl/lvgl/commit/ed9169c56dc1f34b1f021457b78c9f3eccba13cf) +- docs(indev, layer) update lv_obj_set_click() to lv_obj_add_flag() [`bcd99e8`](https://github.com/lvgl/lvgl/commit/bcd99e8e438cc1b63762f8933d26bbb38fd42a2d) +- docs update version support table [`e6e98ab`](https://github.com/lvgl/lvgl/commit/e6e98abbc25cc4aa20b05d1002a651e4012ebff7) +- docs fix example list [`c6f99ad`](https://github.com/lvgl/lvgl/commit/c6f99ad200c7862c2f3cca3811bc2bdc2c95e971) +- docs(examples) add <hr/> to better separate examples [`a1b59e3`](https://github.com/lvgl/lvgl/commit/a1b59e34dd23fb12bd6e9ab0ffa92b2bfcec66b3) +- docs(checkbox) update the comment lv_checkbox_set_text_static [`3e0ddd0`](https://github.com/lvgl/lvgl/commit/3e0ddd028511c6c4a0ba33a15526f404b31a50b8) +- docs(grid) fix missing article [`da0c97a`](https://github.com/lvgl/lvgl/commit/da0c97a367746573fa2385d0ddd184f27ca20dbd) +- docs(display) fix grammar in one spot [`5dbea7d`](https://github.com/lvgl/lvgl/commit/5dbea7d72522e78f66fb468e1d5a98fa28179ed1) +- docs(style) fix typo in style property descriptions [`4e3b860`](https://github.com/lvgl/lvgl/commit/4e3b86020fdc8e183335c6c9b8604129e3e3ddcc) +- docs(flex) fix typo in flex grow section [`e5fafc4`](https://github.com/lvgl/lvgl/commit/e5fafc412214ab01d46ebd37e272e3ffc3164ea4) +- docs(indev) clarify purpose of `continue_reading` flag [`706f81e`](https://github.com/lvgl/lvgl/commit/706f81e5862af27fb0b60cdaf02c650c31787c78) +- docs(license) update company name and year [`7c1eb00`](https://github.com/lvgl/lvgl/commit/7c1eb0064535f2d914b9dc885ebb2a2d0d73381d) +- docs fix typo [`8ab8064`](https://github.com/lvgl/lvgl/commit/8ab806459c1b99990b91b4cd6a656ff6736c1b63) +- docs add libs to the main index [`1a8fed5`](https://github.com/lvgl/lvgl/commit/1a8fed5df02545fe97845e3acd86e33f7048cd8e) +- docs add btn_example.png [`8731ef1`](https://github.com/lvgl/lvgl/commit/8731ef141e2ad2f022b1c01e1bf7605f983b013f) + +- docs(btnmatrix) fix typo with set_all/clear_all parameters [`51a82a1`](https://github.com/lvgl/lvgl/commit/51a82a17ffe938d07d94660f49fd18962060943a) + +### CI and tests + +- ci(micropython) fix git fetch [`2757`](https://github.com/lvgl/lvgl/pull/2757) +- test(txt) initial unit tests and general code cleanup/fixes [`2623`](https://github.com/lvgl/lvgl/pull/2623) +- test add setUp and tearDown to test template [`2648`](https://github.com/lvgl/lvgl/pull/2648) +- test(arc) add initial unit tests [`2617`](https://github.com/lvgl/lvgl/pull/2617) +- ci(micropython) add ESP32 and STM32 tests [`2629`](https://github.com/lvgl/lvgl/pull/2629) +- test(checkbox) add initial tests [`2551`](https://github.com/lvgl/lvgl/pull/2551) +- test(ci) build and run tests in parallel. [`2515`](https://github.com/lvgl/lvgl/pull/2515) +- ci(tests) run tests using ctest [`2503`](https://github.com/lvgl/lvgl/pull/2503) +- ci(tests) add dependency on GNU parallel [`2510`](https://github.com/lvgl/lvgl/pull/2510) +- ci(tests) use common script to install development prereqs [`2504`](https://github.com/lvgl/lvgl/pull/2504) +- test convert Makefile to CMake [`2495`](https://github.com/lvgl/lvgl/pull/2495) +- test Refactor unit test scripts. [`2473`](https://github.com/lvgl/lvgl/pull/2473) + +- test(font_loader) migrate the existing font loader test [`bc5b3be`](https://github.com/lvgl/lvgl/commit/bc5b3be61f7751852dc99509a6ab83faaf6d1235) +- test add build test again, add dropdown test, integrate gcov and gvocr [`e35b1d0`](https://github.com/lvgl/lvgl/commit/e35b1d04bdc7d531d72ebce7d1f031be2631e776) +- test(dropdown) add tess for keypad and encoder [`4143b80`](https://github.com/lvgl/lvgl/commit/4143b804c8f4b4324141ad0f529bac4e9acf1442) +- test add keypad and encoder emulators [`e536bb6`](https://github.com/lvgl/lvgl/commit/e536bb6325728db21ef5c729a99f2161a8125625) +- tests add mouse emulator [`2ba810b`](https://github.com/lvgl/lvgl/commit/2ba810b8de19afc3e9ac18e5bd8ab16af10a4433) +- tests add README [`b765643`](https://github.com/lvgl/lvgl/commit/b765643e4902de359e88fdf6d314e9afdb2daa9a) +- test add move tests to test_cases and test_runners directories [`e9e010a`](https://github.com/lvgl/lvgl/commit/e9e010a8468ee307c350e071251f22459173e601) +- test fix CI build error [`c38cae2`](https://github.com/lvgl/lvgl/commit/c38cae22fbf6cef7564fbebe2145a7def20d52e1) +- ci add config for 8bpp [`3eacc59`](https://github.com/lvgl/lvgl/commit/3eacc5923c0a554e7ff4489776a8982dfc142115) +- test move more source files to src folder [`3672f87`](https://github.com/lvgl/lvgl/commit/3672f873328b4471ac9d5d23696f7bc99a87bc43) +- test update CI for the new tests [`a3898b9`](https://github.com/lvgl/lvgl/commit/a3898b931e81860acf197bc88fd3dd6f8885eb2c) +- test cleaned up report folder [`b9b4ba5`](https://github.com/lvgl/lvgl/commit/b9b4ba5b2608f5709678463f62b3d3f937780235) +- test fix build error [`61cda59`](https://github.com/lvgl/lvgl/commit/61cda59cbe8569326ef9d366c520b89be292f5ea) +- test(font_loader) migrate the existing font loader test [`d6dbbaa`](https://github.com/lvgl/lvgl/commit/d6dbbaaa34304b4c889415439ab562056e0840a5) +- test add move tests to test_cases and test_runners directories [`d2e735e`](https://github.com/lvgl/lvgl/commit/d2e735ef36bd99c16ccaa281dcaa5f418e2dec98) +- test add 3rd party libs to all tests and also fix them [`7a95fa9`](https://github.com/lvgl/lvgl/commit/7a95fa9e2de9639a3c2f1990ff63b467be54a7aa) +- test(arc): add test case for adv_hittest [`e83df6f`](https://github.com/lvgl/lvgl/commit/e83df6f14de1a9eb1d137b123fac96c25a1b7715) +- ci create check for lv_conf_internal.h [`5d8285e`](https://github.com/lvgl/lvgl/commit/5d8285e2d37e19670c1daeff229e1dc331f053c4) +- test fix warning and docs build error [`d908f31`](https://github.com/lvgl/lvgl/commit/d908f31f8f50024d8b3c8d0a11aff9cc1b011049) +- ci(micropython) add rp2 port [`1ab5c96`](https://github.com/lvgl/lvgl/commit/1ab5c9689f61fd2991653beec7d023472fc96239) +- test(dropdown) remove dummy test case [`9fb98da`](https://github.com/lvgl/lvgl/commit/9fb98da8a280dc3d5753da1d2aa79eeb1cba47e0) +- ci(codecov) hide statuses on commits for now [`0b7be77`](https://github.com/lvgl/lvgl/commit/0b7be778a29412fe5562a736855121d19350889c) +- ci(docs) run apt-get update before installation [`f215174`](https://github.com/lvgl/lvgl/commit/f215174999a18b0e5904e97bfda48f3b81271aa1) +- test fix LV_USE_LOG_LEVEL -> LV_LOG_LEVEL typo [`80f0b09`](https://github.com/lvgl/lvgl/commit/80f0b09e34596564ca6ec7c23d148f4ce2e17ca3) +- ci(micropython) add GCC problem matcher [`ab316a0`](https://github.com/lvgl/lvgl/commit/ab316a07bc4d89a633fdd00bc7ff8c5db4b00ad8) + +- test convert Makefile to CMake (#2495) [`9c846ee`](https://github.com/lvgl/lvgl/commit/9c846ee493862ef11b46942a6e5af3c1ed8468d1) + +### Others + +- chore: replace (void)xxx with LV_UNUSED(xxx) [`2779`](https://github.com/lvgl/lvgl/pull/2779) +- animation improvement [`2743`](https://github.com/lvgl/lvgl/pull/2743) +- Improve LV_FORMAT_ATTRIBUTE usage [`2673`](https://github.com/lvgl/lvgl/pull/2673) +- Fix typo in commands to build rlottie [`2723`](https://github.com/lvgl/lvgl/pull/2723) +- del(.gitmodules): delete .gitmodules [`2718`](https://github.com/lvgl/lvgl/pull/2718) +- lv_obj_draw_part_dsc_t.text_length added [`2694`](https://github.com/lvgl/lvgl/pull/2694) +- expose LV_COLOR_DEPTH and LV_COLOR_16_SWAP in micropython [`2679`](https://github.com/lvgl/lvgl/pull/2679) +- sync lvgl/lv_fs_if [`2676`](https://github.com/lvgl/lvgl/pull/2676) +- build: always enable CMake install rule in default configuration [`2636`](https://github.com/lvgl/lvgl/pull/2636) +- build: fix lib name in CMakeLists [`2641`](https://github.com/lvgl/lvgl/pull/2641) +- build: remove use of 'project' keyword in CMakeLists [`2640`](https://github.com/lvgl/lvgl/pull/2640) +- build add install rule to CMakeList.txt [`2621`](https://github.com/lvgl/lvgl/pull/2621) +- Fixed row size calculation [`2633`](https://github.com/lvgl/lvgl/pull/2633) +- arch add small 3rd party libs to lvgl [`2569`](https://github.com/lvgl/lvgl/pull/2569) +- Kconfig: Add missing options [`2597`](https://github.com/lvgl/lvgl/pull/2597) +- Espressif IDF component manager [`2521`](https://github.com/lvgl/lvgl/pull/2521) +- chore(btnmatrix) removed unnecessary semicolon [`2520`](https://github.com/lvgl/lvgl/pull/2520) +- Update README.md [`2516`](https://github.com/lvgl/lvgl/pull/2516) +- Corrected a function name in obj.md [`2511`](https://github.com/lvgl/lvgl/pull/2511) +- Simple spelling fixes [`2496`](https://github.com/lvgl/lvgl/pull/2496) +- added lv_obj_move_up() and lv_obj_move_down() [`2467`](https://github.com/lvgl/lvgl/pull/2467) +- Fix buf name error for "lv_port_disp_template.c" and optimize the arduino example [`2475`](https://github.com/lvgl/lvgl/pull/2475) +- Fix two examples in the docs with new v8 api [`2486`](https://github.com/lvgl/lvgl/pull/2486) +- kconfig: minor fix for default dark theme option [`2426`](https://github.com/lvgl/lvgl/pull/2426) +- doc(table) update doc on cell merging [`2397`](https://github.com/lvgl/lvgl/pull/2397) +- added example lv_example_anim_timeline_1.py [`2387`](https://github.com/lvgl/lvgl/pull/2387) +- refactor(printf) add printf-like function attribute to _lv_txt_set_text_vfmt and lv_label_set_text_fmt [`2332`](https://github.com/lvgl/lvgl/pull/2332) +- Update win.md [`2352`](https://github.com/lvgl/lvgl/pull/2352) +- Nxp pxp vglite v8 dev [`2313`](https://github.com/lvgl/lvgl/pull/2313) +- More Snapable --> Snappable replacements [`2304`](https://github.com/lvgl/lvgl/pull/2304) +- Spelling and other language fixes to documentation [`2293`](https://github.com/lvgl/lvgl/pull/2293) +- Update quick-overview.md [`2295`](https://github.com/lvgl/lvgl/pull/2295) +- adding micropython examples [`2286`](https://github.com/lvgl/lvgl/pull/2286) + +- format run code-formtter.sh [`d67dd94`](https://github.com/lvgl/lvgl/commit/d67dd943cadb3d21a3d9488b6354f669e2e58c65) +- Update ROADMAP.md [`2b1ae3c`](https://github.com/lvgl/lvgl/commit/2b1ae3c107539dec130b988cddca5ddb2b5af652) +- Create .codecov.yml [`e53aa82`](https://github.com/lvgl/lvgl/commit/e53aa82658a1d7324f328c986cb5b7b669803ba2) +- refactor(examples) drop JS-specific code from header.py [`ef41450`](https://github.com/lvgl/lvgl/commit/ef41450ed87f4f4dd936b63349b5a0c9ce880618) +- make test run on master and release/v8.* [`227402a`](https://github.com/lvgl/lvgl/commit/227402a81a1cdd34cd57ec04682166d3961c4481) +- Update release.yml [`0838f12`](https://github.com/lvgl/lvgl/commit/0838f1296b2c55c0b265650ee4310a79730536dd) +- refactor(examples) drop usys import from header.py [`ad1f91a`](https://github.com/lvgl/lvgl/commit/ad1f91ab32c38cab7f0d1448ce3c4e67b47f4526) +- Update ROADMAP.md [`a38fcf2`](https://github.com/lvgl/lvgl/commit/a38fcf2c7aa5fd156d3f2b6965ec4f81d7ff5503) +- Revert "feat(conf) add better check for Kconfig default" [`a5793c7`](https://github.com/lvgl/lvgl/commit/a5793c70a9a60340a5f1c5d33ba1d118af0a76e2) +- remove temporary test file [`a958c29`](https://github.com/lvgl/lvgl/commit/a958c29af7df66f84520036766929232e0c437c4) +- start to implement release/patch [`1626a0c`](https://github.com/lvgl/lvgl/commit/1626a0c029504f26e568677debcb7ab0f6053f83) +- chore(indev) minor formatting [`79ab3d2`](https://github.com/lvgl/lvgl/commit/79ab3d29b01e5f0bff1c754fdc36230584aeaaae) +- add basic patch release script [`1c3ecf1`](https://github.com/lvgl/lvgl/commit/1c3ecf1cc14f5501a345472278cc485a24b8ab9c) +- chore(example) minor improvements on lv_example_list_2 [`bb6d6b7`](https://github.com/lvgl/lvgl/commit/bb6d6b77999fde33f560bde92b394a8811303868) +- tool: add changelog_gen.sh to automatically generate changelog [`6d95521`](https://github.com/lvgl/lvgl/commit/6d955210765de972f78b8c307df2f2387e4580ed) +- update version numbers to v8.1.0-dev [`8691611`](https://github.com/lvgl/lvgl/commit/8691611de2206669cd22e3e97c844fdf2bf494b0) +- chore(test) improve prints [`ea8bed3`](https://github.com/lvgl/lvgl/commit/ea8bed34b49343a4e881bdd42096f69d245ef66e) +- chore(test) improve prints [`0c4bca0`](https://github.com/lvgl/lvgl/commit/0c4bca0f9cbeefaf20fd41e3a561d0e1799bc6b0) +- chore: update lv_conf_internal.h [`41c2dd1`](https://github.com/lvgl/lvgl/commit/41c2dd16ee87f85338603399bb92e1f6eab84bf6) +- chore(format) lv_conf_template.h minor formatting [`3c86d77`](https://github.com/lvgl/lvgl/commit/3c86d777c10c80ec9a4c5d3d403bd1395834004a) +- chore(docs) always deploy master to docs/master as well [`6d05692`](https://github.com/lvgl/lvgl/commit/6d05692d7820a2b833751d6881704b283f1fe618) +- Update CHANGELOG.md [`48fd73d`](https://github.com/lvgl/lvgl/commit/48fd73d20da4f19556660a9fca7faf042c965f56) +- Fix compile errors [`6c956cc`](https://github.com/lvgl/lvgl/commit/6c956cc0f402b96512ed07f8a93003a0319fc49c) +- Update textarea.md [`6d8799f`](https://github.com/lvgl/lvgl/commit/6d8799fbbfb1477ad2e0887644fb4cd900817199) +- chore(assert) add warning about higher memory usage if LV_USE_ASSERT_STYLE is enabled [`33e4330`](https://github.com/lvgl/lvgl/commit/33e433008e23b48540e83bc5399fd0ccb9e90630) +- Update page.html [`9573bab`](https://github.com/lvgl/lvgl/commit/9573bab5cbe2da643f5146e62c176bdd0113d954) +- chore(docs) force docs rebuild [`4a0f413`](https://github.com/lvgl/lvgl/commit/4a0f4139eb98e73b37abf62f66e2cf1c5d4e58db) +- Fix typo error in color.md [`572880c`](https://github.com/lvgl/lvgl/commit/572880ccd3374ccbe81cf09a0620bf95659ca883) +- Update arc.md [`2a9b9e6`](https://github.com/lvgl/lvgl/commit/2a9b9e6e1119db8294fdc63d93548fe06e2b6aa2) +- Update index.rst [`9ce2c77`](https://github.com/lvgl/lvgl/commit/9ce2c7702d15d74f64b7d4bf6273cba442b48c09) +- chore(docs) minor formatting on example's GitHub link [`75209e8`](https://github.com/lvgl/lvgl/commit/75209e893e89b6aa9d6a231af4661ce6a6dd6161) +- chore(lv_conf_template) fix spelling mistake [`9d134a9`](https://github.com/lvgl/lvgl/commit/9d134a99e3f59412ee4a941f20bf70053dd4326d) +- Update CHANGELOG.md [`8472360`](https://github.com/lvgl/lvgl/commit/847236044da01096beae4a586c874b4980f21a55) +- chore(stale) disable on forks [`93c1303`](https://github.com/lvgl/lvgl/commit/93c1303ee7989d25216262e1d0ea244b59b975f6) +- Revert "fix(tests) remove src/test_runners when cleaning" [`ae15a1b`](https://github.com/lvgl/lvgl/commit/ae15a1bbfe122115e5c8ac1f707929673843ad37) + +- style fix usage of clang-format directives [`2122583`](https://github.com/lvgl/lvgl/commit/2122583ec23d82422e1e3d6f2b5a20745fa5dd6d) +- Revert "fix(indev) focus on objects on release instead of press" [`f61b2ca`](https://github.com/lvgl/lvgl/commit/f61b2ca45502472cde8ac0983b73dbf153de2b20) + +## v8.0.2 (16.07.2021) +- fix(theme) improve button focus of keyboard +- fix(tabview) send LV_EVENT_VALUE_CHANGED only once +- fix(imgbtn) use the correct src in LV_EVENT_GET_SELF_SIZE +- fix(color) remove extraneous cast for 8-bit color +- fix(obj style) fix children reposition if the parent's padding changes. +- fix(color) remove extraneous _LV_COLOR_MAKE_TYPE_HELPER (#2372) +- fix(spinner) should not be clickable (#2373) +- fix(obj) improve how the focusing indev is determined +- fix(template) update indev template for v8 +- fix(printf) skip defining attribute if pycparser is used +- refactor(printf) add printf-like function attribute to _lv_txt_set_text_vfmt and lv_label_set_text_fmt (#2332) +- fix(template) include lvgl.h in lv_port_*_template.c files +- fix(obj) detecting which indev sent LV_EVENT_FOCUS +- fix (span) fill LV_EVENT_GET_SELF_SIZE (#2360) +- fix(arc) disable LV_OBJ_FLAG_SCROLL_CHAIN by default +- fix (draw) fix arc bg image drawing with full arcs +- fix(disp) fix memory leak in lv_disp_remove (#2355) +- fix warnings introduced by 3fb8baf5 +- fix(widgets) use lv_obj_class for all the widgets +- fix(obj) move clean ups from lv_obj_del to lv_obj_destructor +- fix(roller) fix partial redraw of the selected area +- fix(roller) adjust the size of the selected area correctly +- fix(obj) delete useless type conversion (#2343) +- fix(lv_obj_scroll.h) typos (#2345) +- fix(scroll) fire LV_EVENT_SCROLL_BEGIN in the same spot for both axes +- fix(btnmatrix) fix button invalidation on focus change +- fix(textarea) style update in oneline mode + improve scroll to cursor +- fix(tlsf) do not use <assert.h> +- fix(imgbtn) consider width==LV_SIZE_CONTENT if only mid. img is set +- fix(refr) reduce the nesting level in lv_refr_area +- fix(txt) enhance the function of break_chars (#2327) +- fix(pxp): update RTOS macro for SDK 2.10 +- fix(vglite): update for v8 +- fix(pxp): update for v8 +- fix(flex) fix layout update and invalidation issues +- fix(flex) fix NULL pointer dereference +- fix(obj, switch) do not send LV_EVENT_VALUE_CHANGED twice +- fix(color) overflow with 16-bit color depth +- fix(coords) fix using large coordinates +- fix(chart) fix crash if no series are added +- fix(chart) invalidation with LV_CHART_UPDATE_MODE_SHIFT +- fix(align) fix lv_obj_align_to G +- fix(table) invalidate the table on cell value change +- fix(label) remove duplicated lv_obj_refresh_self_size +- fix(draw) underflow in subpixel font drawing +- fix (scroll) do not send unnecessary scroll end events + + +## v8.0.1 (14.06.2021) +- docs(filesystem) update to v8 <a href="https://github.com/lvgl/lvgl/commit/7971ade4">7971ade4</a> +- fix(msgbox) create modals on top layer instead of act screen <a href="https://github.com/lvgl/lvgl/commit/5cf6303e">5cf6303e</a> +- fix(colorwheel) disable LV_OBJ_FLAG_SCROLL_CHAIN by default <a href="https://github.com/lvgl/lvgl/commit/48d1c292">48d1c292</a> +- docs(grid) typo fix (#2310) <a href="https://github.com/lvgl/lvgl/commit/69d109d2">69d109d2</a> +- fix(arduino) fix the prototype of my_touchpad_read in the LVGL_Arduino.ino <a href="https://github.com/lvgl/lvgl/commit/1a62f7a6">1a62f7a6</a> +- fix(meter) fix needle image invalidation <a href="https://github.com/lvgl/lvgl/commit/54d8e817">54d8e817</a> +- fix(mem) add lv_ prefix to tlsf functions and types <a href="https://github.com/lvgl/lvgl/commit/0d52b59c">0d52b59c</a> +- fix(calendar) fix the position calculation today <a href="https://github.com/lvgl/lvgl/commit/ad05e196">ad05e196</a> +- fix(typo) rename LV_OBJ_FLAG_SNAPABLE to LV_OBJ_FLAG_SNAPPABLE <a href="https://github.com/lvgl/lvgl/commit/e697807c">e697807c</a> +- docs(color) language fixes (#2302) <a href="https://github.com/lvgl/lvgl/commit/07ecc9f1">07ecc9f1</a> +- fix(tick) minor optimization on lv_tick_inc call test <a href="https://github.com/lvgl/lvgl/commit/b4305df5">b4305df5</a> +- Spelling and other language fixes to documentation (#2293) <a href="https://github.com/lvgl/lvgl/commit/d0aaacaf">d0aaacaf</a> +- fix(theme) show disabled state on buttons of btnmatrix, msgbox and keyboard <a href="https://github.com/lvgl/lvgl/commit/0be582b3">0be582b3</a> +- fix(scroll) keep the scroll position on object deleted <a href="https://github.com/lvgl/lvgl/commit/52edbb46">52edbb46</a> +- fix(msgbox) handle NULL btn map parameter <a href="https://github.com/lvgl/lvgl/commit/769c4a30">769c4a30</a> +- fix(group) allow refocusing objects <a href="https://github.com/lvgl/lvgl/commit/1520208b">1520208b</a> +- docs(overview) spelling fixes <a href="https://github.com/lvgl/lvgl/commit/d2efb8c6">d2efb8c6</a> +- Merge branch 'master' of https://github.com/lvgl/lvgl <a href="https://github.com/lvgl/lvgl/commit/45960838">45960838</a> +- feat(timer) check if lv_tick_inc is called <a href="https://github.com/lvgl/lvgl/commit/aa6641a6">aa6641a6</a> +- feat(docs) add view on GitHub link <a href="https://github.com/lvgl/lvgl/commit/a716ac6e">a716ac6e</a> +- fix(theme) fix the switch style in the default theme <a href="https://github.com/lvgl/lvgl/commit/0c0dc8ea">0c0dc8ea</a> +- docs fix typo <a href="https://github.com/lvgl/lvgl/commit/8ab80645">8ab80645</a> +- Merge branch 'master' of https://github.com/lvgl/lvgl <a href="https://github.com/lvgl/lvgl/commit/e796448f">e796448f</a> +- feat(event) pass the scroll animation to LV_EVENT_SCROLL_BEGIN <a href="https://github.com/lvgl/lvgl/commit/ca54ecfe">ca54ecfe</a> +- fix(tabview) fix with left and right tabs <a href="https://github.com/lvgl/lvgl/commit/17c57449">17c57449</a> +- chore(docs) force docs rebuild <a href="https://github.com/lvgl/lvgl/commit/4a0f4139">4a0f4139</a> +- chore(docs) always deploy master to docs/master as well <a href="https://github.com/lvgl/lvgl/commit/6d05692d">6d05692d</a> +- fix(template) update lv_objx_template to v8 <a href="https://github.com/lvgl/lvgl/commit/38bb8afc">38bb8afc</a> +- docs(extra) add extra/README.md <a href="https://github.com/lvgl/lvgl/commit/8cd504d5">8cd504d5</a> +- Update CHANGELOG.md <a href="https://github.com/lvgl/lvgl/commit/48fd73d2">48fd73d2</a> +- Update quick-overview.md (#2295) <a href="https://github.com/lvgl/lvgl/commit/5616471c">5616471c</a> +- fix(pxp) change LV_COLOR_TRANSP to LV_COLOR_CHROMA_KEY to v8 compatibility <a href="https://github.com/lvgl/lvgl/commit/81f3068d">81f3068d</a> +- adding micropython examples (#2286) <a href="https://github.com/lvgl/lvgl/commit/c60ed68e">c60ed68e</a> +- docs(color) minor fix <a href="https://github.com/lvgl/lvgl/commit/ac8f4534">ac8f4534</a> +- fix(example) revert test code <a href="https://github.com/lvgl/lvgl/commit/77e2c1ff">77e2c1ff</a> +- fix(draw) with additive blending with 32-bit color depth <a href="https://github.com/lvgl/lvgl/commit/786db2af">786db2af</a> +- docs(color) update colors' docs <a href="https://github.com/lvgl/lvgl/commit/9056b5ee">9056b5ee</a> +- Merge branch 'master' of https://github.com/lvgl/lvgl <a href="https://github.com/lvgl/lvgl/commit/a711a1dd">a711a1dd</a> +- perf(refresh) optimize where to wait for lv_disp_flush_ready with 2 buffers <a href="https://github.com/lvgl/lvgl/commit/d0172f14">d0172f14</a> +- docs(lv_obj_style) update add_style and remove_style function headers (#2287) <a href="https://github.com/lvgl/lvgl/commit/60f7bcbf">60f7bcbf</a> +- fix memory leak of spangroup (#2285) <a href="https://github.com/lvgl/lvgl/commit/33e0926a">33e0926a</a> +- fix make lv_img_cache.h public because cache invalidation is public <a href="https://github.com/lvgl/lvgl/commit/38ebcd81">38ebcd81</a> +- Merge branch 'master' of https://github.com/lvgl/lvgl <a href="https://github.com/lvgl/lvgl/commit/2b292495">2b292495</a> +- fix(btnmatrix) fix focus event handling <a href="https://github.com/lvgl/lvgl/commit/3b58ef14">3b58ef14</a> +- Merge pull request #2280 from lvgl/dependabot/pip/docs/urllib3-1.26.5 <a href="https://github.com/lvgl/lvgl/commit/a2f45b26">a2f45b26</a> +- fix(label) calculating the clip area <a href="https://github.com/lvgl/lvgl/commit/57e211cc">57e211cc</a> +- chore(deps): bump urllib3 from 1.26.4 to 1.26.5 in /docs <a href="https://github.com/lvgl/lvgl/commit/b2f77dfc">b2f77dfc</a> +- fix(docs) add docs about the default group <a href="https://github.com/lvgl/lvgl/commit/29bfe604">29bfe604</a> + +## v8.0.0 (01.06.2021) + +v8.0 brings many new features like simplified and more powerful scrolling, new layouts inspired by CSS Flexbox and Grid, simplified and improved widgets, more powerful events, hookable drawing, and more. + +v8 is a major change and therefore it's not backward compatible with v7. + +### Directory structure +- The `lv_` prefix is removed from the folder names +- The `docs` is moved to the `lvgl` repository +- The `examples` are moved to the `lvgl` repository +- Create an `src/extra` folder for complex widgets: + - It makes the core LVGL leaner + - In `extra` we can have a lot and specific widgets + - Good place for contributions + +### Widget changes +- `lv_cont` removed, layout features are moved to `lv_obj` +- `lv_page` removed, scroll features are moved to `lv_obj` +- `lv_objmask` the same can be achieved by events +- `lv_meter` added as the union of `lv_linemeter` and `lv_gauge` +- `lv_span` new widget mimicking HTML `<span>` +- `lv_animing` new widget for simple slideshow animations +- \+ many minor changes and improvements + +### New scrolling +- Support "elastic" scrolling when scrolled in +- Support scroll chaining among any objects types (not only `lv_pages`s) +- Remove `lv_drag`. Similar effect can be achieved by setting the position in `LV_EVENT_PRESSING` +- Add snapping +- Add snap stop to scroll max 1 snap point + +### New layouts +- [CSS Grid](https://css-tricks.com/snippets/css/a-guide-to-grid/)-like layout support +- [CSS Flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/)-like layout support + +### Styles +- Optimize and simplify styles +- State is saved in the object instead of the style property +- Object size and position can be set in styles too + +### Events +- Allow adding multiple events to an object +- A `user_data` can be attached to the added events + +### Driver changes +- `lv_disp_drv_t`, `lv_indev_drv_t`, `lv_fs_drv_t` needs to be `static` +- `...disp_buf...` is renamed to `draw_buf`. See an initialization example [here](https://github.com/lvgl/lv_sim_eclipse_sdl/blob/release/v8.0/main.c#L128-L141). +- No partial update if two screen sized buffers are set +- `disp_drv->full_refresh = 1` makes always the whole display redraw. +- `hor_res` and `ver_res` need to be set in `disp_drv` +- `indev_read_cb` returns `void`. To indicate that there is more that to read set `data->continue_reading = 1` in the `read_cb` + +### Other changes +- Remove the copy parameter from create functions +- Simplified File system interface API +- Use a more generic inheritance +- The built-in themes are reworked +- `lv_obj_align` now saved the alignment and realigns the object automatically but can't be used to align to other than the parent +- `lv_obj_align_to` can align to an object but doesn't save the alignment +- `lv_pct(x)` can be used to set the size and position in percentage +- There are many other changes in widgets that are not detailed here. Please refer to the documentation of the widgets. + +### New release policy +- We will follow [Release branches with GitLab flow](https://docs.gitlab.com/ee/topics/gitlab_flow.html#release-branches-with-gitlab-flow) +- Minor releases are expected in every 3-4 month +- `master` will always contain the latest changes + +### Migrating from v7 to v8 +- First and foremost, create a new `lv_conf.h` based on `lv_conf_template.h`. +- To try the new version it's recommended to use a simulator project and see the examples. +- When migrating your project to v8 + - Update the drivers are described above + - Update the styles + - Update the events + - Use the new layouts instead of `lv_cont` features + - Use `lv_obj` instead of `lv_page` + - See the changes in [Colors](https://docs.lvgl.io/8.0/overview/color.html) + - The other parts are mainly minor renames and refactoring. See the functions' documentation for descriptions. + +## v7.11.0 (16.03.2021) + +### New features +- Add better screen orientation management with software rotation support +- Decide text animation's direction based on base_dir (when using LV_USE_BIDI) + +### Bugfixes +- fix(gauge) fix needle invalidation +- fix(bar) correct symmetric handling for vertical sliders + +## v7.10.1 (16.02.2021) + +### Bugfixes +- fix(draw) overlap outline with background to prevent aliasing artifacts +- fix(indev) clear the indev's `act_obj` in `lv_indev_reset` +- fix(text) fix out of bounds read in `_lv_txt_get_width` +- fix(list) scroll list when button is focused using LV_KEY_NEXT/PREV +- fix(text) improve Arabic contextual analysis by adding hyphen processing and proper handling of lam-alef sequence +- fix(delete) delete animation after the children are deleted +- fix(gauge) consider paddings for needle images + +## v7.10.0 (02.02.2021) + +### New features +- feat(indev) allow input events to be passed to disabled objects +- feat(spinbox) add inline get_step function for MicroPython support + +### Bugfixes +- fix(btnmatrix) fix lv_btnmatrix_get_active_btn_text() when used in a group + +## v7.9.1 (19.01.2021) + +### Bugfixes +- fix(cpicker) fix division by zero +- fix(dropdown) fix selecting options after the last one +- fix(msgbox) use the animation time provided +- fix(gpu_nxp_pxp) fix incorrect define name +- fix(indev) don't leave edit mode if there is only one object in the group +- fix(draw_rect) fix draw pattern stack-use-after-scope error + + +## v7.9.0 (05.01.2021) + +### New features +- feat(chart) add lv_chart_remove_series and lv_chart_hide_series +- feat(img_cache) allow disabling image caching +- calendar: make get_day_of_week() public +- Added support for Zephyr integration + +### Bugfixes +- fix(draw_rect) free buffer used for arabic processing +- fix(win) arabic process the title of the window +- fix(dropdown) arabic process the option in lv_dropdown_add_option +- fix(textarea) buffer overflow in password mode with UTF-8 characters +- fix(textarea) cursor position after hiding character in password mode +- fix(linemeter) draw critical lines with correct color +- fix(lv_conf_internal) be sure Kconfig defines are always uppercase +- fix(kconfig) handle disable sprintf float correctly. +- fix(layout) stop layout after recursion threshold is reached +- fix(gauge) fix redraw with image needle + +## v7.8.1 (15.12.2020) + +### Bugfixes +- fix(lv_scr_load_anim) fix when multiple screens are loaded at the same time with delay +- fix(page) fix LV_SCROLLBAR_MODE_DRAG + +## v7.8.0 (01.12.2020) + +### New features +- make DMA2D non blocking +- add unscii-16 built-in font +- add KConfig +- add lv_refr_get_fps_avg() + +### Bugfixes +- fix(btnmatrix) handle arabic texts in button matrices +- fix(indev) disabled object shouldn't absorb clicks but let the parent to be clicked +- fix(arabic) support processing again already processed texts with _lv_txt_ap_proc +- fix(textarea) support Arabic letter connections +- fix(dropdown) support Arabic letter connections +- fix(value_str) support Arabic letter connections in value string property +- fix(indev) in LV_INDEV_TYPE_BUTTON recognize 1 cycle long presses too +- fix(arc) make arc work with encoder +- fix(slider) adjusting the left knob too with encoder +- fix reference to LV_DRAW_BUF_MAX_NUM in lv_mem.c +- fix(polygon draw) join adjacent points if they are on the same coordinate +- fix(linemeter) fix invalidation when setting new value +- fix(table) add missing invalidation when changing cell type +- refactor(roller) rename LV_ROLLER_MODE_INIFINITE -> LV_ROLLER_MODE_INFINITE + +## v7.7.2 (17.11.2020) +### Bugfixes +- fix(draw_triangle): fix polygon/triangle drawing when the order of points is counter-clockwise +- fix(btnmatrix): fix setting the same map with modified pointers +- fix(arc) fix and improve arc dragging +- label: Repair calculate back `dot` character logical error which cause infinite loop. +- fix(theme_material): remove the bottom border from tabview header +- fix(imgbtn) guess the closest available state with valid src +- fix(spinbox) update cursor position in lv_spinbox_set_step + +## v7.7.1 (03.11.2020) +### Bugfixes +- Respect btnmatrix's `one_check` in `lv_btnmatrix_set_btn_ctrl` +- Gauge: make the needle images to use the styles from `LV_GAUGE_PART_PART` +- Group: fix in `lv_group_remove_obj` to handle deleting hidden objects correctly + +## v7.7.0 (20.10.2020) + +### New features +- Add PXP GPU support (for NXP MCUs) +- Add VG-Lite GPU support (for NXP MCUs) +- Allow max. 16 cell types for table +- Add `lv_table_set_text_fmt()` +- Use margin on calendar header to set distances and padding to the size of the header +- Add `text_sel_bg` style property + +### Bugfixes +- Theme update to support text selection background +- Fix imgbtn state change +- Support RTL in table (draw columns right to left) +- Support RTL in pretty layout (draw columns right to left) +- Skip objects in groups if they are in disabled state +- Fix dropdown selection with RTL basedirection +- Fix rectangle border drawing with large width +- Fix `lv_win_clean()` + +## v7.6.1 (06.10.2020) + +### Bugfixes +- Fix BIDI support in dropdown list +- Fix copying base dir in `lv_obj_create` +- Handle sub pixel rendering in font loader +- Fix transitions with style caching +- Fix click focus +- Fix imgbtn image switching with empty style +- Material theme: do not set the text font to allow easy global font change + +## v7.6.0 (22.09.2020) + +### New features +- Check whether any style property has changed on a state change to decide if any redraw is required + +### Bugfixes +- Fix selection of options with non-ASCII letters in dropdown list +- Fix font loader to support LV_FONT_FMT_TXT_LARGE + +## v7.5.0 (15.09.2020) + +### New features +- Add `clean_dcache_cb` and `lv_disp_clean_dcache` to enable users to use their own cache management function +- Add `gpu_wait_cb` to wait until the GPU is working. It allows to run CPU a wait only when the rendered data is needed. +- Add 10px and 8ox built in fonts + +### Bugfixes +- Fix unexpected DEFOCUS on lv_page when clicking to bg after the scrollable +- Fix `lv_obj_del` and `lv_obj_clean` if the children list changed during deletion. +- Adjust button matrix button width to include padding when spanning multiple units. +- Add rounding to btnmatrix line height calculation +- Add `decmopr_buf` to GC roots +- Fix division by zero in draw_pattern (lv_draw_rect.c) if the image or letter is not found +- Fix drawing images with 1 px height or width + +## v7.4.0 (01.09.2020) + +The main new features of v7.4 are run-time font loading, style caching and arc knob with value setting by click. + +### New features +- Add `lv_font_load()` function - Loads a `lv_font_t` object from a binary font file +- Add `lv_font_free()` function - Frees the memory allocated by the `lv_font_load()` function +- Add style caching to reduce access time of properties with default value +- arc: add set value by click feature +- arc: add `LV_ARC_PART_KNOB` similarly to slider +- send gestures event if the object was dragged. User can check dragging with `lv_indev_is_dragging(lv_indev_act())` in the event function. + +### Bugfixes +- Fix color bleeding on border drawing +- Fix using 'LV_SCROLLBAR_UNHIDE' after 'LV_SCROLLBAR_ON' +- Fix cropping of last column/row if an image is zoomed +- Fix zooming and rotating mosaic images +- Fix deleting tabview with LEFT/RIGHT tab position +- Fix btnmatrix to not send event when CLICK_TRIG = true and the cursor slid from a pressed button +- Fix roller width if selected text is larger than the normal + +## v7.3.1 (18.08.2020) + +### Bugfixes +- Fix drawing value string twice +- Rename `lv_chart_clear_serie` to `lv_chart_clear_series` and `lv_obj_align_origo` to `lv_obj_align_mid` +- Add linemeter's mirror feature again +- Fix text decor (underline strikethrough) with older versions of font converter +- Fix setting local style property multiple times +- Add missing background drawing and radius handling to image button +- Allow adding extra label to list buttons +- Fix crash if `lv_table_set_col_cnt` is called before `lv_table_set_row_cnt` for the first time +- Fix overflow in large image transformations +- Limit extra button click area of button matrix's buttons. With large paddings it was counter-intuitive. (Gaps are mapped to button when clicked). +- Fix `lv_btnmatrix_set_one_check` not forcing exactly one button to be checked +- Fix color picker invalidation in rectangle mode +- Init disabled days to gray color in calendar + +## v7.3.0 (04.08.2020) + +### New features +- Add `lv_task_get_next` +- Add `lv_event_send_refresh`, `lv_event_send_refresh_recursive` to easily send `LV_EVENT_REFRESH` to object +- Add `lv_tabview_set_tab_name()` function - used to change a tab's name +- Add `LV_THEME_MATERIAL_FLAG_NO_TRANSITION` and `LV_THEME_MATERIAL_FLAG_NO_FOCUS` flags +- Reduce code size by adding: `LV_USE_FONT_COMPRESSED` and `LV_FONT_USE_SUBPX` and applying some optimization +- Add `LV_MEMCPY_MEMSET_STD` to use standard `memcpy` and `memset` + +### Bugfixes +- Do not print warning for missing glyph if its height OR width is zero. +- Prevent duplicated sending of `LV_EVENT_INSERT` from text area +- Tidy outer edges of cpicker widget. +- Remove duplicated lines from `lv_tabview_add_tab` +- btnmatrix: handle combined states of buttons (e.g. checked + disabled) +- textarea: fix typo in lv_textarea_set_scrollbar_mode +- gauge: fix image needle drawing +- fix using freed memory in _lv_style_list_remove_style + +## v7.2.0 (21.07.2020) + +### New features +- Add screen transitions with `lv_scr_load_anim()` +- Add display background color, wallpaper and opacity. Shown when the screen is transparent. Can be used with `lv_disp_set_bg_opa/color/image()`. +- Add `LV_CALENDAR_WEEK_STARTS_MONDAY` +- Add `lv_chart_set_x_start_point()` function - Set the index of the x-axis start point in the data array +- Add `lv_chart_set_ext_array()` function - Set an external array of data points to use for the chart +- Add `lv_chart_set_point_id()` function - Set an individual point value in the chart series directly based on index +- Add `lv_chart_get_x_start_point()` function - Get the current index of the x-axis start point in the data array +- Add `lv_chart_get_point_id()` function - Get an individual point value in the chart series directly based on index +- Add `ext_buf_assigned` bit field to `lv_chart_series_t` structure - it's true if external buffer is assigned to series +- Add `lv_chart_set_series_axis()` to assign series to primary or secondary axis +- Add `lv_chart_set_y_range()` to allow setting range of secondary y-axis (based on `lv_chart_set_range` but extended with an axis parameter) +- Allow setting different font for the selected text in `lv_roller` +- Add `theme->apply_cb` to replace `theme->apply_xcb` to make it compatible with the MicroPython binding +- Add `lv_theme_set_base()` to allow easy extension of built-in (or any) themes +- Add `lv_obj_align_x()` and `lv_obj_align_y()` functions +- Add `lv_obj_align_origo_x()` and `lv_obj_align_origo_y()` functions + +### Bugfixes +- `tileview` fix navigation when not screen sized +- Use 14px font by default to for better compatibility with smaller displays +- `linemeter` fix conversation of current value to "level" +- Fix drawing on right border +- Set the cursor image non-clickable by default +- Improve mono theme when used with keyboard or encoder + +## v7.1.0 (07.07.2020) + +### New features +- Add `focus_parent` attribute to `lv_obj` +- Allow using buttons in encoder input device +- Add lv_btnmatrix_set/get_align capability +- DMA2D: Remove dependency on ST CubeMX HAL +- Added `max_used` propriety to `lv_mem_monitor_t` struct +- In `lv_init` test if the strings are UTF-8 encoded. +- Add `user_data` to themes +- Add LV_BIG_ENDIAN_SYSTEM flag to lv_conf.h in order to fix displaying images on big endian systems. +- Add inline function lv_checkbox_get_state(const lv_obj_t * cb) to extend the checkbox functionality. +- Add inline function lv_checkbox_set_state(const lv_obj_t * cb, lv_btn_state_t state ) to extend the checkbox functionality. + +### Bugfixes +- `lv_img` fix invalidation area when angle or zoom changes +- Update the style handling to support Big endian MCUs +- Change some methods to support big endian hardware. +- remove use of c++ keyword 'new' in parameter of function lv_theme_set_base(). +- Add LV_BIG_ENDIAN_SYSTEM flag to lv_conf.h in order to fix displaying images on big endian systems. +- Fix inserting chars in text area in big endian hardware. + +## v7.0.2 (16.06.2020) + +### Bugfixes +- `lv_textarea` fix wrong cursor position when clicked after the last character +- Change all text related indices from 16-bit to 32-bit integers throughout whole library. #1545 +- Fix gestures +- Do not call `set_px_cb` for transparent pixel +- Fix list button focus in material theme +- Fix crash when a text area is cleared with the backspace of a keyboard +- Add version number to `lv_conf_template.h` +- Add log in true double buffering mode with `set_px_cb` +- `lv_dropdown`: fix missing `LV_EVENT_VALUE_CHANGED` event when used with encoder +- `lv_tileview`: fix if not the {0;0} tile is created first +- `lv_debug`: restructure to allow asserting in from `lv_misc` too +- add assert if `_lv_mem_buf_get()` fails +- `lv_textarea`: fix character delete in password mode +- Update `LV_OPA_MIN` and `LV_OPA_MAX` to widen the opacity processed range +- `lv_btnm` fix sending events for hidden buttons +- `lv_gaguge` make `lv_gauge_set_angle_offset` offset the labels and needles too +- Fix typo in the API `scrllable` -> `scrollable` +- `tabview` by default allow auto expanding the page only to right and bottom (#1573) +- fix crash when drawing gradient to the same color +- chart: fix memory leak +- `img`: improve hit test for transformed images + +## v7.0.1 (01.06.2020) + +### Bugfixes +- Make Micropython working by adding the required variables as GC_ROOT +- Prefix some internal API functions with `_` to reduce the API of LVGL +- Fix built-in SimSun CJK font +- Fix UTF-8 encoding when `LV_USE_ARABIC_PERSIAN_CHARS` is enabled +- Fix DMA2D usage when 32 bit images directly blended +- Fix lv_roller in infinite mode when used with encoder +- Add `lv_theme_get_color_secondary()` +- Add `LV_COLOR_MIX_ROUND_OFS` to adjust color mixing to make it compatible with the GPU +- Improve DMA2D blending +- Remove memcpy from `lv_ll` (caused issues with some optimization settings) +- `lv_chart` fix X tick drawing +- Fix vertical dashed line drawing +- Some additional minor fixes and formattings + +## v7.0.0 (18.05.2020) + +### Documentation +The docs for v7 is available at https://docs.littlevgl.com/v7/en/html/index.html + +### Legal changes + +The name of the project is changed to LVGL and the new website is on https://lvgl.io + +LVGL remains free under the same conditions (MIT license) and a company is created to manage LVGL and offer services. + +### New drawing system +Complete rework of LVGL's draw engine to use "masks" for more advanced and higher quality graphical effects. +A possible use-case of this system is to remove the overflowing content from the rounded edges. +It also allows drawing perfectly anti-aliased circles, lines, and arcs. +Internally, the drawings happen by defining masks (such as rounded rectangle, line, angle). +When something is drawn the currently active masks can make some pixels transparent. +For example, rectangle borders are drawn by using 2 rectangle masks: one mask removes the inner part and another the outer part. + +The API in this regard remained the same but some new functions were added: +- `lv_img_set_zoom`: set image object's zoom factor +- `lv_img_set_angle`: set image object's angle without using canvas +- `lv_img_set_pivot`: set the pivot point of rotation + +The new drawing engine brought new drawing features too. They are highlighted in the "style" section. + +### New style system +The old style system is replaced with a new more flexible and lightweighted one. +It uses an approach similar to CSS: support cascading styles, inheriting properties and local style properties per object. +As part of these updates, a lot of objects were reworked and the APIs have been changed. + +- more shadows options: *offset* and *spread* +- gradient stop position to shift the gradient area and horizontal gradient +- `LV_BLEND_MODE_NORMAL/ADDITIVE/SUBTRACTIVE` blending modes +- *clip corner*: crop the content on the rounded corners +- *text underline* and *strikethrough* +- dashed vertical and horizontal lines (*dash gap*, *dash_width*) +- *outline*: a border-like part drawn out of the background. Can have spacing to the background. +- *pattern*: display and image in the middle of the background or repeat it +- *value* display a text which is stored in the style. It can be used e.g. as a light-weighted text on buttons too. +- *margin*: similar to *padding* but used to keep space outside the object + +Read the [Style](https://docs.littlevgl.com/v7/en/html/overview/style.html) section of the documentation to learn how the new styles system works. + +### GPU integration +To better utilize GPUs, from this version GPU usage can be integrated into LVGL. In `lv_conf.h` any supported GPUs can be enabled with a single configuration option. + +Right now, only ST's DMA2D (Chrom-ART) is integrated. More will in the upcoming releases. + +### Renames +The following object types are renamed: +- sw -> switch +- ta -> textarea +- cb -> checkbox +- lmeter -> linemeter +- mbox -> msgbox +- ddlist -> dropdown +- btnm -> btnmatrix +- kb -> keyboard +- preload -> spinner +- lv_objx folder -> lv_widgets +- LV_FIT_FILL -> LV_FIT_PARENT +- LV_FIT_FLOOD -> LV_FLOOD_MAX +- LV_LAYOUT_COL_L/M/R -> LV_LAYOUT_COLUMN_LEFT/MID/RIGHT +- LV_LAYOUT_ROW_T/M/B -> LV_LAYOUT_ROW_TOP/MID/BOTTOM + +### Reworked and improved object +- `dropdown`: Completely reworked. Now creates a separate list when opened and can be dropped to down/up/left/right. +- `label`: `body_draw` is removed, instead, if its style has a visible background/border/shadow etc it will be drawn. Padding really makes the object larger (not just virtually as before) +- `arc`: can draw background too. +- `btn`: doesn't store styles for each state because it's done naturally in the new style system. +- `calendar`: highlight the pressed datum. The used styles are changed: use `LV_CALENDAR_PART_DATE` normal for normal dates, checked for highlighted, focused for today, pressed for the being pressed. (checked+pressed, focused+pressed also work) +- `chart`: only has `LINE` and `COLUMN` types because with new styles all the others can be described. LV_CHART_PART_SERIES sets the style of the series. bg_opa > 0 draws an area in LINE mode. `LV_CHART_PART_SERIES_BG` also added to set a different style for the series area. Padding in `LV_CHART_PART_BG` makes the series area smaller, and it ensures space for axis labels/numbers. +- `linemeter`, `gauge`: can have background if the related style properties are set. Padding makes the scale/lines smaller. scale_border_width and scale_end_border_width allow to draw an arc on the outer part of the scale lines. +- `gauge`: `lv_gauge_set_needle_img` allows use image as needle +- `canvas`: allow drawing to true color alpha and alpha only canvas, add `lv_canvas_blur_hor/ver` and rename `lv_canvas_rotate` to `lv_canvas_transform` +- `textarea`: If available in the font use bullet (`U+2022`) character in text area password + +### New object types +- `lv_objmask`: masks can be added to it. The children will be masked accordingly. + +### Others +- Change the built-in fonts to [Montserrat](https://fonts.google.com/specimen/Montserrat) and add built-in fonts from 12 px to 48 px for every 2nd size. +- Add example CJK and Arabic/Persian/Hebrew built-in font +- Add ° and "bullet" to the built-in fonts +- Add Arabic/Persian script support: change the character according to its position in the text. +- Add `playback_time` to animations. +- Add `repeat_count` to animations instead of the current "repeat forever". +- Replace `LV_LAYOUT_PRETTY` with `LV_LAYOUT_PRETTY_TOP/MID/BOTTOM` + +### Demos +- [lv_examples](https://github.com/littlevgl/lv_examples) was reworked and new examples and demos were added + +### New release policy +- Maintain this Changelog for every release +- Save old major version in new branches. E.g. `release/v6` +- Merge new features and fixes directly into `master` and release a patch or minor releases every 2 weeks. + +### Migrating from v6 to v7 +- First and foremost, create a new `lv_conf.h` based on `lv_conf_template.h`. +- To try the new version it suggested using a simulator project and see the examples. +- If you have a running project, the most difficult part of the migration is updating to the new style system. Unfortunately, there is no better way than manually updating to the new format. +- The other parts are mainly minor renames and refactoring as described above. diff --git a/lib/lvgl/docs/CODE_OF_CONDUCT.md b/lib/lvgl/docs/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..4052ad67 --- /dev/null +++ b/lib/lvgl/docs/CODE_OF_CONDUCT.md @@ -0,0 +1,46 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team using the [contact form](https://lvgl.io/about). All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ diff --git a/lib/lvgl/docs/CODING_STYLE.md b/lib/lvgl/docs/CODING_STYLE.md new file mode 100644 index 00000000..d45f0fc4 --- /dev/null +++ b/lib/lvgl/docs/CODING_STYLE.md @@ -0,0 +1,124 @@ +# Coding style + +## File format +Use [misc/lv_templ.c](https://github.com/lvgl/lvgl/blob/master/src/misc/lv_templ.c) and [misc/lv_templ.h](https://github.com/lvgl/lvgl/blob/master/src/misc/lv_templ.h) + +## Naming conventions +* Words are separated by '_' +* In variable and function names use only lower case letters (e.g. *height_tmp*) +* In enums and defines use only upper case letters (e.g. *e.g. MAX_LINE_NUM*) +* Global names (API): + * start with *lv* + * followed by module name: *btn*, *label*, *style* etc. + * followed by the action (for functions): *set*, *get*, *refr* etc. + * closed with the subject: *name*, *size*, *state* etc. +* Typedefs + * prefer `typedef struct` and `typedef enum` instead of `struct name` and `enum name` + * always end `typedef struct` and `typedef enum` type names with `_t` +* Abbreviations: + * Only words longer or equal than 6 characters can be abbreviated. + * Abbreviate only if it makes the word at least half as long + * Use only very straightforward and well-known abbreviations (e.g. pos: position, def: default, btn: button) + +## Coding guide +* Functions: + * Try to write function shorter than is 50 lines + * Always shorter than 200 lines (except very straightforwards) +* Variables: + * One line, one declaration (BAD: char x, y;) + * Use `<stdint.h>` (*uint8_t*, *int32_t* etc) + * Declare variables where needed (not all at function start) + * Use the smallest required scope + * Variables in a file (outside functions) are always *static* + * Do not use global variables (use functions to set/get static variables) + +## Comments +Before every function have a comment like this: + +```c +/** + * Return with the screen of an object + * @param obj pointer to an object + * @return pointer to a screen + */ +lv_obj_t * lv_obj_get_scr(lv_obj_t * obj); +``` + +Always use `/*Something*/` format and NOT `//Something` + +Write readable code to avoid descriptive comments like: +`x++; /*Add 1 to x*/`. +The code should show clearly what you are doing. + +You should write **why** have you done this: +`x++; /*Because of closing '\0' of the string*/` + +Short "code summaries" of a few lines are accepted. E.g. `/*Calculate the new coordinates*/` + +In comments use \` \` when referring to a variable. E.g. ``/*Update the value of `x_act`*/`` + +### Formatting +Here is example to show bracket placing and using of white spaces: +```c +/** + * Set a new text for a label. Memory will be allocated to store the text by the label. + * @param label pointer to a label object + * @param text '\0' terminated character string. NULL to refresh with the current text. + */ +void lv_label_set_text(lv_obj_t * label, const char * text) +{ /*Main brackets of functions in new line*/ + + if(label == NULL) return; /*No bracket only if the command is inline with the if statement*/ + + lv_obj_inv(label); + + lv_label_ext_t * ext = lv_obj_get_ext(label); + + /*Comment before a section*/ + if(text == ext->txt || text == NULL) { /*Bracket of statements start inline*/ + lv_label_refr_text(label); + return; + } + + ... +} +``` + +Use 4 spaces indentation instead of tab. + +You can use **astyle** to format the code. Run `code-formatter.sh` from the `scrips` folder. + +#### pre-commit + +[pre-commit](https://pre-commit.com/) is a multi-language package manager for pre-commit hooks. +See the [instalation guide](https://pre-commit.com/#installation) to get pre-commit python package +installed into your development machine. + +Once you have `pre-commit` installed you will need to [set up the git hook scripts](https://pre-commit.com/#3-install-the-git-hook-scripts) with: +```console +pre-commit install +``` + +now `pre-commit` will run automatically on `git commit`! + +##### Hooks + +The `format-source` local hook (see `.pre-commit-config.yaml`) runs **astyle** on all the staged source and header +files (that are not excluded, see `exclude` key of the hook configuration) before entering the commit message, +if any file gets formatted by **astyle** you will need to add the change to the staging area and run `git commit` again. + +The `trailing-whitespace` hook fixes trailing whitespaces on all of the files. + +##### Skipping hooks + +If you want to skip any particular hook you can do so with: +```console +SKIP=name-of-the-hook git commit +``` + +##### Testing hooks + +It's no necessary to do a commit to test the hooks, you can test hooks by adding the files into the staging area and run: +```console +pre-commit run name-of-the-hook +```
\ No newline at end of file diff --git a/lib/lvgl/docs/CONTRIBUTING.md b/lib/lvgl/docs/CONTRIBUTING.md new file mode 100644 index 00000000..67590e15 --- /dev/null +++ b/lib/lvgl/docs/CONTRIBUTING.md @@ -0,0 +1,296 @@ + +# Contributing + +## Introduction + +Join LVGL's community and leave your footprint in the library! + +There are a lot of ways to contribute to LVGL even if you are new to the library or even new to programming. + +It might be scary to make the first step but you have nothing to be afraid of. +A friendly and helpful community is waiting for you. Get to know like-minded people and make something great together. + +So let's find which contribution option fits you the best and help you join the development of LVGL! + +Before getting started here are some guidelines to make contribution smoother: +- Be kind and friendly. +- Be sure to read the relevant part of the documentation before posting a question. +- Ask questions in the [Forum](https://forum.lvgl.io/) and use [GitHub](https://github.com/lvgl/) for development-related discussions. +- Always fill out the post or issue templates in the Forum or GitHub (or at least provide equivalent information). It makes understanding your contribution or issue easier and you will get a useful response faster. +- If possible send an absolute minimal but buildable code example in order to reproduce the issue. Be sure it contains all the required variable declarations, constants, and assets (images, fonts). +- Use [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) to format your posts. You can learn it in 10 minutes. +- Speak about one thing in one issue or topic. It makes your post easier to find later for someone with the same question. +- Give feedback and close the issue or mark the topic as solved if your question is answered. +- For non-trivial fixes and features, it's better to open an issue first to discuss the details instead of sending a pull request directly. +- Please read and follow the <a href="https://github.com/lvgl/lvgl/blob/master/docs/CODING_STYLE.md">Coding style</a> guide. + +## Pull request + +Merging new code into the lvgl, documentation, blog, examples, and other repositories happen via *Pull requests* (PR for short). +A PR is a notification like "Hey, I made some updates to your project. Here are the changes, you can add them if you want." +To do this you need a copy (called fork) of the original project under your account, make some changes there, and notify the original repository about your updates. +You can see what it looks like on GitHub for LVGL here: [https://github.com/lvgl/lvgl/pulls](https://github.com/lvgl/lvgl/pulls). + +To add your changes you can edit files online on GitHub and send a new Pull request from there (recommended for small changes) or + add the updates in your favorite editor/IDE and use git to publish the changes (recommended for more complex updates). + +### From GitHub +1. Navigate to the file you want to edit. +2. Click the Edit button in the top right-hand corner. +3. Add your changes to the file. +4. Add a commit message on the bottom of the page. +5. Click the *Propose changes* button. + +### From command line + +The instructions describe the main `lvgl` repository but it works the same way for the other repositories. +1. Fork the [lvgl repository](https://github.com/lvgl/lvgl). To do this click the "Fork" button in the top right corner. +It will "copy" the `lvgl` repository to your GitHub account (`https://github.com/<YOUR_NAME>?tab=repositories`) +2. Clone your forked repository. +3. Add your changes. You can create a *feature branch* from *master* for the updates: `git checkout -b the-new-feature` +4. Commit and push your changes to the forked `lvgl` repository. +5. Create a PR on GitHub from the page of your `lvgl` repository (`https://github.com/<YOUR_NAME>/lvgl`) by clicking the *"New pull request"* button. Don't forget to select the branch where you added your changes. +7. Set the base branch. It means where you want to merge your update. In the `lvgl` repo both the fixes and new features go to `master` branch. +8. Describe what is in the update. An example code is welcome if applicable. +9. If you need to make more changes, just update your forked `lvgl` repo with new commits. They will automatically appear in the PR. + +### Commit message format +The commit messages format is inspired by [Angular Commit Format](https://gist.github.com/brianclements/841ea7bffdb01346392c). + +The following structure should be used: +``` +<type>(<scope>): <subject> +<BLANK LINE> +<body> +<BLANK LINE> +<footer> +``` + +Possible `<type>`s: +- `fix` bugfix in the source code. +- `feat` new feature +- `arch` architectural changes +- `perf` changes that affect the performance +- `example` anything related to examples (even fixes and new examples) +- `docs` anything related to the documentation (even fixes, formatting, and new pages) +- `test` anything related to tests (new and updated tests or CI actions) +- `chore` any minor formatting or style changes that would make the changelog noisy + +`<scope>` is the module, file, or sub-system that is affected by the commit. It's usually one word and can be chosen freely. +For example `img`, `layout`, `txt`, `anim`. The scope can be omitted. + +`<subject>` contains a short description of the change: +- use the imperative, present tense: "change" not "changed" nor "changes" +- don't capitalize the first letter +- no dot (.) at the end +- max 90 characters + +`<body>` optional and can be used to describe the details of this change. + +`<footer>` shall contain +- the words "BREAKING CHANGE" if the changes break the API +- reference to the GitHub issue or Pull Request if applicable. + +Some examples: +``` +fix(img): update size if a new source is set +``` + +``` +fix(bar): fix memory leak + +The animations weren't deleted in the destructor. + +Fixes: #1234 +``` + +``` +feat: add span widget + +The span widget allows mixing different font sizes, colors and styles. +It's similar to HTML <span> +``` + +``` +docs(porting): fix typo +``` + +## Developer Certification of Origin (DCO) + +### Overview + +To ensure all licensing criteria are met for every repository of the LVGL project, we apply a process called DCO (Developer's Certificate of Origin). + +The text of DCO can be read here: [https://developercertificate.org/](https://developercertificate.org/). + +By contributing to any repositories of the LVGL project you agree that your contribution complies with the DCO. + +If your contribution fulfills the requirements of the DCO no further action is needed. If you are unsure feel free to ask us in a comment. + +### Accepted licenses and copyright notices + +To make the DCO easier to digest, here are some practical guides about specific cases: + +#### Your own work + +The simplest case is when the contribution is solely your own work. +In this case you can just send a Pull Request without worrying about any licensing issues. + +#### Use code from online source + +If the code you would like to add is based on an article, post or comment on a website (e.g. StackOverflow) the license and/or rules of that site should be followed. + +For example in case of StackOverflow a notice like this can be used: +``` +/* The original version of this code-snippet was published on StackOverflow. + * Post: http://stackoverflow.com/questions/12345 + * Author: http://stackoverflow.com/users/12345/username + * The following parts of the snippet were changed: + * - Check this or that + * - Optimize performance here and there + */ + ... code snippet here ... +``` + +#### Use MIT licensed code +As LVGL is MIT licensed, other MIT licensed code can be integrated without issues. +The MIT license requires a copyright notice be added to the derived work. Any derivative work based on MIT licensed code must copy the original work's license file or text. + +#### Use GPL licensed code +The GPL license is not compatible with the MIT license. Therefore, LVGL can not accept GPL licensed code. + +## Ways to contribute + +Even if you're just getting started with LVGL there are plenty of ways to get your feet wet. +Most of these options don't even require knowing a single line of LVGL code. + +Below we have collected some opportunities about the ways you can contribute to LVGL. + +### Give LVGL a Star + +Show that you like LVGL by giving it star on GitHub! +<!-- Place this tag in your head or just before your close body tag. --> +<script async defer src="https://buttons.github.io/buttons.js"></script> +<!-- Place this tag where you want the button to render. --> +<a class="github-button" href="https://github.com/lvgl/lvgl" data-icon="octicon-star" data-size="large" data-show-count="true" aria-label="Star lvgl/lvgl on GitHub">Star</a> + +This simple click makes LVGL more visible on GitHub and makes it more attractive to other people. +So with this, you already helped a lot! + +### Tell what you have achieved + +Have you already started using LVGL in a [Simulator](/get-started/platforms/pc-simulator), a development board, or on your custom hardware? +Was it easy or were there some obstacles? Are you happy with the result? +Showing your project to others is a win-win situation because it increases your and LVGL's reputation at the same time. + +You can post about your project on Twitter, Facebook, LinkedIn, create a YouTube video, and so on. +Only one thing: On social media don't forget to add a link to `https://lvgl.io` or `https://github.com/lvgl` and use the hashtag `#lvgl`. Thank you! :) + +You can also open a new topic in the [My projects](https://forum.lvgl.io/c/my-projects/10) category of the Forum. + +The [LVGL Blog](https://blog.lvgl.io) welcomes posts from anyone. +It's a good place to talk about a project you created with LVGL, write a tutorial, or share some nice tricks. +The latest blog posts are shown on the [homepage of LVGL](https://lvgl.io) to make your work more visible. + +The blog is hosted on GitHub. If you add a post GitHub automatically turns it into a website. +See the [README](https://github.com/lvgl/blog) of the blog repo to see how to add your post. + +Any of these help to spread the word and familiarize new developers with LVGL. + +If you don't want to speak about your project publicly, feel free to use [Contact form](https://lvgl.io/#contact) on lvgl.io to private message to us. + +### Write examples +As you learn LVGL you will probably play with the features of widgets. Why not publish your experiments? + +Each widgets' documentation contains examples. For instance, here are the examples of the [Drop-down list](/widgets/core/dropdown#examples) widget. +The examples are directly loaded from the [lvgl/examples](https://github.com/lvgl/lvgl/tree/master/examples) folder. + +So all you need to do is send a [Pull request](#pull-request) to the [lvgl](https://github.com/lvgl/lvgl) repository and follow some conventions: +- Name the examples like `lv_example_<widget_name>_<index>`. +- Make the example as short and simple as possible. +- Add comments to explain what the example does. +- Use 320x240 resolution. +- Update `index.rst` in the example's folder with your new example. To see how other examples are added, look in the [lvgl/examples/widgets](https://github.com/lvgl/lvgl/tree/master/examples/widgets) folder. + +### Improve the docs + +As you read the documentation you might see some typos or unclear sentences. All the documentation is located in the [lvgl/docs](https://github.com/lvgl/lvgl/tree/master/docs) folder. +For typos and straightforward fixes, you can simply edit the file on GitHub. + +Note that the documentation is also formatted in [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). + +### Report bugs +As you use LVGL you might find bugs. Before reporting them be sure to check the relevant parts of the documentation. + +If it really seems like a bug feel free to open an [issue on GitHub](https://github.com/lvgl/lvgl/issues). + +When filing the issue be sure to fill out the template. It helps find the root of the problem while avoiding extensive questions and exchanges with other developers. + +### Send fixes +The beauty of open-source software is you can easily dig in to it to understand how it works. You can also fix or adjust it as you wish. + +If you found and fixed a bug don't hesitate to send a [Pull request](#pull-request) with the fix. + +In your Pull request please also add a line to [`CHANGELOG.md`](https://github.com/lvgl/lvgl/blob/master/CHANGELOG.md). + +### Join the conversations in the Forum +It feels great to know you are not alone if something is not working. It's even better to help others when they struggle with something. + +While you were learning LVGL you might have had questions and used the Forum to get answers. As a result, you probably have more knowledge about how LVGL works. + +One of the best ways to give back is to use the Forum and answer the questions of newcomers - like you were once. + +Just read the titles and if you are familiar with the topic don't hesitate to share your thoughts and suggestions. + +Participating in the discussions is one of the best ways to become part of the project and get to know like-minded people! + +### Add features +If you have created a cool widget, or added useful feature to LVGL feel free to open a new PR for it. +We collect the optional features (a.k.a. plugins) in [lvgl/src/extra](https://github.com/lvgl/lvgl/tree/master/src/extra) folder so if you are interested in adding a new features please use this folder. +The [README](https://github.com/lvgl/lvgl/blob/master/src/extra/README.md) file describes the basics rules of contribution and also lists some ideas. + +For further ideas take a look at the [Roadmap](/ROADMAP) page. If you are interested in any of them feel free to share your opinion and/or participate in the implementation. + +Other features which are (still) not on the road map are listed in the [Feature request](https://forum.lvgl.io/c/feature-request/9) category of the Forum. + +When adding a new features the followings also needs to be updated: +- Update [lv_conf_template.h](https://github.com/lvgl/lvgl/blob/master/lv_conf_template.h) +- Add description in the [docs](https://github.com/lvgl/lvgl/tree/master/docs) +- Add [examples](https://github.com/lvgl/lvgl/tree/master/examples) +- Update the [changelog](https://github.com/lvgl/lvgl/tree/master/docs/CHANGELOG.md) + +### Become a maintainer + +If you want to become part of the core development team, you can become a maintainer of a repository. + +By becoming a maintainer: +- You get write access to that repo: + - Add code directly without sending a pull request + - Accept pull requests + - Close/reopen/edit issues +- Your input has higher impact when we are making decisions + +You can become a maintainer by invitation, however the following conditions need to met +1. Have > 50 replies in the Forum. You can look at your stats [here](https://forum.lvgl.io/u?period=all) +2. Send > 5 non-trivial pull requests to the repo where you would like to be a maintainer + + +If you are interested, just send a message (e.g. from the Forum) to the current maintainers of the repository. They will check if the prerequisites are met. +Note that meeting the prerequisites is not a guarantee of acceptance, i.e. if the conditions are met you won't automatically become a maintainer. +It's up to the current maintainers to make the decision. + +### Move your project repository under LVGL organization +Besides the core `lvgl` repository there are other repos for ports to development boards, IDEs or other environment. +If you ported LVGL to a new platform we can host it under the LVGL organization among the other repos. + +This way your project will become part of the whole LVGL project and can get more visibility. +If you are interested in this opportunity just open an [issue in lvgl repo](https://github.com/lvgl/lvgl/issues) and tell what you have! + +If we agree that your port fit well into the LVGL organization, we will open a repository for your project where you will have admin rights. + +To make this concept sustainable there a few rules to follow: +- You need to add a README to your repo. +- We expect to maintain the repo to some extent: + - Follow at least the major versions of LVGL + - Respond to the issues (in a reasonable time) +- If there is no activity in a repo for 1 year it will be archived diff --git a/lib/lvgl/docs/ROADMAP.md b/lib/lvgl/docs/ROADMAP.md new file mode 100644 index 00000000..0d1a35e4 --- /dev/null +++ b/lib/lvgl/docs/ROADMAP.md @@ -0,0 +1,27 @@ +# Roadmap + +This is a summary for planned new features and a collection of ideas. +This list indicates only the current intention and it can be changed. + +## v8.2 +See [#2790](https://github.com/lvgl/lvgl/issues/2790) + +## Ideas +- Reconsider color format management for run time color format setting, and custom color format usage. (Also [RGB888](https://github.com/lvgl/lvgl/issues/1722)) +- Make gradients more versatile +- Image transformations matrix +- Switch to RGBA colors in styles +- Consider direct binary font format support +- Simplify `group`s. Discussion is [here](https://forum.lvgl.io/t/lv-group-tabindex/2927/3). +- lv_mem_alloc_aligned(size, align) +- Text node. See [#1701](https://github.com/lvgl/lvgl/issues/1701#issuecomment-699479408) +- CPP binding. See [Forum](https://forum.lvgl.io/t/is-it-possible-to-officially-support-optional-cpp-api/2736) +- Optimize font decompression +- Need static analyze (via coverity.io or something else) +- Support dot_begin and dot_middle long modes for labels +- Add new label alignment modes. [#1656](https://github.com/lvgl/lvgl/issues/1656) +- Support larger images: [#1892](https://github.com/lvgl/lvgl/issues/1892) +- Curved text on path +- Variable binding improvements like Redux? +- Functional programming support, pure view? See [here](https://www.freecodecamp.org/news/the-revolution-of-pure-views-aed339db7da4/) +- Circle layout. See [#2871](https://github.com/lvgl/lvgl/issues/2871) diff --git a/lib/lvgl/docs/_ext/lv_example.py b/lib/lvgl/docs/_ext/lv_example.py new file mode 100644 index 00000000..1a818e24 --- /dev/null +++ b/lib/lvgl/docs/_ext/lv_example.py @@ -0,0 +1,98 @@ +import os + +from docutils import nodes +from docutils.parsers.rst import Directive, directives +from docutils.parsers.rst.directives.images import Image +from sphinx.directives.code import LiteralInclude + + +def excluded_list(argument): + return argument.split(',') + + + + +class LvExample(Directive): + required_arguments = 1 + option_spec = { + 'excluded_languages': excluded_list, + 'language': directives.unchanged, + 'description': directives.unchanged + } + def get_example_code_path(self, example_path, language): + return os.path.abspath("../examples/" + example_path + "." + language) + def human_language_name(self, language): + if language == 'py': + return 'MicroPython' + elif language == 'c': + return 'C' + else: + return language + def github_path(self, example_path, language): + env = self.state.document.settings.env + return f"https://github.com/lvgl/lvgl/blob/{env.config.repo_commit_hash}/examples/{example_path}.{language}" + def embed_code(self, example_file, example_path, language, buttons={}): + toggle = nodes.container('', literal_block=False, classes=['toggle']) + header = nodes.container('', literal_block=False, classes=['header']) + toggle.append(header) + try: + with open(example_file) as f: + contents = f.read() + except FileNotFoundError: + contents = 'Error encountered while trying to open ' + example_file + literal_list = nodes.literal_block(contents, contents) + literal_list['language'] = language + toggle.append(literal_list) + paragraph_node = nodes.raw(text=f"<p>{self.human_language_name(language)} code </p>", format='html') + for text, url in buttons.items(): + paragraph_node.append(nodes.raw(text=f"<a class='lv-example-link-button' onclick=\"event.stopPropagation();\" href='{url}'>{text}</a>", format='html')) + header.append(paragraph_node) + return toggle + def run(self): + example_path = self.arguments[0] + example_name = os.path.split(example_path)[1] + excluded_languages = self.options.get('excluded_languages', []) + node_list = [] + + env = self.state.document.settings.env + + iframe_html = "" + + c_path = self.get_example_code_path(example_path, 'c') + py_path = self.get_example_code_path(example_path, 'py') + + c_code = self.embed_code(c_path, example_path, 'c', buttons={ + '<i class="fa fa-github"></i> GitHub': self.github_path(example_path, 'c') + }) + py_code = self.embed_code(py_path, example_path, 'py', buttons={ + '<i class="fa fa-github"></i> GitHub': self.github_path(example_path, 'py'), + '<i class="fa fa-play"></i> Simulator': f"https://sim.lvgl.io/v{env.config.version}/micropython/ports/javascript/index.html?script_startup=https://raw.githubusercontent.com/lvgl/lvgl/{env.config.repo_commit_hash}/examples/header.py&script=https://raw.githubusercontent.com/lvgl/lvgl/{env.config.repo_commit_hash}/examples/{example_path}.py" + }) + + if not 'c' in excluded_languages: + if env.app.tags.has('html'): + iframe_html = f"<div class='lv-example' data-real-src='/{env.config.version}/_static/built_lv_examples/index.html?example={example_name}&w=320&h=240'></div>" + + description_html = f"<div class='lv-example-description'>{self.options.get('description', '')}</div>" + layout_node = nodes.raw(text=f"<div class='lv-example-container'>{iframe_html}{description_html}</div>", format='html') + + node_list.append(layout_node) + if not 'c' in excluded_languages: + node_list.append(c_code) + if not 'py' in excluded_languages: + node_list.append(py_code) + + trailing_node = nodes.raw(text=f"<hr/>", format='html') + node_list.append(trailing_node) + + return node_list + +def setup(app): + app.add_directive("lv_example", LvExample) + app.add_config_value("repo_commit_hash", "", "env") + + return { + 'version': '0.1', + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/lib/lvgl/docs/_static/css/custom.css b/lib/lvgl/docs/_static/css/custom.css new file mode 100644 index 00000000..93a95be1 --- /dev/null +++ b/lib/lvgl/docs/_static/css/custom.css @@ -0,0 +1,133 @@ +table, th, td { + border: 1px solid #bbb; + padding: 10px; +} + +td { + text-align:center; +} +span.pre +{ + padding-right:8px; +} + +span.pre:first-child +{ + padding-right:0px; +} + + +code.sig-name +{ + /*margin-left:8px;*/ +} + +.toggle .header { + display: block; + clear: both; + cursor: pointer; + font-weight: bold; +} + +.toggle .header:before { + font-family: FontAwesome, "Lato","proxima-nova","Helvetica Neue",Arial,sans-serif; + content: "\f0da \00a0 Show "; + display: inline-block; + font-size: 1.1em; +} + +.toggle .header.open:before { + content: "\f0d7 \00a0 Hide "; +} + +.header p { + display: inline-block; + font-size: 1.1em; + margin-bottom: 8px; +} + +.wy-side-nav-search { + background-color: #f5f5f5; +} +.wy-side-nav-search>div.version { + color: #333; + display: none; /*replaced by dropdown*/ +} + + +.home-img { + width:32%; + transition: transform .3s ease-out; +} + +.home-img:hover { + transform: translate(0, -10px); +} + +/*Let `code` wrap*/ +.rst-content code, .rst-content tt, code { + white-space: normal; +} + +.lv-example, .lv-example > iframe { + border: none; + outline: none; + padding: none; + display: block; + width: 320px; + height: 240px; + flex: none; + position: relative; +} + +.lv-example > iframe { + position: absolute; + top: 0; + left: 0; +} + +.lv-example-container { + display: flex; + padding-bottom: 16px; +} +.lv-example-description { + flex: 1 1 auto; + margin-left: 1rem; +} + +.lv-example-link-button { + display: inline-block; + padding: 4px 8px; + border-radius: 4px; + background-color: #2980b9; + color: white; + margin: 0 4px; +} +.lv-example-link-button:hover { + color: white; + filter: brightness(120%); +} + +.lv-example-link-button:visited { + color: white; +} + +dl.cpp.unexpanded dd { + display: none; +} + +.lv-api-expansion-button { + padding: 4px; +} +.lv-api-expansion-button::before { + font-family: FontAwesome, "Lato","proxima-nova","Helvetica Neue",Arial,sans-serif; + display: inline-block; + font-size: 1.1em; + cursor: pointer; +} +.unexpanded .lv-api-expansion-button::before { + content: "\f0da \00a0"; +} +.expanded .lv-api-expansion-button::before { + content: "\f0d7 \00a0"; +}
\ No newline at end of file diff --git a/lib/lvgl/docs/_static/css/fontawesome.min.css b/lib/lvgl/docs/_static/css/fontawesome.min.css new file mode 100644 index 00000000..deb5b4a5 --- /dev/null +++ b/lib/lvgl/docs/_static/css/fontawesome.min.css @@ -0,0 +1,5 @@ +/*! + * Font Awesome Free 5.9.0 by @fontawesome - https://fontawesome.com + * License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) + */ +.fa,.fab,.fal,.far,.fas{-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased;display:inline-block;font-style:normal;font-variant:normal;text-rendering:auto;line-height:1}.fa-lg{font-size:1.33333em;line-height:.75em;vertical-align:-.0667em}.fa-xs{font-size:.75em}.fa-sm{font-size:.875em}.fa-1x{font-size:1em}.fa-2x{font-size:2em}.fa-3x{font-size:3em}.fa-4x{font-size:4em}.fa-5x{font-size:5em}.fa-6x{font-size:6em}.fa-7x{font-size:7em}.fa-8x{font-size:8em}.fa-9x{font-size:9em}.fa-10x{font-size:10em}.fa-fw{text-align:center;width:1.25em}.fa-ul{list-style-type:none;margin-left:2.5em;padding-left:0}.fa-ul>li{position:relative}.fa-li{left:-2em;position:absolute;text-align:center;width:2em;line-height:inherit}.fa-border{border:.08em solid #eee;border-radius:.1em;padding:.2em .25em .15em}.fa-pull-left{float:left}.fa-pull-right{float:right}.fa.fa-pull-left,.fab.fa-pull-left,.fal.fa-pull-left,.far.fa-pull-left,.fas.fa-pull-left{margin-right:.3em}.fa.fa-pull-right,.fab.fa-pull-right,.fal.fa-pull-right,.far.fa-pull-right,.fas.fa-pull-right{margin-left:.3em}.fa-spin{animation:fa-spin 2s infinite linear}.fa-pulse{animation:fa-spin 1s infinite steps(8)}@keyframes fa-spin{0%{transform:rotate(0deg)}to{transform:rotate(1turn)}}.fa-rotate-90{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=1)";transform:rotate(90deg)}.fa-rotate-180{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2)";transform:rotate(180deg)}.fa-rotate-270{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=3)";transform:rotate(270deg)}.fa-flip-horizontal{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=0, mirror=1)";transform:scaleX(-1)}.fa-flip-vertical{transform:scaleY(-1)}.fa-flip-both,.fa-flip-horizontal.fa-flip-vertical,.fa-flip-vertical{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2, mirror=1)"}.fa-flip-both,.fa-flip-horizontal.fa-flip-vertical{transform:scale(-1)}:root .fa-flip-both,:root .fa-flip-horizontal,:root .fa-flip-vertical,:root .fa-rotate-90,:root .fa-rotate-180,:root .fa-rotate-270{filter:none}.fa-stack{display:inline-block;height:2em;line-height:2em;position:relative;vertical-align:middle;width:2.5em}.fa-stack-1x,.fa-stack-2x{left:0;position:absolute;text-align:center;width:100%}.fa-stack-1x{line-height:inherit}.fa-stack-2x{font-size:2em}.fa-inverse{color:#fff}.fa-500px:before{content:"\f26e"}.fa-accessible-icon:before{content:"\f368"}.fa-accusoft:before{content:"\f369"}.fa-acquisitions-incorporated:before{content:"\f6af"}.fa-ad:before{content:"\f641"}.fa-address-book:before{content:"\f2b9"}.fa-address-card:before{content:"\f2bb"}.fa-adjust:before{content:"\f042"}.fa-adn:before{content:"\f170"}.fa-adobe:before{content:"\f778"}.fa-adversal:before{content:"\f36a"}.fa-affiliatetheme:before{content:"\f36b"}.fa-air-freshener:before{content:"\f5d0"}.fa-airbnb:before{content:"\f834"}.fa-algolia:before{content:"\f36c"}.fa-align-center:before{content:"\f037"}.fa-align-justify:before{content:"\f039"}.fa-align-left:before{content:"\f036"}.fa-align-right:before{content:"\f038"}.fa-alipay:before{content:"\f642"}.fa-allergies:before{content:"\f461"}.fa-amazon:before{content:"\f270"}.fa-amazon-pay:before{content:"\f42c"}.fa-ambulance:before{content:"\f0f9"}.fa-american-sign-language-interpreting:before{content:"\f2a3"}.fa-amilia:before{content:"\f36d"}.fa-anchor:before{content:"\f13d"}.fa-android:before{content:"\f17b"}.fa-angellist:before{content:"\f209"}.fa-angle-double-down:before{content:"\f103"}.fa-angle-double-left:before{content:"\f100"}.fa-angle-double-right:before{content:"\f101"}.fa-angle-double-up:before{content:"\f102"}.fa-angle-down:before{content:"\f107"}.fa-angle-left:before{content:"\f104"}.fa-angle-right:before{content:"\f105"}.fa-angle-up:before{content:"\f106"}.fa-angry:before{content:"\f556"}.fa-angrycreative:before{content:"\f36e"}.fa-angular:before{content:"\f420"}.fa-ankh:before{content:"\f644"}.fa-app-store:before{content:"\f36f"}.fa-app-store-ios:before{content:"\f370"}.fa-apper:before{content:"\f371"}.fa-apple:before{content:"\f179"}.fa-apple-alt:before{content:"\f5d1"}.fa-apple-pay:before{content:"\f415"}.fa-archive:before{content:"\f187"}.fa-archway:before{content:"\f557"}.fa-arrow-alt-circle-down:before{content:"\f358"}.fa-arrow-alt-circle-left:before{content:"\f359"}.fa-arrow-alt-circle-right:before{content:"\f35a"}.fa-arrow-alt-circle-up:before{content:"\f35b"}.fa-arrow-circle-down:before{content:"\f0ab"}.fa-arrow-circle-left:before{content:"\f0a8"}.fa-arrow-circle-right:before{content:"\f0a9"}.fa-arrow-circle-up:before{content:"\f0aa"}.fa-arrow-down:before{content:"\f063"}.fa-arrow-left:before{content:"\f060"}.fa-arrow-right:before{content:"\f061"}.fa-arrow-up:before{content:"\f062"}.fa-arrows-alt:before{content:"\f0b2"}.fa-arrows-alt-h:before{content:"\f337"}.fa-arrows-alt-v:before{content:"\f338"}.fa-artstation:before{content:"\f77a"}.fa-assistive-listening-systems:before{content:"\f2a2"}.fa-asterisk:before{content:"\f069"}.fa-asymmetrik:before{content:"\f372"}.fa-at:before{content:"\f1fa"}.fa-atlas:before{content:"\f558"}.fa-atlassian:before{content:"\f77b"}.fa-atom:before{content:"\f5d2"}.fa-audible:before{content:"\f373"}.fa-audio-description:before{content:"\f29e"}.fa-autoprefixer:before{content:"\f41c"}.fa-avianex:before{content:"\f374"}.fa-aviato:before{content:"\f421"}.fa-award:before{content:"\f559"}.fa-aws:before{content:"\f375"}.fa-baby:before{content:"\f77c"}.fa-baby-carriage:before{content:"\f77d"}.fa-backspace:before{content:"\f55a"}.fa-backward:before{content:"\f04a"}.fa-bacon:before{content:"\f7e5"}.fa-balance-scale:before{content:"\f24e"}.fa-balance-scale-left:before{content:"\f515"}.fa-balance-scale-right:before{content:"\f516"}.fa-ban:before{content:"\f05e"}.fa-band-aid:before{content:"\f462"}.fa-bandcamp:before{content:"\f2d5"}.fa-barcode:before{content:"\f02a"}.fa-bars:before{content:"\f0c9"}.fa-baseball-ball:before{content:"\f433"}.fa-basketball-ball:before{content:"\f434"}.fa-bath:before{content:"\f2cd"}.fa-battery-empty:before{content:"\f244"}.fa-battery-full:before{content:"\f240"}.fa-battery-half:before{content:"\f242"}.fa-battery-quarter:before{content:"\f243"}.fa-battery-three-quarters:before{content:"\f241"}.fa-battle-net:before{content:"\f835"}.fa-bed:before{content:"\f236"}.fa-beer:before{content:"\f0fc"}.fa-behance:before{content:"\f1b4"}.fa-behance-square:before{content:"\f1b5"}.fa-bell:before{content:"\f0f3"}.fa-bell-slash:before{content:"\f1f6"}.fa-bezier-curve:before{content:"\f55b"}.fa-bible:before{content:"\f647"}.fa-bicycle:before{content:"\f206"}.fa-biking:before{content:"\f84a"}.fa-bimobject:before{content:"\f378"}.fa-binoculars:before{content:"\f1e5"}.fa-biohazard:before{content:"\f780"}.fa-birthday-cake:before{content:"\f1fd"}.fa-bitbucket:before{content:"\f171"}.fa-bitcoin:before{content:"\f379"}.fa-bity:before{content:"\f37a"}.fa-black-tie:before{content:"\f27e"}.fa-blackberry:before{content:"\f37b"}.fa-blender:before{content:"\f517"}.fa-blender-phone:before{content:"\f6b6"}.fa-blind:before{content:"\f29d"}.fa-blog:before{content:"\f781"}.fa-blogger:before{content:"\f37c"}.fa-blogger-b:before{content:"\f37d"}.fa-bluetooth:before{content:"\f293"}.fa-bluetooth-b:before{content:"\f294"}.fa-bold:before{content:"\f032"}.fa-bolt:before{content:"\f0e7"}.fa-bomb:before{content:"\f1e2"}.fa-bone:before{content:"\f5d7"}.fa-bong:before{content:"\f55c"}.fa-book:before{content:"\f02d"}.fa-book-dead:before{content:"\f6b7"}.fa-book-medical:before{content:"\f7e6"}.fa-book-open:before{content:"\f518"}.fa-book-reader:before{content:"\f5da"}.fa-bookmark:before{content:"\f02e"}.fa-bootstrap:before{content:"\f836"}.fa-border-all:before{content:"\f84c"}.fa-border-none:before{content:"\f850"}.fa-border-style:before{content:"\f853"}.fa-bowling-ball:before{content:"\f436"}.fa-box:before{content:"\f466"}.fa-box-open:before{content:"\f49e"}.fa-boxes:before{content:"\f468"}.fa-braille:before{content:"\f2a1"}.fa-brain:before{content:"\f5dc"}.fa-bread-slice:before{content:"\f7ec"}.fa-briefcase:before{content:"\f0b1"}.fa-briefcase-medical:before{content:"\f469"}.fa-broadcast-tower:before{content:"\f519"}.fa-broom:before{content:"\f51a"}.fa-brush:before{content:"\f55d"}.fa-btc:before{content:"\f15a"}.fa-buffer:before{content:"\f837"}.fa-bug:before{content:"\f188"}.fa-building:before{content:"\f1ad"}.fa-bullhorn:before{content:"\f0a1"}.fa-bullseye:before{content:"\f140"}.fa-burn:before{content:"\f46a"}.fa-buromobelexperte:before{content:"\f37f"}.fa-bus:before{content:"\f207"}.fa-bus-alt:before{content:"\f55e"}.fa-business-time:before{content:"\f64a"}.fa-buysellads:before{content:"\f20d"}.fa-calculator:before{content:"\f1ec"}.fa-calendar:before{content:"\f133"}.fa-calendar-alt:before{content:"\f073"}.fa-calendar-check:before{content:"\f274"}.fa-calendar-day:before{content:"\f783"}.fa-calendar-minus:before{content:"\f272"}.fa-calendar-plus:before{content:"\f271"}.fa-calendar-times:before{content:"\f273"}.fa-calendar-week:before{content:"\f784"}.fa-camera:before{content:"\f030"}.fa-camera-retro:before{content:"\f083"}.fa-campground:before{content:"\f6bb"}.fa-canadian-maple-leaf:before{content:"\f785"}.fa-candy-cane:before{content:"\f786"}.fa-cannabis:before{content:"\f55f"}.fa-capsules:before{content:"\f46b"}.fa-car:before{content:"\f1b9"}.fa-car-alt:before{content:"\f5de"}.fa-car-battery:before{content:"\f5df"}.fa-car-crash:before{content:"\f5e1"}.fa-car-side:before{content:"\f5e4"}.fa-caret-down:before{content:"\f0d7"}.fa-caret-left:before{content:"\f0d9"}.fa-caret-right:before{content:"\f0da"}.fa-caret-square-down:before{content:"\f150"}.fa-caret-square-left:before{content:"\f191"}.fa-caret-square-right:before{content:"\f152"}.fa-caret-square-up:before{content:"\f151"}.fa-caret-up:before{content:"\f0d8"}.fa-carrot:before{content:"\f787"}.fa-cart-arrow-down:before{content:"\f218"}.fa-cart-plus:before{content:"\f217"}.fa-cash-register:before{content:"\f788"}.fa-cat:before{content:"\f6be"}.fa-cc-amazon-pay:before{content:"\f42d"}.fa-cc-amex:before{content:"\f1f3"}.fa-cc-apple-pay:before{content:"\f416"}.fa-cc-diners-club:before{content:"\f24c"}.fa-cc-discover:before{content:"\f1f2"}.fa-cc-jcb:before{content:"\f24b"}.fa-cc-mastercard:before{content:"\f1f1"}.fa-cc-paypal:before{content:"\f1f4"}.fa-cc-stripe:before{content:"\f1f5"}.fa-cc-visa:before{content:"\f1f0"}.fa-centercode:before{content:"\f380"}.fa-centos:before{content:"\f789"}.fa-certificate:before{content:"\f0a3"}.fa-chair:before{content:"\f6c0"}.fa-chalkboard:before{content:"\f51b"}.fa-chalkboard-teacher:before{content:"\f51c"}.fa-charging-station:before{content:"\f5e7"}.fa-chart-area:before{content:"\f1fe"}.fa-chart-bar:before{content:"\f080"}.fa-chart-line:before{content:"\f201"}.fa-chart-pie:before{content:"\f200"}.fa-check:before{content:"\f00c"}.fa-check-circle:before{content:"\f058"}.fa-check-double:before{content:"\f560"}.fa-check-square:before{content:"\f14a"}.fa-cheese:before{content:"\f7ef"}.fa-chess:before{content:"\f439"}.fa-chess-bishop:before{content:"\f43a"}.fa-chess-board:before{content:"\f43c"}.fa-chess-king:before{content:"\f43f"}.fa-chess-knight:before{content:"\f441"}.fa-chess-pawn:before{content:"\f443"}.fa-chess-queen:before{content:"\f445"}.fa-chess-rook:before{content:"\f447"}.fa-chevron-circle-down:before{content:"\f13a"}.fa-chevron-circle-left:before{content:"\f137"}.fa-chevron-circle-right:before{content:"\f138"}.fa-chevron-circle-up:before{content:"\f139"}.fa-chevron-down:before{content:"\f078"}.fa-chevron-left:before{content:"\f053"}.fa-chevron-right:before{content:"\f054"}.fa-chevron-up:before{content:"\f077"}.fa-child:before{content:"\f1ae"}.fa-chrome:before{content:"\f268"}.fa-chromecast:before{content:"\f838"}.fa-church:before{content:"\f51d"}.fa-circle:before{content:"\f111"}.fa-circle-notch:before{content:"\f1ce"}.fa-city:before{content:"\f64f"}.fa-clinic-medical:before{content:"\f7f2"}.fa-clipboard:before{content:"\f328"}.fa-clipboard-check:before{content:"\f46c"}.fa-clipboard-list:before{content:"\f46d"}.fa-clock:before{content:"\f017"}.fa-clone:before{content:"\f24d"}.fa-closed-captioning:before{content:"\f20a"}.fa-cloud:before{content:"\f0c2"}.fa-cloud-download-alt:before{content:"\f381"}.fa-cloud-meatball:before{content:"\f73b"}.fa-cloud-moon:before{content:"\f6c3"}.fa-cloud-moon-rain:before{content:"\f73c"}.fa-cloud-rain:before{content:"\f73d"}.fa-cloud-showers-heavy:before{content:"\f740"}.fa-cloud-sun:before{content:"\f6c4"}.fa-cloud-sun-rain:before{content:"\f743"}.fa-cloud-upload-alt:before{content:"\f382"}.fa-cloudscale:before{content:"\f383"}.fa-cloudsmith:before{content:"\f384"}.fa-cloudversify:before{content:"\f385"}.fa-cocktail:before{content:"\f561"}.fa-code:before{content:"\f121"}.fa-code-branch:before{content:"\f126"}.fa-codepen:before{content:"\f1cb"}.fa-codiepie:before{content:"\f284"}.fa-coffee:before{content:"\f0f4"}.fa-cog:before{content:"\f013"}.fa-cogs:before{content:"\f085"}.fa-coins:before{content:"\f51e"}.fa-columns:before{content:"\f0db"}.fa-comment:before{content:"\f075"}.fa-comment-alt:before{content:"\f27a"}.fa-comment-dollar:before{content:"\f651"}.fa-comment-dots:before{content:"\f4ad"}.fa-comment-medical:before{content:"\f7f5"}.fa-comment-slash:before{content:"\f4b3"}.fa-comments:before{content:"\f086"}.fa-comments-dollar:before{content:"\f653"}.fa-compact-disc:before{content:"\f51f"}.fa-compass:before{content:"\f14e"}.fa-compress:before{content:"\f066"}.fa-compress-arrows-alt:before{content:"\f78c"}.fa-concierge-bell:before{content:"\f562"}.fa-confluence:before{content:"\f78d"}.fa-connectdevelop:before{content:"\f20e"}.fa-contao:before{content:"\f26d"}.fa-cookie:before{content:"\f563"}.fa-cookie-bite:before{content:"\f564"}.fa-copy:before{content:"\f0c5"}.fa-copyright:before{content:"\f1f9"}.fa-couch:before{content:"\f4b8"}.fa-cpanel:before{content:"\f388"}.fa-creative-commons:before{content:"\f25e"}.fa-creative-commons-by:before{content:"\f4e7"}.fa-creative-commons-nc:before{content:"\f4e8"}.fa-creative-commons-nc-eu:before{content:"\f4e9"}.fa-creative-commons-nc-jp:before{content:"\f4ea"}.fa-creative-commons-nd:before{content:"\f4eb"}.fa-creative-commons-pd:before{content:"\f4ec"}.fa-creative-commons-pd-alt:before{content:"\f4ed"}.fa-creative-commons-remix:before{content:"\f4ee"}.fa-creative-commons-sa:before{content:"\f4ef"}.fa-creative-commons-sampling:before{content:"\f4f0"}.fa-creative-commons-sampling-plus:before{content:"\f4f1"}.fa-creative-commons-share:before{content:"\f4f2"}.fa-creative-commons-zero:before{content:"\f4f3"}.fa-credit-card:before{content:"\f09d"}.fa-critical-role:before{content:"\f6c9"}.fa-crop:before{content:"\f125"}.fa-crop-alt:before{content:"\f565"}.fa-cross:before{content:"\f654"}.fa-crosshairs:before{content:"\f05b"}.fa-crow:before{content:"\f520"}.fa-crown:before{content:"\f521"}.fa-crutch:before{content:"\f7f7"}.fa-css3:before{content:"\f13c"}.fa-css3-alt:before{content:"\f38b"}.fa-cube:before{content:"\f1b2"}.fa-cubes:before{content:"\f1b3"}.fa-cut:before{content:"\f0c4"}.fa-cuttlefish:before{content:"\f38c"}.fa-d-and-d:before{content:"\f38d"}.fa-d-and-d-beyond:before{content:"\f6ca"}.fa-dashcube:before{content:"\f210"}.fa-database:before{content:"\f1c0"}.fa-deaf:before{content:"\f2a4"}.fa-delicious:before{content:"\f1a5"}.fa-democrat:before{content:"\f747"}.fa-deploydog:before{content:"\f38e"}.fa-deskpro:before{content:"\f38f"}.fa-desktop:before{content:"\f108"}.fa-dev:before{content:"\f6cc"}.fa-deviantart:before{content:"\f1bd"}.fa-dharmachakra:before{content:"\f655"}.fa-dhl:before{content:"\f790"}.fa-diagnoses:before{content:"\f470"}.fa-diaspora:before{content:"\f791"}.fa-dice:before{content:"\f522"}.fa-dice-d20:before{content:"\f6cf"}.fa-dice-d6:before{content:"\f6d1"}.fa-dice-five:before{content:"\f523"}.fa-dice-four:before{content:"\f524"}.fa-dice-one:before{content:"\f525"}.fa-dice-six:before{content:"\f526"}.fa-dice-three:before{content:"\f527"}.fa-dice-two:before{content:"\f528"}.fa-digg:before{content:"\f1a6"}.fa-digital-ocean:before{content:"\f391"}.fa-digital-tachograph:before{content:"\f566"}.fa-directions:before{content:"\f5eb"}.fa-discord:before{content:"\f392"}.fa-discourse:before{content:"\f393"}.fa-divide:before{content:"\f529"}.fa-dizzy:before{content:"\f567"}.fa-dna:before{content:"\f471"}.fa-dochub:before{content:"\f394"}.fa-docker:before{content:"\f395"}.fa-dog:before{content:"\f6d3"}.fa-dollar-sign:before{content:"\f155"}.fa-dolly:before{content:"\f472"}.fa-dolly-flatbed:before{content:"\f474"}.fa-donate:before{content:"\f4b9"}.fa-door-closed:before{content:"\f52a"}.fa-door-open:before{content:"\f52b"}.fa-dot-circle:before{content:"\f192"}.fa-dove:before{content:"\f4ba"}.fa-download:before{content:"\f019"}.fa-draft2digital:before{content:"\f396"}.fa-drafting-compass:before{content:"\f568"}.fa-dragon:before{content:"\f6d5"}.fa-draw-polygon:before{content:"\f5ee"}.fa-dribbble:before{content:"\f17d"}.fa-dribbble-square:before{content:"\f397"}.fa-dropbox:before{content:"\f16b"}.fa-drum:before{content:"\f569"}.fa-drum-steelpan:before{content:"\f56a"}.fa-drumstick-bite:before{content:"\f6d7"}.fa-drupal:before{content:"\f1a9"}.fa-dumbbell:before{content:"\f44b"}.fa-dumpster:before{content:"\f793"}.fa-dumpster-fire:before{content:"\f794"}.fa-dungeon:before{content:"\f6d9"}.fa-dyalog:before{content:"\f399"}.fa-earlybirds:before{content:"\f39a"}.fa-ebay:before{content:"\f4f4"}.fa-edge:before{content:"\f282"}.fa-edit:before{content:"\f044"}.fa-egg:before{content:"\f7fb"}.fa-eject:before{content:"\f052"}.fa-elementor:before{content:"\f430"}.fa-ellipsis-h:before{content:"\f141"}.fa-ellipsis-v:before{content:"\f142"}.fa-ello:before{content:"\f5f1"}.fa-ember:before{content:"\f423"}.fa-empire:before{content:"\f1d1"}.fa-envelope:before{content:"\f0e0"}.fa-envelope-open:before{content:"\f2b6"}.fa-envelope-open-text:before{content:"\f658"}.fa-envelope-square:before{content:"\f199"}.fa-envira:before{content:"\f299"}.fa-equals:before{content:"\f52c"}.fa-eraser:before{content:"\f12d"}.fa-erlang:before{content:"\f39d"}.fa-ethereum:before{content:"\f42e"}.fa-ethernet:before{content:"\f796"}.fa-etsy:before{content:"\f2d7"}.fa-euro-sign:before{content:"\f153"}.fa-evernote:before{content:"\f839"}.fa-exchange-alt:before{content:"\f362"}.fa-exclamation:before{content:"\f12a"}.fa-exclamation-circle:before{content:"\f06a"}.fa-exclamation-triangle:before{content:"\f071"}.fa-expand:before{content:"\f065"}.fa-expand-arrows-alt:before{content:"\f31e"}.fa-expeditedssl:before{content:"\f23e"}.fa-external-link-alt:before{content:"\f35d"}.fa-external-link-square-alt:before{content:"\f360"}.fa-eye:before{content:"\f06e"}.fa-eye-dropper:before{content:"\f1fb"}.fa-eye-slash:before{content:"\f070"}.fa-facebook:before{content:"\f09a"}.fa-facebook-f:before{content:"\f39e"}.fa-facebook-messenger:before{content:"\f39f"}.fa-facebook-square:before{content:"\f082"}.fa-fan:before{content:"\f863"}.fa-fantasy-flight-games:before{content:"\f6dc"}.fa-fast-backward:before{content:"\f049"}.fa-fast-forward:before{content:"\f050"}.fa-fax:before{content:"\f1ac"}.fa-feather:before{content:"\f52d"}.fa-feather-alt:before{content:"\f56b"}.fa-fedex:before{content:"\f797"}.fa-fedora:before{content:"\f798"}.fa-female:before{content:"\f182"}.fa-fighter-jet:before{content:"\f0fb"}.fa-figma:before{content:"\f799"}.fa-file:before{content:"\f15b"}.fa-file-alt:before{content:"\f15c"}.fa-file-archive:before{content:"\f1c6"}.fa-file-audio:before{content:"\f1c7"}.fa-file-code:before{content:"\f1c9"}.fa-file-contract:before{content:"\f56c"}.fa-file-csv:before{content:"\f6dd"}.fa-file-download:before{content:"\f56d"}.fa-file-excel:before{content:"\f1c3"}.fa-file-export:before{content:"\f56e"}.fa-file-image:before{content:"\f1c5"}.fa-file-import:before{content:"\f56f"}.fa-file-invoice:before{content:"\f570"}.fa-file-invoice-dollar:before{content:"\f571"}.fa-file-medical:before{content:"\f477"}.fa-file-medical-alt:before{content:"\f478"}.fa-file-pdf:before{content:"\f1c1"}.fa-file-powerpoint:before{content:"\f1c4"}.fa-file-prescription:before{content:"\f572"}.fa-file-signature:before{content:"\f573"}.fa-file-upload:before{content:"\f574"}.fa-file-video:before{content:"\f1c8"}.fa-file-word:before{content:"\f1c2"}.fa-fill:before{content:"\f575"}.fa-fill-drip:before{content:"\f576"}.fa-film:before{content:"\f008"}.fa-filter:before{content:"\f0b0"}.fa-fingerprint:before{content:"\f577"}.fa-fire:before{content:"\f06d"}.fa-fire-alt:before{content:"\f7e4"}.fa-fire-extinguisher:before{content:"\f134"}.fa-firefox:before{content:"\f269"}.fa-first-aid:before{content:"\f479"}.fa-first-order:before{content:"\f2b0"}.fa-first-order-alt:before{content:"\f50a"}.fa-firstdraft:before{content:"\f3a1"}.fa-fish:before{content:"\f578"}.fa-fist-raised:before{content:"\f6de"}.fa-flag:before{content:"\f024"}.fa-flag-checkered:before{content:"\f11e"}.fa-flag-usa:before{content:"\f74d"}.fa-flask:before{content:"\f0c3"}.fa-flickr:before{content:"\f16e"}.fa-flipboard:before{content:"\f44d"}.fa-flushed:before{content:"\f579"}.fa-fly:before{content:"\f417"}.fa-folder:before{content:"\f07b"}.fa-folder-minus:before{content:"\f65d"}.fa-folder-open:before{content:"\f07c"}.fa-folder-plus:before{content:"\f65e"}.fa-font:before{content:"\f031"}.fa-font-awesome:before{content:"\f2b4"}.fa-font-awesome-alt:before{content:"\f35c"}.fa-font-awesome-flag:before{content:"\f425"}.fa-font-awesome-logo-full:before{content:"\f4e6"}.fa-fonticons:before{content:"\f280"}.fa-fonticons-fi:before{content:"\f3a2"}.fa-football-ball:before{content:"\f44e"}.fa-fort-awesome:before{content:"\f286"}.fa-fort-awesome-alt:before{content:"\f3a3"}.fa-forumbee:before{content:"\f211"}.fa-forward:before{content:"\f04e"}.fa-foursquare:before{content:"\f180"}.fa-free-code-camp:before{content:"\f2c5"}.fa-freebsd:before{content:"\f3a4"}.fa-frog:before{content:"\f52e"}.fa-frown:before{content:"\f119"}.fa-frown-open:before{content:"\f57a"}.fa-fulcrum:before{content:"\f50b"}.fa-funnel-dollar:before{content:"\f662"}.fa-futbol:before{content:"\f1e3"}.fa-galactic-republic:before{content:"\f50c"}.fa-galactic-senate:before{content:"\f50d"}.fa-gamepad:before{content:"\f11b"}.fa-gas-pump:before{content:"\f52f"}.fa-gavel:before{content:"\f0e3"}.fa-gem:before{content:"\f3a5"}.fa-genderless:before{content:"\f22d"}.fa-get-pocket:before{content:"\f265"}.fa-gg:before{content:"\f260"}.fa-gg-circle:before{content:"\f261"}.fa-ghost:before{content:"\f6e2"}.fa-gift:before{content:"\f06b"}.fa-gifts:before{content:"\f79c"}.fa-git:before{content:"\f1d3"}.fa-git-alt:before{content:"\f841"}.fa-git-square:before{content:"\f1d2"}.fa-github:before{content:"\f09b"}.fa-github-alt:before{content:"\f113"}.fa-github-square:before{content:"\f092"}.fa-gitkraken:before{content:"\f3a6"}.fa-gitlab:before{content:"\f296"}.fa-gitter:before{content:"\f426"}.fa-glass-cheers:before{content:"\f79f"}.fa-glass-martini:before{content:"\f000"}.fa-glass-martini-alt:before{content:"\f57b"}.fa-glass-whiskey:before{content:"\f7a0"}.fa-glasses:before{content:"\f530"}.fa-glide:before{content:"\f2a5"}.fa-glide-g:before{content:"\f2a6"}.fa-globe:before{content:"\f0ac"}.fa-globe-africa:before{content:"\f57c"}.fa-globe-americas:before{content:"\f57d"}.fa-globe-asia:before{content:"\f57e"}.fa-globe-europe:before{content:"\f7a2"}.fa-gofore:before{content:"\f3a7"}.fa-golf-ball:before{content:"\f450"}.fa-goodreads:before{content:"\f3a8"}.fa-goodreads-g:before{content:"\f3a9"}.fa-google:before{content:"\f1a0"}.fa-google-drive:before{content:"\f3aa"}.fa-google-play:before{content:"\f3ab"}.fa-google-plus:before{content:"\f2b3"}.fa-google-plus-g:before{content:"\f0d5"}.fa-google-plus-square:before{content:"\f0d4"}.fa-google-wallet:before{content:"\f1ee"}.fa-gopuram:before{content:"\f664"}.fa-graduation-cap:before{content:"\f19d"}.fa-gratipay:before{content:"\f184"}.fa-grav:before{content:"\f2d6"}.fa-greater-than:before{content:"\f531"}.fa-greater-than-equal:before{content:"\f532"}.fa-grimace:before{content:"\f57f"}.fa-grin:before{content:"\f580"}.fa-grin-alt:before{content:"\f581"}.fa-grin-beam:before{content:"\f582"}.fa-grin-beam-sweat:before{content:"\f583"}.fa-grin-hearts:before{content:"\f584"}.fa-grin-squint:before{content:"\f585"}.fa-grin-squint-tears:before{content:"\f586"}.fa-grin-stars:before{content:"\f587"}.fa-grin-tears:before{content:"\f588"}.fa-grin-tongue:before{content:"\f589"}.fa-grin-tongue-squint:before{content:"\f58a"}.fa-grin-tongue-wink:before{content:"\f58b"}.fa-grin-wink:before{content:"\f58c"}.fa-grip-horizontal:before{content:"\f58d"}.fa-grip-lines:before{content:"\f7a4"}.fa-grip-lines-vertical:before{content:"\f7a5"}.fa-grip-vertical:before{content:"\f58e"}.fa-gripfire:before{content:"\f3ac"}.fa-grunt:before{content:"\f3ad"}.fa-guitar:before{content:"\f7a6"}.fa-gulp:before{content:"\f3ae"}.fa-h-square:before{content:"\f0fd"}.fa-hacker-news:before{content:"\f1d4"}.fa-hacker-news-square:before{content:"\f3af"}.fa-hackerrank:before{content:"\f5f7"}.fa-hamburger:before{content:"\f805"}.fa-hammer:before{content:"\f6e3"}.fa-hamsa:before{content:"\f665"}.fa-hand-holding:before{content:"\f4bd"}.fa-hand-holding-heart:before{content:"\f4be"}.fa-hand-holding-usd:before{content:"\f4c0"}.fa-hand-lizard:before{content:"\f258"}.fa-hand-middle-finger:before{content:"\f806"}.fa-hand-paper:before{content:"\f256"}.fa-hand-peace:before{content:"\f25b"}.fa-hand-point-down:before{content:"\f0a7"}.fa-hand-point-left:before{content:"\f0a5"}.fa-hand-point-right:before{content:"\f0a4"}.fa-hand-point-up:before{content:"\f0a6"}.fa-hand-pointer:before{content:"\f25a"}.fa-hand-rock:before{content:"\f255"}.fa-hand-scissors:before{content:"\f257"}.fa-hand-spock:before{content:"\f259"}.fa-hands:before{content:"\f4c2"}.fa-hands-helping:before{content:"\f4c4"}.fa-handshake:before{content:"\f2b5"}.fa-hanukiah:before{content:"\f6e6"}.fa-hard-hat:before{content:"\f807"}.fa-hashtag:before{content:"\f292"}.fa-hat-wizard:before{content:"\f6e8"}.fa-haykal:before{content:"\f666"}.fa-hdd:before{content:"\f0a0"}.fa-heading:before{content:"\f1dc"}.fa-headphones:before{content:"\f025"}.fa-headphones-alt:before{content:"\f58f"}.fa-headset:before{content:"\f590"}.fa-heart:before{content:"\f004"}.fa-heart-broken:before{content:"\f7a9"}.fa-heartbeat:before{content:"\f21e"}.fa-helicopter:before{content:"\f533"}.fa-highlighter:before{content:"\f591"}.fa-hiking:before{content:"\f6ec"}.fa-hippo:before{content:"\f6ed"}.fa-hips:before{content:"\f452"}.fa-hire-a-helper:before{content:"\f3b0"}.fa-history:before{content:"\f1da"}.fa-hockey-puck:before{content:"\f453"}.fa-holly-berry:before{content:"\f7aa"}.fa-home:before{content:"\f015"}.fa-hooli:before{content:"\f427"}.fa-hornbill:before{content:"\f592"}.fa-horse:before{content:"\f6f0"}.fa-horse-head:before{content:"\f7ab"}.fa-hospital:before{content:"\f0f8"}.fa-hospital-alt:before{content:"\f47d"}.fa-hospital-symbol:before{content:"\f47e"}.fa-hot-tub:before{content:"\f593"}.fa-hotdog:before{content:"\f80f"}.fa-hotel:before{content:"\f594"}.fa-hotjar:before{content:"\f3b1"}.fa-hourglass:before{content:"\f254"}.fa-hourglass-end:before{content:"\f253"}.fa-hourglass-half:before{content:"\f252"}.fa-hourglass-start:before{content:"\f251"}.fa-house-damage:before{content:"\f6f1"}.fa-houzz:before{content:"\f27c"}.fa-hryvnia:before{content:"\f6f2"}.fa-html5:before{content:"\f13b"}.fa-hubspot:before{content:"\f3b2"}.fa-i-cursor:before{content:"\f246"}.fa-ice-cream:before{content:"\f810"}.fa-icicles:before{content:"\f7ad"}.fa-icons:before{content:"\f86d"}.fa-id-badge:before{content:"\f2c1"}.fa-id-card:before{content:"\f2c2"}.fa-id-card-alt:before{content:"\f47f"}.fa-igloo:before{content:"\f7ae"}.fa-image:before{content:"\f03e"}.fa-images:before{content:"\f302"}.fa-imdb:before{content:"\f2d8"}.fa-inbox:before{content:"\f01c"}.fa-indent:before{content:"\f03c"}.fa-industry:before{content:"\f275"}.fa-infinity:before{content:"\f534"}.fa-info:before{content:"\f129"}.fa-info-circle:before{content:"\f05a"}.fa-instagram:before{content:"\f16d"}.fa-intercom:before{content:"\f7af"}.fa-internet-explorer:before{content:"\f26b"}.fa-invision:before{content:"\f7b0"}.fa-ioxhost:before{content:"\f208"}.fa-italic:before{content:"\f033"}.fa-itch-io:before{content:"\f83a"}.fa-itunes:before{content:"\f3b4"}.fa-itunes-note:before{content:"\f3b5"}.fa-java:before{content:"\f4e4"}.fa-jedi:before{content:"\f669"}.fa-jedi-order:before{content:"\f50e"}.fa-jenkins:before{content:"\f3b6"}.fa-jira:before{content:"\f7b1"}.fa-joget:before{content:"\f3b7"}.fa-joint:before{content:"\f595"}.fa-joomla:before{content:"\f1aa"}.fa-journal-whills:before{content:"\f66a"}.fa-js:before{content:"\f3b8"}.fa-js-square:before{content:"\f3b9"}.fa-jsfiddle:before{content:"\f1cc"}.fa-kaaba:before{content:"\f66b"}.fa-kaggle:before{content:"\f5fa"}.fa-key:before{content:"\f084"}.fa-keybase:before{content:"\f4f5"}.fa-keyboard:before{content:"\f11c"}.fa-keycdn:before{content:"\f3ba"}.fa-khanda:before{content:"\f66d"}.fa-kickstarter:before{content:"\f3bb"}.fa-kickstarter-k:before{content:"\f3bc"}.fa-kiss:before{content:"\f596"}.fa-kiss-beam:before{content:"\f597"}.fa-kiss-wink-heart:before{content:"\f598"}.fa-kiwi-bird:before{content:"\f535"}.fa-korvue:before{content:"\f42f"}.fa-landmark:before{content:"\f66f"}.fa-language:before{content:"\f1ab"}.fa-laptop:before{content:"\f109"}.fa-laptop-code:before{content:"\f5fc"}.fa-laptop-medical:before{content:"\f812"}.fa-laravel:before{content:"\f3bd"}.fa-lastfm:before{content:"\f202"}.fa-lastfm-square:before{content:"\f203"}.fa-laugh:before{content:"\f599"}.fa-laugh-beam:before{content:"\f59a"}.fa-laugh-squint:before{content:"\f59b"}.fa-laugh-wink:before{content:"\f59c"}.fa-layer-group:before{content:"\f5fd"}.fa-leaf:before{content:"\f06c"}.fa-leanpub:before{content:"\f212"}.fa-lemon:before{content:"\f094"}.fa-less:before{content:"\f41d"}.fa-less-than:before{content:"\f536"}.fa-less-than-equal:before{content:"\f537"}.fa-level-down-alt:before{content:"\f3be"}.fa-level-up-alt:before{content:"\f3bf"}.fa-life-ring:before{content:"\f1cd"}.fa-lightbulb:before{content:"\f0eb"}.fa-line:before{content:"\f3c0"}.fa-link:before{content:"\f0c1"}.fa-linkedin:before{content:"\f08c"}.fa-linkedin-in:before{content:"\f0e1"}.fa-linode:before{content:"\f2b8"}.fa-linux:before{content:"\f17c"}.fa-lira-sign:before{content:"\f195"}.fa-list:before{content:"\f03a"}.fa-list-alt:before{content:"\f022"}.fa-list-ol:before{content:"\f0cb"}.fa-list-ul:before{content:"\f0ca"}.fa-location-arrow:before{content:"\f124"}.fa-lock:before{content:"\f023"}.fa-lock-open:before{content:"\f3c1"}.fa-long-arrow-alt-down:before{content:"\f309"}.fa-long-arrow-alt-left:before{content:"\f30a"}.fa-long-arrow-alt-right:before{content:"\f30b"}.fa-long-arrow-alt-up:before{content:"\f30c"}.fa-low-vision:before{content:"\f2a8"}.fa-luggage-cart:before{content:"\f59d"}.fa-lyft:before{content:"\f3c3"}.fa-magento:before{content:"\f3c4"}.fa-magic:before{content:"\f0d0"}.fa-magnet:before{content:"\f076"}.fa-mail-bulk:before{content:"\f674"}.fa-mailchimp:before{content:"\f59e"}.fa-male:before{content:"\f183"}.fa-mandalorian:before{content:"\f50f"}.fa-map:before{content:"\f279"}.fa-map-marked:before{content:"\f59f"}.fa-map-marked-alt:before{content:"\f5a0"}.fa-map-marker:before{content:"\f041"}.fa-map-marker-alt:before{content:"\f3c5"}.fa-map-pin:before{content:"\f276"}.fa-map-signs:before{content:"\f277"}.fa-markdown:before{content:"\f60f"}.fa-marker:before{content:"\f5a1"}.fa-mars:before{content:"\f222"}.fa-mars-double:before{content:"\f227"}.fa-mars-stroke:before{content:"\f229"}.fa-mars-stroke-h:before{content:"\f22b"}.fa-mars-stroke-v:before{content:"\f22a"}.fa-mask:before{content:"\f6fa"}.fa-mastodon:before{content:"\f4f6"}.fa-maxcdn:before{content:"\f136"}.fa-medal:before{content:"\f5a2"}.fa-medapps:before{content:"\f3c6"}.fa-medium:before{content:"\f23a"}.fa-medium-m:before{content:"\f3c7"}.fa-medkit:before{content:"\f0fa"}.fa-medrt:before{content:"\f3c8"}.fa-meetup:before{content:"\f2e0"}.fa-megaport:before{content:"\f5a3"}.fa-meh:before{content:"\f11a"}.fa-meh-blank:before{content:"\f5a4"}.fa-meh-rolling-eyes:before{content:"\f5a5"}.fa-memory:before{content:"\f538"}.fa-mendeley:before{content:"\f7b3"}.fa-menorah:before{content:"\f676"}.fa-mercury:before{content:"\f223"}.fa-meteor:before{content:"\f753"}.fa-microchip:before{content:"\f2db"}.fa-microphone:before{content:"\f130"}.fa-microphone-alt:before{content:"\f3c9"}.fa-microphone-alt-slash:before{content:"\f539"}.fa-microphone-slash:before{content:"\f131"}.fa-microscope:before{content:"\f610"}.fa-microsoft:before{content:"\f3ca"}.fa-minus:before{content:"\f068"}.fa-minus-circle:before{content:"\f056"}.fa-minus-square:before{content:"\f146"}.fa-mitten:before{content:"\f7b5"}.fa-mix:before{content:"\f3cb"}.fa-mixcloud:before{content:"\f289"}.fa-mizuni:before{content:"\f3cc"}.fa-mobile:before{content:"\f10b"}.fa-mobile-alt:before{content:"\f3cd"}.fa-modx:before{content:"\f285"}.fa-monero:before{content:"\f3d0"}.fa-money-bill:before{content:"\f0d6"}.fa-money-bill-alt:before{content:"\f3d1"}.fa-money-bill-wave:before{content:"\f53a"}.fa-money-bill-wave-alt:before{content:"\f53b"}.fa-money-check:before{content:"\f53c"}.fa-money-check-alt:before{content:"\f53d"}.fa-monument:before{content:"\f5a6"}.fa-moon:before{content:"\f186"}.fa-mortar-pestle:before{content:"\f5a7"}.fa-mosque:before{content:"\f678"}.fa-motorcycle:before{content:"\f21c"}.fa-mountain:before{content:"\f6fc"}.fa-mouse-pointer:before{content:"\f245"}.fa-mug-hot:before{content:"\f7b6"}.fa-music:before{content:"\f001"}.fa-napster:before{content:"\f3d2"}.fa-neos:before{content:"\f612"}.fa-network-wired:before{content:"\f6ff"}.fa-neuter:before{content:"\f22c"}.fa-newspaper:before{content:"\f1ea"}.fa-nimblr:before{content:"\f5a8"}.fa-node:before{content:"\f419"}.fa-node-js:before{content:"\f3d3"}.fa-not-equal:before{content:"\f53e"}.fa-notes-medical:before{content:"\f481"}.fa-npm:before{content:"\f3d4"}.fa-ns8:before{content:"\f3d5"}.fa-nutritionix:before{content:"\f3d6"}.fa-object-group:before{content:"\f247"}.fa-object-ungroup:before{content:"\f248"}.fa-odnoklassniki:before{content:"\f263"}.fa-odnoklassniki-square:before{content:"\f264"}.fa-oil-can:before{content:"\f613"}.fa-old-republic:before{content:"\f510"}.fa-om:before{content:"\f679"}.fa-opencart:before{content:"\f23d"}.fa-openid:before{content:"\f19b"}.fa-opera:before{content:"\f26a"}.fa-optin-monster:before{content:"\f23c"}.fa-osi:before{content:"\f41a"}.fa-otter:before{content:"\f700"}.fa-outdent:before{content:"\f03b"}.fa-page4:before{content:"\f3d7"}.fa-pagelines:before{content:"\f18c"}.fa-pager:before{content:"\f815"}.fa-paint-brush:before{content:"\f1fc"}.fa-paint-roller:before{content:"\f5aa"}.fa-palette:before{content:"\f53f"}.fa-palfed:before{content:"\f3d8"}.fa-pallet:before{content:"\f482"}.fa-paper-plane:before{content:"\f1d8"}.fa-paperclip:before{content:"\f0c6"}.fa-parachute-box:before{content:"\f4cd"}.fa-paragraph:before{content:"\f1dd"}.fa-parking:before{content:"\f540"}.fa-passport:before{content:"\f5ab"}.fa-pastafarianism:before{content:"\f67b"}.fa-paste:before{content:"\f0ea"}.fa-patreon:before{content:"\f3d9"}.fa-pause:before{content:"\f04c"}.fa-pause-circle:before{content:"\f28b"}.fa-paw:before{content:"\f1b0"}.fa-paypal:before{content:"\f1ed"}.fa-peace:before{content:"\f67c"}.fa-pen:before{content:"\f304"}.fa-pen-alt:before{content:"\f305"}.fa-pen-fancy:before{content:"\f5ac"}.fa-pen-nib:before{content:"\f5ad"}.fa-pen-square:before{content:"\f14b"}.fa-pencil-alt:before{content:"\f303"}.fa-pencil-ruler:before{content:"\f5ae"}.fa-penny-arcade:before{content:"\f704"}.fa-people-carry:before{content:"\f4ce"}.fa-pepper-hot:before{content:"\f816"}.fa-percent:before{content:"\f295"}.fa-percentage:before{content:"\f541"}.fa-periscope:before{content:"\f3da"}.fa-person-booth:before{content:"\f756"}.fa-phabricator:before{content:"\f3db"}.fa-phoenix-framework:before{content:"\f3dc"}.fa-phoenix-squadron:before{content:"\f511"}.fa-phone:before{content:"\f095"}.fa-phone-alt:before{content:"\f879"}.fa-phone-slash:before{content:"\f3dd"}.fa-phone-square:before{content:"\f098"}.fa-phone-square-alt:before{content:"\f87b"}.fa-phone-volume:before{content:"\f2a0"}.fa-photo-video:before{content:"\f87c"}.fa-php:before{content:"\f457"}.fa-pied-piper:before{content:"\f2ae"}.fa-pied-piper-alt:before{content:"\f1a8"}.fa-pied-piper-hat:before{content:"\f4e5"}.fa-pied-piper-pp:before{content:"\f1a7"}.fa-piggy-bank:before{content:"\f4d3"}.fa-pills:before{content:"\f484"}.fa-pinterest:before{content:"\f0d2"}.fa-pinterest-p:before{content:"\f231"}.fa-pinterest-square:before{content:"\f0d3"}.fa-pizza-slice:before{content:"\f818"}.fa-place-of-worship:before{content:"\f67f"}.fa-plane:before{content:"\f072"}.fa-plane-arrival:before{content:"\f5af"}.fa-plane-departure:before{content:"\f5b0"}.fa-play:before{content:"\f04b"}.fa-play-circle:before{content:"\f144"}.fa-playstation:before{content:"\f3df"}.fa-plug:before{content:"\f1e6"}.fa-plus:before{content:"\f067"}.fa-plus-circle:before{content:"\f055"}.fa-plus-square:before{content:"\f0fe"}.fa-podcast:before{content:"\f2ce"}.fa-poll:before{content:"\f681"}.fa-poll-h:before{content:"\f682"}.fa-poo:before{content:"\f2fe"}.fa-poo-storm:before{content:"\f75a"}.fa-poop:before{content:"\f619"}.fa-portrait:before{content:"\f3e0"}.fa-pound-sign:before{content:"\f154"}.fa-power-off:before{content:"\f011"}.fa-pray:before{content:"\f683"}.fa-praying-hands:before{content:"\f684"}.fa-prescription:before{content:"\f5b1"}.fa-prescription-bottle:before{content:"\f485"}.fa-prescription-bottle-alt:before{content:"\f486"}.fa-print:before{content:"\f02f"}.fa-procedures:before{content:"\f487"}.fa-product-hunt:before{content:"\f288"}.fa-project-diagram:before{content:"\f542"}.fa-pushed:before{content:"\f3e1"}.fa-puzzle-piece:before{content:"\f12e"}.fa-python:before{content:"\f3e2"}.fa-qq:before{content:"\f1d6"}.fa-qrcode:before{content:"\f029"}.fa-question:before{content:"\f128"}.fa-question-circle:before{content:"\f059"}.fa-quidditch:before{content:"\f458"}.fa-quinscape:before{content:"\f459"}.fa-quora:before{content:"\f2c4"}.fa-quote-left:before{content:"\f10d"}.fa-quote-right:before{content:"\f10e"}.fa-quran:before{content:"\f687"}.fa-r-project:before{content:"\f4f7"}.fa-radiation:before{content:"\f7b9"}.fa-radiation-alt:before{content:"\f7ba"}.fa-rainbow:before{content:"\f75b"}.fa-random:before{content:"\f074"}.fa-raspberry-pi:before{content:"\f7bb"}.fa-ravelry:before{content:"\f2d9"}.fa-react:before{content:"\f41b"}.fa-reacteurope:before{content:"\f75d"}.fa-readme:before{content:"\f4d5"}.fa-rebel:before{content:"\f1d0"}.fa-receipt:before{content:"\f543"}.fa-recycle:before{content:"\f1b8"}.fa-red-river:before{content:"\f3e3"}.fa-reddit:before{content:"\f1a1"}.fa-reddit-alien:before{content:"\f281"}.fa-reddit-square:before{content:"\f1a2"}.fa-redhat:before{content:"\f7bc"}.fa-redo:before{content:"\f01e"}.fa-redo-alt:before{content:"\f2f9"}.fa-registered:before{content:"\f25d"}.fa-remove-format:before{content:"\f87d"}.fa-renren:before{content:"\f18b"}.fa-reply:before{content:"\f3e5"}.fa-reply-all:before{content:"\f122"}.fa-replyd:before{content:"\f3e6"}.fa-republican:before{content:"\f75e"}.fa-researchgate:before{content:"\f4f8"}.fa-resolving:before{content:"\f3e7"}.fa-restroom:before{content:"\f7bd"}.fa-retweet:before{content:"\f079"}.fa-rev:before{content:"\f5b2"}.fa-ribbon:before{content:"\f4d6"}.fa-ring:before{content:"\f70b"}.fa-road:before{content:"\f018"}.fa-robot:before{content:"\f544"}.fa-rocket:before{content:"\f135"}.fa-rocketchat:before{content:"\f3e8"}.fa-rockrms:before{content:"\f3e9"}.fa-route:before{content:"\f4d7"}.fa-rss:before{content:"\f09e"}.fa-rss-square:before{content:"\f143"}.fa-ruble-sign:before{content:"\f158"}.fa-ruler:before{content:"\f545"}.fa-ruler-combined:before{content:"\f546"}.fa-ruler-horizontal:before{content:"\f547"}.fa-ruler-vertical:before{content:"\f548"}.fa-running:before{content:"\f70c"}.fa-rupee-sign:before{content:"\f156"}.fa-sad-cry:before{content:"\f5b3"}.fa-sad-tear:before{content:"\f5b4"}.fa-safari:before{content:"\f267"}.fa-salesforce:before{content:"\f83b"}.fa-sass:before{content:"\f41e"}.fa-satellite:before{content:"\f7bf"}.fa-satellite-dish:before{content:"\f7c0"}.fa-save:before{content:"\f0c7"}.fa-schlix:before{content:"\f3ea"}.fa-school:before{content:"\f549"}.fa-screwdriver:before{content:"\f54a"}.fa-scribd:before{content:"\f28a"}.fa-scroll:before{content:"\f70e"}.fa-sd-card:before{content:"\f7c2"}.fa-search:before{content:"\f002"}.fa-search-dollar:before{content:"\f688"}.fa-search-location:before{content:"\f689"}.fa-search-minus:before{content:"\f010"}.fa-search-plus:before{content:"\f00e"}.fa-searchengin:before{content:"\f3eb"}.fa-seedling:before{content:"\f4d8"}.fa-sellcast:before{content:"\f2da"}.fa-sellsy:before{content:"\f213"}.fa-server:before{content:"\f233"}.fa-servicestack:before{content:"\f3ec"}.fa-shapes:before{content:"\f61f"}.fa-share:before{content:"\f064"}.fa-share-alt:before{content:"\f1e0"}.fa-share-alt-square:before{content:"\f1e1"}.fa-share-square:before{content:"\f14d"}.fa-shekel-sign:before{content:"\f20b"}.fa-shield-alt:before{content:"\f3ed"}.fa-ship:before{content:"\f21a"}.fa-shipping-fast:before{content:"\f48b"}.fa-shirtsinbulk:before{content:"\f214"}.fa-shoe-prints:before{content:"\f54b"}.fa-shopping-bag:before{content:"\f290"}.fa-shopping-basket:before{content:"\f291"}.fa-shopping-cart:before{content:"\f07a"}.fa-shopware:before{content:"\f5b5"}.fa-shower:before{content:"\f2cc"}.fa-shuttle-van:before{content:"\f5b6"}.fa-sign:before{content:"\f4d9"}.fa-sign-in-alt:before{content:"\f2f6"}.fa-sign-language:before{content:"\f2a7"}.fa-sign-out-alt:before{content:"\f2f5"}.fa-signal:before{content:"\f012"}.fa-signature:before{content:"\f5b7"}.fa-sim-card:before{content:"\f7c4"}.fa-simplybuilt:before{content:"\f215"}.fa-sistrix:before{content:"\f3ee"}.fa-sitemap:before{content:"\f0e8"}.fa-sith:before{content:"\f512"}.fa-skating:before{content:"\f7c5"}.fa-sketch:before{content:"\f7c6"}.fa-skiing:before{content:"\f7c9"}.fa-skiing-nordic:before{content:"\f7ca"}.fa-skull:before{content:"\f54c"}.fa-skull-crossbones:before{content:"\f714"}.fa-skyatlas:before{content:"\f216"}.fa-skype:before{content:"\f17e"}.fa-slack:before{content:"\f198"}.fa-slack-hash:before{content:"\f3ef"}.fa-slash:before{content:"\f715"}.fa-sleigh:before{content:"\f7cc"}.fa-sliders-h:before{content:"\f1de"}.fa-slideshare:before{content:"\f1e7"}.fa-smile:before{content:"\f118"}.fa-smile-beam:before{content:"\f5b8"}.fa-smile-wink:before{content:"\f4da"}.fa-smog:before{content:"\f75f"}.fa-smoking:before{content:"\f48d"}.fa-smoking-ban:before{content:"\f54d"}.fa-sms:before{content:"\f7cd"}.fa-snapchat:before{content:"\f2ab"}.fa-snapchat-ghost:before{content:"\f2ac"}.fa-snapchat-square:before{content:"\f2ad"}.fa-snowboarding:before{content:"\f7ce"}.fa-snowflake:before{content:"\f2dc"}.fa-snowman:before{content:"\f7d0"}.fa-snowplow:before{content:"\f7d2"}.fa-socks:before{content:"\f696"}.fa-solar-panel:before{content:"\f5ba"}.fa-sort:before{content:"\f0dc"}.fa-sort-alpha-down:before{content:"\f15d"}.fa-sort-alpha-down-alt:before{content:"\f881"}.fa-sort-alpha-up:before{content:"\f15e"}.fa-sort-alpha-up-alt:before{content:"\f882"}.fa-sort-amount-down:before{content:"\f160"}.fa-sort-amount-down-alt:before{content:"\f884"}.fa-sort-amount-up:before{content:"\f161"}.fa-sort-amount-up-alt:before{content:"\f885"}.fa-sort-down:before{content:"\f0dd"}.fa-sort-numeric-down:before{content:"\f162"}.fa-sort-numeric-down-alt:before{content:"\f886"}.fa-sort-numeric-up:before{content:"\f163"}.fa-sort-numeric-up-alt:before{content:"\f887"}.fa-sort-up:before{content:"\f0de"}.fa-soundcloud:before{content:"\f1be"}.fa-sourcetree:before{content:"\f7d3"}.fa-spa:before{content:"\f5bb"}.fa-space-shuttle:before{content:"\f197"}.fa-speakap:before{content:"\f3f3"}.fa-speaker-deck:before{content:"\f83c"}.fa-spell-check:before{content:"\f891"}.fa-spider:before{content:"\f717"}.fa-spinner:before{content:"\f110"}.fa-splotch:before{content:"\f5bc"}.fa-spotify:before{content:"\f1bc"}.fa-spray-can:before{content:"\f5bd"}.fa-square:before{content:"\f0c8"}.fa-square-full:before{content:"\f45c"}.fa-square-root-alt:before{content:"\f698"}.fa-squarespace:before{content:"\f5be"}.fa-stack-exchange:before{content:"\f18d"}.fa-stack-overflow:before{content:"\f16c"}.fa-stackpath:before{content:"\f842"}.fa-stamp:before{content:"\f5bf"}.fa-star:before{content:"\f005"}.fa-star-and-crescent:before{content:"\f699"}.fa-star-half:before{content:"\f089"}.fa-star-half-alt:before{content:"\f5c0"}.fa-star-of-david:before{content:"\f69a"}.fa-star-of-life:before{content:"\f621"}.fa-staylinked:before{content:"\f3f5"}.fa-steam:before{content:"\f1b6"}.fa-steam-square:before{content:"\f1b7"}.fa-steam-symbol:before{content:"\f3f6"}.fa-step-backward:before{content:"\f048"}.fa-step-forward:before{content:"\f051"}.fa-stethoscope:before{content:"\f0f1"}.fa-sticker-mule:before{content:"\f3f7"}.fa-sticky-note:before{content:"\f249"}.fa-stop:before{content:"\f04d"}.fa-stop-circle:before{content:"\f28d"}.fa-stopwatch:before{content:"\f2f2"}.fa-store:before{content:"\f54e"}.fa-store-alt:before{content:"\f54f"}.fa-strava:before{content:"\f428"}.fa-stream:before{content:"\f550"}.fa-street-view:before{content:"\f21d"}.fa-strikethrough:before{content:"\f0cc"}.fa-stripe:before{content:"\f429"}.fa-stripe-s:before{content:"\f42a"}.fa-stroopwafel:before{content:"\f551"}.fa-studiovinari:before{content:"\f3f8"}.fa-stumbleupon:before{content:"\f1a4"}.fa-stumbleupon-circle:before{content:"\f1a3"}.fa-subscript:before{content:"\f12c"}.fa-subway:before{content:"\f239"}.fa-suitcase:before{content:"\f0f2"}.fa-suitcase-rolling:before{content:"\f5c1"}.fa-sun:before{content:"\f185"}.fa-superpowers:before{content:"\f2dd"}.fa-superscript:before{content:"\f12b"}.fa-supple:before{content:"\f3f9"}.fa-surprise:before{content:"\f5c2"}.fa-suse:before{content:"\f7d6"}.fa-swatchbook:before{content:"\f5c3"}.fa-swimmer:before{content:"\f5c4"}.fa-swimming-pool:before{content:"\f5c5"}.fa-symfony:before{content:"\f83d"}.fa-synagogue:before{content:"\f69b"}.fa-sync:before{content:"\f021"}.fa-sync-alt:before{content:"\f2f1"}.fa-syringe:before{content:"\f48e"}.fa-table:before{content:"\f0ce"}.fa-table-tennis:before{content:"\f45d"}.fa-tablet:before{content:"\f10a"}.fa-tablet-alt:before{content:"\f3fa"}.fa-tablets:before{content:"\f490"}.fa-tachometer-alt:before{content:"\f3fd"}.fa-tag:before{content:"\f02b"}.fa-tags:before{content:"\f02c"}.fa-tape:before{content:"\f4db"}.fa-tasks:before{content:"\f0ae"}.fa-taxi:before{content:"\f1ba"}.fa-teamspeak:before{content:"\f4f9"}.fa-teeth:before{content:"\f62e"}.fa-teeth-open:before{content:"\f62f"}.fa-telegram:before{content:"\f2c6"}.fa-telegram-plane:before{content:"\f3fe"}.fa-temperature-high:before{content:"\f769"}.fa-temperature-low:before{content:"\f76b"}.fa-tencent-weibo:before{content:"\f1d5"}.fa-tenge:before{content:"\f7d7"}.fa-terminal:before{content:"\f120"}.fa-text-height:before{content:"\f034"}.fa-text-width:before{content:"\f035"}.fa-th:before{content:"\f00a"}.fa-th-large:before{content:"\f009"}.fa-th-list:before{content:"\f00b"}.fa-the-red-yeti:before{content:"\f69d"}.fa-theater-masks:before{content:"\f630"}.fa-themeco:before{content:"\f5c6"}.fa-themeisle:before{content:"\f2b2"}.fa-thermometer:before{content:"\f491"}.fa-thermometer-empty:before{content:"\f2cb"}.fa-thermometer-full:before{content:"\f2c7"}.fa-thermometer-half:before{content:"\f2c9"}.fa-thermometer-quarter:before{content:"\f2ca"}.fa-thermometer-three-quarters:before{content:"\f2c8"}.fa-think-peaks:before{content:"\f731"}.fa-thumbs-down:before{content:"\f165"}.fa-thumbs-up:before{content:"\f164"}.fa-thumbtack:before{content:"\f08d"}.fa-ticket-alt:before{content:"\f3ff"}.fa-times:before{content:"\f00d"}.fa-times-circle:before{content:"\f057"}.fa-tint:before{content:"\f043"}.fa-tint-slash:before{content:"\f5c7"}.fa-tired:before{content:"\f5c8"}.fa-toggle-off:before{content:"\f204"}.fa-toggle-on:before{content:"\f205"}.fa-toilet:before{content:"\f7d8"}.fa-toilet-paper:before{content:"\f71e"}.fa-toolbox:before{content:"\f552"}.fa-tools:before{content:"\f7d9"}.fa-tooth:before{content:"\f5c9"}.fa-torah:before{content:"\f6a0"}.fa-torii-gate:before{content:"\f6a1"}.fa-tractor:before{content:"\f722"}.fa-trade-federation:before{content:"\f513"}.fa-trademark:before{content:"\f25c"}.fa-traffic-light:before{content:"\f637"}.fa-train:before{content:"\f238"}.fa-tram:before{content:"\f7da"}.fa-transgender:before{content:"\f224"}.fa-transgender-alt:before{content:"\f225"}.fa-trash:before{content:"\f1f8"}.fa-trash-alt:before{content:"\f2ed"}.fa-trash-restore:before{content:"\f829"}.fa-trash-restore-alt:before{content:"\f82a"}.fa-tree:before{content:"\f1bb"}.fa-trello:before{content:"\f181"}.fa-tripadvisor:before{content:"\f262"}.fa-trophy:before{content:"\f091"}.fa-truck:before{content:"\f0d1"}.fa-truck-loading:before{content:"\f4de"}.fa-truck-monster:before{content:"\f63b"}.fa-truck-moving:before{content:"\f4df"}.fa-truck-pickup:before{content:"\f63c"}.fa-tshirt:before{content:"\f553"}.fa-tty:before{content:"\f1e4"}.fa-tumblr:before{content:"\f173"}.fa-tumblr-square:before{content:"\f174"}.fa-tv:before{content:"\f26c"}.fa-twitch:before{content:"\f1e8"}.fa-twitter:before{content:"\f099"}.fa-twitter-square:before{content:"\f081"}.fa-typo3:before{content:"\f42b"}.fa-uber:before{content:"\f402"}.fa-ubuntu:before{content:"\f7df"}.fa-uikit:before{content:"\f403"}.fa-umbrella:before{content:"\f0e9"}.fa-umbrella-beach:before{content:"\f5ca"}.fa-underline:before{content:"\f0cd"}.fa-undo:before{content:"\f0e2"}.fa-undo-alt:before{content:"\f2ea"}.fa-uniregistry:before{content:"\f404"}.fa-universal-access:before{content:"\f29a"}.fa-university:before{content:"\f19c"}.fa-unlink:before{content:"\f127"}.fa-unlock:before{content:"\f09c"}.fa-unlock-alt:before{content:"\f13e"}.fa-untappd:before{content:"\f405"}.fa-upload:before{content:"\f093"}.fa-ups:before{content:"\f7e0"}.fa-usb:before{content:"\f287"}.fa-user:before{content:"\f007"}.fa-user-alt:before{content:"\f406"}.fa-user-alt-slash:before{content:"\f4fa"}.fa-user-astronaut:before{content:"\f4fb"}.fa-user-check:before{content:"\f4fc"}.fa-user-circle:before{content:"\f2bd"}.fa-user-clock:before{content:"\f4fd"}.fa-user-cog:before{content:"\f4fe"}.fa-user-edit:before{content:"\f4ff"}.fa-user-friends:before{content:"\f500"}.fa-user-graduate:before{content:"\f501"}.fa-user-injured:before{content:"\f728"}.fa-user-lock:before{content:"\f502"}.fa-user-md:before{content:"\f0f0"}.fa-user-minus:before{content:"\f503"}.fa-user-ninja:before{content:"\f504"}.fa-user-nurse:before{content:"\f82f"}.fa-user-plus:before{content:"\f234"}.fa-user-secret:before{content:"\f21b"}.fa-user-shield:before{content:"\f505"}.fa-user-slash:before{content:"\f506"}.fa-user-tag:before{content:"\f507"}.fa-user-tie:before{content:"\f508"}.fa-user-times:before{content:"\f235"}.fa-users:before{content:"\f0c0"}.fa-users-cog:before{content:"\f509"}.fa-usps:before{content:"\f7e1"}.fa-ussunnah:before{content:"\f407"}.fa-utensil-spoon:before{content:"\f2e5"}.fa-utensils:before{content:"\f2e7"}.fa-vaadin:before{content:"\f408"}.fa-vector-square:before{content:"\f5cb"}.fa-venus:before{content:"\f221"}.fa-venus-double:before{content:"\f226"}.fa-venus-mars:before{content:"\f228"}.fa-viacoin:before{content:"\f237"}.fa-viadeo:before{content:"\f2a9"}.fa-viadeo-square:before{content:"\f2aa"}.fa-vial:before{content:"\f492"}.fa-vials:before{content:"\f493"}.fa-viber:before{content:"\f409"}.fa-video:before{content:"\f03d"}.fa-video-slash:before{content:"\f4e2"}.fa-vihara:before{content:"\f6a7"}.fa-vimeo:before{content:"\f40a"}.fa-vimeo-square:before{content:"\f194"}.fa-vimeo-v:before{content:"\f27d"}.fa-vine:before{content:"\f1ca"}.fa-vk:before{content:"\f189"}.fa-vnv:before{content:"\f40b"}.fa-voicemail:before{content:"\f897"}.fa-volleyball-ball:before{content:"\f45f"}.fa-volume-down:before{content:"\f027"}.fa-volume-mute:before{content:"\f6a9"}.fa-volume-off:before{content:"\f026"}.fa-volume-up:before{content:"\f028"}.fa-vote-yea:before{content:"\f772"}.fa-vr-cardboard:before{content:"\f729"}.fa-vuejs:before{content:"\f41f"}.fa-walking:before{content:"\f554"}.fa-wallet:before{content:"\f555"}.fa-warehouse:before{content:"\f494"}.fa-water:before{content:"\f773"}.fa-wave-square:before{content:"\f83e"}.fa-waze:before{content:"\f83f"}.fa-weebly:before{content:"\f5cc"}.fa-weibo:before{content:"\f18a"}.fa-weight:before{content:"\f496"}.fa-weight-hanging:before{content:"\f5cd"}.fa-weixin:before{content:"\f1d7"}.fa-whatsapp:before{content:"\f232"}.fa-whatsapp-square:before{content:"\f40c"}.fa-wheelchair:before{content:"\f193"}.fa-whmcs:before{content:"\f40d"}.fa-wifi:before{content:"\f1eb"}.fa-wikipedia-w:before{content:"\f266"}.fa-wind:before{content:"\f72e"}.fa-window-close:before{content:"\f410"}.fa-window-maximize:before{content:"\f2d0"}.fa-window-minimize:before{content:"\f2d1"}.fa-window-restore:before{content:"\f2d2"}.fa-windows:before{content:"\f17a"}.fa-wine-bottle:before{content:"\f72f"}.fa-wine-glass:before{content:"\f4e3"}.fa-wine-glass-alt:before{content:"\f5ce"}.fa-wix:before{content:"\f5cf"}.fa-wizards-of-the-coast:before{content:"\f730"}.fa-wolf-pack-battalion:before{content:"\f514"}.fa-won-sign:before{content:"\f159"}.fa-wordpress:before{content:"\f19a"}.fa-wordpress-simple:before{content:"\f411"}.fa-wpbeginner:before{content:"\f297"}.fa-wpexplorer:before{content:"\f2de"}.fa-wpforms:before{content:"\f298"}.fa-wpressr:before{content:"\f3e4"}.fa-wrench:before{content:"\f0ad"}.fa-x-ray:before{content:"\f497"}.fa-xbox:before{content:"\f412"}.fa-xing:before{content:"\f168"}.fa-xing-square:before{content:"\f169"}.fa-y-combinator:before{content:"\f23b"}.fa-yahoo:before{content:"\f19e"}.fa-yammer:before{content:"\f840"}.fa-yandex:before{content:"\f413"}.fa-yandex-international:before{content:"\f414"}.fa-yarn:before{content:"\f7e3"}.fa-yelp:before{content:"\f1e9"}.fa-yen-sign:before{content:"\f157"}.fa-yin-yang:before{content:"\f6ad"}.fa-yoast:before{content:"\f2b1"}.fa-youtube:before{content:"\f167"}.fa-youtube-square:before{content:"\f431"}.fa-zhihu:before{content:"\f63f"}.sr-only{border:0;clip:rect(0,0,0,0);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;width:1px}.sr-only-focusable:active,.sr-only-focusable:focus{clip:auto;height:auto;margin:0;overflow:visible;position:static;width:auto}
\ No newline at end of file diff --git a/lib/lvgl/docs/_static/img/home_1.png b/lib/lvgl/docs/_static/img/home_1.png Binary files differnew file mode 100644 index 00000000..608acfe0 --- /dev/null +++ b/lib/lvgl/docs/_static/img/home_1.png diff --git a/lib/lvgl/docs/_static/img/home_2.png b/lib/lvgl/docs/_static/img/home_2.png Binary files differnew file mode 100644 index 00000000..d61ee512 --- /dev/null +++ b/lib/lvgl/docs/_static/img/home_2.png diff --git a/lib/lvgl/docs/_static/img/home_3.png b/lib/lvgl/docs/_static/img/home_3.png Binary files differnew file mode 100644 index 00000000..da0c2b88 --- /dev/null +++ b/lib/lvgl/docs/_static/img/home_3.png diff --git a/lib/lvgl/docs/_static/img/home_4.png b/lib/lvgl/docs/_static/img/home_4.png Binary files differnew file mode 100644 index 00000000..b059da7e --- /dev/null +++ b/lib/lvgl/docs/_static/img/home_4.png diff --git a/lib/lvgl/docs/_static/img/home_5.png b/lib/lvgl/docs/_static/img/home_5.png Binary files differnew file mode 100644 index 00000000..1d002ea1 --- /dev/null +++ b/lib/lvgl/docs/_static/img/home_5.png diff --git a/lib/lvgl/docs/_static/img/home_6.png b/lib/lvgl/docs/_static/img/home_6.png Binary files differnew file mode 100644 index 00000000..c95b466b --- /dev/null +++ b/lib/lvgl/docs/_static/img/home_6.png diff --git a/lib/lvgl/docs/_static/img/home_banner.jpg b/lib/lvgl/docs/_static/img/home_banner.jpg Binary files differnew file mode 100644 index 00000000..099cd901 --- /dev/null +++ b/lib/lvgl/docs/_static/img/home_banner.jpg diff --git a/lib/lvgl/docs/_static/js/custom.js b/lib/lvgl/docs/_static/js/custom.js new file mode 100644 index 00000000..d16e00b0 --- /dev/null +++ b/lib/lvgl/docs/_static/js/custom.js @@ -0,0 +1,18 @@ +/* API collapsing */ +document.addEventListener('DOMContentLoaded', (event) => { + document.querySelectorAll("dl.cpp").forEach(cppListing => { + const dt = cppListing.querySelector("dt"); + let shouldBeExpanded = false; + if(dt.id == document.location.hash.substring(1)) + shouldBeExpanded = true; + cppListing.classList.add(shouldBeExpanded ? "expanded" : "unexpanded"); + const button = document.createElement("span"); + button.classList.add("lv-api-expansion-button"); + button.addEventListener("click", () => { + cppListing.classList.toggle("unexpanded"); + cppListing.classList.toggle("expanded"); + }); + + dt.insertBefore(button, dt.firstChild); + }); +})
\ No newline at end of file diff --git a/lib/lvgl/docs/_templates/layout.html b/lib/lvgl/docs/_templates/layout.html new file mode 100644 index 00000000..d3c25f08 --- /dev/null +++ b/lib/lvgl/docs/_templates/layout.html @@ -0,0 +1,31 @@ +{% extends "!layout.html" %} + +{%- block extrahead %} +{{ super() }} +<!-- Global site tag (gtag.js) - Google Analytics --> +<script async src="https://www.googletagmanager.com/gtag/js?id=UA-78811084-3"></script> +<script> + window.dataLayer = window.dataLayer || []; + function gtag(){dataLayer.push(arguments);} + gtag('js', new Date()); + + gtag('config', 'UA-78811084-3', { 'anonymize_ip': true }); +</script> +{% endblock %} + +{% block footer %} +{{ super() }} +<div class="footer">This page uses <a href="https://analytics.google.com/"> +Google Analytics</a> to collect statistics. You can disable it by blocking +the JavaScript coming from www.google-analytics.com. +<script type="text/javascript"> + (function() { + var ga = document.createElement('script'); + ga.src = ('https:' == document.location.protocol ? + 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; + ga.setAttribute('async', 'true'); + document.documentElement.firstChild.appendChild(ga); + })(); +</script> +</div> +{% endblock %} diff --git a/lib/lvgl/docs/_templates/page.html b/lib/lvgl/docs/_templates/page.html new file mode 100644 index 00000000..90320b14 --- /dev/null +++ b/lib/lvgl/docs/_templates/page.html @@ -0,0 +1,82 @@ +{% extends "!page.html" %} + +{% block footer %} + +<style> + .wy-side-nav-search > div[role="search"] { + color: black; + } +</style> + <script type="text/javascript"> + $(document).ready(function() { + $(".toggle > *").hide(); + $(".toggle .header").show(); + $(".toggle .header").click(function() { + $(this).parent().children().not(".header").toggle(400); + $(this).parent().children(".header").toggleClass("open"); + }) + }); +</script> + +<script type="text/javascript"> +function add_version_selector() +{ + return fetch("https://raw.githubusercontent.com/lvgl/docs_compiled/gh-pages/versionlist.txt") + .then(res => res.text()) + .then(text => { + const versions = text.split("\n").filter(version => version.trim().length > 0); + let p = document.getElementById("rtd-search-form").parentElement; + p.innerHTML = ` + <select name="versions" id="versions" onchange="ver_sel()" style="border-radius:5px; margin-bottom:15px"> + ${versions.map(version => { + let versionName = ""; + if(version == "master") versionName = "master (latest)"; + else versionName = "v" + ((version.indexOf(".") != -1) ? version : (version + " (latest minor)")); + return `<option value="${version}">${versionName}</option>`; + })} + </select>` + p.innerHTML; + }); +} + +function ver_sel() +{ + var x = document.getElementById("versions").value; + window.location.href = window.location.protocol + "//" + window.location.host + "/" + x + "/"; +} + +document.addEventListener('DOMContentLoaded', (event) => { + add_version_selector().then(() => { + var value = window.location.pathname.split('/')[1]; + document.getElementById("versions").value = value; + }); + +}) +document.addEventListener('DOMContentLoaded', (event) => { + function onIntersection(entries) { + entries.forEach(entry => { + let currentlyLoaded = entry.target.getAttribute("data-is-loaded") == "true"; + let shouldBeLoaded = entry.intersectionRatio > 0; + if(currentlyLoaded != shouldBeLoaded) { + entry.target.setAttribute("data-is-loaded", shouldBeLoaded); + if(shouldBeLoaded) { + let iframe = document.createElement("iframe"); + iframe.src = entry.target.getAttribute("data-real-src"); + entry.target.appendChild(iframe); + } else { + let iframe = entry.target.querySelector("iframe"); + iframe.parentNode.removeChild(iframe); + } + } + }); + } + const config = { + rootMargin: '600px 0px', + threshold: 0.01 + }; + let observer = new IntersectionObserver(onIntersection, config); + document.querySelectorAll(".lv-example").forEach(iframe => { + observer.observe(iframe); + }); +}); +</script> +{% endblock %} diff --git a/lib/lvgl/docs/build.py b/lib/lvgl/docs/build.py new file mode 100755 index 00000000..7a1f7979 --- /dev/null +++ b/lib/lvgl/docs/build.py @@ -0,0 +1,74 @@ +#!/usr/bin/env python3 + +import sys +import os +import subprocess +import re +import example_list as ex + +langs = ['en'] + +# Change to script directory for consistency +abspath = os.path.abspath(__file__) +dname = os.path.dirname(abspath) +os.chdir(dname) + +def cmd(s): + print("") + print(s) + print("-------------------------------------") + r = os.system(s) + if r != 0: + print("Exit build due to previous error") + exit(-1) + +# Get the current branch name +status, br = subprocess.getstatusoutput("git branch | grep '*'") +_, gitcommit = subprocess.getstatusoutput("git rev-parse HEAD") +br = re.sub('\* ', '', br) + +# Generate the list of examples +ex.exec() + +urlpath = re.sub('release/', '', br) + +os.environ['LVGL_URLPATH'] = urlpath +os.environ['LVGL_GITCOMMIT'] = gitcommit + +clean = 0 +trans = 0 +skip_latex = False +args = sys.argv[1:] +if len(args) >= 1: + if "clean" in args: clean = 1 + if "skip_latex" in args: skip_latex = True + +lang = "en" +print("") +print("****************") +print("Building") +print("****************") +if clean: + cmd("rm -rf " + lang) + cmd("mkdir " + lang) + + +print("Running doxygen") +cmd("cd ../scripts && doxygen Doxyfile") +# BUILD PDF + +if not skip_latex: + # Silly workaround to include the more or less correct PDF download link in the PDF + #cmd("cp -f " + lang +"/latex/LVGL.pdf LVGL.pdf | true") + cmd("sphinx-build -b latex . out_latex") + + # Generate PDF + cmd("cd out_latex && latexmk -pdf 'LVGL.tex'") + # Copy the result PDF to the main directory to make it available for the HTML build + cmd("cd out_latex && cp -f LVGL.pdf ../LVGL.pdf") +else: + print("skipping latex build as requested") + +# BUILD HTML +cmd("sphinx-build -b html . ../out_html") + diff --git a/lib/lvgl/docs/conf.py b/lib/lvgl/docs/conf.py new file mode 100644 index 00000000..75d5ae3e --- /dev/null +++ b/lib/lvgl/docs/conf.py @@ -0,0 +1,259 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# LVGL documentation build configuration file, created by +# sphinx-quickstart on Wed Jun 12 16:38:40 2019. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import subprocess +import sys + +sys.path.insert(0, os.path.abspath('./_ext')) + +from subprocess import PIPE, Popen + +import recommonmark +from recommonmark.transform import AutoStructify +from sphinx.builders.html import StandaloneHTMLBuilder + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'recommonmark', + 'sphinx_markdown_tables', + 'breathe', + 'sphinx_sitemap', + 'lv_example' + ] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The default language to highlight source code in. The default is 'python'. +# The value should be a valid Pygments lexer name, see Showing code examples for more details. + + +highlight_language = 'c' + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +source_suffix = ['.rst', '.md'] + + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'LVGL' +copyright = '2021, LVGL Kft' +author = 'LVGL community' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +# embeddedt: extract using scripts/find_version.sh + +version = subprocess.run(["../scripts/find_version.sh"], capture_output=True).stdout.decode("utf-8").strip() + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'doxygen_html', 'Thumbs.db', '.DS_Store', + 'README.md', 'lv_examples', 'out_html', 'env' ] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +html_theme_options = { + 'collapse_navigation' : False, + 'logo_only': True, +} +# For site map generation +html_baseurl = f"https://docs.lvgl.io/{os.environ['LVGL_URLPATH']}/en/html/" + +sitemap_url_scheme = "{link}" + +#lvgl_github_url = f"https://github.com/lvgl/lvgl/blob/{os.environ['LVGL_GITCOMMIT']}/docs" + +#extlinks = {'github_link_base': (github_url + '%s', github_url)} + +html_context = { + 'github_version': os.environ['LVGL_GITCOMMIT'], + 'github_user': 'lvgl', + 'github_repo': 'lvgl', + 'display_github': True, + 'conf_py_path': '/docs/' +} + + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +html_sidebars = { + '**': [ + 'relations.html', # needs 'show_related': True theme option to display + 'searchbox.html', + ] +} + +html_js_files = [ + 'js/custom.js' +] + +html_favicon = 'favicon.png' +html_logo = 'logo_lvgl.png' + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'LVGLdoc' + +html_last_updated_fmt = '' + +# -- Options for LaTeX output --------------------------------------------- + +latex_engine = 'xelatex' +latex_use_xindy = False +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', + + 'inputenc': '', + 'utf8extra': '', + 'classoptions': ',openany,oneside', + 'babel': '\\usepackage{babel}', + 'passoptionstopackages': r''' +\PassOptionsToPackage{bookmarksdepth=5}{hyperref}% depth of pdf bookmarks +''', + 'preamble': r''' +\usepackage{fontspec} +\setmonofont{DejaVu Sans Mono} +\usepackage{silence} +\WarningsOff* +''', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'LVGL.tex', 'LVGL Documentation ' + version, + 'LVGL community', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'lvgl', 'LVGL Documentation ' + version, + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'LVGL', 'LVGL Documentation ' + version, + author, 'Contributors of LVGL', 'One line description of project.', + 'Miscellaneous'), +] + + +breathe_projects = { + "lvgl":"xml/", +} + +StandaloneHTMLBuilder.supported_image_types = [ + 'image/svg+xml', + 'image/gif', #prefer gif over png + 'image/png', + 'image/jpeg' +] + +smartquotes = False + +_, repo_commit_hash = subprocess.getstatusoutput("git rev-parse HEAD") + + +# Example configuration for intersphinx: refer to the Python standard library. + +def setup(app): + app.add_config_value('recommonmark_config', { + 'enable_eval_rst': True, + 'enable_auto_toc_tree': 'True', + }, True) + app.add_transform(AutoStructify) + app.add_css_file('css/custom.css') + app.add_css_file('css/fontawesome.min.css') diff --git a/lib/lvgl/docs/example_list.py b/lib/lvgl/docs/example_list.py new file mode 100755 index 00000000..c65554e3 --- /dev/null +++ b/lib/lvgl/docs/example_list.py @@ -0,0 +1,125 @@ +#!/usr/bin/env python3 +import os + + +def process_index_rst(path): +# print(path) + with open(path) as fp: + last_line="" + line="" + title_tmp="" + line = fp.readline() + d = {} + while line: + if line[0:3] == '"""': + title_tmp = last_line + elif line[0:15] ==".. lv_example::": + name = line[16:].strip() + title_tmp = title_tmp.strip() + d[name] = title_tmp + last_line = line + line = fp.readline() + + return(d) + +h1= { + "get_started":"Get started", + "styles":"Styles", + "anim":"Animations", + "event":"Events", + "layouts":"Layouts", + "scroll":"Scrolling", + "widgets":"Widgets" +} + +widgets = { +"obj":"Base object", +"arc":"Arc", +"bar":"Bar", +"btn":"Button", +"btnmatrix":"Button matrix", +"calendar":"Calendar", +"canvas":"Canvas", +"chart":"Chart", +"checkbox":"Checkbox", +"colorwheel":"Colorwheel", +"dropdown":"Dropdown", +"img":"Image", +"imgbtn":"Image button", +"keyboard":"Keyboard", +"label":"Label", +"led":"LED", +"line":"Line", +"list":"List", +"menu":"Menu", +"meter":"Meter", +"msgbox":"Message box", +"roller":"Roller", +"slider":"Slider", +"span":"Span", +"spinbox":"Spinbox", +"spinner":"Spinner", +"switch":"Switch", +"table":"Table", +"tabview":"Tabview", +"textarea":"Textarea", +"tileview":"Tabview", +"win":"Window", +} + +layouts = { +"flex":"Flex", +"grid":"Grid", +} + + +def print_item(path, lvl, d, fout): + for k in d: + v = d[k] + if k.startswith(path + "/lv_example_"): + fout.write("#"*lvl + " " + v + "\n") + fout.write('```eval_rst\n') + fout.write(f".. lv_example:: {k}\n") + fout.write('```\n') + fout.write("\n") + +def exec(): + paths = [ "../examples/", "../demos/"] + fout = open("examples.md", "w") + filelist = [] + + for path in paths: + for root, dirs, files in os.walk(path): + for f in files: + #append the file name to the list + filelist.append(os.path.join(root,f)) + + filelist = [ fi for fi in filelist if fi.endswith("index.rst") ] + + d_all = {} + #print all the file names + for fn in filelist: + d_act = process_index_rst(fn) + d_all.update(d_act) + + fout.write("```eval_rst\n") + fout.write(":github_url: |github_link_base|/examples.md\n") + fout.write("```\n") + fout.write("\n") + fout.write("# Examples\n") + + for h in h1: + fout.write("## " + h1[h] + "\n") + + if h == "widgets": + for w in widgets: + fout.write("### " + widgets[w] + "\n") + print_item(h + "/" + w, 4, d_all, fout) + elif h == "layouts": + for l in layouts: + fout.write("### " + layouts[l] + "\n") + print_item(h + "/" + l, 4, d_all, fout) + else: + print_item(h, 3, d_all, fout) + + fout.write("") diff --git a/lib/lvgl/docs/favicon.png b/lib/lvgl/docs/favicon.png Binary files differnew file mode 100644 index 00000000..9f65ea56 --- /dev/null +++ b/lib/lvgl/docs/favicon.png diff --git a/lib/lvgl/docs/get-started/bindings/cpp.md b/lib/lvgl/docs/get-started/bindings/cpp.md new file mode 100644 index 00000000..12601659 --- /dev/null +++ b/lib/lvgl/docs/get-started/bindings/cpp.md @@ -0,0 +1,4 @@ +# Cpp + +In progress: https://github.com/lvgl/lv_binding_cpp + diff --git a/lib/lvgl/docs/get-started/bindings/index.md b/lib/lvgl/docs/get-started/bindings/index.md new file mode 100644 index 00000000..32636caf --- /dev/null +++ b/lib/lvgl/docs/get-started/bindings/index.md @@ -0,0 +1,12 @@ +# Bindings + + +```eval_rst + +.. toctree:: + :maxdepth: 2 + + micropython + cpp +``` + diff --git a/lib/lvgl/docs/get-started/bindings/micropython.md b/lib/lvgl/docs/get-started/bindings/micropython.md new file mode 100644 index 00000000..613e7195 --- /dev/null +++ b/lib/lvgl/docs/get-started/bindings/micropython.md @@ -0,0 +1,92 @@ +# Micropython + +## What is Micropython? + +[Micropython](http://micropython.org/) is Python for microcontrollers. +Using Micropython, you can write Python3 code and run it even on a bare metal architecture with limited resources. + +### Highlights of Micropython + +- **Compact** - Fits and runs within just 256k of code space and 16k of RAM. No OS is needed, although you can also run it with an OS, if you want. +- **Compatible** - Strives to be as compatible as possible with normal Python (known as CPython). +- **Versatile** - Supports many architectures (x86, x86-64, ARM, ARM Thumb, Xtensa). +- **Interactive** - No need for the compile-flash-boot cycle. With the REPL (interactive prompt) you can type commands and execute them immediately, run scripts, etc. +- **Popular** - Many platforms are supported. The user base is growing bigger. Notable forks: [MicroPython](https://github.com/micropython/micropython), [CircuitPython](https://github.com/adafruit/circuitpython), [MicroPython_ESP32_psRAM_LoBo](https://github.com/loboris/MicroPython_ESP32_psRAM_LoBo) +- **Embedded Oriented** - Comes with modules specifically for embedded systems, such as the [machine module](https://docs.micropython.org/en/latest/library/machine.html#classes) for accessing low-level hardware (I/O pins, ADC, UART, SPI, I2C, RTC, Timers etc.) + +--- + +## Why Micropython + LVGL? + +Currently, Micropython [does not have a good high-level GUI library](https://forum.micropython.org/viewtopic.php?f=18&t=5543) by default. LVGL is an [Object-Oriented Component Based](https://blog.lvgl.io/2018-12-13/extend-lvgl-objects) high-level GUI library, which seems to be a natural candidate to map into a higher level language, such as Python. LVGL is implemented in C and its APIs are in C. + +### Here are some advantages of using LVGL in Micropython: + +- Develop GUI in Python, a very popular high level language. Use paradigms such as Object-Oriented Programming. +- Usually, GUI development requires multiple iterations to get things right. With C, each iteration consists of **`Change code` > `Build` > `Flash` > `Run`**. +In Micropython it's just **`Change code` > `Run`** ! You can even run commands interactively using the [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) (the interactive prompt) + +### Micropython + LVGL could be used for: + +- Fast prototyping GUI. +- Shortening the cycle of changing and fine-tuning the GUI. +- Modelling the GUI in a more abstract way by defining reusable composite objects, taking advantage of Python's language features such as Inheritance, Closures, List Comprehension, Generators, Exception Handling, Arbitrary Precision Integers and others. +- Make LVGL accessible to a larger audience. No need to know C to create a nice GUI on an embedded system. +This goes well with [CircuitPython vision](https://learn.adafruit.com/welcome-to-circuitpython/what-is-circuitpython). CircuitPython was designed with education in mind, to make it easier for new or inexperienced users to get started with embedded development. +- Creating tools to work with LVGL at a higher level (e.g. drag-and-drop designer). + +--- + +## So what does it look like? + +> TL;DR: +> It's very much like the C API, but Object-Oriented for LVGL components. + +Let's dive right into an example! + +### A simple example + +```python +import lvgl as lv +lv.init() +scr = lv.obj() +btn = lv.btn(scr) +btn.align(lv.scr_act(), lv.ALIGN.CENTER, 0, 0) +label = lv.label(btn) +label.set_text("Button") +lv.scr_load(scr) +``` + +## How can I use it? + +### Online Simulator + +If you want to experiment with LVGL + Micropython without downloading anything - you can use our online simulator! +It's a fully functional LVGL + Micropython that runs entirely in the browser and allows you to edit a python script and run it. + +[Click here to experiment on the online simulator](https://sim.lvgl.io/) + +[Hello World](https://sim.lvgl.io/v7/micropython/ports/javascript/bundle_out/index.html?script=https://gist.githubusercontent.com/amirgon/51299ce9b6448328a855826149482ae6/raw/0f235c6d40462fd2f0e55364b874f14fe3fd613c/lvgl_hello_world.py&script_startup=https://gist.githubusercontent.com/amirgon/7bf15a66ba6d959bbf90d10f3da571be/raw/8684b5fa55318c184b1310663b187aaab5c65be6/init_lv_mp_js.py) + +Note: the online simulator is available for lvgl v6 and v7. + +### PC Simulator + +Micropython is ported to many platforms. One notable port is "unix", which allows you to build and run Micropython (+LVGL) on a Linux machine. (On a Windows machine you might need Virtual Box or WSL or MinGW or Cygwin etc.) + +[Click here to know more information about building and running the unix port](https://github.com/lvgl/lv_micropython) + +### Embedded platform + +In the end, the goal is to run it all on an embedded platform. +Both Micropython and LVGL can be used on many embedded architectures, such as stm32, ESP32 etc. +You would also need display and input drivers. We have some sample drivers (ESP32+ILI9341, as well as some other examples), but chances are you would want to create your own input/display drivers for your specific hardware. +Drivers can be implemented either in C as a Micropython module, or in pure Micropython! + +## Where can I find more information? + +- In this [Blog Post](https://blog.lvgl.io/2019-02-20/micropython-bindings) +- `lv_micropython` [README](https://github.com/lvgl/lv_micropython) +- `lv_binding_micropython` [README](https://github.com/lvgl/lv_binding_micropython) +- The [LVGL micropython forum](https://forum.lvgl.io/c/micropython) (Feel free to ask anything!) +- At Micropython: [docs](http://docs.micropython.org/en/latest/) and [forum](https://forum.micropython.org/) diff --git a/lib/lvgl/docs/get-started/index.md b/lib/lvgl/docs/get-started/index.md new file mode 100644 index 00000000..5d0c4fb4 --- /dev/null +++ b/lib/lvgl/docs/get-started/index.md @@ -0,0 +1,27 @@ +# Get started + +There are several ways to get your feet wet with LVGL. Here is one recommended order of documents to read and things to play with when you are learning to use LVGL: +1. Check the [Online demos](https://lvgl.io/demos) to see LVGL in action (3 minutes) +2. Read the [Introduction](https://docs.lvgl.io/latest/en/html/intro/index.html) page of the documentation (5 minutes) +3. Read the [Quick overview](https://docs.lvgl.io/master/get-started/quick-overview.html) page of the documentation (15 minutes) +4. Set up a [Simulator](https://docs.lvgl.io/master/get-started/platforms/pc-simulator.html) (10 minutes) +5. Try out some [Examples](https://docs.lvgl.io/master/examples.html) +6. Check out the Platform-specific tutorials. (in this section below). (10 minutes) +7. Port LVGL to a board. See the [Porting](https://docs.lvgl.io/master/porting/index.html) guide or check the ready to use [Projects](https://github.com/lvgl?q=lv_port_&type=&language=) +8. Read the [Overview](https://docs.lvgl.io/master/overview/index.html) page to get a better understanding of the library. (2-3 hours) +9. Check the documentation of the [Widgets](https://docs.lvgl.io/master/widgets/index.html) to see their features and usage +10. If you have questions got to the [Forum](http://forum.lvgl.io/) +11. Read the [Contributing](https://docs.lvgl.io/master/CONTRIBUTING.html) guide to see how you can help to improve LVGL (15 minutes) + + +```eval_rst + +.. toctree:: + :maxdepth: 2 + + quick-overview + platforms/index + os/index + bindings/index +``` + diff --git a/lib/lvgl/docs/get-started/os/freertos.md b/lib/lvgl/docs/get-started/os/freertos.md new file mode 100644 index 00000000..8c50b2ae --- /dev/null +++ b/lib/lvgl/docs/get-started/os/freertos.md @@ -0,0 +1,3 @@ +# FreeRTOS + +TODO
\ No newline at end of file diff --git a/lib/lvgl/docs/get-started/os/index.md b/lib/lvgl/docs/get-started/os/index.md new file mode 100644 index 00000000..30ea6af2 --- /dev/null +++ b/lib/lvgl/docs/get-started/os/index.md @@ -0,0 +1,13 @@ +# (RT)OS + +```eval_rst + +.. toctree:: + :maxdepth: 2 + + nuttx + rt-thread + freertos + zephyr +``` + diff --git a/lib/lvgl/docs/get-started/os/nuttx.md b/lib/lvgl/docs/get-started/os/nuttx.md new file mode 100644 index 00000000..97b95f77 --- /dev/null +++ b/lib/lvgl/docs/get-started/os/nuttx.md @@ -0,0 +1,97 @@ +# NuttX RTOS + +## What is NuttX? + +[NuttX](https://nuttx.apache.org/) is a mature and secure real-time operating system (RTOS) with an emphasis on technical standards compliance and small size. +It is scalable from 8-bit to 64-bit microcontrollers and microprocessors and compliant with the Portable Operating System Interface (POSIX) and the American National Standards Institute (ANSI) standards and with many Linux-like subsystems. +The best way to think about NuttX is to think of it as a small Unix/Linux for microcontrollers. + +### Highlights of NuttX + +- **Small** - Fits and runs in microcontrollers as small as 32 kB Flash and 8 kB of RAM. +- **Compliant** - Strives to be as compatible as possible with POSIX and Linux. +- **Versatile** - Supports many architectures (ARM, ARM Thumb, AVR, MIPS, OpenRISC, RISC-V 32-bit and 64-bit, RX65N, x86-64, Xtensa, Z80/Z180, etc.). +- **Modular** - Its modular design allows developers to select only what really matters and use modules to include new features. +- **Popular** - NuttX is used by many companies around the world. Probably you already used a product with NuttX without knowing it was running NuttX. +- **Predictable** - NuttX is a preemptible Realtime kernel, so you can use it to create predictable applications for realtime control. + +--- + +## Why NuttX + LVGL? + +Although NuttX has its own graphic library called [NX](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=139629474), LVGL is a good alternative because users could find more eye-candy demos and they can reuse code from previous projects. +LVGL is an [Object-Oriented Component Based](https://blog.lvgl.io/2018-12-13/extend-lvgl-objects) high-level GUI library, that could fit very well for a RTOS with advanced features like NuttX. +LVGL is implemented in C and its APIs are in C. + +### Here are some advantages of using LVGL in NuttX + +- Develop GUI in Linux first and when it is done just compile it for NuttX. Nothing more, no wasting of time. +- Usually, GUI development for low level RTOS requires multiple iterations to get things right, where each iteration consists of **`Change code` > `Build` > `Flash` > `Run`**. +Using LVGL, Linux and NuttX you can reduce this process and just test everything on your computer and when it is done, compile it on NuttX and that is it. + +### NuttX + LVGL could be used for + +- GUI demos to demonstrate your board graphics capacities. +- Fast prototyping GUI for MVP (Minimum Viable Product) presentation. +- visualize sensor data directly and easily on the board without using a computer. +- Final products with a GUI without a touchscreen (i.e. 3D Printer Interface using Rotary Encoder to Input data). +- Final products with a touchscreen (and all sorts of bells and whistles). + +--- + +## How to get started with NuttX and LVGL? + +There are many boards in the [NuttX mainline](https://github.com/apache/incubator-nuttx) with support for LVGL. +Let's use the [STM32F429IDISCOVERY](https://www.st.com/en/evaluation-tools/32f429idiscovery.html) as an example because it is a very popular board. + +### First you need to install the pre-requisites on your system + +Let's use the [Windows Subsystem for Linux](https://acassis.wordpress.com/2018/01/10/how-to-build-nuttx-on-windows-10/) + +```shell +$ sudo apt-get install automake bison build-essential flex gcc-arm-none-eabi gperf git libncurses5-dev libtool libusb-dev libusb-1.0.0-dev pkg-config kconfig-frontends openocd +``` + +### Now let's create a workspace to save our files + +```shell +$ mkdir ~/nuttxspace +$ cd ~/nuttxspace +``` + +### Clone the NuttX and Apps repositories: + +```shell +$ git clone https://github.com/apache/incubator-nuttx nuttx +$ git clone https://github.com/apache/incubator-nuttx-apps apps +``` + +### Configure NuttX to use the stm32f429i-disco board and the LVGL Demo + +```shell +$ ./tools/configure.sh stm32f429i-disco:lvgl +$ make +``` + +If everything went fine you should have now the file `nuttx.bin` to flash on your board: + +```shell +$ ls -l nuttx.bin +-rwxrwxr-x 1 alan alan 287144 Jun 27 09:26 nuttx.bin +``` + +### Flashing the firmware in the board using OpenOCD: +```shell +$ sudo openocd -f interface/stlink-v2.cfg -f target/stm32f4x.cfg -c init -c "reset halt" -c "flash write_image erase nuttx.bin 0x08000000" +``` + +Reset the board and using the 'NSH>' terminal start the LVGL demo: +```shell +nsh> lvgldemo +``` + +## Where can I find more information? + +- This blog post: [LVGL on LPCXpresso54628](https://acassis.wordpress.com/2018/07/19/running-nuttx-on-lpcxpresso54628-om13098/) +- NuttX mailing list: [Apache NuttX Mailing List](http://nuttx.incubator.apache.org/community/) + diff --git a/lib/lvgl/docs/get-started/os/rt-thread.md b/lib/lvgl/docs/get-started/os/rt-thread.md new file mode 100644 index 00000000..25bf61fc --- /dev/null +++ b/lib/lvgl/docs/get-started/os/rt-thread.md @@ -0,0 +1,48 @@ +# RT-Thread RTOS + +<img src="https://raw.githubusercontent.com/RT-Thread/rt-thread/master/documentation/figures/logo.png" width=40% style="float: center;" > + +## What is RT-Thread? + +[Introduce about RT-Thread and how to run LVGL on RT-Thread in simulators](https://www.youtube.com/watch?v=k7QYk6hSwnc) + +[**RT-Thread**](https://www.rt-thread.io/) is an [open source](https://github.com/RT-Thread/rt-thread), neutral, and community-based real-time operating system (RTOS). RT-Thread has **Standard version** and **Nano version**. For resource-constrained microcontroller (MCU) systems, the Nano version that requires only 3 KB Flash and 1.2 KB RAM memory resources can be tailored with easy-to-use tools. For resource-rich IoT devices, RT-Thread can use the **online software package** management tool, together with system configuration tools, to achieve intuitive and rapid modular cutting, seamlessly import rich software packages; thus, achieving complex functions like Android's graphical interface and touch sliding effects, smart voice interaction effects, and so on. + +### Key features + +- Designed for resource-constrained devices, the minimum kernel requires only 1.2KB of RAM and 3 KB of Flash. +- A variety of standard interfaces, such as POSIX, CMSIS, C++ application environment. +- Has rich components and a prosperous and fast growing <a href="https://packages.rt-thread.org/en/">package ecosystem</a> +- Elegant code style, easy to use, read and master. +- High Scalability. RT-Thread has high-quality scalable software architecture, loose coupling, modularity, is easy to tailor and expand. +- Supports high-performance applications. +- Supports all mainstream compiling tools such as GCC, Keil and IAR. +- Supports a wide range of <a href="https://www.rt-thread.io/board.html">architectures and chips</a>. + + +## How to run LVGL on RT-Thread? + +[中文文档](https://www.rt-thread.org/document/site/#/rt-thread-version/rt-thread-standard/packages-manual/lvgl-docs/introduction) + +LVGL has registered as a [software package](https://packages.rt-thread.org/en/detail.html?package=LVGL) of RT-Thread. By using [Env tool](https://www.rt-thread.io/download.html?download=Env) or [RT-Thread Studio IDE](https://www.rt-thread.io/download.html?download=Studio), RT-Thread users can easily download LVGL source code and combine with RT-Thread project. RT-Thread community has port LVGL to several BSPs: + +| BSP | Note | +| ------------------------------------------------------------ | ---- | +| [QEMU simulator](https://github.com/RT-Thread/rt-thread/tree/master/bsp/qemu-vexpress-a9/applications/lvgl) | | +| [Visual Studio simulator](https://github.com/RT-Thread/rt-thread/tree/master/bsp/simulator/applications/lvgl) | | +| [Nuvoton numaker-iot-m487](https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-iot-m487/applications/lvgl) | | +| [Nuvoton numaker-pfm-m487](https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-pfm-m487/applications/lvgl) | | +| [Nuvoton nk-980iot](https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/nk-980iot/applications/lvgl) | | +| [Nuvoton numaker-m2354](https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-m2354/applications/lvgl) | | +| [Nuvoton nk-n9h30](https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/nk-n9h30/applications/lvgl) | | +| [Nuvoton numaker-m032ki](https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-m032ki/applications/lvgl) | | +| [NXP imxrt1060-evk](https://github.com/RT-Thread/rt-thread/tree/master/bsp/imxrt/imxrt1060-nxp-evk/applications/lvgl) | | +| [STM32L475 pandora](https://github.com/RT-Thread/rt-thread/tree/master/bsp/stm32/stm32l475-atk-pandora/applications/lvgl) | | +| [STM32F407 explorer](https://github.com/RT-Thread/rt-thread/tree/master/bsp/stm32/stm32f407-atk-explorer/applications/lvgl) | | +| [STM32F469 Discovery](https://github.com/RT-Thread/rt-thread/tree/master/bsp/stm32/stm32f469-st-disco/applications/lvgl) | | +| [Raspberry PICO](https://github.com/RT-Thread/rt-thread/tree/master/bsp/raspberry-pico/applications/lvgl) | | + + +### Import a BSP project into RT-Thread Studio + +Clone the latest code from RT-Thread official repository. Open the RT-Thread Studio and select `File -> Import`. In the Import menu, please select `RT-Thread BSP Project into Workspace`, and click `next` button. In the `BSP location area`, please select the root path of the BSP which you prefer to import, such as `C:\Users\xxx\Desktop\rt-thread\bsp\stm32\stm32l475-atk-pandora`. In the `Project Name area`, please type a name for this project, then, press `Finish` button. diff --git a/lib/lvgl/docs/get-started/os/zephyr.md b/lib/lvgl/docs/get-started/os/zephyr.md new file mode 100644 index 00000000..3de47260 --- /dev/null +++ b/lib/lvgl/docs/get-started/os/zephyr.md @@ -0,0 +1,3 @@ +# Zephyr + +TODO
\ No newline at end of file diff --git a/lib/lvgl/docs/get-started/platforms/arduino.md b/lib/lvgl/docs/get-started/platforms/arduino.md new file mode 100644 index 00000000..e9ca2e4d --- /dev/null +++ b/lib/lvgl/docs/get-started/platforms/arduino.md @@ -0,0 +1,79 @@ + +# Arduino + +The [LVGL library](https://github.com/lvgl/lvgl) is directly available as Arduino libraries. + +Note that you need to choose a board powerful enough to run LVGL and your GUI. See the [requirements of LVGL](https://docs.lvgl.io/master/intro/index.html#requirements). + +For example ESP32 is a good candidate to create UI's with LVGL. + +## Get the LVGL Arduino library + +LVGL can be installed via the Arduino IDE Library Manager or as a .ZIP library. + +You can [Download](https://github.com/lvgl/lvgl/archive/refs/heads/master.zip) the latest version of LVGL from GitHub and simply copy it to Arduino's library folder. + +## Set up drivers + +To get started it's recommended to use [TFT_eSPI](https://github.com/Bodmer/TFT_eSPI) library as a TFT driver to simplify testing. +To make it work, setup `TFT_eSPI` according to your TFT display type via editing either +- `User_Setup.h` +- or by selecting a configuration in the `User_Setup_Select.h` + +Both files are located in `TFT_eSPI` library's folder. + +## Configure LVGL + +LVGL has its own configuration file called `lv_conf.h`. When LVGL is installed, follow these configuration steps: +1. Go to the directory of the installed Arduino libraries +2. Go to `lvgl` and copy `lv_conf_template.h` as `lv_conf.h` into the Arduino Libraries directory next to the `lvgl` library folder. +3. Open `lv_conf.h` and change the first `#if 0` to `#if 1` to enable the content of the file +4. Set the color depth of you display in `LV_COLOR_DEPTH` +5. Set `LV_TICK_CUSTOM 1` + +Finally the layout with `lv_conf.h` should look like this: +``` +arduino + |-libraries + |-lvgl + |-other_lib_1 + |-other_lib_2 + |-lv_conf.h +``` + +## Initialize and run LVGL + +Take a look at [LVGL_Arduino.ino](https://github.com/lvgl/lvgl/blob/master/examples/arduino/LVGL_Arduino/LVGL_Arduino.ino) to see how to initialize LVGL. +`TFT_eSPI` is used as the display driver. + +In the INO file you can see how to register a display and a touchpad for LVGL and call an example. + +## Use the examples and demos + +Note that, there is no dedicated INO file for every example. Instead, you can load an example by calling an `lv_example_...` function. For example `lv_example_btn_1()`. + +**IMPORTANT** +Due to some the limitations of Arduino's build system you need to copy `lvgl/examples` to `lvgl/src/examples`. Similarly for the demos `lvgl/demos` to `lvgl/src/demos`. + +## Debugging and logging + +LVGL can display debug information in case of trouble. +In the `LVGL_Arduino.ino` example there is a `my_print` method, which sends this debug information to the serial interface. +To enable this feature you have to edit the `lv_conf.h` file and enable logging in the section `log settings`: + +```c +/*Log settings*/ +#define USE_LV_LOG 1 /*Enable/disable the log module*/ +#if LV_USE_LOG +/* How important log should be added: + * LV_LOG_LEVEL_TRACE A lot of logs to give detailed information + * LV_LOG_LEVEL_INFO Log important events + * LV_LOG_LEVEL_WARN Log if something unwanted happened but didn't cause a problem + * LV_LOG_LEVEL_ERROR Only critical issue, when the system may fail + * LV_LOG_LEVEL_NONE Do not log anything + */ +# define LV_LOG_LEVEL LV_LOG_LEVEL_WARN +``` + +After enabling the log module and setting LV_LOG_LEVEL accordingly, the output log is sent to the `Serial` port @ 115200 bps. + diff --git a/lib/lvgl/docs/get-started/platforms/cmake.md b/lib/lvgl/docs/get-started/platforms/cmake.md new file mode 100644 index 00000000..cee542a1 --- /dev/null +++ b/lib/lvgl/docs/get-started/platforms/cmake.md @@ -0,0 +1,89 @@ + +# CMake +LVGL supports integrating with [CMake](https://cmake.org/). It comes with preconfigured targets for: +- [Espressif (ESP32)](https://docs.espressif.com/projects/esp-idf/en/v3.3/get-started-cmake/index.html) +- [MicroPython](https://docs.micropython.org/en/v1.15/develop/cmodules.html) +- [Zephyr](https://docs.zephyrproject.org/latest/guides/zephyr_cmake_package.html) + +On top of the preconfigured targets you can also use "plain" CMake to integrate LVGL into any custom C/C++ project. + +### Prerequisites +- CMake ( >= 3.12.4 ) +- Compatible build tool e.g. + - [Make](https://www.gnu.org/software/make/) + - [Ninja](https://ninja-build.org/) + +## Building LVGL with CMake +There are many ways to include external CMake projects into your own. A modern one also used in this example is the CMake [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html) module. This module conveniently allows us to download dependencies directly at configure time from e.g. [GitHub](https://github.com/). Here is an example how we might include LVGL into our own project. + +```cmake +cmake_minimum_required(VERSION 3.14) +include(FetchContent) + +project(MyProject LANGUAGES C CXX) + +# Build an executable called "MyFirmware" +add_executable(MyFirmware src/main.c) + +# Specify path to own LVGL config header +set(LV_CONF_PATH + ${CMAKE_CURRENT_SOURCE_DIR}/src/lv_conf.h + CACHE STRING "" FORCE) + +# Fetch LVGL from GitHub +FetchContent_Declare(lvgl URL https://github.com/lvgl/lvgl.git) +FetchContent_MakeAvailable(lvgl) + +# The target "MyFirmware" depends on LVGL +target_link_libraries(MyFirmware PRIVATE lvgl::lvgl) +``` + +This configuration declares a dependency between the two targets **MyFirmware** and **lvgl**. Upon building the target **MyFirmware** this dependency will be resolved and **lvgl** will be built and linked with it. Since LVGL requires a config header called [lv_conf.h](https://github.com/lvgl/lvgl/blob/master/lv_conf_template.h) to be includable by its sources we also set the option `LV_CONF_PATH` to point to our own copy of it. + +### Additional CMake options +Besides `LV_CONF_PATH` there are two additional CMake options to specify include paths. + +`LV_LVGL_H_INCLUDE_SIMPLE` which specifies whether to `#include "lvgl.h"` absolut or relative + +| ON (default) | OFF | +| ------------ | -------------- | +| "lvgl.h" | "../../lvgl.h" | + +`LV_CONF_INCLUDE_SIMPLE` which specifies whether to `#include "lv_conf.h"` and `"lv_drv_conf.h"` absolut or relative + +| ON (default) | OFF | +| --------------- | --------------------- | +| "lv_conf.h" | "../../lv_conf.h" | +| "lv_drv_conf.h" | "../../lv_drv_conf.h" | + +I do not recommend disabling those options unless your folder layout makes it absolutely necessary. + +## Building LVGL examples with CMake +LVGL [examples](https://docs.lvgl.io/master/examples.html) have their own CMake target. If you want to build the examples simply add them to your dependencies. + +```cmake +# The target "MyFirmware" depends on LVGL and examples +target_link_libraries(MyFirmware PRIVATE lvgl::lvgl lvgl::examples) +``` + +## Building LVGL drivers and demos with CMake +Exactly the same goes for the [drivers](https://github.com/lvgl/lv_drivers) and the [demos](https://github.com/lvgl/lvgl/demos). + +```cmake +FetchContent_Declare(lv_drivers + GIT_REPOSITORY https://github.com/lvgl/lv_drivers) +FetchContent_MakeAvailable(lv_drivers) + +# The target "MyFirmware" depends on LVGL, drivers and demos +target_link_libraries(MyFirmware PRIVATE lvgl::lvgl lvgl::drivers lvgl::examples) +``` + +# Build shared libraries with CMake +By default, LVGL will be built as a static library (archive). CMake can instead be instructed to build LVGL as shared library (.so/.dll/etc.): +```cmake +set(BUILD_SHARED_LIBS ON) +``` +OR +``` +$ cmake "-DBUILD_SHARED_LIBS=ON" . +``` diff --git a/lib/lvgl/docs/get-started/platforms/espressif.md b/lib/lvgl/docs/get-started/platforms/espressif.md new file mode 100644 index 00000000..ee65fa23 --- /dev/null +++ b/lib/lvgl/docs/get-started/platforms/espressif.md @@ -0,0 +1,58 @@ + +# Espressif (ESP32 chip series) +LVGL can be used and configured as a standard [ESP-IDF](https://github.com/espressif/esp-idf) component. + +More information about ESP-IDF build system can be found [here](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html). + +## LVGL demo project for ESP32 + +We've created [lv_port_esp32](https://github.com/lvgl/lv_port_esp32), a project using ESP-IDF and LVGL to show one of the demos from [demos](https://github.com/lvgl/lvgl/demos). +You can configure the project to use one of the many supported display controllers and targets (chips). + +See [lvgl_esp32_drivers](https://github.com/lvgl/lvgl_esp32_drivers) repository for a complete list +of supported display and indev (touch) controllers and targets. + +## Using LVGL in your ESP-IDF project + +### Prerequisites + + * ESP-IDF v4.1 and above + * ESP evaluation board with a display + +### Obtaining LVGL + +__Option 1:__ git submodule + +Simply clone LVGL into your `project_root/components` directory and it will be automatically integrated into the project. +If the project is a git repository you can include LVGL as a git submodule: + +```sh +git submodule add https://github.com/lvgl/lvgl.git components/lvgl +``` + +The above command will clone LVGL's main repository into the `components/lvgl` directory. LVGL includes a `CMakeLists.txt` file that sets some configuration options so you can use LVGL right away. + +__Option 2:__ IDF Component Manager + +LVGL is also distributed through [IDF Component Manager](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html). +It allows users to seamlessly integrate [LVGL component](https://components.espressif.com/component/lvgl/lvgl) into their project with following command: + +```sh +idf.py add-dependency lvgl/lvgl>=8.* +``` + +During next project build, LVGL component will be fetched from the component registry and added to project build. + +### Configuration + +When you are ready to configure LVGL, launch the configuration menu with `idf.py menuconfig` in your project root directory, go to `Component config` and then `LVGL configuration`. + +## Using lvgl_esp32_drivers in ESP-IDF project + +You can also add `lvgl_esp32_drivers` as a "component". This component should be located inside a directory named "components" in your project root directory. + +When your project is a git repository you can include `lvgl_esp32_drivers` as a git submodule: + +```sh +git submodule add https://github.com/lvgl/lvgl_esp32_drivers.git components/lvgl_esp32_drivers +``` diff --git a/lib/lvgl/docs/get-started/platforms/index.md b/lib/lvgl/docs/get-started/platforms/index.md new file mode 100644 index 00000000..7ed6a016 --- /dev/null +++ b/lib/lvgl/docs/get-started/platforms/index.md @@ -0,0 +1,16 @@ +# Platforms + +```eval_rst + +.. toctree:: + :maxdepth: 2 + + pc-simulator + nxp + stm32 + espressif + arduino + tasmota-berry + cmake +``` + diff --git a/lib/lvgl/docs/get-started/platforms/nxp.md b/lib/lvgl/docs/get-started/platforms/nxp.md new file mode 100644 index 00000000..9767fbf8 --- /dev/null +++ b/lib/lvgl/docs/get-started/platforms/nxp.md @@ -0,0 +1,168 @@ +# NXP +NXP has integrated LVGL into the MCUXpresso SDK packages for several of their general purpose and crossover +microcontrollers, allowing easy evaluation and migration into your product design. +[Download an SDK for a supported board](https://www.nxp.com/design/software/embedded-software/littlevgl-open-source-graphics-library:LITTLEVGL-OPEN-SOURCE-GRAPHICS-LIBRARY?&tid=vanLITTLEVGL-OPEN-SOURCE-GRAPHICS-LIBRARY) +today and get started with your next GUI application. + +## Creating new project with LVGL +Downloading the MCU SDK example project is recommended as a starting point. It comes fully configured with LVGL (and +with PXP/VGLite support if the modules are present), no additional integration work is required. + +## HW acceleration for NXP iMX RT platforms +Depending on the RT platform used, the acceleration can be done by NXP PXP (PiXel Pipeline) and/or the Verisilicon GPU +through an API named VGLite. There is a single NXP draw context that covers both GPUs allowing to have enabled either +one or even both at the same time. While enableing both 2D accelerators, the VGLite can be used to accelerate widget +drawing while the PXP accelerated blit and fill operations. + +Supported draw callbacks are available in "src/draw/nxp/lv_gpu_nxp.c": +```c + nxp_draw_ctx->base_draw.draw_arc = lv_draw_nxp_arc; + nxp_draw_ctx->base_draw.draw_rect = lv_draw_nxp_rect; + nxp_draw_ctx->base_draw.draw_img_decoded = lv_draw_nxp_img_decoded; + nxp_draw_ctx->blend = lv_draw_nxp_blend; +``` + +If enabled both GPUs, the PXP is the preffered one to be used for drawing operation. A fallback mechanism is +implemented so that if the feature is not supported by PXP (or if PXP fails), the VGLite will take over to handle the +task. At the end, the CPU will assure that every widget drawing is fully covered (if not already done by GPU). + +### PXP accelerator +Several drawing features in LVGL can be offloaded to the PXP engine. The VGLite (if supported) and CPU are available for +other operations while the PXP is running. An RTOS is required to block the LVGL drawing thread and switch to another +task or suspend the CPU for power savings. + +#### Features supported: + - RGB565 and ARGB8888 color formats + - Area fill + optional transparency + - BLIT (BLock Image Transfer) + optional transparency + - Color keying + optional transparency + - Recoloring (color tint) + optional transparency + - Image Rotation (90, 180, 270 degree) + optional transparency + - Recoloring (color tint) + Image Rotation (90, 180, 270 degree) + optional transparency + - Screen Rotation (90, 180, 270 degree) + - RTOS integration layer + - Default FreeRTOS and bare metal code provided + + - Combination of recolor and/or rotation + color key/alpha blend/transparency is supported but PXP needs two steps. + First step is to recolor/rotate the image to a temporarly buffer (please check LV_MEM_SIZE value for allocation limit) + and another step is required to handle color keying, alpha chanel or to apply transparency. + +#### Known limitations: + - Rotation is not supported for images unaligned to blocks of 16x16 pixels. +PXP is set to process 16x16 blocks to optimize the system for memory bandwidth and image processing time. +The output engine essentially truncates any output pixels after the desired number of pixels has been written. +When rotating a source image and the output is not divisible by the block size, the incorrect pixels could be truncated +and the final output image can look shifted. + +#### Basic configuration: + - Select NXP PXP engine in lv_conf.h: Set `LV_USE_GPU_NXP_PXP` to 1 + - Enable default implementation for interrupt handling, PXP start function and automatic initialization: + Set `LV_USE_GPU_NXP_PXP_AUTO_INIT` to 1 + - If `SDK_OS_FREE_RTOS` symbol is defined, FreeRTOS implementation will be used, otherwise bare metal code will be + included + +#### Basic initialization: + - If `LV_USE_GPU_NXP_PXP_AUTO_INIT` is enabled, no user code is required; PXP is initialized automatically in + `lv_init()` + - For manual PXP initialization, default configuration structure for callbacks can be used. Initialize PXP before + calling `lv_init()` +```c + #if LV_USE_GPU_NXP_PXP + #include "src/draw/nxp/pxp/lv_gpu_nxp_pxp.h" + #endif + . . . + #if LV_USE_GPU_NXP_PXP + PXP_COND_STOP(!lv_gpu_nxp_pxp_init(), "PXP init failed."); + #endif +``` + +#### Project setup: + - Add PXP related files to project: + - src/draw/nxp/pxp/lv_gpu_nxp_pxp.c, src/draw/nxp/pxp/lv_gpu_nxp_pxp.h: init, uninit, run/wait PXP device, log/trace + - src/draw/nxp/pxp/lv_draw_pxp_blend.c, src/draw/nxp/pxp/lv_draw_pxp_blend.h: fill and blit (w/o transformation) + - src/draw/nxp/pxp/lv_gpu_nxp_osa.c, src/draw/nxp/pxp/lv_gpu_osa.h: default implementation of OS-specific functions + (bare metal and FreeRTOS only) + - optional, required only if `LV_USE_GPU_NXP_PXP_AUTO_INIT` is set to 1 + - PXP related code depends on two drivers provided by MCU SDK. These drivers need to be added to project: + - fsl_pxp.c, fsl_pxp.h: PXP driver + - fsl_cache.c, fsl_cache.h: CPU cache handling functions + +#### Logging: + - By default, LV_GPU_NXP_PXP_LOG_ERRORS is enabled so that any PXP error will be seen on LVGL output + - For tracing logs about the PXP limitations or size thresholds, the user can enable LV_GPU_NXP_PXP_LOG_TRACES + +#### Advanced configuration: + - Implementation depends on multiple OS-specific functions. The struct `lv_nxp_pxp_cfg_t` with callback pointers is + used as a parameter for the `lv_gpu_nxp_pxp_init()` function. Default implementation for FreeRTOS and baremetal is + provided in lv_gpu_nxp_osa.c + - `pxp_interrupt_init()`: Initialize PXP interrupt (HW setup, OS setup) + - `pxp_interrupt_deinit()`: Deinitialize PXP interrupt (HW setup, OS setup) + - `pxp_run()`: Start PXP job. Use OS-specific mechanism to block drawing thread. PXP must finish drawing before + leaving this function. + - There are configurable area thresholds which are used to decide whether the area will be processed by CPU or by PXP. + Areas smaller than a defined value will be processed by CPU and those bigger than the threshold will be processed by + PXP. These thresholds may be defined as preprocessor variables. Default values are defined in lv_draw_pxp_blend.h + - `LV_GPU_NXP_PXP_BLIT_SIZE_LIMIT`: size threshold for image BLIT, BLIT with color keying, BLIT with recolor and + BLIT with rotation (OPA >= LV_OPA_MAX) + - `LV_GPU_NXP_PXP_BLIT_OPA_SIZE_LIMIT`: size threshold for image BLIT, BLIT with color keying, BLIT with recolor + and BLIT with rotation and transparency (OPA < LV_OPA_MAX) + - `LV_GPU_NXP_PXP_FILL_SIZE_LIMIT`: size threshold for fill operation (OPA >= LV_OPA_MAX) + - `LV_GPU_NXP_PXP_FILL_OPA_SIZE_LIMIT`: size threshold for fill operation with transparency (OPA < LV_OPA_MAX) + +### VGLite accelerator +Extra drawing features in LVGL can be handled by the VGLite engine. The PXP (if supported) and CPU are available for +other operations while the VGLite is running. An RTOS is required to block the LVGL drawing thread and switch to another +task or suspend the CPU for power savings. + +#### Features supported: + - RGB565 and ARGB8888 color formats + - Area fill + optional transparency + - BLIT (BLock Image Transfer) + optional transparency + - Image Rotation (any degree with decimal) + optional transparency + - Image Scale + optional transparency + - Draw background rectangle with radius or gradient + - Draw arc + - RTOS integration layer + +#### Basic configuration: + - Select NXP VGLite engine in lv_conf.h: Set `LV_USE_GPU_NXP_VG_LITE` to 1 + - `SDK_OS_FREE_RTOS` symbol needs to be defined so that the FreeRTOS implementation will be used + +#### Basic initialization: + - Initialize VGLite before calling `lv_init()` by specifying the width/height of tessellation window. Value should be + a multiple of 16; minimum value is 16 pixels, maximum cannot be greater than frame width. If less than or equal to 0, + then no tessellation buffer is created, in which case the function is used for a blit init. +```c + #if LV_USE_GPU_NXP_VG_LITE + #include "vg_lite.h" + #endif + . . . + #if LV_USE_GPU_NXP_VG_LITE + VG_LITE_COND_STOP(vg_lite_init(64, 64) != VG_LITE_SUCCESS, "VGLite init failed."); + #endif +``` + +#### Project setup: + - Add VGLite related files to project: + - src/draw/nxp/vglite/lv_gpu_nxp_vglite.c, src/draw/nxp/vglite/lv_gpu_nxp_vglite.h: buffer init, log/trace + - src/draw/nxp/vglite/lv_draw_vglite_blend.c, src/draw/nxp/vglite/lv_draw_vglite_blend.h: fill and blit + (w/o transformation) + - src/draw/nxp/vglite/lv_draw_vglite_rect.c, src/draw/nxp/vglite/lv_draw_vglite_rect.h: rectangle draw + - src/draw/nxp/vglite/lv_draw_vglite_arc.c, src/draw/nxp/vglite/lv_draw_vglite_arc.h: arc draw + +#### Logging: + - By default, LV_GPU_NXP_VG_LITE_LOG_ERRORS is enabled so that any VGLite error will be seen on LVGL output + - For tracing logs about the VGLite limitations, size thresholds or stride alignment, the user can enable + LV_GPU_NXP_VG_LITE_LOG_TRACES + +#### Advanced configuration: + - There are configurable area thresholds which are used to decide whether the area will be processed by CPU or by + VGLite. Areas smaller than a defined value will be processed by CPU and those bigger than the threshold will be + processed by VGLite. These thresholds may be defined as preprocessor variables. Default values are defined in + lv_draw_vglite_blend.h + - `LV_GPU_NXP_VG_LITE_BLIT_SIZE_LIMIT`: size threshold for image BLIT, BLIT with scale and BLIT with rotation + (OPA >= LV_OPA_MAX) + - `LV_GPU_NXP_VG_LITE_BLIT_OPA_SIZE_LIMIT`: size threshold for image BLIT, BLIT with scale and BLIT with rotation + and transparency (OPA < LV_OPA_MAX) + - `LV_GPU_NXP_VG_LITE_FILL_SIZE_LIMIT`: size threshold for fill operation (OPA >= LV_OPA_MAX) + - `LV_GPU_NXP_VG_LITE_FILL_OPA_SIZE_LIMIT`: size threshold for fill operation with transparency (OPA < LV_OPA_MAX) diff --git a/lib/lvgl/docs/get-started/platforms/pc-simulator.md b/lib/lvgl/docs/get-started/platforms/pc-simulator.md new file mode 100644 index 00000000..3bdc4959 --- /dev/null +++ b/lib/lvgl/docs/get-started/platforms/pc-simulator.md @@ -0,0 +1,100 @@ +# Simulator on PC + + +You can try out LVGL **using only your PC** (i.e. without any development boards). LVGL will run on a simulator environment on the PC where anyone can write and experiment with real LVGL applications. + +Using the simulator on a PC has the following advantages: +- Hardware independent - Write code, run it on the PC and see the result on a monitor. +- Cross-platform - Any Windows, Linux or macOS system can run the PC simulator. +- Portability - The written code is portable, which means you can simply copy it when migrating to embedded hardware. +- Easy Validation - The simulator is also very useful to report bugs because it provides a common platform for every user. So it's a good idea to reproduce a bug in the simulator and use that code snippet in the [Forum](https://forum.lvgl.io). + +## Select an IDE + +The simulator is ported to various IDEs (Integrated Development Environments). Choose your favorite IDE, read its README on GitHub, download the project, and load it to the IDE. + +- [Eclipse with SDL driver](https://github.com/lvgl/lv_sim_eclipse_sdl): Recommended on Linux and Mac +- [CodeBlocks](https://github.com/lvgl/lv_sim_codeblocks_win): Recommended on Windows +- [VisualStudio with SDL driver](https://github.com/lvgl/lv_sim_visual_studio_sdl): For Windows +- [VSCode with SDL driver](https://github.com/lvgl/lv_sim_vscode_sdl): Recommended on Linux and Mac +- [PlatformIO with SDL driver](https://github.com/lvgl/lv_platformio): Recommended on Linux and Mac +- [MDK with FastModel](https://github.com/lvgl/lv_port_an547_cm55_sim): For Windows + +External project not maintained by the LVGL organization: +- [QT Creator](https://github.com/Varanda-Labs/lvgl-qt-sim): Cross platform + +You can use any IDE for development but, for simplicity, the configuration for Eclipse CDT is what we'll focus on in this tutorial. +The following section describes the set-up guide of Eclipse CDT in more detail. + + + +**Note: If you are on Windows, it's usually better to use the Visual Studio or CodeBlocks projects instead. They work out of the box without requiring extra steps.** + +## Set-up Eclipse CDT + +### Install Eclipse CDT + +[Eclipse CDT](https://eclipse.org/cdt/) is a C/C++ IDE. + +Eclipse is a Java-based tool so be sure **Java Runtime Environment** is installed on your system. + +On Debian-based distros (e.g. Ubuntu): `sudo apt-get install default-jre` + +Note: If you are using other distros, then please install a 'Java Runtime Environment' suitable to your distro. +Note: If you are using macOS and get a "Failed to create the Java Virtual Machine" error, uninstall any other Java JDK installs and install Java JDK 8u. This should fix the problem. + +You can download Eclipse's CDT from: [https://www.eclipse.org/cdt/downloads.php](https://www.eclipse.org/cdt/downloads.php). Start the installer and choose *Eclipse CDT* from the list. + +### Install SDL 2 + +The PC simulator uses the [SDL 2](https://www.libsdl.org/download-2.0.php) cross-platform library to simulate a TFT display and a touchpad. + +#### Linux +On **Linux** you can easily install SDL2 using a terminal: + +1. Find the current version of SDL2: `apt-cache search libsdl2 (e.g. libsdl2-2.0-0)` +2. Install SDL2: `sudo apt-get install libsdl2-2.0-0` (replace with the found version) +3. Install SDL2 development package: `sudo apt-get install libsdl2-dev` +4. If build essentials are not installed yet: `sudo apt-get install build-essential` + +#### Windows +If you are using **Windows** firstly you need to install MinGW ([64 bit version](http://mingw-w64.org/doku.php/download)). After installing MinGW, do the following steps to add SDL2: + +1. Download the development libraries of SDL. +Go to [https://www.libsdl.org/download-2.0.php](https://www.libsdl.org/download-2.0.php) and download _Development Libraries: SDL2-devel-2.0.5-mingw.tar.gz_ +2. Decompress the file and go to _x86_64-w64-mingw32_ directory (for 64 bit MinGW) or to _i686-w64-mingw32_ (for 32 bit MinGW) +3. Copy _..._mingw32/include/SDL2_ folder to _C:/MinGW/.../x86_64-w64-mingw32/include_ +4. Copy _..._mingw32/lib/_ content to _C:/MinGW/.../x86_64-w64-mingw32/lib_ +5. Copy _..._mingw32/bin/SDL2.dll_ to _{eclipse_workspace}/pc_simulator/Debug/_. Do it later when Eclipse is installed. + +Note: If you are using **Microsoft Visual Studio** instead of Eclipse then you don't have to install MinGW. + +#### OSX +On **OSX** you can easily install SDL2 with brew: `brew install sdl2` + +If something is not working, then please refer [this tutorial](http://lazyfoo.net/tutorials/SDL/01_hello_SDL/index.php) to get started with SDL. + +### Pre-configured project + +A pre-configured graphics library project (based on the latest release) is always available to get started easily. +You can find the latest one on [GitHub](https://github.com/lvgl/lv_sim_eclipse_sdl). +(Please note that, the project is configured for Eclipse CDT). + +### Add the pre-configured project to Eclipse CDT + +Run Eclipse CDT. It will show a dialogue about the **workspace path**. Before accepting the path, check that path and copy (and unzip) the downloaded pre-configured project there. After that, you can accept the workspace path. Of course you can modify this path but in that case copy the project to the corresponding location. + +Close the start-up window and go to **File->Import** and choose **General->Existing project into Workspace**. **Browse the root directory** of the project and click **Finish** + +On **Windows** you have to do two additional things: + +- Copy the **SDL2.dll** into the project's Debug folder +- Right-click on the project -> Project properties -> C/C++ Build -> Settings -> Libraries -> Add ... and add _mingw32_ above SDLmain and SDL. (The order is important: mingw32, SDLmain, SDL) + +### Compile and Run + +Now you are ready to run LVGL on your PC. Click on the Hammer Icon on the top menu bar to Build the project. If you have done everything right, then you will not get any errors. Note that on some systems additional steps might be required to "see" SDL 2 from Eclipse but in most cases the configuration in the downloaded project is enough. + +After a successful build, click on the Play button on the top menu bar to run the project. Now a window should appear in the middle of your screen. + +Now you are ready to use LVGL and begin development on your PC. diff --git a/lib/lvgl/docs/get-started/platforms/stm32.md b/lib/lvgl/docs/get-started/platforms/stm32.md new file mode 100644 index 00000000..9cf93083 --- /dev/null +++ b/lib/lvgl/docs/get-started/platforms/stm32.md @@ -0,0 +1,4 @@ + +# STM32 + +TODO diff --git a/lib/lvgl/docs/get-started/platforms/tasmota-berry.md b/lib/lvgl/docs/get-started/platforms/tasmota-berry.md new file mode 100644 index 00000000..4eb6459e --- /dev/null +++ b/lib/lvgl/docs/get-started/platforms/tasmota-berry.md @@ -0,0 +1,73 @@ +# Tasmota and berry + +## What is Tasmota? + +[Tasmota](https://github.com/arendst/Tasmota) is a widely used open-source firmware for ESP8266 and EPS32 based devices. It supports a wide variety of devices, sensors and integrations to Home Automation and Cloud services. Tasmota firmware is downloaded more than 200,000 times each month, and has an active and growing community. + +Tasmota provides access to hundreds of supported devices, full support of MQTT, HTTP(S), integration with major Home Automation systems, myriad of sensors, IR, RF, Zigbee, Bluetooth, AWS IoT, Azure IoT, Alexa and many more. + +## What is Berry? + +[Berry](https://github.com/berry-lang/berry) is a ultra-lightweight dynamically typed embedded scripting language. It is designed for lower-performance embedded devices. The interpreter of Berry include a one-pass compiler and register-based VM, all the code is written in ANSI C99. Berry offers a syntax very similar to Python, and is inspired from LUA VM. It is fully integrated in Tasmota + +### Highlights of Berry + +Berry has the following advantages: + +- Lightweight: A well-optimized interpreter with very little resources. Ideal for use in microprocessors. +- Fast: optimized one-pass bytecode compiler and register-based virtual machine. +- Powerful: supports imperative programming, object-oriented programming, functional programming. +- Flexible: Berry is a dynamic type script, and it's intended for embedding in applications. It can provide good dynamic scalability for the host system. +- Simple: simple and natural syntax, support garbage collection, and easy to use FFI (foreign function interface). +- RAM saving: With compile-time object construction, most of the constant objects are stored in read-only code data segments, so the RAM usage of the interpreter is very low when it starts. + +All features are detailed in the [Berry Reference Manual](https://github.com/berry-lang/berry/wiki/Reference) + +--- + +## Why LVGL + Tasmota + Berry? + +In 2021, Tasmota added full support of LVGL for ESP32 based devices. It also introduced the Berry scripting language, a small-footprint language similar to Python and fully integrated in Tasmota. + +A comprehensive mapping of LVGL in Berry language is now available, similar to the mapping of Micropython. It allows to use +98% of all LVGL features. It is also possible to write custom widgets in Berry. + +Versions supported: LVGL v8.3.0, LodePNG v20201017, Freetype 2.10.4 + +### Tasmota + Berry + LVGL could be used for: + +- Fast prototyping GUI. +- Shortening the cycle of changing and fine-tuning the GUI. +- Modelling the GUI in a more abstract way by defining reusable composite objects, taking advantage of Berry's language features such as Inheritance, Closures, Exception Handling... +- Make LVGL accessible to a larger audience. No need to know C to create a nice GUI on an embedded system. + +A higher level interface compatible with [OpenHASP](https://github.com/HASwitchPlate/openHASP) is also under development. + +--- + +## So what does it look like? + +> TL;DR: +> Similar to MicroPython, it's very much like the C API, but Object-Oriented for LVGL components. + +Let's dive right into an example! + +### A simple example + +```python +lv.start() # start LVGL +scr = lv.scr_act() # get default screen +btn = lv.btn(scr) # create button +btn.center() +label = lv.label(btn) # create a label in the button +label.set_text("Button") # set a label to the button +``` + +## How can I use it? + +You can start in less than 10 minutes on a M5Stack or equivalent device in less than 10 minutes in this [short tutorial](https://tasmota.github.io/docs/LVGL_in_10_minutes/) + +## Where can I find more information? + +- [Tasmota Documentation](https://tasmota.github.io/docs/) +- [Berry Documentation](https://github.com/berry-lang/berry/wiki/Reference) +- [Tasmota LVGL Berry documentation](https://tasmota.github.io/docs/LVGL/) diff --git a/lib/lvgl/docs/get-started/quick-overview.md b/lib/lvgl/docs/get-started/quick-overview.md new file mode 100644 index 00000000..163cfdf4 --- /dev/null +++ b/lib/lvgl/docs/get-started/quick-overview.md @@ -0,0 +1,266 @@ + +# Quick overview + +Here you can learn the most important things about LVGL. +You should read this first to get a general impression and read the detailed [Porting](/porting/index) and [Overview](/overview/index) sections after that. + +## Get started in a simulator + +Instead of porting LVGL to embedded hardware straight away, it's highly recommended to get started in a simulator first. + +LVGL is ported to many IDEs to be sure you will find your favorite one. +Go to the [Simulators](/get-started/pc-simulator) section to get ready-to-use projects that can be run on your PC. +This way you can save the time of porting for now and get some experience with LVGL immediately. + +## Add LVGL into your project +If you would rather try LVGL on your own project follow these steps: + +- [Download](https://github.com/lvgl/lvgl/archive/master.zip) or clone the library from GitHub with `git clone https://github.com/lvgl/lvgl.git`. +- Copy the `lvgl` folder into your project. +- Copy `lvgl/lv_conf_template.h` as `lv_conf.h` next to the `lvgl` folder, change the first `#if 0` to `1` to enable the file's content and set the `LV_COLOR_DEPTH` defines. +- Include `lvgl/lvgl.h` in files where you need to use LVGL related functions. +- Call `lv_tick_inc(x)` every `x` milliseconds in a Timer or Task (`x` should be between 1 and 10). It is required for the internal timing of LVGL. +Alternatively, configure `LV_TICK_CUSTOM` (see `lv_conf.h`) so that LVGL can retrieve the current time directly. +- Call `lv_init()` +- Create a draw buffer: LVGL will render the graphics here first, and send the rendered image to the display. +The buffer size can be set freely but 1/10 screen size is a good starting point. +```c +static lv_disp_draw_buf_t draw_buf; +static lv_color_t buf1[DISP_HOR_RES * DISP_VER_RES / 10]; /*Declare a buffer for 1/10 screen size*/ +lv_disp_draw_buf_init(&draw_buf, buf1, NULL, MY_DISP_HOR_RES * MY_DISP_VER_SER / 10); /*Initialize the display buffer.*/ +``` +- Implement and register a function which can copy the rendered image to an area of your display: +```c +static lv_disp_drv_t disp_drv; /*Descriptor of a display driver*/ +lv_disp_drv_init(&disp_drv); /*Basic initialization*/ +disp_drv.flush_cb = my_disp_flush; /*Set your driver function*/ +disp_drv.draw_buf = &draw_buf; /*Assign the buffer to the display*/ +disp_drv.hor_res = MY_DISP_HOR_RES; /*Set the horizontal resolution of the display*/ +disp_drv.ver_res = MY_DISP_VER_RES; /*Set the vertical resolution of the display*/ +lv_disp_drv_register(&disp_drv); /*Finally register the driver*/ + +void my_disp_flush(lv_disp_drv_t * disp, const lv_area_t * area, lv_color_t * color_p) +{ + int32_t x, y; + /*It's a very slow but simple implementation. + *`set_pixel` needs to be written by you to a set pixel on the screen*/ + for(y = area->y1; y <= area->y2; y++) { + for(x = area->x1; x <= area->x2; x++) { + set_pixel(x, y, *color_p); + color_p++; + } + } + + lv_disp_flush_ready(disp); /* Indicate you are ready with the flushing*/ +} + +``` +- Implement and register a function which can read an input device. E.g. for a touchpad: +```c +static lv_indev_drv_t indev_drv; /*Descriptor of a input device driver*/ +lv_indev_drv_init(&indev_drv); /*Basic initialization*/ +indev_drv.type = LV_INDEV_TYPE_POINTER; /*Touch pad is a pointer-like device*/ +indev_drv.read_cb = my_touchpad_read; /*Set your driver function*/ +lv_indev_drv_register(&indev_drv); /*Finally register the driver*/ + +void my_touchpad_read(lv_indev_t * indev, lv_indev_data_t * data) +{ + /*`touchpad_is_pressed` and `touchpad_get_xy` needs to be implemented by you*/ + if(touchpad_is_pressed()) { + data->state = LV_INDEV_STATE_PRESSED; + touchpad_get_xy(&data->point.x, &data->point.y); + } else { + data->state = LV_INDEV_STATE_RELEASED; + } + +} +``` +- Call `lv_timer_handler()` periodically every few milliseconds in the main `while(1)` loop or in an operating system task. +It will redraw the screen if required, handle input devices, animation etc. + +For a more detailed guide go to the [Porting](/porting/index) section. + +## Learn the basics + +### Widgets + +The graphical elements like Buttons, Labels, Sliders, Charts etc. are called objects or widgets. Go to [Widgets](/widgets/index) to see the full list of available widgets. + +Every object has a parent object where it is created. For example, if a label is created on a button, the button is the parent of label. + +The child object moves with the parent and if the parent is deleted the children will be deleted too. + +Children can be visible only within their parent's bounding area. In other words, the parts of the children outside the parent are clipped. + +A Screen is the "root" parent. You can have any number of screens. + +To get the current screen call `lv_scr_act()`, and to load a screen use `lv_scr_load(scr1)`. + +You can create a new object with `lv_<type>_create(parent)`. It will return an `lv_obj_t *` variable that can be used as a reference to the object to set its parameters. + +For example: +```c +lv_obj_t * slider1 = lv_slider_create(lv_scr_act()); +``` + +To set some basic attributes `lv_obj_set_<parameter_name>(obj, <value>)` functions can be used. For example: +```c +lv_obj_set_x(btn1, 30); +lv_obj_set_y(btn1, 10); +lv_obj_set_size(btn1, 200, 50); +``` + +Along with the basic attributes, widgets can have type specific parameters which are set by `lv_<widget_type>_set_<parameter_name>(obj, <value>)` functions. For example: +```c +lv_slider_set_value(slider1, 70, LV_ANIM_ON); +``` + +To see the full API visit the documentation of the widgets or the related header file (e.g. [lvgl/src/widgets/lv_slider.h](https://github.com/lvgl/lvgl/blob/master/src/widgets/lv_slider.h)). + + + +### Events +Events are used to inform the user that something has happened with an object. +You can assign one or more callbacks to an object which will be called if the object is clicked, released, dragged, being deleted, etc. + +A callback is assigned like this: + +```c +lv_obj_add_event_cb(btn, btn_event_cb, LV_EVENT_CLICKED, NULL); /*Assign a callback to the button*/ + +... + +void btn_event_cb(lv_event_t * e) +{ + printf("Clicked\n"); +} +``` + +`LV_EVENT_ALL` can be used instead of `LV_EVENT_CLICKED` to invoke the callback for any event. + +From `lv_event_t * e` the current event code can be retrieved with: +```c +lv_event_code_t code = lv_event_get_code(e); +``` + +The object that triggered the event can be retrieved with: +```c +lv_obj_t * obj = lv_event_get_target(e); +``` + +To learn all features of the events go to the [Event overview](/overview/event) section. + +### Parts +Widgets might be built from one or more *parts*. For example, a button has only one part called `LV_PART_MAIN`. +However, a [Slider](/widgets/core/slider) has `LV_PART_MAIN`, `LV_PART_INDICATOR` and `LV_PART_KNOB`. + +By using parts you can apply different styles to sub-elements of a widget. (See below) + +Read the widgets' documentation to learn which parts each uses. + +### States +LVGL objects can be in a combination of the following states: +- `LV_STATE_DEFAULT` Normal, released state +- `LV_STATE_CHECKED` Toggled or checked state +- `LV_STATE_FOCUSED` Focused via keypad or encoder or clicked via touchpad/mouse +- `LV_STATE_FOCUS_KEY` Focused via keypad or encoder but not via touchpad/mouse +- `LV_STATE_EDITED` Edit by an encoder +- `LV_STATE_HOVERED` Hovered by mouse (not supported now) +- `LV_STATE_PRESSED` Being pressed +- `LV_STATE_SCROLLED` Being scrolled +- `LV_STATE_DISABLED` Disabled + +For example, if you press an object it will automatically go to the `LV_STATE_FOCUSED` and `LV_STATE_PRESSED` states and when you release it the `LV_STATE_PRESSED` state will be removed while focus remains active. + +To check if an object is in a given state use `lv_obj_has_state(obj, LV_STATE_...)`. It will return `true` if the object is currently in that state. + +To manually add or remove states use: +```c +lv_obj_add_state(obj, LV_STATE_...); +lv_obj_clear_state(obj, LV_STATE_...); +``` + +### Styles +A style instance contains properties such as background color, border width, font, etc. that describe the appearance of objects. + +Styles are represented with `lv_style_t` variables. Only their pointer is saved in the objects so they need to be defined as static or global. +Before using a style it needs to be initialized with `lv_style_init(&style1)`. After that, properties can be added to configure the style. For example: +``` +static lv_style_t style1; +lv_style_init(&style1); +lv_style_set_bg_color(&style1, lv_color_hex(0xa03080)) +lv_style_set_border_width(&style1, 2)) +``` +See the full list of properties [here](/overview/style.html#properties). + + +Styles are assigned using the ORed combination of an object's part and state. For example to use this style on the slider's indicator when the slider is pressed: +```c +lv_obj_add_style(slider1, &style1, LV_PART_INDICATOR | LV_STATE_PRESSED); +``` + +If the *part* is `LV_PART_MAIN` it can be omitted: +```c +lv_obj_add_style(btn1, &style1, LV_STATE_PRESSED); /*Equal to LV_PART_MAIN | LV_STATE_PRESSED*/ +``` + +Similarly, `LV_STATE_DEFAULT` can be omitted too: +```c +lv_obj_add_style(slider1, &style1, LV_PART_INDICATOR); /*Equal to LV_PART_INDICATOR | LV_STATE_DEFAULT*/ +``` + +For `LV_STATE_DEFAULT` and `LV_PART_MAIN` simply write `0`: +```c +lv_obj_add_style(btn1, &style1, 0); /*Equal to LV_PART_MAIN | LV_STATE_DEFAULT*/ +``` + + +Styles can be cascaded (similarly to CSS). It means you can add more styles to a part of an object. +For example `style_btn` can set a default button appearance, and `style_btn_red` can overwrite the background color to make the button red: +```c +lv_obj_add_style(btn1, &style_btn, 0); +lv_obj_add_style(btn1, &style1_btn_red, 0); +``` + + +If a property is not set on for the current state, the style with `LV_STATE_DEFAULT` will be used. A default value is used if the property is not defined in the default state. + +Some properties (typically the text-related ones) can be inherited. This means if a property is not set in an object it will be searched for in its parents too. +For example, you can set the font once in the screen's style and all text on that screen will inherit it by default. + + +Local style properties also can be added to objects. This creates a style which resides inside the object and is used only by the object: +```c +lv_obj_set_style_bg_color(slider1, lv_color_hex(0x2080bb), LV_PART_INDICATOR | LV_STATE_PRESSED); +``` + +To learn all the features of styles see the [Style overview](/overview/style) section. + + +### Themes + +Themes are the default styles for objects. Styles from a theme are applied automatically when objects are created. + +The theme for your application is a compile time configuration set in `lv_conf.h`. + +## Examples + +```eval_rst + +.. include:: ../../examples/get_started/index.rst +``` + +## Micropython +Learn more about [Micropython](/get-started/micropython). +```python +# Create a Button and a Label +scr = lv.obj() +btn = lv.btn(scr) +btn.align(lv.scr_act(), lv.ALIGN.CENTER, 0, 0) +label = lv.label(btn) +label.set_text("Button") + +# Load the screen +lv.scr_load(scr) +``` + diff --git a/lib/lvgl/docs/index.md b/lib/lvgl/docs/index.md new file mode 100644 index 00000000..f89f9538 --- /dev/null +++ b/lib/lvgl/docs/index.md @@ -0,0 +1,38 @@ + +```eval_rst + +PDF version: :download:`LVGL.pdf <LVGL.pdf>` +``` + +# Welcome to the documentation of LVGL! + +<img src="_static/img/home_banner.jpg" style="width:100%"> + + +<div style="margin-bottom:48px"> + <a href="intro/index.html"><img class="home-img" src="_static/img/home_1.png" alt="Get familiar with the LVGL project"></a> + <a href="get-started/index.html"><img class="home-img" src="_static/img/home_2.png" alt="Learn the basic of LVGL and its usage on various platforms"></a> + <a href="porting/index.html"><img class="home-img" src="_static/img/home_3.png" alt="See how to port LVGL to any platform"></a> + <a href="overview/index.html"><img class="home-img" src="_static/img/home_4.png" alt="Learn the how LVGL works in more detail"></a> + <a href="widgets/index.html"><img class="home-img" src="_static/img/home_5.png" alt="Take a look at the description of the available widgets"></a> + <a href="CONTRIBUTING.html"><img class="home-img" src="_static/img/home_6.png" alt="Be part of the development of LVGL"></a> +</div> + + +```eval_rst +.. toctree:: + :maxdepth: 2 + + intro/index + examples + get-started/index + porting/index + overview/index + widgets/index + layouts/index + libs/index + others/index + CONTRIBUTING + CHANGELOG + ROADMAP +``` diff --git a/lib/lvgl/docs/intro/index.md b/lib/lvgl/docs/intro/index.md new file mode 100644 index 00000000..0d20b28c --- /dev/null +++ b/lib/lvgl/docs/intro/index.md @@ -0,0 +1,215 @@ + +# Introduction + +LVGL (Light and Versatile Graphics Library) is a free and open-source graphics library providing everything you need to create an embedded GUI with easy-to-use graphical elements, beautiful visual effects and a low memory footprint. + + +## Key features +- Powerful building blocks such as buttons, charts, lists, sliders, images, etc. +- Advanced graphics with animations, anti-aliasing, opacity, smooth scrolling +- Various input devices such as touchpad, mouse, keyboard, encoder, etc. +- Multi-language support with UTF-8 encoding +- Multi-display support, i.e. use multiple TFT, monochrome displays simultaneously +- Fully customizable graphic elements with CSS-like styles +- Hardware independent: use with any microcontroller or display +- Scalable: able to operate with little memory (64 kB Flash, 16 kB RAM) +- OS, external memory and GPU are supported but not required +- Single frame buffer operation even with advanced graphic effects +- Written in C for maximal compatibility (C++ compatible) +- Simulator to start embedded GUI design on a PC without embedded hardware +- Binding to MicroPython +- Tutorials, examples, themes for rapid GUI design +- Documentation is available online and as PDF +- Free and open-source under MIT license + +## Requirements +Basically, every modern controller which is able to drive a display is suitable to run LVGL. The minimal requirements are: +<ul> +<li> 16, 32 or 64 bit microcontroller or processor</li> +<li>> 16 MHz clock speed is recommended</li> +<li> Flash/ROM: > 64 kB for the very essential components (> 180 kB is recommended)</li> +<li> RAM: + <ul> + <li> Static RAM usage: ~2 kB depending on the used features and object types</li> + <li> Stack: > 2kB (> 8 kB is recommended)</li> + <li> Dynamic data (heap): > 4 KB (> 48 kB is recommended if using several objects). + Set by <em>LV_MEM_SIZE</em> in <em>lv_conf.h</em>. </li> + <li> Display buffer: > <em>"Horizontal resolution"</em> pixels (> 10 × <em>"Horizontal resolution"</em> is recommended) </li> + <li> One frame buffer in the MCU or in an external display controller</li> + </ul> +</li> +<li> C99 or newer compiler</li> +<li> Basic C (or C++) knowledge: + <a href="https://www.tutorialspoint.com/cprogramming/c_pointers.htm">pointers</a>, + <a href="https://www.tutorialspoint.com/cprogramming/c_structures.htm">structs</a>, + <a href="https://www.geeksforgeeks.org/callbacks-in-c/">callbacks</a>.</li> +</ul> +<em>Note that memory usage may vary depending on architecture, compiler and build options.</em> + +## License +The LVGL project (including all repositories) is licensed under [MIT license](https://github.com/lvgl/lvgl/blob/master/LICENCE.txt). +This means you can use it even in commercial projects. + +It's not mandatory, but we highly appreciate it if you write a few words about your project in the [My projects](https://forum.lvgl.io/c/my-projects/10) category of the forum or a private message to [lvgl.io](https://lvgl.io/#contact). + +Although you can get LVGL for free there is a massive amount of work behind it. It's created by a group of volunteers who made it available for you in their free time. + +To make the LVGL project sustainable, please consider [contributing](/CONTRIBUTING) to the project. +You can choose from [many different ways of contributing](/CONTRIBUTING) such as simply writing a tweet about you using LVGL, fixing bugs, translating the documentation, or even becoming a maintainer. + +## Repository layout +All repositories of the LVGL project are hosted on GitHub: https://github.com/lvgl + +You will find these repositories there: +- [lvgl](https://github.com/lvgl/lvgl) The library itself with many [examples](https://github.com/lvgl/lvgl/blob/master/examples/) and [demos](https://github.com/lvgl/lvgl/blob/master/demos/). +- [lv_drivers](https://github.com/lvgl/lv_drivers) Display and input device drivers +- [blog](https://github.com/lvgl/blog) Source of the blog's site (https://blog.lvgl.io) +- [sim](https://github.com/lvgl/sim) Source of the online simulator's site (https://sim.lvgl.io) +- [lv_port_...](https://github.com/lvgl?q=lv_port&type=&language=) LVGL ports to development boards or environments +- [lv_binding_..](https://github.com/lvgl?q=lv_binding&type=&language=l) Bindings to other languages + +## Release policy + +The core repositories follow the rules of [Semantic versioning](https://semver.org/): +- Major versions for incompatible API changes. E.g. v5.0.0, v6.0.0 +- Minor version for new but backward-compatible functionalities. E.g. v6.1.0, v6.2.0 +- Patch version for backward-compatible bug fixes. E.g. v6.1.1, v6.1.2 + +Tags like `vX.Y.Z` are created for every release. + +### Release cycle +- Bug fixes: Released on demand even weekly +- Minor releases: Every 3-4 months +- Major releases: Approximately yearly + +### Branches +The core repositories have at least the following branches: +- `master` latest version, patches are merged directly here. +- `release/vX.Y` stable versions of the minor releases +- `fix/some-description` temporary branches for bug fixes +- `feat/some-description` temporary branches for features + + +### Changelog + +The changes are recorded in [CHANGELOG.md](/CHANGELOG). + +### Version support +Before v8 the last minor release of each major series was supported for 1 year. +Starting from v8, every minor release is supported for 1 year. + +| Version | Release date | Support end | Active | +|---------|--------------|-------------|--------| +| v5.3 | Feb 1, 2019 |Feb 1, 2020 | No | +| v6.1 | Nov 26, 2019 |Nov 26, 2020 | No | +| v7.11 | Mar 16, 2021 |Mar 16, 2022 | No | +| v8.0 | 1 Jun, 2021 |1 Jun, 2022 | Yes | +| v8.1 | 10 Nov, 2021 |10 Nov, 2022 | Yes | +| v8.2 | 31 Jan, 2022 |31 Jan, 2023 | Yes | +| v8.3 | In progress | | | + +## FAQ + +### Where can I ask questions? +You can ask questions in the forum: [https://forum.lvgl.io/](https://forum.lvgl.io/). + +We use [GitHub issues](https://github.com/lvgl/lvgl/issues) for development related discussion. +You should use them only if your question or issue is tightly related to the development of the library. + +Before posting a question, please ready this FAQ section as you might find answer to your issue here too. + +### Is my MCU/hardware supported? +Every MCU which is capable of driving a display via parallel port, SPI, RGB interface or anything else and fulfills the [Requirements](#requirements) is supported by LVGL. + +This includes: +- "Common" MCUs like STM32F, STM32H, NXP Kinetis, LPC, iMX, dsPIC33, PIC32, SWM341 etc. +- Bluetooth, GSM, Wi-Fi modules like Nordic NRF and Espressif ESP32 +- Linux with frame buffer device such as /dev/fb0. This includes Single-board computers like the Raspberry Pi +- Anything else with a strong enough MCU and a peripheral to drive a display + +### Is my display supported? +LVGL needs just one simple driver function to copy an array of pixels into a given area of the display. +If you can do this with your display then you can use it with LVGL. + +Some examples of the supported display types: +- TFTs with 16 or 24 bit color depth +- Monitors with an HDMI port +- Small monochrome displays +- Gray-scale displays +- even LED matrices +- or any other display where you can control the color/state of the pixels + +See the [Porting](/porting/display) section to learn more. + +### LVGL doesn't start, randomly crashes or nothing is drawn on the display. What can be the problem? +- Try increasing `LV_MEM_SIZE`. +- Be sure `lv_disp_drv_t`, `lv_indev_drv_t` and `lv_fs_drv_t` are global or `static`. +- Be sure your display works without LVGL. E.g. paint it to red on start up. +- Enable [Logging](porting/log) +- Enable asserts in `lv_conf.h` (`LV_USE_ASSERT_...`) +- If you use an RTOS + - increase the stack size of the task which calls `lv_timer_handler()` + - Be sure you used a mutex as [described here](/porting/os) + +### My display driver is not called. What have I missed? +Be sure you are calling `lv_tick_inc(x)` in an interrupt and `lv_timer_handler()` in your main `while(1)`. + +Learn more in the [Tick](/porting/tick) and [Timer handler](/porting/timer-handler) sections. + +### Why is the display driver called only once? Only the upper part of the display is refreshed. +Be sure you are calling `lv_disp_flush_ready(drv)` at the end of your "*display flush callback*". + +### Why do I see only garbage on the screen? +Probably there a bug in your display driver. Try the following code without using LVGL. You should see a square with red-blue gradient. + +```c +#define BUF_W 20 +#define BUF_H 10 + +lv_color_t buf[BUF_W * BUF_H]; +lv_color_t * buf_p = buf; +uint16_t x, y; +for(y = 0; y < BUF_H; y++) { + lv_color_t c = lv_color_mix(LV_COLOR_BLUE, LV_COLOR_RED, (y * 255) / BUF_H); + for(x = 0; x < BUF_W; x++){ + (*buf_p) = c; + buf_p++; + } +} + +lv_area_t a; +a.x1 = 10; +a.y1 = 40; +a.x2 = a.x1 + BUF_W - 1; +a.y2 = a.y1 + BUF_H - 1; +my_flush_cb(NULL, &a, buf); +``` + +### Why do I see nonsense colors on the screen? +Probably LVGL's color format is not compatible with your display's color format. Check `LV_COLOR_DEPTH` in *lv_conf.h*. + +If you are using 16-bit colors with SPI (or another byte-oriented interface) you probably need to set `LV_COLOR_16_SWAP 1` in *lv_conf.h*. +It swaps the upper and lower bytes of the pixels. + +### How to speed up my UI? +- Turn on compiler optimization and enable cache if your MCU has it +- Increase the size of the display buffer +- Use two display buffers and flush the buffer with DMA (or similar peripheral) in the background +- Increase the clock speed of the SPI or parallel port if you use them to drive the display +- If your display has an SPI port consider changing to a model with a parallel interface because it has much higher throughput +- Keep the display buffer in internal RAM (not in external SRAM) because LVGL uses it a lot and it should have a fast access time + +### How to reduce flash/ROM usage? +You can disable all the unused features (such as animations, file system, GPU etc.) and object types in *lv_conf.h*. + +If you are using GCC/CLANG you can add `-fdata-sections -ffunction-sections` compiler flags and `--gc-sections` linker flag to remove unused functions and variables from the final binary. If possible, add the `-flto` compiler flag to enable link-time-optimisation together with `-Os` for GCC or `-Oz` for CLANG. + +### How to reduce the RAM usage +- Lower the size of the *Display buffer* +- Reduce `LV_MEM_SIZE` in *lv_conf.h*. This memory is used when you create objects like buttons, labels, etc. +- To work with lower `LV_MEM_SIZE` you can create objects only when required and delete them when they are not needed anymore + +### How to work with an operating system? + +To work with an operating system where tasks can interrupt each other (preemptively) you should protect LVGL related function calls with a mutex. +See the [Operating system and interrupts](/porting/os) section to learn more. diff --git a/lib/lvgl/docs/layouts/flex.md b/lib/lvgl/docs/layouts/flex.md new file mode 100644 index 00000000..ff5ef346 --- /dev/null +++ b/lib/lvgl/docs/layouts/flex.md @@ -0,0 +1,119 @@ + +# Flex + +## Overview + +The Flexbox (or Flex for short) is a subset of [CSS Flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/). + +It can arrange items into rows or columns (tracks), handle wrapping, adjust the spacing between the items and tracks, handle *grow* to make the item(s) fill the remaining space with respect to min/max width and height. + +To make an object flex container call `lv_obj_set_layout(obj, LV_LAYOUT_FLEX)`. + +Note that the flex layout feature of LVGL needs to be globally enabled with `LV_USE_FLEX` in `lv_conf.h`. + +## Terms +- tracks: the rows or columns +- main direction: row or column, the direction in which the items are placed +- cross direction: perpendicular to the main direction +- wrap: if there is no more space in the track a new track is started +- grow: if set on an item it will grow to fill the remaining space on the track. +The available space will be distributed among items respective to their grow value (larger value means more space) +- gap: the space between the rows and columns or the items on a track + +## Simple interface + +With the following functions you can set a Flex layout on any parent. + +### Flex flow + +`lv_obj_set_flex_flow(obj, flex_flow)` + +The possible values for `flex_flow` are: +- `LV_FLEX_FLOW_ROW` Place the children in a row without wrapping +- `LV_FLEX_FLOW_COLUMN` Place the children in a column without wrapping +- `LV_FLEX_FLOW_ROW_WRAP` Place the children in a row with wrapping +- `LV_FLEX_FLOW_COLUMN_WRAP` Place the children in a column with wrapping +- `LV_FLEX_FLOW_ROW_REVERSE` Place the children in a row without wrapping but in reversed order +- `LV_FLEX_FLOW_COLUMN_REVERSE` Place the children in a column without wrapping but in reversed order +- `LV_FLEX_FLOW_ROW_WRAP_REVERSE` Place the children in a row with wrapping but in reversed order +- `LV_FLEX_FLOW_COLUMN_WRAP_REVERSE` Place the children in a column with wrapping but in reversed order + +### Flex align +To manage the placement of the children use `lv_obj_set_flex_align(obj, main_place, cross_place, track_cross_place)` + +- `main_place` determines how to distribute the items in their track on the main axis. E.g. flush the items to the right on `LV_FLEX_FLOW_ROW_WRAP`. (It's called `justify-content` in CSS) +- `cross_place` determines how to distribute the items in their track on the cross axis. E.g. if the items have different height place them to the bottom of the track. (It's called `align-items` in CSS) +- `track_cross_place` determines how to distribute the tracks (It's called `align-content` in CSS) + +The possible values are: +- `LV_FLEX_ALIGN_START` means left on a horizontally and top vertically. (default) +- `LV_FLEX_ALIGN_END` means right on a horizontally and bottom vertically +- `LV_FLEX_ALIGN_CENTER` simply center +- `LV_FLEX_ALIGN_SPACE_EVENLY` items are distributed so that the spacing between any two items (and the space to the edges) is equal. Does not apply to `track_cross_place`. +- `LV_FLEX_ALIGN_SPACE_AROUND` items are evenly distributed in the track with equal space around them. +Note that visually the spaces aren’t equal, since all the items have equal space on both sides. +The first item will have one unit of space against the container edge, but two units of space between the next item because that next item has its own spacing that applies. Not applies to `track_cross_place`. +- `LV_FLEX_ALIGN_SPACE_BETWEEN` items are evenly distributed in the track: first item is on the start line, last item on the end line. Not applies to `track_cross_place`. + + +### Flex grow + +Flex grow can be used to make one or more children fill the available space on the track. When more children have grow parameters, the available space will be distributed proportionally to the grow values. +For example, there is 400 px remaining space and 4 objects with grow: +- `A` with grow = 1 +- `B` with grow = 1 +- `C` with grow = 2 + +`A` and `B` will have 100 px size, and `C` will have 200 px size. + +Flex grow can be set on a child with `lv_obj_set_flex_grow(child, value)`. `value` needs to be > 1 or 0 to disable grow on the child. + + +## Style interface + +All the Flex-related values are style properties under the hood and you can use them similarly to any other style property. The following flex related style properties exist: + +- `FLEX_FLOW` +- `FLEX_MAIN_PLACE` +- `FLEX_CROSS_PLACE` +- `FLEX_TRACK_PLACE` +- `FLEX_GROW` + +### Internal padding + +To modify the minimum space flexbox inserts between objects, the following properties can be set on the flex container style: + +- `pad_row` Sets the padding between the rows. + +- `pad_column` Sets the padding between the columns. + +These can for example be used if you don't want any padding between your objects: `lv_style_set_pad_column(&row_container_style,0)` + +## Other features + +### RTL +If the base direction of the container is set the `LV_BASE_DIR_RTL` the meaning of `LV_FLEX_ALIGN_START` and `LV_FLEX_ALIGN_END` is swapped on `ROW` layouts. I.e. `START` will mean right. + +The items on `ROW` layouts, and tracks of `COLUMN` layouts will be placed from right to left. + +### New track + +You can force Flex to put an item into a new line with `lv_obj_add_flag(child, LV_OBJ_FLAG_FLEX_IN_NEW_TRACK)`. + + +## Example + +```eval_rst + +.. include:: ../../examples/layouts/flex/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_flex.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/layouts/grid.md b/lib/lvgl/docs/layouts/grid.md new file mode 100644 index 00000000..ed552cf5 --- /dev/null +++ b/lib/lvgl/docs/layouts/grid.md @@ -0,0 +1,113 @@ + +# Grid + +## Overview + +The Grid layout is a subset of [CSS Flexbox](https://css-tricks.com/snippets/css/complete-guide-grid/). + +It can arrange items into a 2D "table" that has rows or columns (tracks). The item can span through multiple columns or rows. +The track's size can be set in pixel, to the largest item (`LV_GRID_CONTENT`) or in "Free unit" (FR) to distribute the free space proportionally. + +To make an object a grid container call `lv_obj_set_layout(obj, LV_LAYOUT_GRID)`. + +Note that the grid layout feature of LVGL needs to be globally enabled with `LV_USE_GRID` in `lv_conf.h`. + +## Terms +- tracks: the rows or columns +- free unit (FR): if set on track's size is set in `FR` it will grow to fill the remaining space on the parent. +- gap: the space between the rows and columns or the items on a track + +## Simple interface + +With the following functions you can easily set a Grid layout on any parent. + +### Grid descriptors + +First you need to describe the size of rows and columns. It can be done by declaring 2 arrays and the track sizes in them. The last element must be `LV_GRID_TEMPLATE_LAST`. + +For example: +``` +static lv_coord_t column_dsc[] = {100, 400, LV_GRID_TEMPLATE_LAST}; /*2 columns with 100 and 400 ps width*/ +static lv_coord_t row_dsc[] = {100, 100, 100, LV_GRID_TEMPLATE_LAST}; /*3 100 px tall rows*/ +``` + +To set the descriptors on a parent use `lv_obj_set_grid_dsc_array(obj, col_dsc, row_dsc)`. + +Besides simple settings the size in pixel you can use two special values: +- `LV_GRID_CONTENT` set the width to the largest children on this track +- `LV_GRID_FR(X)` tell what portion of the remaining space should be used by this track. Larger value means larger space. + +### Grid items +By default, the children are not added to the grid. They need to be added manually to a cell. + +To do this call `lv_obj_set_grid_cell(child, column_align, column_pos, column_span, row_align, row_pos, row_span)`. + +`column_align` and `row_align` determine how to align the children in its cell. The possible values are: +- `LV_GRID_ALIGN_START` means left on a horizontally and top vertically. (default) +- `LV_GRID_ALIGN_END` means right on a horizontally and bottom vertically +- `LV_GRID_ALIGN_CENTER` simply center + +`colum_pos` and `row_pos` means the zero based index of the cell into the item should be placed. + +`colum_span` and `row_span` means how many tracks should the item involve from the start cell. Must be > 1. + +### Grid align + +If there are some empty space the track can be aligned several ways: +- `LV_GRID_ALIGN_START` means left on a horizontally and top vertically. (default) +- `LV_GRID_ALIGN_END` means right on a horizontally and bottom vertically +- `LV_GRID_ALIGN_CENTER` simply center +- `LV_GRID_ALIGN_SPACE_EVENLY` items are distributed so that the spacing between any two items (and the space to the edges) is equal. Not applies to `track_cross_place`. +- `LV_GRID_ALIGN_SPACE_AROUND` items are evenly distributed in the track with equal space around them. +Note that visually the spaces aren’t equal, since all the items have equal space on both sides. +The first item will have one unit of space against the container edge, but two units of space between the next item because that next item has its own spacing that applies. Not applies to `track_cross_place`. +- `LV_GRID_ALIGN_SPACE_BETWEEN` items are evenly distributed in the track: first item is on the start line, last item on the end line. Not applies to `track_cross_place`. + +To set the track's alignment use `lv_obj_set_grid_align(obj, column_align, row_align)`. + +## Style interface + +All the Grid related values are style properties under the hood and you can use them similarly to any other style properties. The following Grid related style properties exist: + +- `GRID_COLUMN_DSC_ARRAY` +- `GRID_ROW_DSC_ARRAY` +- `GRID_COLUMN_ALIGN` +- `GRID_ROW_ALIGN` +- `GRID_CELL_X_ALIGN` +- `GRID_CELL_COLUMN_POS` +- `GRID_CELL_COLUMN_SPAN` +- `GRID_CELL_Y_ALIGN` +- `GRID_CELL_ROW_POS` +- `GRID_CELL_ROW_SPAN` + +### Internal padding + +To modify the minimum space Grid inserts between objects, the following properties can be set on the Grid container style: + +- `pad_row` Sets the padding between the rows. +- `pad_column` Sets the padding between the columns. + +## Other features + +### RTL +If the base direction of the container is set to `LV_BASE_DIR_RTL`, the meaning of `LV_GRID_ALIGN_START` and `LV_GRID_ALIGN_END` is swapped. I.e. `START` will mean right-most. + +The columns will be placed from right to left. + + +## Example + +```eval_rst + +.. include:: ../../examples/layouts/grid/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_grid.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/layouts/index.md b/lib/lvgl/docs/layouts/index.md new file mode 100644 index 00000000..44108d32 --- /dev/null +++ b/lib/lvgl/docs/layouts/index.md @@ -0,0 +1,11 @@ + +# Layouts + + +```eval_rst +.. toctree:: + :maxdepth: 2 + + flex + grid +``` diff --git a/lib/lvgl/docs/libs/bmp.md b/lib/lvgl/docs/libs/bmp.md new file mode 100644 index 00000000..3aace9e1 --- /dev/null +++ b/lib/lvgl/docs/libs/bmp.md @@ -0,0 +1,38 @@ + +# BMP decoder + +This extension allows the use of BMP images in LVGL. +This implementation uses [bmp-decoder](https://github.com/caj-johnson/bmp-decoder) library. +The pixels are read on demand (not the whole image is loaded) so using BMP images requires very little RAM. + +If enabled in `lv_conf.h` by `LV_USE_BMP` LVGL will register a new image decoder automatically so BMP files can be directly used as image sources. For example: +``` +lv_img_set_src(my_img, "S:path/to/picture.bmp"); +``` + +Note that, a file system driver needs to registered to open images from files. Read more about it [here](https://docs.lvgl.io/master/overview/file-system.html) or just enable one in `lv_conf.h` with `LV_USE_FS_...` + +## Limitations +- Only BMP files are supported and BMP images as C array (`lv_img_dsc_t`) are not. It's because there is no practical differences between how the BMP files and LVGL's image format stores the image data. +- BMP files can be loaded only from file. If you want to store them in flash it's better to convert them to C array with [LVGL's image converter](https://lvgl.io/tools/imageconverter). +- The BMP files color format needs to match with `LV_COLOR_DEPTH`. Use GIMP to save the image in the required format. + Both RGB888 and ARGB888 works with `LV_COLOR_DEPTH 32` +- Palette is not supported. +- Because not the whole image is read in can not be zoomed or rotated. + + +## Example +```eval_rst + +.. include:: ../../examples/libs/bmp/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_bmp.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/libs/ffmpeg.md b/lib/lvgl/docs/libs/ffmpeg.md new file mode 100644 index 00000000..b68712de --- /dev/null +++ b/lib/lvgl/docs/libs/ffmpeg.md @@ -0,0 +1,37 @@ + +# FFmpeg support +[FFmpeg](https://www.ffmpeg.org/) A complete, cross-platform solution to record, convert and stream audio and video. + +## Install FFmpeg +- Download FFmpeg from [here](https://www.ffmpeg.org/download.html) +- `./configure --disable-all --disable-autodetect --disable-podpages --disable-asm --enable-avcodec --enable-avformat --enable-decoders --enable-encoders --enable-demuxers --enable-parsers --enable-protocol='file' --enable-swscale --enable-zlib` +- `make` +- `sudo make install` + +## Add FFmpeg to your project +- Add library: `FFmpeg` (for GCC: `-lavformat -lavcodec -lavutil -lswscale -lm -lz -lpthread`) + +## Usage + +Enable `LV_USE_FFMPEG` in `lv_conf.h`. + +See the examples below. + +Note that, the FFmpeg extension doesn't use LVGL's file system. +You can simply pass the path to the image or video as usual on your operating system or platform. + +## Example +```eval_rst + +.. include:: ../../examples/libs/ffmpeg/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_ffmpeg.h + :project: lvgl + +```
\ No newline at end of file diff --git a/lib/lvgl/docs/libs/freetype.md b/lib/lvgl/docs/libs/freetype.md new file mode 100644 index 00000000..a734bba2 --- /dev/null +++ b/lib/lvgl/docs/libs/freetype.md @@ -0,0 +1,51 @@ + +# FreeType support +Interface to [FreeType](https://www.freetype.org/) to generate font bitmaps run time. + +## Install FreeType +- Download Freetype from [here](https://sourceforge.net/projects/freetype/files/) +- `make` +- `sudo make install` + +## Add FreeType to your project +- Add include path: `/usr/include/freetype2` (for GCC: `-I/usr/include/freetype2 -L/usr/local/lib`) +- Add library: `freetype` (for GCC: `-L/usr/local/lib -lfreetype`) + +## Usage +Enable `LV_USE_FREETYPE` in `lv_conf.h`. + +To cache the glyphs from the opened fonts, set `LV_FREETYPE_CACHE_SIZE >= 0` and then use the following macros for detailed configuration: +1. `LV_FREETYPE_CACHE_SIZE`:maximum memory(bytes) used to cache font bitmap, outline, character maps, etc. 0 means use the system default value, less than 0 means disable cache. Note: that this value does not account for managed FT_Face and FT_Size objects. +1. `LV_FREETYPE_CACHE_FT_FACES`:maximum number of opened FT_Face objects managed by this cache instance.0 means use the system default value. Only useful when LV_FREETYPE_CACHE_SIZE >= 0. +1. `LV_FREETYPE_CACHE_FT_SIZES`:maximum number of opened FT_Size objects managed by this cache instance. 0 means use the system default value. Only useful when LV_FREETYPE_CACHE_SIZE >= 0. + +When you are sure that all the used font sizes will not be greater than 256, you can enable `LV_FREETYPE_SBIT_CACHE`, which is much more memory efficient for small bitmaps. + +You can use `lv_ft_font_init()` to create FreeType fonts. It returns `true` to indicate success, at the same time, the `font` member of `lv_ft_info_t` will be filled with a pointer to an LVGL font, and you can use it like any LVGL font. + +Font style supports bold and italic, you can use the following macros to set: +1. `FT_FONT_STYLE_NORMAL`:default style. +1. `FT_FONT_STYLE_ITALIC`:Italic style +1. `FT_FONT_STYLE_BOLD`:bold style + +They can be combined.eg:`FT_FONT_STYLE_BOLD | FT_FONT_STYLE_ITALIC`. + +Note that, the FreeType extension doesn't use LVGL's file system. +You can simply pass the path to the font as usual on your operating system or platform. + +## Example +```eval_rst +.. include:: ../../examples/libs/freetype/index.rst +``` + + +## Learn more +- FreeType [tutorial](https://www.freetype.org/freetype2/docs/tutorial/step1.html) +- LVGL's [font interface](https://docs.lvgl.io/v7/en/html/overview/font.html#add-a-new-font-engine) + + +## API +```eval_rst +.. doxygenfile:: lv_freetype.h + :project: lvgl +```
\ No newline at end of file diff --git a/lib/lvgl/docs/libs/fsdrv.md b/lib/lvgl/docs/libs/fsdrv.md new file mode 100644 index 00000000..7b9015aa --- /dev/null +++ b/lib/lvgl/docs/libs/fsdrv.md @@ -0,0 +1,21 @@ + +# File System Interfaces + +LVGL has a [File system](https://docs.lvgl.io/master/overview/file-system.html) module to provide an abstraction layer for various file system drivers. + +LVG has built in support for: +- [FATFS](http://elm-chan.org/fsw/ff/00index_e.html) +- STDIO (Linux and Windows using C standard function .e.g fopen, fread) +- POSIX (Linux and Windows using POSIX function .e.g open, read) +- WIN32 (Windows using Win32 API function .e.g CreateFileA, ReadFile) + +You still need to provide the drivers and libraries, this extension provides only the bridge between FATFS, STDIO, POSIX, WIN32 and LVGL. + +## Usage + +In `lv_conf.h` enable `LV_USE_FS_...` and assign an upper cased letter to `LV_FS_..._LETTER` (e.g. `'S'`). +After that you can access files using that driver letter. E.g. `"S:path/to/file.txt"`. + +The work directory can be set with `LV_FS_..._PATH`. E.g. `"/home/joe/projects/"` The actual file/directory paths will be appended to it. + +Cached reading is also supported if `LV_FS_..._CACHE_SIZE` is set to not `0` value. `lv_fs_read` caches this size of data to lower the number of actual reads from the storage. diff --git a/lib/lvgl/docs/libs/gif.md b/lib/lvgl/docs/libs/gif.md new file mode 100644 index 00000000..f3ae7584 --- /dev/null +++ b/lib/lvgl/docs/libs/gif.md @@ -0,0 +1,39 @@ + +# GIF decoder +Allow using GIF images in LVGL. Based on https://github.com/lecram/gifdec + +When enabled in `lv_conf.h` with `LV_USE_GIF` `lv_gif_create(parent)` can be used to create a gif widget. + +`lv_gif_set_src(obj, src)` works very similarly to `lv_img_set_src`. As source, it also accepts images as variables (`lv_img_dsc_t`) or files. + + +## Convert GIF files to C array +To convert a GIF file to byte values array use [LVGL's online converter](https://lvgl.io/tools/imageconverter). Select "Raw" color format and "C array" Output format. + + +## Use GIF images from file +For example: +```c +lv_gif_set_src(obj, "S:path/to/example.gif"); +``` + +Note that, a file system driver needs to be registered to open images from files. Read more about it [here](https://docs.lvgl.io/master/overview/file-system.html) or just enable one in `lv_conf.h` with `LV_USE_FS_...` + + +## Memory requirements +To decode and display a GIF animation the following amount of RAM is required: +- `LV_COLOR_DEPTH 8`: 3 x image width x image height +- `LV_COLOR_DEPTH 16`: 4 x image width x image height +- `LV_COLOR_DEPTH 32`: 5 x image width x image height + +## Example +```eval_rst +.. include:: ../../examples/libs/gif/index.rst +``` + +## API + +```eval_rst +.. doxygenfile:: lv_gif.h + :project: lvgl +```
\ No newline at end of file diff --git a/lib/lvgl/docs/libs/index.md b/lib/lvgl/docs/libs/index.md new file mode 100644 index 00000000..8217e912 --- /dev/null +++ b/lib/lvgl/docs/libs/index.md @@ -0,0 +1,19 @@ +# 3rd party libraries + + +```eval_rst + +.. toctree:: + :maxdepth: 1 + + fsdrv + bmp + sjpg + png + gif + freetype + qrcode + rlottie + ffmpeg +``` + diff --git a/lib/lvgl/docs/libs/png.md b/lib/lvgl/docs/libs/png.md new file mode 100644 index 00000000..96a80248 --- /dev/null +++ b/lib/lvgl/docs/libs/png.md @@ -0,0 +1,27 @@ + +# PNG decoder + +Allow the use of PNG images in LVGL. This implementation uses [lodepng](https://github.com/lvandeve/lodepng) library. + +If enabled in `lv_conf.h` by `LV_USE_PNG` LVGL will register a new image decoder automatically so PNG files can be directly used as any other image sources. + +Note that, a file system driver needs to registered to open images from files. Read more about it [here](https://docs.lvgl.io/master/overview/file-system.html) or just enable one in `lv_conf.h` with `LV_USE_FS_...` + +The whole PNG image is decoded so during decoding RAM equals to `image width x image height x 4` bytes are required. + +As it might take significant time to decode PNG images LVGL's [images caching](https://docs.lvgl.io/master/overview/image.html#image-caching) feature can be useful. + +## Example +```eval_rst + +.. include:: ../../examples/libs/png/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_png.h + :project: lvgl + diff --git a/lib/lvgl/docs/libs/qrcode.md b/lib/lvgl/docs/libs/qrcode.md new file mode 100644 index 00000000..46e0a47d --- /dev/null +++ b/lib/lvgl/docs/libs/qrcode.md @@ -0,0 +1,38 @@ + +# QR code + +QR code generation with LVGL. Uses [QR-Code-generator](https://github.com/nayuki/QR-Code-generator) by [nayuki](https://github.com/nayuki). + +## Get started +- Download or clone this repository + - [Download](https://github.com/lvgl/lv_lib_qrcode.git) from GitHub + - Clone: git clone https://github.com/lvgl/lv_lib_qrcode.git +- Include the library: `#include "lv_lib_qrcode/lv_qrcode.h"` +- Test with the following code: +```c +const char * data = "Hello world"; + +/*Create a 100x100 QR code*/ +lv_obj_t * qr = lv_qrcode_create(lv_scr_act(), 100, lv_color_hex3(0x33f), lv_color_hex3(0xeef)); + +/*Set data*/ +lv_qrcode_update(qr, data, strlen(data)); +``` + +## Notes +- QR codes with less data are smaller, but they scaled by an integer number to best fit to the given size. + + +## Example +```eval_rst + +.. include:: ../../examples/libs/qrcode/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_qrcode.h + :project: lvgl diff --git a/lib/lvgl/docs/libs/rlottie.md b/lib/lvgl/docs/libs/rlottie.md new file mode 100644 index 00000000..85b56540 --- /dev/null +++ b/lib/lvgl/docs/libs/rlottie.md @@ -0,0 +1,106 @@ + + +# Lottie player +Allows to use Lottie animations in LVGL. Taken from this [base repository](https://github.com/ValentiWorkLearning/lv_rlottie) + +LVGL provides the interface to [Samsung/rlottie](https://github.com/Samsung/rlottie) library's C API. That is the actual Lottie player is not part of LVGL, it needs to be built separately. + +## Build Rlottie +To build Samsung's Rlottie C++14-compatible compiler and optionally CMake 3.14 or higher is required. + +To build on desktop you can follow the instructions from Rlottie's [README](https://github.com/Samsung/rlottie/blob/master/README.md). In the most basic case it looks like this: +``` +mkdir rlottie_workdir +cd rlottie_workdir +git clone https://github.com/Samsung/rlottie.git +mkdir build +cd build +cmake ../rlottie +make -j +sudo make install +``` + +And finally add the `-lrlottie` flag to your linker. + +On embedded systems you need to take care of integrating Rlottie to the given build system. + + +## Usage + +You can use animation from files or raw data (text). In either case first you need to enable `LV_USE_RLOTTIE` in `lv_conf.h`. + + +The `width` and `height` of the object be set in the *create* function and the animation will be scaled accordingly. + +### Use Rlottie from file + +To create a Lottie animation from file use: +```c + lv_obj_t * lottie = lv_rlottie_create_from_file(parent, width, height, "path/to/lottie.json"); +``` + +Note that, Rlottie uses the standard STDIO C file API, so you can use the path "normally" and no LVGL specific driver letter is required. + + +### Use Rlottie from raw string data + +`lv_example_rlottie_approve.c` contains an example animation in raw format. Instead storing the JSON string a hex array is stored for the following reasons: +- avoid escaping `"` in the JSON file +- some compilers don't support very long strings + +`lvgl/scripts/filetohex.py` can be used to convert a Lottie file a hex array. E.g.: +``` +./filetohex.py path/to/lottie.json > out.txt +``` + +To create an animation from raw data: + +```c +extern const uint8_t lottie_data[]; +lv_obj_t* lottie = lv_rlottie_create_from_raw(parent, width, height, (const char *)lottie_data); +``` + +## Getting animations + +Lottie is standard and popular format so you can find many animation files on the web. +For example: https://lottiefiles.com/ + +You can also create your own animations with Adobe After Effects or similar software. + +## Controlling animations + +LVGL provides two functions to control the animation mode: `lv_rlottie_set_play_mode` and `lv_rlottie_set_current_frame`. +You'll combine your intentions when calling the first method, like in these examples: +```c +lv_obj_t * lottie = lv_rlottie_create_from_file(scr, 128, 128, "test.json"); +lv_obj_center(lottie); +// Pause to a specific frame +lv_rlottie_set_current_frame(lottie, 50); +lv_rlottie_set_play_mode(lottie, LV_RLOTTIE_CTRL_PAUSE); // The specified frame will be displayed and then the animation will pause + +// Play backward and loop +lv_rlottie_set_play_mode(lottie, LV_RLOTTIE_CTRL_PLAY | LV_RLOTTIE_CTRL_BACKWARD | LV_RLOTTIE_CTRL_LOOP); + +// Play forward once (no looping) +lv_rlottie_set_play_mode(lottie, LV_RLOTTIE_CTRL_PLAY | LV_RLOTTIE_CTRL_FORWARD); +``` + +The default animation mode is **play forward with loop**. + +If you don't enable looping, a `LV_EVENT_READY` is sent when the animation can not make more progress without looping. + +To get the number of frames in an animation or the current frame index, you can cast the `lv_obj_t` instance to a `lv_rlottie_t` instance and inspect the `current_frame` and `total_frames` members. + +## Example +```eval_rst + +.. include:: ../../examples/libs/rlottie/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_rlottie.h + :project: lvgl diff --git a/lib/lvgl/docs/libs/sjpg.md b/lib/lvgl/docs/libs/sjpg.md new file mode 100644 index 00000000..3ee7858e --- /dev/null +++ b/lib/lvgl/docs/libs/sjpg.md @@ -0,0 +1,73 @@ + +# JPG decoder + +Allow the use of JPG images in LVGL. Besides that it also allows the use of a custom format, called Split JPG (SJPG), which can be decoded in more optimal way on embedded systems. + +## Overview + - Supports both normal JPG and the custom SJPG formats. + - Decoding normal JPG consumes RAM with the size fo the whole uncompressed image (recommended only for devices with more RAM) + - SJPG is a custom format based on "normal" JPG and specially made for LVGL. + - SJPG is 'split-jpeg' which is a bundle of small jpeg fragments with an sjpg header. + - SJPG size will be almost comparable to the jpg file or might be a slightly larger. + - File read from file and c-array are implemented. + - SJPEG frame fragment cache enables fast fetching of lines if available in cache. + - By default the sjpg image cache will be image width * 2 * 16 bytes (can be modified) + - Currently only 16 bit image format is supported (TODO) + - Only the required partion of the JPG and SJPG images are decoded, therefore they can't be zoomed or rotated. + +## Usage + +If enabled in `lv_conf.h` by `LV_USE_SJPG` LVGL will register a new image decoder automatically so JPG and SJPG files can be directly used as image sources. For example: +``` +lv_img_set_src(my_img, "S:path/to/picture.jpg"); +``` + +Note that, a file system driver needs to registered to open images from files. Read more about it [here](https://docs.lvgl.io/master/overview/file-system.html) or just enable one in `lv_conf.h` with `LV_USE_FS_...` + + + +## Converter + +### Converting JPG to C array + - Use lvgl online tool https://lvgl.io/tools/imageconverter + - Color format = RAW, output format = C Array + +### Converting JPG to SJPG +python3 and the PIL library required. (PIL can be installed with `pip3 install pillow`) + +To create SJPG from JPG: +- Copy the image to convert into `lvgl/scripts` +- `cd lvgl/scripts` +- `python3 jpg_to_sjpg.py image_to_convert.jpg`. It creates both a C files and an SJPG image. + +The expected result is: +```sh +Conversion started... + +Input: + image_to_convert.jpg + RES = 640 x 480 + +Output: + Time taken = 1.66 sec + bin size = 77.1 KB + walpaper.sjpg (bin file) + walpaper.c (c array) + +All good! +``` + + +## Example +```eval_rst + +.. include:: ../../examples/libs/sjpg/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_sjpg.h + :project: lvgl diff --git a/lib/lvgl/docs/logo_lvgl.png b/lib/lvgl/docs/logo_lvgl.png Binary files differnew file mode 100644 index 00000000..26e5a48a --- /dev/null +++ b/lib/lvgl/docs/logo_lvgl.png diff --git a/lib/lvgl/docs/misc/align.png b/lib/lvgl/docs/misc/align.png Binary files differnew file mode 100644 index 00000000..ebf0c4ef --- /dev/null +++ b/lib/lvgl/docs/misc/align.png diff --git a/lib/lvgl/docs/misc/anim-timeline.png b/lib/lvgl/docs/misc/anim-timeline.png Binary files differnew file mode 100644 index 00000000..b8c030b7 --- /dev/null +++ b/lib/lvgl/docs/misc/anim-timeline.png diff --git a/lib/lvgl/docs/misc/bidi.png b/lib/lvgl/docs/misc/bidi.png Binary files differnew file mode 100644 index 00000000..4315902c --- /dev/null +++ b/lib/lvgl/docs/misc/bidi.png diff --git a/lib/lvgl/docs/misc/boxmodel.png b/lib/lvgl/docs/misc/boxmodel.png Binary files differnew file mode 100644 index 00000000..0368fa99 --- /dev/null +++ b/lib/lvgl/docs/misc/boxmodel.png diff --git a/lib/lvgl/docs/misc/btn_example.png b/lib/lvgl/docs/misc/btn_example.png Binary files differnew file mode 100644 index 00000000..33a3fb09 --- /dev/null +++ b/lib/lvgl/docs/misc/btn_example.png diff --git a/lib/lvgl/docs/misc/button_style_example.gif b/lib/lvgl/docs/misc/button_style_example.gif Binary files differnew file mode 100644 index 00000000..c2a4063e --- /dev/null +++ b/lib/lvgl/docs/misc/button_style_example.gif diff --git a/lib/lvgl/docs/misc/button_style_example.png b/lib/lvgl/docs/misc/button_style_example.png Binary files differnew file mode 100644 index 00000000..38f6b3e4 --- /dev/null +++ b/lib/lvgl/docs/misc/button_style_example.png diff --git a/lib/lvgl/docs/misc/codeblocks.jpg b/lib/lvgl/docs/misc/codeblocks.jpg Binary files differnew file mode 100644 index 00000000..fe4ed952 --- /dev/null +++ b/lib/lvgl/docs/misc/codeblocks.jpg diff --git a/lib/lvgl/docs/misc/eclipse.jpg b/lib/lvgl/docs/misc/eclipse.jpg Binary files differnew file mode 100644 index 00000000..920791dd --- /dev/null +++ b/lib/lvgl/docs/misc/eclipse.jpg diff --git a/lib/lvgl/docs/misc/layers.png b/lib/lvgl/docs/misc/layers.png Binary files differnew file mode 100644 index 00000000..fe18d19a --- /dev/null +++ b/lib/lvgl/docs/misc/layers.png diff --git a/lib/lvgl/docs/misc/par_child1.png b/lib/lvgl/docs/misc/par_child1.png Binary files differnew file mode 100644 index 00000000..e2cbb53d --- /dev/null +++ b/lib/lvgl/docs/misc/par_child1.png diff --git a/lib/lvgl/docs/misc/par_child2.png b/lib/lvgl/docs/misc/par_child2.png Binary files differnew file mode 100644 index 00000000..fb7c0649 --- /dev/null +++ b/lib/lvgl/docs/misc/par_child2.png diff --git a/lib/lvgl/docs/misc/par_child3.png b/lib/lvgl/docs/misc/par_child3.png Binary files differnew file mode 100644 index 00000000..d682aeb8 --- /dev/null +++ b/lib/lvgl/docs/misc/par_child3.png diff --git a/lib/lvgl/docs/misc/platformio.jpg b/lib/lvgl/docs/misc/platformio.jpg Binary files differnew file mode 100644 index 00000000..eb88bfaa --- /dev/null +++ b/lib/lvgl/docs/misc/platformio.jpg diff --git a/lib/lvgl/docs/misc/qtcreator.jpg b/lib/lvgl/docs/misc/qtcreator.jpg Binary files differnew file mode 100644 index 00000000..890dc1e0 --- /dev/null +++ b/lib/lvgl/docs/misc/qtcreator.jpg diff --git a/lib/lvgl/docs/misc/simple_button_example.gif b/lib/lvgl/docs/misc/simple_button_example.gif Binary files differnew file mode 100644 index 00000000..2884923a --- /dev/null +++ b/lib/lvgl/docs/misc/simple_button_example.gif diff --git a/lib/lvgl/docs/misc/simple_button_example.png b/lib/lvgl/docs/misc/simple_button_example.png Binary files differnew file mode 100644 index 00000000..28825e38 --- /dev/null +++ b/lib/lvgl/docs/misc/simple_button_example.png diff --git a/lib/lvgl/docs/misc/symbols.png b/lib/lvgl/docs/misc/symbols.png Binary files differnew file mode 100644 index 00000000..139e3308 --- /dev/null +++ b/lib/lvgl/docs/misc/symbols.png diff --git a/lib/lvgl/docs/misc/sys.png b/lib/lvgl/docs/misc/sys.png Binary files differnew file mode 100644 index 00000000..de5ebcd0 --- /dev/null +++ b/lib/lvgl/docs/misc/sys.png diff --git a/lib/lvgl/docs/misc/visualstudio.jpg b/lib/lvgl/docs/misc/visualstudio.jpg Binary files differnew file mode 100644 index 00000000..0e852d04 --- /dev/null +++ b/lib/lvgl/docs/misc/visualstudio.jpg diff --git a/lib/lvgl/docs/others/fragment.md b/lib/lvgl/docs/others/fragment.md new file mode 100644 index 00000000..ae909386 --- /dev/null +++ b/lib/lvgl/docs/others/fragment.md @@ -0,0 +1,77 @@ + +# Fragment + +Fragment is a concept copied from [Android](https://developer.android.com/guide/fragments). + +It represents a reusable portion of your app's UI. A fragment defines and manages its own layout, has its own lifecycle, +and can handle its own events. Like Android's Fragment that must be hosted by an activity or another fragment, Fragment +in LVGL needs to be hosted by an object, or another fragment. The fragment’s view hierarchy becomes part of, or attaches +to, the host’s view hierarchy. + +Such concept also has some similarities +to [UiViewController on iOS](https://developer.apple.com/documentation/uikit/uiviewcontroller). + +Fragment Manager is a manager holding references to fragments attached to it, and has an internal stack to achieve +navigation. You can use fragment manager to build navigation stack, or multi pane application easily. + +## Usage + +Enable `LV_USE_FRAGMENT` in `lv_conf.h`. + +### Create Fragment Class + +```c +struct sample_fragment_t { + /* IMPORTANT: don't miss this part */ + lv_fragment_t base; + /* States, object references and data fields for this fragment */ + const char *title; +}; + +const lv_fragment_class_t sample_cls = { + /* Initialize something needed */ + .constructor_cb = sample_fragment_ctor, + /* Create view objects */ + .create_obj_cb = sample_fragment_create_obj, + /* IMPORTANT: size of your fragment struct */ + .instance_size = sizeof(struct sample_fragment_t) +}; +``` + +### Use `lv_fragment_manager` + +```c +/* Create fragment instance, and objects will be added to container */ +lv_fragment_manager_t *manager = lv_fragment_manager_create(container, NULL); +/* Replace current fragment with instance of sample_cls, and init_argument is user defined pointer */ +lv_fragment_manager_replace(manager, &sample_cls, init_argument); +``` + +### Fragment Based Navigation + +```c +/* Add one instance into manager stack. View object of current fragment will be destroyed, + * but instances created in class constructor will be kept. + */ +lv_fragment_manager_push(manager, &sample_cls, NULL); + +/* Remove the top most fragment from the stack, and bring back previous one. */ +lv_fragment_manager_pop(manager); +``` + +## Example + +```eval_rst + +.. include:: ../../examples/others/fragment/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_fragment.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/others/gridnav.md b/lib/lvgl/docs/others/gridnav.md new file mode 100644 index 00000000..1e863d45 --- /dev/null +++ b/lib/lvgl/docs/others/gridnav.md @@ -0,0 +1,56 @@ +# Grid navigation + +Grid navigation (gridnav for short) is a feature that changes the currently focused child object as arrow keys are pressed. + +If the children are arranged into a grid-like layout then the up, down, left and right arrows move focus to the nearest sibling +in the respective direction. + +It doesn't matter how the children are positioned, as only the current x and y coordinates are considered. +This means that gridnav works with manually positioned children, as well as [Flex](/layouts/flex) and [Grid](/layouts/grid) layouts. + +Gridnav also works if the children are arranged into a single row or column. +That makes it useful, for example, to simplify navigation on a [List widget](/widgets/extra/list). + +Gridnav assumes that the object to which gridnav is added is part of a [group](/overview/indev.html#groups). +This way, if the object with gridnav is focused, the arrow key presses are automatically forwarded to the object +so that gridnav can process the arrow keys. + +To move the focus to the next widget of the group use `LV_KEY_NEXT/PREV` or `lv_group_focus_next/prev()` or the `TAB` key on keyboard as usual. + +If the container is scrollable and the focused child is out of the view, gridnav will automatically scroll the child into view. + +## Usage + +To add the gridnav feature to an object use `lv_gridnav_add(cont, flags)`. + +`flags` control the behavior of gridnav: +- `LV_GRIDNAV_CTRL_NONE` Default settings +- `LV_GRIDNAV_CTRL_ROLLOVER` If there is no next/previous object in a direction, +the focus goes to the object in the next/previous row (on left/right keys) or first/last row (on up/down keys +- `LV_GRIDNAV_CTRL_SCROLL_FIRST` If an arrow is pressed and the focused object can be scrolled in that direction +then it will be scrolled instead of going to the next/previous object. If there is no more room for scrolling the next/previous object will be focused normally + +`lv_gridnav_remove(cont)` Removes gridnav from an object. + +## Focusable objects + +An object needs to be clickable or click focusable (`LV_OBJ_FLAG_CLICKABLE` or `LV_OBJ_FLAG_CLICK_FOCUSABLE`) +and not hidden (`LV_OBJ_FLAG_HIDDEN`) to be focusable by gridnav. + + +## Example + +```eval_rst + +.. include:: ../../examples/others/gridnav/index.rst + +``` +## API + + +```eval_rst + +.. doxygenfile:: lv_gridnav.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/others/ime_pinyin.md b/lib/lvgl/docs/others/ime_pinyin.md new file mode 100644 index 00000000..82747fff --- /dev/null +++ b/lib/lvgl/docs/others/ime_pinyin.md @@ -0,0 +1,150 @@ +# Pinyin IME + +Pinyin IME provides API to provide Chinese Pinyin input method (Chinese input) for keyboard object, which supports 26 key and 9 key input modes. You can think of `lv_ime_pinyin` as a Pinyin input method plug-in for keyboard objects. + +Normally, an environment where [lv_keyboard](/widgets/extra/keyboard) can run can also run `lv_ime_pinyin`. There are two main influencing factors: the size of the font file and the size of the dictionary. + +<details> +<summary>中文</summary> +<p> + +`lv_ime_pinyin`为[键盘](/widgets/extra/keyboard)组件提供汉语拼音输入法（中文输入）的功能(后文简称为拼音输入法)，支持26键和9键输入模式。您可以将 `lv_ime_pinyin` 看成是键盘组件的汉语拼音输入法插件。 + +一般情况下，只要是[键盘](/widgets/extra/keyboard)组件能运行的环境 `lv_ime_pinyin` 也能运行。有两个影响因素：字库的大小和词库的大小。 + +</p> +</details> + +## Usage + +Enable `LV_USE_IME_PINYIN` in `lv_conf.h`. + +First use `lv_ime_pinyin_create(lv_scr_act())` to create a Pinyin input method plug-in, then use `lv_ime_pinyin_set_keyboard(pinyin_ime, kb)` to add the `keyboard` you created to the Pinyin input method plug-in. +You can use `lv_ime_pinyin_set_dict(pinyin_ime, your_dict)` to use a custom dictionary (if you don't want to use the built-in dictionary at first, you can disable `LV_IME_PINYIN_USE_DEFAULT_DICT` in `lv_conf.h`, which can save a lot of memory space). + +The built-in thesaurus is customized based on the **LV_FONT_SIMSUN_16_CJK** font library, which currently only has more than `1,000` most common CJK radicals, so it is recommended to use custom fonts and thesaurus. + +In the process of using the Pinyin input method plug-in, you can change the keyboard and dictionary at any time. + +<details> +<summary>中文</summary> +<p> + +在 `lv_conf.h` 中打开 `LV_USE_IME_PINYIN`。 + +首先，使用 `lv_ime_pinyin_create(lv_scr_act())` 函数创建一个拼音输入法插件， +然后使用 `lv_ime_pinyin_set_keyboard(pinyin_ime, kb)` 函数将您创建的键盘组件添加到插件中。 + +内置的词库是基于 LVGL 的 **LV_FONT_SIMSUN_16_CJK** 字库定制，这个字库目前只有 `1000` 多个最常见的 CJK 部首，所以建议使用自定义字库和词库。 + +您可以使用 `lv_ime_pinyin_set_dict(pinyin_ime, your_dict)` 函数来设置使用自定义的词库，如果您一开始就不打算使用内置的词库，建议您在 `lv_conf.h` 中将 `LV_IME_PINYIN_USE_DEFAULT_DICT` 关闭，这可以节省一些内存空间。 + +</p> +</details> + +## Custom dictionary + +If you don't want to use the built-in Pinyin dictionary, you can use the custom dictionary. +Or if you think that the built-in phonetic dictionary consumes a lot of memory, you can also use a custom dictionary. + +Customizing the dictionary is very simple. + +First, set `LV_IME_PINYIN_USE_DEFAULT_DICT` to `0` in `lv_conf.h` + +Then, write a dictionary in the following format. + +<details> +<summary>中文</summary> +<p> + +如果您不想使用内置的词库，可以通过下面的方法自定义词库。 + +自定义词典非常简单。 +首先，在 `lv_conf.h` 将 `LV_IME_PINYIN_USE_DEFAULT_DICT` 设置为 0。 +然后按照下面的格式编写词库。 + +</p> +</details> + +### Dictionary format + +The arrangement order of each pinyin syllable is very important. You need to customize your own thesaurus according to the Hanyu Pinyin syllable table. You can read [here](https://baike.baidu.com/item/%E6%B1%89%E8%AF%AD%E6%8B%BC%E9%9F%B3%E9%9F%B3%E8%8A%82/9167981) to learn about the Hanyu Pinyin syllables and the syllable table. + +Then, write your own dictionary according to the following format: + +<details> +<summary>中文</summary> +<p> + +**注意**，各个拼音音节的排列顺序非常重要，您需要按照汉语拼音音节表定制自己的词库，可以阅读[这里](https://baike.baidu.com/item/%E6%B1%89%E8%AF%AD%E6%8B%BC%E9%9F%B3%E9%9F%B3%E8%8A%82/9167981)了解[汉语拼音音节](https://baike.baidu.com/item/%E6%B1%89%E8%AF%AD%E6%8B%BC%E9%9F%B3%E9%9F%B3%E8%8A%82/9167981)以及[音节表](https://baike.baidu.com/item/%E6%B1%89%E8%AF%AD%E6%8B%BC%E9%9F%B3%E9%9F%B3%E8%8A%82/9167981#1)。 + +然后，根据下面的格式编写自己的词库： + +</p> +</details> + +```c +lv_100ask_pinyin_dict_t your_pinyin_dict[] = { + { "a", "啊阿呵吖" }, + { "ai", "埃挨哎唉哀皑蔼矮碍爱隘癌艾" }, + { "an", "按安暗岸俺案鞍氨胺厂广庵揞犴铵桉谙鹌埯黯" }, + { "ang", "昂肮盎仰" }, + { "ao", "凹敖熬翱袄傲奥懊澳" }, + { "ba", "芭捌叭吧笆八疤巴拔跋靶把坝霸罢爸扒耙" }, + { "bai", "白摆佰败拜柏百稗伯" }, + /* ...... */ + { "zuo", "昨左佐做作坐座撮琢柞"}, + {NULL, NULL} + +``` + +**The last item** must end with `{null, null}` , or it will not work properly. + +### Apply new dictionary + +After writing a dictionary according to the above dictionary format, you only need to call this function to set up and use your dictionary: + +<details> +<summary>中文</summary> +<p> + +按照上面的词库格式编写好自己的词库之后，参考下面的用法，调用 `lv_100ask_pinyin_ime_set_dict(pinyin_ime, your_pinyin_dict)` 函数即可设置和使用新词库： + +</p> +</details> + +```c + lv_obj_t * pinyin_ime = lv_100ask_pinyin_ime_create(lv_scr_act()); + lv_100ask_pinyin_ime_set_dict(pinyin_ime, your_pinyin_dict); +``` + +## Input modes + +`lv_ime_pinyin` supports 26 key and 9 key input modes. The mode switching is very simple, just call the function `lv_ime_pinyin_set_mode`. If the second parameter of function `lv_ime_pinyin_set_mode` is' 1 ', switch to 26 key input mode; if it is' 0', switch to 9 key input mode, and the default is' 1 '. + +<details> +<summary>中文</summary> +<p> + +`lv_ime_pinyin` 支持26键和9键输入模式。模式的切换非常简单，只需调用函数 `lv_ime_pinyin_set_mode` 即可。如果函数 `lv_ime_pinyin_set_mode` 的第2个参数为 `1` 则切换到 26 键输入模式，如果为 `0` 则切换到 9 键输入法模式，默认为 `1` 。 + +</p> +</details> + + +## Example + +```eval_rst + +.. include:: ../../examples/others/ime/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_ime_pinyin.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/others/imgfont.md b/lib/lvgl/docs/others/imgfont.md new file mode 100644 index 00000000..0f0f0994 --- /dev/null +++ b/lib/lvgl/docs/others/imgfont.md @@ -0,0 +1,25 @@ +# Image font (imgfont) +Draw image in label or span obj with imgfont. +This is often used to display Unicode emoji icons in text. +Supported image formats: determined by LVGL image decoder. + +## Usage +Enable `LV_USE_IMGFONT` in `lv_conf.h`. + +To create a new imgfont use `lv_imgfont_create(height, path_cb)`. + +`height` used to indicate the size of a imgfont. +`path_cb` Used to get the image path of the specified unicode. + +Use `lv_imgfont_destroy(imgfont)` to destroy a imgfont that is no longer used. + +## Example +```eval_rst +.. include:: ../../examples/others/imgfont/index.rst +``` + +## API +```eval_rst +.. doxygenfile:: lv_imgfont.h + :project: lvgl +``` diff --git a/lib/lvgl/docs/others/index.md b/lib/lvgl/docs/others/index.md new file mode 100644 index 00000000..e45d1caf --- /dev/null +++ b/lib/lvgl/docs/others/index.md @@ -0,0 +1,17 @@ +# Others + + +```eval_rst + +.. toctree:: + :maxdepth: 1 + + snapshot + monkey + gridnav + fragment + msg + imgfont + ime_pinyin +``` + diff --git a/lib/lvgl/docs/others/monkey.md b/lib/lvgl/docs/others/monkey.md new file mode 100644 index 00000000..f230d581 --- /dev/null +++ b/lib/lvgl/docs/others/monkey.md @@ -0,0 +1,35 @@ +# Monkey + +A simple monkey test. Use random input to stress test the application. + +## Usage + +Enable `LV_USE_MONKEY` in `lv_conf.h`. + +First configure monkey, use `lv_monkey_config_t` to define the configuration structure, set the `type` (check [input devices](/overview/indev) for the supported types), and then set the range of `period_range` and `input_range`, the monkey will output random operations at random times within this range. Call `lv_monkey_create` to create monkey. Finally call `lv_monkey_set_enable(monkey, true)` to enable monkey. + +If you want to pause the monkey, call `lv_monkey_set_enable(monkey, false)`. To delete the monkey, call `lv_monkey_del(monkey)`. + +Note that `input_range` has different meanings in different `type`: + +- `LV_INDEV_TYPE_POINTER` No effect, click randomly within the pixels of the screen resolution. +- `LV_INDEV_TYPE_ENCODER` The minimum and maximum values of `enc_diff`. +- `LV_INDEV_TYPE_BUTTON` The minimum and maximum values of `btn_id`. Use `lv_monkey_get_indev()` to get the input device, and use `lv_indev_set_button_points()` to map the key ID to the coordinates. +- `LV_INDEV_TYPE_KEYPAD` No effect, Send random [Keys](/overview/indev). + +## Example + +```eval_rst + +.. include:: ../../examples/others/monkey/index.rst + +``` +## API + + +```eval_rst + +.. doxygenfile:: lv_monkey.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/others/msg.md b/lib/lvgl/docs/others/msg.md new file mode 100644 index 00000000..53deb582 --- /dev/null +++ b/lib/lvgl/docs/others/msg.md @@ -0,0 +1,97 @@ +# Messaging + +Messaging (`lv_msg`) is a classic []publisher subscriber](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern) implementation for LVGL. + +## IDs +Both the publishers and the subscribers needs to know the message identifiers. +In `lv_msg` these are simple `uint32_t` integers. For example: +```c +#define MSG_DOOR_OPENED 1 +#define MSG_DOOR_CLOSED 2 +#define MSG_USER_NAME_CHANGED 100 +#define MSG_USER_AVATAR_CHANGED 101 +``` + +You can orgnaize the message IDs as you wish. + +Both parties also need to know about the format of teh payload. E.g. in the above example +`MSG_DOOR_OPENED` and `MSG_DOOR_CLOSED` has no payload but `MSG_USER_NAME_CHANGED` can have a `const char *` payload containing the user name, and `MSG_USER_AVATAR_CHANGED` a `const void *` image source with the new avatar image. + + +## Send message + +Messages can be sent with `lv_msg_send(msg_id, payload)`. E.g. +```c +lv_msg_send(MSG_USER_DOOR_OPENED, NULL); +lv_msg_send(MSG_USER_NAME_CHANGED, "John Smith"); +``` + +## Subscribe to a message + +`lv_msg_subscribe(msg_id, callback, user_data)` can be used to subscribe to message. + +The callback should look like this: +```c + +static void user_name_subscriber_cb(void * s, lv_msg_t * m) +{ + /*s: a subscriber obeject, can be used to unscubscribe*/ + /*m: a message object with the msg_id, payload, and user_data (set durung subscription)*/ + + ...do something... +} +``` + +From `lv_msg_t` the followings can be used to get some data: +- `lv_msg_get_id(m)` +- `lv_msg_get_payload(m)` +- `lv_msg_get_user_data(m)` + +## Subscribe with an lv_obj +It's quite typical that an LVGL widget is interested in some messages. +To make it simpler `lv_msg_subsribe_obj(msg_id, obj, user_data)` can be used. +If a new message is published with `msg_id` an `LV_EVENT_MSG_RECEIVED` event will be sent to the object. + +For example: +```c +lv_obj_add_event_cb(user_name_label, user_name_label_event_cb, LV_EVENT_MSG_RECEIVED, NULL); +lv_msg_subsribe_obj(MSG_USER_NAME_CHANGED, user_name_label, NULL); + +... + +void user_name_label_event_cb(lv_event_t * e) +{ + lv_obj_t * label = lv_event_get_target(e); + lv_msg_t * m = lv_event_get_msg(e); + lv_label_set_text(label, lv_msg_get_payload(m)); +} + +``` + +### Unsubscribe +`lv_msg_subscribe` returns a pointer which can be used to unsubscribe: +```c +void * s1; +s1 = lv_msg_subscribe(MSG_USER_DOOR_OPENED, some_callback, NULL); + +... + +lv_msg_unsubscribe(s1); +``` + +## Example + +```eval_rst + +.. include:: ../../examples/others/msg/index.rst + +``` +## API + + +```eval_rst + +.. doxygenfile:: lv_msg.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/others/snapshot.md b/lib/lvgl/docs/others/snapshot.md new file mode 100644 index 00000000..fc54ca3f --- /dev/null +++ b/lib/lvgl/docs/others/snapshot.md @@ -0,0 +1,63 @@ +# Snapshot + +Snapshot provides APIs to take snapshot image for LVGL object together with its children. The image will look exactly like the object. + +## Usage + +Simply call API `lv_snapshot_take` to generate the image descriptor which can be set as image object src using `lv_img_set_src`. + + +Note, only below color formats are supported for now: + - LV_IMG_CF_TRUE_COLOR_ALPHA + - LV_IMG_CF_ALPHA_1BIT + - LV_IMG_CF_ALPHA_2BIT + - LV_IMG_CF_ALPHA_4BIT + - LV_IMG_CF_ALPHA_8BIT + + +### Free the Image +The memory `lv_snapshot_take` uses are dynamically allocated using `lv_mem_alloc`. Use API `lv_snapshot_free` to free the memory it takes. This will firstly free memory the image data takes, then the image descriptor. + + +Take caution to free the snapshot but not delete the image object. Before free the memory, be sure to firstly unlink it from image object, using `lv_img_set_src(NULL)` and `lv_img_cache_invalidate_src(src)`. + + +Below code snippet explains usage of this API. + +```c +void update_snapshot(lv_obj_t * obj, lv_obj_t * img_snapshot) +{ + lv_img_dsc_t* snapshot = (void*)lv_img_get_src(img_snapshot); + if(snapshot) { + lv_snapshot_free(snapshot); + } + snapshot = lv_snapshot_take(obj, LV_IMG_CF_TRUE_COLOR_ALPHA); + lv_img_set_src(img_snapshot, snapshot); +} +``` + +### Use Existing Buffer +If the snapshot needs update now and then, or simply caller provides memory, use API `lv_res_t lv_snapshot_take_to_buf(lv_obj_t * obj, lv_img_cf_t cf, lv_img_dsc_t * dsc, void * buf, uint32_t buff_size);` for this case. It's caller's responsibility to alloc/free the memory. + + +If snapshot is generated successfully, the image descriptor is updated and image data will be stored to provided `buf`. + + +Note that snapshot may fail if provided buffer is not enough, which may happen when object size changes. It's recommended to use API `lv_snapshot_buf_size_needed` to check the needed buffer size in byte firstly and resize the buffer accordingly. + +## Example + +```eval_rst + +.. include:: ../../examples/others/snapshot/index.rst + +``` +## API + + +```eval_rst + +.. doxygenfile:: lv_snapshot.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/overview/animation.md b/lib/lvgl/docs/overview/animation.md new file mode 100644 index 00000000..d4800e65 --- /dev/null +++ b/lib/lvgl/docs/overview/animation.md @@ -0,0 +1,144 @@ +# Animations + +You can automatically change the value of a variable between a start and an end value using animations. +Animation will happen by periodically calling an "animator" function with the corresponding value parameter. + +The *animator* functions have the following prototype: +```c +void func(void * var, lv_anim_var_t value); +``` +This prototype is compatible with the majority of the property *set* functions in LVGL. For example `lv_obj_set_x(obj, value)` or `lv_obj_set_width(obj, value)` + + +## Create an animation +To create an animation an `lv_anim_t` variable has to be initialized and configured with `lv_anim_set_...()` functions. + +```c + +/* INITIALIZE AN ANIMATION + *-----------------------*/ + +lv_anim_t a; +lv_anim_init(&a); + +/* MANDATORY SETTINGS + *------------------*/ + +/*Set the "animator" function*/ +lv_anim_set_exec_cb(&a, (lv_anim_exec_xcb_t) lv_obj_set_x); + +/*Set target of the animation*/ +lv_anim_set_var(&a, obj); + +/*Length of the animation [ms]*/ +lv_anim_set_time(&a, duration); + +/*Set start and end values. E.g. 0, 150*/ +lv_anim_set_values(&a, start, end); + +/* OPTIONAL SETTINGS + *------------------*/ + +/*Time to wait before starting the animation [ms]*/ +lv_anim_set_delay(&a, delay); + +/*Set path (curve). Default is linear*/ +lv_anim_set_path(&a, lv_anim_path_ease_in); + +/*Set a callback to indicate when the animation is ready (idle).*/ +lv_anim_set_ready_cb(&a, ready_cb); + +/*Set a callback to indicate when the animation is deleted (idle).*/ +lv_anim_set_deleted_cb(&a, deleted_cb); + +/*Set a callback to indicate when the animation is started (after delay).*/ +lv_anim_set_start_cb(&a, start_cb); + +/*When ready, play the animation backward with this duration. Default is 0 (disabled) [ms]*/ +lv_anim_set_playback_time(&a, time); + +/*Delay before playback. Default is 0 (disabled) [ms]*/ +lv_anim_set_playback_delay(&a, delay); + +/*Number of repetitions. Default is 1. LV_ANIM_REPEAT_INFINITE for infinite repetition*/ +lv_anim_set_repeat_count(&a, cnt); + +/*Delay before repeat. Default is 0 (disabled) [ms]*/ +lv_anim_set_repeat_delay(&a, delay); + +/*true (default): apply the start value immediately, false: apply start value after delay when the anim. really starts. */ +lv_anim_set_early_apply(&a, true/false); + +/* START THE ANIMATION + *------------------*/ +lv_anim_start(&a); /*Start the animation*/ +``` + + +You can apply multiple different animations on the same variable at the same time. +For example, animate the x and y coordinates with `lv_obj_set_x` and `lv_obj_set_y`. However, only one animation can exist with a given variable and function pair and `lv_anim_start()` will remove any existing animations for such a pair. + +## Animation path + +You can control the path of an animation. The most simple case is linear, meaning the current value between *start* and *end* is changed with fixed steps. +A *path* is a function which calculates the next value to set based on the current state of the animation. Currently, there are the following built-in path functions: + +- `lv_anim_path_linear` linear animation +- `lv_anim_path_step` change in one step at the end +- `lv_anim_path_ease_in` slow at the beginning +- `lv_anim_path_ease_out` slow at the end +- `lv_anim_path_ease_in_out` slow at the beginning and end +- `lv_anim_path_overshoot` overshoot the end value +- `lv_anim_path_bounce` bounce back a little from the end value (like hitting a wall) + + +## Speed vs time +By default, you set the animation time directly. But in some cases, setting the animation speed is more practical. + +The `lv_anim_speed_to_time(speed, start, end)` function calculates the required time in milliseconds to reach the end value from a start value with the given speed. +The speed is interpreted in _unit/sec_ dimension. For example, `lv_anim_speed_to_time(20,0,100)` will yield 5000 milliseconds. For example, in the case of `lv_obj_set_x` *unit* is pixels so *20* means *20 px/sec* speed. + +## Delete animations + +You can delete an animation with `lv_anim_del(var, func)` if you provide the animated variable and its animator function. + +## Timeline +A timeline is a collection of multiple animations which makes it easy to create complex composite animations. + +Firstly, create an animation element but don’t call `lv_anim_start()`. + +Secondly, create an animation timeline object by calling `lv_anim_timeline_create()`. + +Thirdly, add animation elements to the animation timeline by calling `lv_anim_timeline_add(at, start_time, &a)`. `start_time` is the start time of the animation on the timeline. Note that `start_time` will override the value of `delay`. + +Finally, call `lv_anim_timeline_start(at)` to start the animation timeline. + +It supports forward and backward playback of the entire animation group, using `lv_anim_timeline_set_reverse(at, reverse)`. + +Call `lv_anim_timeline_stop(at)` to stop the animation timeline. + +Call `lv_anim_timeline_set_progress(at, progress)` function to set the state of the object corresponding to the progress of the timeline. + +Call `lv_anim_timeline_get_playtime(at)` function to get the total duration of the entire animation timeline. + +Call `lv_anim_timeline_get_reverse(at)` function to get whether to reverse the animation timeline. + +Call `lv_anim_timeline_del(at)` function to delete the animation timeline. + + + +## Examples + +```eval_rst + +.. include:: ../../examples/anim/index.rst + +``` +## API + +```eval_rst + +.. doxygenfile:: lv_anim.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/overview/color.md b/lib/lvgl/docs/overview/color.md new file mode 100644 index 00000000..0ee97da8 --- /dev/null +++ b/lib/lvgl/docs/overview/color.md @@ -0,0 +1,153 @@ +# Colors + +The color module handles all color-related functions like changing color depth, creating colors from hex code, converting between color depths, mixing colors, etc. + +The type `lv_color_t` is used to store a color. Its fields are set according to `LV_COLOR_DEPTH` in `lv_conf.h`. (See below) + +You may set `LV_COLOR_16_SWAP` in `lv_conf.h` to swap bytes of *RGB565* colors. You may need this when sending 16-bit colors via a byte-oriented interface like SPI. As 16-bit numbers are stored in little-endian format (lower byte at the lower address), the interface will send the lower byte first. However, displays usually need the higher byte first. A mismatch in the byte order will result in highly distorted colors. + +## Creating colors + +### RGB +Create colors from Red, Green and Blue channel values: +```c +//All channels are 0-255 +lv_color_t c = lv_color_make(red, green, blue); + +//From hex code 0x000000..0xFFFFFF interpreted as RED + GREEN + BLUE +lv_color_t c = lv_color_hex(0x123456); + +//From 3 digits. Same as lv_color_hex(0x112233) +lv_color_t c = lv_color_hex3(0x123); +``` + +### HSV +Create colors from Hue, Saturation and Value values: + +```c +//h = 0..359, s = 0..100, v = 0..100 +lv_color_t c = lv_color_hsv_to_rgb(h, s, v); + +//All channels are 0-255 +lv_color_hsv_t c_hsv = lv_color_rgb_to_hsv(r, g, b); + + +//From lv_color_t variable +lv_color_hsv_t c_hsv = lv_color_to_hsv(color); +``` + +### Palette +LVGL includes [Material Design's palette](https://vuetifyjs.com/en/styles/colors/#material-colors) of colors. In this system all named colors have a nominal main color as well as four darker and five lighter variants. + +The names of the colors are as follows: +- `LV_PALETTE_RED` +- `LV_PALETTE_PINK` +- `LV_PALETTE_PURPLE` +- `LV_PALETTE_DEEP_PURPLE` +- `LV_PALETTE_INDIGO` +- `LV_PALETTE_BLUE` +- `LV_PALETTE_LIGHT_BLUE` +- `LV_PALETTE_CYAN` +- `LV_PALETTE_TEAL` +- `LV_PALETTE_GREEN` +- `LV_PALETTE_LIGHT_GREEN` +- `LV_PALETTE_LIME` +- `LV_PALETTE_YELLOW` +- `LV_PALETTE_AMBER` +- `LV_PALETTE_ORANGE` +- `LV_PALETTE_DEEP_ORANGE` +- `LV_PALETTE_BROWN` +- `LV_PALETTE_BLUE_GREY` +- `LV_PALETTE_GREY` + + +To get the main color use `lv_color_t c = lv_palette_main(LV_PALETTE_...)`. + +For the lighter variants of a palette color use `lv_color_t c = lv_palette_lighten(LV_PALETTE_..., v)`. `v` can be 1..5. +For the darker variants of a palette color use `lv_color_t c = lv_palette_darken(LV_PALETTE_..., v)`. `v` can be 1..4. + +### Modify and mix colors +The following functions can modify a color: +```c +// Lighten a color. 0: no change, 255: white +lv_color_t c = lv_color_lighten(c, lvl); + +// Darken a color. 0: no change, 255: black +lv_color_t c = lv_color_darken(lv_color_t c, lv_opa_t lvl); + +// Lighten or darken a color. 0: black, 128: no change 255: white +lv_color_t c = lv_color_change_lightness(lv_color_t c, lv_opa_t lvl); + + +// Mix two colors with a given ratio 0: full c2, 255: full c1, 128: half c1 and half c2 +lv_color_t c = lv_color_mix(c1, c2, ratio); +``` + +### Built-in colors +`lv_color_white()` and `lv_color_black()` return `0xFFFFFF` and `0x000000` respectively. + +## Opacity +To describe opacity the `lv_opa_t` type is created from `uint8_t`. Some special purpose defines are also introduced: + +- `LV_OPA_TRANSP` Value: 0, means no opacity making the color completely transparent +- `LV_OPA_10` Value: 25, means the color covers only a little +- `LV_OPA_20 ... OPA_80` follow logically +- `LV_OPA_90` Value: 229, means the color near completely covers +- `LV_OPA_COVER` Value: 255, means the color completely covers (full opacity) + +You can also use the `LV_OPA_*` defines in `lv_color_mix()` as a mixing *ratio*. + + +## Color types +The following variable types are defined by the color module: + +- `lv_color1_t` Monochrome color. Also has R, G, B fields for compatibility but they are always the same value (1 byte) +- `lv_color8_t` A structure to store R (3 bit),G (3 bit),B (2 bit) components for 8-bit colors (1 byte) +- `lv_color16_t` A structure to store R (5 bit),G (6 bit),B (5 bit) components for 16-bit colors (2 byte) +- `lv_color32_t` A structure to store R (8 bit),G (8 bit), B (8 bit) components for 24-bit colors (4 byte) +- `lv_color_t` Equal to `lv_color1/8/16/24_t` depending on the configured color depth setting +- `lv_color_int_t` `uint8_t`, `uint16_t` or `uint32_t` depending on the color depth setting. Used to build color arrays from plain numbers. +- `lv_opa_t` A simple `uint8_t` type to describe opacity. + +The `lv_color_t`, `lv_color1_t`, `lv_color8_t`, `lv_color16_t` and `lv_color32_t` types have four fields: + +- `ch.red` red channel +- `ch.green` green channel +- `ch.blue` blue channel +- `full*` red + green + blue as one number + +You can set the current color depth in *lv_conf.h*, by setting the `LV_COLOR_DEPTH` define to 1 (monochrome), 8, 16 or 32. + + +### Convert color +You can convert a color from the current color depth to another. The converter functions return with a number, so you have to use the `full` field to map a converted color back into a structure: + +```c +lv_color_t c; +c.red = 0x38; +c.green = 0x70; +c.blue = 0xCC; + +lv_color1_t c1; +c1.full = lv_color_to1(c); /*Return 1 for light colors, 0 for dark colors*/ + +lv_color8_t c8; +c8.full = lv_color_to8(c); /*Give a 8 bit number with the converted color*/ + +lv_color16_t c16; +c16.full = lv_color_to16(c); /*Give a 16 bit number with the converted color*/ + +lv_color32_t c24; +c32.full = lv_color_to32(c); /*Give a 32 bit number with the converted color*/ +``` + + +## API + + +```eval_rst + +.. doxygenfile:: lv_color.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/overview/coords.md b/lib/lvgl/docs/overview/coords.md new file mode 100644 index 00000000..5d56750d --- /dev/null +++ b/lib/lvgl/docs/overview/coords.md @@ -0,0 +1,363 @@ +# Positions, sizes, and layouts + +## Overview +Similarly to many other parts of LVGL, the concept of setting the coordinates was inspired by CSS. LVGL has by no means a complete implementation of CSS but a comparable subset is implemented (sometimes with minor adjustments). + +In short this means: +- Explicitly set coordinates are stored in styles (size, position, layouts, etc.) +- support min-width, max-width, min-height, max-height +- have pixel, percentage, and "content" units +- x=0; y=0 coordinate means the top-left corner of the parent plus the left/top padding plus border width +- width/height means the full size, the "content area" is smaller with padding and border width +- a subset of flexbox and grid layouts are supported + +### Units +- pixel: Simply a position in pixels. An integer always means pixels. E.g. `lv_obj_set_x(btn, 10)` +- percentage: The percentage of the size of the object or its parent (depending on the property). `lv_pct(value)` converts a value to percentage. E.g. `lv_obj_set_width(btn, lv_pct(50))` +- `LV_SIZE_CONTENT`: Special value to set the width/height of an object to involve all the children. It's similar to `auto` in CSS. E.g. `lv_obj_set_width(btn, LV_SIZE_CONTENT)`. + +### Boxing model +LVGL follows CSS's [border-box](https://developer.mozilla.org/en-US/docs/Web/CSS/box-sizing) model. +An object's "box" is built from the following parts: +- bounding box: the width/height of the elements. +- border width: the width of the border. +- padding: space between the sides of the object and its children. +- content: the content area which is the size of the bounding box reduced by the border width and padding. + + + +The border is drawn inside the bounding box. Inside the border LVGL keeps a "padding margin" when placing an object's children. + +The outline is drawn outside the bounding box. + +### Important notes +This section describes special cases in which LVGL's behavior might be unexpected. + +#### Postponed coordinate calculation +LVGL doesn't recalculate all the coordinate changes immediately. This is done to improve performance. +Instead, the objects are marked as "dirty" and before redrawing the screen LVGL checks if there are any "dirty" objects. If so it refreshes their position, size and layout. + +In other words, if you need to get the coordinate of an object and the coordinates were just changed, LVGL needs to be forced to recalculate the coordinates. +To do this call `lv_obj_update_layout(obj)`. + +The size and position might depend on the parent or layout. Therefore `lv_obj_update_layout` recalculates the coordinates of all objects on the screen of `obj`. + +#### Removing styles +As it's described in the [Using styles](#using-styles) section, coordinates can also be set via style properties. +To be more precise, under the hood every style coordinate related property is stored as a style property. If you use `lv_obj_set_x(obj, 20)` LVGL saves `x=20` in the local style of the object. + +This is an internal mechanism and doesn't matter much as you use LVGL. However, there is one case in which you need to be aware of the implementation. If the style(s) of an object are removed by +```c +lv_obj_remove_style_all(obj) +``` + +or +```c +lv_obj_remove_style(obj, NULL, LV_PART_MAIN); +``` +the earlier set coordinates will be removed as well. + +For example: +```c +/*The size of obj1 will be set back to the default in the end*/ +lv_obj_set_size(obj1, 200, 100); /*Now obj1 has 200;100 size*/ +lv_obj_remove_style_all(obj1); /*It removes the set sizes*/ + + +/*obj2 will have 200;100 size in the end */ +lv_obj_remove_style_all(obj2); +lv_obj_set_size(obj2, 200, 100); +``` + +## Position + +### Simple way +To simply set the x and y coordinates of an object use: +```c +lv_obj_set_x(obj, 10); //Separate... +lv_obj_set_y(obj, 20); +lv_obj_set_pos(obj, 10, 20); //Or in one function +``` + +By default, the x and y coordinates are measured from the top left corner of the parent's content area. +For example if the parent has five pixels of padding on every side the above code will place `obj` at (15, 25) because the content area starts after the padding. + +Percentage values are calculated from the parent's content area size. +```c +lv_obj_set_x(btn, lv_pct(10)); //x = 10 % of parent content area width +``` + +### Align +In some cases it's convenient to change the origin of the positioning from the default top left. If the origin is changed e.g. to bottom-right, the (0,0) position means: align to the bottom-right corner. +To change the origin use: +```c +lv_obj_set_align(obj, align); +``` + +To change the alignment and set new coordinates: +```c +lv_obj_align(obj, align, x, y); +``` + +The following alignment options can be used: +- `LV_ALIGN_TOP_LEFT` +- `LV_ALIGN_TOP_MID` +- `LV_ALIGN_TOP_RIGHT` +- `LV_ALIGN_BOTTOM_LEFT` +- `LV_ALIGN_BOTTOM_MID` +- `LV_ALIGN_BOTTOM_RIGHT` +- `LV_ALIGN_LEFT_MID` +- `LV_ALIGN_RIGHT_MID` +- `LV_ALIGN_CENTER` + +It's quite common to align a child to the center of its parent, therefore a dedicated function exists: +```c +lv_obj_center(obj); + +//Has the same effect +lv_obj_align(obj, LV_ALIGN_CENTER, 0, 0); +``` + +If the parent's size changes, the set alignment and position of the children is updated automatically. + +The functions introduced above align the object to its parent. However, it's also possible to align an object to an arbitrary reference object. +```c +lv_obj_align_to(obj_to_align, reference_obj, align, x, y); +``` + +Besides the alignments options above, the following can be used to align an object outside the reference object: + +- `LV_ALIGN_OUT_TOP_LEFT` +- `LV_ALIGN_OUT_TOP_MID` +- `LV_ALIGN_OUT_TOP_RIGHT` +- `LV_ALIGN_OUT_BOTTOM_LEFT` +- `LV_ALIGN_OUT_BOTTOM_MID` +- `LV_ALIGN_OUT_BOTTOM_RIGHT` +- `LV_ALIGN_OUT_LEFT_TOP` +- `LV_ALIGN_OUT_LEFT_MID` +- `LV_ALIGN_OUT_LEFT_BOTTOM` +- `LV_ALIGN_OUT_RIGHT_TOP` +- `LV_ALIGN_OUT_RIGHT_MID` +- `LV_ALIGN_OUT_RIGHT_BOTTOM` + +For example to align a label above a button and center the label horizontally: +```c +lv_obj_align_to(label, btn, LV_ALIGN_OUT_TOP_MID, 0, -10); +``` + +Note that, unlike with `lv_obj_align()`, `lv_obj_align_to()` can not realign the object if its coordinates or the reference object's coordinates change. + +## Size + +### Simple way +The width and the height of an object can be set easily as well: +```c +lv_obj_set_width(obj, 200); //Separate... +lv_obj_set_height(obj, 100); +lv_obj_set_size(obj, 200, 100); //Or in one function +``` + +Percentage values are calculated based on the parent's content area size. For example to set the object's height to the screen height: +```c +lv_obj_set_height(obj, lv_pct(100)); +``` + +The size settings support a special value: `LV_SIZE_CONTENT`. It means the object's size in the respective direction will be set to the size of its children. +Note that only children on the right and bottom sides will be considered and children on the top and left remain cropped. This limitation makes the behavior more predictable. + +Objects with `LV_OBJ_FLAG_HIDDEN` or `LV_OBJ_FLAG_FLOATING` will be ignored by the `LV_SIZE_CONTENT` calculation. + +The above functions set the size of an object's bounding box but the size of the content area can be set as well. This means an object's bounding box will be enlarged with the addition of padding. +```c +lv_obj_set_content_width(obj, 50); //The actual width: padding left + 50 + padding right +lv_obj_set_content_height(obj, 30); //The actual width: padding top + 30 + padding bottom +``` + +The size of the bounding box and the content area can be retrieved with the following functions: +```c +lv_coord_t w = lv_obj_get_width(obj); +lv_coord_t h = lv_obj_get_height(obj); +lv_coord_t content_w = lv_obj_get_content_width(obj); +lv_coord_t content_h = lv_obj_get_content_height(obj); +``` + +## Using styles +Under the hood the position, size and alignment properties are style properties. +The above described "simple functions" hide the style related code for the sake of simplicity and set the position, size, and alignment properties in the local styles of the object. + +However, using styles to set the coordinates has some great advantages: +- It makes it easy to set the width/height/etc. for several objects together. E.g. make all the sliders 100x10 pixels sized. +- It also makes possible to modify the values in one place. +- The values can be partially overwritten by other styles. For example `style_btn` makes the object `100x50` by default but adding `style_full_width` overwrites only the width of the object. +- The object can have different position or size depending on state. E.g. 100 px wide in `LV_STATE_DEFAULT` but 120 px in `LV_STATE_PRESSED`. +- Style transitions can be used to make the coordinate changes smooth. + + +Here are some examples to set an object's size using a style: +```c +static lv_style_t style; +lv_style_init(&style); +lv_style_set_width(&style, 100); + +lv_obj_t * btn = lv_btn_create(lv_scr_act()); +lv_obj_add_style(btn, &style, LV_PART_MAIN); +``` + +As you will see below there are some other great features of size and position setting. +However, to keep the LVGL API lean, only the most common coordinate setting features have a "simple" version and the more complex features can be used via styles. + +## Translation + +Let's say the there are 3 buttons next to each other. Their position is set as described above. +Now you want to move a button up a little when it's pressed. + +One way to achieve this is by setting a new Y coordinate for the pressed state: +```c +static lv_style_t style_normal; +lv_style_init(&style_normal); +lv_style_set_y(&style_normal, 100); + +static lv_style_t style_pressed; +lv_style_init(&style_pressed); +lv_style_set_y(&style_pressed, 80); + +lv_obj_add_style(btn1, &style_normal, LV_STATE_DEFAULT); +lv_obj_add_style(btn1, &style_pressed, LV_STATE_PRESSED); + +lv_obj_add_style(btn2, &style_normal, LV_STATE_DEFAULT); +lv_obj_add_style(btn2, &style_pressed, LV_STATE_PRESSED); + +lv_obj_add_style(btn3, &style_normal, LV_STATE_DEFAULT); +lv_obj_add_style(btn3, &style_pressed, LV_STATE_PRESSED); +``` + +This works, but it's not really flexible because the pressed coordinate is hard-coded. If the buttons are not at y=100, `style_pressed` won't work as expected. Translations can be used to solve this: +```c +static lv_style_t style_normal; +lv_style_init(&style_normal); +lv_style_set_y(&style_normal, 100); + +static lv_style_t style_pressed; +lv_style_init(&style_pressed); +lv_style_set_translate_y(&style_pressed, -20); + +lv_obj_add_style(btn1, &style_normal, LV_STATE_DEFAULT); +lv_obj_add_style(btn1, &style_pressed, LV_STATE_PRESSED); + +lv_obj_add_style(btn2, &style_normal, LV_STATE_DEFAULT); +lv_obj_add_style(btn2, &style_pressed, LV_STATE_PRESSED); + +lv_obj_add_style(btn3, &style_normal, LV_STATE_DEFAULT); +lv_obj_add_style(btn3, &style_pressed, LV_STATE_PRESSED); +``` + +Translation is applied from the current position of the object. + +Percentage values can be used in translations as well. The percentage is relative to the size of the object (and not to the size of the parent). For example `lv_pct(50)` will move the object with half of its width/height. + +The translation is applied after the layouts are calculated. Therefore, even laid out objects' position can be translated. + +The translation actually moves the object. That means it makes the scrollbars and `LV_SIZE_CONTENT` sized objects react to the position change. + + +## Transformation +Similarly to position, an object's size can be changed relative to the current size as well. +The transformed width and height are added on both sides of the object. This means a 10 px transformed width makes the object 2x10 pixels wider. + +Unlike position translation, the size transformation doesn't make the object "really" larger. In other words scrollbars, layouts, and `LV_SIZE_CONTENT` will not react to the transformed size. +Hence, size transformation is "only" a visual effect. + +This code enlarges a button when it's pressed: +```c +static lv_style_t style_pressed; +lv_style_init(&style_pressed); +lv_style_set_transform_width(&style_pressed, 10); +lv_style_set_transform_height(&style_pressed, 10); + +lv_obj_add_style(btn, &style_pressed, LV_STATE_PRESSED); +``` + +### Min and Max size +Similarly to CSS, LVGL also supports `min-width`, `max-width`, `min-height` and `max-height`. These are limits preventing an object's size from becoming smaller/larger than these values. +They are especially useful if the size is set by percentage or `LV_SIZE_CONTENT`. +```c +static lv_style_t style_max_height; +lv_style_init(&style_max_height); +lv_style_set_y(&style_max_height, 200); + +lv_obj_set_height(obj, lv_pct(100)); +lv_obj_add_style(obj, &style_max_height, LV_STATE_DEFAULT); //Limit the height to 200 px +``` + +Percentage values can be used as well which are relative to the size of the parent's content area. +```c +static lv_style_t style_max_height; +lv_style_init(&style_max_height); +lv_style_set_y(&style_max_height, lv_pct(50)); + +lv_obj_set_height(obj, lv_pct(100)); +lv_obj_add_style(obj, &style_max_height, LV_STATE_DEFAULT); //Limit the height to half parent height +``` + +## Layout + +### Overview +Layouts can update the position and size of an object's children. They can be used to automatically arrange the children into a line or column, or in much more complicated forms. + +The position and size set by the layout overwrites the "normal" x, y, width, and height settings. + +There is only one function that is the same for every layout: `lv_obj_set_layout(obj, <LAYOUT_NAME>)` sets the layout on an object. +For further settings of the parent and children see the documentation of the given layout. + +### Built-in layout +LVGL comes with two very powerful layouts: +- Flexbox +- Grid + +Both are heavily inspired by the CSS layouts with the same name. + +### Flags +There are some flags that can be used on objects to affect how they behave with layouts: +- `LV_OBJ_FLAG_HIDDEN` Hidden objects are ignored in layout calculations. +- `LV_OBJ_FLAG_IGNORE_LAYOUT` The object is simply ignored by the layouts. Its coordinates can be set as usual. +- `LV_OBJ_FLAG_FLOATING` Same as `LV_OBJ_FLAG_IGNORE_LAYOUT` but the object with `LV_OBJ_FLAG_FLOATING` will be ignored in `LV_SIZE_CONTENT` calculations. + +These flags can be added/removed with `lv_obj_add/clear_flag(obj, FLAG);` + +### Adding new layouts + +LVGL can be freely extended by a custom layout like this: +```c +uint32_t MY_LAYOUT; + +... + +MY_LAYOUT = lv_layout_register(my_layout_update, &user_data); + +... + +void my_layout_update(lv_obj_t * obj, void * user_data) +{ + /*Will be called automatically if it's required to reposition/resize the children of "obj" */ +} +``` + +Custom style properties can be added which can be retrieved and used in the update callback. For example: +```c +uint32_t MY_PROP; +... + +LV_STYLE_MY_PROP = lv_style_register_prop(); + +... +static inline void lv_style_set_my_prop(lv_style_t * style, uint32_t value) +{ + lv_style_value_t v = { + .num = (int32_t)value + }; + lv_style_set_prop(style, LV_STYLE_MY_PROP, v); +} + +``` + +## Examples diff --git a/lib/lvgl/docs/overview/display.md b/lib/lvgl/docs/overview/display.md new file mode 100644 index 00000000..b756b77e --- /dev/null +++ b/lib/lvgl/docs/overview/display.md @@ -0,0 +1,103 @@ +# Displays + +``` important:: The basic concept of a *display* in LVGL is explained in the [Porting](/porting/display) section. So before reading further, please read the [Porting](/porting/display) section first. +``` + +## Multiple display support + +In LVGL you can have multiple displays, each with their own driver and objects. The only limitation is that every display needs to have the same color depth (as defined in `LV_COLOR_DEPTH`). +If the displays are different in this regard the rendered image can be converted to the correct format in the drivers `flush_cb`. + +Creating more displays is easy: just initialize more display buffers and register another driver for every display. +When you create the UI, use `lv_disp_set_default(disp)` to tell the library on which display to create objects. + +Why would you want multi-display support? Here are some examples: +- Have a "normal" TFT display with local UI and create "virtual" screens on VNC on demand. (You need to add your VNC driver). +- Have a large TFT display and a small monochrome display. +- Have some smaller and simple displays in a large instrument or technology. +- Have two large TFT displays: one for a customer and one for the shop assistant. + +### Using only one display +Using more displays can be useful but in most cases it's not required. Therefore, the whole concept of multi-display handling is completely hidden if you register only one display. +By default, the last created (and only) display is used. + +`lv_scr_act()`, `lv_scr_load(scr)`, `lv_layer_top()`, `lv_layer_sys()`, `LV_HOR_RES` and `LV_VER_RES` are always applied on the most recently created (default) display. +If you pass `NULL` as `disp` parameter to display related functions the default display will usually be used. +E.g. `lv_disp_trig_activity(NULL)` will trigger a user activity on the default display. (See below in [Inactivity](#Inactivity)). + +### Mirror display + +To mirror the image of a display to another display, you don't need to use multi-display support. Just transfer the buffer received in `drv.flush_cb` to the other display too. + +### Split image +You can create a larger virtual display from an array of smaller ones. You can create it as below: +1. Set the resolution of the displays to the large display's resolution. +2. In `drv.flush_cb`, truncate and modify the `area` parameter for each display. +3. Send the buffer's content to each real display with the truncated area. + +## Screens + +Every display has its own set of [screens](overview/object#screen-the-most-basic-parent) and the objects on each screen. + +Be sure not to confuse displays and screens: + +* **Displays** are the physical hardware drawing the pixels. +* **Screens** are the high-level root objects associated with a particular display. One display can have multiple screens associated with it, but not vice versa. + +Screens can be considered the highest level containers which have no parent. +A screen's size is always equal to its display and their origin is (0;0). Therefore, a screen's coordinates can't be changed, i.e. `lv_obj_set_pos()`, `lv_obj_set_size()` or similar functions can't be used on screens. + +A screen can be created from any object type but the two most typical types are [Base object](/widgets/obj) and [Image](/widgets/core/img) (to create a wallpaper). + +To create a screen, use `lv_obj_t * scr = lv_<type>_create(NULL, copy)`. `copy` can be an existing screen copied into the new screen. + +To load a screen, use `lv_scr_load(scr)`. To get the active screen, use `lv_scr_act()`. These functions work on the default display. If you want to specify which display to work on, use `lv_disp_get_scr_act(disp)` and `lv_disp_load_scr(disp, scr)`. A screen can be loaded with animations too. Read more [here](object.html#load-screens). + +Screens can be deleted with `lv_obj_del(scr)`, but ensure that you do not delete the currently loaded screen. + +### Transparent screens + +Usually, the opacity of the screen is `LV_OPA_COVER` to provide a solid background for its children. If this is not the case (opacity < 100%) the display's background color or image will be visible. +See the [Display background](#display-background) section for more details. If the display's background opacity is also not `LV_OPA_COVER` LVGL has no solid background to draw. + +This configuration (transparent screen and display) could be used to create for example OSD menus where a video is played on a lower layer, and a menu is overlayed on an upper layer. + +To handle transparent displays, special (slower) color mixing algorithms need to be used by LVGL so this feature needs to enabled with `LV_COLOR_SCREEN_TRANSP` in `lv_conf.h`. +The Alpha channel of 32-bit colors will be 0 where there are no objects and 255 where there are solid objects. + +In summary, to enable transparent screens and displays for OSD menu-like UIs: +- Enable `LV_COLOR_SCREEN_TRANSP` in `lv_conf.h` +- Set the screen's opacity to `LV_OPA_TRANSP` e.g. with `lv_obj_set_style_local_bg_opa(lv_scr_act(), LV_OBJMASK_PART_MAIN, LV_STATE_DEFAULT, LV_OPA_TRANSP)` +- Set the display opacity to `LV_OPA_TRANSP` with `lv_disp_set_bg_opa(NULL, LV_OPA_TRANSP);` + +## Features of displays + +### Inactivity + +A user's inactivity time is measured on each display. Every use of an [Input device](/overview/indev) (if [associated with the display](/porting/indev#other-features)) counts as an activity. +To get time elapsed since the last activity, use `lv_disp_get_inactive_time(disp)`. If `NULL` is passed, the lowest inactivity time among all displays will be returned (**NULL isn't just the default display**). + +You can manually trigger an activity using `lv_disp_trig_activity(disp)`. If `disp` is `NULL`, the default screen will be used (**and not all displays**). + +### Background +Every display has a background color, background image and background opacity properties. They become visible when the current screen is transparent or not positioned to cover the whole display. + +The background color is a simple color to fill the display. It can be adjusted with `lv_disp_set_bg_color(disp, color)`; + +The display background image is a path to a file or a pointer to an `lv_img_dsc_t` variable (converted image data) to be used as wallpaper. It can be set with `lv_disp_set_bg_image(disp, &my_img)`; +If a background image is configured the background won't be filled with `bg_color`. + +The opacity of the background color or image can be adjusted with `lv_disp_set_bg_opa(disp, opa)`. + +The `disp` parameter of these functions can be `NULL` to select the default display. + + + +## API + +```eval_rst + +.. doxygenfile:: lv_disp.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/overview/drawing.md b/lib/lvgl/docs/overview/drawing.md new file mode 100644 index 00000000..d1b2d7a0 --- /dev/null +++ b/lib/lvgl/docs/overview/drawing.md @@ -0,0 +1,221 @@ +# Drawing + +With LVGL, you don't need to draw anything manually. Just create objects (like buttons, labels, arc, etc.), move and change them, and LVGL will refresh and redraw what is required. + +However, it can be useful to have a basic understanding of how drawing happens in LVGL to add customization, make it easier to find bugs or just out of curiosity. + +The basic concept is to not draw directly onto the display but rather to first draw on an internal draw buffer. When a drawing (rendering) is ready that buffer is copied to the display. + +The draw buffer can be smaller than a display's size. LVGL will simply render in "tiles" that fit into the given draw buffer. + +This approach has two main advantages compared to directly drawing to the display: +1. It avoids flickering while the layers of the UI are drawn. For example, if LVGL drew directly onto the display, when drawing a *background + button + text*, each "stage" would be visible for a short time. +2. It's faster to modify a buffer in internal RAM and finally write one pixel only once than reading/writing the display directly on each pixel access. +(e.g. via a display controller with SPI interface). + +Note that this concept is different from "traditional" double buffering where there are two display sized frame buffers: +one holds the current image to show on the display, and rendering happens to the other (inactive) frame buffer, and they are swapped when the rendering is finished. +The main difference is that with LVGL you don't have to store two frame buffers (which usually requires external RAM) but only smaller draw buffer(s) that can easily fit into internal RAM. + + +## Mechanism of screen refreshing + +Be sure to get familiar with the [Buffering modes of LVGL](/porting/display) first. + +LVGL refreshes the screen in the following steps: +1. Something happens in the UI which requires redrawing. For example, a button is pressed, a chart is changed, an animation happened, etc. +2. LVGL saves the changed object's old and new area into a buffer, called an *Invalid area buffer*. For optimization, in some cases, objects are not added to the buffer: + - Hidden objects are not added. + - Objects completely out of their parent are not added. + - Areas partially out of the parent are cropped to the parent's area. + - Objects on other screens are not added. +3. In every `LV_DISP_DEF_REFR_PERIOD` (set in `lv_conf.h`) the following happens: + - LVGL checks the invalid areas and joins those that are adjacent or intersecting. + - Takes the first joined area, if it's smaller than the *draw buffer*, then simply renders the area's content into the *draw buffer*. + If the area doesn't fit into the buffer, draw as many lines as possible to the *draw buffer*. + - When the area is rendered, call `flush_cb` from the display driver to refresh the display. + - If the area was larger than the buffer, render the remaining parts too. + - Repeat the same with remaining joined areas. + +When an area is redrawn the library searches the top-most object which covers that area and starts drawing from that object. +For example, if a button's label has changed, the library will see that it's enough to draw the button under the text and it's not necessary to redraw the display under the rest of the button too. + +The difference between buffering modes regarding the drawing mechanism is the following: +1. **One buffer** - LVGL needs to wait for `lv_disp_flush_ready()` (called from `flush_cb`) before starting to redraw the next part. +2. **Two buffers** - LVGL can immediately draw to the second buffer when the first is sent to `flush_cb` because the flushing should be done by DMA (or similar hardware) in the background. +3. **Double buffering** - `flush_cb` should only swap the addresses of the frame buffers. + +## Masking +*Masking* is the basic concept of LVGL's draw engine. +To use LVGL it's not required to know about the mechanisms described here but you might find interesting to know how drawing works under hood. +Knowing about masking comes in handy if you want to customize drawing. + +To learn about masking let's see the steps of drawing first. +LVGL performs the following steps to render any shape, image or text. It can be considered as a drawing pipeline. + +1. **Prepare the draw descriptors** Create a draw descriptor from an object's styles (e.g. `lv_draw_rect_dsc_t`). This gives us the parameters for drawing, for example colors, widths, opacity, fonts, radius, etc. +2. **Call the draw function** Call the draw function with the draw descriptor and some other parameters (e.g. `lv_draw_rect()`). It will render the primitive shape to the current draw buffer. +3. **Create masks** If the shape is very simple and doesn't require masks, go to #5. Otherwise, create the required masks in the draw function. (e.g. a rounded rectangle mask) +4. **Calculate all the added mask** It composites opacity values into a *mask buffer* with the "shape" of the created masks. +E.g. in case of a "line mask" according to the parameters of the mask, keep one side of the buffer as it is (255 by default) and set the rest to 0 to indicate that this side should be removed. +5. **Blend a color or image** During blending, masking (make some pixels transparent or opaque), blending modes (additive, subtractive, etc.) and color/image opacity are handled. + +LVGL has the following built-in mask types which can be calculated and applied real-time: +- `LV_DRAW_MASK_TYPE_LINE` Removes a side from a line (top, bottom, left or right). `lv_draw_line` uses four instances of it. +Essentially, every (skew) line is bounded with four line masks forming a rectangle. +- `LV_DRAW_MASK_TYPE_RADIUS` Removes the inner or outer corners of a rectangle with a radiused transition. It's also used to create circles by setting the radius to large value (`LV_RADIUS_CIRCLE`) +- `LV_DRAW_MASK_TYPE_ANGLE` Removes a circular sector. It is used by `lv_draw_arc` to remove the "empty" sector. +- `LV_DRAW_MASK_TYPE_FADE` Create a vertical fade (change opacity) +- `LV_DRAW_MASK_TYPE_MAP` The mask is stored in a bitmap array and the necessary parts are applied + +Masks are used to create almost every basic primitive: +- **letters** Create a mask from the letter and draw a rectangle with the letter's color using the mask. +- **line** Created from four "line masks" to mask out the left, right, top and bottom part of the line to get a perfectly perpendicular perimeter. +- **rounded rectangle** A mask is created real-time to add a radius to the corners. +- **clip corner** To clip overflowing content (usually children) on rounded corners, a rounded rectangle mask is also applied. +- **rectangle border** Same as a rounded rectangle but the inner part is masked out too. +- **arc drawing** A circular border is drawn but an arc mask is applied too. +- **ARGB images** The alpha channel is separated into a mask and the image is drawn as a normal RGB image. + +### Using masks + +Every mask type has a related parameter structure to describe the mask's data. The following parameter types exist: +- `lv_draw_mask_line_param_t` +- `lv_draw_mask_radius_param_t` +- `lv_draw_mask_angle_param_t` +- `lv_draw_mask_fade_param_t` +- `lv_draw_mask_map_param_t` + +1. Initialize a mask parameter with `lv_draw_mask_<type>_init`. See `lv_draw_mask.h` for the whole API. +2. Add the mask parameter to the draw engine with `int16_t mask_id = lv_draw_mask_add(¶m, ptr)`. `ptr` can be any pointer to identify the mask, (`NULL` if unused). +3. Call the draw functions +4. Remove the mask from the draw engine with `lv_draw_mask_remove_id(mask_id)` or `lv_draw_mask_remove_custom(ptr)`. +5. Free the parameter with `lv_draw_mask_free_param(¶m)`. + +A parameter can be added and removed any number of times, but it needs to be freed when not required anymore. + +`lv_draw_mask_add` saves only the pointer of the mask so the parameter needs to be valid while in use. + +## Hook drawing +Although widgets can be easily customized by styles there might be cases when something more custom is required. +To ensure a great level of flexibility LVGL sends a lot of events during drawing with parameters that tell what LVGL is about to draw. +Some fields of these parameters can be modified to draw something else or any custom drawing operations can be added manually. + +A good use case for this is the [Button matrix](/widgets/core/btnmatrix) widget. By default, its buttons can be styled in different states, but you can't style the buttons one by one. +However, an event is sent for every button and you can, for example, tell LVGL to use different colors on a specific button or to manually draw an image on some buttons. + +Each of these events is described in detail below. + +### Main drawing + +These events are related to the actual drawing of an object. E.g. the drawing of buttons, texts, etc. happens here. + +`lv_event_get_clip_area(event)` can be used to get the current clip area. The clip area is required in draw functions to make them draw only on a limited area. + +#### LV_EVENT_DRAW_MAIN_BEGIN + +Sent before starting to draw an object. This is a good place to add masks manually. E.g. add a line mask that "removes" the right side of an object. + +#### LV_EVENT_DRAW_MAIN + +The actual drawing of an object happens in this event. E.g. a rectangle for a button is drawn here. First, the widgets' internal events are called to perform drawing and after that you can draw anything on top of them. +For example you can add a custom text or an image. + +#### LV_EVENT_DRAW_MAIN_END + +Called when the main drawing is finished. You can draw anything here as well and it's also a good place to remove any masks created in `LV_EVENT_DRAW_MAIN_BEGIN`. + +### Post drawing + +Post drawing events are called when all the children of an object are drawn. For example LVGL use the post drawing phase to draw scrollbars because they should be above all of the children. + +`lv_event_get_clip_area(event)` can be used to get the current clip area. + +#### LV_EVENT_DRAW_POST_BEGIN + +Sent before starting the post draw phase. Masks can be added here too to mask out the post drawn content. + +#### LV_EVENT_DRAW_POST + +The actual drawing should happen here. + +#### LV_EVENT_DRAW_POST_END + +Called when post drawing has finished. If masks were not removed in `LV_EVENT_DRAW_MAIN_END` they should be removed here. + +### Part drawing + +When LVGL draws a part of an object (e.g. a slider's indicator, a table's cell or a button matrix's button) it sends events before and after drawing that part with some context of the drawing. +This allows changing the parts on a very low level with masks, extra drawing, or changing the parameters that LVGL is planning to use for drawing. + +In these events an `lv_obj_draw_part_t` structure is used to describe the context of the drawing. Not all fields are set for every part and widget. +To see which fields are set for a widget refer to the widget's documentation. + +`lv_obj_draw_part_t` has the following fields: + +```c +// Always set +const lv_area_t * clip_area; // The current clip area, required if you need to draw something in the event +uint32_t part; // The current part for which the event is sent +uint32_t id; // The index of the part. E.g. a button's index on button matrix or table cell index. + +// Draw desciptors, set only if related +lv_draw_rect_dsc_t * rect_dsc; // A draw descriptor that can be modified to changed what LVGL will draw. Set only for rectangle-like parts +lv_draw_label_dsc_t * label_dsc; // A draw descriptor that can be modified to changed what LVGL will draw. Set only for text-like parts +lv_draw_line_dsc_t * line_dsc; // A draw descriptor that can be modified to changed what LVGL will draw. Set only for line-like parts +lv_draw_img_dsc_t * img_dsc; // A draw descriptor that can be modified to changed what LVGL will draw. Set only for image-like parts +lv_draw_arc_dsc_t * arc_dsc; // A draw descriptor that can be modified to changed what LVGL will draw. Set only for arc-like parts + +// Other parameters +lv_area_t * draw_area; // The area of the part being drawn +const lv_point_t * p1; // A point calculated during drawing. E.g. a point of a chart or the center of an arc. +const lv_point_t * p2; // A point calculated during drawing. E.g. a point of a chart. +char text[16]; // A text calculated during drawing. Can be modified. E.g. tick labels on a chart axis. +lv_coord_t radius; // E.g. the radius of an arc (not the corner radius). +int32_t value; // A value calculated during drawing. E.g. Chart's tick line value. +const void * sub_part_ptr; // A pointer the identifies something in the part. E.g. chart series. +``` + +`lv_event_get_draw_part_dsc(event)` can be used to get a pointer to `lv_obj_draw_part_t`. + +#### LV_EVENT_DRAW_PART_BEGIN + +Start the drawing of a part. This is a good place to modify the draw descriptors (e.g. `rect_dsc`), or add masks. + +#### LV_EVENT_DRAW_PART_END + +Finish the drawing of a part. This is a good place to draw extra content on the part or remove masks added in `LV_EVENT_DRAW_PART_BEGIN`. + +### Others + +#### LV_EVENT_COVER_CHECK + +This event is used to check whether an object fully covers an area or not. + +`lv_event_get_cover_area(event)` returns a pointer to an area to check and `lv_event_set_cover_res(event, res)` can be used to set one of these results: +- `LV_COVER_RES_COVER` the area is fully covered by the object +- `LV_COVER_RES_NOT_COVER` the area is not covered by the object +- `LV_COVER_RES_MASKED` there is a mask on the object, so it does not fully cover the area + +Here are some reasons why an object would be unable to fully cover an area: +- It's simply not fully in area +- It has a radius +- It doesn't have 100% background opacity +- It's an ARGB or chroma keyed image +- It does not have normal blending mode. In this case LVGL needs to know the colors under the object to apply blending properly +- It's a text, etc + +In short if for any reason the area below an object is visible than the object doesn't cover that area. + +Before sending this event LVGL checks if at least the widget's coordinates fully cover the area or not. If not the event is not called. + +You need to check only the drawing you have added. The existing properties known by a widget are handled in its internal events. +E.g. if a widget has > 0 radius it might not cover an area, but you need to handle `radius` only if you will modify it and the widget won't know about it. + +#### LV_EVENT_REFR_EXT_DRAW_SIZE + +If you need to draw outside a widget, LVGL needs to know about it to provide extra space for drawing. +Let's say you create an event which writes the current value of a slider above its knob. In this case LVGL needs to know that the slider's draw area should be larger with the size required for the text. + +You can simply set the required draw area with `lv_event_set_ext_draw_size(e, size)`. + diff --git a/lib/lvgl/docs/overview/event.md b/lib/lvgl/docs/overview/event.md new file mode 100644 index 00000000..e6dd730a --- /dev/null +++ b/lib/lvgl/docs/overview/event.md @@ -0,0 +1,173 @@ +# Events + +Events are triggered in LVGL when something happens which might be interesting to the user, e.g. when an object +- is clicked +- is scrolled +- has its value changed +- is redrawn, etc. + +## Add events to the object + +The user can assign callback functions to an object to see its events. In practice, it looks like this: +```c +lv_obj_t * btn = lv_btn_create(lv_scr_act()); +lv_obj_add_event_cb(btn, my_event_cb, LV_EVENT_CLICKED, NULL); /*Assign an event callback*/ + +... + +static void my_event_cb(lv_event_t * event) +{ + printf("Clicked\n"); +} +``` +In the example `LV_EVENT_CLICKED` means that only the click event will call `my_event_cb`. See the [list of event codes](#event-codes) for all the options. +`LV_EVENT_ALL` can be used to receive all events. + +The last parameter of `lv_obj_add_event_cb` is a pointer to any custom data that will be available in the event. It will be described later in more detail. + +More events can be added to an object, like this: +```c +lv_obj_add_event_cb(obj, my_event_cb_1, LV_EVENT_CLICKED, NULL); +lv_obj_add_event_cb(obj, my_event_cb_2, LV_EVENT_PRESSED, NULL); +lv_obj_add_event_cb(obj, my_event_cb_3, LV_EVENT_ALL, NULL); /*No filtering, receive all events*/ +``` + +Even the same event callback can be used on an object with different `user_data`. For example: +```c +lv_obj_add_event_cb(obj, increment_on_click, LV_EVENT_CLICKED, &num1); +lv_obj_add_event_cb(obj, increment_on_click, LV_EVENT_CLICKED, &num2); +``` + +The events will be called in the order as they were added. + + +Other objects can use the same *event callback*. + + +## Remove event(s) from an object + +Events can be removed from an object with the `lv_obj_remove_event_cb(obj, event_cb)` function or `lv_obj_remove_event_dsc(obj, event_dsc)`. `event_dsc` is a pointer returned by `lv_obj_add_event_cb`. + +## Event codes + +The event codes can be grouped into these categories: +- Input device events +- Drawing events +- Other events +- Special events +- Custom events + +All objects (such as Buttons/Labels/Sliders etc.) regardless their type receive the *Input device*, *Drawing* and *Other* events. + +However, the *Special events* are specific to a particular widget type. See the [widgets' documentation](/widgets/index) to learn when they are sent, + +*Custom events* are added by the user and are never sent by LVGL. + +The following event codes exist: + +### Input device events +- `LV_EVENT_PRESSED` An object has been pressed +- `LV_EVENT_PRESSING` An object is being pressed (called continuously while pressing) +- `LV_EVENT_PRESS_LOST` An object is still being pressed but slid cursor/finger off of the object +- `LV_EVENT_SHORT_CLICKED` An object was pressed for a short period of time, then released. Not called if scrolled. +- `LV_EVENT_LONG_PRESSED` An object has been pressed for at least the `long_press_time` specified in the input device driver. Not called if scrolled. +- `LV_EVENT_LONG_PRESSED_REPEAT` Called after `long_press_time` in every `long_press_repeat_time` ms. Not called if scrolled. +- `LV_EVENT_CLICKED` Called on release if an object did not scroll (regardless of long press) +- `LV_EVENT_RELEASED` Called in every case when an object has been released +- `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. +- `LV_EVENT_SCROLL_END` Scrolling ends. +- `LV_EVENT_SCROLL` An object was scrolled +- `LV_EVENT_GESTURE` A gesture is detected. Get the gesture with `lv_indev_get_gesture_dir(lv_indev_get_act());` +- `LV_EVENT_KEY` A key is sent to an object. Get the key with `lv_indev_get_key(lv_indev_get_act());` +- `LV_EVENT_FOCUSED` An object is focused +- `LV_EVENT_DEFOCUSED` An object is unfocused +- `LV_EVENT_LEAVE` An object is unfocused but still selected +- `LV_EVENT_HIT_TEST` Perform advanced hit-testing. Use `lv_hit_test_info_t * a = lv_event_get_hit_test_info(e)` and check if `a->point` can click the object or not. If not set `a->res = false` + + +### Drawing events +- `LV_EVENT_COVER_CHECK` Check if an object fully covers an area. The event parameter is `lv_cover_check_info_t *`. +- `LV_EVENT_REFR_EXT_DRAW_SIZE` Get the required extra draw area around an object (e.g. for a shadow). The event parameter is `lv_coord_t *` to store the size. Only overwrite it with a larger value. +- `LV_EVENT_DRAW_MAIN_BEGIN` Starting the main drawing phase. +- `LV_EVENT_DRAW_MAIN` Perform the main drawing +- `LV_EVENT_DRAW_MAIN_END` Finishing the main drawing phase +- `LV_EVENT_DRAW_POST_BEGIN` Starting the post draw phase (when all children are drawn) +- `LV_EVENT_DRAW_POST` Perform the post draw phase (when all children are drawn) +- `LV_EVENT_DRAW_POST_END` Finishing the post draw phase (when all children are drawn) +- `LV_EVENT_DRAW_PART_BEGIN` Starting to draw a part. The event parameter is `lv_obj_draw_dsc_t *`. Learn more [here](/overview/drawing). +- `LV_EVENT_DRAW_PART_END` Finishing to draw a part. The event parameter is `lv_obj_draw_dsc_t *`. Learn more [here](/overview/drawing). + +In `LV_EVENT_DRAW_...` events it's not allowed to adjust the widgets' properties. E.g. you can not call `lv_obj_set_width()`. +In other words only `get` functions can be called. + +### Other events +- `LV_EVENT_DELETE` Object is being deleted +- `LV_EVENT_CHILD_CHANGED` Child was removed/added +- `LV_EVENT_CHILD_CREATED` Child was created, always bubbles up to all parents +- `LV_EVENT_CHILD_DELETED` Child was deleted, always bubbles up to all parents +- `LV_EVENT_SIZE_CHANGED` Object coordinates/size have changed +- `LV_EVENT_STYLE_CHANGED` Object's style has changed +- `LV_EVENT_BASE_DIR_CHANGED` The base dir has changed +- `LV_EVENT_GET_SELF_SIZE` Get the internal size of a widget +- `LV_EVENT_SCREEN_UNLOAD_START` A screen unload started, fired immediately when lv_scr_load/lv_scr_load_anim is called +- `LV_EVENT_SCREEN_LOAD_START` A screen load started, fired when the screen change delay is expired +- `LV_EVENT_SCREEN_LOADED` A screen was loaded, called when all animations are finished +- `LV_EVENT_SCREEN_UNLOADED` A screen was unloaded, called when all animations are finished + +### Special events +- `LV_EVENT_VALUE_CHANGED` The object's value has changed (i.e. slider moved) +- `LV_EVENT_INSERT` Text is being inserted into the object. The event data is `char *` being inserted. +- `LV_EVENT_REFRESH` Notify the object to refresh something on it (for the user) +- `LV_EVENT_READY` A process has finished +- `LV_EVENT_CANCEL` A process has been canceled + + +### Custom events +Any custom event codes can be registered by `uint32_t MY_EVENT_1 = lv_event_register_id();` + +They can be sent to any object with `lv_event_send(obj, MY_EVENT_1, &some_data)` + +## Sending events + +To manually send events to an object, use `lv_event_send(obj, <EVENT_CODE> &some_data)`. + +For example, this can be used to manually close a message box by simulating a button press (although there are simpler ways to do this): +```c +/*Simulate the press of the first button (indexes start from zero)*/ +uint32_t btn_id = 0; +lv_event_send(mbox, LV_EVENT_VALUE_CHANGED, &btn_id); +``` + +### Refresh event + +`LV_EVENT_REFRESH` is a special event because it's designed to let the user notify an object to refresh itself. Some examples: +- notify a label to refresh its text according to one or more variables (e.g. current time) +- refresh a label when the language changes +- enable a button if some conditions are met (e.g. the correct PIN is entered) +- add/remove styles to/from an object if a limit is exceeded, etc + +## Fields of lv_event_t + +`lv_event_t` is the only parameter passed to the event callback and it contains all data about the event. The following values can be gotten from it: +- `lv_event_get_code(e)` get the event code +- `lv_event_get_current_target(e)` get the object to which an event was sent. I.e. the object whose event handler is being called. +- `lv_event_get_target(e)` get the object that originally triggered the event (different from `lv_event_get_target` if [event bubbling](#event-bubbling) is enabled) +- `lv_event_get_user_data(e)` get the pointer passed as the last parameter of `lv_obj_add_event_cb`. +- `lv_event_get_param(e)` get the parameter passed as the last parameter of `lv_event_send` + + +## Event bubbling + +If `lv_obj_add_flag(obj, LV_OBJ_FLAG_EVENT_BUBBLE)` is enabled all events will be sent to an object's parent too. If the parent also has `LV_OBJ_FLAG_EVENT_BUBBLE` enabled the event will be sent to its parent and so on. + +The *target* parameter of the event is always the current target object, not the original object. To get the original target call `lv_event_get_original_target(e)` in the event handler. + + + +## Examples + +```eval_rst + +.. include:: ../../examples/event/index.rst + +``` diff --git a/lib/lvgl/docs/overview/file-system.md b/lib/lvgl/docs/overview/file-system.md new file mode 100644 index 00000000..34d38987 --- /dev/null +++ b/lib/lvgl/docs/overview/file-system.md @@ -0,0 +1,131 @@ +# File system + +LVGL has a 'File system' abstraction module that enables you to attach any type of file system. +A file system is identified by an assigned drive letter. +For example, if an SD card is associated with the letter `'S'`, a file can be reached using `"S:path/to/file.txt"`. + +## Ready to use drivers +The [lv_fs_if](https://github.com/lvgl/lv_fs_if) repository contains prepared drivers using POSIX, standard C and the [FATFS](http://elm-chan.org/fsw/ff/00index_e.html) API. +See its [README](https://github.com/lvgl/lv_fs_if#readme) for the details. + +## Adding a driver + +### Registering a driver +To add a driver, a `lv_fs_drv_t` needs to be initialized like below. The `lv_fs_drv_t` needs to be static, global or dynamically allocated and not a local variable. +```c +static lv_fs_drv_t drv; /*Needs to be static or global*/ +lv_fs_drv_init(&drv); /*Basic initialization*/ + +drv.letter = 'S'; /*An uppercase letter to identify the drive */ +drv.cache_size = my_cache_size; /*Cache size for reading in bytes. 0 to not cache.*/ + +drv.ready_cb = my_ready_cb; /*Callback to tell if the drive is ready to use */ +drv.open_cb = my_open_cb; /*Callback to open a file */ +drv.close_cb = my_close_cb; /*Callback to close a file */ +drv.read_cb = my_read_cb; /*Callback to read a file */ +drv.write_cb = my_write_cb; /*Callback to write a file */ +drv.seek_cb = my_seek_cb; /*Callback to seek in a file (Move cursor) */ +drv.tell_cb = my_tell_cb; /*Callback to tell the cursor position */ + +drv.dir_open_cb = my_dir_open_cb; /*Callback to open directory to read its content */ +drv.dir_read_cb = my_dir_read_cb; /*Callback to read a directory's content */ +drv.dir_close_cb = my_dir_close_cb; /*Callback to close a directory */ + +drv.user_data = my_user_data; /*Any custom data if required*/ + +lv_fs_drv_register(&drv); /*Finally register the drive*/ + +``` + +Any of the callbacks can be `NULL` to indicate that operation is not supported. + + +### Implementing the callbacks + +#### Open callback +The prototype of `open_cb` looks like this: +```c +void * (*open_cb)(lv_fs_drv_t * drv, const char * path, lv_fs_mode_t mode); +``` + +`path` is the path after the drive letter (e.g. "S:path/to/file.txt" -> "path/to/file.txt"). `mode` can be `LV_FS_MODE_WR` or `LV_FS_MODE_RD` to open for writes or reads. + +The return value is a pointer to a *file object* that describes the opened file or `NULL` if there were any issues (e.g. the file wasn't found). +The returned file object will be passed to other file system related callbacks. (see below) + +### Other callbacks +The other callbacks are quite similar. For example `write_cb` looks like this: +```c +lv_fs_res_t (*write_cb)(lv_fs_drv_t * drv, void * file_p, const void * buf, uint32_t btw, uint32_t * bw); +``` + +For `file_p`, LVGL passes the return value of `open_cb`, `buf` is the data to write, `btw` is the Bytes To Write, `bw` is the actually written bytes. + +For a template of these callbacks see [lv_fs_template.c](https://github.com/lvgl/lvgl/blob/master/examples/porting/lv_port_fs_template.c). + + +## Usage example + +The example below shows how to read from a file: +```c +lv_fs_file_t f; +lv_fs_res_t res; +res = lv_fs_open(&f, "S:folder/file.txt", LV_FS_MODE_RD); +if(res != LV_FS_RES_OK) my_error_handling(); + +uint32_t read_num; +uint8_t buf[8]; +res = lv_fs_read(&f, buf, 8, &read_num); +if(res != LV_FS_RES_OK || read_num != 8) my_error_handling(); + +lv_fs_close(&f); +``` +*The mode in `lv_fs_open` can be `LV_FS_MODE_WR` to open for writes only or `LV_FS_MODE_RD | LV_FS_MODE_WR` for both* + +This example shows how to read a directory's content. It's up to the driver how to mark directories in the result but it can be a good practice to insert a `'/'` in front of each directory name. +```c +lv_fs_dir_t dir; +lv_fs_res_t res; +res = lv_fs_dir_open(&dir, "S:/folder"); +if(res != LV_FS_RES_OK) my_error_handling(); + +char fn[256]; +while(1) { + res = lv_fs_dir_read(&dir, fn); + if(res != LV_FS_RES_OK) { + my_error_handling(); + break; + } + + /*fn is empty, if not more files to read*/ + if(strlen(fn) == 0) { + break; + } + + printf("%s\n", fn); +} + +lv_fs_dir_close(&dir); +``` + +## Use drives for images + +[Image](/widgets/core/img) objects can be opened from files too (besides variables stored in the compiled program). + +To use files in image widgets the following callbacks are required: +- open +- close +- read +- seek +- tell + + + +## API + +```eval_rst + +.. doxygenfile:: lv_fs.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/overview/font.md b/lib/lvgl/docs/overview/font.md new file mode 100644 index 00000000..9e1265cf --- /dev/null +++ b/lib/lvgl/docs/overview/font.md @@ -0,0 +1,265 @@ +# Fonts + +In LVGL fonts are collections of bitmaps and other information required to render images of individual letters (glyph). +A font is stored in a `lv_font_t` variable and can be set in a style's *text_font* field. For example: +```c +lv_style_set_text_font(&my_style, &lv_font_montserrat_28); /*Set a larger font*/ +``` + +Fonts have a **bpp (bits per pixel)** property. It shows how many bits are used to describe a pixel in a font. The value stored for a pixel determines the pixel's opacity. +This way, with higher *bpp*, the edges of the letter can be smoother. The possible *bpp* values are 1, 2, 4 and 8 (higher values mean better quality). + +The *bpp* property also affects the amount of memory needed to store a font. For example, *bpp = 4* makes a font nearly four times larger compared to *bpp = 1*. + +## Unicode support + +LVGL supports **UTF-8** encoded Unicode characters. +Your editor needs to be configured to save your code/text as UTF-8 (usually this the default) and be sure that, `LV_TXT_ENC` is set to `LV_TXT_ENC_UTF8` in *lv_conf.h*. (This is the default value) + +To test it try +```c +lv_obj_t * label1 = lv_label_create(lv_scr_act(), NULL); +lv_label_set_text(label1, LV_SYMBOL_OK); +``` + +If all works well, a ✓ character should be displayed. + +## Built-in fonts + +There are several built-in fonts in different sizes, which can be enabled in `lv_conf.h` with *LV_FONT_...* defines. +### Normal fonts +Containing all the ASCII characters, the degree symbol (U+00B0), the bullet symbol (U+2022) and the built-in symbols (see below). +- `LV_FONT_MONTSERRAT_12` 12 px font +- `LV_FONT_MONTSERRAT_14` 14 px font +- `LV_FONT_MONTSERRAT_16` 16 px font +- `LV_FONT_MONTSERRAT_18` 18 px font +- `LV_FONT_MONTSERRAT_20` 20 px font +- `LV_FONT_MONTSERRAT_22` 22 px font +- `LV_FONT_MONTSERRAT_24` 24 px font +- `LV_FONT_MONTSERRAT_26` 26 px font +- `LV_FONT_MONTSERRAT_28` 28 px font +- `LV_FONT_MONTSERRAT_30` 30 px font +- `LV_FONT_MONTSERRAT_32` 32 px font +- `LV_FONT_MONTSERRAT_34` 34 px font +- `LV_FONT_MONTSERRAT_36` 36 px font +- `LV_FONT_MONTSERRAT_38` 38 px font +- `LV_FONT_MONTSERRAT_40` 40 px font +- `LV_FONT_MONTSERRAT_42` 42 px font +- `LV_FONT_MONTSERRAT_44` 44 px font +- `LV_FONT_MONTSERRAT_46` 46 px font +- `LV_FONT_MONTSERRAT_48` 48 px font + +### Special fonts +- `LV_FONT_MONTSERRAT_12_SUBPX` Same as normal 12 px font but with [subpixel rendering](#subpixel-rendering) +- `LV_FONT_MONTSERRAT_28_COMPRESSED` Same as normal 28 px font but stored as a [compressed font](#compress-fonts) with 3 bpp +- `LV_FONT_DEJAVU_16_PERSIAN_HEBREW` 16 px font with normal range + Hebrew, Arabic, Persian letters and all their forms +- `LV_FONT_SIMSUN_16_CJK`16 px font with normal range plus 1000 of the most common CJK radicals +- `LV_FONT_UNSCII_8` 8 px pixel perfect font with only ASCII characters +- `LV_FONT_UNSCII_16` 16 px pixel perfect font with only ASCII characters + + +The built-in fonts are **global variables** with names like `lv_font_montserrat_16` for a 16 px height font. To use them in a style, just add a pointer to a font variable like shown above. + +The built-in fonts with *bpp = 4* contain the ASCII characters and use the [Montserrat](https://fonts.google.com/specimen/Montserrat) font. + +In addition to the ASCII range, the following symbols are also added to the built-in fonts from the [FontAwesome](https://fontawesome.com/) font. + + + +The symbols can be used singly as: +```c +lv_label_set_text(my_label, LV_SYMBOL_OK); +``` + +Or together with strings (compile time string concatenation): +```c +lv_label_set_text(my_label, LV_SYMBOL_OK "Apply"); +``` + +Or more symbols together: +```c +lv_label_set_text(my_label, LV_SYMBOL_OK LV_SYMBOL_WIFI LV_SYMBOL_PLAY); +``` + +## Special features + +### Bidirectional support +Most languages use a Left-to-Right (LTR for short) writing direction, however some languages (such as Hebrew, Persian or Arabic) use Right-to-Left (RTL for short) direction. + +LVGL not only supports RTL texts but supports mixed (a.k.a. bidirectional, BiDi) text rendering too. Some examples: + + + +BiDi support is enabled by `LV_USE_BIDI` in *lv_conf.h* + +All texts have a base direction (LTR or RTL) which determines some rendering rules and the default alignment of the text (Left or Right). +However, in LVGL, the base direction is not only applied to labels. It's a general property which can be set for every object. +If not set then it will be inherited from the parent. +This means it's enough to set the base direction of a screen and every object will inherit it. + +The default base direction for screens can be set by `LV_BIDI_BASE_DIR_DEF` in *lv_conf.h* and other objects inherit the base direction from their parent. + +To set an object's base direction use `lv_obj_set_base_dir(obj, base_dir)`. The possible base directions are: +- `LV_BIDI_DIR_LTR`: Left to Right base direction +- `LV_BIDI_DIR_RTL`: Right to Left base direction +- `LV_BIDI_DIR_AUTO`: Auto detect base direction +- `LV_BIDI_DIR_INHERIT`: Inherit base direction from the parent (or a default value for non-screen objects) + +This list summarizes the effect of RTL base direction on objects: +- Create objects by default on the right +- `lv_tabview`: Displays tabs from right to left +- `lv_checkbox`: Shows the box on the right +- `lv_btnmatrix`: Shows buttons from right to left +- `lv_list`: Shows icons on the right +- `lv_dropdown`: Aligns options to the right +- The texts in `lv_table`, `lv_btnmatrix`, `lv_keyboard`, `lv_tabview`, `lv_dropdown`, `lv_roller` are "BiDi processed" to be displayed correctly + +### Arabic and Persian support +There are some special rules to display Arabic and Persian characters: the *form* of a character depends on its position in the text. +A different form of the same letter needs to be used when it is isolated, at start, middle or end positions. Besides these, some conjunction rules should also be taken into account. + +LVGL supports these rules if `LV_USE_ARABIC_PERSIAN_CHARS` is enabled. + +However, there are some limitations: +- Only displaying text is supported (e.g. on labels), text inputs (e.g. text area) don't support this feature. +- Static text (i.e. const) is not processed. E.g. texts set by `lv_label_set_text()` will be "Arabic processed" but `lv_lable_set_text_static()` won't. +- Text get functions (e.g. `lv_label_get_text()`) will return the processed text. + +### Subpixel rendering + +Subpixel rendering allows for tripling the horizontal resolution by rendering anti-aliased edges on Red, Green and Blue channels instead of at pixel level granularity. This takes advantage of the position of physical color channels of each pixel, resulting in higher quality letter anti-aliasing. Learn more [here](https://en.wikipedia.org/wiki/Subpixel_rendering). + +For subpixel rendering, the fonts need to be generated with special settings: +- In the online converter tick the `Subpixel` box +- In the command line tool use `--lcd` flag. Note that the generated font needs about three times more memory. + +Subpixel rendering works only if the color channels of the pixels have a horizontal layout. That is the R, G, B channels are next to each other and not above each other. +The order of color channels also needs to match with the library settings. By default, LVGL assumes `RGB` order, however this can be swapped by setting `LV_SUBPX_BGR 1` in *lv_conf.h*. + +### Compressed fonts +The bitmaps of fonts can be compressed by +- ticking the `Compressed` check box in the online converter +- not passing the `--no-compress` flag to the offline converter (compression is applied by default) + +Compression is more effective with larger fonts and higher bpp. However, it's about 30% slower to render compressed fonts. +Therefore, it's recommended to compress only the largest fonts of a user interface, because +- they need the most memory +- they can be compressed better +- and probably they are used less frequently then the medium-sized fonts, so the performance cost is smaller. + +## Add a new font + +There are several ways to add a new font to your project: +1. The simplest method is to use the [Online font converter](https://lvgl.io/tools/fontconverter). Just set the parameters, click the *Convert* button, copy the font to your project and use it. **Be sure to carefully read the steps provided on that site or you will get an error while converting.** +2. Use the [Offline font converter](https://github.com/lvgl/lv_font_conv). (Requires Node.js to be installed) +3. If you want to create something like the built-in fonts (Montserrat font and symbols) but in a different size and/or ranges, you can use the `built_in_font_gen.py` script in `lvgl/scripts/built_in_font` folder. +(This requires Python and `lv_font_conv` to be installed) + +To declare a font in a file, use `LV_FONT_DECLARE(my_font_name)`. + +To make fonts globally available (like the built-in fonts), add them to `LV_FONT_CUSTOM_DECLARE` in *lv_conf.h*. + +## Add new symbols +The built-in symbols are created from the [FontAwesome](https://fontawesome.com/) font. + +1. Search for a symbol on [https://fontawesome.com](https://fontawesome.com). For example the [USB symbol](https://fontawesome.com/icons/usb?style=brands). Copy its Unicode ID which is `0xf287` in this case. +2. Open the [Online font converter](https://lvgl.io/tools/fontconverter). Add [FontAwesome.woff](https://lvgl.io/assets/others/FontAwesome5-Solid+Brands+Regular.woff). . +3. Set the parameters such as Name, Size, BPP. You'll use this name to declare and use the font in your code. +4. Add the Unicode ID of the symbol to the range field. E.g.` 0xf287` for the USB symbol. More symbols can be enumerated with `,`. +5. Convert the font and copy the generated source code to your project. Make sure to compile the .c file of your font. +6. Declare the font using `extern lv_font_t my_font_name;` or simply use `LV_FONT_DECLARE(my_font_name);`. + +**Using the symbol** +1. Convert the Unicode value to UTF8, for example on [this site](http://www.ltg.ed.ac.uk/~richard/utf-8.cgi?input=f287&mode=hex). For `0xf287` the *Hex UTF-8 bytes* are `EF 8A 87`. +2. Create a `define` string from the UTF8 values: `#define MY_USB_SYMBOL "\xEF\x8A\x87"` +3. Create a label and set the text. Eg. `lv_label_set_text(label, MY_USB_SYMBOL)` + +Note - `lv_label_set_text(label, MY_USB_SYMBOL)` searches for this symbol in the font defined in `style.text.font` properties. To use the symbol you may need to change it. Eg ` style.text.font = my_font_name` + +## Load a font at run-time +`lv_font_load` can be used to load a font from a file. The font needs to have a special binary format. (Not TTF or WOFF). +Use [lv_font_conv](https://github.com/lvgl/lv_font_conv/) with the `--format bin` option to generate an LVGL compatible font file. + +Note that to load a font [LVGL's filesystem](/overview/file-system) needs to be enabled and a driver must be added. + +Example +```c +lv_font_t * my_font; +my_font = lv_font_load(X/path/to/my_font.bin); + +/*Use the font*/ + +/*Free the font if not required anymore*/ +lv_font_free(my_font); +``` + + +## Add a new font engine + +LVGL's font interface is designed to be very flexible but, even so, you can add your own font engine in place of LVGL's internal one. +For example, you can use [FreeType](https://www.freetype.org/) to real-time render glyphs from TTF fonts or use an external flash to store the font's bitmap and read them when the library needs them. + +A ready to use FreeType can be found in [lv_freetype](https://github.com/lvgl/lv_lib_freetype) repository. + +To do this, a custom `lv_font_t` variable needs to be created: +```c +/*Describe the properties of a font*/ +lv_font_t my_font; +my_font.get_glyph_dsc = my_get_glyph_dsc_cb; /*Set a callback to get info about glyphs*/ +my_font.get_glyph_bitmap = my_get_glyph_bitmap_cb; /*Set a callback to get bitmap of a glyph*/ +my_font.line_height = height; /*The real line height where any text fits*/ +my_font.base_line = base_line; /*Base line measured from the top of line_height*/ +my_font.dsc = something_required; /*Store any implementation specific data here*/ +my_font.user_data = user_data; /*Optionally some extra user data*/ + +... + +/* Get info about glyph of `unicode_letter` in `font` font. + * Store the result in `dsc_out`. + * The next letter (`unicode_letter_next`) might be used to calculate the width required by this glyph (kerning) + */ +bool my_get_glyph_dsc_cb(const lv_font_t * font, lv_font_glyph_dsc_t * dsc_out, uint32_t unicode_letter, uint32_t unicode_letter_next) +{ + /*Your code here*/ + + /* Store the result. + * For example ... + */ + dsc_out->adv_w = 12; /*Horizontal space required by the glyph in [px]*/ + dsc_out->box_h = 8; /*Height of the bitmap in [px]*/ + dsc_out->box_w = 6; /*Width of the bitmap in [px]*/ + dsc_out->ofs_x = 0; /*X offset of the bitmap in [pf]*/ + dsc_out->ofs_y = 3; /*Y offset of the bitmap measured from the as line*/ + dsc_out->bpp = 2; /*Bits per pixel: 1/2/4/8*/ + + return true; /*true: glyph found; false: glyph was not found*/ +} + + +/* Get the bitmap of `unicode_letter` from `font`. */ +const uint8_t * my_get_glyph_bitmap_cb(const lv_font_t * font, uint32_t unicode_letter) +{ + /* Your code here */ + + /* The bitmap should be a continuous bitstream where + * each pixel is represented by `bpp` bits */ + + return bitmap; /*Or NULL if not found*/ +} +``` + +## Use font fallback + +You can specify `fallback` in `lv_font_t` to provide fallback to the font. When the font +fails to find glyph to a letter, it will try to let font from `fallback` to handle. + +`fallback` can be chained, so it will try to solve until there is no `fallback` set. + +```c +/* Roboto font doesn't have support for CJK glyphs */ +lv_font_t *roboto = my_font_load_function(); +/* Droid Sans Fallback has more glyphs but its typeface doesn't look good as Roboto */ +lv_font_t *droid_sans_fallback = my_font_load_function(); +/* So now we can display Roboto for supported characters while having wider characters set support */ +roboto->fallback = droid_sans_fallback; +``` diff --git a/lib/lvgl/docs/overview/image.md b/lib/lvgl/docs/overview/image.md new file mode 100644 index 00000000..32d2641c --- /dev/null +++ b/lib/lvgl/docs/overview/image.md @@ -0,0 +1,330 @@ +# Images + +An image can be a file or a variable which stores the bitmap itself and some metadata. + +## Store images +You can store images in two places +- as a variable in internal memory (RAM or ROM) +- as a file + +### Variables +Images stored internally in a variable are composed mainly of an `lv_img_dsc_t` structure with the following fields: +- **header** + - *cf* Color format. See [below](#color-format) + - *w* width in pixels (<= 2048) + - *h* height in pixels (<= 2048) + - *always zero* 3 bits which need to be always zero + - *reserved* reserved for future use +- **data** pointer to an array where the image itself is stored +- **data_size** length of `data` in bytes + +These are usually stored within a project as C files. They are linked into the resulting executable like any other constant data. + +### Files +To deal with files you need to add a storage *Drive* to LVGL. In short, a *Drive* is a collection of functions (*open*, *read*, *close*, etc.) registered in LVGL to make file operations. +You can add an interface to a standard file system (FAT32 on SD card) or you create your simple file system to read data from an SPI Flash memory. +In every case, a *Drive* is just an abstraction to read and/or write data to memory. +See the [File system](/overview/file-system) section to learn more. + +Images stored as files are not linked into the resulting executable, and must be read into RAM before being drawn. As a result, they are not as resource-friendly as images linked at compile time. However, they are easier to replace without needing to rebuild the main program. + +## Color formats +Various built-in color formats are supported: +- **LV_IMG_CF_TRUE_COLOR** Simply stores the RGB colors (in whatever color depth LVGL is configured for). +- **LV_IMG_CF_TRUE_COLOR_ALPHA** Like `LV_IMG_CF_TRUE_COLOR` but it also adds an alpha (transparency) byte for every pixel. +- **LV_IMG_CF_TRUE_COLOR_CHROMA_KEYED** Like `LV_IMG_CF_TRUE_COLOR` but if a pixel has the `LV_COLOR_TRANSP` color (set in *lv_conf.h*) it will be transparent. +- **LV_IMG_CF_INDEXED_1/2/4/8BIT** Uses a palette with 2, 4, 16 or 256 colors and stores each pixel in 1, 2, 4 or 8 bits. +- **LV_IMG_CF_ALPHA_1/2/4/8BIT** **Only stores the Alpha value with 1, 2, 4 or 8 bits.** The pixels take the color of `style.img_recolor` and the set opacity. The source image has to be an alpha channel. This is ideal for bitmaps similar to fonts where the whole image is one color that can be altered. + +The bytes of `LV_IMG_CF_TRUE_COLOR` images are stored in the following order. + +For 32-bit color depth: +- Byte 0: Blue +- Byte 1: Green +- Byte 2: Red +- Byte 3: Alpha + +For 16-bit color depth: +- Byte 0: Green 3 lower bit, Blue 5 bit +- Byte 1: Red 5 bit, Green 3 higher bit +- Byte 2: Alpha byte (only with LV_IMG_CF_TRUE_COLOR_ALPHA) + +For 8-bit color depth: +- Byte 0: Red 3 bit, Green 3 bit, Blue 2 bit +- Byte 2: Alpha byte (only with LV_IMG_CF_TRUE_COLOR_ALPHA) + + +You can store images in a *Raw* format to indicate that it's not encoded with one of the built-in color formats and an external [Image decoder](#image-decoder) needs to be used to decode the image. +- **LV_IMG_CF_RAW** Indicates a basic raw image (e.g. a PNG or JPG image). +- **LV_IMG_CF_RAW_ALPHA** Indicates that an image has alpha and an alpha byte is added for every pixel. +- **LV_IMG_CF_RAW_CHROMA_KEYED** Indicates that an image is chroma-keyed as described in `LV_IMG_CF_TRUE_COLOR_CHROMA_KEYED` above. + + +## Add and use images + +You can add images to LVGL in two ways: +- using the online converter +- manually create images + +### Online converter +The online Image converter is available here: https://lvgl.io/tools/imageconverter + +Adding an image to LVGL via the online converter is easy. + +1. You need to select a *BMP*, *PNG* or *JPG* image first. +2. Give the image a name that will be used within LVGL. +3. Select the [Color format](#color-formats). +4. Select the type of image you want. Choosing a binary will generate a `.bin` file that must be stored separately and read using the [file support](#files). Choosing a variable will generate a standard C file that can be linked into your project. +5. Hit the *Convert* button. Once the conversion is finished, your browser will automatically download the resulting file. + +In the generated C arrays (variables), bitmaps for all the color depths (1, 8, 16 or 32) are included in the C file, but only the color depth that matches `LV_COLOR_DEPTH` in *lv_conf.h* will actually be linked into the resulting executable. + +In the case of binary files, you need to specify the color format you want: +- RGB332 for 8-bit color depth +- RGB565 for 16-bit color depth +- RGB565 Swap for 16-bit color depth (two bytes are swapped) +- RGB888 for 32-bit color depth + +### Manually create an image +If you are generating an image at run-time, you can craft an image variable to display it using LVGL. For example: + +```c +uint8_t my_img_data[] = {0x00, 0x01, 0x02, ...}; + +static lv_img_dsc_t my_img_dsc = { + .header.always_zero = 0, + .header.w = 80, + .header.h = 60, + .data_size = 80 * 60 * LV_COLOR_DEPTH / 8, + .header.cf = LV_IMG_CF_TRUE_COLOR, /*Set the color format*/ + .data = my_img_data, +}; + +``` + +If the color format is `LV_IMG_CF_TRUE_COLOR_ALPHA` you can set `data_size` like `80 * 60 * LV_IMG_PX_SIZE_ALPHA_BYTE`. + +Another (possibly simpler) option to create and display an image at run-time is to use the [Canvas](/widgets/core/canvas) object. + +### Use images + +The simplest way to use an image in LVGL is to display it with an [lv_img](/widgets/core/img) object: + +```c +lv_obj_t * icon = lv_img_create(lv_scr_act(), NULL); + +/*From variable*/ +lv_img_set_src(icon, &my_icon_dsc); + +/*From file*/ +lv_img_set_src(icon, "S:my_icon.bin"); +``` + +If the image was converted with the online converter, you should use `LV_IMG_DECLARE(my_icon_dsc)` to declare the image in the file where you want to use it. + + +## Image decoder +As you can see in the [Color formats](#color-formats) section, LVGL supports several built-in image formats. In many cases, these will be all you need. LVGL doesn't directly support, however, generic image formats like PNG or JPG. + +To handle non-built-in image formats, you need to use external libraries and attach them to LVGL via the *Image decoder* interface. + +An image decoder consists of 4 callbacks: +- **info** get some basic info about the image (width, height and color format). +- **open** open an image: either store a decoded image or set it to `NULL` to indicate the image can be read line-by-line. +- **read** if *open* didn't fully open an image this function should give some decoded data (max 1 line) from a given position. +- **close** close an opened image, free the allocated resources. + +You can add any number of image decoders. When an image needs to be drawn, the library will try all the registered image decoders until it finds one which can open the image, i.e. one which knows that format. + +The `LV_IMG_CF_TRUE_COLOR_...`, `LV_IMG_INDEXED_...` and `LV_IMG_ALPHA_...` formats (essentially, all non-`RAW` formats) are understood by the built-in decoder. + +### Custom image formats + +The easiest way to create a custom image is to use the online image converter and select `Raw`, `Raw with alpha` or `Raw with chroma-keyed` format. It will just take every byte of the binary file you uploaded and write it as an image "bitmap". You then need to attach an image decoder that will parse that bitmap and generate the real, renderable bitmap. + +`header.cf` will be `LV_IMG_CF_RAW`, `LV_IMG_CF_RAW_ALPHA` or `LV_IMG_CF_RAW_CHROMA_KEYED` accordingly. You should choose the correct format according to your needs: a fully opaque image, using an alpha channel or using a chroma key. + +After decoding, the *raw* formats are considered *True color* by the library. In other words, the image decoder must decode the *Raw* images to *True color* according to the format described in the [Color formats](#color-formats) section. + +If you want to create a custom image, you should use `LV_IMG_CF_USER_ENCODED_0..7` color formats. However, the library can draw images only in *True color* format (or *Raw* but ultimately it will be in *True color* format). +The `LV_IMG_CF_USER_ENCODED_...` formats are not known by the library and therefore they should be decoded to one of the known formats from the [Color formats](#color-formats) section. +It's possible to decode an image to a non-true color format first (for example: `LV_IMG_INDEXED_4BITS`) and then call the built-in decoder functions to convert it to *True color*. + +With *User encoded* formats, the color format in the open function (`dsc->header.cf`) should be changed according to the new format. + + +### Register an image decoder + +Here's an example of getting LVGL to work with PNG images. + +First, you need to create a new image decoder and set some functions to open/close the PNG files. It should look like this: + +```c +/*Create a new decoder and register functions */ +lv_img_decoder_t * dec = lv_img_decoder_create(); +lv_img_decoder_set_info_cb(dec, decoder_info); +lv_img_decoder_set_open_cb(dec, decoder_open); +lv_img_decoder_set_close_cb(dec, decoder_close); + + +/** + * Get info about a PNG image + * @param decoder pointer to the decoder where this function belongs + * @param src can be file name or pointer to a C array + * @param header store the info here + * @return LV_RES_OK: no error; LV_RES_INV: can't get the info + */ +static lv_res_t decoder_info(lv_img_decoder_t * decoder, const void * src, lv_img_header_t * header) +{ + /*Check whether the type `src` is known by the decoder*/ + if(is_png(src) == false) return LV_RES_INV; + + /* Read the PNG header and find `width` and `height` */ + ... + + header->cf = LV_IMG_CF_RAW_ALPHA; + header->w = width; + header->h = height; +} + +/** + * Open a PNG image and return the decided image + * @param decoder pointer to the decoder where this function belongs + * @param dsc pointer to a descriptor which describes this decoding session + * @return LV_RES_OK: no error; LV_RES_INV: can't get the info + */ +static lv_res_t decoder_open(lv_img_decoder_t * decoder, lv_img_decoder_dsc_t * dsc) +{ + + /*Check whether the type `src` is known by the decoder*/ + if(is_png(src) == false) return LV_RES_INV; + + /*Decode and store the image. If `dsc->img_data` is `NULL`, the `read_line` function will be called to get the image data line-by-line*/ + dsc->img_data = my_png_decoder(src); + + /*Change the color format if required. For PNG usually 'Raw' is fine*/ + dsc->header.cf = LV_IMG_CF_... + + /*Call a built in decoder function if required. It's not required if`my_png_decoder` opened the image in true color format.*/ + lv_res_t res = lv_img_decoder_built_in_open(decoder, dsc); + + return res; +} + +/** + * Decode `len` pixels starting from the given `x`, `y` coordinates and store them in `buf`. + * Required only if the "open" function can't open the whole decoded pixel array. (dsc->img_data == NULL) + * @param decoder pointer to the decoder the function associated with + * @param dsc pointer to decoder descriptor + * @param x start x coordinate + * @param y start y coordinate + * @param len number of pixels to decode + * @param buf a buffer to store the decoded pixels + * @return LV_RES_OK: ok; LV_RES_INV: failed + */ +lv_res_t decoder_built_in_read_line(lv_img_decoder_t * decoder, lv_img_decoder_dsc_t * dsc, lv_coord_t x, + lv_coord_t y, lv_coord_t len, uint8_t * buf) +{ + /*With PNG it's usually not required*/ + + /*Copy `len` pixels from `x` and `y` coordinates in True color format to `buf` */ + +} + +/** + * Free the allocated resources + * @param decoder pointer to the decoder where this function belongs + * @param dsc pointer to a descriptor which describes this decoding session + */ +static void decoder_close(lv_img_decoder_t * decoder, lv_img_decoder_dsc_t * dsc) +{ + /*Free all allocated data*/ + + /*Call the built-in close function if the built-in open/read_line was used*/ + lv_img_decoder_built_in_close(decoder, dsc); + +} + +``` + +So in summary: +- In `decoder_info`, you should collect some basic information about the image and store it in `header`. +- In `decoder_open`, you should try to open the image source pointed by `dsc->src`. Its type is already in `dsc->src_type == LV_IMG_SRC_FILE/VARIABLE`. +If this format/type is not supported by the decoder, return `LV_RES_INV`. +However, if you can open the image, a pointer to the decoded *True color* image should be set in `dsc->img_data`. +If the format is known, but you don't want to decode the entire image (e.g. no memory for it), set `dsc->img_data = NULL` and use `read_line` to get the pixel data. +- In `decoder_close` you should free all allocated resources. +- `decoder_read` is optional. Decoding the whole image requires extra memory and some computational overhead. +However, it can decode one line of the image without decoding the whole image, you can save memory and time. +To indicate that the *line read* function should be used, set `dsc->img_data = NULL` in the open function. + + +### Manually use an image decoder + +LVGL will use registered image decoders automatically if you try and draw a raw image (i.e. using the `lv_img` object) but you can use them manually too. Create an `lv_img_decoder_dsc_t` variable to describe the decoding session and call `lv_img_decoder_open()`. + +The `color` parameter is used only with `LV_IMG_CF_ALPHA_1/2/4/8BIT` images to tell color of the image. +`frame_id` can be used if the image to open is an animation. + + +```c + +lv_res_t res; +lv_img_decoder_dsc_t dsc; +res = lv_img_decoder_open(&dsc, &my_img_dsc, color, frame_id); + +if(res == LV_RES_OK) { + /*Do something with `dsc->img_data`*/ + lv_img_decoder_close(&dsc); +} + +``` + + +## Image caching +Sometimes it takes a lot of time to open an image. +Continuously decoding a PNG image or loading images from a slow external memory would be inefficient and detrimental to the user experience. + +Therefore, LVGL caches a given number of images. Caching means some images will be left open, hence LVGL can quickly access them from `dsc->img_data` instead of needing to decode them again. + +Of course, caching images is resource intensive as it uses more RAM to store the decoded image. LVGL tries to optimize the process as much as possible (see below), but you will still need to evaluate if this would be beneficial for your platform or not. Image caching may not be worth it if you have a deeply embedded target which decodes small images from a relatively fast storage medium. + +### Cache size +The number of cache entries can be defined with `LV_IMG_CACHE_DEF_SIZE` in *lv_conf.h*. The default value is 1 so only the most recently used image will be left open. + +The size of the cache can be changed at run-time with `lv_img_cache_set_size(entry_num)`. + +### Value of images +When you use more images than cache entries, LVGL can't cache all the images. Instead, the library will close one of the cached images to free space. + +To decide which image to close, LVGL uses a measurement it previously made of how long it took to open the image. Cache entries that hold slower-to-open images are considered more valuable and are kept in the cache as long as possible. + +If you want or need to override LVGL's measurement, you can manually set the *time to open* value in the decoder open function in `dsc->time_to_open = time_ms` to give a higher or lower value. (Leave it unchanged to let LVGL control it.) + +Every cache entry has a *"life"* value. Every time an image is opened through the cache, the *life* value of all entries is decreased to make them older. +When a cached image is used, its *life* value is increased by the *time to open* value to make it more alive. + +If there is no more space in the cache, the entry with the lowest life value will be closed. + +### Memory usage +Note that a cached image might continuously consume memory. For example, if three PNG images are cached, they will consume memory while they are open. + +Therefore, it's the user's responsibility to be sure there is enough RAM to cache even the largest images at the same time. + +### Clean the cache +Let's say you have loaded a PNG image into a `lv_img_dsc_t my_png` variable and use it in an `lv_img` object. If the image is already cached and you then change the underlying PNG file, you need to notify LVGL to cache the image again. Otherwise, there is no easy way of detecting that the underlying file changed and LVGL will still draw the old image from cache. + +To do this, use `lv_img_cache_invalidate_src(&my_png)`. If `NULL` is passed as a parameter, the whole cache will be cleaned. + + +## API + + +### Image buffer + +```eval_rst + +.. doxygenfile:: lv_img_buf.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/overview/indev.md b/lib/lvgl/docs/overview/indev.md new file mode 100644 index 00000000..87428ac0 --- /dev/null +++ b/lib/lvgl/docs/overview/indev.md @@ -0,0 +1,150 @@ +# Input devices + +An input device usually means: +- Pointer-like input device like touchpad or mouse +- Keypads like a normal keyboard or simple numeric keypad +- Encoders with left/right turn and push options +- External hardware buttons which are assigned to specific points on the screen + + +``` important:: Before reading further, please read the [Porting](/porting/indev) section of Input devices +``` + +## Pointers + +### Cursor + +Pointer input devices (like a mouse) can have a cursor. + +```c +... +lv_indev_t * mouse_indev = lv_indev_drv_register(&indev_drv); + +LV_IMG_DECLARE(mouse_cursor_icon); /*Declare the image source.*/ +lv_obj_t * cursor_obj = lv_img_create(lv_scr_act()); /*Create an image object for the cursor */ +lv_img_set_src(cursor_obj, &mouse_cursor_icon); /*Set the image source*/ +lv_indev_set_cursor(mouse_indev, cursor_obj); /*Connect the image object to the driver*/ +``` + +Note that the cursor object should have `lv_obj_clear_flag(cursor_obj, LV_OBJ_FLAG_CLICKABLE)`. +For images, *clicking* is disabled by default. + +### Gestures +Pointer input devices can detect basic gestures. By default, most of the widgets send the gestures to its parent, so finally the gestures can be detected on the screen object in a form of an `LV_EVENT_GESTURE` event. For example: + +```c +void my_event(lv_event_t * e) +{ + lv_obj_t * screen = lv_event_get_current_target(e); + lv_dir_t dir = lv_indev_get_gesture_dir(lv_indev_act()); + switch(dir) { + case LV_DIR_LEFT: + ... + break; + case LV_DIR_RIGHT: + ... + break; + case LV_DIR_TOP: + ... + break; + case LV_DIR_BOTTOM: + ... + break; + } +} + +... + +lv_obj_add_event_cb(screen1, my_event, LV_EVENT_GESTURE, NULL); +``` + +To prevent passing the gesture event to the parent from an object use `lv_obj_clear_flag(obj, LV_OBJ_FLAG_GESTURE_BUBBLE)`. + +Note that, gestures are not triggered if an object is being scrolled. + +If you did some action on a gesture you can call `lv_indev_wait_release(lv_indev_get_act())` in the event handler to prevent LVGL sending further input device related events. + +## Keypad and encoder + +You can fully control the user interface without a touchpad or mouse by using a keypad or encoder(s). It works similar to the *TAB* key on the PC to select an element in an application or a web page. + +### Groups + +Objects you want to control with a keypad or encoder need to be added to a *Group*. +In every group there is exactly one focused object which receives the pressed keys or the encoder actions. +For example, if a [Text area](/widgets/core/textarea) is focused and you press some letter on a keyboard, the keys will be sent and inserted into the text area. +Similarly, if a [Slider](/widgets/core/slider) is focused and you press the left or right arrows, the slider's value will be changed. + +You need to associate an input device with a group. An input device can send key events to only one group but a group can receive data from more than one input device. + +To create a group use `lv_group_t * g = lv_group_create()` and to add an object to the group use `lv_group_add_obj(g, obj)`. + +To associate a group with an input device use `lv_indev_set_group(indev, g)`, where `indev` is the return value of `lv_indev_drv_register()` + +#### Keys +There are some predefined keys which have special meaning: +- **LV_KEY_NEXT** Focus on the next object +- **LV_KEY_PREV** Focus on the previous object +- **LV_KEY_ENTER** Triggers `LV_EVENT_PRESSED/CLICKED/LONG_PRESSED` etc. events +- **LV_KEY_UP** Increase value or move upwards +- **LV_KEY_DOWN** Decrease value or move downwards +- **LV_KEY_RIGHT** Increase value or move to the right +- **LV_KEY_LEFT** Decrease value or move to the left +- **LV_KEY_ESC** Close or exit (E.g. close a [Drop down list](/widgets/core/dropdown)) +- **LV_KEY_DEL** Delete (E.g. a character on the right in a [Text area](/widgets/core/textarea)) +- **LV_KEY_BACKSPACE** Delete a character on the left (E.g. in a [Text area](/widgets/core/textarea)) +- **LV_KEY_HOME** Go to the beginning/top (E.g. in a [Text area](/widgets/core/textarea)) +- **LV_KEY_END** Go to the end (E.g. in a [Text area](/widgets/core/textarea)) + +The most important special keys are `LV_KEY_NEXT/PREV`, `LV_KEY_ENTER` and `LV_KEY_UP/DOWN/LEFT/RIGHT`. +In your `read_cb` function, you should translate some of your keys to these special keys to support navigation in a group and interact with selected objects. + +Usually, it's enough to use only `LV_KEY_LEFT/RIGHT` because most objects can be fully controlled with them. + +With an encoder you should use only `LV_KEY_LEFT`, `LV_KEY_RIGHT`, and `LV_KEY_ENTER`. + +#### Edit and navigate mode + +Since a keypad has plenty of keys, it's easy to navigate between objects and edit them using the keypad. But encoders have a limited number of "keys" and hence it is difficult to navigate using the default options. *Navigate* and *Edit* modes are used to avoid this problem with encoders. + +In *Navigate* mode, an encoder's `LV_KEY_LEFT/RIGHT` is translated to `LV_KEY_NEXT/PREV`. Therefore, the next or previous object will be selected by turning the encoder. +Pressing `LV_KEY_ENTER` will change to *Edit* mode. + +In *Edit* mode, `LV_KEY_NEXT/PREV` is usually used to modify an object. +Depending on the object's type, a short or long press of `LV_KEY_ENTER` changes back to *Navigate* mode. +Usually, an object which cannot be pressed (like a [Slider](/widgets/core/slider)) leaves *Edit* mode upon a short click. But with objects where a short click has meaning (e.g. [Button](/widgets/core/btn)), a long press is required. + +#### Default group +Interactive widgets - such as buttons, checkboxes, sliders, etc. - can be automatically added to a default group. +Just create a group with `lv_group_t * g = lv_group_create();` and set the default group with `lv_group_set_default(g);` + +Don't forget to assign one or more input devices to the default group with ` lv_indev_set_group(my_indev, g);`. + +### Styling + +If an object is focused either by clicking it via touchpad or focused via an encoder or keypad it goes to the `LV_STATE_FOCUSED` state. Hence, focused styles will be applied to it. + +If an object switches to edit mode it enters the `LV_STATE_FOCUSED | LV_STATE_EDITED` states so these style properties will be shown. + +For a more detailed description read the [Style](https://docs.lvgl.io/v7/en/html/overview/style.html) section. + +## API + + +### Input device + +```eval_rst + +.. doxygenfile:: lv_indev.h + :project: lvgl + +``` + +### Groups + +```eval_rst + +.. doxygenfile:: lv_group.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/overview/index.md b/lib/lvgl/docs/overview/index.md new file mode 100644 index 00000000..2b33ecd6 --- /dev/null +++ b/lib/lvgl/docs/overview/index.md @@ -0,0 +1,29 @@ + +# Overview + + +```eval_rst + +.. toctree:: + :maxdepth: 2 + + object + coords + style + style-props + scroll + layer + event + indev + display + color + font + image + file-system + animation + timer + drawing + renderers/index + new_widget +``` + diff --git a/lib/lvgl/docs/overview/layer.md b/lib/lvgl/docs/overview/layer.md new file mode 100644 index 00000000..8cb4645b --- /dev/null +++ b/lib/lvgl/docs/overview/layer.md @@ -0,0 +1,56 @@ + +# Layers + +## Order of creation + +By default, LVGL draws new objects on top of old objects. + +For example, assume we add a button to a parent object named button1 and then another button named button2. Then button1 (along with its child object(s)) will be in the background and can be covered by button2 and its children. + + + + +```c +/*Create a screen*/ +lv_obj_t * scr = lv_obj_create(NULL, NULL); +lv_scr_load(scr); /*Load the screen*/ + +/*Create 2 buttons*/ +lv_obj_t * btn1 = lv_btn_create(scr, NULL); /*Create a button on the screen*/ +lv_btn_set_fit(btn1, true, true); /*Enable automatically setting the size according to content*/ +lv_obj_set_pos(btn1, 60, 40); /*Set the position of the button*/ + +lv_obj_t * btn2 = lv_btn_create(scr, btn1); /*Copy the first button*/ +lv_obj_set_pos(btn2, 180, 80); /*Set the position of the button*/ + +/*Add labels to the buttons*/ +lv_obj_t * label1 = lv_label_create(btn1, NULL); /*Create a label on the first button*/ +lv_label_set_text(label1, "Button 1"); /*Set the text of the label*/ + +lv_obj_t * label2 = lv_label_create(btn2, NULL); /*Create a label on the second button*/ +lv_label_set_text(label2, "Button 2"); /*Set the text of the label*/ + +/*Delete the second label*/ +lv_obj_del(label2); +``` + +## Bring to the foreground + +There are four explicit ways to bring an object to the foreground: +- Use `lv_obj_move_foreground(obj)` to bring an object to the foreground. Similarly, use `lv_obj_move_background(obj)` to move it to the background. +- Use `lv_obj_move_up(obj)` to move an object one position up in the hierarchy, Similarly, use `lv_obj_move_down(obj)` to move an object one position down in the hierarchy. +- Use `lv_obj_swap(obj1, obj2)` to swap the relative layer position of two objects. +- When `lv_obj_set_parent(obj, new_parent)` is used, `obj` will be on the foreground of the `new_parent`. + + +## Top and sys layers + +LVGL uses two special layers named `layer_top` and `layer_sys`. +Both are visible and common on all screens of a display. **They are not, however, shared among multiple physical displays.** The `layer_top` is always on top of the default screen (`lv_scr_act()`), and `layer_sys` is on top of `layer_top`. + +The `layer_top` can be used by the user to create some content visible everywhere. For example, a menu bar, a pop-up, etc. If the `click` attribute is enabled, then `layer_top` will absorb all user clicks and acts as a modal. +```c +lv_obj_add_flag(lv_layer_top(), LV_OBJ_FLAG_CLICKABLE); +``` + +The `layer_sys` is also used for similar purposes in LVGL. For example, it places the mouse cursor above all layers to be sure it's always visible. diff --git a/lib/lvgl/docs/overview/new_widget.md b/lib/lvgl/docs/overview/new_widget.md new file mode 100644 index 00000000..0d000bf8 --- /dev/null +++ b/lib/lvgl/docs/overview/new_widget.md @@ -0,0 +1,3 @@ + +# New widget + diff --git a/lib/lvgl/docs/overview/object.md b/lib/lvgl/docs/overview/object.md new file mode 100644 index 00000000..a2849dce --- /dev/null +++ b/lib/lvgl/docs/overview/object.md @@ -0,0 +1,223 @@ +# Objects + +In LVGL the **basic building blocks** of a user interface are the objects, also called *Widgets*. +For example a [Button](/widgets/core/btn), [Label](/widgets/core/label), [Image](/widgets/core/img), [List](/widgets/extra/list), [Chart](/widgets/extra/chart) or [Text area](/widgets/core/textarea). + +You can see all the [Object types](/widgets/index) here. + +All objects are referenced using an `lv_obj_t` pointer as a handle. This pointer can later be used to set or get the attributes of the object. + +## Attributes + +### Basic attributes + +All object types share some basic attributes: +- Position +- Size +- Parent +- Styles +- Event handlers +- Etc + +You can set/get these attributes with `lv_obj_set_...` and `lv_obj_get_...` functions. For example: + +```c +/*Set basic object attributes*/ +lv_obj_set_size(btn1, 100, 50); /*Set a button's size*/ +lv_obj_set_pos(btn1, 20,30); /*Set a button's position*/ +``` + +To see all the available functions visit the [Base object's documentation](/widgets/obj). + +### Specific attributes + +The object types have special attributes too. For example, a slider has +- Minimum and maximum values +- Current value + +For these special attributes, every object type may have unique API functions. For example for a slider: + +```c +/*Set slider specific attributes*/ +lv_slider_set_range(slider1, 0, 100); /*Set the min. and max. values*/ +lv_slider_set_value(slider1, 40, LV_ANIM_ON); /*Set the current value (position)*/ +``` + +The API of the widgets is described in their [Documentation](/widgets/index) but you can also check the respective header files (e.g. *widgets/lv_slider.h*) + +## Working mechanisms + +### Parent-child structure + +A parent object can be considered as the container of its children. Every object has exactly one parent object (except screens), but a parent can have any number of children. +There is no limitation for the type of the parent but there are objects which are typically a parent (e.g. button) or a child (e.g. label). + +### Moving together + +If the position of a parent changes, the children will move along with it. +Therefore, all positions are relative to the parent. + + + +```c +lv_obj_t * parent = lv_obj_create(lv_scr_act()); /*Create a parent object on the current screen*/ +lv_obj_set_size(parent, 100, 80); /*Set the size of the parent*/ + +lv_obj_t * obj1 = lv_obj_create(parent); /*Create an object on the previously created parent object*/ +lv_obj_set_pos(obj1, 10, 10); /*Set the position of the new object*/ +``` + +Modify the position of the parent: + + + +```c +lv_obj_set_pos(parent, 50, 50); /*Move the parent. The child will move with it.*/ +``` + +(For simplicity the adjusting of colors of the objects is not shown in the example.) + +### Visibility only on the parent + +If a child is partially or fully outside its parent then the parts outside will not be visible. + + + +```c +lv_obj_set_x(obj1, -30); /*Move the child a little bit off the parent*/ +``` + +This behavior can be overwritten with `lv_obj_add_flag(obj, LV_OBJ_FLAG_OVERFLOW_VISIBLE);` which allow the children to be drawn out of the parent. + + +### Create and delete objects + +In LVGL, objects can be created and deleted dynamically at run time. It means only the currently created (existing) objects consume RAM. + +This allows for the creation of a screen just when a button is clicked to open it, and for deletion of screens when a new screen is loaded. + +UIs can be created based on the current environment of the device. For example one can create meters, charts, bars and sliders based on the currently attached sensors. + +Every widget has its own **create** function with a prototype like this: +```c +lv_obj_t * lv_<widget>_create(lv_obj_t * parent, <other parameters if any>); +``` + +Typically, the create functions only have a *parent* parameter telling them on which object to create the new widget. + +The return value is a pointer to the created object with `lv_obj_t *` type. + + +There is a common **delete** function for all object types. It deletes the object and all of its children. + +```c +void lv_obj_del(lv_obj_t * obj); +``` + +`lv_obj_del` will delete the object immediately. +If for any reason you can't delete the object immediately you can use `lv_obj_del_async(obj)` which will perform the deletion on the next call of `lv_timer_handler()`. +This is useful e.g. if you want to delete the parent of an object in the child's `LV_EVENT_DELETE` handler. + +You can remove all the children of an object (but not the object itself) using `lv_obj_clean(obj)`. + +You can use `lv_obj_del_delayed(obj, 1000)` to delete an object after some time. The delay is expressed in milliseconds. + + +## Screens + +### Create screens +The screens are special objects which have no parent object. So they can be created like: +```c +lv_obj_t * scr1 = lv_obj_create(NULL); +``` + +Screens can be created with any object type. For example, a [Base object](/widgets/obj) or an image to make a wallpaper. + +### Get the active screen +There is always an active screen on each display. By default, the library creates and loads a "Base object" as a screen for each display. + +To get the currently active screen use the `lv_scr_act()` function. + +### Load screens + +To load a new screen, use `lv_scr_load(scr1)`. + +### Layers +There are two automatically generated layers: +- top layer +- system layer + +They are independent of the screens and they will be shown on every screen. The *top layer* is above every object on the screen and the *system layer* is above the *top layer*. +You can add any pop-up windows to the *top layer* freely. But, the *system layer* is restricted to system-level things (e.g. mouse cursor will be placed there with `lv_indev_set_cursor()`). + +The `lv_layer_top()` and `lv_layer_sys()` functions return pointers to the top and system layers respectively. + +Read the [Layer overview](/overview/layer) section to learn more about layers. + + +#### Load screen with animation + +A new screen can be loaded with animation by using `lv_scr_load_anim(scr, transition_type, time, delay, auto_del)`. The following transition types exist: +- `LV_SCR_LOAD_ANIM_NONE` Switch immediately after `delay` milliseconds +- `LV_SCR_LOAD_ANIM_OVER_LEFT/RIGHT/TOP/BOTTOM` Move the new screen over the current towards the given direction +- `LV_SCR_LOAD_ANIM_OUT_LEFT/RIGHT/TOP/BOTTOM` Move out the old screen over the current towards the given direction +- `LV_SCR_LOAD_ANIM_MOVE_LEFT/RIGHT/TOP/BOTTOM` Move both the current and new screens towards the given direction +- `LV_SCR_LOAD_ANIM_FADE_IN/OUT` Fade the new screen over the old screen, or vice versa + +Setting `auto_del` to `true` will automatically delete the old screen when the animation is finished. + +The new screen will become active (returned by `lv_scr_act()`) when the animation starts after `delay` time. +All inputs are disabled during the screen animation. + +### Handling multiple displays +Screens are created on the currently selected *default display*. +The *default display* is the last registered display with `lv_disp_drv_register`. You can also explicitly select a new default display using `lv_disp_set_default(disp)`. + +`lv_scr_act()`, `lv_scr_load()` and `lv_scr_load_anim()` operate on the default screen. + +Visit [Multi-display support](/overview/display) to learn more. + +## Parts + +The widgets are built from multiple parts. For example a [Base object](/widgets/obj) uses the main and scrollbar parts but a [Slider](/widgets/core/slider) uses the main, indicator and knob parts. +Parts are similar to *pseudo-elements* in CSS. + +The following predefined parts exist in LVGL: +- `LV_PART_MAIN` A background like rectangle +- `LV_PART_SCROLLBAR` The scrollbar(s) +- `LV_PART_INDICATOR` Indicator, e.g. for slider, bar, switch, or the tick box of the checkbox +- `LV_PART_KNOB` Like a handle to grab to adjust the value +- `LV_PART_SELECTED` Indicate the currently selected option or section +- `LV_PART_ITEMS` Used if the widget has multiple similar elements (e.g. table cells) +- `LV_PART_TICKS` Ticks on scales e.g. for a chart or meter +- `LV_PART_CURSOR` Mark a specific place e.g. text area's or chart's cursor +- `LV_PART_CUSTOM_FIRST` Custom parts can be added from here. + +The main purpose of parts is to allow styling the "components" of the widgets. +They are described in more detail in the [Style overview](/overview/style) section. + +## States +The object can be in a combination of the following states: +- `LV_STATE_DEFAULT` Normal, released state +- `LV_STATE_CHECKED` Toggled or checked state +- `LV_STATE_FOCUSED` Focused via keypad or encoder or clicked via touchpad/mouse +- `LV_STATE_FOCUS_KEY` Focused via keypad or encoder but not via touchpad/mouse +- `LV_STATE_EDITED` Edit by an encoder +- `LV_STATE_HOVERED` Hovered by mouse (not supported now) +- `LV_STATE_PRESSED` Being pressed +- `LV_STATE_SCROLLED` Being scrolled +- `LV_STATE_DISABLED` Disabled state +- `LV_STATE_USER_1` Custom state +- `LV_STATE_USER_2` Custom state +- `LV_STATE_USER_3` Custom state +- `LV_STATE_USER_4` Custom state + +The states are usually automatically changed by the library as the user interacts with an object (presses, releases, focuses, etc.). +However, the states can be changed manually too. +To set or clear given state (but leave the other states untouched) use `lv_obj_add/clear_state(obj, LV_STATE_...)` +In both cases OR-ed state values can be used as well. E.g. `lv_obj_add_state(obj, part, LV_STATE_PRESSED | LV_PRESSED_CHECKED)`. + +To learn more about the states read the related section of the [Style overview](/overview/style). + +## Snapshot +A snapshot image can be generated for an object together with its children. Check details in [Snapshot](/others/snapshot). diff --git a/lib/lvgl/docs/overview/renderers/arm-2d.md b/lib/lvgl/docs/overview/renderers/arm-2d.md new file mode 100644 index 00000000..d6554771 --- /dev/null +++ b/lib/lvgl/docs/overview/renderers/arm-2d.md @@ -0,0 +1,4 @@ +# ARM-2D GPU + +TODO + diff --git a/lib/lvgl/docs/overview/renderers/dma2d.md b/lib/lvgl/docs/overview/renderers/dma2d.md new file mode 100644 index 00000000..6c6b3d1f --- /dev/null +++ b/lib/lvgl/docs/overview/renderers/dma2d.md @@ -0,0 +1,4 @@ +# DMA2D GPU + +TODO + diff --git a/lib/lvgl/docs/overview/renderers/index.md b/lib/lvgl/docs/overview/renderers/index.md new file mode 100644 index 00000000..b11f5884 --- /dev/null +++ b/lib/lvgl/docs/overview/renderers/index.md @@ -0,0 +1,16 @@ + +# Renderers and GPUs + + +```eval_rst + +.. toctree:: + :maxdepth: 2 + + sw + sdl + arm-2d + pxp-vglite + dma2d +``` + diff --git a/lib/lvgl/docs/overview/renderers/pxp-vglite.md b/lib/lvgl/docs/overview/renderers/pxp-vglite.md new file mode 100644 index 00000000..d68d1e7e --- /dev/null +++ b/lib/lvgl/docs/overview/renderers/pxp-vglite.md @@ -0,0 +1,4 @@ +# NXP PXP and VGLite GPU + +TODO + diff --git a/lib/lvgl/docs/overview/renderers/sdl.md b/lib/lvgl/docs/overview/renderers/sdl.md new file mode 100644 index 00000000..af8b976e --- /dev/null +++ b/lib/lvgl/docs/overview/renderers/sdl.md @@ -0,0 +1,4 @@ +# SDL renderer + +TODO + diff --git a/lib/lvgl/docs/overview/renderers/sw.md b/lib/lvgl/docs/overview/renderers/sw.md new file mode 100644 index 00000000..ccc1c266 --- /dev/null +++ b/lib/lvgl/docs/overview/renderers/sw.md @@ -0,0 +1,4 @@ +# Software renderer + +TODO + diff --git a/lib/lvgl/docs/overview/scroll.md b/lib/lvgl/docs/overview/scroll.md new file mode 100644 index 00000000..554b141a --- /dev/null +++ b/lib/lvgl/docs/overview/scroll.md @@ -0,0 +1,195 @@ +# Scroll + +## Overview +In LVGL scrolling works very intuitively: if an object is outside 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 horizontally or vertically in one stroke; diagonal scrolling is not possible. + +### Scrollbar + +#### Mode +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 an 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_...)` sets the scrollbar mode on an object. + + +#### Styling +The scrollbars have their own dedicated part, called `LV_PART_SCROLLBAR`. For example a scrollbar can turn to red like this: +```c +static lv_style_t style_red; +lv_style_init(&style_red); +lv_style_set_bg_color(&style_red, lv_color_red()); + +... + +lv_obj_add_style(obj, &style_red, LV_PART_SCROLLBAR); +``` + +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_blue, lv_color_blue()); + +... + +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 object's or any parent's main part 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. + +### Events +The following events are related to scrolling: +- `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. +- `LV_EVENT_SCROLL_END` Scrolling ends. +- `LV_EVENT_SCROLL` Scroll happened. Triggered on every position change. +Scroll events + +## Basic example +TODO + +## Features of scrolling + +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 objects can still propagate the scrolling (chain) to their parents. + +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 +- `LV_DIR_BOTTOM` only scroll down +- `LV_DIR_RIGHT` only scroll right +- `LV_DIR_HOR` only scroll horizontally +- `LV_DIR_VER` only scroll vertically +- `LV_DIR_ALL` scroll any directions + +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) 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 `LV_OBJ_FLAG_SCROLL_CHAIN_HOR/VER` 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 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 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 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. + +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 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 + +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 +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 `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 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 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 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. +```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); +} + +lv_obj_t* container = lv_obj_create(NULL); +lv_obj_add_event_cb(container, store_scroll_value_event_cb, LV_EVENT_SCROLL, NULL); +``` + +Scrool coordinates can be retrieve from differents axes with these functions: +- `lv_obj_get_scroll_x(obj)` Get the `x` coordinate of object +- `lv_obj_get_scroll_y(obj)` Get the `y` coordinate of object +- `lv_obj_get_scroll_top(obj)` Get the scroll coordinate from the top +- `lv_obj_get_scroll_bottom(obj)` Get the scroll coordinate from the bottom +- `lv_obj_get_scroll_left(obj)` Get the scroll coordinate from the left +- `lv_obj_get_scroll_right(obj)` Get the scroll coordinate from the right + +## 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 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. + +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: +```c +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 neesd 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 + } +} +``` + +## Examples + +```eval_rst + +.. include:: ../../examples/scroll/index.rst + +``` diff --git a/lib/lvgl/docs/overview/style-props.md b/lib/lvgl/docs/overview/style-props.md new file mode 100644 index 00000000..74a0cd5f --- /dev/null +++ b/lib/lvgl/docs/overview/style-props.md @@ -0,0 +1,790 @@ +# Style properties + +## Size and position +Properties related to size, position, alignment and layout of the objects. + +### width +Sets the width of object. Pixel, percentage and `LV_SIZE_CONTENT` values can be used. Percentage values are relative to the width of the parent's content area. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> Widget dependent</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### min_width +Sets a minimal width. Pixel and percentage values can be used. Percentage values are relative to the width of the parent's content area. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### max_width +Sets a maximal width. Pixel and percentage values can be used. Percentage values are relative to the width of the parent's content area. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> LV_COORD_MAX</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### height +Sets the height of object. Pixel, percentage and `LV_SIZE_CONTENT` can be used. Percentage values are relative to the height of the parent's content area. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> Widget dependent</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### min_height +Sets a minimal height. Pixel and percentage values can be used. Percentage values are relative to the width of the parent's content area. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### max_height +Sets a maximal height. Pixel and percentage values can be used. Percentage values are relative to the height of the parent's content area. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> LV_COORD_MAX</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### x +Set the X coordinate of the object considering the set `align`. Pixel and percentage values can be used. Percentage values are relative to the width of the parent's content area. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### y +Set the Y coordinate of the object considering the set `align`. Pixel and percentage values can be used. Percentage values are relative to the height of the parent's content area. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### align +Set the alignment which tells from which point of the parent the X and Y coordinates should be interpreted. The possible values are: `LV_ALIGN_DEFAULT`, `LV_ALIGN_TOP_LEFT/MID/RIGHT`, `LV_ALIGN_BOTTOM_LEFT/MID/RIGHT`, `LV_ALIGN_LEFT/RIGHT_MID`, `LV_ALIGN_CENTER`. `LV_ALIGN_DEFAULT` means `LV_ALIGN_TOP_LEFT` with LTR base direction and `LV_ALIGN_TOP_RIGHT` with RTL base direction. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_ALIGN_DEFAULT`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### transform_width +Make the object wider on both sides with this value. Pixel and percentage (with `lv_pct(x)`) values can be used. Percentage values are relative to the object's width. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> Yes</li> +</ul> + +### transform_height +Make the object higher on both sides with this value. Pixel and percentage (with `lv_pct(x)`) values can be used. Percentage values are relative to the object's height. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> Yes</li> +</ul> + +### translate_x +Move the object with this value in X direction. Applied after layouts, aligns and other positioning. Pixel and percentage (with `lv_pct(x)`) values can be used. Percentage values are relative to the object's width. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### translate_y +Move the object with this value in Y direction. Applied after layouts, aligns and other positioning. Pixel and percentage (with `lv_pct(x)`) values can be used. Percentage values are relative to the object's height. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### transform_zoom +Zoom an objects. The value 256 (or `LV_IMG_ZOOM_NONE`) means normal size, 128 half size, 512 double size, and so on +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> Yes</li> +</ul> + +### transform_angle +Rotate an objects. The value is interpreted in 0.1 degree units. E.g. 450 means 45 deg. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> Yes</li> +</ul> + +### transform_pivot_x +Set the pivot point's X coordinate for transformations. Relative to the object's top left corner' +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### transform_pivot_y +Set the pivot point's Y coordinate for transformations. Relative to the object's top left corner' +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +## Padding +Properties to describe spacing between the parent's sides and the children and among the children. Very similar to the padding properties in HTML. + +### pad_top +Sets the padding on the top. It makes the content area smaller in this direction. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### pad_bottom +Sets the padding on the bottom. It makes the content area smaller in this direction. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### pad_left +Sets the padding on the left. It makes the content area smaller in this direction. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### pad_right +Sets the padding on the right. It makes the content area smaller in this direction. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### pad_row +Sets the padding between the rows. Used by the layouts. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### pad_column +Sets the padding between the columns. Used by the layouts. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +## Background +Properties to describe the background color and image of the objects. + +### bg_color +Set the background color of the object. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `0xffffff`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### bg_opa +Set the opacity of the background. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_OPA_TRANSP`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### bg_grad_color +Set the gradient color of the background. Used only if `grad_dir` is not `LV_GRAD_DIR_NONE` +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `0x000000`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### bg_grad_dir +Set the direction of the gradient of the background. The possible values are `LV_GRAD_DIR_NONE/HOR/VER`. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_GRAD_DIR_NONE`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### bg_main_stop +Set the point from which the background color should start for gradients. 0 means to top/left side, 255 the bottom/right side, 128 the center, and so on +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### bg_grad_stop +Set the point from which the background's gradient color should start. 0 means to top/left side, 255 the bottom/right side, 128 the center, and so on +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 255</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### bg_grad +Set the gradient definition. The pointed instance must exist while the object is alive. NULL to disable. It wraps `BG_GRAD_COLOR`, `BG_GRAD_DIR`, `BG_MAIN_STOP` and `BG_GRAD_STOP` into one descriptor and allows creating gradients with more colors too. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `NULL`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### bg_dither_mode +Set the dithering mode of the gradient of the background. The possible values are `LV_DITHER_NONE/ORDERED/ERR_DIFF`. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_DITHER_NONE`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### bg_img_src +Set a background image. Can be a pointer to `lv_img_dsc_t`, a path to a file or an `LV_SYMBOL_...` +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `NULL`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> Yes</li> +</ul> + +### bg_img_opa +Set the opacity of the background image. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_OPA_COVER`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### bg_img_recolor +Set a color to mix to the background image. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `0x000000`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### bg_img_recolor_opa +Set the intensity of background image recoloring. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means no mixing, 255, `LV_OPA_100` or `LV_OPA_COVER` means full recoloring, other values or LV_OPA_10, LV_OPA_20, etc are interpreted proportionally. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_OPA_TRANSP`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### bg_img_tiled +If enabled the background image will be tiled. The possible values are `true` or `false`. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +## Border +Properties to describe the borders + +### border_color +Set the color of the border +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `0x000000`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### border_opa +Set the opacity of the border. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_OPA_COVER`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### border_width +Set hte width of the border. Only pixel values can be used. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### border_side +Set only which side(s) the border should be drawn. The possible values are `LV_BORDER_SIDE_NONE/TOP/BOTTOM/LEFT/RIGHT/INTERNAL`. OR-ed values can be used as well, e.g. `LV_BORDER_SIDE_TOP | LV_BORDER_SIDE_LEFT`. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_BORDER_SIDE_NONE`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### border_post +Sets whether the border should be drawn before or after the children are drawn. `true`: after children, `false`: before children +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +## Outline +Properties to describe the outline. It's like a border but drawn outside of the rectangles. + +### outline_width +Set the width of the outline in pixels. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> Yes</li> +</ul> + +### outline_color +Set the color of the outline. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `0x000000`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### outline_opa +Set the opacity of the outline. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_OPA_COVER`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> Yes</li> +</ul> + +### outline_pad +Set the padding of the outline, i.e. the gap between object and the outline. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> Yes</li> +</ul> + +## Shadow +Properties to describe the shadow drawn under the rectangles. + +### shadow_width +Set the width of the shadow in pixels. The value should be >= 0. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> Yes</li> +</ul> + +### shadow_ofs_x +Set an offset on the shadow in pixels in X direction. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> Yes</li> +</ul> + +### shadow_ofs_y +Set an offset on the shadow in pixels in Y direction. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> Yes</li> +</ul> + +### shadow_spread +Make the shadow calculation to use a larger or smaller rectangle as base. The value can be in pixel to make the area larger/smaller +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> Yes</li> +</ul> + +### shadow_color +Set the color of the shadow +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `0x000000`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### shadow_opa +Set the opacity of the shadow. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_OPA_COVER`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> Yes</li> +</ul> + +## Image +Properties to describe the images + +### img_opa +Set the opacity of an image. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_OPA_COVER`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### img_recolor +Set color to mixt to the image. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `0x000000`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### img_recolor_opa +Set the intensity of the color mixing. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +## Line +Properties to describe line-like objects + +### line_width +Set the width of the lines in pixel. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> Yes</li> +</ul> + +### line_dash_width +Set the width of dashes in pixel. Note that dash works only on horizontal and vertical lines +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### line_dash_gap +Set the gap between dashes in pixel. Note that dash works only on horizontal and vertical lines +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### line_rounded +Make the end points of the lines rounded. `true`: rounded, `false`: perpendicular line ending +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### line_color +Set the color fo the lines. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `0x000000`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### line_opa +Set the opacity of the lines. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_OPA_COVER`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +## Arc +TODO + +### arc_width +Set the width (thickness) of the arcs in pixel. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> Yes</li> +</ul> + +### arc_rounded +Make the end points of the arcs rounded. `true`: rounded, `false`: perpendicular line ending +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### arc_color +Set the color of the arc. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `0x000000`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### arc_opa +Set the opacity of the arcs. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_OPA_COVER`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### arc_img_src +Set an image from which the arc will be masked out. It's useful to display complex effects on the arcs. Can be a pointer to `lv_img_dsc_t` or a path to a file +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `NULL`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +## Text +Properties to describe the properties of text. All these properties are inherited. + +### text_color +Sets the color of the text. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `0x000000`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### text_opa +Set the opacity of the text. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_OPA_COVER`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### text_font +Set the font of the text (a pointer `lv_font_t *`). +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_FONT_DEFAULT`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### text_letter_space +Set the letter space in pixels +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### text_line_space +Set the line space in pixels. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### text_decor +Set decoration for the text. The possible values are `LV_TEXT_DECOR_NONE/UNDERLINE/STRIKETHROUGH`. OR-ed values can be used as well. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_TEXT_DECOR_NONE`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### text_align +Set how to align the lines of the text. Note that it doesn't align the object itself, only the lines inside the object. The possible values are `LV_TEXT_ALIGN_LEFT/CENTER/RIGHT/AUTO`. `LV_TEXT_ALIGN_AUTO` detect the text base direction and uses left or right alignment accordingly +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_TEXT_ALIGN_AUTO`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +## Miscellaneous +Mixed properties for various purposes. + +### radius +Set the radius on every corner. The value is interpreted in pixel (>= 0) or `LV_RADIUS_CIRCLE` for max. radius +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### clip_corner +Enable to clip the overflowed content on the rounded corner. Can be `true` or `false`. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### opa +Scale down all opacity values of the object by this factor. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_OPA_COVER`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### color_filter_dsc +Mix a color to all colors of the object. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `NULL`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### color_filter_opa +The intensity of mixing of color filter. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_OPA_TRANSP`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### anim +The animation template for the object's animation. Should be a pointer to `lv_anim_t`. The animation parameters are widget specific, e.g. animation time could be the E.g. blink time of the cursor on the text area or scroll time of a roller. See the widgets' documentation to learn more. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `NULL`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### anim_time +The animation time in milliseconds. Its meaning is widget specific. E.g. blink time of the cursor on the text area or scroll time of a roller. See the widgets' documentation to learn more. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### anim_speed +The animation speed in pixel/sec. Its meaning is widget specific. E.g. scroll speed of label. See the widgets' documentation to learn more. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### transition +An initialized `lv_style_transition_dsc_t` to describe a transition. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `NULL`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### blend_mode +Describes how to blend the colors to the background. The possible values are `LV_BLEND_MODE_NORMAL/ADDITIVE/SUBTRACTIVE/MULTIPLY` +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_BLEND_MODE_NORMAL`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### layout +Set the layout if the object. The children will be repositioned and resized according to the policies set for the layout. For the possible values see the documentation of the layouts. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> 0</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> No</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> + +### base_dir +Set the base direction of the object. The possible values are `LV_BIDI_DIR_LTR/RTL/AUTO`. +<ul> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Default</strong> `LV_BASE_DIR_AUTO`</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Inherited</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Layout</strong> Yes</li> +<li style='display:inline; margin-right: 20px; margin-left: 0px'><strong>Ext. draw</strong> No</li> +</ul> diff --git a/lib/lvgl/docs/overview/style.md b/lib/lvgl/docs/overview/style.md new file mode 100644 index 00000000..25d8ce65 --- /dev/null +++ b/lib/lvgl/docs/overview/style.md @@ -0,0 +1,361 @@ +# Styles + +*Styles* are used to set the appearance of objects. Styles in lvgl are heavily inspired by CSS. The concept in a nutshell is as follows: +- A style is an `lv_style_t` variable which can hold properties like border width, text color and so on. It's similar to a `class` in CSS. +- Styles can be assigned to objects to change their appearance. Upon assignment, the target part (*pseudo-element* in CSS) and target state (*pseudo class*) can be specified. +For example one can add `style_blue` to the knob of a slider when it's in pressed state. +- The same style can be used by any number of objects. +- Styles can be cascaded which means multiple styles may be assigned to an object and each style can have different properties. +Therefore, not all properties have to be specified in a style. LVGL will search for a property until a style defines it or use a default if it's not specified by any of the styles. +For example `style_btn` can result in a default gray button and `style_btn_red` can add only a `background-color=red` to overwrite the background color. +- The most recently added style has higher precedence. This means if a property is specified in two styles the newest style in the object will be used. +- Some properties (e.g. text color) can be inherited from a parent(s) if it's not specified in an object. +- Objects can also have local styles with higher precedence than "normal" styles. +- Unlike CSS (where pseudo-classes describe different states, e.g. `:focus`), in LVGL a property is assigned to a given state. +- Transitions can be applied when the object changes state. + + +## States +The objects can be in the combination of the following states: +- `LV_STATE_DEFAULT` (0x0000) Normal, released state +- `LV_STATE_CHECKED` (0x0001) Toggled or checked state +- `LV_STATE_FOCUSED` (0x0002) Focused via keypad or encoder or clicked via touchpad/mouse +- `LV_STATE_FOCUS_KEY` (0x0004) Focused via keypad or encoder but not via touchpad/mouse +- `LV_STATE_EDITED` (0x0008) Edit by an encoder +- `LV_STATE_HOVERED` (0x0010) Hovered by mouse (not supported now) +- `LV_STATE_PRESSED` (0x0020) Being pressed +- `LV_STATE_SCROLLED` (0x0040) Being scrolled +- `LV_STATE_DISABLED` (0x0080) Disabled state +- `LV_STATE_USER_1` (0x1000) Custom state +- `LV_STATE_USER_2` (0x2000) Custom state +- `LV_STATE_USER_3` (0x4000) Custom state +- `LV_STATE_USER_4` (0x8000) Custom state + +An object can be in a combination of states such as being focused and pressed at the same time. This is represented as `LV_STATE_FOCUSED | LV_STATE_PRESSED`. + +A style can be added to any state or state combination. +For example, setting a different background color for the default and pressed states. +If a property is not defined in a state the best matching state's property will be used. Typically this means the property with `LV_STATE_DEFAULT` is used.˛ +If the property is not set even for the default state the default value will be used. (See later) + +But what does the "best matching state's property" really mean? +States have a precedence which is shown by their value (see in the above list). A higher value means higher precedence. +To determine which state's property to use let's take an example. Imagine the background color is defined like this: +- `LV_STATE_DEFAULT`: white +- `LV_STATE_PRESSED`: gray +- `LV_STATE_FOCUSED`: red + +1. Initially the object is in the default state, so it's a simple case: the property is perfectly defined in the object's current state as white. +2. When the object is pressed there are 2 related properties: default with white (default is related to every state) and pressed with gray. +The pressed state has 0x0020 precedence which is higher than the default state's 0x0000 precedence, so gray color will be used. +3. When the object is focused the same thing happens as in pressed state and red color will be used. (Focused state has higher precedence than default state). +4. When the object is focused and pressed both gray and red would work, but the pressed state has higher precedence than focused so gray color will be used. +5. It's possible to set e.g. rose color for `LV_STATE_PRESSED | LV_STATE_FOCUSED`. +In this case, this combined state has 0x0020 + 0x0002 = 0x0022 precedence, which is higher than the pressed state's precedence so rose color would be used. +6. When the object is in the checked state there is no property to set the background color for this state. So for lack of a better option, the object remains white from the default state's property. + +Some practical notes: +- The precedence (value) of states is quite intuitive, and it's something the user would expect naturally. E.g. if an object is focused the user will still want to see if it's pressed, therefore the pressed state has a higher precedence. +If the focused state had a higher precedence it would overwrite the pressed color. +- If you want to set a property for all states (e.g. red background color) just set it for the default state. If the object can't find a property for its current state it will fall back to the default state's property. +- Use ORed states to describe the properties for complex cases. (E.g. pressed + checked + focused) +- It might be a good idea to use different style elements for different states. +For example, finding background colors for released, pressed, checked + pressed, focused, focused + pressed, focused + pressed + checked, etc. states is quite difficult. +Instead, for example, use the background color for pressed and checked states and indicate the focused state with a different border color. + +## Cascading styles +It's not required to set all the properties in one style. It's possible to add more styles to an object and have the latter added style modify or extend appearance. +For example, create a general gray button style and create a new one for red buttons where only the new background color is set. + +This is much like in CSS when used classes are listed like `<div class=".btn .btn-red">`. + +Styles added later have precedence over ones set earlier. So in the gray/red button example above, the normal button style should be added first and the red style second. +However, the precedence of the states are still taken into account. +So let's examine the following case: +- the basic button style defines dark-gray color for the default state and light-gray color for the pressed state +- the red button style defines the background color as red only in the default state + +In this case, when the button is released (it's in default state) it will be red because a perfect match is found in the most recently added style (red). +When the button is pressed the light-gray color is a better match because it describes the current state perfectly, so the button will be light-gray. + +## Inheritance +Some properties (typically those related to text) can be inherited from the parent object's styles. +Inheritance is applied only if the given property is not set in the object's styles (even in default state). +In this case, if the property is inheritable, the property's value will be searched in the parents until an object specifies a value for the property. The parents will use their own state to determine the value. +So if a button is pressed, and the text color comes from here, the pressed text color will be used. + +## Forced value inheritance/default value +Sometimes you may want to force a child object to use the parent's value for a given style property. To do this you can use +one of the following (depending on what type of style you're using): + +```c +/* regular style */ +lv_style_set_prop_meta(&style, LV_STYLE_TEXT_COLOR, LV_STYLE_PROP_META_INHERIT); +/* local style */ +lv_obj_set_local_style_prop_meta(child, LV_STYLE_TEXT_COLOR, LV_STYLE_PROP_META_INHERIT, LV_PART_MAIN); +``` + +This acts like a value has been set on the style, so setting the value of the property afterwards will remove the flag. + +You may also want to force the default value of a property to be used, without needing to hardcode it in your application. +To do this you can use the same API but with `LV_STYLE_PROP_META_INITIAL` instead. In future versions of LVGL, this +will use the value based upon the current theme, but for now it just selects the internal default regardless of theme. + + +## Parts +Objects can be composed of *parts* which may each have their own styles. + +The following predefined parts exist in LVGL: +- `LV_PART_MAIN` A background like rectangle +- `LV_PART_SCROLLBAR` The scrollbar(s) +- `LV_PART_INDICATOR` Indicator, e.g. for slider, bar, switch, or the tick box of the checkbox +- `LV_PART_KNOB` Like a handle to grab to adjust a value +- `LV_PART_SELECTED` Indicate the currently selected option or section +- `LV_PART_ITEMS` Used if the widget has multiple similar elements (e.g. table cells) +- `LV_PART_TICKS` Ticks on scales e.g. for a chart or meter +- `LV_PART_CURSOR` Mark a specific place e.g. text area's or chart's cursor +- `LV_PART_CUSTOM_FIRST` Custom part identifiers can be added starting from here. + + +For example a [Slider](/widgets/core/slider) has three parts: +- Background +- Indicator +- Knob + +This means all three parts of the slider can have their own styles. See later how to add styles to objects and parts. + +## Initialize styles and set/get properties + +Styles are stored in `lv_style_t` variables. Style variables should be `static`, global or dynamically allocated. +In other words they cannot be local variables in functions which are destroyed when the function exits. +Before using a style it should be initialized with `lv_style_init(&my_style)`. +After initializing a style, properties can be added or changed. + +Property set functions looks like this: `lv_style_set_<property_name>(&style, <value>);` For example: +```c +static lv_style_t style_btn; +lv_style_init(&style_btn); +lv_style_set_bg_color(&style_btn, lv_color_hex(0x115588)); +lv_style_set_bg_opa(&style_btn, LV_OPA_50); +lv_style_set_border_width(&style_btn, 2); +lv_style_set_border_color(&style_btn, lv_color_black()); + +static lv_style_t style_btn_red; +lv_style_init(&style_btn_red); +lv_style_set_bg_color(&style_btn_red, lv_plaette_main(LV_PALETTE_RED)); +lv_style_set_bg_opa(&style_btn_red, LV_OPA_COVER); +``` + +To remove a property use: + +```c +lv_style_remove_prop(&style, LV_STYLE_BG_COLOR); +``` + +To get a property's value from a style: +```c +lv_style_value_t v; +lv_res_t res = lv_style_get_prop(&style, LV_STYLE_BG_COLOR, &v); +if(res == LV_RES_OK) { /*Found*/ + do_something(v.color); +} +``` + +`lv_style_value_t` has 3 fields: +- `num` for integer, boolean and opacity properties +- `color` for color properties +- `ptr` for pointer properties + +To reset a style (free all its data) use: +```c +lv_style_reset(&style); +``` + +Styles can be built as `const` too to save RAM: +```c +const lv_style_const_prop_t style1_props[] = { + LV_STYLE_CONST_WIDTH(50), + LV_STYLE_CONST_HEIGHT(50), + LV_STYLE_PROP_INV, +}; + +LV_STYLE_CONST_INIT(style1, style1_props); +``` + +Later `const` style can be used like any other style but (obviously) new properties can not be added. + + +## Add and remove styles to a widget +A style on its own is not that useful. It must be assigned to an object to take effect. + +### Add styles +To add a style to an object use `lv_obj_add_style(obj, &style, <selector>)`. `<selector>` is an OR-ed value of parts and state to which the style should be added. Some examples: +- `LV_PART_MAIN | LV_STATE_DEFAULT` +- `LV_STATE_PRESSED`: The main part in pressed state. `LV_PART_MAIN` can be omitted +- `LV_PART_SCROLLBAR`: The scrollbar part in the default state. `LV_STATE_DEFAULT` can be omitted. +- `LV_PART_SCROLLBAR | LV_STATE_SCROLLED`: The scrollbar part when the object is being scrolled +- `0` Same as `LV_PART_MAIN | LV_STATE_DEFAULT`. +- `LV_PART_INDICATOR | LV_STATE_PRESSED | LV_STATE_CHECKED` The indicator part when the object is pressed and checked at the same time. + +Using `lv_obj_add_style`: +```c +lv_obj_add_style(btn, &style_btn, 0); /*Default button style*/ +lv_obj_add_style(btn, &btn_red, LV_STATE_PRESSED); /*Overwrite only some colors to red when pressed*/ +``` + +### Remove styles +To remove all styles from an object use `lv_obj_remove_style_all(obj)`. + +To remove specific styles use `lv_obj_remove_style(obj, style, selector)`. This function will remove `style` only if the `selector` matches with the `selector` used in `lv_obj_add_style`. +`style` can be `NULL` to check only the `selector` and remove all matching styles. The `selector` can use the `LV_STATE_ANY` and `LV_PART_ANY` values to remove the style from any state or part. + + +### Report style changes +If a style which is already assigned to an object changes (i.e. a property is added or changed), the objects using that style should be notified. There are 3 options to do this: +1. If you know that the changed properties can be applied by a simple redraw (e.g. color or opacity changes) just call `lv_obj_invalidate(obj)` or `lv_obj_invalidate(lv_scr_act())`. +2. If more complex style properties were changed or added, and you know which object(s) are affected by that style call `lv_obj_refresh_style(obj, part, property)`. +To refresh all parts and properties use `lv_obj_refresh_style(obj, LV_PART_ANY, LV_STYLE_PROP_ANY)`. +3. To make LVGL check all objects to see if they use a style and refresh them when needed, call `lv_obj_report_style_change(&style)`. If `style` is `NULL` all objects will be notified about a style change. + +### Get a property's value on an object +To get a final value of property - considering cascading, inheritance, local styles and transitions (see below) - property get functions like this can be used: +`lv_obj_get_style_<property_name>(obj, <part>)`. +These functions use the object's current state and if no better candidate exists they return a default value. +For example: +```c +lv_color_t color = lv_obj_get_style_bg_color(btn, LV_PART_MAIN); +``` + +## Local styles +In addition to "normal" styles, objects can also store local styles. This concept is similar to inline styles in CSS (e.g. `<div style="color:red">`) with some modification. + +Local styles are like normal styles, but they can't be shared among other objects. If used, local styles are allocated automatically, and freed when the object is deleted. +They are useful to add local customization to an object. + +Unlike in CSS, LVGL local styles can be assigned to states (*pseudo-classes*) and parts (*pseudo-elements*). + +To set a local property use functions like `lv_obj_set_style_<property_name>(obj, <value>, <selector>);` +For example: +```c +lv_obj_set_style_bg_color(slider, lv_color_red(), LV_PART_INDICATOR | LV_STATE_FOCUSED); +``` +## Properties +For the full list of style properties click [here](/overview/style-props). + +### Typical background properties +In the documentation of the widgets you will see sentences like "The widget uses the typical background properties". These "typical background properties" are the ones related to: +- Background +- Border +- Outline +- Shadow +- Padding +- Width and height transformation +- X and Y translation + + +## Transitions +By default, when an object changes state (e.g. it's pressed) the new properties from the new state are set immediately. However, with transitions it's possible to play an animation on state change. +For example, on pressing a button its background color can be animated to the pressed color over 300 ms. + +The parameters of the transitions are stored in the styles. It's possible to set +- the time of the transition +- the delay before starting the transition +- the animation path (also known as the timing or easing function) +- the properties to animate + +The transition properties can be defined for each state. For example, setting a 500 ms transition time in the default state means that when the object goes to the default state a 500 ms transition time is applied. +Setting a 100 ms transition time in the pressed state causes a 100 ms transition when going to the pressed state. +This example configuration results in going to the pressed state quickly and then going back to default slowly. + +To describe a transition an `lv_transition_dsc_t` variable needs to be initialized and added to a style: +```c +/*Only its pointer is saved so must static, global or dynamically allocated */ +static const lv_style_prop_t trans_props[] = { + LV_STYLE_BG_OPA, LV_STYLE_BG_COLOR, + 0, /*End marker*/ +}; + +static lv_style_transition_dsc_t trans1; +lv_style_transition_dsc_init(&trans1, trans_props, lv_anim_path_ease_out, duration_ms, delay_ms); + +lv_style_set_transition(&style1, &trans1); +``` + +## Opacity, Blend modes and Transformations +If the `opa`, `blend_mode`, `transform_angle`, or `transform_zoom` properties are set to their non-default value LVGL creates a snapshot about the widget and all its children in order to blend the whole widget with the set opacity, blend mode and transformation properties. + +These properties have this effect only on the `MAIN` part of the widget. + +The created snapshot is called "intermediate layer" or simply "layer". If only `opa` and/or `blend_mode` is set to a non-default value LVGL can build the layer from smaller chunks. The size of these chunks can be configured by the following properties in `lv_conf.h`: + - `LV_LAYER_SIMPLE_BUF_SIZE`: [bytes] the optimal target buffer size. LVGL will try to allocate this size of memory. + - `LV_LAYER_SIMPLE_FALLBACK_BUF_SIZE`: [bytes] used if `LV_LAYER_SIMPLE_BUF_SIZE` couldn't be allocated. + +If transformation properties were also used the layer can not be rendered in chunks, but one larger memory needs to be allocated. The required memory depends on the angle, zoom and pivot parameters, and the size of the area to redraw, but it's never larger than the size of the widget (including the extra draw size used for shadow, outline, etc). + +If the widget can fully cover the area to redraw, LVGL creates an RGB layer (which is faster to render and uses less memory). If the opposite case ARGB rendering needs to be used. A widget might not cover its area if it has radius, `bg_opa != 255`, has shadow, outline, etc. + +The click area of the widget is also transformed accordingly. + + +## Color filter +TODO + + +## Themes +Themes are a collection of styles. If there is an active theme LVGL applies it on every created widget. +This will give a default appearance to the UI which can then be modified by adding further styles. + +Every display can have a different theme. For example, you could have a colorful theme on a TFT and monochrome theme on a secondary monochrome display. + +To set a theme for a display, two steps are required: +1. Initialize a theme +2. Assign the initialized theme to a display. + +Theme initialization functions can have different prototypes. This example shows how to set the "default" theme: +```c +lv_theme_t * th = lv_theme_default_init(display, /*Use the DPI, size, etc from this display*/ + LV_COLOR_PALETTE_BLUE, LV_COLOR_PALETTE_CYAN, /*Primary and secondary palette*/ + false, /*Light or dark mode*/ + &lv_font_montserrat_10, &lv_font_montserrat_14, &lv_font_montserrat_18); /*Small, normal, large fonts*/ + +lv_disp_set_theme(display, th); /*Assign the theme to the display*/ +``` + + +The included themes are enabled in `lv_conf.h`. If the default theme is enabled by `LV_USE_THEME_DEFAULT 1` LVGL automatically initializes and sets it when a display is created. + +### Extending themes + +Built-in themes can be extended. +If a custom theme is created, a parent theme can be selected. The parent theme's styles will be added before the custom theme's styles. +Any number of themes can be chained this way. E.g. default theme -> custom theme -> dark theme. + +`lv_theme_set_parent(new_theme, base_theme)` extends the `base_theme` with the `new_theme`. + +There is an example for it below. + +## Examples + +```eval_rst + +.. include:: ../../examples/styles/index.rst + +``` + +## API +```eval_rst + +.. doxygenfile:: lv_style.h + :project: lvgl + +.. doxygenfile:: lv_theme.h + :project: lvgl + +.. doxygenfile:: lv_obj_style_gen.h + :project: lvgl + +.. doxygenfile:: lv_style_gen.h + :project: lvgl + + +``` diff --git a/lib/lvgl/docs/overview/timer.md b/lib/lvgl/docs/overview/timer.md new file mode 100644 index 00000000..ca014c7e --- /dev/null +++ b/lib/lvgl/docs/overview/timer.md @@ -0,0 +1,99 @@ +# Timers + +LVGL has a built-in timer system. You can register a function to have it be called periodically. The timers are handled and called in `lv_timer_handler()`, which needs to be called every few milliseconds. +See [Porting](/porting/timer-handler) for more information. + +Timers are non-preemptive, which means a timer cannot interrupt another timer. Therefore, you can call any LVGL related function in a timer. + + +## Create a timer +To create a new timer, use `lv_timer_create(timer_cb, period_ms, user_data)`. It will create an `lv_timer_t *` variable, which can be used later to modify the parameters of the timer. +`lv_timer_create_basic()` can also be used. This allows you to create a new timer without specifying any parameters. + +A timer callback should have a `void (*lv_timer_cb_t)(lv_timer_t *);` prototype. + +For example: +```c +void my_timer(lv_timer_t * timer) +{ + /*Use the user_data*/ + uint32_t * user_data = timer->user_data; + printf("my_timer called with user data: %d\n", *user_data); + + /*Do something with LVGL*/ + if(something_happened) { + something_happened = false; + lv_btn_create(lv_scr_act(), NULL); + } +} + +... + +static uint32_t user_data = 10; +lv_timer_t * timer = lv_timer_create(my_timer, 500, &user_data); + +``` + +## Ready and Reset + +`lv_timer_ready(timer)` makes a timer run on the next call of `lv_timer_handler()`. + +`lv_timer_reset(timer)` resets the period of a timer. It will be called again after the defined period of milliseconds has elapsed. + + +## Set parameters +You can modify some timer parameters later: +- `lv_timer_set_cb(timer, new_cb)` +- `lv_timer_set_period(timer, new_period)` + +## Repeat count + +You can make a timer repeat only a given number of times with `lv_timer_set_repeat_count(timer, count)`. The timer will automatically be deleted after it's called the defined number of times. Set the count to `-1` to repeat indefinitely. + + +## Measure idle time + +You can get the idle percentage time of `lv_timer_handler` with `lv_timer_get_idle()`. Note that, it doesn't measure the idle time of the overall system, only `lv_timer_handler`. +It can be misleading if you use an operating system and call `lv_timer_handler` in a timer, as it won't actually measure the time the OS spends in an idle thread. + +## Asynchronous calls + +In some cases, you can't perform an action immediately. For example, you can't delete an object because something else is still using it, or you don't want to block the execution now. +For these cases, `lv_async_call(my_function, data_p)` can be used to call `my_function` on the next invocation of `lv_timer_handler`. `data_p` will be passed to the function when it's called. +Note that only the data pointer is saved, so you need to ensure that the variable will be "alive" while the function is called. It can be *static*, global or dynamically allocated data. +If you want to cancel an asynchronous call, call `lv_async_call_cancel(my_function, data_p)`, which will clear all asynchronous calls matching `my_function` and `data_p`. + +For example: +```c +void my_screen_clean_up(void * scr) +{ + /*Free some resources related to `scr`*/ + + /*Finally delete the screen*/ + lv_obj_del(scr); +} + +... + +/*Do something with the object on the current screen*/ + +/*Delete screen on next call of `lv_timer_handler`, not right now.*/ +lv_async_call(my_screen_clean_up, lv_scr_act()); + +/*The screen is still valid so you can do other things with it*/ + +``` + +If you just want to delete an object and don't need to clean anything up in `my_screen_cleanup` you could just use `lv_obj_del_async` which will delete the object on the next call to `lv_timer_handler`. + +## API + +```eval_rst + +.. doxygenfile:: lv_timer.h + :project: lvgl + +.. doxygenfile:: lv_async.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/porting/display.md b/lib/lvgl/docs/porting/display.md new file mode 100644 index 00000000..f06d48d0 --- /dev/null +++ b/lib/lvgl/docs/porting/display.md @@ -0,0 +1,243 @@ +# Display interface + +To register a display for LVGL, a `lv_disp_draw_buf_t` and a `lv_disp_drv_t` variable have to be initialized. +- `lv_disp_draw_buf_t` contains internal graphic buffer(s) called draw buffer(s). +- `lv_disp_drv_t` contains callback functions to interact with the display and manipulate low level drawing behavior. + +## Draw buffer + +Draw buffer(s) are simple array(s) that LVGL uses to render the screen content. +Once rendering is ready the content of the draw buffer is sent to the display using the `flush_cb` function set in the display driver (see below). + +A draw buffer can be initialized via a `lv_disp_draw_buf_t` variable like this: +```c +/*A static or global variable to store the buffers*/ +static lv_disp_draw_buf_t disp_buf; + +/*Static or global buffer(s). The second buffer is optional*/ +static lv_color_t buf_1[MY_DISP_HOR_RES * 10]; +static lv_color_t buf_2[MY_DISP_HOR_RES * 10]; + +/*Initialize `disp_buf` with the buffer(s). With only one buffer use NULL instead buf_2 */ +lv_disp_draw_buf_init(&disp_buf, buf_1, buf_2, MY_DISP_HOR_RES*10); +``` + +Note that `lv_disp_draw_buf_t` must be a static, global or dynamically allocated variable. It cannot be a local variable as they are destroyed upon end of scope. + +As you can see above, the draw buffer may be smaller than the screen. In this case, larger areas are redrawn in smaller segments that fit into the draw buffer(s). +If only a small area changes (e.g. a button is pressed) then only that area will be refreshed. + +A larger buffer results in better performance but above 1/10 screen sized buffer(s) there is no significant performance improvement. +Therefore it's recommended to choose the size of the draw buffer(s) to be at least 1/10 screen sized. + +## Buffering modes + +There are several settings to adjust the number draw buffers and buffering/refreshing modes. + +You can measure the performance of different configurations using the [benchmark example](https://github.com/lvgl/lvgl/tree/master/demos/benchmark). + +### One buffer +If only one buffer is used LVGL draws the content of the screen into that draw buffer and sends it to the display. +LVGL then needs to wait until the content of the buffer is sent to the display before drawing something new in it. + +### Two buffers +If two buffers are used LVGL can draw into one buffer while the content of the other buffer is sent to the display in the background. +DMA or other hardware should be used to transfer data to the display so the MCU can continue drawing. +This way, the rendering and refreshing of the display become parallel operations. + +### Full refresh +In the display driver (`lv_disp_drv_t`) enabling the `full_refresh` bit will force LVGL to always redraw the whole screen. This works in both *one buffer* and *two buffers* modes. +If `full_refresh` is enabled and two screen sized draw buffers are provided, LVGL's display handling works like "traditional" double buffering. +This means the `flush_cb` callback only has to update the address of the framebuffer (`color_p` parameter). +This configuration should be used if the MCU has an LCD controller peripheral and not with an external display controller (e.g. ILI9341 or SSD1963) accessed via serial link. The latter will generally be too slow to maintain high frame rates with full screen redraws. + +### Direct mode +If the `direct_mode` flag is enabled in the display driver LVGL will draw directly into a **screen sized frame buffer**. That is the draw buffer(s) needs to be screen sized. +It this case `flush_cb` will be called only once when all dirty areas are redrawn. +With `direct_mode` the frame buffer always contains the current frame as it should be displayed on the screen. +If 2 frame buffers are provided as draw buffers LVGL will alter the buffers but always draw only the dirty areas. +Therefore the 2 buffers needs to synchronized in `flush_cb` like this: +1. Display the frame buffer pointed by `color_p` +2. Copy the redrawn areas from `color_p` to the other buffer. + +The get the redrawn areas to copy use the following functions +`_lv_refr_get_disp_refreshing()` returns the display being refreshed +`disp->inv_areas[LV_INV_BUF_SIZE]` contains the invalidated areas +`disp->inv_area_joined[LV_INV_BUF_SIZE]` if 1 that area was joined into another one and should be ignored +`disp->inv_p` number of valid elements in `inv_areas` + +## Display driver + +Once the buffer initialization is ready a `lv_disp_drv_t` display driver needs to be: +1. initialized with `lv_disp_drv_init(&disp_drv)` +2. its fields need to be set +3. it needs to be registered in LVGL with `lv_disp_drv_register(&disp_drv)` + +Note that `lv_disp_drv_t` also needs to be a static, global or dynamically allocated variable. + +### Mandatory fields +In the most simple case only the following fields of `lv_disp_drv_t` need to be set: +- `draw_buf` pointer to an initialized `lv_disp_draw_buf_t` variable. +- `hor_res` horizontal resolution of the display in pixels. +- `ver_res` vertical resolution of the display in pixels. +- `flush_cb` a callback function to copy a buffer's content to a specific area of the display. +`lv_disp_flush_ready(&disp_drv)` needs to be called when flushing is ready. +LVGL might render the screen in multiple chunks and therefore call `flush_cb` multiple times. To see if the current one is the last chunk of rendering use `lv_disp_flush_is_last(&disp_drv)`. + +### Optional fields +There are some optional display driver data fields: +- `physical_hor_res` horizontal resolution of the full / physical display in pixels. Only set this when _not_ using the full screen (defaults to -1 / same as `hor_res`). +- `physical_ver_res` vertical resolution of the full / physical display in pixels. Only set this when _not_ using the full screen (defaults to -1 / same as `ver_res`). +- `offset_x` horizontal offset from the full / physical display in pixels. Only set this when _not_ using the full screen (defaults to 0). +- `offset_y` vertical offset from the full / physical display in pixels. Only set this when _not_ using the full screen (defaults to 0). +- `color_chroma_key` A color which will be drawn as transparent on chrome keyed images. Set to `LV_COLOR_CHROMA_KEY` from `lv_conf.h` by default. +- `anti_aliasing` use anti-aliasing (edge smoothing). Enabled by default if `LV_COLOR_DEPTH` is set to at least 16 in `lv_conf.h`. +- `rotated` and `sw_rotate` See the [Rotation](#rotation) section below. +- `screen_transp` if `1` the screen itself can have transparency as well. `LV_COLOR_SCREEN_TRANSP` must be enabled in `lv_conf.h` and `LV_COLOR_DEPTH` must be 32. +- `user_data` A custom `void` user data for the driver. +- `full_refresh` always redrawn the whole screen (see above) +- `direct_mode` draw directly into the frame buffer (see above) + +Some other optional callbacks to make it easier and more optimal to work with monochrome, grayscale or other non-standard RGB displays: +- `rounder_cb` Round the coordinates of areas to redraw. E.g. a 2x2 px can be converted to 2x8. +It can be used if the display controller can refresh only areas with specific height or width (usually 8 px height with monochrome displays). +- `set_px_cb` a custom function to write the draw buffer. It can be used to store the pixels more compactly in the draw buffer if the display has a special color format. (e.g. 1-bit monochrome, 2-bit grayscale etc.) +This way the buffers used in `lv_disp_draw_buf_t` can be smaller to hold only the required number of bits for the given area size. Note that rendering with `set_px_cb` is slower than normal rendering. +- `monitor_cb` A callback function that tells how many pixels were refreshed and in how much time. Called when the last chunk is rendered and sent to the display. +- `clean_dcache_cb` A callback for cleaning any caches related to the display. +- `render_start_cb` A callback function that notifies the display driver that rendering has started. It also could be used to wait for VSYNC to start rendering. It's useful if rendering is faster than a VSYNC period. + +LVGL has built-in support to several GPUs (see `lv_conf.h`) but if something else is required these functions can be used to make LVGL use a GPU: +- `gpu_fill_cb` fill an area in the memory with a color. +- `gpu_wait_cb` if any GPU function returns while the GPU is still working, LVGL will use this function when required to make sure GPU rendering is ready. + +### Examples +All together it looks like this: +```c +static lv_disp_drv_t disp_drv; /*A variable to hold the drivers. Must be static or global.*/ +lv_disp_drv_init(&disp_drv); /*Basic initialization*/ +disp_drv.draw_buf = &disp_buf; /*Set an initialized buffer*/ +disp_drv.flush_cb = my_flush_cb; /*Set a flush callback to draw to the display*/ +disp_drv.hor_res = 320; /*Set the horizontal resolution in pixels*/ +disp_drv.ver_res = 240; /*Set the vertical resolution in pixels*/ + +lv_disp_t * disp; +disp = lv_disp_drv_register(&disp_drv); /*Register the driver and save the created display objects*/ +``` + +Here are some simple examples of the callbacks: +```c +void my_flush_cb(lv_disp_drv_t * disp_drv, const lv_area_t * area, lv_color_t * color_p) +{ + /*The most simple case (but also the slowest) to put all pixels to the screen one-by-one + *`put_px` is just an example, it needs to implemented by you.*/ + int32_t x, y; + for(y = area->y1; y <= area->y2; y++) { + for(x = area->x1; x <= area->x2; x++) { + put_px(x, y, *color_p); + color_p++; + } + } + + /* IMPORTANT!!! + * Inform the graphics library that you are ready with the flushing*/ + lv_disp_flush_ready(disp_drv); +} + +void my_gpu_fill_cb(lv_disp_drv_t * disp_drv, lv_color_t * dest_buf, const lv_area_t * dest_area, const lv_area_t * fill_area, lv_color_t color); +{ + /*It's an example code which should be done by your GPU*/ + uint32_t x, y; + dest_buf += dest_width * fill_area->y1; /*Go to the first line*/ + + for(y = fill_area->y1; y < fill_area->y2; y++) { + for(x = fill_area->x1; x < fill_area->x2; x++) { + dest_buf[x] = color; + } + dest_buf+=dest_width; /*Go to the next line*/ + } +} + + +void my_rounder_cb(lv_disp_drv_t * disp_drv, lv_area_t * area) +{ + /* Update the areas as needed. + * For example it makes the area to start only on 8th rows and have Nx8 pixel height.*/ + area->y1 = area->y1 & 0x07; + area->y2 = (area->y2 & 0x07) + 8; +} + +void my_set_px_cb(lv_disp_drv_t * disp_drv, uint8_t * buf, lv_coord_t buf_w, lv_coord_t x, lv_coord_t y, lv_color_t color, lv_opa_t opa) +{ + /* Write to the buffer as required for the display. + * For example it writes only 1-bit for monochrome displays mapped vertically.*/ + buf += buf_w * (y >> 3) + x; + if(lv_color_brightness(color) > 128) (*buf) |= (1 << (y % 8)); + else (*buf) &= ~(1 << (y % 8)); +} + +void my_monitor_cb(lv_disp_drv_t * disp_drv, uint32_t time, uint32_t px) +{ + printf("%d px refreshed in %d ms\n", time, ms); +} + +void my_clean_dcache_cb(lv_disp_drv_t * disp_drv, uint32) +{ + /* Example for Cortex-M (CMSIS) */ + SCB_CleanInvalidateDCache(); +} +``` + +## Other options + +### Rotation + +LVGL supports rotation of the display in 90 degree increments. You can select whether you'd like software rotation or hardware rotation. + +If you select software rotation (`sw_rotate` flag set to 1), LVGL will perform the rotation for you. Your driver can and should assume that the screen width and height have not changed. Simply flush pixels to the display as normal. Software rotation requires no additional logic in your `flush_cb` callback. + +There is a noticeable amount of overhead to performing rotation in software. Hardware rotation is available to avoid unwanted slowdowns. In this mode, LVGL draws into the buffer as if your screen width and height were swapped. You are responsible for rotating the provided pixels yourself. + +The default rotation of your display when it is initialized can be set using the `rotated` flag. The available options are `LV_DISP_ROT_NONE`, `LV_DISP_ROT_90`, `LV_DISP_ROT_180`, or `LV_DISP_ROT_270`. The rotation values are relative to how you would rotate the physical display in the clockwise direction. Thus, `LV_DISP_ROT_90` means you rotate the hardware 90 degrees clockwise, and the display rotates 90 degrees counterclockwise to compensate. + +(Note for users upgrading from 7.10.0 and older: these new rotation enum values match up with the old 0/1 system for rotating 90 degrees, so legacy code should continue to work as expected. Software rotation is also disabled by default for compatibility.) + +Display rotation can also be changed at runtime using the `lv_disp_set_rotation(disp, rot)` API. + +Support for software rotation is a new feature, so there may be some glitches/bugs depending on your configuration. If you encounter a problem please open an issue on [GitHub](https://github.com/lvgl/lvgl/issues). + +### Decoupling the display refresh timer +Normally the dirty (a.k.a invalid) areas are checked and redrawn in every `LV_DISP_DEF_REFR_PERIOD` milliseconds (set in `lv_conf.h`). +However, in some cases you might need more control on when the display refreshing happen, for example to synchronize rendering with VSYNC or the TE signal. + +You can do this in the following way: +```c +/*Delete the original display refresh timer*/ +lv_timer_del(disp->refr_timer); +disp->refr_timer = NULL; + + +/*Call this anywhere you want to refresh the dirty areas*/ +_lv_disp_refr_timer(NULL); +``` + +If you have multiple displays call `lv_disp_set_deafult(disp1);` to select the display to refresh before `_lv_disp_refr_timer(NULL);`. + +Note that `lv_timer_handler()` and `_lv_disp_refr_timer()` can not run at the same time. + +If the performance monitor is enabled, the value of `LV_DISP_DEF_REFR_PERIOD` needs to be set to be consistent with the refresh period of the display to ensure that the statistical results are correct. + +## Further reading + +- [lv_port_disp_template.c](https://github.com/lvgl/lvgl/blob/master/examples/porting/lv_port_disp_template.c) for a template for your own driver. +- [Drawing](/overview/drawing) to learn more about how rendering works in LVGL. +- [Display features](/overview/display) to learn more about higher level display features. + +## API + +```eval_rst + +.. doxygenfile:: lv_hal_disp.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/porting/gpu.md b/lib/lvgl/docs/porting/gpu.md new file mode 100644 index 00000000..d09613ad --- /dev/null +++ b/lib/lvgl/docs/porting/gpu.md @@ -0,0 +1,198 @@ +# Add custom GPU +LVGL has a flexible and extendable draw pipeline. You can hook it to do some rendering with a GPU or even completely replace the built-in software renderer. + +## Draw context +The core structure of drawing is `lv_draw_ctx_t`. +It contains a pointer to a buffer where drawing should happen and a couple of callbacks to draw rectangles, texts, and other primitives. + +### Fields +`lv_draw_ctx_t` has the following fields: +- `void * buf` Pointer to a buffer to draw into +- `lv_area_t * buf_area` The position and size of `buf` (absolute coordinates) +- `const lv_area_t * clip_area` The current clip area with absolute coordinates, always the same or smaller than `buf_area`. All drawings should be clipped to this area. +- `void (*draw_rect)()` Draw a rectangle with shadow, gradient, border, etc. +- `void (*draw_arc)()` Draw an arc +- `void (*draw_img_decoded)()` Draw an (A)RGB image that is already decoded by LVGL. +- `lv_res_t (*draw_img)()` Draw an image before decoding it (it bypasses LVGL's internal image decoders) +- `void (*draw_letter)()` Draw a letter +- `void (*draw_line)()` Draw a line +- `void (*draw_polygon)()` Draw a polygon +- `void (*draw_bg)()` Replace the buffer with a rect without decoration like radius or borders. +- `void (*wait_for_finish)()` Wait until all background operation are finished. (E.g. GPU operations) +- `void * user_data` Custom user data for arbitrary purpose + +(For the sake of simplicity the parameters of the callbacks are not shown here.) + +All `draw_*` callbacks receive a pointer to the current `draw_ctx` as their first parameter. Among the other parameters there is a descriptor that tells what to draw, +e.g. for `draw_rect` it's called [lv_draw_rect_dsc_t](https://github.com/lvgl/lvgl/blob/master/src/draw/lv_draw_rect.h), +for `lv_draw_line` it's called [lv_draw_line_dsc_t](https://github.com/lvgl/lvgl/blob/master/src/draw/lv_draw_line.h), etc. + +To correctly render according to a `draw_dsc` you need to be familiar with the [Boxing model](https://docs.lvgl.io/master/overview/coords.html#boxing-model) of LVGL and the meanings of the fields. The name and meaning of the fields are identical to name and meaning of the [Style properties](https://docs.lvgl.io/master/overview/style-props.html). + +### Initialization +The `lv_disp_drv_t` has 4 fields related to the draw context: +- `lv_draw_ctx_t * draw_ctx` Pointer to the `draw_ctx` of this display +- `void (*draw_ctx_init)(struct _lv_disp_drv_t * disp_drv, lv_draw_ctx_t * draw_ctx)` Callback to initialize a `draw_ctx` +- `void (*draw_ctx_deinit)(struct _lv_disp_drv_t * disp_drv, lv_draw_ctx_t * draw_ctx)` Callback to de-initialize a `draw_ctx` +- `size_t draw_ctx_size` Size of the draw context structure. E.g. `sizeof(lv_draw_sw_ctx_t)` + +When you ignore these fields, LVGL will set default values for callbacks and size in `lv_disp_drv_init()` based on the configuration in `lv_conf.h`. +`lv_disp_drv_register()` will allocate a `draw_ctx` based on `draw_ctx_size` and call `draw_ctx_init()` on it. + +However, you can overwrite the callbacks and the size values before calling `lv_disp_drv_register()`. +It makes it possible to use your own `draw_ctx` with your own callbacks. + + +## Software renderer +LVGL's built in software renderer extends the basic `lv_draw_ctx_t` structure and sets the draw callbacks. It looks like this: +```c +typedef struct { + /** Include the basic draw_ctx type*/ + lv_draw_ctx_t base_draw; + + /** Blend a color or image to an area*/ + void (*blend)(lv_draw_ctx_t * draw_ctx, const lv_draw_sw_blend_dsc_t * dsc); +} lv_draw_sw_ctx_t; +``` + +Set the draw callbacks in `draw_ctx_init()` like: +```c +draw_sw_ctx->base_draw.draw_rect = lv_draw_sw_rect; +draw_sw_ctx->base_draw.draw_letter = lv_draw_sw_letter; +... +``` + +### Blend callback +As you saw above the software renderer adds the `blend` callback field. It's a special callback related to how the software renderer works. +All draw operations end up in the `blend` callback which can either fill an area or copy an image to an area by considering an optional mask. + +The `lv_draw_sw_blend_dsc_t` parameter describes what and how to blend. It has the following fields: +- `const lv_area_t * blend_area` The area with absolute coordinates to draw on `draw_ctx->buf`. If `src_buf` is set, it's the coordinates of the image to blend. +- `const lv_color_t * src_buf` Pointer to an image to blend. If set, `color` is ignored. If not set fill `blend_area` with `color` +- `lv_color_t color` Fill color. Used only if `src_buf == NULL` +- `lv_opa_t * mask_buf` NULL if ignored, or an alpha mask to apply on `blend_area` +- `lv_draw_mask_res_t mask_res` The result of the previous mask operation. (`LV_DRAW_MASK_RES_...`) +- `const lv_area_t * mask_area` The area of `mask_buf` with absolute coordinates +- `lv_opa_t opa` The overall opacity +- `lv_blend_mode_t blend_mode` E.g. `LV_BLEND_MODE_ADDITIVE` + + +## Extend the software renderer + +### New blend callback + +Let's take a practical example: you would like to use your MCUs GPU for color fill operations only. + +As all draw callbacks call `blend` callback to fill an area in the end only the `blend` callback needs to be overwritten. + +First extend `lv_draw_sw_ctx_t`: +```c + +/*We don't add new fields, so just for clarity add new type*/ +typedef lv_draw_sw_ctx_t my_draw_ctx_t; + +void my_draw_ctx_init(lv_disp_drv_t * drv, lv_draw_ctx_t * draw_ctx) +{ + /*Initialize the parent type first */ + lv_draw_sw_init_ctx(drv, draw_ctx); + + /*Change some callbacks*/ + my_draw_ctx_t * my_draw_ctx = (my_draw_ctx_t *)draw_ctx; + + my_draw_ctx->blend = my_draw_blend; + my_draw_ctx->base_draw.wait_for_finish = my_gpu_wait; +} +``` + +After calling `lv_disp_draw_init(&drv)` you can assign the new `draw_ctx_init` callback and set `draw_ctx_size` to overwrite the defaults: +```c +static lv_disp_drv_t drv; +lv_disp_draw_init(&drv); +drv->hor_res = my_hor_res; +drv->ver_res = my_ver_res; +drv->flush_cb = my_flush_cb; + +/*New draw ctx settings*/ +drv->draw_ctx_init = my_draw_ctx_init; +drv->draw_ctx_size = sizeof(my_draw_ctx_t); + +lv_disp_drv_register(&drv); +``` + +This way when LVGL calls `blend` it will call `my_draw_blend` and we can do custom GPU operations. Here is a complete example: +```c +void my_draw_blend(lv_draw_ctx_t * draw_ctx, const lv_draw_sw_blend_dsc_t * dsc) +{ + /*Let's get the blend area which is the intersection of the area to fill and the clip area.*/ + lv_area_t blend_area; + if(!_lv_area_intersect(&blend_area, dsc->blend_area, draw_ctx->clip_area)) return; /*Fully clipped, nothing to do*/ + + /*Fill only non masked, fully opaque, normal blended and not too small areas*/ + if(dsc->src_buf == NULL && dsc->mask == NULL && dsc->opa >= LV_OPA_MAX && + dsc->blend_mode == LV_BLEND_MODE_NORMAL && lv_area_get_size(&blend_area) > 100) { + + /*Got the first pixel on the buffer*/ + lv_coord_t dest_stride = lv_area_get_width(draw_ctx->buf_area); /*Width of the destination buffer*/ + lv_color_t * dest_buf = draw_ctx->buf; + dest_buf += dest_stride * (blend_area.y1 - draw_ctx->buf_area->y1) + (blend_area.x1 - draw_ctx->buf_area->x1); + + /*Make the blend area relative to the buffer*/ + lv_area_move(&blend_area, -draw_ctx->buf_area->x1, -draw_ctx->buf_area->y1); + + /*Call your custom gou fill function to fill blend_area, on dest_buf with dsc->color*/ + my_gpu_fill(dest_buf, dest_stride, &blend_area, dsc->color); + } + /*Fallback: the GPU doesn't support these settings. Call the SW renderer.*/ + else { + lv_draw_sw_blend_basic(draw_ctx, dsc); + } +} +``` + +The implementation of wait callback is much simpler: +```c +void my_gpu_wait(lv_draw_ctx_t * draw_ctx) +{ + while(my_gpu_is_working()); + + /*Call SW renderer's wait callback too*/ + lv_draw_sw_wait_for_finish(draw_ctx); +} +``` + +### New rectangle drawer +If your MCU has a more powerful GPU that can draw e.g. rounded rectangles you can replace the original software drawer too. +A custom `draw_rect` callback might look like this: +```c +void my_draw_rect(lv_draw_ctx_t * draw_ctx, const lv_draw_rect_dsc_t * dsc, const lv_area_t * coords) +{ + if(lv_draw_mask_is_any(coords) == false && dsc->grad == NULL && dsc->bg_img_src == NULL && + dsc->shadow_width == 0 && dsc->blend_mode = LV_BLEND_MODE_NORMAL) + { + /*Draw the background*/ + my_bg_drawer(draw_ctx, coords, dsc->bg_color, dsc->radius); + + /*Draw the border if any*/ + if(dsc->border_width) { + my_border_drawer(draw_ctx, coords, dsc->border_width, dsc->border_color, dsc->border_opa) + } + + /*Draw the outline if any*/ + if(dsc->outline_width) { + my_outline_drawer(draw_ctx, coords, dsc->outline_width, dsc->outline_color, dsc->outline_opa, dsc->outline_pad) + } + } + /*Fallback*/ + else { + lv_draw_sw_rect(draw_ctx, dsc, coords); + } +} +``` + +`my_draw_rect` can fully bypass the use of `blend` callback if needed. + +## Fully custom draw engine + +For example if your MCU/MPU supports a powerful vector graphics engine you might use only that instead of LVGL's SW renderer. +In this case, you need to base the renderer on the basic `lv_draw_ctx_t` (instead of `lv_draw_sw_ctx_t`) and extend/initialize it as you wish. + diff --git a/lib/lvgl/docs/porting/indev.md b/lib/lvgl/docs/porting/indev.md new file mode 100644 index 00000000..0066f56d --- /dev/null +++ b/lib/lvgl/docs/porting/indev.md @@ -0,0 +1,206 @@ +# Input device interface + +## Types of input devices + +To register an input device an `lv_indev_drv_t` variable has to be initialized. **Be sure to register at least one display before you register any input devices.** + +```c +/*Register at least one display before you register any input devices*/ +lv_disp_drv_register(&disp_drv); + +static lv_indev_drv_t indev_drv; +lv_indev_drv_init(&indev_drv); /*Basic initialization*/ +indev_drv.type =... /*See below.*/ +indev_drv.read_cb =... /*See below.*/ +/*Register the driver in LVGL and save the created input device object*/ +lv_indev_t * my_indev = lv_indev_drv_register(&indev_drv); +``` + +The `type` member can be: +- `LV_INDEV_TYPE_POINTER` touchpad or mouse +- `LV_INDEV_TYPE_KEYPAD` keyboard or keypad +- `LV_INDEV_TYPE_ENCODER` encoder with left/right turn and push options +- `LV_INDEV_TYPE_BUTTON` external buttons virtually pressing the screen + +`read_cb` is a function pointer which will be called periodically to report the current state of an input device. + +Visit [Input devices](/overview/indev) to learn more about input devices in general. + +### Touchpad, mouse or any pointer +Input devices that can click points on the screen belong to this category. + +```c +indev_drv.type = LV_INDEV_TYPE_POINTER; +indev_drv.read_cb = my_input_read; + +... + +void my_input_read(lv_indev_drv_t * drv, lv_indev_data_t*data) +{ + if(touchpad_pressed) { + data->point.x = touchpad_x; + data->point.y = touchpad_y; + data->state = LV_INDEV_STATE_PRESSED; + } else { + data->state = LV_INDEV_STATE_RELEASED; + } +} +``` + +To set a mouse cursor use `lv_indev_set_cursor(my_indev, &img_cursor)`. (`my_indev` is the return value of `lv_indev_drv_register`) + +### Keypad or keyboard + +Full keyboards with all the letters or simple keypads with a few navigation buttons belong here. + +To use a keyboard/keypad: +- Register a `read_cb` function with `LV_INDEV_TYPE_KEYPAD` type. +- An object group has to be created: `lv_group_t * g = lv_group_create()` and objects have to be added to it with `lv_group_add_obj(g, obj)` +- The created group has to be assigned to an input device: `lv_indev_set_group(my_indev, g)` (`my_indev` is the return value of `lv_indev_drv_register`) +- Use `LV_KEY_...` to navigate among the objects in the group. See `lv_core/lv_group.h` for the available keys. + +```c +indev_drv.type = LV_INDEV_TYPE_KEYPAD; +indev_drv.read_cb = keyboard_read; + +... + +void keyboard_read(lv_indev_drv_t * drv, lv_indev_data_t*data){ + data->key = last_key(); /*Get the last pressed or released key*/ + + if(key_pressed()) data->state = LV_INDEV_STATE_PRESSED; + else data->state = LV_INDEV_STATE_RELEASED; +} +``` + +### Encoder +With an encoder you can do the following: +1. Press its button +2. Long-press its button +3. Turn left +4. Turn right + +In short, the Encoder input devices work like this: +- By turning the encoder you can focus on the next/previous object. +- When you press the encoder on a simple object (like a button), it will be clicked. +- If you press the encoder on a complex object (like a list, message box, etc.) the object will go to edit mode whereby you can navigate inside the object by turning the encoder. +- To leave edit mode, long press the button. + + +To use an *Encoder* (similarly to the *Keypads*) the objects should be added to groups. + + +```c +indev_drv.type = LV_INDEV_TYPE_ENCODER; +indev_drv.read_cb = encoder_read; + +... + +void encoder_read(lv_indev_drv_t * drv, lv_indev_data_t*data){ + data->enc_diff = enc_get_new_moves(); + + if(enc_pressed()) data->state = LV_INDEV_STATE_PRESSED; + else data->state = LV_INDEV_STATE_RELEASED; +} +``` + +#### Using buttons with Encoder logic +In addition to standard encoder behavior, you can also utilize its logic to navigate(focus) and edit widgets using buttons. +This is especially handy if you have only few buttons available, or you want to use other buttons in addition to encoder wheel. + +You need to have 3 buttons available: +- `LV_KEY_ENTER` will simulate press or pushing of the encoder button +- `LV_KEY_LEFT` will simulate turning encoder left +- `LV_KEY_RIGHT` will simulate turning encoder right +- other keys will be passed to the focused widget + +If you hold the keys it will simulate an encoder advance with period specified in `indev_drv.long_press_rep_time`. + +```c +indev_drv.type = LV_INDEV_TYPE_ENCODER; +indev_drv.read_cb = encoder_with_keys_read; + +... + +void encoder_with_keys_read(lv_indev_drv_t * drv, lv_indev_data_t*data){ + data->key = last_key(); /*Get the last pressed or released key*/ + /* use LV_KEY_ENTER for encoder press */ + if(key_pressed()) data->state = LV_INDEV_STATE_PRESSED; + else { + data->state = LV_INDEV_STATE_RELEASED; + /* Optionally you can also use enc_diff, if you have encoder*/ + data->enc_diff = enc_get_new_moves(); + } +} +``` + +### Button +*Buttons* mean external "hardware" buttons next to the screen which are assigned to specific coordinates of the screen. +If a button is pressed it will simulate the pressing on the assigned coordinate. (Similarly to a touchpad) + +To assign buttons to coordinates use `lv_indev_set_button_points(my_indev, points_array)`. +`points_array` should look like `const lv_point_t points_array[] = { {12,30},{60,90}, ...}` + +``` important:: The points_array can't go out of scope. Either declare it as a global variable or as a static variable inside a function. +``` + +```c +indev_drv.type = LV_INDEV_TYPE_BUTTON; +indev_drv.read_cb = button_read; + +... + +void button_read(lv_indev_drv_t * drv, lv_indev_data_t*data){ + static uint32_t last_btn = 0; /*Store the last pressed button*/ + int btn_pr = my_btn_read(); /*Get the ID (0,1,2...) of the pressed button*/ + if(btn_pr >= 0) { /*Is there a button press? (E.g. -1 indicated no button was pressed)*/ + last_btn = btn_pr; /*Save the ID of the pressed button*/ + data->state = LV_INDEV_STATE_PRESSED; /*Set the pressed state*/ + } else { + data->state = LV_INDEV_STATE_RELEASED; /*Set the released state*/ + } + + data->btn = last_btn; /*Save the last button*/ +} +``` + +## Other features + +### Parameters + +The default value of the following parameters can be changed in `lv_indev_drv_t`: +- `scroll_limit` Number of pixels to slide before actually scrolling the object. +- `scroll_throw` Scroll throw (momentum) slow-down in [%]. Greater value means faster slow-down. +- `long_press_time` Press time to send `LV_EVENT_LONG_PRESSED` (in milliseconds) +- `long_press_rep_time` Interval of sending `LV_EVENT_LONG_PRESSED_REPEAT` (in milliseconds) +- `read_timer` pointer to the `lv_timer` which reads the input device. Its parameters can be changed by `lv_timer_...()` functions. `LV_INDEV_DEF_READ_PERIOD` in `lv_conf.h` sets the default read period. + +### Feedback + +Besides `read_cb` a `feedback_cb` callback can be also specified in `lv_indev_drv_t`. +`feedback_cb` is called when any type of event is sent by the input devices (independently of its type). This allows generating feedback for the user, e.g. to play a sound on `LV_EVENT_CLICKED`. + + +### Associating with a display +Every input device is associated with a display. By default, a new input device is added to the last display created or explicitly selected (using `lv_disp_set_default()`). +The associated display is stored and can be changed in `disp` field of the driver. + +### Buffered reading +By default, LVGL calls `read_cb` periodically. Because of this intermittent polling there is a chance that some user gestures are missed. + +To solve this you can write an event driven driver for your input device that buffers measured data. In `read_cb` you can report the buffered data instead of directly reading the input device. +Setting the `data->continue_reading` flag will tell LVGL there is more data to read and it should call `read_cb` again. + +## Further reading + +- [lv_port_indev_template.c](https://github.com/lvgl/lvgl/blob/master/examples/porting/lv_port_indev_template.c) for a template for your own driver. +- [INdev features](/overview/display) to learn more about higher level input device features. + +## API + +```eval_rst + +.. doxygenfile:: lv_hal_indev.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/porting/index.md b/lib/lvgl/docs/porting/index.md new file mode 100644 index 00000000..2bf1dce9 --- /dev/null +++ b/lib/lvgl/docs/porting/index.md @@ -0,0 +1,20 @@ + +# Porting + +```eval_rst + +.. toctree:: + :maxdepth: 2 + + project + display + indev + tick + timer-handler + sleep + os + log + gpu + +``` + diff --git a/lib/lvgl/docs/porting/log.md b/lib/lvgl/docs/porting/log.md new file mode 100644 index 00000000..9264ebbb --- /dev/null +++ b/lib/lvgl/docs/porting/log.md @@ -0,0 +1,49 @@ +# Logging + +LVGL has a built-in *Log* module to inform the user about what is happening in the library. + +## Log level +To enable logging, set `LV_USE_LOG 1` in `lv_conf.h` and set `LV_LOG_LEVEL` to one of the following values: +- `LV_LOG_LEVEL_TRACE` A lot of logs to give detailed information +- `LV_LOG_LEVEL_INFO` Log important events +- `LV_LOG_LEVEL_WARN` Log if something unwanted happened but didn't cause a problem +- `LV_LOG_LEVEL_ERROR` Only critical issues, where the system may fail +- `LV_LOG_LEVEL_USER` Only user messages +- `LV_LOG_LEVEL_NONE` Do not log anything + +The events which have a higher level than the set log level will be logged too. E.g. if you `LV_LOG_LEVEL_WARN`, errors will be also logged. + +## Printing logs + +### Logging with printf +If your system supports `printf`, you just need to enable `LV_LOG_PRINTF` in `lv_conf.h` to send the logs with `printf`. + + +### Custom log function +If you can't use `printf` or want to use a custom function to log, you can register a "logger" callback with `lv_log_register_print_cb()`. + +For example: + +```c +void my_log_cb(const char * buf) +{ + serial_send(buf, strlen(buf)); +} + +... + + +lv_log_register_print_cb(my_log_cb); + +``` + +## Add logs + +You can also use the log module via the `LV_LOG_TRACE/INFO/WARN/ERROR/USER(text)` or `LV_LOG(text)` functions. Here: + +- `LV_LOG_TRACE/INFO/WARN/ERROR/USER(text)` append following information to your `text` + - Log Level + - \_\_FILE\_\_ + - \_\_LINE\_\_ + - \_\_func\_\_ +- `LV_LOG(text)` is similar to `LV_LOG_USER` but has no extra information attached. diff --git a/lib/lvgl/docs/porting/os.md b/lib/lvgl/docs/porting/os.md new file mode 100644 index 00000000..2dc41661 --- /dev/null +++ b/lib/lvgl/docs/porting/os.md @@ -0,0 +1,50 @@ +# Operating system and interrupts + +LVGL is **not thread-safe** by default. + +However, in the following conditions it's valid to call LVGL related functions: +- In *events*. Learn more in [Events](/overview/event). +- In *lv_timer*. Learn more in [Timers](/overview/timer). + + +## Tasks and threads +If you need to use real tasks or threads, you need a mutex which should be invoked before the call of `lv_timer_handler` and released after it. +Also, you have to use the same mutex in other tasks and threads around every LVGL (`lv_...`) related function call and code. +This way you can use LVGL in a real multitasking environment. Just make use of a mutex to avoid the concurrent calling of LVGL functions. + +Here is some pseudocode to illustrate the concept: + +```c +static mutex_t lvgl_mutex; + +void lvgl_thread(void) +{ + while(1) { + mutex_lock(&lvgl_mutex); + lv_task_handler(); + mutex_unlock(&lvgl_mutex); + thread_sleep(10); /* sleep for 10 ms */ + } +} + +void other_thread(void) +{ + /* You must always hold the mutex while using LVGL APIs */ + mutex_lock(&lvgl_mutex); + lv_obj_t *img = lv_img_create(lv_scr_act()); + mutex_unlock(&lvgl_mutex); + + while(1) { + mutex_lock(&lvgl_mutex); + /* change to the next image */ + lv_img_set_src(img, next_image); + mutex_unlock(&lvgl_mutex); + thread_sleep(2000); + } +} +``` + +## Interrupts +Try to avoid calling LVGL functions from interrupt handlers (except `lv_tick_inc()` and `lv_disp_flush_ready()`). But if you need to do this you have to disable the interrupt which uses LVGL functions while `lv_timer_handler` is running. + +It's a better approach to simply set a flag or some value in the interrupt, and periodically check it in an LVGL timer (which is run by `lv_timer_handler`). diff --git a/lib/lvgl/docs/porting/project.md b/lib/lvgl/docs/porting/project.md new file mode 100644 index 00000000..6d025b90 --- /dev/null +++ b/lib/lvgl/docs/porting/project.md @@ -0,0 +1,66 @@ + +# Set up a project + +## Get the library + +LVGL is available on GitHub: [https://github.com/lvgl/lvgl](https://github.com/lvgl/lvgl). + +You can clone it or [Download](https://github.com/lvgl/lvgl/archive/refs/heads/master.zip) the latest version of the library from GitHub. + +## Add lvgl to your project + +The graphics library itself is the `lvgl` directory. It contains a couple of folders but to use `lvgl` you only need `.c` and `.h` files from the `src` folder. + +### Automatically add files +If your IDE automatically adds the files from the folders copied to the project folder (as Eclipse or VSCode does), you can simply copy the `lvgl` folder as it is into your project. + +### Make and CMake +LVGL also supports `make` and `CMake` build systems out of the box. To add LVGL to your Makefile based build system add these lines to your main Makefile: +```make +LVGL_DIR_NAME ?= lvgl #The name of the lvgl folder (change this if you have renamed it) +LVGL_DIR ?= ${shell pwd} #The path where the lvgl folder is +include $(LVGL_DIR)/$(LVGL_DIR_NAME)/lvgl.mk +``` + +For integration with CMake take a look this section of the [Documentation](/get-started/platforms/cmake). + +### Other platforms and tools +The [Get started](/get-started/index.html) section contains many platform specific descriptions e.g. for ESP32, Arduino, NXP, RT-Thread, NuttX, etc. + +### Demos and Examples + +The `lvgl` folder also contains an `examples` and a `demos` folder. If you needed to add the source files manually to your project, you can do the same with the source files of these two folders too. `make` and `CMake` handles the examples and demos, so no extra action required in these cases. + +## Configuration file + +There is a configuration header file for LVGL called **lv_conf.h**. You modify this header to set the library's basic behavior, disable unused modules and features, adjust the size of memory buffers in compile-time, etc. + +To get `lv_conf.h` **copy lvgl/lv_conf_template.h** next to the `lvgl` directory and rename it to *lv_conf.h*. Open the file and change the `#if 0` at the beginning to `#if 1` to enable its content. So the layout of the files should look like this: +``` +|-lvgl +|-lv_conf.h +|-other files and folders +``` + +Comments in the config file explain the meaning of the options. Be sure to set at least `LV_COLOR_DEPTH` according to your display's color depth. Note that, the examples and demos explicitly need to be enabled in `lv_conf.h`. + +Alternatively, `lv_conf.h` can be copied to another place but then you should add the `LV_CONF_INCLUDE_SIMPLE` define to your compiler options (e.g. `-DLV_CONF_INCLUDE_SIMPLE` for GCC compiler) and set the include path manually (e.g. `-I../include/gui`). +In this case LVGL will attempt to include `lv_conf.h` simply with `#include "lv_conf.h"`. + +You can even use a different name for `lv_conf.h`. The custom path can be set via the `LV_CONF_PATH` define. +For example `-DLV_CONF_PATH="/home/joe/my_project/my_custom_conf.h"` + +If `LV_CONF_SKIP` is defined, LVGL will not try to include `lv_conf.h`. Instead you can pass the config defines using build options. For example `"-DLV_COLOR_DEPTH=32 -DLV_USE_BTN=1"`. The unset options will get a default value which is the same as the ones in `lv_conf_template.h`. + +LVGL also can be used via `Kconfig` and `menuconfig`. You can use `lv_conf.h` together with Kconfig, but keep in mind that the value from `lv_conf.h` or build settings (`-D...`) overwrite the values set in Kconfig. To ignore the configs from `lv_conf.h` simply remove its content, or define `LV_CONF_SKIP`. + + +## Initialization + +To use the graphics library you have to initialize it and setup required components. The order of the initialization is: + +1. Call `lv_init()`. +2. Initialize your drivers. +3. Register the display and input devices drivers in LVGL. Learn more about [Display](/porting/display) and [Input device](/porting/indev) registration. +4. Call `lv_tick_inc(x)` every `x` milliseconds in an interrupt to report the elapsed time to LVGL. [Learn more](/porting/tick). +5. Call `lv_timer_handler()` every few milliseconds to handle LVGL related tasks. [Learn more](/porting/timer-handler). diff --git a/lib/lvgl/docs/porting/sleep.md b/lib/lvgl/docs/porting/sleep.md new file mode 100644 index 00000000..b0a877c7 --- /dev/null +++ b/lib/lvgl/docs/porting/sleep.md @@ -0,0 +1,27 @@ +# Sleep management + +The MCU can go to sleep when no user input happens. In this case, the main `while(1)` should look like this: + +```c +while(1) { + /*Normal operation (no sleep) in < 1 sec inactivity*/ + if(lv_disp_get_inactive_time(NULL) < 1000) { + lv_task_handler(); + } + /*Sleep after 1 sec inactivity*/ + else { + timer_stop(); /*Stop the timer where lv_tick_inc() is called*/ + sleep(); /*Sleep the MCU*/ + } + my_delay_ms(5); +} +``` + +You should also add the following lines to your input device read function to signal a wake-up (press, touch or click etc.) has happened: +```c +lv_tick_inc(LV_DISP_DEF_REFR_PERIOD); /*Force task execution on wake-up*/ +timer_start(); /*Restart the timer where lv_tick_inc() is called*/ +lv_task_handler(); /*Call `lv_task_handler()` manually to process the wake-up event*/ +``` + +In addition to `lv_disp_get_inactive_time()` you can check `lv_anim_count_running()` to see if all animations have finished. diff --git a/lib/lvgl/docs/porting/tick.md b/lib/lvgl/docs/porting/tick.md new file mode 100644 index 00000000..a3e8e94e --- /dev/null +++ b/lib/lvgl/docs/porting/tick.md @@ -0,0 +1,31 @@ +# Tick interface + +LVGL needs a system tick to know elapsed time for animations and other tasks. + +You need to call the `lv_tick_inc(tick_period)` function periodically and provide the call period in milliseconds. For example, `lv_tick_inc(1)` when calling every millisecond. + +`lv_tick_inc` should be called in a higher priority routine than `lv_task_handler()` (e.g. in an interrupt) to precisely know the elapsed milliseconds even if the execution of `lv_task_handler` takes more time. + +With FreeRTOS `lv_tick_inc` can be called in `vApplicationTickHook`. + +On Linux based operating systems (e.g. on Raspberry Pi) `lv_tick_inc` can be called in a thread like below: +```c +void * tick_thread (void *args) +{ + while(1) { + usleep(5*1000); /*Sleep for 5 millisecond*/ + lv_tick_inc(5); /*Tell LVGL that 5 milliseconds were elapsed*/ + } +} +``` + + + +## API + +```eval_rst + +.. doxygenfile:: lv_hal_tick.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/porting/timer-handler.md b/lib/lvgl/docs/porting/timer-handler.md new file mode 100644 index 00000000..2f086b59 --- /dev/null +++ b/lib/lvgl/docs/porting/timer-handler.md @@ -0,0 +1,38 @@ +# Timer Handler + +To handle the tasks of LVGL you need to call `lv_timer_handler()` periodically in one of the following: +- *while(1)* of *main()* function +- timer interrupt periodically (lower priority than `lv_tick_inc()`) +- an OS task periodically + +The timing is not critical but it should be about 5 milliseconds to keep the system responsive. + +Example: +```c +while(1) { + lv_timer_handler(); + my_delay_ms(5); +} +``` + +If you want to use `lv_timer_handler()` in a super-loop, a helper function`lv_timer_handler_run_in_period()` is provided to simplify the porting: + +```c +while(1) { + ... + lv_timer_handler_run_in_period(5); /* run lv_timer_handler() every 5ms */ + ... +} +``` + + In an OS environment, you can use it together with the **delay** or **sleep** provided by OS to release CPU whenever possible: + +```c +while (1) { + lv_timer_handler_run_in_period(5); /* run lv_timer_handler() every 5ms */ + my_delay_ms(5); /* delay 5ms to avoid unnecessary polling */ +} +``` + +To learn more about timers visit the [Timer](/overview/timer) section. + diff --git a/lib/lvgl/docs/requirements.txt b/lib/lvgl/docs/requirements.txt new file mode 100644 index 00000000..0ce26982 --- /dev/null +++ b/lib/lvgl/docs/requirements.txt @@ -0,0 +1,34 @@ +alabaster==0.7.12 +Babel==2.9.1 +breathe==4.30.0 +certifi==2020.12.5 +chardet==4.0.0 +commonmark==0.9.1 +docutils==0.16 +idna==2.10 +imagesize==1.2.0 +importlib-metadata==4.8.1 +Jinja2==2.11.3 +Markdown==3.3.4 +MarkupSafe==1.1.1 +packaging==20.9 +Pygments==2.9.0 +pyparsing==2.4.7 +pytz==2021.1 +recommonmark==0.6.0 +requests==2.25.1 +six==1.16.0 +snowballstemmer==2.1.0 +Sphinx==4.5.0 +sphinx-markdown-tables==0.0.15 +sphinx-rtd-theme==0.5.2 +sphinx-sitemap==2.2.0 +sphinxcontrib-applehelp==1.0.2 +sphinxcontrib-devhelp==1.0.2 +sphinxcontrib-htmlhelp==2.0.0 +sphinxcontrib-jsmath==1.0.1 +sphinxcontrib-qthelp==1.0.3 +sphinxcontrib-serializinghtml==1.1.5 +typing-extensions==3.10.0.0 +urllib3==1.26.5 +zipp==3.4.1 diff --git a/lib/lvgl/docs/widgets/core/arc.md b/lib/lvgl/docs/widgets/core/arc.md new file mode 100644 index 00000000..5b502714 --- /dev/null +++ b/lib/lvgl/docs/widgets/core/arc.md @@ -0,0 +1,116 @@ +# Arc (lv_arc) + +## Overview + +The Arc consists of a background and a foreground arc. The foreground (indicator) can be touch-adjusted. + +## Parts and Styles +- `LV_PART_MAIN` Draws a background using the typical background style properties and an arc using the arc style properties. The arc's size and position will respect the *padding* style properties. +- `LV_PART_INDICATOR` Draws another arc using the *arc* style properties. Its padding values are interpreted relative to the background arc. +- `LV_PART_KNOB` Draws a handle on the end of the indicator using all background properties and padding values. With zero padding the knob size is the same as the indicator's width. +Larger padding makes it larger, smaller padding makes it smaller. + +## Usage + +### Value and range + +A new value can be set using `lv_arc_set_value(arc, new_value)`. +The value is interpreted in a range (minimum and maximum values) which can be modified with `lv_arc_set_range(arc, min, max)`. +The default range is 0..100. + +The indicator arc is drawn on the main part's arc. This if the value is set to maximum the indicator arc will cover the entire "background" arc. +To set the start and end angle of the background arc use the `lv_arc_set_bg_angles(arc, start_angle, end_angle)` functions or `lv_arc_set_bg_start/end_angle(arc, angle)`. + +Zero degrees is at the middle right (3 o'clock) of the object and the degrees are increasing in clockwise direction. +The angles should be in the [0;360] range. + +### Rotation + +An offset to the 0 degree position can be added with `lv_arc_set_rotation(arc, deg)`. + +### Mode + +The arc can be one of the following modes: +- `LV_ARC_MODE_NORMAL` The indicator arc is drawn from the minimum value to the current. +- `LV_ARC_MODE_REVERSE` The indicator arc is drawn counter-clockwise from the maximum value to the current. +- `LV_ARC_MODE_SYMMETRICAL` The indicator arc is drawn from the middle point to the current value. + +The mode can be set by `lv_arc_set_mode(arc, LV_ARC_MODE_...)` and used only if the angle is set by `lv_arc_set_value()` or the arc is adjusted by finger. + +### Change rate +If the arc is pressed the current value will set with a limited speed according to the set *change rate*. +The change rate is defined in degree/second unit and can be set with `lv_arc_set_change_rage(arc, rate)` + + +### Setting the indicator manually +It's also possible to set the angles of the indicator arc directly with `lv_arc_set_angles(arc, start_angle, end_angle)` function or `lv_arc_set_start/end_angle(arc, start_angle)`. +In this case the set "value" and "mode" are ignored. + +In other words, the angle and value settings are independent. You should exclusively use one or the other. Mixing the two might result in unintended behavior. + +To make the arc non-adjustable, remove the style of the knob and make the object non-clickable: +```c +lv_obj_remove_style(arc, NULL, LV_PART_KNOB); +lv_obj_clear_flag(arc, LV_OBJ_FLAG_CLICKABLE); +``` + +### Advanced hit test + +If the `LV_OBJ_FLAG_ADV_HITTEST` flag is enabled the arc can be clicked through in the middle. Clicks are recognized only on the ring of the background arc. `lv_obj_set_ext_click_size()` makes the sensitive area larger inside and outside with the given number of pixels. + + +### Place another object to the knob + +Another object can be positioned according to the current position of the arc in order to follow the arc's current value (angle). +To do this use `lv_arc_align_obj_to_angle(arc, obj_to_align, radius_offset)`. + +Similarly `lv_arc_rotate_obj_to_angle(arc, obj_to_rotate, radius_offset)` can be used to rotate the object to the current value of the arc. + +It's a typical use case to call these functions in the `VALUE_CHANGED` event of the arc. + +## Events +- `LV_EVENT_VALUE_CHANGED` sent when the arc is pressed/dragged to set a new value. +- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` are sent with the following types: + - `LV_ARC_DRAW_PART_BACKGROUND` The background arc. + - `part`: `LV_PART_MAIN` + - `p1`: center of the arc + - `radius`: radius of the arc + - `arc_dsc` + - `LV_ARC_DRAW_PART_FOREGROUND` The foreground arc. + - `part`: `LV_PART_INDICATOR` + - `p1`: center of the arc + - `radius`: radius of the arc + - `arc_dsc` + - LV_ARC_DRAW_PART_KNOB The knob + - `part`: `LV_PART_KNOB` + - `draw_area`: the area of the knob + - `rect_dsc`: + +See the events of the [Base object](/widgets/obj) too. + +Learn more about [Events](/overview/event). + +## Keys +- `LV_KEY_RIGHT/UP` Increases the value by one. +- `LV_KEY_LEFT/DOWN` Decreases the value by one. + + +Learn more about [Keys](/overview/indev). + + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/arc/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_arc.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/core/bar.md b/lib/lvgl/docs/widgets/core/bar.md new file mode 100644 index 00000000..a18f7d74 --- /dev/null +++ b/lib/lvgl/docs/widgets/core/bar.md @@ -0,0 +1,62 @@ +# Bar (lv_bar) + +## Overview + +The bar object has a background and an indicator on it. The width of the indicator is set according to the current value of the bar. + +Vertical bars can be created if the width of the object is smaller than its height. + +Not only the end, but also the start value of the bar can be set, which changes the start position of the indicator. + + +## Parts and Styles +- `LV_PART_MAIN` The background of the bar and it uses the typical background style properties. Adding padding makes the indicator smaller or larger. The `anim_time` style property sets the animation time if the values set with `LV_ANIM_ON`. +- `LV_PART_INDICATOR` The indicator itself; also uses all the typical background properties. + +## Usage + +### Value and range +A new value can be set by `lv_bar_set_value(bar, new_value, LV_ANIM_ON/OFF)`. +The value is interpreted in a range (minimum and maximum values) which can be modified with `lv_bar_set_range(bar, min, max)`. +The default range is 0..100. + +The new value in `lv_bar_set_value` can be set with or without an animation depending on the last parameter (`LV_ANIM_ON/OFF`). + +### Modes +The bar can be one of the following modes: +- `LV_BAR_MODE_NORMAL` A normal bar as described above +- `LV_BAR_MODE_SYMMETRICAL` Draw the indicator from the zero value to current value. Requires a negative minimum range and positive maximum range. +- `LV_BAR_MODE_RANGE` Allows setting the start value too by `lv_bar_set_start_value(bar, new_value, LV_ANIM_ON/OFF)`. The start value always has to be smaller than the end value. + +## Events +- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` are sent for the following parts: + - `LV_BAR_DRAW_PART_INDICATOR` The indicator of the bar + - `part`: `LV_PART_INDICATOR` + - `draw_area`: area of the indicator + - `rect_dsc` + +See the events of the [Base object](/widgets/obj) too. + +Learn more about [Events](/overview/event). + +## Keys +No *Keys* are processed by the object type. + +Learn more about [Keys](/overview/indev). + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/bar/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_bar.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/core/btn.md b/lib/lvgl/docs/widgets/core/btn.md new file mode 100644 index 00000000..5a055d99 --- /dev/null +++ b/lib/lvgl/docs/widgets/core/btn.md @@ -0,0 +1,46 @@ +# Button (lv_btn) + +## Overview + +Buttons have no new features compared to the [Base object](/widgets/obj). They are useful for semantic purposes and have slightly different default settings. + +Buttons, by default, differ from Base object in the following ways: +- Not scrollable +- Added to the default group +- Default height and width set to `LV_SIZE_CONTENT` + +## Parts and Styles +- `LV_PART_MAIN` The background of the button. Uses the typical background style properties. + +## Usage + +There are no new features compared to [Base object](/widgets/obj). + +## Events +- `LV_EVENT_VALUE_CHANGED` when the `LV_OBJ_FLAG_CHECKABLE` flag is enabled and the object is clicked. The event happens on transition to/from the checked state. + + +Learn more about [Events](/overview/event). + +## Keys +Note that the state of `LV_KEY_ENTER` is translated to `LV_EVENT_PRESSED/PRESSING/RELEASED` etc. + +See the events of the [Base object](/widgets/obj) too. + +Learn more about [Keys](/overview/indev). + +## Example +```eval_rst + +.. include:: ../../../examples/widgets/btn/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_btn.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/core/btnmatrix.md b/lib/lvgl/docs/widgets/core/btnmatrix.md new file mode 100644 index 00000000..a9ca82e9 --- /dev/null +++ b/lib/lvgl/docs/widgets/core/btnmatrix.md @@ -0,0 +1,95 @@ +# Button matrix (lv_btnmatrix) + +## Overview + +The Button Matrix object is a lightweight way to display multiple buttons in rows and columns. Lightweight because the buttons are not actually created but just virtually drawn on the fly. This way, one button use only eight extra bytes of memory instead of the ~100-150 bytes a normal [Button](/widgets/core/btn) object plus the 100 or so bytes for the [Label](/widgets/core/label) object. + +The Button matrix is added to the default group (if one is set). Besides the Button matrix is an editable object to allow selecting and clicking the buttons with encoder navigation too. + +## Parts and Styles +- `LV_PART_MAIN` The background of the button matrix, uses the typical background style properties. `pad_row` and `pad_column` sets the space between the buttons. +- `LV_PART_ITEMS` The buttons all use the text and typical background style properties except translations and transformations. + +## Usage + +### Button's text +There is a text on each button. To specify them a descriptor string array, called *map*, needs to be used. +The map can be set with `lv_btnmatrix_set_map(btnm, my_map)`. +The declaration of a map should look like `const char * map[] = {"btn1", "btn2", "btn3", NULL}`. +Note that the last element has to be either `NULL` or an empty string (`""`)! + +Use `"\n"` in the map to insert a **line break**. E.g. `{"btn1", "btn2", "\n", "btn3", ""}`. Each line's buttons have their width calculated automatically. +So in the example the first row will have 2 buttons each with 50% width and a second row with 1 button having 100% width. + +### Control buttons +The buttons' width can be set relative to the other button in the same row with `lv_btnmatrix_set_btn_width(btnm, btn_id, width)` +E.g. in a line with two buttons: *btnA, width = 1* and *btnB, width = 2*, *btnA* will have 33 % width and *btnB* will have 66 % width. +It's similar to how the [`flex-grow`](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow) property works in CSS. +The width must be in the \[1..7\] range and the default width is 1. + +In addition to the width, each button can be customized with the following parameters: +- `LV_BTNMATRIX_CTRL_HIDDEN` Makes a button hidden (hidden buttons still take up space in the layout, they are just not visible or clickable) +- `LV_BTNMATRIX_CTRL_NO_REPEAT` Disable repeating when the button is long pressed +- `LV_BTNMATRIX_CTRL_DISABLED` Makes a button disabled Like `LV_STATE_DISABLED` on normal objects +- `LV_BTNMATRIX_CTRL_CHECKABLE` Enable toggling of a button. I.e. `LV_STATE_CHECHED` will be added/removed as the button is clicked +- `LV_BTNMATRIX_CTRL_CHECKED` Make the button checked. It will use the `LV_STATE_CHECHKED` styles. +- `LV_BTNMATRIX_CTRL_CLICK_TRIG` Enabled: send LV_EVENT_VALUE_CHANGE on CLICK, Disabled: send LV_EVENT_VALUE_CHANGE on PRESS +- `LV_BTNMATRIX_CTRL_POPOVER` Show the button label in a popover when pressing this key +- `LV_BTNMATRIX_CTRL_RECOLOR` Enable recoloring of button texts with `#`. E.g. `"It's #ff0000 red#"` +- `LV_BTNMATRIX_CTRL_CUSTOM_1` Custom free to use flag +- `LV_BTNMATRIX_CTRL_CUSTOM_2` Custom free to use flag + +By default, all flags are disabled. + +To set or clear a button's control attribute, use `lv_btnmatrix_set_btn_ctrl(btnm, btn_id, LV_BTNM_CTRL_...)` and +`lv_btnmatrix_clear_btn_ctrl(btnm, btn_id, LV_BTNMATRIX_CTRL_...)` respectively. More `LV_BTNM_CTRL_...` values can be OR-ed + +To set/clear the same control attribute for all buttons of a button matrix, use `lv_btnmatrix_set_btn_ctrl_all(btnm, LV_BTNM_CTRL_...)` and +`lv_btnmatrix_clear_btn_ctrl_all(btnm, LV_BTNMATRIX_CTRL_...)`. + +The set a control map for a button matrix (similarly to the map for the text), use `lv_btnmatrix_set_ctrl_map(btnm, ctrl_map)`. +An element of `ctrl_map` should look like `ctrl_map[0] = width | LV_BTNM_CTRL_NO_REPEAT | LV_BTNM_CTRL_CHECHKABLE`. +The number of elements should be equal to the number of buttons (excluding newlines characters). + +### One check +The "One check" feature can be enabled with `lv_btnmatrix_set_one_checked(btnm, true)` to allow only one button to be checked at a time. + +## Events +- `LV_EVENT_VALUE_CHANGED` Sent when a button is pressed/released or repeated after long press. The event parameter is set to the ID of the pressed/released button. +- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` are sent for the following types: + - `LV_BTNMATRIX_DRAW_PART_BTN` The individual buttons. + - `part`: `LV_PART_ITEMS` + - `id`:index of the button being drawn + - `draw_area`: the area of teh button + - `rect_dsc` + +See the events of the [Base object](/widgets/obj) too. + +`lv_btnmatrix_get_selected_btn(btnm)` returns the index of the most recently released or focused button or `LV_BTNMATRIX_BTN_NONE` if no such button. + +`lv_btnmatrix_get_btn_text(btnm, btn_id)` returns a pointer to the text of `btn_id`th button. + +Learn more about [Events](/overview/event). + +## Keys +- `LV_KEY_RIGHT/UP/LEFT/RIGHT` To navigate among the buttons to select one +- `LV_KEY_ENTER` To press/release the selected button + +Learn more about [Keys](/overview/indev). + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/btnmatrix/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_btnmatrix.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/core/canvas.md b/lib/lvgl/docs/widgets/core/canvas.md new file mode 100644 index 00000000..27f62361 --- /dev/null +++ b/lib/lvgl/docs/widgets/core/canvas.md @@ -0,0 +1,103 @@ +# Canvas (lv_canvas) + + +## Overview + +A Canvas inherits from [Image](/widgets/core/img) where the user can draw anything. +Rectangles, texts, images, lines, arcs can be drawn here using lvgl's drawing engine. +Additionally "effects" can be applied, such as rotation, zoom and blur. + + +## Parts and Styles +`LV_PART_MAIN` Uses the typical rectangle style properties and image style properties. + +## Usage + +### Buffer +The Canvas needs a buffer in which stores the drawn image. +To assign a buffer to a Canvas, use `lv_canvas_set_buffer(canvas, buffer, width, height, LV_IMG_CF_...)`. +Where `buffer` is a static buffer (not just a local variable) to hold the image of the canvas. +For example, +`static lv_color_t buffer[LV_CANVAS_BUF_SIZE_TRUE_COLOR(width, height)]`. +`LV_CANVAS_BUF_SIZE_...` macros help to determine the size of the buffer with different color formats. + +The canvas supports all the built-in color formats like `LV_IMG_CF_TRUE_COLOR` or `LV_IMG_CF_INDEXED_2BIT`. +See the full list in the [Color formats](/overview/image.html#color-formats) section. + +### Indexed colors +For `LV_IMG_CF_INDEXED_1/2/4/8` color formats a palette needs to be +initialized with `lv_canvas_set_palette(canvas, 3, LV_COLOR_RED)`. It sets pixels with *index=3* to red. + +### Drawing +To set a pixel's color on the canvas, use `lv_canvas_set_px_color(canvas, x, y, LV_COLOR_RED)`. +With `LV_IMG_CF_INDEXED_...` the index of the color needs to be passed as color. +E.g. `lv_color_t c; c.full = 3;` + +To set a pixel's opacity with `LV_IMG_CF_TRUE_COLOR_ALPHA` or `LV_IMG_CF_ALPHA_...` format on the canvas, use `lv_canvas_set_px_opa(canvas, x, y, opa)`. + + +`lv_canvas_fill_bg(canvas, LV_COLOR_BLUE, LV_OPA_50)` fills the whole canvas to blue with 50% opacity. Note that if the current color format doesn't support colors (e.g. `LV_IMG_CF_ALPHA_2BIT`) the color will be ignored. +Similarly, if opacity is not supported (e.g. `LV_IMG_CF_TRUE_COLOR`) it will be ignored. + +An array of pixels can be copied to the canvas with `lv_canvas_copy_buf(canvas, buffer_to_copy, x, y, width, height)`. +The color format of the buffer and the canvas need to match. + +To draw something to the canvas use +- `lv_canvas_draw_rect(canvas, x, y, width, heigth, &draw_dsc)` +- `lv_canvas_draw_text(canvas, x, y, max_width, &draw_dsc, txt)` +- `lv_canvas_draw_img(canvas, x, y, &img_src, &draw_dsc)` +- `lv_canvas_draw_line(canvas, point_array, point_cnt, &draw_dsc)` +- `lv_canvas_draw_polygon(canvas, points_array, point_cnt, &draw_dsc)` +- `lv_canvas_draw_arc(canvas, x, y, radius, start_angle, end_angle, &draw_dsc)` + +`draw_dsc` is a `lv_draw_rect/label/img/line/arc_dsc_t` variable which should be first initialized with one of `lv_draw_rect/label/img/line/arc_dsc_init()` and then modified with the desired colors and other values. + +The draw function can draw to any color format. For example, it's possible to draw a text to an `LV_IMG_VF_ALPHA_8BIT` canvas and use the result image as a [draw mask](/overview/drawing) later. + +### Transformations +`lv_canvas_transform()` can be used to rotate and/or scale the image of an image and store the result on the canvas. +The function needs the following parameters: +- `canvas` pointer to a canvas object to store the result of the transformation. +- `img pointer` to an image descriptor to transform. Can be the image descriptor of another canvas too (`lv_canvas_get_img()`). +- `angle` the angle of rotation (0..3600), 0.1 deg resolution +- `zoom` zoom factor (256: no zoom, 512: double size, 128: half size); +- `offset_x` offset X to tell where to put the result data on destination canvas +- `offset_y` offset X to tell where to put the result data on destination canvas +- `pivot_x` pivot X of rotation. Relative to the source canvas. Set to `source width / 2` to rotate around the center +- `pivot_y` pivot Y of rotation. Relative to the source canvas. Set to `source height / 2` to rotate around the center +- `antialias` true: apply anti-aliasing during the transformation. Looks better but slower. + +Note that a canvas can't be rotated on itself. You need a source and destination canvas or image. + +### Blur +A given area of the canvas can be blurred horizontally with `lv_canvas_blur_hor(canvas, &area, r)` or vertically with `lv_canvas_blur_ver(canvas, &area, r)`. +`r` is the radius of the blur (greater value means more intensive burring). `area` is the area where the blur should be applied (interpreted relative to the canvas). + +## Events +No special events are sent by canvas objects. +The same events are sent as for the + +See the events of the [Images](/widgets/core/img) too. + +Learn more about [Events](/overview/event). + +## Keys +No *Keys* are processed by the object type. + +Learn more about [Keys](/overview/indev). + +## Example +```eval_rst + +.. include:: ../../../examples/widgets/canvas/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_canvas.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/core/checkbox.md b/lib/lvgl/docs/widgets/core/checkbox.md new file mode 100644 index 00000000..99a54fcd --- /dev/null +++ b/lib/lvgl/docs/widgets/core/checkbox.md @@ -0,0 +1,72 @@ +# Checkbox (lv_checkbox) + + +## Overview + +The Checkbox object is created from a "tick box" and a label. When the Checkbox is clicked the tick box is toggled. + +## Parts and Styles +- `LV_PART_MAIN` The is the background of the Checkbox and it uses the text and all the typical background style properties. +`pad_column` adjusts the spacing between the tickbox and the label +- `LV_PART_INDICATOR` The "tick box" is a square that uses all the typical background style properties. +By default, its size is equal to the height of the main part's font. Padding properties make the tick box larger in the respective directions. + +The Checkbox is added to the default group (if it is set). + +## Usage + + +### Text +The text can be modified with the `lv_checkbox_set_text(cb, "New text")` function and will be dynamically allocated. + +To set a static text, +use `lv_checkbox_set_static_text(cb, txt)`. This way, only a pointer to `txt` will be stored. The text then shouldn't be deallocated while the checkbox exists. + +### Check, uncheck, disable +You can manually check, un-check, and disable the Checkbox by using the common state add/clear function: +```c +lv_obj_add_state(cb, LV_STATE_CHECKED); /*Make the chekbox checked*/ +lv_obj_clear_state(cb, LV_STATE_CHECKED); /*MAke the checkbox unchecked*/ +lv_obj_add_state(cb, LV_STATE_CHECKED | LV_STATE_DISABLED); /*Make the checkbox checked and disabled*/ +``` + +## Events +- `LV_EVENT_VALUE_CHANGED` Sent when the checkbox is toggled. +- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` are sent for the following types: + - `LV_CHECKBOX_DRAW_PART_BOX` The tickbox of the checkbox + - `part`: `LV_PART_INDICATOR` + - `draw_area`: the area of the tickbox + - `rect_dsc` + +See the events of the [Base object](/widgets/obj) too. + +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_ENTER` Clicks the checkbox and toggles it + +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). + + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/checkbox/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_checkbox.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/core/dropdown.md b/lib/lvgl/docs/widgets/core/dropdown.md new file mode 100644 index 00000000..c14b9331 --- /dev/null +++ b/lib/lvgl/docs/widgets/core/dropdown.md @@ -0,0 +1,105 @@ +# Drop-down list (lv_dropdown) + + +## Overview + +The drop-down list allows the user to select one value from a list. + +The drop-down list is closed by default and displays a single value or a predefined text. +When activated (by click on the drop-down list), a list is created from which the user may select one option. +When the user selects a new value, the list is deleted again. + +The Drop-down list is added to the default group (if it is set). Besides the Drop-down list is an editable object to allow selecting an option with encoder navigation too. + +## Parts and Styles +The Dropdown widget is built from the elements: "button" and "list" (both not related to the button and list widgets) + +### Button +- `LV_PART_MAIN` The background of the button. Uses the typical background properties and text properties for the text on it. +- `LV_PART_INDICATOR` Typically an arrow symbol that can be an image or a text (`LV_SYMBOL`). + +The button goes to `LV_STATE_CHECKED` when it's opened. + +### List +- `LV_PART_MAIN` The list itself. Uses the typical background properties. `max_height` can be used to limit the height of the list. +- `LV_PART_SCROLLBAR` The scrollbar background, border, shadow properties and width (for its own width) and right padding for the spacing on the right. +- `LV_PART_SELECTED` Refers to the currently pressed, checked or pressed+checked option. Also uses the typical background properties. + +The list is hidden/shown on open/close. To add styles to it use `lv_dropdown_get_list(dropdown)` to get the list object. For example: + +```c +lv_obj_t * list = lv_dropdown_get_list(dropdown) /*Get the list*/ +lv_obj_add_style(list, &my_style, ...) /*Add the styles to the list*/}` +``` + +Alternatively the theme can be extended with the new styles. + +## Usage + +## Overview + +### Set options +Options are passed to the drop-down list as a string with `lv_dropdown_set_options(dropdown, options)`. Options should be separated by `\n`. For example: `"First\nSecond\nThird"`. This string will be saved in the drop-down list, so it can in a local variable. + +The `lv_dropdown_add_option(dropdown, "New option", pos)` function inserts a new option to `pos` index. + +To save memory the options can set from a static(constant) string too with `lv_dropdown_set_static_options(dropdown, options)`. +In this case the options string should be alive while the drop-down list exists and `lv_dropdown_add_option` can't be used + +You can select an option manually with `lv_dropdown_set_selected(dropdown, id)`, where `id` is the index of an option. + +### Get selected option +The get the *index* of the selected option, use `lv_dropdown_get_selected(dropdown)`. + +`lv_dropdown_get_selected_str(dropdown, buf, buf_size)` copies the *name* of the selected option to `buf`. + +### Direction +The list can be created on any side. The default `LV_DIR_BOTTOM` can be modified by `lv_dropdown_set_dir(dropdown, LV_DIR_LEFT/RIGHT/UP/BOTTOM)` function. + +If the list would be vertically out of the screen, it will be aligned to the edge. + +### Symbol +A symbol (typically an arrow) can be added to the dropdown list with `lv_dropdown_set_symbol(dropdown, LV_SYMBOL_...)` + +If the direction of the drop-down list is `LV_DIR_LEFT` the symbol will be shown on the left, otherwise on the right. + +### Show selected +The main part can either show the selected option or a static text. If a static is set with `lv_dropdown_set_text(dropdown, "Some text")` it will be shown regardless to th selected option. +If the text is `NULL` the selected option is displayed on the button. + +### Manually open/close +To manually open or close the drop-down list the `lv_dropdown_open/close(dropdown)` function can be used. + +## Events +Apart from the [Generic events](../overview/event.html#generic-events), the following [Special events](../overview/event.html#special-events) are sent by the drop-down list: +- `LV_EVENT_VALUE_CHANGED` Sent when the new option is selected or the list is opened/closed. +- `LV_EVENT_CANCEL` Sent when the list is closed +- `LV_EVENT_READY` Sent when the list is opened + +See the events of the [Base object](/widgets/obj) too. + +Learn more about [Events](/overview/event). + +## Keys +- `LV_KEY_RIGHT/DOWN` Select the next option. +- `LV_KEY_LEFT/UP` Select the previous option. +- `LY_KEY_ENTER` Apply the selected option (Sends `LV_EVENT_VALUE_CHANGED` event and closes the drop-down list). + +Learn more about [Keys](/overview/indev). + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/dropdown/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_dropdown.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/core/img.md b/lib/lvgl/docs/widgets/core/img.md new file mode 100644 index 00000000..ee1e6acb --- /dev/null +++ b/lib/lvgl/docs/widgets/core/img.md @@ -0,0 +1,139 @@ +# Image (lv_img) + + +## Overview + +Images are the basic object to display images from flash (as arrays) or from files. Images can display symbols (`LV_SYMBOL_...`) too. + +Using the [Image decoder interface](/overview/image.html#image-decoder) custom image formats can be supported as well. + +## Parts and Styles +- `LV_PART_MAIN` A background rectangle that uses the typical background style properties and the image itself using the image style properties. + +## Usage + +### Image source +To provide maximum flexibility, the source of the image can be: + +- a variable in code (a C array with the pixels). +- a file stored externally (e.g. on an SD card). +- a text with [Symbols](/overview/font). + +To set the source of an image, use `lv_img_set_src(img, src)`. + +To generate a pixel array from a PNG, JPG or BMP image, use the [Online image converter tool](https://lvgl.io/tools/imageconverter) and set the converted image with its pointer: `lv_img_set_src(img1, &converted_img_var);` +To make the variable visible in the C file, you need to declare it with `LV_IMG_DECLARE(converted_img_var)`. + +To use external files, you also need to convert the image files using the online converter tool but now you should select the binary output format. +You also need to use LVGL's file system module and register a driver with some functions for the basic file operation. Go to the [File system](/overview/file-system) to learn more. +To set an image sourced from a file, use `lv_img_set_src(img, "S:folder1/my_img.bin")`. + +You can also set a symbol similarly to [Labels](/widgets/core/label). In this case, the image will be rendered as text according to the *font* specified in the style. It enables to use of light-weight monochrome "letters" instead of real images. You can set symbol like `lv_img_set_src(img1, LV_SYMBOL_OK)`. + +### Label as an image +Images and labels are sometimes used to convey the same thing. For example, to describe what a button does. +Therefore, images and labels are somewhat interchangeable, that is the images can display texts by using `LV_SYMBOL_DUMMY` as the prefix of the text. For example, `lv_img_set_src(img, LV_SYMBOL_DUMMY "Some text")`. + + +### Transparency +The internal (variable) and external images support 2 transparency handling methods: + +- **Chroma-keying** - Pixels with `LV_COLOR_CHROMA_KEY` (*lv_conf.h*) color will be transparent. +- **Alpha byte** - An alpha byte is added to every pixel that contains the pixel's opacity + +### Palette and Alpha index +Besides the *True color* (RGB) color format, the following formats are supported: +- **Indexed** - Image has a palette. +- **Alpha indexed** - Only alpha values are stored. + +These options can be selected in the image converter. To learn more about the color formats, read the [Images](/overview/image) section. + +### Recolor +A color can be mixed with every pixel of an image with a given intensity. +This can be useful to show different states (checked, inactive, pressed, etc.) of an image without storing more versions of the same image. +This feature can be enabled in the style by setting `img_recolor_opa` between `LV_OPA_TRANSP` (no recolor, value: 0) and `LV_OPA_COVER` (full recolor, value: 255). +The default value is `LV_OPA_TRANSP` so this feature is disabled. + +The color to mix is set by `img_recolor`. + +### Auto-size +If the width or height of the image object is set to `LV_SIZE_CONTENT` the object's size will be set according to the size of the image source in the respective direction. + +### Mosaic +If the object's size is greater than the image size in any directions, then the image will be repeated like a mosaic. +This allows creation a large image from only a very narrow source. +For example, you can have a *300 x 5* image with a special gradient and set it as a wallpaper using the mosaic feature. + +### Offset +With `lv_img_set_offset_x(img, x_ofs)` and `lv_img_set_offset_y(img, y_ofs)`, you can add some offset to the displayed image. +Useful if the object size is smaller than the image source size. +Using the offset parameter a [Texture atlas](https://en.wikipedia.org/wiki/Texture_atlas) or a "running image" effect can be created by [Animating](/overview/animation) the x or y offset. + +## Transformations + +Using the `lv_img_set_zoom(img, factor)` the images will be zoomed. Set `factor` to `256` or `LV_IMG_ZOOM_NONE` to disable zooming. +A larger value enlarges the images (e.g. `512` double size), a smaller value shrinks it (e.g. `128` half size). +Fractional scale works as well. E.g. `281` for 10% enlargement. + +To rotate the image use `lv_img_set_angle(img, angle)`. Angle has 0.1 degree precision, so for 45.8° set 458. + +The `transform_zoom` and `transform_angle` style properties are also used to determine the final zoom and angle. + +By default, the pivot point of the rotation is the center of the image. It can be changed with `lv_img_set_pivot(img, pivot_x, pivot_y)`. `0;0` is the top left corner. + +The quality of the transformation can be adjusted with `lv_img_set_antialias(img, true/false)`. With enabled anti-aliasing the transformations are higher quality but slower. + +The transformations require the whole image to be available. Therefore indexed images (`LV_IMG_CF_INDEXED_...`), alpha only images (`LV_IMG_CF_ALPHA_...`) or images from files can not be transformed. +In other words transformations work only on true color images stored as C array, or if a custom [Image decoder](/overview/images#image-edecoder) returns the whole image. + +Note that the real coordinates of image objects won't change during transformation. That is `lv_obj_get_width/height/x/y()` will return the original, non-zoomed coordinates. + +**IMPORTANT** +The transformation of the image is independent of the transformation properties coming from styles. (See [here](/overview/style#opacity-and-transformations)). The main differences are that pure image widget transformation +- doesn't transform the children of the image widget +- image is transformed directly without creating an intermediate layer (buffer) to snapshot the widget + +### Size mode + +By default, when the image is zoomed or rotated the real coordinates of the image object are not changed. +The larger content simply overflows the object's boundaries. +It also means the layouts are not affected the by the transformations. + +If you need the object size to be updated to the transformed size set `lv_img_set_size_mode(img, LV_IMG_SIZE_MODE_REAL)`. (The previous mode is the default and called `LV_IMG_SIZE_MODE_VIRTUAL`). +In this case if the width/height of the object is set to `LV_SIZE_CONTENT` the object's size will be set to the zoomed and rotated size. +If an explicit size is set then the overflowing content will be cropped. + +### Rounded image + +You can use `lv_obj_set_style_radius` to set radius to an image, and enable `lv_obj_set_style_clip_corner` to clip the +content to rounded rectangle or circular shape. Please note this will have some negative performance impact to CPU +based renderers. + +## Events +No special events are sent by image objects. + +See the events of the [Base object](/widgets/obj) too. + +Learn more about [Events](/overview/event). + +## Keys +No *Keys* are processed by the object type. + +Learn more about [Keys](/overview/indev). + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/img/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_img.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/core/index.md b/lib/lvgl/docs/widgets/core/index.md new file mode 100644 index 00000000..be6bd8ad --- /dev/null +++ b/lib/lvgl/docs/widgets/core/index.md @@ -0,0 +1,26 @@ +# Core widgets + +```eval_rst + +.. toctree:: + :maxdepth: 1 + + arc + bar + btn + btnmatrix + canvas + checkbox + dropdown + img + label + line + roller + slider + switch + table + textarea + +``` + + diff --git a/lib/lvgl/docs/widgets/core/label.md b/lib/lvgl/docs/widgets/core/label.md new file mode 100644 index 00000000..cf2b3c8d --- /dev/null +++ b/lib/lvgl/docs/widgets/core/label.md @@ -0,0 +1,92 @@ +# Label (lv_label) + +## Overview +A label is the basic object type that is used to display text. + +## Parts and Styles +- `LV_PART_MAIN` Uses all the typical background properties and the text properties. The padding values can be used to add space between the text and the background. +- `LV_PART_SCROLLBAR` The scrollbar that is shown when the text is larger than the widget's size. +- `LV_PART_SELECTED` Tells the style of the [selected text](#text-selection). Only `text_color` and `bg_color` style properties can be used. + +## Usage + +### Set text +You can set the text on a label at runtime with `lv_label_set_text(label, "New text")`. +This will allocate a buffer dynamically, and the provided string will be copied into that buffer. +Therefore, you don't need to keep the text you pass to `lv_label_set_text` in scope after that function returns. + +With `lv_label_set_text_fmt(label, "Value: %d", 15)` printf formatting can be used to set the text. + +Labels are able to show text from a static character buffer. To do so, use `lv_label_set_text_static(label, "Text")`. +In this case, the text is not stored in the dynamic memory and the given buffer is used directly instead. +This means that the array can't be a local variable which goes out of scope when the function exits. +Constant strings are safe to use with `lv_label_set_text_static` (except when used with `LV_LABEL_LONG_DOT`, as it modifies the buffer in-place), as they are stored in ROM memory, which is always accessible. + +### Newline + +Newline characters are handled automatically by the label object. You can use `\n` to make a line break. For example: `"line1\nline2\n\nline4"` + +### Long modes +By default, the width and height of the label is set to `LV_SIZE_CONTENT`. Therefore, the size of the label is automatically expanded to the text size. +Otherwise, if the width or height are explicitly set (using e.g.`lv_obj_set_width` or a layout), the lines wider than the label's width can be manipulated according to several long mode policies. +Similarly, the policies can be applied if the height of the text is greater than the height of the label. +- `LV_LABEL_LONG_WRAP` Wrap too long lines. If the height is `LV_SIZE_CONTENT` the label's height will be expanded, otherwise the text will be clipped. (Default) +- `LV_LABEL_LONG_DOT` Replaces the last 3 characters from bottom right corner of the label with dots (`.`) +- `LV_LABEL_LONG_SCROLL` If the text is wider than the label scroll it horizontally back and forth. If it's higher, scroll vertically. Only one direction is scrolled and horizontal scrolling has higher precedence. +- `LV_LABEL_LONG_SCROLL_CIRCULAR` If the text is wider than the label scroll it horizontally continuously. If it's higher, scroll vertically. Only one direction is scrolled and horizontal scrolling has higher precedence. +- `LV_LABEL_LONG_CLIP` Simply clip the parts of the text outside the label. + +You can specify the long mode with `lv_label_set_long_mode(label, LV_LABEL_LONG_...)` + +Note that `LV_LABEL_LONG_DOT` manipulates the text buffer in-place in order to add/remove the dots. +When `lv_label_set_text` or `lv_label_set_array_text` are used, a separate buffer is allocated and this implementation detail is unnoticed. +This is not the case with `lv_label_set_text_static`. The buffer you pass to `lv_label_set_text_static` must be writable if you plan to use `LV_LABEL_LONG_DOT`. + +### Text recolor +In the text, you can use commands to recolor parts of the text. For example: `"Write a #ff0000 red# word"`. +This feature can be enabled individually for each label by `lv_label_set_recolor()` function. + +### Text selection +If enabled by `LV_LABEL_TEXT_SELECTION` part of the text can be selected. It's similar to when you use your mouse on a PC to select a text. +The whole mechanism (click and select the text as you drag your finger/mouse) is implemented in [Text area](/widgets/core/textarea) and the Label widget only allows manual text selection with +`lv_label_get_text_selection_start(label, start_char_index)` and `lv_label_get_text_selection_start(label, end_char_index)`. + +### Very long texts +LVGL can efficiently handle very long (e.g. > 40k characters) labels by saving some extra data (~12 bytes) to speed up drawing. To enable this feature, set `LV_LABEL_LONG_TXT_HINT 1` in `lv_conf.h`. + +### Custom scrolling animations +Some aspects of the scrolling animations in long modes `LV_LABEL_LONG_SCROLL` and `LV_LABEL_LONG_SCROLL_CIRCULAR` can be customized by setting the animation property of a style, using `lv_style_set_anim()`. +Currently, only the start and repeat delay of the circular scrolling animation can be customized. If you need to customize another aspect of the scrolling animation, feel free to open an [issue on Github](https://github.com/lvgl/lvgl/issues) to request the feature. + +### Symbols +The labels can display symbols alongside letters (or on their own). Read the [Font](/overview/font) section to learn more about the symbols. + +## Events +No special events are sent by the Label. + +See the events of the [Base object](/widgets/obj) too. + +Learn more about [Events](/overview/event). + +## Keys +No *Keys* are processed by the object type. + +Learn more about [Keys](/overview/indev). + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/label/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_label.h + :project: lvgl + +``` + diff --git a/lib/lvgl/docs/widgets/core/line.md b/lib/lvgl/docs/widgets/core/line.md new file mode 100644 index 00000000..31ae3c11 --- /dev/null +++ b/lib/lvgl/docs/widgets/core/line.md @@ -0,0 +1,48 @@ +# Line (lv_line) + +## Overview +The Line object is capable of drawing straight lines between a set of points. + +## Parts and Styles +- `LV_PART_MAIN` uses all the typical background properties and line style properties. + +## Usage + +### Set points +The points have to be stored in an `lv_point_t` array and passed to the object by the `lv_line_set_points(lines, point_array, point_cnt)` function. + +### Auto-size +By default, the Line's width and height are set to `LV_SIZE_CONTENT`. This means it will automatically set its size to fit all the points. If the size is set explicitly, parts on the line may not be visible. + +### Invert y +By default, the *y == 0* point is in the top of the object. It might be counter-intuitive in some cases so the y coordinates can be inverted with `lv_line_set_y_invert(line, true)`. In this case, *y == 0* will be the bottom of the object. +*y invert* is disabled by default. + +## Events +Only the [Generic events](../overview/event.html#generic-events) are sent by the object type. + +See the events of the [Base object](/widgets/obj) too. + +Learn more about [Events](/overview/event). + +## Keys +No *Keys* are processed by the object type. + +Learn more about [Keys](/overview/indev). + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/line/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_line.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/core/roller.md b/lib/lvgl/docs/widgets/core/roller.md new file mode 100644 index 00000000..491d9d23 --- /dev/null +++ b/lib/lvgl/docs/widgets/core/roller.md @@ -0,0 +1,58 @@ +# Roller (lv_roller) + +## Overview + +Roller allows you to simply select one option from a list by scrolling. + +## Parts and Styles +- `LV_PART_MAIN` The background of the roller uses all the typical background properties and text style properties. `style_text_line_space` adjusts the space between the options. +When the Roller is scrolled and doesn't stop exactly on an option it will scroll to the nearest valid option automatically in `anim_time` milliseconds as specified in the style. +- `LV_PART_SELECTED` The selected option in the middle. Besides the typical background properties it uses the text style properties to change the appearance of the text in the selected area. + +## Usage + +### Set options +Options are passed to the Roller as a string with `lv_roller_set_options(roller, options, LV_ROLLER_MODE_NORMAL/INFINITE)`. The options should be separated by `\n`. For example: `"First\nSecond\nThird"`. + +`LV_ROLLER_MODE_INFINITE` makes the roller circular. + +You can select an option manually with `lv_roller_set_selected(roller, id, LV_ANIM_ON/OFF)`, where *id* is the index of an option. + +### Get selected option +To get the *index* of the currently selected option use `lv_roller_get_selected(roller)`. + +`lv_roller_get_selected_str(roller, buf, buf_size)` will copy the name of the selected option to `buf`. + +### Visible rows +The number of visible rows can be adjusted with `lv_roller_set_visible_row_count(roller, num)`. + +This function calculates the height with the current style. If the font, line space, border width, etc. of the roller changes this function needs to be called again. + +## Events +- `LV_EVENT_VALUE_CHANGED` Sent when a new option is selected. + +See the events of the [Base object](/widgets/obj) too. + +Learn more about [Events](/overview/event). + +## Keys +- `LV_KEY_RIGHT/DOWN` Select the next option +- `LV_KEY_LEFT/UP` Select the previous option +- `LY_KEY_ENTER` Apply the selected option (Send `LV_EVENT_VALUE_CHANGED` event) + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/roller/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_roller.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/core/slider.md b/lib/lvgl/docs/widgets/core/slider.md new file mode 100644 index 00000000..d45a4ea7 --- /dev/null +++ b/lib/lvgl/docs/widgets/core/slider.md @@ -0,0 +1,74 @@ +# Slider (lv_slider) + +## Overview + +The Slider object looks like a [Bar](/widgets/core/bar) supplemented with a knob. The knob can be dragged to set a value. Just like Bar, Slider can be vertical or horizontal. + + +## Parts and Styles +- `LV_PART_MAIN` The background of the slider. Uses all the typical background style properties. `padding` makes the indicator smaller in the respective direction. +- `LV_PART_INDICATOR` The indicator that shows the current state of the slider. Also uses all the typical background style properties. +- `LV_PART_KNOB` A rectangle (or circle) drawn at the current value. Also uses all the typical background properties to describe the knob(s). By default, the knob is square (with an optional corner radius) with side length equal to the smaller side of the slider. The knob can be made larger with the `padding` values. Padding values can be asymmetric too. + +## Usage + +### Value and range +To set an initial value use `lv_slider_set_value(slider, new_value, LV_ANIM_ON/OFF)`. The animation time is set by the styles' `anim_time` property. + +To specify the range (min, max values), `lv_slider_set_range(slider, min , max)` can be used. + +### Modes +The slider can be one of the following modes: +- `LV_SLIDER_MODE_NORMAL` A normal slider as described above +- `LV_SLIDER_SYMMETRICAL` Draw the indicator form the zero value to current value. Requires negative minimum range and positive maximum range. +- `LV_SLIDER_RANGE` Allows setting the start value too by `lv_bar_set_start_value(bar, new_value, LV_ANIM_ON/OFF)`. The start value has to be always smaller than the end value. + +The mode can be changed with `lv_slider_set_mode(slider, LV_SLIDER_MODE_...)` + +### Knob-only mode +Normally, the slider can be adjusted either by dragging the knob, or by clicking on the slider bar. +In the latter case the knob moves to the point clicked and slider value changes accordingly. In some cases it is desirable to set the slider to react on dragging the knob only. This feature is enabled by adding the `LV_OBJ_FLAG_ADV_HITTEST`: `lv_obj_add_flag(slider, LV_OBJ_FLAG_ADV_HITTEST)`. + +The extended click area (set by `lv_obj_set_ext_click_area(slider, value)`) increases to knob's click area. + +## Events +- `LV_EVENT_VALUE_CHANGED` Sent while the slider is being dragged or changed with keys. The event is sent continuously while the slider is being dragged. +- `LV_EVENT_RELEASED` Sent when the slider has just been released. +- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` are sent for the following parts. + - `LV_SLIDER_DRAW_PART_KNOB` The main (right) knob of the slider + - `part`: `LV_PART_KNOB` + - `draw_area`: area of the indicator + - `rect_dsc` + - `id`: 0 + - `LV_SLIDER_DRAW_PART_KNOB` The left knob of the slider + - `part`: `LV_PART_KNOB` + - `draw_area`: area of the indicator + - `rect_dsc` + - `id`: 1 + +See the events of the [Bar](/widgets/core/bar) too. + +Learn more about [Events](/overview/event). + +## Keys +- `LV_KEY_UP/RIGHT` Increment the slider's value by 1 +- `LV_KEY_DOWN/LEFT` Decrement the slider's value by 1 + +Learn more about [Keys](/overview/indev). + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/slider/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_slider.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/core/switch.md b/lib/lvgl/docs/widgets/core/switch.md new file mode 100644 index 00000000..f08dd8b3 --- /dev/null +++ b/lib/lvgl/docs/widgets/core/switch.md @@ -0,0 +1,53 @@ + +# Switch (lv_switch) + +## Overview + +The Switch looks like a little slider and can be used to turn something on and off. + + +## Parts and Styles +- `LV_PART_MAIN` The background of the switch uses all the typical background style properties. `padding` makes the indicator smaller in the respective direction. +- `LV_PART_INDICATOR` The indicator that shows the current state of the switch. Also uses all the typical background style properties. +- `LV_PART_KNOB` A rectangle (or circle) drawn at left or right side of the indicator. Also uses all the typical background properties to describe the knob(s). By default, the knob is square (with an optional corner radius) with side length equal to the smaller side of the slider. The knob can be made larger with the `padding` values. Padding values can be asymmetric too. + +## Usage + +### Change state +The switch uses the standard `LV_STATE_CHECKED` state. + +To get the current state of the switch (with `true` being on), use `lv_obj_has_state(switch, LV_STATE_CHECKED)`. + +Call `lv_obj_add_state(switch, LV_STATE_CHECKED)` to turn it on, or `lv_obj_clear_state(switch, LV_STATE_CHECKED)` to turn it off. + + +## Events +- `LV_EVENT_VALUE_CHANGED` Sent when the switch changes state. + +See the events of the [Base object](/widgets/obj) too. + +Learn more about [Events](/overview/event). + +## Keys +- `LV_KEY_UP/RIGHT` Turns on the slider +- `LV_KEY_DOWN/LEFT` Turns off the slider +- `LV_KEY_ENTER` Toggles the switch + +Learn more about [Keys](/overview/indev). + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/switch/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_switch.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/core/table.md b/lib/lvgl/docs/widgets/core/table.md new file mode 100644 index 00000000..df42c8ef --- /dev/null +++ b/lib/lvgl/docs/widgets/core/table.md @@ -0,0 +1,91 @@ +# Table (lv_table) + +## Overview + +Tables, as usual, are built from rows, columns, and cells containing texts. + +The Table object is very lightweight because only the texts are stored. No real objects are created for cells but they are just drawn on the fly. + +The Table is added to the default group (if it is set). Besides the Table is an editable object to allow selecting a cell with encoder navigation too. + +## Parts and Styles +- `LV_PART_MAIN` The background of the table uses all the typical background style properties. +- `LV_PART_ITEMS` The cells of the table also use all the typical background style properties and the text properties. + + +## Usage + +### Set cell value + +The cells can store only text so numbers need to be converted to text before displaying them in a table. + +`lv_table_set_cell_value(table, row, col, "Content")`. The text is saved by the table so it can be even a local variable. + +Line breaks can be used in the text like `"Value\n60.3"`. + +New rows and columns are automatically added is required + +### Rows and Columns + +To explicitly set number of rows and columns use `lv_table_set_row_cnt(table, row_cnt)` and `lv_table_set_col_cnt(table, col_cnt)` + +### Width and Height + +The width of the columns can be set with `lv_table_set_col_width(table, col_id, width)`. The overall width of the Table object will be set to the sum of columns widths. + +The height is calculated automatically from the cell styles (font, padding etc) and the number of rows. + +### Merge cells + +Cells can be merged horizontally with `lv_table_add_cell_ctrl(table, row, col, LV_TABLE_CELL_CTRL_MERGE_RIGHT)`. To merge more adjacent cells call this function for each cell. + +### Scroll +If the label's width or height is set to `LV_SIZE_CONTENT` that size will be used to show the whole table in the respective direction. +E.g. `lv_obj_set_size(table, LV_SIZE_CONTENT, LV_SIZE_CONTENT)` automatically sets the table size to show all the columns and rows. + +If the width or height is set to a smaller number than the "intrinsic" size then the table becomes scrollable. + +## Events +- `LV_EVENT_VALUE_CHANGED` Sent when a new cell is selected with keys. +- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` are sent for the following types: + - `LV_TABLE_DRAW_PART_CELL` The individual cells of the table + - `part`: `LV_PART_ITEMS` + - `draw_area`: area of the indicator + - `rect_dsc` + - `label_dsc` + - `id`: current row × col count + current column + +See the events of the [Base object](/widgets/obj) too. + +Learn more about [Events](/overview/event). + +## Keys + +The following *Keys* are processed by the Tables: +- `LV_KEY_RIGHT/LEFT/UP/DOWN/` Select a cell. + +Note that, as usual, the state of `LV_KEY_ENTER` is translated to `LV_EVENT_PRESSED/PRESSING/RELEASED` etc. + +`lv_table_get_selected_cell(table, &row, &col)` can be used to get the currently selected cell. Row and column will be set to `LV_TABLE_CELL_NONE` no cell is selected. + +Learn more about [Keys](/overview/indev). + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/table/index.rst + +``` + +### MicroPython +No examples yet. + +## API + +```eval_rst + +.. doxygenfile:: lv_table.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/core/textarea.md b/lib/lvgl/docs/widgets/core/textarea.md new file mode 100644 index 00000000..3beadd5c --- /dev/null +++ b/lib/lvgl/docs/widgets/core/textarea.md @@ -0,0 +1,122 @@ +# Text area (lv_textarea) + +## Overview + +The Text Area is a [Base object](widgets/obj) with a [Label](/widgets/core/label) and a cursor on it. +Texts or characters can be added to it. +Long lines are wrapped and when the text becomes long enough the Text area can be scrolled. + +One line mode and password modes are supported. + +## Parts and Styles +- `LV_PART_MAIN` The background of the text area. Uses all the typical background style properties and the text related style properties including `text_align` to align the text to the left, right or center. +- `LV_PART_SCROLLBAR` The scrollbar that is shown when the text is too long. +- `LV_PART_SELECTED` Determines the style of the [selected text](/widgets/core/label.html#text-selection). Only `text_color` and `bg_color` style properties can be used. `bg_color` should be set directly on the label of the text area. +- `LV_PART_CURSOR` Marks the position where the characters are inserted. The cursor's area is always the bounding box of the current character. +A block cursor can be created by adding a background color and background opacity to `LV_PART_CURSOR`'s style. The create line cursor leave the cursor transparent and set a left border. +The `anim_time` style property sets the cursor's blink time. +- `LV_PART_TEXTAREA_PLACEHOLDER` Unique to Text Area, allows styling the placeholder text. + +## Usage + +### Add text + +You can insert text or characters to the current cursor's position with: + +- `lv_textarea_add_char(textarea, 'c')` +- `lv_textarea_add_text(textarea, "insert this text")` + +To add wide characters like `'á'`, `'ß'` or CJK characters use `lv_textarea_add_text(ta, "á")`. + +`lv_textarea_set_text(ta, "New text")` changes the whole text. + +### Placeholder + +A placeholder text can be specified - which is displayed when the Text area is empty - with `lv_textarea_set_placeholder_text(ta, "Placeholder text")` + +### Delete character + +To delete a character from the left of the current cursor position use `lv_textarea_del_char(textarea)`. +To delete from the right use `lv_textarea_del_char_forward(textarea)` + +### Move the cursor + +The cursor position can be modified directly like `lv_textarea_set_cursor_pos(textarea, 10)`. +The `0` position means "before the first characters", +`LV_TA_CURSOR_LAST` means "after the last character" + +You can step the cursor with +- `lv_textarea_cursor_right(textarea)` +- `lv_textarea_cursor_left(textarea)` +- `lv_textarea_cursor_up(textarea)` +- `lv_textarea_cursor_down(textarea)` + +If `lv_textarea_set_cursor_click_pos(textarea, true)` is applied the cursor will jump to the position where the Text area was clicked. + +### Hide the cursor +The cursor is always visible, however it can be a good idea to style it to be visible only in `LV_STATE_FOCUSED` state. + +### One line mode +The Text area can be configured to be on a single line with `lv_textarea_set_one_line(textarea, true)`. +In this mode the height is set automatically to show only one line, line break characters are ignored, and word wrap is disabled. + +### Password mode +The text area supports password mode which can be enabled with `lv_textarea_set_password_mode(textarea, true)`. + +By default, if the `•` ([Bullet, U+2022](http://www.fileformat.info/info/unicode/char/2022/index.htm)) character exists in the font, the entered characters are converted to it after some time or when a new character is entered. If `•` does not exist in the font, `*` will be used. You can override the default character with `lv_textarea_set_password_bullet(textarea, "x")`. + +In password mode `lv_textarea_get_text(textarea)` returns the actual text entered, not the bullet characters. + +The visibility time can be adjusted with `LV_TEXTAREA_DEF_PWD_SHOW_TIME)` in `lv_conf.h`. + +### Accepted characters +You can set a list of accepted characters with `lv_textarea_set_accepted_chars(textarea, "0123456789.+-")`. +Other characters will be ignored. + +### Max text length +The maximum number of characters can be limited with `lv_textarea_set_max_length(textarea, max_char_num)` + + +### Very long texts +If there is a very long text in the Text area (e.g. > 20k characters), scrolling and drawing might be slow. +However, by enabling `LV_LABEL_LONG_TXT_HINT 1` in `lv_conf.h` the performance can be hugely improved. +This will save some additional information about the label to speed up its drawing. +Using `LV_LABEL_LONG_TXT_HINT` the scrolling and drawing will as fast as with "normal" short texts. + +### Select text +Any part of the text can be selected if enabled with `lv_textarea_set_text_selection(textarea, true)`. +This works much like when you select text on your PC with your mouse. + +## Events +- `LV_EVENT_INSERT` Sent right before a character or text is inserted. +The event parameter is the text about to be inserted. `lv_textarea_set_insert_replace(textarea, "New text")` replaces the text to insert. +The new text cannot be in a local variable which is destroyed when the event callback exists. `""` means do not insert anything. +- `LV_EVENT_VALUE_CHANGED` Sent when the content of the text area has been changed. +- `LV_EVENT_READY` Sent when `LV_KEY_ENTER` is pressed (or sent) to a one line text area. + +See the events of the [Base object](/widgets/obj) too. + +Learn more about [Events](/overview/event). + +## Keys +- `LV_KEY_UP/DOWN/LEFT/RIGHT` Move the cursor +- `Any character` Add the character to the current cursor position + +Learn more about [Keys](/overview/indev). + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/textarea/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_textarea.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/extra/animimg.md b/lib/lvgl/docs/widgets/extra/animimg.md new file mode 100644 index 00000000..4727033c --- /dev/null +++ b/lib/lvgl/docs/widgets/extra/animimg.md @@ -0,0 +1,49 @@ +# Animation Image (lv_animimg) + +## Overview + +The animation image is similar to the normal 'Image' object. The only difference is that instead of one source image, you set an array of multiple source images. + +You can specify a duration and repeat count. + + +## Parts and Styles +- `LV_PART_MAIN` A background rectangle that uses the typical background style properties and the image itself using the image style properties. + + +## Usage + +### Image sources +To set the image in a state, use the `lv_animimg_set_src(imgbtn, dsc[], num)`. + + +## Events +No special events are sent by image objects. + +See the events of the Base object too. + +Learn more about [Events](/overview/event). + + +## Keys +No Keys are processed by the object type. + +Learn more about [Keys](/overview/indev). + + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/animimg/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_animimg.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/extra/calendar.md b/lib/lvgl/docs/widgets/extra/calendar.md new file mode 100644 index 00000000..5dd601d1 --- /dev/null +++ b/lib/lvgl/docs/widgets/extra/calendar.md @@ -0,0 +1,82 @@ +# Calendar (lv_calendar) + +## Overview + +The Calendar object is a classic calendar which can: +- show the days of any month in a 7x7 matrix +- Show the name of the days +- highlight the current day (today) +- highlight any user-defined dates + +The Calendar is added to the default group (if it is set). Calendar is an editable object which allow selecting and clicking the dates with encoder navigation too. + +To make the Calendar flexible, by default it doesn't show the current year or month. Instead, there are optional "headers" that can be attached to the calendar. + +## Parts and Styles +The calendar object uses the [Button matrix](/widgets/core/btnmatrix) object under the hood to arrange the days into a matrix. +- `LV_PART_MAIN` The background of the calendar. Uses all the background related style properties. +- `LV_PART_ITEMS` Refers to the dates and day names. Button matrix control flags are set to differentiate the buttons and a custom drawer event is added modify the properties of the buttons as follows: + - day names have no border, no background and drawn with a gray color + - days of the previous and next month have `LV_BTNMATRIX_CTRL_DISABLED` flag + - today has a thicker border with the theme's primary color + - highlighted days have some opacity with the theme's primary color. + +## Usage + +Some functions use the `lv_calendar_date_t` type which is a structure with `year`, `month` and `day` fields. + +### Current date +To set the current date (today), use the `lv_calendar_set_today_date(calendar, year, month, day)` function. `month` needs to be in 1..12 range and `day` in 1..31 range. + +### Shown date +To set the shown date, use `lv_calendar_set_shown_date(calendar, year, month)`; + +### Highlighted days + +The list of highlighted dates should be stored in a `lv_calendar_date_t` array loaded by `lv_calendar_set_highlighted_dates(calendar, highlighted_dates, date_num)`. +Only the array's pointer will be saved so the array should be a static or global variable. + +### Name of the days +The name of the days can be adjusted with `lv_calendar_set_day_names(calendar, day_names)` where `day_names` looks like `const char * day_names[7] = {"Su", "Mo", ...};` +Only the pointer of the day names is saved so the elements should be static, global or constant variables. + +## Events +- `LV_EVENT_VALUE_CHANGED` Sent if a date is clicked. `lv_calendar_get_pressed_date(calendar, &date)` set `date` to the date currently being pressed. Returns `LV_RES_OK` if there is a valid pressed date, else `LV_RES_INV`. + +Learn more about [Events](/overview/event). + +## Keys +- `LV_KEY_RIGHT/UP/LEFT/RIGHT` To navigate among the buttons to dates +- `LV_KEY_ENTER` To press/release the selected date + +Learn more about [Keys](/overview/indev). + +## Headers + +**From v8.1 the header is added directly into the Calendar widget and the API of the headers has been changed.** + +### Arrow buttons + +`lv_calendar_header_arrow_create(calendar)` creates a header that contains a left and right arrow on the sides and a text with the current year and month between them. + + +### Drop-down +`lv_calendar_header_dropdown_create(calendar)` creates a header that contains 2 drop-drown lists: one for the year and another for the month. + + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/calendar/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_calendar.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/extra/chart.md b/lib/lvgl/docs/widgets/extra/chart.md new file mode 100644 index 00000000..4123fbc7 --- /dev/null +++ b/lib/lvgl/docs/widgets/extra/chart.md @@ -0,0 +1,193 @@ +# Chart (lv_chart) + +## Overview + +Charts are a basic object to visualize data points. Currently *Line* charts (connect points with lines and/or draw points on them) and *Bar* charts are supported. + +Charts can have: +- division lines +- 2 y axis +- axis ticks and texts on ticks +- cursors +- scrolling and zooming + +## Parts and Styles +- `LV_PART_MAIN` The background of the chart. Uses all the typical background and *line* (for the division lines) related style properties. *Padding* makes the series area smaller. For column charts `pad_column` sets the space between the columns of the adjacent indices. +- `LV_PART_SCROLLBAR` The scrollbar used if the chart is zoomed. See the [Base object](/widgets/obj)'s documentation for details. +- `LV_PART_ITEMS` Refers to the line or bar series. + - Line chart: The *line* properties are used by the lines. `width`, `height`, `bg_color` and `radius` is used to set the appearance of points. + - Bar chart: The typical background properties are used to style the bars. `pad_column` sets the space between the columns on the same index. +- `LV_PART_INDICATOR` Refers to the points on line and scatter chart (small circles or squares). +- `LV_PART_CURSOR` *Line* properties are used to style the cursors. `width`, `height`, `bg_color` and `radius` are used to set the appearance of points. +- `LV_PART_TICKS` *Line* and *Text* style properties are used to style the ticks + +## Usage + + +### Chart type +The following data display types exist: +- `LV_CHART_TYPE_NONE` Do not display any data. Can be used to hide the series. +- `LV_CHART_TYPE_LINE` Draw lines between the data points and/or points (rectangles or circles) on the data points. +- `LV_CHART_TYPE_BAR` - Draw bars. +- `LV_CHART_TYPE_SCATTER` - X/Y chart drawing point's and lines between the points. . + +You can specify the display type with `lv_chart_set_type(chart, LV_CHART_TYPE_...)`. + + +### Data series +You can add any number of series to the charts by `lv_chart_add_series(chart, color, axis)`. This allocates an `lv_chart_series_t` structure which contains the chosen `color` and an array for the data points. +`axis` can have the following values: +- `LV_CHART_AXIS_PRIMARY_Y` Left axis +- `LV_CHART_AXIS_SECONDARY_Y` Right axis +- `LV_CHART_AXIS_PRIMARY_X` Bottom axis +- `LV_CHART_AXIS_SECONDARY_X` Top axis + + +`axis` tells which axis's range should be used te scale the values. + +`lv_chart_set_ext_y_array(chart, ser, value_array)` makes the chart use an external array for the given series. +`value_array` should look like this: `lv_coord_t * value_array[num_points]`. The array size needs to be large enough to hold all the points of that series. +The array's pointer will be saved in the chart so it needs to be global, static or dynamically allocated. +Note: you should call `lv_chart_refresh(chart)` after the external data source has been updated to update the chart. + +The value array of a series can be obtained with `lv_chart_get_y_array(chart, ser)`, which can be used with `ext_array` or *normal array*s. + +For `LV_CHART_TYPE_SCATTER` type `lv_chart_set_ext_x_array(chart, ser, value_array)` and `lv_chart_get_x_array(chart, ser)` can be used as well. + +### Modify the data +You have several options to set the data of series: +1. Set the values manually in the array like `ser1->points[3] = 7` and refresh the chart with `lv_chart_refresh(chart)`. +2. Use `lv_chart_set_value_by_id(chart, ser, id, value)` where `id` is the index of the point you wish to update. +3. Use the `lv_chart_set_next_value(chart, ser, value)`. +4. Initialize all points to a given value with: `lv_chart_set_all_value(chart, ser, value)`. + +Use `LV_CHART_POINT_NONE` as value to make the library skip drawing that point, column, or line segment. + +For `LV_CHART_TYPE_SCATTER` type `lv_chart_set_value_by_id2(chart, ser, id, value)` and `lv_chart_set_next_value2(chart, ser, x_valuem y_value)` can be used as well. + + +### Update modes +`lv_chart_set_next_value` can behave in two ways depending on *update mode*: +- `LV_CHART_UPDATE_MODE_SHIFT` Shift old data to the left and add the new one to the right. +- `LV_CHART_UPDATE_MODE_CIRCULAR` - Add the new data in circular fashion, like an ECG diagram. + +The update mode can be changed with `lv_chart_set_update_mode(chart, LV_CHART_UPDATE_MODE_...)`. + +### Number of points +The number of points in the series can be modified by `lv_chart_set_point_count(chart, point_num)`. The default value is 10. +Note: this also affects the number of points processed when an external buffer is assigned to a series, so you need to be sure the external array is large enough. + +#### Handling large number of points +On line charts, if the number of points is greater than the pixels horizontally, the Chart will draw only vertical lines to make the drawing of large amount of data effective. +If there are, let's say, 10 points to a pixel, LVGL searches the smallest and the largest value and draws a vertical lines between them to ensure no peaks are missed. + +### Vertical range +You can specify the minimum and maximum values in y-direction with `lv_chart_set_range(chart, axis, min, max)`. +`axis` can be `LV_CHART_AXIS_PRIMARY` (left axis) or `LV_CHART_AXIS_SECONDARY` (right axis). + +The value of the points will be scaled proportionally. The default range is: 0..100. + +### Division lines +The number of horizontal and vertical division lines can be modified by `lv_chart_set_div_line_count(chart, hdiv_num, vdiv_num)`. +The default settings are 3 horizontal and 5 vertical division lines. +If there is a visible border on a side and no padding on that side, the division line would be drawn on top of the border and therefore it won't be drawn. + +### Override default start point for series +If you want a plot to start from a point other than the default which is `point[0]` of the series, you can set an alternative +index with the function `lv_chart_set_x_start_point(chart, ser, id)` where `id` is the new index position to start plotting from. + +Note that `LV_CHART_UPDATE_MODE_SHIFT` also changes the `start_point`. + +### Tick marks and labels +Ticks and labels can be added to the axis with `lv_chart_set_axis_tick(chart, axis, major_len, minor_len, major_cnt, minor_cnt, label_en, draw_size)`. +- `axis` can be `LV_CHART_AXIS_X/PRIMARY_Y/SECONDARY_Y` +- `major_len` is the length of major ticks +- `minor_len` is the length of minor ticks +- `major_cnt` is the number of major ticks on the axis +- `minor_cnt` in the number of minor ticks between two major ticks +- `label_en` `true`: enable label drawing on major ticks +- `draw_size` extra size required to draw the tick and labels (start with 20 px and increase if the ticks/labels are clipped) + +### Zoom +The chart can be zoomed independently in x and y directions with `lv_chart_set_zoom_x(chart, factor)` and `lv_chart_set_zoom_y(chart, factor)`. +If `factor` is 256 there is no zoom. 512 means double zoom, etc. Fractional values are also possible but < 256 value is not allowed. + + +### Cursor + +A cursor can be added with `lv_chart_cursor_t * c1 = lv_chart_add_cursor(chart, color, dir);`. +The possible values of `dir` `LV_DIR_NONE/RIGHT/UP/LEFT/DOWN/HOR/VER/ALL` or their OR-ed values to tell in which direction(s) should the cursor be drawn. + +`lv_chart_set_cursor_pos(chart, cursor, &point)` sets the position of the cursor. +`pos` is a pointer to an `lv_point_t` variable. E.g. `lv_point_t point = {10, 20};`. If the chart is scrolled the cursor will remain in the same place. + +`lv_chart_get_point_pos_by_id(chart, series, id, &point_out)` gets the coordinate of a given point. It's useful to place the cursor at a given point. + +`lv_chart_set_cursor_point(chart, cursor, series, point_id)` sticks the cursor at a point. If the point's position changes (new value or scrolling) the cursor will move with the point. + +## Events +- `LV_EVENT_VALUE_CHANGED` Sent when a new point is clicked pressed. `lv_chart_get_pressed_point(chart)` returns the zero-based index of the pressed point. +- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` are sent with the following types: + - `LV_CHART_DRAW_PART_DIV_LINE_INIT` Used before/after drawn the div lines to add masks to any extra drawings. The following fields are set: + - `part`: `LV_PART_MAIN` + - `line_dsc` + - `LV_CHART_DRAW_PART_DIV_LINE_HOR`, `LV_CHART_DRAW_PART_DIV_LINE_VER` Used for each horizontal and vertical division lines. + - `part`: `LV_PART_MAIN` + - `id`: index of the line + - `p1`, `p2`: points of the line + - `line_dsc` + - `LV_CHART_DRAW_PART_LINE_AND_POINT` Used on line and scatter charts for lines and points. + - `part`: `LV_PART_ITEMS` + - `id`: index of the point + - `value`: value of `id`th point + - `p1`, `p2`: points of the line + - `draw_area`: area of the point + - `line_dsc` + - `rect_dsc` + - `sub_part_ptr`: pointer to the series + - `LV_CHART_DRAW_PART_BAR` Used on bar charts for the rectangles. + - `part`: `LV_PART_ITEMS` + - `id`: index of the point + - `value`: value of `id`th point + - `draw_area`: area of the point + - `rect_dsc`: + - `sub_part_ptr`: pointer to the series + - `LV_CHART_DRAW_PART_CURSOR` Used on cursor lines and points. + - `part`: `LV_PART_CURSOR` + - `p1`, `p2`: points of the line + - `line_dsc` + - `rect_dsc` + - `draw_area`: area of the points + - `LV_CHART_DRAW_PART_TICK_LABEL` Used on tick lines and labels. + - `part`: `LV_PART_TICKS` + - `id`: axis + - `value`: value of the tick + - `text`: `value` converted to decimal or `NULL` for minor ticks + - `line_dsc`, + - `label_dsc`, + +See the events of the [Base object](/widgets/obj) too. + +Learn more about [Events](/overview/event). + +## Keys +No *Keys* are processed by the object type. + +Learn more about [Keys](/overview/indev). + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/chart/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_chart.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/extra/colorwheel.md b/lib/lvgl/docs/widgets/extra/colorwheel.md new file mode 100644 index 00000000..4c8d7c6f --- /dev/null +++ b/lib/lvgl/docs/widgets/extra/colorwheel.md @@ -0,0 +1,55 @@ +# Color wheel (lv_colorwheel) + +## Overview +As its name implies *Color wheel* allows the user to select a color. The Hue, Saturation and Value of the color can be selected separately. + +Long pressing the object, the color wheel will change to the next parameter of the color (hue, saturation or value). A double click will reset the current parameter. + +## Parts and Styles +- `LV_PART_MAIN` Only `arc_width` is used to set the width of the color wheel +- `LV_PART_KNOB` A rectangle (or circle) drawn on the current value. It uses all the rectangle like style properties and padding to make it larger than the width of the arc. + +## Usage + +### Create a color wheel + +`lv_colorwheel_create(parent, knob_recolor)` creates a new color wheel. With `knob_recolor=true` the knob's background color will be set to the current color. + +### Set color + +The color can be set manually with `lv_colorwheel_set_hue/saturation/value(colorwheel, x)` or all at once with `lv_colorwheel_set_hsv(colorwheel, hsv)` or `lv_colorwheel_set_color(colorwheel, rgb)` + +### Color mode + +The current color mode can be manually selected with `lv_colorwheel_set_mode(colorwheel, LV_COLORWHEEL_MODE_HUE/SATURATION/VALUE)`. + +The color mode can be fixed (so as to not change with long press) using `lv_colorwheel_set_mode_fixed(colorwheel, true)` + +## Events +- `LV_EVENT_VALUE_CHANGED` Sent if a new color is selected. + +Learn more about [Events](/overview/event). + +## Keys +- `LV_KEY_UP`, `LV_KEY_RIGHT` Increment the current parameter's value by 1 +- `LV_KEY_DOWN`, `LV_KEY_LEFT` Decrement the current parameter's value by 1 +- `LV_KEY_ENTER` A long press will show the next mode. Double click to reset the current parameter. + +Learn more about [Keys](/overview/indev). + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/colorwheel/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_colorwheel.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/extra/imgbtn.md b/lib/lvgl/docs/widgets/extra/imgbtn.md new file mode 100644 index 00000000..2df40109 --- /dev/null +++ b/lib/lvgl/docs/widgets/extra/imgbtn.md @@ -0,0 +1,66 @@ +# Image button (lv_imgbtn) + +## 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. + +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 +- `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_IMGBTN_STATE_..., src_left, src_center, src_right)`. + +The image sources work the same as described in the [Image object](/widgets/core/img) except that "Symbols" are not supported by the Image button. +Any of the sources can `NULL`. + +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` + +If you set sources only in `LV_IMGBTN_STATE_RELEASED`, these 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. + + +### States +Instead of the regular `lv_obj_add/clear_state()` functions the `lv_imgbtn_set_state(imgbtn, LV_IMGBTN_STATE_...)` functions should be used to manually set a state. + + +## Events +- `LV_EVENT_VALUE_CHANGED` Sent when the button is toggled. + +Learn more about [Events](/overview/event). + +## Keys +- `LV_KEY_RIGHT/UP` Go to toggled state if `LV_OBJ_FLAG_CHECKABLE` is enabled. +- `LV_KEY_LEFT/DOWN` Go to non-toggled state if `LV_OBJ_FLAG_CHECKABLE` is enabled. +- `LV_KEY_ENTER` Clicks the button + + +Learn more about [Keys](/overview/indev). + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/imgbtn/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_imgbtn.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/extra/index.md b/lib/lvgl/docs/widgets/extra/index.md new file mode 100644 index 00000000..cb5cf298 --- /dev/null +++ b/lib/lvgl/docs/widgets/extra/index.md @@ -0,0 +1,27 @@ +# Extra widgets + +```eval_rst + +.. toctree:: + :maxdepth: 1 + + animimg + calendar + chart + colorwheel + imgbtn + keyboard + led + list + menu + meter + msgbox + span + spinbox + spinner + tabview + tileview + win +``` + + diff --git a/lib/lvgl/docs/widgets/extra/keyboard.md b/lib/lvgl/docs/widgets/extra/keyboard.md new file mode 100644 index 00000000..037c0e9e --- /dev/null +++ b/lib/lvgl/docs/widgets/extra/keyboard.md @@ -0,0 +1,92 @@ + + +# Keyboard (lv_keyboard) + +## Overview + +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 matrices Keyboards consist of 2 part: +- `LV_PART_MAIN` The main part. Uses all the typical background properties +- `LV_PART_ITEMS` The buttons. Also uses all typical background properties as well as the *text* properties. + +## Usage + +### Modes +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_NUMBER` Display numbers, +/- sign, and decimal dot +- `LV_KEYBOARD_MODE_USER_1` through `LV_KEYBOARD_MODE_USER_4` User-defined modes. + +The `TEXT` modes' layout contains buttons to change mode. + +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/core/textarea) to the Keyboard to automatically put the clicked characters there. +To assign the text area, use `lv_keyboard_set_textarea(kb, ta)`. + +### Key Popovers +To enable key popovers on press, like on common Android and iOS keyboards, use `lv_keyboard_set_popovers(kb, true)`. The default control maps are preconfigured to only show the popovers on keys that produce a symbol and not on e.g. space. If you use a custom keymap, set the `LV_BTNMATRIX_CTRL_POPOVER` flag for all keys that you want to show a popover. + +Note that popovers for keys in the top row will draw outside the widget boundaries. To account for this, reserve extra free space on top of the keyboard or ensure that the keyboard is added _after_ any widgets adjacent to its top boundary so that the popovers can draw over those. + +The popovers currently are merely a visual effect and don't allow selecting additional characters such as accents yet. + +### 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/core/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` 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 +- `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`, which handles the button pressing, map changing, the assigned text area, etc. You can remove it and replace it with a custom event handler if you wish. + +```eval_rst +.. note:: + In 8.0 and newer, adding an event handler to the keyboard does not remove the default event handler. + This behavior differs from v7, where adding an event handler would always replace the previous one. +``` + + +Learn more about [Events](/overview/event). + +## Keys +- `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). + + +## Examples + + +```eval_rst + +.. include:: ../../../examples/widgets/keyboard/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_keyboard.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/extra/led.md b/lib/lvgl/docs/widgets/extra/led.md new file mode 100644 index 00000000..586c70c0 --- /dev/null +++ b/lib/lvgl/docs/widgets/extra/led.md @@ -0,0 +1,54 @@ +# LED (lv_led) + +## Overview + +The LEDs are rectangle-like (or circle) object whose brightness can be adjusted. With lower brightness the colors of the LED become darker. + +## 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). + +### Toggle +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 +- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` is sent for the following types: + - `LV_LED_DRAW_PART_RECTANGLE` The main rectangle. `LV_OBJ_DRAW_PART_RECTANGLE` is not sent by the base object. + - `part`: `LV_PART_MAIN` + - `rect_dsc` + - `draw_area`: the area of the rectangle + + +See the events of the [Base object](/widgets/obj) too. + +Learn more about [Events](/overview/event). + +## Keys +No *Keys* are processed by the object type. + +Learn more about [Keys](/overview/indev). + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/led/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_led.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/extra/list.md b/lib/lvgl/docs/widgets/extra/list.md new file mode 100644 index 00000000..0742b2a0 --- /dev/null +++ b/lib/lvgl/docs/widgets/extra/list.md @@ -0,0 +1,51 @@ +# List (lv_list) + +## Overview +The List is basically a rectangle with vertical layout to which Buttons and Texts can be added + +## Parts and Styles + +**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** +See the [Button](/widgets/core/btn)'s and [Label](/widgets/core/label)'s documentation. + +## Usage + +### 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 text starts to scroll horizontally if it's too long. + +### Texts +`lv_list_add_text(list, text)` adds a text. + + +## Events +No special events are sent by the List, but sent by the Button as usual. + +Learn more about [Events](/overview/event). + +## Keys +No *Keys* are processed by the object type. + +Learn more about [Keys](/overview/indev). + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/list/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_list.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/extra/menu.md b/lib/lvgl/docs/widgets/extra/menu.md new file mode 100644 index 00000000..bb8992b4 --- /dev/null +++ b/lib/lvgl/docs/widgets/extra/menu.md @@ -0,0 +1,90 @@ +# Menu (lv_menu) + +## Overview +The menu widget can be used to easily create multi-level menus. It handles the traversal between pages automatically. + +## Parts and Styles +The menu widget is built from the following objects: +- Main container: lv_menu_main_cont + - Main header: lv_menu_main_header_cont + - Back btn: [lv_btn](/widgets/core/btn) + - Back btn icon: [lv_img](/widgets/core/img) + - Main page: lv_menu_page +- Sidebar container: lv_menu_sidebar_cont + - Sidebar header: lv_menu_sidebar_header_cont + - Back btn: [lv_btn](/widgets/core/btn) + - Back btn icon: [lv_img](/widgets/core/img) + - Sidebar page: lv_menu_page + +## Usage + +### Create a menu +`lv_menu_create(parent)` creates a new empty menu. + +### Header mode +The following header modes exist: +- `LV_MENU_HEADER_TOP_FIXED` Header is positioned at the top. +- `LV_MENU_HEADER_TOP_UNFIXED` Header is positioned at the top and can be scrolled out of view. +- `LV_MENU_HEADER_BOTTOM_FIXED` Header is positioned at the bottom. + +You can set header modes with `lv_menu_set_mode_header(menu, LV_MENU_HEADER...)`. + +### Root back button mode +The following root back button modes exist: +- `LV_MENU_ROOT_BACK_BTN_DISABLED` +- `LV_MENU_ROOT_BACK_BTN_ENABLED` + +You can set root back button modes with `lv_menu_set_mode_root_back_btn(menu, LV_MENU_ROOT_BACK_BTN...)`. + +### Create a menu page +`lv_menu_page_create(menu, title)` creates a new empty menu page. +You can add any widgets to the page. + +### Set a menu page in the main area +Once a menu page has been created, you can set it to the main area with `lv_menu_set_page(menu, page)`. NULL to clear main and clear menu history. + +### Set a menu page in the sidebar +Once a menu page has been created, you can set it to the sidebar with `lv_menu_set_sidebar_page(menu, page)`. NULL to clear sidebar. + +### Linking between menu pages +For instance, you have created a btn obj in the main page. When you click the btn obj, you want it to open up a new page, use `lv_menu_set_load_page_event(menu, obj, new page)`. + +### Create a menu container, section, separator +The following objects can be created so that it is easier to style the menu: + +`lv_menu_cont_create(parent page)` creates a new empty container. + +`lv_menu_section_create(parent page)` creates a new empty section. + +`lv_menu_separator_create(parent page)` creates a separator. + +## Events +- `LV_EVENT_VALUE_CHANGED` Sent when a page is shown. + - `lv_menu_get_cur_main_page(menu)` returns a pointer to menu page that is currently displayed in main. + - `lv_menu_get_cur_sidebar_page(menu)` returns a pointer to menu page that is currently displayed in sidebar. +- `LV_EVENT_CLICKED` Sent when a back btn in a header from either main or sidebar is clicked. `LV_OBJ_FLAG_EVENT_BUBBLE` is enabled on the buttons so you can add events to the menu itself. + - `lv_menu_back_btn_is_root(menu, btn)` to check if btn is root back btn + +See the events of the [Base object](/widgets/obj) too. + +Learn more about [Events](/overview/event). + +## Keys +No keys are handled by the menu widget. + +Learn more about [Keys](/overview/indev). + + +## Example + +```eval_rst +.. include:: ../../../examples/widgets/menu/index.rst +``` + +## API + +```eval_rst +.. doxygenfile:: lv_menu.h + :project: lvgl + +```
\ No newline at end of file diff --git a/lib/lvgl/docs/widgets/extra/meter.md b/lib/lvgl/docs/widgets/extra/meter.md new file mode 100644 index 00000000..2d9a0f9d --- /dev/null +++ b/lib/lvgl/docs/widgets/extra/meter.md @@ -0,0 +1,113 @@ +# Meter (lv_meter) + +## Overview +The Meter widget can visualize data in very flexible ways. In can show arcs, needles, ticks lines and labels. + +## Parts and Styles +- `LV_PART_MAIN` The background of the Meter. Uses the typical background properties. +- `LV_PART_TICK` The tick lines a labels using the *line* and *text* style properties. +- `LV_PART_INDICATOR` The needle line or image using the *line* and *img* style properties, as well as the background properties to draw a square (or circle) on the pivot of the needles. Padding makes the square larger. +- `LV_PART_ITEMS` The arcs using the *arc* properties. + +## Usage + +### Add a scale + +First a *Scale* needs to be added to the Meter with `lv_meter_scale_t * scale = lv_meter_add_scale(meter)`. +The Scale has minor and major ticks and labels on the major ticks. Later indicators (needles, arcs, tick modifiers) can be added to the meter + +Any number of scales can be added to Meter. + +The minor tick lines can be configured with: `lv_meter_set_scale_ticks(meter, scale, tick_count, line_width, tick_length, ctick_olor)`. + +To add major tick lines use `lv_meter_set_scale_major_ticks(meter, scale, nth_major, tick_width, tick_length, tick_color, label_gap)`. `nth_major` to specify how many minor ticks to skip to draw a major tick. + +Labels are added automatically on major ticks with `label_gap` distance from the ticks with text proportionally to the values of the tick line. + +`lv_meter_set_scale_range(meter, scale, min, max, angle_range, rotation)` sets the value and angle range of the scale. + +### Add indicators + +Indicators need to be added to a Scale and their value is interpreted in the range of the Scale. + +All the indicator add functions return `lv_meter_indicator_t *`. + +#### Needle line + +`indic = lv_meter_add_needle_line(meter, scale, line_width, line_color, r_mod)` adds a needle line to a Scale. By default, the length of the line is the same as the scale's radius but `r_mod` changes the length. + +`lv_meter_set_indicator_value(meter, indic, value)` sets the value of the indicator. + +#### Needle image + +`indic = lv_meter_add_needle_img(meter, scale, img_src, pivot_x, pivot_y)` sets an image that will be used as a needle. `img_src` should be a needle pointing to the right like this `-O--->`. +`pivot_x` and `pivot_y` sets the pivot point of the rotation relative to the top left corner of the image. + +`lv_meter_set_indicator_value(meter, inidicator, value)` sets the value of the indicator. + +#### Arc +`indic = lv_meter_add_arc(meter, scale, arc_width, arc_color, r_mod)` adds and arc indicator. . By default, the radius of the arc is the same as the scale's radius but `r_mod` changes the radius. + +`lv_meter_set_indicator_start_value(meter, indic, value)` and `lv_meter_set_indicator_end_value(meter, inidicator, value)` sets the value of the indicator. + +#### Scale lines (ticks) +`indic = lv_meter_add_scale_lines(meter, scale, color_start, color_end, local, width_mod)` adds an indicator that modifies the ticks lines. +If `local` is `true` the ticks' color will be faded from `color_start` to `color_end` in the indicator's start and end value range. +If `local` is `false` `color_start` and `color_end` will be mapped to the start and end value of the scale and only a "slice" of that color gradient will be visible in the indicator's start and end value range. +`width_mod` modifies the width of the tick lines. + +`lv_meter_set_indicator_start_value(meter, inidicator, value)` and `lv_meter_set_indicator_end_value(meter, inidicator, value)` sets the value of the indicator. + +## Events +- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` is sent for the following types: + - `LV_METER_DRAW_PART_ARC` The arc indicator + - `part`: `LV_PART_ITEMS` + - `sub_part_ptr`: pointer to the indicator + - `arc_dsc` + - `radius`: radius of the arc + - `p1` center of the arc + - `LV_METER_DRAW_PART_NEEDLE_LINE` The needle lines + - `part`: `LV_PART_ITEMS` + - `p1`, `p2` points of the line + - `line_dsc` + - `sub_part_ptr`: pointer to the indicator + - `LV_METER_DRAW_PART_NEEDLE_IMG` The needle images + - `part`: `LV_PART_ITEMS` + - `p1`, `p2` points of the line + - `img_dsc` + - `sub_part_ptr`: pointer to the indicator + - `LV_METER_DRAW_PART_TICK` The tick lines and labels + - `part`: `LV_PART_TICKS` + - `value`: the value of the line + - `text`: `value` converted to decimal or `NULL` on minor lines + - `label_dsc`: label draw descriptor or `NULL` on minor lines + - `line_dsc`: + - `id`: the index of the line + + +See the events of the [Base object](/widgets/obj) too. + +Learn more about [Events](/overview/event). + +## Keys +No keys are handled by the Meter widget. + +Learn more about [Keys](/overview/indev). + + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/meter/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_meter.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/extra/msgbox.md b/lib/lvgl/docs/widgets/extra/msgbox.md new file mode 100644 index 00000000..a0bdbf38 --- /dev/null +++ b/lib/lvgl/docs/widgets/extra/msgbox.md @@ -0,0 +1,67 @@ +# Message box (lv_msgbox) + +## Overview +The Message boxes act as pop-ups. +They are built from a background container, a title, an optional close button, a text and optional buttons. + +The text will be broken into multiple lines automatically and the height will be set automatically to include the text and the buttons. + +The message box can be modal (blocking clicks on the rest of the screen) or not modal. + +## Parts and Styles +The message box is built from other widgets, so you can check these widgets' documentation for details. +- Background: [lv_obj](/widgets/obj) +- Close button: [lv_btn](/widgets/core/btn) +- Title and text: [lv_label](/widgets/core/label) +- Buttons: [lv_btnmatrix](/widgets/core/btnmatrix) + +## Usage + +### Create a message box + +`lv_msgbox_create(parent, title, txt, btn_txts[], add_close_btn)` creates a message box. + +If `parent` is `NULL` the message box will be modal. `title` and `txt` are strings for the title and the text. +`btn_txts[]` is an array with the buttons' text. E.g. `const char * btn_txts[] = {"Ok", "Cancel", NULL}`. +`add_close_btn` can be `true` or `false` to add/don't add a close button. + +### Get the parts +The building blocks of the message box can be obtained using the following functions: +```c +lv_obj_t * lv_msgbox_get_title(lv_obj_t * mbox); +lv_obj_t * lv_msgbox_get_close_btn(lv_obj_t * mbox); +lv_obj_t * lv_msgbox_get_text(lv_obj_t * mbox); +lv_obj_t * lv_msgbox_get_btns(lv_obj_t * mbox); +``` + +### Close the message box +`lv_msgbox_close(msgbox)` closes (deletes) the message box. + +## Events +- `LV_EVENT_VALUE_CHANGED` is sent by the buttons if one of them is clicked. `LV_OBJ_FLAG_EVENT_BUBBLE` is enabled on the buttons so you can add events to the message box itself. +In the event handler, `lv_event_get_target(e)` will return the button matrix and `lv_event_get_current_target(e)` will return the message box. `lv_msgbox_get_active_btn(msgbox)` and `lv_msgbox_get_active_btn_text(msgbox)` can be used to get the index and text of the clicked button. + +Learn more about [Events](/overview/event). + +## Keys +Keys have effect on the close button and button matrix. You can add them manually to a group if required. + +Learn more about [Keys](/overview/indev). + + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/msgbox/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_msgbox.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/extra/span.md b/lib/lvgl/docs/widgets/extra/span.md new file mode 100644 index 00000000..fb18a607 --- /dev/null +++ b/lib/lvgl/docs/widgets/extra/span.md @@ -0,0 +1,85 @@ +# Span (lv_span) + +## Overview + +A spangroup is the object that is used to display rich text. Different from the label object, `spangroup` can render text styled with different fonts, colors, and sizes into the spangroup object. + +## Parts and Styles +- `LV_PART_MAIN` The spangroup has only one part. + +## Usage + +### Set text and style + +The spangroup object uses span to describe text and text style. so, first we need to create `span` descriptor using `lv_span_t * span = lv_spangroup_new_span(spangroup)`. Then use `lv_span_set_text(span, "text")` to set text. The style of the span is configured as with a normal style object by using its `style` member, eg:`lv_style_set_text_color(&span->style, lv_palette_main(LV_PALETTE_RED))`. + +If spangroup object `mode != LV_SPAN_MODE_FIXED` you must call `lv_spangroup_refr_mode()` after you have modified `span` style(eg:set text, changed the font size, del span). + +### Retrieving a span child +Spangroups store their children differently from normal objects, so normal functions for getting children won't work. + +`lv_spangroup_get_child(spangroup, id)` will return a pointer to the child span at index `id`. In addition, `id` can be negative to index from the end of the spangroup where `-1` is the youngest child, `-2` is second youngest, etc. + +e.g. `lv_span_t* span = lv_spangroup_get_child(spangroup, 0)` will return the first child of the spangroup. `lv_span_t* span = lv_spangroup_get_child(spangroup, -1)` will return the last (or most recent) child. + +### Child Count +Use the function `lv_spangroup_get_child_cnt(spangroup)` to get back the number of spans the group is maintaining. + +e.g. `uint32_t size = lv_spangroup_get_child_cnt(spangroup)` + +### Text align +like label object, the spangroup can be set to one the following modes: +- `LV_TEXT_ALIGN_LEFT` Align text to left. +- `LV_TEXT_ALIGN_CENTER` Align text to center. +- `LV_TEXT_ALIGN_RIGHT` Align text to right. +- `LV_TEXT_ALIGN_AUTO` Align text auto. + +use function `lv_spangroup_set_align(spangroup, LV_TEXT_ALIGN_CENTER)` to set text align. + +### Modes +The spangroup can be set to one the following modes: +- `LV_SPAN_MODE_FIXED` fixes the object size. +- `LV_SPAN_MODE_EXPAND` Expand the object size to the text size but stay on a single line. +- `LV_SPAN_MODE_BREAK` Keep width, break the too long lines and auto expand height. + +Use `lv_spangroup_set_mode(spangroup, LV_SPAN_MODE_BREAK)` to set object mode. + +### Overflow +The spangroup can be set to one the following modes: +- `LV_SPAN_OVERFLOW_CLIP` truncates the text at the limit of the area. +- `LV_SPAN_OVERFLOW_ELLIPSIS` will display an ellipsis(`...`) when text overflows the area. + +Use `lv_spangroup_set_overflow(spangroup, LV_SPAN_OVERFLOW_CLIP)` to set object overflow mode. + +### first line indent +Use `lv_spangroup_set_indent(spangroup, 20)` to set the indent of the first line. all modes support pixel units, in addition to LV_SPAN_MODE_FIXED and LV_SPAN_MODE_BREAK mode supports percentage units too. + +### lines +Use `lv_spangroup_set_lines(spangroup, 10)` to set the maximum number of lines to be displayed in LV_SPAN_MODE_BREAK mode, negative values indicate no limit. + +## Events +No special events are sent by this widget. + +Learn more about [Events](/overview/event). + +## Keys +No *Keys* are processed by the object type. + +Learn more about [Keys](/overview/indev). + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/span/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_span.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/extra/spinbox.md b/lib/lvgl/docs/widgets/extra/spinbox.md new file mode 100644 index 00000000..425b2c35 --- /dev/null +++ b/lib/lvgl/docs/widgets/extra/spinbox.md @@ -0,0 +1,59 @@ +# Spinbox (lv_spinbox) + +## Overview +The Spinbox contains a number as text which can be increased or decreased by *Keys* or API functions. +Under the hood the Spinbox is a modified [Text area](/widgets/core/textarea). + +## Parts and Styles +The parts of the Spinbox are identical to the [Text area](/widgets/core/textarea). + +### Value, range and step +`lv_spinbox_set_value(spinbox, 1234)` sets a new value on the Spinbox. + +`lv_spinbox_increment(spinbox)` and `lv_spinbox_decrement(spinbox)` increments/decrements the value of the Spinbox according to the currently selected digit. + +`lv_spinbox_set_range(spinbox, -1000, 2500)` sets a range. If the value is changed by `lv_spinbox_set_value`, by *Keys*,`lv_spinbox_increment/decrement` this range will be respected. + +`lv_spinbox_set_step(spinbox, 100)` sets which digits to change on increment/decrement. Only multiples of ten can be set, and not for example 3. + +`lv_spinbox_set_cursor_pos(spinbox, 1)` sets the cursor to a specific digit to change on increment/decrement. For example position '0' sets the cursor to the least significant digit. + +If an encoder is used as input device, the selected digit is shifted to the right by default whenever the encoder button is clicked. To change this behaviour to shifting to the left, the `lv_spinbox_set_digit_step_direction(spinbox, LV_DIR_LEFT)` can be used + +### Format + +`lv_spinbox_set_digit_format(spinbox, digit_count, separator_position)` sets the number format. `digit_count` is the number of digits excluding the decimal separator and the sign. +`separator_position` is the number of digits before the decimal point. If 0, no decimal point is displayed. + +### Rollover +`lv_spinbox_set_rollover(spinbox, true/false)` enables/disabled rollover mode. If either the minimum or maximum value is reached with rollover enabled, the value will change to the other limit. If rollover is disabled the value will remain at the minimum or maximum value. + +## Events +- `LV_EVENT_VALUE_CHANGED` Sent when the value has changed. + +See the events of the [Text area](/widgets/core/textarea) too. + +Learn more about [Events](/overview/event). + +## Keys +- `LV_KEY_LEFT/RIGHT` With *Keypad* move the cursor left/right. With *Encoder* decrement/increment the selected digit. +- `LV_KEY_UP/DOWN` With *Keypad* and *Encoder* increment/decrement the value. +- `LV_KEY_ENTER` With *Encoder* got the net digit. Jump to the first after the last. + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/spinbox/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_spinbox.h + :project: lvgl + +``` +## Example diff --git a/lib/lvgl/docs/widgets/extra/spinner.md b/lib/lvgl/docs/widgets/extra/spinner.md new file mode 100644 index 00000000..8c9b37c9 --- /dev/null +++ b/lib/lvgl/docs/widgets/extra/spinner.md @@ -0,0 +1,44 @@ +# Spinner (lv_spinner) + +## Overview +The Spinner object is a spinning arc over a ring. + +## Parts and Styles +The parts are identical to the parts of [lv_arc](/widgets/core/arc). + +## Usage + +### Create a spinner + +To create a spinner use `lv_spinner_create(parent, spin_time, arc_length)`. `spin time` sets the spin time in milliseconds, `arc_length` sets the length of the spinning arc in degrees. + +## Events +No special events are sent to the Spinner. + +See the events of the [Arc](/widgets/core/arc) too. + +Learn more about [Events](/overview/event). + +## Keys +No *Keys* are processed by the object type. + +Learn more about [Keys](/overview/indev). + + + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/spinner/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_spinner.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/extra/tabview.md b/lib/lvgl/docs/widgets/extra/tabview.md new file mode 100644 index 00000000..51466cf3 --- /dev/null +++ b/lib/lvgl/docs/widgets/extra/tabview.md @@ -0,0 +1,72 @@ + +# Tabview (lv_tabview) + +## Overview + +The Tab view object can be used to organize content in tabs. +The Tab view is built from other widgets: +- Main container: [lv_obj](/widgets/obj)) + - Tab buttons: [lv_btnmatrix](/widgets/core/btnmatrix) + - Container for the tabs: [lv_obj](/widgets/obj) + - Content of the tabs: [lv_obj](/widgets/obj) + +The tab buttons can be positioned on the top, bottom, left and right side of the Tab view. + +A new tab can be selected either by clicking on a tab button or by sliding horizontally on the content. + +## Parts and Styles +There are no special parts on the Tab view but the `lv_obj` and `lv_btnnmatrix` widgets are used to create the Tab view. + +## Usage + +### Create a Tab view + +`lv_tabview_create(parent, tab_pos, tab_size);` creates a new empty Tab view. `tab_pos` can be `LV_DIR_TOP/BOTTOM/LEFT/RIGHT` to position the tab buttons to a side. +`tab_size` is the height (in case of `LV_DIR_TOP/BOTTOM`) or width (in case of `LV_DIR_LEFT/RIGHT`) tab buttons. + +### Add tabs + +New tabs can be added with `lv_tabview_add_tab(tabview, "Tab name")`. This will return a pointer to an [lv_obj](/widgets/obj) object where the tab's content can be created. + +### Rename tabs + +A tab can be renamed with `lv_tabview_rename_tab(tabview, tab_id, "New Name")`. + +### Change tab + +To select a new tab you can: +- Click on its tab button +- Slide horizontally +- Use `lv_tabview_set_act(tabview, id, LV_ANIM_ON/OFF)` function + +### Get the parts + +`lv_tabview_get_content(tabview)` returns the container for the tabs, `lv_tabview_get_tab_btns(tabview)` returns the Tab buttons object which is a [Button matrix](/widgets/core/btnmatrix). + +## Events +- `LV_EVENT_VALUE_CHANGED` Sent when a new tab is selected by sliding or clicking the tab button. `lv_tabview_get_tab_act(tabview)` returns the zero based index of the current tab. + +Learn more about [Events](/overview/event). + +## Keys + +Keys have effect only on the tab buttons (Button matrix). Add manually to a group if required. + +Learn more about [Keys](/overview/indev). + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/tabview/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_tabview.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/extra/tileview.md b/lib/lvgl/docs/widgets/extra/tileview.md new file mode 100644 index 00000000..efe3bc6b --- /dev/null +++ b/lib/lvgl/docs/widgets/extra/tileview.md @@ -0,0 +1,54 @@ +# Tile view (lv_tileview) + +## Overview + +The Tile view is a container object whose elements (called *tiles*) can be arranged in grid form. +A user can navigate between the tiles by swiping. +Any direction of swiping can be disabled on the tiles individually to not allow moving from one tile to another. + +If the Tile view is screen sized, the user interface resembles what you may have seen on smartwatches. + +## Parts and Styles +The Tile view is built from an [lv_obj](/widgets/obj) container and [lv_obj](/widgets/obj) tiles. + +The parts and styles work the same as for [lv_obj](/widgets/obj). + +## Usage + +### Add a tile + +`lv_tileview_add_tile(tileview, row_id, col_id, dir)` creates a new tile on the `row_id`th row and `col_id`th column. +`dir` can be `LV_DIR_LEFT/RIGHT/TOP/BOTTOM/HOR/VER/ALL` or OR-ed values to enable moving to the adjacent tiles into the given direction by swiping. + +The returned value is an `lv_obj_t *` on which the content of the tab can be created. + +### Change tile +The Tile view can scroll to a tile with `lv_obj_set_tile(tileview, tile_obj, LV_ANIM_ON/OFF)` or `lv_obj_set_tile_id(tileviewv, col_id, row_id, LV_ANIM_ON/OFF);` + + +## Events +- `LV_EVENT_VALUE_CHANGED` Sent when a new tile loaded by scrolling. `lv_tileview_get_tile_act(tabview)` can be used to get current tile. + +## Keys +*Keys* are not handled by the Tile view. + +Learn more about [Keys](/overview/indev). + +## Example + + +```eval_rst + +.. include:: ../../../examples/widgets/tileview/index.rst + +``` + + +## API + +```eval_rst + +.. doxygenfile:: lv_tileview.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/extra/win.md b/lib/lvgl/docs/widgets/extra/win.md new file mode 100644 index 00000000..1db641e5 --- /dev/null +++ b/lib/lvgl/docs/widgets/extra/win.md @@ -0,0 +1,61 @@ +# Window (lv_win) + +## Overview + +The Window is container-like object built from a header with title and buttons and a content area. + +## Parts and Styles +The Window is built from other widgets so you can check their documentation for details: +- Background: [lv_obj](/widgets/obj) +- Header on the background: [lv_obj](/widgets/obj) +- Title on the header: [lv_label](/widgets/core/label) +- Buttons on the header: [lv_btn](/widgets/core/btn) +- Content area on the background: [lv_obj](/widgets/obj) + + +## Usage + +### Create a Window + +`lv_win_create(parent, header_height)` creates a Window with an empty header. + +### Title and buttons + +Any number of texts (but typically only one) can be added to the header with `lv_win_add_title(win, "The title")`. + +Control buttons can be added to the window's header with `lv_win_add_btn(win, icon, btn_width)`. `icon` can be any image source, and `btn_width` is the width of the button. + +The title and the buttons will be added in the order the functions are called. So adding a button, a text and two other buttons will result in a button on the left, a title, and 2 buttons on the right. +The width of the title is set to take all the remaining space on the header. In other words: it pushes to the right all the buttons that are added after the title. + +## Get the parts +`lv_win_get_header(win)` returns a pointer to the header, `lv_win_get_content(win)` returns a pointer to the content container to which the content of the window can be added. + +## Events +No special events are sent by the windows, however events can be added manually to the return value of `lv_win_add_btn`. + +Learn more about [Events](/overview/event). + +## Keys +No *Keys* are handled by the window. + +Learn more about [Keys](/overview/indev). + + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/win/index.rst + +``` + + +## API + +```eval_rst + +.. doxygenfile:: lv_win.h + :project: lvgl + +``` diff --git a/lib/lvgl/docs/widgets/index.md b/lib/lvgl/docs/widgets/index.md new file mode 100644 index 00000000..0d716c27 --- /dev/null +++ b/lib/lvgl/docs/widgets/index.md @@ -0,0 +1,13 @@ +# Widgets + +```eval_rst + +.. toctree:: + :maxdepth: 1 + + obj + core/index + extra/index +``` + + diff --git a/lib/lvgl/docs/widgets/obj.md b/lib/lvgl/docs/widgets/obj.md new file mode 100644 index 00000000..c6354682 --- /dev/null +++ b/lib/lvgl/docs/widgets/obj.md @@ -0,0 +1,198 @@ +# Base object (lv_obj) + +## Overview + +The 'Base Object' implements the basic properties of widgets on a screen, such as: +- coordinates +- parent object +- children +- contains the styles +- attributes like *Clickable*, *Scrollable*, etc. + +In object-oriented thinking, it is the base class from which all other objects in LVGL are inherited. + +The functions and functionalities of the Base object can be used with other widgets too. For example `lv_obj_set_width(slider, 100)` + +The Base object can be directly used as a simple widget: it's nothing more than a rectangle. In HTML terms, think of it as a `<div>`. + +### Coordinates + +Only a small subset of coordinate settings is described here. To see all the features of LVGL (padding, coordinates in styles, layouts, etc) visit the [Coordinates](/overview/coords) page. + +#### Size +The object size can be modified on individual axes with `lv_obj_set_width(obj, new_width)` and `lv_obj_set_height(obj, new_height)`, or both axes can be modified at the same time with `lv_obj_set_size(obj, new_width, new_height)`. + +#### Position +You can set the position relative to the parent with `lv_obj_set_x(obj, new_x)` and `lv_obj_set_y(obj, new_y)`, or both axes at the same time with `lv_obj_set_pos(obj, new_x, new_y)`. + +#### Alignment +You can align the object on its parent with `lv_obj_set_align(obj, LV_ALIGN_...)`. After this every x and y setting will be relative to the set alignment mode. +For example, this will shift the object by 10;20 px from the center of its parent: +```c +lv_obj_set_align(obj, LV_ALIGN_CENTER); +lv_obj_set_pos(obj, 10, 20); + +//Or in one function +lv_obj_align(obj, LV_ALIGN_CENTER, 10, 20); +``` + +To align one object to another use: `lv_obj_align_to(obj_to_align, obj_referece, LV_ALIGN_..., x, y)` + +For example, to align a text below an image: `lv_obj_align_to(text, image, LV_ALIGN_OUT_BOTTOM_MID, 0, 10)`. + +The following align types exist: + + + +### Parents and children +You can set a new parent for an object with `lv_obj_set_parent(obj, new_parent)`. To get the current parent, use `lv_obj_get_parent(obj)`. + +To get a specific child of a parent use `lv_obj_get_child(parent, idx)`. Some examples for `idx`: +- `0` get the child created first +- `1` get the child created second +- `-1` get the child created last + +The children can be iterated lke this: +```c +uint32_t i; +for(i = 0; i < lv_obj_get_child_cnt(parent); i++) { + lv_obj_t * child = lv_obj_get_child(parent, i); + /*Do something with child*/ +} +``` + +`lv_obj_get_index(obj)` returns the index of the object in its parent. It is equivalent to the number of younger children in the parent. + +You can bring an object to the foreground or send it to the background with `lv_obj_move_foreground(obj)` and `lv_obj_move_background(obj)`. + +You can change the index of an object in its parent using `lv_obj_move_to_index(obj, index)`. + +You can swap the position of two objects with `lv_obj_swap(obj1, obj2)`. + +### Display and Screens + +At the highest level of the LVGL object hierarchy is the *display* which represents the driver for a display device (physical display or simulator). A display can have one or more screens associated with it. Each screen contains a hierarchy of objects for graphical widgets representing a layout that covers the entire display. + +When you have created a screen like `lv_obj_t * screen = lv_obj_create(NULL)`, you can make it active with `lv_scr_load(screen)`. The `lv_scr_act()` function gives you a pointer to the active screen. + +If you have multiple displays, it's important to know that the screen functions operate on the most recently created display or the one explicitly selected with `lv_disp_set_default`. + +To get an object's screen use the `lv_obj_get_screen(obj)` function. + +### Events + +To set an event callback for an object, use `lv_obj_add_event_cb(obj, event_cb, LV_EVENT_..., user_data)`, + +To manually send an event to an object, use `lv_event_send(obj, LV_EVENT_..., param)` + +Read the [Event overview](/overview/event) to learn more about events. + + +### Styles +Be sure to read the [Style overview](/overview/style). Here only the most essential functions are described. + +A new style can be added to an object with the `lv_obj_add_style(obj, &new_style, selector)` function. +`selector` is an ORed combination of part and state(s). E.g. `LV_PART_SCROLLBAR | LV_STATE_PRESSED`. + +The base objects use `LV_PART_MAIN` style properties and `LV_PART_SCROLLBAR` with the typical background style properties. + + +### Flags +There are some attributes which can be enabled/disabled by `lv_obj_add/clear_flag(obj, LV_OBJ_FLAG_...)`: + +- `LV_OBJ_FLAG_HIDDEN` Make the object hidden. (Like it wasn't there at all) +- `LV_OBJ_FLAG_CLICKABLE` Make the object clickable by input devices +- `LV_OBJ_FLAG_CLICK_FOCUSABLE` Add focused state to the object when clicked +- `LV_OBJ_FLAG_CHECKABLE` Toggle checked state when the object is clicked +- `LV_OBJ_FLAG_SCROLLABLE` Make the object scrollable +- `LV_OBJ_FLAG_SCROLL_ELASTIC` Allow scrolling inside but with slower speed +- `LV_OBJ_FLAG_SCROLL_MOMENTUM` Make the object scroll further when "thrown" +- `LV_OBJ_FLAG_SCROLL_ONE` Allow scrolling only one snappable children +- `LV_OBJ_FLAG_SCROLL_CHAIN_HOR` Allow propagating the horizontal scroll to a parent +- `LV_OBJ_FLAG_SCROLL_CHAIN_VER` Allow propagating the vertical scroll to a parent +- `LV_OBJ_FLAG_SCROLL_CHAIN` Simple packaging for (`LV_OBJ_FLAG_SCROLL_CHAIN_HOR | LV_OBJ_FLAG_SCROLL_CHAIN_VER`) +- `LV_OBJ_FLAG_SCROLL_ON_FOCUS` Automatically scroll object to make it visible when focused +- `LV_OBJ_FLAG_SCROLL_WITH_ARROW` Allow scrolling the focused object with arrow keys +- `LV_OBJ_FLAG_SNAPPABLE` If scroll snap is enabled on the parent it can snap to this object +- `LV_OBJ_FLAG_PRESS_LOCK` Keep the object pressed even if the press slid from the object +- `LV_OBJ_FLAG_EVENT_BUBBLE` Propagate the events to the parent too +- `LV_OBJ_FLAG_GESTURE_BUBBLE` Propagate the gestures to the parent +- `LV_OBJ_FLAG_ADV_HITTEST` Allow performing more accurate hit (click) test. E.g. accounting for rounded corners +- `LV_OBJ_FLAG_IGNORE_LAYOUT` Make the object positionable by the layouts +- `LV_OBJ_FLAG_FLOATING` Do not scroll the object when the parent scrolls and ignore layout +- `LV_OBJ_FLAG_OVERFLOW_VISIBLE` Do not clip the children's content to the parent's boundary + +- `LV_OBJ_FLAG_LAYOUT_1` Custom flag, free to use by layouts +- `LV_OBJ_FLAG_LAYOUT_2` Custom flag, free to use by layouts + +- `LV_OBJ_FLAG_WIDGET_1` Custom flag, free to use by widget +- `LV_OBJ_FLAG_WIDGET_2` Custom flag, free to use by widget + +- `LV_OBJ_FLAG_USER_1` Custom flag, free to use by user +- `LV_OBJ_FLAG_USER_2` Custom flag, free to use by user +- `LV_OBJ_FLAG_USER_3` Custom flag, free to use by user +- `LV_OBJ_FLAG_USER_4` Custom flag, free to use by user + +Some examples: +```c +/*Hide on object*/ +lv_obj_add_flag(obj, LV_OBJ_FLAG_HIDDEN); + +/*Make an object non-clickable*/ +lv_obj_clear_flag(obj, LV_OBJ_FLAG_CLICKABLE); +``` + +### Groups + +Read the [Input devices overview](/overview/indev) to learn more about *Groups*. + +Objects are added to a *group* with `lv_group_add_obj(group, obj)`, and you can use `lv_obj_get_group(obj)` to see which group an object belongs to. + +`lv_obj_is_focused(obj)` returns if the object is currently focused on its group or not. If the object is not added to a group, `false` will be returned. + + +### Extended click area +By default, the objects can be clicked only within their bounding area. However, this can be extended with `lv_obj_set_ext_click_area(obj, size)`. + +## Events +- `LV_EVENT_VALUE_CHANGED` when the `LV_OBJ_FLAG_CHECKABLE` flag is enabled and the object clicked (on transition to/from the checked state) +- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` is sent for the following types: + - `LV_OBJ_DRAW_PART_RECTANGLE` The main rectangle + - `part`: `LV_PART_MAIN` + - `rect_dsc` + - `draw_area`: the area of the rectangle + - `LV_OBJ_DRAW_PART_BORDER_POST` The border if the `border_post` style property is `true` + - `part`: `LV_PART_MAIN` + - `rect_dsc` + - `draw_area`: the area of the rectangle + - `LV_OBJ_DRAW_PART_SCROLLBAR` the scrollbars + - `part`: `LV_PART_SCROLLBAR` + - `rect_dsc` + - `draw_area`: the area of the rectangle + +Learn more about [Events](/overview/event). + +## Keys +If `LV_OBJ_FLAG_CHECKABLE` is enabled, `LV_KEY_RIGHT` and `LV_KEY_UP` make the object checked, and `LV_KEY_LEFT` and `LV_KEY_DOWN` make it unchecked. + +If `LV_OBJ_FLAG_SCROLLABLE` is enabled, but the object is not editable (as declared by the widget class), the arrow keys (`LV_KEY_UP`, `LV_KEY_DOWN`, `LV_KEY_LEFT`, `LV_KEY_RIGHT`) scroll the object. If the object can only scroll vertically, `LV_KEY_LEFT` and `LV_KEY_RIGHT` will scroll up/down instead, making it compatible with an encoder input device. See [Input devices overview](/overview/indev) for more on encoder behaviors and the edit mode. + + +Learn more about [Keys](/overview/indev). + +## Example + +```eval_rst + +.. include:: ../../examples/widgets/obj/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_obj.h + :project: lvgl + +``` |
