diff options
Diffstat (limited to 'docs')
252 files changed, 29454 insertions, 14791 deletions
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md deleted file mode 100644 index 27fa9f003..000000000 --- a/docs/CHANGELOG.md +++ /dev/null @@ -1,1925 +0,0 @@ -# Changelog - -## [v8.3.6](https://github.com/lvgl/lvgl/compare/v8.3.6...v8.3.5) 3 April 2023 - -### New Features - -- feat(msg): add lv_msg_unsubcribe_obj [`6af0179`](https://github.com/lvgl/lvgl/commit/6af01798d82f90f0c2ba6a9da39c4f10fb427df7) - -### Performance - -### Fixes - -- fix(group): fix default_group becomes wild pointer when deleted [`4076`](https://github.com/lvgl/lvgl/pull/4076) -- fix(fs_posix): allow creating new file and set permission. [`3976`](https://github.com/lvgl/lvgl/pull/3976) -- fix(img): support negative angles [`3846`](https://github.com/lvgl/lvgl/pull/3846) -- fix(gif): synchronize with master [`4003`](https://github.com/lvgl/lvgl/pull/4003) -- fix(gpu): fix STM GPU drivers for some variants [`4004`](https://github.com/lvgl/lvgl/pull/4004) -- fix(img): possible divide by 0 exception (lvgl#3988) [`3990`](https://github.com/lvgl/lvgl/pull/3990) -- fix(arc): fix knob area invalidation [`d0e19eb`](https://github.com/lvgl/lvgl/commit/d0e19eb2d38ba8a500399b0496d7a8363be4003e) -- fix(slider): consider animations on pressing [`0b7777f`](https://github.com/lvgl/lvgl/commit/0b7777f27a7932efe3d594be426e1beb59d80ae3) -- fix(bar): delete running animations when a new value is set without animation [`aa31380`](https://github.com/lvgl/lvgl/commit/aa313806d0ebde475fc2bc360a15172cc1b658a7) -- docs: use a fixed commit of lv_web_emscripten [`501230e`](https://github.com/lvgl/lvgl/commit/501230e0fc95936199b3187d350873c3bb4a94e4) - -### Examples - -### Docs - -- docs(arduino): add note to not use lv_examles library [`2f294aa`](https://github.com/lvgl/lvgl/commit/2f294aa76c8fece98a4fa72304bc6f267ed2a228) -- docs: use a fixed commit of lv_web_emscripten [`501230e`](https://github.com/lvgl/lvgl/commit/501230e0fc95936199b3187d350873c3bb4a94e4) - -### CI and tests - -### Others - -- chore(cmsis-pack): update cmsis-pack for v8.3.6 [`4108`](https://github.com/lvgl/lvgl/pull/4108) -- chore: update the version numbers to v8.3.5-dev [`77670fb`](https://github.com/lvgl/lvgl/commit/77670fb1a55e0f2012ff7a057e535830e7253e22) -- Update build_html_examples.sh [`399069b`](https://github.com/lvgl/lvgl/commit/399069b4a2423c11823581668fe71ce9a7c88e7d) - - -## [v8.3.5](https://github.com/lvgl/lvgl/compare/v8.3.4...v8.3.5) 7 February 2023 - -### Performance - -- perf(gpu): improve NXP's PXP and VGLite accelerators [`3952`](https://github.com/lvgl/lvgl/pull/3952) -- perf(dam2d): rework stm32 dma2d [`3904`](https://github.com/lvgl/lvgl/pull/3904) - -### Fixes - -- fix(monkey): remove executable permissions from source files [`3971`](https://github.com/lvgl/lvgl/pull/3971) -- fix(ci): set Ubuntu version for MicroPython test [`3865`](https://github.com/lvgl/lvgl/pull/3865) -- fix(Kconfig): fix wrong type of LV_FS_STDIO_CACHE_SIZE (v8.3) [`3906`](https://github.com/lvgl/lvgl/pull/3906) -- docs(indev): fix the name of long_press_repeat_time (was long_press_rep_time) [`34c545e`](https://github.com/lvgl/lvgl/commit/34c545ef19dc97c8952a412e533a4cd3924b9fbc) -- fix(roller): consider the recolor setting of the label [`39f4247`](https://github.com/lvgl/lvgl/commit/39f424767fa57376c4cb08cf22951fd56d854fd6) - -### Examples - -### Docs - -- docs(indev): fix the name of long_press_repeat_time (was long_press_rep_time) [`34c545e`](https://github.com/lvgl/lvgl/commit/34c545ef19dc97c8952a412e533a4cd3924b9fbc) - -### CI and tests - -- ci(esp): fix push to the component registry on tag [`e529230`](https://github.com/lvgl/lvgl/commit/e529230f4bb97b4506c430aac96d5ddaef685dc4) - -### Others - -- chore(cmsis-pack): update cmsis-pack for v8.3.5 [`3972`](https://github.com/lvgl/lvgl/pull/3972) -- chore: add an option to "LV_TICK_CUSTOM" [`3879`](https://github.com/lvgl/lvgl/pull/3879) - -- bump version numbers to v8.3.5-dev [`47c8f8f`](https://github.com/lvgl/lvgl/commit/47c8f8f9822f4c0c0ffbe2f12b380bddefcec475) -- Update layer.md [`9faca8a`](https://github.com/lvgl/lvgl/commit/9faca8a8d4125e21dedbf6e46aa1586a6b57e5b8) - - -## [v8.3.4](https://github.com/lvgl/lvgl/compare/v8.3.4...v8.3.3) 15 December 2022 - -### New Features - -- feat(keyboard): ported arabic keyboard from release 7.10.0 [`3728`](https://github.com/lvgl/lvgl/pull/3728) -- feat(table): scroll to the selected cell with key navigation [`39d03a8`](https://github.com/lvgl/lvgl/commit/39d03a80f45847a1977cfe9cc6a509b1613d0aca) - -### Fixes - -- fix(rt-thread): sync rt-thread v5.0.0 rt_align [`3864`](https://github.com/lvgl/lvgl/pull/3864) -- fix(draw): SDL2 gradient support #3848 [`3856`](https://github.com/lvgl/lvgl/pull/3856) -- fix(esp.cmake): add demos and examples [`3784`](https://github.com/lvgl/lvgl/pull/3784) -- fix(indev): fix scrolling on transformed obejcts [`84cf05d`](https://github.com/lvgl/lvgl/commit/84cf05d8b23b31e000db757a278545e58fcbcbe8) -- fix(style): add the missing support for pct pivot in tranasform style properties [`c8e584f`](https://github.com/lvgl/lvgl/commit/c8e584f879a1e1427e7a8f5ff496af39f17df41d) -- fix(flex): be sure obj->w_layout and h_layout can't be set at the same time [`c4c4007`](https://github.com/lvgl/lvgl/commit/c4c400716e80a279e7b3d43b8992915fe94441eb) -- fix(chart): fix very dense bar charts [`bb2c2ac`](https://github.com/lvgl/lvgl/commit/bb2c2ac34ac943978513c7ed51885078979b1c10) -- fix(draw): handle LV_COLOR_DEPTH == 1 too in lv_draw_sw_transform [`bd11ad8`](https://github.com/lvgl/lvgl/commit/bd11ad8542eac9ff51420e5afb80f7e6fcf36a5c) -- fix(example): fix warnings [`1e3ca25`](https://github.com/lvgl/lvgl/commit/1e3ca25fed13bbf85c32a60d4b7041cf8bd525ab) -- fix(benchmark): fix warnings [`1ed026c`](https://github.com/lvgl/lvgl/commit/1ed026ca7307957568fe419f1ff39a15b2535b3e) -- fix(draw): fix text color with sub pixel rendering and BGR order [`e050f5c`](https://github.com/lvgl/lvgl/commit/e050f5ca156f79d752894f38f0a437c946205cb4) -- fix(meter): fix setting part_draw_dsc.id in needle img drawing [`716e5e2`](https://github.com/lvgl/lvgl/commit/716e5e2c8bd2a22e7d56e8d7ca33054a11a1f4ed) -- fix(gridnav): fix stucking in pressed state with encoder [`ad56dfa`](https://github.com/lvgl/lvgl/commit/ad56dfaf7046a9bb8c05e877a8c8852cd14a59af) -- fix(darw): add back the disappeared antialising=0 support [`2c17b28`](https://github.com/lvgl/lvgl/commit/2c17b28ac476c95a4153ab6cabb77b1c7208bb74) -- fix(msg): fix typos in API by adding wrappers [`41fa416`](https://github.com/lvgl/lvgl/commit/41fa41613455260ccdeb87ecb890ce026ff0a435) -- fix(draw): fix transformation accuracy [`e06f03d`](https://github.com/lvgl/lvgl/commit/e06f03db72f98439078118518158f52439dd7bf8) -- fix(style): remove the reduntant define of LV_GRADIENT_MAX_STOPS [`903e94b`](https://github.com/lvgl/lvgl/commit/903e94b716ca1b32cdb51de11df679953699e53b) -- demo(benchmark): fix lv_label_set_text_fmt format strings [`ae38258`](https://github.com/lvgl/lvgl/commit/ae3825871e31cd42cad2f310bdfc605150670511) -- demo(benchmark): fix warning [`1173dcb`](https://github.com/lvgl/lvgl/commit/1173dcba96621e20c9a7240c8572bd6573bce6a0) - -## [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 Microcontroller 2D Graphics Acceleration, e.g. Helium based acceleration, DMA-350 based acceleration etc. -- **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.lvgl.io/7.11/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.lvgl.io/7.11/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/docs/CHANGELOG.rst b/docs/CHANGELOG.rst new file mode 100644 index 000000000..ae8168c9f --- /dev/null +++ b/docs/CHANGELOG.rst @@ -0,0 +1,4111 @@ +.. _changelog: + +Changelog +========= + +# Changelog + +## `v8.3.6 <https://github.com/lvgl/lvgl/compare/v8.3.6...v8.3.5>`__ 3 April 2023 + +### New Features + +- feat(msg): add lv_msg_unsubcribe_obj ```6af0179`` https://github.com/lvgl/lvgl/commit/6af01798d82f90f0c2ba6a9da39c4f10fb427df7`__ + +### Performance + +### Fixes + +- fix(group): fix default_group becomes wild pointer when deleted ```4076`` https://github.com/lvgl/lvgl/pull/4076`__ +- fix(fs_posix): allow creating new file and set permission. ```3976`` https://github.com/lvgl/lvgl/pull/3976`__ +- fix(img): support negative angles ```3846`` https://github.com/lvgl/lvgl/pull/3846`__ +- fix(gif): synchronize with master ```4003`` https://github.com/lvgl/lvgl/pull/4003`__ +- fix(gpu): fix STM GPU drivers for some variants ```4004`` https://github.com/lvgl/lvgl/pull/4004`__ +- fix(img): possible divide by 0 exception (lvgl#3988) ```3990`` https://github.com/lvgl/lvgl/pull/3990`__ +- fix(arc): fix knob area invalidation ```d0e19eb`` https://github.com/lvgl/lvgl/commit/d0e19eb2d38ba8a500399b0496d7a8363be4003e`__ +- fix(slider): consider animations on pressing ```0b7777f`` https://github.com/lvgl/lvgl/commit/0b7777f27a7932efe3d594be426e1beb59d80ae3`__ +- fix(bar): delete running animations when a new value is set without animation ```aa31380`` https://github.com/lvgl/lvgl/commit/aa313806d0ebde475fc2bc360a15172cc1b658a7`__ +- docs: use a fixed commit of lv_web_emscripten ```501230e`` https://github.com/lvgl/lvgl/commit/501230e0fc95936199b3187d350873c3bb4a94e4`__ + +### Examples + +### Docs + +- docs(arduino): add note to not use lv_examles library ```2f294aa`` https://github.com/lvgl/lvgl/commit/2f294aa76c8fece98a4fa72304bc6f267ed2a228`__ +- docs: use a fixed commit of lv_web_emscripten ```501230e`` https://github.com/lvgl/lvgl/commit/501230e0fc95936199b3187d350873c3bb4a94e4`__ + +### CI and tests + +### Others + +- chore(cmsis-pack): update cmsis-pack for v8.3.6 ```4108`` https://github.com/lvgl/lvgl/pull/4108`__ +- chore: update the version numbers to v8.3.5-dev ```77670fb`` https://github.com/lvgl/lvgl/commit/77670fb1a55e0f2012ff7a057e535830e7253e22`__ +- Update build_html_examples.sh ```399069b`` https://github.com/lvgl/lvgl/commit/399069b4a2423c11823581668fe71ce9a7c88e7d`__ + + +`v8.3.5 <https://github.com/lvgl/lvgl/compare/v8.3.4...v8.3.5>`__ 7 February 2023 +--------------------------------------------------------------------------------- + +Performance +~~~~~~~~~~~ + +- perf(gpu): improve NXP’s PXP and VGLite accelerators + ```3952`` <https://github.com/lvgl/lvgl/pull/3952>`__ +- perf(dam2d): rework stm32 dma2d + ```3904`` <https://github.com/lvgl/lvgl/pull/3904>`__ + +Fixes +~~~~~ + +- fix(monkey): remove executable permissions from source files + ```3971`` <https://github.com/lvgl/lvgl/pull/3971>`__ +- fix(ci): set Ubuntu version for MicroPython test + ```3865`` <https://github.com/lvgl/lvgl/pull/3865>`__ +- fix(Kconfig): fix wrong type of LV_FS_STDIO_CACHE_SIZE (v8.3) + ```3906`` <https://github.com/lvgl/lvgl/pull/3906>`__ +- docs(indev): fix the name of long_press_repeat_time (was + long_press_rep_time) + ```34c545e`` <https://github.com/lvgl/lvgl/commit/34c545ef19dc97c8952a412e533a4cd3924b9fbc>`__ +- fix(roller): consider the recolor setting of the label + ```39f4247`` <https://github.com/lvgl/lvgl/commit/39f424767fa57376c4cb08cf22951fd56d854fd6>`__ + +Examples +~~~~~~~~ + +Docs +~~~~ + +- docs(indev): fix the name of long_press_repeat_time (was + long_press_rep_time) + ```34c545e`` <https://github.com/lvgl/lvgl/commit/34c545ef19dc97c8952a412e533a4cd3924b9fbc>`__ + +CI and tests +~~~~~~~~~~~~ + +- ci(esp): fix push to the component registry on tag + ```e529230`` <https://github.com/lvgl/lvgl/commit/e529230f4bb97b4506c430aac96d5ddaef685dc4>`__ + +Others +~~~~~~ + +- chore(cmsis-pack): update cmsis-pack for v8.3.5 + ```3972`` <https://github.com/lvgl/lvgl/pull/3972>`__ + +- chore: add an option to “LV_TICK_CUSTOM” + ```3879`` <https://github.com/lvgl/lvgl/pull/3879>`__ + +- bump version numbers to v8.3.5-dev + ```47c8f8f`` <https://github.com/lvgl/lvgl/commit/47c8f8f9822f4c0c0ffbe2f12b380bddefcec475>`__ + +- Update layer.md + ```9faca8a`` <https://github.com/lvgl/lvgl/commit/9faca8a8d4125e21dedbf6e46aa1586a6b57e5b8>`__ + +`v8.3.4 <https://github.com/lvgl/lvgl/compare/v8.3.4...v8.3.3>`__ 15 December 2022 +---------------------------------------------------------------------------------- + +New Features +~~~~~~~~~~~~ + +- feat(keyboard): ported arabic keyboard from release 7.10.0 + ```3728`` <https://github.com/lvgl/lvgl/pull/3728>`__ +- feat(table): scroll to the selected cell with key navigation + ```39d03a8`` <https://github.com/lvgl/lvgl/commit/39d03a80f45847a1977cfe9cc6a509b1613d0aca>`__ + +.. _fixes-1: + +Fixes +~~~~~ + +- fix(rt-thread): sync rt-thread v5.0.0 rt_align + ```3864`` <https://github.com/lvgl/lvgl/pull/3864>`__ +- fix(draw): SDL2 gradient support #3848 + ```3856`` <https://github.com/lvgl/lvgl/pull/3856>`__ +- fix(esp.cmake): add demos and examples + ```3784`` <https://github.com/lvgl/lvgl/pull/3784>`__ +- fix(indev): fix scrolling on transformed obejcts + ```84cf05d`` <https://github.com/lvgl/lvgl/commit/84cf05d8b23b31e000db757a278545e58fcbcbe8>`__ +- fix(style): add the missing support for pct pivot in tranasform style + properties + ```c8e584f`` <https://github.com/lvgl/lvgl/commit/c8e584f879a1e1427e7a8f5ff496af39f17df41d>`__ +- fix(flex): be sure obj->w_layout and h_layout can’t be set at the + same time + ```c4c4007`` <https://github.com/lvgl/lvgl/commit/c4c400716e80a279e7b3d43b8992915fe94441eb>`__ +- fix(chart): fix very dense bar charts + ```bb2c2ac`` <https://github.com/lvgl/lvgl/commit/bb2c2ac34ac943978513c7ed51885078979b1c10>`__ +- fix(draw): handle LV_COLOR_DEPTH == 1 too in lv_draw_sw_transform + ```bd11ad8`` <https://github.com/lvgl/lvgl/commit/bd11ad8542eac9ff51420e5afb80f7e6fcf36a5c>`__ +- fix(example): fix warnings + ```1e3ca25`` <https://github.com/lvgl/lvgl/commit/1e3ca25fed13bbf85c32a60d4b7041cf8bd525ab>`__ +- fix(benchmark): fix warnings + ```1ed026c`` <https://github.com/lvgl/lvgl/commit/1ed026ca7307957568fe419f1ff39a15b2535b3e>`__ +- fix(draw): fix text color with sub pixel rendering and BGR order + ```e050f5c`` <https://github.com/lvgl/lvgl/commit/e050f5ca156f79d752894f38f0a437c946205cb4>`__ +- fix(meter): fix setting part_draw_dsc.id in needle img drawing + ```716e5e2`` <https://github.com/lvgl/lvgl/commit/716e5e2c8bd2a22e7d56e8d7ca33054a11a1f4ed>`__ +- fix(gridnav): fix stucking in pressed state with encoder + ```ad56dfa`` <https://github.com/lvgl/lvgl/commit/ad56dfaf7046a9bb8c05e877a8c8852cd14a59af>`__ +- fix(darw): add back the disappeared antialising=0 support + ```2c17b28`` <https://github.com/lvgl/lvgl/commit/2c17b28ac476c95a4153ab6cabb77b1c7208bb74>`__ +- fix(msg): fix typos in API by adding wrappers + ```41fa416`` <https://github.com/lvgl/lvgl/commit/41fa41613455260ccdeb87ecb890ce026ff0a435>`__ +- fix(draw): fix transformation accuracy + ```e06f03d`` <https://github.com/lvgl/lvgl/commit/e06f03db72f98439078118518158f52439dd7bf8>`__ +- fix(style): remove the reduntant define of LV_GRADIENT_MAX_STOPS + ```903e94b`` <https://github.com/lvgl/lvgl/commit/903e94b716ca1b32cdb51de11df679953699e53b>`__ +- demo(benchmark): fix lv_label_set_text_fmt format strings + ```ae38258`` <https://github.com/lvgl/lvgl/commit/ae3825871e31cd42cad2f310bdfc605150670511>`__ +- demo(benchmark): fix warning + ```1173dcb`` <https://github.com/lvgl/lvgl/commit/1173dcba96621e20c9a7240c8572bd6573bce6a0>`__ + +`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-2: + +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-1: + +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-1: + +CI and tests +~~~~~~~~~~~~ + +- ci: protect test.c with #if LV_BUILD_TEST + ```be485d7`` <https://github.com/lvgl/lvgl/commit/be485d7605136d2a5d6a633c7cb5b7c525cae7ee>`__ + +.. _others-1: + +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-3: + +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-1: + +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-2: + +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 Microcontroller 2D + Graphics Acceleration, e.g. Helium based acceleration, DMA-350 based + acceleration etc. +- **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-1: + +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-1: + +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-4: + +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-2: + +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-3: + +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-2: + +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-1: + +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-2: + +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-2: + +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-5: + +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-3: + +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-4: + +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-3: + +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-2: + +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-1: + +Breaking Changes +~~~~~~~~~~~~~~~~ + +- :warning: feat(calendar): add the header directly into the calendar widget ```2e08f80`` <https://github.com/lvgl/lvgl/commit/2e08f80361a9d7e5b97f49af6afc3549ffbf2758>`__ + +.. _architectural-1: + +Architectural +~~~~~~~~~~~~~ + +- arch add small 3rd party libs to lvgl + ```2569`` <https://github.com/lvgl/lvgl/pull/2569>`__ + +.. _new-features-3: + +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-3: + +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-6: + +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-4: + +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-5: + +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-4: + +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-2: + +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 7971ade4 +- fix(msgbox) create modals on top layer instead of act screen 5cf6303e +- fix(colorwheel) disable LV_OBJ_FLAG_SCROLL_CHAIN by default 48d1c292 +- docs(grid) typo fix (#2310) 69d109d2 +- fix(arduino) fix the prototype of my_touchpad_read in the + LVGL_Arduino.ino 1a62f7a6 +- fix(meter) fix needle image invalidation 54d8e817 +- fix(mem) add lv\_ prefix to tlsf functions and types 0d52b59c +- fix(calendar) fix the position calculation today ad05e196 +- fix(typo) rename LV_OBJ_FLAG_SNAPABLE to LV_OBJ_FLAG_SNAPPABLE + e697807c +- docs(color) language fixes (#2302) 07ecc9f1 +- fix(tick) minor optimization on lv_tick_inc call test b4305df5 +- Spelling and other language fixes to documentation (#2293) d0aaacaf +- fix(theme) show disabled state on buttons of btnmatrix, msgbox and + keyboard 0be582b3 +- fix(scroll) keep the scroll position on object deleted 52edbb46 +- fix(msgbox) handle NULL btn map parameter 769c4a30 +- fix(group) allow refocusing objects 1520208b +- docs(overview) spelling fixes d2efb8c6 +- Merge branch ‘master’ of https://github.com/lvgl/lvgl 45960838 +- feat(timer) check if lv_tick_inc is called aa6641a6 +- feat(docs) add view on GitHub link a716ac6e +- fix(theme) fix the switch style in the default theme 0c0dc8ea +- docs fix typo 8ab80645 +- Merge branch ‘master’ of https://github.com/lvgl/lvgl e796448f +- feat(event) pass the scroll animation to LV_EVENT_SCROLL_BEGIN + ca54ecfe +- fix(tabview) fix with left and right tabs 17c57449 +- chore(docs) force docs rebuild 4a0f4139 +- chore(docs) always deploy master to docs/master as well 6d05692d +- fix(template) update lv_objx_template to v8 38bb8afc +- docs(extra) add extra/README.md 8cd504d5 +- Update CHANGELOG.md 48fd73d2 +- Update quick-overview.md (#2295) 5616471c +- fix(pxp) change LV_COLOR_TRANSP to LV_COLOR_CHROMA_KEY to v8 + compatibility 81f3068d +- adding micropython examples (#2286) c60ed68e +- docs(color) minor fix ac8f4534 +- fix(example) revert test code 77e2c1ff +- fix(draw) with additive blending with 32-bit color depth 786db2af +- docs(color) update colors’ docs 9056b5ee +- Merge branch ‘master’ of https://github.com/lvgl/lvgl a711a1dd +- perf(refresh) optimize where to wait for lv_disp_flush_ready with 2 + buffers d0172f14 +- docs(lv_obj_style) update add_style and remove_style function headers + (#2287) 60f7bcbf +- fix memory leak of spangroup (#2285) 33e0926a +- fix make lv_img_cache.h public because cache invalidation is public + 38ebcd81 +- Merge branch ‘master’ of https://github.com/lvgl/lvgl 2b292495 +- fix(btnmatrix) fix focus event handling 3b58ef14 +- Merge pull request #2280 from lvgl/dependabot/pip/docs/urllib3-1.26.5 + a2f45b26 +- fix(label) calculating the clip area 57e211cc +- chore(deps): bump urllib3 from 1.26.4 to 1.26.5 in /docs b2f77dfc +- fix(docs) add docs about the default group 29bfe604 + +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-4: + +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-1: + +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-5: + +New features +~~~~~~~~~~~~ + +- feat(indev) allow input events to be passed to disabled objects +- feat(spinbox) add inline get_step function for MicroPython support + +.. _bugfixes-2: + +Bugfixes +~~~~~~~~ + +- fix(btnmatrix) fix lv_btnmatrix_get_active_btn_text() when used in a + group + +v7.9.1 (19.01.2021) +------------------- + +.. _bugfixes-3: + +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-6: + +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-4: + +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-5: + +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-7: + +New features +~~~~~~~~~~~~ + +- make DMA2D non blocking +- add unscii-16 built-in font +- add KConfig +- add lv_refr_get_fps_avg() + +.. _bugfixes-6: + +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-7: + +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-8: + +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-8: + +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-9: + +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-10: + +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-9: + +New features +~~~~~~~~~~~~ + +- Check whether any style property has changed on a state change to + decide if any redraw is required + +.. _bugfixes-11: + +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-10: + +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-12: + +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-11: + +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-13: + +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-14: + +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-12: + +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-15: + +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-13: + +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-16: + +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-14: + +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-17: + +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-18: + +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-19: + +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.lvgl.io/7.11/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.lvgl.io/7.11/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-3: + +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-1: + +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/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md deleted file mode 100644 index 4052ad679..000000000 --- a/docs/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,46 +0,0 @@ -# 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/docs/CODE_OF_CONDUCT.rst.back b/docs/CODE_OF_CONDUCT.rst.back new file mode 100644 index 000000000..7c7cf282b --- /dev/null +++ b/docs/CODE_OF_CONDUCT.rst.back @@ -0,0 +1,83 @@ +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 <http://contributor-covenant.org>`__, version 1.4, available at +`http://contributor-covenant.org/version/1/4 <http://contributor-covenant.org/version/1/4/>`__ diff --git a/docs/CODING_STYLE.md b/docs/CODING_STYLE.md deleted file mode 100644 index 756a5cd24..000000000 --- a/docs/CODING_STYLE.md +++ /dev/null @@ -1,124 +0,0 @@ -# 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-format.py` from the `scripts` 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 -``` diff --git a/docs/CODING_STYLE.rst b/docs/CODING_STYLE.rst new file mode 100644 index 000000000..f5a77a675 --- /dev/null +++ b/docs/CODING_STYLE.rst @@ -0,0 +1,168 @@ +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: + +.. code:: 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. +:literal:`/\*Update the value of \`x_act`*/` + +Formatting +---------- + +Here is example to show bracket placing and using of white spaces: + +.. code:: 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-format.py`` from +the ``scripts`` 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: + +.. code:: 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: + +.. code:: 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: + +.. code:: console + + pre-commit run name-of-the-hook diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md deleted file mode 100644 index 5f739c2a5..000000000 --- a/docs/CONTRIBUTING.md +++ /dev/null @@ -1,296 +0,0 @@ - -# 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/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/docs/CONTRIBUTING.rst b/docs/CONTRIBUTING.rst new file mode 100644 index 000000000..4b0c7e7c5 --- /dev/null +++ b/docs/CONTRIBUTING.rst @@ -0,0 +1,431 @@ +.. _contributing: + +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 Coding style 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. + +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. +6. 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. +7. Describe what is in the update. An example code is welcome if applicable. +8. 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: + +.. code-block:: + + <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/. + +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: + +.. code-block:: + + /* 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! + +.. raw:: html + + <script async defer src="https://buttons.github.io/buttons.js"></script> + +.. raw:: html + + <!-- Place this tag where you want the button to render. --> + +Star + +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/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/docs/Doxyfile b/docs/Doxyfile new file mode 100644 index 000000000..538bfbb69 --- /dev/null +++ b/docs/Doxyfile @@ -0,0 +1,2455 @@ +# Doxyfile 1.8.13 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project. +# +# All text after a double hash (##) is considered a comment and is placed in +# front of the TAG it is preceding. +# +# All text after a single hash (#) is considered a comment and will be ignored. +# The format is: +# TAG = value [value, ...] +# For lists, items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (\" \"). + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- + +# This tag specifies the encoding used for all characters in the config file +# that follow. The default is UTF-8 which is also the encoding used for all text +# before the first occurrence of this tag. Doxygen uses libiconv (or the iconv +# built into libc) for the transcoding. See http://www.gnu.org/software/libiconv +# for the list of possible encodings. +# The default value is: UTF-8. + +DOXYFILE_ENCODING = UTF-8 + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by +# double-quotes, unless you are using Doxywizard) that should identify the +# project for which the documentation is generated. This name is used in the +# title of most generated pages and in a few other places. +# The default value is: My Project. + +PROJECT_NAME = "LVGL" + +# The PROJECT_NUMBER tag can be used to enter a project or revision number. This +# could be handy for archiving the generated documentation or if some version +# control system is used. + +PROJECT_NUMBER = + +# Using the PROJECT_BRIEF tag one can provide an optional one line description +# for a project that appears at the top of each page and should give viewer a +# quick idea about the purpose of the project. Keep the description short. + +PROJECT_BRIEF = + +# With the PROJECT_LOGO tag one can specify a logo or an icon that is included +# in the documentation. The maximum height of the logo should not exceed 55 +# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy +# the logo to the output directory. + +PROJECT_LOGO = + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path +# into which the generated documentation will be written. If a relative path is +# entered, it will be relative to the location where doxygen was started. If +# left blank the current directory will be used. + +OUTPUT_DIRECTORY = . + +# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- +# directories (in 2 levels) under the output directory of each output format and +# will distribute the generated files over these directories. Enabling this +# option can be useful when feeding doxygen a huge amount of source files, where +# putting all generated files in the same directory would otherwise causes +# performance problems for the file system. +# The default value is: NO. + +CREATE_SUBDIRS = NO + +# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII +# characters to appear in the names of generated files. If set to NO, non-ASCII +# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode +# U+3044. +# The default value is: NO. + +ALLOW_UNICODE_NAMES = NO + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese, +# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States), +# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian, +# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages), +# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian, +# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian, +# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish, +# Ukrainian and Vietnamese. +# The default value is: English. + +OUTPUT_LANGUAGE = English + +# If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member +# descriptions after the members that are listed in the file and class +# documentation (similar to Javadoc). Set to NO to disable this. +# The default value is: YES. + +BRIEF_MEMBER_DESC = YES + +# If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief +# description of a member or function before the detailed description +# +# Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# brief descriptions will be completely suppressed. +# The default value is: YES. + +REPEAT_BRIEF = YES + +# This tag implements a quasi-intelligent brief description abbreviator that is +# used to form the text in various listings. Each string in this list, if found +# as the leading text of the brief description, will be stripped from the text +# and the result, after processing the whole list, is used as the annotated +# text. Otherwise, the brief description is used as-is. If left blank, the +# following values are used ($name is automatically replaced with the name of +# the entity):The $name class, The $name widget, The $name file, is, provides, +# specifies, contains, represents, a, an and the. + +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the + +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# doxygen will generate a detailed section even if there is only a brief +# description. +# The default value is: NO. + +ALWAYS_DETAILED_SEC = NO + +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. +# The default value is: NO. + +INLINE_INHERITED_MEMB = NO + +# If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path +# before files name in the file list and in the header files. If set to NO the +# shortest path that makes the file name unique will be used +# The default value is: YES. + +FULL_PATH_NAMES = YES + +# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. +# Stripping is only done if one of the specified strings matches the left-hand +# part of the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the path to +# strip. +# +# Note that you can specify absolute paths here, but also relative paths, which +# will be relative from the directory where doxygen is started. +# This tag requires that the tag FULL_PATH_NAMES is set to YES. + +STRIP_FROM_PATH = + +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the +# path mentioned in the documentation of a class, which tells the reader which +# header file to include in order to use a class. If left blank only the name of +# the header file containing the class definition is used. Otherwise one should +# specify the list of include paths that are normally passed to the compiler +# using the -I flag. + +STRIP_FROM_INC_PATH = + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but +# less readable) file names. This can be useful is your file systems doesn't +# support long names like on DOS, Mac, or CD-ROM. +# The default value is: NO. + +SHORT_NAMES = NO + +# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the +# first line (until the first dot) of a Javadoc-style comment as the brief +# description. If set to NO, the Javadoc-style will behave just like regular Qt- +# style comments (thus requiring an explicit @brief command for a brief +# description.) +# The default value is: NO. + +JAVADOC_AUTOBRIEF = NO + +# If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first +# line (until the first dot) of a Qt-style comment as the brief description. If +# set to NO, the Qt-style will behave just like regular Qt-style comments (thus +# requiring an explicit \brief command for a brief description.) +# The default value is: NO. + +QT_AUTOBRIEF = NO + +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a +# multi-line C++ special comment block (i.e. a block of //! or /// comments) as +# a brief description. This used to be the default behavior. The new default is +# to treat a multi-line C++ comment block as a detailed description. Set this +# tag to YES if you prefer the old behavior instead. +# +# Note that setting this tag to YES also means that rational rose comments are +# not recognized any more. +# The default value is: NO. + +MULTILINE_CPP_IS_BRIEF = NO + +# If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the +# documentation from any documented member that it re-implements. +# The default value is: YES. + +INHERIT_DOCS = YES + +# If the SEPARATE_MEMBER_PAGES tag is set to YES then doxygen will produce a new +# page for each member. If set to NO, the documentation of a member will be part +# of the file/class/namespace that contains it. +# The default value is: NO. + +SEPARATE_MEMBER_PAGES = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen +# uses this value to replace tabs by spaces in code fragments. +# Minimum value: 1, maximum value: 16, default value: 4. + +TAB_SIZE = 4 + +# This tag can be used to specify a number of aliases that act as commands in +# the documentation. An alias has the form: +# name=value +# For example adding +# "sideeffect=@par Side Effects:\n" +# will allow you to put the command \sideeffect (or @sideeffect) in the +# documentation, which will result in a user-defined paragraph with heading +# "Side Effects:". You can put \n's in the value part of an alias to insert +# newlines. + +ALIASES = + +# This tag can be used to specify a number of word-keyword mappings (TCL only). +# A mapping has the form "name=value". For example adding "class=itcl::class" +# will allow you to use the command class in the itcl::class meaning. + +# TCL_SUBST = **OBSOLETE** + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources +# only. Doxygen will then generate output that is more tailored for C. For +# instance, some of the names that are used will be different. The list of all +# members will be omitted, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_FOR_C = YES + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or +# Python sources only. Doxygen will then generate output that is more tailored +# for that language. For instance, namespaces will be presented as packages, +# qualified scopes will look different, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_JAVA = NO + +# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran +# sources. Doxygen will then generate output that is tailored for Fortran. +# The default value is: NO. + +OPTIMIZE_FOR_FORTRAN = NO + +# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL +# sources. Doxygen will then generate output that is tailored for VHDL. +# The default value is: NO. + +OPTIMIZE_OUTPUT_VHDL = NO + +# Doxygen selects the parser to use depending on the extension of the files it +# parses. With this tag you can assign which parser to use for a given +# extension. Doxygen has a built-in mapping, but you can override or extend it +# using this tag. The format is ext=language, where ext is a file extension, and +# language is one of the parsers supported by doxygen: IDL, Java, Javascript, +# C#, C, C++, D, PHP, Objective-C, Python, Fortran (fixed format Fortran: +# FortranFixed, free formatted Fortran: FortranFree, unknown formatted Fortran: +# Fortran. In the later case the parser tries to guess whether the code is fixed +# or free formatted code, this is the default for Fortran type files), VHDL. For +# instance to make doxygen treat .inc files as Fortran files (default is PHP), +# and .f files as C (default is Fortran), use: inc=Fortran f=C. +# +# Note: For files without extension you can use no_extension as a placeholder. +# +# Note that for custom extensions you also need to set FILE_PATTERNS otherwise +# the files are not read by doxygen. + +EXTENSION_MAPPING = + +# If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments +# according to the Markdown format, which allows for more readable +# documentation. See http://daringfireball.net/projects/markdown/ for details. +# The output of markdown processing is further processed by doxygen, so you can +# mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in +# case of backward compatibilities issues. +# The default value is: YES. + +MARKDOWN_SUPPORT = YES + +# When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up +# to that level are automatically included in the table of contents, even if +# they do not have an id attribute. +# Note: This feature currently applies only to Markdown headings. +# Minimum value: 0, maximum value: 99, default value: 0. +# This tag requires that the tag MARKDOWN_SUPPORT is set to YES. + +TOC_INCLUDE_HEADINGS = 0 + +# When enabled doxygen tries to link words that correspond to documented +# classes, or namespaces to their corresponding documentation. Such a link can +# be prevented in individual cases by putting a % sign in front of the word or +# globally by setting AUTOLINK_SUPPORT to NO. +# The default value is: YES. + +AUTOLINK_SUPPORT = YES + +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want +# to include (a tag file for) the STL sources as input, then you should set this +# tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); +# versus func(std::string) {}). This also make the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate. +# The default value is: NO. + +BUILTIN_STL_SUPPORT = NO + +# If you use Microsoft's C++/CLI language, you should set this option to YES to +# enable parsing support. +# The default value is: NO. + +CPP_CLI_SUPPORT = NO + +# Set the SIP_SUPPORT tag to YES if your project consists of sip (see: +# http://www.riverbankcomputing.co.uk/software/sip/intro) sources only. Doxygen +# will parse them like normal C++ but will assume all classes use public instead +# of private inheritance when no explicit protection keyword is present. +# The default value is: NO. + +SIP_SUPPORT = NO + +# For Microsoft's IDL there are propget and propput attributes to indicate +# getter and setter methods for a property. Setting this option to YES will make +# doxygen to replace the get and set methods by a property in the documentation. +# This will only work if the methods are indeed getting or setting a simple +# type. If this is not the case, or you want to show the methods anyway, you +# should set this option to NO. +# The default value is: YES. + +IDL_PROPERTY_SUPPORT = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. +# The default value is: NO. + +DISTRIBUTE_GROUP_DOC = NO + +# If one adds a struct or class to a group and this option is enabled, then also +# any nested class or struct is added to the same group. By default this option +# is disabled and one has to add nested compounds explicitly via \ingroup. +# The default value is: NO. + +GROUP_NESTED_COMPOUNDS = NO + +# Set the SUBGROUPING tag to YES to allow class member groups of the same type +# (for instance a group of public functions) to be put as a subgroup of that +# type (e.g. under the Public Functions section). Set it to NO to prevent +# subgrouping. Alternatively, this can be done per class using the +# \nosubgrouping command. +# The default value is: YES. + +SUBGROUPING = YES + +# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions +# are shown inside the group in which they are included (e.g. using \ingroup) +# instead of on a separate page (for HTML and Man pages) or section (for LaTeX +# and RTF). +# +# Note that this feature does not work in combination with +# SEPARATE_MEMBER_PAGES. +# The default value is: NO. + +INLINE_GROUPED_CLASSES = NO + +# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions +# with only public data fields or simple typedef fields will be shown inline in +# the documentation of the scope in which they are defined (i.e. file, +# namespace, or group documentation), provided this scope is documented. If set +# to NO, structs, classes, and unions are shown on a separate page (for HTML and +# Man pages) or section (for LaTeX and RTF). +# The default value is: NO. + +INLINE_SIMPLE_STRUCTS = NO + +# When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or +# enum is documented as struct, union, or enum with the name of the typedef. So +# typedef struct TypeS {} TypeT, will appear in the documentation as a struct +# with name TypeT. When disabled the typedef will appear as a member of a file, +# namespace, or class. And the struct will be named TypeS. This can typically be +# useful for C code in case the coding convention dictates that all compound +# types are typedef'ed and only the typedef is referenced, never the tag name. +# The default value is: NO. + +TYPEDEF_HIDES_STRUCT = NO + +# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This +# cache is used to resolve symbols given their name and scope. Since this can be +# an expensive process and often the same symbol appears multiple times in the +# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small +# doxygen will become slower. If the cache is too large, memory is wasted. The +# cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range +# is 0..9, the default is 0, corresponding to a cache size of 2^16=65536 +# symbols. At the end of a run doxygen will report the cache usage and suggest +# the optimal cache size from a speed point of view. +# Minimum value: 0, maximum value: 9, default value: 0. + +LOOKUP_CACHE_SIZE = 0 + +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- + +# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in +# documentation are documented, even if no documentation was available. Private +# class members and static file members will be hidden unless the +# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES. +# Note: This will also disable the warnings about undocumented members that are +# normally produced when WARNINGS is set to YES. +# The default value is: NO. + +EXTRACT_ALL = NO + +# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will +# be included in the documentation. +# The default value is: NO. + +EXTRACT_PRIVATE = NO + +# If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal +# scope will be included in the documentation. +# The default value is: NO. + +EXTRACT_PACKAGE = YES + +# If the EXTRACT_STATIC tag is set to YES, all static members of a file will be +# included in the documentation. +# The default value is: NO. + +EXTRACT_STATIC = YES + +# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined +# locally in source files will be included in the documentation. If set to NO, +# only classes defined in header files are included. Does not have any effect +# for Java sources. +# The default value is: YES. + +EXTRACT_LOCAL_CLASSES = YES + +# This flag is only useful for Objective-C code. If set to YES, local methods, +# which are defined in the implementation section but not in the interface are +# included in the documentation. If set to NO, only methods in the interface are +# included. +# The default value is: NO. + +EXTRACT_LOCAL_METHODS = NO + +# If this flag is set to YES, the members of anonymous namespaces will be +# extracted and appear in the documentation as a namespace called +# 'anonymous_namespace{file}', where file will be replaced with the base name of +# the file that contains the anonymous namespace. By default anonymous namespace +# are hidden. +# The default value is: NO. + +EXTRACT_ANON_NSPACES = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all +# undocumented members inside documented classes or files. If set to NO these +# members will be included in the various overviews, but no documentation +# section is generated. This option has no effect if EXTRACT_ALL is enabled. +# The default value is: NO. + +HIDE_UNDOC_MEMBERS = NO + +# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. If set +# to NO, these classes will be included in the various overviews. This option +# has no effect if EXTRACT_ALL is enabled. +# The default value is: NO. + +HIDE_UNDOC_CLASSES = NO + +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend +# (class|struct|union) declarations. If set to NO, these declarations will be +# included in the documentation. +# The default value is: NO. + +HIDE_FRIEND_COMPOUNDS = NO + +# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any +# documentation blocks found inside the body of a function. If set to NO, these +# blocks will be appended to the function's detailed documentation block. +# The default value is: NO. + +HIDE_IN_BODY_DOCS = NO + +# The INTERNAL_DOCS tag determines if documentation that is typed after a +# \internal command is included. If the tag is set to NO then the documentation +# will be excluded. Set it to YES to include the internal documentation. +# The default value is: NO. + +INTERNAL_DOCS = YES + +# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file +# names in lower-case letters. If set to YES, upper-case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows +# and Mac users are advised to set this option to NO. +# The default value is: system dependent. + +CASE_SENSE_NAMES = YES + +# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with +# their full class and namespace scopes in the documentation. If set to YES, the +# scope will be hidden. +# The default value is: NO. + +HIDE_SCOPE_NAMES = NO + +# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will +# append additional text to a page's title, such as Class Reference. If set to +# YES the compound reference will be hidden. +# The default value is: NO. + +HIDE_COMPOUND_REFERENCE= NO + +# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of +# the files that are included by a file in the documentation of that file. +# The default value is: YES. + +SHOW_INCLUDE_FILES = YES + +# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each +# grouped member an include statement to the documentation, telling the reader +# which file to include in order to use the member. +# The default value is: NO. + +SHOW_GROUPED_MEMB_INC = NO + +# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include +# files with double quotes in the documentation rather than with sharp brackets. +# The default value is: NO. + +FORCE_LOCAL_INCLUDES = NO + +# If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the +# documentation for inline members. +# The default value is: YES. + +INLINE_INFO = YES + +# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the +# (detailed) documentation of file and class members alphabetically by member +# name. If set to NO, the members will appear in declaration order. +# The default value is: YES. + +SORT_MEMBER_DOCS = YES + +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief +# descriptions of file, namespace and class members alphabetically by member +# name. If set to NO, the members will appear in declaration order. Note that +# this will also influence the order of the classes in the class list. +# The default value is: NO. + +SORT_BRIEF_DOCS = NO + +# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the +# (brief and detailed) documentation of class members so that constructors and +# destructors are listed first. If set to NO the constructors will appear in the +# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS. +# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief +# member documentation. +# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting +# detailed member documentation. +# The default value is: NO. + +SORT_MEMBERS_CTORS_1ST = NO + +# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy +# of group names into alphabetical order. If set to NO the group names will +# appear in their defined order. +# The default value is: NO. + +SORT_GROUP_NAMES = NO + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by +# fully-qualified names, including namespaces. If set to NO, the class list will +# be sorted only by class name, not including the namespace part. +# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. +# Note: This option applies only to the class list, not to the alphabetical +# list. +# The default value is: NO. + +SORT_BY_SCOPE_NAME = NO + +# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper +# type resolution of all parameters of a function it will reject a match between +# the prototype and the implementation of a member function even if there is +# only one candidate or it is obvious which candidate to choose by doing a +# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still +# accept a match between prototype and implementation in such cases. +# The default value is: NO. + +STRICT_PROTO_MATCHING = NO + +# The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo +# list. This list is created by putting \todo commands in the documentation. +# The default value is: YES. + +GENERATE_TODOLIST = YES + +# The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test +# list. This list is created by putting \test commands in the documentation. +# The default value is: YES. + +GENERATE_TESTLIST = YES + +# The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug +# list. This list is created by putting \bug commands in the documentation. +# The default value is: YES. + +GENERATE_BUGLIST = YES + +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO) +# the deprecated list. This list is created by putting \deprecated commands in +# the documentation. +# The default value is: YES. + +GENERATE_DEPRECATEDLIST= YES + +# The ENABLED_SECTIONS tag can be used to enable conditional documentation +# sections, marked by \if <section_label> ... \endif and \cond <section_label> +# ... \endcond blocks. + +ENABLED_SECTIONS = + +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the +# initial value of a variable or macro / define can have for it to appear in the +# documentation. If the initializer consists of more lines than specified here +# it will be hidden. Use a value of 0 to hide initializers completely. The +# appearance of the value of individual variables and macros / defines can be +# controlled using \showinitializer or \hideinitializer command in the +# documentation regardless of this setting. +# Minimum value: 0, maximum value: 10000, default value: 30. + +MAX_INITIALIZER_LINES = 30 + +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated at +# the bottom of the documentation of classes and structs. If set to YES, the +# list will mention the files that were used to generate the documentation. +# The default value is: YES. + +SHOW_USED_FILES = YES + +# Set the SHOW_FILES tag to NO to disable the generation of the Files page. This +# will remove the Files entry from the Quick Index and from the Folder Tree View +# (if specified). +# The default value is: YES. + +SHOW_FILES = YES + +# Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces +# page. This will remove the Namespaces entry from the Quick Index and from the +# Folder Tree View (if specified). +# The default value is: YES. + +SHOW_NAMESPACES = YES + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from +# the version control system). Doxygen will invoke the program by executing (via +# popen()) the command command input-file, where command is the value of the +# FILE_VERSION_FILTER tag, and input-file is the name of an input file provided +# by doxygen. Whatever the program writes to standard output is used as the file +# version. For an example see the documentation. + +FILE_VERSION_FILTER = + +# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed +# by doxygen. The layout file controls the global structure of the generated +# output files in an output format independent way. To create the layout file +# that represents doxygen's defaults, run doxygen with the -l option. You can +# optionally specify a file name after the option, if omitted DoxygenLayout.xml +# will be used as the name of the layout file. +# +# Note that if you run doxygen from a directory containing a file called +# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE +# tag is left empty. + +LAYOUT_FILE = + +# The CITE_BIB_FILES tag can be used to specify one or more bib files containing +# the reference definitions. This must be a list of .bib files. The .bib +# extension is automatically appended if omitted. This requires the bibtex tool +# to be installed. See also http://en.wikipedia.org/wiki/BibTeX for more info. +# For LaTeX the style of the bibliography can be controlled using +# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the +# search path. See also \cite for info how to create references. + +CITE_BIB_FILES = + +#--------------------------------------------------------------------------- +# Configuration options related to warning and progress messages +#--------------------------------------------------------------------------- + +# The QUIET tag can be used to turn on/off the messages that are generated to +# standard output by doxygen. If QUIET is set to YES this implies that the +# messages are off. +# The default value is: NO. + +QUIET = YES + +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES +# this implies that the warnings are on. +# +# Tip: Turn warnings on while writing the documentation. +# The default value is: YES. + +WARNINGS = NO + +# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate +# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag +# will automatically be disabled. +# The default value is: YES. + +WARN_IF_UNDOCUMENTED = NO + +# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some parameters +# in a documented function, or documenting parameters that don't exist or using +# markup commands wrongly. +# The default value is: YES. + +WARN_IF_DOC_ERROR = NO + +# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that +# are documented, but have no documentation for their parameters or return +# value. If set to NO, doxygen will only warn about wrong or incomplete +# parameter documentation, but not about the absence of documentation. +# The default value is: NO. + +WARN_NO_PARAMDOC = NO + +# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when +# a warning is encountered. +# The default value is: NO. + +WARN_AS_ERROR = NO + +# The WARN_FORMAT tag determines the format of the warning messages that doxygen +# can produce. The string should contain the $file, $line, and $text tags, which +# will be replaced by the file and line number from which the warning originated +# and the warning text. Optionally the format may contain $version, which will +# be replaced by the version of the file (if it could be obtained via +# FILE_VERSION_FILTER) +# The default value is: $file:$line: $text. + +WARN_FORMAT = "WARNING: $file:$line: $text" + +# The WARN_LOGFILE tag can be used to specify a file to which warning and error +# messages should be written. If left blank the output is written to standard +# error (stderr). + +WARN_LOGFILE = + +#--------------------------------------------------------------------------- +# Configuration options related to the input files +#--------------------------------------------------------------------------- + +# The INPUT tag is used to specify the files and/or directories that contain +# documented source files. You may enter file names like myfile.cpp or +# directories like /usr/src/myproject. Separate the files or directories with +# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING +# Note: If this tag is empty the current directory is searched. + +INPUT = *#*#SRC#*#* + +# This tag can be used to specify the character encoding of the source files +# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses +# libiconv (or the iconv built into libc) for the transcoding. See the libiconv +# documentation (see: http://www.gnu.org/software/libiconv) for the list of +# possible encodings. +# The default value is: UTF-8. + +INPUT_ENCODING = UTF-8 + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and +# *.h) to filter out the source-files in the directories. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# read by doxygen. +# +# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, +# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, +# *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, +# *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, +# *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf and *.qsf. + +FILE_PATTERNS = *.h \ + *.hh \ + *.hxx \ + *.hpp \ + *.h++ \ + +# The RECURSIVE tag can be used to specify whether or not subdirectories should +# be searched for input files as well. +# The default value is: NO. + +RECURSIVE = YES + +# The EXCLUDE tag can be used to specify files and/or directories that should be +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. +# +# Note that relative paths are relative to the directory from which doxygen is +# run. + +EXCLUDE = + +# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or +# directories that are symbolic links (a Unix file system feature) are excluded +# from the input. +# The default value is: NO. + +EXCLUDE_SYMLINKS = NO + +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories for example use the pattern */test/* + +EXCLUDE_PATTERNS = + +# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names +# (namespaces, classes, functions, etc.) that should be excluded from the +# output. The symbol name can be a fully qualified name, a word, or if the +# wildcard * is used, a substring. Examples: ANamespace, AClass, +# AClass::ANamespace, ANamespace::*Test +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories use the pattern */test/* + +EXCLUDE_SYMBOLS = + +# The EXAMPLE_PATH tag can be used to specify one or more files or directories +# that contain example code fragments that are included (see the \include +# command). + +EXAMPLE_PATH = + +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and +# *.h) to filter out the source-files in the directories. If left blank all +# files are included. + +EXAMPLE_PATTERNS = * + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude commands +# irrespective of the value of the RECURSIVE tag. +# The default value is: NO. + +EXAMPLE_RECURSIVE = NO + +# The IMAGE_PATH tag can be used to specify one or more files or directories +# that contain images that are to be included in the documentation (see the +# \image command). + +IMAGE_PATH = + +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command: +# +# <filter> <input-file> +# +# where <filter> is the value of the INPUT_FILTER tag, and <input-file> is the +# name of an input file. Doxygen will then use the output that the filter +# program writes to standard output. If FILTER_PATTERNS is specified, this tag +# will be ignored. +# +# Note that the filter must not add or remove lines; it is applied before the +# code is scanned, but not when the output code is generated. If lines are added +# or removed, the anchors will not be placed correctly. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# properly processed by doxygen. + +INPUT_FILTER = + +# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern +# basis. Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. The filters are a list of the form: pattern=filter +# (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how +# filters are used. If the FILTER_PATTERNS tag is empty or if none of the +# patterns match the file name, INPUT_FILTER is applied. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# properly processed by doxygen. + +FILTER_PATTERNS = + +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER) will also be used to filter the input files that are used for +# producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES). +# The default value is: NO. + +FILTER_SOURCE_FILES = NO + +# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file +# pattern. A pattern will override the setting for FILTER_PATTERN (if any) and +# it is also possible to disable source filtering for a specific pattern using +# *.ext= (so without naming a filter). +# This tag requires that the tag FILTER_SOURCE_FILES is set to YES. + +FILTER_SOURCE_PATTERNS = + +# If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that +# is part of the input, its contents will be placed on the main page +# (index.html). This can be useful if you have a project on for instance GitHub +# and want to reuse the introduction page also for the doxygen output. + +USE_MDFILE_AS_MAINPAGE = + +#--------------------------------------------------------------------------- +# Configuration options related to source browsing +#--------------------------------------------------------------------------- + +# If the SOURCE_BROWSER tag is set to YES then a list of source files will be +# generated. Documented entities will be cross-referenced with these sources. +# +# Note: To get rid of all source code in the generated output, make sure that +# also VERBATIM_HEADERS is set to NO. +# The default value is: NO. + +SOURCE_BROWSER = NO + +# Setting the INLINE_SOURCES tag to YES will include the body of functions, +# classes and enums directly into the documentation. +# The default value is: NO. + +INLINE_SOURCES = NO + +# Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any +# special comment blocks from generated source code fragments. Normal C, C++ and +# Fortran comments will always remain visible. +# The default value is: YES. + +STRIP_CODE_COMMENTS = YES + +# If the REFERENCED_BY_RELATION tag is set to YES then for each documented +# function all documented functions referencing it will be listed. +# The default value is: NO. + +REFERENCED_BY_RELATION = NO + +# If the REFERENCES_RELATION tag is set to YES then for each documented function +# all documented entities called/used by that function will be listed. +# The default value is: NO. + +REFERENCES_RELATION = NO + +# If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set +# to YES then the hyperlinks from functions in REFERENCES_RELATION and +# REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will +# link to the documentation. +# The default value is: YES. + +REFERENCES_LINK_SOURCE = YES + +# If SOURCE_TOOLTIPS is enabled (the default) then hovering a hyperlink in the +# source code will show a tooltip with additional information such as prototype, +# brief description and links to the definition and documentation. Since this +# will make the HTML file larger and loading of large files a bit slower, you +# can opt to disable this feature. +# The default value is: YES. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + +SOURCE_TOOLTIPS = YES + +# If the USE_HTAGS tag is set to YES then the references to source code will +# point to the HTML generated by the htags(1) tool instead of doxygen built-in +# source browser. The htags tool is part of GNU's global source tagging system +# (see http://www.gnu.org/software/global/global.html). You will need version +# 4.8.6 or higher. +# +# To use it do the following: +# - Install the latest version of global +# - Enable SOURCE_BROWSER and USE_HTAGS in the config file +# - Make sure the INPUT points to the root of the source tree +# - Run doxygen as normal +# +# Doxygen will invoke htags (and that will in turn invoke gtags), so these +# tools must be available from the command line (i.e. in the search path). +# +# The result: instead of the source browser generated by doxygen, the links to +# source code will now point to the output of htags. +# The default value is: NO. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + +USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a +# verbatim copy of the header file for each class for which an include is +# specified. Set to NO to disable this. +# See also: Section \class. +# The default value is: YES. + +VERBATIM_HEADERS = YES + +# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the +# clang parser (see: http://clang.llvm.org/) for more accurate parsing at the +# cost of reduced performance. This can be particularly helpful with template +# rich C++ code for which doxygen's built-in parser lacks the necessary type +# information. +# Note: The availability of this option depends on whether or not doxygen was +# generated with the -Duse-libclang=ON option for CMake. +# The default value is: NO. + +CLANG_ASSISTED_PARSING = NO + +# If clang assisted parsing is enabled you can provide the compiler with command +# line options that you would normally use when invoking the compiler. Note that +# the include paths will already be set by doxygen for the files and directories +# specified with INPUT and INCLUDE_PATH. +# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. + +CLANG_OPTIONS = + +#--------------------------------------------------------------------------- +# Configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- + +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index of all +# compounds will be generated. Enable this if the project contains a lot of +# classes, structs, unions or interfaces. +# The default value is: YES. + +ALPHABETICAL_INDEX = YES + +# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in +# which the alphabetical index list will be split. +# Minimum value: 1, maximum value: 20, default value: 5. +# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. + +# COLS_IN_ALPHA_INDEX = 5 **OBSOLETE** + +# In case all classes in a project start with a common prefix, all classes will +# be put under the same header in the alphabetical index. The IGNORE_PREFIX tag +# can be used to specify a prefix (or a list of prefixes) that should be ignored +# while generating the index headers. +# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. + +IGNORE_PREFIX = + +#--------------------------------------------------------------------------- +# Configuration options related to the HTML output +#--------------------------------------------------------------------------- + +# If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output +# The default value is: YES. + +GENERATE_HTML = YES + +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: html. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_OUTPUT = doxygen_html + +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each +# generated HTML page (for example: .htm, .php, .asp). +# The default value is: .html. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_FILE_EXTENSION = .html + +# The HTML_HEADER tag can be used to specify a user-defined HTML header file for +# each generated HTML page. If the tag is left blank doxygen will generate a +# standard header. +# +# To get valid HTML the header file that includes any scripts and style sheets +# that doxygen needs, which is dependent on the configuration options used (e.g. +# the setting GENERATE_TREEVIEW). It is highly recommended to start with a +# default header using +# doxygen -w html new_header.html new_footer.html new_stylesheet.css +# YourConfigFile +# and then modify the file new_header.html. See also section "Doxygen usage" +# for information on how to generate the default header that doxygen normally +# uses. +# Note: The header is subject to change so you typically have to regenerate the +# default header when upgrading to a newer version of doxygen. For a description +# of the possible markers and block names see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_HEADER = + +# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each +# generated HTML page. If the tag is left blank doxygen will generate a standard +# footer. See HTML_HEADER for more information on how to generate a default +# footer and what special commands can be used inside the footer. See also +# section "Doxygen usage" for information on how to generate the default footer +# that doxygen normally uses. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_FOOTER = + +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style +# sheet that is used by each HTML page. It can be used to fine-tune the look of +# the HTML output. If left blank doxygen will generate a default style sheet. +# See also section "Doxygen usage" for information on how to generate the style +# sheet that doxygen normally uses. +# Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as +# it is more robust and this tag (HTML_STYLESHEET) will in the future become +# obsolete. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_STYLESHEET = + +# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined +# cascading style sheets that are included after the standard style sheets +# created by doxygen. Using this option one can overrule certain style aspects. +# This is preferred over using HTML_STYLESHEET since it does not replace the +# standard style sheet and is therefore more robust against future updates. +# Doxygen will copy the style sheet files to the output directory. +# Note: The order of the extra style sheet files is of importance (e.g. the last +# style sheet in the list overrules the setting of the previous ones in the +# list). For an example see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_STYLESHEET = + +# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the HTML output directory. Note +# that these files will be copied to the base HTML output directory. Use the +# $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these +# files. In the HTML_STYLESHEET file, use the file name only. Also note that the +# files will be copied as-is; there are no commands or markers available. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_FILES = + +# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen +# will adjust the colors in the style sheet and background images according to +# this color. Hue is specified as an angle on a colorwheel, see +# http://en.wikipedia.org/wiki/Hue for more information. For instance the value +# 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 +# purple, and 360 is red again. +# Minimum value: 0, maximum value: 359, default value: 220. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_HUE = 220 + +# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors +# in the HTML output. For a value of 0 the output will use grayscales only. A +# value of 255 will produce the most vivid colors. +# Minimum value: 0, maximum value: 255, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_SAT = 100 + +# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the +# luminance component of the colors in the HTML output. Values below 100 +# gradually make the output lighter, whereas values above 100 make the output +# darker. The value divided by 100 is the actual gamma applied, so 80 represents +# a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not +# change the gamma. +# Minimum value: 40, maximum value: 240, default value: 80. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_GAMMA = 80 + +# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML +# page will contain the date and time when the page was generated. Setting this +# to YES can help to show when doxygen was last run and thus if the +# documentation is up to date. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_TIMESTAMP = NO + +# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML +# documentation will contain sections that can be hidden and shown after the +# page has loaded. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_DYNAMIC_SECTIONS = NO + +# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries +# shown in the various tree structured indices initially; the user can expand +# and collapse entries dynamically later on. Doxygen will expand the tree to +# such a level that at most the specified number of entries are visible (unless +# a fully collapsed tree already exceeds this amount). So setting the number of +# entries 1 will produce a full collapsed tree by default. 0 is a special value +# representing an infinite number of entries and will result in a full expanded +# tree by default. +# Minimum value: 0, maximum value: 9999, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_INDEX_NUM_ENTRIES = 100 + +# If the GENERATE_DOCSET tag is set to YES, additional index files will be +# generated that can be used as input for Apple's Xcode 3 integrated development +# environment (see: http://developer.apple.com/tools/xcode/), introduced with +# OSX 10.5 (Leopard). To create a documentation set, doxygen will generate a +# Makefile in the HTML output directory. Running make will produce the docset in +# that directory and running make install will install the docset in +# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at +# startup. See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html +# for more information. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_DOCSET = NO + +# This tag determines the name of the docset feed. A documentation feed provides +# an umbrella under which multiple documentation sets from a single provider +# (such as a company or product suite) can be grouped. +# The default value is: Doxygen generated docs. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_FEEDNAME = "Doxygen generated docs" + +# This tag specifies a string that should uniquely identify the documentation +# set bundle. This should be a reverse domain-name style string, e.g. +# com.mycompany.MyDocSet. Doxygen will append .docset to the name. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_BUNDLE_ID = org.doxygen.Project + +# The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify +# the documentation publisher. This should be a reverse domain-name style +# string, e.g. com.mycompany.MyDocSet.documentation. +# The default value is: org.doxygen.Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_PUBLISHER_ID = org.doxygen.Publisher + +# The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher. +# The default value is: Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_PUBLISHER_NAME = Publisher + +# If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three +# additional HTML index files: index.hhp, index.hhc, and index.hhk. The +# index.hhp is a project file that can be read by Microsoft's HTML Help Workshop +# (see: http://www.microsoft.com/en-us/download/details.aspx?id=21138) on +# Windows. +# +# The HTML Help Workshop contains a compiler that can convert all HTML output +# generated by doxygen into a single compiled HTML file (.chm). Compiled HTML +# files are now used as the Windows 98 help format, and will replace the old +# Windows help format (.hlp) on all Windows platforms in the future. Compressed +# HTML files also contain an index, a table of contents, and you can search for +# words in the documentation. The HTML workshop also contains a viewer for +# compressed HTML files. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_HTMLHELP = NO + +# The CHM_FILE tag can be used to specify the file name of the resulting .chm +# file. You can add a path in front of the file if the result should not be +# written to the html output directory. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +CHM_FILE = + +# The HHC_LOCATION tag can be used to specify the location (absolute path +# including file name) of the HTML help compiler (hhc.exe). If non-empty, +# doxygen will try to run the HTML help compiler on the generated index.hhp. +# The file has to be specified with full path. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +HHC_LOCATION = + +# The GENERATE_CHI flag controls if a separate .chi index file is generated +# (YES) or that it should be included in the master .chm file (NO). +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +GENERATE_CHI = NO + +# The CHM_INDEX_ENCODING is used to encode HtmlHelp index (hhk), content (hhc) +# and project file content. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +CHM_INDEX_ENCODING = + +# The BINARY_TOC flag controls whether a binary table of contents is generated +# (YES) or a normal table of contents (NO) in the .chm file. Furthermore it +# enables the Previous and Next buttons. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +BINARY_TOC = NO + +# The TOC_EXPAND flag can be set to YES to add extra items for group members to +# the table of contents of the HTML help documentation and to the tree view. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +TOC_EXPAND = NO + +# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and +# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that +# can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help +# (.qch) of the generated HTML documentation. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_QHP = NO + +# If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify +# the file name of the resulting .qch file. The path specified is relative to +# the HTML output folder. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QCH_FILE = + +# The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help +# Project output. For more information please see Qt Help Project / Namespace +# (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace). +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_NAMESPACE = org.doxygen.Project + +# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt +# Help Project output. For more information please see Qt Help Project / Virtual +# Folders (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#virtual- +# folders). +# The default value is: doc. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_VIRTUAL_FOLDER = doc + +# If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom +# filter to add. For more information please see Qt Help Project / Custom +# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- +# filters). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_CUST_FILTER_NAME = + +# The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the +# custom filter to add. For more information please see Qt Help Project / Custom +# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- +# filters). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_CUST_FILTER_ATTRS = + +# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this +# project's filter section matches. Qt Help Project / Filter Attributes (see: +# http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_SECT_FILTER_ATTRS = + +# The QHG_LOCATION tag can be used to specify the location of Qt's +# qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the +# generated .qhp file. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHG_LOCATION = + +# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be +# generated, together with the HTML files, they form an Eclipse help plugin. To +# install this plugin and make it available under the help contents menu in +# Eclipse, the contents of the directory containing the HTML and XML files needs +# to be copied into the plugins directory of eclipse. The name of the directory +# within the plugins directory should be the same as the ECLIPSE_DOC_ID value. +# After copying Eclipse needs to be restarted before the help appears. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_ECLIPSEHELP = NO + +# A unique identifier for the Eclipse help plugin. When installing the plugin +# the directory name containing the HTML and XML files should also have this +# name. Each documentation set should have its own identifier. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES. + +ECLIPSE_DOC_ID = org.doxygen.Project + +# If you want full control over the layout of the generated HTML pages it might +# be necessary to disable the index and replace it with your own. The +# DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top +# of each HTML page. A value of NO enables the index and the value YES disables +# it. Since the tabs in the index contain the same information as the navigation +# tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +DISABLE_INDEX = NO + +# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index +# structure should be generated to display hierarchical information. If the tag +# value is set to YES, a side panel will be generated containing a tree-like +# index structure (just like the one that is generated for HTML Help). For this +# to work a browser that supports JavaScript, DHTML, CSS and frames is required +# (i.e. any modern browser). Windows users are probably better off using the +# HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can +# further fine-tune the look of the index. As an example, the default style +# sheet generated by doxygen has an example that shows how to put an image at +# the root of the tree instead of the PROJECT_NAME. Since the tree basically has +# the same information as the tab index, you could consider setting +# DISABLE_INDEX to YES when enabling this option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_TREEVIEW = YES + +# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that +# doxygen will group on one line in the generated HTML documentation. +# +# Note that a value of 0 will completely suppress the enum values from appearing +# in the overview section. +# Minimum value: 0, maximum value: 20, default value: 4. +# This tag requires that the tag GENERATE_HTML is set to YES. + +ENUM_VALUES_PER_LINE = 4 + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used +# to set the initial width (in pixels) of the frame in which the tree is shown. +# Minimum value: 0, maximum value: 1500, default value: 250. +# This tag requires that the tag GENERATE_HTML is set to YES. + +TREEVIEW_WIDTH = 250 + +# If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to +# external symbols imported via tag files in a separate window. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +EXT_LINKS_IN_WINDOW = NO + +# Use this tag to change the font size of LaTeX formulas included as images in +# the HTML documentation. When you change the font size after a successful +# doxygen run you need to manually remove any form_*.png images from the HTML +# output directory to force them to be regenerated. +# Minimum value: 8, maximum value: 50, default value: 10. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FORMULA_FONTSIZE = 10 + +# Use the FORMULA_TRANPARENT tag to determine whether or not the images +# generated for formulas are transparent PNGs. Transparent PNGs are not +# supported properly for IE 6.0, but are supported on all modern browsers. +# +# Note that when changing this option you need to delete any form_*.png files in +# the HTML output directory before the changes have effect. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +# FORMULA_TRANSPARENT = YES **OBSOLETE** + +# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see +# http://www.mathjax.org) which uses client side Javascript for the rendering +# instead of using pre-rendered bitmaps. Use this if you do not have LaTeX +# installed or if you want to formulas look prettier in the HTML output. When +# enabled you may also need to install MathJax separately and configure the path +# to it using the MATHJAX_RELPATH option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +USE_MATHJAX = NO + +# When MathJax is enabled you can set the default output format to be used for +# the MathJax output. See the MathJax site (see: +# http://docs.mathjax.org/en/latest/output.html) for more details. +# Possible values are: HTML-CSS (which is slower, but has the best +# compatibility), NativeMML (i.e. MathML) and SVG. +# The default value is: HTML-CSS. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_FORMAT = HTML-CSS + +# When MathJax is enabled you need to specify the location relative to the HTML +# output directory using the MATHJAX_RELPATH option. The destination directory +# should contain the MathJax.js script. For instance, if the mathjax directory +# is located at the same level as the HTML output directory, then +# MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax +# Content Delivery Network so you can quickly see the result without installing +# MathJax. However, it is strongly recommended to install a local copy of +# MathJax from http://www.mathjax.org before deployment. +# The default value is: http://cdn.mathjax.org/mathjax/latest. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest + +# The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax +# extension names that should be enabled during MathJax rendering. For example +# MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_EXTENSIONS = + +# The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces +# of code that will be used on startup of the MathJax code. See the MathJax site +# (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an +# example see the documentation. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_CODEFILE = + +# When the SEARCHENGINE tag is enabled doxygen will generate a search box for +# the HTML output. The underlying search engine uses javascript and DHTML and +# should work on any modern browser. Note that when using HTML help +# (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET) +# there is already a search function so this one should typically be disabled. +# For large projects the javascript based search engine can be slow, then +# enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to +# search using the keyboard; to jump to the search box use <access key> + S +# (what the <access key> is depends on the OS and browser, but it is typically +# <CTRL>, <ALT>/<option>, or both). Inside the search box use the <cursor down +# key> to jump into the search results window, the results can be navigated +# using the <cursor keys>. Press <Enter> to select an item or <escape> to cancel +# the search. The filter options can be selected when the cursor is inside the +# search box by pressing <Shift>+<cursor down>. Also here use the <cursor keys> +# to select a filter and <Enter> or <escape> to activate or cancel the filter +# option. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +SEARCHENGINE = YES + +# When the SERVER_BASED_SEARCH tag is enabled the search engine will be +# implemented using a web server instead of a web client using Javascript. There +# are two flavors of web server based searching depending on the EXTERNAL_SEARCH +# setting. When disabled, doxygen will generate a PHP script for searching and +# an index file used by the script. When EXTERNAL_SEARCH is enabled the indexing +# and searching needs to be provided by external tools. See the section +# "External Indexing and Searching" for details. +# The default value is: NO. +# This tag requires that the tag SEARCHENGINE is set to YES. + +SERVER_BASED_SEARCH = NO + +# When EXTERNAL_SEARCH tag is enabled doxygen will no longer generate the PHP +# script for searching. Instead the search results are written to an XML file +# which needs to be processed by an external indexer. Doxygen will invoke an +# external search engine pointed to by the SEARCHENGINE_URL option to obtain the +# search results. +# +# Doxygen ships with an example indexer (doxyindexer) and search engine +# (doxysearch.cgi) which are based on the open source search engine library +# Xapian (see: http://xapian.org/). +# +# See the section "External Indexing and Searching" for details. +# The default value is: NO. +# This tag requires that the tag SEARCHENGINE is set to YES. + +EXTERNAL_SEARCH = NO + +# The SEARCHENGINE_URL should point to a search engine hosted by a web server +# which will return the search results when EXTERNAL_SEARCH is enabled. +# +# Doxygen ships with an example indexer (doxyindexer) and search engine +# (doxysearch.cgi) which are based on the open source search engine library +# Xapian (see: http://xapian.org/). See the section "External Indexing and +# Searching" for details. +# This tag requires that the tag SEARCHENGINE is set to YES. + +SEARCHENGINE_URL = + +# When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the unindexed +# search data is written to a file for indexing by an external tool. With the +# SEARCHDATA_FILE tag the name of this file can be specified. +# The default file is: searchdata.xml. +# This tag requires that the tag SEARCHENGINE is set to YES. + +SEARCHDATA_FILE = searchdata.xml + +# When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the +# EXTERNAL_SEARCH_ID tag can be used as an identifier for the project. This is +# useful in combination with EXTRA_SEARCH_MAPPINGS to search through multiple +# projects and redirect the results back to the right project. +# This tag requires that the tag SEARCHENGINE is set to YES. + +EXTERNAL_SEARCH_ID = + +# The EXTRA_SEARCH_MAPPINGS tag can be used to enable searching through doxygen +# projects other than the one defined by this configuration file, but that are +# all added to the same external search index. Each project needs to have a +# unique id set via EXTERNAL_SEARCH_ID. The search mapping then maps the id of +# to a relative location where the documentation can be found. The format is: +# EXTRA_SEARCH_MAPPINGS = tagname1=loc1 tagname2=loc2 ... +# This tag requires that the tag SEARCHENGINE is set to YES. + +EXTRA_SEARCH_MAPPINGS = + +#--------------------------------------------------------------------------- +# Configuration options related to the LaTeX output +#--------------------------------------------------------------------------- + +# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output. +# The default value is: YES. + +GENERATE_LATEX = NO + +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: latex. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_OUTPUT = latex + +# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be +# invoked. +# +# Note that when enabling USE_PDFLATEX this option is only used for generating +# bitmaps for formulas in the HTML output, but not in the Makefile that is +# written to the output directory. +# The default file is: latex. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_CMD_NAME = latex + +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to generate +# index for LaTeX. +# The default file is: makeindex. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +MAKEINDEX_CMD_NAME = makeindex + +# If the COMPACT_LATEX tag is set to YES, doxygen generates more compact LaTeX +# documents. This may be useful for small projects and may help to save some +# trees in general. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +COMPACT_LATEX = NO + +# The PAPER_TYPE tag can be used to set the paper type that is used by the +# printer. +# Possible values are: a4 (210 x 297 mm), letter (8.5 x 11 inches), legal (8.5 x +# 14 inches) and executive (7.25 x 10.5 inches). +# The default value is: a4. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +PAPER_TYPE = a4 + +# The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names +# that should be included in the LaTeX output. The package can be specified just +# by its name or with the correct syntax as to be used with the LaTeX +# \usepackage command. To get the times font for instance you can specify : +# EXTRA_PACKAGES=times or EXTRA_PACKAGES={times} +# To use the option intlimits with the amsmath package you can specify: +# EXTRA_PACKAGES=[intlimits]{amsmath} +# If left blank no extra packages will be included. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +EXTRA_PACKAGES = + +# The LATEX_HEADER tag can be used to specify a personal LaTeX header for the +# generated LaTeX document. The header should contain everything until the first +# chapter. If it is left blank doxygen will generate a standard header. See +# section "Doxygen usage" for information on how to let doxygen write the +# default header to a separate file. +# +# Note: Only use a user-defined header if you know what you are doing! The +# following commands have a special meaning inside the header: $title, +# $datetime, $date, $doxygenversion, $projectname, $projectnumber, +# $projectbrief, $projectlogo. Doxygen will replace $title with the empty +# string, for the replacement values of the other commands the user is referred +# to HTML_HEADER. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_HEADER = + +# The LATEX_FOOTER tag can be used to specify a personal LaTeX footer for the +# generated LaTeX document. The footer should contain everything after the last +# chapter. If it is left blank doxygen will generate a standard footer. See +# LATEX_HEADER for more information on how to generate a default footer and what +# special commands can be used inside the footer. +# +# Note: Only use a user-defined footer if you know what you are doing! +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_FOOTER = + +# The LATEX_EXTRA_STYLESHEET tag can be used to specify additional user-defined +# LaTeX style sheets that are included after the standard style sheets created +# by doxygen. Using this option one can overrule certain style aspects. Doxygen +# will copy the style sheet files to the output directory. +# Note: The order of the extra style sheet files is of importance (e.g. the last +# style sheet in the list overrules the setting of the previous ones in the +# list). +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_EXTRA_STYLESHEET = + +# The LATEX_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the LATEX_OUTPUT output +# directory. Note that the files will be copied as-is; there are no commands or +# markers available. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_EXTRA_FILES = + +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated is +# prepared for conversion to PDF (using ps2pdf or pdflatex). The PDF file will +# contain links (just like the HTML output) instead of page references. This +# makes the output suitable for online browsing using a PDF viewer. +# The default value is: YES. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +PDF_HYPERLINKS = YES + +# If the USE_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate +# the PDF file directly from the LaTeX files. Set this option to YES, to get a +# higher quality PDF documentation. +# The default value is: YES. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +USE_PDFLATEX = YES + +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode +# command to the generated LaTeX files. This will instruct LaTeX to keep running +# if errors occur, instead of asking the user for help. This option is also used +# when generating formulas in HTML. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_BATCHMODE = NO + +# If the LATEX_HIDE_INDICES tag is set to YES then doxygen will not include the +# index chapters (such as File Index, Compound Index, etc.) in the output. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_HIDE_INDICES = NO + +# If the LATEX_SOURCE_CODE tag is set to YES then doxygen will include source +# code with syntax highlighting in the LaTeX output. +# +# Note that which sources are shown also depends on other settings such as +# SOURCE_BROWSER. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +# LATEX_SOURCE_CODE = NO **OBSOLETE** + +# The LATEX_BIB_STYLE tag can be used to specify the style to use for the +# bibliography, e.g. plainnat, or ieeetr. See +# http://en.wikipedia.org/wiki/BibTeX and \cite for more info. +# The default value is: plain. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_BIB_STYLE = plain + +# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated +# page will contain the date and time when the page was generated. Setting this +# to NO can help when comparing the output of multiple runs. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_TIMESTAMP = NO + +#--------------------------------------------------------------------------- +# Configuration options related to the RTF output +#--------------------------------------------------------------------------- + +# If the GENERATE_RTF tag is set to YES, doxygen will generate RTF output. The +# RTF output is optimized for Word 97 and may not look too pretty with other RTF +# readers/editors. +# The default value is: NO. + +GENERATE_RTF = NO + +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: rtf. +# This tag requires that the tag GENERATE_RTF is set to YES. + +RTF_OUTPUT = rtf + +# If the COMPACT_RTF tag is set to YES, doxygen generates more compact RTF +# documents. This may be useful for small projects and may help to save some +# trees in general. +# The default value is: NO. +# This tag requires that the tag GENERATE_RTF is set to YES. + +COMPACT_RTF = NO + +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated will +# contain hyperlink fields. The RTF file will contain links (just like the HTML +# output) instead of page references. This makes the output suitable for online +# browsing using Word or some other Word compatible readers that support those +# fields. +# +# Note: WordPad (write) and others do not support links. +# The default value is: NO. +# This tag requires that the tag GENERATE_RTF is set to YES. + +RTF_HYPERLINKS = NO + +# Load stylesheet definitions from file. Syntax is similar to doxygen's config +# file, i.e. a series of assignments. You only have to provide replacements, +# missing definitions are set to their default value. +# +# See also section "Doxygen usage" for information on how to generate the +# default style sheet that doxygen normally uses. +# This tag requires that the tag GENERATE_RTF is set to YES. + +RTF_STYLESHEET_FILE = + +# Set optional variables used in the generation of an RTF document. Syntax is +# similar to doxygen's config file. A template extensions file can be generated +# using doxygen -e rtf extensionFile. +# This tag requires that the tag GENERATE_RTF is set to YES. + +RTF_EXTENSIONS_FILE = + +# If the RTF_SOURCE_CODE tag is set to YES then doxygen will include source code +# with syntax highlighting in the RTF output. +# +# Note that which sources are shown also depends on other settings such as +# SOURCE_BROWSER. +# The default value is: NO. +# This tag requires that the tag GENERATE_RTF is set to YES. + +# RTF_SOURCE_CODE = NO **OBSOLETE** + +#--------------------------------------------------------------------------- +# Configuration options related to the man page output +#--------------------------------------------------------------------------- + +# If the GENERATE_MAN tag is set to YES, doxygen will generate man pages for +# classes and files. +# The default value is: NO. + +GENERATE_MAN = NO + +# The MAN_OUTPUT tag is used to specify where the man pages will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. A directory man3 will be created inside the directory specified by +# MAN_OUTPUT. +# The default directory is: man. +# This tag requires that the tag GENERATE_MAN is set to YES. + +MAN_OUTPUT = man + +# The MAN_EXTENSION tag determines the extension that is added to the generated +# man pages. In case the manual section does not start with a number, the number +# 3 is prepended. The dot (.) at the beginning of the MAN_EXTENSION tag is +# optional. +# The default value is: .3. +# This tag requires that the tag GENERATE_MAN is set to YES. + +MAN_EXTENSION = .3 + +# The MAN_SUBDIR tag determines the name of the directory created within +# MAN_OUTPUT in which the man pages are placed. If defaults to man followed by +# MAN_EXTENSION with the initial . removed. +# This tag requires that the tag GENERATE_MAN is set to YES. + +MAN_SUBDIR = + +# If the MAN_LINKS tag is set to YES and doxygen generates man output, then it +# will generate one additional man file for each entity documented in the real +# man page(s). These additional files only source the real man page, but without +# them the man command would be unable to find the correct page. +# The default value is: NO. +# This tag requires that the tag GENERATE_MAN is set to YES. + +MAN_LINKS = NO + +#--------------------------------------------------------------------------- +# Configuration options related to the XML output +#--------------------------------------------------------------------------- + +# If the GENERATE_XML tag is set to YES, doxygen will generate an XML file that +# captures the structure of the code including all documentation. +# The default value is: NO. + +GENERATE_XML = YES + +# The XML_OUTPUT tag is used to specify where the XML pages will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: xml. +# This tag requires that the tag GENERATE_XML is set to YES. + +XML_OUTPUT = xml + +# If the XML_PROGRAMLISTING tag is set to YES, doxygen will dump the program +# listings (including syntax highlighting and cross-referencing information) to +# the XML output. Note that enabling this will significantly increase the size +# of the XML output. +# The default value is: YES. +# This tag requires that the tag GENERATE_XML is set to YES. + +XML_PROGRAMLISTING = YES + +#--------------------------------------------------------------------------- +# Configuration options related to the DOCBOOK output +#--------------------------------------------------------------------------- + +# If the GENERATE_DOCBOOK tag is set to YES, doxygen will generate Docbook files +# that can be used to generate PDF. +# The default value is: NO. + +GENERATE_DOCBOOK = NO + +# The DOCBOOK_OUTPUT tag is used to specify where the Docbook pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be put in +# front of it. +# The default directory is: docbook. +# This tag requires that the tag GENERATE_DOCBOOK is set to YES. + +DOCBOOK_OUTPUT = docbook + +# If the DOCBOOK_PROGRAMLISTING tag is set to YES, doxygen will include the +# program listings (including syntax highlighting and cross-referencing +# information) to the DOCBOOK output. Note that enabling this will significantly +# increase the size of the DOCBOOK output. +# The default value is: NO. +# This tag requires that the tag GENERATE_DOCBOOK is set to YES. + +# DOCBOOK_PROGRAMLISTING = NO **OBSOLETE** + +#--------------------------------------------------------------------------- +# Configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- + +# If the GENERATE_AUTOGEN_DEF tag is set to YES, doxygen will generate an +# AutoGen Definitions (see http://autogen.sf.net) file that captures the +# structure of the code including all documentation. Note that this feature is +# still experimental and incomplete at the moment. +# The default value is: NO. + +GENERATE_AUTOGEN_DEF = NO + +#--------------------------------------------------------------------------- +# Configuration options related to the Perl module output +#--------------------------------------------------------------------------- + +# If the GENERATE_PERLMOD tag is set to YES, doxygen will generate a Perl module +# file that captures the structure of the code including all documentation. +# +# Note that this feature is still experimental and incomplete at the moment. +# The default value is: NO. + +GENERATE_PERLMOD = NO + +# If the PERLMOD_LATEX tag is set to YES, doxygen will generate the necessary +# Makefile rules, Perl scripts and LaTeX code to be able to generate PDF and DVI +# output from the Perl module output. +# The default value is: NO. +# This tag requires that the tag GENERATE_PERLMOD is set to YES. + +PERLMOD_LATEX = NO + +# If the PERLMOD_PRETTY tag is set to YES, the Perl module output will be nicely +# formatted so it can be parsed by a human reader. This is useful if you want to +# understand what is going on. On the other hand, if this tag is set to NO, the +# size of the Perl module output will be much smaller and Perl will parse it +# just the same. +# The default value is: YES. +# This tag requires that the tag GENERATE_PERLMOD is set to YES. + +PERLMOD_PRETTY = YES + +# The names of the make variables in the generated doxyrules.make file are +# prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. This is useful +# so different doxyrules.make files included by the same Makefile don't +# overwrite each other's variables. +# This tag requires that the tag GENERATE_PERLMOD is set to YES. + +PERLMOD_MAKEVAR_PREFIX = + +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- + +# If the ENABLE_PREPROCESSING tag is set to YES, doxygen will evaluate all +# C-preprocessor directives found in the sources and include files. +# The default value is: YES. + +ENABLE_PREPROCESSING = YES + +# If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names +# in the source code. If set to NO, only conditional compilation will be +# performed. Macro expansion can be done in a controlled way by setting +# EXPAND_ONLY_PREDEF to YES. +# The default value is: NO. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + +MACRO_EXPANSION = YES + +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then +# the macro expansion is limited to the macros specified with the PREDEFINED and +# EXPAND_AS_DEFINED tags. +# The default value is: NO. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + +EXPAND_ONLY_PREDEF = NO + +# If the SEARCH_INCLUDES tag is set to YES, the include files in the +# INCLUDE_PATH will be searched if a #include is found. +# The default value is: YES. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + +SEARCH_INCLUDES = YES + +# The INCLUDE_PATH tag can be used to specify one or more directories that +# contain include files that are not input files but should be processed by the +# preprocessor. +# This tag requires that the tag SEARCH_INCLUDES is set to YES. + +INCLUDE_PATH = + +# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard +# patterns (like *.h and *.hpp) to filter out the header-files in the +# directories. If left blank, the patterns specified with FILE_PATTERNS will be +# used. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + +INCLUDE_FILE_PATTERNS = + +# The PREDEFINED tag can be used to specify one or more macro names that are +# defined before the preprocessor is started (similar to the -D option of e.g. +# gcc). The argument of the tag is a list of macros of the form: name or +# name=definition (no spaces). If the definition and the "=" are omitted, "=1" +# is assumed. To prevent a macro definition from being undefined via #undef or +# recursively expanded use the := operator instead of the = operator. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + +PREDEFINED = DOXYGEN + +# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this +# tag can be used to specify a list of macro names that should be expanded. The +# macro definition that is found in the sources will be used. Use the PREDEFINED +# tag if you want to use a different macro definition that overrules the +# definition found in the source code. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + +EXPAND_AS_DEFINED = + +# If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will +# remove all references to function-like macros that are alone on a line, have +# an all uppercase name, and do not end with a semicolon. Such function macros +# are typically used for boiler-plate code, and will confuse the parser if not +# removed. +# The default value is: YES. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + +SKIP_FUNCTION_MACROS = YES + +#--------------------------------------------------------------------------- +# Configuration options related to external references +#--------------------------------------------------------------------------- + +# The TAGFILES tag can be used to specify one or more tag files. For each tag +# file the location of the external documentation should be added. The format of +# a tag file without this location is as follows: +# TAGFILES = file1 file2 ... +# Adding location for the tag files is done as follows: +# TAGFILES = file1=loc1 "file2 = loc2" ... +# where loc1 and loc2 can be relative or absolute paths or URLs. See the +# section "Linking to external documentation" for more information about the use +# of tag files. +# Note: Each tag file must have a unique name (where the name does NOT include +# the path). If a tag file is not located in the directory in which doxygen is +# run, you must also specify the path to the tagfile here. + +TAGFILES = + +# When a file name is specified after GENERATE_TAGFILE, doxygen will create a +# tag file that is based on the input files it reads. See section "Linking to +# external documentation" for more information about the usage of tag files. + +GENERATE_TAGFILE = + +# If the ALLEXTERNALS tag is set to YES, all external class will be listed in +# the class index. If set to NO, only the inherited external classes will be +# listed. +# The default value is: NO. + +ALLEXTERNALS = NO + +# If the EXTERNAL_GROUPS tag is set to YES, all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will be +# listed. +# The default value is: YES. + +EXTERNAL_GROUPS = YES + +# If the EXTERNAL_PAGES tag is set to YES, all external pages will be listed in +# the related pages index. If set to NO, only the current project's pages will +# be listed. +# The default value is: YES. + +EXTERNAL_PAGES = YES + +# The PERL_PATH should be the absolute path and name of the perl script +# interpreter (i.e. the result of 'which perl'). +# The default file (with absolute path) is: /usr/bin/perl. + +# PERL_PATH = /usr/bin/perl **OBSOLETE** + +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- + +# If the CLASS_DIAGRAMS tag is set to YES, doxygen will generate a class diagram +# (in HTML and LaTeX) for classes with base or super classes. Setting the tag to +# NO turns the diagrams off. Note that this option also works with HAVE_DOT +# disabled, but it is recommended to install and use dot, since it yields more +# powerful graphs. +# The default value is: YES. + +# CLASS_DIAGRAMS = YES **OBSOLETE** + +# You can define message sequence charts within doxygen comments using the \msc +# command. Doxygen will then run the mscgen tool (see: +# http://www.mcternan.me.uk/mscgen/)) to produce the chart and insert it in the +# documentation. The MSCGEN_PATH tag allows you to specify the directory where +# the mscgen tool resides. If left empty the tool is assumed to be found in the +# default search path. + +# MSCGEN_PATH = **OBSOLETE** + +# You can include diagrams made with dia in doxygen documentation. Doxygen will +# then run dia to produce the diagram and insert it in the documentation. The +# DIA_PATH tag allows you to specify the directory where the dia binary resides. +# If left empty dia is assumed to be found in the default search path. + +DIA_PATH = + +# If set to YES the inheritance and collaboration graphs will hide inheritance +# and usage relations if the target is undocumented or is not a class. +# The default value is: YES. + +HIDE_UNDOC_RELATIONS = YES + +# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is +# available from the path. This tool is part of Graphviz (see: +# http://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent +# Bell Labs. The other options in this section have no effect if this option is +# set to NO +# The default value is: YES. + +HAVE_DOT = NO + +# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed +# to run in parallel. When set to 0 doxygen will base this on the number of +# processors available in the system. You can set it explicitly to a value +# larger than 0 to get control over the balance between CPU load and processing +# speed. +# Minimum value: 0, maximum value: 32, default value: 0. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_NUM_THREADS = 0 + +# When you want a differently looking font in the dot files that doxygen +# generates you can specify the font name using DOT_FONTNAME. You need to make +# sure dot is able to find the font, which can be done by putting it in a +# standard location or by setting the DOTFONTPATH environment variable or by +# setting DOT_FONTPATH to the directory containing the font. +# The default value is: Helvetica. +# This tag requires that the tag HAVE_DOT is set to YES. + +# DOT_FONTNAME = Helvetica **OBSOLETE** + +# The DOT_FONTSIZE tag can be used to set the size (in points) of the font of +# dot graphs. +# Minimum value: 4, maximum value: 24, default value: 10. +# This tag requires that the tag HAVE_DOT is set to YES. + +# DOT_FONTSIZE = 10 **OBSOLETE** + +# By default doxygen will tell dot to use the default font as specified with +# DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set +# the path where dot can find it using this tag. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_FONTPATH = + +# If the CLASS_GRAPH tag is set to YES then doxygen will generate a graph for +# each documented class showing the direct and indirect inheritance relations. +# Setting this tag to YES will force the CLASS_DIAGRAMS tag to NO. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +CLASS_GRAPH = YES + +# If the COLLABORATION_GRAPH tag is set to YES then doxygen will generate a +# graph for each documented class showing the direct and indirect implementation +# dependencies (inheritance, containment, and class references variables) of the +# class with other documented classes. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +COLLABORATION_GRAPH = YES + +# If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for +# groups, showing the direct groups dependencies. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +GROUP_GRAPHS = YES + +# If the UML_LOOK tag is set to YES, doxygen will generate inheritance and +# collaboration diagrams in a style similar to the OMG's Unified Modeling +# Language. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +UML_LOOK = NO + +# If the UML_LOOK tag is enabled, the fields and methods are shown inside the +# class node. If there are many fields or methods and many nodes the graph may +# become too big to be useful. The UML_LIMIT_NUM_FIELDS threshold limits the +# number of items for each type to make the size more manageable. Set this to 0 +# for no limit. Note that the threshold may be exceeded by 50% before the limit +# is enforced. So when you set the threshold to 10, up to 15 fields may appear, +# but if the number exceeds 15, the total amount of fields shown is limited to +# 10. +# Minimum value: 0, maximum value: 100, default value: 10. +# This tag requires that the tag HAVE_DOT is set to YES. + +UML_LIMIT_NUM_FIELDS = 10 + +# If the TEMPLATE_RELATIONS tag is set to YES then the inheritance and +# collaboration graphs will show the relations between templates and their +# instances. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +TEMPLATE_RELATIONS = NO + +# If the INCLUDE_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are set to +# YES then doxygen will generate a graph for each documented file showing the +# direct and indirect include dependencies of the file with other documented +# files. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +INCLUDE_GRAPH = YES + +# If the INCLUDED_BY_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are +# set to YES then doxygen will generate a graph for each documented file showing +# the direct and indirect include dependencies of the file with other documented +# files. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +INCLUDED_BY_GRAPH = YES + +# If the CALL_GRAPH tag is set to YES then doxygen will generate a call +# dependency graph for every global function or class method. +# +# Note that enabling this option will significantly increase the time of a run. +# So in most cases it will be better to enable call graphs for selected +# functions only using the \callgraph command. Disabling a call graph can be +# accomplished by means of the command \hidecallgraph. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +CALL_GRAPH = NO + +# If the CALLER_GRAPH tag is set to YES then doxygen will generate a caller +# dependency graph for every global function or class method. +# +# Note that enabling this option will significantly increase the time of a run. +# So in most cases it will be better to enable caller graphs for selected +# functions only using the \callergraph command. Disabling a caller graph can be +# accomplished by means of the command \hidecallergraph. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +CALLER_GRAPH = NO + +# If the GRAPHICAL_HIERARCHY tag is set to YES then doxygen will graphical +# hierarchy of all classes instead of a textual one. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +GRAPHICAL_HIERARCHY = YES + +# If the DIRECTORY_GRAPH tag is set to YES then doxygen will show the +# dependencies a directory has on other directories in a graphical way. The +# dependency relations are determined by the #include relations between the +# files in the directories. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +DIRECTORY_GRAPH = YES + +# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images +# generated by dot. For an explanation of the image formats see the section +# output formats in the documentation of the dot tool (Graphviz (see: +# http://www.graphviz.org/)). +# Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order +# to make the SVG files visible in IE 9+ (other browsers do not have this +# requirement). +# Possible values are: png, png:cairo, png:cairo:cairo, png:cairo:gd, png:gd, +# png:gd:gd, jpg, jpg:cairo, jpg:cairo:gd, jpg:gd, jpg:gd:gd, gif, gif:cairo, +# gif:cairo:gd, gif:gd, gif:gd:gd, svg, png:gd, png:gd:gd, png:cairo, +# png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus and +# png:gdiplus:gdiplus. +# The default value is: png. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_IMAGE_FORMAT = png + +# If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to +# enable generation of interactive SVG images that allow zooming and panning. +# +# Note that this requires a modern browser other than Internet Explorer. Tested +# and working are Firefox, Chrome, Safari, and Opera. +# Note: For IE 9+ you need to set HTML_FILE_EXTENSION to xhtml in order to make +# the SVG files visible. Older versions of IE do not have SVG support. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +INTERACTIVE_SVG = NO + +# The DOT_PATH tag can be used to specify the path where the dot tool can be +# found. If left blank, it is assumed the dot tool can be found in the path. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_PATH = + +# The DOTFILE_DIRS tag can be used to specify one or more directories that +# contain dot files that are included in the documentation (see the \dotfile +# command). +# This tag requires that the tag HAVE_DOT is set to YES. + +DOTFILE_DIRS = + +# The MSCFILE_DIRS tag can be used to specify one or more directories that +# contain msc files that are included in the documentation (see the \mscfile +# command). + +MSCFILE_DIRS = + +# The DIAFILE_DIRS tag can be used to specify one or more directories that +# contain dia files that are included in the documentation (see the \diafile +# command). + +DIAFILE_DIRS = + +# When using plantuml, the PLANTUML_JAR_PATH tag should be used to specify the +# path where java can find the plantuml.jar file. If left blank, it is assumed +# PlantUML is not used or called during a preprocessing step. Doxygen will +# generate a warning when it encounters a \startuml command in this case and +# will not generate output for the diagram. + +PLANTUML_JAR_PATH = + +# When using plantuml, the PLANTUML_CFG_FILE tag can be used to specify a +# configuration file for plantuml. + +PLANTUML_CFG_FILE = + +# When using plantuml, the specified paths are searched for files specified by +# the !include statement in a plantuml block. + +PLANTUML_INCLUDE_PATH = + +# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of nodes +# that will be shown in the graph. If the number of nodes in a graph becomes +# larger than this value, doxygen will truncate the graph, which is visualized +# by representing a node as a red box. Note that doxygen if the number of direct +# children of the root node in a graph is already larger than +# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note that +# the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. +# Minimum value: 0, maximum value: 10000, default value: 50. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_GRAPH_MAX_NODES = 50 + +# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs +# generated by dot. A depth value of 3 means that only nodes reachable from the +# root by following a path via at most 3 edges will be shown. Nodes that lay +# further from the root node will be omitted. Note that setting this option to 1 +# or 2 may greatly reduce the computation time needed for large code bases. Also +# note that the size of a graph can be further restricted by +# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. +# Minimum value: 0, maximum value: 1000, default value: 0. +# This tag requires that the tag HAVE_DOT is set to YES. + +MAX_DOT_GRAPH_DEPTH = 0 + +# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent +# background. This is disabled by default, because dot on Windows does not seem +# to support this out of the box. +# +# Warning: Depending on the platform used, enabling this option may lead to +# badly anti-aliased labels on the edges of a graph (i.e. they become hard to +# read). +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +# DOT_TRANSPARENT = NO **OBSOLETE** + +# Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output +# files in one run (i.e. multiple -o and -T options on the command line). This +# makes dot run faster, but since only newer versions of dot (>1.8.10) support +# this, this feature is disabled by default. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_MULTI_TARGETS = NO + +# If the GENERATE_LEGEND tag is set to YES doxygen will generate a legend page +# explaining the meaning of the various boxes and arrows in the dot generated +# graphs. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +GENERATE_LEGEND = YES + +# If the DOT_CLEANUP tag is set to YES, doxygen will remove the intermediate dot +# files that are used to generate the various graphs. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_CLEANUP = YES diff --git a/docs/README_jp.md b/docs/README_jp.md deleted file mode 100644 index 86f6da697..000000000 --- a/docs/README_jp.md +++ /dev/null @@ -1,430 +0,0 @@ -<p align="right"><a href="../README.md">English</a> | <a href="./README_zh.md">中文</a> | <a href="./README_pt_BR.md">Português do Brasil</a> | <b>日本語</b></p> - - <br> -<p align="center"> - <img src="https://lvgl.io/assets/images/logo_lvgl.png"> -</p> - - <h1 align="center">Light and Versatile Graphics Library</h1> - <br> -<div align="center"> - <img src="https://github.com/kisvegabor/test/raw/master/smartwatch_demo.gif"> - - <img border="1px" src="https://lvgl.io/assets/images/lvgl_widgets_demo.gif"> -</div> -<br> -<p align="center"> -<a href="https://lvgl-io.translate.goog/?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja" title="Homepage of LVGL">Website </a></a> | -<a href="https://docs-lvgl-io.translate.goog/master/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja" title="Detailed documentation with 100+ examples">Docs</a> | -<a href="https://forum.lvgl.io" title="Get help and help others">Forum</a> :gb: | -<a href="https://lvgl-io.translate.goog/demos?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja" title="Demos running in your browser">Demos</a> | -<a href="https://lvgl-io.translate.goog/services?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja" title="Graphics design, UI implementation and consulting">Services</a> | -<a href="https://squareline.io/" title="UI Editor for LVGL">SquareLine Studio</a> :gb: -</p> -<br> - -## :ledger: Overview - -**実績**<br> -LVGL は、フリー＆オープンソースの組み込み用グラフィックスライブラリです。 -あらゆるMCU、MPU、ディスプレイタイプに対応しており、美しいUI(User Interface)を実現できます。 -ARM, STM32, NXP, Espressif, Nuvoton, Arduino, RT-Thread, Zephyr, NuttX, Adafruitなど、業界をリードするベンダーやプロジェクトによりサポートされています。 - -**機能豊富**<br> -モダンで美しいGUIを作成するための機能をすべて備えています。 -30以上の組み込みウィジェット、強力なスタイルシステム、WEB由来のレイアウトマネージャ、多くの言語をサポートする文字グラフィックシステムなどです。 -LVGL のシステム要件は、RAM 32KB、Flash 128KB、Cコンパイラ、フレームバッファ、1/10スクリーンサイズのレンダリング用バッファです。 - -**UIエディタ**<br> -SquareLine Studio は、LVGL用のプロフェッショナル＆リーズナブルなドラッグ＆ドロップ型のUIエディターです。 -Windows、Linux、MacOS で動作し、ウェブサイトへの登録なしで試すことができます。 - -**サービス**<br> -LVGL LLC では、グラフィックデザイン、UI実装、コンサルティングサービスに対する技術サポートが可能です。GUIプロジェクトの開発において何らかのサポートが必要な場合には、お気軽にお問い合わせください。 - - -## :rocket: 特徴 - -**フリー & 移植可能** - - 外部依存関係がなく、完全に移植可能な Cライブラリ。(C++互換) - - 任意の(RT)OS、任意のMCU・MPU用にコンパイル可能。 - - 電子ペーパー、OLEDディスプレイ、TFTディスプレイ、白黒ディスプレイ、モニターに対応。 [Porting Guide](https://docs-lvgl-io.translate.goog/master/porting/project.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) - - MITライセンスにより商用利用可能。 - - システム要件：RAM 32KB、Flash 128KB、フレームバッファ、レンダリング用に1/10以上のスクリーンサイズのバッファ。 - - OS、外部メモリ、GPUもサポート。 - -**ウィジェット、スタイル、レイアウトなど** - - 30以上の組み込み [ウィジェット](https://docs-lvgl-io.translate.goog/master/widgets/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja): ボタン、ラベル、スライダー、グラフ、キーボード、メーター、円弧、表など。 - - ウィジェットの任意の部分を任意の状態にカスタマイズ可能な豊富なスタイルプロパティを備えた柔軟な [スタイルシステム](https://docs-lvgl-io.translate.goog/master/overview/style.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja)。 - - [Flexbox](https://docs-lvgl-io.translate.goog/master/layouts/flex.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) および [グリッド](https://docs-lvgl-io.translate.goog/master/layouts/grid.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) 風のレイアウトエンジンにより、ウィジェットのサイズと位置を自動的に設定。 - - テキスト表示(UTF-8対応)は、中国語、日本語、韓国語、タイ語、ヒンディー語、アラビア語、ペルシア語をサポート。 - - ワードラッピング、カーニング、テキストスクロール、サブピクセルレンダリング、ピンイン-IME中国語入力、テキスト中の絵文字に対応。 - - アニメーション、アンチエイリアシング、不透明度、スムーズスクロール、シャドウ、画像変換などをサポートするレンダリングエンジン。 - - マウス、タッチパッド、キーパッド、キーボード、外部ボタン、エンコーダ等の [入力デバイス](https://docs-lvgl-io.translate.goog/master/porting/indev.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) をサポート。 - - [マルチディスプレイ](https://docs-lvgl-io.translate.goog/master/overview/display.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) 対応。 - -**Binding と Build をサポート** - - [Micropython Binding](https://blog-lvgl-io.translate.goog/2019-02-20/micropython-bindings?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) が LVGL API を公開。 - - カスタムビルドシステムは使用せず、プロジェクトの他のファイルをビルドするときに、LVGLをビルド可能。 - - Make と [CMake](https://docs-lvgl-io.translate.goog/master/get-started/platforms/cmake.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) が含まれており、すぐ使えるようにサポート。 - - [PCのシミュレータで開発したUIコード](https://docs-lvgl-io.translate.goog/master/get-started/platforms/pc-simulator.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) は、そのまま組込み用ハードウェアでも使用可能。 - - [Emscripten port](https://github.com/lvgl/lv_web_emscripten) :gb: によりC言語のUIコードをHTMLファイルに変換。 - -**ドキュメント, ツール, 技術サービス** - - [ドキュメント](https://docs-lvgl-io.translate.goog/master/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja)は[100以上の簡単なサンプルプログラム](https://github.com/lvgl/lvgl/tree/master/examples) :gb: 入り 。 - - [SquareLine Studio](https://squareline.io/) :gb: - UI開発をスピードアップおよび簡素化するためのプロフェッショナルで使いやすいUIエディターソフトウェア。 - - UI開発をよりシンプルかつ迅速にするための、ユーザーインターフェイスの設計、実装、コンサルティングなどの [技術サービス](https://lvgl-io.translate.goog/services?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja)。 - -## :package: パッケージ -LVGL は以下で利用可能です。 -- [Arduino library](https://docs-lvgl-io.translate.goog/master/get-started/platforms/arduino.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) -- [PlatformIO package](https://registry.platformio.org/libraries/lvgl/lvgl) :gb: -- [Zephyr library](https://docs-zephyrproject-org.translate.goog/latest/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) -- [ESP32 component](https://docs-lvgl-io.translate.goog/master/get-started/platforms/espressif.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) -- [NXP MCUXpresso component](https://www-nxp-com.translate.goog/design/software/embedded-software/lvgl-open-source-graphics-library:LITTLEVGL-OPEN-SOURCE-GRAPHICS-LIBRARY?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) -- [NuttX library](https://docs-lvgl-io.translate.goog/master/get-started/os/nuttx.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) -- [RT-Thread RTOS](https://docs-lvgl-io.translate.goog/master/get-started/os/rt-thread.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) -- NXP MCUXpresso library -- CMSIS-Pack - -## :robot: サンプルプログラム - -ウィジェット・レイアウト・スタイルのサンプルプログラムを用意しました。 -C と MicroPython のコードを選べます。 -オンラインの MicroPythonエディタ へのリンクにより、サンプルプログラムの動作確認・編集もできます。 - -その他のサンプルプログラムは [Examples フォルダ](https://github.com/lvgl/lvgl/tree/master/examples) :gb: を確認してください。 - -### Button with Click Event - - - -<details> - <summary>C code</summary> - -```c -lv_obj_t * btn = lv_btn_create(lv_scr_act()); /*Add a button to the current screen*/ -lv_obj_center(btn); /*Set its position*/ -lv_obj_set_size(btn, 100, 50); /*Set its size*/ -lv_obj_add_event(btn, btn_event_cb, LV_EVENT_CLICKED, NULL); /*Assign a callback to the button*/ - -lv_obj_t * label = lv_label_create(btn); /*Add a label to the button*/ -lv_label_set_text(label, "Button"); /*Set the labels text*/ -lv_obj_center(label); /*Align the label to the center*/ -... - -void btn_event_cb(lv_event_t * e) -{ - printf("Clicked\n"); -} -``` -</details> - -<details> - <summary>MicroPython code | <a href="https://sim.lvgl.io/v8.3/micropython/ports/javascript/index.html?script_startup=https://raw.githubusercontent.com/lvgl/lvgl/0d9ab4ee0e591aad1970e3c9164fd7c544ecce70/examples/header.py&script=https://raw.githubusercontent.com/lvgl/lvgl/0d9ab4ee0e591aad1970e3c9164fd7c544ecce70/examples/widgets/slider/lv_example_slider_2.py&script_direct=926bde43ec7af0146c486de470c53f11f167491e" target="_blank">Online Simulator</a> :gb:</summary> - -```python -def btn_event_cb(e): - print("Clicked") - -# Create a Button and a Label -btn = lv.btn(lv.scr_act()) -btn.center() -btn.set_size(100, 50) -btn.add_event(btn_event_cb, lv.EVENT.CLICKED, None) - -label = lv.label(btn) -label.set_text("Button") -label.center() -``` -</details> -<br> - -### Checkboxes with Layout - - -<details> - <summary>C code</summary> - -```c - -lv_obj_set_flex_flow(lv_scr_act(), LV_FLEX_FLOW_COLUMN); -lv_obj_set_flex_align(lv_scr_act(), LV_FLEX_ALIGN_CENTER, LV_FLEX_ALIGN_START, LV_FLEX_ALIGN_CENTER); - -lv_obj_t * cb; -cb = lv_checkbox_create(lv_scr_act()); -lv_checkbox_set_text(cb, "Apple"); -lv_obj_add_event(cb, event_handler, LV_EVENT_ALL, NULL); - -cb = lv_checkbox_create(lv_scr_act()); -lv_checkbox_set_text(cb, "Banana"); -lv_obj_add_state(cb, LV_STATE_CHECKED); -lv_obj_add_event(cb, event_handler, LV_EVENT_ALL, NULL); - -cb = lv_checkbox_create(lv_scr_act()); -lv_checkbox_set_text(cb, "Lemon"); -lv_obj_add_state(cb, LV_STATE_DISABLED); -lv_obj_add_event(cb, event_handler, LV_EVENT_ALL, NULL); - -cb = lv_checkbox_create(lv_scr_act()); -lv_obj_add_state(cb, LV_STATE_CHECKED | LV_STATE_DISABLED); -lv_checkbox_set_text(cb, "Melon\nand a new line"); -lv_obj_add_event(cb, event_handler, LV_EVENT_ALL, NULL); -``` - -</details> - -<details> - <summary>MicroPython code | <a href="https://sim.lvgl.io/v8.3/micropython/ports/javascript/index.html?script_startup=https://raw.githubusercontent.com/lvgl/lvgl/0d9ab4ee0e591aad1970e3c9164fd7c544ecce70/examples/header.py&script=https://raw.githubusercontent.com/lvgl/lvgl/0d9ab4ee0e591aad1970e3c9164fd7c544ecce70/examples/widgets/slider/lv_example_slider_2.py&script_direct=311d37e5f70daf1cb0d2cad24c7f72751b5f1792" target="_blank">Online Simulator</a> :gb:</summary> - -```python -def event_handler(e): - code = e.get_code() - obj = e.get_target_obj() - if code == lv.EVENT.VALUE_CHANGED: - txt = obj.get_text() - if obj.get_state() & lv.STATE.CHECKED: - state = "Checked" - else: - state = "Unchecked" - print(txt + ":" + state) - - -lv.scr_act().set_flex_flow(lv.FLEX_FLOW.COLUMN) -lv.scr_act().set_flex_align(lv.FLEX_ALIGN.CENTER, lv.FLEX_ALIGN.START, lv.FLEX_ALIGN.CENTER) - -cb = lv.checkbox(lv.scr_act()) -cb.set_text("Apple") -cb.add_event(event_handler, lv.EVENT.ALL, None) - -cb = lv.checkbox(lv.scr_act()) -cb.set_text("Banana") -cb.add_state(lv.STATE.CHECKED) -cb.add_event(event_handler, lv.EVENT.ALL, None) - -cb = lv.checkbox(lv.scr_act()) -cb.set_text("Lemon") -cb.add_state(lv.STATE.DISABLED) -cb.add_event(event_handler, lv.EVENT.ALL, None) - -cb = lv.checkbox(lv.scr_act()) -cb.add_state(lv.STATE.CHECKED | lv.STATE.DISABLED) -cb.set_text("Melon") -cb.add_event(event_handler, lv.EVENT.ALL, None) -``` - -</details> -<br> - -### Styling a Slider - - - -<details> - <summary>C code</summary> - -```c -lv_obj_t * slider = lv_slider_create(lv_scr_act()); -lv_slider_set_value(slider, 70, LV_ANIM_OFF); -lv_obj_set_size(slider, 300, 20); -lv_obj_center(slider); - -/*Add local styles to MAIN part (background rectangle)*/ -lv_obj_set_style_bg_color(slider, lv_color_hex(0x0F1215), LV_PART_MAIN); -lv_obj_set_style_bg_opa(slider, 255, LV_PART_MAIN); -lv_obj_set_style_border_color(slider, lv_color_hex(0x333943), LV_PART_MAIN); -lv_obj_set_style_border_width(slider, 5, LV_PART_MAIN); -lv_obj_set_style_pad_all(slider, 5, LV_PART_MAIN); - -/*Create a reusable style sheet for the INDICATOR part*/ -static lv_style_t style_indicator; -lv_style_init(&style_indicator); -lv_style_set_bg_color(&style_indicator, lv_color_hex(0x37B9F5)); -lv_style_set_bg_grad_color(&style_indicator, lv_color_hex(0x1464F0)); -lv_style_set_bg_grad_dir(&style_indicator, LV_GRAD_DIR_HOR); -lv_style_set_shadow_color(&style_indicator, lv_color_hex(0x37B9F5)); -lv_style_set_shadow_width(&style_indicator, 15); -lv_style_set_shadow_spread(&style_indicator, 5); - -/*Add the style sheet to the slider's INDICATOR part*/ -lv_obj_add_style(slider, &style_indicator, LV_PART_INDICATOR); - -/*Add the same style to the KNOB part too and locally overwrite some properties*/ -lv_obj_add_style(slider, &style_indicator, LV_PART_KNOB); - -lv_obj_set_style_outline_color(slider, lv_color_hex(0x0096FF), LV_PART_KNOB); -lv_obj_set_style_outline_width(slider, 3, LV_PART_KNOB); -lv_obj_set_style_outline_pad(slider, -5, LV_PART_KNOB); -lv_obj_set_style_shadow_spread(slider, 2, LV_PART_KNOB); -``` - -</details> - -<details> - <summary>MicroPython code | -<a href="https://sim.lvgl.io/v8.3/micropython/ports/javascript/index.html?script_startup=https://raw.githubusercontent.com/lvgl/lvgl/0d9ab4ee0e591aad1970e3c9164fd7c544ecce70/examples/header.py&script=https://raw.githubusercontent.com/lvgl/lvgl/0d9ab4ee0e591aad1970e3c9164fd7c544ecce70/examples/widgets/slider/lv_example_slider_2.py&script_direct=c431c7b4dfd2cc0dd9c392b74365d5af6ea986f0" target="_blank">Online Simulator</a> :gb: -</summary> - - -```python -# Create a slider and add the style -slider = lv.slider(lv.scr_act()) -slider.set_value(70, lv.ANIM.OFF) -slider.set_size(300, 20) -slider.center() - -# Add local styles to MAIN part (background rectangle) -slider.set_style_bg_color(lv.color_hex(0x0F1215), lv.PART.MAIN) -slider.set_style_bg_opa(255, lv.PART.MAIN) -slider.set_style_border_color(lv.color_hex(0x333943), lv.PART.MAIN) -slider.set_style_border_width(5, lv.PART.MAIN) -slider.set_style_pad_all(5, lv.PART.MAIN) - -# Create a reusable style sheet for the INDICATOR part -style_indicator = lv.style_t() -style_indicator.init() -style_indicator.set_bg_color(lv.color_hex(0x37B9F5)) -style_indicator.set_bg_grad_color(lv.color_hex(0x1464F0)) -style_indicator.set_bg_grad_dir(lv.GRAD_DIR.HOR) -style_indicator.set_shadow_color(lv.color_hex(0x37B9F5)) -style_indicator.set_shadow_width(15) -style_indicator.set_shadow_spread(5) - -# Add the style sheet to the slider's INDICATOR part -slider.add_style(style_indicator, lv.PART.INDICATOR) -slider.add_style(style_indicator, lv.PART.KNOB) - -# Add the same style to the KNOB part too and locally overwrite some properties -slider.set_style_outline_color(lv.color_hex(0x0096FF), lv.PART.KNOB) -slider.set_style_outline_width(3, lv.PART.KNOB) -slider.set_style_outline_pad(-5, lv.PART.KNOB) -slider.set_style_shadow_spread(2, lv.PART.KNOB) -``` -</details> -<br> - -### English, Hebrew (mixed LRT-RTL) and Chinese texts - - - -<details> - <summary>C code</summary> - -```c -lv_obj_t * ltr_label = lv_label_create(lv_scr_act()); -lv_label_set_text(ltr_label, "In modern terminology, a microcontroller is similar to a system on a chip (SoC)."); -lv_obj_set_style_text_font(ltr_label, &lv_font_montserrat_16, 0); -lv_obj_set_width(ltr_label, 310); -lv_obj_align(ltr_label, LV_ALIGN_TOP_LEFT, 5, 5); - -lv_obj_t * rtl_label = lv_label_create(lv_scr_act()); -lv_label_set_text(rtl_label,"מעבד, או בשמו המלא יחידת עיבוד מרכזית (באנגלית: CPU - Central Processing Unit)."); -lv_obj_set_style_base_dir(rtl_label, LV_BASE_DIR_RTL, 0); -lv_obj_set_style_text_font(rtl_label, &lv_font_dejavu_16_persian_hebrew, 0); -lv_obj_set_width(rtl_label, 310); -lv_obj_align(rtl_label, LV_ALIGN_LEFT_MID, 5, 0); - -lv_obj_t * cz_label = lv_label_create(lv_scr_act()); -lv_label_set_text(cz_label, - "嵌入式系统（Embedded System），\n是一种嵌入机械或电气系统内部、具有专一功能和实时计算性能的计算机系统。"); -lv_obj_set_style_text_font(cz_label, &lv_font_simsun_16_cjk, 0); -lv_obj_set_width(cz_label, 310); -lv_obj_align(cz_label, LV_ALIGN_BOTTOM_LEFT, 5, -5); -``` - -</details> - -<details> - <summary>MicroPython code | <a href="https://sim.lvgl.io/v8.3/micropython/ports/javascript/index.html?script_startup=https://raw.githubusercontent.com/lvgl/lvgl/0d9ab4ee0e591aad1970e3c9164fd7c544ecce70/examples/header.py&script=https://raw.githubusercontent.com/lvgl/lvgl/0d9ab4ee0e591aad1970e3c9164fd7c544ecce70/examples/widgets/slider/lv_example_slider_2.py&script_direct=18bb38200a64e10ead1aa17a65c977fc18131842" target="_blank">Online Simulator</a> :gb:</summary> - -```python -ltr_label = lv.label(lv.scr_act()) -ltr_label.set_text("In modern terminology, a microcontroller is similar to a system on a chip (SoC).") -ltr_label.set_style_text_font(lv.font_montserrat_16, 0); - -ltr_label.set_width(310) -ltr_label.align(lv.ALIGN.TOP_LEFT, 5, 5) - -rtl_label = lv.label(lv.scr_act()) -rtl_label.set_text("מעבד, או בשמו המלא יחידת עיבוד מרכזית (באנגלית: CPU - Central Processing Unit).") -rtl_label.set_style_base_dir(lv.BASE_DIR.RTL, 0) -rtl_label.set_style_text_font(lv.font_dejavu_16_persian_hebrew, 0) -rtl_label.set_width(310) -rtl_label.align(lv.ALIGN.LEFT_MID, 5, 0) - -font_simsun_16_cjk = lv.font_load("S:../../assets/font/lv_font_simsun_16_cjk.fnt") - -cz_label = lv.label(lv.scr_act()) -cz_label.set_style_text_font(font_simsun_16_cjk, 0) -cz_label.set_text("嵌入式系统（Embedded System），\n是一种嵌入机械或电气系统内部、具有专一功能和实时计算性能的计算机系统。") -cz_label.set_width(310) -cz_label.align(lv.ALIGN.BOTTOM_LEFT, 5, -5) - -``` -</details> - -## :arrow_forward: はじめに -LVGLを使い始める時は、以下の順に進める事をおすすめします。 - -**LVGLに触れてみましょう** - - 1. LVGLの動きを [オンラインデモ](https://lvgl-io.translate.goog/demos?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) で確認しましょう。 (3分間) - 2. ドキュメントの [Introduction](https://docs-lvgl-io.translate.goog/master/intro/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) を読みましょう。 (5分間) - 3. LVGLの基本に慣れるため [Quick overview](https://docs-lvgl-io.translate.goog/master/get-started/quick-overview.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) を読みましょう。 (15分間) - -**LVGLを使ってみましょう** - - 4. [シミュレータ](https://docs-lvgl-io.translate.goog/master/get-started/platforms/pc-simulator.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) をセットアップしましょう。 (10 minutes) - 5. [サンプルプログラム](https://github.com/lvgl/lvgl/tree/master/examples) :gb: を動かしてみましょう。 - 6. [移植ガイド](https://docs-lvgl-io.translate.goog/master/porting/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) を参考に、LVGLを開発ボードに移植してみましょう。すぐ使える形の [プロジェクト](https://github.com/lvgl?q=lv_port_) :gb: も用意してあります。 - -**より詳しく体験してみましょう** - - 7. ライブラリの理解を深めるため [Overview](https://docs-lvgl-io.translate.goog/master/overview/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) を読みましょう。 (2～3時間) - 8. ウィジェットの機能や使い方の詳細は [Widgets](https://docs-lvgl-io.translate.goog/master/widgets/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) でご確認ください。 - -**助け合いましょう** - - 9. 質問がある場合は [Forum](http://forum.lvgl.io/) :gb: で質問して下さい。 - 10. LVGLの改善への協力は大歓迎です。詳細は [Contributing guide](https://docs-lvgl-io.translate.goog/master/CONTRIBUTING.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) をご覧ください。 (15分間) - -**さらに理解を深めましょう** - - 11. [SquareLine Studio](https://squareline.io/) :gb: をダウンロードして試用してみましょう。 - 12. 技術的サポートが必要であれば、[技術サービス](https://lvgl.io/services) :gb: に問い合わせて下さい。 - - -## :handshake: 技術サービス -[LVGL LLC](https://www.digikey.com/en/design-services-providers/lvgl-kft) は、LVGLライブラリの確かな背景を元に、UI開発のための様々な技術サービスを提供するために設立されました。 UIとグラフィックス業界における15年以上の実績を活かし、UIを次のレベルに引き上げるお手伝いを致します。 - -- **グラフィックデザイン** 当社のグラフィックデザイナーは、製品とハードウェアのリソースに合わせて美しくモダンなデザインにするエキスパートです。 -- **UI実装** お客様または弊社で作成したデザインを元に、UIを実装することも可能です。お客様のハードウェアとLVGLを最大限に活用することをお約束します。 -LVGLにない機能やウィジェットは、私たちが実装しますのでご安心ください。 -- **コンサルタント＆技術サポート** UI開発において、価格と時間を要する作業でのリスクを減らすため、コンサルティングも含めてサポート致します。 -- **Board certification** development board または production ready kit を提供している企業に対しては、ボードがLVGLを実行できるようにするためのボード認定を行います。 - - -サンプルは [Demos](https://lvgl-io.translate.goog/demos?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) をご覧ください。 -詳しくは [Services page](https://lvgl-io.translate.goog/services?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) をご覧ください。 - -お問い合わせは [問い合わせフォーム](https://lvgl.io/#contact) :gb: より送信して下さい。 - - -## :star2: 協力 -LVGLはオープンプロジェクトであり、協力は大歓迎です。 -色々な方法で協力できます。 -協力方法の例 - - LVGLを使用した作品やプロジェクトの公表 - - サンプルプログラムの作成 - - ドキュメントの改善 - - バグの修正 - -協力方法の詳細については、ドキュメントの [Contributing section](https://docs-lvgl-io.translate.goog/master/CONTRIBUTING.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja) をご覧ください。 - -すでに 300人以上がLVGLに足跡を残しています。いっしょに活動しましょう! :slightly_smiling_face: - -<a href="https://github.com/lvgl/lvgl/graphs/contributors"> - <img src="https://contrib.rocks/image?repo=lvgl/lvgl&max=48" /> -</a> - -... and many other. diff --git a/docs/README_jp.rst.back b/docs/README_jp.rst.back new file mode 100644 index 000000000..698c0303b --- /dev/null +++ b/docs/README_jp.rst.back @@ -0,0 +1,648 @@ +.. raw:: html + + <p align="right"> + +English \| 中文 \| Português do Brasil \| 日本語 + +.. raw:: html + + </p> + + + +.. raw:: html + + <p align="center"> + + + +.. raw:: html + + </p> + + + +.. raw:: html + + <h1 align="center"> + +Light and Versatile Graphics Library + +.. raw:: html + + </h1> + + + + + + +.. raw:: html + + <p align="center"> + +Website \| Docs \| Forum :gb: \| Demos \| Services \| SquareLine Studio +:gb: + +.. raw:: html + + </p> + +:ledger: +Overview +----------------- + +**実績**\ LVGL +は、フリー＆オープンソースの組み込み用グラフィックスライブラリです。 +あらゆるMCU、MPU、ディスプレイタイプに対応しており、美しいUI(User +Interface)を実現できます。 ARM, STM32, NXP, Espressif, Nuvoton, Arduino, +RT-Thread, Zephyr, NuttX, +Adafruitなど、業界をリードするベンダーやプロジェクトによりサポートされています。 + +**機能豊富**\ +モダンで美しいGUIを作成するための機能をすべて備えています。 +30以上の組み込みウィジェット、強力なスタイルシステム、WEB由来のレイアウトマネージャ、多くの言語をサポートする文字グラフィックシステムなどです。 +LVGL のシステム要件は、RAM 32KB、Flash +128KB、Cコンパイラ、フレームバッファ、1/10スクリーンサイズのレンダリング用バッファです。 + +**UIエディタ**\ SquareLine Studio +は、LVGL用のプロフェッショナル＆リーズナブルなドラッグ＆ドロップ型のUIエディターです。 +Windows、Linux、MacOS +で動作し、ウェブサイトへの登録なしで試すことができます。 + +**サービス**\ LVGL LLC +では、グラフィックデザイン、UI実装、コンサルティングサービスに対する技術サポートが可能です。GUIプロジェクトの開発において何らかのサポートが必要な場合には、お気軽にお問い合わせください。 + +:rocket: +特徴 +------------- + +**フリー & 移植可能** - 外部依存関係がなく、完全に移植可能な +Cライブラリ。(C++互換) - +任意の(RT)OS、任意のMCU・MPU用にコンパイル可能。 - +電子ペーパー、OLEDディスプレイ、TFTディスプレイ、白黒ディスプレイ、モニターに対応。 +`Porting +Guide <https://docs-lvgl-io.translate.goog/master/porting/project.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ +- MITライセンスにより商用利用可能。 - システム要件：RAM 32KB、Flash +128KB、フレームバッファ、レンダリング用に1/10以上のスクリーンサイズのバッファ。 +- OS、外部メモリ、GPUもサポート。 + +**ウィジェット、スタイル、レイアウトなど** - 30以上の組み込み +`ウィジェット <https://docs-lvgl-io.translate.goog/master/widgets/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__: ボタン、ラベル、スライダー、グラフ、キーボード、メーター、円弧、表など。 +- +ウィジェットの任意の部分を任意の状態にカスタマイズ可能な豊富なスタイルプロパティを備えた柔軟な +`スタイルシステム <https://docs-lvgl-io.translate.goog/master/overview/style.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__\ 。 +- +`Flexbox <https://docs-lvgl-io.translate.goog/master/layouts/flex.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ +および +`グリッド <https://docs-lvgl-io.translate.goog/master/layouts/grid.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ +風のレイアウトエンジンにより、ウィジェットのサイズと位置を自動的に設定。 +- +テキスト表示(UTF-8対応)は、中国語、日本語、韓国語、タイ語、ヒンディー語、アラビア語、ペルシア語をサポート。 +- +ワードラッピング、カーニング、テキストスクロール、サブピクセルレンダリング、ピンイン-IME中国語入力、テキスト中の絵文字に対応。 +- +アニメーション、アンチエイリアシング、不透明度、スムーズスクロール、シャドウ、画像変換などをサポートするレンダリングエンジン。 +- +マウス、タッチパッド、キーパッド、キーボード、外部ボタン、エンコーダ等の +`入力デバイス <https://docs-lvgl-io.translate.goog/master/porting/indev.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ +をサポート。 - +`マルチディスプレイ <https://docs-lvgl-io.translate.goog/master/overview/display.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ +対応。 + +**Binding と Build をサポート** - `Micropython +Binding <https://blog-lvgl-io.translate.goog/2019-02-20/micropython-bindings?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ +が LVGL API を公開。 - +カスタムビルドシステムは使用せず、プロジェクトの他のファイルをビルドするときに、LVGLをビルド可能。 +- Make と +`CMake <https://docs-lvgl-io.translate.goog/master/get-started/platforms/cmake.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ +が含まれており、すぐ使えるようにサポート。 - +`PCのシミュレータで開発したUIコード <https://docs-lvgl-io.translate.goog/master/get-started/platforms/pc-simulator.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ +は、そのまま組込み用ハードウェアでも使用可能。 - `Emscripten +port <https://github.com/lvgl/lv_web_emscripten>`__ :gb: +によりC言語のUIコードをHTMLファイルに変換。 + +**ドキュメント, ツール, 技術サービス** - +`ドキュメント <https://docs-lvgl-io.translate.goog/master/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__\ は\ `100以上の簡単なサンプルプログラム <https://github.com/lvgl/lvgl/tree/master/examples>`__ +:gb: 入り 。 - `SquareLine Studio <https://squareline.io/>`__ :gb: - +UI開発をスピードアップおよび簡素化するためのプロフェッショナルで使いやすいUIエディターソフトウェア。 +- +UI開発をよりシンプルかつ迅速にするための、ユーザーインターフェイスの設計、実装、コンサルティングなどの +`技術サービス <https://lvgl-io.translate.goog/services?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__\ 。 + +:package: +パッケージ +-------------------- + +LVGL は以下で利用可能です。 - `Arduino +library <https://docs-lvgl-io.translate.goog/master/get-started/platforms/arduino.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ +- `PlatformIO +package <https://registry.platformio.org/libraries/lvgl/lvgl>`__ :gb: - +`Zephyr +library <https://docs-zephyrproject-org.translate.goog/latest/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ +- `ESP32 +component <https://docs-lvgl-io.translate.goog/master/get-started/platforms/espressif.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ +- `NXP MCUXpresso +component <https://www-nxp-com.translate.goog/design/software/embedded-software/lvgl-open-source-graphics-library:LITTLEVGL-OPEN-SOURCE-GRAPHICS-LIBRARY?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ +- `NuttX +library <https://docs-lvgl-io.translate.goog/master/get-started/os/nuttx.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ +- `RT-Thread +RTOS <https://docs-lvgl-io.translate.goog/master/get-started/os/rt-thread.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ +- NXP MCUXpresso library - CMSIS-Pack + +:robot: +サンプルプログラム +-------------------------- + +ウィジェット・レイアウト・スタイルのサンプルプログラムを用意しました。 C +と MicroPython のコードを選べます。 オンラインの MicroPythonエディタ +へのリンクにより、サンプルプログラムの動作確認・編集もできます。 + +その他のサンプルプログラムは `Examples +フォルダ <https://github.com/lvgl/lvgl/tree/master/examples>`__ :gb: +を確認してください。 + +Button with Click Event +~~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: https://github.com/kisvegabor/test/raw/master/readme_example_1.gif + :alt: ラベル付きボタンのLVGLサンプルプログラム + + ラベル付きボタンのLVGLサンプルプログラム + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +C code + +.. raw:: html + + </summary> + +.. code:: c + + lv_obj_t * btn = lv_btn_create(lv_scr_act()); /*Add a button to the current screen*/ + lv_obj_center(btn); /*Set its position*/ + lv_obj_set_size(btn, 100, 50); /*Set its size*/ + lv_obj_add_event(btn, btn_event_cb, LV_EVENT_CLICKED, NULL); /*Assign a callback to the button*/ + + lv_obj_t * label = lv_label_create(btn); /*Add a label to the button*/ + lv_label_set_text(label, "Button"); /*Set the labels text*/ + lv_obj_center(label); /*Align the label to the center*/ + ... + + void btn_event_cb(lv_event_t * e) + { + printf("Clicked\n"); + } + +.. raw:: html + + </details> + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +MicroPython code \| Online Simulator :gb: + +.. raw:: html + + </summary> + +.. code:: python + + def btn_event_cb(e): + print("Clicked") + + # Create a Button and a Label + btn = lv.btn(lv.scr_act()) + btn.center() + btn.set_size(100, 50) + btn.add_event(btn_event_cb, lv.EVENT.CLICKED, None) + + label = lv.label(btn) + label.set_text("Button") + label.center() + +.. raw:: html + + </details> + +Checkboxes with Layout +~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: https://github.com/kisvegabor/test/raw/master/readme_example_2.gif + :alt: Checkboxes with layout in LVGL + + Checkboxes with layout in LVGL + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +C code + +.. raw:: html + + </summary> + +.. code:: c + + + lv_obj_set_flex_flow(lv_scr_act(), LV_FLEX_FLOW_COLUMN); + lv_obj_set_flex_align(lv_scr_act(), LV_FLEX_ALIGN_CENTER, LV_FLEX_ALIGN_START, LV_FLEX_ALIGN_CENTER); + + lv_obj_t * cb; + cb = lv_checkbox_create(lv_scr_act()); + lv_checkbox_set_text(cb, "Apple"); + lv_obj_add_event(cb, event_handler, LV_EVENT_ALL, NULL); + + cb = lv_checkbox_create(lv_scr_act()); + lv_checkbox_set_text(cb, "Banana"); + lv_obj_add_state(cb, LV_STATE_CHECKED); + lv_obj_add_event(cb, event_handler, LV_EVENT_ALL, NULL); + + cb = lv_checkbox_create(lv_scr_act()); + lv_checkbox_set_text(cb, "Lemon"); + lv_obj_add_state(cb, LV_STATE_DISABLED); + lv_obj_add_event(cb, event_handler, LV_EVENT_ALL, NULL); + + cb = lv_checkbox_create(lv_scr_act()); + lv_obj_add_state(cb, LV_STATE_CHECKED | LV_STATE_DISABLED); + lv_checkbox_set_text(cb, "Melon\nand a new line"); + lv_obj_add_event(cb, event_handler, LV_EVENT_ALL, NULL); + +.. raw:: html + + </details> + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +MicroPython code \| Online Simulator :gb: + +.. raw:: html + + </summary> + +.. code:: python + + def event_handler(e): + code = e.get_code() + obj = e.get_target_obj() + if code == lv.EVENT.VALUE_CHANGED: + txt = obj.get_text() + if obj.get_state() & lv.STATE.CHECKED: + state = "Checked" + else: + state = "Unchecked" + print(txt + ":" + state) + + + lv.scr_act().set_flex_flow(lv.FLEX_FLOW.COLUMN) + lv.scr_act().set_flex_align(lv.FLEX_ALIGN.CENTER, lv.FLEX_ALIGN.START, lv.FLEX_ALIGN.CENTER) + + cb = lv.checkbox(lv.scr_act()) + cb.set_text("Apple") + cb.add_event(event_handler, lv.EVENT.ALL, None) + + cb = lv.checkbox(lv.scr_act()) + cb.set_text("Banana") + cb.add_state(lv.STATE.CHECKED) + cb.add_event(event_handler, lv.EVENT.ALL, None) + + cb = lv.checkbox(lv.scr_act()) + cb.set_text("Lemon") + cb.add_state(lv.STATE.DISABLED) + cb.add_event(event_handler, lv.EVENT.ALL, None) + + cb = lv.checkbox(lv.scr_act()) + cb.add_state(lv.STATE.CHECKED | lv.STATE.DISABLED) + cb.set_text("Melon") + cb.add_event(event_handler, lv.EVENT.ALL, None) + +.. raw:: html + + </details> + +Styling a Slider +~~~~~~~~~~~~~~~~ + +.. figure:: https://github.com/kisvegabor/test/raw/master/readme_example_3.gif + :alt: Styling a slider with LVGL + + Styling a slider with LVGL + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +C code + +.. raw:: html + + </summary> + +.. code:: c + + lv_obj_t * slider = lv_slider_create(lv_scr_act()); + lv_slider_set_value(slider, 70, LV_ANIM_OFF); + lv_obj_set_size(slider, 300, 20); + lv_obj_center(slider); + + /*Add local styles to MAIN part (background rectangle)*/ + lv_obj_set_style_bg_color(slider, lv_color_hex(0x0F1215), LV_PART_MAIN); + lv_obj_set_style_bg_opa(slider, 255, LV_PART_MAIN); + lv_obj_set_style_border_color(slider, lv_color_hex(0x333943), LV_PART_MAIN); + lv_obj_set_style_border_width(slider, 5, LV_PART_MAIN); + lv_obj_set_style_pad_all(slider, 5, LV_PART_MAIN); + + /*Create a reusable style sheet for the INDICATOR part*/ + static lv_style_t style_indicator; + lv_style_init(&style_indicator); + lv_style_set_bg_color(&style_indicator, lv_color_hex(0x37B9F5)); + lv_style_set_bg_grad_color(&style_indicator, lv_color_hex(0x1464F0)); + lv_style_set_bg_grad_dir(&style_indicator, LV_GRAD_DIR_HOR); + lv_style_set_shadow_color(&style_indicator, lv_color_hex(0x37B9F5)); + lv_style_set_shadow_width(&style_indicator, 15); + lv_style_set_shadow_spread(&style_indicator, 5); + + /*Add the style sheet to the slider's INDICATOR part*/ + lv_obj_add_style(slider, &style_indicator, LV_PART_INDICATOR); + + /*Add the same style to the KNOB part too and locally overwrite some properties*/ + lv_obj_add_style(slider, &style_indicator, LV_PART_KNOB); + + lv_obj_set_style_outline_color(slider, lv_color_hex(0x0096FF), LV_PART_KNOB); + lv_obj_set_style_outline_width(slider, 3, LV_PART_KNOB); + lv_obj_set_style_outline_pad(slider, -5, LV_PART_KNOB); + lv_obj_set_style_shadow_spread(slider, 2, LV_PART_KNOB); + +.. raw:: html + + </details> + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +MicroPython code \| Online Simulator :gb: + +.. raw:: html + + </summary> + +.. code:: python + + # Create a slider and add the style + slider = lv.slider(lv.scr_act()) + slider.set_value(70, lv.ANIM.OFF) + slider.set_size(300, 20) + slider.center() + + # Add local styles to MAIN part (background rectangle) + slider.set_style_bg_color(lv.color_hex(0x0F1215), lv.PART.MAIN) + slider.set_style_bg_opa(255, lv.PART.MAIN) + slider.set_style_border_color(lv.color_hex(0x333943), lv.PART.MAIN) + slider.set_style_border_width(5, lv.PART.MAIN) + slider.set_style_pad_all(5, lv.PART.MAIN) + + # Create a reusable style sheet for the INDICATOR part + style_indicator = lv.style_t() + style_indicator.init() + style_indicator.set_bg_color(lv.color_hex(0x37B9F5)) + style_indicator.set_bg_grad_color(lv.color_hex(0x1464F0)) + style_indicator.set_bg_grad_dir(lv.GRAD_DIR.HOR) + style_indicator.set_shadow_color(lv.color_hex(0x37B9F5)) + style_indicator.set_shadow_width(15) + style_indicator.set_shadow_spread(5) + + # Add the style sheet to the slider's INDICATOR part + slider.add_style(style_indicator, lv.PART.INDICATOR) + slider.add_style(style_indicator, lv.PART.KNOB) + + # Add the same style to the KNOB part too and locally overwrite some properties + slider.set_style_outline_color(lv.color_hex(0x0096FF), lv.PART.KNOB) + slider.set_style_outline_width(3, lv.PART.KNOB) + slider.set_style_outline_pad(-5, lv.PART.KNOB) + slider.set_style_shadow_spread(2, lv.PART.KNOB) + +.. raw:: html + + </details> + +English, Hebrew (mixed LRT-RTL) and Chinese texts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: https://github.com/kisvegabor/test/raw/master/readme_example_4.png + :alt: English, Hebrew and Chinese texts with LVGL + + English, Hebrew and Chinese texts with LVGL + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +C code + +.. raw:: html + + </summary> + +.. code:: c + + lv_obj_t * ltr_label = lv_label_create(lv_scr_act()); + lv_label_set_text(ltr_label, "In modern terminology, a microcontroller is similar to a system on a chip (SoC)."); + lv_obj_set_style_text_font(ltr_label, &lv_font_montserrat_16, 0); + lv_obj_set_width(ltr_label, 310); + lv_obj_align(ltr_label, LV_ALIGN_TOP_LEFT, 5, 5); + + lv_obj_t * rtl_label = lv_label_create(lv_scr_act()); + lv_label_set_text(rtl_label,"מעבד, או בשמו המלא יחידת עיבוד מרכזית (באנגלית: CPU - Central Processing Unit)."); + lv_obj_set_style_base_dir(rtl_label, LV_BASE_DIR_RTL, 0); + lv_obj_set_style_text_font(rtl_label, &lv_font_dejavu_16_persian_hebrew, 0); + lv_obj_set_width(rtl_label, 310); + lv_obj_align(rtl_label, LV_ALIGN_LEFT_MID, 5, 0); + + lv_obj_t * cz_label = lv_label_create(lv_scr_act()); + lv_label_set_text(cz_label, + "嵌入式系统（Embedded System），\n是一种嵌入机械或电气系统内部、具有专一功能和实时计算性能的计算机系统。"); + lv_obj_set_style_text_font(cz_label, &lv_font_simsun_16_cjk, 0); + lv_obj_set_width(cz_label, 310); + lv_obj_align(cz_label, LV_ALIGN_BOTTOM_LEFT, 5, -5); + +.. raw:: html + + </details> + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +MicroPython code \| Online Simulator :gb: + +.. raw:: html + + </summary> + +.. code:: python + + ltr_label = lv.label(lv.scr_act()) + ltr_label.set_text("In modern terminology, a microcontroller is similar to a system on a chip (SoC).") + ltr_label.set_style_text_font(lv.font_montserrat_16, 0); + + ltr_label.set_width(310) + ltr_label.align(lv.ALIGN.TOP_LEFT, 5, 5) + + rtl_label = lv.label(lv.scr_act()) + rtl_label.set_text("מעבד, או בשמו המלא יחידת עיבוד מרכזית (באנגלית: CPU - Central Processing Unit).") + rtl_label.set_style_base_dir(lv.BASE_DIR.RTL, 0) + rtl_label.set_style_text_font(lv.font_dejavu_16_persian_hebrew, 0) + rtl_label.set_width(310) + rtl_label.align(lv.ALIGN.LEFT_MID, 5, 0) + + font_simsun_16_cjk = lv.font_load("S:../../assets/font/lv_font_simsun_16_cjk.fnt") + + cz_label = lv.label(lv.scr_act()) + cz_label.set_style_text_font(font_simsun_16_cjk, 0) + cz_label.set_text("嵌入式系统（Embedded System），\n是一种嵌入机械或电气系统内部、具有专一功能和实时计算性能的计算机系统。") + cz_label.set_width(310) + cz_label.align(lv.ALIGN.BOTTOM_LEFT, 5, -5) + +.. raw:: html + + </details> + +:arrow_forward: +はじめに +------------------------ + +LVGLを使い始める時は、以下の順に進める事をおすすめします。 + +**LVGLに触れてみましょう** + +1. LVGLの動きを + `オンラインデモ <https://lvgl-io.translate.goog/demos?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ + で確認しましょう。 (3分間) +2. ドキュメントの + `Introduction <https://docs-lvgl-io.translate.goog/master/intro/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ + を読みましょう。 (5分間) +3. LVGLの基本に慣れるため `Quick + overview <https://docs-lvgl-io.translate.goog/master/get-started/quick-overview.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ + を読みましょう。 (15分間) + +**LVGLを使ってみましょう** + +4. `シミュレータ <https://docs-lvgl-io.translate.goog/master/get-started/platforms/pc-simulator.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ + をセットアップしましょう。 (10 minutes) +5. `サンプルプログラム <https://github.com/lvgl/lvgl/tree/master/examples>`__ + :gb: を動かしてみましょう。 +6. `移植ガイド <https://docs-lvgl-io.translate.goog/master/porting/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ + を参考に、LVGLを開発ボードに移植してみましょう。すぐ使える形の + `プロジェクト <https://github.com/lvgl?q=lv_port_>`__ :gb: + も用意してあります。 + +**より詳しく体験してみましょう** + +7. ライブラリの理解を深めるため + `Overview <https://docs-lvgl-io.translate.goog/master/overview/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ + を読みましょう。 (2～3時間) +8. ウィジェットの機能や使い方の詳細は + `Widgets <https://docs-lvgl-io.translate.goog/master/widgets/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ + でご確認ください。 + +**助け合いましょう** + +9. 質問がある場合は `Forum <http://forum.lvgl.io/>`__ :gb: + で質問して下さい。 +10. LVGLの改善への協力は大歓迎です。詳細は `Contributing + guide <https://docs-lvgl-io.translate.goog/master/CONTRIBUTING.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ + をご覧ください。 (15分間) + +**さらに理解を深めましょう** + +11. `SquareLine Studio <https://squareline.io/>`__ :gb: + をダウンロードして試用してみましょう。 +12. 技術的サポートが必要であれば、\ `技術サービス <https://lvgl.io/services>`__ + :gb: に問い合わせて下さい。 + +:handshake: +技術サービス +------------------------ + +`LVGL +LLC <https://www.digikey.com/en/design-services-providers/lvgl-kft>`__ +は、LVGLライブラリの確かな背景を元に、UI開発のための様々な技術サービスを提供するために設立されました。 +UIとグラフィックス業界における15年以上の実績を活かし、UIを次のレベルに引き上げるお手伝いを致します。 + +- **グラフィックデザイン** + 当社のグラフィックデザイナーは、製品とハードウェアのリソースに合わせて美しくモダンなデザインにするエキスパートです。 +- **UI実装** + お客様または弊社で作成したデザインを元に、UIを実装することも可能です。お客様のハードウェアとLVGLを最大限に活用することをお約束します。 + LVGLにない機能やウィジェットは、私たちが実装しますのでご安心ください。 +- **コンサルタント＆技術サポート** + UI開発において、価格と時間を要する作業でのリスクを減らすため、コンサルティングも含めてサポート致します。 +- **Board certification** development board または production ready kit + を提供している企業に対しては、ボードがLVGLを実行できるようにするためのボード認定を行います。 + +サンプルは +`Demos <https://lvgl-io.translate.goog/demos?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ +をご覧ください。 詳しくは `Services +page <https://lvgl-io.translate.goog/services?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ +をご覧ください。 + +お問い合わせは `問い合わせフォーム <https://lvgl.io/#contact>`__ :gb: +より送信して下さい。 + +:star2: +協力 +------------ + +LVGLはオープンプロジェクトであり、協力は大歓迎です。 +色々な方法で協力できます。 協力方法の例 - +LVGLを使用した作品やプロジェクトの公表 - サンプルプログラムの作成 - +ドキュメントの改善 - バグの修正 + +協力方法の詳細については、ドキュメントの `Contributing +section <https://docs-lvgl-io.translate.goog/master/CONTRIBUTING.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__ +をご覧ください。 + +すでに 300人以上がLVGLに足跡を残しています。いっしょに活動しましょう! +:slightly_smiling_face: + +… and many other. diff --git a/docs/README_pt_BR.md b/docs/README_pt_BR.md deleted file mode 100644 index 1d9f76a84..000000000 --- a/docs/README_pt_BR.md +++ /dev/null @@ -1,451 +0,0 @@ -**NOTA IMPORTANTE** A próxima versão principal (v9.0.0) está sendo desenvolvida na branch master. -A última versão estável está disponível na branch [release/v8.3](https://github.com/lvgl/lvgl/tree/release/v8.3). - ---- - -<a href="https://opencollective.com/lvgl" target="_blank"><img align="left" src="https://lvgl.io/assets/images/sponsor.png" height="32px"></a> - -<p align="right"> - <a href="../README.md">English</a> | - <a href="./README_zh.md">中文</a> | - <b>Português do Brasil</b> | - <a href="./README_jp.md">日本語</a> -</p> - -<p align="center"> - <img src="https://lvgl.io/assets/images/logo_lvgl.png"> -</p> - - <h1 align="center">LVGL - Biblioteca gráfica leve e versátil</h1> - <br> -<div align="center"> - <img src="https://github.com/kisvegabor/test/raw/master/smartwatch_demo.gif"> - - <img border="1px" src="https://lvgl.io/assets/images/lvgl_widgets_demo.gif"> -</div> -<br> -<p align="center"> - <a href="https://lvgl.io" title="Página inicial do LVGL">Site</a> | - <a href="https://docs.lvgl.io/" title="Documentação detalhada com +100 exemplos">Documentação</a> | - <a href="https://forum.lvgl.io" title="Obtenha ajuda e ajude outras pessoas">Fórum</a> | - <a href="https://lvgl.io/services" title="Design gráfico, implementações e consultoria de serviços">Serviços</a> | - <a href="https://lvgl.io/demos" title="Execute demonstrações no seu navegador">Demonstrações</a> | - <a href="https://squareline.io/" title="Editor web para LVGL">Editor SquareLine Studio</a> -</p> -<br> - -## :monocle_face: Visão Geral - -**Maduro e popular** - -LVGL é a biblioteca gráfica incorporada gratuita e de código aberto mais popular para criar belas interfaces de usuário para qualquer display do tipo MCU, MPU. Ela é suportada por fornecedores e projetos líderes do setor, como ARM, STM32, NXP, Espressif, Nuvoton, Arduino, RT-Thread, Zephyr, NuttX, Adafruit e muitos outros. - -**Rico em recursos** - -Ela tem todos os recursos para a criação de GUIs modernas e bonitas: mais de 30 widgets integrados, um sistema de design poderoso, gerenciadores de layout inspirados na web e um sistema de tipografia com suporte para vários idiomas. Para integrar o LVGL em sua plataforma, tudo que você precisa é de pelo menos 32kB de RAM e 128kB de Flash, um compilador C, um frame buffer e pelo menos uma tela de tamanho 1/10 para renderização. - -**Editor UI profissional** - -SquareLine Studio é um editor de interface do usuário de (arrasta e solta) profissional para LVGL. Ele roda em Windows, Linux e MacOS também e você pode experimentá-lo sem se registrar no site. - -**Serviços** - -Nossa equipe está pronta para ajudá-lo com design gráfico, implementação de UI e serviços de consultoria. Entre em contato conosco se precisar de algum suporte durante o desenvolvimento de seu próximo projeto de GUI. - -## :rocket: Recursos - -**Gratuito e portátil** - - - Uma biblioteca C totalmente portátil (compatível com C++) sem dependências externas. - - Pode ser compilado para qualquer display MCU ou MPU, e qualquer sistema operacional de tempo real (RT-OS). - - Suporta monitores monocromáticos, ePaper, OLED ou TFT. [Guia de portabilidade](https://docs.lvgl.io/master/porting/project.html) - - Distribuído sob a licença do MIT, para que você também possa usá-lo facilmente em projetos comerciais. - - Precisa de apenas 32 kB de RAM e 128 kB de Flash, um frame buffer e pelo menos uma tela de tamanho 1/10 para renderização. - - Sistemas operacionais, memória externa e GPU são suportados, mas não obrigatórios. - -**Widgets, designs, layouts e muito mais** - - - Mais de 30 widgets integrados: botão, etiqueta (label), controle deslizante (slider), gráfico (chart), teclado, medidor (meter), tabelas e muito mais. - - Sistema de design flexível com pelo menos 100 propriedades de estilo para personalizar qualquer parte dos widgets. - - Mecanismos de layouts Flexbox e Grid para dimensionar e posicionar automaticamente os widgets de maneira responsiva. - - Os textos são renderizados com codificação UTF-8, suportando sistemas de escrita CJK (chinês, japonês e coreano), tailandês, hindi, árabe e persa. - - Quebra de palavras (word wrapping), espaçamento entre letras (kerning), rolagem de texto (scrolling), renderização subpixel, entrada em chinês Pinyin-IME e emojis. - - Mecanismo de renderização que suporta animações, anti-aliasing, opacidade, rolagem suave (smooth scroll), sombras, transformação de imagens, etc. - - Suporta mouse, touchpad, teclado, botões externos, dispositivos de entrada codificadores (encoders). - - Suporta vários monitores. - -**Suporte de vinculação (binding) e compilação de arquivos** - - - Exposição da API do LVGL com o [Micropython](https://blog.lvgl.io/2019-02-20/micropython-bindings) - - Nenhum sistema de compilação personalizado é usado. Você pode construir o LVGL enquanto constrói os outros arquivos do seu projeto. - - O suporte para Make e [CMake](https://docs.lvgl.io/master/get-started/platforms/cmake.html) já vem incluído. - - [Desenvolva no PC](https://docs.lvgl.io/master/get-started/platforms/pc-simulator.html) e use o mesmo código de interface do usuário em hardwares incorporados (embedded hardware). - - Converta o código C para um arquivo HTML com o [Emscripten port](https://github.com/lvgl/lv_web_emscripten). - -**Documentação, ferramentas e serviços** - - - Documentação detalhada com [+100 exemplos simples](https://docs.lvgl.io/master/index.html) - - [SquareLine Studio](https://squareline.io) - Um software editor UI profissional e fácil de usar, para acelerar e simplificar o desenvolvimento da interface do usuário. - - [Serviços](https://lvgl.io/services) como design de UI, implementação e consultoria para tornar o desenvolvimento de UI mais simples e rápido. - -## :heart: Patrocinador - -Se o LVGL economizou muito tempo e dinheiro ou você apenas se divertiu ao usá-lo, considere Apoiar o desenvolvimento. - -**Como e com o que utilizamos os recursos doados?** -Nosso objetivo é fornecer compensação financeira para as pessoas que mais fazem pelo LVGL. Isso significa que não apenas os mantenedores, mas qualquer pessoa que implemente um ótimo recurso deve receber um pagamento com o dinheiro acumulado. Usamos as doações para cobrir nossos custos operacionais, como servidores e serviços relacionados. - -**Como doar?** -Usamos o [Open Collective](https://opencollective.com/lvgl), onde você pode enviar facilmente doações únicas ou recorrentes. Você também pode ver todas as nossas despesas de forma transparente. - -**Como receber o pagamento de sua contribuição?** -Se alguém implementar ou corrigir um problema rotulado como [Patrocinado](https://github.com/lvgl/lvgl/labels/Sponsored), essa pessoa receberá um pagamento por esse trabalho. Estimamos o tempo necessário, a complexidade e a importância da questão e definimos um preço de acordo. Para entrar, apenas comente sobre um problema patrocinado dizendo "Olá, gostaria de lidar com isso. É assim que estou planejando corrigi-lo/implementá-lo...". Um trabalho é considerado pronto quando é aprovado e mesclado por um mantenedor. Depois disso, você pode enviar uma "despesa" (expense) pela plataforma [opencollective.com](https://opencollective.com/lvgl) e então receberá o pagamento em alguns dias. - -**Organizações que apoiam o projeto LVGL**<br> -[](https://opencollective.com/lvgl) - -**Pessoas que apoiam o projeto LVGL**<br> -[](https://opencollective.com/lvgl) - -## :package: Pacotes - -LVGL está disponível para: - -- [Arduino library](https://docs.lvgl.io/master/get-started/platforms/arduino.html) -- [PlatformIO package](https://registry.platformio.org/libraries/lvgl/lvgl) -- [Zephyr library](https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_LVGL) -- [ESP32 component](https://docs.lvgl.io/master/get-started/platforms/espressif.html) -- [NXP MCUXpresso component](https://www.nxp.com/design/software/embedded-software/lvgl-open-source-graphics-library:LITTLEVGL-OPEN-SOURCE-GRAPHICS-LIBRARY) -- [NuttX library](https://docs.lvgl.io/master/get-started/os/nuttx.html) -- [RT-Thread RTOS](https://docs.lvgl.io/master/get-started/os/rt-thread.html) -- NXP MCUXpresso library -- CMSIS-Pack - -## :man_technologist: Exemplos - -Veja como criar um botão com um evento de clique em C e MicroPython. Para mais exemplos, veja a pasta [examples](https://github.com/lvgl/lvgl/tree/master/examples). - - - -### Botão com evento de clique - - - -<details> - <summary>Código C</summary> - -```c -lv_obj_t * btn = lv_btn_create(lv_scr_act()); /* Adiciona o botão a tela atual */ -lv_obj_center(btn); /* Define a posição do botão */ -lv_obj_set_size(btn, 100, 50); /* Define o tamanho do botão */ -lv_obj_add_event(btn, btn_event_cb, LV_EVENT_CLICKED, NULL); /* Atribui um retorno de chamada (callback) ao botão */ - -lv_obj_t * label = lv_label_create(btn); /* Adiciona um rótulo (label) */ -lv_label_set_text(label, "Botão"); /* Define um texto para o rótulo (label) */ -lv_obj_center(label); /* Alinha o texto no centro do botão */ -... - -void btn_event_cb(lv_event_t * e) -{ - printf("Clicado\n"); -} -``` -</details> - -<details> - <summary>Código MicroPython | <a href="https://sim.lvgl.io/v8.3/micropython/ports/javascript/index.html?script_startup=https://raw.githubusercontent.com/lvgl/lvgl/0d9ab4ee0e591aad1970e3c9164fd7c544ecce70/examples/header.py&script=https://raw.githubusercontent.com/lvgl/lvgl/0d9ab4ee0e591aad1970e3c9164fd7c544ecce70/examples/widgets/slider/lv_example_slider_2.py&script_direct=926bde43ec7af0146c486de470c53f11f167491e" target="_blank">Simulador online</a></summary> - -```python -def btn_event_cb(e): - print("Clicado") - -# Cria um botão e um rótulo (label) -btn = lv.btn(lv.scr_act()) -btn.center() -btn.set_size(100, 50) -btn.add_event(btn_event_cb, lv.EVENT.CLICKED, None) - -label = lv.label(btn) -label.set_text("Botão") -label.center() -``` -</details> -<br> - -### Caixas de seleção (chackboxes) com layout - - -<details> - <summary>Código em C</summary> - -```c - -lv_obj_set_flex_flow(lv_scr_act(), LV_FLEX_FLOW_COLUMN); -lv_obj_set_flex_align(lv_scr_act(), LV_FLEX_ALIGN_CENTER, LV_FLEX_ALIGN_START, LV_FLEX_ALIGN_CENTER); - -lv_obj_t * cb; -cb = lv_checkbox_create(lv_scr_act()); -lv_checkbox_set_text(cb, "Maça"); -lv_obj_add_event(cb, event_handler, LV_EVENT_ALL, NULL); - -cb = lv_checkbox_create(lv_scr_act()); -lv_checkbox_set_text(cb, "Banana"); -lv_obj_add_state(cb, LV_STATE_CHECKED); -lv_obj_add_event(cb, event_handler, LV_EVENT_ALL, NULL); - -cb = lv_checkbox_create(lv_scr_act()); -lv_checkbox_set_text(cb, "Limão"); -lv_obj_add_state(cb, LV_STATE_DISABLED); -lv_obj_add_event(cb, event_handler, LV_EVENT_ALL, NULL); - -cb = lv_checkbox_create(lv_scr_act()); -lv_obj_add_state(cb, LV_STATE_CHECKED | LV_STATE_DISABLED); -lv_checkbox_set_text(cb, "Melão\ne uma nova linha"); -lv_obj_add_event(cb, event_handler, LV_EVENT_ALL, NULL); -``` -</details> - -<details> - <summary>Código MicroPython | <a href="https://sim.lvgl.io/v8.3/micropython/ports/javascript/index.html?script_startup=https://raw.githubusercontent.com/lvgl/lvgl/0d9ab4ee0e591aad1970e3c9164fd7c544ecce70/examples/header.py&script=https://raw.githubusercontent.com/lvgl/lvgl/0d9ab4ee0e591aad1970e3c9164fd7c544ecce70/examples/widgets/slider/lv_example_slider_2.py&script_direct=311d37e5f70daf1cb0d2cad24c7f72751b5f1792" target="_blank">Online Simulator</a></summary> - -```python -def event_handler(e): - code = e.get_code() - obj = e.get_target_obj() - if code == lv.EVENT.VALUE_CHANGED: - txt = obj.get_text() - if obj.get_state() & lv.STATE.CHECKED: - state = "Marcador" - else: - state = "Desmarcado" - print(txt + ":" + state) - - -lv.scr_act().set_flex_flow(lv.FLEX_FLOW.COLUMN) -lv.scr_act().set_flex_align(lv.FLEX_ALIGN.CENTER, lv.FLEX_ALIGN.START, lv.FLEX_ALIGN.CENTER) - -cb = lv.checkbox(lv.scr_act()) -cb.set_text("Maça") -cb.add_event(event_handler, lv.EVENT.ALL, None) - -cb = lv.checkbox(lv.scr_act()) -cb.set_text("Banana") -cb.add_state(lv.STATE.CHECKED) -cb.add_event(event_handler, lv.EVENT.ALL, None) - -cb = lv.checkbox(lv.scr_act()) -cb.set_text("Limão") -cb.add_state(lv.STATE.DISABLED) -cb.add_event(event_handler, lv.EVENT.ALL, None) - -cb = lv.checkbox(lv.scr_act()) -cb.add_state(lv.STATE.CHECKED | lv.STATE.DISABLED) -cb.set_text("Melão") -cb.add_event(event_handler, lv.EVENT.ALL, None) -``` - -</details> -<br> - -### Estilizando um controle deslizante (slider) - - - -<details> - <summary>Código C</summary> - -```c -lv_obj_t * slider = lv_slider_create(lv_scr_act()); -lv_slider_set_value(slider, 70, LV_ANIM_OFF); -lv_obj_set_size(slider, 300, 20); -lv_obj_center(slider); - -/* Adiciona estilos locais à parte MAIN (retângulo de fundo) */ -lv_obj_set_style_bg_color(slider, lv_color_hex(0x0F1215), LV_PART_MAIN); -lv_obj_set_style_bg_opa(slider, 255, LV_PART_MAIN); -lv_obj_set_style_border_color(slider, lv_color_hex(0x333943), LV_PART_MAIN); -lv_obj_set_style_border_width(slider, 5, LV_PART_MAIN); -lv_obj_set_style_pad_all(slider, 5, LV_PART_MAIN); - -/* Crie uma folha de estilo reutilizável para a parte do (INDICADOR) */ -static lv_style_t style_indicator; -lv_style_init(&style_indicator); -lv_style_set_bg_color(&style_indicator, lv_color_hex(0x37B9F5)); -lv_style_set_bg_grad_color(&style_indicator, lv_color_hex(0x1464F0)); -lv_style_set_bg_grad_dir(&style_indicator, LV_GRAD_DIR_HOR); -lv_style_set_shadow_color(&style_indicator, lv_color_hex(0x37B9F5)); -lv_style_set_shadow_width(&style_indicator, 15); -lv_style_set_shadow_spread(&style_indicator, 5); - -/* Adicione a folha de estilo à parte do INDICATOR do controle deslizante (slider) */ -lv_obj_add_style(slider, &style_indicator, LV_PART_INDICATOR); - -/* Adicione o mesmo estilo à parte do KNOB e sobrescreva localmente algumas propriedades */ -lv_obj_add_style(slider, &style_indicator, LV_PART_KNOB); - -lv_obj_set_style_outline_color(slider, lv_color_hex(0x0096FF), LV_PART_KNOB); -lv_obj_set_style_outline_width(slider, 3, LV_PART_KNOB); -lv_obj_set_style_outline_pad(slider, -5, LV_PART_KNOB); -lv_obj_set_style_shadow_spread(slider, 2, LV_PART_KNOB); -``` - -</details> - -<details> - <summary>Código MicroPython | -<a href="https://sim.lvgl.io/v8.3/micropython/ports/javascript/index.html?script_startup=https://raw.githubusercontent.com/lvgl/lvgl/0d9ab4ee0e591aad1970e3c9164fd7c544ecce70/examples/header.py&script=https://raw.githubusercontent.com/lvgl/lvgl/0d9ab4ee0e591aad1970e3c9164fd7c544ecce70/examples/widgets/slider/lv_example_slider_2.py&script_direct=c431c7b4dfd2cc0dd9c392b74365d5af6ea986f0" target="_blank">Simulador online</a> -</summary> - - -```python -# Crie um controle deslizante (slider) e adicione o estilo -slider = lv.slider(lv.scr_act()) -slider.set_value(70, lv.ANIM.OFF) -slider.set_size(300, 20) -slider.center() - -# Adicione estilos locais à parte MAIN (retângulo de fundo) -slider.set_style_bg_color(lv.color_hex(0x0F1215), lv.PART.MAIN) -slider.set_style_bg_opa(255, lv.PART.MAIN) -slider.set_style_border_color(lv.color_hex(0x333943), lv.PART.MAIN) -slider.set_style_border_width(5, lv.PART.MAIN) -slider.set_style_pad_all(5, lv.PART.MAIN) - -# Crie uma folha de estilo reutilizável para a parte do INDICATOR -style_indicator = lv.style_t() -style_indicator.init() -style_indicator.set_bg_color(lv.color_hex(0x37B9F5)) -style_indicator.set_bg_grad_color(lv.color_hex(0x1464F0)) -style_indicator.set_bg_grad_dir(lv.GRAD_DIR.HOR) -style_indicator.set_shadow_color(lv.color_hex(0x37B9F5)) -style_indicator.set_shadow_width(15) -style_indicator.set_shadow_spread(5) - -# Adicione a folha de estilo à parte do INDICATOR do controle deslizante (slider) -slider.add_style(style_indicator, lv.PART.INDICATOR) -slider.add_style(style_indicator, lv.PART.KNOB) - -# Adicione o mesmo estilo à parte do KNOB e sobrescreva localmente algumas propriedades -slider.set_style_outline_color(lv.color_hex(0x0096FF), lv.PART.KNOB) -slider.set_style_outline_width(3, lv.PART.KNOB) -slider.set_style_outline_pad(-5, lv.PART.KNOB) -slider.set_style_shadow_spread(2, lv.PART.KNOB) -``` - -</details> -<br> - -### Textos em inglês, hebraico (LRT-RTL misto) e chinês - - - -<details> - <summary>Código C</summary> - -```c -lv_obj_t * ltr_label = lv_label_create(lv_scr_act()); -lv_label_set_text(ltr_label, "In modern terminology, a microcontroller is similar to a system on a chip (SoC)."); -lv_obj_set_style_text_font(ltr_label, &lv_font_montserrat_16, 0); -lv_obj_set_width(ltr_label, 310); -lv_obj_align(ltr_label, LV_ALIGN_TOP_LEFT, 5, 5); - -lv_obj_t * rtl_label = lv_label_create(lv_scr_act()); -lv_label_set_text(rtl_label,"מעבד, או בשמו המלא יחידת עיבוד מרכזית (באנגלית: CPU - Central Processing Unit)."); -lv_obj_set_style_base_dir(rtl_label, LV_BASE_DIR_RTL, 0); -lv_obj_set_style_text_font(rtl_label, &lv_font_dejavu_16_persian_hebrew, 0); -lv_obj_set_width(rtl_label, 310); -lv_obj_align(rtl_label, LV_ALIGN_LEFT_MID, 5, 0); - -lv_obj_t * cz_label = lv_label_create(lv_scr_act()); -lv_label_set_text(cz_label, - "嵌入式系统（Embedded System），\n是一种嵌入机械或电气系统内部、具有专一功能和实时计算性能的计算机系统。"); -lv_obj_set_style_text_font(cz_label, &lv_font_simsun_16_cjk, 0); -lv_obj_set_width(cz_label, 310); -lv_obj_align(cz_label, LV_ALIGN_BOTTOM_LEFT, 5, -5); -``` - -</details> - -<details> - <summary>Código MicroPython | <a href="https://sim.lvgl.io/v8.3/micropython/ports/javascript/index.html?script_startup=https://raw.githubusercontent.com/lvgl/lvgl/0d9ab4ee0e591aad1970e3c9164fd7c544ecce70/examples/header.py&script=https://raw.githubusercontent.com/lvgl/lvgl/0d9ab4ee0e591aad1970e3c9164fd7c544ecce70/examples/widgets/slider/lv_example_slider_2.py&script_direct=18bb38200a64e10ead1aa17a65c977fc18131842" target="_blank">Simulador online</a></summary> - -```python -ltr_label = lv.label(lv.scr_act()) -ltr_label.set_text("In modern terminology, a microcontroller is similar to a system on a chip (SoC).") -ltr_label.set_style_text_font(lv.font_montserrat_16, 0); - -ltr_label.set_width(310) -ltr_label.align(lv.ALIGN.TOP_LEFT, 5, 5) - -rtl_label = lv.label(lv.scr_act()) -rtl_label.set_text("מעבד, או בשמו המלא יחידת עיבוד מרכזית (באנגלית: CPU - Central Processing Unit).") -rtl_label.set_style_base_dir(lv.BASE_DIR.RTL, 0) -rtl_label.set_style_text_font(lv.font_dejavu_16_persian_hebrew, 0) -rtl_label.set_width(310) -rtl_label.align(lv.ALIGN.LEFT_MID, 5, 0) - -font_simsun_16_cjk = lv.font_load("S:../../assets/font/lv_font_simsun_16_cjk.fnt") - -cz_label = lv.label(lv.scr_act()) -cz_label.set_style_text_font(font_simsun_16_cjk, 0) -cz_label.set_text("嵌入式系统（Embedded System），\n是一种嵌入机械或电气系统内部、具有专一功能和实时计算性能的计算机系统。") -cz_label.set_width(310) -cz_label.align(lv.ALIGN.BOTTOM_LEFT, 5, -5) - -``` -</details> - -## :arrow_forward: Começando -Esta lista irá guiá-lo para começar com o LVGL passo a passo. - -**Familiarize-se com o LVGL** - - 1. Confira as [demos on-line](https://lvgl.io/demos) para ver o LVGL em ação (~3 minutos) - 2. Leia a página de [introdução](https://docs.lvgl.io/master/intro/index.html) da documentação (~5 minutos) - 3. Familiarize-se com o básico na página de [visão geral rápida](https://docs.lvgl.io/master/get-started/quick-overview.html) (~15 minutos) - -**Começando a usar o LVGL** - - 4. Configure um [simulador](https://docs.lvgl.io/master/get-started/platforms/pc-simulator.html) (~10 minutos) - 5. Experimente alguns [exemplos](https://github.com/lvgl/lvgl/tree/master/examples) - 6. Porte o LVGL para uma placa. Veja o guia [portando o LVGL](https://docs.lvgl.io/master/porting/index.html) ou veja um projeto pronto para usar em [projetos](https://github.com/lvgl?q=lv_port_) - -**Torne-se um profissional** - - 7. Leia a página [visão geral](https://docs.lvgl.io/master/overview/index.html) para entender melhor a biblioteca (~2-3 horas) - 8. Verifique a documentação dos [widgets](https://docs.lvgl.io/master/widgets/index.html) para ver seus recursos e usabilidade - -**Obtenha ajuda e ajude outras pessoas** - - 9. Se você tiver dúvidas, acesse o [Fórum](http://forum.lvgl.io) - 10. Leia o guia de [contribuição](https://docs.lvgl.io/master/CONTRIBUTING.html) para ver como você pode ajudar a melhorar o LVGL (~15 minutos) - -**E mais** - - 11. Baixe e experimente o editor [SquareLine Studio](https://squareline.io). - 12. Entre em contato conosco para [serviços e consultoria](https://lvgl.io/services). - -## :handshake: Serviços -A LVGL LLC foi criada para fornecer uma base sólida para a biblioteca LVGL e oferecer vários tipos de serviços para ajudá-lo no desenvolvimento da sua interface do usuário. Com mais de 15 anos de experiência na indústria gráfica e de interface do usuário, podemos ajudá-lo a levar sua interface do usuário para o próximo nível. - -- **Design gráfico**: Nossos designers gráficos internos são especialistas em criar belos designs modernos que se adaptam ao seu produto e aos recursos do seu hardware. -- **Implementação da interface do usuário**: Também podemos implementar sua interface do usuário com base no design que você ou nós criamos. Você pode ter certeza de que tiraremos o máximo proveito de seu hardware e do LVGL. Se um recurso ou widget estiver faltando no LVGL, não se preocupe, nós o implementaremos para você. -- **Consultoria e Suporte**: Também podemos apoiá-lo com consultoria para evitar erros que podem te custar caros durante o desenvolvimento da sua interface do usuário. -- **Certificação**: Para empresas que oferecem placas para desenvolvimento ou kits prontos para produção, fazemos certificação que mostram como uma placa pode executar o LVGL. - -Confira nossas [demonstrações](https://lvgl.io/demos) como referência. Para obter mais informações, consulte a [página de serviços](https://lvgl.io/services). - -[Fale conosco](https://lvgl.io/#contact) e conte como podemos ajudar. - -## :star2: Contribuindo -O LVGL é um projeto aberto e sua contribuição é muito bem-vinda. Há muitas maneiras de contribuir, desde simplesmente falando sobre seu projeto, escrevendo exemplos, melhorando a documentação, corrigindo bugs até hospedar seu próprio projeto sob a organização LVGL. - -Para obter uma descrição detalhada das oportunidades de contribuição, visite a página de [contribuição](https://docs.lvgl.io/master/CONTRIBUTING.html) da documentação. - -Mais de 300 pessoas já deixaram sua impressão digital no LVGL. Seja um deles! Veja o seu aqui! :slightly_smiling_face: - -<a href="https://github.com/lvgl/lvgl/graphs/contributors"> - <img src="https://contrib.rocks/image?repo=lvgl/lvgl&max=48" /> -</a> - -... e muitos outros. diff --git a/docs/README_pt_BR.rst.back b/docs/README_pt_BR.rst.back new file mode 100644 index 000000000..84a80f8f2 --- /dev/null +++ b/docs/README_pt_BR.rst.back @@ -0,0 +1,708 @@ +:note: **NOTA IMPORTANTE** A próxima versão principal (v9.0.0) está sendo + desenvolvida na branch master. A última versão estável está disponível + na branch `release/v8.3 <https://github.com/lvgl/lvgl/tree/release/v8.3>`__. + +-------------- + +.. raw:: html + + <p align="right"> + +English \| 中文 \| Português do Brasil \| 日本語 + +.. raw:: html + + </p> + +.. raw:: html + + <p align="center"> + + + +.. raw:: html + + </p> + + + +.. raw:: html + + <h1 align="center"> + +LVGL - Biblioteca gráfica leve e versátil + +.. raw:: html + + </h1> + + + +.. raw:: html + + <p align="center"> + + Site \| Documentação \| Fórum \| Serviços \| Demonstrações \| Editor SquareLine Studio + +.. raw:: html + + </p> + +**Visão Geral** +--------------- + +**Maduro e popular** + +LVGL é a biblioteca gráfica incorporada gratuita e de código aberto mais +popular para criar belas interfaces de usuário para qualquer display do +tipo MCU, MPU. Ela é suportada por fornecedores e projetos líderes do +setor, como ARM, STM32, NXP, Espressif, Nuvoton, Arduino, RT-Thread, +Zephyr, NuttX, Adafruit e muitos outros. + +**Rico em recursos** + +Ela tem todos os recursos para a criação de GUIs modernas e bonitas: +mais de 30 widgets integrados, um sistema de design poderoso, +gerenciadores de layout inspirados na web e um sistema de tipografia com +suporte para vários idiomas. Para integrar o LVGL em sua plataforma, +tudo que você precisa é de pelo menos 32kB de RAM e 128kB de Flash, um +compilador C, um frame buffer e pelo menos uma tela de tamanho 1/10 para +renderização. + +**Editor UI profissional** + +SquareLine Studio é um editor de interface do usuário de (arrasta e +solta) profissional para LVGL. Ele roda em Windows, Linux e MacOS também +e você pode experimentá-lo sem se registrar no site. + +**Serviços** + +Nossa equipe está pronta para ajudá-lo com design gráfico, implementação +de UI e serviços de consultoria. Entre em contato conosco se precisar de +algum suporte durante o desenvolvimento de seu próximo projeto de GUI. + +**Recursos** +------------ + +**Gratuito e portátil** + +- Uma biblioteca C totalmente portátil (compatível com C++) sem + dependências externas. +- Pode ser compilado para qualquer display MCU ou MPU, e qualquer + sistema operacional de tempo real (RT-OS). +- Suporta monitores monocromáticos, ePaper, OLED ou TFT. `Guia de + portabilidade <https://docs.lvgl.io/master/porting/project.html>`__ +- Distribuído sob a licença do MIT, para que você também possa usá-lo + facilmente em projetos comerciais. +- Precisa de apenas 32 kB de RAM e 128 kB de Flash, um frame buffer e + pelo menos uma tela de tamanho 1/10 para renderização. +- Sistemas operacionais, memória externa e GPU são suportados, mas não + obrigatórios. + +**Widgets, designs, layouts e muito mais** + +- Mais de 30 widgets integrados: botão, etiqueta (label), controle + deslizante (slider), gráfico (chart), teclado, medidor (meter), + tabelas e muito mais. +- Sistema de design flexível com pelo menos 100 propriedades de estilo + para personalizar qualquer parte dos widgets. +- Mecanismos de layouts Flexbox e Grid para dimensionar e posicionar + automaticamente os widgets de maneira responsiva. +- Os textos são renderizados com codificação UTF-8, suportando sistemas + de escrita CJK (chinês, japonês e coreano), tailandês, hindi, árabe e + persa. +- Quebra de palavras (word wrapping), espaçamento entre letras + (kerning), rolagem de texto (scrolling), renderização subpixel, + entrada em chinês Pinyin-IME e emojis. +- Mecanismo de renderização que suporta animações, anti-aliasing, + opacidade, rolagem suave (smooth scroll), sombras, transformação de + imagens, etc. +- Suporta mouse, touchpad, teclado, botões externos, dispositivos de + entrada codificadores (encoders). +- Suporta vários monitores. + +**Suporte de vinculação (binding) e compilação de arquivos** + +- Exposição da API do LVGL com o + `Micropython <https://blog.lvgl.io/2019-02-20/micropython-bindings>`__ +- Nenhum sistema de compilação personalizado é usado. Você pode + construir o LVGL enquanto constrói os outros arquivos do seu projeto. +- O suporte para Make e + `CMake <https://docs.lvgl.io/master/get-started/platforms/cmake.html>`__ + já vem incluído. +- `Desenvolva no + PC <https://docs.lvgl.io/master/get-started/platforms/pc-simulator.html>`__ + e use o mesmo código de interface do usuário em hardwares + incorporados (embedded hardware). +- Converta o código C para um arquivo HTML com o `Emscripten + port <https://github.com/lvgl/lv_web_emscripten>`__. + +**Documentação, ferramentas e serviços** + +- Documentação detalhada com `+100 exemplos + simples <https://docs.lvgl.io/master/index.html>`__ +- `SquareLine Studio <https://squareline.io>`__ - Um software editor UI + profissional e fácil de usar, para acelerar e simplificar o + desenvolvimento da interface do usuário. +- `Serviços <https://lvgl.io/services>`__ como design de UI, + implementação e consultoria para tornar o desenvolvimento de UI mais + simples e rápido. + +**Patrocinador** +---------------- + +Se o LVGL economizou muito tempo e dinheiro ou você apenas se divertiu +ao usá-lo, considere Apoiar o desenvolvimento. + +**Como e com o que utilizamos os recursos doados?** Nosso objetivo é +fornecer compensação financeira para as pessoas que mais fazem pelo +LVGL. Isso significa que não apenas os mantenedores, mas qualquer pessoa +que implemente um ótimo recurso deve receber um pagamento com o dinheiro +acumulado. Usamos as doações para cobrir nossos custos operacionais, +como servidores e serviços relacionados. + +**Como doar?** Usamos o `Open +Collective <https://opencollective.com/lvgl>`__, onde você pode enviar +facilmente doações únicas ou recorrentes. Você também pode ver todas as +nossas despesas de forma transparente. + +**Como receber o pagamento de sua contribuição?** Se alguém implementar +ou corrigir um problema rotulado como +`Patrocinado <https://github.com/lvgl/lvgl/labels/Sponsored>`__, essa +pessoa receberá um pagamento por esse trabalho. Estimamos o tempo +necessário, a complexidade e a importância da questão e definimos um +preço de acordo. Para entrar, apenas comente sobre um problema +patrocinado dizendo “Olá, gostaria de lidar com isso. É assim que estou +planejando corrigi-lo/implementá-lo…”. Um trabalho é considerado pronto +quando é aprovado e mesclado por um mantenedor. Depois disso, você pode +enviar uma “despesa” (expense) pela plataforma +`opencollective.com <https://opencollective.com/lvgl>`__ e então +receberá o pagamento em alguns dias. + +**Organizações que apoiam o projeto LVGL**\ |Patrocinadores do LVGL| + +**Pessoas que apoiam o projeto LVGL**\ |Backers of LVGL| + +**Pacotes** +----------- + +LVGL está disponível para: + +- `Arduino + library <https://docs.lvgl.io/master/get-started/platforms/arduino.html>`__ +- `PlatformIO + package <https://registry.platformio.org/libraries/lvgl/lvgl>`__ +- `Zephyr + library <https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_LVGL>`__ +- `ESP32 + component <https://docs.lvgl.io/master/get-started/platforms/espressif.html>`__ +- `NXP MCUXpresso + component <https://www.nxp.com/design/software/embedded-software/lvgl-open-source-graphics-library:LITTLEVGL-OPEN-SOURCE-GRAPHICS-LIBRARY>`__ +- `NuttX + library <https://docs.lvgl.io/master/get-started/os/nuttx.html>`__ +- `RT-Thread + RTOS <https://docs.lvgl.io/master/get-started/os/rt-thread.html>`__ +- NXP MCUXpresso library +- CMSIS-Pack + +**Exemplos** +------------ + +Veja como criar um botão com um evento de clique em C e MicroPython. +Para mais exemplos, veja a pasta +`examples <https://github.com/lvgl/lvgl/tree/master/examples>`__. + +.. figure:: https://github.com/lvgl/lvgl/raw/master/docs/misc/btn_example.png + :alt: LVGL button with label example + + LVGL button with label example + +Botão com evento de clique +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: https://github.com/kisvegabor/test/raw/master/readme_example_1.gif + :alt: Botão LVGL com exemplo de rótulo (label) + + Botão LVGL com exemplo de rótulo (label) + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +Código C + +.. raw:: html + + </summary> + +.. code:: c + + lv_obj_t * btn = lv_btn_create(lv_scr_act()); /* Adiciona o botão a tela atual */ + lv_obj_center(btn); /* Define a posição do botão */ + lv_obj_set_size(btn, 100, 50); /* Define o tamanho do botão */ + lv_obj_add_event(btn, btn_event_cb, LV_EVENT_CLICKED, NULL); /* Atribui um retorno de chamada (callback) ao botão */ + + lv_obj_t * label = lv_label_create(btn); /* Adiciona um rótulo (label) */ + lv_label_set_text(label, "Botão"); /* Define um texto para o rótulo (label) */ + lv_obj_center(label); /* Alinha o texto no centro do botão */ + ... + + void btn_event_cb(lv_event_t * e) + { + printf("Clicado\n"); + } + +.. raw:: html + + </details> + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +Código MicroPython \| Simulador online + +.. raw:: html + + </summary> + +.. code:: python + + def btn_event_cb(e): + print("Clicado") + + # Cria um botão e um rótulo (label) + btn = lv.btn(lv.scr_act()) + btn.center() + btn.set_size(100, 50) + btn.add_event(btn_event_cb, lv.EVENT.CLICKED, None) + + label = lv.label(btn) + label.set_text("Botão") + label.center() + +.. raw:: html + + </details> + +Caixas de seleção (chackboxes) com layout +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: https://github.com/kisvegabor/test/raw/master/readme_example_2.gif + :alt: Caixas de seleção (chackboxes) com layout no LVGL + + Caixas de seleção (chackboxes) com layout no LVGL + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +Código em C + +.. raw:: html + + </summary> + +.. code:: c + + + lv_obj_set_flex_flow(lv_scr_act(), LV_FLEX_FLOW_COLUMN); + lv_obj_set_flex_align(lv_scr_act(), LV_FLEX_ALIGN_CENTER, LV_FLEX_ALIGN_START, LV_FLEX_ALIGN_CENTER); + + lv_obj_t * cb; + cb = lv_checkbox_create(lv_scr_act()); + lv_checkbox_set_text(cb, "Maça"); + lv_obj_add_event(cb, event_handler, LV_EVENT_ALL, NULL); + + cb = lv_checkbox_create(lv_scr_act()); + lv_checkbox_set_text(cb, "Banana"); + lv_obj_add_state(cb, LV_STATE_CHECKED); + lv_obj_add_event(cb, event_handler, LV_EVENT_ALL, NULL); + + cb = lv_checkbox_create(lv_scr_act()); + lv_checkbox_set_text(cb, "Limão"); + lv_obj_add_state(cb, LV_STATE_DISABLED); + lv_obj_add_event(cb, event_handler, LV_EVENT_ALL, NULL); + + cb = lv_checkbox_create(lv_scr_act()); + lv_obj_add_state(cb, LV_STATE_CHECKED | LV_STATE_DISABLED); + lv_checkbox_set_text(cb, "Melão\ne uma nova linha"); + lv_obj_add_event(cb, event_handler, LV_EVENT_ALL, NULL); + +.. raw:: html + + </details> + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +Código MicroPython \| Online Simulator + +.. raw:: html + + </summary> + +.. code:: python + + def event_handler(e): + code = e.get_code() + obj = e.get_target_obj() + if code == lv.EVENT.VALUE_CHANGED: + txt = obj.get_text() + if obj.get_state() & lv.STATE.CHECKED: + state = "Marcador" + else: + state = "Desmarcado" + print(txt + ":" + state) + + + lv.scr_act().set_flex_flow(lv.FLEX_FLOW.COLUMN) + lv.scr_act().set_flex_align(lv.FLEX_ALIGN.CENTER, lv.FLEX_ALIGN.START, lv.FLEX_ALIGN.CENTER) + + cb = lv.checkbox(lv.scr_act()) + cb.set_text("Maça") + cb.add_event(event_handler, lv.EVENT.ALL, None) + + cb = lv.checkbox(lv.scr_act()) + cb.set_text("Banana") + cb.add_state(lv.STATE.CHECKED) + cb.add_event(event_handler, lv.EVENT.ALL, None) + + cb = lv.checkbox(lv.scr_act()) + cb.set_text("Limão") + cb.add_state(lv.STATE.DISABLED) + cb.add_event(event_handler, lv.EVENT.ALL, None) + + cb = lv.checkbox(lv.scr_act()) + cb.add_state(lv.STATE.CHECKED | lv.STATE.DISABLED) + cb.set_text("Melão") + cb.add_event(event_handler, lv.EVENT.ALL, None) + +.. raw:: html + + </details> + +Estilizando um controle deslizante (slider) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: https://github.com/kisvegabor/test/raw/master/readme_example_3.gif + :alt: Estilizando um controle deslizante (slider) com LVGL + + Estilizando um controle deslizante (slider) com LVGL + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +Código C + +.. raw:: html + + </summary> + +.. code:: c + + lv_obj_t * slider = lv_slider_create(lv_scr_act()); + lv_slider_set_value(slider, 70, LV_ANIM_OFF); + lv_obj_set_size(slider, 300, 20); + lv_obj_center(slider); + + /* Adiciona estilos locais à parte MAIN (retângulo de fundo) */ + lv_obj_set_style_bg_color(slider, lv_color_hex(0x0F1215), LV_PART_MAIN); + lv_obj_set_style_bg_opa(slider, 255, LV_PART_MAIN); + lv_obj_set_style_border_color(slider, lv_color_hex(0x333943), LV_PART_MAIN); + lv_obj_set_style_border_width(slider, 5, LV_PART_MAIN); + lv_obj_set_style_pad_all(slider, 5, LV_PART_MAIN); + + /* Crie uma folha de estilo reutilizável para a parte do (INDICADOR) */ + static lv_style_t style_indicator; + lv_style_init(&style_indicator); + lv_style_set_bg_color(&style_indicator, lv_color_hex(0x37B9F5)); + lv_style_set_bg_grad_color(&style_indicator, lv_color_hex(0x1464F0)); + lv_style_set_bg_grad_dir(&style_indicator, LV_GRAD_DIR_HOR); + lv_style_set_shadow_color(&style_indicator, lv_color_hex(0x37B9F5)); + lv_style_set_shadow_width(&style_indicator, 15); + lv_style_set_shadow_spread(&style_indicator, 5); + + /* Adicione a folha de estilo à parte do INDICATOR do controle deslizante (slider) */ + lv_obj_add_style(slider, &style_indicator, LV_PART_INDICATOR); + + /* Adicione o mesmo estilo à parte do KNOB e sobrescreva localmente algumas propriedades */ + lv_obj_add_style(slider, &style_indicator, LV_PART_KNOB); + + lv_obj_set_style_outline_color(slider, lv_color_hex(0x0096FF), LV_PART_KNOB); + lv_obj_set_style_outline_width(slider, 3, LV_PART_KNOB); + lv_obj_set_style_outline_pad(slider, -5, LV_PART_KNOB); + lv_obj_set_style_shadow_spread(slider, 2, LV_PART_KNOB); + +.. raw:: html + + </details> + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +Código MicroPython \| Simulador online + +.. raw:: html + + </summary> + +.. code:: python + + # Crie um controle deslizante (slider) e adicione o estilo + slider = lv.slider(lv.scr_act()) + slider.set_value(70, lv.ANIM.OFF) + slider.set_size(300, 20) + slider.center() + + # Adicione estilos locais à parte MAIN (retângulo de fundo) + slider.set_style_bg_color(lv.color_hex(0x0F1215), lv.PART.MAIN) + slider.set_style_bg_opa(255, lv.PART.MAIN) + slider.set_style_border_color(lv.color_hex(0x333943), lv.PART.MAIN) + slider.set_style_border_width(5, lv.PART.MAIN) + slider.set_style_pad_all(5, lv.PART.MAIN) + + # Crie uma folha de estilo reutilizável para a parte do INDICATOR + style_indicator = lv.style_t() + style_indicator.init() + style_indicator.set_bg_color(lv.color_hex(0x37B9F5)) + style_indicator.set_bg_grad_color(lv.color_hex(0x1464F0)) + style_indicator.set_bg_grad_dir(lv.GRAD_DIR.HOR) + style_indicator.set_shadow_color(lv.color_hex(0x37B9F5)) + style_indicator.set_shadow_width(15) + style_indicator.set_shadow_spread(5) + + # Adicione a folha de estilo à parte do INDICATOR do controle deslizante (slider) + slider.add_style(style_indicator, lv.PART.INDICATOR) + slider.add_style(style_indicator, lv.PART.KNOB) + + # Adicione o mesmo estilo à parte do KNOB e sobrescreva localmente algumas propriedades + slider.set_style_outline_color(lv.color_hex(0x0096FF), lv.PART.KNOB) + slider.set_style_outline_width(3, lv.PART.KNOB) + slider.set_style_outline_pad(-5, lv.PART.KNOB) + slider.set_style_shadow_spread(2, lv.PART.KNOB) + +.. raw:: html + + </details> + +Textos em inglês, hebraico (LRT-RTL misto) e chinês +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: https://github.com/kisvegabor/test/raw/master/readme_example_4.png + :alt: Textos em inglês, hebraico (LRT-RTL misto) e chinês com LVGL + + Textos em inglês, hebraico (LRT-RTL misto) e chinês com LVGL + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +Código C + +.. raw:: html + + </summary> + +.. code:: c + + lv_obj_t * ltr_label = lv_label_create(lv_scr_act()); + lv_label_set_text(ltr_label, "In modern terminology, a microcontroller is similar to a system on a chip (SoC)."); + lv_obj_set_style_text_font(ltr_label, &lv_font_montserrat_16, 0); + lv_obj_set_width(ltr_label, 310); + lv_obj_align(ltr_label, LV_ALIGN_TOP_LEFT, 5, 5); + + lv_obj_t * rtl_label = lv_label_create(lv_scr_act()); + lv_label_set_text(rtl_label,"מעבד, או בשמו המלא יחידת עיבוד מרכזית (באנגלית: CPU - Central Processing Unit)."); + lv_obj_set_style_base_dir(rtl_label, LV_BASE_DIR_RTL, 0); + lv_obj_set_style_text_font(rtl_label, &lv_font_dejavu_16_persian_hebrew, 0); + lv_obj_set_width(rtl_label, 310); + lv_obj_align(rtl_label, LV_ALIGN_LEFT_MID, 5, 0); + + lv_obj_t * cz_label = lv_label_create(lv_scr_act()); + lv_label_set_text(cz_label, + "嵌入式系统（Embedded System），\n是一种嵌入机械或电气系统内部、具有专一功能和实时计算性能的计算机系统。"); + lv_obj_set_style_text_font(cz_label, &lv_font_simsun_16_cjk, 0); + lv_obj_set_width(cz_label, 310); + lv_obj_align(cz_label, LV_ALIGN_BOTTOM_LEFT, 5, -5); + +.. raw:: html + + </details> + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +Código MicroPython \| Simulador online + +.. raw:: html + + </summary> + +.. code:: python + + ltr_label = lv.label(lv.scr_act()) + ltr_label.set_text("In modern terminology, a microcontroller is similar to a system on a chip (SoC).") + ltr_label.set_style_text_font(lv.font_montserrat_16, 0); + + ltr_label.set_width(310) + ltr_label.align(lv.ALIGN.TOP_LEFT, 5, 5) + + rtl_label = lv.label(lv.scr_act()) + rtl_label.set_text("מעבד, או בשמו המלא יחידת עיבוד מרכזית (באנגלית: CPU - Central Processing Unit).") + rtl_label.set_style_base_dir(lv.BASE_DIR.RTL, 0) + rtl_label.set_style_text_font(lv.font_dejavu_16_persian_hebrew, 0) + rtl_label.set_width(310) + rtl_label.align(lv.ALIGN.LEFT_MID, 5, 0) + + font_simsun_16_cjk = lv.font_load("S:../../assets/font/lv_font_simsun_16_cjk.fnt") + + cz_label = lv.label(lv.scr_act()) + cz_label.set_style_text_font(font_simsun_16_cjk, 0) + cz_label.set_text("嵌入式系统（Embedded System），\n是一种嵌入机械或电气系统内部、具有专一功能和实时计算性能的计算机系统。") + cz_label.set_width(310) + cz_label.align(lv.ALIGN.BOTTOM_LEFT, 5, -5) + +.. raw:: html + + </details> + +**Começando** +------------- + +Esta lista irá guiá-lo para começar com o LVGL passo a passo. + +**Familiarize-se com o LVGL** + +1. Confira as `demos on-line <https://lvgl.io/demos>`__ para ver o LVGL + em ação (~3 minutos) +2. Leia a página de + `introdução <https://docs.lvgl.io/master/intro/index.html>`__ da + documentação (~5 minutos) +3. Familiarize-se com o básico na página de `visão geral + rápida <https://docs.lvgl.io/master/get-started/quick-overview.html>`__ + (~15 minutos) + +**Começando a usar o LVGL** + +4. Configure um + `simulador <https://docs.lvgl.io/master/get-started/platforms/pc-simulator.html>`__ + (~10 minutos) +5. Experimente alguns + `exemplos <https://github.com/lvgl/lvgl/tree/master/examples>`__ +6. Porte o LVGL para uma placa. Veja o guia `portando o + LVGL <https://docs.lvgl.io/master/porting/index.html>`__ ou veja um + projeto pronto para usar em + `projetos <https://github.com/lvgl?q=lv_port_>`__ + +**Torne-se um profissional** + +7. Leia a página `visão + geral <https://docs.lvgl.io/master/overview/index.html>`__ para + entender melhor a biblioteca (~2-3 horas) +8. Verifique a documentação dos + `widgets <https://docs.lvgl.io/master/widgets/index.html>`__ para ver + seus recursos e usabilidade + +**Obtenha ajuda e ajude outras pessoas** + +9. Se você tiver dúvidas, acesse o `Fórum <http://forum.lvgl.io>`__ +10. Leia o guia de + `contribuição <https://docs.lvgl.io/master/CONTRIBUTING.html>`__ + para ver como você pode ajudar a melhorar o LVGL (~15 minutos) + +**E mais** + +11. Baixe e experimente o editor `SquareLine + Studio <https://squareline.io>`__. +12. Entre em contato conosco para `serviços e + consultoria <https://lvgl.io/services>`__. + +**Serviços** +------------ + +A LVGL LLC foi criada para fornecer uma base sólida para a biblioteca +LVGL e oferecer vários tipos de serviços para ajudá-lo no +desenvolvimento da sua interface do usuário. Com mais de 15 anos de +experiência na indústria gráfica e de interface do usuário, podemos +ajudá-lo a levar sua interface do usuário para o próximo nível. + +- **Design gráfico**: Nossos designers gráficos internos são + especialistas em criar belos designs modernos que se adaptam ao seu + produto e aos recursos do seu hardware. +- **Implementação da interface do usuário**: Também podemos implementar + sua interface do usuário com base no design que você ou nós criamos. + Você pode ter certeza de que tiraremos o máximo proveito de seu + hardware e do LVGL. Se um recurso ou widget estiver faltando no LVGL, + não se preocupe, nós o implementaremos para você. +- **Consultoria e Suporte**: Também podemos apoiá-lo com consultoria + para evitar erros que podem te custar caros durante o desenvolvimento + da sua interface do usuário. +- **Certificação**: Para empresas que oferecem placas para + desenvolvimento ou kits prontos para produção, fazemos certificação + que mostram como uma placa pode executar o LVGL. + +Confira nossas `demonstrações <https://lvgl.io/demos>`__ como +referência. Para obter mais informações, consulte a `página de +serviços <https://lvgl.io/services>`__. + +`Fale conosco <https://lvgl.io/#contact>`__ e conte como podemos ajudar. + +**Contribuindo** +---------------- + +O LVGL é um projeto aberto e sua contribuição é muito bem-vinda. Há +muitas maneiras de contribuir, desde simplesmente falando sobre seu +projeto, escrevendo exemplos, melhorando a documentação, corrigindo bugs +até hospedar seu próprio projeto sob a organização LVGL. + +Para obter uma descrição detalhada das oportunidades de contribuição, +visite a página de +`contribuição <https://docs.lvgl.io/master/CONTRIBUTING.html>`__ da +documentação. + +Mais de 300 pessoas já deixaram sua impressão digital no LVGL. Seja um +deles! Veja o seu aqui! :slightly_smiling_face: + +… e muitos outros. + +.. |Patrocinadores do LVGL| image:: https://opencollective.com/lvgl/organizations.svg?width=600 + :target: https://opencollective.com/lvgl +.. |Backers of LVGL| image:: https://opencollective.com/lvgl/individuals.svg?width=600 + :target: https://opencollective.com/lvgl diff --git a/docs/README_zh.md b/docs/README_zh.md deleted file mode 100644 index 5790bb792..000000000 --- a/docs/README_zh.md +++ /dev/null @@ -1,204 +0,0 @@ -<a href="https://opencollective.com/lvgl" target="_blank"><img align="left" src="https://lvgl.io/assets/images/sponsor.png" height="32px"></a> - -<p align="right"> - <a href="../README.md">English</a> | <b>中文</b> | <a href="./README_pt_BR.md">Português do Brasil</a> | <a href="./README_jp.md">日本語</a> -</p> - -<br> - -<p align="center"> - <img src="https://lvgl.io/assets/images/logo_lvgl.png"> -</p> - - <h1 align="center">Light and Versatile Graphics Library</h1> - <h1 align="center">轻量级通用型图形库</h1> - <br> -<div align="center"> - <img src="https://github.com/kisvegabor/test/raw/master/smartwatch_demo.gif"> - - <img border="1px" src="https://lvgl.io/assets/images/lvgl_widgets_demo.gif"> -</div> -<br> -<p align="center"> -<a href="https://lvgl.io" title="Homepage of LVGL">官网 </a> | -<a href="https://docs.lvgl.io/" title="Detailed documentation with 100+ examples">文档</a> | -<a href="https://forum.lvgl.io" title="Get help and help others">论坛</a> | -<a href="https://lvgl.io/demos" title="Demos running in your browser">示例</a> | -<a href="https://lvgl.io/services" title="Graphics design, UI implementation and consulting">服务</a> | -<a href="https://squareline.io/" title="UI Editor for LVGL">SquareLine Studio</a> -</p> -<br> - -[中文宣传单](./flyers/LVGL-Chinese-Flyer.pdf) - -#### 目录 -- [概况与总览](#概况与总览) - - [特性](#特性) - - [硬件要求](#硬件要求) - - [已经支持的平台](#已经支持的平台) -- [如何入门](#如何入门) -- [例程](#例程) - - [C](#c) - - [Micropython](#micropython) -- [服务](#服务) -- [如何向社区贡献](#如何向社区贡献) - -## 概况与总览 -### 特性 -* 丰富且强大的模块化[图形组件](https://docs.lvgl.io/master/widgets/index.html)：按钮 (buttons)、图表 (charts)、列表 (lists)、滑动条 (sliders)、图片 (images) 等 -* 高级的图形引擎：动画、抗锯齿、透明度、平滑滚动、图层混合等效果 -* 支持多种[输入设备](https://docs.lvgl.io/master/overview/indev.html)：触摸屏、 键盘、编码器、按键等 -* 支持[多显示设备](https://docs.lvgl.io/master/overview/display.html) -* 不依赖特定的硬件平台，可以在任何显示屏上运行 -* 配置可裁剪（最低资源占用：64 kB Flash，16 kB RAM） -* 基于UTF-8的多语种支持，例如中文、日文、韩文、阿拉伯文等 -* 可以通过[类CSS](https://docs.lvgl.io/master/overview/style.html)的方式来设计、布局图形界面（例如：[Flexbox](https://docs.lvgl.io/master/layouts/flex.html)、[Grid](https://docs.lvgl.io/master/layouts/grid.html)） -* 支持操作系统、外置内存、以及硬件加速（LVGL已内建支持STM32 DMA2D、SWM341 DMA2D、NXP PXP和VGLite） -* 即便仅有[单缓冲区(frame buffer)](https://docs.lvgl.io/master/porting/display.html)的情况下，也可保证渲染如丝般顺滑 -* 全部由C编写完成，并支持C++调用 -* 支持Micropython编程，参见：[LVGL API in Micropython](https://blog.lvgl.io/2019-02-20/micropython-bindings) -* 支持[模拟器](https://docs.lvgl.io/master/get-started/platforms/pc-simulator.html)仿真，可以无硬件依托进行开发 -* 丰富详实的[例程](https://github.com/lvgl/lvgl/tree/master/examples) -* 详尽的[文档](http://docs.lvgl.io/)以及API参考手册，可线上查阅或可下载为PDF格式 - -### 硬件要求 - -<table> - <tr> - <td> <strong>要求</strong> </td> - <td><strong>最低要求</strong></td> - <td><strong>建议要求</strong></td> - </tr> - <tr> - <td><strong>架构</strong></td> - <td colspan="2">16、32、64位微控制器或微处理器</td> - </tr> - <tr> - <td> <strong>时钟</strong></td> - <td> > 16 MHz</td> - <td> > 48 MHz</td> - </tr> - - <tr> - <td> <strong>Flash/ROM</strong></td> - <td> > 64 kB </td> - <td> > 180 kB</td> - </tr> - - <tr> - <td> <strong>Static RAM</strong></td> - <td> > 16 kB </td> - <td> > 48 kB</td> - </tr> - - <tr> - <td> <strong>Draw buffer</strong></td> - <td> > 1 × <em>hor. res.</em> pixels </td> - <td> > 1/10屏幕大小 </td> - </tr> - - <tr> - <td> <strong>编译器</strong></td> - <td colspan="2"> C99或更新 </td> - </tr> -</table> - -*注意：资源占用情况与具体硬件平台、编译器等因素有关，上表中仅给出参考值* - -### 已经支持的平台 -LVGL本身并不依赖特定的硬件平台，任何满足LVGL硬件配置要求的微控制器均可运行LVGL。 -如下仅列举其中一部分: - -- NXP: Kinetis, LPC, iMX, iMX RT -- STM32F1, STM32F3, STM32F4, STM32F7, STM32L4, STM32L5, STM32H7 -- Microchip dsPIC33, PIC24, PIC32MX, PIC32MZ -- [Linux frame buffer](https://blog.lvgl.io/2018-01-03/linux_fb) (/dev/fb) -- [Raspberry Pi](http://www.vk3erw.com/index.php/16-software/63-raspberry-pi-official-7-touchscreen-and-littlevgl) -- [Espressif ESP32](https://github.com/lvgl/lv_port_esp32) -- [Infineon Aurix](https://github.com/lvgl/lv_port_aurix) -- Nordic NRF52 Bluetooth modules -- Quectel modems -- [SYNWIT SWM341](https://www.synwit.cn/) - -LVGL也支持： -- [Arduino library](https://docs.lvgl.io/master/get-started/platforms/arduino.html) -- [PlatformIO package](https://registry.platformio.org/libraries/lvgl/lvgl) -- [Zephyr library](https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_LVGL) -- [ESP32 component](https://docs.lvgl.io/master/get-started/platforms/espressif.html) -- [NXP MCUXpresso component](https://www.nxp.com/design/software/embedded-software/lvgl-open-source-graphics-library:LITTLEVGL-OPEN-SOURCE-GRAPHICS-LIBRARY) -- [NuttX library](https://docs.lvgl.io/master/get-started/os/nuttx.html) -- [RT-Thread RTOS](https://www.rt-thread.org/document/site/#/rt-thread-version/rt-thread-standard/packages-manual/lvgl-docs/introduction) - - -## 如何入门 -请按照如下顺序来学习LVGL： -1. 使用[网页在线例程](https://lvgl.io/demos)来体验LVGL（3分钟） -2. 阅读文档[简介](https://docs.lvgl.io/master/intro/index.html)章节来初步了解LVGL（5分钟） -3. 再来阅读一下文档快速[快速概览](https://docs.lvgl.io/master/get-started/quick-overview.html)章节来了解LVGL的基本知识（15分钟） -4. 学习如何使用[模拟器](https://docs.lvgl.io/master/get-started/platforms/pc-simulator.html)来在电脑上仿真LVGL（10分钟） -5. 试着动手实践一些[例程](https://github.com/lvgl/lvgl/tree/master/examples) -6. 参考[移植指南](https://docs.lvgl.io/master/porting/index.html)尝试将LVGL移植到一块开发板上，LVGL也已经提供了一些移植好的[工程](https://github.com/lvgl?q=lv_port_) -7. 仔细阅读文档[总览](https://docs.lvgl.io/master/overview/index.html)章节来更加深入的了解和熟悉LVGL（2-3小时） -8. 浏览文档[组件(Widgets)](https://docs.lvgl.io/master/widgets/index.html)章节来了解如何使用它们 -9. 如果你有问题可以到LVGL[论坛](http://forum.lvgl.io/)提问 -10. 阅读文档[如何向社区贡献](https://docs.lvgl.io/master/CONTRIBUTING.html)章节来看看你能帮LVGL社区做些什么，以促进LVGL软件质量的不断提高（15分钟） - -## 例程 - -更多例程请参见 [examples](https://github.com/lvgl/lvgl/tree/master/examples) 文件夹。 - - - -### C -```c -lv_obj_t * btn = lv_btn_create(lv_scr_act()); /*Add a button to the current screen*/ -lv_obj_set_pos(btn, 10, 10); /*Set its position*/ -lv_obj_set_size(btn, 100, 50); /*Set its size*/ -lv_obj_add_event(btn, btn_event_cb, LV_EVENT_CLICKED, NULL); /*Assign a callback to the button*/ - -lv_obj_t * label = lv_label_create(btn); /*Add a label to the button*/ -lv_label_set_text(label, "Button"); /*Set the labels text*/ -lv_obj_center(label); /*Align the label to the center*/ -... - -void btn_event_cb(lv_event_t * e) -{ - printf("Clicked\n"); -} -``` -### Micropython -更多信息请到 [Micropython官网](https://docs.lvgl.io/master/get-started/bindings/micropython.html) 查询. -```python -def btn_event_cb(e): - print("Clicked") - -# Create a Button and a Label -btn = lv.btn(lv.scr_act()) -btn.set_pos(10, 10) -btn.set_size(100, 50) -btn.add_event(btn_event_cb, lv.EVENT.CLICKED, None) - -label = lv.label(btn) -label.set_text("Button") -label.center() -``` - -## 服务 -LVGL 责任有限公司成立的目的是为了给用户使用LVGL图形库提供额外的技术支持，我们致力于提供以下服务： - -- 图形设计 -- UI设计 -- 技术咨询以及技术支持 - -更多信息请参见 https://lvgl.io/services ，如果有任何问题请随时联系我们。 - - -## 如何向社区贡献 -LVGL是一个开源项目，非常欢迎您参与到社区贡献当中。您有很多种方式来为提高LVGL贡献您的一份力量，包括但不限于： - -- 介绍你基于LVGL设计的作品或项目 -- 写一些例程 -- 修改以及完善文档 -- 修复bug - -请参见文档[如何向社区贡献](https://docs.lvgl.io/master/CONTRIBUTING.html)章节来获取更多信息。 diff --git a/docs/README_zh.rst.back b/docs/README_zh.rst.back new file mode 100644 index 000000000..577e5bb22 --- /dev/null +++ b/docs/README_zh.rst.back @@ -0,0 +1,493 @@ +.. raw:: html + + <p align="right"> + +English \| 中文 \| Português do Brasil \| 日本語 + +.. raw:: html + + </p> + +.. raw:: html + + <p align="center"> + + + +.. raw:: html + + </p> + + + +.. raw:: html + + <h1 align="center"> + +Light and Versatile Graphics Library + +.. raw:: html + + </h1> + +.. raw:: html + + <h1 align="center"> + +轻量级通用型图形库 + +.. raw:: html + + </h1> + + + +.. raw:: html + + <p align="center"> + +官网 \| 文档 \| 论坛 \| 示例 \| 服务 \| SquareLine Studio + +.. raw:: html + + </p> + +`中文宣传单 <./flyers/LVGL-Chinese-Flyer.pdf>`__ + +目录 +^^^^ + +- `概况与总览 <#概况与总览>`__ + + - `特性 <#特性>`__ + - `硬件要求 <#硬件要求>`__ + - `已经支持的平台 <#已经支持的平台>`__ + +- `如何入门 <#如何入门>`__ +- `例程 <#例程>`__ + + - `C <#c>`__ + - `Micropython <#micropython>`__ + +- `服务 <#服务>`__ +- `如何向社区贡献 <#如何向社区贡献>`__ + +概况与总览 +---------- + +特性 +~~~~ + +- 丰富且强大的模块化\ `图形组件 <https://docs.lvgl.io/master/widgets/index.html>`__\ ：按钮 + (buttons)、图表 (charts)、列表 (lists)、滑动条 (sliders)、图片 + (images) 等 +- 高级的图形引擎：动画、抗锯齿、透明度、平滑滚动、图层混合等效果 +- 支持多种\ `输入设备 <https://docs.lvgl.io/master/overview/indev.html>`__\ ：触摸屏、 + 键盘、编码器、按键等 +- 支持\ `多显示设备 <https://docs.lvgl.io/master/overview/display.html>`__ +- 不依赖特定的硬件平台，可以在任何显示屏上运行 +- 配置可裁剪（最低资源占用：64 kB Flash，16 kB RAM） +- 基于UTF-8的多语种支持，例如中文、日文、韩文、阿拉伯文等 +- 可以通过\ `类CSS <https://docs.lvgl.io/master/overview/style.html>`__\ 的方式来设计、布局图形界面（例如：\ `Flexbox <https://docs.lvgl.io/master/layouts/flex.html>`__\ 、\ `Grid <https://docs.lvgl.io/master/layouts/grid.html>`__\ ） +- 支持操作系统、外置内存、以及硬件加速（LVGL已内建支持STM32 + DMA2D、SWM341 DMA2D、NXP PXP和VGLite） +- 即便仅有\ `单缓冲区(frame + buffer) <https://docs.lvgl.io/master/porting/display.html>`__\ 的情况下，也可保证渲染如丝般顺滑 +- 全部由C编写完成，并支持C++调用 +- 支持Micropython编程，参见：\ `LVGL API in + Micropython <https://blog.lvgl.io/2019-02-20/micropython-bindings>`__ +- 支持\ `模拟器 <https://docs.lvgl.io/master/get-started/platforms/pc-simulator.html>`__\ 仿真，可以无硬件依托进行开发 +- 丰富详实的\ `例程 <https://github.com/lvgl/lvgl/tree/master/examples>`__ +- 详尽的\ `文档 <http://docs.lvgl.io/>`__\ 以及API参考手册，可线上查阅或可下载为PDF格式 + +硬件要求 +~~~~~~~~ + +.. raw:: html + + <table> + +.. raw:: html + + <tr> + +.. raw:: html + + <td> + +要求 + +.. raw:: html + + </td> + +.. raw:: html + + <td> + +最低要求 + +.. raw:: html + + </td> + +.. raw:: html + + <td> + +建议要求 + +.. raw:: html + + </td> + +.. raw:: html + + </tr> + +.. raw:: html + + <tr> + +.. raw:: html + + <td> + +架构 + +.. raw:: html + + </td> + +.. raw:: html + + <td colspan="2"> + +16、32、64位微控制器或微处理器 + +.. raw:: html + + </td> + +.. raw:: html + + </tr> + +.. raw:: html + + <tr> + +.. raw:: html + + <td> + +时钟 + +.. raw:: html + + </td> + +.. raw:: html + + <td> + +> 16 MHz + +.. raw:: html + + </td> + +.. raw:: html + + <td> + +> 48 MHz + +.. raw:: html + + </td> + +.. raw:: html + + </tr> + +.. raw:: html + + <tr> + +.. raw:: html + + <td> + +Flash/ROM + +.. raw:: html + + </td> + +.. raw:: html + + <td> + +> 64 kB + +.. raw:: html + + </td> + +.. raw:: html + + <td> + +> 180 kB + +.. raw:: html + + </td> + +.. raw:: html + + </tr> + +.. raw:: html + + <tr> + +.. raw:: html + + <td> + +Static RAM + +.. raw:: html + + </td> + +.. raw:: html + + <td> + +> 16 kB + +.. raw:: html + + </td> + +.. raw:: html + + <td> + +> 48 kB + +.. raw:: html + + </td> + +.. raw:: html + + </tr> + +.. raw:: html + + <tr> + +.. raw:: html + + <td> + +Draw buffer + +.. raw:: html + + </td> + +.. raw:: html + + <td> + +> 1 × hor. res. pixels + +.. raw:: html + + </td> + +.. raw:: html + + <td> + +> 1/10屏幕大小 + +.. raw:: html + + </td> + +.. raw:: html + + </tr> + +.. raw:: html + + <tr> + +.. raw:: html + + <td> + +编译器 + +.. raw:: html + + </td> + +.. raw:: html + + <td colspan="2"> + +C99或更新 + +.. raw:: html + + </td> + +.. raw:: html + + </tr> + +.. raw:: html + + </table> + +*注意：资源占用情况与具体硬件平台、编译器等因素有关，上表中仅给出参考值* + +已经支持的平台 +~~~~~~~~~~~~~~ + +LVGL本身并不依赖特定的硬件平台，任何满足LVGL硬件配置要求的微控制器均可运行LVGL。 +如下仅列举其中一部分: + +- NXP: Kinetis, LPC, iMX, iMX RT +- STM32F1, STM32F3, STM32F4, STM32F7, STM32L4, STM32L5, STM32H7 +- Microchip dsPIC33, PIC24, PIC32MX, PIC32MZ +- `Linux frame buffer <https://blog.lvgl.io/2018-01-03/linux_fb>`__ + (/dev/fb) +- `Raspberry + Pi <http://www.vk3erw.com/index.php/16-software/63-raspberry-pi-official-7-touchscreen-and-littlevgl>`__ +- `Espressif ESP32 <https://github.com/lvgl/lv_port_esp32>`__ +- `Infineon Aurix <https://github.com/lvgl/lv_port_aurix>`__ +- Nordic NRF52 Bluetooth modules +- Quectel modems +- `SYNWIT SWM341 <https://www.synwit.cn/>`__ + +LVGL也支持： - `Arduino +library <https://docs.lvgl.io/master/get-started/platforms/arduino.html>`__ +- `PlatformIO +package <https://registry.platformio.org/libraries/lvgl/lvgl>`__ - +`Zephyr +library <https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_LVGL>`__ +- `ESP32 +component <https://docs.lvgl.io/master/get-started/platforms/espressif.html>`__ +- `NXP MCUXpresso +component <https://www.nxp.com/design/software/embedded-software/lvgl-open-source-graphics-library:LITTLEVGL-OPEN-SOURCE-GRAPHICS-LIBRARY>`__ +- `NuttX +library <https://docs.lvgl.io/master/get-started/os/nuttx.html>`__ - +`RT-Thread +RTOS <https://www.rt-thread.org/document/site/#/rt-thread-version/rt-thread-standard/packages-manual/lvgl-docs/introduction>`__ + +如何入门 +-------- + +请按照如下顺序来学习LVGL： 1. +使用\ `网页在线例程 <https://lvgl.io/demos>`__\ 来体验LVGL（3分钟） 2. +阅读文档\ `简介 <https://docs.lvgl.io/master/intro/index.html>`__\ 章节来初步了解LVGL（5分钟） +3. +再来阅读一下文档快速\ `快速概览 <https://docs.lvgl.io/master/get-started/quick-overview.html>`__\ 章节来了解LVGL的基本知识（15分钟） +4. +学习如何使用\ `模拟器 <https://docs.lvgl.io/master/get-started/platforms/pc-simulator.html>`__\ 来在电脑上仿真LVGL（10分钟） +5. +试着动手实践一些\ `例程 <https://github.com/lvgl/lvgl/tree/master/examples>`__ +6. +参考\ `移植指南 <https://docs.lvgl.io/master/porting/index.html>`__\ 尝试将LVGL移植到一块开发板上，LVGL也已经提供了一些移植好的\ `工程 <https://github.com/lvgl?q=lv_port_>`__ +7. +仔细阅读文档\ `总览 <https://docs.lvgl.io/master/overview/index.html>`__\ 章节来更加深入的了解和熟悉LVGL（2-3小时） +8. +浏览文档\ `组件(Widgets) <https://docs.lvgl.io/master/widgets/index.html>`__\ 章节来了解如何使用它们 +9. 如果你有问题可以到LVGL\ `论坛 <http://forum.lvgl.io/>`__\ 提问 10. +阅读文档\ `如何向社区贡献 <https://docs.lvgl.io/master/CONTRIBUTING.html>`__\ 章节来看看你能帮LVGL社区做些什么，以促进LVGL软件质量的不断提高（15分钟） + +例程 +---- + +更多例程请参见 +`examples <https://github.com/lvgl/lvgl/tree/master/examples>`__ +文件夹。 + +.. figure:: https://github.com/lvgl/lvgl/raw/master/docs/misc/btn_example.png + :alt: LVGL button with label example + + LVGL button with label example + +C +~ + +.. code:: c + + lv_obj_t * btn = lv_btn_create(lv_scr_act()); /*Add a button to the current screen*/ + lv_obj_set_pos(btn, 10, 10); /*Set its position*/ + lv_obj_set_size(btn, 100, 50); /*Set its size*/ + lv_obj_add_event(btn, btn_event_cb, LV_EVENT_CLICKED, NULL); /*Assign a callback to the button*/ + + lv_obj_t * label = lv_label_create(btn); /*Add a label to the button*/ + lv_label_set_text(label, "Button"); /*Set the labels text*/ + lv_obj_center(label); /*Align the label to the center*/ + ... + + void btn_event_cb(lv_event_t * e) + { + printf("Clicked\n"); + } + +Micropython +~~~~~~~~~~~ + +更多信息请到 +`Micropython官网 <https://docs.lvgl.io/master/get-started/bindings/micropython.html>`__ +查询. + +.. code:: python + + def btn_event_cb(e): + print("Clicked") + + # Create a Button and a Label + btn = lv.btn(lv.scr_act()) + btn.set_pos(10, 10) + btn.set_size(100, 50) + btn.add_event(btn_event_cb, lv.EVENT.CLICKED, None) + + label = lv.label(btn) + label.set_text("Button") + label.center() + +服务 +---- + +LVGL +责任有限公司成立的目的是为了给用户使用LVGL图形库提供额外的技术支持，我们致力于提供以下服务： + +- 图形设计 +- UI设计 +- 技术咨询以及技术支持 + +更多信息请参见 https://lvgl.io/services ，如果有任何问题请随时联系我们。 + +如何向社区贡献 +-------------- + +LVGL是一个开源项目，非常欢迎您参与到社区贡献当中。您有很多种方式来为提高LVGL贡献您的一份力量，包括但不限于： + +- 介绍你基于LVGL设计的作品或项目 +- 写一些例程 +- 修改以及完善文档 +- 修复bug + +请参见文档\ `如何向社区贡献 <https://docs.lvgl.io/master/CONTRIBUTING.html>`__\ 章节来获取更多信息。 diff --git a/docs/ROADMAP.md b/docs/ROADMAP.rst index 4c88c568c..4c88c568c 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.rst diff --git a/docs/_ext/lv_example.py b/docs/_ext/lv_example.py index 1a818e246..014e7c3e2 100644 --- a/docs/_ext/lv_example.py +++ b/docs/_ext/lv_example.py @@ -2,16 +2,14 @@ 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 +# 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 = { @@ -19,8 +17,13 @@ class LvExample(Directive): 'language': directives.unchanged, 'description': directives.unchanged } + def get_example_code_path(self, example_path, language): - return os.path.abspath("../examples/" + example_path + "." + language) + base_path = os.path.dirname(__file__) + examples_path = os.path.abspath(os.path.join(base_path, '..', 'examples')) + example_path = os.path.join(examples_path, example_path + '.' + language) + return example_path + def human_language_name(self, language): if language == 'py': return 'MicroPython' @@ -28,18 +31,23 @@ class LvExample(Directive): 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() + with open(example_file, 'rb') as f: + contents = f.read().decode('utf-8') except FileNotFoundError: + print('File Not Found', example_file) contents = 'Error encountered while trying to open ' + example_file + literal_list = nodes.literal_block(contents, contents) literal_list['language'] = language toggle.append(literal_list) @@ -48,6 +56,7 @@ class LvExample(Directive): 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] @@ -61,15 +70,22 @@ class LvExample(Directive): 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 os.path.exists(c_path): + c_code = self.embed_code(c_path, example_path, 'c', buttons={ + '<i class="fa fa-github"></i> View on GitHub': self.github_path(example_path, 'c') + }) + else: + c_code = None + + if os.path.exists(py_path): + py_code = self.embed_code(py_path, example_path, 'py', buttons={ + '<i class="fa fa-github"></i> View on GitHub': self.github_path(example_path, 'py'), + '<i class="fa fa-play"></i> MicroPython 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" + }) + else: + py_code = None - if not 'c' in excluded_languages: + if 'c' not 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>" @@ -77,9 +93,9 @@ class LvExample(Directive): 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: + if 'c' not in excluded_languages and c_code is not None: node_list.append(c_code) - if not 'py' in excluded_languages: + if 'py' not in excluded_languages and py_code is not None: node_list.append(py_code) trailing_node = nodes.raw(text=f"<hr/>", format='html') @@ -87,6 +103,7 @@ class LvExample(Directive): return node_list + def setup(app): app.add_directive("lv_example", LvExample) app.add_config_value("repo_commit_hash", "", "env") diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css index 93a95be1e..d507d0765 100644 --- a/docs/_static/css/custom.css +++ b/docs/_static/css/custom.css @@ -130,4 +130,16 @@ dl.cpp.unexpanded dd { } .expanded .lv-api-expansion-button::before { content: "\f0d7 \00a0"; +} + +.wy-nav-content{ + padding: 1.618em 3.236em; + height: 100%; + max-width: 1920px; + margin: auto +} + +div.body { + min-width: 360px; + max-width: 1920px; }
\ No newline at end of file diff --git a/docs/_static/js/custom.js b/docs/_static/js/custom.js index d16e00b02..2a7b7552c 100644 --- a/docs/_static/js/custom.js +++ b/docs/_static/js/custom.js @@ -15,4 +15,4 @@ document.addEventListener('DOMContentLoaded', (event) => { dt.insertBefore(button, dt.firstChild); }); -})
\ No newline at end of file +}) diff --git a/docs/_static/js/include_html.js b/docs/_static/js/include_html.js new file mode 100644 index 000000000..ad8b0717a --- /dev/null +++ b/docs/_static/js/include_html.js @@ -0,0 +1,29 @@ + +/*https://www.w3schools.com/howto/howto_html_include.asp*/ +function includeHTML() { + var z, i, elmnt, file, xhttp; + /*loop through a collection of all HTML elements:*/ + z = document.getElementsByTagName("*"); + for (i = 0; i < z.length; i++) { + elmnt = z[i]; + /*search for elements with a certain attribute:*/ + file = elmnt.getAttribute("include-html"); + if (file) { + /*make an HTTP request using the attribute value as the file name:*/ + xhttp = new XMLHttpRequest(); + xhttp.onreadystatechange = function() { + if (this.readyState == 4) { + if (this.status == 200) {elmnt.innerHTML = this.responseText;} + if (this.status == 404) {elmnt.innerHTML = "Page not found.";} + /*remove the attribute, and call this function once more:*/ + elmnt.removeAttribute("w3-include-html"); + includeHTML(); + } + } + xhttp.open("GET", file, true); + xhttp.send(); + /*exit the function:*/ + return; + } + } +};
\ No newline at end of file diff --git a/docs/build.py b/docs/build.py index 7a1f7979f..d1214be21 100755 --- a/docs/build.py +++ b/docs/build.py @@ -1,74 +1,261 @@ #!/usr/bin/env python3 +# **************************************************************************** +# IMPOTRANT: If you are getting a lexer error for an example you need to check +# for extra lines at the edn of the file. Only a single empty line +# is allowed!!! Ask me how long it took me to figure this out +# **************************************************************************** + import sys import os import subprocess import re import example_list as ex +import doc_builder +import shutil +import tempfile + +# due to the modifications that take place to the documentation files +# when the documentaation builds it is better to copy the source files to a +# temporary folder and modify the copies. Not setting it up this way makes it +# a real headache when making alterations that need to be comitted as the +# alterations trigger the files as changed. + +# If there is debugging that needs to be done you can provide a command line +# switch of "develop" and it will leave the temporary directory in tact and +# that directory will be output at the end of the build. + +# the html and PDF output locations are going to remain the same as they were. +# it's just the source documentation files that are going to be copied. + +temp_directory = tempfile.mkdtemp(suffix='.lvgl_docs') langs = ['en'] # Change to script directory for consistency -abspath = os.path.abspath(__file__) -dname = os.path.dirname(abspath) -os.chdir(dname) + +base_path = os.path.abspath(os.path.dirname(__file__)) +project_path = os.path.abspath(os.path.join(base_path, '..')) +examples_path = os.path.join(project_path, 'examples') + +lvgl_src_path = os.path.join(project_path, 'src') +latex_output_path = os.path.join(temp_directory, 'out_latex') + +pdf_src_file = os.path.join(latex_output_path, 'LVGL.pdf') +pdf_dst_file = os.path.join(temp_directory, 'LVGL.pdf') +html_src_path = temp_directory +html_dst_path = os.path.join(project_path, 'out_html') + +os.chdir(base_path) + + +clean = 0 +trans = 0 +skip_latex = False +develop = False +args = sys.argv[1:] + +if len(args) >= 1: + if "clean" in args: + clean = 1 + if "skip_latex" in args: + skip_latex = True + if 'develop' in args: + develop = True + def cmd(s): - print("") - print(s) - print("-------------------------------------") - r = os.system(s) - if r != 0: - print("Exit build due to previous error") - exit(-1) + 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 '*'") +status, br = subprocess.getstatusoutput("git branch") _, 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('cleaning...') + # api_path = os.path.join(dname, 'API') + # xml_path = os.path.join(dname, 'xml') + # doxy_path = os.path.join(dname, 'doxygen_html') + + # if os.path.exists(api_path): + # shutil.rmtree(api_path) + + # if os.path.exists(lang): + # shutil.rmtree(lang) + + if os.path.exists(html_dst_path): + shutil.rmtree(html_dst_path) + + # if os.path.exists(xml_path): + # shutil.rmtree(xml_path) + # + # if os.path.exists(doxy_path): + # shutil.rmtree(doxy_path) + + # os.mkdir(api_path) + # os.mkdir(lang) +shutil.copytree('.', temp_directory, dirs_exist_ok=True) +shutil.copytree(examples_path, os.path.join(temp_directory, 'examples')) + +with open(os.path.join(temp_directory, 'Doxyfile'), 'rb') as f: + data = f.read().decode('utf-8') + +data = data.replace('*#*#SRC#*#*', '"{0}"'.format(lvgl_src_path)) + +with open(os.path.join(temp_directory, 'Doxyfile'), 'wb') as f: + f.write(data.encode('utf-8')) + + +print("Generate the list of examples") +ex.exec(temp_directory) print("Running doxygen") -cmd("cd ../scripts && doxygen Doxyfile") -# BUILD PDF +cmd('cd "{0}" && doxygen Doxyfile'.format(temp_directory)) + +print('Reading Doxygen output') + +doc_builder.run( + project_path, + temp_directory, + os.path.join(temp_directory, 'layouts'), + os.path.join(temp_directory, 'libs'), + os.path.join(temp_directory, 'others'), + os.path.join(temp_directory, 'overview'), + os.path.join(temp_directory, 'overview', 'renderers'), + os.path.join(temp_directory, 'porting'), + os.path.join(temp_directory, 'widgets') +) -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") +# we make sure to remove the link to the PDF before the PDF get generated +# doesn't make any sense to have a link to the PDF in the PDF. The link gets +# added if there is a PDF build so the HTML build will have the link. +index_path = os.path.join(temp_directory, 'index.rst') - # 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") +with open(index_path, 'rb') as f: + index_data = f.read().decode('utf-8') + +if 'PDF version: :download:`LVGL.pdf <LVGL.pdf>`' in index_data: + index_data = index_data.replace( + 'PDF version: :download:`LVGL.pdf <LVGL.pdf>`\n', + '' + ) + with open(index_path, 'wb') as f: + f.write(index_data.encode('utf-8')) + +# BUILD PDF +if skip_latex: + print("skipping latex build as requested") else: - print("skipping latex build as requested") + + # 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 "{src}" "{dst}" -j {cpu}'.format( + src=temp_directory, + dst=latex_output_path, + cpu=os.cpu_count() + )) + + # Generate PDF + cmd('cd "{out_latex}" && latexmk -pdf "LVGL.tex"'.format( + out_latex=latex_output_path + )) + + # Copy the result PDF to the main directory to make + # it available for the HTML build + + shutil.copyfile(pdf_src_file, pdf_dst_file) + # cmd("cd out_latex && cp -f LVGL.pdf ../LVGL.pdf") + + # add the PDF link so the HTML build will have it. + index_data = 'PDF version: :download:`LVGL.pdf <LVGL.pdf>`\n' + index_data + + with open(index_path, 'wb') as f: + f.write(index_data.encode('utf-8')) # BUILD HTML -cmd("sphinx-build -b html . ../out_html") + +def get_version(): + path = os.path.join(project_path, 'lvgl.h') + with open(path, 'rb') as f: + d = f.read().decode('utf-8') + + d = d.split('#define LVGL_VERSION_MAJOR', 1)[-1] + major, d = d.split('\n', 1) + d = d.split('#define LVGL_VERSION_MINOR', 1)[-1] + minor, d = d.split('\n', 1) + d = d.split('#define LVGL_VERSION_PATCH', 1)[-1] + patch, d = d.split('\n', 1) + + ver = '{0}.{1}.{2}'.format(major.strip(), minor.strip(), patch.strip()) + + if '#define LVGL_VERSION_INFO' in d: + d = d.split('#define LVGL_VERSION_INFO', 1)[-1] + info, d = d.split('\n', 1) + info = info.strip().replace('"', '') + ver += '-' + info + + return ver + +cmd('sphinx-build -b html "{src}" "{dst}" -D version="{version}" -E -j {cpu}'.format( + src=html_src_path, + dst=html_dst_path, + version=get_version(), + cpu=os.cpu_count() +)) + +if develop: + print('temp directory:', temp_directory) +else: + def iter_temp(p): + folders = [] + remove_folder = True + for temp_file in os.listdir(p): + temp_file = os.path.join(p, temp_file) + if os.path.isdir(temp_file): + folders.append(temp_file) + else: + try: + os.remove(temp_file) + except OSError: + remove_folder = False + + for folder in folders: + if not iter_temp(folder): + remove_folder = False + + if remove_folder: + try: + os.rmdir(p) + except OSError: + remove_folder = False + + return remove_folder + + iter_temp(temp_directory) + +print('output path:', html_dst_path) +print('\nFINISHED!!') diff --git a/docs/conf.py b/docs/conf.py index 75d5ae3ea..3bce6fe0b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -23,9 +23,9 @@ import sys sys.path.insert(0, os.path.abspath('./_ext')) -from subprocess import PIPE, Popen +# from subprocess import PIPE, Popen -import recommonmark +# import recommonmark from recommonmark.transform import AutoStructify from sphinx.builders.html import StandaloneHTMLBuilder @@ -38,15 +38,20 @@ from sphinx.builders.html import StandaloneHTMLBuilder # 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', +extensions = [ + 'sphinx_rtd_theme', + 'sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', - 'recommonmark', - 'sphinx_markdown_tables', + # 'recommonmark', + # 'sphinx_markdown_tables', 'breathe', 'sphinx_sitemap', - 'lv_example' - ] + 'lv_example', + 'sphinx_rtd_dark_mode' +] + +default_dark_mode = False # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -60,7 +65,7 @@ highlight_language = 'c' # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # -source_suffix = ['.rst', '.md'] +source_suffix = ['.rst']# , '.md'] # The master toctree document. @@ -68,9 +73,10 @@ master_doc = 'index' # General information about the project. project = 'LVGL' -copyright = '2021, LVGL Kft' +copyright = '2023, 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. @@ -78,20 +84,20 @@ author = 'LVGL community' # 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() +version = '' # 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 +language = 'en' # 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' ] + 'README.md', 'lv_examples', 'out_html', 'env', '_ext', 'examples'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' @@ -111,10 +117,25 @@ html_theme = 'sphinx_rtd_theme' # further. For a list of options available for each theme, see the # documentation. # + + html_theme_options = { - 'collapse_navigation' : False, + 'display_version': True, + 'prev_next_buttons_location': 'both', + 'style_external_links': False, + # 'vcs_pageview_mode': '', + # 'style_nav_header_background': 'white', + # Toc options + 'sticky_navigation': True, + 'navigation_depth': 4, + 'includehidden': True, + 'titles_only': False, + + 'collapse_navigation': False, 'logo_only': True, } + + # For site map generation html_baseurl = f"https://docs.lvgl.io/{os.environ['LVGL_URLPATH']}/en/html/" @@ -151,7 +172,8 @@ html_sidebars = { } html_js_files = [ - 'js/custom.js' + 'js/custom.js', + 'js/include_html.js' ] html_favicon = 'favicon.png' diff --git a/docs/doc_builder.py b/docs/doc_builder.py new file mode 100644 index 000000000..ec9cd46b7 --- /dev/null +++ b/docs/doc_builder.py @@ -0,0 +1,713 @@ +import os +from xml.etree import ElementTree as ET + +base_path = '' +xml_path = '' + + +def load_xml(fle): + fle = os.path.join(xml_path, fle + '.xml') + + with open(fle, 'rb') as f: + d = f.read().decode('utf-8') + + # This code is to correct a bug in Doxygen. That bug incorrectly parses + # a typedef and it causes an error to occur building the docs. The Error + # doesn't stop the documentation from being generated, I just don't want + # to see the ugly red output. + # + # if 'typedef void() lv_lru_free_t(void *v)' in d: + # d = d.replace( + # '<type>void()</type>\n ' + # '<definition>typedef void() lv_lru_free_t(void *v)</definition>', + # '<type>void</type>\n ' + # '<definition>typedef void(lv_lru_free_t)(void *v)</definition>' + # ) + # with open(fle, 'wb') as f: + # f.write(d.encode('utf-8')) + + return ET.fromstring(d) + + +structures = {} +functions = {} +enums = {} +typedefs = {} +variables = {} +unions = {} +namespaces = {} +files = {} + + +class STRUCT(object): + template = '''\ +.. doxygenstruct:: {name} + :project: lvgl + :members: + :protected-members: + :private-members: + :undoc-members: +''' + + def __init__(self, parent, refid, name, **_): + if name in structures: + self.__dict__.update(structures[name].__dict__) + return + + structures[name] = self + self.parent = parent + self.refid = refid + self.name = name + self.types = set() + self._deps = None + self.header_file = '' + + root = load_xml(refid) + + for compounddef in root: + if compounddef.attrib['id'] != self.refid: + continue + + for child in compounddef: + if child.tag == 'includes': + self.header_file = os.path.splitext(child.text)[0] + + if child.tag != 'sectiondef': + continue + + for memberdef in child: + t = get_type(memberdef) + + if t is None: + continue + + self.types.add(t) + + @property + def deps(self): + if self._deps is None: + self._deps = dict( + typedefs=set(), + functions=set(), + enums=set(), + structures=set(), + unions=set(), + namespaces=set(), + variables=set(), + ) + for type_ in self.types: + if type_ in typedefs: + self._deps['typedefs'].add(typedefs[type_]) + elif type_ in structures: + self._deps['structures'].add(structures[type_]) + elif type_ in unions: + self._deps['unions'].add(unions[type_]) + elif type_ in enums: + self._deps['enums'].add(enums[type_]) + elif type_ in functions: + self._deps['functions'].add(functions[type_]) + elif type_ in variables: + self._deps['variables'].add(variables[type_]) + elif type_ in namespaces: + self._deps['namespaces'].add(namespaces[type_]) + return self._deps + + def __str__(self): + return self.template.format(name=self.name) + + +class UNION(STRUCT): + template = '''\ +.. doxygenunion:: {name} + :project: lvgl +''' + + +def get_type(node): + def gt(n): + for c in n: + if c.tag == 'ref': + t = c.text.strip() + break + else: + t = node.text.strip() + + return t.replace('*', '').replace('(', '').replace(')', '').strip() + + for child in node: + if child.tag == 'type': + return gt(child) + + +class VARIABLE(object): + template = '''\ +.. doxygenvariable:: {name} + :project: lvgl +''' + + def __init__(self, parent, refid, name, **_): + if name in variables: + self.__dict__.update(variables[name].__dict__) + return + + variables[name] = self + self.parent = parent + self.refid = refid + self.name = name + + def __str__(self): + return self.template.format(name=self.name) + + +class NAMESPACE(object): + template = '''\ +.. doxygennamespace:: {name} + :project: lvgl + :members: + :protected-members: + :private-members: + :undoc-members: +''' + + def __init__(self, parent, refid, name, **_): + if name in namespaces: + self.__dict__.update(namespaces[name].__dict__) + return + + namespaces[name] = self + self.parent = parent + self.refid = refid + self.name = name + + def __str__(self): + return self.template.format(name=self.name) + + +class FUNCTION(object): + template = '''\ +.. doxygenfunction:: {name} + :project: lvgl +''' + + def __init__(self, parent, refid, name, **_): + if name in functions: + self.__dict__.update(functions[name].__dict__) + return + + functions[name] = self + self.parent = parent + self.refid = refid + self.name = name + self.types = set() + self.restype = None + self._deps = None + + if parent is not None: + root = load_xml(parent.refid) + + for compounddef in root: + if compounddef.attrib['id'] != parent.refid: + continue + + for child in compounddef: + if child.tag != 'sectiondef': + continue + if child.attrib['kind'] != 'func': + continue + + for memberdef in child: + if memberdef.attrib['id'] == refid: + break + else: + continue + + break + else: + continue + + break + else: + return + + self.restype = get_type(memberdef) + + for child in memberdef: + if child.tag == 'param': + t = get_type(child) + if t is not None: + self.types.add(t) + + if self.restype in self.types: + self.restype = None + + @property + def deps(self): + if self._deps is None: + self._deps = dict( + typedefs=set(), + functions=set(), + enums=set(), + structures=set(), + unions=set(), + namespaces=set(), + variables=set(), + ) + if self.restype is not None: + self.types.add(self.restype) + + for type_ in self.types: + if type_ in typedefs: + self._deps['typedefs'].add(typedefs[type_]) + elif type_ in structures: + self._deps['structures'].add(structures[type_]) + elif type_ in unions: + self._deps['unions'].add(unions[type_]) + elif type_ in enums: + self._deps['enums'].add(enums[type_]) + elif type_ in functions: + self._deps['functions'].add(functions[type_]) + elif type_ in variables: + self._deps['variables'].add(variables[type_]) + elif type_ in namespaces: + self._deps['namespaces'].add(namespaces[type_]) + return self._deps + + def __str__(self): + return self.template.format(name=self.name) + + +class FILE(object): + def __init__(self, _, refid, name, node, **__): + if name in files: + self.__dict__.update(files[name].__dict__) + return + + files[name] = self + + self.refid = refid + self.name = name + self.header_file = os.path.splitext(name)[0] + + enums_ = [] + + for member in node: + if member.tag != 'member': + continue + + cls = globals()[member.attrib['kind'].upper()] + if cls == ENUM: + member.attrib['name'] = member[0].text.strip() + enums_.append(cls(self, **member.attrib)) + elif cls == ENUMVALUE: + if enums_[-1].is_member(member): + enums_[-1].add_member(member) + + else: + member.attrib['name'] = member[0].text.strip() + cls(self, **member.attrib) + + +class ENUM(object): + template = '''\ +.. doxygenenum:: {name} + :project: lvgl +''' + + def __init__(self, parent, refid, name, **_): + if name in enums: + self.__dict__.update(enums[name].__dict__) + return + + enums[name] = self + + self.parent = parent + self.refid = refid + self.name = name + self.members = [] + + def is_member(self, member): + return ( + member.attrib['kind'] == 'enumvalue' and + member.attrib['refid'].startswith(self.refid) + ) + + def add_member(self, member): + self.members.append( + ENUMVALUE( + self, + member.attrib['refid'], + member[0].text.strip() + ) + ) + + def __str__(self): + template = [self.template.format(name=self.name)] + template.extend(list(str(member) for member in self.members)) + + return '\n'.join(template) + + +defines = {} + + +class DEFINE(object): + template = '''\ +.. doxygendefine:: {name} + :project: lvgl +''' + + def __init__(self, parent, refid, name, **_): + if name in defines: + self.__dict__.update(defines[name].__dict__) + return + + defines[name] = self + + self.parent = parent + self.refid = refid + self.name = name + + def __str__(self): + return self.template.format(name=self.name) + + +class ENUMVALUE(object): + template = '''\ +.. doxygenenumvalue:: {name} + :project: lvgl +''' + + def __init__(self, parent, refid, name, **_): + self.parent = parent + self.refid = refid + self.name = name + + def __str__(self): + return self.template.format(name=self.name) + + +class TYPEDEF(object): + template = '''\ +.. doxygentypedef:: {name} + :project: lvgl +''' + + def __init__(self, parent, refid, name, **_): + if name in typedefs: + self.__dict__.update(typedefs[name].__dict__) + return + + typedefs[name] = self + + self.parent = parent + self.refid = refid + self.name = name + self.type = None + self._deps = None + + if parent is not None: + root = load_xml(parent.refid) + + for compounddef in root: + if compounddef.attrib['id'] != parent.refid: + continue + + for child in compounddef: + if child.tag != 'sectiondef': + continue + if child.attrib['kind'] != 'typedef': + continue + + for memberdef in child: + if memberdef.attrib['id'] == refid: + break + else: + continue + + break + else: + continue + + break + else: + return + + self.type = get_type(memberdef) + + @property + def deps(self): + if self._deps is None: + self._deps = dict( + typedefs=set(), + functions=set(), + enums=set(), + structures=set(), + unions=set(), + namespaces=set(), + variables=set(), + ) + if self.type is not None: + type_ = self.type + + if type_ in typedefs: + self._deps['typedefs'].add(typedefs[type_]) + elif type_ in structures: + self._deps['structures'].add(structures[type_]) + elif type_ in unions: + self._deps['unions'].add(unions[type_]) + elif type_ in enums: + self._deps['enums'].add(enums[type_]) + elif type_ in functions: + self._deps['functions'].add(functions[type_]) + elif type_ in variables: + self._deps['variables'].add(variables[type_]) + elif type_ in namespaces: + self._deps['namespaces'].add(namespaces[type_]) + + return self._deps + + def __str__(self): + return self.template.format(name=self.name) + + +classes = {} + + +class CLASS(object): + + def __init__(self, _, refid, name, node, **__): + if name in classes: + self.__dict__.update(classes[name].__dict__) + return + + classes[name] = self + + self.refid = refid + self.name = name + + enums_ = [] + + for member in node: + if member.tag != 'member': + continue + + cls = globals()[member.attrib['kind'].upper()] + if cls == ENUM: + member.attrib['name'] = member[0].text.strip() + enums_.append(cls(self, **member.attrib)) + elif cls == ENUMVALUE: + if enums_[-1].is_member(member): + enums_[-1].add_member(member) + + else: + member.attrib['name'] = member[0].text.strip() + cls(self, **member.attrib) + + +lvgl_src_path = '' +api_path = '' +html_files = {} + + +def iter_src(n, p): + if p: + out_path = os.path.join(api_path, p) + else: + out_path = api_path + + index_file = None + + if p: + src_path = os.path.join(lvgl_src_path, p) + else: + src_path = lvgl_src_path + + folders = [] + + for file in os.listdir(src_path): + if 'private' in file: + continue + + if os.path.isdir(os.path.join(src_path, file)): + folders.append((file, os.path.join(p, file))) + continue + + if not file.endswith('.h'): + continue + + if not os.path.exists(out_path): + os.makedirs(out_path) + + if index_file is None: + index_file = open(os.path.join(out_path, 'index.rst'), 'w') + if n: + index_file.write('=' * len(n)) + index_file.write('\n' + n + '\n') + index_file.write('=' * len(n)) + index_file.write('\n\n\n') + + index_file.write('.. toctree::\n :maxdepth: 2\n\n') + + name = os.path.splitext(file)[0] + index_file.write(' ' + name + '\n') + + rst_file = os.path.join(out_path, name + '.rst') + html_file = os.path.join(p, name + '.html') + html_files[name] = html_file + + with open(rst_file, 'w') as f: + f.write('.. _{0}:'.format(name)) + f.write('\n\n') + f.write('=' * len(file)) + f.write('\n') + f.write(file) + f.write('\n') + f.write('=' * len(file)) + f.write('\n\n\n') + + f.write('.. doxygenfile:: ' + file) + f.write('\n') + f.write(' :project: lvgl') + f.write('\n\n') + + for name, folder in folders: + if iter_src(name, folder): + if index_file is None: + index_file = open(os.path.join(out_path, 'index.rst'), 'w') + + if n: + index_file.write('=' * len(n)) + index_file.write('\n' + n + '\n') + index_file.write('=' * len(n)) + index_file.write('\n\n\n') + + index_file.write('.. toctree::\n :maxdepth: 2\n\n') + + index_file.write(' ' + os.path.split(folder)[-1] + '/index\n') + + if index_file is not None: + index_file.write('\n') + index_file.close() + return True + + return False + + +def clean_name(nme): + if nme.startswith('_lv_'): + nme = nme[4:] + elif nme.startswith('lv_'): + nme = nme[3:] + + if nme.endswith('_t'): + nme = nme[:-2] + + return nme + + +def is_name_match(item_name, obj_name): + u_num = item_name.count('_') + 1 + + obj_name = obj_name.split('_') + if len(obj_name) < u_num: + return False + obj_name = '_'.join(obj_name[:u_num]) + + return item_name == obj_name + + +def get_includes(name1, name2, obj, includes): + name2 = clean_name(name2) + + if not is_name_match(name1, name2): + return + + if obj.parent is not None: + header_file = obj.parent.header_file + elif hasattr(obj, 'header_file'): + header_file = obj.header_file + else: + return + + if not header_file: + return + + if header_file not in html_files: + return + + includes.add((header_file, html_files[header_file])) + + +def run(project_path, temp_directory, *doc_paths): + global base_path + global xml_path + global lvgl_src_path + global api_path + + base_path = temp_directory + xml_path = os.path.join(base_path, 'xml') + api_path = os.path.join(base_path, 'API') + lvgl_src_path = os.path.join(project_path, 'src') + + if not os.path.exists(api_path): + os.makedirs(api_path) + + iter_src('API', '') + index = load_xml('index') + + for compound in index: + compound.attrib['name'] = compound[0].text.strip() + if compound.attrib['kind'] in ('example', 'page', 'dir'): + continue + + globals()[compound.attrib['kind'].upper()]( + None, + node=compound, + **compound.attrib + ) + + for folder in doc_paths: + items = list( + (os.path.splitext(item)[0], os.path.join(folder, item)) + for item in os.listdir(folder) + if item.endswith('rst') and 'index' not in item + ) + + for name, path in items: + html_includes = set() + + for container in ( + defines, + enums, + variables, + namespaces, + structures, + unions, + typedefs, + functions + ): + for n, o in container.items(): + get_includes(name, n, o, html_includes) + + if html_includes: + html_includes = list( + ':ref:`{0}`\n'.format(inc) + for inc, _ in html_includes + ) + + output = ('\n'.join(html_includes)) + '\n' + + with open(path, 'rb') as f: + try: + data = f.read().decode('utf-8') + except UnicodeDecodeError: + print(path) + raise + + data = data.split('.. Autogenerated', 1)[0] + + data += '.. Autogenerated\n\n' + data += output + + with open(path, 'wb') as f: + f.write(data.encode('utf-8')) diff --git a/docs/example_list.py b/docs/example_list.py index c65554e33..36706bc21 100755 --- a/docs/example_list.py +++ b/docs/example_list.py @@ -3,123 +3,160 @@ 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" + # print(path) + with open(path, 'r') as fp: + data = fp.read() + + data = data.split('\n') + + last_line = "" + title_tmp = "" + + for line in data: + line = line.strip() + + if not line: + continue + + if line.startswith('---'): + title_tmp = last_line.strip() + + elif line.startswith('.. lv_example::'): + name = line.replace('.. lv_example::', '').strip() + yield name, title_tmp + + last_line = line + + +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", + "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", +} + +HEADING = '=' +CHAPTER = '#' +SECTION = '*' +SUBSECTION = '=' +SUBSUBSECTION = '-' + + +def write_header(h_num, text, f): + text = text.strip() + if h_num == 0: + f.write(header_defs[h_num] * len(text)) + f.write('\n') + + f.write(text + '\n') + f.write(header_defs[h_num] * len(text)) + f.write('\n\n') + + +# This is the order that Sphinx uses for the headings/titles. 0 is the +# largest and 4 is the smallest. If this order is not kept in the reST files +# Sphinx will complain +header_defs = { + 0: HEADING, + 1: CHAPTER, + 2: SECTION, + 3: SUBSECTION, + 4: SUBSUBSECTION } layouts = { -"flex":"Flex", -"grid":"Grid", + "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("") + for k in d: + v = d[k] + if k.startswith(path + "/lv_example_"): + write_header(lvl, v, fout) + fout.write(f".. lv_example:: {k}\n") + fout.write("\n") + + +def exec(temp_directory): + output_path = os.path.join(temp_directory, 'examples.rst') + + paths = ["../examples/", "../demos/"] + fout = open(output_path, "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_all.update(dict(tuple(item for item in process_index_rst(fn)))) + + # 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\n') + write_header(0, 'Examples', fout) + + for h in h1: + write_header(1, h1[h], fout) + + if h == "widgets": + for w in widgets: + write_header(2, widgets[w], fout) + print_item(h + "/" + w, 3, d_all, fout) + elif h == "layouts": + for l in layouts: + write_header(2, layouts[l], fout) + print_item(h + "/" + l, 3, d_all, fout) + else: + print_item(h, 2, d_all, fout) + + fout.write("") diff --git a/docs/get-started/bindings/cpp.md b/docs/get-started/bindings/cpp.rst index 12601659f..2a1997a99 100644 --- a/docs/get-started/bindings/cpp.md +++ b/docs/get-started/bindings/cpp.rst @@ -1,4 +1,5 @@ -# Cpp +=== +Cpp +=== In progress: https://github.com/lvgl/lv_binding_cpp - diff --git a/docs/get-started/bindings/index.md b/docs/get-started/bindings/index.rst index 2bcdcd4ac..762b9c458 100644 --- a/docs/get-started/bindings/index.md +++ b/docs/get-started/bindings/index.rst @@ -1,8 +1,8 @@ -# Bindings +======== +Bindings +======== -```eval_rst - .. toctree:: :maxdepth: 2 @@ -10,5 +10,3 @@ cpp pikascript javascript -``` - diff --git a/docs/get-started/bindings/javascript.md b/docs/get-started/bindings/javascript.md deleted file mode 100644 index 789702f75..000000000 --- a/docs/get-started/bindings/javascript.md +++ /dev/null @@ -1,113 +0,0 @@ -# JavaScript - -With [lv_binding_js](https://github.com/lvgl/lv_binding_js) you can write lvgl with JavaScript. - -It uses React's virtual DOM concept to manipulate lvgl UI components, providing a familiar React-like experience to users. - -**Code** - -<img src="../../_static/img/js_code.png"> - - -**Code Runing on Real Device** - -<img src="../../_static/img/js_on_device.jpg" style="transform: rotate(270deg); max-width: 400px; padding-left: 100px;"> - -## Table of Contents - - - [Features](#features) - - [Demo](#demo) - - [Building](#building) - - [Components](#components) - - [Font](#font) - - [Animation](#animation) - - [Style](#style) - - [JSAPI](#jsapi) - - [Thanks](#thanks) - - -## Features - -- Support all lvgl built-in components -- Fully suport lvgl flex and grid style -- support most lvgl style，just write like html5 css -- support dynamic load image -- Fully support lvgl animation - -## Demo - -See the [demo](https://github.com/lvgl/lv_binding_js/tree/master/demo) folder - - -## Building - -The following are developer notes on how to build lvgljs on your native platform. They are not complete guides, but include notes on the necessary libraries, compile flags, etc. - -### lvgljs - -- [ubuntu build Notes for sdl simulator](https://github.com/lvgl/lv_binding_js/blob/master/doc/build/build-ubuntu-arm.md) -- [macos x86 build Notes for sdl simulator](https://github.com/lvgl/lv_binding_js/blob/master/doc/build/build-macos-x86-simulator.md) -- [ubuntu build Notes for platform arm](https://github.com/lvgl/lv_binding_js/blob/master/doc/build/build-ubuntu-x86-simualtor.md) - -### JS Bundle -- [JS Bundle build Notes](https://github.com/lvgl/lv_binding_js/blob/master/doc/build/js-bundle.md) - -## Components - -- [View](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/View.md) -- [Image](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Image.md) -- [Button](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Button.md) -- [Text](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Text.md) -- [Input](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Input.md) -- [Textarea](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Textarea.md) -- [Switch](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Switch.md) -- [Checkbox](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Checkbox.md) -- [Dropdownlist](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Dropdownlist.md) -- [ProgressBar](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/ProgressBar.md) -- [Line](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Line.md) -- [Roller](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Roller.md) -- [Keyboard](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Keyboard.md) -- [Calendar](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Calendar.md) -- [Chart](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Chart.md) - -## Font - -[Buitin-Symbol](https://github.com/lvgl/lv_binding_js/blob/master/doc/Symbol/symbol.md) - -## Animation - -[Animation](https://github.com/lvgl/lv_binding_js/blob/master/doc/animate/animate.md) - -## Style - -- [position-size-layout](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/position-size-layout.md) -- [boxing-model](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/boxing-model.md) -- [color](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/color.md) -- [flex](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/flex.md) -- [grid](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/grid.md) -- [font](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/font.md) -- [opacity](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/opacity.md) -- [display](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/display.md) -- [background](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/background.md) -- [scroll](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/scroll.md) -- [shadow](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/shadow.md) -- [recolor](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/recolor.md) -- [line](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/line.md) -- [transition](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/transition.md) -- [transform](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/transform.md) - -## JSAPI - -- [network](https://github.com/lvgl/lv_binding_js/blob/master/doc/jsapi/network.md) -- [filesystem](https://github.com/lvgl/lv_binding_js/blob/master/doc/jsapi/fs.md) -- [dimension](https://github.com/lvgl/lv_binding_js/blob/master/doc/jsapi/dimension.md) - -## Thanks - -lvgljs depends on following excellent work - -[lvgl](https://github.com/lvgl/lvgl): Create beautiful UIs for any MCU, MPU and display type -[QuickJS](https://bellard.org/quickjs/): JavaScript engine -[libuv](https://github.com/libuv/libuv): platform abstraction layer -[curl](https://github.com/curl/curl): HTTP client -[txiki.js](https://github.com/saghul/txiki.js): Tiny JavaScript runtime diff --git a/docs/get-started/bindings/javascript.rst b/docs/get-started/bindings/javascript.rst new file mode 100644 index 000000000..ce996df62 --- /dev/null +++ b/docs/get-started/bindings/javascript.rst @@ -0,0 +1,133 @@ +========== +JavaScript +========== + +With `lv_binding_js <https://github.com/lvgl/lv_binding_js>`__ you can +write lvgl with JavaScript. + +It uses React’s virtual DOM concept to manipulate lvgl UI components, +providing a familiar React-like experience to users. + +**Code** + +**Code Runing on Real Device** + +Table of Contents +----------------- + +- `Features <#features>`__ +- `Demo <#demo>`__ +- `Building <#building>`__ +- `Components <#components>`__ +- `Font <#font>`__ +- `Animation <#animation>`__ +- `Style <#style>`__ +- `JSAPI <#jsapi>`__ +- `Thanks <#thanks>`__ + +Features +-------- + +- Support all lvgl built-in components +- Fully suport lvgl flex and grid style +- support most lvgl style，just write like html5 css +- support dynamic load image +- Fully support lvgl animation + +Demo +---- + +See the +`demo <https://github.com/lvgl/lv_binding_js/tree/master/demo>`__ folder + +Building +-------- + +The following are developer notes on how to build lvgljs on your native +platform. They are not complete guides, but include notes on the +necessary libraries, compile flags, etc. + +lvgljs +~~~~~~ + +- `ubuntu build Notes for sdl + simulator <https://github.com/lvgl/lv_binding_js/blob/master/doc/build/build-ubuntu-arm.md>`__ +- `macos x86 build Notes for sdl + simulator <https://github.com/lvgl/lv_binding_js/blob/master/doc/build/build-macos-x86-simulator.md>`__ +- `ubuntu build Notes for platform + arm <https://github.com/lvgl/lv_binding_js/blob/master/doc/build/build-ubuntu-x86-simualtor.md>`__ + +JS Bundle +~~~~~~~~~ + +- `JS Bundle build + Notes <https://github.com/lvgl/lv_binding_js/blob/master/doc/build/js-bundle.md>`__ + +Components +---------- + +- `View <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/View.md>`__ +- `Image <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Image.md>`__ +- `Button <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Button.md>`__ +- `Text <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Text.md>`__ +- `Input <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Input.md>`__ +- `Textarea <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Textarea.md>`__ +- `Switch <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Switch.md>`__ +- `Checkbox <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Checkbox.md>`__ +- `Dropdownlist <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Dropdownlist.md>`__ +- `ProgressBar <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/ProgressBar.md>`__ +- `Line <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Line.md>`__ +- `Roller <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Roller.md>`__ +- `Keyboard <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Keyboard.md>`__ +- `Calendar <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Calendar.md>`__ +- `Chart <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Chart.md>`__ + +Font +---- + +`Buitin-Symbol <https://github.com/lvgl/lv_binding_js/blob/master/doc/Symbol/symbol.md>`__ + +Animation +--------- + +`Animation <https://github.com/lvgl/lv_binding_js/blob/master/doc/animate/animate.md>`__ + +Style +----- + +.. include::https://github.com/lvgl/lv_binding_js/blob/master/doc/style/position-size-layout.md + +- `position-size-layout <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/position-size-layout.md>`__ +- `boxing-model <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/boxing-model.md>`__ +- `color <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/color.md>`__ +- `flex <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/flex.md>`__ +- `grid <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/grid.md>`__ +- `font <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/font.md>`__ +- `opacity <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/opacity.md>`__ +- `display <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/display.md>`__ +- `background <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/background.md>`__ +- `scroll <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/scroll.md>`__ +- `shadow <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/shadow.md>`__ +- `recolor <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/recolor.md>`__ +- `line <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/line.md>`__ +- `transition <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/transition.md>`__ +- `transform <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/transform.md>`__ + +JSAPI +----- + +- `network <https://github.com/lvgl/lv_binding_js/blob/master/doc/jsapi/network.md>`__ +- `filesystem <https://github.com/lvgl/lv_binding_js/blob/master/doc/jsapi/fs.md>`__ +- `dimension <https://github.com/lvgl/lv_binding_js/blob/master/doc/jsapi/dimension.md>`__ + +Thanks +------ + +lvgljs depends on following excellent work + +`lvgl <https://github.com/lvgl/lvgl>`__: Create beautiful UIs for any +MCU, MPU and display type `QuickJS <https://bellard.org/quickjs/>`__: +JavaScript engine `libuv <https://github.com/libuv/libuv>`__: platform +abstraction layer `curl <https://github.com/curl/curl>`__: HTTP client +`txiki.js <https://github.com/saghul/txiki.js>`__: Tiny JavaScript +runtime diff --git a/docs/get-started/bindings/micropython.md b/docs/get-started/bindings/micropython.md deleted file mode 100644 index 15ed61404..000000000 --- a/docs/get-started/bindings/micropython.md +++ /dev/null @@ -1,193 +0,0 @@ -# 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? - -Micropython [does not have a good native high-level GUI library](https://forum.micropython.org/viewtopic.php?f=18&t=5543). 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.ALIGN.CENTER, 0, 0) -label = lv.label(btn) -label.set_text('Hello World!') -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/) - -Many [LVGL examples](https://docs.lvgl.io/master/examples.html) are available also for Micropython. -Just click the - <img src="https://user-images.githubusercontent.com/11742638/198729010-35a12e49-4945-414a-8c3e-d32bc95da940.png" align=middle /> link! - -### 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 Platforms - -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. [lv_micropython](https://github.com/lvgl/lv_micropython) is a fork of Micropython+LVGL and currently supports Linux, ESP32, STM32 and RP2. It can be ported to any other platform supported by Micropython. - -You would also need display and input drivers. You can either use one of the existing drivers provided with lv_micropython, or you can create your own input/display drivers for your specific hardware. -Drivers can be implemented either in C as a Micropython module, or in pure Python! - -lv_micropython already contains these drivers: -- Display drivers: - - SDL on Linux - - ESP32 specific: ILI9341, ILI9488, GC9A01, ST7789, ST7735 - - Generic (pure Python): ILI9341, ST7789, ST7735 -- Input drivers: - - SDL, XPT2046, FT6X36, ESP32 ADC with resistive touch - -## Where can I find more information? - -- `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/) -- [Blog Post](https://blog.lvgl.io/2019-02-20/micropython-bindings), a little outdated. - -## The Micropython Binding is auto generated! - -LVGL is a git submodule inside [lv_micropython](https://github.com/lvgl/lv_micropython) (LVGL is a git submodule of [lv_binding_micropython](https://github.com/lvgl/lv_binding_micropython) which is itself a submodule of [lv_micropython](https://github.com/lvgl/lv_micropython)). -When building lv_micropython, the public LVGL C API is scanned and Micropython API is auto-generated. That means that lv_micropython provides LVGL API for **any** LVGL version, and generally does not require code changes as LVGL evolves. - -### LVGL C API Coding Conventions - -To support the auto-generation of the Python API, the LVGL C API must follow some coding conventions: - -- Use `enum`s instead of macros. If inevitable to use `define`s export them with `LV_EXPORT_CONST_INT(defined_value)` right after the `define`. -- In function arguments use `type name[]` declaration for array parameters instead of `type * name` -- Use typed pointers instead of `void *` pointers -- Widget constructor must follow the `lv_<widget_name>_create(lv_obj_t * parent)` pattern. -- Widget members function must start with `lv_<modul_name>` and should receive `lv_obj_t *` as first argument which is a pointer to widget object itself. -- `struct` APIs should follow the widgets' conventions. That is to receive a pointer to the `struct` as the first argument, and the prefix of the `struct` name should be used as the prefix of the function name too (e.g. `lv_disp_set_default(lv_disp_t * disp)`) -- Functions and `struct`s which are not part of the public API must begin with underscore in order to mark them as "private". -- Argument must be named in H files too. -- Do not `malloc` into a static or global variables. Instead declare the variable in `LV_ITERATE_ROOTS` list in `lv_gc.h` and mark the variable with `GC_ROOT(variable)` when it's used. -**See [Memory Management](#memory-management)** -- To register and use callbacks one of the followings needs to be followed. **See [Callbacks](#callbacks)** - - Pass a pointer to a `struct` as the first argument of both the registration function and the callback. That `struct` must contain `void * user_data` field. - - The last argument of the registration function must be `void * user_data` and the same `user_data` needs to be passed as the last argument of the callback. - -Most of these rules are simple and straightforward but there are two related concepts that worth a deeper look: **Memory Management** and **Callbacks**. - -### Memory Management - -When LVGL runs in Micropython, all dynamic memory allocations (`lv_malloc`) are handled by Micropython's memory manager which is [garbage-collected](https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)) (GC). -To prevent GC from collecting memory prematurely, all dynamic allocated RAM must be reachable by GC. -GC is aware of most allocations, except from pointers on the [Data Segment](https://en.wikipedia.org/wiki/Data_segment): -- Pointers which are global variables -- Pointers which are static global variables -- Pointers which are static local variables - -Such pointers need to be defined in a special way to make them reachable by GC - -#### Identify The Problem - -Problem happens when an allocated memory's pointer (return value of `lv_malloc`) is stored only in either **global**, **static global** or **static local** pointer variable and not as part of a previously allocated `struct` or other variable. - -#### Solve The Problem - -- Replace the global/static local var with `LV_GC_ROOT(_var)` -- Include `lv_gc.h` on files that use `LV_GC_ROOT` -- Add `_var` to `LV_ITERATE_ROOTS` on `lv_gc.h` - -#### Example - -https://github.com/lvgl/lvgl/commit/adced46eccfa0437f84aa51aedca4895cc3c679c - -#### More Information - -- [In the README](https://github.com/lvgl/lv_binding_micropython#memory-management) -- [In the Blog](https://blog.lvgl.io/2019-02-20/micropython-bindings#i-need-to-allocate-a-littlevgl-struct-such-as-style-color-etc-how-can-i-do-that-how-do-i-allocatedeallocate-memory-for-it) - -### Callbacks - -In C a callback is just a function pointer. -But in Micropython we need to register a *Micropython callable object* for each callback. -Therefore in the Micropython binding we need to register both a function pointer and a Micropython object for every callback. - -Therefore we defined a **callback convention** for the LVGL C API that expects lvgl headers to be defined in a certain way. Callbacks that are declared according to the convention would allow the binding to register a Micropython object next to the function pointer when registering a callback, and access that object when the callback is called. - -The basic idea is that we have `void * user_data` field that is used automatically by the Micropython Binding to save the *Micropython callable object* for a callback. This field must be provided when registering the function pointer, and provided to the callback function itself. -Although called "user_data", the user is not expectd to read/write that field. Instead, the Micropython glue code uses `user_data` to automatically keep track of the Micropython callable object. The glue code updates it when the callback is registered, and uses it when the callback is called in order to invoke a call to the original callable object. - -There are a few options for defining a callback in LVGL C API: -- Option 1: `user_data` in a struct - - There's a struct that contains a field called `void * user_data` - - A pointer to that struct is provided as the **first** argument of a callback registration function - - A pointer to that struct is provided as the **first** argument of the callback itself -- Option 2: `user_data` as a function argument - - A parameter called `void * user_data` is provided to the registration function as the **last** argument - - The callback itself recieves `void *` as the **last** argument -- Option 3: both callback and `user_data` are struct fields - - The API exposes a struct with both function pointer member and `user_data` member - - The function pointer member receives the same struct as its **first** argument - -In practice it's also possible to mix these options, for example provide a struct pointer when registering a callback (option 1) and provide `user_data` argument when calling the callback (options 2), **as long as the same `user_data` that was registered is passed to the callback when it's called**. - -#### Examples - -- [lv_anim_t](https://github.com/lvgl/lvgl/blob/5d50fbc066938d1a4eb43a8366cf83fbd4ce29f2/src/misc/lv_anim.h#L73-L100) contains `user_data` field. -[lv_anim_set_path_cb](https://github.com/lvgl/lvgl/blob/5d50fbc066938d1a4eb43a8366cf83fbd4ce29f2/src/misc/lv_anim.h#L197) registers `path_cb` callback. Both `lv_anim_set_path_cb` and [`lv_anim_path_cb_t`](https://github.com/lvgl/lvgl/blob/5d50fbc066938d1a4eb43a8366cf83fbd4ce29f2/src/misc/lv_anim.h#L46) recieve `lv_anim_t` as their first argument -- [`path_cb` field](https://github.com/lvgl/lvgl/blob/5d50fbc066938d1a4eb43a8366cf83fbd4ce29f2/src/misc/lv_anim.h#L83) can also be assigned directly in the Python code because it's a member of `lv_anim_t` which contains `user_data` field, and [`lv_anim_path_cb_t`](https://github.com/lvgl/lvgl/blob/5d50fbc066938d1a4eb43a8366cf83fbd4ce29f2/src/misc/lv_anim.h#L46) recieve `lv_anim_t` as its first argument. -- [`lv_imgfont_create`](https://github.com/lvgl/lvgl/blob/5d50fbc066938d1a4eb43a8366cf83fbd4ce29f2/src/others/imgfont/lv_imgfont.h#L43) registers `path_cb` and recieves `user_data` as the last argument. The callback [`lv_imgfont_get_path_cb_t`](https://github.com/lvgl/lvgl/blob/5d50fbc066938d1a4eb43a8366cf83fbd4ce29f2/src/others/imgfont/lv_imgfont.h#L29-L31) also receieves the `user_data` as the last argument. - -#### More Information - -- In the [Blog](https://blog.lvgl.io/2019-08-05/micropython-pure-display-driver#using-callbacks) and in the [README](https://github.com/lvgl/lv_binding_micropython#callbacks) -- [[v6.0] Callback conventions #1036](https://github.com/lvgl/lvgl/issues/1036) -- Various discussions: [here](https://github.com/lvgl/lvgl/pull/3294#issuecomment-1184895335) and [here](https://github.com/lvgl/lvgl/issues/1763#issuecomment-762247629) and [here](https://github.com/lvgl/lvgl/issues/316#issuecomment-467221587) diff --git a/docs/get-started/bindings/micropython.rst b/docs/get-started/bindings/micropython.rst new file mode 100644 index 000000000..9ffa8927f --- /dev/null +++ b/docs/get-started/bindings/micropython.rst @@ -0,0 +1,316 @@ +.. _micropython: + +=========== +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? +----------------------- + +Micropython `does not have a good native high-level GUI library <https://forum.micropython.org/viewtopic.php?f=18&t=5543>`__. +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? +-------------------------- + +It's very much like the C API, but Object-Oriented for LVGL components. + +Let's dive right into an example! + + +A simple example +~~~~~~~~~~~~~~~~ + +.. code:: python + + import lvgl as lv + lv.init() + scr = lv.obj() + btn = lv.btn(scr) + btn.align(lv.ALIGN.CENTER, 0, 0) + label = lv.label(btn) + label.set_text('Hello World!') + 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/>`__ + +Many `LVGL examples <https://docs.lvgl.io/master/examples.html>`__ are available also for Micropython. Just click the link! + + +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 Platforms +~~~~~~~~~~~~~~~~~~ + +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. `lv_micropython <https://github.com/lvgl/lv_micropython>`__ is a fork of Micropython+LVGL and currently +supports Linux, ESP32, STM32 and RP2. It can be ported to any other platform supported by Micropython. + +- You would also need display and input drivers. You can either use one of the existing drivers provided with lv_micropython, + or you can create your own input/display drivers for your specific hardware. +- Drivers can be implemented either in C as a Micropython module, or in pure Python! + +lv_micropython already contains these drivers: + +- Display drivers: + + - SDL on Linux + - ESP32 specific: + + - ILI9341 + - ILI9488 + - GC9A01 + - ST7789 + - ST7735 + + - Generic (pure Python): + + - ILI9341 + - ST7789 + - ST7735 + +- Input drivers: + + - SDL + - XPT2046 + - FT6X36 + - ESP32 ADC with resistive touch + + +Where can I find more information? +---------------------------------- + +- ``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/>`__ +- `Blog Post <https://blog.lvgl.io/2019-02-20/micropython-bindings>`__, a little outdated. + + +The Micropython Binding is auto generated! +------------------------------------------ + +- LVGL is a git submodule inside `lv_micropython <https://github.com/lvgl/lv_micropython>`__ + (LVGL is a git submodule of `lv_binding_micropython <https://github.com/lvgl/lv_binding_micropython>`__ + which is itself a submodule of `lv_micropython <https://github.com/lvgl/lv_micropython>`__). +- When building lv_micropython, the public LVGL C API is scanned and Micropython API is auto-generated. That means that + lv_micropython provides LVGL API for **any** LVGL version, and generally does not require code changes as LVGL evolves. + + +LVGL C API Coding Conventions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To support the auto-generation of the Python API, the LVGL C API must +follow some coding conventions: + +- Use ``enum``\ s instead of macros. If inevitable to use ``define``\ s + export them with :cpp:expr:`LV_EXPORT_CONST_INT(defined_value)` right after the ``define``. +- In function arguments use ``type name[]`` declaration for array parameters instead of :cpp:expr:`type * name` +- Use typed pointers instead of :cpp:expr:`void *` pointers +- Widget constructor must follow the ``lv_<widget_name>_create(lv_obj_t * parent)`` pattern. +- Widget members function must start with ``lv_<modul_name>`` and should receive :cpp:expr:`lv_obj_t *` as first + argument which is a pointer to widget object itself. +- ``struct`` APIs should follow the widgets' conventions. That is to receive a pointer to the ``struct`` as the + first argument, and the prefix of the ``struct`` name should be used as the prefix of the + function name too (e.g. :cpp:expr:`lv_disp_set_default(lv_disp_t * disp)`) +- Functions and ``struct``\ s which are not part of the public API must begin with underscore in order to mark them as “private”. +- Argument must be named in H files too. +- Do not ``malloc`` into a static or global variables. Instead declare the variable in :c:macro:`LV_ITERATE_ROOTS` + list in ``lv_gc.h`` and mark the variable with :cpp:expr:`GC_ROOT(variable)` when it's used. **See** :ref:`memory_management` +- To register and use callbacks one of the followings needs to be followed. **See** :ref:`callbacks` + + - Pass a pointer to a ``struct`` as the first argument of both the registration function and the callback. That + ``struct`` must contain ``void * user_data`` field. + - The last argument of the registration function must be ``void * user_data`` and the same ``user_data`` + needs to be passed as the last argument of the callback. + +Most of these rules are simple and straightforward but there are two related concepts that worth a deeper look: +:ref:`memory_management` and :ref:`callbacks`. + +.. _memory_management: + +Memory Management +~~~~~~~~~~~~~~~~~ + +| When LVGL runs in Micropython, all dynamic memory allocations (:cpp:func:`lv_malloc`) are handled by Micropython's memory + manager which is `garbage-collected <https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)>`__ (GC). +| To prevent GC from collecting memory prematurely, all dynamic allocated RAM must be reachable by GC. +| GC is aware of most allocations, except from pointers on the `Data Segment <https://en.wikipedia.org/wiki/Data_segment>`__: + + - Pointers which are global variables + - Pointers which are static global variables + - Pointers which are static local variables + +Such pointers need to be defined in a special way to make them reachable by GC + + +Identify The Problem +^^^^^^^^^^^^^^^^^^^^ + +Problem happens when an allocated memory's pointer (return value of :cpp:func:`lv_malloc`) is stored only in either **global**, +**static global** or **static local** pointer variable and not as part of a previously allocated ``struct`` or other variable. + + +Solve The Problem +^^^^^^^^^^^^^^^^^ + +- Replace the global/static local var with :cpp:expr:`LV_GC_ROOT(_var)` +- Include ``lv_gc.h`` on files that use :c:macro:`LV_GC_ROOT` +- Add ``_var`` to :c:macro:`LV_ITERATE_ROOTS` on ``lv_gc.h`` + +Example +^^^^^^^ + +https://github.com/lvgl/lvgl/commit/adced46eccfa0437f84aa51aedca4895cc3c679c + + +More Information +^^^^^^^^^^^^^^^^ + +- `In the README <https://github.com/lvgl/lv_binding_micropython#memory-management>`__ +- `In the Blog <https://blog.lvgl.io/2019-02-20/micropython-bindings#i-need-to-allocate-a-littlevgl-struct-such-as-style-color-etc-how-can-i-do-that-how-do-i-allocatedeallocate-memory-for-it>`__ + +.. _callbacks: + +Callbacks +~~~~~~~~~ + +In C a callback is just a function pointer. But in Micropython we need to register a *Micropython callable object* for each +callback. Therefore in the Micropython binding we need to register both a function pointer and a Micropython object for every callback. + +Therefore we defined a **callback convention** for the LVGL C API that expects lvgl headers to be defined in a certain +way. Callbacks that are declared according to the convention would allow the binding to register a Micropython object +next to the function pointer when registering a callback, and access that object when the callback is called. + +- The basic idea is that we have ``void * user_data`` field that is used automatically by the Micropython Binding + to save the *Micropython callable object* for a callback. This field must be provided when registering the function + pointer, and provided to the callback function itself. +- Although called "user_data", the user is not expectd to read/write that field. Instead, the Micropython glue code uses + ``user_data`` to automatically keep track of the Micropython callable object. The glue code updates it when the callback + is registered, and uses it when the callback is called in order to invoke a call to the original callable object. + +There are a few options for defining a callback in LVGL C API: + +- Option 1: ``user_data`` in a struct + + - There's a struct that contains a field called ``void * user_data`` + + - A pointer to that struct is provided as the **first** argument of a callback registration function + - A pointer to that struct is provided as the **first** argument of the callback itself + +- Option 2: ``user_data`` as a function argument + + - A parameter called ``void * user_data`` is provided to the registration function as the **last** argument + + - The callback itself recieves ``void *`` as the **last** argument + +- Option 3: both callback and ``user_data`` are struct fields + + - The API exposes a struct with both function pointer member and ``user_data`` member + + - The function pointer member receives the same struct as its **first** argument + +In practice it's also possible to mix these options, for example provide a struct pointer when registering a callback +(option 1) and provide ``user_data`` argument when calling the callback (options 2), +**as long as the same ``user_data`` that was registered is passed to the callback when it's called**. + +Examples +^^^^^^^^ + +- :cpp:type:`lv_anim_t` contains ``user_data`` field. :cpp:func:`lv_anim_set_path_cb` + registers `path_cb` callback. Both ``lv_anim_set_path_cb`` and :cpp:type:`lv_anim_path_cb_t` + recieve :cpp:type:`lv_anim_t` as their first argument +- ``path_cb`` field can also be assigned directly in the Python code because it's a member + of :cpp:type:`lv_anim_t` which contains ``user_data`` field, and :cpp:type:`lv_anim_path_cb_t` + recieve :cpp:type:`lv_anim_t` as its first argument. +- :cpp:func:`lv_imgfont_create` registers ``path_cb`` and recieves ``user_data`` as the last + argument. The callback :cpp:func:`lv_imgfont_get_path_cb_t` also receieves the ``user_data`` as the last argument. + +.. _more-information-1: + +More Information +^^^^^^^^^^^^^^^^ + +- In the `Blog <https://blog.lvgl.io/2019-08-05/micropython-pure-display-driver#using-callbacks>`__ + and in the `README <https://github.com/lvgl/lv_binding_micropython#callbacks>`__ +- `[v6.0] Callback conventions #1036 <https://github.com/lvgl/lvgl/issues/1036>`__ +- Various discussions: `here <https://github.com/lvgl/lvgl/pull/3294#issuecomment-1184895335>`__ + and `here <https://github.com/lvgl/lvgl/issues/1763#issuecomment-762247629>`__ + and`here <https://github.com/lvgl/lvgl/issues/316#issuecomment-467221587>`__ diff --git a/docs/get-started/bindings/pikascript.md b/docs/get-started/bindings/pikascript.md deleted file mode 100644 index 6c9322659..000000000 --- a/docs/get-started/bindings/pikascript.md +++ /dev/null @@ -1,162 +0,0 @@ -# PikaScript - -## What is PikaScript ? - -[PikaScript](https://github.com/pikasTech/pikascript) is a Python interpreter designed specifically for microcontrollers, and it supports a subset of the common Python3 syntax. - -It's lighter, requiring only 32k of code space and 4k of RAM, which means it can run on stm32f103c8 (blue-pill) or even stm32g030c8, on the other hand, you can leave valuable space for more material or larger buffer areas. - -It is simpler, out of the box, runs with no porting and configuration at all, does not depend on OS or file system, has good support for popular IDEs for Windows platforms like Keil, IAR, RT-Thread-Studio, and of course, supports linux-gcc development platforms. - -It's smarter, with a unique C module mechanism that allows you to generate bindings automatically by simply writing the API for the C module in Python, and you don't need to deal with the headache of writing any macros or global tables manually. On the other hand, all C modules have sophisticated smart hints, even hinting at the types of your arguments . - ---- - -## Why PikaScript + LVGL ? - -PikaScript now supports the main features of LVGL8, and these APIs are fully compatible with Micropython! - -This means that you can continue to use already written code from Micropython, and then use less code space and RAM. - -Enjoy detailed code hints down to the parameter type for a better programming experience - -Use a more convenient IDE, such as vs-based simulation projects - -## So how does it look like? - -Here are some examples of lvgl that PikaScript can already run, they are mainly from the lvgl documentation examples - -### LV_ARC - -```python -import pika_lvgl as lv -import PikaStdLib -mem = PikaStdLib.MemChecker() -# Create an Arc -arc = lv.arc(lv.scr_act()) -arc.set_end_angle(200) -arc.set_size(150, 150) -arc.center() -print('mem used max: %0.2f kB' % (mem.getMax())) -print('mem used now: %0.2f kB' % (mem.getNow())) -``` - -### LV_BAR - -``` python -import pika_lvgl as lv -import PikaStdLib -mem = PikaStdLib.MemChecker() -bar1 = lv.bar(lv.scr_act()) -bar1.set_size(200, 20) -bar1.center() -bar1.set_value(70, lv.ANIM.OFF) -print('mem used max: %0.2f kB' % (mem.getMax())) -print('mem used now: %0.2f kB' % (mem.getNow())) -``` - -### LV_BTN - -``` python -import pika_lvgl as lv -import PikaStdLib -mem = PikaStdLib.MemChecker() -def event_cb_1(evt): - print('in evt1') - print('mem used now: %0.2f kB' % (mem.getNow())) -def event_cb_2(evt): - print('in evt2') - print('mem used now: %0.2f kB' % (mem.getNow())) -btn1 = lv.btn(lv.scr_act()) -btn1.align(lv.ALIGN.TOP_MID, 0, 10) -btn2 = lv.btn(lv.scr_act()) -btn2.align(lv.ALIGN.TOP_MID, 0, 50) -btn1.add_event(event_cb_1, lv.EVENT.CLICKED, 0) -btn2.add_event(event_cb_2, lv.EVENT.CLICKED, 0) -print('mem used max: %0.2f kB' % (mem.getMax())) -print('mem used now: %0.2f kB' % (mem.getNow())) -``` - -### LV_CHECKBOX - -``` python -import pika_lvgl as lv -import PikaStdLib -mem = PikaStdLib.MemChecker() -cb = lv.checkbox(lv.scr_act()) -cb.set_text("Apple") -cb.align(lv.ALIGN.TOP_LEFT, 0 ,0) -cb = lv.checkbox(lv.scr_act()) -cb.set_text("Banana") -cb.add_state(lv.STATE.CHECKED) -cb.align(lv.ALIGN.TOP_LEFT, 0 ,30) -cb = lv.checkbox(lv.scr_act()) -cb.set_text("Lemon") -cb.add_state(lv.STATE.DISABLED) -cb.align(lv.ALIGN.TOP_LEFT, 0 ,60) -cb = lv.checkbox(lv.scr_act()) -cb.add_state(lv.STATE.CHECKED | lv.STATE.DISABLED) -cb.set_text("Melon") -cb.align(lv.ALIGN.TOP_LEFT, 0 ,90) -print('mem used max: %0.2f kB' % (mem.getMax())) -print('mem used now: %0.2f kB' % (mem.getNow())) -``` - ---- - -## How does it work? - -PikaScript has a unique C module smart binding tool - -Just write the Python interface in pika_lvgl.pyi (.pyi is the python interface file) - -``` python -# pika_lvgl.pyi -class arc(lv_obj): - def set_end_angle(self, angle: int): ... - def set_bg_angles(self, start: int, end: int): ... - def set_angles(self, start: int, end: int): ... -``` - -Then PikaScript's pre-compiler can automatically bind the following C functions, simply by naming the functions in the module_class_method format, without any additional work, and all binding and registration is done automatically. - -``` C -/* pika_lvgl_arc.c */ -void pika_lvgl_arc_set_end_angle(PikaObj* self, int angle) { - lv_obj_t* lv_obj = obj_getPtr(self, "lv_obj"); - lv_arc_set_end_angle(lv_obj, angle); -} -void pika_lvgl_arc_set_bg_angles(PikaObj *self, int start, int end){ - lv_obj_t* lv_obj = obj_getPtr(self, "lv_obj"); - lv_arc_set_bg_angles(lv_obj, start, end); -} -void pika_lvgl_arc_set_angles(PikaObj *self, int start, int end){ - lv_obj_t* lv_obj = obj_getPtr(self, "lv_obj"); - lv_arc_set_angles(lv_obj, start, end); -} -``` - -To use the module, just `import pika_lvgl` and the precompiler will automatically scan main.py and bind the `pika_lvgl` module - -``` -$ ./rust-msc-latest-win10.exe -(pikascript) packages installed: - pikascript-core==v1.10.0 - PikaStdLib==v1.10.0 - PikaStdDevice==v1.10.0 -(pikascript) pika compiler: - scaning main.py... - binding pika_lvgl.pyi... -``` - -The precompiler is written in Rust, runs on windows and linux, and is completely open source. - -In addition to binding C modules, the precompiler compiles Python scripts to bytecode in the PC, reducing the size of the script and increasing its speed. - ---- - -## How can I use it? - -The simulation repo on vs is available on https://github.com/pikasTech/lv_pikascript - ---- diff --git a/docs/get-started/bindings/pikascript.rst b/docs/get-started/bindings/pikascript.rst new file mode 100644 index 000000000..52b7222de --- /dev/null +++ b/docs/get-started/bindings/pikascript.rst @@ -0,0 +1,203 @@ +PikaScript +========== + +What is PikaScript ? +-------------------- + +`PikaScript <https://github.com/pikasTech/pikascript>`__ is a Python +interpreter designed specifically for microcontrollers, and it supports +a subset of the common Python3 syntax. + +It’s lighter, requiring only 32k of code space and 4k of RAM, which +means it can run on stm32f103c8 (blue-pill) or even stm32g030c8, on the +other hand, you can leave valuable space for more material or larger +buffer areas. + +It is simpler, out of the box, runs with no porting and configuration at +all, does not depend on OS or file system, has good support for popular +IDEs for Windows platforms like Keil, IAR, RT-Thread-Studio, and of +course, supports linux-gcc development platforms. + +It’s smarter, with a unique C module mechanism that allows you to +generate bindings automatically by simply writing the API for the C +module in Python, and you don’t need to deal with the headache of +writing any macros or global tables manually. On the other hand, all C +modules have sophisticated smart hints, even hinting at the types of +your arguments . + +-------------- + + +Why PikaScript + LVGL ? +----------------------- + +PikaScript now supports the main features of LVGL8, and these APIs are +fully compatible with Micropython! + +This means that you can continue to use already written code from +Micropython, and then use less code space and RAM. + +Enjoy detailed code hints down to the parameter type for a better +programming experience + +Use a more convenient IDE, such as vs-based simulation projects + + +So how does it look like? +------------------------- + +Here are some examples of lvgl that PikaScript can already run, they are +mainly from the lvgl documentation examples + + +LV_ARC +~~~~~~ + +.. code:: python + + import pika_lvgl as lv + import PikaStdLib + mem = PikaStdLib.MemChecker() + # Create an Arc + arc = lv.arc(lv.scr_act()) + arc.set_end_angle(200) + arc.set_size(150, 150) + arc.center() + print('mem used max: %0.2f kB' % (mem.getMax())) + print('mem used now: %0.2f kB' % (mem.getNow())) + + +LV_BAR +~~~~~~ + +.. code:: python + + import pika_lvgl as lv + import PikaStdLib + mem = PikaStdLib.MemChecker() + bar1 = lv.bar(lv.scr_act()) + bar1.set_size(200, 20) + bar1.center() + bar1.set_value(70, lv.ANIM.OFF) + print('mem used max: %0.2f kB' % (mem.getMax())) + print('mem used now: %0.2f kB' % (mem.getNow())) + + +LV_BTN +~~~~~~ + +.. code:: python + + import pika_lvgl as lv + import PikaStdLib + mem = PikaStdLib.MemChecker() + def event_cb_1(evt): + print('in evt1') + print('mem used now: %0.2f kB' % (mem.getNow())) + def event_cb_2(evt): + print('in evt2') + print('mem used now: %0.2f kB' % (mem.getNow())) + btn1 = lv.btn(lv.scr_act()) + btn1.align(lv.ALIGN.TOP_MID, 0, 10) + btn2 = lv.btn(lv.scr_act()) + btn2.align(lv.ALIGN.TOP_MID, 0, 50) + btn1.add_event(event_cb_1, lv.EVENT.CLICKED, 0) + btn2.add_event(event_cb_2, lv.EVENT.CLICKED, 0) + print('mem used max: %0.2f kB' % (mem.getMax())) + print('mem used now: %0.2f kB' % (mem.getNow())) + + +LV_CHECKBOX +~~~~~~~~~~~ + +.. code:: python + + import pika_lvgl as lv + import PikaStdLib + mem = PikaStdLib.MemChecker() + cb = lv.checkbox(lv.scr_act()) + cb.set_text("Apple") + cb.align(lv.ALIGN.TOP_LEFT, 0 ,0) + cb = lv.checkbox(lv.scr_act()) + cb.set_text("Banana") + cb.add_state(lv.STATE.CHECKED) + cb.align(lv.ALIGN.TOP_LEFT, 0 ,30) + cb = lv.checkbox(lv.scr_act()) + cb.set_text("Lemon") + cb.add_state(lv.STATE.DISABLED) + cb.align(lv.ALIGN.TOP_LEFT, 0 ,60) + cb = lv.checkbox(lv.scr_act()) + cb.add_state(lv.STATE.CHECKED | lv.STATE.DISABLED) + cb.set_text("Melon") + cb.align(lv.ALIGN.TOP_LEFT, 0 ,90) + print('mem used max: %0.2f kB' % (mem.getMax())) + print('mem used now: %0.2f kB' % (mem.getNow())) + +-------------- + + +How does it work? +----------------- + +PikaScript has a unique C module smart binding tool + +Just write the Python interface in pika_lvgl.pyi (.pyi is the python +interface file) + +.. code:: python + + # pika_lvgl.pyi + class arc(lv_obj): + def set_end_angle(self, angle: int): ... + def set_bg_angles(self, start: int, end: int): ... + def set_angles(self, start: int, end: int): ... + +Then PikaScript’s pre-compiler can automatically bind the following C +functions, simply by naming the functions in the module_class_method +format, without any additional work, and all binding and registration is +done automatically. + +.. code:: c + + /* pika_lvgl_arc.c */ + void pika_lvgl_arc_set_end_angle(PikaObj* self, int angle) { + lv_obj_t* lv_obj = obj_getPtr(self, "lv_obj"); + lv_arc_set_end_angle(lv_obj, angle); + } + void pika_lvgl_arc_set_bg_angles(PikaObj *self, int start, int end){ + lv_obj_t* lv_obj = obj_getPtr(self, "lv_obj"); + lv_arc_set_bg_angles(lv_obj, start, end); + } + void pika_lvgl_arc_set_angles(PikaObj *self, int start, int end){ + lv_obj_t* lv_obj = obj_getPtr(self, "lv_obj"); + lv_arc_set_angles(lv_obj, start, end); + } + +To use the module, just ``import pika_lvgl`` and the precompiler will +automatically scan main.py and bind the ``pika_lvgl`` module + +:: + + $ ./rust-msc-latest-win10.exe + (pikascript) packages installed: + pikascript-core==v1.10.0 + PikaStdLib==v1.10.0 + PikaStdDevice==v1.10.0 + (pikascript) pika compiler: + scaning main.py... + binding pika_lvgl.pyi... + +The precompiler is written in Rust, runs on windows and linux, and is +completely open source. + +In addition to binding C modules, the precompiler compiles Python +scripts to bytecode in the PC, reducing the size of the script and +increasing its speed. + +-------------- + +How can I use it? +----------------- + +The simulation repo on vs is available on +https://github.com/pikasTech/lv_pikascript diff --git a/docs/get-started/index.md b/docs/get-started/index.md deleted file mode 100644 index 8de67bf20..000000000 --- a/docs/get-started/index.md +++ /dev/null @@ -1,27 +0,0 @@ -# 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/master/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/docs/get-started/index.rst b/docs/get-started/index.rst new file mode 100644 index 000000000..960764098 --- /dev/null +++ b/docs/get-started/index.rst @@ -0,0 +1,28 @@ +=========== +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 :ref:`introduction` page of the documentation (5 minutes) +3. Read the :ref:`quick-overview` page of the documentation (15 minutes) +4. Set up a :ref:`simulator` (10 minutes) +5. Try out some :ref:`examples` +6. Check out the Platform-specific tutorials. (in this section below). (10 minutes) +7. Port LVGL to a board. See the :ref:`porting` guide or check the ready to use `Projects <https://github.com/lvgl?q=lv_port_&type=&language=>`__ +8. Read the :ref:`overview` page to get a better understanding of the library. (2-3 hours) +9. Check the documentation of the :ref:`widgets` to see their features and usage +10. If you have questions got to the `Forum <http://forum.lvgl.io/>`__ +11. Read the :ref:`contributing` guide to see how you can help to improve LVGL (15 minutes) + + +.. toctree:: + :maxdepth: 2 + + quick-overview + platforms/index + os/index + bindings/index diff --git a/docs/get-started/os/freertos.md b/docs/get-started/os/freertos.md deleted file mode 100644 index 8c50b2ae0..000000000 --- a/docs/get-started/os/freertos.md +++ /dev/null @@ -1,3 +0,0 @@ -# FreeRTOS - -TODO
\ No newline at end of file diff --git a/docs/get-started/os/freertos.rst b/docs/get-started/os/freertos.rst new file mode 100644 index 000000000..6b485fd3d --- /dev/null +++ b/docs/get-started/os/freertos.rst @@ -0,0 +1,5 @@ +======== +FreeRTOS +======== + +TODO diff --git a/docs/get-started/os/index.md b/docs/get-started/os/index.md deleted file mode 100644 index 30ea6af2a..000000000 --- a/docs/get-started/os/index.md +++ /dev/null @@ -1,13 +0,0 @@ -# (RT)OS - -```eval_rst - -.. toctree:: - :maxdepth: 2 - - nuttx - rt-thread - freertos - zephyr -``` - diff --git a/docs/get-started/os/index.rst b/docs/get-started/os/index.rst new file mode 100644 index 000000000..0606ce9be --- /dev/null +++ b/docs/get-started/os/index.rst @@ -0,0 +1,10 @@ +====== +(RT)OS +====== + +.. toctree:: :maxdepth: 2 + + nuttx + rt-thread + freertos + zephyr diff --git a/docs/get-started/os/nuttx.md b/docs/get-started/os/nuttx.md deleted file mode 100644 index 97b95f771..000000000 --- a/docs/get-started/os/nuttx.md +++ /dev/null @@ -1,97 +0,0 @@ -# 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/docs/get-started/os/nuttx.rst b/docs/get-started/os/nuttx.rst new file mode 100644 index 000000000..99c131793 --- /dev/null +++ b/docs/get-started/os/nuttx.rst @@ -0,0 +1,146 @@ +========== +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/>`__ + +.. code:: 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: shell + + $ mkdir ~/nuttxspace + $ cd ~/nuttxspace + +Clone the NuttX and Apps repositories: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: 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: + +.. code:: 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: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: 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: + +.. code:: 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/docs/get-started/os/rt-thread.md b/docs/get-started/os/rt-thread.md index 447f84f5d..e69de29bb 100644 --- a/docs/get-started/os/rt-thread.md +++ b/docs/get-started/os/rt-thread.md @@ -1,46 +0,0 @@ -# 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? - -[**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) | [Infineon psoc6-evaluationkit-062S2](https://github.com/RT-Thread/rt-thread/tree/master/bsp/Infineon/psoc6-evaluationkit-062S2/applications/lvgl) | -| [Visual Studio simulator](https://github.com/RT-Thread/rt-thread/tree/master/bsp/simulator/applications/lvgl) | [Renesas ra6m3-ek](https://github.com/RT-Thread/rt-thread/tree/master/bsp/renesas/ra6m3-ek/board/lvgl) | -| [Nuvoton numaker-iot-m487](https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-iot-m487/applications/lvgl) | [Renesas ra6m4-cpk](https://github.com/RT-Thread/rt-thread/tree/master/bsp/renesas/ra6m4-cpk/board/lvgl) | -| [Nuvoton numaker-pfm-m487](https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-pfm-m487/applications/lvgl) | [synwit swm341](https://github.com/RT-Thread/rt-thread/tree/master/bsp/synwit/swm341/applications/lvgl) | -| [Nuvoton nk-980iot](https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/nk-980iot/applications/lvgl) | [STM32H750 ART-Pi](https://github.com/RT-Thread/rt-thread/tree/master/bsp/stm32/stm32h750-artpi/applications/lvgl) | -| [Nuvoton numaker-m2354](https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-m2354/applications/lvgl) | [STM32F469 Discovery](https://github.com/RT-Thread/rt-thread/tree/master/bsp/stm32/stm32f469-st-disco/applications/lvgl) | -| [Nuvoton nk-n9h30](https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/nk-n9h30/applications/lvgl) | [STM32F407 explorer](https://github.com/RT-Thread/rt-thread/tree/master/bsp/stm32/stm32f407-atk-explorer/applications/lvgl) | -| [Nuvoton numaker-m032ki](https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-m032ki/applications/lvgl) | [STM32L475 pandora](https://github.com/RT-Thread/rt-thread/tree/master/bsp/stm32/stm32l475-atk-pandora/applications/lvgl) | -| [Nuvoton numaker-hmi-ma35d1](https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-hmi-ma35d1/applications/lvgl) | [NXP imxrt1060-evk](https://github.com/RT-Thread/rt-thread/tree/master/bsp/imxrt/imxrt1060-nxp-evk/applications/lvgl) | -| [Nuvoton numaker-iot-m467](https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-iot-m467/applications/lvgl) | [Raspberry PICO](https://github.com/RT-Thread/rt-thread/tree/master/bsp/raspberry-pico/applications/lvgl) | -| [Nuvoton numaker-m467hj](https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-m467hj/applications/lvgl) | | - -### Tutorials - -- [Introduce about RT-Thread and how to run LVGL on RT-Thread in simulators](https://www.youtube.com/watch?v=k7QYk6hSwnc) -- [How to import a BSP project with latest code into RT-Thread Studio](https://www.youtube.com/watch?v=fREPLuh-h8k) -- [How to Use LVGL with RT-Thread Studio in STM32F469 Discovery Board](https://www.youtube.com/watch?v=O_QA99BxnOE) -- [RT-Thread Youtube Channel](https://www.youtube.com/channel/UCdDHtIfSYPq4002r27ffqPw) -- [RT-Thread documentation center](https://www.rt-thread.io/document/site/) diff --git a/docs/get-started/os/rt-thread.rst b/docs/get-started/os/rt-thread.rst new file mode 100644 index 000000000..173885b9a --- /dev/null +++ b/docs/get-started/os/rt-thread.rst @@ -0,0 +1,86 @@ +============== +RT-Thread RTOS +============== + +What is RT-Thread? +------------------ + +`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 `package ecosystem <https://packages.rt-thread.org/en/>`__ +- 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 `architectures and chips <https://www.rt-thread.io/board.html>`__ + +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 +`softwarepackage <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>`__ | `Infineon psoc6-evaluationkit-062S2 <https://github.com/RT-Thread/rt-thread/tree/master/bsp/Infineon/psoc6-evaluationkit-062S2/applications/lvgl>`__ | ++--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `Visual Studio simulator <https://github.com/RT-Thread/rt-thread/tree/master/bsp/simulator/applications/lvgl>`__ | `Renesas ra6m3-ek <https://github.com/RT-Thread/rt-thread/tree/master/bsp/renesas/ra6m3-ek/board/lvgl>`__ | ++--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `Nuvoton numaker-iot-m487 <https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-iot-m487/applications/lvgl>`__ | `Renesas ra6m4-cpk <https://github.com/RT-Thread/rt-thread/tree/master/bsp/renesas/ra6m4-cpk/board/lvgl>`__ | ++--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `Nuvoton numaker-pfm-m487 <https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-pfm-m487/applications/lvgl>`__ | `synwit swm341 <https://github.com/RT-Thread/rt-thread/tree/master/bsp/synwit/swm341/applications/lvgl>`__ | ++--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `Nuvoton nk-980iot <https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/nk-980iot/applications/lvgl>`__ | `STM32H750 ART-Pi <https://github.com/RT-Thread/rt-thread/tree/master/bsp/stm32/stm32h750-artpi/applications/lvgl>`__ | ++--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `Nuvoton numaker-m2354 <https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-m2354/applications/lvgl>`__ | `STM32F469 Discovery <https://github.com/RT-Thread/rt-thread/tree/master/bsp/stm32/stm32f469-st-disco/applications/lvgl>`__ | ++--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `Nuvoton nk-n9h30 <https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/nk-n9h30/applications/lvgl>`__ | `STM32F407 explorer <https://github.com/RT-Thread/rt-thread/tree/master/bsp/stm32/stm32f407-atk-explorer/applications/lvgl>`__ | ++--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `Nuvoton numaker-m032ki <https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-m032ki/applications/lvgl>`__ | `STM32L475 pandora <https://github.com/RT-Thread/rt-thread/tree/master/bsp/stm32/stm32l475-atk-pandora/applications/lvgl>`__ | ++--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `Nuvoton numaker-hmi-ma35d1 <https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-hmi-ma35d1/applications/lvgl>`__ | `NXP imxrt1060-evk <https://github.com/RT-Thread/rt-thread/tree/master/bsp/imxrt/imxrt1060-nxp-evk/applications/lvgl>`__ | ++--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `Nuvoton numaker-iot-m467 <https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-iot-m467/applications/lvgl>`__ | `Raspberry PICO <https://github.com/RT-Thread/rt-thread/tree/master/bsp/raspberry-pico/applications/lvgl>`__ | ++--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `Nuvoton numaker-m467hj <https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-m467hj/applications/lvgl>`__ | ++--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + + +Tutorials +~~~~~~~~~ + +- `Introduce about RT-Thread and how to run LVGL on RT-Thread in simulators <https://www.youtube.com/watch?v=k7QYk6hSwnc>`__ +- `How to import a BSP project with latest code into RT-Thread Studio <https://www.youtube.com/watch?v=fREPLuh-h8k>`__ +- `How to Use LVGL with RT-Thread Studio in STM32F469 Discovery Board <https://www.youtube.com/watch?v=O_QA99BxnOE>`__ +- `RT-Thread Youtube Channel <https://www.youtube.com/channel/UCdDHtIfSYPq4002r27ffqPw>`__ +- `RT-Thread documentation center <https://www.rt-thread.io/document/site/>`__ diff --git a/docs/get-started/os/zephyr.md b/docs/get-started/os/zephyr.md deleted file mode 100644 index 3de472602..000000000 --- a/docs/get-started/os/zephyr.md +++ /dev/null @@ -1,3 +0,0 @@ -# Zephyr - -TODO
\ No newline at end of file diff --git a/docs/get-started/os/zephyr.rst b/docs/get-started/os/zephyr.rst new file mode 100644 index 000000000..5820814bd --- /dev/null +++ b/docs/get-started/os/zephyr.rst @@ -0,0 +1,5 @@ +====== +Zephyr +====== + +TODO diff --git a/docs/get-started/platforms/arduino.rst b/docs/get-started/platforms/arduino.rst new file mode 100644 index 000000000..092e05f23 --- /dev/null +++ b/docs/get-started/platforms/arduino.rst @@ -0,0 +1,104 @@ +======= +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 :c:macro:`LV_COLOR_DEPTH` +5. Set :c:macro:`LV_TICK_CUSTOM` + +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 :cpp:func:`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``: + +.. code:: 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 :c:macro:`LV_LOG_LEVEL` accordingly, the +output log is sent to the ``Serial`` port @ 115200 bps. diff --git a/docs/get-started/platforms/cmake.md b/docs/get-started/platforms/cmake.md deleted file mode 100644 index adab90191..000000000 --- a/docs/get-started/platforms/cmake.md +++ /dev/null @@ -1,92 +0,0 @@ - -# 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 GIT_REPOSITORY 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 few additional CMake options available. - -#### Include paths options - -- `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" | - -> We do not recommend disabling those options unless your folder layout makes it absolutely necessary. - -#### Examples/demos options - -LVGL [examples](https://docs.lvgl.io/master/examples.html) and [demos](https://github.com/lvgl/lvgl/demos) are built by default in the main CMake file. -To disable their built, use: - -- `LV_CONF_BUILD_DISABLE_EXAMPLES`: Set to `1` to disable _examples_ build -- `LV_CONF_BUILD_DISABLE_DEMOS`: Set to `1` to disable _demos_ build - -## Building LVGL drivers - -To build [LVGL drivers](https://github.com/lvgl/lv_drivers), you can use: - -```cmake -FetchContent_Declare(lv_drivers - GIT_REPOSITORY https://github.com/lvgl/lv_drivers) -FetchContent_MakeAvailable(lv_drivers) - -# The target "MyFirmware" depends on LVGL and drivers -target_link_libraries(MyFirmware PRIVATE lvgl::lvgl lvgl::drivers) -``` - -# 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/docs/get-started/platforms/cmake.rst b/docs/get-started/platforms/cmake.rst new file mode 100644 index 000000000..d11066129 --- /dev/null +++ b/docs/get-started/platforms/cmake.rst @@ -0,0 +1,137 @@ +===== +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. + +.. code:: 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 GIT_REPOSITORY 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 :c:macro:`LV_CONF_PATH` +to point to our own copy of it. + + +Additional CMake options +======================== + +Besides :c:macro:`LV_CONF_PATH` there are few additional CMake options available. + + +Include paths options +--------------------- + +- :c:macro:`LV_LVGL_H_INCLUDE_SIMPLE`: which specifies whether to ``#include "lvgl.h"`` absolut or relative + + ============ ============== + ON (default) OFF + ============ ============== + “lvgl.h” “../../lvgl.h” + ============ ============== + +- :c:macro:`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” + =============== ===================== + +.. + + We do not recommend disabling those options unless your folder layout + makes it absolutely necessary. + + +Examples/demos options +---------------------- + +| LVGL `examples <https://docs.lvgl.io/master/examples.html>`__ and + `demos <https://github.com/lvgl/lvgl/demos>`__ are built by default in + the main CMake file. +| To disable their built, use: + +- :c:macro:`LV_CONF_BUILD_DISABLE_EXAMPLES`: Set to ``1`` to disable *examples* build +- :c:macro:`LV_CONF_BUILD_DISABLE_DEMOS`: Set to ``1`` to disable *demos* build + + +Building LVGL drivers +********************* + +To build `LVGL drivers <https://github.com/lvgl/lv_drivers>`__, you can use: + +.. code:: cmake + + FetchContent_Declare(lv_drivers + GIT_REPOSITORY https://github.com/lvgl/lv_drivers) + FetchContent_MakeAvailable(lv_drivers) + + # The target "MyFirmware" depends on LVGL and drivers + target_link_libraries(MyFirmware PRIVATE lvgl::lvgl lvgl::drivers) + + +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.): + +.. code:: cmake + + set(BUILD_SHARED_LIBS ON) + +OR + +.. code:: console + + $ cmake "-DBUILD_SHARED_LIBS=ON" . diff --git a/docs/get-started/platforms/espressif.md b/docs/get-started/platforms/espressif.md deleted file mode 100644 index ee65fa23d..000000000 --- a/docs/get-started/platforms/espressif.md +++ /dev/null @@ -1,58 +0,0 @@ - -# 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/docs/get-started/platforms/espressif.rst b/docs/get-started/platforms/espressif.rst new file mode 100644 index 000000000..2261c9d28 --- /dev/null +++ b/docs/get-started/platforms/espressif.rst @@ -0,0 +1,85 @@ +============================= +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: + +.. code:: 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: + +.. code:: 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: + +.. code:: sh + + git submodule add https://github.com/lvgl/lvgl_esp32_drivers.git components/lvgl_esp32_drivers diff --git a/docs/get-started/platforms/index.md b/docs/get-started/platforms/index.md deleted file mode 100644 index 04f5eda12..000000000 --- a/docs/get-started/platforms/index.md +++ /dev/null @@ -1,17 +0,0 @@ -# Platforms - -```eval_rst - -.. toctree:: - :maxdepth: 2 - - pc-simulator - nxp - stm32 - espressif - arduino - tasmota-berry - cmake - mdk -``` - diff --git a/docs/get-started/platforms/index.rst b/docs/get-started/platforms/index.rst new file mode 100644 index 000000000..832a7c2b7 --- /dev/null +++ b/docs/get-started/platforms/index.rst @@ -0,0 +1,15 @@ +========= +Platforms +========= + +.. toctree:: + :maxdepth: 2 + + pc-simulator + nxp + stm32 + espressif + arduino + tasmota-berry + cmake + mdk diff --git a/docs/get-started/platforms/mdk.md b/docs/get-started/platforms/mdk.md deleted file mode 100644 index 50acbe145..000000000 --- a/docs/get-started/platforms/mdk.md +++ /dev/null @@ -1,4 +0,0 @@ - -# MDK - -TODO diff --git a/docs/get-started/platforms/mdk.rst b/docs/get-started/platforms/mdk.rst new file mode 100644 index 000000000..037f45be8 --- /dev/null +++ b/docs/get-started/platforms/mdk.rst @@ -0,0 +1,5 @@ +=== +MDK +=== + +TODO diff --git a/docs/get-started/platforms/nxp.md b/docs/get-started/platforms/nxp.md deleted file mode 100644 index 22587c54f..000000000 --- a/docs/get-started/platforms/nxp.md +++ /dev/null @@ -1,178 +0,0 @@ -# NXP -NXP has integrated LVGL into the MCUXpresso SDK packages for 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. Each accelerator has its own context that allows them to be used individually as well -simultaneously (in LVGL multithreading mode). - -### PXP accelerator -Several drawing features in LVGL can be offloaded to the PXP engine. The CPU is available for other operations while the -PXP is running. RTOS is required to block the LVGL drawing thread and switch to another task or suspend the CPU for -power savings. - -Supported draw callbacks are available in "src/draw/nxp/pxp/lv_draw_pxp.c": -```c - pxp_draw_ctx->base_draw.draw_img_decoded = lv_draw_pxp_img_decoded; - pxp_draw_ctx->blend = lv_draw_pxp_blend; - pxp_draw_ctx->base_draw.wait_for_finish = lv_draw_pxp_wait_for_finish; -``` - -#### Features supported: - All operations can be used in conjunction with optional transparency. - - - RGB565 and ARGB8888 color formats - - Area fill with color - - BLIT (BLock Image Transfer) - - Screen Rotation (90, 180, 270 degree) - - Color keying - - Recoloring (color tint) - - Image 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. - That is achieved by PXP in two steps: - - First step is to recolor/rotate the image to a temporary buffer (statically allocated) - - Second step is required to handle color keying, alpha channel 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_draw_pxp.c[.h]: draw context callbacks - - src/draw/nxp/pxp/lv_draw_pxp_blend.c[.h]: fill and blit (with optional transformation) - - src/draw/nxp/pxp/lv_gpu_nxp_pxp.c[.h]: init, uninit, run/wait PXP device - - src/draw/nxp/pxp/lv_gpu_nxp_pxp_osa.c[.h]: OS abstraction (FreeRTOS or bare metal) - - 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[.h]: PXP driver - - fsl_cache.c[.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 SDK debug console - - By default, `LV_GPU_NXP_PXP_LOG_TRACES` is disabled. Enable it for tracing logs (like PXP limitations) - -#### 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 bare metal is - provided in lv_gpu_nxp_pxp_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. - - Area threshold (size limit) is configurable and used to decide whether the area will be processed by PXP or not. - Areas smaller than the defined value will be processed by CPU and those bigger than the threshold will be processed by - PXP. The threshold is defined as a macro in lv_draw_pxp.c - - `LV_GPU_NXP_PXP_SIZE_LIMIT`: size threshold for fill/blit (with optional transformation) - -### VGLite accelerator -Extra drawing features in LVGL can be handled by the VGLite engine. The CPU is 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. - -Supported draw callbacks are available in "src/draw/nxp/vglite/lv_draw_vglite.c": -```c - vglite_draw_ctx->base_draw.init_buf = lv_draw_vglite_init_buf; - vglite_draw_ctx->base_draw.draw_line = lv_draw_vglite_line; - vglite_draw_ctx->base_draw.draw_arc = lv_draw_vglite_arc; - vglite_draw_ctx->base_draw.draw_rect = lv_draw_vglite_rect; - vglite_draw_ctx->base_draw.draw_img_decoded = lv_draw_vglite_img_decoded; - vglite_draw_ctx->blend = lv_draw_vglite_blend; - vglite_draw_ctx->base_draw.wait_for_finish = lv_draw_vglite_wait_for_finish; -``` - -#### Features supported: - All operations can be used in conjunction with optional transparency. - - - RGB565 and ARGB8888 color formats - - Area fill with color - - BLIT (BLock Image Transfer) - - Image Rotation (any degree with decimal) - - Image Scale - - Draw rectangle background with optional radius or gradient - - Blit rectangle background image - - Draw rectangle border/outline with optional rounded corners - - Draw arc with optional rounded ending - - Draw line or dashed line with optional rounded ending - -#### Known limitations: - - Source image alignment: - The byte alignment requirement for a pixel depends on the specific pixel format. Both buffer address and buffer stride - must be aligned. As general rule, the alignment is set to 16 pixels. This makes the buffer address alignment to be - 32 bytes for RGB565 and 64 bytes for ARGB8888. - - For pixel engine (PE) destination, the alignment should be 64 bytes for all tiled (4x4) buffer layouts. - The pixel engine has no additional alignment requirement for linear buffer layouts (`VG_LITE_LINEAR`). - -#### 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 the frame width. If less than or equal - to 0, then no tessellation buffer is created, in which case VGLite is initialized only for blitting. -```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_draw_vglite.c[.h]: draw context callbacks - - src/draw/nxp/vglite/lv_draw_vglite_blend.c[.h]: fill and blit (with optional transformation) - - src/draw/nxp/vglite/lv_draw_vglite_rect.c[.h]: draw rectangle - - src/draw/nxp/vglite/lv_draw_vglite_arc.c[.h]: draw arc - - src/draw/nxp/vglite/lv_draw_vglite_line.c[.h]: draw line - - src/draw/nxp/vglite/lv_vglite_buf.c[.h]: init/get vglite buffer - - src/draw/nxp/vglite/lv_vglite_utils.c[.h]: function helpers - -#### Logging: - - By default, `LV_GPU_NXP_VG_LITE_LOG_ERRORS` is enabled so that any VGLite error will be seen on SDK debug console - - By default, `LV_GPU_NXP_VG_LITE_LOG_TRACES` is disabled. Enable it for tracing logs (like blit split workaround or - VGLite fallback to CPU due to any error on the driver) - -#### Advanced configuration: - - Area threshold (size limit) is configurable and used to decide whether the area will be processed by VGLite or not. - Areas smaller than the defined value will be processed by CPU and those bigger than the threshold will be processed by - VGLite. The threshold is defined as a macro in lv_draw_vglite.c - - `LV_GPU_NXP_VG_LITE_SIZE_LIMIT`: size threshold for fill/blit (with optional transformation) diff --git a/docs/get-started/platforms/nxp.rst b/docs/get-started/platforms/nxp.rst new file mode 100644 index 000000000..0936c57b9 --- /dev/null +++ b/docs/get-started/platforms/nxp.rst @@ -0,0 +1,278 @@ +=== +NXP +=== + +NXP has integrated LVGL into the MCUXpresso SDK packages for 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. Each accelerator has its own context that allows them to be used +individually as well simultaneously (in LVGL multithreading mode). + + +PXP accelerator +~~~~~~~~~~~~~~~ + +Several drawing features in LVGL can be offloaded to the PXP engine. The +CPU is available for other operations while the PXP is running. RTOS is +required to block the LVGL drawing thread and switch to another task or +suspend the CPU for power savings. + +Supported draw callbacks are available in "src/draw/nxp/pxp/lv_draw_pxp.c": + +.. code:: c + + pxp_draw_ctx->base_draw.draw_img_decoded = lv_draw_pxp_img_decoded; + pxp_draw_ctx->blend = lv_draw_pxp_blend; + pxp_draw_ctx->base_draw.wait_for_finish = lv_draw_pxp_wait_for_finish; + + +Features supported: +^^^^^^^^^^^^^^^^^^^ + +All operations can be used in conjunction with optional transparency. + +- RGB565 and ARGB8888 color formats +- Area fill with color +- BLIT (BLock Image Transfer) +- Screen Rotation (90, 180, 270 degree) +- Color keying +- Recoloring (color tint) +- Image 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. That is achieved by PXP in two + steps: + + - First step is to recolor/rotate the image to a temporary buffer (statically allocated) + - Second step is required to handle color keying, alpha channel 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 :c:macro:`LV_USE_GPU_NXP_PXP` to ``1`` +- Enable default implementation for interrupt handling, PXP start + function and automatic initialization: Set + :c:macro:`LV_USE_GPU_NXP_PXP_AUTO_INIT` to ``1`` +- If :c:macro:`SDK_OS_FREE_RTOS` symbol is defined, FreeRTOS implementation + will be used, otherwise bare metal code will be included + + +Basic initialization: +^^^^^^^^^^^^^^^^^^^^^ + +- If :c:macro:`LV_USE_GPU_NXP_PXP_AUTO_INIT` is enabled, no user code is + required; PXP is initialized automatically in :cpp:func:`lv_init` +- For manual PXP initialization, default configuration structure for + callbacks can be used. Initialize PXP before calling :cpp:func:`lv_init` + +.. code:: 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_draw_pxp.c[.h]: draw context callbacks + - src/draw/nxp/pxp/lv_draw_pxp_blend.c[.h]: fill and blit (with optional transformation) + - src/draw/nxp/pxp/lv_gpu_nxp_pxp.c[.h]: init, uninit, run/wait PXP device + - src/draw/nxp/pxp/lv_gpu_nxp_pxp_osa.c[.h]: OS abstraction (FreeRTOS or bare metal) + + - optional, required only if :c:macro:`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[.h]: PXP driver + - fsl_cache.c[.h]: CPU cache handling functions + + +Logging: +^^^^^^^^ + +- By default, :c:macro:`LV_GPU_NXP_PXP_LOG_ERRORS` is enabled so that any PXP error will be seen on SDK debug console +- By default, :c:macro:`LV_GPU_NXP_PXP_LOG_TRACES` is disabled. Enable it for tracing logs (like PXP limitations) + + +Advanced configuration: +^^^^^^^^^^^^^^^^^^^^^^^ + +- Implementation depends on multiple OS-specific functions. The struct + :cpp:struct:`lv_nxp_pxp_cfg_t` with callback pointers is used as a parameter + for the :cpp:func:`lv_gpu_nxp_pxp_init` function. Default implementation + for FreeRTOS and bare metal is provided in lv_gpu_nxp_pxp_osa.c + + - :cpp:func:`pxp_interrupt_init`: Initialize PXP interrupt (HW setup, OS setup) + - :cpp:func:`pxp_interrupt_deinit`: Deinitialize PXP interrupt (HW setup, OS setup) + - :cpp:func:`pxp_run`: Start PXP job. Use OS-specific mechanism to block drawing thread. + PXP must finish drawing before leaving this function. + +- Area threshold (size limit) is configurable and used to decide + whether the area will be processed by PXP or not. Areas smaller than + the defined value will be processed by CPU and those bigger than the + threshold will be processed by PXP. The threshold is defined as a + macro in lv_draw_pxp.c + + - :c:macro:`LV_GPU_NXP_PXP_SIZE_LIMIT`: size threshold for fill/blit (with optional transformation) + + +VGLite accelerator +~~~~~~~~~~~~~~~~~~ + +Extra drawing features in LVGL can be handled by the VGLite engine. The +CPU is 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. + +Supported draw callbacks are available in "src/draw/nxp/vglite/lv_draw_vglite.c": + +.. code:: c + + vglite_draw_ctx->base_draw.init_buf = lv_draw_vglite_init_buf; + vglite_draw_ctx->base_draw.draw_line = lv_draw_vglite_line; + vglite_draw_ctx->base_draw.draw_arc = lv_draw_vglite_arc; + vglite_draw_ctx->base_draw.draw_rect = lv_draw_vglite_rect; + vglite_draw_ctx->base_draw.draw_img_decoded = lv_draw_vglite_img_decoded; + vglite_draw_ctx->blend = lv_draw_vglite_blend; + vglite_draw_ctx->base_draw.wait_for_finish = lv_draw_vglite_wait_for_finish; + +.. _features-supported-1: + + +Features supported: +^^^^^^^^^^^^^^^^^^^ + +All operations can be used in conjunction with optional transparency. + +- RGB565 and ARGB8888 color formats +- Area fill with color +- BLIT (BLock Image Transfer) +- Image Rotation (any degree with decimal) +- Image Scale +- Draw rectangle background with optional radius or gradient +- Blit rectangle background image +- Draw rectangle border/outline with optional rounded corners +- Draw arc with optional rounded ending +- Draw line or dashed line with optional rounded ending + +.. _known-limitations-1: + + +Known limitations: +^^^^^^^^^^^^^^^^^^ + +- Source image alignment: The byte alignment requirement for a pixel + depends on the specific pixel format. Both buffer address and buffer + stride must be aligned. As general rule, the alignment is set to 16 + pixels. This makes the buffer address alignment to be 32 bytes for + RGB565 and 64 bytes for ARGB8888. +- For pixel engine (PE) destination, the alignment should be 64 bytes + for all tiled (4x4) buffer layouts. The pixel engine has no + additional alignment requirement for linear buffer layouts + (:c:macro:`VG_LITE_LINEAR`). + +.. _basic-configuration-1: + + +Basic configuration: +^^^^^^^^^^^^^^^^^^^^ + +- Select NXP VGLite engine in lv_conf.h: Set :c:macro:`LV_USE_GPU_NXP_VG_LITE` to 1 +- :c:macro:`SDK_OS_FREE_RTOS` symbol needs to be defined so that the FreeRTOS implementation will be used + +.. _basic-initialization-1: + +Basic initialization: +^^^^^^^^^^^^^^^^^^^^^ + +- Initialize VGLite before calling :cpp:func:`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 the + frame width. If less than or equal to 0, then no tessellation buffer + is created, in which case VGLite is initialized only for blitting. + +.. code:: 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-1: + +Project setup: +^^^^^^^^^^^^^^ + +- Add VGLite related files to project: + + - src/draw/nxp/vglite/lv_draw_vglite.c[.h]: draw context callbacks + - src/draw/nxp/vglite/lv_draw_vglite_blend.c[.h]: fill and blit (with optional transformation) + - src/draw/nxp/vglite/lv_draw_vglite_rect.c[.h]: draw rectangle + - src/draw/nxp/vglite/lv_draw_vglite_arc.c[.h]: draw arc + - src/draw/nxp/vglite/lv_draw_vglite_line.c[.h]: draw line + - src/draw/nxp/vglite/lv_vglite_buf.c[.h]: init/get vglite buffer + - src/draw/nxp/vglite/lv_vglite_utils.c[.h]: function helpers + +.. _logging-1: + +Logging: +^^^^^^^^ + +- By default, :c:macro:`LV_GPU_NXP_VG_LITE_LOG_ERRORS` is enabled so that any VGLite error will be seen on SDK debug console +- By default, :c:macro:`LV_GPU_NXP_VG_LITE_LOG_TRACES` is disabled. Enable it + for tracing logs (like blit split workaround or VGLite fallback to CPU due to any error on the driver) + +.. _advanced-configuration-1: + +Advanced configuration: +^^^^^^^^^^^^^^^^^^^^^^^ + +- Area threshold (size limit) is configurable and used to decide + whether the area will be processed by VGLite or not. Areas smaller + than the defined value will be processed by CPU and those bigger than + the threshold will be processed by VGLite. The threshold is defined + as a macro in lv_draw_vglite.c + + - :c:macro:`LV_GPU_NXP_VG_LITE_SIZE_LIMIT`: size threshold for fill/blit (with optional transformation) diff --git a/docs/get-started/platforms/pc-simulator.md b/docs/get-started/platforms/pc-simulator.md deleted file mode 100644 index 587f845cf..000000000 --- a/docs/get-started/platforms/pc-simulator.md +++ /dev/null @@ -1,100 +0,0 @@ -# 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](https://www.mingw-w64.org/downloads/#msys2)). 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/docs/get-started/platforms/pc-simulator.rst b/docs/get-started/platforms/pc-simulator.rst new file mode 100644 index 000000000..f5ac5115d --- /dev/null +++ b/docs/get-started/platforms/pc-simulator.rst @@ -0,0 +1,152 @@ +.. _simulator: + +=============== +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 SDLdriver <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. Start the installer and +choose *Eclipse CDT* from the list. + +Install SDL 2 +~~~~~~~~~~~~~ + +The PC simulator uses the `SDL2 <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 <https://www.mingw-w64.org/downloads/#msys2>`__). 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 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/docs/get-started/platforms/stm32.md b/docs/get-started/platforms/stm32.md deleted file mode 100644 index bf3c1c827..000000000 --- a/docs/get-started/platforms/stm32.md +++ /dev/null @@ -1,219 +0,0 @@ - -# STM32 - -LVGL Can be added to [STM32CubeIDE](https://www.st.com/en/development-tools/stm32cubeide.html) in a similar fashion to any other Eclipse-based IDE. - -## Including LVGL in a Project -* Create or open a project in STM32CubeIDE. -* Copy the entire LVGL folder to *[project_folder]/Drivers/lvgl*. -* In the STM32CubeIDE **Project Explorer** pane: right click on the LVGL folder that you copied (you may need to refresh the view first before it will appear), and select **Add/remove include path...**. If this doesn't appear, or doesn't work, you can review your project include paths under the **Project** - **Properties** menu, and then navigating to **C/C++ Build** - **Settings** - **Include paths**, and ensuring that the LVGL directory is listed. - -Now that the source files are included in your project, follow the instructions for [Porting](https://docs.lvgl.io/master/porting/project.html) your project to create the ```lv_conf.h``` file, and initialise the display. - -## Bare Metal Example -A minimal example using STM32CubeIDE, and HAL. -* When setting up **Pinout and Configuration** using the **Device Configuration Tool**, select **System Core** - **SYS** and ensure that **Timebase Source** is set to **SysTick**. -* Configure any other peripherals (including the LCD panel), and initialise them in *main.c*. -* ```#include "lvgl.h"``` in the *main.c* file. -* Create some frame buffer(s) as global variables: -``` -//Frame buffers -/*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[BUFF_SIZE]; //TODO: Chose a buffer size. DISPLAY_WIDTH * 10 is one suggestion. -static lv_color_t buf_2[BUFF_SIZE]; -``` -* In your ```main()``` function, after initialising your CPU, peripherals, and LCD panel, call ```lv_init();``` to initialise LVGL. You can then register the frame buffers using ```lv_disp_draw_buf_init()```, and create the display driver using ```lv_disp_drv_init()```. -``` -//Initialise LVGL UI library -lv_init(); -lv_disp_draw_buf_init(&disp_buf, buf_1, NULL, BUFF_SIZE); - -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 = WIDTH; /*Set the horizontal resolution in pixels*/ -disp_drv.ver_res = HEIGHT; /*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*/ -``` -* Create some dummy objects to test the output: -``` -// Change the active screen's background color -lv_obj_set_style_bg_color(lv_scr_act(), lv_color_hex(0x003a57), LV_PART_MAIN); -lv_obj_set_style_text_color(lv_scr_act(), lv_color_hex(0xffffff), LV_PART_MAIN); - -/*Create a spinner*/ -lv_obj_t * spinner = lv_spinner_create(lv_scr_act(), 1000, 60); -lv_obj_set_size(spinner, 64, 64); -lv_obj_align(spinner, LV_ALIGN_BOTTOM_MID, 0, 0); -``` -* Add a call to ```lv_timer_handler()``` inside your ```while(1)``` loop: -``` -/* Infinite loop */ -while (1) -{ - lv_timer_handler(); - HAL_Delay(5); -} -``` -* Add a call to ```lv_tick_inc()``` inside the ```SysTick_Handler()``` function. Open the *stm32xxxx_it.c* file (the name will depend on your specific MCU), and update the ```SysTick_Handler()``` function: -``` -void SysTick_Handler(void) -{ - /* USER CODE BEGIN SysTick_IRQn 0 */ - - HAL_SYSTICK_IRQHandler(); - lv_tick_inc(1); - #ifdef USE_RTOS_SYSTICK - osSystickHandler(); - #endif - - /* USER CODE END SysTick_IRQn 0 */ - HAL_IncTick(); - /* USER CODE BEGIN SysTick_IRQn 1 */ - - /* USER CODE END SysTick_IRQn 1 */ -} -``` -* Finally, write the callback function, ```my_flush_cb()```, which will send the display buffer to your LCD panel. Below is one example, but it will vary depending on your setup. -``` -void my_flush_cb(lv_disp_drv_t * disp_drv, const lv_area_t * area, lv_color_t * color_p) -{ - //Set the drawing region - set_draw_window(area->x1, area->y1, area->x2, area->y2); - - int height = area->y2 - area->y1 + 1; - int width = area->x2 - area->x1 + 1; - - //We will do the SPI write manually here for speed - HAL_GPIO_WritePin(DC_PORT, DC_PIN, GPIO_PIN_SET); - //CS low to begin data - HAL_GPIO_WritePin(CS_PORT, CS_PIN, GPIO_PIN_RESET); - - //Write colour to each pixel - for (int i = 0; i < width * height; i++) { - parallel_write(color_p->full); - color_p++; - } - - //Return CS to high - HAL_GPIO_WritePin(CS_PORT, CS_PIN, GPIO_PIN_SET); - - /* IMPORTANT!!! - * Inform the graphics library that you are ready with the flushing*/ - lv_disp_flush_ready(disp_drv); -} -``` - -## FreeRTOS Example -A minimal example using STM32CubeIDE, HAL, and CMSISv1 (FreeRTOS). <br /> -*Note that we have not used Mutexes in this example, however LVGL is **NOT** thread safe and so Mutexes should be used. See: [Operating system and interrupts](https://docs.lvgl.io/master/porting/os.html)* -* ```#include "lvgl.h"``` -* Create your frame buffer(s) as global variables: -``` -//Frame buffers -/*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[BUFF_SIZE]; //TODO: Declare your own BUFF_SIZE appropriate to your system. -static lv_color_t buf_2[BUFF_SIZE]; -``` -* In your ```main()``` function, after your peripherals (SPI, GPIOs, LCD etc) have been initialised, initialise LVGL using ```lv_init();```, register the frame buffers using ```lv_disp_draw_buf_init()```, and create a new display driver using ```lv_disp_drv_init()```. -``` -//Initialise LVGL UI library -lv_init(); -lv_disp_draw_buf_init(&disp_buf, buf_1, buf_2, BUFF_SIZE); - -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 = WIDTH; /*Set the horizontal resolution in pixels*/ -disp_drv.ver_res = HEIGHT; /*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*/ - -// Register the touch controller with LVGL - Not included here for brevity. -``` -* Create some dummy objects to test the output: -``` -// Change the active screen's background color -lv_obj_set_style_bg_color(lv_scr_act(), lv_color_hex(0x003a57), LV_PART_MAIN); -lv_obj_set_style_text_color(lv_scr_act(), lv_color_hex(0xffffff), LV_PART_MAIN); - -/*Create a spinner*/ -lv_obj_t * spinner = lv_spinner_create(lv_scr_act(), 1000, 60); -lv_obj_set_size(spinner, 64, 64); -lv_obj_align(spinner, LV_ALIGN_BOTTOM_MID, 0, 0); -``` -* Create two threads to call ```lv_timer_handler()```, and ```lv_tick_inc()```.You will need two ```osThreadId``` handles for CMSISv1. These don't strictly have to be globally accessible in this case, however STM32Cube code generation does by default. If you are using CMSIS and STM32Cube code generation it should look something like this: -``` -//Thread Handles -osThreadId lvgl_tickHandle; -osThreadId lvgl_timerHandle; -``` -``` -/* definition and creation of lvgl_tick */ -osThreadDef(lvgl_tick, LGVLTick, osPriorityNormal, 0, 1024); -lvgl_tickHandle = osThreadCreate(osThread(lvgl_tick), NULL); - -//LVGL update timer -osThreadDef(lvgl_timer, LVGLTimer, osPriorityNormal, 0, 1024); -lvgl_timerHandle = osThreadCreate(osThread(lvgl_timer), NULL); -``` -And create the thread functions: -``` -/* LVGL timer for tasks. */ -void LVGLTimer(void const * argument) -{ - for(;;) - { - lv_timer_handler(); - osDelay(20); - } -} -/* LVGL tick source */ -void LGVLTick(void const * argument) -{ - for(;;) - { - lv_tick_inc(10); - osDelay(10); - } -} -``` -* Finally, create the ```my_flush_cb()``` function to output the frame buffer to your LCD. The specifics of this function will vary depending on which MCU features you are using. Below is an example for a typical MCU interface. -``` -void my_flush_cb(lv_disp_drv_t * disp_drv, const lv_area_t * area, lv_color_t * color_p) -{ - //Set the drawing region - set_draw_window(area->x1, area->y1, area->x2, area->y2); - - int height = area->y2 - area->y1 + 1; - int width = area->x2 - area->x1 + 1; - - //Begin SPI Write for DATA - HAL_GPIO_WritePin(DC_PORT, DC_PIN, GPIO_PIN_SET); - HAL_GPIO_WritePin(CS_PORT, CS_PIN, GPIO_PIN_RESET); - - //Write colour to each pixel - for (int i = 0; i < width * height; i++) { - parallel_write(color_p->full); - color_p++; - } - - //Return CS to high - HAL_GPIO_WritePin(CS_PORT, CS_PIN, GPIO_PIN_SET); - - /* IMPORTANT!!! - * Inform the graphics library that you are ready with the flushing*/ - lv_disp_flush_ready(disp_drv); -} -``` diff --git a/docs/get-started/platforms/stm32.rst b/docs/get-started/platforms/stm32.rst new file mode 100644 index 000000000..d0209aed9 --- /dev/null +++ b/docs/get-started/platforms/stm32.rst @@ -0,0 +1,277 @@ +===== +STM32 +===== + +LVGL Can be added to `STM32CubeIDE <https://www.st.com/en/development-tools/stm32cubeide.html>`__ +in a similar fashion to any other Eclipse-based IDE. + +Including LVGL in a Project +--------------------------- + +- Create or open a project in STM32CubeIDE. +- Copy the entire LVGL folder to *[project_folder]/Drivers/lvgl*. +- In the STM32CubeIDE **Project Explorer** pane: right click on the + LVGL folder that you copied (you may need to refresh the view first + before it will appear), and select **Add/remove include path…**. If + this doesn't appear, or doesn't work, you can review your project + include paths under the **Project** -> **Properties** menu, and then + navigating to **C/C++ Build** -> **Settings** -> **Include paths**, and + ensuring that the LVGL directory is listed. + +Now that the source files are included in your project, follow the +instructions for `Porting <https://docs.lvgl.io/master/porting/project.html>`__ your +project to create the ``lv_conf.h`` file, and initialise the display. + +Bare Metal Example +------------------ + +A minimal example using STM32CubeIDE, and HAL. \* When setting up +**Pinout and Configuration** using the **Device Configuration Tool**, +select **System Core** -> **SYS** and ensure that **Timebase Source** is +set to **SysTick**. \* Configure any other peripherals (including the +LCD panel), and initialise them in *main.c*. \* ``#include "lvgl.h"`` in +the *main.c* file. \* Create some frame buffer(s) as global variables: + +.. code:: c + + //Frame buffers + /*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[BUFF_SIZE]; //TODO: Chose a buffer size. DISPLAY_WIDTH * 10 is one suggestion. + static lv_color_t buf_2[BUFF_SIZE]; + +- In your ``main()`` function, after initialising your CPU, + peripherals, and LCD panel, call :cpp:func:`lv_init` to initialise LVGL. + You can then register the frame buffers using + :cpp:func:`lv_disp_draw_buf_init`, and create the display driver using + :cpp:func:`lv_disp_drv_init`. + +.. code:: c + + //Initialise LVGL UI library + lv_init(); + lv_disp_draw_buf_init(&disp_buf, buf_1, NULL, BUFF_SIZE); + + 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 = WIDTH; /*Set the horizontal resolution in pixels*/ + disp_drv.ver_res = HEIGHT; /*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*/ + +- Create some dummy objects to test the output: + +.. code:: c + + // Change the active screen's background color + lv_obj_set_style_bg_color(lv_scr_act(), lv_color_hex(0x003a57), LV_PART_MAIN); + lv_obj_set_style_text_color(lv_scr_act(), lv_color_hex(0xffffff), LV_PART_MAIN); + + /*Create a spinner*/ + lv_obj_t * spinner = lv_spinner_create(lv_scr_act(), 1000, 60); + lv_obj_set_size(spinner, 64, 64); + lv_obj_align(spinner, LV_ALIGN_BOTTOM_MID, 0, 0); + +- Add a call to :cpp:func:`lv_timer_handler` inside your ``while(1)`` loop: + +.. code:: c + + /* Infinite loop */ + while (1) + { + lv_timer_handler(); + HAL_Delay(5); + } + +- Add a call to :cpp:func:`lv_tick_inc` inside the :cpp:func:`SysTick_Handler` + function. Open the *stm32xxxx_it.c* file (the name will depend on + your specific MCU), and update the :cpp:func:`SysTick_Handler` function: + +.. code:: c + + void SysTick_Handler(void) + { + /* USER CODE BEGIN SysTick_IRQn 0 */ + + HAL_SYSTICK_IRQHandler(); + lv_tick_inc(1); + #ifdef USE_RTOS_SYSTICK + osSystickHandler(); + #endif + + /* USER CODE END SysTick_IRQn 0 */ + HAL_IncTick(); + /* USER CODE BEGIN SysTick_IRQn 1 */ + + /* USER CODE END SysTick_IRQn 1 */ + } + +- Finally, write the callback function, ``my_flush_cb``, which will + send the display buffer to your LCD panel. Below is one example, but + it will vary depending on your setup. + +.. code:: c + + void my_flush_cb(lv_disp_drv_t * disp_drv, const lv_area_t * area, lv_color_t * color_p) + { + //Set the drawing region + set_draw_window(area->x1, area->y1, area->x2, area->y2); + + int height = area->y2 - area->y1 + 1; + int width = area->x2 - area->x1 + 1; + + //We will do the SPI write manually here for speed + HAL_GPIO_WritePin(DC_PORT, DC_PIN, GPIO_PIN_SET); + //CS low to begin data + HAL_GPIO_WritePin(CS_PORT, CS_PIN, GPIO_PIN_RESET); + + //Write colour to each pixel + for (int i = 0; i < width * height; i++) { + parallel_write(color_p->full); + color_p++; + } + + //Return CS to high + HAL_GPIO_WritePin(CS_PORT, CS_PIN, GPIO_PIN_SET); + + /* IMPORTANT!!! + * Inform the graphics library that you are ready with the flushing*/ + lv_disp_flush_ready(disp_drv); + } + +FreeRTOS Example +---------------- + +A minimal example using STM32CubeIDE, HAL, and CMSISv1 (FreeRTOS). *Note +that we have not used Mutexes in this example, however LVGL is* **NOT** +*thread safe and so Mutexes should be used*. See: :ref:`os_interrupt` +\* ``#include "lvgl.h"`` \* Create your frame buffer(s) as global +variables: + +.. code:: c + + //Frame buffers + /*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[BUFF_SIZE]; //TODO: Declare your own BUFF_SIZE appropriate to your system. + static lv_color_t buf_2[BUFF_SIZE]; + +- In your ``main`` function, after your peripherals (SPI, GPIOs, LCD + etc) have been initialised, initialise LVGL using :cpp:func:`lv_init`, + register the frame buffers using :cpp:func:`lv_disp_draw_buf_init`, and + create a new display driver using :cpp:func:`lv_disp_drv_init`. + +.. code:: c + + //Initialise LVGL UI library + lv_init(); + lv_disp_draw_buf_init(&disp_buf, buf_1, buf_2, BUFF_SIZE); + + 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 = WIDTH; /*Set the horizontal resolution in pixels*/ + disp_drv.ver_res = HEIGHT; /*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*/ + + // Register the touch controller with LVGL - Not included here for brevity. + +- Create some dummy objects to test the output: + +.. code:: c + + // Change the active screen's background color + lv_obj_set_style_bg_color(lv_scr_act(), lv_color_hex(0x003a57), LV_PART_MAIN); + lv_obj_set_style_text_color(lv_scr_act(), lv_color_hex(0xffffff), LV_PART_MAIN); + + /*Create a spinner*/ + lv_obj_t * spinner = lv_spinner_create(lv_scr_act(), 1000, 60); + lv_obj_set_size(spinner, 64, 64); + lv_obj_align(spinner, LV_ALIGN_BOTTOM_MID, 0, 0); + +- Create two threads to call :cpp:func:`lv_timer_handler`, and + :cpp:func:`lv_tick_inc`.You will need two ``osThreadId`` handles for + CMSISv1. These don't strictly have to be globally accessible in this + case, however STM32Cube code generation does by default. If you are + using CMSIS and STM32Cube code generation it should look something + like this: + +.. code:: c + + //Thread Handles + osThreadId lvgl_tickHandle; + osThreadId lvgl_timerHandle; + + /* definition and creation of lvgl_tick */ + osThreadDef(lvgl_tick, LGVLTick, osPriorityNormal, 0, 1024); + lvgl_tickHandle = osThreadCreate(osThread(lvgl_tick), NULL); + + //LVGL update timer + osThreadDef(lvgl_timer, LVGLTimer, osPriorityNormal, 0, 1024); + lvgl_timerHandle = osThreadCreate(osThread(lvgl_timer), NULL); + +- And create the thread functions: + +.. code:: c + + /* LVGL timer for tasks. */ + void LVGLTimer(void const * argument) + { + for(;;) + { + lv_timer_handler(); + osDelay(20); + } + } + /* LVGL tick source */ + void LGVLTick(void const * argument) + { + for(;;) + { + lv_tick_inc(10); + osDelay(10); + } + } + +- Finally, create the ``my_flush_cb`` function to output the frame + buffer to your LCD. The specifics of this function will vary + depending on which MCU features you are using. Below is an example + for a typical MCU interface. + +.. code:: c + + void my_flush_cb(lv_disp_drv_t * disp_drv, const lv_area_t * area, lv_color_t * color_p) + { + //Set the drawing region + set_draw_window(area->x1, area->y1, area->x2, area->y2); + + int height = area->y2 - area->y1 + 1; + int width = area->x2 - area->x1 + 1; + + //Begin SPI Write for DATA + HAL_GPIO_WritePin(DC_PORT, DC_PIN, GPIO_PIN_SET); + HAL_GPIO_WritePin(CS_PORT, CS_PIN, GPIO_PIN_RESET); + + //Write colour to each pixel + for (int i = 0; i < width * height; i++) { + parallel_write(color_p->full); + color_p++; + } + + //Return CS to high + HAL_GPIO_WritePin(CS_PORT, CS_PIN, GPIO_PIN_SET); + + /* IMPORTANT!!! + * Inform the graphics library that you are ready with the flushing*/ + lv_disp_flush_ready(disp_drv); + } diff --git a/docs/get-started/platforms/tasmota-berry.md b/docs/get-started/platforms/tasmota-berry.md deleted file mode 100644 index e07cf25a0..000000000 --- a/docs/get-started/platforms/tasmota-berry.md +++ /dev/null @@ -1,73 +0,0 @@ -# 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.0.2, 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/docs/get-started/platforms/tasmota-berry.rst b/docs/get-started/platforms/tasmota-berry.rst new file mode 100644 index 000000000..038101b94 --- /dev/null +++ b/docs/get-started/platforms/tasmota-berry.rst @@ -0,0 +1,105 @@ +================= +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.0.2, 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 +~~~~~~~~~~~~~~~~ + +.. code:: 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/docs/get-started/quick-overview.md b/docs/get-started/quick-overview.md deleted file mode 100644 index bd71cf65e..000000000 --- a/docs/get-started/quick-overview.md +++ /dev/null @@ -1,266 +0,0 @@ - -# 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/platforms/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[MY_DISP_HOR_RES * MY_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_RES / 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_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_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_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_drv_t * indev_drv, 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/slider/lv_slider.h](https://github.com/lvgl/lvgl/blob/master/src/widgets/slider/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(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/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/bindings/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/docs/get-started/quick-overview.rst b/docs/get-started/quick-overview.rst new file mode 100644 index 000000000..a475094ae --- /dev/null +++ b/docs/get-started/quick-overview.rst @@ -0,0 +1,350 @@ +.. _quick-overview: + +============== +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 +:ref:`porting` and :ref:`overview` 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 :ref:`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 :c:macro:`LV_COLOR_DEPTH` defines. +- Include ``lvgl/lvgl.h`` in files where you need to use LVGL related functions. +- Call :cpp:expr:`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 :c:macro:`LV_TICK_CUSTOM` (see + ``lv_conf.h``) so that LVGL can retrieve the current time directly. +- Call :cpp:func:`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. + +.. code:: c + + static lv_disp_draw_buf_t draw_buf; + static lv_color_t buf1[MY_DISP_HOR_RES * MY_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_RES / 10); /*Initialize the display buffer.*/ + +- Implement and register a function which can copy the rendered image + to an area of your display: + +.. code:: c + + static lv_disp_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_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: + +.. code:: c + + static lv_indev_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_drv_t * indev_drv, 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 :cpp:func:`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 :ref:`porting` +section. + +Learn the basics +---------------- + +Widgets +~~~~~~~ + +The graphical elements like Buttons, Labels, Sliders, Charts etc. are +called objects or widgets. Go to :ref:`widgets` 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 :cpp:func:`lv_scr_act`, and to load a screen +use :cpp:expr:`lv_scr_load(scr1)`. + +You can create a new object with ``lv_<type>_create(parent)``. It will +return an :cpp:type:`lv_obj_t` ``*`` variable that can be used as a reference to the +object to set its parameters. + +For example: + +.. code:: 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: + +.. code:: 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: + +.. code:: 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/slider/lv_slider.h <https://github.com/lvgl/lvgl/blob/master/src/widgets/slider/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: + +.. code:: c + + lv_obj_add_event(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"); + } + +:cpp:enumerator:`LV_EVENT_ALL` can be used instead of :cpp:enumerator:`LV_EVENT_CLICKED` to invoke +the callback for any event. + +From :cpp:expr:`lv_event_t * e` the current event code can be retrieved with: + +.. code:: c + + lv_event_code_t code = lv_event_get_code(e); + +The object that triggered the event can be retrieved with: + +.. code:: c + + lv_obj_t * obj = lv_event_get_target(e); + +To learn all features of the events go to the :ref:`events` section. + +Parts +~~~~~ + +Widgets might be built from one or more *parts*. For example, a button +has only one part called :cpp:enumerator:`LV_PART_MAIN`. However, a +:ref:`slider` has :cpp:enumerator:`LV_PART_MAIN`, :cpp:enumerator:`LV_PART_INDICATOR` +and :cpp:enumerator:`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: + +- :cpp:enumerator:`LV_STATE_DEFAULT`: Normal, released state +- :cpp:enumerator:`LV_STATE_CHECKED`: Toggled or checked state +- :cpp:enumerator:`LV_STATE_FOCUSED`: Focused via keypad or encoder or clicked via touchpad/mouse +- :cpp:enumerator:`LV_STATE_FOCUS_KEY`: Focused via keypad or encoder but not via touchpad/mouse +- :cpp:enumerator:`LV_STATE_EDITED`: Edit by an encoder +- :cpp:enumerator:`LV_STATE_HOVERED`: Hovered by mouse (not supported now) +- :cpp:enumerator:`LV_STATE_PRESSED`: Being pressed +- :cpp:enumerator:`LV_STATE_SCROLLED`: Being scrolled +- :cpp:enumerator:`LV_STATE_DISABLED`: Disabled + +For example, if you press an object it will automatically go to the +:cpp:enumerator:`LV_STATE_FOCUSED` and :cpp:enumerator:`LV_STATE_PRESSED` states and when you +release it the :cpp:enumerator:`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: + +.. code:: 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 :cpp:struct:`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 +:cpp:expr:`lv_style_init(&style1)`. After that, properties can be added to +configure the style. For example: + +.. code:: c + + 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 :ref:`style_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: + +.. code:: c + + lv_obj_add_style(slider1, &style1, LV_PART_INDICATOR | LV_STATE_PRESSED); + +If the *part* is :cpp:enumerator:`LV_PART_MAIN` it can be omitted: + +.. code:: c + + lv_obj_add_style(btn1, &style1, LV_STATE_PRESSED); /*Equal to LV_PART_MAIN | LV_STATE_PRESSED*/ + +Similarly, :cpp:enumerator:`LV_STATE_DEFAULT` can be omitted too: + +.. code:: c + + lv_obj_add_style(slider1, &style1, LV_PART_INDICATOR); /*Equal to LV_PART_INDICATOR | LV_STATE_DEFAULT*/ + +For :cpp:enumerator:`LV_STATE_DEFAULT` and :cpp:enumerator:`LV_PART_MAIN` simply write ``0``: + +.. code:: 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: + +.. code:: 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 +:cpp:enumerator:`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: + +.. code:: 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 :ref:`styles` 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 +-------- + +.. include:: ../examples/get_started/index.rst + +Micropython +----------- + +Learn more about :ref:`micropython`. + +.. code:: python + + import lvgl as lv + + # 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/docs/index.md b/docs/index.rst index f89f95382..950080cae 100644 --- a/docs/index.md +++ b/docs/index.rst @@ -1,38 +1,32 @@ +===================================== +Welcome to the documentation of LVGL! +===================================== -```eval_rst +.. raw:: html -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 -``` +.. toctree:: + :maxdepth: 6 + + intro/index + examples + get-started/index + porting/index + overview/index + widgets/index + layouts/index + libs/index + others/index + API/index + CONTRIBUTING + CODING_STYLE + CHANGELOG + ROADMAP diff --git a/docs/intro/index.md b/docs/intro/index.md deleted file mode 100644 index 4d7e53c59..000000000 --- a/docs/intro/index.md +++ /dev/null @@ -1,213 +0,0 @@ - -# 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 | No | -| v8.1 | 10 Nov, 2021 | 10 Nov, 2022 | No | -| v8.2 | 31 Jan, 2022 | 31 Jan, 2023 | Yes | -| v8.3 | 6 July, 2022 | 6 July, 2023 | Yes | -| v9.0 | 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, Espressif ESP32 and Raspberry Pi Pico W -- 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_t`, `lv_indev_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*. - -### 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/docs/intro/index.rst b/docs/intro/index.rst new file mode 100644 index 000000000..671525109 --- /dev/null +++ b/docs/intro/index.rst @@ -0,0 +1,285 @@ +.. _introduction: + +============ +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: + +Requirements +------------ + +Basically, every modern controller which is able to drive a display is suitable to run LVGL. The minimal requirements are: + +* 16, 32 or 64 bit microcontroller or processor +* > 16 MHz clock speed is recommended +* Flash/ROM: > 64 kB for the very essential components (> 180 kB is recommended) +* RAM: + * Static RAM usage: ~2 kB depending on the used features and object types + * stack: > 2kB (> 8 kB is recommended) + * Dynamic data (heap): > 2 KB (> 48 kB is recommended if using several objects). + Set by :c:macro:`LV_MEM_SIZE` in `lv_conf.h`. + * Display buffer: > *"Horizontal resolution"* pixels (> 10 *"Horizontal resolution"* is recommended) + * One frame buffer in the MCU or in an external display controller +* C99 or newer compiler +* Basic C (or C++) knowledge: + * `pointers <https://www.tutorialspoint.com/cprogramming/c_pointers.htm>`_. + * `structs <https://www.tutorialspoint.com/cprogramming/c_structures.htm>`_. + * `callbacks <https://www.geeksforgeeks.org/callbacks-in-c/>`_. + + + +:Note: *memory usage may vary depending on architecture, compiler and build options.* + +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 :ref:`contributing` to the project. +You can choose from many different ways of contributing See :ref:`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 version: incompatible API changes. E.g. v5.0.0, v6.0.0 +* Minor version: new but backward-compatible functionalities. E.g. v6.1.0, v6.2.0 +* Patch version: 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 :ref:`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 | 1 Feb, 2019 | 1 Feb, 2020 | No | ++---------+--------------+--------------+--------+ +|v6.1 | 26 Nov, 2019 | 26 Nov, 2020 | No | ++---------+--------------+--------------+--------+ +|v7.11 | 16 Mar, 2021 | 16 Mar, 2022 | No | ++---------+--------------+--------------+--------+ +|v8.0 | 1 Jun, 2021 | 1 Jun, 2022 | No | ++---------+--------------+--------------+--------+ +|v8.1 | 10 Nov, 2021 | 10 Nov, 2022 | No | ++---------+--------------+--------------+--------+ +|v8.2 | 31 Jan, 2022 | 31 Jan, 2023 | Yes | ++---------+--------------+--------------+--------+ +|v8.3 | 6 July, 2022 | 6 July, 2023 | Yes | ++---------+--------------+--------------+--------+ +|v9.0 |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 :ref:`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, Espressif ESP32 and Raspberry Pi Pico W +* 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 :ref:`display_interface` section to learn more. + + +LVGL doesn't start, randomly crashes or nothing is drawn on the display. What can be the problem? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Try increasing :c:macro:`LV_MEM_SIZE`. +* Be sure :cpp:type:`lv_disp_t`, :cpp:type:`lv_indev_t` and :cpp:type:`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 :ref:`logging` +* Enable asserts in `lv_conf.h` (`LV_USE_ASSERT_...`) +* If you use an RTOS + * increase the stack size of the task which calls :cpp:func:`lv_timer_handler` + * Be sure you used a mutex as described here: :ref:`os_interrupt` + + +My display driver is not called. What have I missed? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Be sure you are calling :cpp:expr:`lv_tick_inc(x)` in an interrupt and :cpp:func:`lv_timer_handler` in your main ``while(1)``. + +Learn more in the :ref:`tick` and :ref:`timer` sections. + + +Why is the display driver called only once? Only the upper part of the display is refreshed. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Be sure you are calling :cpp:expr:`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. + +.. code-block:: 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 :c:macro:`LV_COLOR_DEPTH` in *lv_conf.h*. + + +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 :c:macro:`LV_MEM_SIZE` in *lv_conf.h*. This memory is used when you create objects like buttons, labels, etc. +* To work with lower :c:macro:`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 :ref:`os_interrupt` section to learn more. diff --git a/docs/layouts/flex.md b/docs/layouts/flex.md deleted file mode 100644 index ff5ef346a..000000000 --- a/docs/layouts/flex.md +++ /dev/null @@ -1,119 +0,0 @@ - -# 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/docs/layouts/flex.rst b/docs/layouts/flex.rst new file mode 100644 index 000000000..917b557b8 --- /dev/null +++ b/docs/layouts/flex.rst @@ -0,0 +1,156 @@ +==== +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 +:c:expr:`lv_obj_set_layout(obj, LV_LAYOUT_FLEX)`. + +Note that the flex layout feature of LVGL needs to be globally enabled +with :c:macro:`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 +--------- + +:c:expr:`lv_obj_set_flex_flow(obj, flex_flow)` + +The possible values for ``flex_flow`` are: + +- :c:enumerator:`LV_FLEX_FLOW_ROW`: Place the children in a row without wrapping +- :c:enumerator:`LV_FLEX_FLOW_COLUMN`: Place the children in a column without wrapping +- :c:enumerator:`LV_FLEX_FLOW_ROW_WRAP`: Place the children in a row with wrapping +- :c:enumerator:`LV_FLEX_FLOW_COLUMN_WRAP`: Place the children in a column with wrapping +- :c:enumerator:`LV_FLEX_FLOW_ROW_REVERSE`: Place the children in a row without wrapping but in reversed order +- :c:enumerator:`LV_FLEX_FLOW_COLUMN_REVERSE`: Place the children in a column without wrapping but in reversed order +- :c:enumerator:`LV_FLEX_FLOW_ROW_WRAP_REVERSE`: Place the children in a row with wrapping but in reversed order +- :c:enumerator:`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 +:c:expr:`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 :c:enumerator:`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: + +- :c:enumerator:`LV_FLEX_ALIGN_START`: means left on a horizontally and top vertically. (default) +- :c:enumerator:`LV_FLEX_ALIGN_END`: means right on a horizontally and bottom vertically +- :c:enumerator:`LV_FLEX_ALIGN_CENTER`: simply center +- :c:enumerator:`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``. +- :c:enumerator:`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``. +- :c:enumerator:`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 +:c:expr:`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: + +- :c:enumerator:`FLEX_FLOW` +- :c:enumerator:`FLEX_MAIN_PLACE` +- :c:enumerator:`FLEX_CROSS_PLACE` +- :c:enumerator:`FLEX_TRACK_PLACE` +- :c:enumerator:`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: :c:expr:`lv_style_set_pad_column(&row_container_style,0)` + +Other features +************** + +RTL +--- + +If the base direction of the container is set the +:c:enumerator:`LV_BASE_DIR_RTL` the meaning of +:c:enumerator:`LV_FLEX_ALIGN_START` and +:c:enumerator:`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 +:c:expr:`lv_obj_add_flag(child, LV_OBJ_FLAG_FLEX_IN_NEW_TRACK)`. + +Example +******* + +.. include:: ../examples/layouts/flex/index.rst + +API +*** diff --git a/docs/layouts/grid.md b/docs/layouts/grid.md deleted file mode 100644 index ed552cf52..000000000 --- a/docs/layouts/grid.md +++ /dev/null @@ -1,113 +0,0 @@ - -# 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/docs/layouts/grid.rst b/docs/layouts/grid.rst new file mode 100644 index 000000000..30c6196cf --- /dev/null +++ b/docs/layouts/grid.rst @@ -0,0 +1,147 @@ +==== +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 +(:c:macro:`LV_GRID_CONTENT`) or in "Free unit" (FR) to distribute the free +space proportionally. + +To make an object a grid container call :c:expr:`lv_obj_set_layout(obj, LV_LAYOUT_GRID)`. + +Note that the grid layout feature of LVGL needs to be globally enabled +with :c:macro:`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 :c:macro:`LV_GRID_TEMPLATE_LAST`. + +For example: + +.. code:: c + + 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 +:c:expr:`lv_obj_set_grid_dsc_array(obj, col_dsc, row_dsc)`. + +Besides simple settings the size in pixel you can use two special +values: + +- :c:macro:`LV_GRID_CONTENT` set the width to the largest children on this track +- :c:expr:`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 +:c:expr:`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: + +- :c:enumerator:`LV_GRID_ALIGN_START`: means left on a horizontally and top vertically. (default) +- :c:enumerator:`LV_GRID_ALIGN_END`: means right on a horizontally and bottom vertically +- :c:enumerator:`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: + +- :c:enumerator:`LV_GRID_ALIGN_START`: means left on a horizontally and top vertically. (default) +- :c:enumerator:`LV_GRID_ALIGN_END`: means right on a horizontally and bottom vertically +- :c:enumerator:`LV_GRID_ALIGN_CENTER`: simply center +- :c:enumerator:`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``. +- :c:enumerator:`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``. +- :c:enumerator:`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 +:c:expr:`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: + +- :c:enumerator:`GRID_COLUMN_DSC_ARRAY` +- :c:enumerator:`GRID_ROW_DSC_ARRAY` +- :c:enumerator:`GRID_COLUMN_ALIGN` +- :c:enumerator:`GRID_ROW_ALIGN` +- :c:enumerator:`GRID_CELL_X_ALIGN` +- :c:enumerator:`GRID_CELL_COLUMN_POS` +- :c:enumerator:`GRID_CELL_COLUMN_SPAN` +- :c:enumerator:`GRID_CELL_Y_ALIGN` +- :c:enumerator:`GRID_CELL_ROW_POS` +- :c:enumerator:`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 :c:enumerator:`LV_BASE_DIR_RTL`, +the meaning of :c:enumerator:`LV_GRID_ALIGN_START` and :c:enumerator:`LV_GRID_ALIGN_END` is +swapped. I.e. ``START`` will mean right-most. + +The columns will be placed from right to left. + +Example +******* + +.. include:: ../examples/layouts/grid/index.rst + +API +*** diff --git a/docs/layouts/index.md b/docs/layouts/index.md deleted file mode 100644 index 44108d32a..000000000 --- a/docs/layouts/index.md +++ /dev/null @@ -1,11 +0,0 @@ - -# Layouts - - -```eval_rst -.. toctree:: - :maxdepth: 2 - - flex - grid -``` diff --git a/docs/layouts/index.rst b/docs/layouts/index.rst new file mode 100644 index 000000000..4ab3bb995 --- /dev/null +++ b/docs/layouts/index.rst @@ -0,0 +1,10 @@ +======= +Layouts +======= + + +.. toctree:: + :maxdepth: 2 + + flex + grid diff --git a/docs/libs/barcode.md b/docs/libs/barcode.md deleted file mode 100644 index 48ddd4b41..000000000 --- a/docs/libs/barcode.md +++ /dev/null @@ -1,30 +0,0 @@ - -# Barcode - -Barcode generation with LVGL. Uses [code128](https://github.com/fhunleth/code128) by [fhunleth](https://github.com/fhunleth). - -## Usage - -Enable `LV_USE_BARCODE` in `lv_conf.h`. - -Use `lv_barcode_create()` to create a barcode object, and use `lv_barcode_update()` to generate a barcode. - -Call `lv_barcode_set_scale()` or `lv_barcode_set_dark/light_color()` to adjust scaling and color, and call `lv_barcode_update()` again to regenerate the barcode. - -## Notes -- It is best not to manually set the width of the barcode, because when the width of the object is lower than the width of the barcode, the display will be incomplete due to truncation. -- The scale adjustment can only be an integer multiple, for example, `lv_barcode_set_scale(barcode, 2)` means 2x scaling. - -## Example -```eval_rst - -.. include:: ../../examples/libs/barcode/index.rst - -``` - -## API - -```eval_rst - -.. doxygenfile:: lv_barcode.h - :project: lvgl diff --git a/docs/libs/barcode.rst b/docs/libs/barcode.rst new file mode 100644 index 000000000..a70fce1fd --- /dev/null +++ b/docs/libs/barcode.rst @@ -0,0 +1,40 @@ +======= +Barcode +======= + +Barcode generation with LVGL. Uses +`code128 <https://github.com/fhunleth/code128>`__ by +`fhunleth <https://github.com/fhunleth>`__. + +Usage +----- + +Enable :c:macro:`LV_USE_BARCODE` in ``lv_conf.h``. + +Use :c:expr:`lv_barcode_create()` to create a barcode object, and use +:c:expr:`lv_barcode_update()` to generate a barcode. + +Call :c:expr:`lv_barcode_set_scale()` or :c:expr:`lv_barcode_set_dark/light_color()` +to adjust scaling and color, and call :c:expr:`lv_barcode_update()` again to +regenerate the barcode. + +Notes +----- + +- It is best not to manually set the width of the barcode, because when + the width of the object is lower than the width of the barcode, the + display will be incomplete due to truncation. +- The scale adjustment can only be an integer multiple, for example, + :c:expr:`lv_barcode_set_scale(barcode, 2)` means 2x scaling. + +Example +------- + +.. include:: ../examples/libs/barcode/index.rst + +API +--- + +:ref:`lv_barcode` + +:ref:`code128` diff --git a/docs/libs/bmp.md b/docs/libs/bmp.md deleted file mode 100644 index 3aace9e1f..000000000 --- a/docs/libs/bmp.md +++ /dev/null @@ -1,38 +0,0 @@ - -# 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/docs/libs/bmp.rst b/docs/libs/bmp.rst new file mode 100644 index 000000000..dc322c289 --- /dev/null +++ b/docs/libs/bmp.rst @@ -0,0 +1,45 @@ +=========== +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 :c:macro:`LV_USE_BMP` LVGL will register a new +image decoder automatically so BMP files can be directly used as image +sources. For example: + +.. code:: c + + 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 :ref:`file-system` or just +enable one in ``lv_conf.h`` with ``LV_USE_FS_...`` + +Limitations +----------- + +- Only BMP files are supported and BMP images as C array + (:c:struct:`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 :c:macro:`LV_COLOR_DEPTH`. + Use GIMP to save the image in the required format. Both RGB888 and + ARGB888 works with :c:macro:`LV_COLOR_DEPTH` ``32`` +- Palette is not supported. +- Because not the whole image is read in can not be zoomed or rotated. + +Example +------- + +.. include:: ../examples/libs/bmp/index.rst + +API +--- + +:ref:`lv_bmp` diff --git a/docs/libs/ffmpeg.md b/docs/libs/ffmpeg.md deleted file mode 100644 index b68712de4..000000000 --- a/docs/libs/ffmpeg.md +++ /dev/null @@ -1,37 +0,0 @@ - -# 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/docs/libs/ffmpeg.rst b/docs/libs/ffmpeg.rst new file mode 100644 index 000000000..d8dc0e95d --- /dev/null +++ b/docs/libs/ffmpeg.rst @@ -0,0 +1,40 @@ +============== +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 :c:macro:`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 +------- + +.. include:: ../examples/libs/ffmpeg/index.rst + +API +--- + +:ref:`lv_ffmpeg` diff --git a/docs/libs/freetype.md b/docs/libs/freetype.md deleted file mode 100644 index 8597ab0a9..000000000 --- a/docs/libs/freetype.md +++ /dev/null @@ -1,86 +0,0 @@ - -# FreeType support -Interface to [FreeType](https://www.freetype.org/) to generate font bitmaps run time. - -## Add FreeType to your project - -First, Download FreeType from [here](https://sourceforge.net/projects/freetype/files/). - -There are two ways to use FreeType: -### For UNIX -For UNIX systems, it is recommended to use the way of compiling and installing libraries. -- Enter the FreeType source code directory. -- `make` -- `sudo make install` -- Add include path: `/usr/include/freetype2` (for GCC: `-I/usr/include/freetype2 -L/usr/local/lib`) -- Link library: `freetype` (for GCC: `-L/usr/local/lib -lfreetype`) - -### For Embedded Devices -For embedded devices, it is more recommended to use the FreeType configuration file provided by LVGL, which only includes the most commonly used functions, which is very meaningful for saving limited FLASH space. - -- Copy the FreeType source code to your project directory. -- Refer to the following `Makefile` for configuration: - -```make -# FreeType custom configuration header file -CFLAGS += -DFT2_BUILD_LIBRARY -CFLAGS += -DFT_CONFIG_MODULES_H=<lvgl/src/libs/freetype/ftmodule.h> -CFLAGS += -DFT_CONFIG_OPTIONS_H=<lvgl/src/libs/freetype/ftoption.h> - -# FreeType include path -CFLAGS += -Ifreetype/include - -# FreeType C source file -FT_CSRCS += freetype/src/base/ftbase.c -FT_CSRCS += freetype/src/base/ftbitmap.c -FT_CSRCS += freetype/src/base/ftdebug.c -FT_CSRCS += freetype/src/base/ftglyph.c -FT_CSRCS += freetype/src/base/ftinit.c -FT_CSRCS += freetype/src/cache/ftcache.c -FT_CSRCS += freetype/src/gzip/ftgzip.c -FT_CSRCS += freetype/src/sfnt/sfnt.c -FT_CSRCS += freetype/src/smooth/smooth.c -FT_CSRCS += freetype/src/truetype/truetype.c -CSRCS += $(FT_CSRCS) -``` - -## Usage -Enable `LV_USE_FREETYPE` in `lv_conf.h`. - -Cache configuration: -- `LV_FREETYPE_CACHE_SIZE` - Maximum memory(Bytes) used to cache font bitmap, outline, character maps, etc. **Note:** This value does not include the memory used by 'FT_Face' and 'FT_Size' objects -- `LV_FREETYPE_CACHE_FT_FACES` - Maximum open number of `FT_Face` objects. -- `LV_FREETYPE_CACHE_FT_SIZES` - Maximum open number of `FT_Size` objects. - -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. - -By default, 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. - -If you want FreeType to use lvgl's memory allocation and file system interface, you can enable `LV_FREETYPE_USE_LVGL_PORT` in `lv_conf.h`, convenient for unified management. - -The font style supports *Italic* and **Bold** fonts processed by software, and can be set with reference to the following values: -- `LV_FREETYPE_FONT_STYLE_NORMAL` - Default style. -- `LV_FREETYPE_FONT_STYLE_ITALIC` - Italic style. -- `LV_FREETYPE_FONT_STYLE_BOLD` - Bold style. - -They can be combined.eg: `LV_FREETYPE_FONT_STYLE_BOLD | LV_FREETYPE_FONT_STYLE_ITALIC`. - -Use the `lv_freetype_font_create()` function to create a font. To delete a font, use `lv_freetype_font_del()`. For more detailed usage, please refer to example code. - -## 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/master/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/docs/libs/freetype.rst b/docs/libs/freetype.rst new file mode 100644 index 000000000..c609235d0 --- /dev/null +++ b/docs/libs/freetype.rst @@ -0,0 +1,112 @@ +================ +FreeType support +================ + +Interface to `FreeType <https://www.freetype.org/>`__ to generate font +bitmaps run time. + +Add FreeType to your project +---------------------------- + +First, Download FreeType from `here <https://sourceforge.net/projects/freetype/files/>`__. + +There are two ways to use FreeType: ### For UNIX For UNIX systems, it is +recommended to use the way of compiling and installing libraries. - +Enter the FreeType source code directory. + +- ``make`` +- ``sudo make install`` +- Add include path: ``/usr/include/freetype2`` (for GCC: ``-I/usr/include/freetype2 -L/usr/local/lib``) +- Link library: ``freetype`` (for GCC: ``-L/usr/local/lib -lfreetype``) + +For Embedded Devices +~~~~~~~~~~~~~~~~~~~~ + +For embedded devices, it is more recommended to use the FreeType +configuration file provided by LVGL, which only includes the most +commonly used functions, which is very meaningful for saving limited +FLASH space. + +- Copy the FreeType source code to your project directory. +- Refer to the following ``Makefile`` for configuration: + +.. code:: make + + # FreeType custom configuration header file + CFLAGS += -DFT2_BUILD_LIBRARY + CFLAGS += -DFT_CONFIG_MODULES_H=<lvgl/src/libs/freetype/ftmodule.h> + CFLAGS += -DFT_CONFIG_OPTIONS_H=<lvgl/src/libs/freetype/ftoption.h> + + # FreeType include path + CFLAGS += -Ifreetype/include + + # FreeType C source file + FT_CSRCS += freetype/src/base/ftbase.c + FT_CSRCS += freetype/src/base/ftbitmap.c + FT_CSRCS += freetype/src/base/ftdebug.c + FT_CSRCS += freetype/src/base/ftglyph.c + FT_CSRCS += freetype/src/base/ftinit.c + FT_CSRCS += freetype/src/cache/ftcache.c + FT_CSRCS += freetype/src/gzip/ftgzip.c + FT_CSRCS += freetype/src/sfnt/sfnt.c + FT_CSRCS += freetype/src/smooth/smooth.c + FT_CSRCS += freetype/src/truetype/truetype.c + CSRCS += $(FT_CSRCS) + +Usage +----- + +Enable :c:macro:`LV_USE_FREETYPE` in ``lv_conf.h``. + +Cache configuration: + +- :c:macro:`LV_FREETYPE_CACHE_SIZE` Maximum memory(Bytes) used to cache font bitmap, outline, character maps, etc. + :Note: This value does not include the memory used by ``FT_Face`` and ``FT_Size`` objects +- :c:macro:`LV_FREETYPE_CACHE_FT_FACES`: Maximum open number of ``FT_Face`` objects. +- :c:macro:`LV_FREETYPE_CACHE_FT_SIZES`: Maximum open number of ``FT_Size`` objects. + +When you are sure that all the used font sizes will not be greater than +256, you can enable :c:macro:`LV_FREETYPE_SBIT_CACHE`, which is much more +memory efficient for small bitmaps. + +By default, 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. + +If you want FreeType to use lvgl's memory allocation and file system +interface, you can enable :c:macro:`LV_FREETYPE_USE_LVGL_PORT` in +``lv_conf.h``, convenient for unified management. + +The font style supports *Italic* and **Bold** fonts processed by +software, and can be set with reference to the following values: + +- :c:enumerator:`LV_FREETYPE_FONT_STYLE_NORMAL`: Default style. +- :c:enumerator:`LV_FREETYPE_FONT_STYLE_ITALIC`: Italic style. +- :c:enumerator:`LV_FREETYPE_FONT_STYLE_BOLD`: Bold style. + +They can be combined.eg: +:c:expr:`LV_FREETYPE_FONT_STYLE_BOLD | LV_FREETYPE_FONT_STYLE_ITALIC`. + +Use the :c:expr:`lv_freetype_font_create()` function to create a font. To +delete a font, use :c:expr:`lv_freetype_font_del()`. For more detailed usage, +please refer to example code. + +Example +------- + +.. include:: ../examples/libs/freetype/index.rst + +Learn more +---------- + +- FreeType`tutorial <https://www.freetype.org/freetype2/docs/tutorial/step1.html>`__ +- LVGL's :ref:`add_font` + +API +--- + +:ref:`lv_freetype` + +:ref:`ftoption` + +:ref:`ftmodule` diff --git a/docs/libs/fs.rst b/docs/libs/fs.rst new file mode 100644 index 000000000..0cb00e502 --- /dev/null +++ b/docs/libs/fs.rst @@ -0,0 +1,35 @@ +====================== +File System Interfaces +====================== + +LVGL has a :ref:`file-system` 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. :c:func:`lv_fs_read` caches this size of data to lower the +number of actual reads from the storage. + +API +*** + +:ref:`lv_fsdrv` diff --git a/docs/libs/fsdrv.md b/docs/libs/fsdrv.md deleted file mode 100644 index 7b9015aa2..000000000 --- a/docs/libs/fsdrv.md +++ /dev/null @@ -1,21 +0,0 @@ - -# 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/docs/libs/gif.md b/docs/libs/gif.md deleted file mode 100644 index f3ae75847..000000000 --- a/docs/libs/gif.md +++ /dev/null @@ -1,39 +0,0 @@ - -# 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/docs/libs/gif.rst b/docs/libs/gif.rst new file mode 100644 index 000000000..a924b9103 --- /dev/null +++ b/docs/libs/gif.rst @@ -0,0 +1,55 @@ +=========== +GIF decoder +=========== + +Allow using GIF images in LVGL. Based on +https://github.com/lecram/gifdec + +When enabled in ``lv_conf.h`` with :c:macro:`LV_USE_GIF` +:c:expr:`lv_gif_create(parent)` can be used to create a gif widget. + +:c:expr:`lv_gif_set_src(obj, src)` works very similarly to :c:func:`lv_img_set_src`. +As source, it also accepts images as variables (:c:struct:`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: + +.. code:: 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 :ref:`file-system` 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: + +- :c:macro:`LV_COLOR_DEPTH` ``8``: 3 x image width x image height +- :c:macro:`LV_COLOR_DEPTH` ``16``: 4 x image width x image height +- :c:macro:`LV_COLOR_DEPTH` ``32``: 5 x image width x image height + +Example +------- + +.. include:: ../examples/libs/gif/index.rst + +API +--- + +:ref:`lv_gif` + +:ref:`gifdec` diff --git a/docs/libs/index.md b/docs/libs/index.md deleted file mode 100644 index 6e3fda0df..000000000 --- a/docs/libs/index.md +++ /dev/null @@ -1,21 +0,0 @@ -# 3rd party libraries - - -```eval_rst - -.. toctree:: - :maxdepth: 1 - - fsdrv - bmp - sjpg - png - gif - freetype - tiny_ttf - qrcode - barcode - rlottie - ffmpeg -``` - diff --git a/docs/libs/index.rst b/docs/libs/index.rst new file mode 100644 index 000000000..b43b45aab --- /dev/null +++ b/docs/libs/index.rst @@ -0,0 +1,19 @@ +=================== +3rd party libraries +=================== + + +.. toctree:: + :maxdepth: 1 + + fs + bmp + sjpg + png + gif + freetype + tiny_ttf + qrcode + barcode + rlottie + ffmpeg diff --git a/docs/libs/png.md b/docs/libs/png.md deleted file mode 100644 index 96a802488..000000000 --- a/docs/libs/png.md +++ /dev/null @@ -1,27 +0,0 @@ - -# 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/docs/libs/png.rst b/docs/libs/png.rst new file mode 100644 index 000000000..daee64504 --- /dev/null +++ b/docs/libs/png.rst @@ -0,0 +1,31 @@ +=========== +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 :c:macro:`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 :ref:`file-system` 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 :ref:`image-caching` feature can be useful. + +Example +------- + +.. include:: ../examples/libs/png/index.rst + +API +--- + +:ref:`lv_png` + +:ref:`lodepng` diff --git a/docs/libs/qrcode.md b/docs/libs/qrcode.md deleted file mode 100644 index dc25fd7d7..000000000 --- a/docs/libs/qrcode.md +++ /dev/null @@ -1,30 +0,0 @@ - -# QR code - -QR code generation with LVGL. Uses [QR-Code-generator](https://github.com/nayuki/QR-Code-generator) by [nayuki](https://github.com/nayuki). - -## Usage - -Enable `LV_USE_QRCODE` in `lv_conf.h`. - -Use `lv_qrcode_create()` to create a qrcode object, and use `lv_qrcode_update()` to generate a QR code. - -If you need to re-modify the size and color, use `lv_qrcode_set_size()` and `lv_qrcode_set_dark/light_color()`, and call `lv_qrcode_update()` again to regenerate the QR code. - -## 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/docs/libs/qrcode.rst b/docs/libs/qrcode.rst new file mode 100644 index 000000000..c14573fa6 --- /dev/null +++ b/docs/libs/qrcode.rst @@ -0,0 +1,37 @@ +======= +QR code +======= + +QR code generation with LVGL. Uses +`QR-Code-generator <https://github.com/nayuki/QR-Code-generator>`__ by +`nayuki <https://github.com/nayuki>`__. + +Usage +----- + +Enable :c:macro:`LV_USE_QRCODE` in ``lv_conf.h``. + +Use :c:expr:`lv_qrcode_create()` to create a qrcode object, and use +:c:expr:`lv_qrcode_update()` to generate a QR code. + +If you need to re-modify the size and color, use +:c:expr:`lv_qrcode_set_size()` and :c:expr:`lv_qrcode_set_dark/light_color()`, and +call :c:expr:`lv_qrcode_update()` again to regenerate the QR code. + +Notes +----- + +- QR codes with less data are smaller, but they scaled by an integer + number to best fit to the given size. + +Example +------- + +.. include:: ../examples/libs/qrcode/index.rst + +API +--- + +:ref:`lv_qrcode` + +:ref:`qrcodegen` diff --git a/docs/libs/rlottie.md b/docs/libs/rlottie.md deleted file mode 100644 index ff8980f2a..000000000 --- a/docs/libs/rlottie.md +++ /dev/null @@ -1,194 +0,0 @@ - - -# 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. - -### ESP-IDF example at bottom - -## 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. - - -## ESP-IDF Example -### Background -Rlottie can be expensive to render on embedded hardware. Lottie animations tend to use a large amount of CPU time and can use large portions of RAM. This will vary from lottie to lottie but in general for best performance: -* Limit total # of frames in the animation -* Where possible, try to avoid bezier type animations -* Limit animation render size - -If your ESP32 chip does not have SPIRAM you will face severe limitations in render size. - -To give a better idea on this, lets assume you want to render a 240x320 lottie animation. - -In order to pass initialization of the lv_rlottie_t object, you need 240x320x32/8 (307k) available memory. The latest ESP32-S3 has 256kb RAM available for this (before freeRtos and any other initialization starts taking chunks out). So while you can probably start to render a 50x50 animation without SPIRAM, PSRAM is highly recommended. - -Additionally, while you might be able to pass initialization of the lv_rlottie_t object, as rlottie renders frame to frame, this consumes additional memory. A 30 frame animation that plays over 1 second probably has minimal issues, but a 300 frame animation playing over 10 seconds could very easily crash due to lack of memory as rlottie renders, depending on the complexity of the animation. - -Rlottie will not compile for the IDF using the -02 compiler option at this time. - -For stability in lottie animations, I found that they run best in the IDF when enabling LV_MEM_CUSTOM (using stdlib.h) - -For all its faults, when running right-sized animations, they provide a wonderful utility to LVGL on embedded LCDs and can look really good when done properly. - -When picking/designing a lottie animation consider the following limitations: -- Build the lottie animation to be sized for the intended size - it can scale/resize, but performance will be best when the base lottie size is as intended -- Limit total number of frames, the longer the lottie animation is, the more memory it will consume for rendering (rlottie consumes IRAM for rendering) -- Build the lottie animation for the intended frame rate - default lottie is 60fps, embedded LCDs likely wont go above 30fps - -### IDF Setup -Where the LVGL simulator uses the installed rlottie lib, the IDF works best when using rlottie as a submodule under the components directory. - -``` -cd 'your/project/directory' -git add submodule -git add submodule https://github.com/Samsung/rlottie.git ./components/rlottie/rlottie -git submodule update --init --recursive -``` - -Now, Rlottie is available as a component in the IDF, but it requires some additional changes and a CMakeLists file to tell the IDF how to compile. - - -### Rlottie patch file -Rlottie relies on a dynamic linking for an image loader lib. This needs to be disabled as the IDF doesn't play nice with dynamic linking. - -A patch file is available in lvgl uner: /env_support/esp/rlottie/0001-changes-to-compile-with-esp-idf.patch - -Apply the patch file to your rlottie submodule. - -### CMakeLists for IDF -An example CMakeLists file has been provided at /env_support/esp/rlottie/CMakeLists.txt - -Copy this CMakeLists file to 'your-project-directory'/components/rlottie/ - -In addition to the component CMakeLists file, you'll also need to tell your project level CMakeLists in your IDF project to require rlottie: - -``` -REQUIRES "lvgl" "rlottie" -``` - -From here, you should be able to use lv_rlottie objects in your ESP-IDF project as any other widget in LVGL ESP examples. Please remember that these animations can be highly resource constrained and this does not guarantee that every animation will work. - -### Additional Rlottie considerations in ESP-IDF -While unecessary, removing the rlottie/rlottie/example folder can remove many un-needed files for this embedded LVGL application - -From here, you can use the relevant LVGL lv_rlottie functions to create lottie animations in LVGL on embedded hardware! - -Please note, that while lottie animations are capable of running on many ESP chips, below is recommended for best performance. - -* ESP32-S3-WROOM-1-N16R8 - * 16mb quad spi flash - * 8mb octal spi PSRAM -* IDF4.4 or higher - -The Esp-box devkit meets this spec and https://github.com/espressif/esp-box is a great starting point to adding lottie animations. - -you'll need to enable LV_USE_RLOTTIE through idf.py menuconfig under LVGL component settings. - -### Additional changes to make use of SPIRAM - -lv_alloc/realloc do not make use of SPIRAM. Given the high memory usage of lottie animations, it is recommended to shift as much out of internal DRAM into SPIRAM as possible. In order to do so, SPIRAM will need to be enabled in the menuconfig options for your given espressif chip. - -There may be a better solution for this, but for the moment the recommendation is to make local modifications to the lvgl component in your espressif project. This is as simple as swapping lv_alloc/lv_realloc calls in lv_rlottie.c with heap_caps_malloc (for IDF) with the appropriate MALLOC_CAP call - for SPIRAM usage this is MALLOC_CAP_SPIRAM. - -```c -rlottie->allocated_buf = heap_caps_malloc(allocaled_buf_size+1, MALLOC_CAP_SPIRAM); -``` - - -## Example -```eval_rst - -.. include:: ../../examples/libs/rlottie/index.rst - -``` - -## API - -```eval_rst - -.. doxygenfile:: lv_rlottie.h - :project: lvgl diff --git a/docs/libs/rlottie.rst b/docs/libs/rlottie.rst new file mode 100644 index 000000000..c14ce8551 --- /dev/null +++ b/docs/libs/rlottie.rst @@ -0,0 +1,277 @@ +============= +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: + +.. code:: shell + + 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. + +ESP-IDF example at bottom +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Usage +----- + +You can use animation from files or raw data (text). In either case +first you need to enable :c:macro:`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: + +.. code:: 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.: + +.. code:: shell + + ./filetohex.py path/to/lottie.json > out.txt + +To create an animation from raw data: + +.. code:: 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: +:c:func:`lv_rlottie_set_play_mode` and :c:func:`lv_rlottie_set_current_frame`. +You'll combine your intentions when calling the first method, like in +these examples: + +.. code:: 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 :c:enumerator:`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 :c:struct:`lv_obj_t` instance to a :c:struct:`lv_rlottie_t` instance +and inspect the ``current_frame`` and ``total_frames`` members. + +ESP-IDF Example +--------------- + +Background +~~~~~~~~~~ + +Rlottie can be expensive to render on embedded hardware. Lottie +animations tend to use a large amount of CPU time and can use large +portions of RAM. This will vary from lottie to lottie but in general for +best performance: \* Limit total # of frames in the animation \* Where +possible, try to avoid bezier type animations \* Limit animation render +size + +If your ESP32 chip does not have SPIRAM you will face severe limitations +in render size. + +To give a better idea on this, lets assume you want to render a 240x320 +lottie animation. + +In order to pass initialization of the lv_rlottie_t object, you need +240x320x32/8 (307k) available memory. The latest ESP32-S3 has 256kb RAM +available for this (before freeRtos and any other initialization starts +taking chunks out). So while you can probably start to render a 50x50 +animation without SPIRAM, PSRAM is highly recommended. + +Additionally, while you might be able to pass initialization of the +lv_rlottie_t object, as rlottie renders frame to frame, this consumes +additional memory. A 30 frame animation that plays over 1 second +probably has minimal issues, but a 300 frame animation playing over 10 +seconds could very easily crash due to lack of memory as rlottie +renders, depending on the complexity of the animation. + +Rlottie will not compile for the IDF using the -02 compiler option at +this time. + +For stability in lottie animations, I found that they run best in the +IDF when enabling :c:macro:`LV_MEM_CUSTOM` (using stdlib.h) + +For all its faults, when running right-sized animations, they provide a +wonderful utility to LVGL on embedded LCDs and can look really good when +done properly. + +When picking/designing a lottie animation consider the following +limitations: - Build the lottie animation to be sized for the intended +size - it can scale/resize, but performance will be best when the base +lottie size is as intended - Limit total number of frames, the longer +the lottie animation is, the more memory it will consume for rendering +(rlottie consumes IRAM for rendering) - Build the lottie animation for +the intended frame rate - default lottie is 60fps, embedded LCDs likely +wont go above 30fps + +IDF Setup +~~~~~~~~~ + +Where the LVGL simulator uses the installed rlottie lib, the IDF works +best when using rlottie as a submodule under the components directory. + +.. code:: shell + + cd 'your/project/directory' + git add submodule + git add submodule https://github.com/Samsung/rlottie.git ./components/rlottie/rlottie + git submodule update --init --recursive + +Now, Rlottie is available as a component in the IDF, but it requires +some additional changes and a CMakeLists file to tell the IDF how to +compile. + +Rlottie patch file +~~~~~~~~~~~~~~~~~~ + +Rlottie relies on a dynamic linking for an image loader lib. This needs +to be disabled as the IDF doesn't play nice with dynamic linking. + +A patch file is available in lvgl uner: +``/env_support/esp/rlottie/0001-changes-to-compile-with-esp-idf.patch`` + +Apply the patch file to your rlottie submodule. + +CMakeLists for IDF +~~~~~~~~~~~~~~~~~~ + +An example CMakeLists file has been provided at +``/env_support/esp/rlottie/CMakeLists.txt`` + +Copy this CMakeLists file to +``‘your-project-directory'/components/rlottie/`` + +In addition to the component CMakeLists file, you'll also need to tell +your project level CMakeLists in your IDF project to require rlottie: + +.. code:: console + + REQUIRES "lvgl" "rlottie" + +From here, you should be able to use lv_rlottie objects in your ESP-IDF +project as any other widget in LVGL ESP examples. Please remember that +these animations can be highly resource constrained and this does not +guarantee that every animation will work. + +Additional Rlottie considerations in ESP-IDF +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +While unecessary, removing the ``rlottie/rlottie/example`` folder can remove +many un-needed files for this embedded LVGL application + +From here, you can use the relevant LVGL lv_rlottie functions to create +lottie animations in LVGL on embedded hardware! + +Please note, that while lottie animations are capable of running on many +ESP chips, below is recommended for best performance. + +- ESP32-S3-WROOM-1-N16R8 + + - 16mb quad spi flash + - 8mb octal spi PSRAM + +- IDF4.4 or higher + +The Esp-box devkit meets this spec and +https://github.com/espressif/esp-box is a great starting point to adding +lottie animations. + +you'll need to enable:c:macro:`LV_USE_RLOTTIE` through idf.py menuconfig under +LVGL component settings. + +Additional changes to make use of SPIRAM +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +lv_alloc/realloc do not make use of SPIRAM. Given the high memory usage +of lottie animations, it is recommended to shift as much out of internal +DRAM into SPIRAM as possible. In order to do so, SPIRAM will need to be +enabled in the menuconfig options for your given espressif chip. + +There may be a better solution for this, but for the moment the +recommendation is to make local modifications to the lvgl component in +your espressif project. This is as simple as swapping +lv_alloc/lv_realloc calls in lv_rlottie.c with heap_caps_malloc (for +IDF) with the appropriate :c:expr:`MALLOC_CAP` call - for SPIRAM usage this is +:c:expr:`MALLOC_CAP_SPIRAM`. + +.. code:: c + + rlottie->allocated_buf = heap_caps_malloc(allocaled_buf_size+1, MALLOC_CAP_SPIRAM); + +Example +------- + +.. include:: ../examples/libs/rlottie/index.rst + + +API +--- + +:ref:`lv_rlottie` diff --git a/docs/libs/sjpg.md b/docs/libs/sjpg.md deleted file mode 100644 index 3ee7858ee..000000000 --- a/docs/libs/sjpg.md +++ /dev/null @@ -1,73 +0,0 @@ - -# 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/docs/libs/sjpg.rst b/docs/libs/sjpg.rst new file mode 100644 index 000000000..c583aa59c --- /dev/null +++ b/docs/libs/sjpg.rst @@ -0,0 +1,96 @@ +=========== +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 :c:macro:`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: + +.. code:: c + + 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 :ref:`file-system` 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: + +.. code:: 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 +------- + +.. include:: ../examples/libs/sjpg/index.rst + + +API +--- + +:ref:`lv_sjpg` + +:ref:`tjpgd` + +:ref:`tjpgdcnf` diff --git a/docs/libs/tiny_ttf.md b/docs/libs/tiny_ttf.md deleted file mode 100644 index de31f4e10..000000000 --- a/docs/libs/tiny_ttf.md +++ /dev/null @@ -1,29 +0,0 @@ -# Tiny TTF font engine - -## Usage - -Allow using TrueType fonts LVGL. Based on https://github.com/nothings/stb - -When enabled in `lv_conf.h` with `LV_USE_TINY_TTF` `lv_tiny_ttf_create_data(data, data_size, line_height)` can be used to create a TTF font instance at the specified line height. You can then use that font anywhere `lv_font_t` is accepted. - -By default, the TTF or OTF file must be embedded as an array, either in a header, or loaded into RAM in order to function. - -However, if `LV_TINY_TTF_FILE_SUPPORT` is enabled, `lv_tiny_ttf_create_file(path, line_height)` will also be available, allowing tiny_ttf to stream from a file. The file must remain open the entire time the font is being used. - -After a font is created, you can change the size by using `lv_tiny_ttf_set_size(font, line_height)`. - -By default, a font will use up to 4KB of cache to speed up rendering glyphs. This maximum can be changed by using `lv_tiny_ttf_create_data_ex(data, data_size, line_height, cache_size)` or `lv_tiny_ttf_create_file_ex(path, line_height, cache_size)` (when available). The cache size is indicated in bytes. - -## Example -```eval_rst - -.. include:: ../../examples/libs/tiny_ttf/index.rst - -``` - -## API - -```eval_rst - -.. doxygenfile:: lv_tiny_ttf.h - :project: lvgl diff --git a/docs/libs/tiny_ttf.rst b/docs/libs/tiny_ttf.rst new file mode 100644 index 000000000..61e56cee9 --- /dev/null +++ b/docs/libs/tiny_ttf.rst @@ -0,0 +1,46 @@ +==================== +Tiny TTF font engine +==================== + +Usage +----- + +Allow using TrueType fonts LVGL. Based on +https://github.com/nothings/stb + +When enabled in ``lv_conf.h`` with :c:macro:`LV_USE_TINY_TTF` +:c:expr:`lv_tiny_ttf_create_data(data, data_size, line_height)` can be used to +create a TTF font instance at the specified line height. You can then +use that font anywhere :c:struct:`lv_font_t` is accepted. + +By default, the TTF or OTF file must be embedded as an array, either in +a header, or loaded into RAM in order to function. + +However, if :c:macro:`LV_TINY_TTF_FILE_SUPPORT` is enabled, +:c:expr:`lv_tiny_ttf_create_file(path, line_height)` will also be available, +allowing tiny_ttf to stream from a file. The file must remain open the +entire time the font is being used. + +After a font is created, you can change the size by using +:c:expr:`lv_tiny_ttf_set_size(font, line_height)`. + +By default, a font will use up to 4KB of cache to speed up rendering +glyphs. This maximum can be changed by using +:c:expr:`lv_tiny_ttf_create_data_ex(data, data_size, line_height, cache_size)` +or :c:expr:`lv_tiny_ttf_create_file_ex(path, line_height, cache_size)` (when +available). The cache size is indicated in bytes. + +Example +------- + +.. include:: ../examples/libs/tiny_ttf/index.rst + + +API +--- + +:ref:`lv_tiny_ttf` + +:ref:`stb_rect_pack` + +:ref:`stb_truetype_htcw` diff --git a/docs/others/file_explorer.md b/docs/others/file_explorer.md deleted file mode 100644 index 463377d75..000000000 --- a/docs/others/file_explorer.md +++ /dev/null @@ -1,161 +0,0 @@ -# File Explorer - -`lv_file_explorer` provides an API to browse the contents of the file system. `lv_file_explorer` only provides the file browsing function, but does not provide the actual file operation function. In other words, you can't click a picture file to open and view the picture like a PC. `lv_file_explorer` will tell you the full path and name of the currently clicked file. The file operation function needs to be implemented by the user. - - -The file list in `lv_file_explorer` is based on [lv_table](/widgets/table), and the quick access bar is based on [lv_list](/widgets/list). Therefore, care should be taken to ensure that [lv_table](/widgets/table) and [lv_list](/widgets/list) are enabled. - -<details> -<summary>中文</summary> -<p> - -`lv_file_explorer` 提供API让我们可以浏览文件系统中的内容。`lv_file_explorer` 只提供了文件浏览功能，并不提供实际的文件操作功能，也就是说，不能像PC那样点击一个图片文件就可以打开查看该图片。`lv_file_explorer` 会告诉您当前点击的文件的完整路径和名称，文件操作功能需要用户自己实现。 - -`lv_file_explorer` 中的文件列表基于 [lv_table](/widgets/table) 实现，快速访问栏基于 [lv_list](/widgets/list) 实现。因此，要注意确保使能了 `lv_table` 和 `lv_list`。 - - -</p> -</details> - -## Usage - -Enable `LV_USE_FILE_EXPLORER` in `lv_conf.h`. - -First use `lv_file_explorer_create(lv_scr_act())` to create a file explorer, The default size is the screen size. After that, you can customize the style like widget. - -<details> -<summary>中文</summary> -<p> - -在 `lv_conf.h` 中打开 `LV_USE_FILE_EXPLORER`。 - -首先，使用 `lv_file_explorer_create(lv_scr_act())` 函数创建一个文件浏览器，默认大小为屏幕大小，之后可以像组件那样自定义样式。 - -</p> -</details> - - -### Quick access - -The quick access bar is optional. You can turn off `LV_FILE_EXPLORER_QUICK_ACCESS` in `lv_conf.h` so that the quick access bar will not be created. This can save some memory, but not much. After the quick access bar is created, it can be hidden by clicking the button at the top left corner of the browsing area, which is very useful for small screen devices. - -You can use `lv_file_explorer_set_quick_access_path(file_explorer, LV_FILE_EXPLORER_QA_XX, "path")` to set the path of the quick access bar. The items of the quick access bar are fixed. Currently, there are the following items: - -- `LV_FILE_EXPLORER_QA_HOME` -- `LV_FILE_EXPLORER_QA_MUSIC` -- `LV_FILE_EXPLORER_QA_PICTURES` -- `LV_FILE_EXPLORER_QA_VIDEO` -- `LV_FILE_EXPLORER_QA_DOCS` -- `LV_FILE_EXPLORER_QA_MNT` -- `LV_FILE_EXPLORER_QA_FS` - -<details> -<summary>中文</summary> -<p> - -快速访问栏是可选的，您可以在 `lv_conf.h` 中关闭 `LV_FILE_EXPLORER_QUICK_ACCESS`，这样快速访问栏就不会被创建出来，这能节省一些内存，但并不是很多。快速访问栏被创建出来之后，可以通过点击浏览区域顶部左上角的按钮隐藏起来，这对于小屏幕设备非常有用。 - -可以通过 `lv_file_explorer_set_quick_access_path(file_explorer, LV_FILE_EXPLORER_QA_XX, "path")` 设置快速访问栏的路径，快速访问栏的项目是固定的，目前有以下项目： - -- `LV_FILE_EXPLORER_QA_HOME` -- `LV_FILE_EXPLORER_QA_MUSIC` -- `LV_FILE_EXPLORER_QA_PICTURES` -- `LV_FILE_EXPLORER_QA_VIDEO` -- `LV_FILE_EXPLORER_QA_DOCS` -- `LV_FILE_EXPLORER_QA_MNT` -- `LV_FILE_EXPLORER_QA_FS` - -</p> -</details> - -### Sort - -You can use `lv_file_explorer_set_sort(file_explorer, LV_EXPLORER_SORT_XX)` to set sorting method. There are the following sorting methods: - -- `LV_EXPLORER_SORT_NONE` -- `LV_EXPLORER_SORT_KIND` - -You can customize the sorting. Before custom sort, please set the default sorting to `LV_EXPLORER_SORT_NONE`. The default is `LV_EXPLORER_SORT_NONE`. - -<details> -<summary>中文</summary> -<p> - -可以通过 `lv_file_explorer_set_sort(file_explorer, LV_EXPLORER_SORT_XX)` 设置排序方式，有以下排序方式： - -- `LV_EXPLORER_SORT_NONE` -- `LV_EXPLORER_SORT_KIND` - -您可以自定义排序规则，在这之前请先将排序规则设置为 `LV_EXPLORER_SORT_NONE` 然后在 `LV_EVENT_READY` 事件中处理。默认的排序规则是 `LV_EXPLORER_SORT_NONE` - -</p> -</details> - -## Event - -- `LV_EVENT_READY` sent shen a directory is opened. You can customize the sort. - -- `LV_EVENT_VALUE_CHANGED` sent when an item(file) in the file list is clicked. - -You can use `lv_file_explorer_get_cur_path` to get the current path and `lv_file_explorer_get_sel_fn` to get the name of the currently selected file in the event processing function. For example: - -```c -static void file_explorer_event_handler(lv_event_t * e) -{ - lv_event_code_t code = lv_event_get_code(e); - lv_obj_t * obj = lv_event_get_target(e); - - if(code == LV_EVENT_VALUE_CHANGED) { - char * cur_path = lv_file_explorer_get_cur_path(obj); - char * sel_fn = lv_file_explorer_get_sel_fn(obj); - LV_LOG_USER("%s%s", cur_path, sel_fn); - } -} -``` - -You can also save the obtained **path** and **file** name into an array through functions such as *strcpy* and *strcat* for later use. - -<details> -<summary>中文</summary> -<p> - -- 当打开一个目录后会发送 `LV_EVENT_READY` 事件。您可以在这里自定义排序规则。 -- 当文件列表中的项目（文件）被点击时会发送 `LV_EVENT_VALUE_CHANGED` 事件。 - -可以在事件处理函数中通过 `lv_file_explorer_get_cur_path` 获取当前所在的路径，通过 `lv_file_explorer_get_sel_fn` 获取当前选中的文件的名称。比如： - -```c -static void file_explorer_event_handler(lv_event_t * e) -{ - lv_event_code_t code = lv_event_get_code(e); - lv_obj_t * obj = lv_event_get_target(e); - - if(code == LV_EVENT_VALUE_CHANGED) { - char * cur_path = lv_file_explorer_get_cur_path(obj); - char * sel_fn = lv_file_explorer_get_sel_fn(obj); - LV_LOG_USER("%s%s", cur_path, sel_fn); - } -} -``` - -您还可以将获取到的 **路径** 和 **文件名称** 通过例如 strcpy 和 strcat 函数保存到一个数组中，方便后续使用。 - -</p> -</details> - -## Example - -```eval_rst - -.. include:: ../../examples/others/file_explorer/index.rst - -``` - -## API - -```eval_rst - -.. doxygenfile:: lv_file_explorer.h - :project: lvgl - -``` diff --git a/docs/others/file_explorer.rst b/docs/others/file_explorer.rst new file mode 100644 index 000000000..5a10e6ce9 --- /dev/null +++ b/docs/others/file_explorer.rst @@ -0,0 +1,299 @@ +============= +File Explorer +============= + +``lv_file_explorer`` provides an API to browse the contents of the file +system. ``lv_file_explorer`` only provides the file browsing function, +but does not provide the actual file operation function. In other words, +you can’t click a picture file to open and view the picture like a PC. +``lv_file_explorer`` will tell you the full path and name of the +currently clicked file. The file operation function needs to be +implemented by the user. + +The file list in ``lv_file_explorer`` is based on +`lv_table </widgets/table>`__, and the quick access bar is based on +`lv_list </widgets/list>`__. Therefore, care should be taken to ensure +that `lv_table </widgets/table>`__ and `lv_list </widgets/list>`__ are +enabled. + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +中文 + +.. raw:: html + + </summary> + +.. raw:: html + + <p> + +``lv_file_explorer`` +提供API让我们可以浏览文件系统中的内容。\ ``lv_file_explorer`` +只提供了文件浏览功能，并不提供实际的文件操作功能，也就是说，不能像PC那样点击一个图片文件就可以打开查看该图片。\ ``lv_file_explorer`` +会告诉您当前点击的文件的完整路径和名称，文件操作功能需要用户自己实现。 + +``lv_file_explorer`` 中的文件列表基于 `lv_table </widgets/table>`__ +实现，快速访问栏基于 `lv_list </widgets/list>`__ +实现。因此，要注意确保使能了 ``lv_table`` 和 ``lv_list``\ 。 + +.. raw:: html + + </p> + +.. raw:: html + + </details> + +Usage +----- + +Enable :c:macro:`LV_USE_FILE_EXPLORER` in ``lv_conf.h``. + +First use :c:expr:`lv_file_explorer_create(lv_scr_act())` to create a file +explorer, The default size is the screen size. After that, you can +customize the style like widget. + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +中文 + +.. raw:: html + + </summary> + +.. raw:: html + + <p> + +在 ``lv_conf.h`` 中打开 :c:macro:`LV_USE_FILE_EXPLORER`\ 。 + +首先，使用 :c:expr:`lv_file_explorer_create(lv_scr_act())` +函数创建一个文件浏览器，默认大小为屏幕大小，之后可以像组件那样自定义样式。 + +.. raw:: html + + </p> + +.. raw:: html + + </details> + +Quick access +~~~~~~~~~~~~ + +The quick access bar is optional. You can turn off +:c:macro:`LV_FILE_EXPLORER_QUICK_ACCESS` in ``lv_conf.h`` so that the quick +access bar will not be created. This can save some memory, but not much. +After the quick access bar is created, it can be hidden by clicking the +button at the top left corner of the browsing area, which is very useful +for small screen devices. + +You can use +:c:expr:`lv_file_explorer_set_quick_access_path(file_explorer, LV_FILE_EXPLORER_QA_XX, "path")` +to set the path of the quick access bar. The items of the quick access +bar are fixed. Currently, there are the following items: + +- :c:enumerator:`LV_FILE_EXPLORER_QA_HOME` +- :c:enumerator:`LV_FILE_EXPLORER_QA_MUSIC` +- :c:enumerator:`LV_FILE_EXPLORER_QA_PICTURES` +- :c:enumerator:`LV_FILE_EXPLORER_QA_VIDEO` +- :c:enumerator:`LV_FILE_EXPLORER_QA_DOCS` +- :c:enumerator:`LV_FILE_EXPLORER_QA_MNT` +- :c:enumerator:`LV_FILE_EXPLORER_QA_FS` + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +中文 + +.. raw:: html + + </summary> + +.. raw:: html + + <p> + +快速访问栏是可选的，您可以在 ``lv_conf.h`` 中关闭 +:c:macro:`LV_FILE_EXPLORER_QUICK_ACCESS`\ ，这样快速访问栏就不会被创建出来，这能节省一些内存，但并不是很多。快速访问栏被创建出来之后，可以通过点击浏览区域顶部左上角的按钮隐藏起来，这对于小屏幕设备非常有用。 + +可以通过 +:c:expr:`lv_file_explorer_set_quick_access_path(file_explorer, LV_FILE_EXPLORER_QA_XX, "path")` +设置快速访问栏的路径，快速访问栏的项目是固定的，目前有以下项目： + +- :c:enumerator:`LV_FILE_EXPLORER_QA_HOME` +- :c:enumerator:`LV_FILE_EXPLORER_QA_MUSIC` +- :c:enumerator:`LV_FILE_EXPLORER_QA_PICTURES` +- :c:enumerator:`LV_FILE_EXPLORER_QA_VIDEO` +- :c:enumerator:`LV_FILE_EXPLORER_QA_DOCS` +- :c:enumerator:`LV_FILE_EXPLORER_QA_MNT` +- :c:enumerator:`LV_FILE_EXPLORER_QA_FS` + +.. raw:: html + + </p> + +.. raw:: html + + </details> + +Sort +~~~~ + +You can use +:c:expr:`lv_file_explorer_set_sort(file_explorer, LV_EXPLORER_SORT_XX)` to set +sorting method. There are the following sorting methods: + +- :c:enumerator:`LV_EXPLORER_SORT_NONE` +- :c:enumerator:`LV_EXPLORER_SORT_KIND` + +You can customize the sorting. Before custom sort, please set the +default sorting to :c:enumerator:`LV_EXPLORER_SORT_NONE`. The default is +:c:enumerator:`LV_EXPLORER_SORT_NONE`. + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +中文 + +.. raw:: html + + </summary> + +.. raw:: html + + <p> + +可以通过 +:c:expr:`lv_file_explorer_set_sort(file_explorer, LV_EXPLORER_SORT_XX)` +设置排序方式，有以下排序方式： + +- :c:enumerator:`LV_EXPLORER_SORT_NONE` +- :c:enumerator:`LV_EXPLORER_SORT_KIND` + +您可以自定义排序规则，在这之前请先将排序规则设置为 +:c:enumerator:`LV_EXPLORER_SORT_NONE` 然后在 :c:enumerator:`LV_EVENT_READY` +事件中处理。默认的排序规则是 :c:enumerator:`LV_EXPLORER_SORT_NONE` + +.. raw:: html + + </p> + +.. raw:: html + + </details> + +Event +----- + +- :c:enumerator:`LV_EVENT_READY` sent shen a directory is opened. You can customize + the sort. + +- :c:enumerator:`LV_EVENT_VALUE_CHANGED` sent when an item(file) in the file list + is clicked. + +You can use :c:func:`lv_file_explorer_get_cur_path` to get the current path +and :c:func:`lv_file_explorer_get_sel_fn` to get the name of the currently +selected file in the event processing function. For example: + +.. code:: c + + static void file_explorer_event_handler(lv_event_t * e) + { + lv_event_code_t code = lv_event_get_code(e); + lv_obj_t * obj = lv_event_get_target(e); + + if(code == LV_EVENT_VALUE_CHANGED) { + char * cur_path = lv_file_explorer_get_cur_path(obj); + char * sel_fn = lv_file_explorer_get_sel_fn(obj); + LV_LOG_USER("%s%s", cur_path, sel_fn); + } + } + +You can also save the obtained **path** and **file** name into an array +through functions such as *strcpy* and *strcat* for later use. + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +中文 + +.. raw:: html + + </summary> + +.. raw:: html + + <p> + +- 当打开一个目录后会发送 :c:enumerator:`LV_EVENT_READY` + 事件。您可以在这里自定义排序规则。 +- 当文件列表中的项目（文件）被点击时会发送 :c:enumerator:`LV_EVENT_VALUE_CHANGED` + 事件。 + +可以在事件处理函数中通过 :c:func:`lv_file_explorer_get_cur_path` +获取当前所在的路径，通过 :c:func:`lv_file_explorer_get_sel_fn` +获取当前选中的文件的名称。比如： + +.. code:: c + + static void file_explorer_event_handler(lv_event_t * e) + { + lv_event_code_t code = lv_event_get_code(e); + lv_obj_t * obj = lv_event_get_target(e); + + if(code == LV_EVENT_VALUE_CHANGED) { + char * cur_path = lv_file_explorer_get_cur_path(obj); + char * sel_fn = lv_file_explorer_get_sel_fn(obj); + LV_LOG_USER("%s%s", cur_path, sel_fn); + } + } + +您还可以将获取到的 **路径** 和 **文件名称** 通过例如 strcpy 和 strcat +函数保存到一个数组中，方便后续使用。 + +.. raw:: html + + </p> + +.. raw:: html + + </details> + +Example +------- + +.. include:: ../examples/others/file_explorer/index.rst + +API +--- + +:ref:`lv_file_explorer` diff --git a/docs/others/fragment.md b/docs/others/fragment.md deleted file mode 100644 index ae909386f..000000000 --- a/docs/others/fragment.md +++ /dev/null @@ -1,77 +0,0 @@ - -# 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/docs/others/fragment.rst b/docs/others/fragment.rst new file mode 100644 index 000000000..29b3eabc2 --- /dev/null +++ b/docs/others/fragment.rst @@ -0,0 +1,80 @@ +======== +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 :c:macro:`LV_USE_FRAGMENT` in ``lv_conf.h``. + +Create Fragment Class +~~~~~~~~~~~~~~~~~~~~~ + +.. code:: 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`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: 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 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: 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 +------- + +.. include:: ../examples/others/fragment/index.rst + +API +--- + +:ref:`lv_fragment` diff --git a/docs/others/gridnav.md b/docs/others/gridnav.md deleted file mode 100644 index 028a50033..000000000 --- a/docs/others/gridnav.md +++ /dev/null @@ -1,56 +0,0 @@ -# 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/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/docs/others/gridnav.rst b/docs/others/gridnav.rst new file mode 100644 index 000000000..ef6eab2e6 --- /dev/null +++ b/docs/others/gridnav.rst @@ -0,0 +1,67 @@ +=============== +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/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 +:c:expr:`LV_KEY_NEXT/PREV` or :c:expr:`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 +:c:expr:`lv_gridnav_add(cont, flags)`. + +``flags`` control the behavior of gridnav: + +- :c:enumerator:`LV_GRIDNAV_CTRL_NONE`: Default settings +- :c:enumerator:`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) +- :c:enumerator:`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 + +:c:expr:`lv_gridnav_remove(cont)` Removes gridnav from an object. + +Focusable objects +----------------- + +An object needs to be clickable or click focusable +(:c:enumerator:`LV_OBJ_FLAG_CLICKABLE` or :c:enumerator:`LV_OBJ_FLAG_CLICK_FOCUSABLE`) and not +hidden (:c:enumerator:`LV_OBJ_FLAG_HIDDEN`) to be focusable by gridnav. + +Example +------- + +.. include:: ../examples/others/gridnav/index.rst + +API +--- + +:ref:`lv_gridnav` diff --git a/docs/others/ime_pinyin.md b/docs/others/ime_pinyin.md deleted file mode 100644 index f18a1303a..000000000 --- a/docs/others/ime_pinyin.md +++ /dev/null @@ -1,166 +0,0 @@ -# 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/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/keyboard)组件提供汉语拼音输入法（中文输入）的功能(后文简称为拼音输入法)，支持26键和9键输入模式。您可以将 `lv_ime_pinyin` 看成是键盘组件的汉语拼音输入法插件。 - -一般情况下，只要是[键盘](/widgets/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); -``` - -## Modes - -The lv_ime_pinyin have the following modes: - -- `LV_IME_PINYIN_MODE_K26` Pinyin 26 key input mode -- `LV_IME_PINYIN_MODE_K9` Pinyin 9 key input mode -- `LV_IME_PINYIN_MODE_K9_NUMBER` Numeric keypad mode - -The `TEXT` modes' layout contains buttons to change mode. - -To set the mode manually, use `lv_ime_pinyin_set_mode(pinyin_ime, mode)` . The default mode is `LV_IME_PINYIN_MODE_K26` . - -<details> -<summary>中文</summary> -<p> - -lv_ime_pinyin 有以下模式： - -- `LV_IME_PINYIN_MODE_K26` 拼音26键 -- `LV_IME_PINYIN_MODE_K9` 拼音9键(九宫格) -- `LV_IME_PINYIN_MODE_K9_NUMBER` 九宫格布局的数字键盘 - -每个模式的布局中都包含有更改到其他模式的按钮。 - -您可以通过 `lv_keyboard_set_mode(kb, mode)` 函数手动设置模式。默认的模式是 `LV_IME_PINYIN_MODE_K26` 。 - -</p> -</details> - - -## Example - -```eval_rst - -.. include:: ../../examples/others/ime/index.rst - -``` - -## API - -```eval_rst - -.. doxygenfile:: lv_ime_pinyin.h - :project: lvgl - -``` diff --git a/docs/others/ime_pinyin.rst b/docs/others/ime_pinyin.rst new file mode 100644 index 000000000..0c4ae17eb --- /dev/null +++ b/docs/others/ime_pinyin.rst @@ -0,0 +1,314 @@ +========== +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/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. + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +中文 + +.. raw:: html + + </summary> + +.. raw:: html + + <p> + +``lv_ime_pinyin``\ 为\ `键盘 </widgets/keyboard>`__\ 组件提供汉语拼音输入法（中文输入）的功能(后文简称为拼音输入法)，支持26键和9键输入模式。您可以将 +``lv_ime_pinyin`` 看成是键盘组件的汉语拼音输入法插件。 + +一般情况下，只要是\ `键盘 </widgets/keyboard>`__\ 组件能运行的环境 +``lv_ime_pinyin`` 也能运行。有两个影响因素：字库的大小和词库的大小。 + +.. raw:: html + + </p> + +.. raw:: html + + </details> + +Usage +----- + +Enable :c:macro:`LV_USE_IME_PINYIN` in ``lv_conf.h``. + +First use :c:expr:`lv_ime_pinyin_create(lv_scr_act())` to create a Pinyin +input method plug-in, then use +:c:expr:`lv_ime_pinyin_set_keyboard(pinyin_ime, kb)` to add the ``keyboard`` +you created to the Pinyin input method plug-in. You can use +:c:expr:`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 :c:macro:`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. + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +中文 + +.. raw:: html + + </summary> + +.. raw:: html + + <p> + +在 ``lv_conf.h`` 中打开 :c:macro:`LV_USE_IME_PINYIN`\ 。 + +首先，使用 :c:expr:`lv_ime_pinyin_create(lv_scr_act())` +函数创建一个拼音输入法插件， 然后使用 +:c:expr:`lv_ime_pinyin_set_keyboard(pinyin_ime, kb)` +函数将您创建的键盘组件添加到插件中。 + +内置的词库是基于 LVGL 的 **LV_FONT_SIMSUN_16_CJK** +字库定制，这个字库目前只有 ``1000`` 多个最常见的 CJK +部首，所以建议使用自定义字库和词库。 + +您可以使用 :c:expr:`lv_ime_pinyin_set_dict(pinyin_ime, your_dict)` +函数来设置使用自定义的词库，如果您一开始就不打算使用内置的词库，建议您在 +``lv_conf.h`` 中将 :c:macro:`LV_IME_PINYIN_USE_DEFAULT_DICT` +关闭，这可以节省一些内存空间。 + +.. raw:: html + + </p> + +.. raw:: html + + </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 :c:macro:`LV_IME_PINYIN_USE_DEFAULT_DICT` to ``0`` in ``lv_conf.h`` + +Then, write a dictionary in the following format. + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +中文 + +.. raw:: html + + </summary> + +.. raw:: html + + <p> + +如果您不想使用内置的词库，可以通过下面的方法自定义词库。 + +自定义词典非常简单。 首先，在 ``lv_conf.h`` 将 +:c:macro:`LV_IME_PINYIN_USE_DEFAULT_DICT` 设置为 0。 +然后按照下面的格式编写词库。 + +.. raw:: html + + </p> + +.. raw:: html + + </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: + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +中文 + +.. raw:: html + + </summary> + +.. raw:: html + + <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>`__\ 。 + +然后，根据下面的格式编写自己的词库： + +.. raw:: html + + </p> + +.. raw:: html + + </details> + +.. code:: 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: + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +中文 + +.. raw:: html + + </summary> + +.. raw:: html + + <p> + +按照上面的词库格式编写好自己的词库之后，参考下面的用法，调用 +:c:expr:`lv_100ask_pinyin_ime_set_dict(pinyin_ime, your_pinyin_dict)` +函数即可设置和使用新词库： + +.. raw:: html + + </p> + +.. raw:: html + + </details> + +.. code:: 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); + +Modes +----- + +The lv_ime_pinyin have the following modes: + +- :c:enumerator:`LV_IME_PINYIN_MODE_K26`: Pinyin 26 key input mode +- :c:enumerator:`LV_IME_PINYIN_MODE_K9`: Pinyin 9 key input mode +- :c:enumerator:`LV_IME_PINYIN_MODE_K9_NUMBER`: Numeric keypad mode + +The ``TEXT`` modes’ layout contains buttons to change mode. + +To set the mode manually, use +:c:expr:`lv_ime_pinyin_set_mode(pinyin_ime, mode)` . The default mode is +:c:enumerator:`LV_IME_PINYIN_MODE_K26` . + +.. raw:: html + + <details> + +.. raw:: html + + <summary> + +中文 + +.. raw:: html + + </summary> + +.. raw:: html + + <p> + +lv_ime_pinyin 有以下模式： + +- :c:enumerator:`LV_IME_PINYIN_MODE_K26`: 拼音26键 +- :c:enumerator:`LV_IME_PINYIN_MODE_K9`: 拼音9键(九宫格) +- :c:enumerator:`LV_IME_PINYIN_MODE_K9_NUMBER`: 九宫格布局的数字键盘 + +每个模式的布局中都包含有更改到其他模式的按钮。 + +您可以通过 :c:expr:`lv_keyboard_set_mode(kb, mode)` +函数手动设置模式。默认的模式是 :c:enumerator:`LV_IME_PINYIN_MODE_K26` 。 + +.. raw:: html + + </p> + +.. raw:: html + + </details> + +Example +------- + +.. include:: ../examples/others/ime/index.rst + +API +--- + +:ref:`lv_ime_pinyin` diff --git a/docs/others/imgfont.md b/docs/others/imgfont.md deleted file mode 100644 index 0f0f09941..000000000 --- a/docs/others/imgfont.md +++ /dev/null @@ -1,25 +0,0 @@ -# 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/docs/others/imgfont.rst b/docs/others/imgfont.rst new file mode 100644 index 000000000..11d38a370 --- /dev/null +++ b/docs/others/imgfont.rst @@ -0,0 +1,30 @@ +==================== +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 :c:macro:`LV_USE_IMGFONT` in ``lv_conf.h``. + +To create a new imgfont use :c:expr:`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 :c:expr:`lv_imgfont_destroy(imgfont)` to destroy a imgfont that is no +longer used. + +Example +------- + +.. include:: ../examples/others/imgfont/index.rst + +API +--- + +:ref:`lv_imgfont` diff --git a/docs/others/index.md b/docs/others/index.md deleted file mode 100644 index b9518ee72..000000000 --- a/docs/others/index.md +++ /dev/null @@ -1,18 +0,0 @@ -# Others - - -```eval_rst - -.. toctree:: - :maxdepth: 1 - - snapshot - monkey - gridnav - file_explorer - fragment - msg - imgfont - ime_pinyin -``` - diff --git a/docs/others/index.rst b/docs/others/index.rst new file mode 100644 index 000000000..e106ee4cb --- /dev/null +++ b/docs/others/index.rst @@ -0,0 +1,15 @@ +====== +Others +====== + +.. toctree:: + :maxdepth: 1 + + snapshot + monkey + gridnav + file_explorer + fragment + msg + imgfont + ime_pinyin diff --git a/docs/others/monkey.md b/docs/others/monkey.md deleted file mode 100644 index f230d581e..000000000 --- a/docs/others/monkey.md +++ /dev/null @@ -1,35 +0,0 @@ -# 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/docs/others/monkey.rst b/docs/others/monkey.rst new file mode 100644 index 000000000..ee85e1c3d --- /dev/null +++ b/docs/others/monkey.rst @@ -0,0 +1,40 @@ +====== +Monkey +====== + +A simple monkey test. Use random input to stress test the application. + +Usage +----- + +Enable :c:macro:`LV_USE_MONKEY` in ``lv_conf.h``. + +First configure monkey, use :c:struct:`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 +:c:func:`lv_monkey_create` to create monkey. Finally call +:c:expr:`lv_monkey_set_enable(monkey, true)` to enable monkey. + +If you want to pause the monkey, call +:c:expr:`lv_monkey_set_enable(monkey, false)`. To delete the monkey, call +:c:expr:`lv_monkey_del(monkey)`. + +Note that ``input_range`` has different meanings in different ``type``: + +- :c:enumerator:`LV_INDEV_TYPE_POINTER`: No effect, click randomly within the pixels of the screen resolution. +- :c:enumerator:`LV_INDEV_TYPE_ENCODER`: The minimum and maximum values of ``enc_diff``. +- :c:enumerator:`LV_INDEV_TYPE_BUTTON`: The minimum and maximum values of ``btn_id``. + Use :c:expr:`lv_monkey_get_indev()` to get the input device, and use + :c:expr:`lv_indev_set_button_points()` to map the key ID to the coordinates. +- :c:enumerator:`LV_INDEV_TYPE_KEYPAD`: No effect, Send random :ref:`indev_keys`. + +Example +------- + +.. include:: ../examples/others/monkey/index.rst + +API +--- + +:ref:`lv_monkey` diff --git a/docs/others/msg.md b/docs/others/msg.md deleted file mode 100644 index ce0f01a6c..000000000 --- a/docs/others/msg.md +++ /dev/null @@ -1,125 +0,0 @@ -# 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 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 organize the message IDs as you wish. - -Both parties also need to know about the format of the payload. E.g. in the above example -`MSG_DOOR_OPENED` and `MSG_DOOR_CLOSED` might have 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. - -To be more precise the message ID's type is declared like this: -```c -typedef lv_uintptr_t lv_msg_id_t; -``` - -This way, if a value in stored in a global variable (e.g. the current temperature) then the address of that variable can be used as message ID too by simply casting it to `lv_msg_id_t`. It saves the creation of message IDs manually as the variable itself serves as message ID too. - - -## Subscribe to a message - -`lv_msg_subscribe(msg_id, callback, user_data)` can be used to subscribe to message. - - -Don't forget that `msg_id` can be a constant or a variable address too: -```c -lv_msg_subscribe(45, my_callback_1, NULL); - -int v; -lv_msg_subscribe((lv_msg_id_t)&v, my_callback_2, NULL); -``` - -The callback should look like this: -```c - -static void user_name_subscriber_cb(lv_msg_t * m) -{ - /*m: a message object with the msg_id, payload, and user_data (set during 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(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)); -} - -``` - -Here `msg_id` also can be a variable's address: -```c -char name[64]; -lv_msg_subsribe_obj(name, user_name_label, NULL); -``` - -### 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); -``` - -## 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"); -``` - -If have subscribed to a variable with `lv_msg_subscribe((lv_msg_id_t)&v, callback, NULL)` and changed the variable's value the subscribers can be notified like this: -```c -v = 10; -lv_msg_update_value(&v); //Notify all the subscribers of `(lv_msg_id_t)&v` -``` -It's handy way of creating API for the UI too. If the UI provides some global variables (e.g. `int current_tempereature;`) and anyone can read and write this variable. After writing they can notify all the elements who are interested in that value. E.g. an `lv_label` can subscribe to `(lv_msg_id_t)¤t_tempereature` and update its text when it's notified about the new temperature. - -## Example - -```eval_rst - -.. include:: ../../examples/others/msg/index.rst - -``` -## API - - -```eval_rst - -.. doxygenfile:: lv_msg.h - :project: lvgl - -``` diff --git a/docs/others/msg.rst b/docs/others/msg.rst new file mode 100644 index 000000000..99a33ac88 --- /dev/null +++ b/docs/others/msg.rst @@ -0,0 +1,153 @@ +========= +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 integers. For example: + +.. code:: 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 organize the message IDs as you wish. + +Both parties also need to know about the format of the payload. E.g. in +the above example :c:enumerator:`MSG_DOOR_OPENED` and :c:enumerator:`MSG_DOOR_CLOSED` might have +no payload but :c:enumerator:`MSG_USER_NAME_CHANGED` can have a :c:expr:`const char *` +payload containing the user name, and :c:enumerator:`MSG_USER_AVATAR_CHANGED` a +:c:expr:`const void *` image source with the new avatar image. + +To be more precise the message ID’s type is declared like this: + +.. code:: c + + typedef lv_uintptr_t lv_msg_id_t; + +This way, if a value in stored in a global variable (e.g. the current +temperature) then the address of that variable can be used as message ID +too by simply casting it to :c:type:`lv_msg_id_t`. It saves the creation of +message IDs manually as the variable itself serves as message ID too. + +Subscribe to a message +---------------------- + +:c:expr:`lv_msg_subscribe(msg_id, callback, user_data)` can be used to +subscribe to message. + +Don’t forget that ``msg_id`` can be a constant or a variable address +too: + +.. code:: c + + lv_msg_subscribe(45, my_callback_1, NULL); + + int v; + lv_msg_subscribe((lv_msg_id_t)&v, my_callback_2, NULL); + +The callback should look like this: + +.. code:: c + + + static void user_name_subscriber_cb(lv_msg_t * m) + { + /*m: a message object with the msg_id, payload, and user_data (set during subscription)*/ + + ...do something... + } + +From :c:struct:`lv_msg_t` the followings can be used to get some data: + +- :c:expr:`lv_msg_get_id(m)` +- :c:expr:`lv_msg_get_payload(m)` +- :c:expr:`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 :c:expr:`lv_msg_subsribe_obj(msg_id, obj, user_data)` can +be used. If a new message is published with ``msg_id`` an +:c:enumerator:`LV_EVENT_MSG_RECEIVED` event will be sent to the object. + +For example: + +.. code:: c + + lv_obj_add_event(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)); + } + +Here ``msg_id`` also can be a variable’s address: + +.. code:: c + + char name[64]; + lv_msg_subsribe_obj(name, user_name_label, NULL); + +Unsubscribe +~~~~~~~~~~~ + +:c:func:`lv_msg_subscribe` returns a pointer which can be used to unsubscribe: + +.. code:: c + + void * s1; + s1 = lv_msg_subscribe(MSG_USER_DOOR_OPENED, some_callback, NULL); + + ... + + lv_msg_unsubscribe(s1); + +Send message +------------ + +Messages can be sent with :c:expr:`lv_msg_send(msg_id, payload)`. E.g. + +.. code:: c + + lv_msg_send(MSG_USER_DOOR_OPENED, NULL); + lv_msg_send(MSG_USER_NAME_CHANGED, "John Smith"); + +If have subscribed to a variable with +:c:expr:`lv_msg_subscribe((lv_msg_id_t)&v, callback, NULL)` and changed the +variable’s value the subscribers can be notified like this: + +.. code:: c + + v = 10; + lv_msg_update_value(&v); //Notify all the subscribers of `(lv_msg_id_t)&v` + +It’s handy way of creating API for the UI too. If the UI provides some +global variables (e.g. ``int current_tempereature``) and anyone can +read and write this variable. After writing they can notify all the +elements who are interested in that value. E.g. an ``lv_label`` can +subscribe to :c:expr:`(lv_msg_id_t)¤t_tempereature` and update its text +when it’s notified about the new temperature. + +Example +------- + +.. include:: ../examples/others/msg/index.rst + +API +--- + +:ref:`lv_msg` diff --git a/docs/others/snapshot.md b/docs/others/snapshot.md deleted file mode 100644 index 69c7fe615..000000000 --- a/docs/others/snapshot.md +++ /dev/null @@ -1,60 +0,0 @@ -# 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 - - LV_IMG_CF_TRUE_COLOR_ALPHA - - 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/docs/others/snapshot.rst b/docs/others/snapshot.rst new file mode 100644 index 000000000..715843da3 --- /dev/null +++ b/docs/others/snapshot.rst @@ -0,0 +1,66 @@ +======== +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 :c:func:`lv_snapshot_take` to generate the image descriptor +which can be set as image object src using :c:func:`lv_img_set_src`. + +Note, only below color formats are supported for now: - +LV_IMG_CF_TRUE_COLOR - LV_IMG_CF_TRUE_COLOR_ALPHA - LV_IMG_CF_ALPHA_8BIT + +Free the Image +~~~~~~~~~~~~~~ + +The memory :c:func:`lv_snapshot_take` uses are dynamically allocated using +:c:func:`lv_mem_alloc`. Use API :c:func:`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 :c:expr:`lv_img_set_src(NULL)` and :c:expr:`lv_img_cache_invalidate_src(src)`. + +Below code snippet explains usage of this API. + +.. code:: 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 +:c:func:`lv_snapshot_buf_size_needed` to check the needed buffer size in byte +firstly and resize the buffer accordingly. + +Example +------- + +.. include:: ../examples/others/snapshot/index.rst + +API +--- + +:ref:`lv_snapshot` diff --git a/docs/overview/anim.rst b/docs/overview/anim.rst new file mode 100644 index 000000000..c8ebd5da8 --- /dev/null +++ b/docs/overview/anim.rst @@ -0,0 +1,173 @@ +========== +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: + +.. code:: 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 :cpp:expr:`lv_obj_set_x(obj, value)` or +:cpp:expr:`lv_obj_set_width(obj, value)` + +Create an animation +******************* + +To create an animation an :cpp:type:`lv_anim_t` variable has to be initialized +and configured with ``lv_anim_set_...()`` functions. + +.. code:: 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 +:cpp:func:`lv_obj_set_x` and :cpp:func:`lv_obj_set_y`. However, only one animation can +exist with a given variable and function pair and :cpp:func:`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: + +- :cpp:func:`lv_anim_path_linear`: linear animation +- :cpp:func:`lv_anim_path_step`: change in one step at the end +- :cpp:func:`lv_anim_path_ease_in`: slow at the beginning +- :cpp:func:`lv_anim_path_ease_out`: slow at the end +- :cpp:func:`lv_anim_path_ease_in_out`: slow at the beginning and end +- :cpp:func:`lv_anim_path_overshoot`: overshoot the end value +- :cpp:func:`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 :cpp:expr:`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, :cpp:expr:`lv_anim_speed_to_time(20, 0, 100)` will yield 5000 +milliseconds. For example, in the case of :cpp:func:`lv_obj_set_x` *unit* is +pixels so *20* means *20 px/sec* speed. + +Delete animations +***************** + +You can delete an animation with :cpp:expr:`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 :cpp:func:`lv_anim_start`. + +Secondly, create an animation timeline object by calling +:cpp:func:`lv_anim_timeline_create`. + +Thirdly, add animation elements to the animation timeline by calling +:cpp:expr:`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 :cpp:expr:`lv_anim_timeline_start(at)` to start the animation +timeline. + +It supports forward and backward playback of the entire animation group, +using :cpp:expr:`lv_anim_timeline_set_reverse(at, reverse)`. + +Call :cpp:expr:`lv_anim_timeline_stop(at)` to stop the animation timeline. + +Call :cpp:expr:`lv_anim_timeline_set_progress(at, progress)` function to set the +state of the object corresponding to the progress of the timeline. + +Call :cpp:expr:`lv_anim_timeline_get_playtime(at)` function to get the total +duration of the entire animation timeline. + +Call :cpp:expr:`lv_anim_timeline_get_reverse(at)` function to get whether to +reverse the animation timeline. + +Call :cpp:expr:`lv_anim_timeline_del(at)` function to delete the animation +timeline. + +.. image:: /misc/anim-timeline.png + +Examples +******** + +.. include:: ../examples/anim/index.rst + +API +*** diff --git a/docs/overview/animation.md b/docs/overview/animation.md deleted file mode 100644 index d4800e650..000000000 --- a/docs/overview/animation.md +++ /dev/null @@ -1,144 +0,0 @@ -# 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/docs/overview/color.md b/docs/overview/color.md deleted file mode 100644 index b988b9def..000000000 --- a/docs/overview/color.md +++ /dev/null @@ -1,151 +0,0 @@ -# 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) - -## 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/docs/overview/color.rst b/docs/overview/color.rst new file mode 100644 index 000000000..662cfd91e --- /dev/null +++ b/docs/overview/color.rst @@ -0,0 +1,187 @@ +====== +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 :cpp:type:`lv_color_t` is used to store a color. Its fields are set +according to :c:macro:`LV_COLOR_DEPTH` in ``lv_conf.h``. (See below) + +Creating colors +*************** + +RGB +--- + +Create colors from Red, Green and Blue channel values: + +.. code:: 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: + +.. code:: 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: + +- :c:macro:`LV_PALETTE_RED` +- :c:macro:`LV_PALETTE_PINK` +- :c:macro:`LV_PALETTE_PURPLE` +- :c:macro:`LV_PALETTE_DEEP_PURPLE` +- :c:macro:`LV_PALETTE_INDIGO` +- :c:macro:`LV_PALETTE_BLUE` +- :c:macro:`LV_PALETTE_LIGHT_BLUE` +- :c:macro:`LV_PALETTE_CYAN` +- :c:macro:`LV_PALETTE_TEAL` +- :c:macro:`LV_PALETTE_GREEN` +- :c:macro:`LV_PALETTE_LIGHT_GREEN` +- :c:macro:`LV_PALETTE_LIME` +- :c:macro:`LV_PALETTE_YELLOW` +- :c:macro:`LV_PALETTE_AMBER` +- :c:macro:`LV_PALETTE_ORANGE` +- :c:macro:`LV_PALETTE_DEEP_ORANGE` +- :c:macro:`LV_PALETTE_BROWN` +- :c:macro:`LV_PALETTE_BLUE_GREY` +- :c:macro:`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: + +.. code:: 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 +--------------- + +:cpp:func:`lv_color_white` and :cpp:func:`lv_color_black` return ``0xFFFFFF`` and +``0x000000`` respectively. + +Opacity +******* + +To describe opacity the :cpp:var:`lv_opa_t` type is created from ``uint8_t``. +Some special purpose defines are also introduced: + +- :cpp:enumerator:`LV_OPA_TRANSP` Value: 0, means no opacity making the color + completely transparent +- :cpp:enumerator:`LV_OPA_10` Value: 25, means the color covers only a little +- ``LV_OPA_20 ... OPA_80`` follow logically +- :cpp:enumerator:`LV_OPA_90` Value: 229, means the color near completely covers +- :cpp:enumerator:`LV_OPA_COVER` Value: 255, means the color completely covers (full + opacity) + +You can also use the ``LV_OPA_*`` defines in :cpp:func:`lv_color_mix` as a +mixing *ratio*. + +Color types +*********** + +The following variable types are defined by the color module: + +- :cpp:union:`lv_color1_t` Monochrome color. Also has R, G, B fields for + compatibility but they are always the same value (1 byte) +- :cpp:union:`lv_color8_t` A structure to store R (3 bit),G (3 bit),B (2 bit) + components for 8-bit colors (1 byte) +- :cpp:class:`lv_color16_t` A structure to store R (5 bit),G (6 bit),B (5 bit) + components for 16-bit colors (2 byte) +- :cpp:class:`lv_color32_t` A structure to store R (8 bit),G (8 bit), B (8 bit) + components for 24-bit colors (4 byte) +- :cpp:type:`lv_color_t` Equal to ``lv_color1/8/16/24_t`` depending on the + configured color depth setting +- :cpp:type:`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. +- :cpp:var:`lv_opa_t` A simple ``uint8_t`` type to describe opacity. + +The :cpp:type:`lv_color_t`, :cpp:union:`lv_color1_t`, :cpp:union:`lv_color8_t`, :cpp:class:`lv_color16_t` +and :cpp:class:`lv_color32_t` types have four fields: + +- :cpp:member:`red` red channel +- :cpp:member:`green` green channel +- :cpp:member:`blue` blue channel +- :cpp:member:`full` red + green + blue as one number + +You can set the current color depth in *lv_conf.h*, by setting the +:c:macro:`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 +:cpp:member:`full` field to map a converted color back into a structure: + +.. code:: 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 +*** diff --git a/docs/overview/coord.rst b/docs/overview/coord.rst new file mode 100644 index 000000000..901a7f508 --- /dev/null +++ b/docs/overview/coord.rst @@ -0,0 +1,501 @@ +============================= +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. :cpp:expr:`lv_obj_set_x(btn, 10)` +- percentage: The percentage of the size of the object or its parent + (depending on the property). :cpp:expr:`lv_pct(value)` converts a value to + percentage. E.g. :cpp:expr:`lv_obj_set_width(btn, lv_pct(50))` +- :c:macro:`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. :cpp:expr:`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. + +.. image:: /misc/boxmodel.png + :alt: The box models of LVGL: The content area is smaller than the bounding box with the padding and border width + +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 :cpp:func:`lv_obj_update_layout`. + +The size and position might depend on the parent or layout. Therefore +:cpp:func:`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 :cpp:expr:`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 + +.. code:: c + + lv_obj_remove_style_all(obj) + +or + +.. code:: c + + lv_obj_remove_style(obj, NULL, LV_PART_MAIN); + +the earlier set coordinates will be removed as well. + +For example: + +.. code:: 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: + +.. code:: 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. + +.. code:: 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: + +.. code:: c + + lv_obj_set_align(obj, align); + +To change the alignment and set new coordinates: + +.. code:: c + + lv_obj_align(obj, align, x, y); + +The following alignment options can be used: + +- :cpp:enumerator:`LV_ALIGN_TOP_LEFT` +- :cpp:enumerator:`LV_ALIGN_TOP_MID` +- :cpp:enumerator:`LV_ALIGN_TOP_RIGHT` +- :cpp:enumerator:`LV_ALIGN_BOTTOM_LEFT` +- :cpp:enumerator:`LV_ALIGN_BOTTOM_MID` +- :cpp:enumerator:`LV_ALIGN_BOTTOM_RIGHT` +- :cpp:enumerator:`LV_ALIGN_LEFT_MID` +- :cpp:enumerator:`LV_ALIGN_RIGHT_MID` +- :cpp:enumerator:`LV_ALIGN_CENTER` + +It's quite common to align a child to the center of its parent, +therefore a dedicated function exists: + +.. code:: 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. + +.. code:: 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: + +- :cpp:enumerator:`LV_ALIGN_OUT_TOP_LEFT` +- :cpp:enumerator:`LV_ALIGN_OUT_TOP_MID` +- :cpp:enumerator:`LV_ALIGN_OUT_TOP_RIGHT` +- :cpp:enumerator:`LV_ALIGN_OUT_BOTTOM_LEFT` +- :cpp:enumerator:`LV_ALIGN_OUT_BOTTOM_MID` +- :cpp:enumerator:`LV_ALIGN_OUT_BOTTOM_RIGHT` +- :cpp:enumerator:`LV_ALIGN_OUT_LEFT_TOP` +- :cpp:enumerator:`LV_ALIGN_OUT_LEFT_MID` +- :cpp:enumerator:`LV_ALIGN_OUT_LEFT_BOTTOM` +- :cpp:enumerator:`LV_ALIGN_OUT_RIGHT_TOP` +- :cpp:enumerator:`LV_ALIGN_OUT_RIGHT_MID` +- :cpp:enumerator:`LV_ALIGN_OUT_RIGHT_BOTTOM` + +For example to align a label above a button and center the label +horizontally: + +.. code:: c + + lv_obj_align_to(label, btn, LV_ALIGN_OUT_TOP_MID, 0, -10); + +Note that, unlike with :cpp:func:`lv_obj_align`, :cpp:func:`lv_obj_align_to` can not +realign the object if its coordinates or the reference object's +coordinates change. + +Size +**** + +Sizing the Simple way +--------------------- + +The width and the height of an object can be set easily as well: + +.. code:: 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: + +.. code:: c + + lv_obj_set_height(obj, lv_pct(100)); + +The size settings support a special value: :c:macro:`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 :cpp:enumerator:`LV_OBJ_FLAG_HIDDEN` or :cpp:enumerator:`LV_OBJ_FLAG_FLOATING` will be +ignored by the :c:macro:`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. + +.. code:: 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: + +.. code:: 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 :cpp:enumerator:`LV_STATE_DEFAULT` but 120 px + in :cpp:enumerator:`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: + +.. code:: 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: + +.. code:: 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: + +.. code:: 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 :cpp:expr:`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 :c:macro:`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 +:c:macro:`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: + +.. code:: 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 +:c:macro:`LV_SIZE_CONTENT`. + +.. code:: 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. + +.. code:: 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 +****** + +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: +:cpp:func:`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: + +- :cpp:enumerator:`LV_OBJ_FLAG_HIDDEN` Hidden objects are ignored in layout calculations. +- :cpp:enumerator:`LV_OBJ_FLAG_IGNORE_LAYOUT` The object is simply ignored by the layouts. Its coordinates can be set as usual. +- :cpp:enumerator:`LV_OBJ_FLAG_FLOATING` Same as :cpp:enumerator:`LV_OBJ_FLAG_IGNORE_LAYOUT` but the object with :cpp:enumerator:`LV_OBJ_FLAG_FLOATING` will be ignored in :c:macro:`LV_SIZE_CONTENT` calculations. + +These flags can be added/removed with :cpp:expr:`lv_obj_add_flag(obj, FLAG)` and :cpp:expr:`lv_obj_clear_flag(obj, FLAG)` + +Adding new layouts +------------------ + +LVGL can be freely extended by a custom layout like this: + +.. code:: 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: + +.. code:: 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 +******** + +API +*** diff --git a/docs/overview/coords.md b/docs/overview/coords.md deleted file mode 100644 index 5d56750de..000000000 --- a/docs/overview/coords.md +++ /dev/null @@ -1,363 +0,0 @@ -# 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/docs/overview/disp.rst b/docs/overview/disp.rst new file mode 100644 index 000000000..08ee7e7e4 --- /dev/null +++ b/docs/overview/disp.rst @@ -0,0 +1,165 @@ +======== +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 :c:macro:`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 +:cpp:expr:`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. + +:cpp:func:`lv_scr_act`, :cpp:func:`lv_scr_load`, :cpp:func:`lv_layer_top`, +:cpp:func:`lv_layer_sys`, :c:macro:`LV_HOR_RES` and :c:macro:`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. :cpp:expr:`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 +``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 ``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. :cpp:expr:`lv_obj_set_pos()`, :cpp:expr:`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/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 :cpp:expr:`lv_scr_load(scr)`. To get the active screen, +use :cpp:expr:`lv_scr_act()`. These functions work on the default display. If +you want to specify which display to work on, use +:cpp:expr:`lv_disp_get_scr_act(disp)` and :cpp:expr:`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 :cpp:expr:`lv_obj_del(scr)`, but ensure that you do +not delete the currently loaded screen. + +Transparent screens +------------------- + +Usually, the opacity of the screen is :cpp:enumerator:`LV_OPA_COVER` to provide a +solid background for its children. If this is not the case (opacity < +100%) the display’s ``bottom_layer`` be visible. If the bottom layer’s +opacity is also not :cpp:enumerator:`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 overlaid on an upper layer. + +To properly render the screen the display’s color format needs to be set +to one with alpha channel. + +In summary, to enable transparent screens and displays for OSD menu-like +UIs: + +- Set the screen’s ``bg_opa`` to transparent: + :cpp:expr:`lv_obj_set_style_bg_opa(lv_scr_act(), LV_OPA_TRANSP, 0)` +- Set the bottom layer’s ``bg_opa`` to transparent: + :cpp:expr:`lv_obj_set_style_bg_opa(lv_scr_act(), LV_OPA_TRANSP, 0)` +- Set the screen’s bg_opa to 0: + :cpp:expr:`lv_obj_set_style_bg_opa(lv_layer_bottom(), LV_OPA_TRANSP, 0)` +- Set a color format with alpha channel. E.g. + :cpp:expr:`lv_disp_set_color_format(disp, LV_COLOR_FORMAT_NATIVE_ALPHA)` + +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 +:cpp:expr:`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 +:cpp:expr:`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 :cpp:expr:`lv_obj_set_style_bg_color(obj, color)`; + +The display background image is a path to a file or a pointer to an +:cpp:struct:`lv_img_dsc_t` variable (converted image data) to be used as +wallpaper. It can be set with :cpp:expr:`lv_obj_set_style_bg_img_src(obj, &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 +:cpp:expr:`lv_obj_set_style_bg_opa(obj, opa)`. + +The ``disp`` parameter of these functions can be ``NULL`` to select the +default display. + +API +*** diff --git a/docs/overview/display.md b/docs/overview/display.md deleted file mode 100644 index 9c7a0cc57..000000000 --- a/docs/overview/display.md +++ /dev/null @@ -1,102 +0,0 @@ -# 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)). - -### Duplicate display - -To duplicate the image of a display to another display, you don't need to the use multi-display support. Just transfer the buffer received in `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 `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/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 `bottom_layer` will be visible. -If the bottom layer's 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 overlaid on an upper layer. - -To properly render the screen the display's color format needs to be set to one with alpha channel. - -In summary, to enable transparent screens and displays for OSD menu-like UIs: -- Set the screen's `bg_opa` to transparent: `lv_obj_set_style_local_bg_opa(lv_scr_act(), LV_OPA_TRANSP, 0)` -- Set the bottom layer's `bg_opa` to transparent: `lv_obj_set_style_local_bg_opa(lv_bottom_layer(), LV_OPA_TRANSP, 0)` -- Set a color format with alpha channel. E.g. `lv_disp_set_color_format(disp, LV_COLOR_FORMAT_NATIVE_ALPHA)` - -## 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/docs/overview/draw.rst b/docs/overview/draw.rst new file mode 100644 index 000000000..5eb0620ce --- /dev/null +++ b/docs/overview/draw.rst @@ -0,0 +1,363 @@ +.. _drawing: + +======= +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 :c:macro:`LV_DEF_REFR_PERIOD` (set in ``lv_hal_disp.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 :cpp:func:`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. :cpp:struct:`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. :cpp:func:`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: + +- :cpp:enumerator:`LV_DRAW_MASK_TYPE_LINE`: Removes a side from a + line (top, bottom, left or right). :cpp:func:`lv_draw_line` uses four instances + of it. Essentially, every (skew) line is bounded with four line masks + forming a rectangle. +- :cpp:enumerator:`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 + (:c:macro:`LV_RADIUS_CIRCLE`) +- :cpp:enumerator:`LV_DRAW_MASK_TYPE_ANGLE`: Removes a circular + sector. It is used by :cpp:func:`lv_draw_arc` to remove the "empty" sector. +- :cpp:enumerator:`LV_DRAW_MASK_TYPE_FADE`: Create a vertical fade (change opacity) +- :cpp:enumerator:`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: + +- :cpp:type:`lv_draw_mask_line_param_t` +- :cpp:type:`lv_draw_mask_radius_param_t` +- :cpp:type:`lv_draw_mask_angle_param_t` +- :cpp:type:`lv_draw_mask_fade_param_t` +- :cpp:type:`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 =`` :cpp:expr:`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 + :cpp:expr:`lv_draw_mask_remove_id(mask_id)` or + :cpp:expr:`lv_draw_mask_remove_custom(ptr)`. +5. Free the parameter with :cpp:expr:`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. + +:cpp:func:`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/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. + +:cpp:expr:`lv_event_get_draw_ctx(event)` can be used to get the current draw ctx +and in that structure is the 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 +:cpp:enumerator:`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. + +:cpp:expr:`lv_event_get_draw_ctx(event)` can be used to get the current draw ctx +and in that structure is the clip area. The clip area is required in draw functions to make them draw only +on a limited 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 +:cpp:enumerator:`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 :cpp:struct:`lv_obj_draw_part_dsc_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. + +:cpp:struct:`lv_obj_draw_part_dsc_t` has the following fields: + +.. code:: c + + typedef struct { + lv_draw_ctx_t * draw_ctx; /**< Draw context*/ + const struct _lv_obj_class_t * class_p; /**< The class that sent the event */ + uint32_t type; /**< The type if part being draw. Element of `lv_<name>_draw_part_type_t` */ + lv_area_t * draw_area; /**< The area of the part being drawn*/ + 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*/ + const lv_point_t * + p1; /**< A point calculated during drawing. E.g. a point of chart or the center of an arc.*/ + const lv_point_t * p2; /**< A point calculated during drawing. E.g. a point of chart.*/ + char * text; /**< A text calculated during drawing. Can be modified. E.g. tick labels on a chart axis.*/ + uint32_t text_length; /**< Size of the text buffer containing null-terminated text string calculated during drawing.*/ + 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.*/ + 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_obj_draw_part_dsc_t; + +:cpp:expr:`lv_event_get_draw_part_dsc(event)` can be used to get a pointer to +:cpp:struct:`lv_obj_draw_part_dsc_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 :cpp:enumerator:`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. + +:cpp:expr:`lv_event_get_cover_area(event)` returns a pointer to an area to check +and :cpp:expr:`lv_event_set_cover_res(event, res)` can be used to set one of +these results: + +- :cpp:enumerator:`LV_COVER_RES_COVER`: the area is fully covered by the object +- :cpp:enumerator:`LV_COVER_RES_NOT_COVER`: the area is not covered by the object +- :cpp:enumerator:`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 +:cpp:expr:`lv_event_set_ext_draw_size(e, size)`. + +API +*** diff --git a/docs/overview/drawing.md b/docs/overview/drawing.md deleted file mode 100644 index 1fbb9fb65..000000000 --- a/docs/overview/drawing.md +++ /dev/null @@ -1,221 +0,0 @@ -# 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_DEF_REFR_PERIOD` (set in `lv_hal_disp.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/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/docs/overview/event.md b/docs/overview/event.md deleted file mode 100644 index 939018a00..000000000 --- a/docs/overview/event.md +++ /dev/null @@ -1,184 +0,0 @@ -# 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(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` 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(obj, my_event_cb_1, LV_EVENT_CLICKED, NULL); -lv_obj_add_event(obj, my_event_cb_2, LV_EVENT_PRESSED, NULL); -lv_obj_add_event(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(obj, increment_on_click, LV_EVENT_CLICKED, &num1); -lv_obj_add_event(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`. - -## 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_THROW_BEGIN` Sent once when the object is released while scrolling but the "momentum" still keeps the content scrolling. -- `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`. -- `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 - -``` - -## API - - -```eval_rst - -.. doxygenfile:: lv_event.h - :project: lvgl - -``` diff --git a/docs/overview/event.rst b/docs/overview/event.rst new file mode 100644 index 000000000..8cf2653a0 --- /dev/null +++ b/docs/overview/event.rst @@ -0,0 +1,214 @@ +.. _events: + +====== +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: + +.. code:: c + + lv_obj_t * btn = lv_btn_create(lv_scr_act()); + lv_obj_add_event(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 :cpp:enumerator:`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. :cpp:enumerator:`LV_EVENT_ALL` can be used to receive all events. + +The last parameter of :cpp:func:`lv_obj_add_event` 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: + +.. code:: c + + lv_obj_add_event(obj, my_event_cb_1, LV_EVENT_CLICKED, NULL); + lv_obj_add_event(obj, my_event_cb_2, LV_EVENT_PRESSED, NULL); + lv_obj_add_event(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: + +.. code:: c + + lv_obj_add_event(obj, increment_on_click, LV_EVENT_CLICKED, &num1); + lv_obj_add_event(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 +:cpp:expr:`lv_obj_remove_event(obj, event_cb)` function + +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 +------------------- + +- :cpp:enumerator:`LV_EVENT_PRESSED`: An object has been pressed +- :cpp:enumerator:`LV_EVENT_PRESSING`: An object is being pressed (called continuously while pressing) +- :cpp:enumerator:`LV_EVENT_PRESS_LOST`: An object is still being pressed but slid cursor/finger off of the object +- :cpp:enumerator:`LV_EVENT_SHORT_CLICKED`: An object was pressed for a short period of time, then released. Not called if scrolled. +- :cpp:enumerator:`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. +- :cpp:enumerator:`LV_EVENT_LONG_PRESSED_REPEAT`: Called after ``long_press_time`` in every ``long_press_repeat_time`` ms. Not called if scrolled. +- :cpp:enumerator:`LV_EVENT_CLICKED`: Called on release if an object did not scroll (regardless of long press) +- :cpp:enumerator:`LV_EVENT_RELEASED`: Called in every case when an object has been released +- :cpp:enumerator:`LV_EVENT_SCROLL_BEGIN`: Scrolling begins. The event parameter is ``NULL`` or an :cpp:type:`lv_anim_t` ``*`` with a scroll animation descriptor that can be modified if required. +- :cpp:enumerator:`LV_EVENT_SCROLL_THROW_BEGIN`: Sent once when the object is released while scrolling but the "momentum" still keeps the content scrolling. +- :cpp:enumerator:`LV_EVENT_SCROLL_END`: Scrolling ends. +- :cpp:enumerator:`LV_EVENT_SCROLL`: An object was scrolled +- :cpp:enumerator:`LV_EVENT_GESTURE`: A gesture is detected. Get the gesture with :cpp:expr:`lv_indev_get_gesture_dir(lv_indev_get_act())` +- :cpp:enumerator:`LV_EVENT_KEY`: A key is sent to an object. Get the key with :cpp:expr:`lv_indev_get_key(lv_indev_get_act())` +- :cpp:enumerator:`LV_EVENT_FOCUSED`: An object is focused +- :cpp:enumerator:`LV_EVENT_DEFOCUSED`: An object is unfocused +- :cpp:enumerator:`LV_EVENT_LEAVE`: An object is unfocused but still selected +- :cpp:enumerator:`LV_EVENT_HIT_TEST`: Perform advanced hit-testing. Use :cpp:struct:`lv_hit_test_info_t` ``* a =`` :cpp:expr:`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 +-------------- + +- :cpp:enumerator:`LV_EVENT_COVER_CHECK`: Check if an object fully covers an area. The event parameter is :cpp:struct:`lv_cover_check_info_t` ``*``. +- :cpp:enumerator:`LV_EVENT_REFR_EXT_DRAW_SIZE`: Get the required extra draw area around an object (e.g. for a shadow). The event parameter is :cpp:type:`lv_coord_t` ``*`` to store the size. Only overwrite it with a larger value. +- :cpp:enumerator:`LV_EVENT_DRAW_MAIN_BEGIN`: Starting the main drawing phase. +- :cpp:enumerator:`LV_EVENT_DRAW_MAIN`: Perform the main drawing +- :cpp:enumerator:`LV_EVENT_DRAW_MAIN_END`: Finishing the main drawing phase +- :cpp:enumerator:`LV_EVENT_DRAW_POST_BEGIN`: Starting the post draw phase (when all children are drawn) +- :cpp:enumerator:`LV_EVENT_DRAW_POST`: Perform the post draw phase (when all children are drawn) +- :cpp:enumerator:`LV_EVENT_DRAW_POST_END`: Finishing the post draw phase (when all children are drawn) +- :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN`: Starting to draw a part. The event parameter is :cpp:struct:`lv_obj_draw_dsc_t` ``*``. Learn more :ref:`drawing`. +- :cpp:enumerator:`LV_EVENT_DRAW_PART_END`: Finishing to draw a part. The event parameter is :cpp:struct:`lv_obj_draw_dsc_t` ``*``. Learn more :ref:`drawing`. + +In ``LV_EVENT_DRAW_...`` events it's not allowed to adjust the widgets' +properties. E.g. you can not call :cpp:func:`lv_obj_set_width`. In other words +only ``get`` functions can be called. + +Other events +------------ + +- :cpp:enumerator:`LV_EVENT_DELETE`: Object is being deleted +- :cpp:enumerator:`LV_EVENT_CHILD_CHANGED`: Child was removed/added +- :cpp:enumerator:`LV_EVENT_CHILD_CREATED`: Child was created, always bubbles up to all parents +- :cpp:enumerator:`LV_EVENT_CHILD_DELETED`: Child was deleted, always bubbles up to all parents +- :cpp:enumerator:`LV_EVENT_SIZE_CHANGED`: Object coordinates/size have changed +- :cpp:enumerator:`LV_EVENT_STYLE_CHANGED`: Object's style has changed +- :cpp:enumerator:`LV_EVENT_BASE_DIR_CHANGED`: The base dir has changed +- :cpp:enumerator:`LV_EVENT_GET_SELF_SIZE`: Get the internal size of a widget +- :cpp:enumerator:`LV_EVENT_SCREEN_UNLOAD_START`: A screen unload started, fired immediately when lv_scr_load/lv_scr_load_anim is called +- :cpp:enumerator:`LV_EVENT_SCREEN_LOAD_START`: A screen load started, fired when the screen change delay is expired +- :cpp:enumerator:`LV_EVENT_SCREEN_LOADED`: A screen was loaded, called when all animations are finished +- :cpp:enumerator:`LV_EVENT_SCREEN_UNLOADED`: A screen was unloaded, called when all animations are finished + +Special events +-------------- + +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED`: The object's value has changed (i.e. slider moved) +- :cpp:enumerator:`LV_EVENT_INSERT`: Text is being inserted into the object. The event data is ``char *`` being inserted. +- :cpp:enumerator:`LV_EVENT_REFRESH`: Notify the object to refresh something on it (for the user) +- :cpp:enumerator:`LV_EVENT_READY`: A process has finished +- :cpp:enumerator:`LV_EVENT_CANCEL`: A process has been canceled + +Custom events +------------- + +Any custom event codes can be registered by +``uint32_t MY_EVENT_1 =`` :cpp:func:`lv_event_register_id` + +They can be sent to any object with +:cpp:expr:`lv_event_send(obj, MY_EVENT_1, &some_data)` + +Sending events +************** + +To manually send events to an object, use +:cpp:expr:`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): + +.. code:: 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 +------------- + +:cpp:enumerator:`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 +******************** + +:cpp:type:`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: + +- :cpp:expr:`lv_event_get_code(e)`: get the event code +- :cpp:expr:`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. +- :cpp:expr:`lv_event_get_target(e)`: get the object that originally triggered the event (different from :cpp:func:`lv_event_get_target` if `event bubbling <#event-bubbling>`__ is enabled) +- :cpp:expr:`lv_event_get_user_data(e)`: get the pointer passed as the last parameter of :cpp:func:`lv_obj_add_event`. +- :cpp:expr:`lv_event_get_param(e)`: get the parameter passed as the last parameter of :cpp:func:`lv_event_send` + +Event bubbling +************** + +If :cpp:expr:`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 +:cpp:enumerator:`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 +:cpp:expr:`lv_event_get_target_obj(e)` in the event handler. + +Examples +******** + +.. include:: ../examples/event/index.rst + +API +*** diff --git a/docs/overview/file-system.md b/docs/overview/file-system.md deleted file mode 100644 index 65c9e9387..000000000 --- a/docs/overview/file-system.md +++ /dev/null @@ -1,131 +0,0 @@ -# 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 - -LVGL contains prepared drivers for the API of POSIX, standard C, Windows, and [FATFS](http://elm-chan.org/fsw/ff/00index_e.html). Learn more [here](/libs/fsdrv). - -## 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/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/docs/overview/font.md b/docs/overview/font.md deleted file mode 100644 index 9e1265cff..000000000 --- a/docs/overview/font.md +++ /dev/null @@ -1,265 +0,0 @@ -# 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/docs/overview/font.rst b/docs/overview/font.rst new file mode 100644 index 000000000..b9efc92f3 --- /dev/null +++ b/docs/overview/font.rst @@ -0,0 +1,369 @@ +===== +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 +:cpp:type:`lv_font_t` variable and can be set in a style's *text_font* field. +For example: + +.. code:: 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, :c:macro:`LV_TXT_ENC` is set to :c:macro:`LV_TXT_ENC_UTF8` in +*lv_conf.h*. (This is the default value) + +To test it try + +.. code:: 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). + +- :c:macro:`LV_FONT_MONTSERRAT_12`: 12 px font +- :c:macro:`LV_FONT_MONTSERRAT_14`: 14 px font +- :c:macro:`LV_FONT_MONTSERRAT_16`: 16 px font +- :c:macro:`LV_FONT_MONTSERRAT_18`: 18 px font +- :c:macro:`LV_FONT_MONTSERRAT_20`: 20 px font +- :c:macro:`LV_FONT_MONTSERRAT_22`: 22 px font +- :c:macro:`LV_FONT_MONTSERRAT_24`: 24 px font +- :c:macro:`LV_FONT_MONTSERRAT_26`: 26 px font +- :c:macro:`LV_FONT_MONTSERRAT_28`: 28 px font +- :c:macro:`LV_FONT_MONTSERRAT_30`: 30 px font +- :c:macro:`LV_FONT_MONTSERRAT_32`: 32 px font +- :c:macro:`LV_FONT_MONTSERRAT_34`: 34 px font +- :c:macro:`LV_FONT_MONTSERRAT_36`: 36 px font +- :c:macro:`LV_FONT_MONTSERRAT_38`: 38 px font +- :c:macro:`LV_FONT_MONTSERRAT_40`: 40 px font +- :c:macro:`LV_FONT_MONTSERRAT_42`: 42 px font +- :c:macro:`LV_FONT_MONTSERRAT_44`: 44 px font +- :c:macro:`LV_FONT_MONTSERRAT_46`: 46 px font +- :c:macro:`LV_FONT_MONTSERRAT_48`: 48 px font + +Special fonts +------------- + +- :c:macro:`LV_FONT_MONTSERRAT_12_SUBPX`: Same as normal 12 px font but with `subpixel rendering <#subpixel-rendering>`__ +- :c:macro:`LV_FONT_MONTSERRAT_28_COMPRESSED`: Same as normal 28 px font but stored as a `compressed font <#compress-fonts>`__ with 3 bpp +- :c:macro:`LV_FONT_DEJAVU_16_PERSIAN_HEBREW`: 16 px font with normal range + Hebrew, Arabic, Persian letters and all their forms +- :c:macro:`LV_FONT_SIMSUN_16_CJK`: 16 px font with normal range plus 1000 of the most common CJK radicals +- :c:macro:`LV_FONT_UNSCII_8`: 8 px pixel perfect font with only ASCII characters +- :c:macro:`LV_FONT_UNSCII_16`: 16 px pixel perfect font with only ASCII characters + +The built-in fonts are **global variables** with names like +:cpp:var:`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. + +.. image:: /misc/symbols.png + +The symbols can be used singly as: + +.. code:: c + + lv_label_set_text(my_label, LV_SYMBOL_OK); + +Or together with strings (compile time string concatenation): + +.. code:: c + + lv_label_set_text(my_label, LV_SYMBOL_OK "Apply"); + +Or more symbols together: + +.. code:: 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: + +.. image:: /misc/bidi.png + +BiDi support is enabled by :c:macro:`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 +:c:macro:`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 :cpp:expr:`lv_obj_set_base_dir(obj, base_dir)`. +The possible base directions are: + +- :cpp:enumerator:`LV_BASE_DIR_LTR`: Left to Right base direction +- :cpp:enumerator:`LV_BASE_DIR_RTL`: Right to Left base direction +- :cpp:enumerator:`LV_BASE_DIR_AUTO`: Auto detect base direction + +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 :c:macro:`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 :cpp:func:`lv_label_set_text` will be "Arabic processed" but :cpp:func:`lv_label_set_text_static` won't. +- Text get functions (e.g. :cpp:func:`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 :c:macro:`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_font: + +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 :cpp:expr:`LV_FONT_DECLARE(my_font_name)`. + +To make fonts globally available (like the built-in fonts), add them to +:c:macro:`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. 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 :cpp:expr:`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. :cpp:expr:`lv_label_set_text(label, MY_USB_SYMBOL)` + +:note: :cpp:expr:`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 +*********************** + +:cpp:func:`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: To load a font `LVGL's filesystem </overview/file-system>`__ + needs to be enabled and a driver must be added. + +Example + +.. code:: 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 :cpp:type:`lv_font_t` variable needs to be created: + +.. code:: 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 :cpp:type:`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. + +.. code:: 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; + +API +*** diff --git a/docs/overview/fs.rst b/docs/overview/fs.rst new file mode 100644 index 000000000..bc908e450 --- /dev/null +++ b/docs/overview/fs.rst @@ -0,0 +1,159 @@ +.. _file-system: + +=========== +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 +******************** + +LVGL contains prepared drivers for the API of POSIX, standard C, +Windows, and `FATFS <http://elm-chan.org/fsw/ff/00index_e.html>`__. +Learn more `here </libs/fsdrv>`__. + +Adding a driver +*************** + +Registering a driver +-------------------- + +To add a driver, a :cpp:type:`lv_fs_drv_t` needs to be initialized like below. +The :cpp:type:`lv_fs_drv_t` needs to be static, global or dynamically allocated +and not a local variable. + +.. code:: 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: + +.. code:: 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 :cpp:enumerator:`LV_FS_MODE_WR` or :cpp:enumerator:`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: + +.. code:: 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: + +.. code:: 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 :cpp:func:`lv_fs_open` can be :cpp:enumerator:`LV_FS_MODE_WR` to open for writes +only or :cpp:enumerator:`LV_FS_MODE_RD` ``|`` :cpp:enumerator:`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. + +.. code:: 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/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 +*** diff --git a/docs/overview/image.md b/docs/overview/image.md deleted file mode 100644 index af6f18ed3..000000000 --- a/docs/overview/image.md +++ /dev/null @@ -1,366 +0,0 @@ -# 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/canvas) object. - -### Use images - -The simplest way to use an image in LVGL is to display it with an [lv_img](/widgets/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. - -### Custom cache algorithm -If you want to implement your own cache algorithm, you can refer to the following code to replace the LVGL built-in image cache manager: -```c -static _lv_img_cache_entry_t * my_img_cache_open(const void * src, lv_color_t color, int32_t frame_id) -{ - ... -} - -static void my_img_cache_set_size(uint16_t new_entry_cnt) -{ - ... -} - -static void my_img_cache_invalidate_src(const void * src) -{ - ... -} - -void my_img_cache_init(void) -{ - /* Before replacing the image cache manager, - * you should ensure that all caches are cleared to prevent memory leaks. - */ - lv_img_cache_invalidate_src(NULL); - - /*Initialize image cache manager.*/ - lv_img_cache_manager_t manager; - lv_img_cache_manager_init(&manager); - manager.open_cb = my_img_cache_open; - manager.set_size_cb = my_img_cache_set_size; - manager.invalidate_src_cb = my_img_cache_invalidate_src; - - /*Apply image cache manager to LVGL.*/ - lv_img_cache_manager_apply(&manager); -} -``` - -## API - - -### Image buffer - -```eval_rst - -.. doxygenfile:: lv_img_buf.h - :project: lvgl - -``` diff --git a/docs/overview/img.rst b/docs/overview/img.rst new file mode 100644 index 000000000..69020a192 --- /dev/null +++ b/docs/overview/img.rst @@ -0,0 +1,490 @@ +====== +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 +:cpp:struct:`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: + +- :cpp:enumerator:`LV_COLOR_FORMAT_NATIVE`: Simply stores the RGB colors (in whatever color depth LVGL is configured for). +- :cpp:enumerator:`LV_COLOR_FORMAT_NATIVE_ALPHA`: Like :cpp:enumerator:`LV_COLOR_FORMAT_NATIVE` but it also adds an alpha (transparency) byte for every pixel. +- :cpp:enumerator:`LV_COLOR_FORMAT_NATIVE_CHROMA_KEYED`: Like :cpp:enumerator:`LV_COLOR_FORMAT_NATIVE` but if a pixel has the + :c:macro:`LV_COLOR_TRANSP` color (set in *lv_conf.h*) it will be transparent. +- :cpp:enumerator:`LV_IMG_CF_INDEXED_1BIT`, :cpp:enumerator:`LV_IMG_CF_INDEXED_2BIT`, :cpp:enumerator:`LV_IMG_CF_INDEXED_4BIT`, :cpp:enumerator:`LV_IMG_CF_INDEXED_8BIT`: + Uses a palette with 2, 4, 16 or 256 colors and stores each pixel in 1, 2, 4 or 8 bits. +- :cpp:enumerator:`LV_IMG_CF_ALPHA_1BIT`, :cpp:enumerator:`LV_IMG_CF_ALPHA_2BIT`, :cpp:enumerator:`LV_IMG_CF_ALPHA_4BIT`, :cpp:enumerator:`LV_IMG_CF_ALPHA_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 :cpp:enumerator:`LV_COLOR_FORMAT_NATIVE` images are stored in the following order. + +- 32-bit color depth: + - **Byte 0**: Blue + - **Byte 1**: Green + - **Byte 2**: Red + - **Byte 3**: Alpha (only with :cpp:enumerator:`LV_COLOR_FORMAT_NATIVE_ALPHA`) +- 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 :cpp:enumerator:`LV_COLOR_FORMAT_NATIVE_ALPHA`) +- 8-bit color depth: + - **Byte 0**: Red 3 bit, Green 3 bit, Blue 2 bit + - **Byte 2**: Alpha byte (only with :cpp:enumerator:`LV_COLOR_FORMAT_NATIVE_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. + +- :cpp:enumerator:`LV_COLOR_FORMAT_RAW`: Indicates a basic raw image (e.g. a PNG or JPG image). +- :cpp:enumerator:`LV_COLOR_FORMAT_RAW_ALPHA`: Indicates that an image has alpha and an alpha byte is added for every pixel. +- :cpp:enumerator:`LV_IMG_CF_RAW_CHROMA_KEYED`: Indicates that an image is chroma-keyed as described in :cpp:enumerator:`LV_COLOR_FORMAT_NATIVE_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 :c:macro:`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: + +.. code:: 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 :cpp:enumerator:`LV_COLOR_FORMAT_NATIVE_ALPHA` you can set +``data_size`` like ``80 * 60 *`` :cpp:enumerator:`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/canvas>`__ object. + +Use images +---------- + +The simplest way to use an image in LVGL is to display it with an +`lv_img </widgets/img>`__ object: + +.. code:: 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 +:cpp:expr:`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: + - store a decoded image + - 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 :cpp:enumerator:`LV_IMG_CF_RAW`, :cpp:enumerator:`LV_IMG_CF_RAW_ALPHA` or +:cpp:enumerator:`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: :cpp:enumerator:`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: + +.. code:: 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 :cpp:enumerator:`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 :cpp:type:`lv_img_decoder_dsc_t` variable to describe +the decoding session and call :cpp:func:`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. + +.. code:: 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: + +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 +:c:macro:`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 +:cpp:expr:`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 :cpp:struct:`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 :cpp:expr:`lv_img_cache_invalidate_src(&my_png)`. If ``NULL`` is +passed as a parameter, the whole cache will be cleaned. + +Custom cache algorithm +---------------------- + +If you want to implement your own cache algorithm, you can refer to the +following code to replace the LVGL built-in image cache manager: + +.. code:: c + + static _lv_img_cache_entry_t * my_img_cache_open(const void * src, lv_color_t color, int32_t frame_id) + { + ... + } + + static void my_img_cache_set_size(uint16_t new_entry_cnt) + { + ... + } + + static void my_img_cache_invalidate_src(const void * src) + { + ... + } + + void my_img_cache_init(void) + { + /* Before replacing the image cache manager, + * you should ensure that all caches are cleared to prevent memory leaks. + */ + lv_img_cache_invalidate_src(NULL); + + /*Initialize image cache manager.*/ + lv_img_cache_manager_t manager; + lv_img_cache_manager_init(&manager); + manager.open_cb = my_img_cache_open; + manager.set_size_cb = my_img_cache_set_size; + manager.invalidate_src_cb = my_img_cache_invalidate_src; + + /*Apply image cache manager to LVGL.*/ + lv_img_cache_manager_apply(&manager); + } + +API +*** diff --git a/docs/overview/indev.md b/docs/overview/indev.md deleted file mode 100644 index e0289be91..000000000 --- a/docs/overview/indev.md +++ /dev/null @@ -1,150 +0,0 @@ -# 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_create(); -... -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(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/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/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)`. - -#### 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/dropdown)) -- **LV_KEY_DEL** Delete (E.g. a character on the right in a [Text area](/widgets/textarea)) -- **LV_KEY_BACKSPACE** Delete a character on the left (E.g. in a [Text area](/widgets/textarea)) -- **LV_KEY_HOME** Go to the beginning/top (E.g. in a [Text area](/widgets/textarea)) -- **LV_KEY_END** Go to the end (E.g. in a [Text area](/widgets/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/slider)) leaves *Edit* mode upon a short click. But with objects where a short click has meaning (e.g. [Button](/widgets/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/master/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/docs/overview/indev.rst b/docs/overview/indev.rst new file mode 100644 index 000000000..4398222af --- /dev/null +++ b/docs/overview/indev.rst @@ -0,0 +1,194 @@ +============= +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. + +.. code:: c + + ... + lv_indev_t * mouse_indev = lv_indev_create(); + ... + 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 +:cpp:expr:`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 :cpp:enumerator:`LV_EVENT_GESTURE` +event. For example: + +.. code:: 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(screen1, my_event, LV_EVENT_GESTURE, NULL); + +To prevent passing the gesture event to the parent from an object use +:cpp:expr:`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 +:cpp:expr:`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/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/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 :cpp:expr:`lv_group_t * g = lv_group_create()` and to add +an object to the group use :cpp:expr:`lv_group_add_obj(g, obj)`. + +To associate a group with an input device use +:cpp:expr:`lv_indev_set_group(indev, g)`. + +.. _indev_keys: + +Keys +^^^^ + +There are some predefined keys which have special meaning: + +- :cpp:enumerator:`LV_KEY_NEXT`: Focus on the next object +- :cpp:enumerator:`LV_KEY_PREV`: Focus on the previous object +- :cpp:enumerator:`LV_KEY_ENTER`: Triggers :cpp:enumerator:`LV_EVENT_PRESSED`, :cpp:enumerator:`LV_EVENT_CLICKED`, or :cpp:enumerator:`LV_EVENT_LONG_PRESSED` etc. events +- :cpp:enumerator:`LV_KEY_UP`: Increase value or move upwards +- :cpp:enumerator:`LV_KEY_DOWN`: Decrease value or move downwards +- :cpp:enumerator:`LV_KEY_RIGHT`: Increase value or move to the right +- :cpp:enumerator:`LV_KEY_LEFT`: Decrease value or move to the left +- :cpp:enumerator:`LV_KEY_ESC`: Close or exit (E.g. close a `Drop down list </widgets/dropdown>`__) +- :cpp:enumerator:`LV_KEY_DEL`: Delete (E.g. a character on the right in a `Text area </widgets/textarea>`__) +- :cpp:enumerator:`LV_KEY_BACKSPACE`: Delete a character on the left (E.g. in a `Text area </widgets/textarea>`__) +- :cpp:enumerator:`LV_KEY_HOME`: Go to the beginning/top (E.g. in a `Text area </widgets/textarea>`__) +- :cpp:enumerator:`LV_KEY_END`: Go to the end (E.g. in a `Text area </widgets/textarea>`__) + +The most important special keys In your ``read_cb`` function + + - :cpp:enumerator:`LV_KEY_NEXT` + - :cpp:enumerator:`LV_KEY_PREV` + - :cpp:enumerator:`LV_KEY_ENTER`, + - :cpp:enumerator:`LV_KEY_UP`, + - :cpp:enumerator:`LV_KEY_DOWN`, + - :cpp:enumerator:`LV_KEY_LEFT` + - :cpp:enumerator:`LV_KEY_RIGHT` + +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 :cpp:enumerator:`LV_KEY_LEFT` and :cpp:enumerator:`LV_KEY_RIGHT` because most +objects can be fully controlled with them. + +With an encoder you should use only :cpp:enumerator:`LV_KEY_LEFT`, :cpp:enumerator:`LV_KEY_RIGHT`, +and :cpp:enumerator:`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 :cpp:enumerator:`LV_KEY_LEFT` or :cpp:enumerator:`LV_KEY_RIGHT` is translated to +:cpp:enumerator:`LV_KEY_NEXT` or :cpp:enumerator:`LV_KEY_PREV`. Therefore, the next or previous object will be +selected by turning the encoder. Pressing :cpp:enumerator:`LV_KEY_ENTER` will change +to *Edit* mode. + +In *Edit* mode, :cpp:enumerator:`LV_KEY_NEXT` and :cpp:enumerator:`LV_KEY_PREV` is usually used to modify an +object. Depending on the object's type, a short or long press of +:cpp:enumerator:`LV_KEY_ENTER` changes back to *Navigate* mode. Usually, an object +which cannot be pressed (like a `Slider </widgets/slider>`__) leaves +*Edit* mode upon a short click. But with objects where a short click has +meaning (e.g. `Button </widgets/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 +:cpp:expr:`lv_group_t * g = lv_group_create()` and set the default group with +:cpp:expr:`lv_group_set_default(g)` + +Don't forget to assign one or more input devices to the default group +with :cpp:expr:`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 :cpp:enumerator:`LV_STATE_FOCUSED` state. +Hence, focused styles will be applied to it. + +If an object switches to edit mode it enters the +:cpp:expr:`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/master/overview/style.html>`__ section. + + +API +*** diff --git a/docs/overview/index.md b/docs/overview/index.md deleted file mode 100644 index 2b33ecd60..000000000 --- a/docs/overview/index.md +++ /dev/null @@ -1,29 +0,0 @@ - -# 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/docs/overview/index.rst b/docs/overview/index.rst new file mode 100644 index 000000000..7058405d7 --- /dev/null +++ b/docs/overview/index.rst @@ -0,0 +1,28 @@ +.. _overview: + +======== +Overview +======== + + +.. toctree:: + :maxdepth: 2 + + obj + coord + style + style-props + scroll + layer + event + indev + disp + color + font + img + fs + anim + timer + draw + renderers/index + new_widget diff --git a/docs/overview/layer.md b/docs/overview/layer.md deleted file mode 100644 index c772bb8df..000000000 --- a/docs/overview/layer.md +++ /dev/null @@ -1,55 +0,0 @@ - -# 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); -``` - -## Change order - -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_to_index(obj, idx)` to move an object to a given index in the order of children. (0: background, child_num - 1: foreground, <0: count from the top, to move forward (up): `lv_obj_move_to_index(obj, lv_obj_get_index(obj) - 1)`) -- 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/docs/overview/layer.rst b/docs/overview/layer.rst new file mode 100644 index 000000000..fa0a0974f --- /dev/null +++ b/docs/overview/layer.rst @@ -0,0 +1,80 @@ +====== +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. + +.. image:: /misc/layers.png + +.. code:: 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); + +Change order +************ + +There are four explicit ways to bring an object to the foreground: + +- Use :cpp:expr:`lv_obj_move_foreground(obj)` to bring an object to the foreground. + Similarly, use :cpp:expr:`lv_obj_move_background(obj)` to move it to the background. +- Use :cpp:expr:`lv_obj_move_to_index(obj, idx)` to move an object to a given index in the order of children. + + - ``0``: background + - ``child_num - 1``: foreground + - ``< 0``: count from the top, to move forward (up): :cpp:expr:`lv_obj_move_to_index(obj, lv_obj_get_index(obj) - 1)` + +- Use :cpp:expr:`lv_obj_swap(obj1, obj2)` to swap the relative layer position of two objects. +- When :cpp:expr:`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 (:cpp:func:`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. + +.. code:: 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. + +API +*** diff --git a/docs/overview/new_widget.md b/docs/overview/new_widget.md deleted file mode 100644 index 0d000bf86..000000000 --- a/docs/overview/new_widget.md +++ /dev/null @@ -1,3 +0,0 @@ - -# New widget - diff --git a/docs/overview/new_widget.rst b/docs/overview/new_widget.rst new file mode 100644 index 000000000..1e876c0d7 --- /dev/null +++ b/docs/overview/new_widget.rst @@ -0,0 +1,3 @@ +========== +New widget +========== diff --git a/docs/overview/obj.rst b/docs/overview/obj.rst new file mode 100644 index 000000000..38fdfc4c7 --- /dev/null +++ b/docs/overview/obj.rst @@ -0,0 +1,308 @@ +======= +Objects +======= + +In LVGL the **basic building blocks** of a user interface are the +objects, also called *Widgets*. For example a +`Button </widgets/btn>`__, `Label </widgets/label>`__, +`Image </widgets/img>`__, `List </widgets/list>`__, +`Chart </widgets/chart>`__ or `Text area </widgets/textarea>`__. + +You can see all the `Object types </widgets/index>`__ here. + +All objects are referenced using an :cpp:type:`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: + +.. code:: 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: + +.. code:: 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. + +.. image:: /misc/par_child1.png + +.. code:: 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: + +.. image:: /misc/par_child2.png + +.. code:: 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. + +.. image:: /misc/par_child3.png + +.. code:: c + + lv_obj_set_x(obj1, -30); /*Move the child a little bit off the parent*/ + +This behavior can be overwritten with +:cpp:expr:`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: + +.. code:: 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 :cpp:type:`lv_obj_t` ``*`` +type. + +There is a common **delete** function for all object types. It deletes +the object and all of its children. + +.. code:: c + + void lv_obj_del(lv_obj_t * obj); + +:cpp:func:`lv_obj_del` will delete the object immediately. If for any reason you +can't delete the object immediately you can use +:cpp:expr:`lv_obj_del_async(obj)` which will perform the deletion on the next +call of :cpp:func:`lv_timer_handler`. This is useful e.g. if you want to +delete the parent of an object in the child's :cpp:enumerator:`LV_EVENT_DELETE` +handler. + +You can remove all the children of an object (but not the object itself) +using :cpp:expr:`lv_obj_clean(obj)`. + +You can use :cpp:expr:`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: + +.. code:: 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 :cpp:func:`lv_scr_act` function. + +Load screens +------------ + +To load a new screen, use :cpp:expr:`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 +:cpp:func:`lv_indev_set_cursor`). + +The :cpp:func:`lv_layer_top` and :cpp:func:`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 +:cpp:expr:`lv_scr_load_anim(scr, transition_type, time, delay, auto_del)`. The +following transition types exist: + +- :cpp:enumerator:`LV_SCR_LOAD_ANIM_NONE`: Switch immediately after ``delay`` milliseconds +- :cpp:enumerator:`LV_SCR_LOAD_ANIM_OVER_LEFT`, :cpp:enumerator:`LV_SCR_LOAD_ANIM_OVER_RIGHT`, :cpp:enumerator:`LV_SCR_LOAD_ANIM_OVER_TOP` and :cpp:enumerator:`LV_SCR_LOAD_ANIM_OVER_BOTTOM`: Move the new screen over the current towards the given direction +- :cpp:enumerator:`LV_SCR_LOAD_ANIM_OUT_LEFT`, :cpp:enumerator:`LV_SCR_LOAD_ANIM_OUT_RIGHT`, :cpp:enumerator:`LV_SCR_LOAD_ANIM_OUT_TOP` and :cpp:enumerator:`LV_SCR_LOAD_ANIM_OUT_BOTTOM`: Move out the old screen over the current towards the given direction +- :cpp:enumerator:`LV_SCR_LOAD_ANIM_MOVE_LEFT`, :cpp:enumerator:`LV_SCR_LOAD_ANIM_MOVE_RIGHT`, :cpp:enumerator:`LV_SCR_LOAD_ANIM_MOVE_TOP` and :cpp:enumerator:`LV_SCR_LOAD_ANIM_MOVE_BOTTOM`: Move both the current and new screens towards the given direction +- :cpp:enumerator:`LV_SCR_LOAD_ANIM_FADE_IN` and :cpp:enumerator:`LV_SCR_LOAD_ANIM_FADE_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 :cpp:func:`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 +:cpp:func:`lv_disp_drv_register`. You can also explicitly select a new default +display using :cpp:expr:`lv_disp_set_default(disp)`. + +:cpp:func:`lv_scr_act`, :cpp:func:`lv_scr_load` and :cpp:func:`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/slider>`__ uses the main, indicator and knob parts. +Parts are similar to *pseudo-elements* in CSS. + +The following predefined parts exist in LVGL: + +- :cpp:enumerator:`LV_PART_MAIN`: A background like rectangle +- :cpp:enumerator:`LV_PART_SCROLLBAR`: The scrollbar(s) +- :cpp:enumerator:`LV_PART_INDICATOR`: Indicator, e.g. for slider, bar, switch, or the tick box of the checkbox +- :cpp:enumerator:`LV_PART_KNOB`: Like a handle to grab to adjust the value +- :cpp:enumerator:`LV_PART_SELECTED`: Indicate the currently selected option or section +- :cpp:enumerator:`LV_PART_ITEMS`: Used if the widget has multiple similar elements (e.g. table cells) +- :cpp:enumerator:`LV_PART_TICKS`: Ticks on scales e.g. for a chart or meter +- :cpp:enumerator:`LV_PART_CURSOR`: Mark a specific place e.g. text area's or chart's cursor +- :cpp:enumerator:`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: + +- :cpp:enumerator:`LV_STATE_DEFAULT`: Normal, released state +- :cpp:enumerator:`LV_STATE_CHECKED`: Toggled or checked state +- :cpp:enumerator:`LV_STATE_FOCUSED`: Focused via keypad or encoder or clicked via touchpad/mouse +- :cpp:enumerator:`LV_STATE_FOCUS_KEY`: Focused via keypad or encoder but not via touchpad/mouse +- :cpp:enumerator:`LV_STATE_EDITED`: Edit by an encoder +- :cpp:enumerator:`LV_STATE_HOVERED`: Hovered by mouse (not supported now) +- :cpp:enumerator:`LV_STATE_PRESSED`: Being pressed +- :cpp:enumerator:`LV_STATE_SCROLLED`: Being scrolled +- :cpp:enumerator:`LV_STATE_DISABLED`: Disabled state +- :cpp:enumerator:`LV_STATE_USER_1`: Custom state +- :cpp:enumerator:`LV_STATE_USER_2`: Custom state +- :cpp:enumerator:`LV_STATE_USER_3`: Custom state +- :cpp:enumerator:`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. +:cpp:expr:`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>`__. + +API +*** diff --git a/docs/overview/object.md b/docs/overview/object.md deleted file mode 100644 index fa2319933..000000000 --- a/docs/overview/object.md +++ /dev/null @@ -1,223 +0,0 @@ -# Objects - -In LVGL the **basic building blocks** of a user interface are the objects, also called *Widgets*. -For example a [Button](/widgets/btn), [Label](/widgets/label), [Image](/widgets/img), [List](/widgets/list), [Chart](/widgets/chart) or [Text area](/widgets/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/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/docs/overview/renderers/arm-2d.md b/docs/overview/renderers/arm-2d.md deleted file mode 100644 index 85a4dbc55..000000000 --- a/docs/overview/renderers/arm-2d.md +++ /dev/null @@ -1,32 +0,0 @@ -# Arm-2D GPU - -Arm-2D is not a GPU but **an abstraction layer for 2D GPUs dedicated to Microcontrollers**. It supports all Cortex-M processors ranging from Cortex-M0 to the latest Cortex-M85. - -Arm-2D is an open-source project on Github. For more, please refer to: https://github.com/ARM-software/Arm-2D. - - - -## How to Use - -In general, you can set the macro `LV_USE_GPU_ARM2D` to `1`in `lv_conf.h` to enable Arm-2D acceleration for LVGL. - -If you are using **[CMSIS-Pack](https://github.com/lvgl/lvgl/tree/master/env_support/cmsis-pack)** to deploy the LVGL. You don't have to define the macro `LV_USE_GPU_ARM2D` manually, instead, please select the component `GPU Arm-2D` in the **RTE** dialog. This step will define the macro for us. - - - -## Design Considerations - -As mentioned before, Arm-2D is an abstraction layer for 2D GPU; hence if there is no accelerator or dedicated instruction set (such as Helium or ACI) available for Arm-2D, it provides negligible performance boost for LVGL (sometimes worse) for regular Cortex-M processors. - -**We highly recommend you enable Arm-2D acceleration for LVGL** when: - -- The target processors are **Cortex-M55** and/or **Cortex-M85** -- The target processors support **[Helium](https://developer.arm.com/documentation/102102/0103/?lang=en)**. -- The device vendor provides an arm-2d compliant driver for their propriotory 2D accelerators and/or customized instruction set. -- The target device contains [DMA-350](https://community.arm.com/arm-community-blogs/b/internet-of-things-blog/posts/arm-corelink-dma-350-next-generation-direct-memory-access-for-endpoint-ai) - - - -## Examples - -- [A Cortex-M55 (supports Helium) based MDK Project, PC emulation is available.](https://github.com/lvgl/lv_port_an547_cm55_sim) diff --git a/docs/overview/renderers/arm2d.rst b/docs/overview/renderers/arm2d.rst new file mode 100644 index 000000000..fe4d62cc4 --- /dev/null +++ b/docs/overview/renderers/arm2d.rst @@ -0,0 +1,51 @@ +========== +Arm-2D GPU +========== + +Arm-2D is not a GPU but **an abstraction layer for 2D GPUs dedicated to +Microcontrollers**. It supports all Cortex-M processors ranging from +Cortex-M0 to the latest Cortex-M85. + +Arm-2D is an open-source project on Github. For more, please refer to: +https://github.com/ARM-software/Arm-2D. + +How to Use +********** + +In general, you can set the macro :c:macro:`LV_USE_GPU_ARM2D` to ``1`` in +``lv_conf.h`` to enable Arm-2D acceleration for LVGL. + +If you are using +`CMSIS-Pack <https://github.com/lvgl/lvgl/tree/master/env_support/cmsis-pack>`__ +to deploy the LVGL. You don’t have to define the macro +:c:macro:`LV_USE_GPU_ARM2D` manually, instead, please select the component +``GPU Arm-2D`` in the **RTE** dialog. This step will define the macro for us. + +Design Considerations +********************* + +As mentioned before, Arm-2D is an abstraction layer for 2D GPU; hence if +there is no accelerator or dedicated instruction set (such as Helium or +ACI) available for Arm-2D, it provides negligible performance boost for +LVGL (sometimes worse) for regular Cortex-M processors. + +**We highly recommend you enable Arm-2D acceleration for LVGL** when: + +- The target processors are **Cortex-M55** and/or **Cortex-M85** +- The target processors support + `Helium <https://developer.arm.com/documentation/102102/0103/?lang=en>`__. +- The device vendor provides an arm-2d compliant driver for their + propriotory 2D accelerators and/or customized instruction set. +- The target device contains + `DMA-350 <https://community.arm.com/arm-community-blogs/b/internet-of-things-blog/posts/arm-corelink-dma-350-next-generation-direct-memory-access-for-endpoint-ai>`__ + +Examples +******** + +- `A Cortex-M55 (supports Helium) based MDK Project, PC emulation is + available. <https://github.com/lvgl/lv_port_an547_cm55_sim>`__ + +API +*** + +:ref:`lv_gpu_arm2d` diff --git a/docs/overview/renderers/dma2d.md b/docs/overview/renderers/dma2d.md deleted file mode 100644 index 6c6b3d1f8..000000000 --- a/docs/overview/renderers/dma2d.md +++ /dev/null @@ -1,4 +0,0 @@ -# DMA2D GPU - -TODO - diff --git a/docs/overview/renderers/index.md b/docs/overview/renderers/index.md deleted file mode 100644 index b11f58843..000000000 --- a/docs/overview/renderers/index.md +++ /dev/null @@ -1,16 +0,0 @@ - -# Renderers and GPUs - - -```eval_rst - -.. toctree:: - :maxdepth: 2 - - sw - sdl - arm-2d - pxp-vglite - dma2d -``` - diff --git a/docs/overview/renderers/index.rst b/docs/overview/renderers/index.rst new file mode 100644 index 000000000..7d3c96b59 --- /dev/null +++ b/docs/overview/renderers/index.rst @@ -0,0 +1,13 @@ +================== +Renderers and GPUs +================== + +.. toctree:: + :maxdepth: 2 + + sw + sdl + arm2d + pxp + stm32_dma2d + vglite diff --git a/docs/overview/renderers/pxp-vglite.md b/docs/overview/renderers/pxp-vglite.md deleted file mode 100644 index d68d1e7e5..000000000 --- a/docs/overview/renderers/pxp-vglite.md +++ /dev/null @@ -1,4 +0,0 @@ -# NXP PXP and VGLite GPU - -TODO - diff --git a/docs/overview/renderers/pxp.rst b/docs/overview/renderers/pxp.rst new file mode 100644 index 000000000..423e9519b --- /dev/null +++ b/docs/overview/renderers/pxp.rst @@ -0,0 +1,14 @@ +=========== +NXP PXP GPU +=========== + +API +--- + +:ref:`lv_draw_pxp` + +:ref:`lv_draw_pxp_blend` + +:ref:`lv_gpu_nxp_pxp` + +:ref:`lv_gpu_nxp_pxp_osa` diff --git a/docs/overview/renderers/sdl.md b/docs/overview/renderers/sdl.md deleted file mode 100644 index af8b976e2..000000000 --- a/docs/overview/renderers/sdl.md +++ /dev/null @@ -1,4 +0,0 @@ -# SDL renderer - -TODO - diff --git a/docs/overview/renderers/sdl.rst b/docs/overview/renderers/sdl.rst new file mode 100644 index 000000000..600bd2fa8 --- /dev/null +++ b/docs/overview/renderers/sdl.rst @@ -0,0 +1,26 @@ +============ +SDL renderer +============ + +API +--- + +:ref:`lv_draw_sdl` + +:ref:`lv_draw_sdl_composite` + +:ref:`lv_draw_sdl_img` + +:ref:`lv_draw_sdl_layer` + +:ref:`lv_draw_sdl_mask` + +:ref:`lv_draw_sdl_priv` + +:ref:`lv_draw_sdl_rect` + +:ref:`lv_draw_sdl_stack_blur` + +:ref:`lv_draw_sdl_texture_cache` + +:ref:`lv_draw_sdl_utils` diff --git a/docs/overview/renderers/stm32_dma2d.rst b/docs/overview/renderers/stm32_dma2d.rst new file mode 100644 index 000000000..b4f8c3c27 --- /dev/null +++ b/docs/overview/renderers/stm32_dma2d.rst @@ -0,0 +1,8 @@ +========= +DMA2D GPU +========= + +API +--- + +:ref:`lv_gpu_stm32_dma2d` diff --git a/docs/overview/renderers/sw.md b/docs/overview/renderers/sw.md deleted file mode 100644 index ccc1c2661..000000000 --- a/docs/overview/renderers/sw.md +++ /dev/null @@ -1,4 +0,0 @@ -# Software renderer - -TODO - diff --git a/docs/overview/renderers/sw.rst b/docs/overview/renderers/sw.rst new file mode 100644 index 000000000..cf6b90c86 --- /dev/null +++ b/docs/overview/renderers/sw.rst @@ -0,0 +1,14 @@ +================= +Software renderer +================= + +API +--- + +:ref:`lv_draw_sw` + +:ref:`lv_draw_sw_blend` + +:ref:`lv_draw_sw_dither` + +:ref:`lv_draw_sw_gradient` diff --git a/docs/overview/renderers/vglite.rst b/docs/overview/renderers/vglite.rst new file mode 100644 index 000000000..6057188ec --- /dev/null +++ b/docs/overview/renderers/vglite.rst @@ -0,0 +1,20 @@ +============== +NXP VGLite GPU +============== + +API +--- + +:ref:`lv_draw_vglite` + +:ref:`lv_draw_vglite_arc` + +:ref:`lv_draw_vglite_blend` + +:ref:`lv_draw_vglite_line` + +:ref:`lv_draw_vglite_rect` + +:ref:`lv_vglite_buf` + +:ref:`lv_vglite_utils` diff --git a/docs/overview/scroll.md b/docs/overview/scroll.md deleted file mode 100644 index 0a9458df2..000000000 --- a/docs/overview/scroll.md +++ /dev/null @@ -1,195 +0,0 @@ -# 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(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/docs/overview/scroll.rst b/docs/overview/scroll.rst new file mode 100644 index 000000000..18eff0462 --- /dev/null +++ b/docs/overview/scroll.rst @@ -0,0 +1,281 @@ +====== +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: + +- :cpp:enumerator:`LV_SCROLLBAR_MODE_OFF`: Never show the scrollbars +- :cpp:enumerator:`LV_SCROLLBAR_MODE_ON`: Always show the scrollbars +- :cpp:enumerator:`LV_SCROLLBAR_MODE_ACTIVE`: Show scroll bars while an object is being scrolled +- :cpp:enumerator:`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 +:cpp:enumerator:`LV_PART_SCROLLBAR`. For example a scrollbar can turn to red like +this: + +.. code:: 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 :cpp:enumerator:`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: + +.. code:: 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 :cpp:enumerator:`LV_PART_SCROLLBAR` is RTL +(:c:macro:`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 :cpp:enumerator:`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: + +- :cpp:enumerator:`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. +- :cpp:enumerator:`LV_EVENT_SCROLL_END`: Scrolling ends. +- :cpp:enumerator:`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 +:cpp:expr:`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: +- :cpp:enumerator:`LV_DIR_TOP`: only scroll up +- :cpp:enumerator:`LV_DIR_LEFT`: only scroll left +- :cpp:enumerator:`LV_DIR_BOTTOM`: only scroll down +- :cpp:enumerator:`LV_DIR_RIGHT`: only scroll right +- :cpp:enumerator:`LV_DIR_HOR`: only scroll horizontally +- :cpp:enumerator:`LV_DIR_VER`: only scroll vertically +- :cpp:enumerator:`LV_DIR_ALL`: scroll any directions + +OR-ed values are also possible. E.g. :cpp:expr:`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 +:cpp:enumerator:`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 :cpp:enumerator:`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 :cpp:enumerator:`LV_OBJ_FLAG_SNAPPABLE` flag. + +An object can align snapped children in four ways: + +- :cpp:enumerator:`LV_SCROLL_SNAP_NONE`: Snapping is disabled. (default) +- :cpp:enumerator:`LV_SCROLL_SNAP_START`: Align the children to the left/top side of a scrolled object +- :cpp:enumerator:`LV_SCROLL_SNAP_END`: Align the children to the right/bottom side of a scrolled object +- :cpp:enumerator:`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 +:cpp:enumerator:`LV_SCROLL_SNAP_NONE`. + +This feature can be enabled by the :cpp:enumerator:`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. + +.. code:: 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(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 :cpp:enumerator:`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: + +.. code:: 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 +******** + +.. include:: ../examples/scroll/index.rst + +API +*** diff --git a/docs/overview/style-props.md b/docs/overview/style-props.md deleted file mode 100644 index 2161bd60c..000000000 --- a/docs/overview/style-props.md +++ /dev/null @@ -1,829 +0,0 @@ -# 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_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> - -## Margin -Properties to describe spacing around an object. Very similar to the margin properties in HTML. - -### margin_top -Sets the margin on the top. The object will keep this space from its siblings in 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> - -### margin_bottom -Sets the margin on the bottom. The object will keep this space from its siblings in 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> - -### margin_left -Sets the margin on the left. The object will keep this space from its siblings in 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> - -### margin_right -Sets the margin on the right. The object will keep this space from its siblings in 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/docs/overview/style-props.rst b/docs/overview/style-props.rst new file mode 100644 index 000000000..bd36a6de8 --- /dev/null +++ b/docs/overview/style-props.rst @@ -0,0 +1,4892 @@ +================ +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 :c:macro:`LV_SIZE_CONTENT` +values can be used. Percentage values are relative to the width of the +parent’s content area. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default Widget dependent + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </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. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </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. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default LV_COORD_MAX + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +height +~~~~~~ + +Sets the height of object. Pixel, percentage and :c:macro:`LV_SIZE_CONTENT` can +be used. Percentage values are relative to the height of the parent’s +content area. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default Widget dependent + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </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. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </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. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default LV_COORD_MAX + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </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. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </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. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </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: + +- :cpp:enumerator:`LV_ALIGN_DEFAULT`, +- :cpp:enumerator:`LV_ALIGN_TOP_LEFT` +- :cpp:enumerator:`LV_ALIGN_TOP_MID` +- :cpp:enumerator:`LV_ALIGN_TOP_RIGHT`, +- :cpp:enumerator:`LV_ALIGN_BOTTOM_LEFT` +- :cpp:enumerator:`LV_ALIGN_BOTTOM_MID` +- :cpp:enumerator:`LV_ALIGN_BOTTOM_RIGHT`, +- :cpp:enumerator:`LV_ALIGN_LEFT_MID` +- :cpp:enumerator:`LV_ALIGN_RIGHT_MID`, +- :cpp:enumerator:`LV_ALIGN_CENTER`. +- :cpp:enumerator:`LV_ALIGN_DEFAULT` + +:cpp:enumerator:`LV_ALIGN_DEFAULT` means :cpp:enumerator:`LV_ALIGN_TOP_LEFT` +with LTR base direction and :cpp:enumerator:`LV_ALIGN_TOP_RIGHT` with RTL base +direction. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_ALIGN_DEFAULT` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +transform_width +~~~~~~~~~~~~~~~ + +Make the object wider on both sides with this value. Pixel and +percentage (with :cpp:expr:`lv_pct(x)`) values can be used. Percentage values +are relative to the object’s width. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw Yes + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +transform_height +~~~~~~~~~~~~~~~~ + +Make the object higher on both sides with this value. Pixel and +percentage (with :cpp:expr:`lv_pct(x)`) values can be used. Percentage values +are relative to the object’s height. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw Yes + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +translate_x +~~~~~~~~~~~ + +Move the object with this value in X direction. Applied after layouts, +aligns and other positioning. Pixel and percentage (with :cpp:expr:`lv_pct(x)`) +values can be used. Percentage values are relative to the object’s +width. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +translate_y +~~~~~~~~~~~ + +Move the object with this value in Y direction. Applied after layouts, +aligns and other positioning. Pixel and percentage (with :cpp:expr:`lv_pct(x)`) +values can be used. Percentage values are relative to the object’s +height. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +transform_zoom +~~~~~~~~~~~~~~ + +Zoom an objects. The value 256 (or :cpp:enumerator:`LV_ZOOM_NONE`) means normal size, +128 half size, 512 double size, and so on + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw Yes + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +transform_angle +~~~~~~~~~~~~~~~ + +Rotate an objects. The value is interpreted in 0.1 degree units. E.g. +450 means 45 deg. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw Yes + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +transform_pivot_x +~~~~~~~~~~~~~~~~~ + +Set the pivot point’s X coordinate for transformations. Relative to the +object’s top left corner’ + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +transform_pivot_y +~~~~~~~~~~~~~~~~~ + +Set the pivot point’s Y coordinate for transformations. Relative to the +object’s top left corner’ + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </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. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +pad_bottom +~~~~~~~~~~ + +Sets the padding on the bottom. It makes the content area smaller in +this direction. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +pad_left +~~~~~~~~ + +Sets the padding on the left. It makes the content area smaller in this +direction. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +pad_right +~~~~~~~~~ + +Sets the padding on the right. It makes the content area smaller in this +direction. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +pad_row +~~~~~~~ + +Sets the padding between the rows. Used by the layouts. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +pad_column +~~~~~~~~~~ + +Sets the padding between the columns. Used by the layouts. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +Margin +------ + +Properties to describe spacing around an object. Very similar to the +margin properties in HTML. + +margin_top +~~~~~~~~~~ + +Sets the margin on the top. The object will keep this space from its +siblings in layouts. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +margin_bottom +~~~~~~~~~~~~~ + +Sets the margin on the bottom. The object will keep this space from its +siblings in layouts. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +margin_left +~~~~~~~~~~~ + +Sets the margin on the left. The object will keep this space from its +siblings in layouts. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +margin_right +~~~~~~~~~~~~ + +Sets the margin on the right. The object will keep this space from its +siblings in layouts. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +Background +---------- + +Properties to describe the background color and image of the objects. + +bg_color +~~~~~~~~ + +Set the background color of the object. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default ``0xffffff`` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +bg_opa +~~~~~~ + +Set the opacity of the background. Value 0, :cpp:enumerator:`LV_OPA_0` or +:cpp:enumerator:`LV_OPA_TRANSP` means fully transparent, 255, :cpp:enumerator:`LV_OPA_100` or +:cpp:enumerator:`LV_OPA_COVER` means fully covering, other values or :cpp:enumerator:`LV_OPA_10`, +:cpp:enumerator:`LV_OPA_20`, etc means semi transparency. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_OPA_TRANSP` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +bg_grad_color +~~~~~~~~~~~~~ + +Set the gradient color of the background. Used only if ``grad_dir`` is +not :cpp:enumerator:`LV_GRAD_DIR_NONE` + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default ``0x000000`` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +bg_grad_dir +~~~~~~~~~~~ + +Set the direction of the gradient of the background. The possible values +are: + +- :cpp:enumerator:`LV_GRAD_DIR_NONE` +- :cpp:enumerator:`LV_GRAD_DIR_HOR` +- :cpp:enumerator:`LV_GRAD_DIR_VER` + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_GRAD_DIR_NONE` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </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 + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </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 + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 255 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +bg_grad +~~~~~~~ + +Set the gradient definition. The pointed instance must exist while the +object is alive. NULL to disable. It wraps :cpp:enumerator:`BG_GRAD_COLOR`, +:cpp:enumerator:`BG_GRAD_DIR`, :cpp:enumerator:`BG_MAIN_STOP` and :cpp:enumerator:`BG_GRAD_STOP` into one +descriptor and allows creating gradients with more colors too. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default ``NULL`` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +bg_dither_mode +~~~~~~~~~~~~~~ + +Set the dithering mode of the gradient of the background. The possible +values are: + +- :cpp:enumerator:`LV_DITHER_NONE` +- :cpp:enumerator:`LV_DITHER_ORDERED` +- :cpp:enumerator:`LV_DITHER_ERR_DIFF` + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_DITHER_NONE` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +bg_img_src +~~~~~~~~~~ + +Set a background image. Can be a pointer to :cpp:struct:`lv_img_dsc_t`, a path to +a file or an ``LV_SYMBOL_...`` + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default ``NULL`` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw Yes + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +bg_img_opa +~~~~~~~~~~ + +Set the opacity of the background image. Value 0, :cpp:enumerator:`LV_OPA_0` or +:cpp:enumerator:`LV_OPA_TRANSP` means fully transparent, 255, :cpp:enumerator:`LV_OPA_100` or +:cpp:enumerator:`LV_OPA_COVER` means fully covering, other values or LV_OPA_10, +LV_OPA_20, etc means semi transparency. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_OPA_COVER` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +bg_img_recolor +~~~~~~~~~~~~~~ + +Set a color to mix to the background image. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default ``0x000000`` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +bg_img_recolor_opa +~~~~~~~~~~~~~~~~~~ + +Set the intensity of background image recoloring. Value 0, :cpp:enumerator:`LV_OPA_0` +or :cpp:enumerator:`LV_OPA_TRANSP` means no mixing, 255, :cpp:enumerator:`LV_OPA_100` or +:cpp:enumerator:`LV_OPA_COVER` means full recoloring, other values or LV_OPA_10, +LV_OPA_20, etc are interpreted proportionally. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_OPA_TRANSP` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +bg_img_tiled +~~~~~~~~~~~~ + +If enabled the background image will be tiled. The possible values are +``true`` or ``false``. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +Border +------ + +Properties to describe the borders + +border_color +~~~~~~~~~~~~ + +Set the color of the border + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default ``0x000000`` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +border_opa +~~~~~~~~~~ + +Set the opacity of the border. Value 0, :cpp:enumerator:`LV_OPA_0` or +:cpp:enumerator:`LV_OPA_TRANSP` means fully transparent, 255, :cpp:enumerator:`LV_OPA_100` or +:cpp:enumerator:`LV_OPA_COVER` means fully covering, other values or LV_OPA_10, +LV_OPA_20, etc means semi transparency. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_OPA_COVER` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +border_width +~~~~~~~~~~~~ + +Set hte width of the border. Only pixel values can be used. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +border_side +~~~~~~~~~~~ + +Set only which side(s) the border should be drawn. The possible values +are: + +- :cpp:enumerator:`LV_BORDER_SIDE_NONE` +- :cpp:enumerator:`LV_BORDER_SIDE_TOP` +- :cpp:enumerator:`LV_BORDER_SIDE_BOTTOM` +- :cpp:enumerator:`LV_BORDER_SIDE_LEFT` +- :cpp:enumerator:`LV_BORDER_SIDE_RIGHT` +- :cpp:enumerator:`LV_BORDER_SIDE_INTERNAL` + +OR-ed values can be used as well, e.g. :cpp:expr:`LV_BORDER_SIDE_TOP | LV_BORDER_SIDE_LEFT`. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_BORDER_SIDE_NONE` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +border_post +~~~~~~~~~~~ + +Sets whether the border should be drawn before or after the children are +drawn. ``true``: after children, ``false``: before children + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </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. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw Yes + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +outline_color +~~~~~~~~~~~~~ + +Set the color of the outline. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default ``0x000000`` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +outline_opa +~~~~~~~~~~~ + +Set the opacity of the outline. Value 0, :cpp:enumerator:`LV_OPA_0` or +:cpp:enumerator:`LV_OPA_TRANSP` means fully transparent, 255, :cpp:enumerator:`LV_OPA_100` or +:cpp:enumerator:`LV_OPA_COVER` means fully covering, other values or LV_OPA_10, +LV_OPA_20, etc means semi transparency. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_OPA_COVER` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw Yes + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +outline_pad +~~~~~~~~~~~ + +Set the padding of the outline, i.e. the gap between object and the +outline. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw Yes + +.. raw:: html + + </li> + +.. raw:: html + + </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. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw Yes + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +shadow_ofs_x +~~~~~~~~~~~~ + +Set an offset on the shadow in pixels in X direction. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw Yes + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +shadow_ofs_y +~~~~~~~~~~~~ + +Set an offset on the shadow in pixels in Y direction. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw Yes + +.. raw:: html + + </li> + +.. raw:: html + + </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 + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw Yes + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +shadow_color +~~~~~~~~~~~~ + +Set the color of the shadow + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default ``0x000000`` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +shadow_opa +~~~~~~~~~~ + +Set the opacity of the shadow. Value 0, :cpp:enumerator:`LV_OPA_0` or +:cpp:enumerator:`LV_OPA_TRANSP` means fully transparent, 255, :cpp:enumerator:`LV_OPA_100` or +:cpp:enumerator:`LV_OPA_COVER` means fully covering, other values or LV_OPA_10, +LV_OPA_20, etc means semi transparency. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_OPA_COVER` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw Yes + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +Image +----- + +Properties to describe the images + +img_opa +~~~~~~~ + +Set the opacity of an image. Value 0, :cpp:enumerator:`LV_OPA_0` or :cpp:enumerator:`LV_OPA_TRANSP` +means fully transparent, 255, :cpp:enumerator:`LV_OPA_100` or :cpp:enumerator:`LV_OPA_COVER` means +fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi +transparency. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_OPA_COVER` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +img_recolor +~~~~~~~~~~~ + +Set color to mixt to the image. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default ``0x000000`` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +img_recolor_opa +~~~~~~~~~~~~~~~ + +Set the intensity of the color mixing. Value 0, :cpp:enumerator:`LV_OPA_0` or +:cpp:enumerator:`LV_OPA_TRANSP` means fully transparent, 255, :cpp:enumerator:`LV_OPA_100` or +:cpp:enumerator:`LV_OPA_COVER` means fully covering, other values or LV_OPA_10, +LV_OPA_20, etc means semi transparency. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +Line +---- + +Properties to describe line-like objects + +line_width +~~~~~~~~~~ + +Set the width of the lines in pixel. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw Yes + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +line_dash_width +~~~~~~~~~~~~~~~ + +Set the width of dashes in pixel. Note that dash works only on +horizontal and vertical lines + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +line_dash_gap +~~~~~~~~~~~~~ + +Set the gap between dashes in pixel. Note that dash works only on +horizontal and vertical lines + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +line_rounded +~~~~~~~~~~~~ + +Make the end points of the lines rounded. ``true``: rounded, ``false``: +perpendicular line ending + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +line_color +~~~~~~~~~~ + +Set the color fo the lines. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default ``0x000000`` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +line_opa +~~~~~~~~ + +Set the opacity of the lines. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_OPA_COVER` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +Arc +--- + +TODO + +arc_width +~~~~~~~~~ + +Set the width (thickness) of the arcs in pixel. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw Yes + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +arc_rounded +~~~~~~~~~~~ + +Make the end points of the arcs rounded. ``true``: rounded, ``false``: +perpendicular line ending + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +arc_color +~~~~~~~~~ + +Set the color of the arc. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default ``0x000000`` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +arc_opa +~~~~~~~ + +Set the opacity of the arcs. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_OPA_COVER` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </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 +:cpp:struct:`lv_img_dsc_t` or a path to a file + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default ``NULL`` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +Text +---- + +Properties to describe the properties of text. All these properties are +inherited. + +text_color +~~~~~~~~~~ + +Sets the color of the text. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default ``0x000000`` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +text_opa +~~~~~~~~ + +Set the opacity of the text. Value 0, :cpp:enumerator:`LV_OPA_0` or :cpp:enumerator:`LV_OPA_TRANSP` +means fully transparent, 255, :cpp:enumerator:`LV_OPA_100` or :cpp:enumerator:`LV_OPA_COVER` means +fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi +transparency. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_OPA_COVER` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +text_font +~~~~~~~~~ + +Set the font of the text (a pointer :cpp:type:`lv_font_t` ``*``). + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_FONT_DEFAULT` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +text_letter_space +~~~~~~~~~~~~~~~~~ + +Set the letter space in pixels + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +text_line_space +~~~~~~~~~~~~~~~ + +Set the line space in pixels. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +text_decor +~~~~~~~~~~ + +Set decoration for the text. The possible values are: + +- :cpp:enumerator:`LV_TEXT_DECOR_NONE` +- :cpp:enumerator:`LV_TEXT_DECOR_UNDERLINE` +- :cpp:enumerator:`LV_TEXT_DECOR_STRIKETHROUGH` + +OR-ed values can be used as well. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_TEXT_DECOR_NONE` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </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: + +- :cpp:enumerator:`LV_TEXT_ALIGN_LEFT` +- :cpp:enumerator:`LV_TEXT_ALIGN_CENTER` +- :cpp:enumerator:`LV_TEXT_ALIGN_RIGHT` +- :cpp:enumerator:`LV_TEXT_ALIGN_AUTO` ` + +:cpp:enumerator:`LV_TEXT_ALIGN_AUTO` detect the text base direction and uses left or right alignment accordingly + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_TEXT_ALIGN_AUTO` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +Miscellaneous +------------- + +Mixed properties for various purposes. + +radius +~~~~~~ + +Set the radius on every corner. The value is interpreted in pixel (>= 0) +or :c:macro:`LV_RADIUS_CIRCLE` for max. radius + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +clip_corner +~~~~~~~~~~~ + +Enable to clip the overflowed content on the rounded corner. Can be +``true`` or ``false``. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +opa +~~~ + +Scale down all opacity values of the object by this factor. Value 0, +:cpp:enumerator:`LV_OPA_0` or :cpp:enumerator:`LV_OPA_TRANSP` means fully transparent, 255, +:cpp:enumerator:`LV_OPA_100` or :cpp:enumerator:`LV_OPA_COVER` means fully covering, other values or +LV_OPA_10, LV_OPA_20, etc means semi transparency. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_OPA_COVER` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +color_filter_dsc +~~~~~~~~~~~~~~~~ + +Mix a color to all colors of the object. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default ``NULL`` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +color_filter_opa +~~~~~~~~~~~~~~~~ + +The intensity of mixing of color filter. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_OPA_TRANSP` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +anim +~~~~ + +The animation template for the object’s animation. Should be a pointer +to :cpp:type:`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. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default ``NULL`` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </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. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </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. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +transition +~~~~~~~~~~ + +An initialized :cpp:struct:`lv_style_transition_dsc_t` to describe a transition. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default ``NULL`` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +blend_mode +~~~~~~~~~~ + +Describes how to blend the colors to the background. The possible values +are: + +- :cpp:enumerator:`LV_BLEND_MODE_NORMAL` +- :cpp:enumerator:`LV_BLEND_MODE_ADDITIVE` +- :cpp:enumerator:`LV_BLEND_MODE_SUBTRACTIVE` +- :cpp:enumerator:`LV_BLEND_MODE_MULTIPLY` + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_BLEND_MODE_NORMAL` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </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. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default 0 + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited No + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> + +base_dir +~~~~~~~~ + +Set the base direction of the object. The possible values are: + +- :cpp:enumerator:`LV_BASE_DIR_LTR` +- :cpp:enumerator:`LV_BASE_DIR_RTL` +- :cpp:enumerator:`LV_BASE_DIR_AUTO`. + +.. raw:: html + + <ul> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Default :cpp:enumerator:`LV_BASE_DIR_AUTO` + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Inherited Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Layout Yes + +.. raw:: html + + </li> + +.. raw:: html + + <li style="display:inline; margin-right: 20px; margin-left: 0px"> + +Ext. draw No + +.. raw:: html + + </li> + +.. raw:: html + + </ul> diff --git a/docs/overview/style.md b/docs/overview/style.md deleted file mode 100644 index fb28ff0af..000000000 --- a/docs/overview/style.md +++ /dev/null @@ -1,374 +0,0 @@ -# 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/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_CONST_PROPS_END -}; - -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*/ -``` - -### Replace styles -To replace a specific style of an object use `lv_obj_replace_style(obj, old_style, new_style, selector)`. This function -will only replace `old_style` with `new_style` if the `selector` matches the `selector` used in `lv_obj_add_style`. -Both styles, i.e. `old_style` and `new_style`, must not be `NULL` (for adding and removing separate functions exist). -If the combination of `old_style` and `selector` exists multiple times in `obj`'s styles, all occurrences will be -replaced. The return value of the function indicates whether at least one successful replacement took place. - -Using `lv_obj_replace_style`: -```c -lv_obj_add_style(btn, &style_btn, 0); /*Add a button style*/ -lv_obj_replace_style(btn, &style_btn, &new_style_btn, 0); /*Replace the button style with a different one*/ -``` - -### 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/docs/overview/style.rst b/docs/overview/style.rst new file mode 100644 index 000000000..3ddc3282b --- /dev/null +++ b/docs/overview/style.rst @@ -0,0 +1,536 @@ +.. _styles: + +====== +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 :cpp:type:`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: + +- :cpp:enumerator:`LV_STATE_DEFAULT`: (0x0000) Normal, released state +- :cpp:enumerator:`LV_STATE_CHECKED`: (0x0001) Toggled or checked state +- :cpp:enumerator:`LV_STATE_FOCUSED`: (0x0002) Focused via keypad or encoder or clicked via touchpad/mouse +- :cpp:enumerator:`LV_STATE_FOCUS_KEY`: (0x0004) Focused via keypad or encoder but not via touchpad/mouse +- :cpp:enumerator:`LV_STATE_EDITED`: (0x0008) Edit by an encoder +- :cpp:enumerator:`LV_STATE_HOVERED`: (0x0010) Hovered by mouse (not supported now) +- :cpp:enumerator:`LV_STATE_PRESSED`: (0x0020) Being pressed +- :cpp:enumerator:`LV_STATE_SCROLLED`: (0x0040) Being scrolled +- :cpp:enumerator:`LV_STATE_DISABLED`: (0x0080) Disabled state +- :cpp:enumerator:`LV_STATE_USER_1`: (0x1000) Custom state +- :cpp:enumerator:`LV_STATE_USER_2`: (0x2000) Custom state +- :cpp:enumerator:`LV_STATE_USER_3`: (0x4000) Custom state +- :cpp:enumerator:`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 :cpp:expr:`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 +:cpp:enumerator:`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: + +- :cpp:enumerator:`LV_STATE_DEFAULT`: white +- :cpp:enumerator:`LV_STATE_PRESSED`: gray +- :cpp:enumerator:`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 :cpp:expr:`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): + +.. code:: 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 :cpp:enumerator:`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: + +- :cpp:enumerator:`LV_PART_MAIN`: A background like rectangle +- :cpp:enumerator:`LV_PART_SCROLLBAR`: The scrollbar(s) +- :cpp:enumerator:`LV_PART_INDICATOR`: Indicator, e.g. for slider, bar, switch, or the tick box of the checkbox +- :cpp:enumerator:`LV_PART_KNOB`: Like a handle to grab to adjust a value +- :cpp:enumerator:`LV_PART_SELECTED`: Indicate the currently selected option or section +- :cpp:enumerator:`LV_PART_ITEMS`: Used if the widget has multiple similar elements (e.g. table cells) +- :cpp:enumerator:`LV_PART_TICKS`: Ticks on scales e.g. for a chart or meter +- :cpp:enumerator:`LV_PART_CURSOR`: Mark a specific place e.g. text area’s or chart’s cursor +- :cpp:enumerator:`LV_PART_CUSTOM_FIRST`: Custom part identifiers can be added starting from here. + +For example a `Slider </widgets/slider.html>`__ 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 :cpp:type:`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 +:cpp:expr:`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: + +.. code:: 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: + +.. code:: c + + lv_style_remove_prop(&style, LV_STYLE_BG_COLOR); + +To get a property’s value from a style: + +.. code:: 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); + } + +:cpp:union:`lv_style_value_t` has 3 fields: + +- :cpp:member:`num`: for integer, boolean and opacity properties +- :cpp:member:`color`: for color properties +- :cpp:member:`ptr`: for pointer properties + +To reset a style (free all its data) use: + +.. code:: c + + lv_style_reset(&style); + +Styles can be built as ``const`` too to save RAM: + +.. code:: c + + const lv_style_const_prop_t style1_props[] = { + LV_STYLE_CONST_WIDTH(50), + LV_STYLE_CONST_HEIGHT(50), + LV_STYLE_CONST_PROPS_END + }; + + 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: + +- :cpp:expr:`LV_PART_MAIN | LV_STATE_DEFAULT` +- :cpp:enumerator:`LV_STATE_PRESSED`: The main part in pressed state. :cpp:enumerator:`LV_PART_MAIN` can be omitted +- :cpp:enumerator:`LV_PART_SCROLLBAR`: The scrollbar part in the default state. :cpp:enumerator:`LV_STATE_DEFAULT` can be omitted. +- :cpp:expr:`LV_PART_SCROLLBAR | LV_STATE_SCROLLED`: The scrollbar part when the object is being scrolled +- :cpp:expr:`LV_PART_INDICATOR | LV_STATE_PRESSED | LV_STATE_CHECKED` The indicator part when the object is pressed and checked at the same time. + +Using :cpp:func:`lv_obj_add_style`: + +.. code:: 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*/ + +Replace styles +-------------- + +To replace a specific style of an object use +:cpp:expr:`lv_obj_replace_style(obj, old_style, new_style, selector)`. This +function will only replace ``old_style`` with ``new_style`` if the +``selector`` matches the ``selector`` used in ``lv_obj_add_style``. Both +styles, i.e. ``old_style`` and ``new_style``, must not be ``NULL`` (for +adding and removing separate functions exist). If the combination of +``old_style`` and ``selector`` exists multiple times in ``obj``\ ’s +styles, all occurrences will be replaced. The return value of the +function indicates whether at least one successful replacement took +place. + +Using :cpp:func:`lv_obj_replace_style`: + +.. code:: c + + lv_obj_add_style(btn, &style_btn, 0); /*Add a button style*/ + lv_obj_replace_style(btn, &style_btn, &new_style_btn, 0); /*Replace the button style with a different one*/ + +Remove styles +------------- + +To remove all styles from an object use :cpp:expr:`lv_obj_remove_style_all(obj)`. + +To remove specific styles use +:cpp:expr:`lv_obj_remove_style(obj, style, selector)`. This function will remove +``style`` only if the ``selector`` matches with the ``selector`` used in +:cpp:func:`lv_obj_add_style`. ``style`` can be ``NULL`` to check only the +``selector`` and remove all matching styles. The ``selector`` can use +the :cpp:enumerator:`LV_STATE_ANY` and :cpp:enumerator:`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 :cpp:expr:`lv_obj_invalidate(obj)` + or :cpp:expr:`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 :cpp:expr:`lv_obj_refresh_style(obj, part, property)`. + To refresh all parts and properties use :cpp:expr:`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 :cpp:expr:`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: + +.. code:: 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: + +.. code:: c + + lv_obj_set_style_bg_color(slider, lv_color_red(), LV_PART_INDICATOR | LV_STATE_FOCUSED); + +.. _style_properties: + +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 :cpp:struct:`lv_transition_dsc_t` variable needs to be +initialized and added to a style: + +.. code:: 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``: + +- :cpp:enumerator:`LV_LAYER_SIMPLE_BUF_SIZE`: [bytes] the optimal target buffer size. LVGL will try to allocate this size of memory. +- :cpp:enumerator:`LV_LAYER_SIMPLE_FALLBACK_BUF_SIZE`: [bytes] used if :cpp:enumerator:`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: + +.. code:: 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 :c:macro:`LV_USE_THEME_DEFAULT` 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. + +:cpp:expr:`lv_theme_set_parent(new_theme, base_theme)` extends the +``base_theme`` with the ``new_theme``. + +There is an example for it below. + +Examples +******** + +.. include:: ../examples/styles/index.rst + +API +*** diff --git a/docs/overview/timer.md b/docs/overview/timer.md deleted file mode 100644 index ca014c7e3..000000000 --- a/docs/overview/timer.md +++ /dev/null @@ -1,99 +0,0 @@ -# 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/docs/overview/timer.rst b/docs/overview/timer.rst new file mode 100644 index 000000000..bb28e68e8 --- /dev/null +++ b/docs/overview/timer.rst @@ -0,0 +1,122 @@ +====== +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 +:cpp:func:`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 +:cpp:expr:`lv_timer_create(timer_cb, period_ms, user_data)`. It will create an +:cpp:type:`lv_timer_t` ``*`` variable, which can be used later to modify the +parameters of the timer. :cpp:func:`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: + +.. code:: 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 +*************** + +:cpp:expr:`lv_timer_ready(timer)` makes a timer run on the next call of +:cpp:func:`lv_timer_handler`. + +:cpp:expr:`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: + +- :cpp:expr:`lv_timer_set_cb(timer, new_cb)` +- :cpp:expr:`lv_timer_set_period(timer, new_period)` + +Repeat count +************ + +You can make a timer repeat only a given number of times with +:cpp:expr:`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 :cpp:func:`lv_timer_handler` with +:cpp:func:`lv_timer_get_idle`. Note that, it doesn’t measure the idle time of +the overall system, only :cpp:func:`lv_timer_handler`. It can be misleading if +you use an operating system and call :cpp:func:`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, +:cpp:expr:`lv_async_call(my_function, data_p)` can be used to call +``my_function`` on the next invocation of :cpp:func:`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 :cpp:expr:`lv_async_call_cancel(my_function, data_p)`, which will +clear all asynchronous calls matching ``my_function`` and ``data_p``. + +For example: + +.. code:: 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 :cpp:func:`lv_obj_del_async` which +will delete the object on the next call to :cpp:func:`lv_timer_handler`. + +API +*** diff --git a/docs/porting/disp.rst b/docs/porting/disp.rst new file mode 100644 index 000000000..dfd72b96d --- /dev/null +++ b/docs/porting/disp.rst @@ -0,0 +1,261 @@ +.. _display_interface: + +================= +Display interface +================= + +To create a display for LVGL call +:cpp:expr:`lv_disp_t * disp = lv_disp_create(hor_res, ver_res)`. You can create +a multiple displays and a different driver for each (see below), + +Basic setup +*********** + +Draw buffer(s) are simple array(s) that LVGL uses to render the screen’s +content. Once rendering is ready the content of the draw buffer is sent +to the display using the ``flush_cb`` function. + +flush_cb +-------- + +An example ``flush_cb`` looks like this: + +.. code:: c + + void my_flush_cb(lv_disp_t * disp, const lv_area_t * area, lv_color_t * buf) + { + /*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 be 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 LVGL that you are ready with the flushing and buf is not used anymore*/ + lv_disp_flush_ready(disp); + } + +Use :cpp:expr:`lv_disp_set_flush_cb(disp, my_flush_cb)` to set a new ``flush_cb``. + +:cpp:expr:`lv_disp_flush_ready(disp)` needs to be called when flushing is ready +to inform LVGL the buffer is not used anymore by the driver and it can +render new content into it. + +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 :cpp:expr:`lv_disp_flush_is_last(disp)`. + +Draw buffers +------------ + +The draw buffers can be set with +:cpp:expr:`lv_disp_set_draw_buffers(disp, buf1, buf2, buf_size_px, render_mode)` + +- ``buf1`` a bufer where LVGL can render +- ``buf2`` a second optional buffer (see more details below) +- ``buf_size_byte`` size of the buffer(s) in bytes +- ``render_mode`` + + - :cpp:enumerator:`LV_DISP_RENDER_MODE_PARTIAL` Use the buffer(s) to render the + screen is smaller parts. This way the buffers can be smaller then + the display to save RAM. At least 1/10 sceen size buffer(s) are + recommended. In ``flush_cb`` the rendered images needs to be + copied to the given area of the display. + - :cpp:enumerator:`LV_DISP_RENDER_MODE_DIRECT` The buffer(s) has to be screen + sized and LVGL will render into the correct location of the + buffer. This way the buffer always contain the whole image. If two + buffer are used the rendered ares are automatically copied to the + other buffer after flushing. Due to this in ``flush_cb`` typically + only a frame buffer address needs to be changed and always the + changed areas will be redrawn. + - :cpp:enumerator:`LV_DISP_RENDER_MODE_FULL` The buffer can smaller or screen + sized but LVGL will always redraw the whole screen even is only 1 + pixel has been changed. If 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). + +Example: + +.. code:: c + + static lv_color_t buf[LCD_HOR_RES * LCD_VER_RES / 10]; + lv_disp_set_draw_buffers(disp, buf, NULL, sizeof(buf), LV_DISP_RENDER_MODE_PARTIAL); + +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 via the ``flush_cb``. LVGL +then needs to wait until the content of the buffer is sent to the +display before drawing something new into 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. + +Advnaced options +**************** + +Resolution +---------- + +To set the resolution of the display after creation use +:cpp:expr:`lv_disp_set_res(disp, hor_res, ver_res)` + +It’s not mandatory to use the whole display for LVGL, however in some +cases the physical resolution is important. For example the touchpad +still sees the whole resolution and the values needs to be converted to +the active LVGL display area. So the physical resoltution and the offset +of the active area can be set with +:cpp:expr:`lv_disp_set_physical_res(disp, hor_res, ver_res)` and +:cpp:expr:`lv_disp_set_offset(disp, x, y)` + +Rotation +-------- + +LVGL supports rotation of the display in 90 degree increments. You can +select whether you’d like software rotation or hardware rotation. + +The orientation of the display can be changed with +``lv_disp_set_rotation(disp, LV_DISP_ROTATION_0/90/180/270, true/false)``. +LVGL will swap the horizontal and vertical resolutions internally +according to the set degree. IF the last paramter is ``true`` LVGL will +rotate the rendered image. If it’s ``false`` the display driver should +rotate the rendered image. + +Color format +------------ + +Set the color format of the display. The default is +:cpp:enumerator:`LV_COLOR_FORMAT_NATIVE` which means LVGL render with the follow +formats dpeneding on :c:macro:`LV_COLOR_DEPTH`: + +- :c:macro:`LV_COLOR_DEPTH` ``32``: XRGB8888 (4 bytes/pixel) +- :c:macro:`LV_COLOR_DEPTH` ``24``: RGB888 (3 bytes/pixel) +- :c:macro:`LV_COLOR_DEPTH` ``16``: RGB565 (2 bytes/pixel) +- :c:macro:`LV_COLOR_DEPTH` ``8``: L8 (1 bytes/pixel) + +The ``color_format`` can be changed with +:cpp:expr:`lv_disp_set_color_depth(disp, LV_COLOR_FORMAT_...)` to the following +values: + +- :cpp:enumerator:`LV_COLOR_FORMAT_NATIVE_ALPHA`: Append an alpha byte to the native format resulting + in A8L8, ARGB8565, ARGB8888 formats. +- :cpp:enumerator:`LV_COLOR_FORMAT_NATIVE_REVERSE`: Reverse the byte order of the native format. Useful if the + rendered image is sent to the disply via SPI and + the display needs the bytes in the opposite order. +- :cpp:enumerator:`LV_COLOR_FORMAT_L8`: Lightness only on 8 bit +- :cpp:enumerator:`LV_COLOR_FORMAT_A8`: Alpha only on 8 bit +- :cpp:enumerator:`LV_COLOR_FORMAT_I8`: Indexed (palette) 8 bit +- :cpp:enumerator:`LV_COLOR_FORMAT_A8L8`: Lightness on 8 bit with 8 bit alpha +- :cpp:enumerator:`LV_COLOR_FORMAT_ARGB2222`: ARGB with 2 bit for each channel +- :cpp:enumerator:`LV_COLOR_FORMAT_RGB565`: 16 bit RGB565 format without alpha channel +- :cpp:enumerator:`LV_COLOR_FORMAT_ARGB8565`: 16 bit RGB565 format and 8 bit alpha channel +- :cpp:enumerator:`LV_COLOR_FORMAT_ARGB1555`: 5 bit for each color channel and 1 bit for alpha +- :cpp:enumerator:`LV_COLOR_FORMAT_ARGB4444`: 4 bit for each channel +- :cpp:enumerator:`LV_COLOR_FORMAT_RGB888`: 8 bit for each color channel with out alpha channel +- :cpp:enumerator:`LV_COLOR_FORMAT_ARGB8888`: 8 bit for each channel +- :cpp:enumerator:`LV_COLOR_FORMAT_XRGB8888`: 8 bit for each color channel and 8 bit placholder for the alpha cannel + +If the color fotmat is set to non-native ``draw_ctx->buffer_convert`` +function will be called before calling ``flush_cb`` to convert the +native color format to the desired, therfore rendering in non-native +formats has a negative effect on peroformance. Learn more about +``draw_ctx`` `here </porting/gpu>`__. + +It’s very important that draw buffer(s) should be large enough for both +the native format and the target color format. For example if +``LV_COLOR_DEPTH == 16`` and :cpp:enumerator:`LV_COLOR_FORMAT_XRGB8888` is selected +LVGL will choosoe the larger to figure out how many pixel can be +rendered at once. Therefore with :cpp:enumerator:`LV_DISP_RENDER_MODE_FULL` and the +larger pixel size needs to choosen. + +:cpp:enumerator:`LV_DISP_RENDER_MODE_DIRECT` supports only the +:cpp:enumerator:`LV_COLOR_FORMAT_NATIVE` format. + +Antialiasing +------------ + +:cpp:expr:`lv_disp_set_antialiasing(disp, true/false)` enables/disables the +antialiasing (edge smoothing) on the given display. + +User data +--------- + +With :cpp:expr:`lv_disp_set_user_data(disp, p)` a pointer to a custom data can +be stored in display object. + +Events +****** + +:cpp:expr:`lv_disp_add_event(disp, event_cb, LV_DISP_EVENT_..., user_data)` adds +an event handler to a display. The following events are sent: + +- :cpp:enumerator:`LV_DISP_EVENT_INVALIDATE_AREA` An area is invalidated (marked for redraw). + :cpp:expr:`lv_event_get_param(e)` returns a pointer to an :cpp:struct:`lv_area_t` + varaible with the coordinates of the area to be invalidated. The ara can + be freely modified is needed to adopt it the specialrequirement of the + display. Usually needed with monoschrome displays to invalidate Nx8 + lines at once. +- :cpp:enumerator:`LV_DISP_EVENT_RENDER_START`: Called when rendering starts. +- :cpp:enumerator:`LV_DISP_EVENT_RENDER_READY`: Called when rendering is ready +- :cpp:enumerator:`LV_DISP_EVENT_RESOLUTION_CHANGED`: Called when the resolution changes due + to :cpp:func:`lv_disp_set_resolution` or :cpp:func:`lv_disp_set_rotation`. + +Other options +************* + +Decoupling the display refresh timer +------------------------------------ + +Normally the dirty (a.k.a invalid) areas are checked and redrawn in +every :c:macro:`LV_DEF_REFR_PERIOD` milliseconds (set in ``lv_hal_disp.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: + +.. code:: 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 :cpp:expr:`lv_disp_set_deafult(disp1)` to +select the display to refresh before :cpp:expr:`_lv_disp_refr_timer(NULL)`. + +.. note:: that :cpp:func:`lv_timer_handler` and :cpp:func:`_lv_disp_refr_timer` can not +run at the same time. + +If the performance monitor is enabled, the value of +:c:macro:`LV_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 +*** diff --git a/docs/porting/display.md b/docs/porting/display.md deleted file mode 100644 index 906af78a9..000000000 --- a/docs/porting/display.md +++ /dev/null @@ -1,164 +0,0 @@ -# Display interface - -To create a display for LVGL call `lv_disp_t * disp = lv_disp_create(hor_res, ver_res)`. You can create a multiple displays and a different driver for each (see below), - -## Basic setup - -Draw buffer(s) are simple array(s) that LVGL uses to render the screen's content. -Once rendering is ready the content of the draw buffer is sent to the display using the `flush_cb` function. - - -### flush_cb -An example `flush_cb` looks like this: -```c -void my_flush_cb(lv_disp_t * disp, const lv_area_t * area, lv_color_t * buf) -{ - /*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 be 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 LVGL that you are ready with the flushing and buf is not used anymore*/ - lv_disp_flush_ready(disp); -} -``` - -Use `lv_disp_set_flush_cb(disp, my_flush_cb)` to set a new `flush_cb`. - -`lv_disp_flush_ready(disp)` needs to be called when flushing is ready to inform LVGL the buffer is not used anymore by the driver and it can render new content into it. - -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)`. - - -### Draw buffers -The draw buffers can be set with -`lv_disp_set_draw_buffers(disp, buf1, buf2, buf_size_px, render_mode);` - -- `buf1` a bufer where LVGL can render -- `buf2` a second optional buffer (see more details below) -- `buf_size_byte` size of the buffer(s) in bytes -- `render_mode` - - `LV_DISP_RENDER_MODE_PARTIAL` Use the buffer(s) to render the screen is smaller parts. This way the buffers can be smaller then the display to save RAM. At least 1/10 sceen size buffer(s) are recommended. In `flush_cb` the rendered images needs to be copied to the given area of the display. - - `LV_DISP_RENDER_MODE_DIRECT` The buffer(s) has to be screen sized and LVGL will render into the correct location of the buffer. This way the buffer always contain the whole image. If two buffer are used the rendered ares are automatically copied to the other buffer after flushing. Due to this in `flush_cb` typically only a frame buffer address needs to be changed and always the changed areas will be redrawn. - - `LV_DISP_RENDER_MODE_FULL` The buffer can smaller or screen sized but LVGL will always redraw the whole screen even is only 1 pixel has been changed. If 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). - -Example: -```c -static lv_color_t buf[LCD_HOR_RES * LCD_VER_RES / 10]; -lv_disp_set_draw_buffers(disp, buf, NULL, sizeof(buf), LV_DISP_RENDER_MODE_PARTIAL); -``` - -#### 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 via the `flush_cb`. -LVGL then needs to wait until the content of the buffer is sent to the display before drawing something new into 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. - - -## Advanced options - -### Resolution -To set the resolution of the display after creation use `lv_disp_set_res(disp, hor_res, ver_res);` - -It's not mandatory to use the whole display for LVGL, however in some cases the physical resolution is important. For example the touchpad still sees the whole resolution and the values needs to be converted -to the active LVGL display area. So the physical resoltution and the offset of the active area can be set with `lv_disp_set_physical_res(disp, hor_res, ver_res);`and `lv_disp_set_offset(disp, x, y);` - -### Rotation -LVGL supports rotation of the display in 90 degree increments. You can select whether you'd like software rotation or hardware rotation. - -The orientation of the display can be changed with -`lv_disp_set_rotation(disp, LV_DISP_ROTATION_0/90/180/270, true/false)`. -LVGL will swap the horizontal and vertical resolutions internally according to the set degree. IF the last paramter is `true` LVGL will rotate the rendered image. If it's `false` the display driver should rotate the rendered image. - -### Color format - -Set the color format of the display. The default is `LV_COLOR_FORMAT_NATIVE` which means LVGL render with the follow formats dpeneding on `LV_COLOR_DEPTH`: -- `LV_COLOR_DEPTH 32` XRGB8888 (4 bytes/pixel) -- `LV_COLOR_DEPTH 24` RGB888 (3 bytes/pixel) -- `LV_COLOR_DEPTH 16` RGB565 (2 bytes/pixel) -- `LV_COLOR_DEPTH 8` L8 (1 bytes/pixel) - -The `color_format` can be changed with `lv_disp_set_color_depth(disp, LV_COLOR_FORMAT_...)` to the following values: -- `LV_COLOR_FORMAT_NATIVE_ALPHA` Append an alpha byte to the native format resulting in A8L8, ARGB8565, ARGB8888 formats. -- `LV_COLOR_FORMAT_NATIVE_REVERSE` Reverse the byte order of the native format. Useful if the rendered image is sent to the disply via SPI and the display needs the bytes in the opposite order. -- `LV_COLOR_FORMAT_L8` Lightness only on 8 bit -- `LV_COLOR_FORMAT_A8` Alpha only on 8 bit -- `LV_COLOR_FORMAT_I8` Indexed (palette) 8 bit -- `LV_COLOR_FORMAT_A8L8` Lightness on 8 bit with 8 bit alpha -- `LV_COLOR_FORMAT_ARGB2222` ARGB with 2 bit for each channel -- `LV_COLOR_FORMAT_RGB565` 16 bit RGB565 format without alpha channel -- `LV_COLOR_FORMAT_ARGB8565` 16 bit RGB565 format and 8 bit alpha channel -- `LV_COLOR_FORMAT_ARGB1555` 5 bit for each color channel and 1 bit for alpha -- `LV_COLOR_FORMAT_ARGB4444` 4 bit for each channel -- `LV_COLOR_FORMAT_RGB888` 8 bit for each color channel with out alpha channel -- `LV_COLOR_FORMAT_ARGB8888` 8 bit for each channel -- `LV_COLOR_FORMAT_XRGB8888` 8 bit for each color channel and 8 bit placholder for the alpha cannel - -If the color fotmat is set to non-native `draw_ctx->buffer_convert` function will be called before calling `flush_cb` to convert the native color format to the desired, therfore rendering in non-native formats has a negative effect on peroformance. Learn more about `draw_ctx` [here](/porting/gpu). - -It's very important that draw buffer(s) should be large enough for both the native format and the target color format. For example if `LV_COLOR_DEPTH == 16` and `LV_COLOR_FORMAT_XRGB8888` is selected LVGL will choosoe the larger to figure out how many pixel can be rendered at once. Therefore with `LV_DISP_RENDER_MODE_FULL` and the larger pixel size needs to choosen. - -`LV_DISP_RENDER_MODE_DIRECT` supports only the `LV_COLOR_FORMAT_NATIVE` format. - -### Antialiasing -`lv_disp_set_antialiasing(disp, true/false)` enables/disables the antialiasing (edge smoothing) on the given display. - -### User data -With `lv_disp_set_user_data(disp, p)` a pointer to a custom data can be stored in display object. - -## Events -`lv_disp_add_event(disp, event_cb, LV_DISP_EVENT_..., user_data)` adds an event handler to a display. -The following events are sent: -- `LV_DISP_EVENT_INVALIDATE_AREA` An area is invalidated (marked for redraw). `lv_event_get_param(e)` returns a pointer to an `lv_area_t` varaible with the coordinates of the area to be invalidated. The ara can be freely modified is needed to adopt it the specialrequirement of the display. Usually needed with monoschrome displays to invalidate Nx8 lines at once. -- `LV_DISP_EVENT_RENDER_START` Called when rendering starts. -- `LV_DISP_EVENT_RENDER_READY` Called when rendering is ready -- `LV_DISP_EVENT_RESOLUTION_CHANGED` CAlled when the resolution changes due to `lv_disp_set_resolution()` or `lv_disp_set_rotation()`. - - - -## Other options - -### Decoupling the display refresh timer -Normally the dirty (a.k.a invalid) areas are checked and redrawn in every `LV_DEF_REFR_PERIOD` milliseconds (set in `lv_hal_disp.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_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_disp.h - :project: lvgl - -``` diff --git a/docs/porting/draw.rst b/docs/porting/draw.rst new file mode 100644 index 000000000..c398ee04c --- /dev/null +++ b/docs/porting/draw.rst @@ -0,0 +1,252 @@ +============== +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 :cpp:type:`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 +------ + +:cpp:type:`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 +:cpp:struct:`lv_draw_rect_dsc_t`, +for :cpp:func:`lv_draw_line` it’s called :cpp:struct:`lv_draw_line_dsc_t`, +etc. + +To correctly render according to a ``draw_dsc`` you need to be familiar +with the `Boxing model </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 </overview/style-props.html>`__. + +Initialization +-------------- + +The :cpp:type:`lv_disp_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_t * disp_drv, lv_draw_ctx_t * draw_ctx)`` Callback to initialize a ``draw_ctx`` +- ``void (*draw_ctx_deinit)(struct _lv_disp_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. :cpp:expr:`sizeof(lv_draw_sw_ctx_t)` + +When you ignore these fields, LVGL will set default values for callbacks +and size in :cpp:func:`lv_disp_drv_init` based on the configuration in +``lv_conf.h``. :cpp:func:`lv_disp_drv_register` will allocate a ``draw_ctx`` +based on ``draw_ctx_size`` and call :cpp:func:`draw_ctx_init` on it. + +However, you can overwrite the callbacks and the size values before +calling :cpp:func:`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 :cpp:type:`lv_draw_ctx_t` +structure and sets the draw callbacks. It looks like this: + +.. code:: 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 :cpp:func:`draw_ctx_init` like: + +.. code:: 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 :cpp:struct:`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. :cpp:enumerator:`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 :cpp:struct:`lv_draw_sw_ctx_t`: + +.. code:: 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_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 :cpp:expr:`lv_disp_draw_init(&drv)` you can assign the new +:cpp:func:`draw_ctx_init` callback and set ``draw_ctx_size`` to overwrite the +defaults: + +.. code:: c + + static lv_disp_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: + +.. code:: 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: + +.. code:: 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: + +.. code:: 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 :cpp:type:`lv_draw_ctx_t` (instead of +:cpp:struct:`lv_draw_sw_ctx_t`) and extend/initialize it as you wish. + +API +*** diff --git a/docs/porting/gpu.md b/docs/porting/gpu.md deleted file mode 100644 index 2c2b8a4a2..000000000 --- a/docs/porting/gpu.md +++ /dev/null @@ -1,198 +0,0 @@ -# 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_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_t * disp_drv, lv_draw_ctx_t * draw_ctx)` Callback to initialize a `draw_ctx` -- `void (*draw_ctx_deinit)(struct _lv_disp_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_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_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/docs/porting/indev.md b/docs/porting/indev.md deleted file mode 100644 index 95046c1e3..000000000 --- a/docs/porting/indev.md +++ /dev/null @@ -1,199 +0,0 @@ -# Input device interface - -## Types of input devices - -To create an input device use - -```c -/*Register at least one display before you register any input devices*/ -lv_indev_t * indev = lv_indev_create(); -lv_indev_set_type(indev, LV_INDEV_TYPE_...); /*See below.*/ -lv_indev_set_read_cb(indev, read_cb); /*See below.*/ -``` - -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 -lv_indev_set_type(indev, LV_INDEV_TYPE_POINTER); -... - -void my_input_read(lv_indev_t * indev, 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(indev, &img_cursor)`. - -### 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 and use `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(indev, g)` -- Use `LV_KEY_...` to navigate among the objects in the group. See `lv_core/lv_group.h` for the available keys. - -```c - -lv_indev_set_type(indev, LV_INDEV_TYPE_KEYPAD); - -... - -void keyboard_read(lv_indev_t * indev, 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 -lv_indev_set_type(indev, LV_INDEV_TYPE_ENCODER); - -... - -void encoder_read(lv_indev_t * indev, 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_repeat_time`. - -```c - -lv_indev_set_type(indev, LV_INDEV_TYPE_ENCODER); - -... - -void encoder_with_keys_read(lv_indev_t * indev, 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 - -lv_indev_set_type(indev, LV_INDEV_TYPE_BUTTON); - -... - -void button_read(lv_indev_t * indev, 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_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_repeat_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_DEF_REFR_PERIOD` in `lv_hal_disp.h` sets the default read period. - -### Feedback - -Besides `read_cb` a `feedback_cb` callback can be also specified in `lv_indev_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_indev.h - :project: lvgl - -``` diff --git a/docs/porting/indev.rst b/docs/porting/indev.rst new file mode 100644 index 000000000..c6f969849 --- /dev/null +++ b/docs/porting/indev.rst @@ -0,0 +1,239 @@ +====================== +Input device interface +====================== + +Types of input devices +********************** + +To create an input device use + +.. code:: c + + /*Register at least one display before you register any input devices*/ + lv_indev_t * indev = lv_indev_create(); + lv_indev_set_type(indev, LV_INDEV_TYPE_...); /*See below.*/ + lv_indev_set_read_cb(indev, read_cb); /*See below.*/ + +The ``type`` member can be: + +- :cpp:enumerator:`LV_INDEV_TYPE_POINTER`: touchpad or mouse +- :cpp:enumerator:`LV_INDEV_TYPE_KEYPAD`: keyboard or keypad +- :cpp:enumerator:`LV_INDEV_TYPE_ENCODER`: encoder with left/right turn and push options +- :cpp:enumerator:`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. + +.. code:: c + + lv_indev_set_type(indev, LV_INDEV_TYPE_POINTER); + ... + + void my_input_read(lv_indev_t * indev, 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 :cpp:expr:`lv_indev_set_cursor(indev, &img_cursor)`. + +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 and use :cpp:enumerator:`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 :cpp:expr:`lv_group_add_obj(g, obj)` +- The created group has to be assigned to an input device: :cpp:expr:`lv_indev_set_group(indev, g)` +- Use ``LV_KEY_...`` to navigate among the objects in the group. See + ``lv_core/lv_group.h`` for the available keys. + +.. code:: c + + + lv_indev_set_type(indev, LV_INDEV_TYPE_KEYPAD); + + ... + + void keyboard_read(lv_indev_t * indev, 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. + +.. code:: c + + lv_indev_set_type(indev, LV_INDEV_TYPE_ENCODER); + + ... + + void encoder_read(lv_indev_t * indev, 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: + +- :cpp:enumerator:`LV_KEY_ENTER`: will simulate press or pushing of the encoder button +- :cpp:enumerator:`LV_KEY_LEFT`: will simulate turning encoder left +- :cpp:enumerator:`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_repeat_time``. + +.. code:: c + + + lv_indev_set_type(indev, LV_INDEV_TYPE_ENCODER); + + ... + + void encoder_with_keys_read(lv_indev_t * indev, 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.` + +.. code:: c + + + lv_indev_set_type(indev, LV_INDEV_TYPE_BUTTON); + + ... + + void button_read(lv_indev_t * indev, 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 :cpp:type:`lv_indev_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 :cpp:enumerator:`LV_EVENT_LONG_PRESSED` (in milliseconds) +- ``long_press_repeat_time`` Interval of sending :cpp:enumerator:`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. :c:macro:`LV_DEF_REFR_PERIOD` + in ``lv_hal_disp.h`` sets the default read period. + +Feedback +-------- + +Besides ``read_cb`` a ``feedback_cb`` callback can be also specified in +:cpp:type:`lv_indev_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 :cpp:enumerator:`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 :cpp:func:`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 +*** diff --git a/docs/porting/index.md b/docs/porting/index.md deleted file mode 100644 index 2bf1dce91..000000000 --- a/docs/porting/index.md +++ /dev/null @@ -1,20 +0,0 @@ - -# Porting - -```eval_rst - -.. toctree:: - :maxdepth: 2 - - project - display - indev - tick - timer-handler - sleep - os - log - gpu - -``` - diff --git a/docs/porting/index.rst b/docs/porting/index.rst new file mode 100644 index 000000000..24db95fdb --- /dev/null +++ b/docs/porting/index.rst @@ -0,0 +1,19 @@ +.. _porting: + +======= +Porting +======= + + +.. toctree:: + :maxdepth: 2 + + project + disp + indev + tick + timer_handler + sleep + os + log + draw diff --git a/docs/porting/log.md b/docs/porting/log.md deleted file mode 100644 index 1d6a7fc9f..000000000 --- a/docs/porting/log.md +++ /dev/null @@ -1,49 +0,0 @@ -# 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(lv_log_level_t level, 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/docs/porting/log.rst b/docs/porting/log.rst new file mode 100644 index 000000000..96314c6df --- /dev/null +++ b/docs/porting/log.rst @@ -0,0 +1,71 @@ +.. _logging: + +======= +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 :c:macro:`LV_USE_LOG` in ``lv_conf.h`` and set +:c:macro:`LV_LOG_LEVEL` to one of the following values: + +- :c:macro:`LV_LOG_LEVEL_TRACE`: A lot of logs to give detailed information +- :c:macro:`LV_LOG_LEVEL_INFO`: Log important events +- :c:macro:`LV_LOG_LEVEL_WARN`: Log if something unwanted happened but didn’t cause a problem +- :c:macro:`LV_LOG_LEVEL_ERROR`: Only critical issues, where the system may fail +- :c:macro:`LV_LOG_LEVEL_USER`: Only user messages +- :c:macro:`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 :c:macro:`LV_LOG_LEVEL_WARN`, errors will be also +logged. + +Printing logs +************* + +Logging with printf +------------------- + +If your system supports ``printf``, you just need to enable +:c:macro:`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 :cpp:func:`lv_log_register_print_cb`. + +For example: + +.. code:: c + + void my_log_cb(lv_log_level_t level, 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. + +API +*** diff --git a/docs/porting/os.md b/docs/porting/os.md deleted file mode 100644 index 2dc416619..000000000 --- a/docs/porting/os.md +++ /dev/null @@ -1,50 +0,0 @@ -# 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/docs/porting/os.rst b/docs/porting/os.rst new file mode 100644 index 000000000..859f29c4c --- /dev/null +++ b/docs/porting/os.rst @@ -0,0 +1,65 @@ +.. _os_interrupt: + +=============================== +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 :ref:`events`. - +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 :cpp:func:`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: + +.. code:: 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 +:cpp:func:`lv_tick_inc` and :cpp:func:`lv_disp_flush_ready`). But if you need to do +this you have to disable the interrupt which uses LVGL functions while +:cpp:func:`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 +:cpp:func:`lv_timer_handler`). diff --git a/docs/porting/project.md b/docs/porting/project.md deleted file mode 100644 index a5e3754cd..000000000 --- a/docs/porting/project.md +++ /dev/null @@ -1,66 +0,0 @@ - -# 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) 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/docs/porting/project.rst b/docs/porting/project.rst new file mode 100644 index 000000000..f2ab6a86a --- /dev/null +++ b/docs/porting/project.rst @@ -0,0 +1,121 @@ +================ +Set up a project +================ + +Get the library +--------------- + +LVGL is available on GitHub: 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: + +.. code:: 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>`__ 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 :c:macro:`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 :c:macro:`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 :c:macro:`LV_CONF_PATH` define. For example +``-DLV_CONF_PATH="/home/joe/my_project/my_custom_conf.h"`` + +If :c:macro:`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 :c:macro:`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 :cpp:func:`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 :cpp:expr:`lv_tick_inc(x)` every ``x`` milliseconds in an interrupt to + report the elapsed time to LVGL. `Learn more </porting/tick>`__. +5. Call :cpp:func:`lv_timer_handler` every few milliseconds to handle LVGL + related tasks. `Learn more </porting/timer-handler>`__. diff --git a/docs/porting/sleep.md b/docs/porting/sleep.md deleted file mode 100644 index e69208168..000000000 --- a/docs/porting/sleep.md +++ /dev/null @@ -1,27 +0,0 @@ -# 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_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/docs/porting/sleep.rst b/docs/porting/sleep.rst new file mode 100644 index 000000000..adb988e18 --- /dev/null +++ b/docs/porting/sleep.rst @@ -0,0 +1,33 @@ +================ +Sleep management +================ + +The MCU can go to sleep when no user input happens. In this case, the +main ``while(1)`` should look like this: + +.. code:: 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: + +.. code:: c + + lv_tick_inc(LV_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 :cpp:func:`lv_disp_get_inactive_time` you can check +:cpp:func:`lv_anim_count_running` to see if all animations have finished. diff --git a/docs/porting/tick.md b/docs/porting/tick.md deleted file mode 100644 index a3e8e94ef..000000000 --- a/docs/porting/tick.md +++ /dev/null @@ -1,31 +0,0 @@ -# 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/docs/porting/tick.rst b/docs/porting/tick.rst new file mode 100644 index 000000000..a8e63ce75 --- /dev/null +++ b/docs/porting/tick.rst @@ -0,0 +1,35 @@ +.. _tick: + +============== +Tick interface +============== + +LVGL needs a system tick to know elapsed time for animations and other +tasks. + +You need to call the :cpp:expr:`lv_tick_inc(tick_period)` function periodically +and provide the call period in milliseconds. For example, +:cpp:expr:`lv_tick_inc(1)` when calling every millisecond. + +:cpp:func:`lv_tick_inc` should be called in a higher priority routine than +:cpp:func:`lv_task_handler` (e.g. in an interrupt) to precisely know the +elapsed milliseconds even if the execution of :cpp:func:`lv_task_handler` takes +more time. + +With FreeRTOS :cpp:func:`lv_tick_inc` can be called in ``vApplicationTickHook``. + +On Linux based operating systems (e.g. on Raspberry Pi) :cpp:func:`lv_tick_inc` +can be called in a thread like below: + +.. code:: 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 +--- diff --git a/docs/porting/timer-handler.md b/docs/porting/timer-handler.md deleted file mode 100644 index 2f086b597..000000000 --- a/docs/porting/timer-handler.md +++ /dev/null @@ -1,38 +0,0 @@ -# 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/docs/porting/timer_handler.rst b/docs/porting/timer_handler.rst new file mode 100644 index 000000000..b65b2d3ad --- /dev/null +++ b/docs/porting/timer_handler.rst @@ -0,0 +1,52 @@ +.. _timer: + +============= +Timer Handler +============= + +To handle the tasks of LVGL you need to call :cpp:func:`lv_timer_handler` +periodically in one of the following: + +- *while(1)* of *main()* function +- timer interrupt periodically (lower priority than :cpp:func:`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: + +.. code:: c + + while(1) { + lv_timer_handler(); + my_delay_ms(5); + } + +If you want to use :cpp:func:`lv_timer_handler` in a super-loop, a helper +function :cpp:func:`lv_timer_handler_run_in_period` is provided to simplify +the porting: + +.. code:: 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: + +.. code:: 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. + +API +*** diff --git a/docs/requirements.txt b/docs/requirements.txt index 0ce269828..0d5074b8d 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,34 +1,14 @@ -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 +Sphinx +breathe +imagesize +importlib-metadata +sphinx-rtd-theme +sphinx-sitemap +sphinxcontrib-applehelp +sphinxcontrib-devhelp +sphinxcontrib-htmlhelp +sphinxcontrib-jsmath +sphinxcontrib-qthelp +sphinxcontrib-serializinghtml +sphinx-rtd-dark-mode +typing-extensions diff --git a/docs/widgets/animimg.md b/docs/widgets/animimg.md deleted file mode 100644 index c472647a0..000000000 --- a/docs/widgets/animimg.md +++ /dev/null @@ -1,49 +0,0 @@ -# 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/docs/widgets/animimg.rst b/docs/widgets/animimg.rst new file mode 100644 index 000000000..6fcf1450d --- /dev/null +++ b/docs/widgets/animimg.rst @@ -0,0 +1,51 @@ +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 +**************** + +- :cpp:enumerator:`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 +:cpp:expr:`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 :ref:`events`. + +Keys +**** + +No Keys are processed by the object type. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/animimg/index.rst + +API +*** diff --git a/docs/widgets/arc.md b/docs/widgets/arc.md deleted file mode 100644 index a7bcd55fc..000000000 --- a/docs/widgets/arc.md +++ /dev/null @@ -1,120 +0,0 @@ -# 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)` - -### Knob offset -Changing the knob offset allows the location of the knob to be moved relative to the end of the arc -The knob offset can be set by `lv_arc_set_knob_offset(arc, offset_angle)`, will only be visible if LV_PART_KNOB is visible - - -### 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/docs/widgets/arc.rst b/docs/widgets/arc.rst new file mode 100644 index 000000000..3f71dc1ab --- /dev/null +++ b/docs/widgets/arc.rst @@ -0,0 +1,169 @@ +Arc (lv_arc) +============ + +Overview +******** + +The Arc consists of a background and a foreground arc. The foreground +(indicator) can be touch-adjusted. + +Parts and Styles +**************** + +- :cpp:enumerator:`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. +- :cpp:enumerator:`LV_PART_INDICATOR` Draws another arc using the *arc* style + properties. Its padding values are interpreted relative to the + background arc. +- :cpp:enumerator:`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 :cpp:expr:`lv_arc_set_value(arc, new_value)`. The +value is interpreted in a range (minimum and maximum values) which can +be modified with :cpp:expr:`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 +:cpp:expr:`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 +:cpp:expr:`lv_arc_set_rotation(arc, deg)`. + +Mode +---- + +The arc can be one of the following modes: + +- :cpp:enumerator:`LV_ARC_MODE_NORMAL` The indicator arc is drawn from the minimum value to the current. +- :cpp:enumerator:`LV_ARC_MODE_REVERSE` The indicator arc is drawn counter-clockwise + from the maximum value to the current. +- :cpp:enumerator:`LV_ARC_MODE_SYMMETRICAL` The indicator arc is drawn from the middle point to the current value. + +The mode can be set by :cpp:expr:`lv_arc_set_mode(arc, LV_ARC_MODE_...)` and +used only if the angle is set by :cpp:func:`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 +:cpp:expr:`lv_arc_set_change_rage(arc, rate)` + +Knob offset +----------- + +Changing the knob offset allows the location of the knob to be moved +relative to the end of the arc The knob offset can be set by +:cpp:expr:`lv_arc_set_knob_offset(arc, offset_angle)`, will only be visible if +:cpp:enumerator:`LV_PART_KNOB` is visible + +Setting the indicator manually +------------------------------ + +It’s also possible to set the angles of the indicator arc directly with +:cpp:expr:`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: + +.. code:: c + + lv_obj_remove_style(arc, NULL, LV_PART_KNOB); + lv_obj_clear_flag(arc, LV_OBJ_FLAG_CLICKABLE); + +Advanced hit test +----------------- + +If the :cpp:enumerator:`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. :cpp:func:`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 :cpp:expr:`lv_arc_align_obj_to_angle(arc, obj_to_align, radius_offset)`. + +Similarly +:cpp:expr:`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 +****** + +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` sent when the arc is pressed/dragged to + set a new value. +- :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN` and :cpp:enumerator:`LV_EVENT_DRAW_PART_END` are sent + with the following types: + + - :cpp:enumerator:`LV_ARC_DRAW_PART_BACKGROUND` The background arc. + + - ``part``: :cpp:enumerator:`LV_PART_MAIN` + - ``p1``: center of the arc + - ``radius``: radius of the arc + - ``arc_dsc`` + + - :cpp:enumerator:`LV_ARC_DRAW_PART_FOREGROUND` The foreground arc. + + - ``part``: :cpp:enumerator:`LV_PART_INDICATOR` + - ``p1``: center of the arc + - ``radius``: radius of the arc + - ``arc_dsc`` + + - LV_ARC_DRAW_PART_KNOB The knob + + - ``part``: :cpp:enumerator:`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 :ref:`events`. + +Keys +**** + +- ``LV_KEY_RIGHT/UP`` Increases the value by one. +- ``LV_KEY_LEFT/DOWN`` Decreases the value by one. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/arc/index.rst + +API +*** diff --git a/docs/widgets/bar.md b/docs/widgets/bar.md deleted file mode 100644 index c3bdc7d3c..000000000 --- a/docs/widgets/bar.md +++ /dev/null @@ -1,62 +0,0 @@ -# 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/docs/widgets/bar.rst b/docs/widgets/bar.rst new file mode 100644 index 000000000..11df842d5 --- /dev/null +++ b/docs/widgets/bar.rst @@ -0,0 +1,82 @@ +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 +**************** + +- :cpp:enumerator:`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 :cpp:enumerator:`LV_ANIM_ON`. +- :cpp:enumerator:`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 :cpp:expr:`lv_bar_set_range(bar, min, max)`. The default range is +0..100. + +The new value in :cpp:func:`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: + +- :cpp:enumerator:`LV_BAR_MODE_NORMAL` A normal bar as described above +- :cpp:enumerator:`LV_BAR_MODE_SYMMETRICAL` Draw the indicator from the zero value to current value. Requires a negative + minimum range and positive maximum range. +- :cpp:enumerator:`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 +****** + +- :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN` and :cpp:enumerator:`LV_EVENT_DRAW_PART_END` are sent + for the following parts: + + - :cpp:enumerator:`LV_BAR_DRAW_PART_INDICATOR` The indicator of the bar + + - ``part``: :cpp:enumerator:`LV_PART_INDICATOR` + - ``draw_area``: area of the indicator + - ``rect_dsc`` + +See the events of the `Base object </widgets/obj>`__ too. + +Learn more about :ref:`events`. + +Keys +**** + +No *Keys* are processed by the object type. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/bar/index.rst + +API +*** diff --git a/docs/widgets/btn.md b/docs/widgets/btn.md deleted file mode 100644 index 6015ba01d..000000000 --- a/docs/widgets/btn.md +++ /dev/null @@ -1,46 +0,0 @@ -# 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/docs/widgets/btn.rst b/docs/widgets/btn.rst new file mode 100644 index 000000000..e66af2332 --- /dev/null +++ b/docs/widgets/btn.rst @@ -0,0 +1,52 @@ +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 :cpp:enumerator:`LV_SIZE_CONTENT` + +Parts and Styles +**************** + +- :cpp:enumerator:`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 +****** + +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` when the :cpp:enumerator:`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 :ref:`events`. + +Keys +**** + +Note that the state of :cpp:enumerator:`LV_KEY_ENTER` is translated to +:cpp:enumerator:`LV_EVENT_PRESSED`, :cpp:enumerator:`LV_EVENT_PRESSING` +and :cpp:enumerator:`LV_EVENT_RELEASED` etc. + +See the events of the `Base object </widgets/obj>`__ too. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/btn/index.rst + +API +*** diff --git a/docs/widgets/btnmatrix.md b/docs/widgets/btnmatrix.md index 30ca8170c..e69de29bb 100644 --- a/docs/widgets/btnmatrix.md +++ b/docs/widgets/btnmatrix.md @@ -1,97 +0,0 @@ -# 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/btn) object plus the 100 or so bytes for the [Label](/widgets/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..15\] 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 - -Note that long pressing the button matrix with an encoder can mean to enter/leave edit mode and simply long pressing a button to make it repeat as well. To avoid this contradiction it's suggested to add `lv_btnmatrix_set_btn_ctrl_all(btnm, LV_BTNMATRIX_CTRL_CLICK_TRIG | LV_BTNMATRIX_CTRL_NO_REPEAT);` to the button matrix if used with encoder. This way, the pressed button repeat feature is disabled and on leaving edit mode the selected button won't be activated. - -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/docs/widgets/btnmatrix.rst b/docs/widgets/btnmatrix.rst new file mode 100644 index 000000000..30f888fc0 --- /dev/null +++ b/docs/widgets/btnmatrix.rst @@ -0,0 +1,147 @@ +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/btn>`__ object plus the 100 or so bytes +for the `Label </widgets/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 +**************** + +- :cpp:enumerator:`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. +- :cpp:enumerator:`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 +:cpp:expr:`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 :cpp:expr:`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..15] range and the +default width is 1. + +In addition to the width, each button can be customized with the +following parameters: + +- :cpp:enumerator:`LV_BTNMATRIX_CTRL_HIDDEN`: Makes a button hidden (hidden buttons still take up space in the layout, they are just not visible or clickable) +- :cpp:enumerator:`LV_BTNMATRIX_CTRL_NO_REPEAT`: Disable repeating when the button is long pressed +- :cpp:enumerator:`LV_BTNMATRIX_CTRL_DISABLED`: Makes a button disabled Like :cpp:enumerator:`LV_STATE_DISABLED` on normal objects +- :cpp:enumerator:`LV_BTNMATRIX_CTRL_CHECKABLE`: Enable toggling of a button. I.e. :cpp:enumerator:`LV_STATE_CHECHED` will be added/removed as the button is clicked +- :cpp:enumerator:`LV_BTNMATRIX_CTRL_CHECKED`: Make the button checked. It will use the :cpp:enumerator:`LV_STATE_CHECHKED` styles. +- :cpp:enumerator:`LV_BTNMATRIX_CTRL_CLICK_TRIG`: Enabled: send LV_EVENT_VALUE_CHANGE on CLICK, Disabled: send :cpp:enumerator:`LV_EVENT_VALUE_CHANGE` on PRESS +- :cpp:enumerator:`LV_BTNMATRIX_CTRL_POPOVER`: Show the button label in a popover when pressing this key +- :cpp:enumerator:`LV_BTNMATRIX_CTRL_RECOLOR`: Enable recoloring of button texts with ``#``. E.g. ``"It's #ff0000 red#"`` +- :cpp:enumerator:`LV_BTNMATRIX_CTRL_CUSTOM_1`: Custom free to use flag +- :cpp:enumerator:`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 +:cpp:expr:`lv_btnmatrix_set_one_checked(btnm, true)` to allow only one button to +be checked at a time. + +Events +****** + +- :cpp:enumerator:`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. +- :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN` and :cpp:enumerator:`LV_EVENT_DRAW_PART_END` are sent + for the following types: + + - :cpp:enumerator:`LV_BTNMATRIX_DRAW_PART_BTN` The individual buttons. + + - ``part``: :cpp:enumerator:`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. + +:cpp:expr:`lv_btnmatrix_get_selected_btn(btnm)` returns the index of the most +recently released or focused button or :cpp:enumerator:`LV_BTNMATRIX_BTN_NONE` if no +such button. + +:cpp:expr:`lv_btnmatrix_get_btn_text(btnm, btn_id)` returns a pointer to the +text of ``btn_id``\ th button. + +Learn more about :ref:`events`. + +Keys +**** + +- ``LV_KEY_RIGHT/UP/LEFT/RIGHT`` To navigate among the buttons to + select one +- :cpp:enumerator:`LV_KEY_ENTER` To press/release the selected button + +Note that long pressing the button matrix with an encoder can mean to +enter/leave edit mode and simply long pressing a button to make it +repeat as well. To avoid this contradiction it’s suggested to add +:cpp:expr:`lv_btnmatrix_set_btn_ctrl_all(btnm, LV_BTNMATRIX_CTRL_CLICK_TRIG | LV_BTNMATRIX_CTRL_NO_REPEAT)` +to the button matrix if used with encoder. This way, the pressed button +repeat feature is disabled and on leaving edit mode the selected button +won’t be activated. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/btnmatrix/index.rst + +API +*** diff --git a/docs/widgets/calendar.md b/docs/widgets/calendar.md deleted file mode 100644 index bc2dd7bf8..000000000 --- a/docs/widgets/calendar.md +++ /dev/null @@ -1,82 +0,0 @@ -# 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/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/docs/widgets/calendar.rst b/docs/widgets/calendar.rst new file mode 100644 index 000000000..6e4a0a0e3 --- /dev/null +++ b/docs/widgets/calendar.rst @@ -0,0 +1,113 @@ +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/btnmatrix>`__ +object under the hood to arrange the days into a matrix. + +- :cpp:enumerator:`LV_PART_MAIN` The background of the calendar. Uses all the background related style properties. +- :cpp:enumerator:`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 :cpp:enumerator:`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 :cpp:struct:`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 +:cpp:expr:`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 +:cpp:expr:`lv_calendar_set_shown_date(calendar, year, month)` + +Highlighted days +---------------- + +The list of highlighted dates should be stored in a +:cpp:struct:`lv_calendar_date_t` array loaded by +:cpp:expr:`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 +:cpp:expr:`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 +****** + +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent if a date is clicked. + :cpp:expr:`lv_calendar_get_pressed_date(calendar, &date)` set ``date`` to the + date currently being pressed. Returns :cpp:enumerator:`LV_RES_OK` if there is a + valid pressed date, else :cpp:enumerator:`LV_RES_INV`. + +Learn more about :ref:`events`. + +Keys +**** + +- ``LV_KEY_RIGHT/UP/LEFT/RIGHT`` To navigate among the buttons to dates +- :cpp:enumerator:`LV_KEY_ENTER` To press/release the selected date + +Learn more about :ref:`indev_keys`. + +Headers +******* + +**From v8.1 the header is added directly into the Calendar widget and +the API of the headers has been changed.** + +Arrow buttons +------------- + +:cpp:expr:`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 +--------- + +:cpp:expr:`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 +******* + +.. include:: ../examples/widgets/calendar/index.rst + +API +*** diff --git a/docs/widgets/canvas.md b/docs/widgets/canvas.md deleted file mode 100644 index ce659efa7..000000000 --- a/docs/widgets/canvas.md +++ /dev/null @@ -1,103 +0,0 @@ -# Canvas (lv_canvas) - - -## Overview - -A Canvas inherits from [Image](/widgets/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 uint8_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/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/docs/widgets/canvas.rst b/docs/widgets/canvas.rst new file mode 100644 index 000000000..7970d3175 --- /dev/null +++ b/docs/widgets/canvas.rst @@ -0,0 +1,137 @@ +Canvas (lv_canvas) +================== + +Overview +******** + +A Canvas inherits from `Image </widgets/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 +**************** + +:cpp:enumerator:`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 +:cpp:expr:`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 uint8_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 +:cpp:enumerator:`LV_IMG_CF_TRUE_COLOR` or :cpp:enumerator:`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 :cpp:expr:`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 +:cpp:expr:`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 :cpp:enumerator:`LV_IMG_CF_TRUE_COLOR_ALPHA` or +``LV_IMG_CF_ALPHA_...`` format on the canvas, use +:cpp:expr:`lv_canvas_set_px_opa(canvas, x, y, opa)`. + +:cpp:expr:`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. :cpp:enumerator:`LV_IMG_CF_ALPHA_2BIT`) the color will be +ignored. Similarly, if opacity is not supported +(e.g. :cpp:enumerator:`LV_IMG_CF_TRUE_COLOR`) it will be ignored. + +An array of pixels can be copied to the canvas with +:cpp:expr:`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: + +- :cpp:expr:`lv_canvas_draw_rect(canvas, x, y, width, heigth, &draw_dsc)` +- :cpp:expr:`lv_canvas_draw_text(canvas, x, y, max_width, &draw_dsc, txt)` +- :cpp:expr:`lv_canvas_draw_img(canvas, x, y, &img_src, &draw_dsc)` +- :cpp:expr:`lv_canvas_draw_line(canvas, point_array, point_cnt, &draw_dsc)` +- :cpp:expr:`lv_canvas_draw_polygon(canvas, points_array, point_cnt, &draw_dsc)` +- :cpp:expr:`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 :cpp:enumerator:`LV_IMG_VF_ALPHA_8BIT` canvas and use +the result image as a `draw mask </overview/drawing>`__ later. + +Transformations +--------------- + +:cpp:func:`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 (:cpp:func:`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 +:cpp:expr:`lv_canvas_blur_hor(canvas, &area, r)` or vertically with +:cpp:expr:`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/img>`__ too. + +Learn more about :ref:`events`. + +Keys +**** + +No *Keys* are processed by the object type. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/canvas/index.rst + +API +*** diff --git a/docs/widgets/chart.md b/docs/widgets/chart.md deleted file mode 100644 index a50aaac71..000000000 --- a/docs/widgets/chart.md +++ /dev/null @@ -1,193 +0,0 @@ -# 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/docs/widgets/chart.rst b/docs/widgets/chart.rst new file mode 100644 index 000000000..d9fc0e4ee --- /dev/null +++ b/docs/widgets/chart.rst @@ -0,0 +1,291 @@ +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 +**************** + +- :cpp:enumerator:`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. +- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar used if the chart is zoomed. See + the `Base object </widgets/obj>`__\ ’s documentation for details. +- :cpp:enumerator:`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. + +- :cpp:enumerator:`LV_PART_INDICATOR` Refers to the points on line and scatter chart + (small circles or squares). +- :cpp:enumerator:`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. +- :cpp:enumerator:`LV_PART_TICKS` *Line* and *Text* style properties are used to + style the ticks + +Usage +***** + +Chart type +---------- + +The following data display types exist: + +- :cpp:enumerator:`LV_CHART_TYPE_NONE`: Do not display any data. Can be used to hide the series. +- :cpp:enumerator:`LV_CHART_TYPE_LINE`: Draw lines between the data points and/or points (rectangles or circles) on the data points. +- :cpp:enumerator:`LV_CHART_TYPE_BAR`: Draw bars. +- :cpp:enumerator:`LV_CHART_TYPE_SCATTER`: X/Y chart drawing point’s and lines between the points. . + +You can specify the display type with +:cpp:expr:`lv_chart_set_type(chart, LV_CHART_TYPE_...)`. + +Data series +----------- + +You can add any number of series to the charts by +:cpp:expr:`lv_chart_add_series(chart, color, axis)`. This allocates an +:cpp:struct:`lv_chart_series_t` structure which contains the chosen ``color`` and +an array for the data points. ``axis`` can have the following values: + +- :cpp:enumerator:`LV_CHART_AXIS_PRIMARY_Y` Left axis +- :cpp:enumerator:`LV_CHART_AXIS_SECONDARY_Y` Right axis +- :cpp:enumerator:`LV_CHART_AXIS_PRIMARY_X` Bottom axis +- :cpp:enumerator:`LV_CHART_AXIS_SECONDARY_X` Top axis + +``axis`` tells which axis’s range should be used te scale the values. + +:cpp:expr:`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 +:cpp:expr:`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 +:cpp:expr:`lv_chart_get_y_array(chart, ser)`, which can be used with +``ext_array`` or *normal array*\ s. + +For :cpp:enumerator:`LV_CHART_TYPE_SCATTER` type +:cpp:expr:`lv_chart_set_ext_x_array(chart, ser, value_array)` and +:cpp:expr:`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 :cpp:enumerator:`lv_chart_refresh(chart)`. +2. Use :cpp:expr:`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 :cpp:expr:`lv_chart_set_next_value(chart, ser, value)`. +4. Initialize all points to a given value with :cpp:expr:`lv_chart_set_all_value(chart, ser, value)`. + +Use :cpp:enumerator:`LV_CHART_POINT_NONE` as value to make the library skip drawing +that point, column, or line segment. + +For :cpp:enumerator:`LV_CHART_TYPE_SCATTER` type +:cpp:expr:`lv_chart_set_value_by_id2(chart, ser, id, value)` and +:cpp:expr:`lv_chart_set_next_value2(chart, ser, x_valuem y_value)` can be used +as well. + +Update modes +------------ + +:cpp:func:`lv_chart_set_next_value` can behave in two ways depending on *update +mode*: + +- :cpp:enumerator:`LV_CHART_UPDATE_MODE_SHIFT`: Shift old data to the left and add the new one to the right. +- :cpp:enumerator:`LV_CHART_UPDATE_MODE_CIRCULAR`: Add the new data in circular fashion, like an ECG diagram. + +The update mode can be changed with +:cpp:expr:`lv_chart_set_update_mode(chart, LV_CHART_UPDATE_MODE_...)`. + +Number of points +---------------- + +The number of points in the series can be modified by +:cpp:expr:`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 +:cpp:expr:`lv_chart_set_range(chart, axis, min, max)`. ``axis`` can be +:cpp:enumerator:`LV_CHART_AXIS_PRIMARY` (left axis) or :cpp:enumerator:`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 +:cpp:expr:`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 :cpp:expr:`lv_chart_set_x_start_point(chart, ser, id)` where ``id`` is +the new index position to start plotting from. + +Note that :cpp:enumerator:`LV_CHART_UPDATE_MODE_SHIFT` also changes the +``start_point``. + +Tick marks and labels +--------------------- + +Ticks and labels can be added to the axis with +:cpp:expr:`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 +:cpp:expr:`lv_chart_set_zoom_x(chart, factor)` and +:cpp:expr:`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. + +:cpp:expr:`lv_chart_set_cursor_pos(chart, cursor, &point)` sets the position of +the cursor. ``pos`` is a pointer to an :cpp:struct:`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. + +:cpp:expr:`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. + +:cpp:expr:`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 +****** + +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new point is clicked pressed. + :cpp:expr:`lv_chart_get_pressed_point(chart)` returns the zero-based index of + the pressed point. +- :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN` and :cpp:enumerator:`LV_EVENT_DRAW_PART_END` are sent + with the following types: + + - :cpp:enumerator:`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``: :cpp:enumerator:`LV_PART_MAIN` + - ``line_dsc`` + + - :cpp:enumerator:`LV_CHART_DRAW_PART_DIV_LINE_HOR`, + :cpp:enumerator:`LV_CHART_DRAW_PART_DIV_LINE_VER` Used for each horizontal and + vertical division lines. + + - ``part``: :cpp:enumerator:`LV_PART_MAIN` + - ``id``: index of the line + - ``p1``, ``p2``: points of the line + - ``line_dsc`` + + - :cpp:enumerator:`LV_CHART_DRAW_PART_LINE_AND_POINT` Used on line and scatter + charts for lines and points. + + - ``part``: :cpp:enumerator:`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 + + - :cpp:enumerator:`LV_CHART_DRAW_PART_BAR` Used on bar charts for the rectangles. + + - ``part``: :cpp:enumerator:`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 + + - :cpp:enumerator:`LV_CHART_DRAW_PART_CURSOR` Used on cursor lines and points. + + - ``part``: :cpp:enumerator:`LV_PART_CURSOR` + - ``p1``, ``p2``: points of the line + - ``line_dsc`` + - ``rect_dsc`` + - ``draw_area``: area of the points + + - :cpp:enumerator:`LV_CHART_DRAW_PART_TICK_LABEL` Used on tick lines and labels. + + - ``part``: :cpp:enumerator:`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 :ref:`events`. + +Keys +**** + +No *Keys* are processed by the object type. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/chart/index.rst + +API +*** diff --git a/docs/widgets/checkbox.md b/docs/widgets/checkbox.md deleted file mode 100644 index f35152006..000000000 --- a/docs/widgets/checkbox.md +++ /dev/null @@ -1,74 +0,0 @@ -# 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*/ -``` - -To get whether the checkbox is checked or not use: `lv_obj_has_state(cb, LV_STATE_CHECKED)`. - -## 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/docs/widgets/checkbox.rst b/docs/widgets/checkbox.rst new file mode 100644 index 000000000..f300a5441 --- /dev/null +++ b/docs/widgets/checkbox.rst @@ -0,0 +1,88 @@ +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 +**************** + +- :cpp:enumerator:`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 +- :cpp:enumerator:`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 +:cpp:expr:`lv_checkbox_set_text(cb, "New text")` function and will be +dynamically allocated. + +To set a static text, use :cpp:expr:`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: + +.. code:: 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*/ + +To get whether the checkbox is checked or not use: +:cpp:expr:`lv_obj_has_state(cb, LV_STATE_CHECKED)`. + +Events +****** + +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the checkbox is toggled. +- :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN` and :cpp:enumerator:`LV_EVENT_DRAW_PART_END` are sent + for the following types: + + - :cpp:enumerator:`LV_CHECKBOX_DRAW_PART_BOX` The tickbox of the checkbox + + - ``part``: :cpp:enumerator:`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 :ref:`events`. + +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 - +:cpp:enumerator:`LV_KEY_ENTER` Clicks the checkbox and toggles it + +Note that, as usual, the state of :cpp:enumerator:`LV_KEY_ENTER` is translated to +``LV_EVENT_PRESSED/PRESSING/RELEASED`` etc. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/checkbox/index.rst + +API +*** diff --git a/docs/widgets/colorwheel.md b/docs/widgets/colorwheel.md deleted file mode 100644 index 2dbf35f1e..000000000 --- a/docs/widgets/colorwheel.md +++ /dev/null @@ -1,55 +0,0 @@ -# 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/docs/widgets/colorwheel.rst b/docs/widgets/colorwheel.rst new file mode 100644 index 000000000..a9671b676 --- /dev/null +++ b/docs/widgets/colorwheel.rst @@ -0,0 +1,75 @@ +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 +**************** + +- :cpp:enumerator:`LV_PART_MAIN` Only ``arc_width`` is used to set the width of the + color wheel +- :cpp:enumerator:`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 +-------------------- + +:cpp:expr:`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 :cpp:expr:`lv_colorwheel_set_hsv(colorwheel, hsv)` or +:cpp:expr:`lv_colorwheel_set_color(colorwheel, rgb)` + +Color mode +---------- + +The current color mode can be manually selected with +:cpp:expr:`lv_colorwheel_set_mode(colorwheel, LV_COLORWHEEL_MODE_HUE)`. + +The color mode can be fixed (so as to not change with long press) using +:cpp:expr:`lv_colorwheel_set_mode_fixed(colorwheel, true)` + +Events +****** + +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent if a new color is selected. + +Learn more about :ref:`events`. + +Keys +**** + +- :cpp:enumerator:`LV_KEY_UP`, :cpp:enumerator:`LV_KEY_RIGHT` Increment the current parameter’s + value by 1 +- :cpp:enumerator:`LV_KEY_DOWN`, :cpp:enumerator:`LV_KEY_LEFT` Decrement the current parameter’s + value by 1 +- :cpp:enumerator:`LV_KEY_ENTER` A long press will show the next mode. Double click + to reset the current parameter. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/colorwheel/index.rst + +API +*** diff --git a/docs/widgets/dropdown.md b/docs/widgets/dropdown.md deleted file mode 100644 index 74d641ace..000000000 --- a/docs/widgets/dropdown.md +++ /dev/null @@ -1,105 +0,0 @@ -# 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/docs/widgets/dropdown.rst b/docs/widgets/dropdown.rst new file mode 100644 index 000000000..c21e4594a --- /dev/null +++ b/docs/widgets/dropdown.rst @@ -0,0 +1,155 @@ +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 +------ + +- :cpp:enumerator:`LV_PART_MAIN` The background of the button. Uses the typical + background properties and text properties for the text on it. +- :cpp:enumerator:`LV_PART_INDICATOR` Typically an arrow symbol that can be an image + or a text (:cpp:enumerator:`LV_SYMBOL`). + +The button goes to :cpp:enumerator:`LV_STATE_CHECKED` when it’s opened. + +List +---- + +- :cpp:enumerator:`LV_PART_MAIN` The list itself. Uses the typical background + properties. ``max_height`` can be used to limit the height of the + list. +- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar background, border, shadow + properties and width (for its own width) and right padding for the + spacing on the right. +- :cpp:enumerator:`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 +:cpp:expr:`lv_dropdown_get_list(dropdown)` to get the list object. For example: + +.. code:: c + + lv_obj_t * list = lv_dropdown_get_list(dropdown) /*Get the list*/ + lv_obj_add_style(list, &my_style, selector) /*Add the styles to the list*/ + +Alternatively the theme can be extended with the new styles. + +Usage +***** + +Options +******* + +Set options +----------- + +Options are passed to the drop-down list as a string with +:cpp:expr:`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 :cpp:expr:`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 :cpp:expr:`lv_dropdown_set_static_options(dropdown, options)`. In this case +the options string should be alive while the drop-down list exists and +:cpp:func:`lv_dropdown_add_option` can’t be used + +You can select an option manually with +:cpp:expr:`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 +:cpp:expr:`lv_dropdown_get_selected(dropdown)`. + +:cpp:expr:`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 :cpp:enumerator:`LV_DIR_BOTTOM` can +be modified by :cpp:expr:`lv_dropdown_set_dir(dropdown, LV_DIR_LEFT)` 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 +:cpp:expr:`lv_dropdown_set_symbol(dropdown, LV_SYMBOL_...)` + +If the direction of the drop-down list is :cpp:enumerator:`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 :cpp:expr:`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: + +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the new option is selected or the list is opened/closed. +- :cpp:enumerator:`LV_EVENT_CANCEL` Sent when the list is closed +- :cpp:enumerator:`LV_EVENT_READY` Sent when the list is opened + +See the events of the `Base object </widgets/obj>`__ too. + +Learn more about :ref:`events`. + +Keys +**** + +- ``LV_KEY_RIGHT/DOWN`` Select the next option. +- ``LV_KEY_LEFT/UP`` Select the previous option. +- :cpp:enumerator:`LV_KEY_ENTER` Apply the selected option (Sends + :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` event and closes the drop-down list). + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/dropdown/index.rst + +API +*** diff --git a/docs/widgets/img.md b/docs/widgets/img.md deleted file mode 100644 index 03a506b90..000000000 --- a/docs/widgets/img.md +++ /dev/null @@ -1,139 +0,0 @@ -# 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/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_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/docs/widgets/img.rst b/docs/widgets/img.rst new file mode 100644 index 000000000..b4d4329d9 --- /dev/null +++ b/docs/widgets/img.rst @@ -0,0 +1,209 @@ +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 +**************** + +- :cpp:enumerator:`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 :cpp:expr:`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 :cpp:expr:`lv_img_set_src(img1, &converted_img_var)` +To make the variable visible in the C file, you need to declare it with +:cpp:expr:`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 :cpp:expr:`lv_img_set_src(img, "S:folder1/my_img.bin")`. + +You can also set a symbol similarly to `Labels </widgets/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 +:cpp:expr:`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 :c:macro:`LV_SYMBOL_DUMMY` as the prefix of the text. For example, +:cpp:expr:`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 :c:macro:`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 :cpp:enumerator:`LV_OPA_TRANSP` (no recolor, value: 0) and +:cpp:enumerator:`LV_OPA_COVER` (full recolor, value: 255). The default value is +:cpp:enumerator:`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 :c:macro:`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 :cpp:expr:`lv_img_set_offset_x(img, x_ofs)` and +:cpp:expr:`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 :cpp:expr:`lv_img_set_zoom(img, factor)` the images will be zoomed. +Set ``factor`` to ``256`` or :c:macro:`LV_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 :cpp:expr:`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 :cpp:expr:`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 +:cpp:expr:`lv_img_set_antialias(img, true)`. 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 +:cpp:expr:`lv_img_set_size_mode(img, LV_IMG_SIZE_MODE_REAL)`. (The previous mode +is the default and called :cpp:enumerator:`LV_IMG_SIZE_MODE_VIRTUAL`). In this case if +the width/height of the object is set to :c:macro:`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 :cpp:func:`lv_obj_set_style_radius` to set radius to an image, and +enable :cpp:func:`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 :ref:`events`. + +Keys +**** + +No *Keys* are processed by the object type. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/img/index.rst + +API +*** diff --git a/docs/widgets/imgbtn.md b/docs/widgets/imgbtn.md deleted file mode 100644 index 6642ade17..000000000 --- a/docs/widgets/imgbtn.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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/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/docs/widgets/imgbtn.rst b/docs/widgets/imgbtn.rst new file mode 100644 index 000000000..629c7d803 --- /dev/null +++ b/docs/widgets/imgbtn.rst @@ -0,0 +1,77 @@ +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 +**************** + +- :cpp:enumerator:`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 +:cpp:expr:`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/img>`__ +except that “Symbols” are not supported by the Image button. Any of the sources can ``NULL``. + +The possible states are: + +- :cpp:enumerator:`LV_IMGBTN_STATE_RELEASED` +- :cpp:enumerator:`LV_IMGBTN_STATE_PRESSED` +- :cpp:enumerator:`LV_IMGBTN_STATE_DISABLED` +- :cpp:enumerator:`LV_IMGBTN_STATE_CHECKED_RELEASED` +- :cpp:enumerator:`LV_IMGBTN_STATE_CHECKED_PRESSED` +- :cpp:enumerator:`LV_IMGBTN_STATE_CHECKED_DISABLED` + +If you set sources only in :cpp:enumerator:`LV_IMGBTN_STATE_RELEASED`, these sources +will be used in other states too. If you set e.g. :cpp:enumerator:`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 +:cpp:expr:`lv_imgbtn_set_state(imgbtn, LV_IMGBTN_STATE_...)` functions should be +used to manually set a state. + +Events +****** + +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the button is toggled. + +Learn more about :ref:`events`. + +Keys +**** + +- ``LV_KEY_RIGHT/UP`` Go to toggled state if :cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE` + is enabled. +- ``LV_KEY_LEFT/DOWN`` Go to non-toggled state if + :cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE` is enabled. +- :cpp:enumerator:`LV_KEY_ENTER` Clicks the button + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/imgbtn/index.rst + +API +*** diff --git a/docs/widgets/index.md b/docs/widgets/index.md deleted file mode 100644 index dca57311b..000000000 --- a/docs/widgets/index.md +++ /dev/null @@ -1,44 +0,0 @@ -# Widgets - -```eval_rst - -.. toctree:: - :maxdepth: 1 - - obj - arc - animimg - bar - btn - btnmatrix - calendar - chart - colorwheel - canvas - checkbox - dropdown - img - imgbtn - keyboard - label - led - line - list - menu - meter - msgbox - roller - slider - span - spinbox - spinner - switch - table - tabview - textarea - tileview - win - -``` - - diff --git a/docs/widgets/index.rst b/docs/widgets/index.rst new file mode 100644 index 000000000..1c918fe37 --- /dev/null +++ b/docs/widgets/index.rst @@ -0,0 +1,42 @@ +.. _widgets: + +======= +Widgets +======= + +.. toctree:: + :maxdepth: 1 + + obj + arc + animimg + bar + btn + btnmatrix + calendar + chart + colorwheel + canvas + checkbox + dropdown + img + imgbtn + keyboard + label + led + line + list + menu + meter + msgbox + roller + slider + span + spinbox + spinner + switch + table + tabview + textarea + tileview + win diff --git a/docs/widgets/keyboard.md b/docs/widgets/keyboard.md deleted file mode 100644 index 92ccc05c2..000000000 --- a/docs/widgets/keyboard.md +++ /dev/null @@ -1,92 +0,0 @@ - - -# Keyboard (lv_keyboard) - -## Overview - -The Keyboard object is a special [Button matrix](/widgets/btnmatrix) with predefined keymaps and other features to realize a virtual keyboard to write texts into a [Text area](/widgets/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/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, LV_KEYBOARD_MODE_..., kb_map, kb_ctrl);`. See the [Button matrix](/widgets/btnmatrix) for more information about creating new maps a ctrls. - -Keep in mind that using following keywords will have the same effect as with the original map: -- `LV_SYMBOL_OK` Send `LV_EVENT_RADY` to the assigend Text area. -- `LV_SYMBOL_CLOSE` or `LV_SYMBOL_KEYBOARD` Send `LV_EVENT_CANCEL` to the assigend Text area. -- `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/docs/widgets/keyboard.rst b/docs/widgets/keyboard.rst new file mode 100644 index 000000000..da66aa80f --- /dev/null +++ b/docs/widgets/keyboard.rst @@ -0,0 +1,119 @@ +Keyboard (lv_keyboard) +====================== + +Overview +******** + +The Keyboard object is a special `Button matrix </widgets/btnmatrix>`__ +with predefined keymaps and other features to realize a virtual keyboard +to write texts into a `Text area </widgets/textarea>`__. + +Parts and Styles +**************** + +Similarly to Button matrices Keyboards consist of 2 part: + +- :cpp:enumerator:`LV_PART_MAIN` The main part. Uses all the typical background properties +- :cpp:enumerator:`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: + +- :cpp:enumerator:`LV_KEYBOARD_MODE_TEXT_LOWER` Display lower case letters +- :cpp:enumerator:`LV_KEYBOARD_MODE_TEXT_UPPER` Display upper case letters +- :cpp:enumerator:`LV_KEYBOARD_MODE_TEXT_SPECIAL` Display special characters +- :cpp:enumerator:`LV_KEYBOARD_MODE_NUMBER` Display numbers, +/- sign, and decimal dot +- :cpp:enumerator:`LV_KEYBOARD_MODE_USER_1` through :cpp:enumerator:`LV_KEYBOARD_MODE_USER_4` User-defined modes. + +The ``TEXT`` modes’ layout contains buttons to change mode. + +To set the mode manually, use :cpp:expr:`lv_keyboard_set_mode(kb, mode)`. The +default mode is :cpp:enumerator:`LV_KEYBOARD_MODE_TEXT_UPPER`. + +Assign Text area +---------------- + +You can assign a `Text area </widgets/textarea>`__ to the Keyboard to +automatically put the clicked characters there. To assign the text area, +use :cpp:expr:`lv_keyboard_set_textarea(kb, ta)`. + +Key Popovers +------------ + +To enable key popovers on press, like on common Android and iOS +keyboards, use :cpp:expr:`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 :cpp:enumerator:`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 +:cpp:expr:`lv_keyboard_set_map(kb, LV_KEYBOARD_MODE_..., kb_map, kb_ctrl)`. See +the `Button matrix </widgets/btnmatrix>`__ for more information about +creating new maps a ctrls. + +Keep in mind that using following keywords will have the same effect as +with the original map: + +- :c:macro:`LV_SYMBOL_OK` Send ``LV_EVENT_RADY`` to the assigend Text area. +- :c:macro:`LV_SYMBOL_CLOSE` or :c:macro:`LV_SYMBOL_KEYBOARD` Send :cpp:enumerator:`LV_EVENT_CANCEL` to the assigend Text area. +- :c:macro:`LV_SYMBOL_BACKSPACE` Delete on the left. +- :c:macro:`LV_SYMBOL_LEFT` Move the cursor left. +- :c:macro:`LV_SYMBOL_RIGHT` Move the cursor right. +- :c:macro:`LV_SYMBOL_NEW_LINE` New line. +- *“ABC”* Load the uppercase map. +- *“abc”* Load the lower case map. +- *“1#”* Load the lower case map. + +Events +****** + +- :cpp:enumerator:`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. +- :cpp:enumerator:`LV_EVENT_READY`: The *Ok* button is clicked. +- :cpp:enumerator:`LV_EVENT_CANCEL`: The *Close* button is clicked. + +The keyboard has a **default event handler** callback called +:cpp:func:`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. + + +: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 :ref:`events`. + +Keys +**** + +- ``LV_KEY_RIGHT/UP/LEFT/RIGHT`` To navigate among the buttons and + select one. +- :cpp:enumerator:`LV_KEY_ENTER` To press/release the selected button. + +Learn more about :ref:`indev_keys`. + +Examples +******** + +.. include:: ../examples/widgets/keyboard/index.rst + +API +*** diff --git a/docs/widgets/label.md b/docs/widgets/label.md deleted file mode 100644 index 9762f4493..000000000 --- a/docs/widgets/label.md +++ /dev/null @@ -1,92 +0,0 @@ -# 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/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/docs/widgets/label.rst b/docs/widgets/label.rst new file mode 100644 index 000000000..4f0da796d --- /dev/null +++ b/docs/widgets/label.rst @@ -0,0 +1,147 @@ +Label (lv_label) +================ + +Overview +******** + +A label is the basic object type that is used to display text. + +Parts and Styles +**************** + +- :cpp:enumerator:`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. +- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar that is shown when the text is + larger than the widget’s size. +- :cpp:enumerator:`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 +:cpp:expr:`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 +:cpp:func:`lv_label_set_text` in scope after that function returns. + +With :cpp:expr:`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 :cpp:expr:`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 :cpp:func:`lv_label_set_text_static` (except when used with +:cpp:enumerator:`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 +:c:macro:`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.\ :cpp:func:`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. + +- :cpp:enumerator:`LV_LABEL_LONG_WRAP` Wrap too long lines. If the height is :c:macro:`LV_SIZE_CONTENT` the label’s + height will be expanded, otherwise the text will be clipped. (Default) +- :cpp:enumerator:`LV_LABEL_LONG_DOT` Replaces the last 3 characters from bottom right corner of the label with dots (``.``) +- :cpp:enumerator:`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. +- :cpp:enumerator:`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. +- :cpp:enumerator:`LV_LABEL_LONG_CLIP` Simply clip the parts of the text outside the label. + +You can specify the long mode with :cpp:expr:`lv_label_set_long_mode(label, LV_LABEL_LONG_...)` + +Note that :cpp:enumerator:`LV_LABEL_LONG_DOT` manipulates the text buffer in-place in +order to add/remove the dots. When :cpp:func:`lv_label_set_text` or +:cpp:func:`lv_label_set_array_text` are used, a separate buffer is allocated and +this implementation detail is unnoticed. This is not the case with +:cpp:func:`lv_label_set_text_static`. The buffer you pass to +:cpp:func:`lv_label_set_text_static` must be writable if you plan to use +:cpp:enumerator:`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 :cpp:func:`lv_label_set_recolor` function. + +Text selection +-------------- + +If enabled by :c:macro:`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/textarea>`__ and +the Label widget only allows manual text selection with +:cpp:expr:`lv_label_get_text_selection_start(label, start_char_index)` and +:cpp:expr:`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 +:cpp:enumerator:`LV_LABEL_LONG_SCROLL` and :cpp:enumerator:`LV_LABEL_LONG_SCROLL_CIRCULAR` can be +customized by setting the animation property of a style, using +:cpp:func:`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 :ref:`events`. + +Keys +**** + +No *Keys* are processed by the object type. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/label/index.rst + +API +*** diff --git a/docs/widgets/led.md b/docs/widgets/led.md deleted file mode 100644 index 747161a10..000000000 --- a/docs/widgets/led.md +++ /dev/null @@ -1,54 +0,0 @@ -# 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/docs/widgets/led.rst b/docs/widgets/led.rst new file mode 100644 index 000000000..0f9f5bf41 --- /dev/null +++ b/docs/widgets/led.rst @@ -0,0 +1,69 @@ +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 :cpp:enumerator:`LV_LED_PART_MAIN` and it +uses all the typical background style properties. + +Usage +***** + +Color +----- + +You can set the color of the LED with +:cpp:expr:`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 :cpp:expr:`lv_led_set_bright(led, bright)`. +The brightness should be between 0 (darkest) and 255 (lightest). + +Toggle +------ + +Use :cpp:expr:`lv_led_on(led)` and :cpp:expr:`lv_led_off(led)` to set the brightness to +a predefined ON or OFF value. The :cpp:expr:`lv_led_toggle(led)` toggles between +the ON and OFF state. + +Events +****** + +- :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN` and :cpp:enumerator:`LV_EVENT_DRAW_PART_END` is sent + for the following types: + + - :cpp:enumerator:`LV_LED_DRAW_PART_RECTANGLE` The main rectangle. + :cpp:enumerator:`LV_OBJ_DRAW_PART_RECTANGLE` is not sent by the base object. + + - ``part``: :cpp:enumerator:`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 :ref:`events`. + +Keys +**** + +No *Keys* are processed by the object type. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/led/index.rst + +API +*** diff --git a/docs/widgets/line.md b/docs/widgets/line.md deleted file mode 100644 index 86578c968..000000000 --- a/docs/widgets/line.md +++ /dev/null @@ -1,51 +0,0 @@ -# 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. - -Their coordinates can either be specified as raw pixel coordinates (e.g. `{5, 10}`), or as a percentage of the line's bounding box using `LV_PCT(x)`. In the latter case, the line's width/height may need to be set explicitly using -`lv_obj_set_width/height`, as percentage values do not automatically expand the bounding box. - -### 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/docs/widgets/line.rst b/docs/widgets/line.rst new file mode 100644 index 000000000..43db43b18 --- /dev/null +++ b/docs/widgets/line.rst @@ -0,0 +1,70 @@ +Line (lv_line) +============== + +Overview +******** + +The Line object is capable of drawing straight lines between a set of +points. + +Parts and Styles +**************** + +- :cpp:enumerator:`LV_PART_MAIN` uses all the typical background properties and line + style properties. + +Usage +***** + +Set points +---------- + +The points have to be stored in an :cpp:struct:`lv_point_t` array and passed to +the object by the :cpp:expr:`lv_line_set_points(lines, point_array, point_cnt)` +function. + +Their coordinates can either be specified as raw pixel coordinates +(e.g. ``{5, 10}``), or as a percentage of the line’s bounding box using +:cpp:expr:`lv_pct(x)`. In the latter case, the line’s width/height may need to +be set explicitly using ``lv_obj_set_width/height``, as percentage +values do not automatically expand the bounding box. + +Auto-size +--------- + +By default, the Line’s width and height are set to :c:macro:`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 :cpp:expr:`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 :ref:`events`. + +Keys +**** + +No *Keys* are processed by the object type. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/line/index.rst + +API +*** diff --git a/docs/widgets/list.md b/docs/widgets/list.md deleted file mode 100644 index b5c99f9e0..000000000 --- a/docs/widgets/list.md +++ /dev/null @@ -1,51 +0,0 @@ -# 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/btn)'s and [Label](/widgets/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/docs/widgets/list.rst b/docs/widgets/list.rst new file mode 100644 index 000000000..855ae3383 --- /dev/null +++ b/docs/widgets/list.rst @@ -0,0 +1,58 @@ +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** + +- :cpp:enumerator:`LV_PART_MAIN` The main part of the list that uses all the typical background properties +- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar. See the `Base objects </widgets/obj>`__ documentation for details. + +**Buttons and Texts** See the `Button </widgets/btn>`__\ ’s and `Label </widgets/label>`__\ ’s documentation. + +Usage +***** + +Buttons +------- + +:cpp:expr:`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 +----- + +:cpp:expr:`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 :ref:`events`. + +Keys +**** + +No *Keys* are processed by the object type. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/list/index.rst + +API +*** diff --git a/docs/widgets/menu.md b/docs/widgets/menu.md deleted file mode 100644 index cf7d1c071..000000000 --- a/docs/widgets/menu.md +++ /dev/null @@ -1,90 +0,0 @@ -# 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/btn) - - Back btn icon: [lv_img](/widgets/img) - - Main page: lv_menu_page -- Sidebar container: lv_menu_sidebar_cont - - Sidebar header: lv_menu_sidebar_header_cont - - Back btn: [lv_btn](/widgets/btn) - - Back btn icon: [lv_img](/widgets/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/docs/widgets/menu.rst b/docs/widgets/menu.rst new file mode 100644 index 000000000..7dd75d9e4 --- /dev/null +++ b/docs/widgets/menu.rst @@ -0,0 +1,121 @@ +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/btn>`__ - Back btn icon: `lv_img </widgets/img>`__ - +Main page: lv_menu_page - Sidebar container: lv_menu_sidebar_cont - +Sidebar header: lv_menu_sidebar_header_cont - Back btn: +`lv_btn </widgets/btn>`__ - Back btn icon: `lv_img </widgets/img>`__ - +Sidebar page: lv_menu_page + +Usage +***** + +Create a menu +------------- + +:cpp:expr:`lv_menu_create(parent)` creates a new empty menu. + +Header mode +----------- + +The following header modes exist: + +- :cpp:enumerator:`LV_MENU_HEADER_TOP_FIXED` Header is positioned at the top. +- :cpp:enumerator:`LV_MENU_HEADER_TOP_UNFIXED` Header is positioned at the top and can be scrolled out of view. +- :cpp:enumerator:`LV_MENU_HEADER_BOTTOM_FIXED` Header is positioned at the bottom. + +You can set header modes with :cpp:expr:`lv_menu_set_mode_header(menu, LV_MENU_HEADER...)`. + +Root back button mode +--------------------- + +The following root back button modes exist: + +- :cpp:enumerator:`LV_MENU_ROOT_BACK_BTN_DISABLED` +- :cpp:enumerator:`LV_MENU_ROOT_BACK_BTN_ENABLED` + +You can set root back button modes with +:cpp:expr:`lv_menu_set_mode_root_back_btn(menu, LV_MENU_ROOT_BACK_BTN...)`. + +Create a menu page +------------------ + +:cpp:expr:`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 +:cpp:expr:`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 +:cpp:expr:`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 +:cpp:expr:`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: + +- :cpp:expr:`lv_menu_cont_create(parent page)` creates a new empty container. +- :cpp:expr:`lv_menu_section_create(parent page)` creates a new empty section. +- :cpp:expr:`lv_menu_separator_create(parent page)` creates a separator. + +Events +****** + +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a page is shown. + + - :cpp:expr:`lv_menu_get_cur_main_page(menu)` returns a pointer to menu page + that is currently displayed in main. + - :cpp:expr:`lv_menu_get_cur_sidebar_page(menu)` returns a pointer to menu + page that is currently displayed in sidebar. + +- :cpp:enumerator:`LV_EVENT_CLICKED` Sent when a back btn in a header from either + main or sidebar is clicked. :cpp:enumerator:`LV_OBJ_FLAG_EVENT_BUBBLE` is enabled + on the buttons so you can add events to the menu itself. + + - :cpp:expr:`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 :ref:`events`. + +Keys +**** + +No keys are handled by the menu widget. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/menu/index.rst + +API +*** diff --git a/docs/widgets/meter.md b/docs/widgets/meter.md deleted file mode 100644 index de2537ce1..000000000 --- a/docs/widgets/meter.md +++ /dev/null @@ -1,110 +0,0 @@ -# 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 - -### Scale - -The Scale has minor and major ticks, and labels on the major ticks. - -The minor tick lines can be configured with: `lv_meter_set_scale_ticks(meter, tick_count, line_width, tick_length, ctick_olor)`. - -To show major tick lines use `lv_meter_set_scale_major_ticks(meter, 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, min, max, angle_range, rotation)` sets the value and angle range of the scale. - -### Add indicators - -Indicators can be added to meter and their value is interpreted in the range of the scale. - -All the indicator add functions return an `lv_meter_indicator_t *`. - -#### Needle line - -`indic = lv_meter_add_needle_line(meter, 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, 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, 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, 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/docs/widgets/meter.rst b/docs/widgets/meter.rst new file mode 100644 index 000000000..86847a186 --- /dev/null +++ b/docs/widgets/meter.rst @@ -0,0 +1,158 @@ +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 +**************** + +- :cpp:enumerator:`LV_PART_MAIN` The background of the Meter. Uses the typical + background properties. +- :cpp:enumerator:`LV_PART_TICK` The tick lines a labels using the *line* and *text* + style properties. +- :cpp:enumerator:`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. +- :cpp:enumerator:`LV_PART_ITEMS` The arcs using the *arc* properties. + +Usage +***** + +Scale +----- + +The Scale has minor and major ticks, and labels on the major ticks. + +The minor tick lines can be configured with: +:cpp:expr:`lv_meter_set_scale_ticks(meter, tick_count, line_width, tick_length, ctick_olor)`. + +To show major tick lines use +:cpp:expr:`lv_meter_set_scale_major_ticks(meter, 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. + +:cpp:expr:`lv_meter_set_scale_range(meter, min, max, angle_range, rotation)` +sets the value and angle range of the scale. + +Add indicators +-------------- + +Indicators can be added to meter and their value is interpreted in the +range of the scale. + +All the indicator add functions return an ``lv_meter_indicator_t *``. + +Needle line +^^^^^^^^^^^ + +``indic = lv_meter_add_needle_line(meter, 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. + +:cpp:expr:`lv_meter_set_indicator_value(meter, indic, value)` sets the value of +the indicator. + +Needle image +^^^^^^^^^^^^ + +``indic = lv_meter_add_needle_img(meter, 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. + +:cpp:expr:`lv_meter_set_indicator_value(meter, inidicator, value)` sets the +value of the indicator. + +Arc +^^^ + +``indic = lv_meter_add_arc(meter, 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. + +:cpp:expr:`lv_meter_set_indicator_start_value(meter, indic, value)` and +:cpp:expr:`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, 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. + +:cpp:expr:`lv_meter_set_indicator_start_value(meter, inidicator, value)` and +:cpp:expr:`lv_meter_set_indicator_end_value(meter, inidicator, value)` sets the +value of the indicator. + +Events +****** + +- :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN` and :cpp:enumerator:`LV_EVENT_DRAW_PART_END` is sent + for the following types: + + - :cpp:enumerator:`LV_METER_DRAW_PART_ARC` The arc indicator + + - ``part``: :cpp:enumerator:`LV_PART_ITEMS` + - ``sub_part_ptr``: pointer to the indicator + - ``arc_dsc`` + - ``radius``: radius of the arc + - ``p1`` center of the arc + + - :cpp:enumerator:`LV_METER_DRAW_PART_NEEDLE_LINE` The needle lines + + - ``part``: :cpp:enumerator:`LV_PART_ITEMS` + - ``p1``, ``p2`` points of the line + - ``line_dsc`` + - ``sub_part_ptr``: pointer to the indicator + + - :cpp:enumerator:`LV_METER_DRAW_PART_NEEDLE_IMG` The needle images + + - ``part``: :cpp:enumerator:`LV_PART_ITEMS` + - ``p1``, ``p2`` points of the line + - ``img_dsc`` + - ``sub_part_ptr``: pointer to the indicator + + - :cpp:enumerator:`LV_METER_DRAW_PART_TICK` The tick lines and labels + + - ``part``: :cpp:enumerator:`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 :ref:`events`. + +Keys +**** + +No keys are handled by the Meter widget. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/meter/index.rst + +API +*** diff --git a/docs/widgets/msgbox.md b/docs/widgets/msgbox.md deleted file mode 100644 index 84ea6bac3..000000000 --- a/docs/widgets/msgbox.md +++ /dev/null @@ -1,67 +0,0 @@ -# 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/btn) -- Title and text: [lv_label](/widgets/label) -- Buttons: [lv_btnmatrix](/widgets/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/docs/widgets/msgbox.rst b/docs/widgets/msgbox.rst new file mode 100644 index 000000000..0d01dc489 --- /dev/null +++ b/docs/widgets/msgbox.rst @@ -0,0 +1,89 @@ +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/btn>`__ +- Title and text: `lv_label </widgets/label>`__ +- Buttons: `lv_btnmatrix </widgets/btnmatrix>`__ + +Usage +***** + +Create a message box +-------------------- + +:cpp:expr:`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: + +.. code:: 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 +--------------------- + +:cpp:expr:`lv_msgbox_close(msgbox)` closes (deletes) the message box. + +Events +****** + +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` is sent by the buttons if one of them is + clicked. :cpp:enumerator:`LV_OBJ_FLAG_EVENT_BUBBLE` is enabled on the buttons so + you can add events to the message box itself. In the event handler, + :cpp:expr:`lv_event_get_target(e)` will return the button matrix and + :cpp:expr:`lv_event_get_current_target(e)` will return the message box. + :cpp:expr:`lv_msgbox_get_active_btn(msgbox)` and + :cpp:expr:`lv_msgbox_get_active_btn_text(msgbox)` can be used to get the + index and text of the clicked button. + +Learn more about :ref:`events`. + +Keys +**** + +Keys have effect on the close button and button matrix. You can add them +manually to a group if required. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/msgbox/index.rst + +API +*** diff --git a/docs/widgets/obj.md b/docs/widgets/obj.md deleted file mode 100644 index aa8f8e8ee..000000000 --- a/docs/widgets/obj.md +++ /dev/null @@ -1,198 +0,0 @@ -# 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(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 - -``` diff --git a/docs/widgets/obj.rst b/docs/widgets/obj.rst new file mode 100644 index 000000000..475ccf86b --- /dev/null +++ b/docs/widgets/obj.rst @@ -0,0 +1,277 @@ +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 :cpp:expr:`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 +:cpp:expr:`lv_obj_set_width(obj, new_width)` and +:cpp:expr:`lv_obj_set_height(obj, new_height)`, or both axes can be modified at +the same time with :cpp:expr:`lv_obj_set_size(obj, new_width, new_height)`. + +Position +^^^^^^^^ + +You can set the position relative to the parent with +:cpp:expr:`lv_obj_set_x(obj, new_x)` and :cpp:expr:`lv_obj_set_y(obj, new_y)`, or both +axes at the same time with :cpp:expr:`lv_obj_set_pos(obj, new_x, new_y)`. + +Alignment +^^^^^^^^^ + +You can align the object on its parent with +:cpp:expr:`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: + +.. code:: 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: +:cpp:expr:`lv_obj_align_to(obj_to_align, obj_referece, LV_ALIGN_..., x, y)` + +For example, to align a text below an image: +:cpp:expr:`lv_obj_align_to(text, image, LV_ALIGN_OUT_BOTTOM_MID, 0, 10)`. + +The following align types exist: |image1| + +Parents and children +-------------------- + +You can set a new parent for an object with +:cpp:expr:`lv_obj_set_parent(obj, new_parent)`. To get the current parent, use +:cpp:expr:`lv_obj_get_parent(obj)`. + +To get a specific child of a parent use :cpp:expr:`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: + +.. code:: 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*/ + } + +:cpp:expr:`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 :cpp:expr:`lv_obj_move_foreground(obj)` and +:cpp:expr:`lv_obj_move_background(obj)`. + +You can change the index of an object in its parent using +:cpp:expr:`lv_obj_move_to_index(obj, index)`. + +You can swap the position of two objects with +:cpp:expr:`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 +:cpp:expr:`lv_scr_load(screen)`. The :cpp:func:`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 :cpp:func:`lv_disp_set_default`. + +To get an object’s screen use the :cpp:expr:`lv_obj_get_screen(obj)` function. + +Events +------ + +To set an event callback for an object, use +:cpp:expr:`lv_obj_add_event(obj, event_cb, LV_EVENT_..., user_data)`, + +To manually send an event to an object, use +:cpp:expr:`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 +:cpp:expr:`lv_obj_add_style(obj, &new_style, selector)` function. ``selector`` +is an ORed combination of part and state(s). E.g. +:cpp:expr:`LV_PART_SCROLLBAR | LV_STATE_PRESSED`. + +The base objects use :cpp:enumerator:`LV_PART_MAIN` style properties and +:cpp:enumerator:`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_...)``: + +- :cpp:enumerator:`LV_OBJ_FLAG_HIDDEN` Make the object hidden. (Like it wasn’t there at all) +- :cpp:enumerator:`LV_OBJ_FLAG_CLICKABLE` Make the object clickable by input devices +- :cpp:enumerator:`LV_OBJ_FLAG_CLICK_FOCUSABLE` Add focused state to the object when clicked +- :cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE` Toggle checked state when the object is clicked +- :cpp:enumerator:`LV_OBJ_FLAG_SCROLLABLE` Make the object scrollable +- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_ELASTIC` Allow scrolling inside but with slower speed +- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_MOMENTUM` Make the object scroll further when “thrown” +- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_ONE` Allow scrolling only one snappable children +- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_CHAIN_HOR` Allow propagating the horizontal scroll to a parent +- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_CHAIN_VER` Allow propagating the vertical scroll to a parent +- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_CHAIN` Simple packaging for (:cpp:expr:`LV_OBJ_FLAG_SCROLL_CHAIN_HOR | LV_OBJ_FLAG_SCROLL_CHAIN_VER`) +- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_ON_FOCUS` Automatically scroll object to make it visible when focused +- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_WITH_ARROW` Allow scrolling the focused object with arrow keys +- :cpp:enumerator:`LV_OBJ_FLAG_SNAPPABLE` If scroll snap is enabled on the parent it can snap to this object +- :cpp:enumerator:`LV_OBJ_FLAG_PRESS_LOCK` Keep the object pressed even if the press slid from the object +- :cpp:enumerator:`LV_OBJ_FLAG_EVENT_BUBBLE` Propagate the events to the parent too +- :cpp:enumerator:`LV_OBJ_FLAG_GESTURE_BUBBLE` Propagate the gestures to the parent +- :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST` Allow performing more accurate hit (click) test. E.g. accounting for rounded corners +- :cpp:enumerator:`LV_OBJ_FLAG_IGNORE_LAYOUT` Make the object positionable by the layouts +- :cpp:enumerator:`LV_OBJ_FLAG_FLOATING` Do not scroll the object when the parent scrolls and ignore layout +- :cpp:enumerator:`LV_OBJ_FLAG_OVERFLOW_VISIBLE` Do not clip the children’s content to the parent’s boundary +- :cpp:enumerator:`LV_OBJ_FLAG_LAYOUT_1` Custom flag, free to use by layouts +- :cpp:enumerator:`LV_OBJ_FLAG_LAYOUT_2` Custom flag, free to use by layouts +- :cpp:enumerator:`LV_OBJ_FLAG_WIDGET_1` Custom flag, free to use by widget +- :cpp:enumerator:`LV_OBJ_FLAG_WIDGET_2` Custom flag, free to use by widget +- :cpp:enumerator:`LV_OBJ_FLAG_USER_1` Custom flag, free to use by user +- :cpp:enumerator:`LV_OBJ_FLAG_USER_2` Custom flag, free to use by user +- :cpp:enumerator:`LV_OBJ_FLAG_USER_3` Custom flag, free to use by user +- :cpp:enumerator:`LV_OBJ_FLAG_USER_4` Custom flag, free to use by user + +Some examples: + +.. code:: 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 :cpp:expr:`lv_group_add_obj(group, obj)`, +and you can use :cpp:expr:`lv_obj_get_group(obj)` to see which group an object +belongs to. + +:cpp:expr:`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 +:cpp:expr:`lv_obj_set_ext_click_area(obj, size)`. + +.. _events-1: + +Events +****** + +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` when the :cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE` flag is + enabled and the object clicked (on transition to/from the checked state) +- :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN` and :cpp:enumerator:`LV_EVENT_DRAW_PART_END` is sent + for the following types: + + - :cpp:enumerator:`LV_OBJ_DRAW_PART_RECTANGLE` The main rectangle + + - ``part``: :cpp:enumerator:`LV_PART_MAIN` + - ``rect_dsc`` + - ``draw_area``: the area of the rectangle + + - :cpp:enumerator:`LV_OBJ_DRAW_PART_BORDER_POST` The border if the ``border_post`` + style property is ``true`` + + - ``part``: :cpp:enumerator:`LV_PART_MAIN` + - ``rect_dsc`` + - ``draw_area``: the area of the rectangle + + - :cpp:enumerator:`LV_OBJ_DRAW_PART_SCROLLBAR` the scrollbars + + - ``part``: :cpp:enumerator:`LV_PART_SCROLLBAR` + - ``rect_dsc`` + - ``draw_area``: the area of the rectangle + +Learn more about :ref:`events`. + +Keys +**** + +If :cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE` is enabled, :cpp:enumerator:`LV_KEY_RIGHT` and +:cpp:enumerator:`LV_KEY_UP` make the object checked, and :cpp:enumerator:`LV_KEY_LEFT` and +:cpp:enumerator:`LV_KEY_DOWN` make it unchecked. + +If :cpp:enumerator:`LV_OBJ_FLAG_SCROLLABLE` is enabled, but the object is not editable +(as declared by the widget class), the arrow keys (:cpp:enumerator:`LV_KEY_UP`, +:cpp:enumerator:`LV_KEY_DOWN`, :cpp:enumerator:`LV_KEY_LEFT`, :cpp:enumerator:`LV_KEY_RIGHT`) scroll the object. +If the object can only scroll vertically, :cpp:enumerator:`LV_KEY_LEFT` and +:cpp:enumerator:`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 :ref:`indev_keys`. + +.. |image1| image:: /misc/align.png + + +Example +******* + +.. include:: ../examples/widgets/obj/index.rst + +API +*** diff --git a/docs/widgets/roller.md b/docs/widgets/roller.md deleted file mode 100644 index b7c084ec6..000000000 --- a/docs/widgets/roller.md +++ /dev/null @@ -1,58 +0,0 @@ -# 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/docs/widgets/roller.rst b/docs/widgets/roller.rst new file mode 100644 index 000000000..f66452243 --- /dev/null +++ b/docs/widgets/roller.rst @@ -0,0 +1,77 @@ +Roller (lv_roller) +================== + +Overview +******** + +Roller allows you to simply select one option from a list by scrolling. + +Parts and Styles +**************** + +- :cpp:enumerator:`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. +- :cpp:enumerator:`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 +:cpp:expr:`lv_roller_set_options(roller, options, LV_ROLLER_MODE_NORMAL)`. +The options should be separated by ``\n``. For example: +``"First\nSecond\nThird"``. + +:cpp:enumerator:`LV_ROLLER_MODE_INFINITE` makes the roller circular. + +You can select an option manually with +:cpp:expr:`lv_roller_set_selected(roller, id, LV_ANIM_ON)`, +where *id* is the index of an option. + +Get selected option +------------------- + +To get the *index* of the currently selected option use :cpp:expr:`lv_roller_get_selected(roller)`. + +:cpp:expr:`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 :cpp:expr:`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 +****** + +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new option is selected. + +See the events of the `Base object </widgets/obj>`__ too. + +Learn more about :ref:`events`. + +Keys +**** + +- ``LV_KEY_RIGHT/DOWN`` Select the next option +- ``LV_KEY_LEFT/UP`` Select the previous option +- :cpp:enumerator:`LY_KEY_ENTER` Apply the selected option (Send :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` event) + +Example +******* + +.. include:: ../examples/widgets/roller/index.rst + +API +*** diff --git a/docs/widgets/slider.md b/docs/widgets/slider.md deleted file mode 100644 index 3b3907ef4..000000000 --- a/docs/widgets/slider.md +++ /dev/null @@ -1,74 +0,0 @@ -# Slider (lv_slider) - -## Overview - -The Slider object looks like a [Bar](/widgets/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/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/docs/widgets/slider.rst b/docs/widgets/slider.rst new file mode 100644 index 000000000..acec7fa1d --- /dev/null +++ b/docs/widgets/slider.rst @@ -0,0 +1,107 @@ +.. _slider: + +Slider (lv_slider) +================== + +Overview +******** + +The Slider object looks like a `Bar </widgets/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 +**************** + +- :cpp:enumerator:`LV_PART_MAIN` The background of the slider. Uses all the typical + background style properties. ``padding`` makes the indicator smaller + in the respective direction. +- :cpp:enumerator:`LV_PART_INDICATOR` The indicator that shows the current state of + the slider. Also uses all the typical background style properties. +- :cpp:enumerator:`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 :cpp:expr:`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), :cpp:expr:`lv_slider_set_range(slider, min , max)` can be used. + +Modes +----- + +The slider can be one of the following modes: + +- :cpp:enumerator:`LV_SLIDER_MODE_NORMAL` A normal slider as described above +- :cpp:enumerator:`LV_SLIDER_SYMMETRICAL` Draw the indicator form the zero value to + current value. Requires negative minimum range and positive maximum range. +- :cpp:enumerator:`LV_SLIDER_RANGE` Allows setting the start value too by + :cpp:expr:`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 :cpp:expr:`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 :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST`: +:cpp:expr:`lv_obj_add_flag(slider, LV_OBJ_FLAG_ADV_HITTEST)`. + +The extended click area (set by :cpp:expr:`lv_obj_set_ext_click_area(slider, value)`) increases to knob’s click area. + +Events +****** + +- :cpp:enumerator:`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. +- :cpp:enumerator:`LV_EVENT_RELEASED` Sent when the slider has just been released. +- :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN` and :cpp:enumerator:`LV_EVENT_DRAW_PART_END` are sent + for the following parts. + + - :cpp:enumerator:`LV_SLIDER_DRAW_PART_KNOB` The main (right) knob of the slider + + - ``part``: :cpp:enumerator:`LV_PART_KNOB` + - ``draw_area``: area of the indicator + - ``rect_dsc`` + - ``id``: 0 + + - :cpp:enumerator:`LV_SLIDER_DRAW_PART_KNOB` The left knob of the slider + + - ``part``: :cpp:enumerator:`LV_PART_KNOB` + - ``draw_area``: area of the indicator + - ``rect_dsc`` + - ``id``: 1 + +See the events of the `Bar </widgets/bar>`__ too. + +Learn more about :ref:`events`. + +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 :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/slider/index.rst + +API +*** diff --git a/docs/widgets/span.md b/docs/widgets/span.md deleted file mode 100644 index dc9d0652d..000000000 --- a/docs/widgets/span.md +++ /dev/null @@ -1,85 +0,0 @@ -# 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/docs/widgets/span.rst b/docs/widgets/span.rst new file mode 100644 index 000000000..891715bb1 --- /dev/null +++ b/docs/widgets/span.rst @@ -0,0 +1,127 @@ +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 +**************** + +- :cpp:enumerator:`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 :cpp:expr:`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::cpp:expr:`lv_style_set_text_color(&span->style, lv_palette_main(LV_PALETTE_RED))`. + +If spangroup object ``mode != LV_SPAN_MODE_FIXED`` you must call +:cpp:func:`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. + +:cpp:expr:`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 :cpp:expr:`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: + +- :cpp:enumerator:`LV_TEXT_ALIGN_LEFT` Align text to left. +- :cpp:enumerator:`LV_TEXT_ALIGN_CENTER` Align text to center. +- :cpp:enumerator:`LV_TEXT_ALIGN_RIGHT` Align text to right. +- :cpp:enumerator:`LV_TEXT_ALIGN_AUTO` Align text auto. + +use function :cpp:expr:`lv_spangroup_set_align(spangroup, LV_TEXT_ALIGN_CENTER)` +to set text align. + +Modes +----- + +The spangroup can be set to one the following modes: + +- :cpp:enumerator:`LV_SPAN_MODE_FIXED` fixes the object size. +- :cpp:enumerator:`LV_SPAN_MODE_EXPAND` Expand the object size to the text size but stay on a single line. +- :cpp:enumerator:`LV_SPAN_MODE_BREAK` Keep width, break the too long lines and auto expand height. + +Use :cpp:expr:`lv_spangroup_set_mode(spangroup, LV_SPAN_MODE_BREAK)` to set +object mode. + +Overflow +-------- + +The spangroup can be set to one the following modes: + +- :cpp:enumerator:`LV_SPAN_OVERFLOW_CLIP` truncates the text at the limit of the area. +- :cpp:enumerator:`LV_SPAN_OVERFLOW_ELLIPSIS` will display an ellipsis(``...``) when text overflows the area. + +Use :cpp:expr:`lv_spangroup_set_overflow(spangroup, LV_SPAN_OVERFLOW_CLIP)` to set object overflow mode. + +first line indent +----------------- + +Use :cpp:expr:`lv_spangroup_set_indent(spangroup, 20)` to set the indent of the +first line. all modes support pixel units, in addition to :cpp:enumerator:`LV_SPAN_MODE_FIXED` +and :cpp:enumerator:`LV_SPAN_MODE_BREAK` mode supports percentage units +too. + +lines +----- + +Use :cpp:expr:`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 :ref:`events`. + +Keys +**** + +No *Keys* are processed by the object type. + +Learn more about :ref:`indev_keys`. + +Example +******* + + +.. include:: ../examples/widgets/span/index.rst + +API +*** diff --git a/docs/widgets/spinbox.md b/docs/widgets/spinbox.md deleted file mode 100644 index c1b68640a..000000000 --- a/docs/widgets/spinbox.md +++ /dev/null @@ -1,59 +0,0 @@ -# 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/textarea). - -## Parts and Styles -The parts of the Spinbox are identical to the [Text area](/widgets/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/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/docs/widgets/spinbox.rst b/docs/widgets/spinbox.rst new file mode 100644 index 000000000..d1d7cc47c --- /dev/null +++ b/docs/widgets/spinbox.rst @@ -0,0 +1,80 @@ +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/textarea>`__. + +Parts and Styles +**************** + +The parts of the Spinbox are identical to the `Text +area </widgets/textarea>`__. + +Value, range and step +--------------------- + +:cpp:expr:`lv_spinbox_set_value(spinbox, 1234)` sets a new value on the Spinbox. + +:cpp:expr:`lv_spinbox_increment(spinbox)` and :cpp:expr:`lv_spinbox_decrement(spinbox)` +increments/decrements the value of the Spinbox according to the currently selected digit. + +:cpp:expr:`lv_spinbox_set_range(spinbox, -1000, 2500)` sets a range. If the +value is changed by :cpp:func:`lv_spinbox_set_value`, by +*Keys*,\ ``lv_spinbox_increment/decrement`` this range will be respected. + +:cpp:expr:`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. + +:cpp:expr:`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 :cpp:expr:`lv_spinbox_set_digit_step_direction(spinbox, LV_DIR_LEFT)` can be used + +Format +------ + +:cpp:expr:`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 +-------- + +:cpp:expr:`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 +****** + +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the value has changed. + +See the events of the `Text area </widgets/textarea>`__ too. + +Learn more about :ref:`events`. + +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. +- :cpp:enumerator:`LV_KEY_ENTER` With *Encoder* got the net digit. Jump to the first + after the last. + +Example +******* + +.. include:: ../examples/widgets/spinbox/index.rst + +API +*** diff --git a/docs/widgets/spinner.md b/docs/widgets/spinner.md deleted file mode 100644 index 87996e01e..000000000 --- a/docs/widgets/spinner.md +++ /dev/null @@ -1,44 +0,0 @@ -# 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/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/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/docs/widgets/spinner.rst b/docs/widgets/spinner.rst new file mode 100644 index 000000000..5d6f27ccb --- /dev/null +++ b/docs/widgets/spinner.rst @@ -0,0 +1,46 @@ +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/arc>`__. + +Usage +***** + +Create a spinner +---------------- + +To create a spinner use +:cpp:expr:`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/arc>`__ too. + +Learn more about :ref:`events`. + +Keys +**** + +No *Keys* are processed by the object type. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/spinner/index.rst + +API +*** diff --git a/docs/widgets/switch.md b/docs/widgets/switch.md deleted file mode 100644 index f0630add4..000000000 --- a/docs/widgets/switch.md +++ /dev/null @@ -1,53 +0,0 @@ - -# 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/docs/widgets/switch.rst b/docs/widgets/switch.rst new file mode 100644 index 000000000..022ce7bfd --- /dev/null +++ b/docs/widgets/switch.rst @@ -0,0 +1,63 @@ +Switch (lv_switch) +================== + +Overview +******** + +The Switch looks like a little slider and can be used to turn something +on and off. + +Parts and Styles +**************** + +- :cpp:enumerator:`LV_PART_MAIN` The background of the switch uses all the typical + background style properties. ``padding`` makes the indicator smaller + in the respective direction. +- :cpp:enumerator:`LV_PART_INDICATOR` The indicator that shows the current state of + the switch. Also uses all the typical background style properties. +- :cpp:enumerator:`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 :cpp:enumerator:`LV_STATE_CHECKED` state. + +To get the current state of the switch (with ``true`` being on), use +:cpp:expr:`lv_obj_has_state(obj, LV_STATE_CHECKED)`. + +Call :cpp:expr:`lv_obj_add_state(obj, LV_STATE_CHECKED)` to turn it on, or +:cpp:expr:`lv_obj_clear_state(obj, LV_STATE_CHECKED)` to turn it off. + +Events +****** + +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the switch changes state. + +See the events of the `Base object </widgets/obj>`__ too. + +Learn more about :ref:`events`. + +Keys +**** + +- ``LV_KEY_UP/RIGHT`` Turns on the slider +- ``LV_KEY_DOWN/LEFT`` Turns off the slider +- :cpp:enumerator:`LV_KEY_ENTER` Toggles the switch + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/switch/index.rst + +API +*** diff --git a/docs/widgets/table.md b/docs/widgets/table.md deleted file mode 100644 index 115361895..000000000 --- a/docs/widgets/table.md +++ /dev/null @@ -1,91 +0,0 @@ -# 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/docs/widgets/table.rst b/docs/widgets/table.rst new file mode 100644 index 000000000..65cc225e1 --- /dev/null +++ b/docs/widgets/table.rst @@ -0,0 +1,123 @@ +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 +**************** + +- :cpp:enumerator:`LV_PART_MAIN` The background of the table uses all the typical + background style properties. +- :cpp:enumerator:`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. + +:cpp:expr:`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 +:cpp:expr:`lv_table_set_row_cnt(table, row_cnt)` and +:cpp:expr:`lv_table_set_col_cnt(table, col_cnt)` + +Width and Height +---------------- + +The width of the columns can be set with +:cpp:expr:`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 +:cpp:expr:`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 :c:macro:`LV_SIZE_CONTENT` that size +will be used to show the whole table in the respective direction. E.g. +:cpp:expr:`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 +****** + +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new cell is selected with + keys. +- :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN` and :cpp:enumerator:`LV_EVENT_DRAW_PART_END` are sent + for the following types: + + - :cpp:enumerator:`LV_TABLE_DRAW_PART_CELL` The individual cells of the table + + - ``part``: :cpp:enumerator:`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 :ref:`events`. + +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 :cpp:enumerator:`LV_KEY_ENTER` is translated to +``LV_EVENT_PRESSED/PRESSING/RELEASED`` etc. + +:cpp:expr:`lv_table_get_selected_cell(table, &row, &col)` can be used to get the +currently selected cell. Row and column will be set to +:c:macro:`LV_TABLE_CELL_NONE` no cell is selected. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/table/index.rst + +MicroPython +----------- + +No examples yet. + +API +*** diff --git a/docs/widgets/tabview.md b/docs/widgets/tabview.md deleted file mode 100644 index df33b9d8e..000000000 --- a/docs/widgets/tabview.md +++ /dev/null @@ -1,72 +0,0 @@ - -# 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/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/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/docs/widgets/tabview.rst b/docs/widgets/tabview.rst new file mode 100644 index 000000000..7ba261e29 --- /dev/null +++ b/docs/widgets/tabview.rst @@ -0,0 +1,91 @@ +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/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 +----------------- + +:cpp:expr:`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 :cpp:expr:`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 +:cpp:expr:`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 :cpp:expr:`lv_tabview_set_act(tabview, id, LV_ANIM_ON)` function + +Get the parts +------------- + +:cpp:expr:`lv_tabview_get_content(tabview)` returns the container for the tabs, +:cpp:expr:`lv_tabview_get_tab_btns(tabview)` returns the Tab buttons object +which is a `Button matrix </widgets/btnmatrix>`__. + +Events +****** + +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new tab is selected by sliding + or clicking the tab button. :cpp:expr:`lv_tabview_get_tab_act(tabview)` + returns the zero based index of the current tab. + +Learn more about :ref:`events`. + +Keys +**** + +Keys have effect only on the tab buttons (Button matrix). Add manually +to a group if required. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/tabview/index.rst + +API +*** diff --git a/docs/widgets/textarea.md b/docs/widgets/textarea.md deleted file mode 100644 index 86ac80f5f..000000000 --- a/docs/widgets/textarea.md +++ /dev/null @@ -1,122 +0,0 @@ -# Text area (lv_textarea) - -## Overview - -The Text Area is a [Base object](widgets/obj) with a [Label](/widgets/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/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/docs/widgets/textarea.rst b/docs/widgets/textarea.rst new file mode 100644 index 000000000..245f74780 --- /dev/null +++ b/docs/widgets/textarea.rst @@ -0,0 +1,179 @@ +Text area (lv_textarea) +======================= + +Overview +******** + +The Text Area is a `Base object <widgets/obj.html>`__ with a +`Label </widgets/label.html>`__ 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 +**************** + +- :cpp:enumerator:`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. +- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar that is shown when the text is + too long. +- :cpp:enumerator:`LV_PART_SELECTED` Determines the style of the `selected + text </widgets/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. +- :cpp:enumerator:`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 :cpp:enumerator:`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. +- :cpp:enumerator:`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: + +- :cpp:expr:`lv_textarea_add_char(textarea, 'c')` +- :cpp:expr:`lv_textarea_add_text(textarea, "insert this text")` + +To add wide characters like ``'á'``, ``'ß'`` or CJK characters use +:cpp:expr:`lv_textarea_add_text(ta, "á")`. + +:cpp:expr:`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 :cpp:expr:`lv_textarea_set_placeholder_text(ta, "Placeholder text")` + +Delete character +---------------- + +To delete a character from the left of the current cursor position use +:cpp:expr:`lv_textarea_del_char(textarea)`. To delete from the right use +:cpp:expr:`lv_textarea_del_char_forward(textarea)` + +Move the cursor +--------------- + +The cursor position can be modified directly like +:cpp:expr:`lv_textarea_set_cursor_pos(textarea, 10)`. The ``0`` position means +“before the first characters”, :cpp:enumerator:`LV_TA_CURSOR_LAST` means “after the +last character” + +You can step the cursor with + +- :cpp:expr:`lv_textarea_cursor_right(textarea)` +- :cpp:expr:`lv_textarea_cursor_left(textarea)` +- :cpp:expr:`lv_textarea_cursor_up(textarea)` +- :cpp:expr:`lv_textarea_cursor_down(textarea)` + +If :cpp:expr:`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 :cpp:enumerator:`LV_STATE_FOCUSED` state. + +One line mode +------------- + +The Text area can be configured to be on a single line with +:cpp:expr:`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 +:cpp:expr:`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 :cpp:expr:`lv_textarea_set_password_bullet(textarea, "x")`. + +In password mode :cpp:expr:`lv_textarea_get_text(textarea)` returns the actual +text entered, not the bullet characters. + +The visibility time can be adjusted with :c:macro:`LV_TEXTAREA_DEF_PWD_SHOW_TIME` in ``lv_conf.h``. + +Accepted characters +------------------- + +You can set a list of accepted characters with +:cpp:expr:`lv_textarea_set_accepted_chars(textarea, "0123456789.+-")`. Other +characters will be ignored. + +Max text length +--------------- + +The maximum number of characters can be limited with +:cpp:expr:`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 +:c:macro:`LV_LABEL_LONG_TXT_HINT` 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 :c:macro:`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 +:cpp:expr:`lv_textarea_set_text_selection(textarea, true)`. This works much like +when you select text on your PC with your mouse. + +Events +****** + +- :cpp:enumerator:`LV_EVENT_INSERT` Sent right before a character or text is + inserted. The event parameter is the text about to be inserted. + :cpp:expr:`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. +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the content of the text area has + been changed. +- :cpp:enumerator:`LV_EVENT_READY` Sent when :cpp:enumerator:`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 :ref:`events`. + +Keys +**** + +- ``LV_KEY_UP/DOWN/LEFT/RIGHT`` Move the cursor +- ``Any character`` Add the character to the current cursor position + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/textarea/index.rst + +API +*** diff --git a/docs/widgets/tileview.md b/docs/widgets/tileview.md deleted file mode 100644 index a87c4b304..000000000 --- a/docs/widgets/tileview.md +++ /dev/null @@ -1,54 +0,0 @@ -# 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/docs/widgets/tileview.rst b/docs/widgets/tileview.rst new file mode 100644 index 000000000..b9ac00023 --- /dev/null +++ b/docs/widgets/tileview.rst @@ -0,0 +1,64 @@ +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 +---------- + +:cpp:expr:`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 +:cpp:expr:`lv_obj_set_tile(tileview, tile_obj, LV_ANIM_ON/OFF)` or +:cpp:expr:`lv_obj_set_tile_id(tileviewv, col_id, row_id, LV_ANIM_ON/OFF)` + +Events +****** + +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new tile loaded by scrolling. + :cpp:expr:`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 :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/tileview/index.rst + +API +*** diff --git a/docs/widgets/win.md b/docs/widgets/win.md deleted file mode 100644 index 085eb5a95..000000000 --- a/docs/widgets/win.md +++ /dev/null @@ -1,61 +0,0 @@ -# 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/label) -- Buttons on the header: [lv_btn](/widgets/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/docs/widgets/win.rst b/docs/widgets/win.rst new file mode 100644 index 000000000..d1d4a6616 --- /dev/null +++ b/docs/widgets/win.rst @@ -0,0 +1,76 @@ +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/label>`__ +- Buttons on the header: `lv_btn </widgets/btn>`__ +- Content area on the background: `lv_obj </widgets/obj>`__ + +Usage +***** + +Create a Window +--------------- + +:cpp:expr:`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 :cpp:expr:`lv_win_add_title(win, "The title")`. + +Control buttons can be added to the window’s header with +:cpp:expr:`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 +************* + +:cpp:expr:`lv_win_get_header(win)` returns a pointer to the header, +:cpp:expr:`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 :cpp:func:`lv_win_add_btn`. + +Learn more about :ref:`events`. + +Keys +**** + +No *Keys* are handled by the window. + +Learn more about :ref:`indev_keys`. + +Example +******* + +.. include:: ../examples/widgets/win/index.rst + +API +*** |